pycif.plugins.simulators.gausscost — API reference

Configuration reference: gausscost plugin

pycif.plugins.simulators.gausscost.dump.write_cost(self, run_id, j_b, j_o, zcost)

Append one cost-function record to cost.txt and cost.csv.

Parameters:

• self (Plugin) – simulator plugin instance (provides cost_file and cost_file_csv path attributes).

• run_id (int) – minimiser iteration identifier.

• j_b (float) – background cost term \(J_b\).

• j_o (float) – observation cost term \(J_o\).

• zcost (float) – total cost \(J = J_b + J_o\).

pycif.plugins.simulators.gausscost.dump.write_gradcost(self, run_id, znorm_grad_b, znorm_grad_o, znorm_grad)

Append one gradient-norm record to gradcost.txt and gradcost.csv.

Args:

self (Plugin): simulator plugin instance (provides gradcost_file

and gradcost_file_csv path attributes).

run_id (int): minimiser iteration identifier. znorm_grad_b (float): norm of the background gradient :math:`|

abla J_b|`.

znorm_grad_o (float): norm of the observation gradient :math:`|

abla J_o|`.

znorm_grad (float): norm of the total gradient :math:`|

abla J|`.

pycif.plugins.simulators.gausscost.dump.dump_cost(self, run_id: int, j_b: float, j_o: float, zgrad_b: float, zgrad_o: float) → None

Pickle the cost-function components and gradient vectors for restart.

Saves (j_b, j_o, zgrad_b, zgrad_o) to $workdir/simulator/cost_grad.NNNN.pickle so that a restarted inversion can skip recomputing the forward and adjoint runs.

Parameters:

• self (Plugin) – simulator plugin instance (provides simulator_dir).

• run_id (int) – minimiser iteration identifier; used to name the file.

• j_b (float) – background cost \(J_b\).

• j_o (float) – observation cost \(J_o\).

• zgrad_b (np.ndarray) – background gradient component.

• zgrad_o (np.ndarray) – observation gradient component.

pycif.plugins.simulators.gausscost.dump.load_cost(self, run_id: int) → tuple[float, float, float, float] | tuple[None, None, None, None]

Reload the cost-function components and gradient vectors from a pickle file.

Looks for cost_grad.NNNN.pickle (zero-padded) first, then falls back to the legacy non-padded name. Returns four None values when the file does not exist or cannot be read.

Parameters:

• self (Plugin) – simulator plugin instance (provides simulator_dir).

• run_id (int) – minimiser iteration identifier.

Returns:

(j_b, j_o, zgrad_b, zgrad_o) if the file exists and is readable; (None, None, None, None) otherwise.

Return type:

tuple

pycif.plugins.simulators.gausscost.simul.simul(self, chi, grad=True, run_id=-1, split_obs_vs_control=False, linear=False, **kwargs)

Evaluate the Bayesian Gaussian cost function and its gradient.

Computes

\[J(\boldsymbol{\chi}) = \underbrace{\tfrac{1}{2}\boldsymbol{\chi}^\top\boldsymbol{\chi}}_{J_b} + \underbrace{\tfrac{1}{2} (\mathcal{H}(\mathbf{x}) - \mathbf{y})^\top \mathbf{R}^{-1} (\mathcal{H}(\mathbf{x}) - \mathbf{y})}_{J_o}\]

and its gradient

\[\nabla J = \boldsymbol{\chi} + \mathbf{L}^\top \mathbf{H}^\top \mathbf{R}^{-1}(\mathcal{H}(\mathbf{x}) - \mathbf{y})\]

where \(\mathbf{x} = \mathbf{x}_b + \mathbf{L}\boldsymbol{\chi}\) and \(\mathbf{L} = \mathbf{B}^{1/2}\).

Both \(J\) and \(\nabla J\) are written to $workdir/simulator/ for monitoring and restart purposes.

Parameters:

• self (Plugin) – gausscost simulator plugin instance.

• chi (np.ndarray) – current iterate \(\boldsymbol{\chi}\), shape (n,).

• grad (bool) – if True (default), also compute and return the gradient.

• run_id (int) – unique call identifier used for sub-directory names and for reloading previously computed results.

• split_obs_vs_control (bool) – if True, return (j_b, j_o, zgrad_b, zgrad_o) instead of (zcost, zgrad).

• linear (bool) – if True, linearise around \(\mathbf{x}_b\) by calling the TL obs-operator instead of the full forward.

• **kwargs – forwarded to the obs-operator.

Returns:

• (zcost, zgrad) — default (grad=True, split_obs_vs_control=False).

• zcost — when grad=False.

• (j_b, j_o, zgrad_b, zgrad_o) — when split_obs_vs_control=True.

Return type:

tuple or float

Raises:

ValueError – if the obs-operator is not attached, if departures contain NaNs (and replace_NaNs is False), or if any cost/gradient value is non-finite.

pycif.plugins.simulators.gausscost.simul.get_departures(self, chi, controlvect, run_id, linear=False, reload_results=False, **kwargs)

Compute the observation-space departures \(\mathcal{H}(\mathbf{x}) - \mathbf{y}\).

Optionally reloads previously computed forward results from disk. When linear is True, calls the TL obs-operator and returns \(\mathbf{H}\,\delta\mathbf{x} + \mathbf{y}_\mathrm{sim,ref} - \mathbf{y}\).

Parameters:

• self (Plugin) – gausscost simulator plugin instance.

• chi (np.ndarray) – current iterate, shape (n,).

• controlvect – control vector plugin instance.

• run_id (int) – unique call identifier forwarded to the obs-operator.

• linear (bool) – if True, use the tangent-linear operator.

• reload_results (bool) – if True, attempt to reload a cached forward run before recomputing.

• **kwargs – forwarded to the obs-operator.

Returns:

departure vector \(\mathcal{H}(\mathbf{x}) - \mathbf{y}\), shape (m,).

Return type:

np.ndarray

pycif.plugins.simulators.gausscost.svd.svd_init(datastore)

Pre-compute the SVD of daily-averaged reference observations per parameter.

For each unique parameter in datastore, resamples observations to daily means, imputes missing values iteratively using the leading SVD components, and stores the resulting U, Vh, and singular values s.

Parameters:

datastore (pd.DataFrame) – observation datastore with at least the columns parameter, station, and obs, indexed by datetime.

Returns:

mapping {parameter: {"U": U, "Vh": Vh, "s": s}} where U and Vh are the left/right singular vectors and s the singular values from numpy.linalg.svd().

Return type:

dict

pycif.plugins.simulators.gausscost.svd.svd_cost(self, datastore, Jref)

Compute the SVD-based observation cost term and its adjoint increment.

Projects daily-averaged model-observation departures onto the pre-computed SVD basis from svd_init(). Errors are set proportional to \(s_k^{-1/4}\) (from gausscost) so that poorly constrained patterns are down-weighted. Writes the adjoint sensitivity back to datastore["obs_incr"] for use by the adjoint obs-operator.

Parameters:

• self (Plugin) – gausscost simulator plugin instance; must have self.svd_vectors populated by svd_init() and optionally self.crop_svd (int) to discard trailing SVD modes.

• datastore (pd.DataFrame) – observation datastore; the obs_incr column is updated in-place with the adjoint increment.

• Jref (float) – reference observation cost (unused; kept for interface consistency with the non-SVD code path).

Returns:

SVD-based observation cost \(J_o\).

Return type:

float