Simulator

MaCh3SBI tools provides utilities for getting priors and simulations directly from a simulator. For a high level overview of how to set up a simulator see getting started.

Prior

A set of classes which define a prior. Priors can either be flat (uniform), Gaussian or “cyclical”.

class Prior(prior_data, flat_msk=None, cyclical_parameters=None, nuisance_parameters=None)

Composite MaCh3 prior combining cyclical, flat, and Gaussian components.

Designed to replicate MaCh3’s prior construction (https://github.com/mach3-software/MaCh3) and satisfy the sbi Distribution interface.

Parameters are assigned to distributions in the following order:

• Cyclical — matched by cyclical_parameters (fnmatch patterns).

• Flat — flagged by flat_msk and not cyclical.

• Gaussian — everything else.

Nuisance parameters can be filtered at construction time or later via set_nuisance_filter(), without modifying the underlying data.

Parameters:

• prior_data (PriorData)

• flat_msk (list[bool] | None)

• cyclical_parameters (list[str] | None)

• nuisance_parameters (list[str] | None)

property prior_data: PriorData

Active PriorData after applying the nuisance filter.

property mean: Tensor

Prior mean — the nominal parameter values.

property n_params: int

Number of active (non-nuisance) parameters.

property variance: Tensor

Per-parameter prior variance, assembled from all sub-distributions.

property support

Independent interval support defined by the parameter bounds.

set_nuisance_filter(nuisance_patterns=None)

Update the nuisance parameter filter.

Parameters matching any of nuisance_patterns (fnmatch-style) are excluded from sampling and density evaluation. Call with None to reset and include all parameters.

Parameters:

nuisance_patterns (list[str] | None) – fnmatch patterns (e.g. ['syst_*']), or None to clear the filter.

Return type:

None

sample(sample_shape=())

Draw samples from the composite prior.

Parameters:

sample_shape – Batch shape, e.g. torch.Size([1000]).

Return type:

Tensor

Returns:

Tensor of shape (*sample_shape, n_params).

rsample(sample_shape=())

Draw reparameterised samples (where supported by sub-distributions).

Parameters:

sample_shape – Batch shape.

Return type:

Tensor

Returns:

Tensor of shape (*sample_shape, n_params).

check_bounds(params)

Check whether each sample in params lies within the prior bounds.

Parameters:

params (Tensor) – Tensor of shape (n_samples, n_params).

Return type:

Tensor

Returns:

Boolean tensor of shape (n_samples,).

save(output_path)

Pickle the prior to output_path.

Parameters:

output_path (Path) – Destination file path. Parent directories are created automatically.

Return type:

None

to(device)

Move all tensors to device in-place.

Parameters:

device (device) – Target PyTorch device.

Return type:

Prior

Returns:

self, for chaining.

create_prior(simulator_instance, nuisance_pars=None, cyclical_pars=None)

Convenience function to build a Prior from a simulator instance.

Reads all parameter metadata from simulator_instance and constructs the appropriate composite prior. Warns about parameters with unusually wide bounds (>10σ).

prior = create_prior(simulator, nuisance_pars=["syst_*"], cyclical_pars=["angle"])
prior.save(Path("prior.pkl"))

Parameters:

• simulator_instance (SimulatorProtocol) – An object implementing SimulatorProtocol.

• nuisance_pars (list[str] | None) – fnmatch patterns for parameters to exclude from the prior (e.g. ['syst_*']).

• cyclical_pars (list[str] | None) – fnmatch patterns for parameters that should use a cyclical sinusoidal prior over [-2π, 2π].

Return type:

Prior

Returns:

Configured Prior ready for use with sbi.

load_prior(prior_path, device=device(type='cpu'))

Load a pickled Prior from disk.

prior = load_prior(Path("prior.pkl"))

Parameters:

• prior_path (Path) – Path to a .pkl file produced by Prior.save().

• device – Device to move the prior to after loading. Defaults to CPU.

Return type:

Prior

Returns:

The loaded Prior.

Raises:

PriorNotFound – If prior_path does not exist or does not contain a valid Prior.

Cyclical Distribution

A custom distribution for handling cyclical parameters. This uses a prior of

\[\begin{split}p(\theta) = \begin{cases} \frac{1}{2\pi}\sin^{2}\left[\frac{1}{4}(\theta+2\pi) \right] & \mathrm{if}\ \ -2\pi\le \theta\le 2\pi \\ 0 & \mathrm{otherwise} \end{cases}\end{split}\]

Pictorially, the prior is

This allows the SBI to learn far the distribution better than simply having the distribution cycle at \(\pm \pi\). Post-fit this can be wrapped back around to the range \(\pm \pi\),

class CyclicalDistribution(nominals, lower_bounds, upper_bounds)

Sinusoidal prior for cyclical (periodic) parameters over [-2π, 2π].

The probability density function is:

\[p(\theta) = \frac{1}{2\pi} \sin^2\!\left(\frac{\theta + 2\pi}{4}\right), \quad \theta \in [-2\pi,\, 2\pi]\]

Sampling uses inverse transform sampling via a precomputed CDF lookup table.

Note

Only bounds of exactly [-2π, 2π] are supported. Passing any other bounds raises NotImplementedError.

Parameters:

• nominals (Tensor)

• lower_bounds (Tensor)

• upper_bounds (Tensor)

property mean

Mean of the distribution (zero by symmetry).

property variance: Tensor

Variance of the distribution.

Computed analytically as \(\int p(x)\,x^2\,dx\) over [-2π, 2π].

pdf(theta)

Evaluate the probability density function at theta.

Parameters:

theta (Tensor) – Input tensor. Values outside [-2π, 2π] have zero density.

Return type:

Tensor

Returns:

PDF values, same shape as theta.

cdf(theta)

Evaluate the cumulative distribution function at theta.

Parameters:

theta (Tensor) – Input tensor.

Return type:

Tensor

Returns:

CDF values in [0, 1], same shape as theta.

log_prob(value)

Evaluate the log probability density at value.

Returns -inf for values outside [-2π, 2π].

Parameters:

value (Tensor) – Input tensor.

Return type:

Tensor

Returns:

Log-density values, same shape as value.

sample(sample_shape=())

Draw samples via inverse transform sampling.

Parameters:

sample_shape (Size | list[int] | tuple[int, ...]) – Desired batch shape. Pass torch.Size([n]) for n independent samples.

Return type:

Tensor

Returns:

Sampled tensor of shape (*sample_shape, event_size).

Simulator

class Simulator(module_name, class_name, config, nuisance_pars=None, cyclical_pars=None)

Wraps a SimulatorProtocol with prior construction and simulation utilities.

The simulator draws parameter vectors from the prior, passes each through the underlying simulator, and applies Poisson smearing to the output. Failed simulations are skipped with a warning.

Parameters:

• module_name (str)

• class_name (str)

• config (Path)

• nuisance_pars (list[str] | None)

• cyclical_pars (list[str] | None)

simulate(n_samples)

Draw n_samples from the prior and run the forward simulator.

Each successful simulation draws θ ~ prior, calls simulator.simulate(θ), then applies Poisson smearing x ~ Poisson(simulator_output). Samples that raise an exception are silently skipped.

Parameters:

n_samples (int) – Number of simulation attempts.

Return type:

tuple[ndarray[tuple[Any, ...], dtype[float32]], ndarray[tuple[Any, ...], dtype[float32]]]

Returns:

Tuple of (theta, x) arrays, each of length ≤ n_samples. Fewer samples are returned if any simulations failed.

save(file_path, theta, x, prior_path=None)

Save simulation outputs to a feather file.

Optionally also pickles the prior alongside the data.

Parameters:

• file_path (Path) – Destination .feather file path.

• theta (ndarray[tuple[Any, ...], dtype[float32]]) – Sampled parameter arrays, shape (n, n_params).

• x (ndarray[tuple[Any, ...], dtype[float32]]) – Simulated observable arrays, shape (n, n_bins).

• prior_path (Path | None) – If provided, the prior is also saved here as a .pkl file.

Return type:

None

save_data(file_path)

Save the observed data bins from the simulator to a parquet file.

Calls get_data_bins() and writes the result under the key "data". Useful for producing the observation vector x_o used during inference.

Parameters:

file_path (Path) – Destination .parquet file path. Parent directories are created automatically.

Return type:

None

get_simulator(module_name, class_name, config)

Dynamically import, validate, and instantiate a simulator.

The class is checked against SimulatorProtocol before instantiation. Equivalent to:

from <module_name> import <class_name>
return class_name(config)

# Example — loading a MaCh3 simulator
get_simulator("mypackage.simulator", "MySimulator", Path("fitter.yaml"))

Parameters:

• module_name (str) – Dotted Python module path (e.g. 'mypackage.simulator').

• class_name (str) – Name of the simulator class within the module.

• config (Path) – Path to the simulator configuration file.

Return type:

SimulatorProtocol

Returns:

An instantiated, protocol-validated simulator object.

Raises:

• SimulatorImportError – If the module or class cannot be found.

• SimulatorImplementationError – If the class does not satisfy SimulatorProtocol.

• SimulatorSetupError – If config does not exist on disk.

Simulator Protocol

class SimulatorProtocol(simulator_config)

Interface that every simulator must implement.

Simulators are configured via a single file path passed to __init__. For MaCh3 this is the fitter YAML config. All parameter-level methods operate over the full (un-filtered) parameter vector.

Parameters:

simulator_config (Path | str)

simulate(theta)

Run a single forward simulation.

Parameters:

theta (list[float]) – Input parameter vector.

Return type:

list[float]

Returns:

Predicted observable vector x.

get_parameter_names()

Return the name of each parameter in theta.

Return type:

list[str]

Returns:

Ordered list of parameter name strings.

get_parameter_bounds()

Return hard lower and upper bounds for each parameter.

Return type:

tuple[list[float], list[float]]

Returns:

Tuple of (lower_bounds, upper_bounds), each a list of floats with one entry per parameter.

get_is_flat(i)

Return whether parameter i should use a flat (uniform) prior.

Parameters:

i (int) – Zero-based parameter index.

Return type:

bool

Returns:

True if the parameter is flat, False for Gaussian.

get_data_bins()

Return the observed data bin values x_o.

Return type:

list[float]

Returns:

Observed data vector.

get_parameter_nominals()

Return the nominal (mean) value for each parameter.

Return type:

list[float]

Returns:

Ordered list of nominal values.

get_parameter_errors()

Return the 1σ error for each parameter.

Return type:

list[float]

Returns:

Ordered list of parameter errors.

get_covariance_matrix()

Return the full parameter covariance matrix.

Return type:

ndarray

Returns:

Square numpy array of shape (n_params, n_params).