CLI Reference¶

The mach3sbi command-line tool is the main entry point for running simulations, training, and inference. For a higher level overview see getting started

mach3sbi¶

mach3sbi — simulation-based inference tools for MaCh3.

Run mach3sbi COMMAND --help for detailed usage of each subcommand.

mach3sbi [OPTIONS] COMMAND [ARGS]...

Options

--log-level <log_level>¶: Console logging level. One of DEBUG, INFO, WARNING, ERROR.

--log_file <log_file>¶: Optional path to write a plain-text log file.

create_prior¶

Generate a Prior from a simulator and save it to disk.

Instantiates the simulator, reads its parameter names, bounds, nominals, and covariance, then constructs and pickles a Prior object ready for use in training and inference.

Example:

mach3sbi create_prior \
    -m mypackage.simulator -s MySimulator \
    -c config.yaml -o prior.pkl

mach3sbi create_prior [OPTIONS]

Options

-o, --output_file <output_file>¶: Required Name of file to output to

-m, --simulator_module <simulator_module>¶: Required Dotted Python module path containing the simulator class (e.g. ‘mypackage.simulator’).

-s, --simulator_class <simulator_class>¶: Required Name of the simulator class within the module. Must implement SimulatorProtocol.

-c, --config <config>¶: Required Path to the simulator configuration file (e.g. a MaCh3 fitter YAML).

-p, --nuisance_pars <nuisance_pars>¶: Parameter name patterns (fnmatch-style, e.g. ‘syst_*’) to exclude from the prior and training.

--cyclical_pars, --cy <cyclical_pars>¶: Parameter name patterns (fnmatch-style) that should use a cyclical sinusoidal prior over [-2π, 2π].

--flipped_pars, --fl <flipped_pars>¶: Parameter name patterns (fnmatch-style) that should flip around 0

diagnostics¶

Run model diagnostics

mach3sbi diagnostics [OPTIONS]

Options

-o, --output_file <output_file>¶: Required Name of file to output to

-m, --simulator_module <simulator_module>¶: Required Dotted Python module path containing the simulator class (e.g. ‘mypackage.simulator’).

-s, --simulator_class <simulator_class>¶: Required Name of the simulator class within the module. Must implement SimulatorProtocol.

-c, --config <config>¶: Required Path to the simulator configuration file (e.g. a MaCh3 fitter YAML).

-p, --nuisance_pars <nuisance_pars>¶: Parameter name patterns (fnmatch-style, e.g. ‘syst_*’) to exclude from the prior and training.

--cyclical_pars, --cy <cyclical_pars>¶: Parameter name patterns (fnmatch-style) that should use a cyclical sinusoidal prior over [-2π, 2π].

--flipped_pars, --fl <flipped_pars>¶: Parameter name patterns (fnmatch-style) that should flip around 0

-i, --posterior <posterior>¶: Required Path to a saved density estimator checkpoint (.pt / .ckpt). The model architecture is read directly from the checkpoint — no architecture flags are needed.

-p, --nuisance_pars <nuisance_pars>¶

-cy, --cyclical_pars <cyclical_pars>¶

--make_sbc_rank¶

--make_expected_coverage¶

--make_tarp¶

--make_logl_comp¶

-n, --n_prior_samples <n_prior_samples>¶

--n_posterior_samples <n_posterior_samples>¶

importance-sample¶

Importance sample the posterior given observed data.

mach3sbi importance-sample [OPTIONS]

Options

-i, --posterior <posterior>¶: Required Path to a saved density estimator checkpoint (.pt / .ckpt). The model architecture is read directly from the checkpoint — no architecture flags are needed.

-n, --n_samples <n_samples>¶: Required Number of posterior samples to draw.

--oversampling_factor <oversampling_factor>¶: Oversampling rate.

--max-sampling-batch <max_sampling_batch>¶: Max sampling batch size.

-o, --output_file <output_file>¶: Required Name of file to output to

-m, --simulator_module <simulator_module>¶: Required Dotted Python module path containing the simulator class (e.g. ‘mypackage.simulator’).

-s, --simulator_class <simulator_class>¶: Required Name of the simulator class within the module. Must implement SimulatorProtocol.

-c, --config <config>¶: Required Path to the simulator configuration file (e.g. a MaCh3 fitter YAML).

-p, --nuisance_pars <nuisance_pars>¶: Parameter name patterns (fnmatch-style, e.g. ‘syst_*’) to exclude from the prior and training.

--cyclical_pars, --cy <cyclical_pars>¶: Parameter name patterns (fnmatch-style) that should use a cyclical sinusoidal prior over [-2π, 2π].

--flipped_pars, --fl <flipped_pars>¶: Parameter name patterns (fnmatch-style) that should flip around 0

inference¶

Sample the posterior distribution conditioned on observed data.

Loads a trained density estimator checkpoint, reads the model architecture directly from it (no --model / --hidden / etc. flags required), conditions the posterior on the observed data vector, draws --n_samples samples, and writes them as a parquet file with one column per parameter.

Example:

mach3sbi inference \
    -i models/best.pt -r prior.pkl \
    -n 100000 -o observed.parquet -s samples.parquet

mach3sbi inference [OPTIONS]

Options

-i, --posterior <posterior>¶: Required Path to a saved density estimator checkpoint (.pt / .ckpt). The model architecture is read directly from the checkpoint — no architecture flags are needed.

-o, --observed_data_file <observed_data_file>¶: Required Path to the observed data parquet file (produced by save_data).

-s, --save_file <save_file>¶: Required Where to save the posterior samples (parquet).

-r, --prior_path <prior_path>¶: Required Path to a saved Prior .pkl file.

-p, --nuisance_pars <nuisance_pars>¶: Parameter name patterns to exclude (must match those used during training).

-n, --n_samples <n_samples>¶: Required Number of posterior samples to draw.

save_data¶

Save observed data bins from the simulator to parquet.

mach3sbi save_data [OPTIONS]

Options

-o, --output_file <output_file>¶: Required Name of file to output to

-m, --simulator_module <simulator_module>¶: Required Dotted Python module path containing the simulator class (e.g. ‘mypackage.simulator’).

-s, --simulator_class <simulator_class>¶: Required Name of the simulator class within the module. Must implement SimulatorProtocol.

-c, --config <config>¶: Required Path to the simulator configuration file (e.g. a MaCh3 fitter YAML).

-p, --nuisance_pars <nuisance_pars>¶: Parameter name patterns (fnmatch-style, e.g. ‘syst_*’) to exclude from the prior and training.

--cyclical_pars, --cy <cyclical_pars>¶: Parameter name patterns (fnmatch-style) that should use a cyclical sinusoidal prior over [-2π, 2π].

--flipped_pars, --fl <flipped_pars>¶: Parameter name patterns (fnmatch-style) that should flip around 0

simulate¶

Draw samples from the prior and run the simulator for each.

Samples n_simulations parameter vectors θ from the prior, passes each through the simulator, applies Poisson smearing to the output, and saves the (θ, x) pairs as a feather file. Failed simulations are skipped with a warning.

Example:

mach3sbi simulate \
    -m mypackage.simulator -s MySimulator \
    -c config.yaml -n 100000 -o sims.feather

mach3sbi simulate [OPTIONS]

Options

-o, --output_file <output_file>¶: Required Name of file to output to

-m, --simulator_module <simulator_module>¶: Required Dotted Python module path containing the simulator class (e.g. ‘mypackage.simulator’).

-s, --simulator_class <simulator_class>¶: Required Name of the simulator class within the module. Must implement SimulatorProtocol.

-c, --config <config>¶: Required Path to the simulator configuration file (e.g. a MaCh3 fitter YAML).

-p, --nuisance_pars <nuisance_pars>¶: Parameter name patterns (fnmatch-style, e.g. ‘syst_*’) to exclude from the prior and training.

--cyclical_pars, --cy <cyclical_pars>¶: Parameter name patterns (fnmatch-style) that should use a cyclical sinusoidal prior over [-2π, 2π].

--flipped_pars, --fl <flipped_pars>¶: Parameter name patterns (fnmatch-style) that should flip around 0

-n, --n_simulations <n_simulations>¶: Required Number of simulation samples to generate.

-r, --prior_file <prior_file>¶: Optional path to also save the prior used for this run.

train¶

Train a Neural Posterior Estimation (NPE) density estimator.

Loads simulations from --dataset, builds an NPE model with the specified architecture, and trains it with a custom loop featuring linear warm-up, ReduceLROnPlateau scheduling, EMA-based early stopping, and periodic checkpointing.

The full model configuration (architecture + hyperparameters) is embedded in every checkpoint, so inference requires no architecture flags.

Example:

mach3sbi train \
    -r prior.pkl -d sims/ -s models/run.pt \
    --model maf --hidden 128 --transforms 8 \
    --max_epochs 50000 --stop_after_epochs 200

mach3sbi train [OPTIONS]

Options

-s, --save_file <save_file>¶: Required Base path for saving the model. Checkpoints are written relative to this.

-d, --dataset <dataset>¶: Required Path to folder of .feather simulation files.

-r, --prior_path <prior_path>¶: Required Path to a saved Prior .pkl file.

-p, --nuisance_pars <nuisance_pars>¶: Parameter name patterns (fnmatch-style) to exclude from training.

--model <model>¶

Density estimator architecture: ‘maf’ (Masked Autoregressive Flow) or ‘nse’ (Neural Spline Flow).

Default:: zuko_maf

--hidden <hidden>¶

Number of hidden units per layer.

Default:: 64

--num_blocks <num_blocks>¶

Number of residual blocks.

Default:: 2

--dropout <dropout>¶

Dropout probability applied during training.

Default:: 0.2

--transforms <transforms>¶

Number of autoregressive transforms (MAF only).

Default:: 5

--num_bins <num_bins>¶

Number of spline bins (NSF only).

Default:: 10

--batch_size <batch_size>¶

Number of samples per training batch.

Default:: 2048

--max_epochs <max_epochs>¶

Maximum number of training epochs.

Default:: 100000

--learning_rate <learning_rate>¶

Initial learning rate for the Adam optimiser.

Default:: 0.0005

--ema_alpha <ema_alpha>¶

Smoothing factor for the EMA of validation loss used in early stopping.

Default:: 0.01

--stop_after_epochs <stop_after_epochs>¶

Stop if EMA validation loss has not improved for this many epochs.

Default:: 50

--validation_fraction <validation_fraction>¶

Fraction of data held out for validation.

Default:: 0.1

--scheduler_patience <scheduler_patience>¶

Epochs without improvement before ReduceLROnPlateau halves the learning rate.

Default:: 20

--num_workers <num_workers>¶

Number of DataLoader worker processes.

Default:: 1

--use_amp¶: Enable automatic mixed precision (AMP). May not improve performance on all hardware.

--compile_model¶: Compile with torch.compile. Reduces per-step time on supported hardware but increases startup time.

--prune_model <prune_model>¶: Prune the model. This reduces the number of nodes dynamically but may compromise accuracy.

--autosave_every <autosave_every>¶

Save a periodic checkpoint every N epochs (best-model saves are always written).

Default:: 1

--resume_checkpoint <resume_checkpoint>¶: Path to a checkpoint file to resume training from.

--print_interval <print_interval>¶

Log training progress every N epochs.

Default:: 1

--tensorboard_dir <tensorboard_dir>¶: Directory for TensorBoard event files. Omit to disable TensorBoard logging.

--show_progress¶: Show two-level fit/epoch progress bars (works in CLI and Jupyter).