The public entry to inference: one call shape for every method (infer),
the methods' own entry points, and the modelling primitives re-exported.
Every method runs a probabilistic program as a savepoint handler: SMC
(foerster.inference.smc) for the particle methods — smc-infer,
importance-sampling, pimh-infer, pgibbs-infer, pgas-infer, ipmcmc-infer
(foerster.inference.pmcmc), bbvi-infer (foerster.inference.bbvi) and
kernel-infer with a PInferenceKernel — and replay plus accept over traces
(foerster.runtime.trace) for the Markov-chain kernels.
Pure inference (:world-policy :fresh, the default) runs in fresh worlds;
:world-policy :fork in canonical forks of the caller's world
(foerster.inference.worlds; methods that run several times fork the
caller once, foerster.runtime.canonical). Particle measures hold
Samples (result, trace, and a canonical particle's world descriptor).
Errors keep this namespace's keywords wherever they are raised.
All functions return Spin<EmpiricalMeasure> for composability;
post-processing is measure-centric (query, predict:
foerster.inference.posterior).
The public entry to inference: one call shape for every method (`infer`), the methods' own entry points, and the modelling primitives re-exported. Every method runs a probabilistic program as a savepoint handler: SMC (`foerster.inference.smc`) for the particle methods — smc-infer, importance-sampling, pimh-infer, pgibbs-infer, pgas-infer, ipmcmc-infer (`foerster.inference.pmcmc`), bbvi-infer (`foerster.inference.bbvi`) and kernel-infer with a PInferenceKernel — and replay plus accept over traces (`foerster.runtime.trace`) for the Markov-chain kernels. Pure inference (`:world-policy :fresh`, the default) runs in fresh worlds; `:world-policy :fork` in canonical forks of the caller's world (`foerster.inference.worlds`; methods that run several times fork the caller once, `foerster.runtime.canonical`). Particle measures hold `Sample`s (result, trace, and a canonical particle's world descriptor). Errors keep this namespace's keywords wherever they are raised. All functions return Spin<EmpiricalMeasure> for composability; post-processing is measure-centric (query, predict: `foerster.inference.posterior`).
(bbvi-infer model-task num-particles num-iterations & [opts])Black-box variational inference. See org.replikativ.foerster.inference.bbvi/bbvi-infer.
Black-box variational inference. See `org.replikativ.foerster.inference.bbvi/bbvi-infer`.
(conditional model opts)Nested inference: a spin resolving the posterior of model's value under
opts (as for infer) as a distribution — a categorical over the values
the inner inference found, weighted (Anglican's conditional). The outer
program samples from it, or observes against it:
(let [guess (await (infer/conditional (inner-model x) {:method :enumerate}))] (sample guess :id :their-guess))
The inner inference runs in fresh worlds of its own. Under exact
enumeration the distribution is exact; otherwise it is the inner measure,
so it has as many atoms as distinct values. Memoize it (process/mem) when
the outer program asks the same question repeatedly. A finite inner
approximation may bias nonlinear outer computations; more outer draws do
not remove fixed inner error, and memoization does not make it exact. The
returned distribution carries :inference/nesting provenance metadata.
Nested inference: a spin resolving the posterior of `model`'s value under
`opts` (as for `infer`) as a distribution — a categorical over the values
the inner inference found, weighted (Anglican's `conditional`). The outer
program samples from it, or observes against it:
(let [guess (await (infer/conditional (inner-model x) {:method :enumerate}))]
(sample guess :id :their-guess))
The inner inference runs in fresh worlds of its own. Under exact
enumeration the distribution is exact; otherwise it is the inner measure,
so it has as many atoms as distinct values. Memoize it (`process/mem`) when
the outer program asks the same question repeatedly. A finite inner
approximation may bias nonlinear outer computations; more outer draws do
not remove fixed inner error, and memoization does not make it exact. The
returned distribution carries :inference/nesting provenance metadata.See org.replikativ.foerster.effects/deterministic.
See `org.replikativ.foerster.effects/deterministic`.
See org.replikativ.foerster.effects/factor.
See `org.replikativ.foerster.effects/factor`.
(get-variational-dists measure)The learned {address distribution} of a bbvi-infer result. See org.replikativ.foerster.inference.bbvi/get-variational-dists.
The learned {address distribution} of a `bbvi-infer` result. See `org.replikativ.foerster.inference.bbvi/get-variational-dists`.
(importance-sampling model-task num-samples & [opts])Importance sampling: num-samples runs of model-task, each weighted by
its observations, never resampled (savepoint SMC with
:resample-threshold 0). Options and result as for smc-infer.
Importance sampling: `num-samples` runs of `model-task`, each weighted by its observations, never resampled (savepoint SMC with `:resample-threshold` 0). Options and result as for `smc-infer`.
(infer model
{:keys [method particles iterations chains burn step-size kernel]
:as opts})Run model under the inference method (:method opts) — one call shape
for every method, as Anglican's doquery:
(infer/infer (model) {:method :smc :particles 1000}) (infer/infer (model) {:method :mh :iterations 4000 :chains 4 :burn 1000}) (infer/infer (model) {:method :pmmh :particles 100 :iterations 2000 :params #{:drift}})
Methods and their sizes:
:enumerate (exact; finite supports only,
:max-branches; :policy, :seed,
:world-policy as for :smc)
:importance :smc :tempered :particles
:parallel-tempering :chains (temperatures, default 10),
:rounds; one block site
:pimh :pgibbs :pgas :ipmcmc :bbvi :particles :iterations
:mh :rmh :nuts :iterations per chain, :chains (default
4), :burn, :step-size (:rmh, :nuts);
every draw after :burn is kept; :nuts
adapts during :burn (block sites),
from :step-size and :inverse-metric,
each chain jittered around :init
unless :jitter false
(k/nuts-kernel). :rmh with
:compiled? true (JVM) runs on the
model compiled to plain functions
(foerster.inference.compiled): a model from
analysis/model whose structure is
static, else refused with the
reasons; its traces hold the latent
values only
:kernel :kernel (a foerster.moves.kernel kernel)
and :chains or :particles
:pmmh :particles per SMC, :iterations,
:params (and smc2/pmmh options)
The other options go to the method (see its function). Returns a spin
resolving the measure.
Run `model` under the inference method `(:method opts)` — one call shape
for every method, as Anglican's `doquery`:
(infer/infer (model) {:method :smc :particles 1000})
(infer/infer (model) {:method :mh :iterations 4000 :chains 4 :burn 1000})
(infer/infer (model) {:method :pmmh :particles 100 :iterations 2000
:params #{:drift}})
Methods and their sizes:
:enumerate (exact; finite supports only,
:max-branches; :policy, :seed,
:world-policy as for :smc)
:importance :smc :tempered :particles
:parallel-tempering :chains (temperatures, default 10),
:rounds; one block site
:pimh :pgibbs :pgas :ipmcmc :bbvi :particles :iterations
:mh :rmh :nuts :iterations per chain, :chains (default
4), :burn, :step-size (:rmh, :nuts);
every draw after :burn is kept; :nuts
adapts during :burn (block sites),
from :step-size and :inverse-metric,
each chain jittered around :init
unless :jitter false
(`k/nuts-kernel`). :rmh with
:compiled? true (JVM) runs on the
model compiled to plain functions
(`foerster.inference.compiled`): a model from
`analysis/model` whose structure is
static, else refused with the
reasons; its traces hold the latent
values only
:kernel :kernel (a `foerster.moves.kernel` kernel)
and :chains or :particles
:pmmh :particles per SMC, :iterations,
:params (and `smc2/pmmh` options)
The other options go to the method (see its function). Returns a spin
resolving the measure.See org.replikativ.foerster.effects/intervene!.
See `org.replikativ.foerster.effects/intervene!`.
(ipmcmc-infer model-task num-particles num-iterations & [opts])Interacting particle MCMC. See org.replikativ.foerster.inference.pmcmc/ipmcmc-infer.
Interacting particle MCMC. See `org.replikativ.foerster.inference.pmcmc/ipmcmc-infer`.
(kernel-infer model-task kernel num-particles & [opts])Run inference with a kernel.
Markov-chain kernels (single-site-mh-kernel, random-walk-mh-kernel,
block-gibbs-kernel, hmc-kernel) run num-particles independent chains.
Any other PInferenceKernel runs savepoint SMC whose latent sites take the
value the kernel's step gives (the prior kernel: a draw from the prior).
Args:
random/set-seed!) seeds
the runfoerster.runtime.trace/reexecute)Returns: Spin<EmpiricalMeasure>
Examples: ;; Importance sampling with prior kernel (spin (let [model (coin-flip-model) measure (await (kernel-infer model (prior-kernel) 100 {:barrier-policy :none}))] (query measure identity)))
Run inference with a kernel.
Markov-chain kernels (`single-site-mh-kernel`, `random-walk-mh-kernel`,
`block-gibbs-kernel`, `hmc-kernel`) run `num-particles` independent chains.
Any other PInferenceKernel runs savepoint SMC whose latent sites take the
value the kernel's `step` gives (the prior kernel: a draw from the prior).
Args:
- model-task: Spin (from model function) - Probabilistic program to infer
- kernel: a kernel (e.g., prior-kernel, single-site-mh-kernel)
- num-particles: Number of particles (chains)
- opts: Optional map with:
- :barrier-policy - :every-observe (default, SMC) | :none (importance
sampling)
- :resample-threshold - ESS threshold (default 0.5)
- :executor - Shared executor for all particles
- :seed - the run's seed: the same seed, the same draws, whatever the
executor; without it the process generator (`random/set-seed!`) seeds
the run
- :world-policy - :fresh (default) for pure inference, or :fork to
execute each particle (each chain) in a frozen canonical Yggdrasil
world that is discarded after the final values are captured; chains
fork one frozen fork of the caller made when inference starts and
reuse nothing incrementally (`foerster.runtime.trace/reexecute`)
- :world-opts - Optional :systems/:rights/:snapshots policy forwarded to
canonical forks; lifecycle fields are owned by inference
- :authority, :grant - budgets (doc/worlds.md); particle kernels only
Returns: Spin<EmpiricalMeasure>
Examples:
;; Importance sampling with prior kernel
(spin
(let [model (coin-flip-model)
measure (await (kernel-infer model (prior-kernel) 100
{:barrier-policy :none}))]
(query measure identity)))See org.replikativ.foerster.effects/observe.
See `org.replikativ.foerster.effects/observe`.
(parallel-tempering-infer model-task num-chains & [opts])Non-reversible parallel tempering (foerster.inference.parallel-tempering) of a
model-task that is one block site with a :sample and
:sample-log-density: num-chains chains on the path from that draw
density to the posterior, swapping states between neighbours, with the
schedule tuned over :rounds rounds of doubling length (default 10).
Options: :rounds, :steps (random-walk steps per chain per scan),
:executor, :seed (fixes every draw), :world-policy (:fork: the
program runs in a fork of the caller's world) and :world-opts; no
:authority yet.
Returns a spin resolving the EmpiricalMeasure of the last round's
target-chain states; m/log-marginal is the stepping-stone evidence and
:temperatures, :barrier, :local-barrier, :round-trips and
:swap-acceptance diagnose the run.
Non-reversible parallel tempering (`foerster.inference.parallel-tempering`) of a `model-task` that is one block site with a `:sample` and `:sample-log-density`: `num-chains` chains on the path from that draw density to the posterior, swapping states between neighbours, with the schedule tuned over `:rounds` rounds of doubling length (default 10). Options: `:rounds`, `:steps` (random-walk steps per chain per scan), `:executor`, `:seed` (fixes every draw), `:world-policy` (:fork: the program runs in a fork of the caller's world) and `:world-opts`; no `:authority` yet. Returns a spin resolving the EmpiricalMeasure of the last round's target-chain states; `m/log-marginal` is the stepping-stone evidence and `:temperatures`, `:barrier`, `:local-barrier`, `:round-trips` and `:swap-acceptance` diagnose the run.
(pgas-infer model-task num-particles num-iterations & [opts])Particle Gibbs with ancestor sampling. See org.replikativ.foerster.inference.pmcmc/pgas-infer.
Particle Gibbs with ancestor sampling. See `org.replikativ.foerster.inference.pmcmc/pgas-infer`.
(pgibbs-infer model-task num-particles num-iterations & [opts])Particle Gibbs (conditional SMC). See org.replikativ.foerster.inference.pmcmc/pgibbs-infer.
Particle Gibbs (conditional SMC). See `org.replikativ.foerster.inference.pmcmc/pgibbs-infer`.
(pimh-infer model-task num-particles num-iterations & [opts])Particle independent Metropolis-Hastings. See org.replikativ.foerster.inference.pmcmc/pimh-infer.
Particle independent Metropolis-Hastings. See `org.replikativ.foerster.inference.pmcmc/pimh-infer`.
(predict measure pred-fn num-samples)Draws from a measure, each passed to pred-fn. See org.replikativ.foerster.inference.posterior/predict.
Draws from a measure, each passed to `pred-fn`. See `org.replikativ.foerster.inference.posterior/predict`.
(predictive model measure n & [{:keys [interventions]}])Posterior predictive draws of model. See org.replikativ.foerster.inference.posterior/predictive.
Posterior predictive draws of `model`. See `org.replikativ.foerster.inference.posterior/predictive`.
(query measure query-fn)Weighted statistics of a function of the program's value. See org.replikativ.foerster.inference.posterior/query.
Weighted statistics of a function of the program's value. See `org.replikativ.foerster.inference.posterior/query`.
See org.replikativ.foerster.effects/sample.
See `org.replikativ.foerster.effects/sample`.
(smc-infer model-task num-particles & [opts])Sequential Monte Carlo: num-particles particles run model-task (a
spin); at every observation the population is resampled when its
effective sample size falls below :resample-threshold·N. Runs on
savepoints (foerster.inference.smc/smc); the measure holds Samples, and its
m/log-marginal estimates the evidence.
Options:
:resample-threshold ESS fraction below which to resample (default 0.5)
:world-policy :fresh (default): fresh worlds; :fork: canonical
forks of the caller's world (doc/worlds.md)
:world-opts fork options for :fork (:systems, :rights, :snapshots)
:authority, :grant a world.scope/PResourceAuthority and the budget the
inference draws from the caller's wallet (:fork)
:executor the executor the worlds run on (default: spindel's)
:policy a foerster.runtime.trace/policy deciding the sites
(constraints, interventions, proposals)
:anchors, :rejuvenate resample-move: after each resampling, MH moves
from anchored sites (foerster.inference.smc/smc; :fresh only)
Returns a spin resolving the EmpiricalMeasure.
(sp/with-context world @(smc-infer (model) 1000)) ; at the REPL (spin (query (await (smc-infer (model) 1000)) identity))
Sequential Monte Carlo: `num-particles` particles run `model-task` (a
spin); at every observation the population is resampled when its
effective sample size falls below `:resample-threshold`·N. Runs on
savepoints (`foerster.inference.smc/smc`); the measure holds `Sample`s, and its
`m/log-marginal` estimates the evidence.
Options:
:resample-threshold ESS fraction below which to resample (default 0.5)
:world-policy :fresh (default): fresh worlds; :fork: canonical
forks of the caller's world (doc/worlds.md)
:world-opts fork options for :fork (:systems, :rights, :snapshots)
:authority, :grant a world.scope/PResourceAuthority and the budget the
inference draws from the caller's wallet (:fork)
:executor the executor the worlds run on (default: spindel's)
:policy a `foerster.runtime.trace/policy` deciding the sites
(constraints, interventions, proposals)
:anchors, :rejuvenate resample-move: after each resampling, MH moves
from anchored sites (`foerster.inference.smc/smc`; :fresh only)
Returns a spin resolving the EmpiricalMeasure.
(sp/with-context world @(smc-infer (model) 1000)) ; at the REPL
(spin (query (await (smc-infer (model) 1000)) identity))(tempered-infer model-task num-particles & [opts])Tempered SMC (foerster.inference.tempering): num-particles complete runs of
model-task, moved from the prior to the posterior through the targets
p(x)·L(x)^β with an adaptive schedule of β. Explores posteriors whose
modes a Markov chain cannot cross, and estimates the evidence (its
contract says :unverified: the schedule adapts to the population).
Options: :ess-target (0.5), :moves (single-site MH moves per particle
per step; default a sweep), :scale (2.38), :waste-free P, :max-steps,
:executor, :seed (fixes every draw), :world-policy (:fork: every
particle in a fork of one frozen fork of the caller's world, without
incremental reuse) and :world-opts; no :authority yet.
Returns a spin resolving the EmpiricalMeasure; :temperatures holds the
schedule.
Tempered SMC (`foerster.inference.tempering`): `num-particles` complete runs of `model-task`, moved from the prior to the posterior through the targets p(x)·L(x)^β with an adaptive schedule of β. Explores posteriors whose modes a Markov chain cannot cross, and estimates the evidence (its contract says `:unverified`: the schedule adapts to the population). Options: `:ess-target` (0.5), `:moves` (single-site MH moves per particle per step; default a sweep), `:scale` (2.38), `:waste-free` P, `:max-steps`, `:executor`, `:seed` (fixes every draw), `:world-policy` (:fork: every particle in a fork of one frozen fork of the caller's world, without incremental reuse) and `:world-opts`; no `:authority` yet. Returns a spin resolving the EmpiricalMeasure; `:temperatures` holds the schedule.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |