mom_eos module reference¶

Provides subroutines for quantities specific to the equation of state.

Data Types¶

eos_type

A control structure for the equation of state.

Functions/Subroutines¶

`calculate_density_elem()`	Density of sea water (in-situ if pressure is local) [R ~> kg m-3].
`calculate_density_scalar()`	Calls the appropriate subroutine to calculate density of sea water for scalar inputs.
`calculate_stanley_density_scalar()`	Calls the appropriate subroutine to calculate density of sea water for scalar inputs including the variance of T, S and covariance of T-S.
`calculate_density_1d()`	Calls the appropriate subroutine to calculate the density of sea water for 1-D array inputs, potentially limiting the domain of indices that are worked on.
`calculate_stanley_density_1d()`	Calls the appropriate subroutine to calculate the density of sea water for 1-D array inputs including the variance of T, S and covariance of T-S, potentially limiting the domain of indices that are worked on.
`calculate_spec_vol_array()`	Calls the appropriate subroutine to calculate the specific volume of sea water for 1-D array inputs.
`calc_spec_vol_scalar()`	Calls the appropriate subroutine to calculate specific volume of sea water for scalar inputs.
`calc_spec_vol_1d()`	Calls the appropriate subroutine to calculate the specific volume of sea water for 1-D array inputs, potentially limiting the domain of indices that are worked on.
`calculate_tfreeze_scalar()`	Calls the appropriate subroutine to calculate the freezing point for scalar inputs.
`calculate_tfreeze_array()`	Calls the appropriate subroutine to calculate the freezing point for a 1-D array.
`calculate_tfreeze_1d()`	Calls the appropriate subroutine to calculate the freezing point for a 1-D array, taking dimensionally rescaled arguments with factors stored in EOS.
`calculate_density_derivs_array()`	Calls the appropriate subroutine to calculate density derivatives for 1-D array inputs.
`calculate_density_derivs_1d()`	Calls the appropriate subroutine to calculate density derivatives for 1-D array inputs.
`calculate_density_derivs_scalar()`	Calls the appropriate subroutines to calculate density derivatives by promoting a scalar to a one-element array.
`calculate_density_second_derivs_1d()`	Calls the appropriate subroutine to calculate density second derivatives for 1-D array inputs.
`calculate_density_second_derivs_scalar()`	Calls the appropriate subroutine to calculate density second derivatives for scalar inputs.
`calculate_spec_vol_derivs_array()`	Calls the appropriate subroutine to calculate specific volume derivatives for an array.
`calc_spec_vol_derivs_1d()`	Calls the appropriate subroutine to calculate specific volume derivatives for 1-d array inputs, potentially limiting the domain of indices that are worked on.
`calculate_compress_1d()`	Calls the appropriate subroutine to calculate the density and compressibility for 1-D array inputs.
`calculate_compress_scalar()`	Calculate density and compressibility for a scalar.
`average_specific_vol()`	Calls the appropriate subroutine to calculate the layer averaged specific volume either using Boole’s rule quadrature or analytical and nearly-analytical averages in pressure.
`eos_fit_range()`	Return the range of temperatures, salinities and pressures for which the equation of state that is being used has been fitted to observations.
`eos_domain()`	This subroutine returns a two point integer array indicating the domain of i-indices to work on in EOS calls based on information from a hor_index type.
`analytic_int_specific_vol_dp()`	Calls the appropriate subroutine to calculate analytical and nearly-analytical integrals in pressure across layers of geopotential anomalies, which are required for calculating the finite-volume form pressure accelerations in a non-Boussinesq model.
`analytic_int_density_dz()`	This subroutine calculates analytical and nearly-analytical integrals of pressure anomalies across layers, which are required for calculating the finite-volume form pressure accelerations in a Boussinesq model.
`query_compressible()`	Returns true if the equation of state is compressible (i.e.
`get_eos_name()`	Returns the string identifying the equation of state with enumeration “id”.
`eos_init()`	Initializes EOS_type by allocating and reading parameters.
`eos_manual_init()`	Manually initialized an EOS type (intended for unit testing of routines which need a specific EOS)
`eos_use_linear()`	Set equation of state structure (EOS) to linear with given coefficients.
`convert_temp_salt_for_teos10()`	Convert T&S to Absolute Salinity and Conservative Temperature if using TEOS10.
`cons_temp_to_pot_temp()`	Converts an array of conservative temperatures to potential temperatures.
`pot_temp_to_cons_temp()`	Converts an array of potential temperatures to conservative temperatures.
`abs_saln_to_prac_saln()`	Converts an array of absolute salinity to practical salinity.
`prac_saln_to_abs_saln()`	Converts an array of absolute salinity to practical salinity.
`eos_quadrature()`	Return value of EOS_quadrature.
`eos_unit_tests()`	Runs unit tests for consistency on the equations of state.
`test_ts_conversion_consistency()`
`test_tfr_consistency()`
`write_check_msg()`	Write a message indicating how well a value matches its check value.
`test_eos_consistency()`	Test an equation of state for self-consistency and consistency with check values, returning false if it is consistent by all tests, and true if it fails any test.

Detailed Description¶

The MOM_EOS module is a wrapper for various equations of state (i.e. Linear, Wright, Wright_full, Wright_red, UNESCO, TEOS10, Roquet_SpV or Roquet_rho) and provides a uniform interface to the rest of the model independent of which equation of state is being used.

Type Documentation¶

type mom_eos/eos_type¶

A control structure for the equation of state.

Type fields:

% form_of_eos [integer] :: The equation of state to use.
% form_of_tfreeze [integer] :: The expression for the potential temperature of the freezing point.
% eos_quadrature [logical] :: If true, always use the generic (quadrature) code for the integrals of density.
% compressible [logical] :: If true, in situ density is a function of pressure.
% rho_t0_s0 [real] :: The density at T=0, S=0 [kg m-3].
% drho_dt [real] :: The partial derivative of density with temperature [kg m-3 degC-1].
% drho_ds [real] :: The partial derivative of density with salinity [kg m-3 ppt-1].
% tfr_s0_p0 [real] :: The freezing potential temperature at S=0, P=0 [degC].
% dtfr_ds [real] :: The derivative of freezing point with salinity [degC ppt-1].
% dtfr_dp [real] :: The derivative of freezing point with pressure [degC Pa-1].
% use_wright_2nd_deriv_bug [logical] :: If true, use a separate subroutine that retains a buggy version of the calculations of the second derivative of density with temperature and with temperature and pressure. This bug is corrected in the default version.
% m_to_z [real] :: A constant that translates distances in meters to the units of depth [Z m-1 ~> 1].
% kg_m3_to_r [real] :: A constant that translates kilograms per meter cubed to the units of density [R m3 kg-1 ~> 1].
% r_to_kg_m3 [real] :: A constant that translates the units of density to kilograms per meter cubed [kg m-3 R-1 ~> 1].
% rl2_t2_to_pa [real] :: Convert pressures from R L2 T-2 to Pa [Pa T2 R-1 L-2 ~> 1].
% l_t_to_m_s [real] :: Convert lateral velocities from L T-1 to m s-1 [m T s-1 L-1 ~> 1].
% degc_to_c [real] :: A constant that translates degrees Celsius to the units of temperature [C degC-1 ~> 1].
% c_to_degc [real] :: A constant that translates the units of temperature to degrees Celsius [degC C-1 ~> 1].
% ppt_to_s [real] :: A constant that translates parts per thousand to the units of salinity [S ppt-1 ~> 1].
% s_to_ppt [real] :: A constant that translates the units of salinity to parts per thousand [ppt S-1 ~> 1].
% type [class( eos_base ),allocatable] :: The instance of the actual equation of state.

Function/Subroutine Documentation¶

function mom_eos/calculate_density_elem(EOS, T, S, pressure, rho_ref, scale) [elemental]¶

Density of sea water (in-situ if pressure is local) [R ~> kg m-3].

If rho_ref is present, the anomaly with respect to rho_ref is returned. The pressure and density can be rescaled with the values stored in EOS. If the scale argument is present the density scaling uses the product of the two scaling factors.

Parameters:

eos :: [in] Equation of state structure
t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
rho_ref :: [in] A reference density [R ~> kg m-3]
scale :: [in] A multiplicative factor by which to scale output density in combination with scaling stored in EOS [various]

subroutine mom_eos/calculate_density_scalar(T, S, pressure, rho, EOS, rho_ref, scale)¶

Calls the appropriate subroutine to calculate density of sea water for scalar inputs. If rho_ref is present, the anomaly with respect to rho_ref is returned. The pressure and density can be rescaled with the values stored in EOS. If the scale argument is present the density scaling uses the product of the two scaling factors.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
rho :: [out] Density (in-situ if pressure is local) [R ~> kg m-3]
eos :: [in] Equation of state structure
rho_ref :: [in] A reference density [R ~> kg m-3]
scale :: [in] A multiplicative factor by which to scale output density in combination with scaling stored in EOS [various]

Called from:

mom_eos::calculate_density::calculate_stanley_density_scalar

subroutine mom_eos/calculate_stanley_density_scalar(T, S, pressure, Tvar, TScov, Svar, rho, EOS, rho_ref, scale)¶

Calls the appropriate subroutine to calculate density of sea water for scalar inputs including the variance of T, S and covariance of T-S. The calculation uses only the second order correction in a series as discussed in Stanley et al., 2020. If rho_ref is present, the anomaly with respect to rho_ref is returned. The density can be rescaled using rho_ref.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
tvar :: [in] Variance of potential temperature referenced to the surface [C2 ~> degC2]
tscov :: [in] Covariance of potential temperature and salinity [C S ~> degC ppt]
svar :: [in] Variance of salinity [S2 ~> ppt2]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
rho :: [out] Density (in-situ if pressure is local) [R ~> kg m-3]
eos :: [in] Equation of state structure
rho_ref :: [in] A reference density [R ~> kg m-3].
scale :: [in] A multiplicative factor by which to scale output density in combination with scaling stored in EOS [various]

subroutine mom_eos/calculate_density_1d(T, S, pressure, rho, EOS, dom, rho_ref, scale)¶

Calls the appropriate subroutine to calculate the density of sea water for 1-D array inputs, potentially limiting the domain of indices that are worked on. If rho_ref is present, the anomaly with respect to rho_ref is returned.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
rho :: [inout] Density (in-situ if pressure is local) [R ~> kg m-3]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
rho_ref :: [in] A reference density [R ~> kg m-3]
scale :: [in] A multiplicative factor by which to scale density in combination with scaling stored in EOS [various]

Called from:

mom_eos::calculate_density::calculate_stanley_density_1d

subroutine mom_eos/calculate_stanley_density_1d(T, S, pressure, Tvar, TScov, Svar, rho, EOS, dom, rho_ref, scale)¶

Calls the appropriate subroutine to calculate the density of sea water for 1-D array inputs including the variance of T, S and covariance of T-S, potentially limiting the domain of indices that are worked on. The calculation uses only the second order correction in a series as discussed in Stanley et al., 2020. If rho_ref is present, the anomaly with respect to rho_ref is returned.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
tvar :: [in] Variance of potential temperature [C2 ~> degC2]
tscov :: [in] Covariance of potential temperature and salinity [C S ~> degC ppt]
svar :: [in] Variance of salinity [S2 ~> ppt2]
rho :: [inout] Density (in-situ if pressure is local) [R ~> kg m-3]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
rho_ref :: [in] A reference density [R ~> kg m-3]
scale :: [in] A multiplicative factor by which to scale density in combination with scaling stored in EOS [various]

subroutine mom_eos/calculate_spec_vol_array(T, S, pressure, specvol, start, npts, EOS, spv_ref, scale)¶

Calls the appropriate subroutine to calculate the specific volume of sea water for 1-D array inputs.

Parameters:

t :: [in] potential temperature relative to the surface [degC]
s :: [in] salinity [ppt]
pressure :: [in] pressure [Pa]
specvol :: [inout] in situ specific volume [kg m-3]
start :: [in] the starting point in the arrays.
npts :: [in] the number of values to calculate.
eos :: [in] Equation of state structure
spv_ref :: [in] A reference specific volume [m3 kg-1]
scale :: [in] A multiplicative factor by which to scale specific volume in combination with scaling stored in EOS [various]

Called from:

mom_eos::calculate_spec_vol::calc_spec_vol_1d mom_eos::calculate_spec_vol::calc_spec_vol_scalar

subroutine mom_eos/calc_spec_vol_scalar(T, S, pressure, specvol, EOS, spv_ref, scale)¶

Calls the appropriate subroutine to calculate specific volume of sea water for scalar inputs.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
specvol :: [out] In situ or potential specific volume [R-1 ~> m3 kg-1] or other units determined by the scale argument
eos :: [in] Equation of state structure
spv_ref :: [in] A reference specific volume [R-1 ~> m3 kg-1]
scale :: [in] A multiplicative factor by which to scale specific volume in combination with scaling stored in EOS [various]

subroutine mom_eos/calc_spec_vol_1d(T, S, pressure, specvol, EOS, dom, spv_ref, scale)¶

Calls the appropriate subroutine to calculate the specific volume of sea water for 1-D array inputs, potentially limiting the domain of indices that are worked on.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
specvol :: [inout] In situ specific volume [R-1 ~> m3 kg-1]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
spv_ref :: [in] A reference specific volume [R-1 ~> m3 kg-1]
scale :: [in] A multiplicative factor by which to scale output specific volume in combination with scaling stored in EOS [various]

subroutine mom_eos/calculate_tfreeze_scalar(S, pressure, T_fr, EOS, pres_scale, scale_from_EOS)¶

Calls the appropriate subroutine to calculate the freezing point for scalar inputs.

Parameters:

s :: [in] Salinity, [ppt] or [S ~> ppt] depending on scale_from_EOS
pressure :: [in] Pressure, in [Pa] or [R L2 T-2 ~> Pa] depending on pres_scale or scale_from_EOS
t_fr :: [out] Freezing point potential temperature referenced to the surface [degC] or [C ~> degC] depending on scale_from_EOS
eos :: [in] Equation of state structure
pres_scale :: [in] A multiplicative factor to convert pressure into Pa [Pa T2 R-1 L-2 ~> 1].
scale_from_eos :: [in] If present true use the dimensional scaling factors stored in EOS. Omission is the same .false.

subroutine mom_eos/calculate_tfreeze_array(S, pressure, T_fr, start, npts, EOS, pres_scale)¶

Calls the appropriate subroutine to calculate the freezing point for a 1-D array.

Parameters:

s :: [in] Salinity [ppt]
pressure :: [in] Pressure, in [Pa] or [R L2 T-2 ~> Pa] depending on pres_scale
t_fr :: [inout] Freezing point potential temperature referenced to the surface [degC]
start :: [in] Starting index within the array
npts :: [in] The number of values to calculate
eos :: [in] Equation of state structure
pres_scale :: [in] A multiplicative factor to convert pressure into Pa [Pa T2 R-1 L-2 ~> 1].

subroutine mom_eos/calculate_tfreeze_1d(S, pressure, T_fr, EOS, dom)¶

Calls the appropriate subroutine to calculate the freezing point for a 1-D array, taking dimensionally rescaled arguments with factors stored in EOS.

Parameters:

s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
t_fr :: [inout] Freezing point potential temperature referenced to the surface [C ~> degC]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.

subroutine mom_eos/calculate_density_derivs_array(T, S, pressure, drho_dT, drho_dS, start, npts, EOS, scale)¶

Calls the appropriate subroutine to calculate density derivatives for 1-D array inputs.

Parameters:

t :: [in] Potential temperature referenced to the surface [degC]
s :: [in] Salinity [ppt]
pressure :: [in] Pressure [Pa]
drho_dt :: [inout] The partial derivative of density with potential temperature [kg m-3 degC-1] or other units determined by the optional scale argument
drho_ds :: [inout] The partial derivative of density with salinity, in [kg m-3 ppt-1] or other units determined by the optional scale argument
start :: [in] Starting index within the array
npts :: [in] The number of values to calculate
eos :: [in] Equation of state structure
scale :: [in] A multiplicative factor by which to scale density in combination with scaling stored in EOS [various]

Called from:

mom_eos::calculate_density_derivs::calculate_density_derivs_1d

subroutine mom_eos/calculate_density_derivs_1d(T, S, pressure, drho_dT, drho_dS, EOS, dom, scale)¶

Calls the appropriate subroutine to calculate density derivatives for 1-D array inputs.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
drho_dt :: [inout] The partial derivative of density with potential temperature [R C-1 ~> kg m-3 degC-1]
drho_ds :: [inout] The partial derivative of density with salinity [R S-1 ~> kg m-3 ppt-1]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale density in combination with scaling stored in EOS [various]

subroutine mom_eos/calculate_density_derivs_scalar(T, S, pressure, drho_dT, drho_dS, EOS, scale)¶

Calls the appropriate subroutines to calculate density derivatives by promoting a scalar to a one-element array.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
drho_dt :: [out] The partial derivative of density with potential temperature [R C-1 ~> kg m-3 degC-1] or other units determined by the optional scale argument
drho_ds :: [out] The partial derivative of density with salinity, in [R S-1 ~> kg m-3 ppt-1] or other units determined by the optional scale argument
eos :: [in] Equation of state structure
scale :: [in] A multiplicative factor by which to scale density in combination with scaling stored in EOS [various]

subroutine mom_eos/calculate_density_second_derivs_1d(T, S, pressure, drho_dS_dS, drho_dS_dT, drho_dT_dT, drho_dS_dP, drho_dT_dP, EOS, dom, scale)¶

Calls the appropriate subroutine to calculate density second derivatives for 1-D array inputs.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
drho_ds_ds :: [inout] Partial derivative of beta with respect to S [R S-2 ~> kg m-3 ppt-2]
drho_ds_dt :: [inout] Partial derivative of beta with respect to T [R S-1 C-1 ~> kg m-3 ppt-1 degC-1]
drho_dt_dt :: [inout] Partial derivative of alpha with respect to T [R C-2 ~> kg m-3 degC-2]
drho_ds_dp :: [inout] Partial derivative of beta with respect to pressure [T2 S-1 L-2 ~> kg m-3 ppt-1 Pa-1]
drho_dt_dp :: [inout] Partial derivative of alpha with respect to pressure [T2 C-1 L-2 ~> kg m-3 degC-1 Pa-1]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale density in combination with scaling stored in EOS [various]

Called from:

mom_eos::calculate_density::calculate_stanley_density_1d

subroutine mom_eos/calculate_density_second_derivs_scalar(T, S, pressure, drho_dS_dS, drho_dS_dT, drho_dT_dT, drho_dS_dP, drho_dT_dP, EOS, scale)¶

Calls the appropriate subroutine to calculate density second derivatives for scalar inputs.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
drho_ds_ds :: [out] Partial derivative of beta with respect to S [R S-2 ~> kg m-3 ppt-2]
drho_ds_dt :: [out] Partial derivative of beta with respect to T [R S-1 C-1 ~> kg m-3 ppt-1 degC-1]
drho_dt_dt :: [out] Partial derivative of alpha with respect to T [R C-2 ~> kg m-3 degC-2]
drho_ds_dp :: [out] Partial derivative of beta with respect to pressure [T2 S-1 L-2 ~> kg m-3 ppt-1 Pa-1]
drho_dt_dp :: [out] Partial derivative of alpha with respect to pressure [T2 C-1 L-2 ~> kg m-3 degC-1 Pa-1]
eos :: [in] Equation of state structure
scale :: [in] A multiplicative factor by which to scale density in combination with scaling stored in EOS [various]

Called from:

mom_eos::calculate_density::calculate_stanley_density_scalar

subroutine mom_eos/calculate_spec_vol_derivs_array(T, S, pressure, dSV_dT, dSV_dS, start, npts, EOS)¶

Calls the appropriate subroutine to calculate specific volume derivatives for an array.

Parameters:

t :: [in] Potential temperature referenced to the surface [degC]
s :: [in] Salinity [ppt]
pressure :: [in] Pressure [Pa]
dsv_dt :: [inout] The partial derivative of specific volume with potential temperature [m3 kg-1 degC-1]
dsv_ds :: [inout] The partial derivative of specific volume with salinity [m3 kg-1 ppt-1]
start :: [in] Starting index within the array
npts :: [in] The number of values to calculate
eos :: [in] Equation of state structure

Called from:

mom_eos::calculate_specific_vol_derivs::calc_spec_vol_derivs_1d

subroutine mom_eos/calc_spec_vol_derivs_1d(T, S, pressure, dSV_dT, dSV_dS, EOS, dom, scale)¶

Calls the appropriate subroutine to calculate specific volume derivatives for 1-d array inputs, potentially limiting the domain of indices that are worked on.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
dsv_dt :: [inout] The partial derivative of specific volume with potential temperature [R-1 C-1 ~> m3 kg-1 degC-1]
dsv_ds :: [inout] The partial derivative of specific volume with salinity [R-1 S-1 ~> m3 kg-1 ppt-1]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale specific volume in combination with scaling stored in EOS [various]

subroutine mom_eos/calculate_compress_1d(T, S, pressure, rho, drho_dp, EOS, dom)¶

Calls the appropriate subroutine to calculate the density and compressibility for 1-D array inputs. The inputs and outputs use dimensionally rescaled units.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
rho :: [inout] In situ density [R ~> kg m-3]
drho_dp :: [inout] The partial derivative of density with pressure (also the inverse of the square of sound speed) [T2 L-2 ~> s2 m-2]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.

Called from:

mom_eos::calculate_compress::calculate_compress_scalar

subroutine mom_eos/calculate_compress_scalar(T, S, pressure, rho, drho_dp, EOS)¶

Calculate density and compressibility for a scalar. This just promotes the scalar to an array with a singleton dimension and calls calculate_compress_1d. The inputs and outputs use dimensionally rescaled units.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
pressure :: [in] Pressure [R L2 T-2 ~> Pa]
rho :: [out] In situ density [R ~> kg m-3]
drho_dp :: [out] The partial derivative of density with pressure (also the inverse of the square of sound speed) [T2 L-2 ~> s2 m-2]
eos :: [in] Equation of state structure

subroutine mom_eos/average_specific_vol(T, S, p_t, dp, SpV_avg, EOS, dom, scale)¶

Calls the appropriate subroutine to calculate the layer averaged specific volume either using Boole’s rule quadrature or analytical and nearly-analytical averages in pressure.

Parameters:

t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
p_t :: [in] Pressure at the top of the layer [R L2 T-2 ~> Pa]
dp :: [in] Pressure change in the layer [R L2 T-2 ~> Pa]
spv_avg :: [inout] The vertical average specific volume in the layer [R-1 ~> m3 kg-1]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale output specific volume in combination with scaling stored in EOS [various]

Call to:

eos_linear eos_wright eos_wright_full eos_wright_reduced

Called from:

mom_density_integrals::avg_specific_vol mom_interface_heights::find_rho_bottom test_eos_consistency

subroutine mom_eos/eos_fit_range(EOS, T_min, T_max, S_min, S_max, p_min, p_max)¶

Return the range of temperatures, salinities and pressures for which the equation of state that is being used has been fitted to observations. Care should be taken when applying this equation of state outside of its fit range.

Parameters:

eos :: [in] Equation of state structure
t_min :: [out] The minimum temperature over which this EoS is fitted [degC]
t_max :: [out] The maximum temperature over which this EoS is fitted [degC]
s_min :: [out] The minimum salinity over which this EoS is fitted [ppt]
s_max :: [out] The maximum salinity over which this EoS is fitted [ppt]
p_min :: [out] The minimum pressure over which this EoS is fitted [Pa]
p_max :: [out] The maximum pressure over which this EoS is fitted [Pa]

Called from:

test_eos_consistency

function mom_eos/eos_domain(HI, halo) [integer]¶

This subroutine returns a two point integer array indicating the domain of i-indices to work on in EOS calls based on information from a hor_index type.

Parameters:

hi :: [in] The horizontal index structure
halo :: [in] The halo size to work on; missing is equivalent to 0.

Return:

undefined :: The index domain that the EOS will work on, taking into account that the arrays inside the EOS routines will start at 1.

Called from:

mom::adjust_ssh_for_p_atm mom_isopycnal_slopes::calc_isoneutral_slopes mom_forcing_type::calculatebuoyancyflux1d mom_tracer_z_init::determine_temperature mom_set_diffusivity::double_diffusion mom_interface_heights::dz_to_thickness::dz_to_thickness_eos mom_entrain_diffusive::entrainment_diffusive mom_set_diffusivity::find_n2 mom_int_tide_input::find_n2_bottom mom_interface_heights::find_rho_bottom mom_set_diffusivity::find_tke_to_kd mom_diabatic_driver::layered_diabatic mom_mixed_layer_restrat::mixedlayer_restrat_bodner mom_mixed_layer_restrat::mixedlayer_restrat_om4 mom_pressureforce_fv::pressureforce_fv_bouss mom_regularize_layers::regularize_surface rgc_initialization::rgc_initialize_sponges mom_set_diffusivity::set_density_ratios mom_entrain_diffusive::set_ent_bl mom_full_convection::smoothed_drdt_drds mom_tracer_hor_diff::tracer_epipycnal_ml_diff user_change_diffusivity::user_change_diff

subroutine mom_eos/analytic_int_specific_vol_dp(T, S, p_t, p_b, alpha_ref, HI, EOS, dza, intp_dza, intx_dza, inty_dza, halo_size, bathyP, dP_tiny, useMassWghtInterp)¶

Calls the appropriate subroutine to calculate analytical and nearly-analytical integrals in pressure across layers of geopotential anomalies, which are required for calculating the finite-volume form pressure accelerations in a non-Boussinesq model. There are essentially no free assumptions, apart from the use of Boole’s rule to do the horizontal integrals, and from a truncation in the series for log(1-eps/1+eps) that assumes that |eps| < 0.34.

Parameters:

hi :: [in] The horizontal index structure
t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
p_t :: [in] Pressure at the top of the layer [R L2 T-2 ~> Pa]
p_b :: [in] Pressure at the bottom of the layer [R L2 T-2 ~> Pa]
alpha_ref :: [in] A mean specific volume that is subtracted out to reduce the magnitude of each of the integrals [R-1 ~> m3 kg-1] The calculation is mathematically identical with different values of alpha_ref, but this reduces the effects of roundoff.
eos :: [in] Equation of state structure
dza :: [inout] The change in the geopotential anomaly across
intp_dza :: [inout] The integral in pressure through the layer of the
intx_dza :: [inout] The integral in x of the difference between the
inty_dza :: [inout] The integral in y of the difference between the
halo_size :: [in] The width of halo points on which to calculate dza.
bathyp :: [in] The pressure at the bathymetry [R L2 T-2 ~> Pa]
dp_tiny :: [in] A miniscule pressure change with the same units as p_t [R L2 T-2 ~> Pa]
usemasswghtinterp :: [in] If true, uses mass weighting to interpolate T/S for top and bottom integrals.

Call to:

eos_linear eos_wright eos_wright_full eos_wright_reduced

subroutine mom_eos/analytic_int_density_dz(T, S, z_t, z_b, rho_ref, rho_0, G_e, HI, EOS, dpa, intz_dpa, intx_dpa, inty_dpa, bathyT, dz_neglect, useMassWghtInterp, Z_0p)¶

This subroutine calculates analytical and nearly-analytical integrals of pressure anomalies across layers, which are required for calculating the finite-volume form pressure accelerations in a Boussinesq model.

Parameters:

hi :: [in] Ocean horizontal index structure
t :: [in] Potential temperature referenced to the surface [C ~> degC]
s :: [in] Salinity [S ~> ppt]
z_t :: [in] Height at the top of the layer in depth units [Z ~> m]
z_b :: [in] Height at the bottom of the layer [Z ~> m]
rho_ref :: [in] A mean density [R ~> kg m-3], that is subtracted out to reduce the magnitude of each of the integrals.
rho_0 :: [in] A density [R ~> kg m-3], that is used to calculate the pressure (as p~=-z*rho_0*G_e) used in the equation of state.
g_e :: [in] The Earth’s gravitational acceleration [L2 Z-1 T-2 ~> m s-2]
eos :: [in] Equation of state structure
dpa :: [inout] The change in the pressure anomaly
intz_dpa :: [inout] The integral through the thickness of the
intx_dpa :: [inout] The integral in x of the difference between
inty_dpa :: [inout] The integral in y of the difference between
bathyt :: [in] The depth of the bathymetry [Z ~> m]
dz_neglect :: [in] A miniscule thickness change [Z ~> m]
usemasswghtinterp :: [in] If true, uses mass weighting to interpolate T/S for top and bottom integrals.
z_0p :: [in] The height at which the pressure is 0 [Z ~> m]

Call to:

eos_linear eos_wright eos_wright_full eos_wright_reduced

function mom_eos/query_compressible(EOS) [logical]¶

Returns true if the equation of state is compressible (i.e. has pressure dependence)

Parameters:: eos :: [in] Equation of state structure
Called from:: mom_pressureforce_mont::pressureforce_mont_bouss mom_pressureforce_mont::pressureforce_mont_nonbouss

function mom_eos/get_eos_name(id) [character(:)]¶

Returns the string identifying the equation of state with enumeration “id”.

Parameters:: id :: [in] Enumerated ID
Return:: undefined :: The name of the EOS
Call to:: eos_jackett06 eos_jackett06_string eos_linear eos_linear_string eos_roquet_rho eos_roquet_rho_string eos_roquet_spv eos_roquet_spv_string eos_teos10 eos_teos10_string eos_unesco eos_unesco_string eos_wright eos_wright_full eos_wright_full_string eos_wright_red_string eos_wright_reduced eos_wright_string

subroutine mom_eos/eos_init(param_file, EOS, US)¶

Initializes EOS_type by allocating and reading parameters. The scaling factors in US are stored in EOS for later use.

Parameters:

param_file :: [in] Parameter file structure
eos :: [inout] Equation of state structure
us :: [in] A dimensional unit scaling type

Call to:

eos_default eos_jackett06 eos_jackett06_string eos_jackett_string eos_linear eos_linear_string eos_manual_init eos_nemo_string eos_roquet_rho eos_roquet_rho_string eos_roquet_spv eos_roquet_spv_string eos_teos10 eos_teos10_string eos_unesco eos_unesco_string eos_wright eos_wright_full eos_wright_full_string eos_wright_red_string eos_wright_reduced eos_wright_string tfreeze_linear tfreeze_linear_string tfreeze_millero tfreeze_millero_string tfreeze_teos10 tfreeze_teos10_string tfreeze_teospoly tfreeze_teospoly_string

Called from:

mom_ice_shelf::initialize_ice_shelf mom::initialize_mom

subroutine mom_eos/eos_manual_init(EOS, form_of_EOS, form_of_TFreeze, EOS_quadrature, Compressible, Rho_T0_S0, drho_dT, dRho_dS, TFr_S0_P0, dTFr_dS, dTFr_dp, use_Wright_2nd_deriv_bug)¶

Manually initialized an EOS type (intended for unit testing of routines which need a specific EOS)

Parameters:

eos :: [inout] Equation of state structure
form_of_eos :: [in] A coded integer indicating the equation of state to use.
form_of_tfreeze :: [in] A coded integer indicating the expression for the potential temperature of the freezing point.
eos_quadrature :: [in] If true, always use the generic (quadrature) code for the integrals of density.
compressible :: [in] If true, in situ density is a function of pressure.
rho_t0_s0 :: [in] Density at T=0 degC and S=0 ppt [kg m-3]
drho_dt :: [in] Partial derivative of density with temperature in [kg m-3 degC-1]
drho_ds :: [in] Partial derivative of density with salinity in [kg m-3 ppt-1]
tfr_s0_p0 :: [in] The freezing potential temperature at S=0, P=0 [degC]
dtfr_ds :: [in] The derivative of freezing point with salinity in [degC ppt-1]
dtfr_dp :: [in] The derivative of freezing point with pressure in [degC Pa-1]
use_wright_2nd_deriv_bug :: [in] Allow the Wright 2nd deriv bug

Call to:

eos_jackett06 eos_linear eos_quadrature eos_roquet_rho eos_roquet_spv eos_teos10 eos_unesco eos_wright eos_wright_full eos_wright_reduced

Called from:

eos_init eos_unit_tests eos_use_linear test_eos_consistency

subroutine mom_eos/eos_use_linear(Rho_T0_S0, dRho_dT, dRho_dS, EOS, use_quadrature)¶

Set equation of state structure (EOS) to linear with given coefficients.

Parameters:

rho_t0_s0 :: [in] Density at T=0 degC and S=0 ppt [kg m-3]
drho_dt :: [in] Partial derivative of density with temperature [kg m-3 degC-1]
drho_ds :: [in] Partial derivative of density with salinity [kg m-3 ppt-1]
use_quadrature :: [in] If true, always use the generic (quadrature) code for the integrals of density.
eos :: [inout] Equation of state structure

Call to:

eos_linear eos_manual_init

subroutine mom_eos/convert_temp_salt_for_teos10(T, S, HI, kd, mask_z, EOS)¶

Convert T&S to Absolute Salinity and Conservative Temperature if using TEOS10.

Parameters:

kd :: [in] The number of layers to work on
hi :: [in] The horizontal index structure
t :: [inout] Potential temperature referenced to the surface [C ~> degC]
s :: [inout] Salinity [S ~> ppt]
mask_z :: [in] 3d mask regulating which points to convert [nondim]
eos :: [in] Equation of state structure

Call to:

eos_roquet_rho eos_roquet_spv eos_teos10

subroutine mom_eos/cons_temp_to_pot_temp(T, S, poTemp, EOS, dom, scale)¶

Converts an array of conservative temperatures to potential temperatures. The input arguments use the dimensionally rescaling as specified within the EOS type. The output potential temperature uses this same scaling, but this can be replaced by the factor given by scale.

Parameters:

t :: [in] Conservative temperature [C ~> degC]
s :: [in] Absolute salinity [S ~> ppt]
potemp :: [inout] The potential temperature with a reference pressure of 0 Pa, [C ~> degC]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale the output potential temperature in place of with scaling stored in EOS. A value of 1.0 returns temperatures in [degC], while the default is equivalent to EOSdegC_to_C.

Called from:

mom_diagnostics::calculate_diagnostic_fields mom_diagnostics::post_surface_thermo_diags test_ts_conversion_consistency

subroutine mom_eos/pot_temp_to_cons_temp(T, S, consTemp, EOS, dom, scale)¶

Converts an array of potential temperatures to conservative temperatures. The input arguments use the dimensionally rescaling as specified within the EOS type. The output potential temperature uses this same scaling, but this can be replaced by the factor given by scale.

Parameters:

t :: [in] Potential temperature [C ~> degC]
s :: [in] Absolute salinity [S ~> ppt]
constemp :: [inout] The conservative temperature [C ~> degC]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale the output potential temperature in place of with scaling stored in EOS. A value of 1.0 returns temperatures in [degC], while the default is equivalent to EOSdegC_to_C.

Called from:

test_ts_conversion_consistency

subroutine mom_eos/abs_saln_to_prac_saln(S, prSaln, EOS, dom, scale)¶

Converts an array of absolute salinity to practical salinity. The input arguments use the dimensionally rescaling as specified within the EOS type. The output potential temperature uses this same scaling, but this can be replaced by the factor given by scale.

Parameters:

s :: [in] Absolute salinity [S ~> ppt]
prsaln :: [inout] Practical salinity [S ~> PSU]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale the output practical salinities in place of with scaling stored in EOS. A value of 1.0 returns salinities in [PSU], while the default is equivalent to EOSppt_to_S.

Called from:

mom_diagnostics::calculate_diagnostic_fields mom_diagnostics::post_surface_thermo_diags test_ts_conversion_consistency

subroutine mom_eos/prac_saln_to_abs_saln(S, absSaln, EOS, dom, scale)¶

Converts an array of absolute salinity to practical salinity. The input arguments use the dimensionally rescaling as specified within the EOS type. The output potential temperature uses this same scaling, but this can be replaced by the factor given by scale.

Parameters:

s :: [in] Practical salinity [S ~> PSU]
abssaln :: [inout] Absolute salinity [S ~> ppt]
eos :: [in] Equation of state structure
dom :: [in] The domain of indices to work on, taking into account that arrays start at 1.
scale :: [in] A multiplicative factor by which to scale the output absolute salnities in place of with scaling stored in EOS. A value of 1.0 returns salinities in [ppt], while the default is equivalent to EOSppt_to_S.

Called from:

test_ts_conversion_consistency

function mom_eos/eos_quadrature(EOS) [logical]¶

Return value of EOS_quadrature.

Parameters:: eos :: [in] Equation of state structure
Called from:: eos_manual_init test_eos_consistency

function mom_eos/eos_unit_tests(verbose) [logical]¶

Runs unit tests for consistency on the equations of state. This should only be called from a single/root thread. It returns True if any test fails, otherwise it returns False.

Parameters:: verbose :: [in] If true, write results to stdout
Call to:: eos_jackett06 eos_linear eos_manual_init eos_roquet_rho eos_roquet_spv eos_teos10 eos_unesco eos_wright eos_wright_full eos_wright_reduced test_eos_consistency test_tfr_consistency test_ts_conversion_consistency tfreeze_linear tfreeze_millero tfreeze_teos10 tfreeze_teospoly
Called from:: mom_unit_tests::unit_tests

function mom_eos/test_ts_conversion_consistency(T_cons, S_abs, T_pot, S_prac, EOS, verbose) [logical]¶

Parameters:

t_cons :: [in] Conservative temperature [degC]
s_abs :: [in] Absolute salinity [g kg-1]
t_pot :: [in] Potential temperature [degC]
s_prac :: [in] Practical salinity [PSU]
eos :: [in] Equation of state structure
verbose :: [in] If true, write results to stdout

Call to:

abs_saln_to_prac_saln cons_temp_to_pot_temp pot_temp_to_cons_temp prac_saln_to_abs_saln write_check_msg

Called from:

eos_unit_tests

function mom_eos/test_tfr_consistency(S_test, p_test, EOS, verbose, EOS_name, TFr_check) [logical]¶

Parameters:

s_test :: [in] Salinity or absolute salinity [S ~> ppt]
p_test :: [in] Pressure [R L2 T-2 ~> Pa]
eos :: [in] Equation of state structure
verbose :: [in] If true, write results to stdout
eos_name :: [in] A name used in error messages to describe the EoS
tfr_check :: [in] A check value for the Freezing point [C ~> degC]

Call to:

write_check_msg

Called from:

eos_unit_tests

subroutine mom_eos/write_check_msg(var_name, val, val_chk, val_tol, test_OK)¶

Write a message indicating how well a value matches its check value.

Parameters:

var_name :: [in] The name of the variable being tested.
val :: [in] The value being checked [various]
val_chk :: [in] The value being checked [various]
val_tol :: [in] The value being checked [various]
test_ok :: [in] True if the values are within their tolerance

Called from:

test_eos_consistency test_tfr_consistency test_ts_conversion_consistency

function mom_eos/test_eos_consistency(T_test, S_test, p_test, EOS, verbose, EOS_name, rho_check, spv_check, skip_2nd, avg_Sv_check) [logical]¶

Test an equation of state for self-consistency and consistency with check values, returning false if it is consistent by all tests, and true if it fails any test.

Parameters:

t_test :: [in] Potential temperature or conservative temperature [C ~> degC]
s_test :: [in] Salinity or absolute salinity [S ~> ppt]
p_test :: [in] Pressure [R L2 T-2 ~> Pa]
eos :: [in] Equation of state structure
verbose :: [in] If true, write results to stdout
eos_name :: [in] A name used in error messages to describe the EoS
rho_check :: [in] A check value for the density [R ~> kg m-3]
spv_check :: [in] A check value for the specific volume [R-1 ~> m3 kg-1]
skip_2nd :: [in] If present and true, do not check the 2nd derivatives.
avg_sv_check :: [in] If present and true, compare analytical and numerical quadrature estimates of the layer-averaged specific volume.

Call to:

average_specific_vol check_fd derivs_2d eos_fit_range eos_manual_init eos_quadrature first_deriv second_deriv write_check_msg

Called from:

eos_unit_tests