sequince-bilby

Interface and plugin for using sequince with bilby.

The plugin provides the following samplers via bilby:

• sequince-smc: standard sequential Monte Carlo
• sequince-ps: persistent sampling

Installation

Install sequince-bilby with pip (Python 3.11 or newer is required):

pip install sequince-bilby

For development setup, see the contributing guidelines.

Usage

See the Bilby documentation for guidance on defining likelihoods and priors, running analyses, and working with results.

Once installed, select a sampler with bilby.run_sampler:

import bilby

likelihood = ...
priors = ...

result = bilby.run_sampler(
    likelihood=likelihood,
    priors=priors,
    sampler="sequince-smc",
    n_particles=500,
)

Use sampler="sequince-ps" for persistent sampling. Keyword arguments are forwarded to the corresponding Sequince prebuilt sampler. See the Bilby documentation for likelihoods, priors, and results.

Parallelization

For NumPy sampling, set npool to the number of worker processes:

result = bilby.run_sampler(
    likelihood=likelihood,
    priors=priors,
    sampler="sequince-smc",
    npool=4,
)

Array backends

Sampling uses NumPy by default and supports released Bilby 2.8. JAX and PyTorch require an array-aware development version of Bilby, the corresponding backend package, and priors and likelihoods that support that backend.

Enable array API support before importing Bilby:

export BILBY_ARRAY_API=1
export SCIPY_ARRAY_API=1
export JAX_ENABLE_X64=1  # For JAX double precision.

Select the backend with sampler_backend:

result = bilby.run_sampler(
    likelihood=likelihood,
    priors=priors,
    sampler="sequince-smc",
    sampler_backend="jax",
    npool=1,
    map_fn="vmap",
    jit=True,
    sampling_seed=1234,
)

Backend sampling requires npool=1 without a pool. Use map_fn="vmap" for vectorized likelihood evaluation; the likelihood must support the backend's vectorization. For JAX, jit=True compiles the callback and requires traceable priors and likelihoods. These options do not compile the full sampler loop. Omit map_fn and jit to use the default mapping.

PyTorch support is experimental: the tested Bilby development version can fail during prior normalization for particles outside prior support. CuPy is not supported.

Run the backend example with the optional bilby-main development environment:

pixi run -e bilby-main example-backends --backend jax

Reproducibility

Use sampling_seed for reproducible runs on a given backend. You can also pass a generator with rng. Without either, sampling uses Bilby's random generator. Different backends use different random streams.

When resuming, use the same backend as the checkpoint. The saved RNG state takes precedence over a new seed or generator.

Checkpointing

HDF5 checkpointing and resume are enabled by default. The default checkpoint is <outdir>/<label>_<sampler>_checkpoint.h5.

result = bilby.run_sampler(
    likelihood=likelihood,
    priors=priors,
    sampler="sequince-ps",
    checkpoint=True,
    checkpoint_filename="checkpoint.h5",
    checkpoint_frequency=10,
    resume=True,
)

Set checkpoint=False or resume=False to disable either behavior.

Samples

result.posterior contains equal-weight samples obtained by rejection sampling. The full particle population and its normalized weights are stored in result.nested_samples. The complete Sequince result is also saved as an HDF5 file in outdir.

Citing

If you use sequince-bilby in scientific work, please cite Sequince and Bilby. Follow Bilby's citation guidance for the Bilby paper, the DOI for the version used, and any additional references relevant to your analysis.

If you use sequince-ps, please also cite the persistent sampling paper. For gravitational-wave analyses, please also cite arXiv:2506.18977.

Contributing

Bug reports, feature requests, and pull requests are welcome via the GitHub repository. Please see the contributing guidelines and Sequince's AI policy.

Related repositories

The following repositories are part of the sequince ecosystem:

• sequince: provides modular sequential Monte Carlo samplers and reusable sampling components
• sequince-density: provides density estimators for preconditioned SMC and ASPIRE-style analyses
• sequince-examples: provides examples demonstrating Sequince's features
• orng: provides cross-backend random number generation
• acai: provides array-API compatible control flow and iteration

License

Licensed under the MIT License.