Skip to main content

nroy_sampling

nroy_sampling

NROY sampling pipeline inspired by the hmer R package.

Provides two methods for generating non-implausible parameter samples: - ‘lhs’: Pure LHS rejection sampling (simple, can be slow at low acceptance) - ‘ray_resample’: 4-stage pipeline (LHS → ray sampling → importance sampling → maximin thinning) that efficiently explores small NROY regions

To test points you supply (a known truth, a uniform or Sobol design, MCMC proposals), use HistoryMatching.in_nroy(), and HistoryMatching.implausibility() to see which wave and target ruled a point out. Both apply the same test as generate_nroy_design. nroy_mask is that test as a function of an emulator bank, for use without the engine, for example when filtering candidates in chunks on worker processes.

Reference: Iskauskas (2024), “Emulation and History Matching using the hmer Package”, Journal of Statistical Software.

Classes

Name Description
NROYResult Container for NROY sampling results with stats.

NROYResult

nroy_sampling.NROYResult(samples, lhs_accepted, lhs_tested)

Container for NROY sampling results with stats.

Functions

Name Description
generate_nroy_design Generate NROY parameter samples filtered through all emulators.
nroy_mask Boolean mask of candidates that pass every emulator in the bank.

generate_nroy_design

nroy_sampling.generate_nroy_design(
    n_points,
    parameter_space,
    emulator_bank,
    observations,
    threshold=3.5,
    sampling_strategy=None,
    method='auto',
    seed=None,
    lhs_factor=10,
    n_lines=20,
    points_per_line=50,
    imp_scale=1.0,
    imp_target_rate=(0.1, 0.225),
    imp_batch_size=1000,
    imp_max_batches=200,
    lhs_fallback_rate=0.1,
    maximin_reps=1000,
    max_candidates=4000000,
)

Generate NROY parameter samples filtered through all emulators.

Parameters

n_points : int Target number of NROY samples to return. parameter_space : ParameterSpace Bounds for each parameter. emulator_bank : EmulatorBank All trained emulators (across waves) used for filtering. observations : ObservationData Target values and uncertainties. threshold : float Implausibility threshold (default 3.5). sampling_strategy : SamplingStrategy, optional Strategy for generating initial LHS candidates. Defaults to LHS maximin. method : str 'auto' (default) runs LHS rejection and escalates to the ray + importance-sampling pipeline only if LHS underfills; 'lhs' does pure rejection sampling; 'ray' seeds with a small LHS draw then goes straight to ray + importance sampling. seed : int, optional Random seed for reproducibility.

Returns

pd.DataFrame Up to n_points rows of NROY parameter samples.

nroy_mask

nroy_sampling.nroy_mask(
    candidates,
    emulator_bank,
    observations,
    threshold,
    param_cols,
    mask=None,
)

Boolean mask of candidates that pass every emulator in the bank.

Emulators are applied oldest wave first with short-circuit evaluation: a candidate that fails one emulator is not tested against the rest. The early waves’ emulators were trained over the whole box and reject most far-away points, so this order evaluates far fewer points than newest first (#279); the mask doesn’t depend on the order. This is the single definition of NROY membership used by generate_nroy_design and by HistoryMatching.in_nroy.

An emulator that implements predict_bounds, such as BayesLinear, is screened first: a point is ruled out if it is implausible even with its mean at the edge of the tolerance nearest the target and its variance at the upper bound, and ruled in if it is plausible even with its mean at the far edge and its variance at the lower bound. Only the points in between go through predict. Because predict’s mean and variance always lie within the bounds, and the screen keeps a relative margin of 1e-9 for rounding, the mask is the same as calling predict on every point. (That mask can itself depend, at the level of rounding, on how candidates are batched, since BLAS results for one row can depend on the other rows; screening adds nothing beyond that.) Other emulators go through predict for every point.

Parameters

Name Type Description Default
candidates pd.DataFrame Parameter samples, one row per point. required
emulator_bank EmulatorBank Trained emulators, by iteration and feature. required
observations ObservationData Targets the emulators are compared against. required
threshold float Implausibility cut-off. required
param_cols list Parameter columns passed to the emulators. required
mask Optional[np.ndarray] Optional starting mask; only rows already True are tested. None

Returns

Name Type Description
np.ndarray Array of shape (len(candidates),), True where a point is not ruled
np.ndarray out.

Raises

Name Type Description
RuntimeError An emulator failed to predict on the candidates.