pycif.plugins.obsoperators.onnx — API reference

pycif.plugins.obsoperators.onnx — API reference#

Configuration reference: onnx plugin

pycif.plugins.obsoperators.onnx.obsoper.obsoper(self, controlvect, obsvect, mode, run_id=0, datei=datetime.datetime(1979, 1, 1, 0, 0), datef=datetime.datetime(2100, 1, 1, 0, 0), workdir='./', reload_results=False, check_transforms=False, ignore_exceptions=False, force_fetch_results=False, **kwargs)[source]#

Apply the ONNX surrogate observation operator.

Forward (mode='fwd'):

\[\mathbf{y}_\text{sim} = \mathcal{N}(\mathbf{x})\]

Sets obsvect.ysim and returns obsvect.

Tangent-linear (mode='tl'):

\[\delta\mathbf{y} \approx \frac{\mathcal{N}(\mathbf{x}+\varepsilon\,\delta\mathbf{x}) - \mathcal{N}(\mathbf{x}-\varepsilon\,\delta\mathbf{x})} {2\varepsilon}\]

Requires 2 forward passes (central finite differences). Sets both obsvect.ysim and obsvect.dy; returns obsvect.

Adjoint (mode='adj'):

\[\delta\mathbf{x} \approx \mathbf{J}(\mathbf{x})^\top\,\delta\mathbf{y}\]

where \(\mathbf{J}\) is built column-by-column via central finite differences (\(2 n_\text{ctl}\) forward passes). The Jacobian is cached and reused for repeated adjoint calls at the same \(\mathbf{x}\).

Parameters:

  • self – Obs-operator plugin instance. Must have _ort_operator set by a prior call to ini_data.

  • controlvect – Control-vector object. controlvect.x is read in fwd / tl modes; controlvect.dx is read in tl mode and written in adj mode.

  • obsvect – Observation-vector object. obsvect.ysim is written in fwd / tl modes; obsvect.dy is read in adj mode and written in tl mode.

  • mode – One of 'fwd', 'tl', or 'adj'.

  • run_id – Run identifier (unused; present for interface compatibility).

  • datei – Simulation start date (unused).

  • datef – Simulation end date (unused).

  • workdir – Working directory (unused).

  • reload_results – Reload pre-computed results (unused).

  • check_transforms – Validate transform consistency (unused).

  • ignore_exceptions – Swallow non-fatal errors (unused).

  • force_fetch_results – If True, raise CifIOError immediately.

  • **kwargs – Additional keyword arguments (ignored).

Returns:

obsvect in 'fwd' and 'tl' modes; controlvect in 'adj'.

Raises:

CifIOError – if force_fetch_results is True.

Zero-dependency ONNX inference wrapper.

Loads a serialised model from an ONNX file and exposes a forward method that maps a 1-D state vector to a 1-D observation vector. The only required dependency is onnxruntime — no PyTorch, JAX, or other ML framework needed.

Example:

from pycif.plugins.obsoperators.onnx.onnx_operator import OnnxSurrogateOperator
op = OnnxSurrogateOperator("surrogate.onnx")
y  = op.forward(x)   # x: np.ndarray float64, y: np.ndarray float64
class pycif.plugins.obsoperators.onnx.onnx_operator.OnnxSurrogateOperator(onnx_path: str)[source]#

Bases: object

Drop-in replacement for a CIF obs operator backed by ONNX Runtime.

Parameters:

onnx_path – Path to the .onnx model file.

forward(x: ndarray) → ndarray[source]#

Run inference.

Parameters:

x – Input array of shape (N_state,) for a single sample or (batch, N_state) for a batch. A 1-D input is temporarily promoted to batch size 1 and squeezed back on output.

Returns:

float64 output array — shape (N_obs,) for a 1-D input, (batch, N_obs) for batched input.