Ensemble Kalman Inversion (EKI)#

The EKI workflows provide single- and multi-fidelity ensemble Kalman inversion utilities for parameter inference problems. Both workflows are derivative-free with respect to the forward model, support concurrent sample evaluation, and write restart files that can be used to resume long-running solves.

Single-fidelity EKI updates a parameter ensemble with Kalman-style covariance estimates formed from forward-model QoIs. Multi-fidelity EKI preserves the same high-fidelity inverse target while augmenting the update with a surrogate-based control-variate correction built from shared FOM/ROM samples and additional ROM-only samples.

For more detailed algorithmic background, see the function-level API documentation for the single- and multi-fidelity drivers below.

Single-fidelity EKI#

romtools.workflows.inverse.eki_drivers.run_eki(model, parameter_space, observations, observations_covariance, parameter_mins=None, parameter_maxes=None, absolute_work_dir=None, ensemble_size=30, initial_step_size=0.05, 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=0.001, rejuvenation_strategy='none', rejuvenation_interval=5, rejuvenation_inflation=1.1, rejuvenation_prior_weight=0.0025, max_rejuvenations=3, rejuvenation_cooldown=10, max_iterations=50, random_seed=1, evaluation_concurrency=1, restart_file=None, dispatcher=None, *, bounded_parameter_handling='clip', transform_interior_margin=0.0, transform_map='sigmoid', absolute_eki_directory=None)[source]

Run EKI with historical clipping or an unconstrained bound transform.

Parameters:

  • model (QoiModel)

  • parameter_space (ParameterSpace)

  • observations (ndarray)

  • observations_covariance (ndarray)

  • parameter_mins (ndarray)

  • parameter_maxes (ndarray)

  • absolute_work_dir (str)

  • ensemble_size (int)

  • initial_step_size (float)

  • regularization_parameter (float)

  • step_size_growth_factor (float)

  • step_size_decay_factor (float)

  • max_step_size_decrease_trys (int)

  • relaxation_parameter (float)

  • error_norm_tolerance (float)

  • delta_params_tolerance (float)

  • rejuvenation_strategy (str)

  • rejuvenation_interval (int)

  • rejuvenation_inflation (float)

  • rejuvenation_prior_weight (float)

  • max_rejuvenations (int)

  • rejuvenation_cooldown (int)

  • max_iterations (int)

  • random_seed (int)

  • dispatcher (BaseDispatcher | None)

  • bounded_parameter_handling (str)

  • transform_interior_margin (float)

  • transform_map (str)

  • absolute_eki_directory (str)

Multi-fidelity EKI#

romtools.workflows.inverse.mf_eki_drivers.run_mf_eki(model, rom_model_builder, parameter_space, observations, observations_covariance, parameter_mins=None, parameter_maxes=None, absolute_work_dir=None, fom_ensemble_size=10, rom_extra_ensemble_size=30, rom_tolerance=0.005, use_updated_rom_in_update_on_rebuild=True, 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=0.001, rejuvenation_strategy='none', rejuvenation_interval=5, rejuvenation_inflation=1.1, rejuvenation_prior_weight=0.0025, max_rejuvenations=3, rejuvenation_cooldown=10, max_rom_training_history=1, rom_substep_start_iteration=0, rom_substep_end_iteration=None, num_rom_substeps=0, max_iterations=50, random_seed=1, fom_evaluation_concurrency=1, rom_evaluation_concurrency=1, restart_file=None, dispatcher=None, *, bounded_parameter_handling='clip', transform_interior_margin=0.0, transform_map='sigmoid', absolute_eki_directory=None)[source]

Run MF-EKI with historical clipping or an unconstrained bound transform.

Parameters:

  • model (QoiModel)

  • rom_model_builder (QoiModelBuilderWithTrainingData)

  • parameter_space (ParameterSpace)

  • observations (ndarray)

  • observations_covariance (ndarray)

  • parameter_mins (ndarray)

  • parameter_maxes (ndarray)

  • absolute_work_dir (str)

  • fom_ensemble_size (int)

  • rom_tolerance (float)

  • use_updated_rom_in_update_on_rebuild (bool)

  • initial_step_size (float)

  • regularization_parameter (float)

  • step_size_growth_factor (float)

  • step_size_decay_factor (float)

  • max_step_size_decrease_trys (int)

  • relaxation_parameter (float)

  • error_norm_tolerance (float)

  • delta_params_tolerance (float)

  • rejuvenation_strategy (str)

  • rejuvenation_interval (int)

  • rejuvenation_inflation (float)

  • rejuvenation_prior_weight (float)

  • max_rejuvenations (int)

  • rejuvenation_cooldown (int)

  • max_rom_training_history (int)

  • rom_substep_start_iteration (int)

  • rom_substep_end_iteration (int | None)

  • num_rom_substeps (int)

  • max_iterations (int)

  • random_seed (int)

  • fom_evaluation_concurrency (int)

  • rom_evaluation_concurrency (int)

  • restart_file (str)

  • dispatcher (BaseDispatcher | None)

  • bounded_parameter_handling (str)

  • transform_interior_margin (float)

  • transform_map (str)

  • absolute_eki_directory (str)