Vector transport

Similar to the exponential and logarithmic map also the parallel transport might be costly to compute, especially when there is no closed form solution known and it has to be approximated with numerical methods. Similar to the retraction and its inverse, the generalisation of the parallel transport can be phrased as follows

A vector transport is a way to transport a vector between two tangent spaces. Let $p,q ∈ \mathcal M$ be given, $c$ the curve along which we want to transport (cf. parallel transport, for example a geodesic or curve given by a retraction. We can specify the geodesic or curve a retraction realises for example by a direction $d$.

More precisely using [AMS08], Def. 8.1.1, a vector transport $T_{p,d}: T_p\mathcal M \to T_q\mathcal M$, $p∈ \mathcal M$, $Y∈ T_p\mathcal M$ is a smooth mapping associated to a retraction $\operatorname{retr}_p(Y) = q$ such that

  1. (associated retraction) $\mathcal T_{p,d}X ∈ T_q\mathcal M$ if and only if $q = \operatorname{retr}_p(d)$,
  2. (consistency) $\mathcal T_{p,0_p}X = X$ for all $X∈T_p\mathcal M$,
  3. (linearity) $\mathcal T_{p,d}(αX+βY) = \mathcal αT_{p,d}X + \mathcal βT_{p,d}Y$ for all $α, β ∈ 𝔽$,

hold.

Currently the following methods for vector transport are defined in ManifoldsBase.jl.

ManifoldsBase.default_vector_transport_methodMethod
default_vector_transport_method(M::AbstractManifold)
default_vector_transport_method(M::AbstractManifold, ::Type{T}) where {T}

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 ParallelTransport.

This method can also be specified more precisely with a point type T, for the case that on a M there are two different representations of points, which provide different vector transport methods.

source
ManifoldsBase.vector_transport_alongMethod
vector_transport_along(
    M::AbstractManifold,
    p,
    X,
    c::AbstractVector,
    m::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.

source
ManifoldsBase.vector_transport_alongMethod
function vector_transport_along(
    M::AbstractManifold,
    p,
    X,
    c::AbstractVector,
    m::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.

source
ManifoldsBase.vector_transport_directionFunction
vector_transport_direction(M::AbstractManifold, p, X, d)
vector_transport_direction(M::AbstractManifold, p, X, d, m::AbstractVectorTransportMethod)

Given an AbstractManifold$\mathcal M$ the vector transport is a generalization of the parallel_transport_direction that identifies vectors from different tangent spaces.

More precisely using [AMS08], Def. 8.1.1, a vector transport $T_{p,d}: T_p\mathcal M \to T_q\mathcal M$, $p∈ \mathcal M$, $Y∈ T_p\mathcal M$ is a smooth mapping associated to a retraction $\operatorname{retr}_p(Y) = q$ such that

  1. (associated retraction) $\mathcal T_{p,d}X ∈ T_q\mathcal M$ if and only if $q = \operatorname{retr}_p(d)$.
  2. (consistency) $\mathcal T_{p,0_p}X = X$ for all $X∈T_p\mathcal M$
  3. (linearity) $\mathcal T_{p,d}(αX+βY) = α\mathcal T_{p,d}X + β\mathcal T_{p,d}Y$

For the AbstractVectorTransportMethod we might even omit the third point. The AbstractLinearVectorTransportMethods are linear.

Input Parameters

Usually this method requires a AbstractRetractionMethod as well. By default this is assumed to be the default_retraction_method or implicitly given (and documented) for a vector transport. To explicitly distinguish different retractions for a vector transport, see VectorTransportDirection.

Instead of spcifying a start direction d one can equivalently also specify a target tanget space $T_q\mathcal M$, see vector_transport_to. By default vector_transport_direction falls back to using vector_transport_to, using the default_retraction_method on M.

source
ManifoldsBase.vector_transport_direction!Function
vector_transport_direction!(M::AbstractManifold, Y, p, X, d)
vector_transport_direction!(M::AbstractManifold, Y, p, X, d, m::AbstractVectorTransportMethod)

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

See vector_transport_direction for more details.

source
ManifoldsBase.vector_transport_toFunction
vector_transport_to(M::AbstractManifold, p, X, q)
vector_transport_to(M::AbstractManifold, p, X, q, m::AbstractVectorTransportMethod)
vector_transport_to(M::AbstractManifold, p, X, q, m::AbstractVectorTransportMethod)

Transport a vector X from the tangent space at a point p on the AbstractManifoldM along a curve implicitly given by an AbstractRetractionMethod associated to m. By default m is the default_vector_transport_method(M). To explicitly specify a (different) retraction to the implicitly assumeed retraction, see VectorTransportTo. Note that some vector transport methods might also carry their own retraction they are associated to, like the DifferentiatedRetractionVectorTransport and some are even independent of the retraction, for example the ProjectionTransport.

This method is equivalent to using $d = \operatorname{retr}^{-1}_p(q)$ in vector_transport_direction(M, p, X, q, m, r), where you can find the formal definition. This is the fallback for VectorTransportTo.

source

Types of vector transports

To distinguish different types of vector transport we introduce the AbstractVectorTransportMethod. The following concrete types are available.

ManifoldsBase.AbstractLinearVectorTransportMethodType
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.

source
ManifoldsBase.DifferentiatedRetractionVectorTransportType
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∈\mathcal M$ a point, and $X,Y∈ 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 [AMS08], 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)
source
ManifoldsBase.EmbeddedVectorTransportType
EmbeddedVectorTransport{T<:AbstractVectorTransportMethod} <: AbstractVectorTransportMethod

Compute a vector transport by using the vector transport of type T in the embedding and projecting the result.

Constructor

EmbeddedVectorTransport(vt::AbstractVectorTransportMethod)

Generate the vector transport with vector transport vt to use in the embedding.

source
ManifoldsBase.PoleLadderTransportType
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∈ T_p\mathcal M$ be a tangent vector at $p∈\mathcal M$ and $q∈\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 [Pen18]

The pole ladder was was proposed in [LP13]. 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[LP13]. For an even cheaper transport the inner operations can be changed to an AbstractRetractionMethodretraction and an AbstractInverseRetractionMethodinverse_retraction, respectively.

source
ManifoldsBase.ScaledVectorTransportType
ScaledVectorTransport{T} <: AbstractVectorTransportMethod

Introduce a scaled variant of any AbstractVectorTransportMethodT, as introduced in [SI13] for some $X∈ 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)
source
ManifoldsBase.SchildsLadderTransportType
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∈ T_p\mathcal M$ be a tangent vector at $p∈\mathcal M$ and $q∈\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 [EPS72].

Constructor

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

Construct the classical Schilds ladder that employs exp and log, i.e. as proposed in [EPS72]. For an even cheaper transport these inner operations can be changed to an AbstractRetractionMethodretraction and an AbstractInverseRetractionMethodinverse_retraction, respectively.

source
ManifoldsBase.VectorTransportDirectionType
VectorTransportDirection{VM<:AbstractVectorTransportMethod,RM<:AbstractRetractionMethod}
    <: AbstractVectorTransportMethod

Specify a vector_transport_direction using a AbstractVectorTransportMethod with explicitly using the AbstractRetractionMethod to determine the point in the specified direction where to transsport to. Note that you only need this for the non-default (non-implicit) second retraction method associated to a vector transport, i.e. when a first implementation assumed an implicit associated retraction.

source
ManifoldsBase.VectorTransportToType
VectorTransportTo{VM<:AbstractVectorTransportMethod,RM<:AbstractRetractionMethod}
    <: AbstractVectorTransportMethod

Specify a vector_transport_to using a AbstractVectorTransportMethod with explicitly using the AbstractInverseRetractionMethod to determine the direction that transports from in pto q. Note that you only need this for the non-default (non-implicit) second retraction method associated to a vector transport, i.e. when a first implementation assumed an implicit associated retraction.

source
ManifoldsBase.VectorTransportWithKeywordsType
VectorTransportWithKeywords{V<:AbstractVectorTransportMethod, K} <: AbstractVectorTransportMethod

Since vector transports might have keywords, this type is a way to set them as an own type to be used as a specific vector transport. Another reason for this type is that we dispatch on the vector transport first and only the last layer would be implemented with keywords, so this way they can be passed down.

Fields

  • vector_transport the vector transport that is decorated with keywords
  • kwargs the keyword arguments

Note that you can nest this type. Then the most outer specification of a keyword is used.

Constructor

VectorTransportWithKeywords(m::T; kwargs...) where {T <: AbstractVectorTransportMethod}

Specify the subtype T <:AbstractVectorTransportMethod to have keywords kwargs....

source

Functions to implement (on Layer III)

While you should always add your documentation to the first layer vector transport methods above when implementing new manifolds, the actual implementation happens on the following functions on layer III.

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

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 avoids 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.

source
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, typeof(p)),
    inverse_retraction = default_inverse_retraction_method(M, typeof(p)),
)

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

source
ManifoldsBase.schilds_ladderFunction
schilds_ladder(
    M,
    p,
    d,
    q,
    c = mid_point(M, q, d);
    retraction = default_retraction_method(M, typeof(p)),
    inverse_retraction = default_inverse_retraction_method(M, typeof(p)),
)

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}_p( 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)$.

source
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, typeof(p)),
    inverse_retraction = default_inverse_retraction_method(M, typeof(p)),
)

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.

source
ManifoldsBase.vector_transport_along_embedded!Method
vector_transport_along_embedded!(M::AbstractManifold, Y, p, X, c, m::AbstractVectorTransportMethod; kwargs...)

Compute the vector transport of X from $T_p\mathcal M$ along the curve c using the vector transport method m in the embedding and projecting the result back on the corresponding tangent space. The result is computed in place of Y.

source
ManifoldsBase.vector_transport_along_project!Method
vector_transport_along_project!(M::AbstractManifold, Y, p, X, c::AbstractVector)

Compute the vector transport of X from $T_p\mathcal M$ along the curve c using a projection. The result is computed in place of Y.

source
ManifoldsBase.vector_transport_direction_embedded!Method
vector_transport_direction_embedded!(M::AbstractManifold, Y, p, X, d, m::AbstractVectorTransportMethod)

Compute the vector transport of X from $T_p\mathcal M$ into the direction d using the AbstractRetractionMethodm in the embedding.

The default implementataion requires one allocation for the points and tangent vectors in the embedding and the resulting point, but the final projection is performed in place of Y

source
ManifoldsBase.vector_transport_to_embedded!Method
vector_transport_to_embedded!(M::AbstractManifold, Y, p, X, q, m::AbstractRetractionMethod)

Compute the vector transport of X from $T_p\mathcal M$ to the point q using the of the AbstractRetractionMethodm in th embedding.

The default implementataion requires one allocation for the points and tangent vectors in the embedding and the resulting point, but the final projection is performed in place of Y

source
ManifoldsBase.vector_transport_to_project!Method
vector_transport_to_project!(M::AbstractManifold, Y, p, X, q)

Compute a vector transport by projecting $X\in T_p\mathcal M$ onto the tangent space $T_q\mathcal M$ at $q$ in place of Y.

source