Retractions and inverse Retractions

The exponential and logarithmic map might be too expensive to evaluate or not be available in a very stable numerical way on certain manifolds $\mathcal M$. Retractions provide a possibly cheap, fast and stable alternative.

A retraction $\operatorname{retr}_p: T_p\mathcal M → \mathcal M$ is a smooth map that fulfils (for all $p\in\mathcal M$) that

  1. $\operatorname{retr}_p(0) = p$
  2. $D\operatorname{retr}_p(0): T_p\mathcal M \to T_p\mathcal M$ is the identity map,

i.e. $D\operatorname{retr}_p(0)[X]=X$ holds for all $X\in T_p\mathcal M$,

where $D\operatorname{retr}_p$ denotes the differential of the retraction.

A retraction $\operatorname{retr}_p$ can be interpreted as a first order approximation to the exponential map $\exp_p$.

The retraction is called of second order if for all $X$ the curves $c(t) = R_p(tX)$ have a zero acceleration at $t=0$, i.e. $c''(0) = 0$.

The following figure compares the exponential map exp(M, p, X) on the Circle (ℂ) (or Sphere(1) embedded in $ℝ^2$ with one possible retraction, the one based on projections. Note especially that $\operatorname{dist}(p,q)=\lVert X\rVert_p$ while this is not the case for the result $\operatorname{retr}_p(X) = q'$.

A comparison of the exponential map and a retraction on the Circle.

Similar to the exponential map the retraction might not be globally invertible, but locally it is. So locally one can define the inverse retraction $\operatorname{retr}_p^{-1}\colon \mathcal M \to T_p\mathcal M$, which can be seen as a first order approximation to the logarithmic map. Within the ManifoldsBase.jl interface the inverse retraction is called inverse_retract.

The general interface looks as follows.

ManifoldsBase.inverse_retract — Function
inverse_retract(M::AbstractManifold, p, q)
inverse_retract(M::AbstractManifold, p, q, method::AbstractInverseRetractionMethod

Compute the inverse retraction, a cheaper, approximate version of the logarithmic map), of points p and q on the AbstractManifold M.

Inverse retraction method can be specified by the last argument, defaulting to default_inverse_retraction_method(M). For available inverse retractions on certain manifolds see the documentation on the corresponding manifold.

See also retract.

ManifoldsBase.inverse_retract! — Function
inverse_retract!(M::AbstractManifold, X, p, q[, method::AbstractInverseRetractionMethod])

Compute the inverse retraction, a cheaper, approximate version of the logarithmic map), of points p and q on the AbstractManifold M. Result is saved to X.

Inverse retraction method can be specified by the last argument, defaulting to default_inverse_retraction_method(M). See the documentation of respective manifolds for available methods.

See also retract!.

ManifoldsBase.retract — Function
retract(M::AbstractManifold, p, X, method::AbstractRetractionMethod=default_retraction_method(M))
retract(M::AbstractManifold, p, X, t::Real=1, method::AbstractRetractionMethod=default_retraction_method(M))

Compute a retraction, a cheaper, approximate version of the exponential map, from p into direction X, scaled by t, on the AbstractManifold M.

A retraction $\operatorname{retr}_p: T_p\mathcal M → \mathcal M$ is a smooth map that fulfils

  1. $\operatorname{retr}_p(0) = p$
  2. $D\operatorname{retr}_p(0): T_p\mathcal M \to T_p\mathcal M$ is the identity map,

i.e. $D\operatorname{retr}_p(0)[X]=X$ holds for all $X\in T_p\mathcal M$,

where $D\operatorname{retr}_p$ denotes the differential of the retraction

The retraction is called of second order if for all $X$ the curves $c(t) = R_p(tX)$ have a zero acceleration at $t=0$, i.e. $c''(0) = 0$.

Retraction method can be specified by the last argument, defaulting to default_retraction_method(M). For further available retractions see the documentation of respective manifolds.

Locally, the retraction is invertible. For the inverse operation, see inverse_retract.

ManifoldsBase.retract! — Function
retract!(M::AbstractManifold, q, p, X)
retract!(M::AbstractManifold, q, p, X, t::Real=1)
retract!(M::AbstractManifold, q, p, X, method::AbstractRetractionMethod)
retract!(M::AbstractManifold, q, p, X, t::Real=1, method::AbstractRetractionMethod)

Compute a retraction, a cheaper, approximate version of the exponential map, from p into direction X, scaled by t, on the AbstractManifold manifold M. Result is saved to q.

Retraction method can be specified by the last argument, defaulting to default_retraction_method(M). See the documentation of respective manifolds for available methods.

See retract for more details.

Types of Retractions

To distinguish different types of retractions, the last argument of the retraction as well as its inverse specifies a type. The following ones are available.

ManifoldsBase.EmbeddedInverseRetraction — Type

EmbeddedInverseRetraction{T<:AbstractInverseRetractionMethod} <: AbstractInverseRetractionMethod

Compute an inverse retraction by using the inverse retraction of type T in the embedding and projecting the result

Constructor

EmbeddedInverseRetraction(r::AbstractInverseRetractionMethod)

Generate the inverse retraction with inverse retraction r to use in the embedding.

ManifoldsBase.EmbeddedRetraction — Type
EmbeddedRetraction{T<:AbstractRetractionMethod} <: AbstractRetractionMethod

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

Constructor

EmbeddedRetraction(r::AbstractRetractionMethod)

Generate the retraction with retraction r to use in the embedding.

ManifoldsBase.NLSolveInverseRetraction — Type
NLSolveInverseRetraction{T<:AbstractRetractionMethod,TV,TK} <:
    ApproximateInverseRetraction

An inverse retraction method for approximating the inverse of a retraction using NLsolve.

Constructor

NLSolveInverseRetraction(
    method::AbstractRetractionMethod[, X0];
    project_tangent=false,
    project_point=false,
    nlsolve_kwargs...,
)

Constructs an approximate inverse retraction for the retraction method with initial guess X0, defaulting to the zero vector. If project_tangent is true, then the tangent vector is projected before the retraction using project. If project_point is true, then the resulting point is projected after the retraction. nlsolve_kwargs are keyword arguments passed to NLsolve.nlsolve.

ManifoldsBase.ODEExponentialRetraction — Type
ODEExponentialRetraction{T<:AbstractRetractionMethod, B<:AbstractBasis} <: AbstractRetractionMethod

Approximate the exponential map on the manifold by evaluating the ODE descripting the geodesic at 1, assuming the default connection of the given manifold by solving the ordinary differential equation

\[\frac{d^2}{dt^2} p^k + Γ^k_{ij} \frac{d}{dt} p_i \frac{d}{dt} p_j = 0,\]

where $Γ^k_{ij}$ are the Christoffel symbols of the second kind, and the Einstein summation convention is assumed.

Constructor

ODEExponentialRetraction(
    r::AbstractRetractionMethod,
    b::AbstractBasis=DefaultOrthogonalBasis(),
)

Generate the retraction with a retraction to use internally (for some approaches) and a basis for the tangent space(s).

ManifoldsBase.PadeInverseRetraction — Type
PadeInverseRetraction{m} <: AbstractRetractionMethod

An inverse retraction based on the Padé approximation of order $m$ for the retraction.

ManifoldsBase.PadeRetraction — Type
PadeRetraction{m} <: AbstractRetractionMethod

A retraction based on the Padé approximation of order $m$

ManifoldsBase.ProjectionRetraction — Type
ProjectionRetraction <: AbstractRetractionMethod

Retractions that are based on projection and usually addition in the embedding.

ManifoldsBase.ShootingInverseRetraction — Type
ShootingInverseRetraction <: ApproximateInverseRetraction

Approximating the inverse of a retraction using the shooting method.

This implementation of the shooting method works by using another inverse retraction to form the first guess of the vector. This guess is updated by shooting the vector, guessing the vector pointing from the shooting result to the target point, and transporting this vector update back to the initial point on a discretized grid. This process is repeated until the norm of the vector update falls below a specified tolerance or the maximum number of iterations is reached.

Fields

  • retraction::AbstractRetractionMethod: The retraction whose inverse is approximated.
  • initial_inverse_retraction::AbstractInverseRetractionMethod: The inverse retraction used to form the initial guess of the vector.
  • vector_transport::AbstractVectorTransportMethod: The vector transport used to transport the initial guess of the vector.
  • num_transport_points::Int: The number of discretization points used for vector transport in the shooting method. 2 is the minimum number of points, including just the endpoints.
  • tolerance::Real: The tolerance for the shooting method.
  • max_iterations::Int: The maximum number of iterations for the shooting method.

The functions on layer 3

While you should always add your documentation to retract or retract! when implementing new manifolds, the actual implementation happens on the following functions on layer III.

ManifoldsBase.inverse_retract_shooting — Method
inverse_retract_shooting(M::AbstractManifold, p, q, m::ShootingInverseRetraction)

Approximate the inverse of a retraction using the shooting method.