Modes mode

Modes mode#

Mode plugins: top-level computation drivers for pyCIF.

Description#

The mode plugin is the highest-level class in pyCIF. When pyCIF starts, it reads the YAML configuration, instantiates all required plugins (model, obsoperator, controlvect, obsvect, …), and then calls the execute function of the selected mode. Everything else — the number of forward runs, whether an adjoint is required, how results are saved — is controlled by the mode.

Because the mode sits at the top of the call hierarchy, it is never called by any other pyCIF plugin: it is the initiator. This also means mode plugins have the most freedom in how they orchestrate sub-plugins.

Modes in pyCIF represent a range of computation workflows:

  • A single forward simulation or sensitivity run.

  • A full variational Bayesian inversion (4D-Var).

  • A direct analytical inversion via explicit H-matrix construction.

  • Ensemble-based filtering (EnSRF).

  • Adjoint/tangent-linear correctness tests.

  • Post-processing of saved inversion results.

Available modes#

Plugin name / version

Description

forward / std

Forward or tangent-linear run

adj-tl_test / std

Adjoint and TL correctness test suite

4dvar / std

Variational (4D-Var) inversion

analytic / std

Direct BLUE inversion via H-matrix

response-functions / std

H-matrix column-by-column construction

footprint / std

Adjoint backward sensitivity / footprint run

EnSRF / std

Ensemble Square Root Filter

co2mvs / std

CO2MVS outer-loop driver (ECMWF/LMDZ-IFS)

post-proc / std

Post-processing of saved inversion outputs

See each mode’s own __init__.py for its full mathematical framework and parameter documentation.

Required plugin interface#

Every mode plugin is a Python package whose __init__.py must expose at minimum an execute function and the three plugin identification variables. The optional ini_data function is called during initialisation when present.

Plugin identification#

Every mode plugin module must define the following module-level variables:

_name (str):

short name used to select this mode in the YAML (mode.plugin.name).

_version (str):

version string (mode.plugin.version), typically "std".

_fullname (str):

human-readable name shown in log output.

Example:

_name = "forward"
_version = "std"
_fullname = "Forward run"

requirements (optional)#

A dict mapping plugin-class names to dependency specifications. Each entry tells pyCIF which other plugin classes must be instantiated before execute is called. If a required plugin is absent from the YAML, pyCIF raises an error at startup:

requirements = {
    "controlvect": {
        "name": "standard", "version": "std",
        "empty": True, "any": True
    },
    "obsoperator": {
        "name": "standard", "version": "std", "empty": True
    },
}

The "any": True flag means the user may substitute any compatible plugin; "empty": True means the plugin is not required to carry data at startup.

input_arguments (optional)#

A dict that declares configurable YAML parameters for the mode. Each entry follows the standard pyCIF argument schema:

input_arguments = {
    "param_name": {
        "doc":      "One-line description shown in the documentation.",
        "default":  <default_value>,   # omit for mandatory parameters
        "optional": True,              # include only if parameter is optional
        "accepted": <type_or_values>,  # Python type, list, or dict of choices
    },
    ...
}

All parameters declared here are automatically applied to the plugin instance as attributes before ini_data and execute are called.

Functions#

execute (mandatory)#

The execute function is the sole mandatory callable. It is invoked once by the pyCIF entry point after all plugins have been initialised.

Signature:

def execute(self, **kwargs):
    ...
self:

the mode plugin instance. By the time execute is called, self carries:

  • All YAML parameters as attributes (from input_arguments).

  • Simulation window: self.datei, self.datef.

  • Working directory: self.workdir.

  • All required sub-plugins (e.g. self.controlvect, self.obsoperator, self.obsvect).

**kwargs:

extra keyword arguments forwarded by the pyCIF entry point; typically not used but must be accepted for interface compatibility.

The return value is optional but recommended so that the pyCIF entry point can log or dump final outputs:

  • forward mode — obsvect populated with simulated values.

  • variational / analytic mode — (controlvect, obsvect).

  • adjoint test — test ratio in multiples of machine epsilon.

  • footprint mode — controlvect populated with adjoint sensitivities.

  • post-proc — nothing (outputs written to disk inside execute).

ini_data (optional)#

Called immediately after the plugin is instantiated and its input_arguments are applied from the YAML, before execute. Use it to validate argument combinations, derive computed attributes, or create output directories:

def ini_data(plugin, **kwargs):
    ...
plugin:

the partially initialised mode plugin instance.

**kwargs:

unused; accepted for interface consistency.

Typical uses in existing modes:

  • variational — checks that a minimizer has a simulator attached.

  • analytic — creates the base_functions/ and H_matrix/ output directories.

  • response-functions — validates mutually exclusive argument pairs and pre-processes the ignore_tracers list.

Template#

The forward mode is the simplest reference implementation. Its execute function illustrates the canonical pattern: retrieve sub-plugins from self, call the obs-operator, and return the result.

pycif.plugins.modes.forward.execute(self, **kwargs)[source]

Run the observation operator in forward (or tangent-linear) mode.

Initialises the control vector from its background state when use_xb is set, validates that both x and at least one observation are defined, then calls the obs-operator. Optionally perturbs the resulting simulated observations with Gaussian noise (controlled by perturb_obsvect and obserror) and dumps the resulting observation vector.

Parameters:

  • self (Plugin) – mode plugin carrying all configuration attributes (workdir, datei, datef, run_mode, use_xb, perturb_obsvect, obserror, reload_results).

  • **kwargs – forwarded verbatim to the observation operator.

Returns:

the observation vector populated with simulated values.

Return type:

ObsVect

Available Modes mode#

The following modes are implemented in pyCIF so far: