`ManifoldsBase.jl` – an interface for manifolds

ManifoldsBase.AbstractOrthogonalBasis — Type

AbstractOrthogonalBasis{𝔽,VST<:VectorSpaceType}

Abstract type that represents an orthonormal basis of vector space of type VST on a manifold or a subset of it.

The type parameter 𝔽 denotes the AbstractNumbers that will be used for the vectors elements.

See also

ManifoldsBase.AbstractOrthonormalBasis — Type

AbstractOrthonormalBasis{𝔽,VST<:VectorSpaceType}

Abstract type that represents an orthonormal basis of vector space of type VST on a manifold or a subset of it.

The type parameter 𝔽 denotes the AbstractNumbers that will be used for the vectors elements.

See also

ManifoldsBase.CachedBasis — Type

CachedBasis{𝔽,V,<:AbstractBasis{𝔽}} <: AbstractBasis{𝔽}

A cached version of the given basis with precomputed basis vectors. The basis vectors are stored in data, either explicitly (like in cached variants of ProjectedOrthonormalBasis) or implicitly.

Constructor

CachedBasis(basis::AbstractBasis, data)

ManifoldsBase.DefaultBasis — Type

DefaultBasis{𝔽,VST<:VectorSpaceType}

An arbitrary basis of vector space of type VST on a manifold. This will usually be the fastest basis available for a manifold.

The type parameter 𝔽 denotes the AbstractNumbers that will be used for the vectors elements.

See also

ManifoldsBase.DefaultOrthogonalBasis — Type

DefaultOrthogonalBasis{𝔽,VST<:VectorSpaceType}

An arbitrary orthogonal basis of vector space of type VST on a manifold. This will usually be the fastest orthogonal basis available for a manifold.

The type parameter 𝔽 denotes the AbstractNumbers that will be used for the vectors elements.

See also

ManifoldsBase.DefaultOrthonormalBasis — Type

DefaultOrthonormalBasis(𝔽::AbstractNumbers = ℝ, vs::VectorSpaceType = TangentSpace)

An arbitrary orthonormal basis of vector space of type VST on a manifold. This will usually be the fastest orthonormal basis available for a manifold.

The type parameter 𝔽 denotes the AbstractNumbers that will be used for the vectors elements.

See also

AbstractLinearVectorTransportMethod

ManifoldsBase.DiagonalizingOrthonormalBasis — Type

DiagonalizingOrthonormalBasis{𝔽,TV} <: AbstractOrthonormalBasis{𝔽,TangentSpaceType}

An orthonormal basis Ξ as a vector of tangent vectors (of length determined by manifold_dimension) in the tangent space that diagonalizes the curvature tensor $R(u,v)w$ and where the direction frame_direction $v$ has curvature 0.

The type parameter 𝔽 denotes the AbstractNumbers that will be used for the vectors elements.

Constructor

DiagonalizingOrthonormalBasis(frame_direction, 𝔽::AbstractNumbers = ℝ)

ManifoldsBase.GramSchmidtOrthonormalBasis — Type

GramSchmidtOrthonormalBasis{𝔽} <: AbstractOrthonormalBasis{𝔽}

An orthonormal basis obtained from a basis.

Constructor

GramSchmidtOrthonormalBasis(𝔽::AbstractNumbers = ℝ)

ManifoldsBase.ProjectedOrthonormalBasis — Type

ProjectedOrthonormalBasis(method::Symbol, 𝔽::AbstractNumbers = ℝ)

An orthonormal basis that comes from orthonormalization of basis vectors of the ambient space projected onto the subspace representing the tangent space at a given point.

The type parameter 𝔽 denotes the AbstractNumbers that will be used for the vectors elements.

Available methods:

:gram_schmidt uses a modified Gram-Schmidt orthonormalization.
:svd uses SVD decomposition to orthogonalize projected vectors. The SVD-based method should be more numerically stable at the cost of an additional assumption (local metric tensor at a point where the basis is calculated has to be diagonal).

ManifoldsBase.VectorSpaceType — Type

VectorSpaceType

Abstract type for tangent spaces, cotangent spaces, their tensor products, exterior products, etc.

Every vector space fiber is supposed to provide:

a method of constructing vectors,
basic operations: addition, subtraction, multiplication by a scalar and negation (unary minus),
zero_vector(fiber, p) to construct zero vectors at point p,
allocate(X) and allocate(X, T) for vector X and type T,
copyto!(X, Y) for vectors X and Y,
number_eltype(v) for vector v,
vector_space_dimension.

Optionally:

inner product via inner (used to provide Riemannian metric on vector bundles),
flat and sharp,
norm (by default uses inner),
project (for embedded vector spaces),
representation_size (if support for ProductArray is desired),
broadcasting for basic operations.

ManifoldsBase.allocation_promotion_function — Method

allocation_promotion_function(M::AbstractManifold, f, args::Tuple)

Determine the function that must be used to ensure that the allocated representation is of the right type. This is needed for get_vector when a point on a complex manifold is represented by a real-valued vectors with a real-coefficient basis, so that a complex-valued vector representation is allocated.

ManifoldsBase.dual_basis — Method

dual_basis(M::AbstractManifold, p, B::AbstractBasis)

Get the dual basis to B, a basis of a vector space at point p from manifold M.

The dual to the $i$th vector $v_i$ from basis B is a vector $v^i$ from the dual space such that $v^i(v_j) = δ^i_j$, where $δ^i_j$ is the Kronecker delta symbol:

\[δ^i_j = \begin{cases} 1 & \text{ if } i=j, \\ 0 & \text{ otherwise.} \end{cases}\]

ManifoldsBase.get_basis — Method

get_basis(M::AbstractManifold, p, B::AbstractBasis) -> CachedBasis

Compute the basis vectors of the tangent space at a point on manifold M represented by p.

Returned object derives from AbstractBasis and may have a field .vectors that stores tangent vectors or it may store them implicitly, in which case the function get_vectors needs to be used to retrieve the basis vectors.

ManifoldsBase.get_coordinates — Method

get_coordinates(M::AbstractManifold, p, X, B::AbstractBasis)
get_coordinates(M::AbstractManifold, p, X, B::CachedBasis)

Compute a one-dimensional vector of coefficients of the tangent vector X at point denoted by p on manifold M in basis B.

Depending on the basis, p may not directly represent a point on the manifold. For example if a basis transported along a curve is used, p may be the coordinate along the curve. If a CachedBasis is provided, their stored vectors are used, otherwise the user has to provide a method to compute the coordinates.

For the CachedBasis keep in mind that the reconstruction with get_vector requires either a dual basis or the cached basis to be selfdual, for example orthonormal

Vector transport

There are three main functions for vector transport:

Different types of vector transport are implemented using subtypes of AbstractVectorTransportMethod:

ManifoldsBase.AbstractLinearVectorTransportMethod — Type

AbstractLinearVectorTransportMethod <: AbstractVectorTransportMethod

Abstract type for linear methods for transporting vectors, that is transport of a linear combination of vectors is a linear combination of transported vectors.

ManifoldsBase.AbstractVectorTransportMethod — Type

AbstractVectorTransportMethod

Abstract type for methods for transporting vectors. Such vector transports are not necessarily linear.

See also

ManifoldsBase.DifferentiatedRetractionVectorTransport — Type

DifferentiatedRetractionVectorTransport{R<:AbstractRetractionMethod} <:
    AbstractVectorTransportMethod

A type to specify a vector transport that is given by differentiating a retraction. This can be introduced in two ways. Let $\mathcal M$ be a Riemannian manifold, $p\in\mathcal M$ a point, and $X,Y\in T_p\mathcal M$ denote two tangent vectors at $p$.

Given a retraction (cf. AbstractRetractionMethod) $\operatorname{retr}$, the vector transport of X in direction Y (cf. vector_transport_direction) by differentiation this retraction, is given by

\[\mathcal T^{\operatorname{retr}}_{p,Y}X = D_Y\operatorname{retr}_p(Y)[X] = \frac{\mathrm{d}}{\mathrm{d}t}\operatorname{retr}_p(Y+tX)\Bigr|_{t=0}.\]

see ^{[AbsilMahonySepulchre2008]}, Section 8.1.2 for more details.

This can be phrased similarly as a vector_transport_to by introducing $q=\operatorname{retr}_pX$ and defining

\[\mathcal T^{\operatorname{retr}}_{q \gets p}X = \mathcal T^{\operatorname{retr}}_{p,Y}X\]

which in practice usually requires the inverse_retract to exists in order to compute $Y = \operatorname{retr}_p^{-1}q$.

Constructor

DifferentiatedRetractionVectorTransport(m::AbstractRetractionMethod)

ManifoldsBase.ParallelTransport — Type

ParallelTransport = DifferentiatedRetractionVectorTransport{ExponentialRetraction}

Specify to use parallel transport vector transport method.

To be precise let $c(t)$ be a curve depending on the method

the (assumed to be unique) geodesic $c(t) = γ_{p,q}(t)$ from $γ_{p,q}(0)=p$ to $γ_{p,q}(1)=q$ for vector_transport_to $\mathcal P_{q\gets p}Y$
the unique geodesic $c(t)=γ_{p,X}(t)$ from $γ_{p,X}(0)=p$ into direction $\dot γ_{p,X}(0)=X$ for vector_transport_direction $\mathcal P_{p,X}Y$
a given curve $c(0)=p$ for vector_transport_along $\mathcal P^cY$

In these cases $Y\in T_p\mathcal M$ is the vector that we would like to transport from the tangent space at $p=c(0)$ to the tangent space at $c(1)$.

Let $Z\colon [0,1] \to T\mathcal M$, $Z(t)\in T_{c(t)}\mathcal M$ be a smooth vector field along the curve $c$ with $Z(0) = Y$, such that $Z$ is parallel, i.e. its covariant derivative $\frac{\mathrm{D}}{\mathrm{d}t}Z$ is zero. Note that such a $Z$ always exists and is unique.

Then the parallel transport is given by $Z(1)$.

Note that since it is technically the DifferentiatedRetractionVectorTransport of the exp (cf. ExponentialRetraction), we define ParallelTransport as an alias.

ManifoldsBase.PoleLadderTransport — Type

PoleLadderTransport <: AbstractVectorTransportMethod

Specify to use pole_ladder as vector transport method within vector_transport_to, vector_transport_direction, or vector_transport_along, i.e.

Let $X\in T_p\mathcal M$ be a tangent vector at $p\in\mathcal M$ and $q\in\mathcal M$ the point to transport to. Then $x = \exp_pX$ is used to call y =pole_ladder(M, p, x, q) and the resulting vector is obtained by computing $Y = -\log_qy$.

The PoleLadderTransport posesses two advantages compared to SchildsLadderTransport:

it is cheaper to evaluate, if you want to transport several vectors, since the mid point $c$ then stays unchanged.
while both methods are exact if the curvature is zero, pole ladder is even exact in symmetric Riemannian manifolds^[Pennec2018]

The pole ladder was was proposed in ^{[LorenziPennec2014]}. Its name stems from the fact that it resembles a pole ladder when applied to a sequence of points usccessively.

Constructor

PoleLadderTransport(
    retraction = ExponentialRetraction(),
    inverse_retraction = LogarithmicInverseRetraction(),
)

Construct the classical pole ladder that employs exp and log, i.e. as proposed in^{[LorenziPennec2014]}. For an even cheaper transport the inner operations can be changed to an AbstractRetractionMethod retraction and an AbstractInverseRetractionMethod inverse_retraction, respectively.

ManifoldsBase.ProjectionTransport — Type

ProjectionTransport <: AbstractVectorTransportMethod

Specify to use projection onto tangent space as vector transport method within vector_transport_to, vector_transport_direction, or vector_transport_along. See project for details.

ManifoldsBase.ScaledVectorTransport — Type

ScaledVectorTransport{T} <: AbstractVectorTransportMethod

Introduce a scaled variant of any AbstractVectorTransportMethod T, as introduced in ^{[SatoIwai2013]} for some $X\in T_p\mathcal M$ as

\[ \mathcal T^{\mathrm{S}}(X) = \frac{\lVert X\rVert_p}{\lVert \mathcal T(X)\rVert_q}\mathcal T(X).\]

Note that the resulting point q has to be known, i.e. for vector_transport_direction the curve or more precisely its end point has to be known (via an exponential map or a retraction). Therefore a default implementation is only provided for the vector_transport_to

Constructor

ScaledVectorTransport(m::AbstractVectorTransportMethod)

ManifoldsBase.SchildsLadderTransport — Type

SchildsLadderTransport <: AbstractVectorTransportMethod

Specify to use schilds_ladder as vector transport method within vector_transport_to, vector_transport_direction, or vector_transport_along, i.e.

Let $X\in T_p\mathcal M$ be a tangent vector at $p\in\mathcal M$ and $q\in\mathcal M$ the point to transport to. Then

\[P^{\mathrm{S}}_{q\gets p}(X) = \log_q\bigl( \operatorname{retr}_p ( 2\operatorname{retr}_p^{-1}c ) \bigr),\]

where $c$ is the mid point between $q$ and $d=\exp_pX$.

This method employs the internal function schilds_ladder(M, p, d, q) that avoids leaving the manifold.

The name stems from the image of this paralleltogram in a repeated application yielding the image of a ladder. The approximation was proposed in ^{[EhlersPiraniSchild1972]}.

Constructor

SchildsLadderTransport(
    retraction = ExponentialRetraction(),
    inverse_retraction = LogarithmicInverseRetraction(),
)

Construct the classical Schilds ladder that employs exp and log, i.e. as proposed in^{[EhlersPiraniSchild1972]}. For an even cheaper transport these inner operations can be changed to an AbstractRetractionMethod retraction and an AbstractInverseRetractionMethod inverse_retraction, respectively.

ManifoldsBase.default_vector_transport_method — Method

default_vector_transport_method(M::AbstractManifold)

The AbstractVectorTransportMethod that is used when calling vector_transport_along, vector_transport_to, or vector_transport_direction without specifying the vector transport method. By default, this is DifferentiatedRetractionVectorTransport(default_retraction_method(M)).

ManifoldsBase.pole_ladder — Function

pole_ladder(
    M,
    p,
    d,
    q,
    c = mid_point(M, p, q);
    retraction=default_retraction_method(M),
    inverse_retraction=default_inverse_retraction_method(M)
)

Compute an inner step of the pole ladder, that can be used as a vector_transport_to. Let $c = \gamma_{p,q}(\frac{1}{2})$ mid point between p and q, then the pole ladder is given by

\[ \operatorname{Pl}(p,d,q) = \operatorname{retr}_d (2\operatorname{retr}_d^{-1}c)\]

Where the classical pole ladder employs $\operatorname{retr}_d=\exp_d$ and $\operatorname{retr}_d^{-1}=\log_d$ but for an even cheaper transport these can be set to different AbstractRetractionMethod and AbstractInverseRetractionMethod.

When you have $X=log_pd$ and $Y = -\log_q \operatorname{Pl}(p,d,q)$, you will obtain the PoleLadderTransport. When performing multiple steps, this method avoidsd the switching to the tangent space. Keep in mind that after $n$ successive steps the tangent vector reads $Y_n = (-1)^n\log_q \operatorname{Pl}(p_{n-1},d_{n-1},p_n)$.

It is cheaper to evaluate than schilds_ladder, sinc if you want to form multiple ladder steps between p and q, but with different d, there is just one evaluation of a geodesic each., since the center c can be reused.

ManifoldsBase.pole_ladder! — Function

pole_ladder(
    M,
    pl,
    p,
    d,
    q,
    c = mid_point(M, p, q),
    X = allocate_result_type(M, log, d, c);
    retraction = default_retraction_method(M),
    inverse_retraction = default_inverse_retraction_method(M),
)

Compute the pole_ladder, i.e. the result is saved in pl. X is used for storing intermediate inverse retraction.

ManifoldsBase.schilds_ladder — Function

schilds_ladder(
    M,
    p,
    d,
    q,
    c = mid_point(M, q, d);
    retraction = default_retraction_method(M),
    inverse_retraction = default_inverse_retraction_method(M),
)

Perform an inner step of schilds ladder, which can be used as a vector_transport_to, see SchildsLadderTransport. Let $c = \gamma_{q,d}(\frac{1}{2})$ denote the mid point on the shortest geodesic connecting $q$ and the point $d$. Then Schild's ladder reads as

\[\operatorname{Sl}(p,d,q) = \operatorname{retr}_x( 2\operatorname{retr}_p^{-1} c)\]

Where the classical Schilds ladder employs $\operatorname{retr}_d=\exp_d$ and $\operatorname{retr}_d^{-1}=\log_d$ but for an even cheaper transport these can be set to different AbstractRetractionMethod and AbstractInverseRetractionMethod.

In consistency with pole_ladder you can change the way the mid point is computed using the optional parameter c, but note that here it's the mid point between q and d.

When you have $X=log_pd$ and $Y = \log_q \operatorname{Sl}(p,d,q)$, you will obtain the PoleLadderTransport. Then the approximation to the transported vector is given by $\log_q\operatorname{Sl}(p,d,q)$.

When performing multiple steps, this method avoidsd the switching to the tangent space. Hence after $n$ successive steps the tangent vector reads $Y_n = \log_q \operatorname{Pl}(p_{n-1},d_{n-1},p_n)$.

ManifoldsBase.schilds_ladder! — Function

schilds_ladder!(
    M,
    sl
    p,
    d,
    q,
    c = mid_point(M, q, d),
    X = allocate_result_type(M, log, d, c);
    retraction = default_retraction_method(M),
    inverse_retraction = default_inverse_retraction_method(M),
)

Compute schilds_ladder and return the value in the parameter sl. If the required mid point c was computed before, it can be passed using c, and the allocation of new memory can be avoided providing a tangent vector X for the interims result.

vector_transport_along!(
    M::AbstractManifold,
    Y,
    p,
    X,
    c::AbstractVector,
    method::AbstractVectorTransportMethod
) where {T}

Compute the vector transport along a discretized curve c using an AbstractVectorTransportMethod method succesively along the sampled curve.

function vector_transport_along!(
    M::AbstractManifold,
    Y,
    p,
    X,
    c::AbstractVector,
    method::PoleLadderTransport
)

Compute the vector transport along a discretized curve using PoleLadderTransport succesively along the sampled curve. This method is avoiding additional allocations as well as inner exp/log by performing all ladder steps on the manifold and only computing one tangent vector in the end.

vector_transport_along!(
    M::AbstractManifold,
    Y,
    p,
    X,
    c::AbstractVector,
    method::SchildsLadderTransport
)

Compute the vector transport along a discretized curve using SchildsLadderTransport succesively along the sampled curve. This method is avoiding additional allocations as well as inner exp/log by performing all ladder steps on the manifold and only computing one tangent vector in the end.

vector_transport_along!(M::AbstractManifold, Y, p, X, c)
vector_transport_along!(M::AbstractManifold, Y, p, X, c, method::AbstractVectorTransportMethod)

Transport a vector X from the tangent space at a point p on the AbstractManifold M along the curve represented by c using the method, which defaults to default_vector_transport_method(M). The result is saved to Y.

ManifoldsBase.vector_transport_along — Method

vector_transport_along(M::AbstractManifold, p, X, c)
vector_transport_along(M::AbstractManifold, p, X, c, method::AbstractVectorTransportMethod)

ManifoldsBase.vector_transport_direction! — Method

vector_transport_direction!(M::AbstractManifold, Y, p, X, d)
vector_transport_direction!(M::AbstractManifold, Y, p, X, d, method::AbstractVectorTransportMethod)

Transport a vector X from the tangent space at a point p on the AbstractManifold M in the direction indicated by the tangent vector d at p. By default, retract and vector_transport_to! are used with the method, which defaults to default_vector_transport_method(M). The result is saved to Y.

ManifoldsBase.vector_transport_direction — Method

vector_transport_direction(M::AbstractManifold, p, X, d)
vector_transport_direction(M::AbstractManifold, p, X, d, method::AbstractVectorTransportMethod)

vector_transport_to!(M::AbstractManifold, Y, p, X, q, method::PoleLadderTransport)

Perform a vector transport by using PoleLadderTransport.

vector_transport_to!(M::AbstractManifold, Y, p, X, q, method::ProjectionTransport)

Transport a vector X from the tangent space at p on the AbstractManifold M by interpreting it as an element of the embedding and then projecting it onto the tangent space at q. This function needs to be separately implemented for each manifold because projection project may also change vector representation (if it's different than in the embedding) and it is assumed that the vector X already has the correct representation for M.

vector_transport_to!(M::AbstractManifold, Y, p, X, q, method::SchildsLadderTransport)

Perform a vector transport by using SchildsLadderTransport.