romtools.workflows.inverse.run_eki#

romtools.workflows.inverse.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