pycif.plugins.transforms.complex.isotopes — API reference

pycif.plugins.transforms.complex.isotopes — API reference#

Configuration reference: isotopes plugin

pycif.plugins.transforms.complex.isotopes.adjoint.adjoint(transf, data, mapper, di, df, mode, runsubdir, workdir, **kwargs)[source]#

Propagate two-isotopologue sensitivities back to δ and total-concentration sensitivities.

The adjoint of forward(). Uses forward data stored in transf.fwd_data to compute:

  • Sensitivity to total concentration: \(\partial J/\partial C_{tot} = (a \cdot s_{iso_2} + s_{iso_1}) / (1+a)\)

  • Sensitivity to δ-signature: \(\partial J/\partial\delta = R_{std} \cdot C_{tot} \cdot (s_{iso_2} - s_{iso_1}) / (1000 \cdot (1+a)^2)\)

Returns immediately when mode != 'adj'.

Parameters:

  • transf (Plugin) – isotopes plugin instance (carries fwd_data).

  • data – datastore object.

  • mapper (dict) – transform mapper.

  • di (datetime) – sub-simulation start date.

  • df (datetime) – sub-simulation end date.

  • mode (str) – must be 'adj'; returns unchanged data otherwise.

  • runsubdir (str) – unused.

  • workdir (str) – unused.

  • **kwargs – unused.

Returns:

updated datastore object.

Return type:

data

pycif.plugins.transforms.complex.isotopes.forward.forward(transf, data, mapper, ddi, ddf, mode, runsubdir, workdir, **kwargs)[source]#

Compute two-isotopologue concentrations from a δ-value and total concentration.

Given one isotopic signature δ and total concentration \(C_{tot}\):

\[ \begin{align}\begin{aligned}a = (1 + \delta/1000) \cdot R_{std}\\[iso_1] = C_{tot} / (1 + a), \quad [iso_2] = C_{tot} \cdot a / (1 + a)\end{aligned}\end{align} \]

Saves signature and spec_data on transf.fwd_data for use by the adjoint. Applies an optional mass correction (unit = 'mass').

Parameters:

  • transf (Plugin) – isotopes plugin instance (carries parameters_in with standard, parameters_out with iso_mass / spec_mass, unit, and component).

  • data – datastore object carrying .datastore dict.

  • mapper (dict) – transform mapper.

  • ddi (datetime) – sub-simulation start date.

  • ddf (datetime) – sub-simulation end date.

  • mode (str) – 'fwd' or 'tl'.

  • runsubdir (str) – unused.

  • workdir (str) – unused.

  • **kwargs – unused.

Returns:

updated datastore object.

Return type:

data

pycif.plugins.transforms.complex.isotopes.native2obsvect.native2obsvect(transf, y0, mapper, mod_input, ddi, ddf, mode, runsubdir, workdir, **kwargs)[source]#

Convert model isotopologue outputs to observation-vector δ-values and totals.

Only acts when mod_input == 'obs'. From the two simulated isotopologue columns, computes the δ-value and the total (or mass-corrected) concentration:

  • δ-value = \(([iso_2] / [iso_1] / R_{std} - 1) \times 1000\)

  • total = \([iso_1] + [iso_2]\) (volume) or mass-corrected equivalent (unit = 'mass')

In TL mode the tangent-linear of both quantities is computed.

Forward data (isotopologue and reference concentrations) are saved on transf.fwd_data[ddi] for use by the adjoint in obsvect2native.

Parameters:

  • transf (Plugin) – isotopes plugin instance (carries parameters_in, parameters_out, unit, fwd_data).

  • y0 (pd.DataFrame) – obs-vector DataFrame with 'sim' and 'sim_tl' columns; modified in-place.

  • mapper (dict) – transform mapper.

  • mod_input (str) – component type; the function returns y0 unchanged unless mod_input == 'obs'.

  • ddi (datetime) – sub-simulation start date.

  • ddf (datetime) – sub-simulation end date.

  • mode (str) – 'fwd' or 'tl'.

  • runsubdir (str) – unused.

  • workdir (str) – unused.

  • **kwargs – unused.

Returns:

updated obs-vector DataFrame.

Return type:

pd.DataFrame

pycif.plugins.transforms.complex.isotopes.obsvect2native.obsvect2native(transf, y0, mapper, mod_input, ddi, ddf, mode, runsubdir, workdir, **kwargs)[source]#

Split obs-vector observations into two isotopologue sub-species.

Expands each matched observation into two rows — one per output isotopologue — by duplicating the original DataFrame and assigning the appropriate output parameter names.

In adjoint mode, propagates obs_incr from the (δ, total) space back to the individual isotopologue increments using the forward concentrations saved in transf.fwd_data[ddi]:

  • Reference increment (denominator): \(\partial J / \partial [ref] = -[iso]/[ref]^2 \cdot incr \cdot 1000 / R_{std}\)

  • Isotopologue increment (numerator): \(\partial J / \partial [iso] = 1/[ref] \cdot incr \cdot 1000 / R_{std}\)

Parameters:

  • transf (Plugin) – isotopes plugin instance (carries parameters_in, parameters_out, fwd_data).

  • y0 (pd.DataFrame) – obs-vector DataFrame; extended and reordered in-place.

  • mapper (dict) – transform mapper.

  • mod_input (str) – component type (e.g. 'obs').

  • ddi (datetime) – sub-simulation start date.

  • ddf (datetime) – sub-simulation end date.

  • mode (str) – 'fwd', 'tl', or 'adj'.

  • runsubdir (str) – unused.

  • workdir (str) – unused.

  • **kwargs – unused.

Returns:

updated obs-vector DataFrame sorted by indorig and parameter.

Return type:

pd.DataFrame