romtools.workflows.inverse.eki_drivers#

Single-fidelity ensemble Kalman inversion drivers.

This module provides a derivative-free ensemble Kalman inversion (EKI) workflow for black-box forward models. The algorithm evolves an ensemble of parameter realizations so that the corresponding model outputs become consistent with observed quantities of interest.

Theory

run_eki solves a deterministic inverse problem by repeatedly updating an ensemble \(\{\theta^{(j)}\}_{j=1}^{J}\). At each iteration the forward model is evaluated on every ensemble member, producing QoIs \(g(\theta^{(j)})\). The ensemble mean prediction is compared with the observations \(y\), and the parameter ensemble is corrected with a Kalman-style affine update.

With parameter anomalies

\[S_{\theta} = \frac{1}{\sqrt{J-1}} \left[ \theta^{(1)} - \bar{\theta}, \ldots, \theta^{(J)} - \bar{\theta} \right],\]

and QoI anomalies

\[S_y = \frac{1}{\sqrt{J-1}} \left[ g(\theta^{(1)}) - \bar{g}, \ldots, g(\theta^{(J)}) - \bar{g} \right],\]

the implementation forms the update directions by solving

\[\Delta \Theta = S_{\theta} S_y^{\top} \left( S_y S_y^{\top} + \Gamma_y + \lambda I \right)^{-1} \left[ y - g(\theta^{(1)}), \ldots, y - g(\theta^{(J)}) \right],\]

where \(\Gamma_y\) is the observation covariance and \(\lambda\) is the Tikhonov regularization parameter. Each ensemble member is then updated by adding a scaled column of \(\Delta \Theta\).

Step Acceptance

The routine uses a simple trust-region-like acceptance rule on top of the EKI update. A trial step is accepted only if the mean observation-space error norm decreases by at least the factor set by relaxation_parameter. Accepted steps grow the step size by step_size_growth_factor; rejected steps shrink it by step_size_decay_factor until either a step is accepted or the maximum number of retries is reached.

Practical Notes

  • The forward model is treated as derivative-free; only QoI evaluations are required.

  • Parameter bounds are enforced by clipping sampled and updated parameters to parameter_mins and parameter_maxes when provided.

  • Restart files store the ensemble, QoIs, mean QoI, and current step size so long runs can be resumed from an iteration directory.

Relation to run_mf_eki

run_eki is the single-fidelity baseline. The multifidelity driver romtools.workflows.inverse.mf_eki_drivers.run_mf_eki() augments this workflow with ROM control variates and adaptive surrogate rebuilding, but the high-fidelity correction and step-acceptance logic remain closely related.

Functions

compute_eki_update(parameter_samples, qois, ...)

compute_eki_update2(parameter_samples, qois, ...)

run_eki(model, parameter_space, ...[, ...])

Run a single-fidelity ensemble Kalman inversion (EKI) workflow.
romtools.workflows.inverse.eki_drivers.run_eki(model, parameter_space, observations, observations_covariance, parameter_mins=None, parameter_maxes=None, absolute_eki_directory='/home/runner/work/rom-tools-and-workflows/rom-tools-and-workflows/work/', ensemble_size=30, initial_step_size=0.1, regularization_parameter=0.0001, step_size_growth_factor=1.25, step_size_decay_factor=2.0, max_step_size_decrease_trys=5, relaxation_parameter=1.05, error_norm_tolerance=1e-05, delta_params_tolerance=1e-06, max_iterations=50, random_seed=1, evaluation_concurrency=1, restart_file=None)[source]#

Run a single-fidelity ensemble Kalman inversion (EKI) workflow.

The routine draws or restores a parameter ensemble, evaluates the forward model for every ensemble member, forms the ensemble Kalman correction, and accepts or rejects trial updates based on the reduction in mean QoI error. The workflow is fully derivative-free with respect to model.

Parameters:

  • model (QoiModel) – QoiModel to evaluate at ensemble samples.

  • parameter_space (ParameterSpace) – ParameterSpace used to draw the initial ensemble when restart_file is not provided.

  • observations (ndarray) – Observed QoI vector \(y\).

  • observations_covariance (ndarray) – Observation covariance matrix \(\Gamma_y\) used in the Kalman solve.

  • parameter_mins (ndarray) – Optional lower bounds applied to sampled and updated parameters.

  • parameter_maxes (ndarray) – Optional upper bounds applied to sampled and updated parameters.

  • absolute_eki_directory (str) – Absolute path to the working directory. Each accepted or tested iteration writes into iteration_<k>/run_* subdirectories under this path.

  • ensemble_size (int) – Number of ensemble members used in the EKI update.

  • initial_step_size (float) – Initial multiplier applied to the computed Kalman update directions.

  • regularization_parameter (float) – Tikhonov regularization added to the QoI covariance solve for numerical stability.

  • step_size_growth_factor (float) – Factor used to increase the step size after an accepted iteration.

  • step_size_decay_factor (float) – Factor used to decrease the step size after a rejected trial iteration.

  • max_step_size_decrease_trys (int) – Maximum number of consecutive rejected trial steps before the routine exits.

  • relaxation_parameter (float) – Acceptance threshold on the mean error norm. A trial step is accepted when the new norm is below relaxation_parameter * current_error_norm.

  • error_norm_tolerance (float) – Stop when the mean observation-space error norm falls below this value.

  • delta_params_tolerance (float) – Stop when the norm of the proposed ensemble update falls below this value.

  • max_iterations (int) – Maximum number of EKI iterations.

  • random_seed (int) – RNG seed used for the initial ensemble draw.

  • evaluation_concurrency – Number of concurrent model evaluations used by each EKI iteration.

  • restart_file – Optional .npz restart file produced by a prior EKI run. When set, the saved ensemble, QoIs, error state, and step size are restored instead of drawing a new ensemble.

Returns:

Tuple (parameter_samples, qois) containing the final ensemble and the corresponding QoI matrix from the last accepted iteration.

On this page

This Page