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

Configuration reference: toobsvect plugin

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

Read observation-vector sensitivities and populate the input datastore.

The adjoint of forward(): reads obsvect.dy (the observation-space adjoint increment, e.g. set by the simulator to \(\mathbf{R}^{-1}(\mathbf{H}\mathbf{x} - \mathbf{y})\)) and writes it into the 'adj_out' column of each tracer’s sparse datastore entry.

Also copies obsvect.ysim into 'spec' so that downstream adjoint transforms can access the reference forward simulation. Locations outside the active observation mask (obsvect.obsvect_mask) are zeroed out.

When split_freq is configured, only the observations in the current sub-window are processed and their dates are clipped to the window boundaries.

Parameters:

• transform (Plugin) – toobsvect transform instance.

• inout_datastore (dict) – datastore; 'inputs' entries are populated with sparse DataFrames carrying spec, incr, and adj_out columns.

• controlvect – control vector plugin (unused).

• obsvect – observation vector plugin; ysim and dy are read.

• mapper (dict) – transform mapper.

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

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

• mode (str) – 'adj'.

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

• workdir (str) – root working directory (unused).

• onlyinit (bool) – unused; kept for interface consistency.

• **kwargs – unused.

pycif.plugins.transforms.system.toobsvect.forward.forward(transform, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, **kwargs)

Store simulated concentrations from the datastore into the global observation vector.

For each observation tracer (isobs = True) found in the input datastore:

1. Reads the 'spec' (and 'incr' in TL mode) columns from the datastore entry datastore[tracer_id][ddi].

2. Accumulates them into the corresponding slice of obsvect.ysim (and obsvect.dy) via the tracer’s ypointer offset.

3. Zeros obsvect.dy at locations outside the active observation mask.

4. Writes the simulated and adjoint columns back into the tracer’s reference datastore for diagnostic access.

When split_freq is configured, only the observations falling within the current sub-window [ddi, split_ddf) are accumulated, weighted by their fractional overlap with the window.

Parameters:

• transform (Plugin) – toobsvect transform instance.

• inout_datastore (dict) – datastore with 'inputs' carrying sampled simulated fields.

• controlvect – control vector plugin (unused).

• obsvect – observation vector plugin; ysim and dy are updated in-place.

• mapper (dict) – transform mapper.

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

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

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

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

• workdir (str) – root working directory (unused).

• onlyinit (bool) – if True, return immediately.

• **kwargs – unused.

pycif.plugins.transforms.system.toobsvect.perturb_transform.perturb_transform(self, nsamples, dir_samples, file_samples, transf_mapper)

Extend the observation vector to accommodate all ensemble members.

For each __sample#N tracer found in the mapper inputs, creates a copy of the reference tracer with a shifted ypointer (offset by member_ID × obsvect.dim_ref) and a deep copy of the datastore with the parameter name updated to the sample-specific name.

The global obsvect.dim is extended to (nmembers + 1) × dim_ref, and the data arrays dy, ysim, yobs, yobs_err, and obsvect_mask are tiled accordingly.

Reference (non-sampled) tracers are removed from the datavect to prevent double-counting.

Parameters:

• self (Plugin) – toobsvect transform instance.

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

• dir_samples (str) – directory containing the ensemble files (unused here; kept for API consistency).

• file_samples (str) – ensemble control-vector file name (unused).

• transf_mapper (dict) – transform mapper; 'inputs' is scanned for __sample#N tracer IDs.