Skip to content

periodic

Adapters that translate Jim's periodic-parameter spec into the form each sampler backend expects.

periodic_index = {1: (0.0, 2 * jnp.pi), ...}   # key = dimension index

Each backend wants a different shape: flowMC already accepts an index-keyed dict directly; BlackJAX NS AW needs a stepper function on flat arrays; BlackJAX NSS needs a proposal factory with the same interface as blackjax.ns.nss.covariance_proposal; BlackJAX SMC needs a re-centring map onto the real line. The adapters below handle those conversions.

All adapters operate on flat JAX arrays of shape (n_dims,).

Functions:

Name Description
to_prior_space_proposal

Return a BlackJAX NSS proposal factory that wraps periodic prior-space dims.

to_recentring_map

Re-centring map for BlackJAX SMC (sampling space to the real line).

to_unit_cube_stepper

Stepper function for BlackJAX NS AW (unit-cube space).

to_prior_space_proposal(periodic_index: Optional[dict[int, tuple[float, float]]], n_dims: int, sample_direction_from_covariance: Callable) -> Callable ¤

Return a BlackJAX NSS proposal factory that wraps periodic prior-space dims.

Has the same interface as blackjax.ns.nss.covariance_proposal: proposal(init_state_fn, loglikelihood_0, cov) -> proposal_generator.

to_recentring_map(periodic_index: Optional[dict[int, tuple[float, float]]], n_dims: int) -> tuple[Callable, Callable, Callable] ¤

Re-centring map for BlackJAX SMC (sampling space to the real line).

For each periodic dimension, the cut goes in the middle of the widest arc that holds no particle. The value is rotated so that the cut sits at the ends of the period, then mapped to the real line with a logit. The map is a bijection for fixed cuts, so an MCMC move in u is exact once the log-Jacobian is included. Other dimensions pass through unchanged.

Returns:

Type Description
Callable

(cuts_fn, forward_fn, inverse_fn) with

Callable
  • cuts_fn(particles) -> cuts, particles of shape (n, n_dims) and cuts of shape (n_dims,) (0 for non-periodic dimensions);
Callable
  • forward_fn(x, cuts) -> u;
tuple[Callable, Callable, Callable]
  • inverse_fn(u, cuts) -> (x, log_det), with log_det = log|dx/du|.

to_unit_cube_stepper(periodic_index: Optional[list[int]], n_dims: int) -> Callable ¤

Stepper function for BlackJAX NS AW (unit-cube space).

Signature: stepper_fn(position, direction, step_size) -> new_position

periodic_index is a list of dimension indices to wrap; bounds are implicit because NS AW always operates in [0, 1]^n_dims, so wrapping is always mod(pos + step_size * dir, 1.0).