pycif.plugins.transforms.basic.unit_conversion — API reference

Configuration reference: unit_conversion plugin

pycif.plugins.transforms.basic.unit_conversion.adjoint.adjoint(transf, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, **kwargs)

Unit conversion utility for the unit_conversion transform.

This module computes a scalar scaling factor f such that

value_out = f * value_in

given a source unit string and a target unit string.

Supported unit families

Dimensional units via pint:

Any unit recognised by pint — kg, g, mol, s, m, Pa, etc., including compound units such as kg m-2 s-1 or nmol mol-1.

Atmospheric mixing-ratio shorthands:

ppm, ppb, ppt (and v-suffixed variants) are dimensionless mole-fraction ratios registered as custom pint units:

• 1 ppm = 1e-6 mol mol⁻¹

• 1 ppb = 1e-9 mol mol⁻¹

• 1 ppt = 1e-12 mol mol⁻¹

Species-qualified mass units (geochemistry conventions):

kgC, TgCO2, GtN, kgCH4, etc. encode the molecular or atomic weight of a specific species. pint does not know these; they are pre-processed here by splitting the SI prefix+base unit from the species qualifier (e.g. kgC → base kg, species C with M = 12.011 g mol⁻¹). When source and target qualifiers differ, the inter-species factor M_in / M_out is applied automatically.

Time unit aliases:

y and yr are mapped to year before pint sees the string, because y is the SI yocto prefix (1×10⁻²⁴) in standard pint.

Usage

from .convert import get_conversion_factor

get_conversion_factor("kg", "g")               # 1000.0
get_conversion_factor("ppb", "mol mol-1")       # 1e-9
get_conversion_factor("kgC m-2 yr-1",
                      "gC m-2 s-1")            # 1000 / 3.156e7
get_conversion_factor("kgCO2 m-2 s-1",
                      "kgC m-2 s-1")           # 12.011 / 44.009
get_conversion_factor("kg kg-1", "ppb",
                      mol_weight=16.043)        # 28.97/16.043 × 1e9

Dependencies

Requires pint (pip install pint).

pycif.plugins.transforms.basic.unit_conversion.convert.SPECIES_MOLAR_MASS: dict[str, float] = {'C': 12.011, 'CH4': 16.043, 'CO': 28.01, 'CO2': 44.009, 'H2O': 18.015, 'HCHO': 30.026, 'N': 14.007, 'N2O': 44.013, 'NH3': 17.031, 'NO': 30.006, 'NO2': 46.006, 'NOx': 46.006, 'O3': 48.0, 'S': 32.06, 'SO2': 64.06}

Known species qualifiers and their molecular weights (g mol⁻¹). Keys are matched case-sensitively at the END of a unit token.

pycif.plugins.transforms.basic.unit_conversion.convert.get_conversion_factor(unit_in: str, unit_out: str, mol_weight: float | None = None) → float

Compute the scalar factor f such that value_out = f * value_in.

The function handles four conversion paths, applied in order:

1. Identical units — returns 1.0 immediately.

2. Species qualifier mismatch — inter-species factor M_in / M_out is applied first, then the residual dimensional conversion is handled by pint. Example: kgCO2 m-2 s-1 → kgC m-2 s-1 gives 12.011 / 44.009.

3. Mass fraction ↔ mole fraction — the cross-family factor M_air / M_species (or its inverse) is applied together with any scale difference within each family. Requires mol_weight.

4. Pure dimensional conversion — delegated entirely to pint.

Parameters:

• unit_in (str) – Source unit string. Supports pint syntax plus mixing-ratio shorthands (ppm, ppb, ppt / v variants), species qualifiers (kgC, TgCO2, …), and time aliases (y / yr → year).

• unit_out (str) – Target unit string (same conventions).

• mol_weight (float, optional) – Species molar mass in g mol⁻¹. Required only for mass-fraction ↔ mole-fraction conversions when neither unit carries a species qualifier. When qualifiers are present their molar masses are used instead and this argument is ignored.

Returns:

Multiplicative scaling factor.

Return type:

float

Raises:

• ImportError – if pint is not installed.

• ValueError – if the conversion is dimensionally impossible, ambiguous, or requires a molar mass that was not provided.

Examples:

get_conversion_factor("kg", "g")
# → 1000.0

get_conversion_factor("ppb", "mol mol-1")
# → 1e-9

get_conversion_factor("kgC m-2 yr-1", "gC m-2 s-1")
# → 1000 / 3.156e7   (mass unchanged, time+prefix only)

get_conversion_factor("kgCO2 m-2 s-1", "kgC m-2 s-1")
# → 12.011 / 44.009  (inter-species, base units cancel)

get_conversion_factor("TgCO2 yr-1", "molCO2 s-1")
# → 1e9 / (44.009e-3) / 3.156e7

get_conversion_factor("kg kg-1", "ppb", mol_weight=16.043)
# → (28.97 / 16.043) * 1e9

pycif.plugins.transforms.basic.unit_conversion.forward.forward(transf, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, **kwargs)