Skip to content

virgil.smc

Adaptive tempered sequential Monte Carlo on BlackJAX: the evidence and posterior particles of a flat-vector model, and the evidence ratio between two likelihoods. See virgil.smc for the algorithm and its references.

Adaptive tempered sequential Monte Carlo on BlackJAX.

Provisional

May change in any 0.4.x release without a deprecation cycle.

tempered_smc tempers a prior to prior × L; bridge_smc tempers prior × L₁ to prior × L₂ from given particles, π_β ∝ prior · L₁^(1-β) · L₂^β. Both return the particles, their weights, log Z (the log evidence, or the log ratio Z₂/Z₁ for a bridge) with a Monte Carlo error from a single run, and the schedule. The error is the genealogy-based estimator of Lee & Whiteley (2018), extended to adaptive SMC by Du & Guyader (2021); it needs multinomial resampling, which is what is used. When the genealogy has collapsed to one ancestor the error is nan and variance_degenerate is set. The next β solves for an ESS of one half of the incremental weights of the (resampled) particles, as in BlackJAX's adaptive tempering (Jasra et al. 2011; Zhou, Johansen & Aston 2016). The mutation is fixed-length HMC with the step size and trajectory length tuned per stage and the mass matrix set to the particle covariance (Buchholz, Chopin & Jacob 2021). A run that reaches the time or stage cap has not reached β = 1: it returns stopped=True and no particles. Parameters are a flat vector; the log densities take one. With x64 on, use float64 particles: BlackJAX draws the HMC momentum in the default float width.

Source: BlackJAX (Cabezas et al. 2024), Del Moral, Doucet & Jasra 2006, Jasra et al. 2011, Lee & Whiteley 2018, Du & Guyader 2021 (see references/provenance.toml).

SMCResult dataclass

The outcome of a tempered SMC run.

Attributes:

Name Type Description
particles array or None

(replicates · n_particles, d) particles at β = 1; None if stopped.

weights array or None

Normalized weights of particles (sum to one).

log_z float

Log evidence (log ratio for a bridge): the log of the mean of the replicates' unbiased Ẑ. nan if stopped.

log_z_error float

Standard error of log_z from the genealogy-based variance estimator; nan if variance_degenerate.

log_z_variance float

The unclipped variance estimate behind log_z_error; it is unbiased and so can be negative. nan if every particle of a replicate shares one ancestor, or if stopped.

log_z_replicates array

Each replicate's log Ẑ.

betas list of array

Per replicate, β after each stage.

ess list of array

Per replicate, the ESS of the weights after each stage.

stopped bool

A replicate reached the time or stage cap before β = 1.

undersampled bool

A replicate's final ESS is below ess_target · n_particles.

variance_degenerate bool

The error estimate is unusable: all particles of a replicate share one ancestor, or the estimate is not positive. Use more particles.

particles instance-attribute

weights instance-attribute

log_z instance-attribute

log_z_error instance-attribute

log_z_variance instance-attribute

log_z_replicates instance-attribute

betas instance-attribute

ess instance-attribute

stopped instance-attribute

undersampled instance-attribute

variance_degenerate instance-attribute

__init__(particles, weights, log_z, log_z_error, log_z_variance, log_z_replicates, betas, ess, stopped, undersampled, variance_degenerate)

tempered_smc(logprior, loglike, init_particles, *, key, n_particles, replicates=1, ess_target=0.25, steps=5, leapfrogs=4, step_size=None, alpha=1.0, max_stages=200, max_seconds=float('inf'), moves=())

Temper the prior to prior × likelihood with adaptive SMC.

Parameters:

Name Type Description Default
logprior callable

Normalized log prior and log likelihood of one flat parameter vector.

required
loglike callable

Normalized log prior and log likelihood of one flat parameter vector.

required
init_particles callable

init_particles(key, n) returns n exact prior draws: an array (n, d), or a dict with the continuous block under "x" and auxiliary arrays (for example discrete labels) under other keys. logprior and loglike then take the dict.

required
key PRNGKey
required
n_particles int

Particles per replicate.

required
replicates int

Independent runs, pooled into one evidence and one particle set. The error comes from each run's genealogy, so one run suffices; more are for cross-checks (compare log_z_replicates).

1
ess_target float

Fraction of n_particles below which the final ESS sets undersampled. It is below the schedule's one half so that a healthy run, whose final ESS scatters about one half, is not flagged.

0.25
steps int

HMC mutations per stage.

5
leapfrogs

Initial trajectory length, initial step size (default d**-0.25) and the ESJD offset of the per-stage tuning (Buchholz et al. 2021).

4
step_size

Initial trajectory length, initial step size (default d**-0.25) and the ESJD offset of the per-stage tuning (Buchholz et al. 2021).

4
alpha

Initial trajectory length, initial step size (default d**-0.25) and the ESJD offset of the per-stage tuning (Buchholz et al. 2021).

4
max_stages

Caps; reaching either returns stopped=True.

200
max_seconds

Caps; reaching either returns stopped=True.

200
moves sequence of callable

Extra mutations run after the HMC steps of each round, each move(key, particle, logdensity) -> (particle, info) on one particle, where logdensity is the tempered log density at the current β. A move must leave that density invariant (a Gibbs update, or Metropolis-Hastings with its own acceptance); HMC moves only the continuous block.

()

Returns:

Name Type Description
SMCResult
Source Jasra et al. 2011; Buchholz, Chopin & Jacob 2021.

bridge_smc(logprior, loglike1, loglike2, particles, *, key, weights=None, n_particles=None, replicates=1, ess_target=0.25, steps=5, leapfrogs=4, step_size=None, alpha=1.0, max_stages=200, max_seconds=float('inf'), moves=())

Bridge prior × L₁ to prior × L₂: π_β ∝ prior · L₁^(1-β) · L₂^β.

particles ((m, d), with optional weights) sample prior × L₁; each replicate resamples n_particles of them. log_z estimates log(Z₂ / Z₁). The replicates share the input cloud, so log_z_error excludes the variance of that cloud. Other arguments are those of tempered_smc.

Returns:

Name Type Description
SMCResult
Source Del Moral, Doucet & Jasra 2006; Zhou, Johansen & Aston 2016.