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)[source]

The calibration method abstract class.

analyze() → CalibrationMethodBase[source]

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[source]

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][source]

Getter method for the artifact list.

Returns:: The calibration workflow artifact list.
Return type:: list[str]

get_engines(as_string: bool = False) → list | str[source]

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[source]

Get the estimated parameter values, and potentially their uncertainties.

Returns:: The estimated parameter values.
Return type:: ParameterEstimatesModel

specify() → CalibrationMethodBase[source]

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)[source]

The calibration workflow abstract class.

add_parameter_estimate(estimate: ParameterEstimateModel) → None[source]

Add a parameter estimate to the set of estimates.

Parameters:: estimate (ParameterEstimateModel) – The parameter estimate.

abstract analyze() → None[source]

Analyze the results of the simulation calibration procedure.

Raises:: NotImplementedError – Error raised for the unimplemented abstract method.

append_artifact(artifact: str) → None[source]

Add a new artifact to the artifacts list.

Parameters:: artifact (str) – The artifact to append.

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[source]

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

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[source]

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[source]

Execute the simulation calibration procedure.

Raises:: NotImplementedError – Error raised for the unimplemented abstract method.

extend_X(X: ndarray, Y_rows: int) → ndarray[source]

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

get_artifacts() → list[str][source]

Getter method for the artifact list.

Returns:: The calibration workflow artifact list.
Return type:: list[str]

get_calibration_func_kwargs() → dict[source]

Get the calibration function named arguments.

Returns:: The calibration function named arguments.
Return type:: dict

get_default_rng(random_seed: int | None = None) → Generator[source]

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[source]

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][source]

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[source]

Get the estimated parameter values, and potentially their uncertainties.

Returns:: The estimated parameter values.
Return type:: ParameterEstimatesModel

get_simulation_uuid() → str[source]

Get a new simulation uuid.

Returns:: The simulation uuid.
Return type:: str

join(*paths: str) → str[source]

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[source]

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[source]: Posthook to run after analyze().

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[source]: Posthook to run after execute().

posthook_specify() → None[source]: Posthook to run after specify().

prehook_analyze() → None[source]: 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[source]

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[source]: Prehook to run before execute().

prehook_specify() → None[source]: Prehook to run before specify().

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

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[source]

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[source]

Set the simulation output labels from output data.

Parameters:: Y (np.ndarray) – The simulation outputs.

abstract specify() → None[source]

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[source]

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[source]

The example simulation model abstract class.

abstract get_observed_data() → ndarray | DataFrame[source]

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[source]

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)[source]

The Emukit base class.

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

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[source]: 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)[source]

The history matching base class.

specify() → None[source]: 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)[source]

The OpenTurns base class.

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

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[source]

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[source]

Get new parameter samples.

Parameters:: n_samples (int) – The number of samples.
Returns:: The parameter samples.
Return type:: np.ndarray

specify() → None[source]: 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)[source]

The simulation-based inference base class.

specify() → None[source]: 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)[source]

The surrogate modelling base class.

sample_parameters(n_samples: int) → ndarray[source]

Sample from the paramete space.

Parameters:: n_samples (int) – The number of samples.
Returns:: The sampled parameter values.
Return type:: np.ndarray

specify() → None[source]: Specify the parameters of the model calibration procedure.