# API

`SeawaterPolynomials`

`SeawaterPolynomials.AbstractSeawaterPolynomial`

— Type`AbstractSeawaterPolynomial`

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

`SeawaterPolynomials.haline_contraction`

— Method`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.

`SeawaterPolynomials.haline_sensitivity`

— Function`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.

`SeawaterPolynomials.thermal_expansion`

— Method`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.

`SeawaterPolynomials.thermal_sensitivity`

— Function`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.

*decreases* downwards to negative values, towards the bottom of the ocean.

`SeawaterPolynomials.ρ`

— Method`ρ(Θ, 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`

.

*decreases* downwards to negative values, towards the bottom of the ocean.

This function aliases `total_density`

.

`SeawaterPolynomials.ρ′`

— Function`ρ′(Θ, 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`

.

*decreases* downwards to negative values, towards the bottom of the ocean.

The function aliases `density_anomaly`

.

`SeawaterPolynomials.TEOS10`

`SeawaterPolynomials.TEOS10.TEOS10EquationOfState`

— Type`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."

`SeawaterPolynomials.TEOS10.TEOS10SeawaterPolynomial`

— Type`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).

`SeawaterPolynomials.TEOS10.TEOS10SeawaterPolynomial`

— Type`struct TEOS10SeawaterPolynomial{FT} <: AbstractSeawaterPolynomial end`

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

`SeawaterPolynomials.haline_sensitivity`

— Method`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.

`SeawaterPolynomials.thermal_sensitivity`

— Method`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.

`SeawaterPolynomials.ρ`

— Method`ρ(Θ, 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.

`SeawaterPolynomials.SecondOrderSeawaterPolynomials`

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.SecondOrderSeawaterPolynomial`

— Type`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ᴬ * Θ + ⋯`

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.CabbelingRoquetSeawaterPolynomial`

— Function`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`

.

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.CabbelingThermobaricityRoquetSeawaterPolynomial`

— Function`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`

.

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.FreezingRoquetSeawaterPolynomial`

— Function`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`

.

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.LinearRoquetSeawaterPolynomial`

— Function`LinearRoquetSeawaterPolynomial([FT=Float64])`

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

For more information see `RoquetSeawaterPolynomial`

.

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.RoquetEquationOfState`

— Function`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).

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.RoquetSeawaterPolynomial`

— Function`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.

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.SecondOrderRoquetSeawaterPolynomial`

— Function`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`

.

`SeawaterPolynomials.SecondOrderSeawaterPolynomials.SimplestRealisticRoquetSeawaterPolynomial`

— Function`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`

.