xwmt.eos module

xwmt.eos module#

Equation-of-state handling for xwmt, delegated to the xeos package.

xwmt derives seawater density (and the thermal-expansion alpha / haline- contraction beta coefficients used to split density transformations into heat- and salt-driven components) from layer temperature and salinity. The actual equation-of-state (EOS) evaluation is delegated to xeos (hdrake/xeos), so any EOS that xeos supports can be selected — ideally the same EOS used by the ocean model that produced the data. See list_eos() (or xeos.list_eos()) for the available formulations.

Two helpers bridge xwmt’s data conventions and xeos:

  • resolve_eos() turns a user-facing eos specification (a canonical xeos id such as "teos10" or "wright97-full", an already-built xeos.EquationOfState, or None) into an xeos.EquationOfState (or None).

  • convert_ts() converts the dataset’s temperature/salinity — whose kinds the user declares via t_var/s_var — into the temperature/salinity kinds the chosen EOS expects, using gsw. This guards against the silent- corruption failure mode where, e.g., conservative temperature is fed to an EOS that expects potential temperature.

xwmt.eos.convert_ts(t, s, eos, t_var, s_var, p, lon=None, lat=None)#

Convert (t, s) into the temperature/salinity kinds that eos expects.

All conversions go through absolute salinity / conservative temperature (the “hubs” that gsw’s conversion routines are written around) and are applied lazily via xarray.apply_ufunc(), so xarray labels and dask laziness are preserved. When the input kinds already match what eos wants (e.g. the default conservative/absolute inputs for a TEOS-10 EOS), the inputs are returned unchanged with no conversion.

Parameters:

  • t (xr.DataArray) – Temperature and salinity whose kinds are declared by t_var/s_var.

  • s (xr.DataArray) – Temperature and salinity whose kinds are declared by t_var/s_var.

  • eos (xeos.EquationOfState) – Target EOS; its temperature/salinity properties give the required kinds.

  • t_var ({"conservative", "potential", "in-situ"}) – Kind of the input temperature t.

  • s_var ({"absolute", "practical"}) – Kind of the input salinity s.

  • p (xr.DataArray) – In-situ sea pressure [dbar], used by the salinity and in-situ-temperature conversions.

  • lon (xr.DataArray, optional) – Longitude/latitude, used for the practical<->absolute salinity conversion.

  • lat (xr.DataArray, optional) – Longitude/latitude, used for the practical<->absolute salinity conversion.

Returns:

(temp, salt) – Temperature and salinity in the kinds required by eos.

Return type:

tuple of xr.DataArray

xwmt.eos.list_eos()#

Return the sorted list of canonical EOS ids supported by xeos.

xwmt.eos.resolve_eos(eos)#

Resolve an eos specification to an xeos.EquationOfState.

Parameters:

eos (None, str, or xeos.EquationOfState) –

  • None: no EOS; the caller must supply alpha, beta and the requested density variable directly in the dataset.

  • str: a canonical xeos EOS id (see list_eos()), e.g. "teos10", "wright97-full", "jmd95".

  • xeos.EquationOfState: used as-is (e.g. one built with xeos.from_model(...) or a parameterised xeos.equation_of_state("linear", rho0=..., talpha=..., sbeta=...)).

Return type:

xeos.EquationOfState or None