torch.distributions.VonMises

class VonMises extends Distribution

new VonMises(loc: number | Tensor, concentration: number | Tensor, options?: DistributionOptions)

readonlyloc(Tensor): – Mean direction of the distribution (in radians).
readonlyconcentration(Tensor): – Concentration parameter (κ ≥ 0). Higher values mean more concentration around the mean.
readonlyarg_constraints(unknown)
readonlysupport(unknown)
readonlyhas_rsample(unknown)
readonlymean(Tensor)
readonlymode(Tensor)
readonlyvariance(Tensor)

Von Mises distribution: circular normal for directional/angular data on the circle [0, 2π).

Parameterized by loc μ (mean direction, in radians) and concentration κ (κ ≥ 0). The circular/directional analog of the normal distribution. Support is [0, 2π) where 0 and 2π represent the same angle. Von Mises is the maximum entropy distribution on the circle given a specified mean direction and concentration. Essential for:

Directional/circular data (wind direction, compass angles, clock times)
Orientation and heading estimation (robotics, navigation, computer vision)
Phase angles and periodic phenomena (signal processing, time series)
Animal movement directions (ecology, behavioral analysis)
Wrapped angular measurements (any circular/periodic data)
Bayesian directional statistics
Maximum entropy prior for angles/directions

Concentration Parameter κ: Controls spread on the circle.

κ = 0: uniform distribution (any direction equally likely)
κ → ∞: approaches a point mass (almost deterministic)
κ = 1: moderate spread
Higher κ means tighter clustering around mean direction μ

Circularity: Angles are periodic (0 = 2π = 4π). Von Mises respects this: mean direction μ = 0.1 rad and μ = 2π + 0.1 rad are equivalent.

\begin{aligned} \text{PDF: } f(\theta) = \frac{\exp(\kappa \cos(\theta - \mu))}{2\pi I_0(\kappa)} \quad \theta \in [0, 2\pi) \\ \text{Mean direction: } \mu \quad \text{(in radians)} \\ \text{Concentration: } \kappa \geq 0 \quad \text{(κ=0 uniform, κ→∞ point mass)} \\ \text{Circular variance: } 1 - \frac{I_1(\kappa)}{I_0(\kappa)} \quad \text{(where } I_0, I_1 \text{ are Bessel functions)} \\ \text{Entropy: } H = \ln(2\pi I_0(\kappa)) - \kappa \frac{I_1(\kappa)}{I_0(\kappa)} \end{aligned}

Support on circle: Angles [0, 2π) where 0 ≡ 2π (periodic)
Concentration κ ≥ 0: κ=0 is uniform; κ→∞ approaches point mass
κ→∞ limit: VonMises(μ, κ→∞) → Delta(μ) (point mass at μ)
κ=0 special case: Uniform on [0, 2π) regardless of loc parameter
Mean resultant length: R = I₁(κ)/I₀(κ), measures concentration (0=spread, 1=tight)
Circular data: Only meaningful for periodic/angular data (not for linear data)
Equivalent angles: loc and loc + 2πn represent same direction

κ must be non-negative: κ 0 causes errors
Circular support: Not suitable for linear data; use Normal for non-periodic angles
CPU only: GPU support not yet implemented; use CPU tensors
Wraparound at 2π: Probability mass correctly wraps at boundaries (0 ≡ 2π)

Examples

// Northerly wind direction: mean = π/2 radians (north)
const vm = new torch.distributions.VonMises(Math.PI / 2, 5);
const wind_dirs = vm.sample([1000]);  // 1000 wind direction samples
// Most winds from roughly north, concentrated around π/2

// Uniform distribution: κ=0
const uniform_circ = new torch.distributions.VonMises(0, 0);
const random_angles = uniform_circ.sample([100]);  // uniformly random angles

// Tight clustering: large κ
const tight = new torch.distributions.VonMises(0, 20);  // mean=0, tight
const concentrated = tight.sample([100]);  // mostly near 0 radians

// Robot heading estimation from noisy sensor
// Sensor reports heading μ with uncertainty (concentration κ)
const sensor_mean = 1.5;  // ~85 degrees
const sensor_precision = 10;  // moderately precise sensor
const heading_dist = new torch.distributions.VonMises(sensor_mean, sensor_precision);
const estimated_heading = heading_dist.sample();

// Batched directional distributions
const means = torch.tensor([0, Math.PI/2, Math.PI, 3*Math.PI/2]);
const concentrations = torch.tensor([2, 5, 2, 5]);
const dist = new torch.distributions.VonMises(means, concentrations);
const samples = dist.sample();  // [4] shaped angles

// Circular statistics: mean resultant length
const vm = new torch.distributions.VonMises(Math.PI / 4, 3);
const mrl = vm.concentration;  // mean resultant length indicator
// Higher mrl → less circular variance → more concentrated