autosim.simulations.base

Base simulator interfaces and batching helpers.

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.

Parameters:

• parameters_range (dict[str, tuple[float, float]])

• output_names (list[str])

• log_level (str)

classmethod simulator_name()

Get the name of the simulator class.

Return type:

str

property parameters_range: dict[str, tuple[float, float]]

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

property param_names: list[str]

List of parameter names.

property param_bounds: list[tuple[float, float]]

List of parameter bounds.

property output_names: list[str]

List of output parameter names.

property in_dim: int

Input dimensionality.

property out_dim: int

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:

Tensor

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 (Tensor) – 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:

Tensor | None

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 (Tensor) – 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[Tensor, Tensor]

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:

int

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, Tensor]

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.

Parameters:

• parameters_range (dict[str, tuple[float, float]])

• output_names (list[str])

• log_level (str)

• device (str | device | None)

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:

Tensor

forward(x, allow_failures=True)

Run a single simulation on the configured device.

Parameters:

• x (Tensor) – 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:

Tensor | None

forward_batch(x, allow_failures=True)

Run a batch of simulations with device management.

Parameters:

• x (Tensor) – 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[Tensor, Tensor]

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

Bases: Simulator, ABC

Base class for simulators that output spatiotemporal data.

This class extends the base Simulator with additional functionality for handling spatiotemporal outputs, such as reshaping to spatiotemporal format and returning constant fields.

Parameters:

• parameters_range (dict[str, tuple[float, float]])

• output_names (list[str])

• log_level (str)

abstract forward_samples_spatiotemporal(n, random_seed=None, ensure_exact_n=False)

Generate spatiotemporal samples from the simulator.

Parameters:

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

• random_seed (int | None) – Random seed for reproducibility. Defaults to None.

• ensure_exact_n (bool) – When True, retry failed simulations until exactly n successful samples are collected. Defaults to False.

Returns:

A dictionary containing the reshaped spatiotemporal data, constant scalars, and constant fields.

Return type:

dict