# Copyright Contributors to the Pyro project.
# SPDX-License-Identifier: Apache-2.0
"""
Composable Gibbs kernels: a composite :class:`Gibbs` kernel that updates the latent sites of a
model block by block, the generic block kernels :class:`CustomGibbs` and :class:`DiscreteGibbs`,
and the pure helpers they share with the HMC-within-Gibbs kernels
(:mod:`numpyro.infer.hmc_gibbs`, :mod:`numpyro.infer.mixed_hmc`).
"""
from collections import OrderedDict
from collections.abc import Callable, Sequence
import copy
from functools import partial, reduce
from typing import Any, NamedTuple, Protocol, TypeAlias
import numpy as np
import jax
from jax import random
from jax.flatten_util import ravel_pytree
import jax.numpy as jnp
from jax.scipy.special import expit
from numpyro._typing import (
ConstrainFn,
ModelArgs,
ModelKwargs,
ModelT,
PotentialFn,
PyTree,
SiteValues,
TraceT,
)
from numpyro.handlers import condition, seed, substitute, trace
from numpyro.infer.hmc import HMC
from numpyro.infer.initialization import init_to_sample
from numpyro.infer.mcmc import MCMCKernel
from numpyro.infer.util import (
_prepare_model_for_potential,
_transforms_from_trace,
potential_energy,
transform_fn,
)
from numpyro.util import cond, fori_loop, identity, is_prng_key
__all__ = [
"CustomGibbs",
"CustomGibbsState",
"DiscreteGibbs",
"DiscreteGibbsState",
"GIBBS_SITES_KWARG",
"Gibbs",
"GibbsState",
"GibbsUpdateFn",
"ModelWrapper",
"ProposalFn",
"SiteSelector",
"SitesSpec",
"any_changed",
"conditioned",
"discrete_gibbs_sweep",
"discrete_latent_sites",
"discrete_support_sizes",
"latent_sample_sites",
"prototype_trace",
"select_discrete_proposal",
"subsample_plate_sizes",
"with_conditioning",
]
GIBBS_SITES_KWARG: str = "_gibbs_sites"
"""Reserved model keyword through which conditioning values travel."""
ModelWrapper: TypeAlias = Callable[[ModelT], ModelT]
"""Maps a model to a model with the same call signature (conditioning, likelihood estimation)."""
SiteSelector: TypeAlias = Callable[[TraceT], Sequence[str]]
"""Picks site names from a prototype trace, e.g. :func:`discrete_latent_sites`."""
SitesSpec: TypeAlias = Sequence[str] | SiteSelector | None
"""How a block declares its sites: explicit names, a selector, or `None` for the remainder."""
[docs]
class GibbsUpdateFn(Protocol):
"""
Signature of the user callable of :class:`~numpyro.infer.gibbs.CustomGibbs` /
:class:`~numpyro.infer.hmc_gibbs.HMCGibbs`. Called with keywords only; `hmc_sites` holds
the constrained values of every conditioning site (the name is kept for compatibility).
"""
self, *, rng_key: jax.Array, gibbs_sites: SiteValues, hmc_sites: SiteValues
) -> SiteValues: ...
def _conditioned_model(model: ModelT, *args: Any, **kwargs: Any) -> Any:
"""Module-level target of :func:`conditioned` (kept module-level so kernels pickle)."""
values = kwargs.pop(GIBBS_SITES_KWARG, {})
with condition(data=values), substitute(data=values):
return model(*args, **kwargs)
[docs]
def conditioned(model: ModelT) -> ModelT:
"""
Return a model that pops :data:`GIBBS_SITES_KWARG` from its keyword arguments and runs
`model` under `condition(data=values)` and `substitute(data=values)`. Idempotent: wrapping
an already conditioned model returns it unchanged.
:param model: the model.
:return: the conditioned model.
"""
if isinstance(model, partial) and model.func is _conditioned_model:
return model
return partial(_conditioned_model, model)
[docs]
def with_conditioning(
model_kwargs: ModelKwargs | None,
values: SiteValues,
*,
allowed: frozenset[str] | None = None,
) -> ModelKwargs:
"""
Return a copy of `model_kwargs` whose :data:`GIBBS_SITES_KWARG` entry is the existing
entry (if any) extended by `values`. Extending rather than replacing is what makes nested
composites correct: at any depth a block sees exactly the sites it does not own.
:param model_kwargs: keyword arguments of the model.
:param values: conditioning values to add.
:param allowed: when given, raise if a key of `values` is outside this set.
:return: a new keyword argument dict.
"""
if allowed is not None:
extra = set(values) - allowed
if extra:
raise ValueError(f"Cannot condition on non-latent sites {sorted(extra)}.")
model_kwargs = {} if model_kwargs is None else dict(model_kwargs)
model_kwargs[GIBBS_SITES_KWARG] = {
**model_kwargs.get(GIBBS_SITES_KWARG, {}),
**values,
}
return model_kwargs
[docs]
def prototype_trace(
model: ModelT,
rng_key: jax.Array,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> TraceT:
"""
Trace `model` once with values drawn by :func:`~numpyro.infer.initialization.init_to_sample`
(which also handles sites without a `sample` method, such as `ImproperUniform`). Callers
must not store the returned trace on a kernel object (it may hold tracers under
`pmap`/`vmap`); store only static metadata derived from it.
:param model: the model.
:param rng_key: random key used to draw the prototype values.
:param tuple model_args: arguments provided to the model.
:param dict model_kwargs: keyword arguments provided to the model.
:return: the trace.
"""
model_kwargs = {} if model_kwargs is None else model_kwargs
return trace(
substitute(seed(model, rng_key), substitute_fn=init_to_sample)
).get_trace(*model_args, **model_kwargs)
[docs]
def latent_sample_sites(model_trace: TraceT) -> tuple[str, ...]:
"""
Names of unobserved `sample` sites in trace order.
:param model_trace: a model trace, see :func:`prototype_trace`.
:return: the site names.
"""
return tuple(
name
for name, site in model_trace.items()
if site["type"] == "sample" and not site["is_observed"]
)
[docs]
def discrete_latent_sites(model_trace: TraceT) -> tuple[str, ...]:
"""
Unobserved sample sites whose distribution has enumerate support and which are not
marked `infer={"enumerate": "parallel"}`. Usable as a :data:`SitesSpec` selector.
:param model_trace: a model trace, see :func:`prototype_trace`.
:return: the site names.
"""
return tuple(
name
for name, site in model_trace.items()
if site["type"] == "sample"
and not site["is_observed"]
and site["fn"].has_enumerate_support
and site["infer"].get("enumerate", "") != "parallel"
)
[docs]
def discrete_support_sizes(
model_trace: TraceT, sites: Sequence[str]
) -> dict[str, np.ndarray]:
"""
Per-site support sizes broadcast to the site's shape, as static `numpy` arrays.
:param model_trace: a model trace, see :func:`prototype_trace`.
:param sites: names of discrete sites in `model_trace`.
:return: `{site_name: support_sizes}`.
"""
return {
name: np.broadcast_to(
model_trace[name]["fn"].enumerate_support(False).shape[0],
jnp.shape(model_trace[name]["value"]),
)
for name in sites
}
def _flat_support_sizes(model_trace: TraceT, sites: Sequence[str]) -> np.ndarray:
"""Support sizes flattened in :func:`ravel_pytree` leaf order, as a static numpy array.
Built with pure numpy so that it stays concrete when `init` runs under a staging
trace such as :func:`jax.pmap` (`jnp` operations would produce tracers there).
"""
sizes = discrete_support_sizes(model_trace, sites)
return np.concatenate([np.ravel(leaf) for leaf in jax.tree.leaves(sizes)])
def _flat_support_lows(model_trace: TraceT, sites: Sequence[str]) -> np.ndarray:
"""Smallest support value of each flat coordinate, in :func:`ravel_pytree` leaf order.
The discrete proposals propose the indices `0, ..., support_size - 1`; this is the
offset from an index to a value, e.g. `low` for
:class:`~numpyro.distributions.DiscreteUniform`. It is read from `support.lower_bound`
(0 for the boolean support) rather than from the values of `enumerate_support`, which
are traced when `init` runs under :func:`jax.pmap`; :func:`_flat_support_sizes` only
uses the static shape of `enumerate_support`.
"""
lows = {
name: np.broadcast_to(
np.asarray(getattr(model_trace[name]["fn"].support, "lower_bound", 0)),
jnp.shape(model_trace[name]["value"]),
)
for name in sites
}
return np.concatenate([np.ravel(leaf) for leaf in jax.tree.leaves(lows)])
[docs]
def subsample_plate_sizes(model_trace: TraceT) -> dict[str, tuple[int, int]]:
"""
Subsample plates of a trace.
:param model_trace: a model trace, see :func:`prototype_trace`.
:return: `{plate_name: (size, subsample_size)}` for plates with `size > subsample_size`.
"""
return {
name: site["args"]
for name, site in model_trace.items()
if site["type"] == "plate"
and (site["args"][1] is not None)
and site["args"][0] > site["args"][1]
}
[docs]
def any_changed(old: PyTree, new: PyTree) -> jax.Array:
"""
Whether any leaf of two pytrees with the same structure differs.
:param old: a pytree.
:param new: a pytree with the same structure as `old`.
:return: a scalar boolean array.
"""
flags = [
jnp.any(a != b)
for a, b in zip(jax.tree.leaves(old), jax.tree.leaves(new), strict=True)
]
if not flags:
return jnp.array(False)
return reduce(jnp.logical_or, flags)
[docs]
class GibbsState(NamedTuple):
"""
- **z** - dict of the current values of all latent sites, each in the native representation
of the block that owns it (unconstrained for HMC blocks, constrained for
:class:`DiscreteGibbs` and :class:`CustomGibbs` blocks). Written once per step from the
block states; never read back by :meth:`Gibbs.sample`.
- **block_states** - tuple with one state pytree per block, in block order. Source of truth
during a sweep. Addressable from `extra_fields` as `"block_states.<i>.<field>"`.
- **rng_key** - random key for the next step.
"""
z: SiteValues
block_states: tuple[PyTree, ...]
rng_key: jax.Array
def _as_arrays(values: SiteValues) -> SiteValues:
"""Canonicalize values to arrays so that `cond` branches carrying them agree on dtypes."""
return {k: jnp.asarray(v) for k, v in values.items()}
def _or(flags: Sequence[Any]) -> Any:
"""
Logical or of Python bools and traced booleans. Returns a Python bool when the result is
statically known, so that callers can skip emitting a `cond`.
"""
traced = [f for f in flags if not isinstance(f, bool)]
if any(f is True for f in flags):
return True
if not traced:
return False
return reduce(jnp.logical_or, traced)
def _maybe_refresh(
kernel: MCMCKernel,
state: PyTree,
changed: Any,
model_args: ModelArgs,
model_kwargs: ModelKwargs,
) -> PyTree:
if changed is False:
return state
if changed is True:
return kernel.refresh(state, model_args, model_kwargs)
return cond(
changed,
state,
lambda s: kernel.refresh(s, model_args, model_kwargs),
state,
identity,
)
def _has_model(kernel: MCMCKernel) -> bool:
return getattr(kernel, "model", None) is not None
[docs]
class Gibbs(MCMCKernel):
"""
Composite kernel that updates the latent sites of a model block by block. Each block is a
`(kernel, sites)` pair; the block kernel is run on the model conditioned on the current
values of every site it does not own. Blocks are visited in order once per MCMC step.
:param blocks: sequence of `(kernel, sites)`. `kernel` is any
:class:`~numpyro.infer.mcmc.MCMCKernel` that implements
:meth:`~numpyro.infer.mcmc.MCMCKernel.refresh` (and
:meth:`~numpyro.infer.mcmc.MCMCKernel.wrap_model` if it holds a model). `sites` is a
sequence of site names, a callable mapping a prototype trace to site names (for example
:func:`~numpyro.infer.gibbs.discrete_latent_sites`), or `None` for "all latent
sample sites not owned by another block" (allowed for at most one block). All
model-based blocks must be built on the same model callable.
Validation at construction: at least one block; kernels override `refresh`; model-based
kernels share one model; each model-based kernel is rebound once with
``kernel.wrap_model(conditioned)``.
Validation at `init` (errors, never warnings, because the fallbacks inside
:func:`~numpyro.infer.util.initialize_model` are silent): the union of block sites equals
the set of unobserved sample sites minus those marked `enumerate="parallel"`; no discrete
latent is left to an HMC block; blocks are disjoint and non-empty; no site is already
conditioned by an enclosing composite; `init_params` keys lie in the union (unconstrained
values for HMC blocks, constrained values otherwise); the model has no subsample plates
(use :class:`~numpyro.infer.hmc_gibbs.HMCECS`); HMC blocks have no value-dependent
supports.
.. note:: Each HMC block adapts its step size and mass matrix on its own conditional, so
blocks should leave `find_heuristic_step_size=False` (the heuristic binds the potential
to the initial conditioning). Strongly correlated continuous sites belong in one HMC
block.
**Example**
.. doctest::
>>> from jax import random
>>> import jax.numpy as jnp
>>> import numpyro
>>> import numpyro.distributions as dist
>>> from numpyro.infer import MCMC, NUTS, Gibbs, DiscreteGibbs, CustomGibbs
>>> from numpyro.infer.gibbs import discrete_latent_sites
...
>>> def model(probs, locs):
... c = numpyro.sample("c", dist.Categorical(probs))
... x = numpyro.sample("x", dist.Normal(locs[c], 0.5))
... y = numpyro.sample("y", dist.Normal(0.0, 2.0))
... numpyro.sample("obs", dist.Normal(x + y, 1.0), obs=jnp.array([1.0]))
...
>>> def gibbs_fn(rng_key, gibbs_sites, hmc_sites):
... x = hmc_sites["x"]
... return {"y": dist.Normal(0.8 * (1 - x), jnp.sqrt(0.8)).sample(rng_key)}
...
>>> kernel = Gibbs([
... (DiscreteGibbs(model), discrete_latent_sites),
... (CustomGibbs(gibbs_fn), ["y"]),
... (NUTS(model), None),
... ])
>>> mcmc = MCMC(kernel, num_warmup=100, num_samples=100, progress_bar=False)
>>> mcmc.run(random.key(0), jnp.array([0.15, 0.3, 0.3, 0.25]), jnp.array([-2.0, 0.0, 2.0, 4.0]))
>>> mcmc.print_summary() # doctest: +SKIP
"""
_state_cls: type[GibbsState] = GibbsState
sample_field: str = "z"
def __init__(self, blocks: Sequence[tuple[MCMCKernel, SitesSpec]]) -> None:
blocks = list(blocks)
if not blocks:
raise ValueError("Gibbs requires at least one block.")
kernels, specs = [], []
for block in blocks:
if not (isinstance(block, tuple) and len(block) == 2):
raise ValueError("Each block must be a `(kernel, sites)` pair.")
kernel, spec = block
if not isinstance(kernel, MCMCKernel):
raise ValueError(f"{kernel!r} is not an MCMCKernel.")
if type(kernel).refresh is MCMCKernel.refresh:
raise ValueError(
f"{type(kernel).__name__} does not implement `refresh` and cannot be "
"used as a block of Gibbs."
)
if hasattr(kernel, "model") and kernel.model is None:
raise ValueError(
"Kernels built from a potential function cannot be blocks of Gibbs."
)
if spec is not None and not callable(spec):
spec = tuple(spec)
if not spec or not all(isinstance(s, str) for s in spec):
raise ValueError(
"`sites` must be a non-empty sequence of site names, a callable "
"or None."
)
kernels.append(kernel)
specs.append(spec)
if sum(spec is None for spec in specs) > 1:
raise ValueError("At most one block can use `None` for its sites.")
models = [kernel.model for kernel in kernels if _has_model(kernel)]
if not models:
raise ValueError("Gibbs requires at least one block built on a model.")
if any(model != models[0] for model in models[1:]):
raise ValueError("All model-based blocks must share the same model.")
self._model = models[0]
self._kernels = tuple(
kernel.wrap_model(conditioned) if _has_model(kernel) else kernel
for kernel in kernels
)
self._specs = tuple(specs)
# static metadata resolved at `init`
self._sites: tuple[tuple[str, ...], ...] = ()
self._has_deterministic = False
self._sample_fn = None
@property
def model(self) -> ModelT | None:
"""The shared, unwrapped model of the model-based blocks."""
return self._model
@property
def blocks(self) -> tuple[tuple[MCMCKernel, SitesSpec], ...]:
"""The `(kernel, sites)` pairs; kernels are the conditioned copies actually run."""
return tuple(zip(self._kernels, self._specs))
@property
def default_fields(self) -> tuple[str, ...]:
return ("z",)
[docs]
def get_diagnostics_str(self, state: GibbsState) -> str:
parts = [
kernel.get_diagnostics_str(block_state)
for kernel, block_state in zip(self._kernels, state.block_states)
]
return " | ".join(part for part in parts if part)
def _resolve_partition(
self, model_trace: Any, enclosing: frozenset[str]
) -> tuple[tuple[str, ...], ...]:
latent = tuple(
name
for name in latent_sample_sites(model_trace)
if model_trace[name]["infer"].get("enumerate", "") != "parallel"
)
latent_set = frozenset(latent)
sites: list[tuple[str, ...] | None] = []
for spec in self._specs:
if spec is None:
sites.append(None)
continue
names = tuple(spec(model_trace)) if callable(spec) else spec
unknown = [name for name in names if name not in latent_set]
if unknown:
hint = (
" (already conditioned by an enclosing kernel)"
if any(name in enclosing for name in unknown)
else ""
)
raise ValueError(
f"Sites {unknown} are not latent sample sites of the model{hint}."
)
sites.append(names)
owned = [name for names in sites if names is not None for name in names]
duplicates = sorted({name for name in owned if owned.count(name) > 1})
if duplicates:
raise ValueError(f"Sites {duplicates} are owned by more than one block.")
remainder = tuple(name for name in latent if name not in owned)
# the remainder block may own no sites (for example an HMC block on a model whose
# latent sites are all discrete); explicit blocks may not
if None in sites:
sites[sites.index(None)] = remainder
elif remainder:
raise ValueError(
f"Latent sites {list(remainder)} are not owned by any block; add a block "
"or use `None` as the sites of one block."
)
resolved = tuple(names if names is not None else () for names in sites)
for kernel, spec, names in zip(self._kernels, self._specs, resolved):
if not names and spec is not None:
raise ValueError(f"Block {type(kernel).__name__} owns no sites.")
if isinstance(kernel, HMC):
discrete = [
name
for name in names
if model_trace[name]["fn"].support.is_discrete
]
if discrete:
raise ValueError(
f"Discrete latent sites {discrete} cannot be sampled by an HMC "
"block; use DiscreteGibbs or mark them with "
"`infer={'enumerate': 'parallel'}`."
)
return resolved
@staticmethod
def _block_trace(model_trace: Any, names: Sequence[str]) -> Any:
"""The trace restricted to the block's sample sites (other site types are kept)."""
return OrderedDict(
(name, site)
for name, site in model_trace.items()
if site["type"] != "sample" or name in names
)
def _split_init_params(
self, init_params: SiteValues | None
) -> tuple[SiteValues | None, ...]:
if not init_params:
return tuple(None for _ in self._kernels)
owned = {name for names in self._sites for name in names}
unknown = sorted(set(init_params) - owned)
if unknown:
raise ValueError(f"`init_params` has unknown sites {unknown}.")
return tuple(
{name: init_params[name] for name in names if name in init_params} or None
for names in self._sites
)
[docs]
def init(
self,
rng_key: jax.Array,
num_warmup: int,
init_params: SiteValues | None,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> GibbsState:
if not is_prng_key(rng_key):
raise ValueError(
"Gibbs only supports a single random key; for multiple chains use "
'`chain_method="parallel"`, `chain_method="sequential"` or a callable '
"chain method such as `jax.vmap`."
)
model_kwargs = {} if model_kwargs is None else dict(model_kwargs)
enclosing = frozenset(model_kwargs.get(GIBBS_SITES_KWARG, {}))
rng_key, key_trace = random.split(rng_key)
model_trace = prototype_trace(
conditioned(self._model), key_trace, model_args, model_kwargs
)
if subsample_plate_sizes(model_trace):
raise ValueError(
"Gibbs does not support models with subsample plates; use HMCECS."
)
self._sites = self._resolve_partition(model_trace, enclosing)
self._has_deterministic = any(
site["type"] == "deterministic" for site in model_trace.values()
)
block_init_params = self._split_init_params(init_params)
# constrained initial values of every latent site, used to condition the blocks
constrained = {
name: model_trace[name]["value"] for names in self._sites for name in names
}
for kernel, names, params in zip(self._kernels, self._sites, block_init_params):
if isinstance(kernel, HMC):
transforms = _transforms_from_trace(
self._block_trace(model_trace, names), raise_warnings=False
)
if transforms.dynamic_support:
raise ValueError(
f"The supports of sites {list(names)} depend on other sites; "
"Gibbs does not support value-dependent supports across blocks."
)
if params:
constrained.update(transform_fn(transforms.inv_transforms, params))
elif params:
constrained.update(params)
block_states = []
for i, (kernel, names, params) in enumerate(
zip(self._kernels, self._sites, block_init_params)
):
siblings = {k: v for k, v in constrained.items() if k not in names}
kwargs_i = with_conditioning(model_kwargs, siblings)
if not isinstance(kernel, HMC):
params = {**{k: constrained[k] for k in names}, **(params or {})}
rng_key, key_i = random.split(rng_key)
state_i = kernel.init(key_i, num_warmup, params, model_args, kwargs_i)
block_states.append(state_i)
z_i = getattr(state_i, kernel.sample_field)
constrained_i = kernel.get_constrain_fn(model_args, kwargs_i)(z_i)
constrained.update({k: constrained_i[k] for k in names})
# blocks were initialized against prototype values of later blocks; refresh them
for i in range(len(self._kernels) - 1):
siblings = {k: v for k, v in constrained.items() if k not in self._sites[i]}
kwargs_i = with_conditioning(model_kwargs, siblings)
block_states[i] = self._kernels[i].refresh(
block_states[i], model_args, kwargs_i
)
z = self._merge_z(block_states)
self._sample_fn = self._sample_one
return self._state_cls(z, tuple(block_states), rng_key)
def _merge_z(self, block_states: Sequence[PyTree]) -> SiteValues:
z = {}
for kernel, names, block_state in zip(self._kernels, self._sites, block_states):
z_i = getattr(block_state, kernel.sample_field)
z.update({k: z_i[k] for k in names})
return z
def _sample_one(
self,
state: GibbsState,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> GibbsState:
model_kwargs = {} if model_kwargs is None else model_kwargs
num_blocks = len(self._kernels)
block_states = list(state.block_states)
z_blocks = [
getattr(block_state, kernel.sample_field)
for kernel, block_state in zip(self._kernels, block_states)
]
# constrained values of each block's own sites, for conditioning its siblings
constrained = [
{
k: v
for k, v in kernel.get_constrain_fn(model_args, model_kwargs)(
z_i
).items()
if k in names
}
for kernel, names, z_i in zip(self._kernels, self._sites, z_blocks)
]
def kwargs_for(i: int) -> ModelKwargs:
siblings = {}
for j in range(num_blocks):
if j != i:
siblings.update(constrained[j])
return with_conditioning(model_kwargs, siblings)
moved: list[Any] = [False] * num_blocks
for i, (kernel, names) in enumerate(zip(self._kernels, self._sites)):
kwargs_i = kwargs_for(i)
# siblings visited earlier in this sweep may have moved since the last refresh
block_states[i] = _maybe_refresh(
kernel, block_states[i], _or(moved[:i]), model_args, kwargs_i
)
block_states[i] = kernel.sample(block_states[i], model_args, kwargs_i)
z_new = getattr(block_states[i], kernel.sample_field)
moved[i] = any_changed(z_blocks[i], z_new)
constrained[i] = {
k: v
for k, v in kernel.get_constrain_fn(model_args, kwargs_i)(z_new).items()
if k in names
}
# siblings visited later in this sweep may have moved; refresh against the final values
for i in range(num_blocks - 1):
block_states[i] = _maybe_refresh(
self._kernels[i],
block_states[i],
_or(moved[i + 1 :]),
model_args,
kwargs_for(i),
)
rng_key, _ = random.split(state.rng_key)
return state._replace(
z=self._merge_z(block_states),
block_states=tuple(block_states),
rng_key=rng_key,
)
[docs]
def sample(
self,
state: GibbsState,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> GibbsState:
"""
Run one sweep over the blocks from the given :class:`GibbsState` and return the
resulting :class:`GibbsState`.
:param GibbsState state: the current state.
:param tuple model_args: arguments provided to the model.
:param dict model_kwargs: keyword arguments provided to the model.
:return: the next state.
"""
assert self._sample_fn is not None, "`init` must be called before `sample`."
return self._sample_fn(state, model_args, model_kwargs)
[docs]
def refresh(
self,
state: GibbsState,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> GibbsState:
"""Identity: :meth:`sample` refreshes each block against the current conditioning."""
return state
[docs]
def wrap_model(self, wrapper: ModelWrapper) -> "Gibbs":
"""New composite with `wrapper` applied to every model-based block (nesting)."""
kernel = copy.copy(self)
kernel._model = wrapper(self._model)
kernel._kernels = tuple(
block.wrap_model(wrapper) if _has_model(block) else block
for block in self._kernels
)
kernel._sites = ()
kernel._sample_fn = None
return kernel
[docs]
def get_constrain_fn(
self,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> ConstrainFn:
"""Constrain each block's sites with the block's own constrain function (no replay)."""
if not self._sites:
return identity
def fn(z: SiteValues) -> SiteValues:
out = {}
for kernel, names in zip(self._kernels, self._sites):
z_i = {k: z[k] for k in names}
constrained_i = kernel.get_constrain_fn(model_args, model_kwargs)(z_i)
out.update({k: constrained_i[k] for k in names})
return out
return fn
[docs]
def postprocess_fn(
self,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> ConstrainFn:
"""
Constrain each block's sites with the block's own constrain function, then, only if
the model has `deterministic` sites, replay the model once with all constrained values
substituted to collect them.
"""
if not self._sites:
return identity
constrain = self.get_constrain_fn(model_args, model_kwargs)
if not self._has_deterministic:
return constrain
model_kwargs = {} if model_kwargs is None else model_kwargs
def fn(z: SiteValues) -> SiteValues:
constrained = constrain(z)
model = substitute(
seed(conditioned(self._model), random.key(0)), data=constrained
)
model_trace = trace(model).get_trace(*model_args, **model_kwargs)
deterministic = {
name: site["value"]
for name, site in model_trace.items()
if site["type"] == "deterministic"
}
return {**constrained, **deterministic}
return fn
def __getstate__(self) -> dict[str, Any]:
state = self.__dict__.copy()
state["_sample_fn"] = None
return state
[docs]
class CustomGibbsState(NamedTuple):
"""
- **z** - dict of the block's current (constrained) values.
- **rng_key** - random key for the next step.
"""
z: SiteValues
rng_key: jax.Array
[docs]
class CustomGibbs(MCMCKernel):
"""
Block kernel that delegates the update to a user callable. The callable receives the
current values of the block's sites and the constrained values of all conditioning sites
and returns new values for the block's sites (it must sample from the conditional;
correctness is the user's responsibility, as with
:class:`~numpyro.infer.hmc_gibbs.HMCGibbs`). Only usable as a block of :class:`Gibbs`.
:param gibbs_fn: called as `gibbs_fn(rng_key=..., gibbs_sites=..., hmc_sites=...)`; the
keyword names are kept for compatibility with existing `HMCGibbs` users, and
`hmc_sites` holds all conditioning sites (not only HMC ones). The returned dict must
have exactly the block's site names as keys.
"""
sample_field: str = "z"
def __init__(self, gibbs_fn: GibbsUpdateFn) -> None:
if not callable(gibbs_fn):
raise ValueError("gibbs_fn must be a callable")
self._gibbs_fn = gibbs_fn
[docs]
def init(
self,
rng_key: jax.Array,
num_warmup: int,
init_params: SiteValues | None,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> CustomGibbsState:
"""`init_params` are the block's initial (constrained) values, supplied by the composite."""
if not init_params:
raise ValueError(
"CustomGibbs requires initial values; use it as a block of Gibbs."
)
return CustomGibbsState(_as_arrays(init_params), rng_key)
[docs]
def sample(
self,
state: CustomGibbsState,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> CustomGibbsState:
"""Reads the conditioning values from `model_kwargs[GIBBS_SITES_KWARG]`."""
model_kwargs = {} if model_kwargs is None else model_kwargs
rng_key, key_update = random.split(state.rng_key)
z_new = self._gibbs_fn(
rng_key=key_update,
gibbs_sites=state.z,
hmc_sites=model_kwargs.get(GIBBS_SITES_KWARG, {}),
)
if set(z_new) != set(state.z):
raise ValueError(
f"gibbs_fn must return values for exactly the sites {sorted(state.z)}, "
f"got {sorted(z_new)}."
)
return state._replace(z=_as_arrays(z_new), rng_key=rng_key)
[docs]
def refresh(
self,
state: CustomGibbsState,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> CustomGibbsState:
"""Identity: nothing is cached."""
return state
[docs]
def wrap_model(self, wrapper: ModelWrapper) -> "CustomGibbs":
"""Returns `self`: there is no model."""
return self
[docs]
def get_constrain_fn(
self,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> Callable:
"""Identity: the block's values are already constrained."""
return identity
# Discrete proposals. Each is called as
# `(rng_key, z, pe, potential_fn, idx, support_size) -> (rng_key, z_new, pe_new, log_accept_ratio)`
# where `idx` is the flat coordinate of `z` to update and `support_size` its support size.
ProposalFn: TypeAlias = Callable[
[jax.Array, SiteValues, jax.Array, PotentialFn, jax.Array, jax.Array],
tuple[jax.Array, SiteValues, jax.Array, jax.Array],
]
"""`(rng_key, z, pe, potential_fn, idx, support_size) -> (rng_key, z_new, pe_new, log_accept_ratio)`.
The proposals work with indices: they propose `z[idx]` in `0, ..., support_size - 1`. For
supports that do not start at 0, such as `DiscreteUniform(low, high)`, shift the values, e.g.
with the `support_lows_flat` argument of :func:`discrete_gibbs_sweep`."""
def _discrete_gibbs_proposal_body_fn(
z_init_flat, unravel_fn, pe_init, potential_fn, idx, i, val
):
rng_key, z, pe, log_weight_sum = val
rng_key, rng_transition = random.split(rng_key)
proposal = jnp.where(i >= z_init_flat[idx], i + 1, i)
z_new_flat = z_init_flat.at[idx].set(proposal)
z_new = unravel_fn(z_new_flat)
pe_new = potential_fn(z_new)
log_weight_new = pe_init - pe_new
# Handles the NaN case...
log_weight_new = jnp.where(jnp.isfinite(log_weight_new), log_weight_new, -jnp.inf)
# transition_prob = e^weight_new / (e^weight_logsumexp + e^weight_new)
transition_prob = expit(log_weight_new - log_weight_sum)
z, pe = cond(
random.bernoulli(rng_transition, transition_prob),
(z_new, pe_new),
identity,
(z, pe),
identity,
)
log_weight_sum = jnp.logaddexp(log_weight_new, log_weight_sum)
return rng_key, z, pe, log_weight_sum
def _discrete_gibbs_proposal(
rng_key: jax.Array,
z_discrete: SiteValues,
pe: jax.Array,
potential_fn: PotentialFn,
idx: jax.Array,
support_size: jax.Array,
) -> tuple[jax.Array, SiteValues, jax.Array, jax.Array]:
# idx: current index of `z_discrete_flat` to update
# support_size: support size of z_discrete at the index idx
z_discrete_flat, unravel_fn = ravel_pytree(z_discrete)
# Here we loop over the support of z_flat[idx] to get z_new
# Note: we can't vmap potential_fn over all proposals and sample from the conditional
# categorical distribution because support_size is a traced value, i.e. its value
# might change across different discrete variables;
# so here we will loop over all proposals and use an online scheme to sample from
# the conditional categorical distribution
body_fn = partial(
_discrete_gibbs_proposal_body_fn,
z_discrete_flat,
unravel_fn,
pe,
potential_fn,
idx,
)
init_val = (rng_key, z_discrete, pe, jnp.array(0.0))
rng_key, z_new, pe_new, _ = fori_loop(0, support_size - 1, body_fn, init_val)
log_accept_ratio = jnp.array(0.0)
return rng_key, z_new, pe_new, log_accept_ratio
def _discrete_modified_gibbs_proposal(
rng_key: jax.Array,
z_discrete: SiteValues,
pe: jax.Array,
potential_fn: PotentialFn,
idx: jax.Array,
support_size: jax.Array,
stay_prob: float = 0.0,
) -> tuple[jax.Array, SiteValues, jax.Array, jax.Array]:
assert isinstance(stay_prob, float) and stay_prob >= 0.0 and stay_prob < 1
z_discrete_flat, unravel_fn = ravel_pytree(z_discrete)
body_fn = partial(
_discrete_gibbs_proposal_body_fn,
z_discrete_flat,
unravel_fn,
pe,
potential_fn,
idx,
)
# like gibbs_step but here, weight of the current value is 0
init_val = (rng_key, z_discrete, pe, jnp.array(-jnp.inf))
rng_key, z_new, pe_new, log_weight_sum = fori_loop(
0, support_size - 1, body_fn, init_val
)
rng_key, rng_stay = random.split(rng_key)
z_new, pe_new = cond(
random.bernoulli(rng_stay, stay_prob),
(z_discrete, pe),
identity,
(z_new, pe_new),
identity,
)
# here we calculate the MH correction: (1 - P(z)) / (1 - P(z_new))
# where 1 - P(z) ~ weight_sum
# and 1 - P(z_new) ~ 1 + weight_sum - z_new_weight
log_accept_ratio = log_weight_sum - jnp.log(
jnp.exp(log_weight_sum) - jnp.expm1(pe - pe_new)
)
return rng_key, z_new, pe_new, log_accept_ratio
def _discrete_rw_proposal(
rng_key: jax.Array,
z_discrete: SiteValues,
pe: jax.Array,
potential_fn: PotentialFn,
idx: jax.Array,
support_size: jax.Array,
) -> tuple[jax.Array, SiteValues, jax.Array, jax.Array]:
rng_key, rng_proposal = random.split(rng_key, 2)
z_discrete_flat, unravel_fn = ravel_pytree(z_discrete)
proposal = random.randint(rng_proposal, (), minval=0, maxval=support_size)
z_new_flat = z_discrete_flat.at[idx].set(proposal)
z_new = unravel_fn(z_new_flat)
pe_new = potential_fn(z_new)
log_accept_ratio = pe - pe_new
return rng_key, z_new, pe_new, log_accept_ratio
def _discrete_modified_rw_proposal(
rng_key: jax.Array,
z_discrete: SiteValues,
pe: jax.Array,
potential_fn: PotentialFn,
idx: jax.Array,
support_size: jax.Array,
stay_prob: float = 0.0,
) -> tuple[jax.Array, SiteValues, jax.Array, jax.Array]:
assert isinstance(stay_prob, float) and stay_prob >= 0.0 and stay_prob < 1
rng_key, rng_proposal, rng_stay = random.split(rng_key, 3)
z_discrete_flat, unravel_fn = ravel_pytree(z_discrete)
i = random.randint(rng_proposal, (), minval=0, maxval=support_size - 1)
proposal = jnp.where(i >= z_discrete_flat[idx], i + 1, i)
proposal = jnp.where(
random.bernoulli(rng_stay, stay_prob), z_discrete_flat[idx], proposal
)
z_new_flat = z_discrete_flat.at[idx].set(proposal)
z_new = unravel_fn(z_new_flat)
pe_new = potential_fn(z_new)
log_accept_ratio = pe - pe_new
return rng_key, z_new, pe_new, log_accept_ratio
[docs]
def select_discrete_proposal(random_walk: bool, modified: bool) -> ProposalFn:
"""
Pick the discrete proposal: the exact conditional (Gibbs) or a uniform random walk, each
optionally in Liu's modified form that never proposes the current value.
:param bool random_walk: uniform proposals over the support instead of the conditional.
:param bool modified: use the modified (Metropolised) proposal.
"""
if random_walk:
if modified:
return partial(_discrete_modified_rw_proposal, stay_prob=0.0)
return _discrete_rw_proposal
if modified:
return partial(_discrete_modified_gibbs_proposal, stay_prob=0.0)
return _discrete_gibbs_proposal
def _offset_proposal(
proposal_fn: ProposalFn, support_lows_flat: np.ndarray
) -> ProposalFn:
"""
Wrap `proposal_fn`, which proposes values in `0, ..., support_size - 1`, for supports
that start at `support_lows_flat` instead, such as `DiscreteUniform(low, high)`.
"""
if not np.any(support_lows_flat):
return proposal_fn
def offset_proposal_fn(
rng_key: jax.Array,
z: SiteValues,
pe: jax.Array,
potential_fn: PotentialFn,
idx: jax.Array,
support_size: jax.Array,
) -> tuple[jax.Array, SiteValues, jax.Array, jax.Array]:
z_flat, unravel_fn = ravel_pytree(z)
lows = jnp.asarray(support_lows_flat, dtype=z_flat.dtype)
def shifted_potential_fn(z_shifted: SiteValues) -> jax.Array:
return potential_fn(unravel_fn(ravel_pytree(z_shifted)[0] + lows))
rng_key, z_new, pe_new, log_accept_ratio = proposal_fn(
rng_key,
unravel_fn(z_flat - lows),
pe,
shifted_potential_fn,
idx,
support_size,
)
z_new = unravel_fn(ravel_pytree(z_new)[0] + lows)
return rng_key, z_new, pe_new, log_accept_ratio
return offset_proposal_fn
[docs]
def discrete_gibbs_sweep(
rng_key: jax.Array,
z: SiteValues,
potential_energy: jax.Array,
potential_fn: PotentialFn,
support_sizes_flat: jax.Array,
proposal_fn: ProposalFn,
support_lows_flat: np.ndarray | jax.Array | None = None,
) -> tuple[SiteValues, jax.Array]:
"""
One sweep over the flat discrete coordinates of `z` in a random order, each coordinate
updated with `proposal_fn` and Metropolis corrected.
:param rng_key: random key.
:param z: current discrete values.
:param potential_energy: potential energy at `z`.
:param potential_fn: potential energy as a function of the discrete values.
:param support_sizes_flat: support size of each flat coordinate, in `ravel_pytree` order.
:param proposal_fn: a discrete proposal, see :func:`select_discrete_proposal`.
:param support_lows_flat: smallest support value of each flat coordinate, in
`ravel_pytree` order. The proposals work with the indices
`0, ..., support_size - 1`, so `z` is shifted by these values once per sweep.
`None` (default) means that every support starts at 0.
:return: the new values and their potential energy.
"""
if support_lows_flat is not None:
z_flat, unravel_fn = ravel_pytree(z)
lows = jnp.asarray(support_lows_flat, dtype=z_flat.dtype)
def index_potential_fn(z_idx: SiteValues) -> jax.Array:
return potential_fn(unravel_fn(ravel_pytree(z_idx)[0] + lows))
z_idx, pe = discrete_gibbs_sweep(
rng_key,
unravel_fn(z_flat - lows),
potential_energy,
index_potential_fn,
support_sizes_flat,
proposal_fn,
)
return unravel_fn(ravel_pytree(z_idx)[0] + lows), pe
num_discretes = support_sizes_flat.shape[0]
rng_key, rng_permute = random.split(rng_key)
idxs = random.permutation(rng_permute, jnp.arange(num_discretes))
def body_fn(i, val):
idx = idxs[i]
support_size = support_sizes_flat[idx]
rng_key, z, pe = val
rng_key, z_new, pe_new, log_accept_ratio = proposal_fn(
rng_key, z, pe, potential_fn, idx, support_size
)
rng_key, rng_accept = random.split(rng_key)
# u ~ Uniform(0, 1), u < accept_ratio => -log(u) > -log_accept_ratio
# and -log(u) ~ exponential(1)
z, pe = cond(
random.exponential(rng_accept) > -log_accept_ratio,
(z_new, pe_new),
identity,
(z, pe),
identity,
)
return rng_key, z, pe
init_val = (rng_key, z, potential_energy)
_, z, pe = fori_loop(0, num_discretes, body_fn, init_val)
return z, pe
[docs]
class DiscreteGibbsState(NamedTuple):
"""
- **z** - dict of the current discrete values.
- **potential_energy** - potential energy at `z` under the current conditioning (the block's
own potential, which differs from an HMC block's by a constant and cannot be handed
across blocks).
- **rng_key** - random key for the next step.
"""
z: SiteValues
potential_energy: jax.Array
rng_key: jax.Array
[docs]
class DiscreteGibbs(MCMCKernel):
"""
Metropolis / Gibbs updates of the discrete latent sites of a model, one flat coordinate at
a time in a random order. Usable standalone on a purely discrete model, or as a block of
:class:`Gibbs`.
The potential is the negative log joint of the model at the block's (constrained) values,
with every other latent site fixed to the conditioning values passed through the model
keyword arguments; sites marked `infer={"enumerate": "parallel"}` are marginalized exactly
as in HMC.
:param model: the model.
:param bool random_walk: uniform proposals over the support instead of the exact
conditional.
:param bool modified: Liu's modified (Metropolised) proposal that never proposes the
current value.
**References:**
1. *Peskun's theorem and a modified discrete-state Gibbs sampler*, Liu, J. S. (1996)
"""
sample_field: str = "z"
def __init__(
self, model: ModelT, *, random_walk: bool = False, modified: bool = False
) -> None:
self._model = model
self._random_walk = random_walk
self._modified = modified
self._proposal_fn = select_discrete_proposal(random_walk, modified)
# static metadata resolved at `init`
self._sites: tuple[str, ...] | None = None
self._support_sizes_flat: np.ndarray | None = None
self._support_lows_flat: np.ndarray | None = None
self._enum = False
# closes over trace values, rebuilt at every `init`
self._prepared_model: ModelT | None = None
@property
def model(self) -> ModelT:
return self._model
[docs]
def get_potential_fn(
self,
model_args: ModelArgs = (),
model_kwargs: ModelKwargs | None = None,
) -> PotentialFn:
"""Potential over the block's discrete values for the given arguments and conditioning."""
if self._prepared_model is None:
raise RuntimeError(
"`get_potential_fn` requires the kernel to be initialized; run `init` first."
)
prepared_model, enum = self._prepared_model, self._enum
def potential_fn(z: SiteValues) -> jax.Array:
return potential_energy(
prepared_model,
model_args,
with_conditioning(model_kwargs, z),
{},
enum=enum,
)
return potential_fn
[docs]
def init(
self,
rng_key: jax.Array,
num_warmup: int,
init_params: SiteValues | None,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> DiscreteGibbsState:
model_kwargs = {} if model_kwargs is None else dict(model_kwargs)
rng_key, key_trace = random.split(rng_key)
model_trace = prototype_trace(
conditioned(self._model), key_trace, model_args, model_kwargs
)
sites = discrete_latent_sites(model_trace)
if not sites:
raise ValueError(
"Cannot detect any discrete latent variables in the model."
)
others = [
name
for name in latent_sample_sites(model_trace)
if name not in sites
and model_trace[name]["infer"].get("enumerate", "") != "parallel"
]
if others:
raise ValueError(
f"DiscreteGibbs cannot sample the latent sites {others}; condition on them "
"or use DiscreteGibbs as a block of Gibbs."
)
self._sites = sites
self._support_sizes_flat = _flat_support_sizes(model_trace, sites)
self._support_lows_flat = _flat_support_lows(model_trace, sites)
self._enum = any(
site["type"] == "sample"
and not site["is_observed"]
and site["infer"].get("enumerate", "") == "parallel"
for site in model_trace.values()
)
self._prepared_model = _prepare_model_for_potential(
conditioned(self._model), model_trace, enum=self._enum
)
init_params = {} if init_params is None else init_params
z = _as_arrays(
{name: init_params.get(name, model_trace[name]["value"]) for name in sites}
)
pe = self.get_potential_fn(model_args, model_kwargs)(z)
return DiscreteGibbsState(z, jnp.asarray(pe), rng_key)
[docs]
def sample(
self,
state: DiscreteGibbsState,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> DiscreteGibbsState:
"""One :func:`~numpyro.infer.gibbs.discrete_gibbs_sweep` with the selected proposal."""
assert (
self._support_sizes_flat is not None and self._support_lows_flat is not None
), "`init` must be called before `sample`."
rng_key, key_sweep = random.split(state.rng_key)
z, pe = discrete_gibbs_sweep(
key_sweep,
state.z,
state.potential_energy,
self.get_potential_fn(model_args, model_kwargs),
jnp.asarray(self._support_sizes_flat),
self._proposal_fn,
self._support_lows_flat if np.any(self._support_lows_flat) else None,
)
return state._replace(z=z, potential_energy=pe, rng_key=rng_key)
[docs]
def refresh(
self,
state: DiscreteGibbsState,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> DiscreteGibbsState:
"""Recompute `potential_energy` at `state.z` (one model evaluation)."""
pe = self.get_potential_fn(model_args, model_kwargs)(state.z)
return state._replace(potential_energy=jnp.asarray(pe))
[docs]
def wrap_model(self, wrapper: ModelWrapper) -> "DiscreteGibbs":
kernel = copy.copy(self)
kernel._model = wrapper(self._model)
kernel._sites = None
kernel._support_sizes_flat = None
kernel._support_lows_flat = None
kernel._prepared_model = None
return kernel
[docs]
def get_constrain_fn(
self,
model_args: ModelArgs,
model_kwargs: ModelKwargs | None,
) -> Callable:
"""Identity: discrete values are already constrained."""
return identity
def __getstate__(self) -> dict[str, Any]:
state = self.__dict__.copy()
state["_prepared_model"] = None
return state