diff --git a/previews/PR217/.documenter-siteinfo.json b/previews/PR217/.documenter-siteinfo.json index c24f7286..77282dc8 100644 --- a/previews/PR217/.documenter-siteinfo.json +++ b/previews/PR217/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.7","generation_timestamp":"2024-12-09T12:10:25","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.7","generation_timestamp":"2024-12-09T12:36:00","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/previews/PR217/bases/index.html b/previews/PR217/bases/index.html index c574a214..75aee309 100644 --- a/previews/PR217/bases/index.html +++ b/previews/PR217/bases/index.html @@ -1,8 +1,8 @@ -Bases for tangent spaces · ManifoldsBase.jl
GitHub

Bases for tangent spaces

The following functions and types provide support for bases of the tangent space of different manifolds. Moreover, bases of the cotangent space are also supported, though this description focuses on the tangent space. An orthonormal basis of the tangent space $T_p \mathcal M$ of (real) dimension $n$ has a real-coefficient basis $e_1, e_2, …, e_n$ if $\mathrm{Re}(g_p(e_i, e_j)) = δ_{ij}$ for each $i,j ∈ \{1, 2, …, n\}$ where $g_p$ is the Riemannian metric at point $p$. A vector $X$ from the tangent space $T_p \mathcal M$ can be expressed in Einstein notation as a sum $X = X^i e_i$, where (real) coefficients $X^i$ are calculated as $X^i = \mathrm{Re}(g_p(X, e_i))$.

The main types are:

The main functions are:

  • get_basis precomputes a basis at a certain point.
  • get_coordinates returns coordinates of a tangent vector.
  • get_vector returns a vector for the specified coordinates.
  • get_vectors returns a vector of basis vectors. Calling it should be avoided for high-dimensional manifolds.
ManifoldsBase.AbstractBasis — Type
AbstractBasis{𝔽,VST<:VectorSpaceType}

Abstract type that represents a 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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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)
source
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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
ManifoldsBase.DefaultOrthonormalBasis — Type
DefaultOrthonormalBasis(𝔽::AbstractNumbers = ℝ, vs::VectorSpaceType = TangentSpaceType())

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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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 as coefficients in linear combinations of the basis vectors.

Constructor

DiagonalizingOrthonormalBasis(frame_direction, 𝔽::AbstractNumbers = ℝ)
source
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 as coefficients in linear combinations of the basis vectors.

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).
source
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(X) for vector X,
  • 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,
  • broadcasting for basic operations.
source
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.

source
ManifoldsBase.change_basis — Method
change_basis(M::AbstractManifold, p, c, B_in::AbstractBasis, B_out::AbstractBasis)

Given a vector with coordinates c at point p from manifold M in basis B_in, compute coordinates of the same vector in basis B_out.

source
ManifoldsBase.coordinate_eltype — Method
coordinate_eltype(M::AbstractManifold, p, 𝔽::AbstractNumbers)

Get the element type for 𝔽-field coordinates of the tangent space at a point p from manifold M. This default assumes that usually complex bases of complex manifolds have real coordinates but it can be overridden by a more specific method.

source
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} +Bases for tangent spaces · ManifoldsBase.jl

GitHub

Bases for tangent spaces

The following functions and types provide support for bases of the tangent space of different manifolds. Moreover, bases of the cotangent space are also supported, though this description focuses on the tangent space. An orthonormal basis of the tangent space $T_p \mathcal M$ of (real) dimension $n$ has a real-coefficient basis $e_1, e_2, …, e_n$ if $\mathrm{Re}(g_p(e_i, e_j)) = δ_{ij}$ for each $i,j ∈ \{1, 2, …, n\}$ where $g_p$ is the Riemannian metric at point $p$. A vector $X$ from the tangent space $T_p \mathcal M$ can be expressed in Einstein notation as a sum $X = X^i e_i$, where (real) coefficients $X^i$ are calculated as $X^i = \mathrm{Re}(g_p(X, e_i))$.

The main types are:

The main functions are:

  • get_basis precomputes a basis at a certain point.
  • get_coordinates returns coordinates of a tangent vector.
  • get_vector returns a vector for the specified coordinates.
  • get_vectors returns a vector of basis vectors. Calling it should be avoided for high-dimensional manifolds.
ManifoldsBase.AbstractBasis — Type
AbstractBasis{𝔽,VST<:VectorSpaceType}

Abstract type that represents a 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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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)
source
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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
ManifoldsBase.DefaultOrthonormalBasis — Type
DefaultOrthonormalBasis(𝔽::AbstractNumbers = ℝ, vs::VectorSpaceType = TangentSpaceType())

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 as coefficients in linear combinations of the basis vectors.

See also

VectorSpaceType

source
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 as coefficients in linear combinations of the basis vectors.

Constructor

DiagonalizingOrthonormalBasis(frame_direction, 𝔽::AbstractNumbers = ℝ)
source
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 as coefficients in linear combinations of the basis vectors.

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).
source
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(X) for vector X,
  • 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,
  • broadcasting for basic operations.
source
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.

source
ManifoldsBase.change_basis — Method
change_basis(M::AbstractManifold, p, c, B_in::AbstractBasis, B_out::AbstractBasis)

Given a vector with coordinates c at point p from manifold M in basis B_in, compute coordinates of the same vector in basis B_out.

source
ManifoldsBase.coordinate_eltype — Method
coordinate_eltype(M::AbstractManifold, p, 𝔽::AbstractNumbers)

Get the element type for 𝔽-field coordinates of the tangent space at a point p from manifold M. This default assumes that usually complex bases of complex manifolds have real coordinates but it can be overridden by a more specific method.

source
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}\]

source
ManifoldsBase.get_basis — Method
get_basis(M::AbstractManifold, p, B::AbstractBasis; kwargs...) -> 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.

See also: get_coordinates, get_vector

source
ManifoldsBase.get_coordinates — Function
get_coordinates(M::AbstractManifold, p, X, B::AbstractBasis=DefaultOrthonormalBasis())
-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

See also: get_vector, get_basis

source
ManifoldsBase.get_vector — Function
X = get_vector(M::AbstractManifold, p, c, B::AbstractBasis=DefaultOrthonormalBasis())

Convert a one-dimensional vector of coefficients in a basis B of the tangent space at p on manifold M to a tangent vector X at p.

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.

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

See also: get_coordinates, get_basis

source
ManifoldsBase.get_vectors — Method
get_vectors(M::AbstractManifold, p, B::AbstractBasis=get_basis(M, p, DefaultOrthonormalBasis()))

Get the basis vectors of basis B of the tangent space at point p. The function may or may not work if passed a basis other than a CachedBasis. A CachedBasis can be obtained by calling get_basis.

source
ManifoldsBase.gram_schmidt — Method
gram_schmidt(M::AbstractManifold{𝔽}, p, B::AbstractBasis{𝔽}) where {𝔽}
-gram_schmidt(M::AbstractManifold, p, V::AbstractVector)

Compute an ONB in the tangent space at p on the [AbstractManifold](@ref} M from either an AbstractBasis basis ´B´ or a set of (at most) manifold_dimension(M) many vectors. Note that this method requires the manifold and basis to work on the same AbstractNumbers 𝔽, i.e. with real coefficients.

The method always returns a basis, i.e. linearly dependent vectors are removed.

Keyword arguments

  • warn_linearly_dependent (false) – warn if the basis vectors are not linearly independent
  • skip_linearly_dependent (false) – whether to just skip (true) a vector that is linearly dependent to the previous ones or to stop (false, default) at that point
  • return_incomplete_set (false) – throw an error if the resulting set of vectors is not a basis but contains less vectors

further keyword arguments can be passed to set the accuracy of the independence test. Especially atol is raised slightly by default to atol = 5*1e-16.

Return value

When a set of vectors is orthonormalized a set of vectors is returned. When an AbstractBasis is orthonormalized, a CachedBasis is returned.

source
ManifoldsBase.hat — Method
hat(M::AbstractManifold, p, Xⁱ)

Given a basis $e_i$ on the tangent space at a point p and tangent component vector $X^i ∈ ℝ$, compute the equivalent vector representation $X=X^i e_i$, where Einstein summation notation is used:

\[∧ : X^i ↦ X^i e_i\]

For array manifolds, this converts a vector representation of the tangent vector to an array representation. The vee map is the hat map's inverse.

source
ManifoldsBase.number_of_coordinates — Method
number_of_coordinates(M::AbstractManifold, B::AbstractBasis)
-number_of_coordinates(M::AbstractManifold, ::𝔾)

Compute the number of coordinates in basis of field type 𝔾 on a manifold M. This also corresponds to the number of vectors represented by B, or stored within B in case of a CachedBasis.

source
ManifoldsBase.vee — Method
vee(M::AbstractManifold, p, X)

Given a basis $e_i$ on the tangent space at a point p and tangent vector X, compute the vector components $X^i ∈ ℝ$, such that $X = X^i e_i$, where Einstein summation notation is used:

\[\vee : X^i e_i ↦ X^i\]

For array manifolds, this converts an array representation of the tangent vector to a vector representation. The hat map is the vee map's inverse.

source
+\end{cases}\]

source
ManifoldsBase.get_basis — Method
get_basis(M::AbstractManifold, p, B::AbstractBasis; kwargs...) -> 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.

See also: get_coordinates, get_vector

source
ManifoldsBase.get_coordinates — Function
get_coordinates(M::AbstractManifold, p, X, B::AbstractBasis=DefaultOrthonormalBasis())
+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

See also: get_vector, get_basis

source
ManifoldsBase.get_vector — Function
X = get_vector(M::AbstractManifold, p, c, B::AbstractBasis=DefaultOrthonormalBasis())

Convert a one-dimensional vector of coefficients in a basis B of the tangent space at p on manifold M to a tangent vector X at p.

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.

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

See also: get_coordinates, get_basis

source
ManifoldsBase.get_vectors — Method
get_vectors(M::AbstractManifold, p, B::AbstractBasis=get_basis(M, p, DefaultOrthonormalBasis()))

Get the basis vectors of basis B of the tangent space at point p. The function may or may not work if passed a basis other than a CachedBasis. A CachedBasis can be obtained by calling get_basis.

source
ManifoldsBase.gram_schmidt — Method
gram_schmidt(M::AbstractManifold{𝔽}, p, B::AbstractBasis{𝔽}) where {𝔽}
+gram_schmidt(M::AbstractManifold, p, V::AbstractVector)

Compute an ONB in the tangent space at p on the [AbstractManifold](@ref} M from either an AbstractBasis basis ´B´ or a set of (at most) manifold_dimension(M) many vectors. Note that this method requires the manifold and basis to work on the same AbstractNumbers 𝔽, i.e. with real coefficients.

The method always returns a basis, i.e. linearly dependent vectors are removed.

Keyword arguments

  • warn_linearly_dependent (false) – warn if the basis vectors are not linearly independent
  • skip_linearly_dependent (false) – whether to just skip (true) a vector that is linearly dependent to the previous ones or to stop (false, default) at that point
  • return_incomplete_set (false) – throw an error if the resulting set of vectors is not a basis but contains less vectors

further keyword arguments can be passed to set the accuracy of the independence test. Especially atol is raised slightly by default to atol = 5*1e-16.

Return value

When a set of vectors is orthonormalized a set of vectors is returned. When an AbstractBasis is orthonormalized, a CachedBasis is returned.

source
ManifoldsBase.hat — Method
hat(M::AbstractManifold, p, Xⁱ)

Given a basis $e_i$ on the tangent space at a point p and tangent component vector $X^i ∈ ℝ$, compute the equivalent vector representation $X=X^i e_i$, where Einstein summation notation is used:

\[∧ : X^i ↦ X^i e_i\]

For array manifolds, this converts a vector representation of the tangent vector to an array representation. The vee map is the hat map's inverse.

source
ManifoldsBase.number_of_coordinates — Method
number_of_coordinates(M::AbstractManifold, B::AbstractBasis)
+number_of_coordinates(M::AbstractManifold, ::𝔾)

Compute the number of coordinates in basis of field type 𝔾 on a manifold M. This also corresponds to the number of vectors represented by B, or stored within B in case of a CachedBasis.

source
ManifoldsBase.vee — Method
vee(M::AbstractManifold, p, X)

Given a basis $e_i$ on the tangent space at a point p and tangent vector X, compute the vector components $X^i ∈ ℝ$, such that $X = X^i e_i$, where Einstein summation notation is used:

\[\vee : X^i e_i ↦ X^i\]

For array manifolds, this converts an array representation of the tangent vector to a vector representation. The hat map is the vee map's inverse.

source
diff --git a/previews/PR217/decorator/index.html b/previews/PR217/decorator/index.html index 565ceb72..765e6f4d 100644 --- a/previews/PR217/decorator/index.html +++ b/previews/PR217/decorator/index.html @@ -1,3 +1,3 @@ -Decorating/Extending a Manifold · ManifoldsBase.jl
GitHub

A Decorator for manifolds

Several properties of a manifold are often implicitly assumed, for example the choice of the (Riemannian) metric, the group structure or the embedding. The latter shall serve as an example how to either implicitly or explicitly specify the embedding to avoid re-implementations and/or distinguish different embeddings.

The abstract decorator

When first implementing a manifold, it might be beneficial to dispatch certain computations to already existing manifolds. For an embedded manifold that is isometrically embedded this might be the inner the manifold inherits in each tangent space from its embedding.

This means we would like to dispatch the default implementation of a function to some other manifold. We refer to this as implicit decoration, since one can not “see” explicitly that a certain manifold inherits this property. As an example consider the Sphere. At each point the tangent space can be identified with a subspace of the tangent space in the embedding, the Euclidean manifold which the unit vectors of the sphere belong to. Thus every tangent space inherits its metric from the embedding. Since in the default implementation in Manifolds.jl points are represented by unit vectors and tangent vectors at a point as vectors orthogonal to that point, we can just dispatch the inner product to the embedding without having to re-implement this. The manifold using such an implicit dispatch just has to be a subtype of AbstractDecoratorManifold.

Traits with an inheritance hierarchy

The properties mentioned above might form a hierarchy. For embedded manifolds, again, we might have just a manifold whose points are represented in some embedding. If the manifold is even isometrically embedded, it is embedded but also inherits the Riemannian metric by restricting the metric from the embedding to the corresponding tangent space under consideration. But it also inherits the functions defined for the plain embedding, for example checking some conditions for the validity of points and vectors. If it is even a submanifold, also further functions are inherited like the shortest_geodesic.

We use a variation of Tim Holy's Traits Trick (THTT) which takes into account this nestedness of traits.

ManifoldsBase.AbstractDecoratorManifold — Type
AbstractDecoratorManifold{𝔽} <: AbstractManifold{𝔽}

Declare a manifold to be an abstract decorator. A manifold which is a subtype of is a decorated manifold, i.e. has

  • certain additional properties or
  • delegates certain properties to other manifolds.

Most prominently, a manifold might be an embedded manifold, i.e. points on a manifold $\mathcal M$ are represented by (some, maybe not all) points on another manifold $\mathcal N$. Depending on the type of embedding, several functions are dedicated to the embedding. For example if the embedding is isometric, then the inner does not have to be implemented for $\mathcal M$ but can be automatically implemented by deligation to $\mathcal N$.

This is modelled by the AbstractDecoratorManifold and traits. These are mapped to functions, which determine the types of transparencies.

source
ManifoldsBase.IsExplicitDecorator — Type
IsExplicitDecorator <: AbstractTrait

Specify that a certain type should dispatch per default to its decorated_manifold.

Note

Any decorator behind this decorator might not have any effect, since the function dispatch is moved to its field at this point. Therefore this decorator should always be last in the TraitList.

source
ManifoldsBase.TraitList — Type
TraitList <: AbstractTrait

Combine two traits into a combined trait. Note that this introduces a preceedence. the first of the traits takes preceedence if a trait is implemented for both functions.

Constructor

TraitList(head::AbstractTrait, tail::AbstractTrait)
source
ManifoldsBase.@next_trait_function — Macro
next_trait_function(trait_type, sig)

Define a special trait-handling method for function indicated by sig. It does not change the result but the presence of such additional methods may prevent method recursion limits in Julia's inference from being triggered. Some functions may work faster after adding methods generated by next_trait_function.

See the "Trait recursion breaking" section at the bottom of src/decorator_trait.jl file for an example of intended usage.

source
ManifoldsBase.active_traits — Method
active_traits(f, args...)

Return the list of traits applicable to the given call of function f`. This function should be overloaded for specific function calls.

source
ManifoldsBase.merge_traits — Method
merge_traits(t1, t2, trest...)

Merge two traits into a nested list of traits. Note that this takes trait preceedence into account, i.e. t1 takes preceedence over t2 is any operations. It always returns either ab EmptyTrait or a TraitList.

This means that for

  • one argument it just returns the trait itself if it is list-like, or wraps the trait in a single-element list otherwise,
  • two arguments that are list-like, it merges them,
  • two arguments of which only the first one is list-like and the second one is not, it appends the second argument to the list,
  • two arguments of which only the second one is list-like, it prepends the first one to the list,
  • two arguments of which none is list-like, it creates a two-element list.
  • more than two arguments it recursively performs a left-assiciative recursive reduction on arguments, that is for example merge_traits(t1, t2, t3) is equivalent to merge_traits(merge_traits(t1, t2), t3)
source
ManifoldsBase.next_trait — Method
next_trait(t::AbstractTrait)

Return the next trait to consider, which by default is no following trait (i.e. EmptyTrait).

Expecially for a a TraitList this function returns the (remaining) tail of the remaining traits.

source
ManifoldsBase.parent_trait — Method
parent_trait(t::AbstractTrait)

Return the parent trait for trait t, that is the more general trait whose behaviour it inherits as a fallback.

source

The key part of the trait system is that it forms a list of traits, from the most specific one to the least specific one, and tries to find a specific implementation of a function for a trait in the least. This ensures that there are, by design, no ambiguities (caused by traits) in the method selection process. Trait resolution is driven by Julia's method dispatch and the compiler is sufficiently clever to quite reliably constant-propagate traits and inline method calls.

The list of traits is browsed from the most specific one for implementation of a given function for that trait. If one is found, the implementation is called and it may internally call completely different function, breaking the trait dispatch chain. When no implementation for a trait is found, the next trait on the list is checked, until EmptyTrait is reached, which is conventionally the last trait to be considered, expected to have the most generic default implementation of a function If you want to continue with the following traits afterwards, use s =next_trait(t) of a TraitList t to continue working on the next trait in the list by calling the function with s as first argument.

The Manifold decorator

Based on the generic TraitList the following types, functions, and macros introduce the decorator trait which allows to decorate an arbitrary <:AbstractDecoratorManifold with further features.

ManifoldsBase.decorated_manifold — Method
decorated_manifold(M::AbstractDecoratorManifold)

For a manifold M that is decorated with some properties, this function returns the manifold without that manifold, i.e. the manifold that was decorated.

source
ManifoldsBase.get_embedding — Method
get_embedding(M::AbstractDecoratorManifold)
-get_embedding(M::AbstractDecoratorManifold, p)

Specify the embedding of a manifold that has abstract decorators. the embedding might depend on a point representation, where different point representations are distinguished as subtypes of AbstractManifoldPoint. A unique or default representation might also just be an AbstractArray.

source

For an example see the (implicit) embedded manifold.

+Decorating/Extending a Manifold · ManifoldsBase.jl
GitHub

A Decorator for manifolds

Several properties of a manifold are often implicitly assumed, for example the choice of the (Riemannian) metric, the group structure or the embedding. The latter shall serve as an example how to either implicitly or explicitly specify the embedding to avoid re-implementations and/or distinguish different embeddings.

The abstract decorator

When first implementing a manifold, it might be beneficial to dispatch certain computations to already existing manifolds. For an embedded manifold that is isometrically embedded this might be the inner the manifold inherits in each tangent space from its embedding.

This means we would like to dispatch the default implementation of a function to some other manifold. We refer to this as implicit decoration, since one can not “see” explicitly that a certain manifold inherits this property. As an example consider the Sphere. At each point the tangent space can be identified with a subspace of the tangent space in the embedding, the Euclidean manifold which the unit vectors of the sphere belong to. Thus every tangent space inherits its metric from the embedding. Since in the default implementation in Manifolds.jl points are represented by unit vectors and tangent vectors at a point as vectors orthogonal to that point, we can just dispatch the inner product to the embedding without having to re-implement this. The manifold using such an implicit dispatch just has to be a subtype of AbstractDecoratorManifold.

Traits with an inheritance hierarchy

The properties mentioned above might form a hierarchy. For embedded manifolds, again, we might have just a manifold whose points are represented in some embedding. If the manifold is even isometrically embedded, it is embedded but also inherits the Riemannian metric by restricting the metric from the embedding to the corresponding tangent space under consideration. But it also inherits the functions defined for the plain embedding, for example checking some conditions for the validity of points and vectors. If it is even a submanifold, also further functions are inherited like the shortest_geodesic.

We use a variation of Tim Holy's Traits Trick (THTT) which takes into account this nestedness of traits.

ManifoldsBase.AbstractDecoratorManifold — Type
AbstractDecoratorManifold{𝔽} <: AbstractManifold{𝔽}

Declare a manifold to be an abstract decorator. A manifold which is a subtype of is a decorated manifold, i.e. has

  • certain additional properties or
  • delegates certain properties to other manifolds.

Most prominently, a manifold might be an embedded manifold, i.e. points on a manifold $\mathcal M$ are represented by (some, maybe not all) points on another manifold $\mathcal N$. Depending on the type of embedding, several functions are dedicated to the embedding. For example if the embedding is isometric, then the inner does not have to be implemented for $\mathcal M$ but can be automatically implemented by deligation to $\mathcal N$.

This is modelled by the AbstractDecoratorManifold and traits. These are mapped to functions, which determine the types of transparencies.

source
ManifoldsBase.IsExplicitDecorator — Type
IsExplicitDecorator <: AbstractTrait

Specify that a certain type should dispatch per default to its decorated_manifold.

Note

Any decorator behind this decorator might not have any effect, since the function dispatch is moved to its field at this point. Therefore this decorator should always be last in the TraitList.

source
ManifoldsBase.TraitList — Type
TraitList <: AbstractTrait

Combine two traits into a combined trait. Note that this introduces a preceedence. the first of the traits takes preceedence if a trait is implemented for both functions.

Constructor

TraitList(head::AbstractTrait, tail::AbstractTrait)
source
ManifoldsBase.@next_trait_function — Macro
next_trait_function(trait_type, sig)

Define a special trait-handling method for function indicated by sig. It does not change the result but the presence of such additional methods may prevent method recursion limits in Julia's inference from being triggered. Some functions may work faster after adding methods generated by next_trait_function.

See the "Trait recursion breaking" section at the bottom of src/decorator_trait.jl file for an example of intended usage.

source
ManifoldsBase.active_traits — Method
active_traits(f, args...)

Return the list of traits applicable to the given call of function f`. This function should be overloaded for specific function calls.

source
ManifoldsBase.merge_traits — Method
merge_traits(t1, t2, trest...)

Merge two traits into a nested list of traits. Note that this takes trait preceedence into account, i.e. t1 takes preceedence over t2 is any operations. It always returns either ab EmptyTrait or a TraitList.

This means that for

  • one argument it just returns the trait itself if it is list-like, or wraps the trait in a single-element list otherwise,
  • two arguments that are list-like, it merges them,
  • two arguments of which only the first one is list-like and the second one is not, it appends the second argument to the list,
  • two arguments of which only the second one is list-like, it prepends the first one to the list,
  • two arguments of which none is list-like, it creates a two-element list.
  • more than two arguments it recursively performs a left-assiciative recursive reduction on arguments, that is for example merge_traits(t1, t2, t3) is equivalent to merge_traits(merge_traits(t1, t2), t3)
source
ManifoldsBase.next_trait — Method
next_trait(t::AbstractTrait)

Return the next trait to consider, which by default is no following trait (i.e. EmptyTrait).

Expecially for a a TraitList this function returns the (remaining) tail of the remaining traits.

source
ManifoldsBase.parent_trait — Method
parent_trait(t::AbstractTrait)

Return the parent trait for trait t, that is the more general trait whose behaviour it inherits as a fallback.

source

The key part of the trait system is that it forms a list of traits, from the most specific one to the least specific one, and tries to find a specific implementation of a function for a trait in the least. This ensures that there are, by design, no ambiguities (caused by traits) in the method selection process. Trait resolution is driven by Julia's method dispatch and the compiler is sufficiently clever to quite reliably constant-propagate traits and inline method calls.

The list of traits is browsed from the most specific one for implementation of a given function for that trait. If one is found, the implementation is called and it may internally call completely different function, breaking the trait dispatch chain. When no implementation for a trait is found, the next trait on the list is checked, until EmptyTrait is reached, which is conventionally the last trait to be considered, expected to have the most generic default implementation of a function If you want to continue with the following traits afterwards, use s =next_trait(t) of a TraitList t to continue working on the next trait in the list by calling the function with s as first argument.

The Manifold decorator

Based on the generic TraitList the following types, functions, and macros introduce the decorator trait which allows to decorate an arbitrary <:AbstractDecoratorManifold with further features.

ManifoldsBase.decorated_manifold — Method
decorated_manifold(M::AbstractDecoratorManifold)

For a manifold M that is decorated with some properties, this function returns the manifold without that manifold, i.e. the manifold that was decorated.

source
ManifoldsBase.get_embedding — Method
get_embedding(M::AbstractDecoratorManifold)
+get_embedding(M::AbstractDecoratorManifold, p)

Specify the embedding of a manifold that has abstract decorators. the embedding might depend on a point representation, where different point representations are distinguished as subtypes of AbstractManifoldPoint. A unique or default representation might also just be an AbstractArray.

source

For an example see the (implicit) embedded manifold.

diff --git a/previews/PR217/design/index.html b/previews/PR217/design/index.html index 23327151..2ee210a7 100644 --- a/previews/PR217/design/index.html +++ b/previews/PR217/design/index.html @@ -18,4 +18,4 @@ julia> y[1] 1-element Array{Float64,1}: - 6.90031725726027e-310

The function allocate_result allocates a correct return value. It takes into account the possibility that different arguments may have different numeric number_eltype types thorough the allocate_result_type function. The most prominent example of the usage of this function is the logarithmic function log when used with typed points. Lets assume on a manifold M the have points of type P and corresponding tangent vector types V. then the logarithmic map has the signature

log(::M, ::P, ::P)

but the return type would be $V$, whose internal sizes (fields/arrays) will depend on the concrete type of one of the points. This is accomplished by implementing a method allocate_result(::M, ::typeof(log), ::P, ::P) that returns the concrete variable for the result. This way, even with specific types, one just has to implement log! and the one line for the allocation.

Note

This dispatch from the allocating to the in-place variant happens in Layer I (which changed in ManifoldsBase.jl 0.15), that is, functions like exp or retract allocate their result and call the in-place variant exp! and retract! afterwards, where the ladder passes down to layer III to reach retract_polar!.

+ 6.90031725726027e-310

The function allocate_result allocates a correct return value. It takes into account the possibility that different arguments may have different numeric number_eltype types thorough the allocate_result_type function. The most prominent example of the usage of this function is the logarithmic function log when used with typed points. Lets assume on a manifold M the have points of type P and corresponding tangent vector types V. then the logarithmic map has the signature

log(::M, ::P, ::P)

but the return type would be $V$, whose internal sizes (fields/arrays) will depend on the concrete type of one of the points. This is accomplished by implementing a method allocate_result(::M, ::typeof(log), ::P, ::P) that returns the concrete variable for the result. This way, even with specific types, one just has to implement log! and the one line for the allocation.

Note

This dispatch from the allocating to the in-place variant happens in Layer I (which changed in ManifoldsBase.jl 0.15), that is, functions like exp or retract allocate their result and call the in-place variant exp! and retract! afterwards, where the ladder passes down to layer III to reach retract_polar!.

diff --git a/previews/PR217/functions/index.html b/previews/PR217/functions/index.html index 7dd4e59c..2ca42892 100644 --- a/previews/PR217/functions/index.html +++ b/previews/PR217/functions/index.html @@ -1,10 +1,10 @@ Basic functions · ManifoldsBase.jl
GitHub

Functions on manifolds

This page collects several basic functions on manifolds.

The exponential map, the logarithmic map, and geodesics

Geodesics are the generalizations of a straight line to manifolds, i.e. their intrinsic acceleration is zero. Together with geodesics one also obtains the exponential map and its inverse, the logarithmic map. Informally speaking, the exponential map takes a vector (think of a direction and a length) at one point and returns another point, which lies towards this direction at distance of the specified length. The logarithmic map does the inverse, i.e. given two points, it tells which vector “points towards” the other point.

Base.exp — Method
exp(M::AbstractManifold, p, X)
-exp(M::AbstractManifold, p, X, t::Number = 1)

Compute the exponential map of tangent vector X, optionally scaled by t, at point p from the manifold AbstractManifold M, i.e.

\[\exp_p X = γ_{p,X}(1),\]

where $γ_{p,X}$ is the unique geodesic starting in $γ(0)=p$ such that $\dot γ(0) = X$.

See also shortest_geodesic, retract.

source
Base.log — Method
log(M::AbstractManifold, p, q)

Compute the logarithmic map of point q at base point p on the AbstractManifold M. The logarithmic map is the inverse of the exponential map. Note that the logarithmic map might not be globally defined.

See also inverse_retract.

source
ManifoldsBase.exp! — Method
exp!(M::AbstractManifold, q, p, X)
-exp!(M::AbstractManifold, q, p, X, t::Number = 1)

Compute the exponential map of tangent vector X, optionally scaled by t, at point p from the manifold AbstractManifold M. The result is saved to q.

If you want to implement exponential map for your manifold, you should implement the method with t, that is exp!(M::MyManifold, q, p, X, t::Number).

See also exp.

source
ManifoldsBase.geodesic! — Method
geodesic!(M::AbstractManifold, Q, p, X, T::AbstractVector) -> AbstractVector

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This function evaluates the geodeic at time points t fom T in place of Q.

source
ManifoldsBase.geodesic! — Method
geodesic!(M::AbstractManifold, q, p, X, t::Real)

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This function evaluates the geodeic at t in place of q.

source
ManifoldsBase.geodesic! — Method
geodesic!(M::AbstractManifold, p, X) -> Function

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This yields that the curve has constant velocity and is locally distance-minimizing.

This function returns a function (q,t) of (time) t that mutates q`.

source
ManifoldsBase.geodesic — Method
geodesic(M::AbstractManifold, p, X, T::AbstractVector) -> AbstractVector

Evaluate the geodesic $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

at time points t from T.

source
ManifoldsBase.geodesic — Method
geodesic(M::AbstractManifold, p, X, t::Real)

Evaluate the geodesic $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

at time t.

source
ManifoldsBase.geodesic — Method
geodesic(M::AbstractManifold, p, X) -> Function

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This yields, that the curve has constant velocity that is locally distance-minimizing.

This function returns a function of (time) t.

source
ManifoldsBase.log! — Method
log!(M::AbstractManifold, X, p, q)

Compute the logarithmic map of point q at base point p on the AbstractManifold M. The result is saved to X. The logarithmic map is the inverse of the exp!onential map. Note that the logarithmic map might not be globally defined.

see also log and inverse_retract!,

source
ManifoldsBase.shortest_geodesic! — Method
shortest_geodesic!(M::AbstractManifold, R, p, q, T::AbstractVector) -> AbstractVector

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at all t from T in place of R. When there are multiple shortest geodesics, a deterministic choice will be taken.

source
ManifoldsBase.shortest_geodesic! — Method
shortest_geodesic!(M::AabstractManifold, r, p, q, t::Real)

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at t in place of r. When there are multiple shortest geodesics, a deterministic choice will be taken.

source
ManifoldsBase.shortest_geodesic! — Method
shortest_geodesic!(M::AbstractManifold, p, q) -> Function

Get a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$. When there are multiple shortest geodesics, a deterministic choice will be returned.

This function returns a function (r,t) -> ... of time t which works in place of r.

Further variants

shortest_geodesic!(M::AabstractManifold, r, p, q, t::Real)
-shortest_geodesic!(M::AbstractManifold, R, p, q, T::AbstractVector) -> AbstractVector

mutate (and return) the point r and the vector of points R, respectively, returning the point at time t or points at times t in T along the shortest geodesic.

source
ManifoldsBase.shortest_geodesic — Method
shortest_geodesic(M::AbstractManifold, p, q, T::AbstractVector) -> AbstractVector

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at time points T. When there are multiple shortest geodesics, a deterministic choice will be returned.

source
ManifoldsBase.shortest_geodesic — Method
shortest_geodesic(M::AabstractManifold, p, q, t::Real)

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at time t. When there are multiple shortest geodesics, a deterministic choice will be returned.

source
ManifoldsBase.shortest_geodesic — Method
shortest_geodesic(M::AbstractManifold, p, q) -> Function

Get a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$. When there are multiple shortest geodesics, a deterministic choice will be returned.

This function returns a function of time, which may be a Real or an AbstractVector.

source

Parallel transport

While moving vectors from one base point to another is the identity in the Euclidean space – or in other words all tangent spaces (directions one can “walk” into) are the same. This is different on a manifold.

If we have two points $p,q ∈ \mathcal M$, we take a $c: [0,1] → \mathcal M$ connecting the two points, i.e. $c(0) = p$ and $c(1) = q$. this could be a (or the) geodesic. If we further consider a vector field $X: [0,1] → T\mathcal M$, i.e. where $X(t) ∈ T_{c(t)}\mathcal M$. Then the vector field is called parallel if its covariant derivative $\frac{\mathrm{D}}{\mathrm{d}t}X(t) = 0$ for all $t∈ |0,1]$.

If we now impose a value for $X=X(0) ∈ T_p\mathcal M$, we obtain an ODE with an initial condition. The resulting value $X(1) ∈ T_q\mathcal M$ is called the parallel transport of X along $c$ or in case of a geodesic the _parallel transport of X from p to q.

ManifoldsBase.parallel_transport_along — Method
Y = parallel_transport_along(M::AbstractManifold, p, X, c)

Compute the parallel transport of the vector X from the tangent space at p along the curve c.

To be precise let $c(t)$ be a curve $c(0)=p$ for vector_transport_along $\mathcal P^cY$

THen In the result $Y\in T_p\mathcal M$ is the vector $X$ 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)$.

source

Further functions on manifolds

General functions provided by the interface

Base.angle — Method
angle(M::AbstractManifold, p, X, Y)

Compute the angle between tangent vectors X and Y at point p from the AbstractManifold M with respect to the inner product from inner.

source
Base.copyto! — Method
copyto!(M::AbstractManifold, Y, p, X)

Copy the value(s) from X to Y, where both are tangent vectors from the tangent space at p on the AbstractManifold M. This function defaults to calling copyto!(Y, X), but it might be useful to overwrite the function at the level, where also information from p and M can be accessed.

source
Base.copyto! — Method
copyto!(M::AbstractManifold, q, p)

Copy the value(s) from p to q, where both are points on the AbstractManifold M. This function defaults to calling copyto!(q, p), but it might be useful to overwrite the function at the level, where also information from M can be accessed.

source
Base.isapprox — Method
isapprox(M::AbstractManifold, p, X, Y; error:Symbol=:none; kwargs...)

Check if vectors X and Y tangent at p from AbstractManifold M are approximately equal.

The optional positional argument can be used to get more information for the case that the result is false, if the concrete manifold provides such information. Currently the following are supported

  • :error - throws an error if isapprox evaluates to false, providing possibly a more detailed error. Note that this turns isapprox basically to an @assert.
  • :info – prints the information in an @info
  • :warn – prints the information in an @warn
  • :none (default) – the function just returns true/false

By default these informations are collected by calling check_approx.

Keyword arguments can be used to specify tolerances.

source
Base.isapprox — Method
isapprox(M::AbstractManifold, p, q; error::Symbol=:none, kwargs...)

Check if points p and q from AbstractManifold M are approximately equal.

The keyword argument can be used to get more information for the case that the result is false, if the concrete manifold provides such information. Currently the following are supported

  • :error - throws an error if isapprox evaluates to false, providing possibly a more detailed error. Note that this turns isapprox basically to an @assert.
  • :info – prints the information in an @info
  • :warn – prints the information in an @warn
  • :none (default) – the function just returns true/false

Keyword arguments can be used to specify tolerances.

source
Base.rand — Method
Random.rand(M::AbstractManifold, [d::Integer]; vector_at=nothing)
-Random.rand(rng::AbstractRNG, M::AbstractManifold, [d::Integer]; vector_at=nothing)

Generate a random point on manifold M (when vector_at is nothing) or a tangent vector at point vector_at (when it is not nothing).

Optionally a random number generator rng to be used can be specified. An optional integer d indicates that a vector of d points or tangent vectors is to be generated.

Note

Usually a uniform distribution should be expected for compact manifolds and a Gaussian-like distribution for non-compact manifolds and tangent vectors, although it is not guaranteed. The distribution may change between releases.

rand methods for specific manifolds may take additional keyword arguments.

source
ManifoldsBase.Weingarten — Method
Weingarten(M, p, X, V)

Compute the Weingarten map $\mathcal W_p\colon T_p\mathcal M × N_p\mathcal M \to T_p\mathcal M$, where $N_p\mathcal M$ is the orthogonal complement of the tangent space $T_p\mathcal M$ of the embedded submanifold $\mathcal M$, where we denote the embedding by $\mathcal E$.

The Weingarten map can be defined by restricting the differential of the orthogonal projection $\operatorname{proj}_{T_p\mathcal M}\colon T_p \mathcal E \to T_p\mathcal M$ with respect to the base point $p$, i.e. defining

\[\mathcal P_X := D_p\operatorname{proj}_{T_p\mathcal M}(Y)[X], -\qquad Y \in T_p \mathcal E, X \in T_p\mathcal M,\]

the Weingarten map can be written as $\mathcal W_p(X,V) = \mathcal P_X(V)$.

The Weingarten map is named after Julius Weingarten (1836–1910).

source
ManifoldsBase.allocate — Method
allocate(a)
+exp(M::AbstractManifold, p, X, t::Number = 1)

Compute the exponential map of tangent vector X, optionally scaled by t, at point p from the manifold AbstractManifold M, i.e.

\[\exp_p X = γ_{p,X}(1),\]

where $γ_{p,X}$ is the unique geodesic starting in $γ(0)=p$ such that $\dot γ(0) = X$.

See also shortest_geodesic, retract.

source
Base.log — Method
log(M::AbstractManifold, p, q)

Compute the logarithmic map of point q at base point p on the AbstractManifold M. The logarithmic map is the inverse of the exponential map. Note that the logarithmic map might not be globally defined.

See also inverse_retract.

source
ManifoldsBase.exp! — Method
exp!(M::AbstractManifold, q, p, X)
+exp!(M::AbstractManifold, q, p, X, t::Number = 1)

Compute the exponential map of tangent vector X, optionally scaled by t, at point p from the manifold AbstractManifold M. The result is saved to q.

If you want to implement exponential map for your manifold, you should implement the method with t, that is exp!(M::MyManifold, q, p, X, t::Number).

See also exp.

source
ManifoldsBase.geodesic! — Method
geodesic!(M::AbstractManifold, Q, p, X, T::AbstractVector) -> AbstractVector

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This function evaluates the geodeic at time points t fom T in place of Q.

source
ManifoldsBase.geodesic! — Method
geodesic!(M::AbstractManifold, q, p, X, t::Real)

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This function evaluates the geodeic at t in place of q.

source
ManifoldsBase.geodesic! — Method
geodesic!(M::AbstractManifold, p, X) -> Function

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This yields that the curve has constant velocity and is locally distance-minimizing.

This function returns a function (q,t) of (time) t that mutates q`.

source
ManifoldsBase.geodesic — Method
geodesic(M::AbstractManifold, p, X, T::AbstractVector) -> AbstractVector

Evaluate the geodesic $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

at time points t from T.

source
ManifoldsBase.geodesic — Method
geodesic(M::AbstractManifold, p, X, t::Real)

Evaluate the geodesic $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

at time t.

source
ManifoldsBase.geodesic — Method
geodesic(M::AbstractManifold, p, X) -> Function

Get the geodesic with initial point p and velocity X on the AbstractManifold M. A geodesic is a curve of zero acceleration. That is for the curve $γ_{p,X}: I → \mathcal M$, with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ a geodesic further fulfills

\[∇_{\dot γ_{p,X}(t)} \dot γ_{p,X}(t) = 0,\]

i.e. the curve is acceleration free with respect to the Riemannian metric. This yields, that the curve has constant velocity that is locally distance-minimizing.

This function returns a function of (time) t.

source
ManifoldsBase.log! — Method
log!(M::AbstractManifold, X, p, q)

Compute the logarithmic map of point q at base point p on the AbstractManifold M. The result is saved to X. The logarithmic map is the inverse of the exp!onential map. Note that the logarithmic map might not be globally defined.

see also log and inverse_retract!,

source
ManifoldsBase.shortest_geodesic! — Method
shortest_geodesic!(M::AbstractManifold, R, p, q, T::AbstractVector) -> AbstractVector

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at all t from T in place of R. When there are multiple shortest geodesics, a deterministic choice will be taken.

source
ManifoldsBase.shortest_geodesic! — Method
shortest_geodesic!(M::AabstractManifold, r, p, q, t::Real)

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at t in place of r. When there are multiple shortest geodesics, a deterministic choice will be taken.

source
ManifoldsBase.shortest_geodesic! — Method
shortest_geodesic!(M::AbstractManifold, p, q) -> Function

Get a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$. When there are multiple shortest geodesics, a deterministic choice will be returned.

This function returns a function (r,t) -> ... of time t which works in place of r.

Further variants

shortest_geodesic!(M::AabstractManifold, r, p, q, t::Real)
+shortest_geodesic!(M::AbstractManifold, R, p, q, T::AbstractVector) -> AbstractVector

mutate (and return) the point r and the vector of points R, respectively, returning the point at time t or points at times t in T along the shortest geodesic.

source
ManifoldsBase.shortest_geodesic — Method
shortest_geodesic(M::AbstractManifold, p, q, T::AbstractVector) -> AbstractVector

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at time points T. When there are multiple shortest geodesics, a deterministic choice will be returned.

source
ManifoldsBase.shortest_geodesic — Method
shortest_geodesic(M::AabstractManifold, p, q, t::Real)

Evaluate a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$ at time t. When there are multiple shortest geodesics, a deterministic choice will be returned.

source
ManifoldsBase.shortest_geodesic — Method
shortest_geodesic(M::AbstractManifold, p, q) -> Function

Get a geodesic $γ_{p,q}(t)$ whose length is the shortest path between the points pand q, where $γ_{p,q}(0)=p$ and $γ_{p,q}(1)=q$. When there are multiple shortest geodesics, a deterministic choice will be returned.

This function returns a function of time, which may be a Real or an AbstractVector.

source

Parallel transport

While moving vectors from one base point to another is the identity in the Euclidean space – or in other words all tangent spaces (directions one can “walk” into) are the same. This is different on a manifold.

If we have two points $p,q ∈ \mathcal M$, we take a $c: [0,1] → \mathcal M$ connecting the two points, i.e. $c(0) = p$ and $c(1) = q$. this could be a (or the) geodesic. If we further consider a vector field $X: [0,1] → T\mathcal M$, i.e. where $X(t) ∈ T_{c(t)}\mathcal M$. Then the vector field is called parallel if its covariant derivative $\frac{\mathrm{D}}{\mathrm{d}t}X(t) = 0$ for all $t∈ |0,1]$.

If we now impose a value for $X=X(0) ∈ T_p\mathcal M$, we obtain an ODE with an initial condition. The resulting value $X(1) ∈ T_q\mathcal M$ is called the parallel transport of X along $c$ or in case of a geodesic the _parallel transport of X from p to q.

ManifoldsBase.parallel_transport_along — Method
Y = parallel_transport_along(M::AbstractManifold, p, X, c)

Compute the parallel transport of the vector X from the tangent space at p along the curve c.

To be precise let $c(t)$ be a curve $c(0)=p$ for vector_transport_along $\mathcal P^cY$

THen In the result $Y\in T_p\mathcal M$ is the vector $X$ 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)$.

source

Further functions on manifolds

General functions provided by the interface

Base.angle — Method
angle(M::AbstractManifold, p, X, Y)

Compute the angle between tangent vectors X and Y at point p from the AbstractManifold M with respect to the inner product from inner.

source
Base.copyto! — Method
copyto!(M::AbstractManifold, Y, p, X)

Copy the value(s) from X to Y, where both are tangent vectors from the tangent space at p on the AbstractManifold M. This function defaults to calling copyto!(Y, X), but it might be useful to overwrite the function at the level, where also information from p and M can be accessed.

source
Base.copyto! — Method
copyto!(M::AbstractManifold, q, p)

Copy the value(s) from p to q, where both are points on the AbstractManifold M. This function defaults to calling copyto!(q, p), but it might be useful to overwrite the function at the level, where also information from M can be accessed.

source
Base.isapprox — Method
isapprox(M::AbstractManifold, p, X, Y; error:Symbol=:none; kwargs...)

Check if vectors X and Y tangent at p from AbstractManifold M are approximately equal.

The optional positional argument can be used to get more information for the case that the result is false, if the concrete manifold provides such information. Currently the following are supported

  • :error - throws an error if isapprox evaluates to false, providing possibly a more detailed error. Note that this turns isapprox basically to an @assert.
  • :info – prints the information in an @info
  • :warn – prints the information in an @warn
  • :none (default) – the function just returns true/false

By default these informations are collected by calling check_approx.

Keyword arguments can be used to specify tolerances.

source
Base.isapprox — Method
isapprox(M::AbstractManifold, p, q; error::Symbol=:none, kwargs...)

Check if points p and q from AbstractManifold M are approximately equal.

The keyword argument can be used to get more information for the case that the result is false, if the concrete manifold provides such information. Currently the following are supported

  • :error - throws an error if isapprox evaluates to false, providing possibly a more detailed error. Note that this turns isapprox basically to an @assert.
  • :info – prints the information in an @info
  • :warn – prints the information in an @warn
  • :none (default) – the function just returns true/false

Keyword arguments can be used to specify tolerances.

source
Base.rand — Method
Random.rand(M::AbstractManifold, [d::Integer]; vector_at=nothing)
+Random.rand(rng::AbstractRNG, M::AbstractManifold, [d::Integer]; vector_at=nothing)

Generate a random point on manifold M (when vector_at is nothing) or a tangent vector at point vector_at (when it is not nothing).

Optionally a random number generator rng to be used can be specified. An optional integer d indicates that a vector of d points or tangent vectors is to be generated.

Note

Usually a uniform distribution should be expected for compact manifolds and a Gaussian-like distribution for non-compact manifolds and tangent vectors, although it is not guaranteed. The distribution may change between releases.

rand methods for specific manifolds may take additional keyword arguments.

source
ManifoldsBase.Weingarten — Method
Weingarten(M, p, X, V)

Compute the Weingarten map $\mathcal W_p\colon T_p\mathcal M × N_p\mathcal M \to T_p\mathcal M$, where $N_p\mathcal M$ is the orthogonal complement of the tangent space $T_p\mathcal M$ of the embedded submanifold $\mathcal M$, where we denote the embedding by $\mathcal E$.

The Weingarten map can be defined by restricting the differential of the orthogonal projection $\operatorname{proj}_{T_p\mathcal M}\colon T_p \mathcal E \to T_p\mathcal M$ with respect to the base point $p$, i.e. defining

\[\mathcal P_X := D_p\operatorname{proj}_{T_p\mathcal M}(Y)[X], +\qquad Y \in T_p \mathcal E, X \in T_p\mathcal M,\]

the Weingarten map can be written as $\mathcal W_p(X,V) = \mathcal P_X(V)$.

The Weingarten map is named after Julius Weingarten (1836–1910).

source
ManifoldsBase.allocate — Method
allocate(a)
 allocate(a, dims::Integer...)
 allocate(a, dims::Tuple)
 allocate(a, T::Type)
@@ -15,7 +15,7 @@
 allocate(M::AbstractManifold, a, dims::Tuple)
 allocate(M::AbstractManifold, a, T::Type)
 allocate(M::AbstractManifold, a, T::Type, dims::Integer...)
-allocate(M::AbstractManifold, a, T::Type, dims::Tuple)

Allocate an object similar to a. It is similar to function similar, although instead of working only on the outermost layer of a nested structure, it maps recursively through outer layers and calls similar on the innermost array-like object only. Type T is the new number element type number_eltype, if it is not given the element type of a is retained. The dims argument can be given for non-nested allocation and is forwarded to the function similar.

It's behavior can be overridden by a specific manifold, for example power manifold with nested replacing representation can decide that allocate for Array{<:SArray} returns another Array{<:SArray} instead of Array{<:MArray}, as would be done by default.

source
ManifoldsBase.allocate_on — Method
allocate_on(M::AbstractManifold, [T:::Type])
+allocate(M::AbstractManifold, a, T::Type, dims::Tuple)

Allocate an object similar to a. It is similar to function similar, although instead of working only on the outermost layer of a nested structure, it maps recursively through outer layers and calls similar on the innermost array-like object only. Type T is the new number element type number_eltype, if it is not given the element type of a is retained. The dims argument can be given for non-nested allocation and is forwarded to the function similar.

It's behavior can be overridden by a specific manifold, for example power manifold with nested replacing representation can decide that allocate for Array{<:SArray} returns another Array{<:SArray} instead of Array{<:MArray}, as would be done by default.

source
ManifoldsBase.allocate_on — Method
allocate_on(M::AbstractManifold, [T:::Type])
 allocate_on(M::AbstractManifold, F::FiberType, [T:::Type])

Allocate a new point on manifold M with optional type given by T. Note that T is not number element type as in allocate but rather the type of the entire point to be returned.

If F is provided, then an element of the corresponding fiber is allocated, assuming it is independent of the base point.

To allocate a tangent vector, use ``

Example

julia> using ManifoldsBase
 
 julia> M = ManifoldsBase.DefaultManifold(4)
@@ -48,12 +48,12 @@
  0.0
  0.0
  0.0
-
source
ManifoldsBase.base_manifold — Function
base_manifold(M::AbstractManifold, depth = Val(-1))

Return the internally stored AbstractManifold for decorated manifold M and the base manifold for vector bundles or power manifolds. The optional parameter depth can be used to remove only the first depth many decorators and return the AbstractManifold from that level, whether its decorated or not. Any negative value deactivates this depth limit.

source
ManifoldsBase.default_type — Method
default_type(M::AbstractManifold, ft::FiberType)

Get the default type of points from the fiber ft of the fiber bundle based on manifold M. For example, call default_type(MyManifold(), TangentSpaceType()) to get the default type of a tangent vector.

source
ManifoldsBase.distance — Method
distance(M::AbstractManifold, p, q)

Shortest distance between the points p and q on the AbstractManifold M, i.e.

\[d(p,q) = \inf_{γ} L(γ),\]

where the infimum is over all piecewise smooth curves $γ: [a,b] \to \mathcal M$ connecting $γ(a)=p$ and $γ(b)=q$ and

\[L(γ) = \displaystyle\int_{a}^{b} \lVert \dotγ(t)\rVert_{γ(t)} \mathrm{d}t\]

is the length of the curve $γ$.

If $\mathcal M$ is not connected, i.e. consists of several disjoint components, the distance between two points from different components should be $∞$.

source
ManifoldsBase.embed! — Method
embed!(M::AbstractManifold, Y, p, X)

Embed a tangent vector X at a point p on the AbstractManifold M into the ambient space and return the result in Y. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, embed! includes changing data representation, if applicable, i.e. if the tangents on M are not represented in the same way as tangents on the embedding, the representation is changed accordingly. This is the case for example for Lie groups, when tangent vectors are represented in the Lie algebra. The embedded tangents are then in the tangent spaces of the embedded base points.

The default is set in such a way that it assumes that the points on M are represented in their embedding (for example like the unit vectors in a space to represent the sphere) and hence embedding also for tangent vectors is the identity by default.

See also: EmbeddedManifold, project!

source
ManifoldsBase.embed! — Method
embed!(M::AbstractManifold, q, p)

Embed point p from the AbstractManifold M into an ambient space. This method is only available for manifolds where implicitly an embedding or ambient space is given. Not implementing this function means, there is no proper embedding for your manifold. Additionally, embed might include changing data representation, if applicable, i.e. if points on M are not represented in the same way as their counterparts in the embedding, the representation is changed accordingly.

The default is set in such a way that it assumes that the points on M are represented in their embedding (for example like the unit vectors in a space to represent the sphere) and hence embedding in the identity by default.

If you have more than one embedding, see EmbeddedManifold for defining a second embedding. If your point p is already represented in some embedding, see AbstractDecoratorManifold how you can avoid reimplementing code from the embedded manifold

See also: EmbeddedManifold, project!

source
ManifoldsBase.embed — Method
embed(M::AbstractManifold, p, X)

Embed a tangent vector X at a point p on the AbstractManifold M into an ambient space. This method is only available for manifolds where implicitly an embedding or ambient space is given. Not implementing this function means, there is no proper embedding for your tangent space(s).

Additionally, embed might include changing data representation, if applicable, i.e. if tangent vectors on M are not represented in the same way as their counterparts in the embedding, the representation is changed accordingly.

The default is set in such a way that memory is allocated and embed!(M, Y, p. X) is called.

If you have more than one embedding, see EmbeddedManifold for defining a second embedding. If your tangent vector X is already represented in some embedding, see AbstractDecoratorManifold how you can avoid reimplementing code from the embedded manifold

See also: EmbeddedManifold, project

source
ManifoldsBase.embed — Method
embed(M::AbstractManifold, p)

Embed point p from the AbstractManifold M into the ambient space. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, embed includes changing data representation, if applicable, i.e. if the points on M are not represented in the same way as points on the embedding, the representation is changed accordingly.

The default is set in such a way that memory is allocated and embed!(M, q, p) is called.

See also: EmbeddedManifold, project

source
ManifoldsBase.embed_project — Method
embed_project(M::AbstractManifold, p, X)

Embed vector X tangent at p from manifold M an project it back to tangent space at p. For points from that tangent space this is identity but in case embedding is defined for tangent vectors from outside of it, this can serve as a way to for example remove numerical inaccuracies caused by some algorithms.

source
ManifoldsBase.embed_project — Method
embed_project(M::AbstractManifold, p)

Embed p from manifold M an project it back to M. For points from M this is identity but in case embedding is defined for points outside of M, this can serve as a way to for example remove numerical inaccuracies caused by some algorithms.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(M::AbstractManifold)

Infimum of the injectivity radii injectivity_radius(M,p) of all points p on the AbstractManifold.

injectivity_radius(M::AbstractManifold, p)

Return the distance $d$ such that exp(M, p, X) is injective for all tangent vectors shorter than $d$ (i.e. has an inverse).

injectivity_radius(M::AbstractManifold[, x], method::AbstractRetractionMethod)
-injectivity_radius(M::AbstractManifold, x, method::AbstractRetractionMethod)

Distance $d$ such that retract(M, p, X, method) is injective for all tangent vectors shorter than $d$ (i.e. has an inverse) for point p if provided or all manifold points otherwise.

In order to dispatch on different retraction methods, please either implement _injectivity_radius(M[, p], m::T) for your retraction R or specifically injectivity_radius_exp(M[, p]) for the exponential map. By default the variant with a point p assumes that the default (without p) can ve called as a lower bound.

source
ManifoldsBase.is_point — Method
is_point(M::AbstractManifold, p; error::Symbol = :none, kwargs...)
-is_point(M::AbstractManifold, p, throw_error::Bool; kwargs...)

Return whether p is a valid point on the AbstractManifold M. By default the function calls check_point, which returns an ErrorException or nothing.

How to report a potential error can be set using the error= keyword

  • :error - throws an error if p is not a point
  • :info - displays the error message as an @info
  • :warn - displays the error message as a @warning
  • :none (default) – the function just returns true/false

all other symbols are equivalent to error=:none.

The second signature is a shorthand, where the boolean is used for error=:error (true) and error=:none (default, false). This case ignores the error= keyword

source
ManifoldsBase.is_vector — Method
is_vector(M::AbstractManifold, p, X, check_base_point::Bool=true; error::Symbol=:none, kwargs...)
-is_vector(M::AbstractManifold, p, X, check_base_point::Bool=true, throw_error::Boolean; kwargs...)

Return whether X is a valid tangent vector at point p on the AbstractManifold M. Returns either true or false.

If check_base_point is set to true, this function also (first) calls is_point on p. Then, the function calls check_vector and checks whether the returned value is nothing or an error.

How to report a potential error can be set using the error= keyword

  • :error - throws an error if X is not a tangent vector and/or p is not point

^ :info - displays the error message as an @info

  • :warn - displays the error message as a @warning.
  • :none - (default) the function just returns true/false

all other symbols are equivalent to error=:none

The second signature is a shorthand, where throw_error is used for error=:error (true) and error=:none (default, false). This case ignores the error= keyword.

source
ManifoldsBase.mid_point! — Method
mid_point!(M::AbstractManifold, q, p1, p2)

Calculate the middle between the two point p1 and p2 from manifold M. By default uses log, divides the vector by 2 and uses exp!. Saves the result in q.

source
ManifoldsBase.mid_point — Method
mid_point(M::AbstractManifold, p1, p2)

Calculate the middle between the two point p1 and p2 from manifold M. By default uses log, divides the vector by 2 and uses exp.

source
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::AbstractManifold, p, X, Y, Z)

Compute the value of the Riemann tensor $R(X_f,Y_f)Z_f$ at point p, where $X_f$, $Y_f$ and $Z_f$ are vector fields defined by parallel transport of, respectively, X, Y and Z to the desired point. All computations are performed using the connection associated to manifold M.

The formula reads $R(X_f,Y_f)Z_f = \nabla_X\nabla_Y Z - \nabla_Y\nabla_X Z - \nabla_{[X, Y]}Z$, where $[X, Y]$ is the Lie bracket of vector fields.

Note that some authors define this quantity with inverse sign.

source
ManifoldsBase.sectional_curvature — Method
sectional_curvature(M::AbstractManifold, p, X, Y)

Compute the sectional curvature of a manifold $\mathcal M$ at a point $p \in \mathcal M$ on two linearly independent tangent vectors at $p$. The formula reads

\[ +

source
ManifoldsBase.base_manifold — Function
base_manifold(M::AbstractManifold, depth = Val(-1))

Return the internally stored AbstractManifold for decorated manifold M and the base manifold for vector bundles or power manifolds. The optional parameter depth can be used to remove only the first depth many decorators and return the AbstractManifold from that level, whether its decorated or not. Any negative value deactivates this depth limit.

source
ManifoldsBase.default_type — Method
default_type(M::AbstractManifold, ft::FiberType)

Get the default type of points from the fiber ft of the fiber bundle based on manifold M. For example, call default_type(MyManifold(), TangentSpaceType()) to get the default type of a tangent vector.

source
ManifoldsBase.distance — Method
distance(M::AbstractManifold, p, q)

Shortest distance between the points p and q on the AbstractManifold M, i.e.

\[d(p,q) = \inf_{γ} L(γ),\]

where the infimum is over all piecewise smooth curves $γ: [a,b] \to \mathcal M$ connecting $γ(a)=p$ and $γ(b)=q$ and

\[L(γ) = \displaystyle\int_{a}^{b} \lVert \dotγ(t)\rVert_{γ(t)} \mathrm{d}t\]

is the length of the curve $γ$.

If $\mathcal M$ is not connected, i.e. consists of several disjoint components, the distance between two points from different components should be $∞$.

source
ManifoldsBase.embed! — Method
embed!(M::AbstractManifold, Y, p, X)

Embed a tangent vector X at a point p on the AbstractManifold M into the ambient space and return the result in Y. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, embed! includes changing data representation, if applicable, i.e. if the tangents on M are not represented in the same way as tangents on the embedding, the representation is changed accordingly. This is the case for example for Lie groups, when tangent vectors are represented in the Lie algebra. The embedded tangents are then in the tangent spaces of the embedded base points.

The default is set in such a way that it assumes that the points on M are represented in their embedding (for example like the unit vectors in a space to represent the sphere) and hence embedding also for tangent vectors is the identity by default.

See also: EmbeddedManifold, project!

source
ManifoldsBase.embed! — Method
embed!(M::AbstractManifold, q, p)

Embed point p from the AbstractManifold M into an ambient space. This method is only available for manifolds where implicitly an embedding or ambient space is given. Not implementing this function means, there is no proper embedding for your manifold. Additionally, embed might include changing data representation, if applicable, i.e. if points on M are not represented in the same way as their counterparts in the embedding, the representation is changed accordingly.

The default is set in such a way that it assumes that the points on M are represented in their embedding (for example like the unit vectors in a space to represent the sphere) and hence embedding in the identity by default.

If you have more than one embedding, see EmbeddedManifold for defining a second embedding. If your point p is already represented in some embedding, see AbstractDecoratorManifold how you can avoid reimplementing code from the embedded manifold

See also: EmbeddedManifold, project!

source
ManifoldsBase.embed — Method
embed(M::AbstractManifold, p, X)

Embed a tangent vector X at a point p on the AbstractManifold M into an ambient space. This method is only available for manifolds where implicitly an embedding or ambient space is given. Not implementing this function means, there is no proper embedding for your tangent space(s).

Additionally, embed might include changing data representation, if applicable, i.e. if tangent vectors on M are not represented in the same way as their counterparts in the embedding, the representation is changed accordingly.

The default is set in such a way that memory is allocated and embed!(M, Y, p. X) is called.

If you have more than one embedding, see EmbeddedManifold for defining a second embedding. If your tangent vector X is already represented in some embedding, see AbstractDecoratorManifold how you can avoid reimplementing code from the embedded manifold

See also: EmbeddedManifold, project

source
ManifoldsBase.embed — Method
embed(M::AbstractManifold, p)

Embed point p from the AbstractManifold M into the ambient space. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, embed includes changing data representation, if applicable, i.e. if the points on M are not represented in the same way as points on the embedding, the representation is changed accordingly.

The default is set in such a way that memory is allocated and embed!(M, q, p) is called.

See also: EmbeddedManifold, project

source
ManifoldsBase.embed_project — Method
embed_project(M::AbstractManifold, p, X)

Embed vector X tangent at p from manifold M an project it back to tangent space at p. For points from that tangent space this is identity but in case embedding is defined for tangent vectors from outside of it, this can serve as a way to for example remove numerical inaccuracies caused by some algorithms.

source
ManifoldsBase.embed_project — Method
embed_project(M::AbstractManifold, p)

Embed p from manifold M an project it back to M. For points from M this is identity but in case embedding is defined for points outside of M, this can serve as a way to for example remove numerical inaccuracies caused by some algorithms.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(M::AbstractManifold)

Infimum of the injectivity radii injectivity_radius(M,p) of all points p on the AbstractManifold.

injectivity_radius(M::AbstractManifold, p)

Return the distance $d$ such that exp(M, p, X) is injective for all tangent vectors shorter than $d$ (i.e. has an inverse).

injectivity_radius(M::AbstractManifold[, x], method::AbstractRetractionMethod)
+injectivity_radius(M::AbstractManifold, x, method::AbstractRetractionMethod)

Distance $d$ such that retract(M, p, X, method) is injective for all tangent vectors shorter than $d$ (i.e. has an inverse) for point p if provided or all manifold points otherwise.

In order to dispatch on different retraction methods, please either implement _injectivity_radius(M[, p], m::T) for your retraction R or specifically injectivity_radius_exp(M[, p]) for the exponential map. By default the variant with a point p assumes that the default (without p) can ve called as a lower bound.

source
ManifoldsBase.is_point — Method
is_point(M::AbstractManifold, p; error::Symbol = :none, kwargs...)
+is_point(M::AbstractManifold, p, throw_error::Bool; kwargs...)

Return whether p is a valid point on the AbstractManifold M. By default the function calls check_point, which returns an ErrorException or nothing.

How to report a potential error can be set using the error= keyword

  • :error - throws an error if p is not a point
  • :info - displays the error message as an @info
  • :warn - displays the error message as a @warning
  • :none (default) – the function just returns true/false

all other symbols are equivalent to error=:none.

The second signature is a shorthand, where the boolean is used for error=:error (true) and error=:none (default, false). This case ignores the error= keyword

source
ManifoldsBase.is_vector — Method
is_vector(M::AbstractManifold, p, X, check_base_point::Bool=true; error::Symbol=:none, kwargs...)
+is_vector(M::AbstractManifold, p, X, check_base_point::Bool=true, throw_error::Boolean; kwargs...)

Return whether X is a valid tangent vector at point p on the AbstractManifold M. Returns either true or false.

If check_base_point is set to true, this function also (first) calls is_point on p. Then, the function calls check_vector and checks whether the returned value is nothing or an error.

How to report a potential error can be set using the error= keyword

  • :error - throws an error if X is not a tangent vector and/or p is not point

^ :info - displays the error message as an @info

  • :warn - displays the error message as a @warning.
  • :none - (default) the function just returns true/false

all other symbols are equivalent to error=:none

The second signature is a shorthand, where throw_error is used for error=:error (true) and error=:none (default, false). This case ignores the error= keyword.

source
ManifoldsBase.mid_point! — Method
mid_point!(M::AbstractManifold, q, p1, p2)

Calculate the middle between the two point p1 and p2 from manifold M. By default uses log, divides the vector by 2 and uses exp!. Saves the result in q.

source
ManifoldsBase.mid_point — Method
mid_point(M::AbstractManifold, p1, p2)

Calculate the middle between the two point p1 and p2 from manifold M. By default uses log, divides the vector by 2 and uses exp.

source
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::AbstractManifold, p, X, Y, Z)

Compute the value of the Riemann tensor $R(X_f,Y_f)Z_f$ at point p, where $X_f$, $Y_f$ and $Z_f$ are vector fields defined by parallel transport of, respectively, X, Y and Z to the desired point. All computations are performed using the connection associated to manifold M.

The formula reads $R(X_f,Y_f)Z_f = \nabla_X\nabla_Y Z - \nabla_Y\nabla_X Z - \nabla_{[X, Y]}Z$, where $[X, Y]$ is the Lie bracket of vector fields.

Note that some authors define this quantity with inverse sign.

source
ManifoldsBase.sectional_curvature — Method
sectional_curvature(M::AbstractManifold, p, X, Y)

Compute the sectional curvature of a manifold $\mathcal M$ at a point $p \in \mathcal M$ on two linearly independent tangent vectors at $p$. The formula reads

\[ \kappa_p(X, Y) = \frac{⟨R(X, Y, Y), X⟩_p}{\lVert X \rVert^2_p \lVert Y \rVert^2_p - ⟨X, Y⟩^2_p} -\]

where $R(X, Y, Y)$ is the riemann_tensor on $\mathcal M$.

Input

  • M: a manifold $\mathcal M$
  • p: a point $p \in \mathcal M$
  • X: a tangent vector $X \in T_p \mathcal M$
  • Y: a tangent vector $Y \in T_p \mathcal M$
source
ManifoldsBase.sectional_curvature_max — Method
sectional_curvature_max(M::AbstractManifold)

Upper bound on sectional curvature of manifold M. The formula reads

\[\omega = \operatorname{sup}_{p\in\mathcal M, X\in T_p\mathcal M, Y\in T_p\mathcal M, ⟨X, Y⟩ ≠ 0} \kappa_p(X, Y)\]

source
ManifoldsBase.sectional_curvature_min — Method
sectional_curvature_min(M::AbstractManifold)

Lower bound on sectional curvature of manifold M. The formula reads

\[\omega = \operatorname{inf}_{p\in\mathcal M, X\in T_p\mathcal M, Y\in T_p\mathcal M, ⟨X, Y⟩ ≠ 0} \kappa_p(X, Y)\]

source
ManifoldsBase.zero_vector! — Method
zero_vector!(M::AbstractManifold, X, p)

Save to X the tangent vector from the tangent space $T_p\mathcal M$ at p that represents the zero vector, i.e. such that retracting X to the AbstractManifold M at p produces p.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::AbstractManifold, p)

Return the tangent vector from the tangent space $T_p\mathcal M$ at p on the AbstractManifold M, that represents the zero vector, i.e. such that a retraction at p produces p.

source

Internal functions

While you should always add your documentation to functions from the last section, some of the functions dispatch onto functions on layer III. These are the ones you usually implement for your manifold – unless there is no lower level function called, like for the manifold_dimension.

Base.convert — Method
convert(T::Type, M::AbstractManifold, p, X)

Convert vector X tangent at point p from manifold M to type T.

source
Base.convert — Method
convert(T::Type, M::AbstractManifold, p)

Convert point p from manifold M to type T.

source
ManifoldsBase._isapprox — Method
_isapprox(M::AbstractManifold, p, X, Y; kwargs...)

An internal function for testing whether tangent vectors X and Y from tangent space at point p from manifold M are approximately equal. Returns either true or false and does not support errors like isapprox.

For more details see documentation of check_approx.

source
ManifoldsBase._isapprox — Method
_isapprox(M::AbstractManifold, p, q; kwargs...)

An internal function for testing whether points p and q from manifold M are approximately equal. Returns either true or false and does not support errors like isapprox.

For more details see documentation of check_approx.

source
ManifoldsBase._pick_basic_allocation_argument — Method
_pick_basic_allocation_argument(::AbstractManifold, f, x...)

Pick which one of elements of x should be used as a basis for allocation in the allocate_result(M::AbstractManifold, f, x...) method. This can be specialized to, for example, skip Identity arguments in Manifolds.jl group-related functions.

source
ManifoldsBase.allocate_result — Method
allocate_result(M::AbstractManifold, f, x...)

Allocate an array for the result of function f on AbstractManifold M and arguments x... for implementing the non-modifying operation using the modifying operation.

Usefulness of passing a function is demonstrated by methods that allocate results of musical isomorphisms.

source
ManifoldsBase.check_approx — Method
check_approx(M::AbstractManifold, p, q; kwargs...)
-check_approx(M::AbstractManifold, p, X, Y; kwargs...)

Check whether two elements are approximately equal, either p, q on the AbstractManifold or the two tangent vectors X, Y in the tangent space at p are approximately the same. The keyword arguments kwargs can be used to set tolerances, similar to Julia's isapprox.

This function might use isapprox from Julia internally and is similar to isapprox, with the difference that is returns an ApproximatelyError if the two elements are not approximately equal, containting a more detailed description/reason. If the two elements are approximalely equal, this method returns nothing.

This method is an internal function and is called by isapprox whenever the user specifies an error= keyword therein. _isapprox is another related internal function. It is supposed to provide a fast true/false decision whether points or vectors are equal or not, while check_approx also provides a textual explanation. If no additional explanation is needed, a manifold may just implement a method of _isapprox, while it should also implement check_approx if a more detailed explanation could be helpful.

source
ManifoldsBase.check_point — Method
check_point(M::AbstractManifold, p; kwargs...) -> Union{Nothing,String}

Return nothing when p is a point on the AbstractManifold M. Otherwise, return an error with description why the point does not belong to manifold M.

By default, check_point returns nothing, i.e. if no checks are implemented, the assumption is to be optimistic for a point not deriving from the AbstractManifoldPoint type.

source
ManifoldsBase.check_size — Method
check_size(M::AbstractManifold, p)
-check_size(M::AbstractManifold, p, X)

Check whether p has the right representation_size for a AbstractManifold M. Additionally if a tangent vector is given, both p and X are checked to be of corresponding correct representation sizes for points and tangent vectors on M.

By default, check_size returns nothing, i.e. if no checks are implemented, the assumption is to be optimistic.

source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractManifold, p, X; kwargs...) -> Union{Nothing,String}

Check whether X is a valid tangent vector in the tangent space of p on the AbstractManifold M. An implementation does not have to validate the point p. If it is not a tangent vector, an error string should be returned.

By default, check_vector returns nothing, i.e. if no checks are implemented, the assumption is to be optimistic for tangent vectors not deriving from the TVector type.

source

Approximation Methods

ManifoldsBase.ExtrinsicEstimation — Type
ExtrinsicEstimation{T} <: AbstractApproximationMethod

Method for estimation in the ambient space with a method of type T and projecting the result back to the manifold.

source
ManifoldsBase.GeodesicInterpolationWithinRadius — Type
GeodesicInterpolationWithinRadius{T} <: AbstractApproximationMethod

Method for estimation based on geodesic interpolation that is restricted to some radius

Constructor

GeodesicInterpolationWithinRadius(radius::Real)
source
ManifoldsBase.default_approximation_method — Method
default_approximation_method(M::AbstractManifold, f)
-default_approximation_method(M::AbtractManifold, f, T)

Specify a default estimation method for an AbstractManifold and a specific function f and optionally as well a type T to distinguish different (point or vector) representations on M.

By default, all functions f call the signature for just a manifold. The exceptional functions are:

source

Error Messages

This interface introduces a small set of own error messages.

ManifoldsBase.ApproximatelyError — Type
ApproximatelyError{V,S} <: Exception

Store an error that occurs when two data structures, e.g. points or tangent vectors.

Fields

  • val amount the two approximate elements are apart – is set to NaN if this is not known
  • msg a message providing more detail about the performed test and why it failed.

Constructors

ApproximatelyError(val::V, msg::S) where {V,S}

Generate an Error with value val and message msg.

ApproximatelyError(msg::S) where {S}

Generate a message without a value (using val=NaN internally) and message msg.

source
ManifoldsBase.ComponentManifoldError — Type
CompnentError{I,E} <: Exception

Store an error that occured in a component, where the additional index is stored.

Fields

  • index::I index where the error occured`
  • error::E error that occured.
source
ManifoldsBase.ManifoldDomainError — Type
ManifoldDomainError{<:Exception} <: Exception

An error to represent a nested (Domain) error on a manifold, for example if a point or tangent vector is invalid because its representation in some embedding is already invalid.

source
+\]

where $R(X, Y, Y)$ is the riemann_tensor on $\mathcal M$.

Input

source
ManifoldsBase.sectional_curvature_max — Method
sectional_curvature_max(M::AbstractManifold)

Upper bound on sectional curvature of manifold M. The formula reads

\[\omega = \operatorname{sup}_{p\in\mathcal M, X\in T_p\mathcal M, Y\in T_p\mathcal M, ⟨X, Y⟩ ≠ 0} \kappa_p(X, Y)\]

source
ManifoldsBase.sectional_curvature_min — Method
sectional_curvature_min(M::AbstractManifold)

Lower bound on sectional curvature of manifold M. The formula reads

\[\omega = \operatorname{inf}_{p\in\mathcal M, X\in T_p\mathcal M, Y\in T_p\mathcal M, ⟨X, Y⟩ ≠ 0} \kappa_p(X, Y)\]

source
ManifoldsBase.zero_vector! — Method
zero_vector!(M::AbstractManifold, X, p)

Save to X the tangent vector from the tangent space $T_p\mathcal M$ at p that represents the zero vector, i.e. such that retracting X to the AbstractManifold M at p produces p.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::AbstractManifold, p)

Return the tangent vector from the tangent space $T_p\mathcal M$ at p on the AbstractManifold M, that represents the zero vector, i.e. such that a retraction at p produces p.

source

Internal functions

While you should always add your documentation to functions from the last section, some of the functions dispatch onto functions on layer III. These are the ones you usually implement for your manifold – unless there is no lower level function called, like for the manifold_dimension.

Base.convert — Method
convert(T::Type, M::AbstractManifold, p, X)

Convert vector X tangent at point p from manifold M to type T.

source
Base.convert — Method
convert(T::Type, M::AbstractManifold, p)

Convert point p from manifold M to type T.

source
ManifoldsBase._isapprox — Method
_isapprox(M::AbstractManifold, p, X, Y; kwargs...)

An internal function for testing whether tangent vectors X and Y from tangent space at point p from manifold M are approximately equal. Returns either true or false and does not support errors like isapprox.

For more details see documentation of check_approx.

source
ManifoldsBase._isapprox — Method
_isapprox(M::AbstractManifold, p, q; kwargs...)

An internal function for testing whether points p and q from manifold M are approximately equal. Returns either true or false and does not support errors like isapprox.

For more details see documentation of check_approx.

source
ManifoldsBase._pick_basic_allocation_argument — Method
_pick_basic_allocation_argument(::AbstractManifold, f, x...)

Pick which one of elements of x should be used as a basis for allocation in the allocate_result(M::AbstractManifold, f, x...) method. This can be specialized to, for example, skip Identity arguments in Manifolds.jl group-related functions.

source
ManifoldsBase.allocate_result — Method
allocate_result(M::AbstractManifold, f, x...)

Allocate an array for the result of function f on AbstractManifold M and arguments x... for implementing the non-modifying operation using the modifying operation.

Usefulness of passing a function is demonstrated by methods that allocate results of musical isomorphisms.

source
ManifoldsBase.allocate_result_type — Method
allocate_result_type(M::AbstractManifold, f, args::NTuple{N,Any}) where N

Return type of element of the array that will represent the result of function f and the AbstractManifold M on given arguments args (passed as a tuple).

source
ManifoldsBase.are_linearly_independent — Method
are_linearly_independent(M::AbstractManifold, p, X, Y)

Check is vectors X, Y tangent at p to M are linearly independent.

source
ManifoldsBase.check_approx — Method
check_approx(M::AbstractManifold, p, q; kwargs...)
+check_approx(M::AbstractManifold, p, X, Y; kwargs...)

Check whether two elements are approximately equal, either p, q on the AbstractManifold or the two tangent vectors X, Y in the tangent space at p are approximately the same. The keyword arguments kwargs can be used to set tolerances, similar to Julia's isapprox.

This function might use isapprox from Julia internally and is similar to isapprox, with the difference that is returns an ApproximatelyError if the two elements are not approximately equal, containting a more detailed description/reason. If the two elements are approximalely equal, this method returns nothing.

This method is an internal function and is called by isapprox whenever the user specifies an error= keyword therein. _isapprox is another related internal function. It is supposed to provide a fast true/false decision whether points or vectors are equal or not, while check_approx also provides a textual explanation. If no additional explanation is needed, a manifold may just implement a method of _isapprox, while it should also implement check_approx if a more detailed explanation could be helpful.

source
ManifoldsBase.check_point — Method
check_point(M::AbstractManifold, p; kwargs...) -> Union{Nothing,String}

Return nothing when p is a point on the AbstractManifold M. Otherwise, return an error with description why the point does not belong to manifold M.

By default, check_point returns nothing, i.e. if no checks are implemented, the assumption is to be optimistic for a point not deriving from the AbstractManifoldPoint type.

source
ManifoldsBase.check_size — Method
check_size(M::AbstractManifold, p)
+check_size(M::AbstractManifold, p, X)

Check whether p has the right representation_size for a AbstractManifold M. Additionally if a tangent vector is given, both p and X are checked to be of corresponding correct representation sizes for points and tangent vectors on M.

By default, check_size returns nothing, i.e. if no checks are implemented, the assumption is to be optimistic.

source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractManifold, p, X; kwargs...) -> Union{Nothing,String}

Check whether X is a valid tangent vector in the tangent space of p on the AbstractManifold M. An implementation does not have to validate the point p. If it is not a tangent vector, an error string should be returned.

By default, check_vector returns nothing, i.e. if no checks are implemented, the assumption is to be optimistic for tangent vectors not deriving from the TVector type.

source
ManifoldsBase.size_to_tuple — Method
size_to_tuple(::Type{S}) where S<:Tuple

Converts a size given by Tuple{N, M, ...} into a tuple (N, M, ...).

source

Approximation Methods

ManifoldsBase.AbstractApproximationMethod — Type
AbstractApproximationMethod

Abstract type for defining estimation methods on manifolds.

source
ManifoldsBase.CyclicProximalPointEstimation — Type
CyclicProximalPointEstimation <: AbstractApproximationMethod

Method for estimation using the cyclic proximal point technique, which is based on proximal maps.

source
ManifoldsBase.EfficientEstimator — Type
EfficientEstimator <: AbstractApproximationMethod

Method for estimation in the best possible sense, see Efficiency (Statictsics) for more details. This can for example be used when computing the usual mean on an Euclidean space, which is the best estimator.

source
ManifoldsBase.ExtrinsicEstimation — Type
ExtrinsicEstimation{T} <: AbstractApproximationMethod

Method for estimation in the ambient space with a method of type T and projecting the result back to the manifold.

source
ManifoldsBase.GeodesicInterpolation — Type
GeodesicInterpolation <: AbstractApproximationMethod

Method for estimation based on geodesic interpolation.

source
ManifoldsBase.GeodesicInterpolationWithinRadius — Type
GeodesicInterpolationWithinRadius{T} <: AbstractApproximationMethod

Method for estimation based on geodesic interpolation that is restricted to some radius

Constructor

GeodesicInterpolationWithinRadius(radius::Real)
source
ManifoldsBase.GradientDescentEstimation — Type
GradientDescentEstimation <: AbstractApproximationMethod

Method for estimation using gradient descent.

source
ManifoldsBase.WeiszfeldEstimation — Type
WeiszfeldEstimation <: AbstractApproximationMethod

Method for estimation using the Weiszfeld algorithm, compare for example the computation of the Geometric median.

source
ManifoldsBase.default_approximation_method — Method
default_approximation_method(M::AbstractManifold, f)
+default_approximation_method(M::AbtractManifold, f, T)

Specify a default estimation method for an AbstractManifold and a specific function f and optionally as well a type T to distinguish different (point or vector) representations on M.

By default, all functions f call the signature for just a manifold. The exceptional functions are:

source

Error Messages

This interface introduces a small set of own error messages.

ManifoldsBase.AbstractManifoldDomainError — Type
AbstractManifoldDomainError <: Exception

An absytract Case for Errors when checking validity of points/vectors on mainfolds

source
ManifoldsBase.ApproximatelyError — Type
ApproximatelyError{V,S} <: Exception

Store an error that occurs when two data structures, e.g. points or tangent vectors.

Fields

  • val amount the two approximate elements are apart – is set to NaN if this is not known
  • msg a message providing more detail about the performed test and why it failed.

Constructors

ApproximatelyError(val::V, msg::S) where {V,S}

Generate an Error with value val and message msg.

ApproximatelyError(msg::S) where {S}

Generate a message without a value (using val=NaN internally) and message msg.

source
ManifoldsBase.ComponentManifoldError — Type
CompnentError{I,E} <: Exception

Store an error that occured in a component, where the additional index is stored.

Fields

  • index::I index where the error occured`
  • error::E error that occured.
source
ManifoldsBase.CompositeManifoldError — Type
CompositeManifoldError{T} <: Exception

A composite type to collect a set of errors that occured. Mainly used in conjunction with ComponentManifoldError to store a set of errors that occured.

Fields

  • errors a Vector of <:Exceptions.
source
ManifoldsBase.ManifoldDomainError — Type
ManifoldDomainError{<:Exception} <: Exception

An error to represent a nested (Domain) error on a manifold, for example if a point or tangent vector is invalid because its representation in some embedding is already invalid.

source
ManifoldsBase.OutOfInjectivityRadiusError — Type
OutOfInjectivityRadiusError

An error thrown when a function (for example logarithmic map or inverse_retract) is given arguments outside of its injectivity_radius.

source
diff --git a/previews/PR217/index.html b/previews/PR217/index.html index 0419427b..fdce3cb4 100644 --- a/previews/PR217/index.html +++ b/previews/PR217/index.html @@ -9,4 +9,4 @@ TITLE = {Manifolds.Jl: An Extensible Julia Framework for Data Analysis on Manifolds}, VOLUME = {49}, YEAR = {2023} -}

Note that the citation is in BibLaTeX format.

+}

Note that the citation is in BibLaTeX format.

diff --git a/previews/PR217/manifolds/index.html b/previews/PR217/manifolds/index.html index 2d13a73b..2571ce52 100644 --- a/previews/PR217/manifolds/index.html +++ b/previews/PR217/manifolds/index.html @@ -1,5 +1,5 @@ -Manifolds · ManifoldsBase.jl
GitHub

Manifolds

While the interface ManifoldsBase.jl does not cover concrete manifolds, it provides a few helpers to build or create manifolds based on existing manifolds

A default manifold

DefaultManifold is a simplified version of Euclidean and demonstrates a basic interface implementation. It can be used to perform simple tests. Since when using Manifolds.jl the Euclidean is available, the DefaultManifold itself is not exported.

ManifoldsBase.DefaultManifold — Type
DefaultManifold <: AbstractManifold

This default manifold illustrates the main features of the interface and provides a skeleton to build one's own manifold. It is a simplified/shortened variant of Euclidean from Manifolds.jl.

This manifold further illustrates how to type your manifold points and tangent vectors. Note that the interface does not require this, but it might be handy in debugging and educative situations to verify correctness of involved variables.

Constructor

DefaultManifold(n::Int...; field = ℝ, parameter::Symbol = :field)

Arguments:

  • n: shape of array representing points on the manifold.
  • field: field over which the manifold is defined. Either ℝ, ℂ or ℍ.
  • parameter: whether a type parameter should be used to store n. By default size is stored in a field. Value can either be :field or :type.
source

Embedded manifold

The embedded manifold is a manifold $\mathcal M$ which is modelled explicitly specifying its embedding $\mathcal N$ in which the points and tangent vectors are represented. Most prominently is_point and is_vector of an embedded manifold are implemented to check whether the point is a valid point in the embedding. This can of course still be extended by further tests. ManifoldsBase.jl provides two possibilities of easily introducing this in order to dispatch some functions to the embedding.

Implicit case: the IsEmbeddedManifold Trait

For the implicit case, your manifold has to be a subtype of the AbstractDecoratorManifold. Adding a method to the active_traits function for a manifold that returns an AbstractTrait IsEmbeddedManifold, makes that manifold an embedded manifold. You just have to also define get_embedding so that appropriate functions are passed on to that embedding. This is the implicit case, since the manifold type itself does not carry any information about the embedding, just the trait and the function definition do.

Explicit case: the EmbeddedManifold

The EmbeddedManifold itself is an AbstractDecoratorManifold so it is a case of the implicit embedding itself, but internally stores both the original manifold and the embedding. They are also parameters of the type. This way, an additional embedding of one manifold in another can be modelled. That is, if the manifold is implemented using the implicit embedding approach from before but can also be implemented using a different embedding, then this method should be chosen, since you can dispatch functions that you want to implement in this embedding then on the type which explicitly has the manifold and its embedding as parameters.

Hence this case should be used for any further embedding after the first or if the default implementation works without an embedding and the alternative needs one.

ManifoldsBase.EmbeddedManifold — Type
EmbeddedManifold{𝔽, MT <: AbstractManifold, NT <: AbstractManifold} <: AbstractDecoratorManifold{𝔽}

A type to represent an explicit embedding of a AbstractManifold M of type MT embedded into a manifold N of type NT. By default, an embedded manifold is set to be embedded, but neither isometrically embedded nor a submanifold.

Note

This type is not required if a manifold M is to be embedded in one specific manifold N. One can then just implement embed! and project!. You can further pass functions to the embedding, for example, when it is an isometric embedding, by using an AbstractDecoratorManifold. Only for a second –maybe considered non-default– embedding, this type should be considered in order to dispatch on different embed and project methods for different embeddings N.

Fields

  • manifold the manifold that is an embedded manifold
  • embedding a second manifold, the first one is embedded into

Constructor

EmbeddedManifold(M, N)

Generate the EmbeddedManifold of the AbstractManifold M into the AbstractManifold N.

source
ManifoldsBase.decorated_manifold — Method
decorated_manifold(M::EmbeddedManifold, d::Val{N} = Val(-1))

Return the manifold of M that is decorated with its embedding. For this specific type the internally stored enhanced manifold M.manifold is returned.

See also base_manifold, where this is used to (potentially) completely undecorate the manifold.

source

Metrics

Most metric-related functionality is currently defined in Manifolds.jl but a few basic types are defined here.

ManifoldsBase.AbstractMetric — Type
AbstractMetric

Abstract type for the pseudo-Riemannian metric tensor $g$, a family of smoothly varying inner products on the tangent space. See inner.

Functor

(metric::Metric)(M::AbstractManifold)
-(metric::Metric)(M::MetricManifold)

Generate the MetricManifold that wraps the manifold M with given metric. This works for both a variable containing the metric as well as a subtype T<:AbstractMetric, where a zero parameter constructor T() is availabe. If M is already a metric manifold, the inner manifold with the new metric is returned.

source
ManifoldsBase.EuclideanMetric — Type
EuclideanMetric <: RiemannianMetric

A general type for any manifold that employs the Euclidean Metric, for example the Euclidean manifold itself, or the Sphere, where every tangent space (as a plane in the embedding) uses this metric (in the embedding).

Since the metric is independent of the field type, this metric is also used for the Hermitian metrics, i.e. metrics that are analogous to the EuclideanMetric but where the field type of the manifold is ℂ.

This metric is the default metric for example for the Euclidean manifold.

source
ManifoldsBase.RiemannianMetric — Type
RiemannianMetric <: AbstractMetric

Abstract type for Riemannian metrics, a family of positive definite inner products. The positive definite property means that for $X ∈ T_p \mathcal M$, the inner product $g(X, X) > 0$ whenever $X$ is not the zero vector.

source
ManifoldsBase.change_metric — Method
change_metric(M::AbstractcManifold, G2::AbstractMetric, p, X)

On the AbstractManifold M with implicitly given metric $g_1$ and a second AbstractMetric $g_2$ this function performs a change of metric in the sense that it returns the tangent vector $Z=BX$ such that the linear map $B$ fulfills

\[g_2(Y_1,Y_2) = g_1(BY_1,BY_2) \quad \text{for all } Y_1, Y_2 ∈ T_p\mathcal M.\]

source
ManifoldsBase.change_representer — Method
change_representer(M::AbstractManifold, G2::AbstractMetric, p, X)

Convert the representer X of a linear function (in other words a cotangent vector at p) in the tangent space at p on the AbstractManifold M given with respect to the AbstractMetric G2 into the representer with respect to the (implicit) metric of M.

In order to convert X into the representer with respect to the (implicitly given) metric $g_1$ of M, we have to find the conversion function $c: T_p\mathcal M \to T_p\mathcal M$ such that

\[ g_2(X,Y) = g_1(c(X),Y)\]

source

A manifold for validation

ValidationManifold is a simple decorator using the AbstractDecoratorManifold that “decorates” a manifold with tests that all involved points and vectors are valid for the wrapped manifold. For example involved input and output paratemers are checked before and after running a function, repectively. This is done by calling is_point or is_vector whenever applicable.

ManifoldsBase.ValidationFibreVector — Type
ValidationFibreVector{TType<:VectorSpaceType,V,P} <: AbstractFibreVector{TType}

Represent a tangent vector to a point on an ValidationManifold. The original vector of the manifold is stored internally. The corresponding base point of the fibre can be stored as well.

The TType indicates the type of fibre, for example TangentSpaceType or CotangentSpaceType.

Fields

  • value::V: the internally stored vector on the fibre
  • point::P: the point the vector is associated with

Constructor

    ValidationFibreVector{TType}(value, point=nothing)
source
ManifoldsBase.ValidationMPoint — Type
ValidationMPoint{P} <: AbstractManifoldPoint

Represent a point on an ValidationManifold. The point is stored internally.

Fields

  • value::P: the internally stored point on a manifold

Constructor

    ValidationMPoint(value)

Create a point on the manifold with the value value.

source
ManifoldsBase.ValidationManifold — Type
ValidationManifold{𝔽,M<:AbstractManifold{𝔽}} <: AbstractDecoratorManifold{𝔽}

A manifold to add tests to input and output values of functions defined in the interface.

Additionally the points and tangent vectors can also be encapsulated, cf. ValidationMPoint, ValidationTVector, and ValidationCoTVector. These types can be used to see where some data is assumed to be from, when working on manifolds where both points and tangent vectors are represented as (plain) arrays.

Using the ignore_contexts keyword allows to specify a single Symbol or a vector of Symbols Of which contexts to ignore.

Current contexts are

  • :All: disable all checks
  • :Point: checks for points
  • :Vector: checks for vectors
  • :Output: checks for output
  • :Input: checks for input variables

Using the ignore_functions keyword (dictionary) allows to disable/ignore certain checks within single functions for this manifold. The key of the dictionary has to be the Function to exclude something in. The value is either a single symbol or a vector of symbols with the same meaning as the ignore_contexts keyword, but limited to this function

Examples

  • exp => :All disables all checks in the exp function
  • exp => :Point excludes point checks in the exp function
  • exp => [:Point, :Vector] excludes point and vector checks in the exp function

This manifold is a decorator for a manifold, i.e. it decorates a AbstractManifold M with types points, vectors, and covectors.

Fields

  • manifold::M: The manifold to be decorated
  • mode::Symbol: The mode to be used for error handling, either :error or :warn
  • ignore_contexts::AbstractVector{Symbol}: store contexts to be ignored of validation.
  • ignore_functions::Dict{<:Function,<:Union{Symbol,<:AbstractVector{Symbol}}: store contexts to be ignored with in a function or its mutating variant.

Constructors

ValidationManifold(M::AbstractManifold; kwargs...)

Generate the Validation manifold

ValidationManifold(M::AbstractManifold, V::ValidationManifold; kwargs...)

Generate the Validation manifold for M with the default values of V.

Keyword arguments

  • error::Symbol=:error: specify how errors in the validation should be reported. this is passed to is_point and is_vector as the error keyword argument. Available values are :error, :warn, :info, and :none. Every other value is treated as :none.
  • store_base_point::Bool=false: specify whether or not to store the point p a tangent or cotangent vector is associated with. This can be useful for debugging purposes.
  • ignore_contexts = Vector{Symbol}() a vector to indicate which validation contexts should not be performed.
  • ignore_functions=Dict{Function,Union{Symbol,Vector{Symbol}}}() a dictionary to disable certain contexts within functions. The key here is the non-mutating function variant (if it exists). The contexts are thre same as in ignore_contexts.
source
ManifoldsBase._msg — Method
_msg(str; error=:None, within::Union{Nothing,<:Function} = nothing,
-context::Union{NTuple{N,Symbol} where N} = NTuple{0,Symbol}())

issue a message str according to the mode mode (as @error, @warn, @info).

source
ManifoldsBase._vMc — Function
_vMc(M::ValidationManifold, f::Function, context::Symbol)
-_vMc(M::ValidationManifold, f::Function, context::NTuple{N,Symbol}) where {N}

Return whether a check should be performed within f and the context(s) provided.

This function returns false and hence indicates not to check, when

  • (one of the) context(s) is in the ignore list for f within ignore_functions
  • (one of the) context(s) is in the ignore_contexts list

Otherwise the test is active.

!!! Note This function is internal and used very often, co it has a very short name; _vMc stands for "ValidationManifold check".

source
ManifoldsBase.is_point — Method
is_point(M::ValidationManifold, p; kwargs...)

Perform is_point on a ValidationManifold, where two additional keywords can be used

  • within=nothing to specify a function from within which this call was issued
  • context::NTuple{N,Symbol} where N=() to specify one or more contexts, this call was issued in. The context :Point is added before checking whether the test should be performed

all other keywords are passed on.

source
ManifoldsBase.is_vector — Function
is_vector(M::ValidationManifold, p, X, cbp=true; kwargs...)

perform is_vector on a ValidationManifold, where two additional keywords can be used

  • within=nothing to specify a function from within which this call was issued
  • context::NTuple{N,Symbol} where N=() to specify one or more contexts, this call was issued in. The context :Point is added before checking whether the test should be performed

all other keywords are passed on.

source
+Manifolds · ManifoldsBase.jl
GitHub

Manifolds

While the interface ManifoldsBase.jl does not cover concrete manifolds, it provides a few helpers to build or create manifolds based on existing manifolds

A default manifold

DefaultManifold is a simplified version of Euclidean and demonstrates a basic interface implementation. It can be used to perform simple tests. Since when using Manifolds.jl the Euclidean is available, the DefaultManifold itself is not exported.

ManifoldsBase.DefaultManifold — Type
DefaultManifold <: AbstractManifold

This default manifold illustrates the main features of the interface and provides a skeleton to build one's own manifold. It is a simplified/shortened variant of Euclidean from Manifolds.jl.

This manifold further illustrates how to type your manifold points and tangent vectors. Note that the interface does not require this, but it might be handy in debugging and educative situations to verify correctness of involved variables.

Constructor

DefaultManifold(n::Int...; field = ℝ, parameter::Symbol = :field)

Arguments:

  • n: shape of array representing points on the manifold.
  • field: field over which the manifold is defined. Either ℝ, ℂ or ℍ.
  • parameter: whether a type parameter should be used to store n. By default size is stored in a field. Value can either be :field or :type.
source

Embedded manifold

The embedded manifold is a manifold $\mathcal M$ which is modelled explicitly specifying its embedding $\mathcal N$ in which the points and tangent vectors are represented. Most prominently is_point and is_vector of an embedded manifold are implemented to check whether the point is a valid point in the embedding. This can of course still be extended by further tests. ManifoldsBase.jl provides two possibilities of easily introducing this in order to dispatch some functions to the embedding.

Implicit case: the IsEmbeddedManifold Trait

For the implicit case, your manifold has to be a subtype of the AbstractDecoratorManifold. Adding a method to the active_traits function for a manifold that returns an AbstractTrait IsEmbeddedManifold, makes that manifold an embedded manifold. You just have to also define get_embedding so that appropriate functions are passed on to that embedding. This is the implicit case, since the manifold type itself does not carry any information about the embedding, just the trait and the function definition do.

Explicit case: the EmbeddedManifold

The EmbeddedManifold itself is an AbstractDecoratorManifold so it is a case of the implicit embedding itself, but internally stores both the original manifold and the embedding. They are also parameters of the type. This way, an additional embedding of one manifold in another can be modelled. That is, if the manifold is implemented using the implicit embedding approach from before but can also be implemented using a different embedding, then this method should be chosen, since you can dispatch functions that you want to implement in this embedding then on the type which explicitly has the manifold and its embedding as parameters.

Hence this case should be used for any further embedding after the first or if the default implementation works without an embedding and the alternative needs one.

ManifoldsBase.EmbeddedManifold — Type
EmbeddedManifold{𝔽, MT <: AbstractManifold, NT <: AbstractManifold} <: AbstractDecoratorManifold{𝔽}

A type to represent an explicit embedding of a AbstractManifold M of type MT embedded into a manifold N of type NT. By default, an embedded manifold is set to be embedded, but neither isometrically embedded nor a submanifold.

Note

This type is not required if a manifold M is to be embedded in one specific manifold N. One can then just implement embed! and project!. You can further pass functions to the embedding, for example, when it is an isometric embedding, by using an AbstractDecoratorManifold. Only for a second –maybe considered non-default– embedding, this type should be considered in order to dispatch on different embed and project methods for different embeddings N.

Fields

  • manifold the manifold that is an embedded manifold
  • embedding a second manifold, the first one is embedded into

Constructor

EmbeddedManifold(M, N)

Generate the EmbeddedManifold of the AbstractManifold M into the AbstractManifold N.

source
ManifoldsBase.decorated_manifold — Method
decorated_manifold(M::EmbeddedManifold, d::Val{N} = Val(-1))

Return the manifold of M that is decorated with its embedding. For this specific type the internally stored enhanced manifold M.manifold is returned.

See also base_manifold, where this is used to (potentially) completely undecorate the manifold.

source

Metrics

Most metric-related functionality is currently defined in Manifolds.jl but a few basic types are defined here.

ManifoldsBase.AbstractMetric — Type
AbstractMetric

Abstract type for the pseudo-Riemannian metric tensor $g$, a family of smoothly varying inner products on the tangent space. See inner.

Functor

(metric::Metric)(M::AbstractManifold)
+(metric::Metric)(M::MetricManifold)

Generate the MetricManifold that wraps the manifold M with given metric. This works for both a variable containing the metric as well as a subtype T<:AbstractMetric, where a zero parameter constructor T() is availabe. If M is already a metric manifold, the inner manifold with the new metric is returned.

source
ManifoldsBase.EuclideanMetric — Type
EuclideanMetric <: RiemannianMetric

A general type for any manifold that employs the Euclidean Metric, for example the Euclidean manifold itself, or the Sphere, where every tangent space (as a plane in the embedding) uses this metric (in the embedding).

Since the metric is independent of the field type, this metric is also used for the Hermitian metrics, i.e. metrics that are analogous to the EuclideanMetric but where the field type of the manifold is ℂ.

This metric is the default metric for example for the Euclidean manifold.

source
ManifoldsBase.RiemannianMetric — Type
RiemannianMetric <: AbstractMetric

Abstract type for Riemannian metrics, a family of positive definite inner products. The positive definite property means that for $X ∈ T_p \mathcal M$, the inner product $g(X, X) > 0$ whenever $X$ is not the zero vector.

source
ManifoldsBase.change_metric — Method
change_metric(M::AbstractcManifold, G2::AbstractMetric, p, X)

On the AbstractManifold M with implicitly given metric $g_1$ and a second AbstractMetric $g_2$ this function performs a change of metric in the sense that it returns the tangent vector $Z=BX$ such that the linear map $B$ fulfills

\[g_2(Y_1,Y_2) = g_1(BY_1,BY_2) \quad \text{for all } Y_1, Y_2 ∈ T_p\mathcal M.\]

source
ManifoldsBase.change_representer — Method
change_representer(M::AbstractManifold, G2::AbstractMetric, p, X)

Convert the representer X of a linear function (in other words a cotangent vector at p) in the tangent space at p on the AbstractManifold M given with respect to the AbstractMetric G2 into the representer with respect to the (implicit) metric of M.

In order to convert X into the representer with respect to the (implicitly given) metric $g_1$ of M, we have to find the conversion function $c: T_p\mathcal M \to T_p\mathcal M$ such that

\[ g_2(X,Y) = g_1(c(X),Y)\]

source

A manifold for validation

ValidationManifold is a simple decorator using the AbstractDecoratorManifold that “decorates” a manifold with tests that all involved points and vectors are valid for the wrapped manifold. For example involved input and output paratemers are checked before and after running a function, repectively. This is done by calling is_point or is_vector whenever applicable.

ManifoldsBase.ValidationFibreVector — Type
ValidationFibreVector{TType<:VectorSpaceType,V,P} <: AbstractFibreVector{TType}

Represent a tangent vector to a point on an ValidationManifold. The original vector of the manifold is stored internally. The corresponding base point of the fibre can be stored as well.

The TType indicates the type of fibre, for example TangentSpaceType or CotangentSpaceType.

Fields

  • value::V: the internally stored vector on the fibre
  • point::P: the point the vector is associated with

Constructor

    ValidationFibreVector{TType}(value, point=nothing)
source
ManifoldsBase.ValidationMPoint — Type
ValidationMPoint{P} <: AbstractManifoldPoint

Represent a point on an ValidationManifold. The point is stored internally.

Fields

  • value::P: the internally stored point on a manifold

Constructor

    ValidationMPoint(value)

Create a point on the manifold with the value value.

source
ManifoldsBase.ValidationManifold — Type
ValidationManifold{𝔽,M<:AbstractManifold{𝔽}} <: AbstractDecoratorManifold{𝔽}

A manifold to add tests to input and output values of functions defined in the interface.

Additionally the points and tangent vectors can also be encapsulated, cf. ValidationMPoint, ValidationTVector, and ValidationCoTVector. These types can be used to see where some data is assumed to be from, when working on manifolds where both points and tangent vectors are represented as (plain) arrays.

Using the ignore_contexts keyword allows to specify a single Symbol or a vector of Symbols Of which contexts to ignore.

Current contexts are

  • :All: disable all checks
  • :Point: checks for points
  • :Vector: checks for vectors
  • :Output: checks for output
  • :Input: checks for input variables

Using the ignore_functions keyword (dictionary) allows to disable/ignore certain checks within single functions for this manifold. The key of the dictionary has to be the Function to exclude something in. The value is either a single symbol or a vector of symbols with the same meaning as the ignore_contexts keyword, but limited to this function

Examples

  • exp => :All disables all checks in the exp function
  • exp => :Point excludes point checks in the exp function
  • exp => [:Point, :Vector] excludes point and vector checks in the exp function

This manifold is a decorator for a manifold, i.e. it decorates a AbstractManifold M with types points, vectors, and covectors.

Fields

  • manifold::M: The manifold to be decorated
  • mode::Symbol: The mode to be used for error handling, either :error or :warn
  • ignore_contexts::AbstractVector{Symbol}: store contexts to be ignored of validation.
  • ignore_functions::Dict{<:Function,<:Union{Symbol,<:AbstractVector{Symbol}}: store contexts to be ignored with in a function or its mutating variant.

Constructors

ValidationManifold(M::AbstractManifold; kwargs...)

Generate the Validation manifold

ValidationManifold(M::AbstractManifold, V::ValidationManifold; kwargs...)

Generate the Validation manifold for M with the default values of V.

Keyword arguments

  • error::Symbol=:error: specify how errors in the validation should be reported. this is passed to is_point and is_vector as the error keyword argument. Available values are :error, :warn, :info, and :none. Every other value is treated as :none.
  • store_base_point::Bool=false: specify whether or not to store the point p a tangent or cotangent vector is associated with. This can be useful for debugging purposes.
  • ignore_contexts = Vector{Symbol}() a vector to indicate which validation contexts should not be performed.
  • ignore_functions=Dict{Function,Union{Symbol,Vector{Symbol}}}() a dictionary to disable certain contexts within functions. The key here is the non-mutating function variant (if it exists). The contexts are thre same as in ignore_contexts.
source
ManifoldsBase._msg — Method
_msg(str; error=:None, within::Union{Nothing,<:Function} = nothing,
+context::Union{NTuple{N,Symbol} where N} = NTuple{0,Symbol}())

issue a message str according to the mode mode (as @error, @warn, @info).

source
ManifoldsBase._vMc — Function
_vMc(M::ValidationManifold, f::Function, context::Symbol)
+_vMc(M::ValidationManifold, f::Function, context::NTuple{N,Symbol}) where {N}

Return whether a check should be performed within f and the context(s) provided.

This function returns false and hence indicates not to check, when

  • (one of the) context(s) is in the ignore list for f within ignore_functions
  • (one of the) context(s) is in the ignore_contexts list

Otherwise the test is active.

!!! Note This function is internal and used very often, co it has a very short name; _vMc stands for "ValidationManifold check".

source
ManifoldsBase.is_point — Method
is_point(M::ValidationManifold, p; kwargs...)

Perform is_point on a ValidationManifold, where two additional keywords can be used

  • within=nothing to specify a function from within which this call was issued
  • context::NTuple{N,Symbol} where N=() to specify one or more contexts, this call was issued in. The context :Point is added before checking whether the test should be performed

all other keywords are passed on.

source
ManifoldsBase.is_vector — Function
is_vector(M::ValidationManifold, p, X, cbp=true; kwargs...)

perform is_vector on a ValidationManifold, where two additional keywords can be used

  • within=nothing to specify a function from within which this call was issued
  • context::NTuple{N,Symbol} where N=() to specify one or more contexts, this call was issued in. The context :Point is added before checking whether the test should be performed

all other keywords are passed on.

source
diff --git a/previews/PR217/metamanifolds/index.html b/previews/PR217/metamanifolds/index.html index 9e18abb8..345f3a92 100644 --- a/previews/PR217/metamanifolds/index.html +++ b/previews/PR217/metamanifolds/index.html @@ -1,32 +1,32 @@ -Meta-Manifolds · ManifoldsBase.jl
GitHub

Meta Manifolds

While the interface does not provide concrete manifolds itself, it does provide several manifolds that can be build based on a given AbstractManifold instance.

(Abstract) power manifold

A power manifold is constructed like higher dimensional vector spaces are formed from the real line, just that for every point $p = (p_1,\ldots,p_n) ∈ \mathcal M^n$ on the power manifold $\mathcal M^n$ the entries of $p$ are points $p_1,\ldots,p_n ∈ \mathcal M$ on some manifold $\mathcal M$. Note that $n$ can also be replaced by multiple values, such that $p$ is not a vector but a matrix or a multi-index array of points.

ManifoldsBase.PowerManifold — Type
PowerManifold{𝔽,TM<:AbstractManifold,TSize,TPR<:AbstractPowerRepresentation} <: AbstractPowerManifold{𝔽,TM}

The power manifold $\mathcal M^{n_1× n_2 × … × n_d}$ with power geometry. TSize defines the number of elements along each axis, either statically using TypeParameter or storing it in a field.

For example, a manifold-valued time series would be represented by a power manifold with $d$ equal to 1 and $n_1$ equal to the number of samples. A manifold-valued image (for example in diffusion tensor imaging) would be represented by a two-axis power manifold ($d=2$) with $n_1$ and $n_2$ equal to width and height of the image.

While the size of the manifold is static, points on the power manifold would not be represented by statically-sized arrays.

Constructor

PowerManifold(M::PowerManifold, N_1, N_2, ..., N_d; parameter::Symbol=:field)
+Meta-Manifolds · ManifoldsBase.jl
GitHub
Meta Manifolds
While the interface does not provide concrete manifolds itself, it does provide several manifolds that can be build based on a given AbstractManifold instance.
(Abstract) power manifold
A power manifold is constructed like higher dimensional vector spaces are formed from the real line, just that for every point $p = (p_1,\ldots,p_n) ∈ \mathcal M^n$ on the power manifold $\mathcal M^n$ the entries of $p$ are points $p_1,\ldots,p_n ∈ \mathcal M$ on some manifold $\mathcal M$. Note that $n$ can also be replaced by multiple values, such that $p$ is not a vector but a matrix or a multi-index array of points.
ManifoldsBase.PowerManifold — Type
PowerManifold{𝔽,TM<:AbstractManifold,TSize,TPR<:AbstractPowerRepresentation} <: AbstractPowerManifold{𝔽,TM}
The power manifold $\mathcal M^{n_1× n_2 × … × n_d}$ with power geometry.  TSize defines the number of elements along each axis, either statically using  TypeParameter or storing it in a field.
For example, a manifold-valued time series would be represented by a power manifold with $d$ equal to 1 and $n_1$ equal to the number of samples. A manifold-valued image (for example in diffusion tensor imaging) would be represented by a two-axis power manifold ($d=2$) with $n_1$ and $n_2$ equal to width and height of the image.
While the size of the manifold is static, points on the power manifold would not be represented by statically-sized arrays.
Constructor
PowerManifold(M::PowerManifold, N_1, N_2, ..., N_d; parameter::Symbol=:field)
 PowerManifold(M::AbstractManifold, NestedPowerRepresentation(), N_1, N_2, ..., N_d; parameter::Symbol=:field)
-M^(N_1, N_2, ..., N_d)
Generate the power manifold $M^{N_1 × N_2 × … × N_d}$. By default, a PowerManifold is expanded further, i.e. for M=PowerManifold(N, 3) PowerManifold(M, 2) is equivalent to PowerManifold(N, 3, 2). Points are then 3×2 matrices of points on N. Providing a NestedPowerRepresentation as the second argument to the constructor can be used to nest manifold, i.e. PowerManifold(M, NestedPowerRepresentation(), 2) represents vectors of length 2 whose elements are vectors of length 3 of points on N in a nested array representation.
The third signature M^(...) is equivalent to the first one, and hence either yields a combination of power manifolds to one larger power manifold, or a power manifold with the default representation.
Since there is no default AbstractPowerRepresentation within this interface, the ^ operator is only available for PowerManifolds and concatenates dimensions.
parameter: whether a type parameter should be used to store n. By default size is stored in a field. Value can either be :field or :type.
source
Base.copyto! — Method
copyto!(M::PowerManifoldNested, Y, p, X)
Copy the values elementwise, i.e. call copyto!(M.manifold, B, a, A) for all elements A, a and B of X, p, and Y, respectively.
source
Base.copyto! — Method
copyto!(M::PowerManifoldNested, q, p)
Copy the values elementwise, i.e. call copyto!(M.manifold, b, a) for all elements a and b of p and q, respectively.
source
Base.exp — Method
exp(M::AbstractPowerManifold, p, X)
Compute the exponential map from p in direction X on the AbstractPowerManifold M, which can be computed using the base manifolds exponential map elementwise.
source
Base.fill! — Method
fill!(P, p, M::AbstractPowerManifold)
Fill a point P on the AbstractPowerManifold M, setting every entry to p.
Note
while usually the manifold is the first argument in all functions in ManifoldsBase.jl, we follow the signature of fill!, where the power manifold serves are the size information.
source
Base.fill — Method
fill(p, M::AbstractPowerManifold)
Create a point on the AbstractPowerManifold M, where every entry is set to the point p.
Note
while usually the manifold is a first argument in all functions in ManifoldsBase.jl, we follow the signature of fill, where the power manifold serves are the size information.
source
Base.getindex — Method
getindex(p, M::AbstractPowerManifold, i::Union{Integer,Colon,AbstractVector}...)
-p[M::AbstractPowerManifold, i...]
Access the element(s) at index [i...] of a point p on an AbstractPowerManifold M by linear or multidimensional indexing. See also Array Indexing in Julia.
source
Base.log — Method
log(M::AbstractPowerManifold, p, q)
Compute the logarithmic map from p to q on the AbstractPowerManifold M, which can be computed using the base manifolds logarithmic map elementwise.
source
Base.setindex! — Method
setindex!(q, p, M::AbstractPowerManifold, i::Union{Integer,Colon,AbstractVector}...)
-q[M::AbstractPowerManifold, i...] = p
Set the element(s) at index [i...] of a point q on an AbstractPowerManifold M by linear or multidimensional indexing to q. See also Array Indexing in Julia.
source
Base.view — Method
view(p, M::PowerManifoldNested, i::Union{Integer,Colon,AbstractVector}...)
Get the view of the element(s) at index [i...] of a point p on an AbstractPowerManifold M by linear or multidimensional indexing.
source
LinearAlgebra.norm — Function
norm(M::AbstractPowerManifold, p, X, r::Real=2)
Compute the norm of X from the tangent space of p on an AbstractPowerManifold M, i.e. from the element wise norms r-norm is computed, where the default r=2 yields the Frobenius norm is computed.
source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::AbstractPowerManifold, p, X, V)
-Weingarten!(M::AbstractPowerManifold, Y, p, X, V)
Since the metric decouples, also the computation of the Weingarten map $\mathcal W_p$ can be computed elementwise on the single elements of the PowerManifold M.
source
ManifoldsBase._allocate_access_nested — Method
_allocate_access_nested(M::PowerManifoldNested, y, i)
Helper function for allocate_result on PowerManifoldNested. In allocation y can be a number in which case _access_nested wouldn't work.
source
ManifoldsBase.change_metric — Method
change_metric(M::AbstractPowerManifold, ::AbstractMetric, p, X)
Since the metric on a power manifold decouples, the change of metric can be done elementwise.
source
ManifoldsBase.change_representer — Method
change_representer(M::AbstractPowerManifold, ::AbstractMetric, p, X)
Since the metric on a power manifold decouples, the change of a representer can be done elementwise
source
ManifoldsBase.check_point — Method
check_point(M::AbstractPowerManifold, p; kwargs...)
Check whether p is a valid point on an AbstractPowerManifold M, i.e. each element of p has to be a valid point on the base manifold. If p is not a point on M a CompositeManifoldError consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.check_power_size — Method
check_power_size(M, p)
-check_power_size(M, p, X)
Check whether phas the right size to represent points onM`` generically, i.e. just checking the overall sizes, not the individual ones per manifold.
source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractPowerManifold, p, X; kwargs... )
Check whether X is a tangent vector to p an the AbstractPowerManifold M, i.e. atfer check_point(M, p), and all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.default_inverse_retraction_method — Method
default_inverse_retraction_method(M::PowerManifold)
Use the default inverse retraction method of the internal M.manifold also in defaults of functions defined for the power manifold, meaning that this is used elementwise.
source
ManifoldsBase.default_retraction_method — Method
default_retraction_method(M::PowerManifold)
Use the default retraction method of the internal M.manifold also in defaults of functions defined for the power manifold, meaning that this is used elementwise.
source
ManifoldsBase.default_vector_transport_method — Method
default_vector_transport_method(M::PowerManifold)
Use the default vector transport method of the internal M.manifold also in defaults of functions defined for the power manifold, meaning that this is used elementwise.
source
ManifoldsBase.distance — Function
distance(M::AbstractPowerManifold, p, q, r::Real=2)
-distance(M::AbstractPowerManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an AbstractPowerManifold.
First, the componentwise distances are computed using the Riemannian distance function on M.manifold. These can be approximated using the norm of an AbstractInverseRetractionMethod m. This yields an array of distance values.
Second, we compute the r-norm on this array of distances. This is also the only place, there the r is used.
source
ManifoldsBase.distance — Method
distance(M::AbstractPowerManifold, p, q, r::Real=2)
-distance(M::AbstractPowerManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an AbstractPowerManifold.
First, the componentwise distances are computed using the Riemannian distance function on M.manifold. These can be approximated using the norm of an AbstractInverseRetractionMethod m. This yields an array of distance values.
Second, we compute the r-norm on this array of distances. This is also the only place, there the r is used.
source
ManifoldsBase.inner — Method
inner(M::AbstractPowerManifold, p, X, Y)
Compute the inner product of X and Y from the tangent space at p on an AbstractPowerManifold M, i.e. for each arrays entry the tangent vector entries from X and Y are in the tangent space of the corresponding element from p. The inner product is then the sum of the elementwise inner products.
source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::PowerManifold)
Returns the manifold-dimension of an PowerManifold M $=\mathcal N = (\mathcal M)^{n_1,…,n_d}$, i.e. with $n=(n_1,…,n_d)$ the array size of the power manifold and $d_{\mathcal M}$ the dimension of the base manifold $\mathcal M$, the manifold is of dimension
\[\dim(\mathcal N) = \dim(\mathcal M)\prod_{i=1}^d n_i = n_1n_2⋅…⋅ n_d \dim(\mathcal M).\]
source
ManifoldsBase.sectional_curvature — Method
sectional_curvature(M::AbstractPowerManifold, p, X, Y)
Compute the sectional curvature of a power manifold manifold $\mathcal M$ at a point $p \in \mathcal M$ on two linearly independent tangent vectors at $p$. It may be 0 for  if projections of X and Y on subspaces corresponding to component manifolds are not linearly independent.
source
ManifoldsBase.sectional_curvature_max — Method
sectional_curvature_max(M::AbstractPowerManifold)
Upper bound on sectional curvature of AbstractPowerManifold M. It is the maximum of sectional curvature of the wrapped manifold and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0, ... 0) and (0, X_2, 0, ..., 0) is 0.
source
ManifoldsBase.sectional_curvature_min — Method
sectional_curvature_min(M::AbstractPowerManifold)
Lower bound on sectional curvature of AbstractPowerManifold M. It is the minimum of sectional curvature of the wrapped manifold and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0, ... 0) and (0, X_2, 0, ..., 0) is 0.
source
Product Manifold
ManifoldsBase.ProductManifold — Type
ProductManifold{𝔽,TM<:Tuple} <: AbstractManifold{𝔽}
Product manifold $M_1 × M_2 × …  × M_n$ with product geometry.
Constructor
ProductManifold(M_1, M_2, ..., M_n)
generates the product manifold $M_1 × M_2 × … × M_n$. Alternatively, the same manifold can be contructed using the × operator: M_1 × M_2 × M_3.
source
Base.exp — Method
exp(M::ProductManifold, p, X)
compute the exponential map from p in the direction of X on the ProductManifold M, which is the elementwise exponential map on the internal manifolds that build M.
source
Base.getindex — Method
getindex(M::TangentSpace{𝔽,<:ProductManifold}, i::Integer)
-TpM[i]
Access the ith manifold component from a ProductManifolds' tangent space TpM.
source
Base.log — Method
log(M::ProductManifold, p, q)
Compute the logarithmic map from p to q on the ProductManifold M, which can be computed using the logarithmic maps of the manifolds elementwise.
source
LinearAlgebra.cross — Method
×(m, n)
+M^(N_1, N_2, ..., N_d)
Generate the power manifold $M^{N_1 × N_2 × … × N_d}$. By default, a PowerManifold is expanded further, i.e. for M=PowerManifold(N, 3) PowerManifold(M, 2) is equivalent to PowerManifold(N, 3, 2). Points are then 3×2 matrices of points on N. Providing a NestedPowerRepresentation as the second argument to the constructor can be used to nest manifold, i.e. PowerManifold(M, NestedPowerRepresentation(), 2) represents vectors of length 2 whose elements are vectors of length 3 of points on N in a nested array representation.
The third signature M^(...) is equivalent to the first one, and hence either yields a combination of power manifolds to one larger power manifold, or a power manifold with the default representation.
Since there is no default AbstractPowerRepresentation within this interface, the ^ operator is only available for PowerManifolds and concatenates dimensions.
parameter: whether a type parameter should be used to store n. By default size is stored in a field. Value can either be :field or :type.
source
Base.copyto! — Method
copyto!(M::PowerManifoldNested, Y, p, X)
Copy the values elementwise, i.e. call copyto!(M.manifold, B, a, A) for all elements A, a and B of X, p, and Y, respectively.
source
Base.copyto! — Method
copyto!(M::PowerManifoldNested, q, p)
Copy the values elementwise, i.e. call copyto!(M.manifold, b, a) for all elements a and b of p and q, respectively.
source
Base.exp — Method
exp(M::AbstractPowerManifold, p, X)
Compute the exponential map from p in direction X on the AbstractPowerManifold M, which can be computed using the base manifolds exponential map elementwise.
source
Base.fill! — Method
fill!(P, p, M::AbstractPowerManifold)
Fill a point P on the AbstractPowerManifold M, setting every entry to p.
Note
while usually the manifold is the first argument in all functions in ManifoldsBase.jl, we follow the signature of fill!, where the power manifold serves are the size information.
source
Base.fill — Method
fill(p, M::AbstractPowerManifold)
Create a point on the AbstractPowerManifold M, where every entry is set to the point p.
Note
while usually the manifold is a first argument in all functions in ManifoldsBase.jl, we follow the signature of fill, where the power manifold serves are the size information.
source
Base.getindex — Method
getindex(p, M::AbstractPowerManifold, i::Union{Integer,Colon,AbstractVector}...)
+p[M::AbstractPowerManifold, i...]
Access the element(s) at index [i...] of a point p on an AbstractPowerManifold M by linear or multidimensional indexing. See also Array Indexing in Julia.
source
Base.log — Method
log(M::AbstractPowerManifold, p, q)
Compute the logarithmic map from p to q on the AbstractPowerManifold M, which can be computed using the base manifolds logarithmic map elementwise.
source
Base.setindex! — Method
setindex!(q, p, M::AbstractPowerManifold, i::Union{Integer,Colon,AbstractVector}...)
+q[M::AbstractPowerManifold, i...] = p
Set the element(s) at index [i...] of a point q on an AbstractPowerManifold M by linear or multidimensional indexing to q. See also Array Indexing in Julia.
source
Base.view — Method
view(p, M::PowerManifoldNested, i::Union{Integer,Colon,AbstractVector}...)
Get the view of the element(s) at index [i...] of a point p on an AbstractPowerManifold M by linear or multidimensional indexing.
source
LinearAlgebra.norm — Function
norm(M::AbstractPowerManifold, p, X, r::Real=2)
Compute the norm of X from the tangent space of p on an AbstractPowerManifold M, i.e. from the element wise norms r-norm is computed, where the default r=2 yields the Frobenius norm is computed.
source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::AbstractPowerManifold, p, X, V)
+Weingarten!(M::AbstractPowerManifold, Y, p, X, V)
Since the metric decouples, also the computation of the Weingarten map $\mathcal W_p$ can be computed elementwise on the single elements of the PowerManifold M.
source
ManifoldsBase._allocate_access_nested — Method
_allocate_access_nested(M::PowerManifoldNested, y, i)
Helper function for allocate_result on PowerManifoldNested. In allocation y can be a number in which case _access_nested wouldn't work.
source
ManifoldsBase.change_metric — Method
change_metric(M::AbstractPowerManifold, ::AbstractMetric, p, X)
Since the metric on a power manifold decouples, the change of metric can be done elementwise.
source
ManifoldsBase.change_representer — Method
change_representer(M::AbstractPowerManifold, ::AbstractMetric, p, X)
Since the metric on a power manifold decouples, the change of a representer can be done elementwise
source
ManifoldsBase.check_point — Method
check_point(M::AbstractPowerManifold, p; kwargs...)
Check whether p is a valid point on an AbstractPowerManifold M, i.e. each element of p has to be a valid point on the base manifold. If p is not a point on M a CompositeManifoldError consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.check_power_size — Method
check_power_size(M, p)
+check_power_size(M, p, X)
Check whether phas the right size to represent points onM`` generically, i.e. just checking the overall sizes, not the individual ones per manifold.
source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractPowerManifold, p, X; kwargs... )
Check whether X is a tangent vector to p an the AbstractPowerManifold M, i.e. atfer check_point(M, p), and all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.default_inverse_retraction_method — Method
default_inverse_retraction_method(M::PowerManifold)
Use the default inverse retraction method of the internal M.manifold also in defaults of functions defined for the power manifold, meaning that this is used elementwise.
source
ManifoldsBase.default_retraction_method — Method
default_retraction_method(M::PowerManifold)
Use the default retraction method of the internal M.manifold also in defaults of functions defined for the power manifold, meaning that this is used elementwise.
source
ManifoldsBase.default_vector_transport_method — Method
default_vector_transport_method(M::PowerManifold)
Use the default vector transport method of the internal M.manifold also in defaults of functions defined for the power manifold, meaning that this is used elementwise.
source
ManifoldsBase.distance — Function
distance(M::AbstractPowerManifold, p, q, r::Real=2)
+distance(M::AbstractPowerManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an AbstractPowerManifold.
First, the componentwise distances are computed using the Riemannian distance function on M.manifold. These can be approximated using the norm of an AbstractInverseRetractionMethod m. This yields an array of distance values.
Second, we compute the r-norm on this array of distances. This is also the only place, there the r is used.
source
ManifoldsBase.distance — Method
distance(M::AbstractPowerManifold, p, q, r::Real=2)
+distance(M::AbstractPowerManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an AbstractPowerManifold.
First, the componentwise distances are computed using the Riemannian distance function on M.manifold. These can be approximated using the norm of an AbstractInverseRetractionMethod m. This yields an array of distance values.
Second, we compute the r-norm on this array of distances. This is also the only place, there the r is used.
source
ManifoldsBase.inner — Method
inner(M::AbstractPowerManifold, p, X, Y)
Compute the inner product of X and Y from the tangent space at p on an AbstractPowerManifold M, i.e. for each arrays entry the tangent vector entries from X and Y are in the tangent space of the corresponding element from p. The inner product is then the sum of the elementwise inner products.
source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::PowerManifold)
Returns the manifold-dimension of an PowerManifold M $=\mathcal N = (\mathcal M)^{n_1,…,n_d}$, i.e. with $n=(n_1,…,n_d)$ the array size of the power manifold and $d_{\mathcal M}$ the dimension of the base manifold $\mathcal M$, the manifold is of dimension
\[\dim(\mathcal N) = \dim(\mathcal M)\prod_{i=1}^d n_i = n_1n_2⋅…⋅ n_d \dim(\mathcal M).\]
source
ManifoldsBase.sectional_curvature — Method
sectional_curvature(M::AbstractPowerManifold, p, X, Y)
Compute the sectional curvature of a power manifold manifold $\mathcal M$ at a point $p \in \mathcal M$ on two linearly independent tangent vectors at $p$. It may be 0 for  if projections of X and Y on subspaces corresponding to component manifolds are not linearly independent.
source
ManifoldsBase.sectional_curvature_max — Method
sectional_curvature_max(M::AbstractPowerManifold)
Upper bound on sectional curvature of AbstractPowerManifold M. It is the maximum of sectional curvature of the wrapped manifold and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0, ... 0) and (0, X_2, 0, ..., 0) is 0.
source
ManifoldsBase.sectional_curvature_min — Method
sectional_curvature_min(M::AbstractPowerManifold)
Lower bound on sectional curvature of AbstractPowerManifold M. It is the minimum of sectional curvature of the wrapped manifold and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0, ... 0) and (0, X_2, 0, ..., 0) is 0.
source
Product Manifold
ManifoldsBase.ProductManifold — Type
ProductManifold{𝔽,TM<:Tuple} <: AbstractManifold{𝔽}
Product manifold $M_1 × M_2 × …  × M_n$ with product geometry.
Constructor
ProductManifold(M_1, M_2, ..., M_n)
generates the product manifold $M_1 × M_2 × … × M_n$. Alternatively, the same manifold can be contructed using the × operator: M_1 × M_2 × M_3.
source
Base.exp — Method
exp(M::ProductManifold, p, X)
compute the exponential map from p in the direction of X on the ProductManifold M, which is the elementwise exponential map on the internal manifolds that build M.
source
Base.getindex — Method
getindex(M::TangentSpace{𝔽,<:ProductManifold}, i::Integer)
+TpM[i]
Access the ith manifold component from a ProductManifolds' tangent space TpM.
source
Base.log — Method
log(M::ProductManifold, p, q)
Compute the logarithmic map from p to q on the ProductManifold M, which can be computed using the logarithmic maps of the manifolds elementwise.
source
LinearAlgebra.cross — Method
×(M, N)
 cross(M, N)
-cross(M1, M2, M3,...)
Return the ProductManifold For two AbstractManifolds M and N, where for the case that one of them is a ProductManifold itself, the other is either prepended (if N is a product) or appenden (if M) is. If both are product manifold, they are combined into one product manifold, keeping the order.
For the case that more than one is a product manifold of these is build with the same approach as above
source
LinearAlgebra.cross — Method
×(m, n)
+cross(M1, M2, M3,...)
Return the ProductManifold For two AbstractManifolds M and N, where for the case that one of them is a ProductManifold itself, the other is either prepended (if N is a product) or appenden (if M) is. If both are product manifold, they are combined into one product manifold, keeping the order.
For the case that more than one is a product manifold of these is build with the same approach as above
source
LinearAlgebra.norm — Function
norm(M::ProductManifold, p, X, r::Real=2)
Compute the (r-)norm of X from the tangent space of p on the ProductManifold, i.e. from the element wise norms the 2-norm is computed.
source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::ProductManifold, p, X, V)
-Weingarten!(M::ProductManifold, Y, p, X, V)
Since the metric decouples, also the computation of the Weingarten map $\mathcal W_p$ can be computed elementwise on the single elements of the ProductManifold M.
source
ManifoldsBase.change_metric — Method
change_metric(M::ProductManifold, ::AbstractMetric, p, X)
Since the metric on a product manifold decouples, the change of metric can be done elementwise.
source
ManifoldsBase.change_representer — Method
change_representer(M::ProductManifold, ::AbstractMetric, p, X)
Since the metric on a product manifold decouples, the change of a representer can be done elementwise
source
ManifoldsBase.check_point — Method
check_point(M::ProductManifold, p; kwargs...)
Check whether p is a valid point on the ProductManifold M. If p is not a point on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.check_size — Method
check_size(M::ProductManifold, p; kwargs...)
Check whether p is of valid size on the ProductManifold M. If p has components of wrong size a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.check_vector — Method
check_vector(M::ProductManifold, p, X; kwargs... )
Check whether X is a tangent vector to p on the ProductManifold M, i.e. all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.distance — Function
distance(M::ProductManifold, p, q, r::Real=2)
-distance(M::ProductManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an ProductManifold.
First, the componentwise distances are computed. These can be approximated using the norm of an AbstractInverseRetractionMethod m. Then, the r-norm of the tuple of these elements is computed.
source
ManifoldsBase.distance — Function
distance(M::ProductManifold, p, q, r::Real=2)
-distance(M::ProductManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an ProductManifold.
First, the componentwise distances are computed. These can be approximated using the norm of an AbstractInverseRetractionMethod m. Then, the r-norm of the tuple of these elements is computed.
source
ManifoldsBase.inner — Method
inner(M::ProductManifold, p, X, Y)
compute the inner product of two tangent vectors X, Y from the tangent space at p on the ProductManifold M, which is just the sum of the internal manifolds that build M.
source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::ProductManifold, p, q, m::InverseProductRetraction)
Compute the inverse retraction from p with respect to q on the ProductManifold M using an InverseProductRetraction, which by default encapsulates a inverse retraction for each manifold of the product. Then this method is performed elementwise, so the encapsulated inverse retraction methods have to be available per factor.
source
ManifoldsBase.retract — Method
retract(M::ProductManifold, p, X, m::ProductRetraction)
Compute the retraction from p with tangent vector X on the ProductManifold M using an ProductRetraction, which by default encapsulates retractions of the base manifolds. Then this method is performed elementwise, so the encapsulated retractions method has to be one that is available on the manifolds.
source
ManifoldsBase.sectional_curvature — Method
sectional_curvature(M::ProductManifold, p, X, Y)
Compute the sectional curvature of a manifold $\mathcal M$ at a point $p \in \mathcal M$ on two linearly independent tangent vectors at $p$. It may be 0 for a product of non-flat manifolds if projections of X and Y on subspaces corresponding to component manifolds are not linearly independent.
source
ManifoldsBase.sectional_curvature_max — Method
sectional_curvature_max(M::ProductManifold)
Upper bound on sectional curvature of ProductManifold M. It is the maximum of sectional curvatures of component manifolds and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0) and (0, X_2) is 0.
source
ManifoldsBase.sectional_curvature_min — Method
sectional_curvature_min(M::ProductManifold)
Lower bound on sectional curvature of ProductManifold M. It is the minimum of sectional curvatures of component manifolds and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0) and (0, X_2) is 0.
source
ManifoldsBase.select_from_tuple — Method
select_from_tuple(t::NTuple{N, Any}, positions::Val{P})
Selects elements of tuple t at positions specified by the second argument. For example select_from_tuple(("a", "b", "c"), Val((3, 1, 1))) returns ("c", "a", "a").
source
ManifoldsBase.submanifold — Method
submanifold(M::ProductManifold, i::Val)
-submanifold(M::ProductManifold, i::AbstractVector)
Extract the factor of the product manifold M indicated by indices in i. For example, for i equal to Val((1, 3)) the product manifold constructed from the first and the third factor is returned.
The version with AbstractVector is not type-stable, for better preformance use Val.
source
LinearAlgebra.norm — Function
norm(M::ProductManifold, p, X, r::Real=2)
Compute the (r-)norm of X from the tangent space of p on the ProductManifold, i.e. from the element wise norms the 2-norm is computed.
source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::ProductManifold, p, X, V)
+Weingarten!(M::ProductManifold, Y, p, X, V)
Since the metric decouples, also the computation of the Weingarten map $\mathcal W_p$ can be computed elementwise on the single elements of the ProductManifold M.
source
ManifoldsBase.change_metric — Method
change_metric(M::ProductManifold, ::AbstractMetric, p, X)
Since the metric on a product manifold decouples, the change of metric can be done elementwise.
source
ManifoldsBase.change_representer — Method
change_representer(M::ProductManifold, ::AbstractMetric, p, X)
Since the metric on a product manifold decouples, the change of a representer can be done elementwise
source
ManifoldsBase.check_point — Method
check_point(M::ProductManifold, p; kwargs...)
Check whether p is a valid point on the ProductManifold M. If p is not a point on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.check_size — Method
check_size(M::ProductManifold, p; kwargs...)
Check whether p is of valid size on the ProductManifold M. If p has components of wrong size a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.check_vector — Method
check_vector(M::ProductManifold, p, X; kwargs... )
Check whether X is a tangent vector to p on the ProductManifold M, i.e. all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.
The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.distance — Function
distance(M::ProductManifold, p, q, r::Real=2)
+distance(M::ProductManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an ProductManifold.
First, the componentwise distances are computed. These can be approximated using the norm of an AbstractInverseRetractionMethod m. Then, the r-norm of the tuple of these elements is computed.
source
ManifoldsBase.distance — Function
distance(M::ProductManifold, p, q, r::Real=2)
+distance(M::ProductManifold, p, q, m::AbstractInverseRetractionMethod=LogarithmicInverseRetraction(), r::Real=2)
Compute the distance between q and p on an ProductManifold.
First, the componentwise distances are computed. These can be approximated using the norm of an AbstractInverseRetractionMethod m. Then, the r-norm of the tuple of these elements is computed.
source
ManifoldsBase.inner — Method
inner(M::ProductManifold, p, X, Y)
compute the inner product of two tangent vectors X, Y from the tangent space at p on the ProductManifold M, which is just the sum of the internal manifolds that build M.
source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::ProductManifold, p, q, m::InverseProductRetraction)
Compute the inverse retraction from p with respect to q on the ProductManifold M using an InverseProductRetraction, which by default encapsulates a inverse retraction for each manifold of the product. Then this method is performed elementwise, so the encapsulated inverse retraction methods have to be available per factor.
source
ManifoldsBase.retract — Method
retract(M::ProductManifold, p, X, m::ProductRetraction)
Compute the retraction from p with tangent vector X on the ProductManifold M using an ProductRetraction, which by default encapsulates retractions of the base manifolds. Then this method is performed elementwise, so the encapsulated retractions method has to be one that is available on the manifolds.
source
ManifoldsBase.sectional_curvature — Method
sectional_curvature(M::ProductManifold, p, X, Y)
Compute the sectional curvature of a manifold $\mathcal M$ at a point $p \in \mathcal M$ on two linearly independent tangent vectors at $p$. It may be 0 for a product of non-flat manifolds if projections of X and Y on subspaces corresponding to component manifolds are not linearly independent.
source
ManifoldsBase.sectional_curvature_max — Method
sectional_curvature_max(M::ProductManifold)
Upper bound on sectional curvature of ProductManifold M. It is the maximum of sectional curvatures of component manifolds and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0) and (0, X_2) is 0.
source
ManifoldsBase.sectional_curvature_min — Method
sectional_curvature_min(M::ProductManifold)
Lower bound on sectional curvature of ProductManifold M. It is the minimum of sectional curvatures of component manifolds and 0 in case there are two or more component manifolds, as the sectional curvature corresponding to the plane spanned by vectors (X_1, 0) and (0, X_2) is 0.
source
ManifoldsBase.select_from_tuple — Method
select_from_tuple(t::NTuple{N, Any}, positions::Val{P})
Selects elements of tuple t at positions specified by the second argument. For example select_from_tuple(("a", "b", "c"), Val((3, 1, 1))) returns ("c", "a", "a").
source
ManifoldsBase.submanifold — Method
submanifold(M::ProductManifold, i::Val)
+submanifold(M::ProductManifold, i::AbstractVector)
Extract the factor of the product manifold M indicated by indices in i. For example, for i equal to Val((1, 3)) the product manifold constructed from the first and the third factor is returned.
The version with AbstractVector is not type-stable, for better preformance use Val.
source
ManifoldsBase.submanifold_component — Method
submanifold_component(M::AbstractManifold, p, i::Integer)
 submanifold_component(M::AbstractManifold, p, ::Val{i}) where {i}
 submanifold_component(p, i::Integer)
-submanifold_component(p, ::Val{i}) where {i}
Project the product array p on M to its ith component. A new array is returned.
source
ManifoldsBase.submanifold_components — Method
submanifold_components(M::AbstractManifold, p)
-submanifold_components(p)
Get the projected components of p on the submanifolds of M. The components are returned in a Tuple.
source
ManifoldsBase.ziptuples — Method
ziptuples(a, b[, c[, d[, e]]])
Zips tuples a, b, and remaining in a fast, type-stable way. If they have different lengths, the result is trimmed to the length of the shorter tuple.
source
Fiber
ManifoldsBase.Fiber — Type
Fiber{𝔽,TFiber<:FiberType,TM<:AbstractManifold{𝔽},TX} <: AbstractManifold{𝔽}
A fiber of a fiber bundle at a point p on the manifold.
This fiber itself is also a manifold. For vector fibers it's by default flat and hence isometric to the Euclidean manifold.
Fields
  • manifold    – base space of the fiber bundle
  • point       – a point $p$ from the base space; the fiber corresponds to the preimage                 by bundle projection $\pi^{-1}(\{p\})$.
Constructor
Fiber(M::AbstractManifold, p, fiber_type::FiberType)
A fiber of type fiber_type at point p from the manifold manifold.
source
ManifoldsBase.VectorSpaceFiber — Type
VectorSpaceFiber{𝔽,M,TSpaceType} = Fiber{𝔽,TSpaceType,M}
-    where {𝔽,M<:AbstractManifold{𝔽},TSpaceType<:VectorSpaceType}
Alias for a Fiber when the fiber is a vector space.
source
Tangent Space
ManifoldsBase.CotangentSpace — Type
CotangentSpace{𝔽,M} = Fiber{𝔽,CotangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}
A manifold for the Cotangent space $T^*_p\mathcal M$ at a point $p\in\mathcal M$. This is modelled as an alias for VectorSpaceFiber corresponding to CotangentSpaceType.
Constructor
CotangentSpace(M::AbstractManifold, p)
Return the manifold (vector space) representing the cotangent space $T^*_p\mathcal M$ at point p, $p\in\mathcal M$.
source
ManifoldsBase.TangentSpace — Type
TangentSpace{𝔽,M} = Fiber{𝔽,TangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}
A manifold for the tangent space $T_p\mathcal M$ at a point $p\in\mathcal M$. This is modelled as an alias for VectorSpaceFiber corresponding to TangentSpaceType.
Constructor
TangentSpace(M::AbstractManifold, p)
Return the manifold (vector space) representing the tangent space $T_p\mathcal M$ at point p, $p\in\mathcal M$.
source
Base.exp — Method
exp(TpM::TangentSpace, X, V)
Exponential map of tangent vectors X from TpM and a direction V, which is also from the TangentSpace TpM since we identify the tangent space of TpM with TpM. The exponential map then simplifies to the sum X+V.
source
Base.log — Method
log(TpM::TangentSpace, X, Y)
Logarithmic map on the TangentSpace TpM, calculated as the difference of tangent vectors q and p from TpM.
source
ManifoldsBase.Weingarten — Method
Y = Weingarten(TpM::TangentSpace, X, V, A)
-Weingarten!(TpM::TangentSpace, Y, p, X, V)
Compute the Weingarten map $\mathcal W_X$ at X on the TangentSpace TpM with respect to the tangent vector $V \in T_p\mathcal M$ and the normal vector $A \in N_p\mathcal M$.
Since this a flat space by itself, the result is always the zero tangent vector.
source
ManifoldsBase.inner — Method
inner(M::TangentSpace, X, V, W)
For any $X ∈ T_p\mathcal M$ we identify the tangent space $T_X(T_p\mathcal M)$ with $T_p\mathcal M$ again. Hence an inner product of $V,W$ is just the inner product of the tangent space itself. $⟨V,W⟩_X = ⟨V,W⟩_p$.
source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(::TangentSpace, X, V, Y)
Transport the tangent vector $Z ∈ T_X(T_p\mathcal M)$ from X to Y. Since we identify $T_X(T_p\mathcal M) = T_p\mathcal M$ and the tangent space is a vector space, parallel transport simplifies to the identity, so this function yields $V$ as a result.
source
ManifoldsBase.project — Method
project(TpM::TangentSpace, X, V)
Project the vector V from the embedding of the tangent space TpM (identified with $T_X(T_p\mathcal M)$), that is project the vector V onto the tangent space at TpM.point.
source
ManifoldsBase.zero_vector — Method
zero_vector(TpM::TangentSpace, X)
Zero tangent vector at point X from the TangentSpace TpM, that is the zero tangent vector at point TpM.point, since we identify the tangent space $T_X(T_p\mathcal M)$ with $T_p\mathcal M$.
source

+submanifold_component(p, ::Val{i}) where {i}

Project the product array p on M to its ith component. A new array is returned.

source
ManifoldsBase.submanifold_components — Method
submanifold_components(M::AbstractManifold, p)
+submanifold_components(p)

Get the projected components of p on the submanifolds of M. The components are returned in a Tuple.

source
ManifoldsBase.ziptuples — Method
ziptuples(a, b[, c[, d[, e]]])

Zips tuples a, b, and remaining in a fast, type-stable way. If they have different lengths, the result is trimmed to the length of the shorter tuple.

source

Fiber

ManifoldsBase.Fiber — Type
Fiber{𝔽,TFiber<:FiberType,TM<:AbstractManifold{𝔽},TX} <: AbstractManifold{𝔽}

A fiber of a fiber bundle at a point p on the manifold.

This fiber itself is also a manifold. For vector fibers it's by default flat and hence isometric to the Euclidean manifold.

Fields

  • manifold – base space of the fiber bundle
  • point – a point $p$ from the base space; the fiber corresponds to the preimage by bundle projection $\pi^{-1}(\{p\})$.

Constructor

Fiber(M::AbstractManifold, p, fiber_type::FiberType)

A fiber of type fiber_type at point p from the manifold manifold.

source
ManifoldsBase.VectorSpaceFiber — Type
VectorSpaceFiber{𝔽,M,TSpaceType} = Fiber{𝔽,TSpaceType,M}
+    where {𝔽,M<:AbstractManifold{𝔽},TSpaceType<:VectorSpaceType}

Alias for a Fiber when the fiber is a vector space.

source

Tangent Space

ManifoldsBase.CotangentSpace — Type
CotangentSpace{𝔽,M} = Fiber{𝔽,CotangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}

A manifold for the Cotangent space $T^*_p\mathcal M$ at a point $p\in\mathcal M$. This is modelled as an alias for VectorSpaceFiber corresponding to CotangentSpaceType.

Constructor

CotangentSpace(M::AbstractManifold, p)

Return the manifold (vector space) representing the cotangent space $T^*_p\mathcal M$ at point p, $p\in\mathcal M$.

source
ManifoldsBase.TangentSpace — Type
TangentSpace{𝔽,M} = Fiber{𝔽,TangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}

A manifold for the tangent space $T_p\mathcal M$ at a point $p\in\mathcal M$. This is modelled as an alias for VectorSpaceFiber corresponding to TangentSpaceType.

Constructor

TangentSpace(M::AbstractManifold, p)

Return the manifold (vector space) representing the tangent space $T_p\mathcal M$ at point p, $p\in\mathcal M$.

source
Base.exp — Method
exp(TpM::TangentSpace, X, V)

Exponential map of tangent vectors X from TpM and a direction V, which is also from the TangentSpace TpM since we identify the tangent space of TpM with TpM. The exponential map then simplifies to the sum X+V.

source
Base.log — Method
log(TpM::TangentSpace, X, Y)

Logarithmic map on the TangentSpace TpM, calculated as the difference of tangent vectors q and p from TpM.

source
ManifoldsBase.Weingarten — Method
Y = Weingarten(TpM::TangentSpace, X, V, A)
+Weingarten!(TpM::TangentSpace, Y, p, X, V)

Compute the Weingarten map $\mathcal W_X$ at X on the TangentSpace TpM with respect to the tangent vector $V \in T_p\mathcal M$ and the normal vector $A \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

source
ManifoldsBase.inner — Method
inner(M::TangentSpace, X, V, W)

For any $X ∈ T_p\mathcal M$ we identify the tangent space $T_X(T_p\mathcal M)$ with $T_p\mathcal M$ again. Hence an inner product of $V,W$ is just the inner product of the tangent space itself. $⟨V,W⟩_X = ⟨V,W⟩_p$.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(::TangentSpace, X, V, Y)

Transport the tangent vector $Z ∈ T_X(T_p\mathcal M)$ from X to Y. Since we identify $T_X(T_p\mathcal M) = T_p\mathcal M$ and the tangent space is a vector space, parallel transport simplifies to the identity, so this function yields $V$ as a result.

source
ManifoldsBase.project — Method
project(TpM::TangentSpace, X, V)

Project the vector V from the embedding of the tangent space TpM (identified with $T_X(T_p\mathcal M)$), that is project the vector V onto the tangent space at TpM.point.

source
ManifoldsBase.zero_vector — Method
zero_vector(TpM::TangentSpace, X)

Zero tangent vector at point X from the TangentSpace TpM, that is the zero tangent vector at point TpM.point, since we identify the tangent space $T_X(T_p\mathcal M)$ with $T_p\mathcal M$.

source
diff --git a/previews/PR217/numerical_verification/index.html b/previews/PR217/numerical_verification/index.html index f5e7e21a..a61e8d01 100644 --- a/previews/PR217/numerical_verification/index.html +++ b/previews/PR217/numerical_verification/index.html @@ -16,7 +16,7 @@ slope_tol::Real = 0.1, error::Symbol = :none, window = nothing, -)

Check numerically wether the inverse retraction inverse_retraction_method is correct. This requires the exp and norm functions to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated,

Keyword arguments

source
ManifoldsBase.check_retraction — Function
check_retraction(
+)

Check numerically wether the inverse retraction inverse_retraction_method is correct. This requires the exp and norm functions to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated,

Keyword arguments

  • exactness_tol: if all errors are below this tolerance, the inverse retraction is considered to be exact
  • io: provide an IO to print the result to
  • limits: specify the limits in the log_range, that is the exponent for the range
  • log_range: specify the range of points (in log scale) to sample the length of the tangent vector X
  • N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
  • name: name to display in the plot
  • plot: whether to plot the result (see plot_slope) The plot is in log-log-scale. This is returned and can then also be saved.
  • second_order: check whether the retraction is of second order. if set to false, first order is checked.
  • slope_tol: tolerance for the slope (global) of the approximation
  • error: specify how to report errors: :none, :info, :warn, or :error are available
  • window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:N.
source
ManifoldsBase.check_retraction — Function
check_retraction(
     M::AbstractManifold,
     rectraction_method::AbstractRetractionMethod,
     p=rand(M),
@@ -33,7 +33,7 @@
     slope_tol::Real = 0.1,
     error::Symbol = :none,
     window = nothing,
-)

Check numerically wether the retraction vector_transport_to is correct, by selecting a set of points $q_i = \exp_p (t_i X)$ where $t$ takes all values from log_range, to then compare parallel_transport_to to the vector_transport_method applied to the vector Y.

This requires the exp, parallel_transport_to and norm function to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated,

Keyword arguments

  • exactness_tol: if all errors are below this tolerance, the retraction is considered to be exact
  • io: provide an IO to print the result to
  • limits: specify the limits in the log_range, that is the exponent for the range
  • log_range: specify the range of points (in log scale) to sample the length of the tangent vector X
  • N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
  • name: name to display in the plot
  • plot: whether to plot the result (if Plots.jl is loaded). The plot is in log-log-scale. This is returned and can then also be saved.
  • second_order: check whether the retraction is of second order. if set to false, first order is checked.
  • slope_tol: tolerance for the slope (global) of the approximation
  • error: specify how to report errors: :none, :info, :warn, or :error are available
  • window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:N.
source
ManifoldsBase.check_vector_transport — Function
check_vector_transport(
+)

Check numerically wether the retraction vector_transport_to is correct, by selecting a set of points $q_i = \exp_p (t_i X)$ where $t$ takes all values from log_range, to then compare parallel_transport_to to the vector_transport_method applied to the vector Y.

This requires the exp, parallel_transport_to and norm function to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated,

Keyword arguments

  • exactness_tol: if all errors are below this tolerance, the retraction is considered to be exact
  • io: provide an IO to print the result to
  • limits: specify the limits in the log_range, that is the exponent for the range
  • log_range: specify the range of points (in log scale) to sample the length of the tangent vector X
  • N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
  • name: name to display in the plot
  • plot: whether to plot the result (if Plots.jl is loaded). The plot is in log-log-scale. This is returned and can then also be saved.
  • second_order: check whether the retraction is of second order. if set to false, first order is checked.
  • slope_tol: tolerance for the slope (global) of the approximation
  • error: specify how to report errors: :none, :info, :warn, or :error are available
  • window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:N.
source
ManifoldsBase.check_vector_transport — Function
check_vector_transport(
     M::AbstractManifold,
     vector_transport_method::AbstractVectorTransportMethod,
     p=rand(M),
@@ -51,11 +51,11 @@
     slope_tol::Real = 0.1,
     error::Symbol = :none,
     window = nothing,
-)

Check numerically wether the retraction vector_transport_to is correct, by selecting a set of points $q_i = \exp_p (t_i X)$ where $t$ takes all values from log_range, to then compare parallel_transport_to to the vector_transport_method applied to the vector Y.

This requires the exp, parallel_transport_to and norm function to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated,

Keyword arguments

  • exactness_tol: if all errors are below this tolerance, the differential is considered to be exact
  • io: provide an IO to print the result to
  • limits: specify the limits in the log_range, that is the exponent for the range
  • log_range: specify the range of points (in log scale) to sample the differential line
  • N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
  • name: name to display in the plot
  • plot: whether to plot the result (if Plots.jl is loaded). The plot is in log-log-scale. This is returned and can then also be saved.
  • second_order: check whether the retraction is of second order. if set to false, first order is checked.
  • slope_tol: tolerance for the slope (global) of the approximation
  • error: specify how to report errors: :none, :info, :warn, or :error are available
  • window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:N.
source

Internal functions

The following functions split the check into several parts, for example looking for the best fitting window and finding out the best slope, or plotting the slope.

ManifoldsBase.find_best_slope_window — Function
(a, b, i, j) = find_best_slope_window(X, Y, window=nothing; slope::Real=2.0, slope_tol::Real=0.1)

Check data X,Y for the largest contiguous interval (window) with a regression line fitting “best”. Among all intervals with a slope within slope_tol to slope the longest one is taken. If no such interval exists, the one with the slope closest to slope is taken.

If the window is set to nothing (default), all window sizes 2,...,length(X) are checked. You can also specify a window size or an array of window sizes.

For each window size, all its translates in the data is checked. For all these (shifted) windows the regression line is computed (with a,b in a + t*b) and the best line is computed.

From the best line the following data is returned

  • a, b specifying the regression line a + t*b
  • i, j determining the window, i.e the regression line stems from data X[i], ..., X[j]
Note

This function has to be implemented using some statistics package. loading Statistics.jl provides a default implementation.

source
ManifoldsBase.plot_slope — Method
plot_slope(x, y;
+)

Check numerically wether the retraction vector_transport_to is correct, by selecting a set of points $q_i = \exp_p (t_i X)$ where $t$ takes all values from log_range, to then compare parallel_transport_to to the vector_transport_method applied to the vector Y.

This requires the exp, parallel_transport_to and norm function to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated,

Keyword arguments

  • exactness_tol: if all errors are below this tolerance, the differential is considered to be exact
  • io: provide an IO to print the result to
  • limits: specify the limits in the log_range, that is the exponent for the range
  • log_range: specify the range of points (in log scale) to sample the differential line
  • N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
  • name: name to display in the plot
  • plot: whether to plot the result (if Plots.jl is loaded). The plot is in log-log-scale. This is returned and can then also be saved.
  • second_order: check whether the retraction is of second order. if set to false, first order is checked.
  • slope_tol: tolerance for the slope (global) of the approximation
  • error: specify how to report errors: :none, :info, :warn, or :error are available
  • window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:N.
source

Internal functions

The following functions split the check into several parts, for example looking for the best fitting window and finding out the best slope, or plotting the slope.

ManifoldsBase.find_best_slope_window — Function
(a, b, i, j) = find_best_slope_window(X, Y, window=nothing; slope::Real=2.0, slope_tol::Real=0.1)

Check data X,Y for the largest contiguous interval (window) with a regression line fitting “best”. Among all intervals with a slope within slope_tol to slope the longest one is taken. If no such interval exists, the one with the slope closest to slope is taken.

If the window is set to nothing (default), all window sizes 2,...,length(X) are checked. You can also specify a window size or an array of window sizes.

For each window size, all its translates in the data is checked. For all these (shifted) windows the regression line is computed (with a,b in a + t*b) and the best line is computed.

From the best line the following data is returned

  • a, b specifying the regression line a + t*b
  • i, j determining the window, i.e the regression line stems from data X[i], ..., X[j]
Note

This function has to be implemented using some statistics package. loading Statistics.jl provides a default implementation.

source
ManifoldsBase.plot_slope — Method
plot_slope(x, y;
     slope=2,
     line_base=0,
     a=0,
     b=2.0,
     i=1,
     j=length(x)
-)

Plot the result from the verification functions on data x,y with two comparison lines

  1. line_base + tslope as the global slope(s) the plot could have
  2. a + b*t on the interval [x[i], x[j]] for some (best fitting) comparison slope
Note

This function has to be implemented for a certain plotting package. loading Plots.jl provides a default implementation.

source
+)

Plot the result from the verification functions on data x,y with two comparison lines

  1. line_base + tslope as the global slope(s) the plot could have
  2. a + b*t on the interval [x[i], x[j]] for some (best fitting) comparison slope
Note

This function has to be implemented for a certain plotting package. loading Plots.jl provides a default implementation.

source diff --git a/previews/PR217/projections/index.html b/previews/PR217/projections/index.html index e6ad73a1..8d8c2330 100644 --- a/previews/PR217/projections/index.html +++ b/previews/PR217/projections/index.html @@ -1,2 +1,2 @@ -Projections · ManifoldsBase.jl
GitHub

Projections

A manifold might be embedded in some space. Often this is implicitly assumed, for example the complex Circle is embedded in the complex plane. Let‘s keep the circle in mind in the following as a simple example. For the general case of explicitly stating an embedding and/or to distinguish several, different embeddings, see Embedded Manifolds below.

To make this a little more concrete, let‘s assume we have a manifold $\mathcal M$ which is embedded in some manifold $\mathcal N$ and the image $i(\mathcal M)$ of the embedding function $i$ is a closed set (with respect to the topology on $\mathcal N$). Then we can do two kinds of projections.

To make this concrete in an example for the Circle $\mathcal M=\mathcal C := \{ p ∈ ℂ | |p| = 1\}$ the embedding can be chosen to be the manifold $\mathcal N = ℂ$ and due to our representation of $\mathcal C$ as complex numbers already, we have $i(p) = p$, that is the identity as the embedding function.

The first projection we can consider is for a given a point $p∈\mathcal N$ in the embedding we can look for the closest point on the manifold $\mathcal M$, i.e.

\[ \operatorname*{arg\,min}_{q∈ \mathcal M}\ d_{\mathcal N}(i(q),p)\]

And this resulting $q$ we call the projection of $p$ onto the manifold $\mathcal M$.

The second projection we can look at is for a given a point $p∈\mathcal M$ and a vector in $X∈ T_{i(p)}\mathcal N$ in the embedding, where we can similarly look for the closest tangent vector $Y∈ T_p\mathcal M$, which we have to embed itself before itself. Embedding a tangent vector is usually the same as using the pushforward $\mathrm{d}i_p$ of the embedding (at $p$). We obtain

\[ \operatorname*{arg\,min}_{Y∈ T_p\mathcal M}\ \bigl\lVert \mathrm{d}i(p)[Y] - X \bigr\rVert_{i(p)}\]

And we call the resulting $Y$ the projection of $X$ onto the tangent space $T_p\mathcal M$ at $p$.

Let‘s look at the little more concrete example of the complex circle again. Here, the closest point of $p ∈ ℂ$ is just the projection onto the circle, or in other words $q = \frac{p}{\lvert p \rvert}$, as long as $p\neq 0$. For $p=0$ the projection is not defined. A tangent space $T_p\mathcal C$ in the embedding is the line through the origin that is orthogonal to a point $p∈\mathcal C$. This can be better visualized by looking at $p+T_p\mathcal C$ which is actually the line tangent to $p$ on the unit circle. Note that this shift does not change the resulting projection relative to the origin of the tangent space.

Here the projection can be computed as the classical projection onto the line, i.e. $Y = X - ⟨X,p⟩X$.

Both projections onto $\mathcal C$ and onto $T_p\mathcal C$ are illustrated in the following figure.

An example illustrating the two kinds of projections on the Circle.

The functions provided in this interface are the following.

ManifoldsBase.project! — Method
project!(M::AbstractManifold, Y, p, X)

Project ambient space representation of a vector X to a tangent vector at point p on the AbstractManifold M. The result is saved in vector Y. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, project! includes changing data representation, if applicable, i.e. if the tangents on M are not represented in the same way as points on the embedding, the representation is changed accordingly. This is the case for example for Lie groups, when tangent vectors are represented in the Lie algebra. after projection the change to the Lie algebra is perfomed, too.

See also: EmbeddedManifold, embed!

source
ManifoldsBase.project! — Method
project!(M::AbstractManifold, q, p)

Project point p from the ambient space onto the AbstractManifold M. The result is storedin q. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, the projection includes changing data representation, if applicable, i.e. if the points on M are not represented in the same array data, the data is changed accordingly.

See also: EmbeddedManifold, embed!

source
ManifoldsBase.project — Method
project(M::AbstractManifold, p, X)

Project ambient space representation of a vector X to a tangent vector at point p on the AbstractManifold M. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, project includes changing data representation, if applicable, i.e. if the tangents on M are not represented in the same way as points on the embedding, the representation is changed accordingly. This is the case for example for Lie groups, when tangent vectors are represented in the Lie algebra. after projection the change to the Lie algebra is perfomed, too.

See also: EmbeddedManifold, embed

source
ManifoldsBase.project — Method
project(M::AbstractManifold, p)

Project point p from the ambient space of the AbstractManifold M to M. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, the projection includes changing data representation, if applicable, i.e. if the points on M are not represented in the same array data, the data is changed accordingly.

See also: EmbeddedManifold, embed

source
+Projections · ManifoldsBase.jl
GitHub

Projections

A manifold might be embedded in some space. Often this is implicitly assumed, for example the complex Circle is embedded in the complex plane. Let‘s keep the circle in mind in the following as a simple example. For the general case of explicitly stating an embedding and/or to distinguish several, different embeddings, see Embedded Manifolds below.

To make this a little more concrete, let‘s assume we have a manifold $\mathcal M$ which is embedded in some manifold $\mathcal N$ and the image $i(\mathcal M)$ of the embedding function $i$ is a closed set (with respect to the topology on $\mathcal N$). Then we can do two kinds of projections.

To make this concrete in an example for the Circle $\mathcal M=\mathcal C := \{ p ∈ ℂ | |p| = 1\}$ the embedding can be chosen to be the manifold $\mathcal N = ℂ$ and due to our representation of $\mathcal C$ as complex numbers already, we have $i(p) = p$, that is the identity as the embedding function.

The first projection we can consider is for a given a point $p∈\mathcal N$ in the embedding we can look for the closest point on the manifold $\mathcal M$, i.e.

\[ \operatorname*{arg\,min}_{q∈ \mathcal M}\ d_{\mathcal N}(i(q),p)\]

And this resulting $q$ we call the projection of $p$ onto the manifold $\mathcal M$.

The second projection we can look at is for a given a point $p∈\mathcal M$ and a vector in $X∈ T_{i(p)}\mathcal N$ in the embedding, where we can similarly look for the closest tangent vector $Y∈ T_p\mathcal M$, which we have to embed itself before itself. Embedding a tangent vector is usually the same as using the pushforward $\mathrm{d}i_p$ of the embedding (at $p$). We obtain

\[ \operatorname*{arg\,min}_{Y∈ T_p\mathcal M}\ \bigl\lVert \mathrm{d}i(p)[Y] - X \bigr\rVert_{i(p)}\]

And we call the resulting $Y$ the projection of $X$ onto the tangent space $T_p\mathcal M$ at $p$.

Let‘s look at the little more concrete example of the complex circle again. Here, the closest point of $p ∈ ℂ$ is just the projection onto the circle, or in other words $q = \frac{p}{\lvert p \rvert}$, as long as $p\neq 0$. For $p=0$ the projection is not defined. A tangent space $T_p\mathcal C$ in the embedding is the line through the origin that is orthogonal to a point $p∈\mathcal C$. This can be better visualized by looking at $p+T_p\mathcal C$ which is actually the line tangent to $p$ on the unit circle. Note that this shift does not change the resulting projection relative to the origin of the tangent space.

Here the projection can be computed as the classical projection onto the line, i.e. $Y = X - ⟨X,p⟩X$.

Both projections onto $\mathcal C$ and onto $T_p\mathcal C$ are illustrated in the following figure.

An example illustrating the two kinds of projections on the Circle.

The functions provided in this interface are the following.

ManifoldsBase.project! — Method
project!(M::AbstractManifold, Y, p, X)

Project ambient space representation of a vector X to a tangent vector at point p on the AbstractManifold M. The result is saved in vector Y. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, project! includes changing data representation, if applicable, i.e. if the tangents on M are not represented in the same way as points on the embedding, the representation is changed accordingly. This is the case for example for Lie groups, when tangent vectors are represented in the Lie algebra. after projection the change to the Lie algebra is perfomed, too.

See also: EmbeddedManifold, embed!

source
ManifoldsBase.project! — Method
project!(M::AbstractManifold, q, p)

Project point p from the ambient space onto the AbstractManifold M. The result is storedin q. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, the projection includes changing data representation, if applicable, i.e. if the points on M are not represented in the same array data, the data is changed accordingly.

See also: EmbeddedManifold, embed!

source
ManifoldsBase.project — Method
project(M::AbstractManifold, p, X)

Project ambient space representation of a vector X to a tangent vector at point p on the AbstractManifold M. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, project includes changing data representation, if applicable, i.e. if the tangents on M are not represented in the same way as points on the embedding, the representation is changed accordingly. This is the case for example for Lie groups, when tangent vectors are represented in the Lie algebra. after projection the change to the Lie algebra is perfomed, too.

See also: EmbeddedManifold, embed

source
ManifoldsBase.project — Method
project(M::AbstractManifold, p)

Project point p from the ambient space of the AbstractManifold M to M. This method is only available for manifolds where implicitly an embedding or ambient space is given. Additionally, the projection includes changing data representation, if applicable, i.e. if the points on M are not represented in the same array data, the data is changed accordingly.

See also: EmbeddedManifold, embed

source
diff --git a/previews/PR217/references/index.html b/previews/PR217/references/index.html index 8e119c74..4b30d3e6 100644 --- a/previews/PR217/references/index.html +++ b/previews/PR217/references/index.html @@ -1,2 +1,2 @@ -References · ManifoldsBase.jl
GitHub

Literature

[AMS08]
P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
[Bou23]
[EPS72]
J. Ehlers, F. A. Pirani and A. Schild. Republication of: The geometry of free fall and light propagation. General Relativity and Gravitation 44, 1587–1609 (1972).
[LP13]
M. Lorenzi and X. Pennec. Efficient Parallel Transport of Deformations in Time Series of Images: From Schild's to Pole Ladder. Journal of Mathematical Imaging and Vision 50, 5–17 (2013), arXiv:00870489.
[MF12]
P. Muralidharan and P. T. Fletcher. Sasaki metrics for analysis of longitudinal data on manifolds. In: 2012 IEEE Conference on Computer Vision and Pattern Recognition (2012).
[Pen18]
[SI13]
H. Sato and T. Iwai. A new, globally convergent Riemannian conjugate gradient method. Optimization 64, 1011–1031 (2013), arXiv:1302.0125.
+References · ManifoldsBase.jl
GitHub

Literature

[AMS08]
P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
[Bou23]
[EPS72]
J. Ehlers, F. A. Pirani and A. Schild. Republication of: The geometry of free fall and light propagation. General Relativity and Gravitation 44, 1587–1609 (1972).
[LP13]
M. Lorenzi and X. Pennec. Efficient Parallel Transport of Deformations in Time Series of Images: From Schild's to Pole Ladder. Journal of Mathematical Imaging and Vision 50, 5–17 (2013), arXiv:00870489.
[MF12]
P. Muralidharan and P. T. Fletcher. Sasaki metrics for analysis of longitudinal data on manifolds. In: 2012 IEEE Conference on Computer Vision and Pattern Recognition (2012).
[Pen18]
[SI13]
H. Sato and T. Iwai. A new, globally convergent Riemannian conjugate gradient method. Optimization 64, 1011–1031 (2013), arXiv:1302.0125.
diff --git a/previews/PR217/retractions/index.html b/previews/PR217/retractions/index.html index 83a1d8de..f8350720 100644 --- a/previews/PR217/retractions/index.html +++ b/previews/PR217/retractions/index.html @@ -1,18 +1,18 @@ Retractions · ManifoldsBase.jl
GitHub

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∈\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∈ 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.default_inverse_retraction_method — Method
default_inverse_retraction_method(M::AbstractManifold)
-default_inverse_retraction_method(M::AbstractManifold, ::Type{T}) where {T}

The AbstractInverseRetractionMethod that is used when calling inverse_retract without specifying the inverse retraction method. By default, this is the LogarithmicInverseRetraction.

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 inverse retraction methods.

source
ManifoldsBase.default_retraction_method — Method
default_retraction_method(M::AbstractManifold)
-default_retraction_method(M::AbstractManifold, ::Type{T}) where {T}

The AbstractRetractionMethod that is used when calling retract without specifying the retraction method. By default, this is the ExponentialRetraction.

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 retraction methods.

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

source
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!.

source
ManifoldsBase.retract — Function
retract(M::AbstractManifold, p, X, method::AbstractRetractionMethod=default_retraction_method(M, typeof(p)))
-retract(M::AbstractManifold, p, X, t::Number=1, method::AbstractRetractionMethod=default_retraction_method(M, typeof(p)))

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.

source
ManifoldsBase.retract! — Function
retract!(M::AbstractManifold, q, p, X)
+default_inverse_retraction_method(M::AbstractManifold, ::Type{T}) where {T}

The AbstractInverseRetractionMethod that is used when calling inverse_retract without specifying the inverse retraction method. By default, this is the LogarithmicInverseRetraction.

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 inverse retraction methods.

source
ManifoldsBase.default_retraction_method — Method
default_retraction_method(M::AbstractManifold)
+default_retraction_method(M::AbstractManifold, ::Type{T}) where {T}

The AbstractRetractionMethod that is used when calling retract without specifying the retraction method. By default, this is the ExponentialRetraction.

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 retraction methods.

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

source
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!.

source
ManifoldsBase.retract — Function
retract(M::AbstractManifold, p, X, method::AbstractRetractionMethod=default_retraction_method(M, typeof(p)))
+retract(M::AbstractManifold, p, X, t::Number=1, method::AbstractRetractionMethod=default_retraction_method(M, typeof(p)))

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.

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

source

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.

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

source
ManifoldsBase.InverseRetractionWithKeywords — Type
InverseRetractionWithKeywords{R<:AbstractRetractionMethod,K} <: AbstractInverseRetractionMethod

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

Fields

  • inverse_retraction the inverse retraction 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

InverseRetractionWithKeywords(m::T; kwargs...) where {T <: AbstractInverseRetractionMethod}

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

source
ManifoldsBase.NLSolveInverseRetraction — Type
NLSolveInverseRetraction{T<:AbstractRetractionMethod,TV,TK} <:
+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.

source

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.

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

source
ManifoldsBase.InverseRetractionWithKeywords — Type
InverseRetractionWithKeywords{R<:AbstractRetractionMethod,K} <: AbstractInverseRetractionMethod

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

Fields

  • inverse_retraction the inverse retraction 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

InverseRetractionWithKeywords(m::T; kwargs...) where {T <: AbstractInverseRetractionMethod}

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

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

source
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(
+)

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.

source
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).

source
ManifoldsBase.PadeInverseRetraction — Type
PadeInverseRetraction{m} <: AbstractInverseRetractionMethod

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

Technical Note

Though you would call e.g. inverse_retract(M, p, q, PadeInverseRetraction(m)), to implement an inverse Padé retraction, define inverse_retract_pade!(M, X, p, q, m) for your manifold M.

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

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

Constructor

PadeRetraction(m::Int)
Technical Note

Though you would call e.g. retract(M, p, X, PadeRetraction(m)), to implement a Padé retraction, define retract_pade!(M, q, p, X, t, m) for your manifold M.

source
ManifoldsBase.PolarRetraction — Type
PolarRetraction <: AbstractRetractionMethod

Retractions that are based on singular value decompositions of the matrix / matrices for point and tangent vectors.

Technical Note

Though you would call e.g. retract(M, p, X, PolarRetraction()), to implement a polar retraction, define retract_polar!(M, q, p, X, t) for your manifold M.

source
ManifoldsBase.ProjectionRetraction — Type
ProjectionRetraction <: AbstractRetractionMethod

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

Technical Note

Though you would call e.g. retract(M, p, X, ProjectionRetraction()), to implement a projection retraction, define retract_project!(M, q, p, X, t) for your manifold M.

source
ManifoldsBase.QRRetraction — Type
QRRetraction <: AbstractRetractionMethod

Retractions that are based on a QR decomposition of the matrix / matrices for point and tangent vector on a AbstractManifold

Technical Note

Though you would call e.g. retract(M, p, X, QRRetraction()), to implement a QR retraction, define retract_qr!(M, q, p, X, t) for your manifold M.

source
ManifoldsBase.RetractionWithKeywords — Type
RetractionWithKeywords{R<:AbstractRetractionMethod,K} <: AbstractRetractionMethod

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

Fields

  • retraction the retraction 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

RetractionWithKeywords(m::T; kwargs...) where {T <: AbstractRetractionMethod}

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

source
ManifoldsBase.SasakiRetraction — Type
struct SasakiRetraction <: AbstractRetractionMethod end

Exponential map on TangentBundle computed via Euler integration as described in [MF12]. The system of equations for $\gamma : ℝ \to T\mathcal M$ such that $\gamma(1) = \exp_{p,X}(X_M, X_F)$ and $\gamma(0)=(p, X)$ reads

\[\dot{\gamma}(t) = (\dot{p}(t), \dot{X}(t)) = (R(X(t), \dot{X}(t))\dot{p}(t), 0)\]

where $R$ is the Riemann curvature tensor (see riemann_tensor).

Constructor

SasakiRetraction(L::Int)

In this constructor L is the number of integration steps.

source
ManifoldsBase.SoftmaxRetraction — Type
SoftmaxRetraction <: AbstractRetractionMethod

Describes a retraction that is based on the softmax function.

Technical Note

Though you would call e.g. retract(M, p, X, SoftmaxRetraction()), to implement a softmax retraction, define retract_softmax!(M, q, p, X, t) for your manifold M.

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

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.

+)

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

source
ManifoldsBase.PadeInverseRetraction — Type
PadeInverseRetraction{m} <: AbstractInverseRetractionMethod

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

Technical Note

Though you would call e.g. inverse_retract(M, p, q, PadeInverseRetraction(m)), to implement an inverse Padé retraction, define inverse_retract_pade!(M, X, p, q, m) for your manifold M.

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

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

Constructor

PadeRetraction(m::Int)
Technical Note

Though you would call e.g. retract(M, p, X, PadeRetraction(m)), to implement a Padé retraction, define retract_pade!(M, q, p, X, t, m) for your manifold M.

source
ManifoldsBase.PolarInverseRetraction — Type
PolarInverseRetraction <: AbstractInverseRetractionMethod

Inverse retractions that are based on a singular value decomposition of the matrix / matrices for point and tangent vector on a AbstractManifold

Technical Note

Though you would call e.g. inverse_retract(M, p, q, PolarInverseRetraction()), to implement an inverse polar retraction, define inverse_retract_polar!(M, X, p, q) for your manifold M.

source
ManifoldsBase.PolarRetraction — Type
PolarRetraction <: AbstractRetractionMethod

Retractions that are based on singular value decompositions of the matrix / matrices for point and tangent vectors.

Technical Note

Though you would call e.g. retract(M, p, X, PolarRetraction()), to implement a polar retraction, define retract_polar!(M, q, p, X, t) for your manifold M.

source
ManifoldsBase.ProjectionInverseRetraction — Type
ProjectionInverseRetraction <: AbstractInverseRetractionMethod

Inverse retractions that are based on a projection (or its inversion).

Technical Note

Though you would call e.g. inverse_retract(M, p, q, ProjectionInverseRetraction()), to implement an inverse projection retraction, define inverse_retract_project!(M, X, p, q) for your manifold M.

source
ManifoldsBase.ProjectionRetraction — Type
ProjectionRetraction <: AbstractRetractionMethod

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

Technical Note

Though you would call e.g. retract(M, p, X, ProjectionRetraction()), to implement a projection retraction, define retract_project!(M, q, p, X, t) for your manifold M.

source
ManifoldsBase.QRInverseRetraction — Type
QRInverseRetraction <: AbstractInverseRetractionMethod

Inverse retractions that are based on a QR decomposition of the matrix / matrices for point and tangent vector on a AbstractManifold

Technical Note

Though you would call e.g. inverse_retract(M, p, q, QRInverseRetraction()), to implement an inverse QR retraction, define inverse_retract_qr!(M, X, p, q) for your manifold M.

source
ManifoldsBase.QRRetraction — Type
QRRetraction <: AbstractRetractionMethod

Retractions that are based on a QR decomposition of the matrix / matrices for point and tangent vector on a AbstractManifold

Technical Note

Though you would call e.g. retract(M, p, X, QRRetraction()), to implement a QR retraction, define retract_qr!(M, q, p, X, t) for your manifold M.

source
ManifoldsBase.RetractionWithKeywords — Type
RetractionWithKeywords{R<:AbstractRetractionMethod,K} <: AbstractRetractionMethod

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

Fields

  • retraction the retraction 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

RetractionWithKeywords(m::T; kwargs...) where {T <: AbstractRetractionMethod}

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

source
ManifoldsBase.SasakiRetraction — Type
struct SasakiRetraction <: AbstractRetractionMethod end

Exponential map on TangentBundle computed via Euler integration as described in [MF12]. The system of equations for $\gamma : ℝ \to T\mathcal M$ such that $\gamma(1) = \exp_{p,X}(X_M, X_F)$ and $\gamma(0)=(p, X)$ reads

\[\dot{\gamma}(t) = (\dot{p}(t), \dot{X}(t)) = (R(X(t), \dot{X}(t))\dot{p}(t), 0)\]

where $R$ is the Riemann curvature tensor (see riemann_tensor).

Constructor

SasakiRetraction(L::Int)

In this constructor L is the number of integration steps.

source
ManifoldsBase.SoftmaxInverseRetraction — Type
SoftmaxInverseRetraction <: AbstractInverseRetractionMethod

Describes an inverse retraction that is based on the softmax function.

Technical Note

Though you would call e.g. inverse_retract(M, p, q, SoftmaxInverseRetraction()), to implement an inverse softmax retraction, define inverse_retract_softmax!(M, X, p, q) for your manifold M.

source
ManifoldsBase.SoftmaxRetraction — Type
SoftmaxRetraction <: AbstractRetractionMethod

Describes a retraction that is based on the softmax function.

Technical Note

Though you would call e.g. retract(M, p, X, SoftmaxRetraction()), to implement a softmax retraction, define retract_softmax!(M, q, p, X, t) for your manifold M.

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

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_cayley! — Method
inverse_retract_cayley!(M::AbstractManifold, X, p, q)

Compute the in-place variant of the CayleyInverseRetraction, which by default calls the first order [PadeInverseRetraction§(@ref).

source
ManifoldsBase.inverse_retract_embedded! — Method
inverse_retract_embedded!(M::AbstractManifold, X, p, q, m::AbstractInverseRetractionMethod)

Compute the in-place variant of the EmbeddedInverseRetraction using the AbstractInverseRetractionMethod m in the embedding (see get_embedding) and projecting the result back.

source
ManifoldsBase.inverse_retract_nlsolve! — Method
inverse_retract_nlsolve!(M::AbstractManifold, X, p, q, m::NLSolveInverseRetraction)

Compute the in-place variant of the NLSolveInverseRetraction m.

source
ManifoldsBase.inverse_retract_pade! — Method
inverse_retract_pade!(M::AbstractManifold, p, q, n)

Compute the in-place variant of the PadeInverseRetraction(n),

source
ManifoldsBase.inverse_retract_polar! — Method
inverse_retract_polar!(M::AbstractManifold, X, p, q)

Compute the in-place variant of the PolarInverseRetraction.

source
ManifoldsBase.inverse_retract_project! — Method
inverse_retract_project!(M::AbstractManifold, X, p, q)

Compute the in-place variant of the ProjectionInverseRetraction.

source
ManifoldsBase.inverse_retract_qr! — Method
inverse_retract_qr!(M::AbstractManifold, X, p, q)

Compute the in-place variant of the QRInverseRetraction.

source
ManifoldsBase.inverse_retract_softmax! — Method
inverse_retract_softmax!(M::AbstractManifold, X, p, q)

Compute the in-place variant of the SoftmaxInverseRetraction.

source
ManifoldsBase.retract_cayley! — Method
retract_cayley!(M::AbstractManifold, q, p, X, t)

Compute the in-place variant of the CayleyRetraction, which by default falls back to calling the first order PadeRetraction.

source
ManifoldsBase.retract_embedded! — Method
retract_embedded!(M::AbstractManifold, q, p, X, t, m::AbstractRetractionMethod)

Compute the in-place variant of the EmbeddedRetraction using the AbstractRetractionMethod m in the embedding (see get_embedding) and projecting the result back.

source
ManifoldsBase.retract_exp_ode! — Method
retract_exp_ode!(M::AbstractManifold, q, p, X, t, m::AbstractRetractionMethod, B::AbstractBasis)

Compute the in-place variant of the ODEExponentialRetraction(m, B).

source
ManifoldsBase.retract_pade! — Method
retract_pade!(M::AbstractManifold, q, p, X, t, m::PadeRetraction)

Compute the in-place variant of the PadeRetraction m.

source
ManifoldsBase.retract_polar! — Method
retract_polar!(M::AbstractManifold, q, p, X, t)

Compute the in-place variant of the PolarRetraction.

source
ManifoldsBase.retract_project! — Method
retract_project!(M::AbstractManifold, q, p, X, t)

Compute the in-place variant of the ProjectionRetraction.

source
ManifoldsBase.retract_qr! — Method
retract_qr!(M::AbstractManifold, q, p, X, t)

Compute the in-place variant of the QRRetraction.

source
ManifoldsBase.retract_sasaki! — Method
retract_sasaki!(M::AbstractManifold, q, p, X, t::Number, m::SasakiRetraction)

Compute the in-place variant of the SasakiRetraction m.

source
ManifoldsBase.retract_softmax! — Method
retract_softmax!(M::AbstractManifold, q, p, X, t)

Compute the in-place variant of the SoftmaxRetraction.

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

Approximate the inverse of a retraction using the shooting method.

source
diff --git a/previews/PR217/tutorials/implement-a-manifold/index.html b/previews/PR217/tutorials/implement-a-manifold/index.html index 6a15a223..3a3317da 100644 --- a/previews/PR217/tutorials/implement-a-manifold/index.html +++ b/previews/PR217/tutorials/implement-a-manifold/index.html @@ -103,4 +103,4 @@ default_retraction_method(::ScaledSphere) = ProjectionRetraction()
default_retraction_method (generic function with 6 methods)

Then

default_retraction_method(M)
ProjectionRetraction()

and retract without a method specified would always fall back to using the projection retraction instead of the exponential map. Note that for compatibilty there is the AbstractRetractionMethod called ExponentialRetraction which makes retract fall back to calling exp.

Technical Details

This notebook was rendered with the following environment

Pkg.status()
Status `~/work/ManifoldsBase.jl/ManifoldsBase.jl/tutorials/Project.toml`
   [7073ff75] IJulia v1.26.0
   [3362f125] ManifoldsBase v0.15.22 `~/work/ManifoldsBase.jl/ManifoldsBase.jl`
-  [91a5bcdd] Plots v1.40.9
+ [91a5bcdd] Plots v1.40.9 diff --git a/previews/PR217/types/index.html b/previews/PR217/types/index.html index 91829bb7..a6086fab 100644 --- a/previews/PR217/types/index.html +++ b/previews/PR217/types/index.html @@ -1,5 +1,5 @@ -An abstract manifold · ManifoldsBase.jl
GitHub

The Manifold interface

The AbstractManifold

The main type is the AbstractManifold. It represents the manifold per se. Throughout the documentation of ManifoldsBase.jl we might use the Euclidean Space and the Sphere (both implemented in Manifolds.jl) as easy examples to illustrate properties and features of this interface on concrete examples.

ManifoldsBase.AbstractManifold — Type
AbstractManifold{𝔽}

A type to represent a (Riemannian) manifold. The AbstractManifold is a central type of this interface. It allows to distinguish different implementations of functions like the exponential and logarithmic map for different manifolds. Usually, the manifold is the first parameter in any of these functions within ManifoldsBase.jl. Based on these, say “elementary” functions, as the two mentioned above, more general functions are built, for example the shortest_geodesic and the geodesic. These should only be overwritten (reimplemented) if for a certain manifold specific, more efficient implementations are possible, that do not just call the elementary functions.

The [AbstractManifold] is parametrized by AbstractNumbers to distinguish for example real (ℝ) and complex (ℂ) manifolds.

For subtypes the preferred order of parameters is: size and simple value parameters, followed by the AbstractNumbers field, followed by data type parameters, which might depend on the abstract number field type.

source

which should store information about the manifold, for example parameters inherent to the manifold.

Points on a manifold

Points do not necessarily have to be typed. Usually one can just use any type. When a manifold has multiple representations, these should be distinguished by point and vector types.

ManifoldsBase.AbstractManifoldPoint — Type
AbstractManifoldPoint

Type for a point on a manifold. While an AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used either

  • for more complicated representations,
  • semantic verification, or
  • when dispatching on different representations of points on a manifold.

Since semantic verification and different representations usually might still only store a matrix internally, it is possible to use @manifold_element_forwards and @default_manifold_fallbacks to reduce implementation overhead.

source

Converting points between different representations can be performed using the convert function with either two or three arguments (convert(T, M, p) or convert(T, p)). For some manifolds providing M may be necessary. The first variant falls back to the second variant.

Tangent and Cotangent spaces

ManifoldsBase.AbstractFibreVector — Type
AbstractFibreVector{TType<:VectorSpaceType}

Type for a vector from a vector space (fibre of a vector bundle) of type TType of a manifold. While a AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used for more complicated representations, semantic verification, or even dispatch for different representations of tangent vectors and their types on a manifold.

You may use macro @manifold_vector_forwards to introduce commonly used method definitions for your subtype of AbstractFibreVector.

source
ManifoldsBase.CoTVector — Type
CoTVector = AbstractFibreVector{CotangentSpaceType}

Type for a cotangent vector of a manifold. While a AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used for more complicated representations, semantic verification, or even dispatch for different representations of cotangent vectors and their types on a manifold.

source
ManifoldsBase.FVector — Type
FVector(type::VectorSpaceType, data, basis::AbstractBasis)

Decorator indicating that the vector data contains coordinates of a vector from a fiber of a vector bundle of type type. basis is an object describing the basis of that space in which the coordinates are given.

Conversion between FVector representation and the default representation of an object (for example a tangent vector) for a manifold should be done using get_coordinates and get_vector.

Examples

julia> using Manifolds
+An abstract manifold · ManifoldsBase.jl
GitHub
The Manifold interface
The AbstractManifold
The main type is the AbstractManifold. It represents the manifold per se. Throughout the documentation of ManifoldsBase.jl we might use the Euclidean Space and the Sphere (both implemented in Manifolds.jl) as easy examples to illustrate properties and features of this interface on concrete examples.
ManifoldsBase.AbstractManifold — Type
AbstractManifold{𝔽}
A type to represent a (Riemannian) manifold. The AbstractManifold is a central type of this interface. It allows to distinguish different implementations of functions like the exponential and logarithmic map for different manifolds. Usually, the manifold is the first parameter in any of these functions within ManifoldsBase.jl. Based on these, say “elementary” functions, as the two mentioned above, more general functions are built, for example the shortest_geodesic and the geodesic. These should only be overwritten (reimplemented) if for a certain manifold specific, more efficient implementations are possible, that do not just call the elementary functions.
The [AbstractManifold] is parametrized by AbstractNumbers to distinguish for example real (ℝ) and complex (ℂ) manifolds.
For subtypes the preferred order of parameters is: size and simple value parameters, followed by the AbstractNumbers field, followed by data type parameters, which might depend on the abstract number field type.
source
which should store information about the manifold, for example parameters inherent to the manifold.
Points on a manifold
Points do not necessarily have to be typed. Usually one can just use any type. When a manifold has multiple representations, these should be distinguished by point and vector types.
ManifoldsBase.AbstractManifoldPoint — Type
AbstractManifoldPoint
Type for a point on a manifold. While an AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used either
  • for more complicated representations,
  • semantic verification, or
  • when dispatching on different representations of points on a manifold.
Since semantic verification and different representations usually might still only store a matrix internally, it is possible to use @manifold_element_forwards and @default_manifold_fallbacks to reduce implementation overhead.
source
Converting points between different representations can be performed using the convert function with either two or three arguments (convert(T, M, p) or convert(T, p)). For some manifolds providing M may be necessary. The first variant falls back to the second variant.
Tangent and Cotangent spaces
ManifoldsBase.AbstractFibreVector — Type
AbstractFibreVector{TType<:VectorSpaceType}
Type for a vector from a vector space (fibre of a vector bundle) of type TType of a manifold. While a AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used for more complicated representations, semantic verification, or even dispatch for different representations of tangent vectors and their types on a manifold.
You may use macro @manifold_vector_forwards to introduce commonly used method definitions for your subtype of AbstractFibreVector.
source
ManifoldsBase.CoTVector — Type
CoTVector = AbstractFibreVector{CotangentSpaceType}
Type for a cotangent vector of a manifold. While a AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used for more complicated representations, semantic verification, or even dispatch for different representations of cotangent vectors and their types on a manifold.
source
ManifoldsBase.FVector — Type
FVector(type::VectorSpaceType, data, basis::AbstractBasis)
Decorator indicating that the vector data contains coordinates of a vector from a fiber of a vector bundle of type type. basis is an object describing the basis of that space in which the coordinates are given.
Conversion between FVector representation and the default representation of an object (for example a tangent vector) for a manifold should be done using get_coordinates and get_vector.
Examples
julia> using Manifolds
 
 julia> M = Sphere(2)
 Sphere(2, ℝ)
@@ -26,9 +26,9 @@
 3-element Vector{Float64}:
  -0.0
   2.0
- -1.0
source
ManifoldsBase.TVector — Type
TVector = AbstractFibreVector{TangentSpaceType}
Type for a tangent vector of a manifold. While a AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used for more complicated representations, semantic verification, or even dispatch for different representations of tangent vectors and their types on a manifold.
source
This interface also covers a large variety how to model bases in tangent spaces.
Converting tangent vectors between different representations can be performed using the convert function with either three or four arguments (convert(T, M, p, X) or convert(T, p, X)). For some manifolds providing M may be necessary. The first variant falls back to the second variant.
Macros for automatic forwards for simple points/tangent vectors
When distinguishing different representations of points or tangent vectors on one manifold, it might happen that both a subtype of AbstractManifoldPoint and a subtype of TVector are just encapsulating a value
This is taken into account by the following macros, that forward several actions just to this field. Most prominently vector operations for the tangent vectors. If there is still a default case, a macro sets this type to be equivalent to calling the manifold functions just with the types field that carries the value.
ManifoldsBase.@default_manifold_fallbacks — Macro
default_manifold_fallbacks(TM, TP, TV, pfield::Symbol, vfield::Symbol)
Introduce default fallbacks for all basic functions on manifolds, for manifold of type TM, points of type TP, tangent vectors of type TV, with forwarding to fields pfield and vfield for point and tangent vector functions, respectively.
source
ManifoldsBase.@manifold_element_forwards — Macro
manifold_element_forwards(T, field::Symbol)
-manifold_element_forwards(T, Twhere, field::Symbol)
Introduce basic fallbacks for type T (which can be a subtype of Twhere) that represents points or vectors for a manifold. Fallbacks will work by forwarding to the field passed in field`
List of forwarded functions:
source
ManifoldsBase.@manifold_vector_forwards — Macro
manifold_vector_forwards(T, field::Symbol)
-manifold_vector_forwards(T, Twhere, field::Symbol)
Introduce basic fallbacks for type T that represents vectors from a vector bundle for a manifold. Twhere is put into where clause of each method. Fallbacks work by forwarding to field passed as field.
List of forwarded functions:
example
@eval @manifold_vector_forwards ValidationFibreVector{TType} TType value
source
Number Systems
The AbstractManifold has one parameter to distinguish the number system a manifold is based on.
ManifoldsBase._unify_number_systems — Method
_unify_number_systems(𝔽s::AbstractNumbers...)
Compute a number system that includes all given number systems (as sub-systems) and is closed under addition and multiplication.
source
Type Parameter
Concrete AbstractManifolds usually correspond to families of manifolds that are parameterized by some numbers, for example determining their manifold_dimension. Those numbers can either be stored in a field or as a type parameter of the structure. The TypeParameter offers the flexibility to have this parameter either as type parameter or a field.
ManifoldsBase.TypeParameter — Type
TypeParameter{T}
Represents numeric parameters of a manifold type as type parameters, allowing for static specialization of methods.
source
ManifoldsBase.wrap_type_parameter — Function
wrap_type_parameter(parameter::Symbol, data)
Wrap data in TypeParameter if parameter is :type or return data unchanged if parameter is :field. Intended for use in manifold constructors, see DefaultManifold for an example.
source

+ -1.0
source
ManifoldsBase.TVector — Type
TVector = AbstractFibreVector{TangentSpaceType}

Type for a tangent vector of a manifold. While a AbstractManifold does not necessarily require this type, for example when it is implemented for Vectors or Matrix type elements, this type can be used for more complicated representations, semantic verification, or even dispatch for different representations of tangent vectors and their types on a manifold.

source

This interface also covers a large variety how to model bases in tangent spaces.

Converting tangent vectors between different representations can be performed using the convert function with either three or four arguments (convert(T, M, p, X) or convert(T, p, X)). For some manifolds providing M may be necessary. The first variant falls back to the second variant.

Macros for automatic forwards for simple points/tangent vectors

When distinguishing different representations of points or tangent vectors on one manifold, it might happen that both a subtype of AbstractManifoldPoint and a subtype of TVector are just encapsulating a value

This is taken into account by the following macros, that forward several actions just to this field. Most prominently vector operations for the tangent vectors. If there is still a default case, a macro sets this type to be equivalent to calling the manifold functions just with the types field that carries the value.

ManifoldsBase.@default_manifold_fallbacks — Macro
default_manifold_fallbacks(TM, TP, TV, pfield::Symbol, vfield::Symbol)

Introduce default fallbacks for all basic functions on manifolds, for manifold of type TM, points of type TP, tangent vectors of type TV, with forwarding to fields pfield and vfield for point and tangent vector functions, respectively.

source
ManifoldsBase.@manifold_element_forwards — Macro
manifold_element_forwards(T, field::Symbol)
+manifold_element_forwards(T, Twhere, field::Symbol)

Introduce basic fallbacks for type T (which can be a subtype of Twhere) that represents points or vectors for a manifold. Fallbacks will work by forwarding to the field passed in field`

List of forwarded functions:

source
ManifoldsBase.@manifold_vector_forwards — Macro
manifold_vector_forwards(T, field::Symbol)
+manifold_vector_forwards(T, Twhere, field::Symbol)

Introduce basic fallbacks for type T that represents vectors from a vector bundle for a manifold. Twhere is put into where clause of each method. Fallbacks work by forwarding to field passed as field.

List of forwarded functions:

example

@eval @manifold_vector_forwards ValidationFibreVector{TType} TType value
source

Number Systems

The AbstractManifold has one parameter to distinguish the number system a manifold is based on.

ManifoldsBase._unify_number_systems — Method
_unify_number_systems(𝔽s::AbstractNumbers...)

Compute a number system that includes all given number systems (as sub-systems) and is closed under addition and multiplication.

source

Type Parameter

Concrete AbstractManifolds usually correspond to families of manifolds that are parameterized by some numbers, for example determining their manifold_dimension. Those numbers can either be stored in a field or as a type parameter of the structure. The TypeParameter offers the flexibility to have this parameter either as type parameter or a field.

ManifoldsBase.TypeParameter — Type
TypeParameter{T}

Represents numeric parameters of a manifold type as type parameters, allowing for static specialization of methods.

source
ManifoldsBase.wrap_type_parameter — Function
wrap_type_parameter(parameter::Symbol, data)

Wrap data in TypeParameter if parameter is :type or return data unchanged if parameter is :field. Intended for use in manifold constructors, see DefaultManifold for an example.

source
diff --git a/previews/PR217/vector_transports/index.html b/previews/PR217/vector_transports/index.html index caef9482..eb6ce91f 100644 --- a/previews/PR217/vector_transports/index.html +++ b/previews/PR217/vector_transports/index.html @@ -1,37 +1,37 @@ Vector transports · ManifoldsBase.jl
GitHub

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_method — Method
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_along — Method
vector_transport_along(
+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_along — Method
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_along — Method
function vector_transport_along(
+)

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_along — Method
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_direction — Function
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 AbstractManifold M 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_to — Function
vector_transport_to(M::AbstractManifold, p, X, q)
+)

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_direction — Function
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 AbstractManifold M 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_to — Function
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 AbstractManifold M 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.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.

source
ManifoldsBase.DifferentiatedRetractionVectorTransport — Type
DifferentiatedRetractionVectorTransport{R<:AbstractRetractionMethod} <:
+vector_transport_to(M::AbstractManifold, p, X, q, m::AbstractVectorTransportMethod)

Transport a vector X from the tangent space at a point p on the AbstractManifold M 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.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.

source
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∈\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.EmbeddedVectorTransport — Type
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.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∈ 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(
+= \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.EmbeddedVectorTransport — Type
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.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∈ 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 AbstractRetractionMethod retraction and an AbstractInverseRetractionMethod inverse_retraction, respectively.

source
ManifoldsBase.ScaledVectorTransport — Type
ScaledVectorTransport{T} <: AbstractVectorTransportMethod

Introduce a scaled variant of any AbstractVectorTransportMethod T, 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.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∈ 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) = +)

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 AbstractRetractionMethod retraction and an AbstractInverseRetractionMethod inverse_retraction, respectively.

source
ManifoldsBase.ScaledVectorTransport — Type
ScaledVectorTransport{T} <: AbstractVectorTransportMethod

Introduce a scaled variant of any AbstractVectorTransportMethod T, 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.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∈ 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 AbstractRetractionMethod retraction and an AbstractInverseRetractionMethod inverse_retraction, respectively.

source
ManifoldsBase.VectorTransportDirection — Type
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.VectorTransportTo — Type
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.VectorTransportWithKeywords — Type
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.VectorTransportDirection — Type
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.VectorTransportTo — Type
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.VectorTransportWithKeywords — Type
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_ladder — Function
pole_ladder(
     M,
     p,
     d,
@@ -39,7 +39,7 @@
     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(
+)

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,
@@ -49,7 +49,7 @@
     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_ladder — Function
schilds_ladder(
     M,
     p,
     d,
@@ -57,7 +57,7 @@
     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!(
+)

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,
@@ -67,4 +67,4 @@
     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 AbstractRetractionMethod m 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 AbstractRetractionMethod m 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
+)

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_diff! — Method
vector_transport_along_diff!(M::AbstractManifold, Y, p, X, c, m::AbstractRetractionMethod)

Compute the vector transport of X from $T_p\mathcal M$ along the curve c using the differential of the AbstractRetractionMethod m in place of Y.

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_diff! — Method
vector_transport_direction_diff!(M::AbstractManifold, Y, p, X, d, m::AbstractRetractionMethod)

Compute the vector transport of X from $T_p\mathcal M$ into the direction d using the differential of the AbstractRetractionMethod m 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 AbstractRetractionMethod m 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_diff! — Method
vector_transport_to_diff(M::AbstractManifold, p, X, q, r)

Compute a vector transport by using a DifferentiatedRetractionVectorTransport r 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 AbstractRetractionMethod m 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