Struct PoincareBall 

pub struct PoincareBall<T> {
    pub c: T,
}

Poincare ball model of hyperbolic geometry.

The open ball (\mathbb{B}^d_c = {x \in \mathbb{R}^d : c|x|^2 < 1}) equipped with the Riemannian metric

[ g_x = \lambda_x^2 I, \quad \lambda_x = \frac{2}{1 - c|x|^2} ]

where (\lambda_x) is the conformal factor. As (|x| \to 1/\sqrt{c}), (\lambda_x \to \infty), so distances near the boundary grow without bound – this is how infinite hierarchical depth fits in a finite Euclidean volume.

Curvature: the sectional curvature is (-c) everywhere. Larger (c) means stronger negative curvature (more “room” for tree branching). The standard choice is (c = 1).

Key operations: all defined via Mobius gyrovector space arithmetic (Ungar, 2008). See individual method docs for formulas.

Fields

c: T

Curvature parameter (c > 0)

Implementations

impl<T> PoincareBall<T>

where T: Float + FromPrimitive + Zero + ScalarOperand + LinalgScalar,

pub fn new(c: T) -> Self

Create a Poincare ball model with curvature c.

pub fn mobius_add( &self, x: &ArrayView1<'_, T>, y: &ArrayView1<'_, T>, ) -> Array1<T>

Mobius addition in the Poincare ball (gyrovector space operation).

[ x \oplus_c y = \frac{(1 + 2c\langle x,y\rangle + c|y|^2),x + (1 - c|x|^2),y} {1 + 2c\langle x,y\rangle + c^2|x|^2|y|^2} ]

This is the non-commutative, non-associative “addition” that replaces Euclidean vector addition in hyperbolic space. It satisfies:

• (x \oplus_c 0 = x) (identity)
• (x \oplus_c (-x) = 0) (inverse)
• Left cancellation: ((-x) \oplus_c (x \oplus_c y) = y)

pub fn distance(&self, x: &ArrayView1<'_, T>, y: &ArrayView1<'_, T>) -> T

Hyperbolic distance in the Poincare ball.

[ d_c(x, y) = \frac{2}{\sqrt{c}},\mathrm{arctanh}\bigl(\sqrt{c},|(-x) \oplus_c y|\bigr) ]

This is the geodesic distance on the Riemannian manifold ((\mathbb{B}^d_c, g)). Near the origin it approximates (2|x - y|); near the boundary it grows logarithmically in (1/(1-c|x|^2)).

pub fn log_map_zero(&self, y: &ArrayView1<'_, T>) -> Array1<T>

Logarithmic map at the origin: (\log_0(y) = \frac{\mathrm{arctanh}(\sqrt{c}|y|)}{\sqrt{c}|y|},y).

Maps a point on the manifold to a tangent vector at the origin. For small (|y|), this is approximately the identity.

pub fn exp_map_zero(&self, v: &ArrayView1<'_, T>) -> Array1<T>

Exponential map at the origin: (\exp_0(v) = \frac{\tanh(\sqrt{c}|v|)}{\sqrt{c}|v|},v).

Maps a tangent vector at the origin to a point on the manifold. The (\tanh) ensures the result stays inside the ball ((\tanh(t) < 1) for all (t)).

pub fn is_in_ball(&self, x: &ArrayView1<'_, T>) -> bool

Check if point is inside the Poincare ball (||x|| < 1/sqrt(c)).

pub fn project(&self, x: &ArrayView1<'_, T>) -> Array1<T>

Project point onto ball boundary if outside.

Trait Implementations

impl Manifold for PoincareBall<f64>

Available on crate feature ndarray only.

fn exp_map( &self, x: &ArrayView1<'_, f64>, v: &ArrayView1<'_, f64>, ) -> Array1<f64>

Map a tangent vector to a manifold point: (\exp_x(v) \in M).

fn log_map( &self, x: &ArrayView1<'_, f64>, y: &ArrayView1<'_, f64>, ) -> Array1<f64>

Map a manifold point to a tangent vector: (\log_x(y) \in T_x M).

fn parallel_transport( &self, x: &ArrayView1<'_, f64>, y: &ArrayView1<'_, f64>, v: &ArrayView1<'_, f64>, ) -> Array1<f64>

Parallel transport a tangent vector along a geodesic: (\Gamma_{x \to y}(v) \in T_y M).

fn project( &self, x: &ArrayBase<ViewRepr<&f64>, Dim<[usize; 1]>>, ) -> ArrayBase<OwnedRepr<f64>, Dim<[usize; 1]>>

Project a point in ambient space back onto the manifold.