i7aof.convert

Conversion utilities and workflows for TEOS-10 operations and CMIP CT/SA generation. The TEOS-10 steps use NumPy arrays with GSW directly for performance. See i7aof.convert for developer details and CMIP Inputs for usage and performance tips (e.g., time chunking).

TEOS-10 conversion utilities to compute Absolute Salinity (SA) and Conservative Temperature (CT) from Practical Salinity (SP) and potential temperature (PT), with xarray/dask support.

This module is I/O-free and operates on xarray DataArray/Dataset, keeping variable and dimension names flexible.

i7aof.convert.teos10.compute_ct(pt: DataArray, sa: DataArray) → DataArray

Compute Conservative Temperature (CT).

Parameters:

  • pt (xr.DataArray) – Potential temperature (degC), aligned with sa.

  • sa (xr.DataArray) – Absolute Salinity (g kg-1), aligned with pt.

Returns:

Conservative Temperature (degC) broadcast to the common grid and with attributes units and long_name set.

Return type:

xr.DataArray

i7aof.convert.teos10.compute_ct_sa(sp: DataArray, pt: DataArray, z_or_p: DataArray, lon: DataArray, lat: DataArray, is_pressure: bool = False, normalize_lon: bool = True) → Tuple[DataArray, DataArray]

Compute SA and CT together.

Parameters:

  • sp (xr.DataArray) – Practical Salinity (PSS-78, unitless).

  • pt (xr.DataArray) – Potential temperature (degC), aligned or broadcastable to sp.

  • z_or_p (xr.DataArray) – Depth (m, positive down), TEOS-10 z (m, negative down), or pressure (dbar) if is_pressure=True.

  • lon (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • lat (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • is_pressure (bool, optional) – If True, interpret z_or_p as pressure (dbar). Otherwise, compute pressure from depth and latitude.

  • normalize_lon (bool, optional) – Normalize longitudes to [0, 360).

Returns:

Tuple of (sa, ct), where sa is Absolute Salinity (g kg-1) and ct is Conservative Temperature (degC), both broadcast to the common grid and with standard attributes set.

Return type:

(xr.DataArray, xr.DataArray)

i7aof.convert.teos10.compute_sa(sp: DataArray, z_or_p: DataArray, lon: DataArray, lat: DataArray, is_pressure: bool = False, normalize_lon: bool = True) → DataArray

Compute Absolute Salinity (SA) from Practical Salinity (SP).

Parameters:

  • sp (xr.DataArray) – Practical Salinity (PSS-78, unitless).

  • z_or_p (xr.DataArray) – Depth (m, positive down) or TEOS-10 z (m, negative down) or pressure (dbar) if is_pressure=True. Will be broadcast to SP.

  • lon (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • lat (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • is_pressure (bool) – If True, interpret z_or_p as pressure (dbar). Otherwise, compute pressure from depth and latitude.

  • normalize_lon (bool) – Normalize longitudes to [0, 360).

Returns:

Absolute Salinity (g kg-1) with the same grid as sp and attributes units and long_name set.

Return type:

xr.DataArray

i7aof.convert.teos10.convert_dataset_to_ct_sa(ds_thetao: Dataset | DataArray, ds_so: Dataset | DataArray, thetao_var: str = 'thetao', so_var: str = 'so', lat_var: str = 'lat', lon_var: str = 'lon', depth_var: str = 'lev', depth_positive: str | None = None) → Dataset

Convert a thetao/so pair to a dataset with ct and sa.

Parameters:

  • ds_thetao (xr.Dataset or xr.DataArray) – Dataset containing potential temperature variable thetao_var (or a DataArray of potential temperature).

  • ds_so (xr.Dataset or xr.DataArray) – Dataset containing Practical Salinity variable so_var (or a DataArray of Practical Salinity).

  • thetao_var (str, optional) – Name of the potential temperature variable in ds_thetao.

  • so_var (str, optional) – Name of the Practical Salinity variable in ds_so.

  • lat_var (str, optional) – Names of the latitude and longitude coordinate variables.

  • lon_var (str, optional) – Names of the latitude and longitude coordinate variables.

  • depth_var (str, optional) – Name of the depth coordinate (commonly ‘lev’).

  • depth_positive ({"down", "up", None}, optional) – Explicit direction of depth_var. If None, inferred from CF attributes when available.

Returns:

Dataset with variables: - ct (degC): Conservative Temperature - sa (g kg-1): Absolute Salinity Common coordinates (time, depth_var, lat_var, lon_var) are attached when present in inputs. Basic provenance comments are set.

Return type:

xr.Dataset

i7aof.convert.paths.get_ct_sa_output_paths(config, model: str, scenario: str, workdir: str) → List[str]

Derive absolute output paths for converted ct_sa files based on the thetao and so file lists in the config. Filenames are formed by replacing the variable token (thetao/so) in the thetao basename with ‘ct_sa’ and writing into:

{workdir}/convert/{model}/{scenario}/Omon/ct_sa/

Returns a list of absolute output filenames, one per input pair, in the same order as the thetao list.

Parameters:

  • config (mpas_tools.config.MpasConfigParser) – Configuration object containing file lists under [{scenario}_files] for thetao and so.

  • model (str) – Name of the CMIP model (used to build the output directory path).

  • scenario (str) – Scenario key (e.g., historical, ssp585) used to select file lists from the config.

  • workdir (str) – Base working directory where converted files are written under convert/{model}/{scenario}/Omon/ct_sa.

Returns:

Absolute paths to ct_sa output files, one per thetao/so pair, in the same order as the thetao list.

Return type:

List[str]

i7aof.convert.cmip.convert_cmip(model: str, scenario: str, inputdir: str | None = None, workdir: str | None = None, user_config_filename: str | None = None) → None

Convert thetao/so monthly files to ct/sa for a CMIP model.

Conversion is performed per thetao/so pair. Outputs store only ct & sa plus coordinate variables; bounds variables for depth/lat/lon are injected only in the final merged file to avoid acquiring a spurious time dimension.

Parameters:

  • model (str) – Name of the CMIP model (used to select the model config and to construct output paths).

  • scenario (str) – Scenario key (e.g., ‘historical’, ‘ssp585’) used to pick input file lists from the config.

  • inputdir (str, optional) – Base directory where the relative input file paths are resolved. If not provided, uses [inputdir] base_dir from the config.

  • workdir (str, optional) – Base working directory where outputs will be written. If not provided, uses [workdir] base_dir from the config.

  • user_config_filename (str, optional) – Optional user config that overrides defaults (paths, variable names, chunk sizes, etc.).

i7aof.convert.cmip.main() → None