Base

Calibration

Contains base classes for the various calibration methods

Abstract base classes are defined for the simulation calibration procedures.

class calisim.base.calibration_base.CalibrationMethodBase(calibration_func: Callable, specification: CalibrationModel, task: str, engine: str, implementations: dict[str, type[CalibrationWorkflowBase]], implementation: CalibrationWorkflowBase | None = None)

The calibration method abstract class.

analyze() → CalibrationMethodBase

Analyze the results of the simulation calibration procedure.

Raises:

ValueError – Error raised when the implementation is not set.

Returns:

The calibration method.

Return type:

CalibrationMethodBase

execute() → CalibrationMethodBase

Execute the simulation calibration procedure.

Raises:

ValueError – Error raised when the implementation is not set.

Returns:

The calibration method.

Return type:

CalibrationMethodBase

get_artifacts() → list[str]

Getter method for the artifact list.

Returns:

The calibration workflow artifact list.

Return type:

list[str]

get_engines(as_string: bool = False) → list | str

Get a list of supported engines.

Parameters:

as_string (bool, optional) – Whether to return the engine list as a string. Defaults to False.

Returns:

The list of supported engines.

Return type:

list | str

get_parameter_estimates() → ParameterEstimatesModel

Get the estimated parameter values, and potentially their uncertainties.

Returns:

The estimated parameter values.

Return type:

ParameterEstimatesModel

specify() → CalibrationMethodBase

Specify the parameters of the model calibration procedure.

Raises:

ValueError – Error raised when the implementation is not set.

Returns:

The calibration method.

Return type:

CalibrationMethodBase

class calisim.base.calibration_base.CalibrationWorkflowBase(calibration_func: Callable, specification: CalibrationModel, task: str)

The calibration workflow abstract class.

add_parameter_estimate(estimate: ParameterEstimateModel) → None

Add a parameter estimate to the set of estimates.

Parameters:

estimate (ParameterEstimateModel) – The parameter estimate.

abstract analyze() → None

Analyze the results of the simulation calibration procedure.

Raises:

NotImplementedError – Error raised for the unimplemented abstract method.

append_artifact(artifact: str) → None

Add a new artifact to the artifacts list.

Parameters:

artifact (str) – The artifact to append.

calc_uncertainty_calibration_metric(metric: str, mu: ndarray, sigma: ndarray, Y: ndarray, recal_model: BaseEstimator | None = None) → float

Calculate predictive uncertainty calibration metrics.

Parameters:

• metric (str) – The metric name.

• mu (np.ndarray) – The conditional mean predictions.

• sigma (np.ndarray) – The conditional predicted standard deviations.

• Y (np.ndarray) – The simulation output data.

• recal_model (BaseEstimator | None, optional) – The prediction recalibrator. Defaults to None.

Returns:

The uncertainty calibration metric.

Return type:

float

calculate_shap_importances(X: ndarray, emulator: BaseEstimator, names: list[str], test_size: float = 0, outfile: str | None = None) → None

Calculate SHAP importances using Kernel SHAP.

Parameters:

• X (np.ndarray) – The training data.

• emulator (BaseEstimator) – The surrogate model.

• names (list[str]) – The parameter names.

• test_size (float, optional) – The test dataset size. Defaults to 0.

• outfile (str | None, optional) – The output file. Defaults to None.

calibration_func_wrapper(X: ndarray, workflow: CalibrationWorkflowBase, observed_data: DataFrame | ndarray, parameter_names: list[str], data_types: list[ParameterDataType], calibration_kwargs: dict, wrap_values: bool = False) → ndarray

Wrapper function for the calibration function.

Parameters:

• X (np.ndarray) – The parameter set matrix.

• workflow (CalibrationWorkflowBase) – The calibration workflow.

• observed_data (pd.DataFrame | np.ndarray) – The observed data.

• parameter_names (list[str]) – The list of simulation parameter names.

• data_types (list[ParameterDataType]) – The data types for each parameter.

• calibration_kwargs (dict) – Arguments to supply to the calibration function.

• wrap_values (bool) – Whether to wrap scalar values with a list. Defaults to False.

Returns:

The simulation output data.

Return type:

np.ndarray

call_calibration_func(parameters: dict | list[dict], simulation_id: str | list[str], observed_data: ndarray | None, **method_kwargs: dict) → float | list[float] | ndarray | DataFrame

Wrapper method for the calibration function.

Parameters:

• results (np.ndarray | pd.DataFrame | float) – The simulation results.

• parameters (dict | List[dict]) – The simulation parameters.

• simulation_id (str | List[str]) – The simulation IDs.

• observed_data (np.ndarray | None) – The observed data.

Returns:

The

calibration function results.

Return type:

float | list[float] | np.ndarray | pd.DataFrame

create_file_path(file_path: str) → str

Create file path if it does not exist.

Parameters:

file_path (str) – The file path to create.

Returns:

The created file path.

Return type:

str

abstract execute() → None

Execute the simulation calibration procedure.

Raises:

NotImplementedError – Error raised for the unimplemented abstract method.

extend_X(X: ndarray, Y_rows: int) → ndarray

Extend the number of rows for X with a dummy index column.

Parameters:

• X (np.ndarray) – The input matrix.

• Y_rows (int)

Returns:

The extended input matrix with a dummy column.

Return type:

np.ndarray

fit_recalibrator(emulator: BaseEstimator, mu: ndarray, sigma: ndarray, y: ndarray) → None

Fit a model recalibrator using Isotonic regression.

Parameters:

• emulator (BaseEstimator) – The surrogate model.

• mu (np.ndarray) – The conditional mean predictions.

• sigma (np.ndarray) – The conditional predicted standard deviations.

• Y (np.ndarray) – The simulation output data.

get_artifacts() → list[str]

Getter method for the artifact list.

Returns:

The calibration workflow artifact list.

Return type:

list[str]

get_calibration_func_kwargs() → dict

Get the calibration function named arguments.

Returns:

The calibration function named arguments.

Return type:

dict

get_default_rng(random_seed: int | None = None) → Generator

Get a numpy random number generator.

Parameters:

random_seed (int | None, optional) – The random seed. Defaults to None.

Returns:

The random number generator.

Return type:

np.random.Generator

get_full_factorial_design(parameter_spec: ParameterSpecification | None = None) → ndarray

Get a full factorial design from a parameter specification.

Parameters:

parameter_spec (ParameterSpecification | None, optional) – The simulation parameter specification. Defaults to None.

Returns:

The full factorial design.

Return type:

np.ndarray

get_parameter_bounds(spec: DistributionModel) → tuple[float, float]

Get the lower and upper bounds from a parameter specification.

Parameters:

spec (DistributionModel) – The parameter specification.

Raises:

ValueError – Error raised when the bounds cannot be identified.

Returns:

The lower and upper bounds.

Return type:

tuple[float, float]

get_parameter_estimates() → ParameterEstimatesModel

Get the estimated parameter values, and potentially their uncertainties.

Returns:

The estimated parameter values.

Return type:

ParameterEstimatesModel

get_simulation_uuid() → str

Get a new simulation uuid.

Returns:

The simulation uuid.

Return type:

str

join(*paths: str) → str

Join file paths.

Parameters:

paths (str) – The file paths.

Returns:

The joined file paths.

Return type:

str

plot_simulated_vs_observed(simulated_data: ndarray, observed_data: ndarray, outdir: str, time_now: str, task: str, experiment_name: str, label: str = '') → None

Plot simulated data against observed data.

Parameters:

• simulated_data (np.ndarray) – The simulated data.

• observed_data (np.ndarray) – The observed data.

• outdir (str) – The output directory.

• time_now (str) – The current time.

• task (str) – The calibration task.

• experiment_name (str) – The experiment name.

• label (str, optional) – The plot axes label. Defaults to “”.

posthook_analyze() → None

Posthook to run after analyze().

posthook_calibration_func(results: ndarray | DataFrame | float, parameters: dict | list[dict], simulation_id: str | list[str], observed_data: ndarray | None, **method_kwargs: dict) → tuple

Posthook to run after calling the calibration function

Parameters:

• results (np.ndarray | pd.DataFrame | float) – The simulation results.

• parameters (dict | List[dict]) – The simulation parameters.

• simulation_id (str | List[str]) – The simulation IDs.

• observed_data (np.ndarray | None) – The observed data.

Returns:

The calibration function results and parameters.

Return type:

tuple

posthook_execute() → None

Posthook to run after execute().

posthook_specify() → None

Posthook to run after specify().

prehook_analyze() → None

Prehook to run before analyze().

prehook_calibration_func(parameters: dict | list[dict], simulation_id: str | list[str], observed_data: ndarray | None, **method_kwargs: dict) → tuple

Prehook to run before calling the calibration function

Parameters:

• parameters (dict | List[dict]) – The simulation parameters.

• simulation_id (str | List[str]) – The simulation IDs.

• observed_data (np.ndarray | None) – The observed data.

Returns:

The calibration function parameters.

Return type:

tuple

prehook_execute() → None

Prehook to run before execute().

prehook_specify() → None

Prehook to run before specify().

prepare_analyze() → tuple[str, str, str, str | None]

Perform preparations for the analyze step.

Returns:

A list of

metadata needed for the analysis outputs.

Return type:

tuple[str, str, str, str | None]

present_fig(fig: Figure, outdir: str | None, time_now: str, task: str, experiment_name: str, suffix: str) → None

Present the figure by showing or writing to file.

Parameters:

• fig (Figure) – The matplotlib figure.

• outdir (str | None) – The image output directory.

• time_now (str) – The current time.

• task (str) – The current calibration task.

• suffix (str) – The file name suffix.

set_output_labels_from_Y(Y: ndarray) → None

Set the simulation output labels from output data.

Parameters:

Y (np.ndarray) – The simulation outputs.

abstract specify() → None

Specify the parameters of the model calibration procedure.

Raises:

NotImplementedError – Error raised for the unimplemented abstract method.

calisim.base.calibration_base.pre_post_hooks(f: Callable) → Callable

Execute prehooks and posthooks for calibration methods.

Parameters:

f (Callable) – The wrapped function.

Returns:

The wrapper function.

Return type:

Callable

Example Model

Contains base classes for various example models

Abstract base classes are defined for the example simulation models.

class calisim.base.example_model_base.ExampleModelBase

The example simulation model abstract class.

abstract get_observed_data() → ndarray | DataFrame

Retrieve observed data.

Raises:

NotImplementedError – Error raised for the unimplemented abstract method.

Returns:

The observed data.

Return type:

np.ndarray | pd.DataFrame

abstract simulate(parameters: dict) → ndarray | DataFrame

Run the simulation.

Args: parameters (dict): The simulation parameters.

Raises:

NotImplementedError: Error raised for the

unimplemented abstract method.

Returns:

The simulated data.

Return type:

np.ndarray | pd.DataFrame

Emukit

Contains the Emukit base class

The defined base class for the Emukit library.

class calisim.base.emukit_base.EmukitBase(calibration_func: Callable, specification: CalibrationModel, task: str)

The Emukit base class.

get_X_Y(n_init: int, target_function: Callable) → tuple[ndarray, ndarray]

Get the X and Y matrices.

Parameters:

• n_init (int) – The number of samples to take from the random design.

• target_function (Callable) – The simulation function.

Returns:

The X and Y matrices.

Return type:

tuple[np.ndarray, np.ndarray]

specify() → None

Specify the parameters of the model calibration procedure.

History Matching

Contains the history matching base class

The defined base class for performing history matching.

class calisim.base.history_matching_base.HistoryMatchingBase(calibration_func: Callable, specification: CalibrationModel, task: str)

The history matching base class.

specify() → None

Specify the parameters of the model calibration procedure.

OpenTurns

Contains the OpenTurns base class

The defined base class for performing OpenTurns.

class calisim.base.openturns_base.OpenTurnsBase(calibration_func: Callable, specification: CalibrationModel, task: str)

The OpenTurns base class.

get_X_Y(n_samples: int, target_function: Callable) → tuple[ndarray, ndarray]

Get the X and Y matrices.

Parameters:

• n_samples (int) – The number of samples to take from the random design.

• target_function (Callable) – The simulation function.

Returns:

The X and Y matrices.

Return type:

tuple[np.ndarray, np.ndarray]

get_ot_func_wrapper(func_sample: Callable) → Callable

Get an OpenTurns wrapper for Python functions.

Parameters:

func_sample (Callable) – The function to wrap.

Returns:

The wrapped function.

Return type:

Callable

sample_parameters(n_samples: int) → ndarray

Get new parameter samples.

Parameters:

n_samples (int) – The number of samples.

Returns:

The parameter samples.

Return type:

np.ndarray

specify() → None

Specify the parameters of the model calibration procedure.

Simulation-Based Inference

Contains the simulation-based inference base class

The defined base class for performing simulation-based inference.

class calisim.base.sbi_base.SimulationBasedInferenceBase(calibration_func: Callable, specification: CalibrationModel, task: str)

The simulation-based inference base class.

specify() → None

Specify the parameters of the model calibration procedure.

Surrogate Modelling

Contains the surrogate modelling base class

The defined base class for surrogate modelling.

class calisim.base.surrogate_base.SurrogateBase(calibration_func: Callable, specification: CalibrationModel, task: str)

The surrogate modelling base class.

sample_parameters(n_samples: int) → ndarray

Sample from the paramete space.

Parameters:

n_samples (int) – The number of samples.

Returns:

The sampled parameter values.

Return type:

np.ndarray

specify() → None

Specify the parameters of the model calibration procedure.