pyfvcom2.ocean module

A collection of some useful ocean functions. These are taken from a range of MATLAB toolboxes as well as from ocean_funcs.ncl, which in turn has taken them from the CSIRO SEAWATER (now GSW) MATLAB toolbox.

The NCL code can be found at:

http://www.ncl.ucar.edu/Support/talk_archives/2013/att-1501/ocean_funcs.ncl__size_15540__creation-date_

The MATLAB toolboxes used includes:

http://www.cmar.csiro.au/datacentre/ext_docs/seawater.htm http://mooring.ucsd.edu/software/matlab/doc/toolbox/ocean/ http://www.mbari.org/staff/etp3/ocean1.htm

See also:

Feistel, R., A new extended Gibbs thermodynamic potential of seawater, Prog. Oceanogr., 58, 43-115, http://authors.elsevier.com/sd/article/S0079661103000880 corrigendum 61 (2004) 99, 2003.

Fofonoff, P. & Millard, R.C. Unesco 1983. Algorithms for computation of fundamental properties of seawater, 1983. Unesco Tech. Pap. in Mar. Sci., No. 44.

Jackett, D. R., T. J. McDougall, R. Feistel, D. G. Wright, and S. M. Griffies, Updated algorithms for density, potential temperature, conservative temperature and freezing temperature of seawater, Journal of Atmospheric and Oceanic Technology, submitted, 2005.

The Simpson-Hunter parameter is described in:

Simpson, JH, and JR Hunter. “Fronts in the Irish Sea.” Nature 250 (1974): 404-6.

The relative humidity from dew point temperature and ambient temperature is taken from:

http://www.vaisala.com/Vaisala%20Documents/Application%20notes/Humidity_Conversion_Formulas_B210973EN-F.pdf

Provides functions:

pressure2depth : convert pressure (decibars) to depth in metres
depth2pressure : convert depth in metres to pressure in decibars
dT_adiab_sw : calculate adiabatic temperature gradient
theta_sw : calculate potential temperature for sea water
cp_sw : calculate constant pressure specific heat for seawater
sw_smow : calculate density of Standard Mean Ocean Water
sw_dens0 : calculate seawater density at atmospheric surface pressure
sw_seck : calculate Secant Bulk Modulus (K) of seawater
sw_dens : calculate density from temperature, salinity and pressure
sw_svan : calculate specific volume anomaly (only use if you don’t already have density)
sw_sal78 : calculate salinity from conductivity, temperature and pressure based on the Fofonoff and Millard (1983) SAL78 FORTRAN function
sw_sal80 : calculate salinity from conductivity, temperature and pressure based on the UCSD sal80.m function (identical approach in sw_salinity)
sw_salinity : calculate salinity from conductivity, temperature and pressure (identical approach in sw_sal80)
dens_jackett : alternative formulation for calculating density from temperature and salinity (after Jackett et al. (2005)
pea: calculate the potential energy anomaly (stratification index).
simpsonhunter : calculate the Simpson-Hunter parameter to predict frontal locations.
mixedlayerdepth : calculate the mixed layer depth using the ERSEM definition.
stokes : calculate the Stokes parameter.
dissipation : calculate the tidal dissipation from a current speed.
rhum : calculate relative humidity from dew point temperature and ambient temperature.
cfl : calculate the CFL number for some model output.
turbulent_kinetic_energy : calculate the Turbulent Kinetic Energy from a velocity field.

Pierre Cazenave (Plymouth Marine Laboratory)

pyfvcom2.ocean.cond2salt(cond)[source]

Convert conductivity to salinity assuming constant temperature and pressure.

Assumes constant temperature (25 Celsius) and pressure.

Args:: cond (ndarray): Conductivity in microsiemens per cm.
Returns:: ndarray: Salinity in PSU.
References:: Schemel, L. E., 2001, Simplified conversions between specific conductance and salinity units for use with data from monitoring stations, IEP Newsletter, v. 14, no. 1, p. 17-18 [accessed July 27, 2004, at http://www.iep.ca.gov/report/newsletter/2001winter/IEPNewsletterWinter2001.pdf]

pyfvcom2.ocean.cp_sw(t, s, p)[source]

Calculate constant pressure specific heat (cp) for seawater.

Calculate constant pressure specific heat (cp) for seawater, from temperature, salinity and pressure.

Args:

t (ndarray): Temperature (1D array) in degrees Celsius. s (ndarray): Salinity (1D array) in practical salinity units (unitless). Must be the

same shape as t.

p (ndarray): Pressure (1D array) in decibars. Must be the same shape as t.

Returns:

ndarray: Constant pressure specific heat (Celsius).

Notes:

Valid temperature range is -2 to 40C and salinity is 0-42 PSU. Warnings are issued if the data fall outside these ranges.

pyfvcom2.ocean.dT_adiab_sw(t, s, p)[source]

Calculate adiabatic temperature gradient (degrees Celsius dbar^{-1}).

Args:: t (ndarray): Temperature (Celsius). All three arrays must have the same shape. s (ndarray): Salinity (PSU). All three arrays must have the same shape. p (ndarray): Pressure (decibars). All three arrays must have the same shape.
Returns:: ndarray: Adiabatic temperature gradient.

pyfvcom2.ocean.dens_jackett(th, s, p=None)[source]

Compute the in-situ density according to the Jackett et al. (2005) equation of state.

This equation of state for sea water is based on the Gibbs potential developed by Fiestel (2003). The pressure dependence can be switched on (off by default) by giving an absolute pressure value (> 0).

Args:

th (ndarray): Potential temperature (degrees Celsius). s (ndarray): Salinity (PSU). p (ndarray, optional): Gauge pressure (decibar) (absolute pressure - 10.1325 decibar).

Returns:

ndarray: In-situ density (kg m^{-3}).

Notes:

The check value is dens_jackett(20, 20, 1000) = 1017.728868019642.

Adopted from GOTM (www.gotm.net) (Original author(s): Hans Burchard & Karsten Bolding) and the PMLPython script EqS.py.

References:

Feistel, R., A new extended Gibbs thermodynamic potential of seawater, Prog. Oceanogr., 58, 43-115, http://authors.elsevier.com/sd/article/S0079661103000880 corrigendum 61 (2004) 99, 2003.

Jackett, D. R., T. J. McDougall, R. Feistel, D. G. Wright, and S. M. Griffies, Updated algorithms for density, potential temperature, conservative temperature and freezing temperature of seawater, Journal of Atmospheric and Oceanic Technology, submitted, 2005.

pyfvcom2.ocean.depth2pressure(z, lat)[source]

Convert from depth in metres to pressure in decibars.

Args:

z (ndarray): Depth (1D array) in metres. Must be positive down (negative values are: set to zero before conversion to pressure).

lat (ndarray): Latitudes for samples in z.

Returns:

ndarray: Pressure in decibars.

pyfvcom2.ocean.dissipation(rho, U, Cd=0.0025)[source]

Calculate tidal dissipation for a given tidal harmonic (or harmonics).

Args:

rho (ndarray): Density (kg m^{-3}). See dens_jackett() for calculating density from: temperature and salinity. Must be depth-averaged or a single value.
U (ndarray): Tidal harmonic major axis. Extend the array into the second dimension: to include results from multiple constituents.
Cd (float or ndarray, optional): Value for the quadratic drag coefficient. Defaults to: 2.5e-3. Can be an array whose size matches the number of locations in rho.

Returns:

ndarray: Tidal dissipation. Units?

References:

Souza, A. J. “On the Use of the Stokes Number to Explain Frictional Tidal Dynamics and Water Column Structure in Shelf Seas.” Ocean Science 9, no. 2 (April 2, 2013): 391-98. doi:10.5194/os-9-391-2013.

Pingree, R. D., and D. K. Griffiths. “Tidal Fronts on the Shelf Seas around the British Isles.” Journal of Geophysical Research: Oceans 83, no. C9 (1978): 4615-22. doi:10.1029/JC083iC09p04615.

pyfvcom2.ocean.mixedlayerdepth(rho, depth, thresh=0.03)[source]

Calculate the mixed layer depth based on a threshold in vertical density.

Calculate the mixed layer depth based on a threshold in the vertical density distribution.

Args:

rho (ndarray): Density in kg m^{3} [time, depth, position] or [depth, position] or [depth]. depth (ndarray): Water depth (m, -ve down) corresponding to the positions in rho whose space

matches rho.

thresh (float, optional): Density threshold (use at your own risk!). Defaults to 0.03kg m^{-3}.

Returns:

ndarray: Depth at which the density exceeds the surface value plus the: threshold (m, -ve down).

Notes:

The mixed layer depth is given as the layer depth where the density is greater than the threshold. As such, there is no interpolation between layer depths (for now).

If you have coarse layers, you will resolve the mixed layer depth poorly. You will also get odd patterns where the water depth happens to make the vertical layer which is closest to the actual density threshold jump by one, either up or down.

Really, I need to add a linear interpolation between the two closest layers.

pyfvcom2.ocean.pea(temp, salinity, depth, levels)[source]

Calculate potential energy anomaly (stratification index).

Args:: temp (ndarray): Temperature data (depth-resolved). salinity (ndarray): Salinity data (depth-resolved). depth (ndarray): Water depth (positive down). Can be 1D (node) or 3D (time, siglay, node). levels (ndarray): Vertical levels (fractions of 0-1) (FVCOM = siglev).
Returns:: ndarray: Potential energy anomaly (J/m^{3}).
Notes:: As with the zbar code, this could do with cleaning up by transposing the arrays so the depth dimension is always first. This would make calculations which require an axis to always use the 0th one instead of either the 0th or 1st.

pyfvcom2.ocean.pressure2depth(p, lat)[source]

Convert from pressure in decibars to depth in metres.

Args:: p (ndarray): Pressure (1D array) in decibars. lat (ndarray): Latitudes for samples in p.
Returns:: ndarray: Water depth in metres.
Notes:: This implements the UNESCO Technical Papers in Marine Science No. 44 (available from http://unesdoc.unesco.org/images/0005/000598/059832eb.pdf).

pyfvcom2.ocean.rhum(dew, temperature)[source]

Calculate relative humidity from dew temperature and ambient temperature.

This uses the range of constants which yields results accurate in the range -20 to 50 Celsius.

Args:: dew (ndarray): Dew point temperature (Celsius). temperature (ndarray): Ambient temperature (Celsius).
Returns:: ndarray: Relative humidity (%).
References:: http://www.vaisala.com/Vaisala%20Documents/Application%20notes/Humidity_Conversion_Formulas_B210973EN-F.pdf

pyfvcom2.ocean.simpsonhunter(u, v, depth, levels, sampling=False)[source]

Calculate the Simpson-Hunter parameter (h/u^{3}).

Args:

u (ndarray): Depth-resolved current vector (u-component). v (ndarray): Depth-resolved current vector (v-component). depth (ndarray): Water depth (m, +ve down). Must be on the same grid as u and v. levels (ndarray): Vertical levels (fractions of 0-1) (FVCOM = siglev). sampling (int, optional): If given, calculate the current speed maximum over

sampling indices.

Returns:

ndarray: Simpson-Hunter parameter (np.log10(m^{-2}s^{-3})).

References:

Simpson, JH, and JR Hunter. “Fronts in the Irish Sea.” Nature 250 (1974): 404-6.
Holt, Jason, and Lars Umlauf. “Modelling the Tidal Mixing Fronts and Seasonal Stratification of the Northwest European Continental Shelf.” Continental Shelf Research 28, no. 7 (April 2008): 887-903. doi:10.1016/j.csr.2008.01.012.

pyfvcom2.ocean.stokes(h, U, omega, z0, delta=False, U_star=False)[source]

Calculate the Stokes number for a given data set.

Args:

h (ndarray): Water depth (positive down) in metres. U (float): Constituent of interest’s (e.g. M2) major axis in metres. omega (float): Oscillatory frequency of the constituent of interest (e.g. M2) in

s^{-1}. For M2, omega is 1.4e-4.

z0 (float or ndarray): Roughness length in metres. Either a single value or an array: the same shape as the depth data.

delta (bool, optional): Return the oscillatory boundary layer thickness (delta). U_star (bool, optional): Return the frictional velocity (U_star).

Returns:

ndarray or tuple: Stokes number. If delta or U_star are True, returns tuple with: additional values: - S (ndarray): Stokes number. - delta (ndarray, optional): Oscillatory boundary layer thickness (Lamb, 1932). - U_star (ndarray, optional): Frictional velocity (U_star = Cd^{1/2}U).

Examples:

>>> h = 30
>>> z0 = 0.0025
>>> U = 0.25
>>> omega = 1 / 44714.1647021416
>>> S = stokes(h, U, omega, z0)
>>> S
0.70923635467504365
>>> S, U_star = stokes(h, U, omega, z0, U_star=True)
>>> U_star
0.011915170758540733

References:

Souza, A. J. “On the Use of the Stokes Number to Explain Frictional Tidal Dynamics and Water Column Structure in Shelf Seas.” Ocean Science 9, no. 2 (April 2, 2013): 391-98. doi:10.5194/os-9-391-2013.

Lamb, H. “Hydrodynamics”, 6th Edn., Cambridge University Press, New York, USA, p. 622, 1932.

pyfvcom2.ocean.sw_dens(t, s, p)[source]

Convert temperature, salinity and pressure to density.

Args:

t (ndarray): Temperature (1D array) in degrees Celsius. s (ndarray): Salinity (1D array) in practical salinity units (unitless). Must be the

same shape as t.

p (ndarray): Pressure (1D array) in decibars. Must be the same shape as t.

Returns:

ndarray: Density in kg m^{-3}.

Notes:

Valid temperature range is -2 to 40C, salinity is 0-42 and pressure is 0-10000 decibars. Warnings are issued if the data fall outside these ranges.

pyfvcom2.ocean.sw_dens0(t, s)[source]

Calculate sea water density at atmospheric surface pressure.

Args:: t (ndarray): Temperature (1D array) in degrees Celsius. s (ndarray): Salinity (PSU). Must be the same size as t.
Returns:: ndarray: Seawater density at atmospheric surface pressure (kg m^{-1}).

pyfvcom2.ocean.sw_sal78(c, t, p)[source]

Simplified version of the original SAL78 function from Fofonoff and Millard (1983).

This does only the conversion from conductivity, temperature and pressure to salinity. Returns zero for conductivity values below 0.0005.

Args:

c (ndarray): Conductivity (S m{-1}). t (ndarray): Temperature (degrees Celsius IPTS-68). p (ndarray): Pressure (decibars).

Returns:

ndarray: Salinity (PSU-78).

Notes:

The Conversion from IPTS-68 to ITS90 is:: T90 = 0.99976 * T68 T68 = 1.00024 * T90

These constants are defined here as c90 (0.99976) and c68 (1.00024).

pyfvcom2.ocean.sw_sal80(args)[source]

Wrapper for sw_sal78 with compatible interface.

Args:: args (tuple): Tuple containing (conductivity, temperature, pressure) arguments.
Returns:: ndarray: Salinity (PSU-78).

pyfvcom2.ocean.sw_salinity(args)[source]

Wrapper for sw_sal78 with compatible interface.

Args:: args (tuple): Tuple containing (conductivity, temperature, pressure) arguments.
Returns:: ndarray: Salinity (PSU-78).

pyfvcom2.ocean.sw_seck(t, s, p)[source]

Calculate Secant Bulk Modulus (K) of seawater.

Args:

t (ndarray): Temperature (1D array) in degrees Celsius. s (ndarray): Salinity (1D array) in practical salinity units (unitless). Must be the

same shape as t.

p (ndarray): Pressure (1D array) in decibars. Must be the same shape as t.

Returns:

ndarray: Secant Bulk Modulus of seawater.

pyfvcom2.ocean.sw_smow(t)[source]

Calculate the density of Standard Mean Ocean Water (pure water).

Args:: t (ndarray): Temperature (1D array) in degrees Celsius.
Returns:: ndarray: Density in kg m^{-3}.

pyfvcom2.ocean.sw_svan(t, s, p)[source]

Calculate the specific volume (steric) anomaly.

Args:

t (ndarray): Temperature (1D array) in degrees Celsius. s (ndarray): Salinity (1D array) in practical salinity units (unitless). Must be the

same shape as t.

p (ndarray): Pressure (1D array) in decibars. Must be the same shape as t.

Returns:

ndarray: Specific Volume Anomaly in kg m^{-3}.

pyfvcom2.ocean.theta_sw(t, s, p, pr)[source]

Calculate potential temperature for seawater from temperature, salinity and pressure.

Args:

t (ndarray): Temperature (1D array) in degrees Celsius. s (ndarray): Salinity (1D array) in practical salinity units (unitless). Must be the

same shape as t.

p (ndarray): Pressure (1D array) in decibars. Must be the same shape as t. pr (ndarray): Reference pressure (decibars) either a scalar or the same shape as t.

Returns:

ndarray: Potential temperature (Celsius).

pyfvcom2.ocean.zbar(data, levels)[source]

Depth-average values in data.

Args:

data (ndarray): Values to be depth-averaged. Shape is [t, z, x] where t is time, z is: vertical and x is space (unstructured).

levels (ndarray): Array of vertical layer thicknesses. Shape is [z, x] or [t, z, x].

Returns:

ndarray: Depth-averaged values in data.