Simulators simulator

Simulators simulator#

Simulator plugins: cost function evaluation for variational inversions.

Description#

A simulator plugin evaluates a scalar cost function \(J(\boldsymbol{\chi})\) and its gradient \(\nabla J(\boldsymbol{\chi})\) for a given iterate \(\boldsymbol{\chi}\) in the pre-conditioned chi-space. It is called at each iteration of the minimiser via:

J, grad_J = simulator.simul(chi, run_id=k)

The simulator orchestrates three sub-operations:

  1. Forward run — computes \(\mathcal{H}(\mathbf{x})\) via the obs-operator to obtain simulated observations.

  2. Cost evaluation — assembles the background and observation terms of \(J\).

  3. Adjoint run — propagates the observation-space increment \(\mathbf{R}^{-1}(\mathcal{H}(\mathbf{x}) - \mathbf{y})\) back through the adjoint obs-operator and applies the square-root-B mapping to produce \(\nabla J\).

Available simulators#

Plugin name / version

Description

gausscost / std

Bayesian Gaussian cost function (standard variational inversion)

gausscost / FLEXPART

Gaussian cost function variant for FLEXPART Lagrangian footprints

dummy_txt / std

Analytical quadratic bowl for algorithm testing (no obs-operator needed)

Required plugin interface#

Plugin identification#

_name (str):

plugin name, e.g. "gausscost".

_version (str):

version string, typically "std".

requirements#

Simulators require at minimum a controlvect sub-plugin, and usually also obsvect and obsoperator:

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

input_arguments (optional)#

Declare configurable YAML parameters following the standard pyCIF schema.

Functions#

simul (mandatory)#

The sole mandatory callable; invoked at each minimiser iteration:

def simul(self, chi, grad=True, run_id=-1, **kwargs):
    ...
self:

simulator plugin instance with all input_arguments applied and sub-plugins attached (self.controlvect, self.obsvect, self.obsoperator).

chi (np.ndarray):

current iterate \(\boldsymbol{\chi}\), shape (n,).

grad (bool):

if True (default), return both cost and gradient.

run_id (int):

unique identifier for this call; used as a sub-directory name for saving forward/adjoint outputs.

**kwargs:

forwarded to the obs-operator.

Returns (J, grad_J) when grad=True, or just J when grad=False.

ini_data (optional)#

Called after input_arguments are applied, before simul. Typically used to create output directories and back up any existing cost files:

def ini_data(plugin, **kwargs) -> None:
    ...

Available Simulators simulator#

The following simulators are implemented in pyCIF so far: