i7aof.convert¶

Purpose: Conversion utilities for TEOS-10 and workflows to generate CT/SA (Conservative Temperature/Absolute Salinity) and TF (Thermal Forcing) from CMIP thetao/so and from extrapolated climatologies.

Public Python API (by module)¶

Module: i7aof.convert.teos10
- compute_sa(): SA from SP + depth/pressure + lon/lat.
- compute_ct(): CT from pt + SA.
- compute_ct_sa(): Convenience to compute SA, then CT.
- compute_ct_freezing(): Conservative temperature at the freezing point given SA and depth or pressure (TEOS-10 GSW CT_freezing), used for TF.
- convert_dataset_to_ct_sa(): High-level helper to convert paired thetao/so datasets to a ct/sa dataset with coordinates preserved.
Module: i7aof.convert.paths
- get_ct_sa_output_paths(): Build output filenames for ct/sa derived from thetao/so lists in config; used by both conversion and remapping to ensure consistent naming.
Module: i7aof.convert.cmip_to_ct_sa
- convert_cmip_to_ct_sa(): Convert all thetao/so monthly pairs for a model/scenario to native-grid ct/sa files under convert/{model}/{scenario}/Omon/ct_sa.
Module: i7aof.convert.ct_sa_to_tf
- cmip_ct_sa_to_tf(): Compute monthly TF from bias-corrected ct/sa under biascorr/{model}/{scenario}/{clim}/Omon/ct_sa and write to .../Omon/tf.
- clim_ct_sa_to_tf(): Compute TF from extrapolated climatology ct/sa by writing *_tf_extrap[_z].nc alongside *_ct_extrap[_z].nc.

Required config options¶

[workdir] base_dir — required unless workdir arg is provided.
[inputdir] base_dir — required unless inputdir arg is provided.
[cmip_dataset]
- lon_var, lat_var: variable/dimension names on input
[convert_cmip] (optional overrides)
- depth_var: name of source depth coordinate (default ‘lev’).
- time_chunk: integer or None; conversion time chunk size.
Scenario sections, e.g. [historical_files], [ssp585_files] must define:
- thetao, so: expressions expanding to lists of relative input paths.

Outputs¶

Native-grid ct/sa monthly files under: convert/{model}/{scenario}/Omon/ct_sa
Filenames mirror thetao basenames with the variable token replaced by ct_sa. Existing outputs are skipped for resumability.

Usage¶

Python

from i7aof.convert.cmip import convert_cmip

convert_cmip(
  model='CESM2-WACCM',
  scenario='historical',
  user_config_filename='my-config.cfg',
)

CLI

ismip7-antarctic-convert-cmip-to-ct-sa \
  --model CESM2-WACCM \
  --scenario historical \
  --config my-config.cfg

ismip7-antarctic-cmip-ct-sa-to-tf \
  --model CESM2-WACCM \
  --scenario historical \
  --clim OI_Climatology \
  --config my-config.cfg

ismip7-antarctic-clim-ct-sa-to-tf \
  --clim OI_Climatology \
  --config my-config.cfg

Internals (for maintainers)¶

TEOS-10 now uses direct NumPy calls to GSW (gsw) for speed and simplicity, with explicit broadcasting:
- Pressure: p = gsw.p_from_z(z, lat) with shapes (Z,1,1) and (Y,X)
- Salinity: SA = gsw.SA_from_SP(SP, p, lon, lat)
- Temperature: CT = gsw.CT_from_pt(SA, PT) Inputs are eagerly .load()ed per time chunk to avoid large dask graphs.
Longitudes can be normalized to [0, 360).
Depth to TEOS-10 z conversion handled by _depth_to_z with CF-compliant attribute detection; meters and centimeters are supported.
Conversion runs in a manual time-chunk loop; each chunk is written to a unique temporary NetCDF file (adjacent to the final output), then combined via xarray.open_mfdataset and the temp directory is removed. A tqdm progress bar reports chunk progress.
Conversion keeps ct and sa together; types are cast to float32 for size.
TF uses TEOS-10 freezing CT with saturation_fraction=0.0; pressure is computed from ISMIP z and latitude.
Output path derivation centralized in i7aof.convert.paths.
Optional debugging: set environment variable I7AOF_DEBUG_TEOS10=1 to print timings and shapes around the heavy TEOS-10 computations.

Edge cases / validations¶

thetao and so list lengths must match; otherwise a ValueError is raised.
Inputs must align exactly in time and depth; strict alignment is enforced.
Depth units in meters or centimeters are supported (assumed meters if unit-less); other units raise a ValueError.