calibrax.metrics.functional.distance

Distance functions spanning a geometric hierarchy from flat spaces to curved manifolds. Includes Euclidean, Manhattan, Chebyshev, and Minkowski norms (flat geometry), Mahalanobis (affine), cosine and Jaccard (set/angle), Poincare and Lorentz (hyperbolic), and Randers (asymmetric Finsler).

Distance functions across geometric spaces.

Pure functions for computing distances between vectors or distributions. Covers the three constant-curvature geometries: Euclidean (zero curvature), cosine/spherical (positive curvature), and Poincare/Lorentz/hyperbolic (negative curvature). Also includes discrete set distances (Hamming, Jaccard) and the Randers asymmetric Finsler distance for directed relationships.

Includes 11 functions: cosine_distance, euclidean_distance, manhattan_distance, chebyshev_distance, mahalanobis_distance, hamming_distance, minkowski_distance, jaccard_distance, poincare_distance, lorentz_distance, randers_distance.

cosine_distance(a: Any, b: Any) -> Any

Cosine distance: 1 - cosine_similarity(a, b).

Measures angular separation between vectors. Lives on the unit sphere (positive curvature geometry).

Note

Direction: LOWER (0.0 = identical direction). Range: [0, 2]. 0 = same direction, 1 = orthogonal, 2 = opposite. Not a true metric (violates triangle inequality), but arccos(1 - d) is a true metric on the sphere. Invariant under scaling.

Parameters:

Name	Type	Description	Default
a	Any	First vector or batch of vectors.	required
b	Any	Second vector or batch of vectors.	required

Returns:

Type	Description
Any	Cosine distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> cosine_distance(jnp.array([1.0, 0.0]), jnp.array([1.0, 0.0]))
0.0

euclidean_distance(a: Any, b: Any) -> Any

Euclidean (L2) distance.

Standard distance in flat (zero curvature) Euclidean space.

Note

Direction: LOWER (0.0 = identical). Range: [0, inf). True metric: satisfies identity, symmetry, triangle inequality. Invariant under rotation and translation.

Parameters:

Name	Type	Description	Default
a	Any	First vector or batch of vectors.	required
b	Any	Second vector or batch of vectors.	required

Returns:

Type	Description
Any	Euclidean distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> euclidean_distance(jnp.array([1.0, 0.0]), jnp.array([0.0, 1.0]))
1.4142...

manhattan_distance(a: Any, b: Any) -> Any

Manhattan (L1) distance.

Sum of absolute differences. Also called taxicab or city-block distance.

Note

Direction: LOWER (0.0 = identical). Range: [0, inf). True metric. Invariant under translation.

Parameters:

Name	Type	Description	Default
a	Any	First vector or batch of vectors.	required
b	Any	Second vector or batch of vectors.	required

Returns:

Type	Description
Any	Manhattan distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> manhattan_distance(jnp.array([1.0, 0.0]), jnp.array([0.0, 1.0]))
2.0

chebyshev_distance(a: Any, b: Any) -> Any

Chebyshev (L-infinity) distance.

Maximum absolute difference across dimensions.

Note

Direction: LOWER (0.0 = identical). Range: [0, inf). True metric. Invariant under translation.

Parameters:

Name	Type	Description	Default
a	Any	First vector or batch of vectors.	required
b	Any	Second vector or batch of vectors.	required

Returns:

Type	Description
Any	Chebyshev distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> chebyshev_distance(jnp.array([1.0, 0.0]), jnp.array([0.0, 3.0]))
3.0

mahalanobis_distance(a: Any, b: Any, *, precision_matrix: Any | None = None) -> Any

Mahalanobis distance.

Generalized Euclidean distance weighted by an inverse covariance (precision) matrix: sqrt((a-b)^T S^-1 (a-b)).

Note

Direction: LOWER (0.0 = identical). Range: [0, inf). True metric when precision_matrix is positive definite. Reduces to Euclidean when precision_matrix is identity.

Parameters:

Name	Type	Description	Default
a	Any	First vector or batch of vectors.	required
b	Any	Second vector or batch of vectors.	required
precision_matrix	Any | None	Inverse covariance matrix. If None, uses identity (equivalent to Euclidean distance).	None

Returns:

Type	Description
Any	Mahalanobis distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> a = jnp.array([1.0, 0.0])
>>> b = jnp.array([0.0, 1.0])
>>> mahalanobis_distance(a, b)  # identity → Euclidean
1.4142...

hamming_distance(a: Any, b: Any) -> Any

Hamming distance: fraction of differing positions.

Discrete metric on integer or boolean arrays.

Note

Direction: LOWER (0.0 = identical). Range: [0, 1]. True metric on discrete space.

Parameters:

Name	Type	Description	Default
a	Any	First integer/boolean array.	required
b	Any	Second integer/boolean array.	required

Returns:

Type	Description
Any	Hamming distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> hamming_distance(jnp.array([1, 0, 1]), jnp.array([1, 1, 1]))
0.333...

minkowski_distance(a: Any, b: Any, *, p: float = 2.0) -> Any

Minkowski (Lp) distance.

Generalized distance: (sum|a_i - b_i|^p)^(1/p). p=1 is Manhattan, p=2 is Euclidean.

Note

Direction: LOWER (0.0 = identical). Range: [0, inf). True metric for p >= 1.

Parameters:

Name	Type	Description	Default
a	Any	First vector or batch of vectors.	required
b	Any	Second vector or batch of vectors.	required
p	float	Order of the norm. Must be >= 1.	2.0

Returns:

Type	Description
Any	Minkowski distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> minkowski_distance(jnp.array([1.0, 0.0]), jnp.array([0.0, 1.0]), p=1.0)
2.0

jaccard_distance(a: Any, b: Any) -> Any

Jaccard distance: 1 - |A intersection B| / |A union B|.

Set-based distance for binary vectors. Complement of the Jaccard similarity index.

Note

Direction: LOWER (0.0 = identical sets). Range: [0, 1]. True metric on the space of finite sets. Symmetric: J(A,B) = J(B,A).

Parameters:

Name	Type	Description	Default
a	Any	First binary/non-negative vector.	required
b	Any	Second binary/non-negative vector.	required

Returns:

Type	Description
Any	Jaccard distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> jaccard_distance(jnp.array([1, 1, 0]), jnp.array([1, 0, 1]))
0.666...

poincare_distance(a: Any, b: Any, *, curvature: float = 1.0) -> Any

Geodesic distance in the Poincare ball model of hyperbolic space.

Points must lie inside the ball: curvature * ||x||^2 < 1. Hyperbolic space has exponential volume growth matching tree/hierarchy structures.

Note

Direction: LOWER (0.0 = identical points). Range: [0, inf). True metric. Symmetric. Differentiable. Distance grows without bound as points approach the ball boundary. Complements cosine_distance (spherical/positive curvature) and euclidean_distance (flat/zero curvature).

Parameters:

Name	Type	Description	Default
a	Any	First point or batch inside the Poincare ball.	required
b	Any	Second point or batch inside the Poincare ball.	required
curvature	float	Curvature parameter (default 1.0). Higher values shrink the ball radius.	1.0

Returns:

Type	Description
Any	Poincare distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> poincare_distance(jnp.array([0.0, 0.0]), jnp.array([0.5, 0.0]))
1.0986...

lorentz_distance(a: Any, b: Any) -> Any

Geodesic distance on the Lorentz (hyperboloid) model of hyperbolic space.

Points live on the upper hyperboloid <x,x>_L = -1, x_0 > 0 in R^(n+1). Uses the Minkowski inner product: <a,b>_L = -a_0*b_0 + sum(a_i*b_i). Isometric to the Poincare ball but numerically more stable near the boundary.

Note

Direction: LOWER (0.0 = identical points). Range: [0, inf). True metric. Symmetric. Differentiable. Invariant under Lorentz transformations. More numerically stable than Poincare for optimization.

Parameters:

Name	Type	Description	Default
a	Any	First point on the hyperboloid (first component is time-like).	required
b	Any	Second point on the hyperboloid.	required

Returns:

Type	Description
Any	Lorentz distance as a scalar value.

Examples:

>>> import jax.numpy as jnp
>>> # Point on hyperboloid: x_0 = sqrt(1 + ||x||^2)
>>> a = jnp.array([1.0, 0.0, 0.0])  # origin on hyperboloid
>>> lorentz_distance(a, a)
0.0

randers_distance(a: Any, b: Any, *, drift: Any) -> Any

Randers distance: asymmetric Finsler metric with directional bias.

Adds a "wind" vector to Euclidean distance: d_R(a,b) = ||b-a||_2 + <drift, b-a>. The drift vector must satisfy ||drift|| < 1 (sub-sonic condition).

Note

Direction: LOWER (0.0 = identical points). Range: [0, inf). NOT a true metric (asymmetric: d(a,b) != d(b,a)). The asymmetry is a geometric feature, not a deficiency. Applications: directed graph embeddings, latent space geometry.

Parameters:

Name	Type	Description	Default
a	Any	First point or batch of points.	required
b	Any	Second point or batch of points.	required
drift	Any	Wind/bias vector. Must satisfy ||drift|| < 1.	required

Returns:

Type	Description
Any	Randers distance as a scalar value.

Raises:

Type	Description
ValueError	If ||drift|| >= 1 (sub-sonic condition violated).

Examples:

>>> import jax.numpy as jnp
>>> a = jnp.array([0.0, 0.0])
>>> b = jnp.array([1.0, 0.0])
>>> randers_distance(a, b, drift=jnp.array([0.0, 0.0]))
1.0