sequince-density provides density estimators for use with the sequince SMC
framework, including fitted proposal distributions and normalizing flows for
preconditioned sampling.
sequince-density can be installed directly from PyPI:
pip install sequince-densityHowever, we recommend also installing the relevant dependencies for the features you plan to use. See below for more details.
- Normalizing-flow adapters for Zuko (PyTorch) and FlowJAX (JAX).
- Gaussian-mixture proposals fitted with scikit-learn.
- Integration with Sequince's
FlowTransformfor mutation in a learned latent space andFlowProposalfor fitted proposal distributions.
Install the optional dependencies for your chosen backend:
pip install "sequince-density[zuko]"
# Alternatively, for the JAX backend:
pip install "sequince-density[flowjax]"Fit a Zuko flow to a two-dimensional sample population, then draw samples and evaluate their log densities:
import numpy as np
from sequince_density import ZukoFlow
rng = np.random.default_rng(42)
particles = rng.normal(size=(2000, 2))
flow = ZukoFlow(dims=2, flow_class="MAF", hidden_features=[32, 32])
flow.fit(particles, n_epochs=100, batch_size=500, rng=42)
samples, log_q = flow.sample_and_log_prob(256, rng=43)ZukoFlow returns PyTorch tensors; FlowJax returns JAX arrays.
For preconditioned SMC, pass an unfitted flow to FlowTransform and use the
transform as the particle_transform argument to
make_standard_bayesian_smc. The mutation step fits it to the current particle
population:
from sequince.transforms import FlowTransform
transform = FlowTransform(
ZukoFlow(dims=2, flow_class="MAF", hidden_features=[32, 32]),
fit_kwargs={"n_epochs": 100, "batch_size": 500},
)GMM support is provided via scikit-learn and can be installed with:
pip install "sequince-density[gmm]"import numpy as np
from sequince_density import GaussianMixtureProposal
particles = np.random.default_rng(42).normal(size=(2000, 2))
proposal = GaussianMixtureProposal(n_components=4).fit(particles, rng=42)
samples, log_q = proposal.sample_and_log_prob(256, rng=43)Fitting expects particles shaped (n_particles, n_dimensions). Nonuniform
weights are not supported; use an equal-weight population, such as particles
after resampling.
Both Gaussian mixtures and normalizing flows can provide a fitted starting
distribution for SMC. GaussianMixtureProposal implements Sequince's proposal
interface directly. Wrap a flow in FlowProposal to use the same interface,
including conversion to the SMC particle backend:
from sequince.proposals import FlowProposal
proposal = FlowProposal(
ZukoFlow(dims=2, flow_class="MAF", hidden_features=[32, 32]),
fit_kwargs={"n_epochs": 100, "batch_size": 500},
).fit(particles, rng=42)For either fitted proposal type, pass proposal as log_proposal to
make_standard_bayesian_smc and draw the initial particles from that same
proposal. SMC then bridges from the proposal to the target posterior.
In an ASPIRE-style analysis, a flow is fitted to samples from an initial analysis and used as the starting proposal for a new SMC run with an updated likelihood.
Full proposal examples will be linked here once published in
sequince-examples.
See the sequince density documentation for installation, density fitting, and integration with Sequince proposals and transforms.
The sequince-examples
repository and corresponding documentation contain examples highlighting
different features in sequince.
Bug reports, feature requests, and pull requests are welcome via the GitHub repository. Please see the contributing guidelines and AI policy.
The following repositories are part of the sequince ecosystem:
sequince: the mainsequincerepositorysequince-bilby: provides an interface for using prebuiltsequincesamplers withbilbyorng: provides cross-backend random number generationacai: provides array-API compatible control flow and iteration
Licensed under the MIT License.