Skip to main content

iteration_result

iteration_result

IterationResult — the result of a single history matching wave.

Classes

Name Description
IterationResult Immutable result from one history matching wave (iteration).

IterationResult

iteration_result.IterationResult(
    iteration,
    parameter_space,
    samples,
    simulation_results,
    emulated_outputs,
    emulators,
    nroy_fraction,
    execution_time_seconds,
)

Immutable result from one history matching wave (iteration).

Holds the parameter samples run this wave, the simulator outputs, the outputs that were emulated, the trained emulators, and the fraction of parameter space still plausible (nroy_fraction).

The NROY (Not Ruled Out Yet) set itself is not stored here — it is defined implicitly by the emulator bank. Use HistoryMatching.get_nroy_samples to draw plausible samples. The final wave’s samples + simulation_results can be fed directly into trajectory selection.

Methods

Name Description
get_emulator Get the emulator trained for a specific output this wave.
get_emulator_quality_metrics Quality metrics for each emulated output.
plot_emulator_diagnostics Plot diagnostics for a specific output’s emulator.
plot_emulator_quality Bar chart of per-output emulator R² (delegates to
plot_predicted_vs_actual Predicted-vs-actual scatter for one output’s emulator on its held-out
quality_table Per-output emulator quality as a table (rows = outputs; columns
save Save everything about this wave to {directory}/wave{N}/.
summary A summary of this wave as a plain dict (handy for logging/inspection).
get_emulator
iteration_result.IterationResult.get_emulator(output)

Get the emulator trained for a specific output this wave.

Parameters
Name Type Description Default
output str Name of the emulated output. required
Returns
Name Type Description
BaseEmulator Emulator instance.
Raises
Name Type Description
KeyError If no emulator was trained for that output this wave.
get_emulator_quality_metrics
iteration_result.IterationResult.get_emulator_quality_metrics()

Quality metrics for each emulated output.

Returns
Name Type Description
Dict[str, Dict[str, float]] Dict mapping each output name to a metrics dict with keys
Dict[str, Dict[str, float]] r2 (test R²), mse (test MSE), and n_train (training points).
Dict[str, Dict[str, float]] A key is absent if that metric could not be computed.
plot_emulator_diagnostics
iteration_result.IterationResult.plot_emulator_diagnostics(output, **kwargs)

Plot diagnostics for a specific output’s emulator.

Parameters
Name Type Description Default
output str Name of the emulated output. required
**kwargs Additional arguments passed to the emulator’s plot method. {}
plot_emulator_quality
iteration_result.IterationResult.plot_emulator_quality(ax=None, **kwargs)

Bar chart of per-output emulator R² (delegates to historymatching.plotting.plot_emulator_quality).

plot_predicted_vs_actual
iteration_result.IterationResult.plot_predicted_vs_actual(
    output,
    *,
    ax=None,
    **kwargs,
)

Predicted-vs-actual scatter for one output’s emulator on its held-out test set (delegates to historymatching.plotting.plot_predicted_vs_actual).

quality_table
iteration_result.IterationResult.quality_table()

Per-output emulator quality as a table (rows = outputs; columns r2/mse/n_train). Renders nicely in notebooks.

save
iteration_result.IterationResult.save(directory, all_results=None)

Save everything about this wave to {directory}/wave{N}/.

Writes the parameter samples.csv and simulation_results.csv, a pickle of each emulator under emulators/, per-output diagnostic figures (predicted-vs-actual, and ARD lengthscales for GPR), a metrics.json, and — when all_results is supplied — a convergence.png showing the plausible fraction across waves.

Parameters
Name Type Description Default
directory str Parent directory; a wave{N}/ subfolder is created. required
all_results Optional[list] Optional list of all waves so far, used for the convergence plot. None
Returns
Name Type Description
str The path to the wave{N}/ directory that was written.
summary
iteration_result.IterationResult.summary()

A summary of this wave as a plain dict (handy for logging/inspection).