mod momentum

module momentum

Momentum kernels for HMC: standard Gaussian (q=1) and q-Gaussian (Tsallis q in (1, 1+2/dim); doi:10.1007/BF01016429).

q-Gaussian momentum unifies HMC with the GSA Tsallis hierarchy (doi:10.1016/S0378-4371(96)00271-3). The kinetic term is the logarithmic Tsallis form over the squared momentum norm, and the density is the corresponding multivariate q-Gaussian.

q -> 1+ recovers Gaussian momentum. q in (1, 1 + 2/dim) gives heavy-tailed momentum draws, which is exactly what HMC needs to escape local cups on multimodal objectives (Rastrigin / Schwefel). At q approaching 1 + 2/dim, the q-Gaussian normalisation diverges; the constructor asserts the valid range.

Sampling uses the standard Student-t / q-Gaussian representation: draw z from N(0, I_d), draw g from Gamma(alpha, 1) with alpha = 1/(q-1) - d/2, then set p = z * sqrt(1 / ((q-1) * g)).

Traits

trait Momentum

Generic momentum kernel for HMC. Implementors define the sampling distribution and the kinetic energy + its gradient w.r.t. p.

Functions

fn dk_dp(&self, p: &Array1<f64>) -> Array1<f64>

Gradient of K w.r.t. p. Used in the leapfrog drift step.

fn kinetic(&self, p: &Array1<f64>) -> f64

Kinetic energy K(p). Used in the Hamiltonian computation.

fn sample<R: Rng>(&self, dim: usize, rng: &mut R) -> Array1<f64>

Draw a fresh momentum vector.

fn uturn(&self, x_left: &Array1<f64>, p_left: &Array1<f64>, x_right: &Array1<f64>, p_right: &Array1<f64>) -> bool

NUTS U-turn termination predicate: returns true iff the trajectory has reversed direction between the leftmost and rightmost states. For Gaussian momentum: <p_l, dx> < 0 || <p_r, dx> < 0 per Hoffman/Gelman 2014 NUTS, eqn 9. The default implementation uses this Gaussian formula (correct for both Gaussian and q-Gaussian since dK/dp is just p rescaled, preserving sign).

Structs and Unions

struct GaussianMomentum

Standard Gaussian momentum: K(p) = |p|^2 / 2, dK/dp = p. Recovered as the q -> 1+ limit of the q-Gaussian.

Traits implemented

impl Momentum for GaussianMomentum

struct QGaussianMomentum

q-Gaussian (Tsallis) momentum with index q in (1, 1 + 2/dim). Heavy-tailed for q > 1; the kinetic term grows logarithmically in |p|^2 so large momentum draws cost much less than under Gaussian momentum. This is the q-deformed Hamiltonian dynamics that lets HMC-SA escape local cups on multimodal objectives.

q: f64

Tsallis index. Must satisfy 1 < q < 1 + 2/dim to give a normalisable density. Boundary q == 1 falls back to Gaussian.

Implementations

impl QGaussianMomentum

Functions

fn max_dim(&self) -> usize

Maximum dim for which this q gives a valid q-Gaussian.

fn new(q: f64) -> Self

Constructs with the given q. Validate against dim separately before sampling – the dim arrives at sample time.

Traits implemented

impl Momentum for QGaussianMomentum