What’s new
Version 2.2.0 (2026-11-09)
Changed defaults
BayesLinearlearns its nugget by default:nugget='mle', was a fixed1e-6. A fixed jitter of 1e-6 treats every simulator as deterministic, so the emulator fits a stochastic simulator’s run-to-run noise as signal. On the 48 benchmark scenarios below, all with run-to-run noise, the learned nugget’s median held-out R² is 0.733, against 0.543 for the old default and 0.654 for a fixed 1e-6 with this release’s search; it is at least as high in all 48. The default lower bound on the learned nugget,nugget_bounds[0], rises from 1e-8 to 1e-6, the old fixed value. For a deterministic simulator the learned nugget goes to that bound, which keeps the correlation matrix well conditioned and keepspredict_bounds’s variance screening as tight as before. The'midpoint'start therefore begins at a nugget of 1e-3 instead of 1e-4. Passnugget=1e-6(ornugget_bounds=(1e-8, 1.0)) for the old behaviour. Results change for every Bayes-linear emulator built with the defaults, including the engine’s. Training is no slower than the old default: 36 s against 46 s for the benchmark’s 48 fits, and 49 s against 51 s at 3,000 points × 21 parameters.
Fixes
- Bayes-linear hyperparameter fits no longer stop after one step, with fixed or learned nuggets, and both run one procedure. Before, the fixed-nugget fit (the default is
nugget=1e-6) andnugget='mle'each made one L-BFGS-B start from correlation lengths 1, in separate code, and both failed the same way. With every variable bounded, L-BFGS-B’s first trial step is the whole negative gradient, and the raw NLL’s gradient grows with the number of training points, so that step put many log correlation lengths on their lower bound at once. There the NLL is flat, so the search stopped with a zero gradient and reported success, leaving the trend plus white noise. Both could also stop at a poor local optimum. Now:- One search, used for every fit. It minimizes NLL / n, which keeps the first step short, with an analytic gradient of the concentrated NLL with respect to the log correlation lengths and log nugget, from the existing Cholesky factor, in place of d + 1 finite-difference evaluations. A fixed nugget only leaves log(nugget) out of the variables.
ftolis relative, so its meaning is unchanged;gtolnow applies to the gradient of NLL / n. At 3,000 training points × 21 parameters, one NLL-and-gradient evaluation takes 0.38 s; finite differences need 22 NLL evaluations of 0.175 s each, about 3.9 s. - Several starts, for every fit. The new
startsoption lists them, default('warm', 'midpoint', 1e-2). Each runs a search over the correlation lengths and the nugget withinnugget_bounds.'warm'first fits the correlation lengths with the nugget fixed atwarm_nugget(new option, default1e-2), then searches from there.'midpoint'starts from correlation lengths 1 and the geometric middle ofnugget_bounds(the old'mle'start). A number is a starting nugget with correlation lengths 1. Withnugget='mle', the lowest NLL among these solutions, the warm start’s first stage included, wins. With a fixed nugget, the correlation lengths are then refitted at the fixed nugget from each solution and from correlation lengths 1, and the lowest refit wins. Letting the nugget move takes the search around barriers between optima in the correlation lengths: at 3,000 points × 21 parameters and a fixed nugget of 0.03, both searches over the correlation lengths alone stop at NLL −2,465, and the refit from the learned-nugget solution reaches −2,795. No one start wins everywhere, so the search from correlation lengths 1 stays a candidate. Every run’s NLL, nugget, iterations, evaluations, message and time is inget_hyperparameters()['starts'].
tests/benchmarks/benchmark_mle_nugget.py: 300 and 1,000 points, 10 and 21 parameters, noise sd 0.1–0.6; with the new defaultnugget_bounds), fixed-nugget fits at 1e-6, 0.01 and 0.03 stopped after at most one iteration, with correlation lengths on their lower bound, in 27, 25 and 19 scenarios, and 28, 33 and 26 ended more than 1 NLL above the best fit found at the same nugget, by up to 228. Now every fixed-nugget fit is within 0.05 NLL of that best, and the median held-out R² rose from 0.543, 0.567 and 0.599 to 0.654, 0.714 and 0.728. The fixed-nugget fits took 184 s in all, against 166 s. Thenugget='mle'fit used to end more than 1 NLL above a fixed nugget of 0.01 or 0.03 in 18 scenarios, by up to 338; its median held-out R² rose from 0.543 to 0.733, and its fits took 36 s against 73 s. In 2 of the 48 (noise sd 0.6), it still ends 2.2 and 4.7 NLL above a fixed nugget of 0.03, a local optimum. At 3,000 points × 21 parameters (noise sd 0.2) on macOS, fits took 66 s at nugget 1e-6 (51 s before), 68 s at 0.03 (88 s, NLL −2,794.9 both), and 49 s with'mle'(68 s, NLL −2,797.0 against −2,455.8). Results change for every Bayes-linear emulator, fixed nugget or learned. (#281) - One search, used for every fit. It minimizes NLL / n, which keeps the first step short, with an analytic gradient of the concentrated NLL with respect to the log correlation lengths and log nugget, from the existing Cholesky factor, in place of d + 1 finite-difference evaluations. A fixed nugget only leaves log(nugget) out of the variables.
Version 2.1.0 (2026-11-04)
New features
- Public NROY membership test.
HistoryMatching.in_nroy(samples, batch_size=None)returns a boolean mask: True where a point is inside the bounds and passes every committed emulator.HistoryMatching.implausibility(samples)returns each point’s implausibility under every committed emulator, with (iteration, feature) columns. Both use the same test asgenerate_nroy_design. Use them for points you supply: a known truth in a re-identification run, uniform candidates for trajectory selection, MCMC proposals, or samples from another method. historymatching.nroy_sampling.nroy_maskis that test as a function of an emulator bank, for filtering without the engine.- Faster NROY tests with Bayes-linear emulators, same mask.
nroy_mask(behindgenerate_nroy_design,in_nroyandget_nroy_samples) first asks each emulator forpredict_bounds(x): bounds on the mean and variance thatpredictwould return. A point that is implausible at every value within the bounds is ruled out, and one that is plausible at every value is ruled in. Only the points in between go throughpredict.BayesLinearbounds the variance below bysigma2 * nuggetand above by the variance given only its first 500 training points, which costs about 2% of the full variance at 3,750 training points. Other emulators keep callingpredicton every point, andimplausibility()is unchanged. In a synthetic benchmark with 21 parameters, 3,750 training points, two outputs and 100,000 uniform candidates (tests/benchmarks/benchmark_nroy_screening.py), the bounds decided 80–94% of the points. Screening madenroy_mask1.6–3.0× faster on macOS (Accelerate). On Linux with OpenBLAS it was 3.5–7.3× faster with one thread, the Coiled batch setting, and 1.3–2.1× with eight. Masks were identical in every run. With the fasterpredictbelow,nroy_maskis 7.6–10.7× faster than before on macOS and 8.5–16.4× faster with one OpenBLAS thread. (#277) - Bayes-linear
predictandtrainare faster and use far less memory. The correlations with the training points come from one matrix product (|a|^2 + |b|^2 - 2 a.b) instead of an(n_new, n_train, d)array of differences. At 3,750 training points × 21 parameters,predicton 5,000 points went from 5.9 s and 6.0 GB peak to 0.37 s and 0.28 GB. A batch of 20,000 points, which used to need about 24 GB, takes 1.7 s and 1.1 GB. One training likelihood evaluation went from 1.3 s and 4.5 GB to 0.32 s and 0.31 GB, andtrain()('mle'nugget) from 37 s to 9 s on 900 points and from 768 s and 3.7 GB to 374 s and 0.26 GB on 3,375. The variance now takes one triangular solve instead of two, which is 2–3× faster. Results move at the rounding level, about 1e-13 on well-conditioned emulators. With near-duplicate training points and nuggets of 1e-6 to 1e-8, means move by up to 4e-7 and variances by up to 5e-6 relative. Fits can follow a slightly different optimizer path. (#277) nroy_maskapplies emulators oldest wave first, so it evaluates fewer points. The mask is the same. Each emulator sees only the points still in. The early waves’ emulators were trained over the whole box and reject most far-away points, while the newest one was trained in a small region and rejects few. On a 10-wave, 21-parameter Bayes-linear bank, uniform candidates over the box needed 1.21 emulator evaluations each oldest first, against 2.17 newest first, which is 1.8× less work. The greedy optimum was 1.205. Candidates jittered around NROY points, like the ray and importance-sampling proposals, were also as cheap or cheaper oldest first: 1.82 against 3.20, 4.74 against 5.34, and 8.69 against 8.88 as the jitter shrank. (#279)
Fixes
- The linear-model and GLM emulators report the std of a new simulator run, so their implausibility is right. Implausibility divides by the target’s data uncertainty plus the emulator’s variance, so that variance has to include the simulator’s run-to-run noise, as
BayesLinear(sigma_sq * nugget) andGPR(predict_y) already do.LinearModel('linear') andGLM('glm') returned only the standard error of the fitted mean, which understates it and rules out too much;LinearModelScipyreturned the spread of all training outputs, which overstates it. They now return the predictive std: residual variance plus the mean’s variance forLinearModelandLinearModelScipy, and the family’s variance at the mean (scale for Gaussian, the mean for Poisson) plus the mean’s variance forGLM. In a test with known noise, the standard deviation of (new run − predicted mean) / predicted std was 10.9 (LinearModel) and 0.44 (LinearModelScipy) before, and 0.99 for all of them now. Their interval columns follow the same definitions. (#273) GLM.predictworks on statsmodels 0.15, which removed thelinear=argument it used.LinearModelandGLMcan predict a single point.statsmodels.add_constantskips the intercept when every column is constant, which a one-row frame always is, so one-point predictions failed with a shape error; in the NROY filter that happened whenever one candidate was left. The intercept is now always added, in training and prediction.LinearModel’s interval columns also no longer come back as NaN for frames with non-contiguous index labels.- Every wave draws a fresh design, and every run records its seed. Previously, each wave’s candidate generation restarted from
random_seed, so consecutive waves re-drew the same plausible points. In a 21-parameter, 10-wave run, 34% of all design points repeated earlier ones. Each wave, wave 1 included, now draws from its own stream, derived from(random_seed, wave). random_seed=None(the default) now draws a seed from OS entropy instead of running unseeded. The seed used, and whether it was user-supplied or drawn, is logged, written torun_config.jsonand stored in checkpoints, and resuming restores it. Passing that seed back reproduces the run under the same package version. This release changes which run a given seed produces, so seeded results differ from earlier versions.FastGPRPredictor’s numpy fallback (no numba) returns the predictive variance, not zero, matching the numba kernel and GPflow. Zero variance made every implausibility too large. (#272)
Removed
- The engine’s separate GPR filter (
_filter_fast,_filter_samples_slow,_build_fast_predictors) andhistorymatching.emulators.fast_predict.filter_nroy. The engine’s wave 1 sampler, its only caller, now filters throughnroy_masklikegenerate_nroy_designandin_nroy, so NROY membership has one implementation. Normal runs never reached the removed path: it ran only when wave 1 started with emulators already in the bank.FastGPRPredictorstays inemulators.fast_predict.
Version 2.0.1 (2026-06-07)
New features
- Plotting module —
historymatching.plotting. Composable figure helpers, each taking plain data, accepting anax=/axes=, and returning the Matplotlib axes:plot_pairplot(NROY corner plot),plot_marginals,plot_convergence,plot_zscores_vs_targets,plot_ensemble_fan,plot_constrained_dims,plot_emulator_quality,plot_predicted_vs_actual,plot_targets,plot_parameter_bounds, plusvariance_reduction/marginal_variance_reduction. The common ones are re-exported at the top level (e.g.hm.plot_pairplot). - Object-level plotting & summaries that delegate to the module:
HistoryMatching.plot_convergence/plot_marginals/plot_nroy/plot_zscores/plot_constrained_dims/nroy_summary;IterationResult.quality_table/plot_emulator_quality/plot_predicted_vs_actual;ParameterSpace.plot_bounds/summary;ObservationData.plot_targets/summary;EmulatorBank.summary. - Visualization tutorial —
docs/tutorials/06_visualization.ipynb.
Deprecations
HistoryMatching.plot_nroy_parameters()→ useplot_nroy()(pass known values viatruth=instead oftrue_parameters=). The old name still works with aDeprecationWarningand returns(fig, axes).
Fixes
- Emulator predictions are now consistently indexed, fixing a crash in the NROY filter.
EmulationResultsbuilt its mean from whatever the emulator passed — a numpy array (getting a freshRangeIndex) or a pandas Series (carrying the caller’s labels) — and its std independently. When the two disagreed, downstream arithmetic likeabs(mean - target) / np.sqrt(variance)aligned them by label rather than elementwise, returning the union of both indexes. Since the NROY filter predicts oncandidates.loc[mask], whose labels are non-contiguous after the first wave, this surfaced asoperands could not be broadcast together with shapes (15,) (29,) (15,)from_filter_nroy.LinearModelwas the emulator that actually tripped it (statsmodels returns an ndarray mean but a labelled Series formean_se). All emulators now label mean, std, and additional data with the index of the DataFrame they predicted on, andEmulationResultsforces the three onto a single shared index so the failure mode cannot recur. - The engine’s implausibility filter no longer silently drops constraints.
HistoryMatching._filter_samples_slowwas a near-verbatim copy of_filter_nroyinhistorymatching.nroy_sampling, but with one consequential difference: it caught emulator failures, logged a warning, and continued. Skipping a feature drops its constraint entirely, so points that should have been ruled implausible survived and the NROY region came out too wide — the exact failure mode the canonical implementation documents and deliberately guards against. The engine now delegates to_filter_nroy, so the two paths cannot drift apart and a failing emulator raises instead. Per-feature debug logging moved into the shared implementation and is unchanged. plot_emulator_qualityreads ther2metric key produced byget_emulator_quality_metrics()(previouslyr2_score, which silently produced empty charts).BaseEmulator.get_implausibilitynow addsmodel_discrepancyin quadrature (i.e. squared), consistent with the production pathObservationData.calculate_implausibility. This diagnostic helper previously added it un-squared; the main implausibility filtering was already correct and is unaffected.- Corrected the BIC value reported by
BaseEmulator.test(): the parameter penalty was2·k·log(n)and is now the standardk·log(n)(AIC was already correct).
Internal
- Hardened the emulator diagnostic plots (
plot_predictions,plot_zscores) against index mismatches: columns built from emulator output are now assigned by position rather than relying on pandas label alignment, which would fill them with NaN rather than raise if the indexes ever disagreed. - Removed unused legacy rejection-sampling methods (
_get_nroy_samples_serial,_compute_next_samples_serial) and the now-orphaned_filter_samples_with_bankhelper. The adaptive rejection-sampling loop now lives in a single place (_generate_plausible_samples); the public NROY path is unchanged (generate_nroy_design). - Replaced the hardcoded Bayes-linear correlation-length optimisation bounds with a named, documented
LOG_THETA_BOUNDSconstant. - Added
benchmarks/benchmark_predict.py(andbenchmarks/README.md) comparing the numba fast-predict path against GPflow, with a mean-agreement correctness guard that doubles as a regression check.
Version 2.0.0 (2026-06-05)
Breaking changes
- New flat constructor API. The fluent
HistoryMatchingBuilder(.with_*()+.build()) is removed in favour of a singleHistoryMatching(...)constructor that takes all options as keyword arguments. See the migration guide for the full v1→v2 mapping. engine.set_simulation_function(f)removed — passfunction=fto the constructor, or setengine.function = f.engine.update_*()methods removed — reconfigure via attribute assignment (e.g.engine.max_iterations = n).IterationResultmethods renamed/removed:summary_statistics()→summary(),get_emulator_for_feature()→get_emulator(),export_*()→save();get_implausibility_scores()removed.
Changed defaults
- Default emulator is now
bayes_linear(pure NumPy/SciPy, no TensorFlow dependency) — previouslygpr. Passemulator_type='gpr'for Gaussian Process emulation. - Default NROY method is now
'auto'(LHS first, escalating toray_resampleonly when LHS acceptance is too low) — in v1,get_nroy_samples()defaulted toray_resample.
The last release with the builder API is tagged v1.0.0.
Version 1.0.0 development (untagged; all part of the v1.0.0 tag)
New features
- Bayes Linear emulator: New
BayesLinearemulator type ('bayes_linear') inspired by the hmer R package. Uses an OLS regression trend plus squared-exponential correlated residuals with ARD correlation lengths. Pure numpy/scipy — no TensorFlow dependency. Good uncertainty quantification comparable to GPR, with faster training for moderate datasets. - Ray-resample NROY sampling: New 4-stage pipeline for finding NROY samples, inspired by hmer’s
generate_new_design(). Stages: (1) LHS rejection, (2) ray sampling along pairs of distant NROY points, (3) PCA-oriented importance sampling, (4) maximin thinning for space-filling coverage. Much faster than pure rejection at low acceptance rates (<1%). Was the default in v1 (changed to'auto'in v2.0.0); passnroy_method='lhs'for pure rejection or'ray_resample'to always use this pipeline. Tune vianroy_options=dict(n_lines=20, points_per_line=50, ...). - Detailed run logging: Engine writes
log.txtto the output directory with per-phase timing, per-emulator training progress, and NROY sampling progress at 10% intervals. Hyperparameters (ARD lengthscales, etc.) saved tometrics.json. - Improved diagnostics: Residuals/predictions wrap to 5-column grid for high-dimensional problems. Pred-vs-true split into train/test panels with error bars. Error scatter and histogram also split train/test. Convergence plot uses log y-axis.
- Auto-checkpointing: Engine saves emulators, diagnostics, and checkpoint after each wave by default. Configure with the
output_dir=andrun_name=arguments. Disable withoutput_dir=None - Resume from checkpoint:
engine.run(resume=True)loads the latest checkpoint and continues from where it left off - Parallel rejection sampling: the
n_jobs=nargument parallelizes NROY candidate filtering across CPU cores. Workers load emulators from disk — no GPU required. Also available per-call:engine.get_nroy_samples(10000, n_jobs=4) get_nroy_samples(n): Draw arbitrary number of NROY samples filtered through ALL emulators. Cheap — uses emulator predictions onlydrop_emulator_from_pending(feature): Selectively remove a poor emulator before committing a wave- Per-wave diagnostics: Auto-saved figures (predicted vs actual, convergence, NROY samples) in
wave{N}/{feature}/subdirectories
Improvements
- GPR emulator: Removed spurious bias column, data-informed initial hyperparameters, plain Softplus on noise variance (no artificial floor), don’t abort on optimizer
success=False - GPR diagnostics:
plot_predictions()uses observation CIs (includes noise) instead of latent-function CIs nroy_fraction: Per-wave fresh-LHS acceptance rate (replaces cumulativenon_implausible_fraction)- Random sampler: Fixed seed handling (
default_rng(seed)instead of ignorednp.random.seed) info()display:len()instead ofnp.size()for sample counts- Emulator quality metrics: Lazy
test()call + correct metric key lookup (emulator_metrics['R2']) - Column filtering: Engine filters to parameter-space columns before emulator training/prediction (metadata like
rand_seedis ignored)
API changes
IterationResult.non_implausible_pointsremoved — useengine.get_nroy_samples()IterationResult.non_implausible_fractionrenamed tonroy_fraction
Version 1.0.0 (2025) — tagged release (the complete v1)
New features
- Object-oriented API: New
HistoryMatchingclass for single-call workflow configuration and execution - Domain objects:
ParameterSpace,ObservationData,EmulatorBank, andIterationResultfor clean data management - Strategy pattern: Pluggable sampling strategies (LHS, grid, random), feature selection (auto, manual), and emulator types (linear, GLM, GPR)
- Interactive workflows: Step-by-step execution with
step()/commit_step()/revert_step() - Automatic workflows: Multi-iteration execution with
run()and convergence detection - Checkpoint/resume: Save and restore engine state for long-running workflows
- GPR with ARD: Gaussian Process Regression emulators with Automatic Relevance Determination lengthscales
- Auto feature selection: Fano factor-based automatic feature selection with correlation filtering
Improvements
- Replaced pyDOE2 with
scipy.stats.qmcfor Python 3.12+ compatibility - Reproducible LHS sampling via proper scipy seed propagation
- Added
setuptools<81pin for GPflow compatibility - Comprehensive test suite (188 tests)
- Six tutorial notebooks covering basic through advanced workflows
Removed
- Legacy procedural API (
Config,do_step,reduce_space) - Old
hm2package - Docker configuration
- Old DTK/radius/SIR examples