ONNX surrogate observation operator onnx/std

ONNX surrogate observation operator `onnx/std`#

Description#

ONNX surrogate observation operator.

Loads a pre-trained surrogate model from an ONNX file and exposes the standard CIF observation-operator interface (forward / tangent-linear / adjoint).

The ONNX model is expected to map a state vector \(\mathbf{x} \in \mathbb{R}^{n_\text{ctl}}\) to an observation vector \(\mathbf{y} \in \mathbb{R}^{n_\text{obs}}\). It is typically produced by the training mode plugin via torch.onnx.export.

The three operational modes are:

Forward (fwd): \(\mathbf{y}_\text{sim} = \mathcal{N}(\mathbf{x})\) where \(\mathcal{N}\) is the neural-network surrogate.
Tangent-linear (tl): \(\delta\mathbf{y} \approx \mathbf{J}(\mathbf{x})\,\delta\mathbf{x}\) approximated by a central finite-difference Jacobian-vector product (2 forward passes).
Adjoint (adj): \(\delta\mathbf{x} \approx \mathbf{J}(\mathbf{x})^\top\,\delta\mathbf{y}\) using the full finite-difference Jacobian (\(2 \times n_\text{ctl}\) forward passes, cached across calls at the same \(\mathbf{x}\)).

Configuration#

obsoperator:
  name: onnx
  version: std
  onnx_file: path/to/surrogate.onnx   # relative to workdir, or absolute
  fd_epsilon: 1.0e-5                  # optional; finite-difference step

YAML arguments#

The following arguments are used to configure the plugin. pyCIF will return an exception at the initialization if mandatory arguments are not specified, or if any argument does not fit accepted values or type:

Optional arguments#

onnx_file : str, optional, default “surrogate.onnx”: Path to the ONNX model file. Relative paths are resolved against workdir.

fd_epsilon : float, optional, default 1e-05: Finite-difference step size used for tangent-linear and adjoint modes. Defaults to 1e-5, which is appropriate for float32 models.

Requirements#

The current plugin requires the present plugins to run properly:

Requirement name	Requirement type	Explicit definition	Any valid	Default name	Default version
obsvect	ObsVect	True	True	standard	std
controlvect	ControlVect	True	True	standard	std
datavect	DataVect	True	True	standard	std
platform	Platform	True	True	None	None

YAML template#

Please find below a template for a YAML configuration:

obsoperator:
  plugin:
    name: onnx
    version: std
    type: obsoperator

  # Optional arguments
  onnx_file: XXXXX  # str
  fd_epsilon: XXXXX  # float