API

AbstractSeawaterPolynomial

Abstract type for Boussinesq equations of state expressed as polynomial functions of conservative temperature, absolute salinity, and geopotential depth.

haline_contraction(Θ, Sᴬ, Z, equation_of_state)

Return the "Boussinesq haline contraction coefficient" for a seawater parcel with reference density ρᵣ and absolute salinity Sᴬ, at fixed conservative temperture Θ and geopotential height Z, using the Boussinesq equation_of_state. The haline contraction coefficient is

\[β(Θ, Sᴬ, Z) = \left.\frac{1}{ρᵣ} \frac{∂ρ}{∂Sᴬ}\right|_{Θ, Z},\]

and describes changes in seawater density due to changes in absolute salinity. 'Haline contraction' is so named because, due to sign convention, positive values reflect increasing seawater density with increasing absolute salinity, and thus a slight 'contraction' of oceanic fluid parcels.

The geopotential height is defined such that $Z(x, y) = 0$ at sea level and decreases downwards to negative values, towards the bottom of the ocean.

haline_sensitivity(Θ, Sᴬ, Z, equation_of_state)

Return the "Boussinesq haline sensitivity coefficient" for a seawater parcel with absolute salinity Sᴬ, at fixed conservative temperature Θ, and geopotential height Z, using the Boussinesq equation_of_state. The haline sensitivity coefficient is

\[b(Θ, Sᴬ, Z) = \left.\frac{∂ρ}{∂Sᴬ}\right|_{Θ, Z} ,\]

and measures how much seawater density changes when absolute salinity is changed. It has units of [kg/m³/(g/kg)], and differs from haline_contraction ($β$) by a factor of the reference density $ρᵣ$. The sign of the haline sensitivity coefficient is defined to be consistent with the haline contraction coefficient.

The geopotential height is defined such that $Z(x, y) = 0$ at sea level and decreases downwards to negative values, towards the bottom of the ocean.

thermal_expansion(Θ, Sᴬ, Z, equation_of_state)

Return the "Boussinesq thermal expansion coefficient" for a seawater parcel with reference density ρᵣ and conservative temperture Θ, at fixed absolute salinity Sᴬ and geopotential height Z, using the Boussinesq equation_of_state. The thermal expansion coefficient is

\[α(Θ, Sᴬ, Z) = - \left.\frac{1}{ρᵣ} \frac{∂ρ}{∂Θ}\right|_{Sᴬ, Z} ,\]

and describes seawater density changes due to changes in conservative temperature. 'Thermal expansion' is so named because, due to sign convention, positive values reflect decreasing seawater density with increasing conservative temperature, and thus an 'expansion' of oceanic fluid parcels. In many, but not all conditions in Earth's ocean (at temperatures greater than 4ᵒC in freshwater), the thermal expansion coefficient is positive.

The geopotential height is defined such that $Z(x, y) = 0$ at sea level and decreases downwards to negative values, towards the bottom of the ocean.

thermal_sensitivity(Θ, Sᴬ, Z, equation_of_state)

Return the "Boussinesq thermal sensitivity coefficient" for a seawater parcel with conservative temperature Θ, at fixed absolute salinity Sᴬ, and geopotential height Z using the Boussinesq equation_of_state. The thermal sensitivity coefficient is

\[a(Θ, Sᴬ, Z) = - \left.\frac{∂ρ}{∂Θ}\right|_{Sᴬ, Z} ,\]

and measures how much seawater density changes when conservative temperature is changed. It has units of [kg/m³/(g/kg)], and differs from thermal_expansion ($α$) by a factor of the reference density $ρᵣ$. In many, but not all conditions in Earth's ocean (at temperatures greater than 4ᵒC in freshwater), the thermal sensitivity coefficient is positive.

The geopotential height is defined such that $Z(x, y) = 0$ at sea level and decreases downwards to negative values, towards the bottom of the ocean.

ρ(Θ, Sᴬ, Z, equation_of_state)

Return the total density of a seawater parcel with conservative temperature Θ, absolute salinity Sᴬ, at the geopotential height Z, using the Boussinesq equation_of_state.

The geopotential height is defined such that $Z(x, y) = 0$ at sea level and decreases downwards to negative values, towards the bottom of the ocean.

This function aliases total_density.

ρ′(Θ, Sᴬ, Z, equation_of_state)

Return the density anomaly of a seawater parcel with conservative temperature Θ, absolute salinity Sᴬ, at the geopotential height Z, using the Boussinesq equation_of_state.

The geopotential height is defined such that $Z(x, y) = 0$ at sea level and decreases downwards to negative values, towards the bottom of the ocean.

The function aliases density_anomaly.

TEOS10EquationOfState(FT=Float64; reference_density=1020)

Return an BoussinesqEquationOfState with a TEOS10SeawaterPolynomial of float type FT with reference density = 1020 kg m⁻³, the value used by

Roquet et al., "Accurate polynomial expressions for the density and specific volume of seawater using the TEOS-10 standard", Ocean Modelling (2015).

when fitting polynomial coefficients to the full TEOS-10 standard equation of state. See the discussion prior to equation 8 in Roquet et al. (2015).

Note that according to Roquet et al. (2015):

"In a Boussinesq model, the choice of the $ρ₀$ value is important, yet it varies significantly among OGCMs, as it is a matter of personal preference."

TEOS10SeawaterPolynomial(FT=Float64)

Return an object representing a 55-term polynomial approximation to the TEOS-10 standard equation of state for seawater. See

Roquet et al., "Accurate polynomial expressions for the density and specific volume of seawater using the TEOS-10 standard", Ocean Modelling (2015).

struct TEOS10SeawaterPolynomial{FT} <: AbstractSeawaterPolynomial end

A 55-term polynomial approximation to the TEOS-10 standard equation of state for seawater.

Θ_from_T(Sᴬ, T, p)

Return the TEOS-10 conservative temperature $Θ$ from absolute salinity, in-situ temperature and sea pressure, computed as Θ_from_θ(Sᴬ, θ_from_T(Sᴬ, T, p)). Direct translation of gsw_ct_from_t of https://github.com/TEOS-10/GSW-C.

Inputs

• Sᴬ: absolute salinity [g/kg]
• T : in-situ temperature, ITS-90 [°C]
• p : sea pressure [dbar]

Output

• Θ : conservative temperature [°C]

References

• IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of seawater – 2010. http://www.teos-10.org/pubs/TEOS-10_Manual.pdf

Θ_from_θ(Sᴬ, θ)

Return the TEOS-10 conservative temperature $Θ$ from absolute salinity $Sᴬ$ and potential temperature $θ$ referenced to $p = 0$ dbar, computed as $Θ = h⁰(Sᴬ, θ) / cᵖ⁰$ where $h⁰$ is the potential-enthalpy polynomial and $cᵖ⁰ = 3991.867957...$ J/kg/K is the TEOS-10 reference heat capacity. Direct translation of gsw_ct_from_pt of https://github.com/TEOS-10/GSW-C.

Inputs

• Sᴬ: absolute salinity [g/kg]
• θ : potential temperature, ITS-90, p_ref = 0 dbar [°C]

Output

• Θ : conservative temperature [°C]

References

• IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of seawater – 2010: Calculation and use of thermodynamic properties. Intergovernmental Oceanographic Commission, Manuals and Guides No. 56, UNESCO. http://www.teos-10.org/pubs/TEOS-10_Manual.pdf

θ_from_T(Sᴬ, T, p)

Return the TEOS-10 potential temperature $θ$ referenced to $p = 0$ dbar from absolute salinity, in-situ temperature and sea pressure. $θ$ is the root of $η(Sᴬ, θ, 0) = η(Sᴬ, T, p)$, found with a polynomial first guess followed by two modified Newton–Raphson iterations (McDougall and Wotherspoon, 2014). Direct translation of gsw_pt0_from_t of https://github.com/TEOS-10/GSW-C.

Inputs

• Sᴬ: absolute salinity [g/kg]
• T : in-situ temperature, ITS-90 [°C]
• p : sea pressure (gauge: absolute pressure − 10.1325 dbar) [dbar]

Output

• θ : potential temperature, p_ref = 0 dbar [°C]

References

• IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of seawater – 2010. http://www.teos-10.org/pubs/TEOS-10_Manual.pdf
• McDougall, T. J. and S. J. Wotherspoon, 2014: A simple modification of Newton's method to achieve convergence of order 1 + √2. Applied Mathematics Letters, 29, 20–25.

θ_from_Θ(Sᴬ, Θ)

Return the TEOS-10 potential temperature $θ$ referenced to $p = 0$ dbar from absolute salinity and conservative temperature. $θ$ is the root of $Θ_from_θ(Sᴬ, θ) = Θ$, found with a rational-polynomial first guess followed by one and a half modified Newton–Raphson iterations (McDougall and Wotherspoon, 2014). Direct translation of gsw_pt_from_ct of https://github.com/TEOS-10/GSW-C.

Inputs

• Sᴬ: absolute salinity [g/kg]
• Θ : conservative temperature [°C]

Output

• θ : potential temperature, p_ref = 0 dbar [°C]

References

• IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of seawater – 2010. http://www.teos-10.org/pubs/TEOS-10_Manual.pdf
• McDougall, T. J. and S. J. Wotherspoon, 2014: A simple modification of Newton's method to achieve convergence of order 1 + √2. Applied Mathematics Letters, 29, 20–25.

haline_sensitivity(Θ, Sᴬ, Z, ::TEOS10)

Return the Boussinesq haline sensitivity coefficient $∂ρ/∂Sᴬ$ [kg/m³/(g/kg)] computed using the 55-term polynomial approximation to TEOS-10 described in Roquet et al. (§3.1, 2014).

Inputs

• Θ: conservative temperature (ITS-90) [°C]
• Sᴬ: absolute salinity [g/kg]
• Z: geopotential depth [m]

Output

• b: Boussinesq haline sensitivity coefficient $∂ρ/∂Sᴬ$ [kg/m³/(g/kg)]

References

• Roquet, F., Madec, G., McDougall, T. J., Barker, P. M., 2014: Accurate polynomial expressions for the density and specific volume of seawater using the TEOS-10 standard. Ocean Modelling.

thermal_sensitivity(Θ, Sᴬ, Z, ::TEOS10)

Return the Boussinesq thermal sensitivity coefficient $-∂ρ/∂Θ$ [kg/m³/K] computed using the 55-term polynomial approximation to TEOS-10 described in Roquet et al. (§3.1, 2014).

Inputs

• Θ: conservative temperature (ITS-90) [°C]
• Sᴬ: absolute salinity [g/kg]
• Z: geopotential depth [m]

Output

• a: Boussinesq thermal sensitivity coefficient $-∂ρ/∂Θ$ [kg/m³/K]

References

• Roquet, F., Madec, G., McDougall, T. J., Barker, P. M., 2014: Accurate polynomial expressions for the density and specific volume of seawater using the TEOS-10 standard. Ocean Modelling.

ρ(Θ, Sᴬ, Z, ::BoussinesqEquationOfState{<:TEOS10EquationOfState})

Return the in-situ density of seawater with state (Θ, Sᴬ, Z) using the 55-term polynomial approximation to TEOS-10 described in Roquet et al. (§3.1, 2014).

Inputs

• Θ: conservative temperature (ITS-90) [°C]
• Sᴬ: absolute salinity [g/kg]
• Z: geopotential depth [m]

Output

• ρ: in-situ density [kg/m³]

References

• Roquet, F., Madec, G., McDougall, T. J., Barker, P. M., 2014: Accurate polynomial expressions for the density and specific volume of seawater using the TEOS-10 standard. Ocean Modelling.

struct SecondOrderSeawaterPolynomial{FT} <: AbstractSeawaterPolynomial

Container of coefficients for a second-order polynomial function of absolute salinity Sᴬ, conservative temperature Θ, and geopotential depth Z for seawater density.

The coefficients have the form

\[Rᵦᵪᵩ ,\]

where $β, χ, φ$ denote the order of the term to which the coefficent corresponds: $β$ is the polynomial order of absolute salinity, $Sᴬ$, $χ$ is the polynomial order of conservative temperature, $Θ$, and $φ$ is the order of geopotential height, $Z$.

For a SecondOrderSeawaterPolynomial, $β + χ + φ < 3$.

The coefficient $R₁₁₀$ arises in the seawater polynomial as

seawater_polynomial(Θ, Sᴬ, Z) = ⋯ + R₁₁₀ * Sᴬ * Θ + ⋯

CabbelingRoquetSeawaterPolynomial([FT=Float64])

Parameters for a minimal equation of state that describes cabbeling, optimized for the 'current' oceanic temperature and salinity distribution.

For more information see RoquetSeawaterPolynomial.

CabbelingThermobaricityRoquetSeawaterPolynomial([FT=Float64])

Parameters for a minimal equation of state that describes cabbeling and thermobaric effects on sewater density, optimized for the 'current' oceanic temperature and salinity distribution.

For more information see RoquetSeawaterPolynomial.

FreezingRoquetSeawaterPolynomial(FT=Float64)

Parameters for a minimal equation of state that describes seawater density near its freezing point, optimized for the 'current' oceanic temperature and salinity distribution.

For more information see RoquetSeawaterPolynomial.

LinearRoquetSeawaterPolynomial([FT=Float64])

Parameters for a linear equation of state optimized for the 'current' oceanic temperature and salinity distribution.

For more information see RoquetSeawaterPolynomial.

RoquetEquationOfState([FT=Float64,] coefficient_set=:SecondOrder; reference_density=1024.6)

Return an BoussinesqEquationOfState with a RoquetSeawaterPolynomial corresponding to coefficient_set and with reference density = 1024.6 kg m⁻³, the average density of seawater at the surface of the world ocean.

See RoquetSeawaterPolynomial for options for the coefficient_set. The optimzed coefficient sets for the RoquetSeawaterPolynomial are listed in Table 3 in

Roquet et al., "Defining a Simplified yet 'Realistic' Equation of State for Seawater", Journal of Physical Oceanography (2015).

RoquetSeawaterPolynomial([FT=Float64,] coefficient_set=:SecondOrder)

Return a SecondOrderSeawaterPolynomial with coefficients optimized by

Roquet et al., "Defining a Simplified yet 'Realistic' Equation of State for Seawater", Journal of Physical Oceanography (2015).

The coefficient_set is a symbol or string that selects one of the "sets" of optimized second order coefficients.

Coefficient sets

• :Linear: a linear equation of state, $ρ = ρᵣ + R₀₁₀ Θ + R₁₀₀ Sᴬ$.

• :Cabbeling: includes quadratic temperature term, $ρ = ρᵣ + R₀₁₀ Θ + R₁₀₀ Sᴬ + R₀₂₀ Θ²$.

• :CabbelingThermobaricity: includes 'thermobaricity' term, $ρ = ρᵣ + R₀₁₀ Θ + R₁₀₀ Sᴬ + R₀₂₀ Θ² - R₀₁₁ Θ Z$.

• :Freezing: same as :cabbeling_thermobaricity with modified constants to increase accuracy near freezing.

• :SecondOrder: includes quadratic salinity, halibaricity, and thermohaline term, $ρ = ρᵣ + R₁₀₀ Sᴬ + R₀₁₀ Θ + R₀₂₀ Θ² - R₀₁₁ Θ Z + R₂₀₀ (Sᴬ)² - R₁₀₁ Sᴬ Z + R₁₁₀ Sᴬ Θ$.

• :SimplestRealistic: the proposed simplest though "realistic" equation of state for seawater from Roquet et al. (2015), $ρ = ρᵣ + R₁₀₀ Sᴬ + R₀₁₀ Θ - R₀₂₀ Θ² - R₀₁₁ Θ Z$

The optimized coefficients are reported in Table 3 of Roquet et al., "Defining a Simplified yet 'Realistic' Equation of State for Seawater", Journal of Physical Oceanography (2015), and further discussed around equations (12)–(15). The optimization minimizes errors in estimated horizontal density gradient estiamted from climatological temperature and salinity distributions between the 5 simplified forms chosen by Roquet et. al and the full-fledged TEOS-10 equation of state. The :SimplestRealistic equation of state is equation (17) in Roquet et al. (2015) which they propose is the simplest yet "realistic" form for the equation of state for the density of seawater.

Note: In equation (17) by Roquet et al. (2015), the :SimplestRealistic equation of state has an extra term $R₀₀₀ = - C_b Θ₀² / 2$ that is not included in the coefficient set above since this term has no effect on ocean dynamics.

SecondOrderRoquetSeawaterPolynomial([FT=Float64])

Parameters for a fully second-order equation of state for seawater, optimized for the 'current' oceanic temperature and salinity distribution.

For more information see RoquetSeawaterPolynomial.

SimplestRealisticRoquetSeawaterPolynomial([FT=Float64])

Parameters for the simplest yet "realistic" equation of state for seawater from Roquet et al. (2015) (see equation (17)), optimized for the 'current' oceanic temperature and salinity distribution.

For more information see RoquetSeawaterPolynomial.