Hyperbolic space
The hyperbolic space can be represented in three different ways. In the following the common functions are collected. Then, specific methods for each of the representations, especially conversions between those.
A function in this general section uses vectors interpreted as if in the hyperboloid model, and other representations usually just convert to this representation to use these general functions.
Manifolds.Hyperbolic
— TypeHyperbolic{N} <: AbstractEmbeddedManifold{ℝ,DefaultIsometricEmbeddingType}
The hyperbolic space $\mathcal H^n$ represented by $n+1$-Tuples, i.e. embedded in the Lorentz
ian manifold equipped with the MinkowskiMetric
$⟨\cdot,\cdot⟩_{\mathrm{M}}$. The space is defined as
The tangent space $T_p \mathcal H^n$ is given by
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 Vector
s 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
.
Manifolds.HyperboloidPoint
— TypeHyperboloidPoint <: MPoint
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. AbstractVector
s are assumed to have this repesentation.
Manifolds.HyperboloidTVector
— TypeHyperboloidTVector <: 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.
Manifolds.PoincareBallPoint
— TypePoincareBallPoint <: MPoint
A point on the Hyperbolic
manifold $\mathcal H^n$ can be represented as a vector of norm less than one in $\mathbb R^n$.
Manifolds.PoincareBallTVector
— TypePoincareBallTVector <: TVector
In the Poincaré ball model of the Hyperbolic
$\mathcal H^n$ tangent vectors are represented as vectors in $ℝ^{n}$.
Manifolds.PoincareHalfSpacePoint
— TypePoincareHalfSpacePoint <: MPoint
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$.
Manifolds.PoincareHalfSpaceTVector
— TypePoincareHalfPlaneTVector <: TVector
In the Poincaré half plane model of the Hyperbolic
$\mathcal H^n$ tangent vectors are represented as vectors in $ℝ^{n}$.
Base.exp
— Methodexp(M::Hyperbolic, p, X)
Compute the exponential map on the Hyperbolic
space $\mathcal H^n$ emanating from p
towards X
. The formula reads
where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric
on the embedding, the Lorentz
ian manifold.
Base.log
— Methodlog(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$
where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric
on the embedding, the Lorentz
ian manifold. For $p=q$ the logarihmic map is equal to the zero vector.
ManifoldsBase.check_manifold_point
— Methodcheck_manifold_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$
ManifoldsBase.check_tangent_vector
— Methodcheck_tangent_vector(M::Hyperbolic{n}, p, X; check_base_point = true, kwargs... )
Check whether X
is a tangent vector to p
on the Hyperbolic
M
, i.e. after check_manifold_point
(M,p)
, X
has to be of the same dimension as p
. The optional parameter check_base_point
indicates whether to call check_manifold_point
for 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}$.
ManifoldsBase.injectivity_radius
— Methodinjectivity_radius(M::Hyperbolic)
injectivity_radius(M::Hyperbolic, p)
Return the injectivity radius on the Hyperbolic
, which is $∞$.
ManifoldsBase.manifold_dimension
— Methodmanifold_dimension(M::Hyperbolic)
Return the dimension of the hyperbolic space manifold $\mathcal H^n$, i.e. $\dim(\mathcal H^n) = n$.
ManifoldsBase.project
— Methodproject(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
where $⟨\cdot, \cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric
on the embedding, the Lorentz
ian manifold.
Projection is only available for the (default) HyperboloidTVector
representation, the others don't have such an embedding
ManifoldsBase.vector_transport_to
— Methodvector_transport_to(M::Hyperbolic, p, X, q, ::ParallelTransport)
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
where $⟨\cdot,\cdot⟩_p$ denotes the inner product in the tangent space at p
.
Statistics.mean
— Methodmean(
M::Hyperbolic,
x::AbstractVector,
[w::AbstractWeights,]
method = CyclicProximalPointEstimation();
kwargs...,
)
Compute the Riemannian mean
of x
on the Hyperbolic
space using CyclicProximalPointEstimation
.
hyperboloid model
Base.convert
— Methodconvert(::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
Note that this is also used, when the type to convert to is a vector.
Base.convert
— Methodconvert(::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.
Base.convert
— Methodconvert(::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
Base.convert
— Methodconvert(::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.
Base.convert
— Methodconvert(
::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.
Base.convert
— Methodconvert(
::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.
ManifoldsBase.distance
— Methoddistance(M::Hyperbolic, p, q)
distance(M::Hyperbolic, p::HyperboloidPoint, q::HyperboloidPoint)
Compute the distance on the Hyperbolic
M
, which reads
where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric
on the embedding, the Lorentz
ian manifold.
ManifoldsBase.inner
— Methodinner(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
This employs the metric of the embedding, see Lorentz
space.
Poincaré ball model
Base.convert
— Methodconvert(::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
Note that this is also used, when x
is a vector.
Base.convert
— Methodconvert(::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
Base.convert
— Methodconvert(::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
where $\tilde X = \begin{pmatrix}X_1\\⋮\\X_n\end{pmatrix}$ and $\tilde p = \begin{pmatrix}p_1\\⋮\\p_n\end{pmatrix}$.
Base.convert
— Methodconvert(
::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
where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.
Base.convert
— Methodconvert(
::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.
Base.convert
— Methodconvert(
::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.
ManifoldsBase.distance
— Methoddistance(::Hyperbolic, p::PoincareBallPoint, q::PoincareBallPoint)
Compute the distance on the Hyperbolic
manifold $\mathcal H^n$ represented in the Poincaré ball model. The formula reads
ManifoldsBase.inner
— Methodinner(::Hyperbolic, p::PoincareBallPoint, X::PoincareBallTVector, Y::PoincareBallTVector)
Compute the inner producz in the Poincaré ball model. The formula reads
ManifoldsBase.project
— Methodproject(::Hyperbolic, ::PoincareBallPoint, ::PoincareBallTVector)
projction of tangent vectors in the Poincaré ball model is just the identity, since the tangent space consists of all $ℝ^n$.
Poincaré half space model
Base.convert
— Methodconvert(::Type{PoincareHalfSpacePoint}, p::Hyperboloid)
convert(::Type{PoincareHalfSpacePoint}, p)
convert a HyperboloidPoint
or Vector
p
(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.
Base.convert
— Methodconvert(::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
Base.convert
— Methodconvert(::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.
Base.convert
— Methodconvert(::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
where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.
Base.convert
— Methodconvert(
::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.
Base.convert
— Methodconvert(
::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.
ManifoldsBase.distance
— Methoddistance(::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
ManifoldsBase.inner
— Methodinner(
::Hyperbolic{n},
p::PoincareHalfSpacePoint,
X::PoincareHalfSpaceTVector,
Y::PoincareHalfSpaceTVector
)
Compute the inner product in the Poincaré half space model. The formula reads
ManifoldsBase.project
— Methodproject(::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$.