Skip to content

CLI Config Reference¤

jim-run is driven entirely by a single TOML file. This page documents every section, field, and default value.

CLI flags¤

jim-run [CONFIG] [OPTIONS]
Flag Description
CONFIG Path to the TOML config file
--init PATH Write a GW150914-style template config to PATH and exit
--verbose, -v Enable DEBUG-level logging
--help Show usage and exit

Top-level fields¤

Field Type Default Description
seed int 0 JAX random seed for everything except injected noise, which has its own noise_seed

Reproducibility

The same config, with the same seed and noise_seed, gives bit-identical samples. This is not guaranteed on GPU, across JAX versions, or for sharded nested sampling with a different n_devices.


[data]¤

Selects where strain and PSD data come from. The type field is required and determines which other fields are valid.

type = "gwosc" — fetch from GWOSC¤

Fetches public LIGO/Virgo/KAGRA strain and PSD from the Gravitational-Wave Open Science Center.

Field Type Default Description
detectors list[str] — Detector identifiers, e.g. ["H1", "L1", "V1"]
trigger_time float — GPS trigger time (seconds)
duration float — Analysis segment length (seconds)
post_trigger_duration float 2.0 Seconds after the trigger kept in the window
psd_duration float — Off-source segment length for PSD estimation (seconds)

type = "injection" — synthetic signal in Gaussian noise¤

Injects a waveform into simulated Gaussian noise drawn from the detector PSD.

By default the PSD is the design-sensitivity ASD Jim ships for each detector; see Default design-sensitivity ASD. To use your own, set psd_files or asd_files; see the note on PSD and ASD files below.

Field Type Default Description
detectors list[str] — Detector identifiers
trigger_time float — GPS trigger time
duration float — Segment length (seconds)
sampling_frequency float — Sample rate in Hz (e.g. 2048.0)
injection_parameters dict[str, float] — Signal parameters to inject
zero_noise bool false If true, inject into zero noise.
noise_seed int — Seed for the injected noise. Required unless zero_noise = true.
psd_files dict[str, path] — Map from detector name to PSD file. Mutually exclusive with asd_files. Omit both to use the built-in design-sensitivity ASD.
asd_files dict[str, path] — Map from detector name to ASD file. Mutually exclusive with psd_files.

Example:

[data]
type = "injection"
detectors = ["H1", "L1"]
trigger_time = 1126259462.4
duration = 4.0
sampling_frequency = 2048.0
noise_seed = 0

[data.injection_parameters]
M_c     = 28.3
q       = 0.85
s1_z    = 0.0
s2_z    = 0.0
iota    = 0.4
d_L     = 440.0
t_c     = 0.0
phase_c = 0.0
psi     = 0.0
ra      = 1.375
dec     = -1.21

type = "file" — load from local files¤

Loads strain and PSD from local files. Useful for offline or CI use.

Supported strain formats: .npz, .gwf / .gwf.gz, .hdf5 / .h5, .csv. PSD and ASD formats are described in the note on PSD and ASD files below.

Field Type Default Description
detectors list[str] — Detector identifiers
trigger_time float — GPS trigger time
strain_files dict[str, path] — Map from individual detector name to strain file (any supported format)
psd_files dict[str, path] — Map from detector name to PSD file. Exactly one of psd_files and asd_files is required.
asd_files dict[str, path] — Map from detector name to ASD file. Exactly one of psd_files and asd_files is required.
strain_channels dict[str, str] {} Channel name per detector for GWF/HDF5 files (e.g. "H1:GDS-CALIB_STRAIN"). If omitted, common LIGO/Virgo preset channel names are tried for .gwf files.

For detectors = ["ET"], provide separate entries for ET1, ET2 and ET3 in strain_files, strain_channels, psd_files and asd_files. detectors = ["ET_2L"] works the same way with ET_Sar and ET_EMR.

Example with .npz files (no channels required):

[data]
type = "file"
detectors = ["H1", "L1"]
trigger_time = 1126259462.4

[data.strain_files]
H1 = "h1_strain.npz"
L1 = "l1_strain.npz"

[data.psd_files]
H1 = "h1_psd.npz"
L1 = "l1_psd.npz"

Example with .gwf frame files and .txt ASD curves:

[data]
type = "file"
detectors = ["H1", "L1"]
trigger_time = 1126259462.4

[data.strain_files]
H1 = "H-H1_LOSC_4_V2-1126259446-32.gwf"
L1 = "L-L1_LOSC_4_V2-1126259446-32.gwf"

[data.strain_channels]
H1 = "H1:GWOSC-4KHZ_R1_STRAIN"
L1 = "L1:GWOSC-4KHZ_R1_STRAIN"

[data.asd_files]
H1 = "O3-H1_asd.txt"
L1 = "O3-L1_asd.txt"

PSD and ASD files

file and injection runs read the PSD from the files named in one of two tables:

Table Values Formats
psd_files PSD, \(\mathrm{Hz}^{-1}\) .npz, .txt, .dat, .csv
asd_files ASD, \(\mathrm{Hz}^{-1/2}\) .npz, .txt, .dat, .csv
  • Set at most one of the two tables.
  • Once a table is set it must name every detector in detectors; there is no per-detector fallback to the built-in default.
  • ET and ET_2L are named by their individual detectors: ET1, ET2 and ET3, or ET_Sar and ET_EMR.
  • An .npz archive holds values and frequencies arrays; the table it is listed under decides whether values is read as a PSD or an ASD.
  • Text files have two columns: frequency in Hz, then the value.

Next-generation detector response

injection and file runs with ET, ET_2L or CE in detectors can turn on two options for those detectors; see Next-generation detectors for when each matters. The injected signal and the likelihood use the same response.

Field Type Default Description
earth_rotation bool false Follow the Earth's rotation while the signal is in the frequency range of the data.
finite_arm_length bool false Do not assume the arms are short compared to the gravitational wavelength.

[waveform]¤

Field Type Default Description
approximant str — Waveform model name
f_ref float 20.0 Reference frequency in Hz for spin conventions

[prior]¤

Each entry maps a parameter name to a prior specification. The parameter name becomes the column name in the output samples.

[prior]
M_c = { type = "uniform", min = 10.0, max = 80.0 }
iota = { type = "sine" }

Prior types¤

uniform¤

param = { type = "uniform", min = <float>, max = <float> }

Uniform distribution on [min, max].

gaussian¤

param = { type = "gaussian", loc = <float>, scale = <float> }

Normal distribution with mean loc and standard deviation scale.

sine¤

param = { type = "sine" }

Sine-weighted prior on \([0, \pi]\). Standard choice for inclination iota.

cosine¤

param = { type = "cosine" }

Cosine-weighted prior on \([-\pi/2, \pi/2]\). Standard choice for declination dec.

power_law¤

param = { type = "power_law", min = <float>, max = <float>, alpha = <float> }

Power-law \(p(x) \propto x^\alpha\) on [min, max]. Use alpha = 2 for a prior uniform in volume on luminosity distance.

rayleigh¤

param = { type = "rayleigh", scale = <float> }

Rayleigh distribution with scale parameter σ.

uniform_sphere¤

spin1 = { type = "uniform_sphere" }

Uniform distribution on the unit sphere. Generates three output parameters: {name}_mag, {name}_theta, {name}_phi. Use for 3-D spin vectors.


[sampling]¤

Optional section that controls the coordinate system the sampler explores. The CLI auto-infers transforms for all other cases and declares the angles that wrap around as periodic for every sampler whenever their prior covers one full period.

Field Type Default Description
detector_frame_time bool true Sample the arrival time at the first detector in data.detectors rather than the geocentric time. Set to false to sample the geocentric t_c directly.
detector_frame_sky bool true Sample azimuth/zenith relative to the detector baseline (requires ≥ 2 detectors) rather than ra/dec. Set to false to sample ra/dec directly.

[likelihood]¤

Field Type Default Description
f_min float — Lower frequency cutoff in Hz
f_max float — Upper frequency cutoff in Hz
fixed_parameters dict[str, float] {} Parameters held fixed at these values and excluded from sampling
phase_marginalization bool false Analytically marginalise over coalescence phase
time_marginalization table — Optional — Analytically marginalise over coalescence time (see below)
distance_marginalization table — Optional — Analytically marginalise over luminosity distance (see below)
heterodyne table — Optional — Use the relative-binning likelihood (see below)
multiband table — Optional — Use the multi-banded likelihood (see below)

[likelihood.time_marginalization]¤

[likelihood.time_marginalization]
tc_range = [-0.1, 0.1]  # seconds relative to trigger_time

[likelihood.distance_marginalization]¤

[likelihood.distance_marginalization]
n_dist_points = 10000  # integration grid size
# ref_dist = 440.0     # optional: reference distance in Mpc; omit to auto-select

[likelihood.distance_marginalization.distance_prior]
d_L = { type = "power_law", min = 1.0, max = 2000.0, alpha = 2.0 }

[likelihood.heterodyne]¤

Enables HeterodynedTransientLikelihoodFD (relative binning).

[likelihood.heterodyne]
# Binning: specify at most one of the two options below.
# epsilon = 0.5  # max phase change per bin in rad (default when neither is set)
# n_bins = 60    # fixed bin count (mutually exclusive with epsilon)

[likelihood.heterodyne.reference_parameters]
type = "optimizer"   # "optimizer" | "provided" | "injection"
popsize = 500
n_steps = 1000
# target = -1234.5    # optional log-likelihood value to stop the search early at
reference_parameters.type Description
"optimizer" Find reference parameters via CMA-ES optimisation (default)
"provided" Supply explicit likelihood-space values via a values dict
"injection" Use data.injection_parameters as reference (injection runs only)

[likelihood.multiband]¤

Enables MultibandedTransientLikelihoodFD (geometric frequency banding).

All fields are optional; when omitted, defaults are chosen adaptively based on the data and prior.


[sampler]¤

The type field selects the backend. Each backend has its own set of tuning parameters.

Sampler comparison¤

type Algorithm Evidence
flowmc Normalizing-flow MCMC No
blackjax-smc Sequential Monte Carlo Yes
blackjax-nss Nested slice sampling Yes
blackjax-swig Nested Slice within Gibbs with waveform caching Yes
blackjax-ns-aw Nested sampling (acceptance-walk) Yes

type = "flowmc"¤

Field Default Description
n_chains 1000 Number of parallel chains
n_local_steps 100 Local MCMC steps per chain per global step
n_global_steps 1000 Global (normalizing-flow) steps per training loop
n_training_loops 20 Number of training loops
n_production_loops 10 Number of production (no-training) loops
n_epochs 20 Normalizing-flow training epochs per loop
local_kernel "MALA" Local kernel: "MALA", "HMC", or "GRW", or a sub-table for kernel-specific settings (see below)
n_NFproposal_batch_size 1000 Flow proposal batch size
global_thinning 1 Keep every Nth global step in the production chain
local_thinning 1 Keep every Nth local step
early_stopping true Stop training when the loss plateaus
parallel_tempering disabled Set to true to enable with defaults, false (or omit) to disable, or a sub-table for custom settings (see below)
checkpoint_dir {output.dir}/ Directory for checkpoint.pkl; set by the CLI automatically
checkpoint_interval 600.0 Seconds between checkpoint writes; 0 disables checkpointing

Local-kernel sub-table:

[sampler.local_kernel]
kernel = "HMC"
step_size = 0.01
n_leapfrog_steps = 20

Parallel-tempering sub-table:

[sampler.parallel_tempering]
n_temperatures = 5
max_temperature = 10.0
n_tempered_steps = 5

type = "blackjax-smc"¤

Field Default Description
n_particles 5000 Number of particles
mcmc_kernel "tpCN" Kernel that moves the particles: "tpCN" or "GRW", or a sub-table for kernel-specific settings (see below)
flow enabled Normalizing-flow coordinates for the kernel: a sub-table for custom settings (see below), or false to disable
target_ess_fraction 3.0 (0.9 if persistent_sampling = false) Optional — target effective sample size as a fraction of n_particles; use instead of target_ess, not both
target_ess — Optional — target absolute ESS count; use instead of target_ess_fraction, not both
batch_size 0 Particles per sequential batch when evaluating the posterior; 0 evaluates all at once
persistent_sampling true Reuse particles across temperatures
temperature_ladder — Optional — fixed list of temperatures from 0.0 to 1.0; omit to use adaptive tempering
checkpoint_dir {output.dir}/ Directory for checkpoint.pkl; set by the CLI automatically
checkpoint_interval 600.0 Seconds between checkpoint writes; 0 disables checkpointing

Kernel sub-table, t-pCN (the default):

[sampler.mcmc_kernel]
kernel = "tpCN"
n_patience_per_dim = 20       # stop after this many steps per dimension without improvement
n_max_per_dim = 100           # at most this many steps per dimension per temperature
target_acceptance_rate = 0.15

Kernel sub-table, Gaussian random walk:

[sampler.mcmc_kernel]
kernel = "GRW"
n_mcmc_steps_per_dim = 100    # steps per dimension per temperature
initial_cov_scale = 0.5       # first scale of the proposal covariance
target_acceptance_rate = 0.234
scale_adaptation_gain = 3.0

Flow sub-table:

[sampler.flow]
n_layers = 6
hidden_size = [64, 64]
n_bins = 8
n_epochs = 200                # training epochs per temperature
batch_size = 500
learning_rate = 1e-3

type = "blackjax-nss"¤

Field Default Description
n_live 1000 Number of live points
n_delete_frac 0.5 Fraction of live points replaced per iteration
num_inner_steps_per_dim 10 Slice steps per dimension for the nested kernel
termination_dlogz 0.1 Stop when the remaining log-evidence contribution falls below this
n_devices 1 Number of local devices used to shard live points; n_live and n_delete must be divisible by it
checkpoint_dir {output.dir}/ Directory for checkpoint.pkl; set by the CLI automatically
checkpoint_interval 600.0 Seconds between checkpoint writes; 0 disables checkpointing

type = "blackjax-swig"¤

Field Default Description
blocks required Ordered lists of sampling-space parameter names
n_live 500 Number of live points
n_delete_frac 0.5 Fraction of live points replaced per iteration
num_inner_steps_per_dim 1 Slice steps per dimension within each block
num_gibbs_sweeps 2 Complete block sweeps per replacement
termination_dlogz 0.1 Stop when the remaining evidence contribution falls below this
n_devices 1 Number of local devices used to shard live points; n_live and n_delete must be divisible by it
checkpoint_dir {output.dir}/ Directory for checkpoint.pkl; set by the CLI automatically
checkpoint_interval 600.0 Seconds between checkpoint writes; 0 disables checkpointing

type = "blackjax-ns-aw"¤

Requires all sampling-space parameters to lie in \([0, 1]\). The CLI enforces this automatically.

Field Default Description
n_live 1000 Number of live points
n_delete_frac 0.5 Fraction of live points replaced per iteration
n_target 60 Target number of accepted steps per replacement
max_mcmc 5000 Maximum MCMC steps per replacement attempt
termination_dlogz 0.1 Termination criterion on remaining log-evidence
checkpoint_dir {output.dir}/ Directory for checkpoint.pkl; set by the CLI automatically
checkpoint_interval 600.0 Seconds between checkpoint writes; 0 disables checkpointing

[output]¤

Field Type Default Description
dir path — Directory to write all outputs into
overwrite bool false Allow overwriting an existing output directory
save_corner bool false Save a corner plot (corner.png); requires the corner package
n_samples int 0 Number of posterior samples to save; 0 means save all
corner_parameters list[str] — Optional — parameter names to include in the corner plot; default is all parameters

Output files¤

File Description
samples.npz Posterior samples; one array key per parameter name, plus log_likelihood
diagnostics.json Scalar diagnostics: log evidence (nested samplers), acceptance rates, etc.
diagnostics.npz Array diagnostics: log-probability traces, chain arrays, etc.
config.final.toml The fully-resolved config including all defaults; re-run with jim-run config.final.toml
corner.png Corner plot (only when save_corner = true)