autoemulate.simulations.base

class Simulator(parameters_range, output_names, log_level='progress_bar')

Bases: ABC, ValidationMixin

Base class for simulations. All simulators should inherit from this class.

This class provides the interface and common functionality for different simulation implementations.

classmethod simulator_name()

Get the name of the simulator class.

property parameters_range

Dictionary mapping input parameter names to their (min, max) ranges.

property param_names

List of parameter names.

property param_bounds

List of parameter bounds.

property output_names

List of output parameter names.

property in_dim

Input dimensionality.

property out_dim

Output dimensionality.

sample_inputs(n_samples, random_seed=None, method='lhs')

Generate random samples using Quasi-Monte Carlo methods.

Available methods are Sobol or Latin Hypercube Sampling. For overview, see the scipy documentation: https://docs.scipy.org/doc/scipy/reference/stats.qmc.html

Parameters:

• n_samples (int) – Number of samples to generate.

• random_seed (int | None) – Random seed for reproducibility. If None, no seed is set.

• method (str) – Sampling method to use. One of [“lhs”, “sobol”].

Returns:

Parameter samples (column order is given by self.param_names)

Return type:

TensorLike

forward(x, allow_failures=True)

Generate samples from input data using the simulator.

Combines the abstract method _forward with some validation checks. If there is a failure during the forward pass of the simulation, the error is logged and None is returned.

Parameters:

• x (TensorLike) – Input tensor of shape (n_samples, self.in_dim).

• allow_failures (bool) – Whether to allow failures during simulation. Default is True. When true, failed simulations will return None instead of raising an error. When False, error is raised.

Returns:

Simulated output tensor. None if the simulation failed.

Return type:

TensorLike

forward_batch(x, allow_failures=True)

Run multiple simulations.

If allow_failures is False, failed simulations will raise an error. Otherwise, failed simulations are skipped, and only successful results are returned along with their corresponding input parameters.

Parameters:

• x (TensorLike) – Tensor of input parameters to make predictions for.

• allow_failures (bool) – Whether to allow failures during simulation. Default is True. When true, failed simulations will return None instead of raising an error. When False, error is raised.

Returns:

Tuple of (simulation_results, valid_input_parameters). Only successful simulations are included.

Return type:

tuple[TensorLike, TensorLike]

get_parameter_idx(name)

Get the index of a specific parameter.

Parameters:

name (str) – Name of the parameter to retrieve.

Returns:

Index of the specified parameter.

Return type:

float

get_outputs_as_dict()

Return simulation results as a dictionary with output names as keys.

Returns:

Dictionary where keys are output names and values are tensors of shape (n_samples,) for each output dimension.

Return type:

dict[str, TensorLike]

class TorchSimulator(parameters_range, output_names, log_level='progress_bar', device=None)

Bases: Simulator, TorchDeviceMixin

Simulator that runs computations on a specified torch device.

This subclass extends Simulator with the TorchDeviceMixin so that simulators implemented in PyTorch (e.g., torchcor) can run on CPU or accelerator hardware. Inputs are moved to self.device before the forward pass and the resulting tensors are kept on the same device.

sample_inputs(n_samples, random_seed=None, method='lhs')

Sample inputs and move them to the simulator’s device.

Parameters:

• n_samples (int) – Number of samples to generate.

• random_seed (int | None) – Optional random seed to make sampling reproducible.

• method (str) – Sampling method, one of "lhs" or "sobol".

Returns:

Sampled inputs located on self.device.

Return type:

TensorLike

forward(x, allow_failures=True)

Run a single simulation on the configured device.

Parameters:

• x (TensorLike) – Input tensor with shape (n_samples, in_dim).

• allow_failures (bool) – When True, failures return None instead of raising.

Returns:

Simulation result on self.device or None on failure.

Return type:

TensorLike | None

forward_batch(x, allow_failures=True)

Run a batch of simulations with device management.

Parameters:

• x (TensorLike) – Batch of inputs with shape (batch_size, in_dim).

• allow_failures (bool) – Whether to skip failures (True) or raise immediately (False).

Returns:

Tuple of (results, valid_inputs) residing on self.device.

Return type:

tuple[TensorLike, TensorLike]