pycif.plugins.transforms.system.fromcontrol — API reference

pycif.plugins.transforms.system.fromcontrol — API reference#

Configuration reference: fromcontrol plugin

pycif.plugins.transforms.system.fromcontrol.adjoint.adjoint(transform, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, **kwargs)[source]#

Accumulate model sensitivities into the control-vector gradient dx.

The adjoint of forward(): for each control tracer, takes the model sensitivity field adj_out (shape: time × level × lat × lon) from the output datastore and aggregates it back into the flattened control-vector gradient controlvect.dx.

The aggregation applies:

  1. Temporal aggregation — sensitivities are summed into the control-vector time periods via date-indexed lookup.

  2. Vertical aggregation — vmap2vaggreg() reduces the full 3-D sensitivity to the vertical resolution of the control vector (column, vpixels, or kbands).

  3. Horizontal projection — map2scale() maps the 2-D spatial sensitivity to the control-vector horizontal resolution (pixels, bands, regions, or global).

  4. Prior scaling — for scalar control variables the sensitivity is weighted by the prior physical input field value.

Non-control tracers and tracers absent from controlvect.datavect are silently skipped.

Parameters:

  • transform (Plugin) – fromcontrol transform instance.

  • inout_datastore (dict) – datastore; 'outputs' holds the model-space sensitivities (adj_out field).

  • controlvect – control vector plugin; dx is incremented in-place.

  • obsvect – observation vector plugin (unused).

  • mapper (dict) – transform mapper with output tracer metadata.

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

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

  • mode (str) – 'adj'.

  • runsubdir (str) – sub-simulation run directory.

  • workdir (str) – root working directory.

  • onlyinit (bool) – if True, return immediately (dry-run pass).

  • **kwargs – forwarded to tracer.read for prior scaling.

pycif.plugins.transforms.system.fromcontrol.forward.forward(transform, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, **kwargs)[source]#

Project the control vector onto physical model-input fields.

For each output tracer declared in the mapper:

  • Non-control tracers (iscontrol = False) — input files are read via tracer.read and stored verbatim.

  • Scalar control tracers (type = 'scalar', default) — the control-vector slice is unpacked to a map (scale2map()), re-indexed to the merged output date grid, and multiplied element-wise by the prior physical input field read from disk.

  • Physical control tracers (type = 'physical') — the control-vector slice is projected directly to physical space at the model domain resolution without reading any prior files.

In tangent-linear mode (mode = 'tl'), the same operations apply to controlvect.dx in parallel, producing an 'incr' field.

For ensemble runs (perturb_xb = True), delegates to forward_perturb() to handle all members in one I/O pass.

Parameters:

  • transform (Plugin) – fromcontrol transform instance.

  • inout_datastore (dict) – mutable datastore ('inputs', 'outputs').

  • controlvect – control vector plugin (x, dx).

  • obsvect – observation vector plugin (unused).

  • mapper (dict) – transform mapper with output tracer metadata.

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

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

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

  • runsubdir (str) – sub-simulation run directory.

  • workdir (str) – root working directory.

  • **kwargs – forwarded to tracer.read.

pycif.plugins.transforms.system.fromcontrol.forward_perturb.forward_perturb(transform, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, **kwargs)[source]#

Ensemble-optimised forward projection for perturbation (EnSRF / MC) runs.

Loads all ensemble members from a pre-saved control-vector file in a single I/O call (controlvect.load(..., ensemble=True)), then applies scale2map() to the entire ensemble at once. This avoids the per-member I/O overhead of calling the standard forward() function nsamples times.

Two memory strategies are supported (selected via the mapper flag loadin_perturb_full_vertical):

  • Full vertical (default) — all levels are loaded for every member. Produces inout_datastore["outputs"][trid][ddi]["spec"] for each sample tracer ID.

  • Reduced vertical — only the first member uses the full vertical extent; subsequent members use only the surface level (index surface_level, default 0). This reduces peak memory at the cost of approximate upper-level perturbations.

Note

Physical control variables (type = 'physical') are not yet supported and will raise NotImplementedError.

Parameters:

  • transform (Plugin) – fromcontrol transform instance with dir_samples and file_samples attributes set by perturb_transform().

  • inout_datastore (dict) – mutable datastore.

  • controlvect – control vector plugin (x_ens, dx_ens loaded in-place).

  • obsvect – observation vector plugin (unused).

  • mapper (dict) – transform mapper; 'outputs' contains one entry per sample tracer ID (__sample#N).

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

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

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

  • runsubdir (str) – sub-simulation run directory.

  • workdir (str) – root working directory.

  • **kwargs – forwarded to tracer.read.

pycif.plugins.transforms.system.fromcontrol.perturb_transform.perturb_transform(self, nsamples, dir_samples, file_samples, transf_mapper)[source]#

Prepare the fromcontrol transform for ensemble (perturbation) mode.

Registers the ensemble control-vector file path on the transform so that forward_perturb() can load all members at once, and extends the datavect to include one tracer copy per sample (__sample#N naming convention). The reference (non-sampled) tracers are then removed from the datavect to avoid duplicate processing.

Parameters:

  • self (Plugin) – fromcontrol transform instance; receives perturb_xb = True, nsamples, dir_samples, and file_samples as new attributes.

  • nsamples (int) – total number of ensemble members.

  • dir_samples (str) – directory containing the ensemble control-vector file.

  • file_samples (str) – file name of the ensemble control vector.

  • transf_mapper (dict) – the transform mapper; its 'outputs' dict is scanned for __sample#N tracer IDs to set up.