Skip to main content

engine

engine

HistoryMatching — the main user-facing class for running a calibration.

Configure everything in one constructor call (parameter bounds, observations, simulator function, and options), then call HistoryMatching.run for an automated workflow or HistoryMatching.step / commit_step / revert_step for interactive, wave-by-wave control.

Classes

Name Description
EngineState Possible states of the HistoryMatching engine.
HistoryMatching Bayesian history matching — configure everything in one constructor call.
IterationSnapshot Snapshot of engine state at a specific iteration.

EngineState

engine.EngineState()

Possible states of the HistoryMatching engine.

HistoryMatching

engine.HistoryMatching(
    function=None,
    bounds=None,
    observations=None,
    *,
    sampling_strategy='lhs',
    feature_selection=None,
    emulator_type='bayes_linear',
    emulator_factory=None,
    emulator_bank=None,
    n_samples=1000,
    implausibility_threshold=3.0,
    max_iterations=10,
    random_seed=None,
    auto_reduce_space=False,
    oversample_factor=1.1,
    max_batch_size=10000,
    output_dir='./hm_output',
    run_name=None,
    convergence_threshold=0.0,
    nroy_method='auto',
    nroy_options=None,
    max_candidate_factor=1000,
)

Bayesian history matching — configure everything in one constructor call.

Pass your parameter bounds, observations, and simulator function as plain arguments. Friendly values (strings, dicts, lists) are accepted for the strategy options and turned into the underlying objects for you; sensible defaults are used for anything you omit.

Examples

import historymatching as hm

# The simulator takes a DataFrame of samples and returns one row of outputs per sample.
# Each output name must match an observation key.
def run_sir(samples):
    rows = []
    for _, row in samples.iterrows():
        rows.append({'peak_incidence': simulate_peak(row['beta'], row['gamma'])})
    return rows   # a DataFrame is also accepted

engine = HistoryMatching(
    function=run_sir,
    bounds={'beta': (0.5, 3.0), 'gamma': (0.1, 1.0)},
    observations={'peak_incidence': (120.0, 50.0)},  # (mean, std)
    emulator_type='bayes_linear',
    n_samples=500,
    max_iterations=4,
)

# Automated execution
results = engine.run()
plausible = engine.get_nroy_samples()     # NROY = "Not Ruled Out Yet"

# Interactive, step-by-step execution
result = engine.step()             # run one wave
engine.commit_step()               # accept it (or engine.revert_step())
engine.feature_selection = ['different_output']   # reconfigure on the fly
result = engine.step()

The simulator function receives a pandas DataFrame of parameter samples (one row per sample) and may return either a DataFrame or a list of dicts (one dict per sample) mapping output names to values.

Attributes

Name Description
emulator_factory The emulator factory. Assign an EmulatorFactory for full control.
emulator_type Emulator type as a string. Assign 'gpr'/'glm'/'linear' to change it.
feature_selection Which outputs to emulate each wave. Assign a name/list/dict/strategy (e.g. engine.feature_selection = ['peak']).
max_iterations Maximum number of waves to run (you may raise it mid-run).
outputs Names of the observed outputs being matched.
parameters Names of the parameters being calibrated.
results All committed IterationResult objects, in order.
sampling_strategy Sampling strategy. Assign a name/dict/strategy to change it (e.g. engine.sampling_strategy = 'grid').

Methods

Name Description
add_iteration_callback Add callback to be called after each iteration.
add_progress_callback Add callback to be called on progress updates.
commit_step Commit the pending iteration results.
drop_emulator_from_pending Remove a specific emulator from the pending iteration before committing.
enumerate Iterate over committed waves as (iteration, result, samples) tuples.
get_all_results Get all committed iteration results.
get_iteration_result Get result for a specific iteration.
get_nroy_samples Get plausible parameter samples — the calibration result.
get_pending_next_samples Get the proposed samples for the next iteration, if available.
get_status_summary Get a human-readable, multi-line summary of the current status.
implausibility Implausibility of each parameter point under every committed emulator.
in_nroy Test whether each parameter point is inside the current NROY region.
load_checkpoint Load engine state from checkpoint file.
nroy_summary Print and return a text summary of the current NROY region: number of
plot_constrained_dims Constrained-direction (variance-reduction) plot of the NROY cloud
plot_convergence Plot the NROY fraction per wave (delegates to
plot_ensemble_fan Fan/spaghetti plot of an ensemble of trajectories vs observed data.
plot_marginals Marginal histograms of the NROY samples (delegates to
plot_nroy Corner/pairplot of the NROY parameter cloud (delegates to
plot_nroy_parameters Deprecated alias for plot_nroy.
plot_zscores Standardised outputs vs targets across waves (delegates to
print_emulator_quality_metrics Print and return per-feature emulator quality metrics for a wave.
revert_step Revert the pending iteration results.
run Run automated history matching workflow.
save_checkpoint Save engine state to checkpoint file.
save_diagnostics Save every committed wave’s artifacts under directory.
step Execute a single history matching iteration.
validate Validate the engine’s configuration.
add_iteration_callback
engine.HistoryMatching.add_iteration_callback(callback)

Add callback to be called after each iteration.

add_progress_callback
engine.HistoryMatching.add_progress_callback(callback)

Add callback to be called on progress updates.

commit_step
engine.HistoryMatching.commit_step()

Commit the pending iteration results.

This makes the changes from the last step() permanent and advances the iteration counter.

Raises
Name Type Description
RuntimeError If no pending iteration to commit
drop_emulator_from_pending
engine.HistoryMatching.drop_emulator_from_pending(feature)

Remove a specific emulator from the pending iteration before committing.

Call this after step() but before commit_step() to exclude an emulator whose diagnostics indicate a poor fit. The emulator will not be stored in the bank and will not contribute to implausibility filtering in future waves.

The simulation data for this wave is unaffected — only the emulator is dropped. The remaining emulators are committed as normal.

Parameters
Name Type Description Default
feature str Name of the feature whose emulator should be dropped. required
Raises
Name Type Description
RuntimeError If called when no step is pending.
KeyError If the feature was not emulated in the pending step.
Example
result = engine.step()

metrics = result.get_emulator_quality_metrics()
for output in result.emulated_outputs:
    print(f"{output}: R²={metrics[output]['r2']:.3f}")

# Drop any emulator with a poor fit before committing
engine.drop_emulator_from_pending('output_c')
engine.commit_step()
enumerate
engine.HistoryMatching.enumerate()

Iterate over committed waves as (iteration, result, samples) tuples.

Example
for i, result, samples in engine.enumerate():
    print(i, result.nroy_fraction, len(samples))
get_all_results
engine.HistoryMatching.get_all_results()

Get all committed iteration results.

get_iteration_result
engine.HistoryMatching.get_iteration_result(iteration)

Get result for a specific iteration.

get_nroy_samples
engine.HistoryMatching.get_nroy_samples(n=None, method=None, **kwargs)

Get plausible parameter samples — the calibration result.

Returns the NROY (“Not Ruled Out Yet”) samples: parameter sets that pass ALL committed emulators’ implausibility checks. By default returns the pre-computed set from the last wave (n_samples of them). Pass n to draw a fresh, larger set filtered through the current emulator bank. No new simulations are run — only fast emulator predictions are used.

Parameters
Name Type Description Default
n Optional[int] Number of NROY samples to return. If None, returns the pre-computed set from the last committed wave. None
method Optional[str] NROY sampling method: 'auto' (LHS first, escalates to ray+importance if needed), 'lhs' (pure rejection only), or None (uses engine default). For unbiased final samples (e.g. trajectory selection), use method='lhs'. None
**kwargs Extra options passed to generate_nroy_design(): n_lines, points_per_line (ray_resample); max_candidates (lhs); imp_scale, maximin_reps, etc. {}
Returns
Name Type Description
pd.DataFrame DataFrame of NROY samples, or empty DataFrame if no iterations committed.
Example
results = engine.run()
nroy = engine.get_nroy_samples()                    # cached from last wave
nroy = engine.get_nroy_samples(10000)               # larger draw (default method)
nroy = engine.get_nroy_samples(5000, method='lhs')  # unbiased for posterior
nroy = engine.get_nroy_samples(5000, method='auto',
                               n_lines=40, points_per_line=100)
get_pending_next_samples
engine.HistoryMatching.get_pending_next_samples()

Get the proposed samples for the next iteration, if available.

This allows inspection of pre-computed samples after step() but before commit_step(). The samples are computed during step() execution and will be used for the next iteration if the current step is committed.

Returns
Name Type Description
Optional[pd.DataFrame] DataFrame of proposed samples for next iteration, or None if no step is pending
Example
result = engine.step()
next_samples = engine.get_pending_next_samples()
if next_samples is not None:
    print(f"Proposed {len(next_samples)} samples for next iteration")
    # Inspect the samples before deciding to commit
    engine.commit_step()  # or engine.revert_step()
get_status_summary
engine.HistoryMatching.get_status_summary()

Get a human-readable, multi-line summary of the current status.

(To reconfigure mid-run, just assign to the matching attribute, e.g. engine.feature_selection = ['peak'] or engine.max_iterations = 20.)

implausibility
engine.HistoryMatching.implausibility(samples)

Implausibility of each parameter point under every committed emulator.

A diagnostic companion to in_nroy(): it evaluates every emulator on every point, without short-circuiting, so you can see which wave and target ruled a point out, and by how much. A point is in NROY when it is inside the bounds and every value in its row is at most implausibility_threshold.

Parameters
Name Type Description Default
samples pd.DataFrame DataFrame with one column per parameter. required
Returns
Name Type Description
pd.DataFrame DataFrame indexed like samples, with one column per committed
pd.DataFrame emulator. Columns are a MultiIndex of (iteration, feature). Use
pd.DataFrame .max(axis=1) for each point’s maximum implausibility.
Raises
Name Type Description
ValueError If a parameter column is missing.
in_nroy
engine.HistoryMatching.in_nroy(samples, batch_size=None)

Test whether each parameter point is inside the current NROY region.

A point is in NROY when it lies inside the parameter bounds and passes the implausibility threshold for every committed emulator. This is the same test get_nroy_samples() applies to its candidates, so the two always agree. Use it for points you supply yourself: a known truth in a re-identification run, a uniform or Sobol design for trajectory selection, an MCMC proposal, or samples from another method.

No simulations are run — only emulator predictions. Pending (uncommitted) emulators are not used.

Parameters
Name Type Description Default
samples pd.DataFrame DataFrame with one column per parameter; extra columns are ignored. required
batch_size Optional[int] Optional number of rows to test at a time, to bound the memory of emulator predictions on very large candidate sets. None
Returns
Name Type Description
np.ndarray Boolean array of shape (len(samples),), in row order.
Raises
Name Type Description
ValueError If a parameter column is missing.
Example

mask = engine.in_nroy(candidates) nroy = candidates[mask] engine.in_nroy(pd.DataFrame([true_params]))[0] # truth ruled out?

load_checkpoint
engine.HistoryMatching.load_checkpoint(
    filepath,
    sampling_strategy,
    feature_selection,
    emulator_factory,
)

Load engine state from checkpoint file.

nroy_summary
engine.HistoryMatching.nroy_summary()

Print and return a text summary of the current NROY region: number of waves and samples, latest NROY fraction, and each parameter’s median with its 95% interval.

plot_constrained_dims
engine.HistoryMatching.plot_constrained_dims(n_top=5, axes=None, **kwargs)

Constrained-direction (variance-reduction) plot of the NROY cloud (delegates to historymatching.plotting.plot_constrained_dims).

plot_convergence
engine.HistoryMatching.plot_convergence(ax=None, **kwargs)

Plot the NROY fraction per wave (delegates to historymatching.plotting.plot_convergence).

plot_ensemble_fan
engine.HistoryMatching.plot_ensemble_fan(
    trajectories,
    observed=None,
    x=None,
    xlabel='Index',
    ylabel='Value',
    title='Ensemble vs observed',
    ax=None,
    show=False,
    **kwargs,
)

Fan/spaghetti plot of an ensemble of trajectories vs observed data.

Delegates to historymatching.plotting.plot_ensemble_fan. Handy for eyeballing how well a set of plausible (NROY) parameter sets reproduces the data.

Parameters
Name Type Description Default
trajectories 2-D array-like, shape (n_runs, n_timepoints) — one row per simulated trajectory. required
observed Optional observed series of length n_timepoints. None
x Optional x-axis values (defaults to 0..n_timepoints-1). None
xlabel, ylabel, title Axis labels / title. required
ax Optional matplotlib Axes to draw into (a new figure is made if None). None
show bool If True, call plt.show() before returning. False
**kwargs Forwarded to the plotting function (e.g. ci, show_members, show_band). {}
Returns
Name Type Description
The Matplotlib Axes.
plot_marginals
engine.HistoryMatching.plot_marginals(truth=None, axes=None, **kwargs)

Marginal histograms of the NROY samples (delegates to historymatching.plotting.plot_marginals).

plot_nroy
engine.HistoryMatching.plot_nroy(
    samples=None,
    truth=None,
    derived=None,
    bins=25,
    axes=None,
    **kwargs,
)

Corner/pairplot of the NROY parameter cloud (delegates to historymatching.plotting.plot_pairplot).

Pass derived to overlay computed quantities, e.g. {'R0': lambda df: df['beta'] / df['gamma']}.

plot_nroy_parameters
engine.HistoryMatching.plot_nroy_parameters(
    samples=None,
    derived=None,
    true_parameters=None,
    bins=25,
    fig_kwargs=None,
    show=False,
)

Deprecated alias for plot_nroy.

Deprecated since v2.0.1. Use plot_nroy instead (true_parameters= is now truth=). Retained as a thin forwarder that returns (fig, axes) for backwards compatibility; fig_kwargs is no longer applied.

plot_zscores
engine.HistoryMatching.plot_zscores(ax=None, **kwargs)

Standardised outputs vs targets across waves (delegates to historymatching.plotting.plot_zscores_vs_targets).

print_emulator_quality_metrics
engine.HistoryMatching.print_emulator_quality_metrics(iteration=None)

Print and return per-feature emulator quality metrics for a wave.

Parameters
Name Type Description Default
iteration Optional[int] Wave number to report (1-based). Defaults to the most recently committed wave. None
Returns
Name Type Description
dict Dict mapping feature name -> metrics dict (R², MSE, training size, …).
revert_step
engine.HistoryMatching.revert_step()

Revert the pending iteration results.

This discards the changes from the last step() and returns to the previous state.

Raises
Name Type Description
RuntimeError If no pending iteration to revert
run
engine.HistoryMatching.run(auto_commit=True, resume=False)

Run automated history matching workflow.

Parameters
Name Type Description Default
auto_commit bool Whether to automatically commit each iteration True
resume bool If True, load checkpoint from output_dir and continue. If False (default), start fresh. Raises if a checkpoint exists and resume is False (to prevent accidental overwrites). False
Returns
Name Type Description
list[IterationResult] List of IterationResult objects for all iterations
Raises
Name Type Description
ValueError If simulation function is not set or configuration is invalid
save_checkpoint
engine.HistoryMatching.save_checkpoint(filepath)

Save engine state to checkpoint file.

save_diagnostics
engine.HistoryMatching.save_diagnostics(directory, verbose=False)

Save every committed wave’s artifacts under directory.

Writes one wave{N}/ subdirectory per wave (samples, simulator outputs, pickled emulators, predicted-vs-actual + ARD diagnostic plots, a convergence figure, and metrics.json) by calling IterationResult.save for each wave. This is the manual equivalent of the per-wave output written automatically when output_dir is set.

Parameters
Name Type Description Default
directory str Directory to write into (created if needed). required
verbose bool If True, print the path written for each wave. False
step
engine.HistoryMatching.step(features=None)

Execute a single history matching iteration.

Parameters
Name Type Description Default
features Optional[list[str]] Optional list of features to emulate (overrides strategy) None
Returns
Name Type Description
IterationResult IterationResult for this iteration
Raises
Name Type Description
RuntimeError If engine is not in a valid state for stepping
ValueError If simulation function is not set or configuration is invalid
validate
engine.HistoryMatching.validate()

Validate the engine’s configuration.

Checks that the required components are present and that all numeric and enumerated options are within their valid ranges. Called automatically at the start of run and step (configuration attributes are public and may be changed after construction); may also be called directly.

Raises
Name Type Description
ValueError If any required component is missing or an option is invalid.

IterationSnapshot

engine.IterationSnapshot(
    iteration,
    parameter_space,
    emulator_bank,
    result=None,
    next_samples=None,
    total_samples_generated=0,
    total_samples_accepted=0,
    acceptance_rate=1.0,
    metadata=dict(),
)

Snapshot of engine state at a specific iteration.