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

-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).

-o, --output_file <output_file>

Path to write the output file.

-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π].

inference

Sample the posterior distribution conditioned on observed data.

Loads a trained density estimator, conditions it on the observed data vector from --observed_data-file, draws --n_samples posterior samples, and writes them as a parquet file with one column per parameter.

The model architecture flags must match those used during train.

Example:

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

mach3sbi inference [OPTIONS]

Options

-i, --posterior <posterior>

Required Path to a saved density estimator checkpoint (.pt).

-s, --save_file <save_file>

Required Where to save the inference result to.

-n, --n_samples <n_samples>

Required Number of posterior samples to draw.

-o, --observed_data-file <observed_data_file>

Path to the observed data parquet file (produced by save_data).

--model <model>

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

--hidden <hidden>

Number of hidden units per layer in the density estimator.

--dropout <dropout>

Dropout probability applied during training.

--num_blocks <num_blocks>

Number of residual blocks in the density estimator.

--transforms <transforms>

Number of autoregressive transforms (MAF only).

--num_bins <num_bins>

Number of spline bins (NSF only).

-r, --prior_path <prior_path>

Required Path to a saved Prior .pkl file.

-p, --nuisance_pars <nuisance_pars>

Parameter name patterns (fnmatch-style, e.g. ‘syst_*’) to exclude from the prior and training.

save_data

Extract and save the observed data bins from the simulator.

Calls get_data_bins() on the simulator and writes the result to a parquet file. Useful for producing the observed data vector x_o that is passed to inference.

Example:

mach3sbi save_data \
    -m mypackage.simulator -s MySimulator \
    -c config.yaml -o observed.parquet

mach3sbi save_data [OPTIONS]

Options

-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).

-o, --output_file <output_file>

Path to write the output file.

-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π].

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

-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).

-o, --output_file <output_file>

Path to write the output file.

-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π].

-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.

Example:

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

mach3sbi train [OPTIONS]

Options

-s, --save_file <save_file>

Required Base name of file to save model to. Checkpoints will use 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, e.g. ‘syst_*’) to exclude from the prior and training.

--model <model>

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

--hidden <hidden>

Number of hidden units per layer in the density estimator.

--dropout <dropout>

Dropout probability applied during training.

--num_blocks <num_blocks>

Number of residual blocks in the density estimator.

--transforms <transforms>

Number of autoregressive transforms (MAF only).

--num_bins <num_bins>

Number of spline bins (NSF only).

--batch_size <batch_size>

Number of samples per training batch.

--max_epochs <max_epochs>

Maximum number of training epochs.

--warmup_epochs <warmup_epochs>

Number of epochs for linear learning-rate warm-up from 1% to 100%.

--ema_alpha <ema_alpha>

Smoothing factor for the exponential moving average of validation loss used in early stopping.

--learning_rate <learning_rate>

Initial learning rate for the Adam optimiser.

--stop_after_epochs <stop_after_epochs>

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

--validation_fraction <validation_fraction>

Fraction of data held out for validation.

--num_workers <num_workers>

Number of DataLoader worker processes for data loading.

--autosave_every <autosave_every>

Save a checkpoint every N epochs (in addition to best-model saves).

--resume_checkpoint <resume_checkpoint>

Path to a checkpoint file to resume training from.

--use_amp

Enable automatic mixed precision (AMP) training. May not improve performance on all hardware.

--print_interval <print_interval>

Log training progress every N epochs.

--tensorboard_dir <tensorboard_dir>

Directory for TensorBoard event files. Omit to disable TensorBoard logging.

--scheduler_patience <scheduler_patience>

Number of epochs without improvement before the ReduceLROnPlateau scheduler halves the learning rate.

--show_progress

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

--compile_model

Compile the model with torch.compile. Can reduce per-step time on supported hardware but increases startup time.