autoemulate.calibration.history_matching

autoemulate.calibration.history_matching#

class HistoryMatching(observations, threshold=3.0, model_discrepancy=0.0, rank=1, device=None)[source]#

Bases: TorchDeviceMixin

History Matching class for model calibration.

History matching is a model calibration method, which uses observed data to rule out implausible parameter values. The implausibility metric is:

\[\begin{split}I_i(\bar{x_0}) = \frac{|z_i - \\mathbb{E}(f_i(\bar{x_0}))|} {\\sqrt{\text{Var}[z_i - \\mathbb{E}(f_i(\bar{x_0}))]}}\end{split}\]

Queried parameters above a given implausibility threshold are ruled out (RO) whereas all other parameters are marked as not ruled out yet (NROY).

get_nroy(implausibility, x=None)[source]#

Get indices of NROY points from implausibility scores.

If x is provided, returns parameter values at NROY indices.

Parameters:

  • implausibility (TensorLike) – Tensor of implausibility scores for tested input parameters.

  • x (Tensorlike | None) – Optional tensor of scored input parameters.

Returns:

Indices of NROY points or x parameters at NROY indices.

Return type:

TensorLike

get_ro(implausibility, x=None)[source]#

Get indices of RO points from implausibility scores.

If x is provided, returns parameter values at RO indices.

Parameters:

  • implausibility (TensorLike) – Tensor of implausibility scores for tested input parameters.

  • x (Tensorlike | None) – Optional tensor of scored iput parameters.

Returns:

Indices of RO points or x parameters at RO indices.

Return type:

TensorLike

calculate_implausibility(pred_means, pred_vars)[source]#

Calculate implausibility scores.

Parameters:

  • pred_means (TensorLike) – Tensor of prediction means [n_samples, n_outputs]

  • pred_vars (TensorLike) – Tensor of prediction variances [n_samples, n_outputs].

Returns:

Tensor of implausibility scores.

Return type:

TensorLike

static generate_param_bounds(nroy_x, buffer_ratio=0.05, param_names=None, min_samples=1)[source]#

Generate lower/upper parameter bounds as min/max of NROY samples.

Parameters:

  • nroy_x (TensorLike) – A tensor of NROY parameter samples [n_samples, n_inputs].

  • buffer_ratio (float) – A scaling factor used to expand the bounds of the (NROY) parameter space. It is applied as a ratio of the range (max_val - min_val) of each input parameter to create a buffer around the NROY minimum and maximum values.

  • param_names (list[str] | None) – Optional list of parameter names. If None, uses default [“x1”, …, “xn”].

  • min_samples (int) – Minimum number of samples needed to generate new bounds.

Returns:

The generated [lower, upper] parameter bounds. Returns None if there are not enough samples to generate bounds from.

Return type:

dict[str, [float, float]] | None

class HistoryMatchingWorkflow(simulator, emulator, observations, threshold=3.0, model_discrepancy=0.0, rank=1, train_x=None, train_y=None, device=None, random_seed=None)[source]#

Bases: HistoryMatching

History Matching Workflow class.

Run history matching workflow: - sample parameter values to test from the current NROY parameter space - use emulator to rule out implausible parameters and update NROY space - make predictions for a subset the NROY parameters using the simulator - refit the emulator using the simulated data

generate_samples(n)[source]#

Generate parameter samples and evaluate implausibility.

Draw n samples from the simulator min/max parameter bounds and evaluate implausability given emulator predictions.

Parameters:

n (int) – The number of parameter samples to generate.

Returns:

A tensor of tested input parameters and their implausability scores.

Return type:

tuple[TensorLike, TensorLike]

update_simulator_bounds(nroy_x, buffer_ratio=0.05)[source]#

Update simulator parameter bounds to min/max of NROY parameter samples.

Parameters:

  • nroy_x (TensorLike) – A tensor of NROY parameter samples [n_samples, n_inputs]

  • buffer_ratio (float) – A scaling factor used to expand the bounds of the (NROY) parameter space. It is applied as a ratio of the range (max_val - min_val) of each input parameter to create a buffer around the NROY minimum and maximum values.

sample_tensor(n, x)[source]#

Randomly sample n rows from x.

Parameters:

  • n (int) – The number of samples to draw.

  • x (TensorLike) – The tensor to sample from.

Returns:

A tensor of samples with n rows.

Return type:

TensorLike

simulate(x)[source]#

Simulate x parameter inputs and filter out failed simulations.

Parameters:

x (TensorLike) – A tensor of parameters to simulate [n_samples, n_inputs].

Returns:

Tensors of succesfully simulated input parameters and predictions.

Return type:

tuple[TensorLike, TensorLike]

run(n_simulations=100, n_test_samples=10000, max_retries=3, buffer_ratio=0.0)[source]#

Run a wave of the history matching workflow.

Parameters:

  • n_simulations (int) – The number of simulations to run.

  • n_test_samples (int) – Number of input parameters to test for implausibility with the emulator. Parameters to simulate are sampled from this NROY subset.

  • max_retries (int) –

    Maximum number of times to try to generate n_simulations NROY parameters. That is the maximum number of times to repeat the following steps:

    • draw n_test_samples parameters

    • use emulator to make predictions for those parameters

    • score implausability of parameters given predictions

    • identify NROY parameters within this set

  • buffer_ratio (float) – A scaling factor used to expand the bounds of the (NROY) parameter space. It is applied as a ratio of the range (max_val - min_val) of each input parameter to create a buffer around the NROY minimum and maximum values when updating the simulator parameter bounds.

Returns:

A tensor of tested input parameters and their implausibility scores from which simulation samples were then selected.

Return type:

tuple[TensorLike, TensorLike]

Contents