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
|
|
weights |
array or None
|
Normalized weights of |
log_z |
float
|
Log evidence (log ratio for a bridge): the log of the mean of the
replicates' unbiased |
log_z_error |
float
|
Standard error of |
log_z_variance |
float
|
The unclipped variance estimate behind |
log_z_replicates |
array
|
Each replicate's |
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 |
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
|
|
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 |
1
|
ess_target
|
float
|
Fraction of |
0.25
|
steps
|
int
|
HMC mutations per stage. |
5
|
leapfrogs
|
Initial trajectory length, initial step size (default |
4
|
|
step_size
|
Initial trajectory length, initial step size (default |
4
|
|
alpha
|
Initial trajectory length, initial step size (default |
4
|
|
max_stages
|
Caps; reaching either returns |
200
|
|
max_seconds
|
Caps; reaching either returns |
200
|
|
moves
|
sequence of callable
|
Extra mutations run after the HMC steps of each round, each
|
()
|
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.
|
|