Hyperbolic space

Hyperbolic{N} <: AbstractDecoratorManifold{ℝ}

The hyperbolic space $\mathcal H^n$ represented by $n+1$-Tuples, i.e. embedded in the Lorentzian manifold equipped with the MinkowskiMetric $⟨\cdot,\cdot⟩_{\mathrm{M}}$. The space is defined as

\[\mathcal H^n = \Bigl\{p ∈ ℝ^{n+1}\ \Big|\ ⟨p,p⟩_{\mathrm{M}}= -p_{n+1}^2 + \displaystyle\sum_{k=1}^n p_k^2 = -1, p_{n+1} > 0\Bigr\},.\]

The tangent space $T_p \mathcal H^n$ is given by

\[T_p \mathcal H^n := \bigl\{ X ∈ ℝ^{n+1} : ⟨p,X⟩_{\mathrm{M}} = 0 \bigr\}.\]

Note that while the MinkowskiMetric renders the Lorentz manifold (only) pseudo-Riemannian, on the tangent bundle of the Hyperbolic space it induces a Riemannian metric. The corresponding sectional curvature is $-1$.

If p and X are Vectors of length n+1 they are assumed to be a HyperboloidPoint and a HyperboloidTVector, respectively

Other models are the Poincaré ball model, see PoincareBallPoint and PoincareBallTVector, respectiely and the Poincaré half space model, see PoincareHalfSpacePoint and PoincareHalfSpaceTVector, respectively.

Constructor

Hyperbolic(n)

Generate the Hyperbolic manifold of dimension n.

HyperboloidPoint <: AbstractManifoldPoint

In the Hyperboloid model of the Hyperbolic $\mathcal H^n$ points are represented as vectors in $ℝ^{n+1}$ with MinkowskiMetric equal to $-1$.

This representation is the default, i.e. AbstractVectors are assumed to have this repesentation.

HyperboloidTVector <: TVector

In the Hyperboloid model of the Hyperbolic $\mathcal H^n$ tangent vctors are represented as vectors in $ℝ^{n+1}$ with MinkowskiMetric $⟨p,X⟩_{\mathrm{M}}=0$ to their base point $p$.

This representation is the default, i.e. vectors are assumed to have this repesentation.

PoincareBallPoint <: AbstractManifoldPoint

A point on the Hyperbolic manifold $\mathcal H^n$ can be represented as a vector of norm less than one in $\mathbb R^n$.

PoincareBallTVector <: TVector

In the Poincaré ball model of the Hyperbolic $\mathcal H^n$ tangent vectors are represented as vectors in $ℝ^{n}$.

PoincareHalfSpacePoint <: AbstractManifoldPoint

A point on the Hyperbolic manifold $\mathcal H^n$ can be represented as a vector in the half plane, i.e. $x ∈ ℝ^n$ with $x_d > 0$.

PoincareHalfPlaneTVector <: TVector

In the Poincaré half plane model of the Hyperbolic $\mathcal H^n$ tangent vectors are represented as vectors in $ℝ^{n}$.

exp(M::Hyperbolic, p, X)

Compute the exponential map on the Hyperbolic space $\mathcal H^n$ emanating from p towards X. The formula reads

\[\exp_p X = \cosh(\sqrt{⟨X,X⟩_{\mathrm{M}}})p + \sinh(\sqrt{⟨X,X⟩_{\mathrm{M}}})\frac{X}{\sqrt{⟨X,X⟩_{\mathrm{M}}}},\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

log(M::Hyperbolic, p, q)

Compute the logarithmic map on the Hyperbolic space $\mathcal H^n$, the tangent vector representing the geodesic starting from p reaches q after time 1. The formula reads for $p ≠ q$

\[\log_p q = d_{\mathcal H^n}(p,q) \frac{q-⟨p,q⟩_{\mathrm{M}} p}{\lVert q-⟨p,q⟩_{\mathrm{M}} p \rVert_2},\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold. For $p=q$ the logarihmic map is equal to the zero vector.

manifold_dimension(M::Hyperbolic)

Return the volume of the hyperbolic space manifold $\mathcal H^n$, i.e. infinity.

check_point(M::Hyperbolic, p; kwargs...)

Check whether p is a valid point on the Hyperbolic M.

For the HyperboloidPoint or plain vectors this means that, p is a vector of length $n+1$ with inner product in the embedding of -1, see MinkowskiMetric. The tolerance for the last test can be set using the kwargs....

For the PoincareBallPoint a valid point is a vector $p ∈ ℝ^n$ with a norm stricly less than 1.

For the PoincareHalfSpacePoint a valid point is a vector from $p ∈ ℝ^n$ with a positive last entry, i.e. $p_n>0$

check_vector(M::Hyperbolic{n}, p, X; kwargs... )

Check whether X is a tangent vector to p on the Hyperbolic M, i.e. after check_point(M,p), X has to be of the same dimension as p. The tolerance for the last test can be set using the kwargs....

For a the hyperboloid model or vectors, X has to be orthogonal to p with respect to the inner product from the embedding, see MinkowskiMetric.

For a the Poincaré ball as well as the Poincaré half plane model, X has to be a vector from $ℝ^{n}$.

injectivity_radius(M::Hyperbolic)
injectivity_radius(M::Hyperbolic, p)

Return the injectivity radius on the Hyperbolic, which is $∞$.

is_flat(::Hyperbolic)

Return false. Hyperbolic is not a flat manifold.

manifold_dimension(M::Hyperbolic)

Return the dimension of the hyperbolic space manifold $\mathcal H^n$, i.e. $\dim(\mathcal H^n) = n$.

parallel_transport_to(M::Hyperbolic, p, X, q)

Compute the paralllel transport of the X from the tangent space at p on the Hyperbolic space $\mathcal H^n$ to the tangent at q along the geodesic connecting p and q. The formula reads

\[\mathcal P_{q←p}X = X - \frac{⟨\log_p q,X⟩_p}{d^2_{\mathcal H^n}(p,q)} \bigl(\log_p q + \log_qp \bigr),\]

where $⟨\cdot,\cdot⟩_p$ denotes the inner product in the tangent space at p.

project(M::Hyperbolic, p, X)

Perform an orthogonal projection with respect to the Minkowski inner product of X onto the tangent space at p of the Hyperbolic space M.

The formula reads

\[Y = X + ⟨p,X⟩_{\mathrm{M}} p,\]

where $⟨\cdot, \cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

riemann_tensor(M::Hyperbolic{n}, p, X, Y, Z)

Compute the Riemann tensor $R(X,Y)Z$ at point p on Hyperbolic M. The formula reads (see e.g., [Lee19] Proposition 8.36)

\[R(X,Y)Z = - (\langle Z, Y \rangle X - \langle Z, X \rangle Y)\]

mean(
    M::Hyperbolic,
    x::AbstractVector,
    [w::AbstractWeights,]
    method = CyclicProximalPointEstimation();
    kwargs...,
)

Compute the Riemannian mean of x on the Hyperbolic space using CyclicProximalPointEstimation.

convert(::Type{HyperboloidPoint}, p::PoincareBallPoint)
convert(::Type{AbstractVector}, p::PoincareBallPoint)

convert a point PoincareBallPoint x (from $ℝ^n$) from the Poincaré ball model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidPoint $π(p) ∈ ℝ^{n+1}$. The isometry is defined by

\[π(p) = \frac{1}{1-\lVert p \rVert^2} \begin{pmatrix}2p_1\\⋮\\2p_n\\1+\lVert p \rVert^2\end{pmatrix}\]

Note that this is also used, when the type to convert to is a vector.

convert(::Type{HyperboloidPoint}, p::PoincareHalfSpacePoint)
convert(::Type{AbstractVector}, p::PoincareHalfSpacePoint)

convert a point PoincareHalfSpacePoint p (from $ℝ^n$) from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidPoint $π(p) ∈ ℝ^{n+1}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.

convert(::Type{HyperboloidTVector}, p::PoincareBallPoint, X::PoincareBallTVector)
convert(::Type{AbstractVector}, p::PoincareBallPoint, X::PoincareBallTVector)

Convert the PoincareBallTVector X from the tangent space at p to a HyperboloidTVector by computing the push forward of the isometric map, cf. convert(::Type{HyperboloidPoint}, p::PoincareBallPoint).

The push forward $π_*(p)$ maps from $ℝ^n$ to a subspace of $ℝ^{n+1}$, the formula reads

\[π_*(p)[X] = \begin{pmatrix} \frac{2X_1}{1-\lVert p \rVert^2} + \frac{4}{(1-\lVert p \rVert^2)^2}⟨X,p⟩p_1\\ ⋮\\ \frac{2X_n}{1-\lVert p \rVert^2} + \frac{4}{(1-\lVert p \rVert^2)^2}⟨X,p⟩p_n\\ \frac{4}{(1-\lVert p \rVert^2)^2}⟨X,p⟩ \end{pmatrix}.\]

convert(::Type{HyperboloidTVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)
convert(::Type{AbstractVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)

convert a point PoincareHalfSpaceTVector X (from $ℝ^n$) at p from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidTVector $π(p) ∈ ℝ^{n+1}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.

convert(
    ::Type{Tuple{HyperboloidPoint,HyperboloidTVector}}.
    (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}
)
convert(
    ::Type{Tuple{P,T}},
    (p, X)::Tuple{PoincareBallPoint,PoincareBallTVector},
) where {P<:AbstractVector, T <: AbstractVector}

Convert a PoincareBallPoint p and a PoincareBallTVector X to a HyperboloidPoint and a HyperboloidTVector simultaneously, see convert(::Type{HyperboloidPoint}, ::PoincareBallPoint) and convert(::Type{HyperboloidTVector}, ::PoincareBallPoint, ::PoincareBallTVector) for the formulae.

convert(
    ::Type{Tuple{HyperboloidPoint,HyperboloidTVector},
    (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}
)
convert(
    ::Type{Tuple{T,T},
    (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}
) where {T<:AbstractVector}

convert a point PoincareHalfSpaceTVector X (from $ℝ^n$) at p from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a tuple of a HyperboloidPoint and a HyperboloidTVector $π(p) ∈ ℝ^{n+1}$ simultaneously.

This is done in two steps, namely transforming it to the Poincare ball model and from there further on to a Hyperboloid.

Y = riemannian_Hessian(M::Hyperbolic, p, G, H, X)
riemannian_Hessian!(M::Hyperbolic, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

Let $\mathbf{g} = \mathbf{g}^{-1} = \operatorname{diag}(1,...,1,-1)$. Then using Remark 4.1 [Ngu23] the formula reads

\[\operatorname{Hess}f(p)[X] = \operatorname{proj}_{T_p\mathcal M}\bigl( \mathbf{g}^{-1}\nabla^2f(p)[X] + X⟨p,\mathbf{g}^{-1}∇f(p)⟩_p \bigr).\]

volume_density(M::Hyperbolic, p, X)

Compute volume density function of the hyperbolic manifold. The formula reads $(\sinh(\lVert X\rVert)/\lVert X\rVert)^(n-1)$ where n is the dimension of M. It is derived from Eq. (4.1) in[CLLD22].

change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p, X)

Change the Eucliden representer X of a cotangent vector at point p. We only have to correct for the metric, which means that the sign of the last entry changes, since for the result $Y$ we are looking for a tangent vector such that

\[ g_p(Y,Z) = -y_{n+1}z_{n+1} + \sum_{i=1}^n y_iz_i = \sum_{i=1}^{n+1} z_ix_i\]

holds, which directly yields $y_i=x_i$ for $i=1,\ldots,n$ and $y_{n+1}=-x_{n+1}$.

distance(M::Hyperbolic, p, q)
distance(M::Hyperbolic, p::HyperboloidPoint, q::HyperboloidPoint)

Compute the distance on the Hyperbolic M, which reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}( - ⟨p, q⟩_{\mathrm{M}}),\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

get_coordinates(M::Hyperbolic, p, X, ::DefaultOrthonormalBasis)

Compute the coordinates of the vector X with respect to the orthogonalized version of the unit vectors from $ℝ^n$, where $n$ is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.

get_vector(M::Hyperbolic, p, c, ::DefaultOrthonormalBasis)

Compute the vector from the coordinates with respect to the orthogonalized version of the unit vectors from $ℝ^n$, where $n$ is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.

inner(M::Hyperbolic{n}, p, X, Y)
inner(M::Hyperbolic{n}, p::HyperboloidPoint, X::HyperboloidTVector, Y::HyperboloidTVector)

Cmpute the inner product in the Hyperboloid model, i.e. the minkowski_metric in the embedding. The formula reads

\[g_p(X,Y) = ⟨X,Y⟩_{\mathrm{M}} = -X_{n}Y_{n} + \displaystyle\sum_{k=1}^{n-1} X_kY_k.\]

This employs the metric of the embedding, see Lorentz space.

_hyperbolize(M, p, Y)

Given the Hyperbolic(n) manifold using the hyperboloid model and a point p thereon, we can put a vector $Y\in ℝ^n$ into the tangent space by computing its last component such that for the resulting p we have that its minkowski_metric is $⟨p,X⟩_{\mathrm{M}} = 0$, i.e. $X_{n+1} = \frac{⟨\tilde p, Y⟩}{p_{n+1}}$, where $\tilde p = (p_1,\ldots,p_n)$.

_hyperbolize(M, q)

Given the Hyperbolic(n) manifold using the hyperboloid model, a point from the $q\in ℝ^n$ can be set onto the manifold by computing its last component such that for the resulting p we have that its minkowski_metric is $⟨p,p⟩_{\mathrm{M}} = - 1$, i.e. $p_{n+1} = \sqrt{\lVert q \rVert^2 - 1}$

convert(::Type{PoincareBallPoint}, p::HyperboloidPoint)
convert(::Type{PoincareBallPoint}, p::T) where {T<:AbstractVector}

convert a HyperboloidPoint $p∈ℝ^{n+1}$ from the hyperboloid model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareBallPoint $π(p)∈ℝ^{n}$ in the Poincaré ball model. The isometry is defined by

\[π(p) = \frac{1}{1+p_{n+1}} \begin{pmatrix}p_1\\⋮\\p_n\end{pmatrix}\]

Note that this is also used, when x is a vector.

convert(::Type{PoincareBallPoint}, p::PoincareHalfSpacePoint)

convert a point PoincareHalfSpacePoint p (from $ℝ^n$) from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareBallPoint $π(p) ∈ ℝ^n$. Denote by $\tilde p = (p_1,\ldots,p_{d-1})^{\mathrm{T}}$. Then the isometry is defined by

\[π(p) = \frac{1}{\lVert \tilde p \rVert^2 + (p_n+1)^2} \begin{pmatrix}2p_1\\⋮\\2p_{n-1}\\\lVert p\rVert^2 - 1\end{pmatrix}.\]

convert(::Type{PoincareBallTVector}, p::HyperboloidPoint, X::HyperboloidTVector)
convert(::Type{PoincareBallTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}

convert a HyperboloidTVector X at p to a PoincareBallTVector on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Hyperboloid to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::HyperboloidPoint).

The formula reads

\[π_*(p)[X] = \frac{1}{p_{n+1}+1}\Bigl(\tilde X - \frac{X_{n+1}}{p_{n+1}+1}\tilde p \Bigl),\]

where $\tilde X = \begin{pmatrix}X_1\\⋮\\X_n\end{pmatrix}$ and $\tilde p = \begin{pmatrix}p_1\\⋮\\p_n\end{pmatrix}$.

convert(
    ::Type{PoincareBallTVector},
    p::PoincareHalfSpacePoint,
    X::PoincareHalfSpaceTVector
)

convert a PoincareHalfSpaceTVector X at p to a PoincareBallTVector on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Poincaré half space to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint).

The formula reads

\[π_*(p)[X] = \frac{1}{\lVert \tilde p\rVert^2 + (1+p_n)^2} \begin{pmatrix} 2X_1\\ ⋮\\ 2X_{n-1}\\ 2⟨X,p⟩ \end{pmatrix} - \frac{2}{(\lVert \tilde p\rVert^2 + (1+p_n)^2)^2} \begin{pmatrix} 2p_1(⟨X,p⟩+X_n)\\ ⋮\\ 2p_{n-1}(⟨X,p⟩+X_n)\\ (\lVert p \rVert^2-1)(⟨X,p⟩+X_n) \end{pmatrix}\]

where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.

convert(
    ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
    (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}
)
convert(
    ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
    (p, X)::Tuple{P,T},
) where {P<:AbstractVector, T <: AbstractVector}

Convert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::HyperboloidPoint) and convert(::Type{PoincareBallTVector}, ::HyperboloidPoint, ::HyperboloidTVector) for the formulae.

convert(
    ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
    (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}
)
convert(
    ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
    (p, X)::Tuple{T,T},
) where {T <: AbstractVector}

Convert a PoincareHalfSpacePoint p and a PoincareHalfSpaceTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint) and convert(::Type{PoincareBallTVector}, ::PoincareHalfSpacePoint, ::PoincareHalfSpaceTVector) for the formulae.

change_metric(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)

Since in the metric we always have the term $α = \frac{2}{1-\sum_{i=1}^n p_i^2}$ per element, the correction for the metric reads $Z = \frac{1}{α}X$.

change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)

Since in the metric we have the term $α = \frac{2}{1-\sum_{i=1}^n p_i^2}$ per element, the correction for the gradient reads $Y = \frac{1}{α^2}X$.

distance(::Hyperbolic, p::PoincareBallPoint, q::PoincareBallPoint)

Compute the distance on the Hyperbolic manifold $\mathcal H^n$ represented in the Poincaré ball model. The formula reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}\Bigl( 1 + \frac{2\lVert p - q \rVert^2}{(1-\lVert p\rVert^2)(1-\lVert q\rVert^2)} \Bigr)\]

inner(::Hyperbolic, p::PoincareBallPoint, X::PoincareBallTVector, Y::PoincareBallTVector)

Compute the inner producz in the Poincaré ball model. The formula reads

\[g_p(X,Y) = \frac{4}{(1-\lVert p \rVert^2)^2} ⟨X, Y⟩ .\]

project(::Hyperbolic, ::PoincareBallPoint, ::PoincareBallTVector)

projction of tangent vectors in the Poincaré ball model is just the identity, since the tangent space consists of all $ℝ^n$.

convert(::Type{PoincareHalfSpacePoint}, p::Hyperboloid)
convert(::Type{PoincareHalfSpacePoint}, p)

convert a HyperboloidPoint or Vectorp (from $ℝ^{n+1}$) from the Hyperboloid model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareHalfSpacePoint $π(x) ∈ ℝ^{n}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a PoincareHalfSpacePoint point.

convert(::Type{PoincareHalfSpacePoint}, p::PoincareBallPoint)

convert a point PoincareBallPoint p (from $ℝ^n$) from the Poincaré ball model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareHalfSpacePoint $π(p) ∈ ℝ^n$. Denote by $\tilde p = (p_1,\ldots,p_{n-1})$. Then the isometry is defined by

\[π(p) = \frac{1}{\lVert \tilde p \rVert^2 - (p_n-1)^2} \begin{pmatrix}2p_1\\⋮\\2p_{n-1}\\1-\lVert p\rVert^2\end{pmatrix}.\]

convert(::Type{PoincareHalfSpaceTVector}, p::HyperboloidPoint, ::HyperboloidTVector)
convert(::Type{PoincareHalfSpaceTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}

convert a HyperboloidTVector X at p to a PoincareHalfSpaceTVector on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Hyperboloid to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint).

This is done similarly to the approach there, i.e. by using the Poincaré ball model as an intermediate step.

convert(::Type{PoincareHalfSpaceTVector}, p::PoincareBallPoint, X::PoincareBallTVector)

convert a PoincareBallTVector X at p to a PoincareHalfSpacePoint on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Poincaré ball to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint).

The formula reads

\[π_*(p)[X] = \frac{1}{\lVert \tilde p\rVert^2 + (1-p_n)^2} \begin{pmatrix} 2X_1\\ ⋮\\ 2X_{n-1}\\ -2⟨X,p⟩ \end{pmatrix} - \frac{2}{(\lVert \tilde p\rVert^2 + (1-p_n)^2)^2} \begin{pmatrix} 2p_1(⟨X,p⟩-X_n)\\ ⋮\\ 2p_{n-1}(⟨X,p⟩-X_n)\\ (\lVert p \rVert^2-1)(⟨X,p⟩-X_n) \end{pmatrix}\]

where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.

convert(
    ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},
    (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}
)
convert(
    ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},
    (p, X)::Tuple{P,T},
) where {P<:AbstractVector, T <: AbstractVector}

Convert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::Tuple{HyperboloidPoint,HyperboloidTVector}) for the formulae.

convert(
    ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},
    (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}
)

Convert a PoincareBallPoint p and a PoincareBallTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::PoincareBallPoint,::PoincareBallTVector) for the formulae.

distance(::Hyperbolic, p::PoincareHalfSpacePoint, q::PoincareHalfSpacePoint)

Compute the distance on the Hyperbolic manifold $\mathcal H^n$ represented in the Poincaré half space model. The formula reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}\Bigl( 1 + \frac{\lVert p - q \rVert^2}{2 p_n q_n} \Bigr)\]

inner(
    ::Hyperbolic{n},
    p::PoincareHalfSpacePoint,
    X::PoincareHalfSpaceTVector,
    Y::PoincareHalfSpaceTVector
)

Compute the inner product in the Poincaré half space model. The formula reads

\[g_p(X,Y) = \frac{⟨X,Y⟩}{p_n^2}.\]

project(::Hyperbolic, ::PoincareHalfSpacePoint ::PoincareHalfSpaceTVector)

projction of tangent vectors in the Poincaré half space model is just the identity, since the tangent space consists of all $ℝ^n$.