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.

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

merge-shards

Merge feather files

mach3sbi merge-shards [OPTIONS]

Options

-s, --simulation_dir <simulation_dir>

-o, --output_file <output_file>

-r, --prior_path <prior_path>

Drop theta columns excluded by this prior’s nuisance filter. Masking at read time saves no I/O (row-major pages pull whole rows), so this is the only way to stop paying to read unused parameters. Bakes the nuisance choice into the output – changing it means re-merging.

--shuffle

Randomise shard order and permute rows within a sliding window. Training reads sequentially and splits train/val contiguously, so without this the validation set is just the tail of the shard order.

--shuffle_buffer_rows <shuffle_buffer_rows>

Shuffle window size in rows. Costs ~rows x (x_dim + theta_dim) x 4 bytes of RAM.

Default:

5000000

--seed <seed>

Seed for shard ordering and window permutation.

Default:

42

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.

strip-theta

Drop nuisance theta columns from merged .npy data

mach3sbi strip-theta [OPTIONS]

Options

-d, --data_dir <data_dir>

Required Directory containing the merged theta.npy and x.npy.

-r, --prior_path <prior_path>

Required Prior whose nuisance filter selects the columns to keep.

-o, --output_dir <output_dir>

Destination for the narrowed theta.npy (x.npy is symlinked, not copied).

--in_place

Replace theta.npy in data_dir via a temp file and atomic rename. Destroys the unfiltered theta – recovering it means re-merging.

--chunk_rows <chunk_rows>

Rows per streamed chunk.

Default:

262144

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 Folder containing the merged theta.npy and x.npy (see merge-shards).

-r, --prior_path <prior_path>

Required Path to a saved Prior .pkl file.

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

100

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

50

--num_workers <num_workers>

Number of DataLoader worker processes.

Default:

1

--prefetch_factor <prefetch_factor>

Batches each worker stages ahead. Host RAM is roughly num_workers x prefetch_factor x batch_size x row_bytes, all pinned.

Default:

4

--shuffle_block_size <shuffle_block_size>

Rows per contiguous block; blocks are shuffled, rows are not. Size to one filesystem record (128 rows of ~1 KiB = one 128 KiB ZFS record). Raise on high-latency storage, lower to decorrelate more.

Default:

128

--val_batch_multiplier <val_batch_multiplier>

Validation batch size as a multiple of –batch_size. Validation is no-grad, so a larger batch costs no extra memory.

Default:

4

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

--compress_x

Apply PCA compression to X (if resuming this has not effect)

--compress_x_components <compress_x_components>

How many components to compress X down to

--compress_theta

Apply PCA compression to (if resuming this has not effect)

--compress_theta_components <compress_theta_components>

How many components to compress theta down to

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