This notebook demonstrates how to use the history matching library with a stochastic SIR epidemiological model using the fully automated workflow.
Overview
History matching is an iterative method for model calibration that: 1. Uses statistical emulators to approximate expensive simulations 2. Iteratively reduces the parameter space to “plausible” regions 3. Avoids regions where the model cannot match observed data
We will calibrate a SIR model to synthetic outbreak data to recover the “true” transmission parameters. History matching is often run manually, inspecting emulator diagnostics and choosing features wave by wave; here we rely on the package’s automatic feature selection, which works well enough to calibrate end-to-end from a single run() call. For the hands-on manual approach, see the Manual Workflow tutorial.
import numpy as npimport pandas as pdimport matplotlib.pyplot as pltimport historymatching as hmimport logging; logging.getLogger("historymatching").propagate =False# keep INFO logs out of the rendered docsfrom model import SIR, generate_observed_data%matplotlib inlinenp.random.seed(42)
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1794256908.546855 3922 cudart_stub.cc:31] Could not find cuda drivers on your machine, GPU will not be used.
I0000 00:00:1794256908.588083 3922 cpu_feature_guard.cc:227] This TensorFlow binary is optimized to use available CPU instructions in performance-critical operations.
To enable the following instructions: AVX2 FMA, in other operations, rebuild TensorFlow with the appropriate compiler flags.
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1794256909.752156 3922 cudart_stub.cc:31] Could not find cuda drivers on your machine, GPU will not be used.
/home/runner/work/historymatching/historymatching/.venv/lib/python3.13/site-packages/gpflow/versions.py:1: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
import pkg_resources
Generate Synthetic “Observed” Data
We create synthetic outbreak data with known parameters that we will try to recover through history matching.
Configure the run in a single hm.HistoryMatching(...) call. We define: - bounds: the search space for calibration - observations: the target data as (mean, std) pairs - function: the simulator to run at each sampled point
By default feature selection (feature_selection) uses automatic mean-squared z-score selection capped at one feature per wave. You can raise that cap — or specify features explicitly — to train several emulators in a single wave. Each emulator targets one observable, and implausibility is computed per-emulator then maximised across all of them, so a sample must pass every constraint simultaneously.
Automated mode: raise the cap
engine = hm.HistoryMatching( bounds=parameter_bounds, observations=observations, function=sir_simulation_function, sampling_strategy="lhs", emulator_type="bayes_linear", feature_selection={"method": "mean_sq_z", "max_features": 3}, # ← up to 3 per wave n_samples=500, max_iterations=4, implausibility_threshold=3.0, random_seed=123,)results = engine.run()
Inspecting per-feature quality after engine.run()
IterationResult.get_emulator_quality_metrics() returns one entry per emulated feature. Use it to check whether each emulator was worth including:
print("Per-feature emulator quality across all waves:")print(f"{'Wave':<6}{'Feature':<20}{'R²':>6}{'MSE':>10}{'n_train':>8}")print("-"*56)for result in results: metrics = result.get_emulator_quality_metrics()for feature, m in metrics.items(): r2 = m.get("r2", float("nan")) mse = m.get("mse", float("nan")) n = m.get("n_train", "?")print(f"{result.iteration:<6}{feature:<20}{r2:>6.3f}{mse:>10.4g}{n:>8}")
In the automated workflow there is no opportunity to drop a poor emulator mid-wave — use the manual workflow (Manual Workflow) if you need to inspect diagnostics and selectively drop emulators before committing each wave.
Saving diagnostics to disk
Each IterationResult has a save(fig_dir, all_results) method that writes per-feature predicted-vs-actual plots, ARD lengthscale charts (GPR only), a convergence figure, and a metrics.json file:
import tempfile, osdiag_dir = tempfile.mkdtemp(prefix="hm_diagnostics_")for result in results: result.save(diag_dir, all_results=results)print(f"Diagnostics saved to {diag_dir}/")for f insorted(os.listdir(diag_dir)):print(f" {f}")
Diagnostics saved to /tmp/hm_diagnostics_iplia15d/
wave1
wave2
wave3
wave4
Summary
This notebook demonstrated the automated history matching workflow:
Model setup: imported SIR and generate_observed_data from model.py
Configuration: used hm.HistoryMatching to define parameter bounds, observations, and emulator settings in a single constructor call
Execution: called engine.run() to run all iterations automatically
Analysis: inspected the final plausible parameter space and validated against observed data
Next steps
Goal
Tutorial
Manual step-by-step control with emulator inspection