ManifoldsBase.jl – an interface for manifolds

AbstractInverseRetractionMethod

Abstract type for methods for inverting a retraction (see inverse_retract).

AbstractRetractionMethod

Abstract type for methods for retracting a tangent vector to a manifold.

CoTVector

Type for a cotangent vector of a manifold. While a Manifold 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.

ExponentialRetraction

Retraction using the exponential map.

LogarithmicInverseRetraction

Inverse retraction using the logarithmic map.

MPoint

Type for a point on a manifold. While a Manifold 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 points on a manifold.

Manifold{F}

A manifold type. The Manifold is used to dispatch to different functions on a manifold, usually as the first argument of the function. Examples are the exponential and logarithmic maps as well as more general functions that are built on them like the geodesic.

The manifold is parametrized by an 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.

OutOfInjectivityRadiusError

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

ParallelTransport <: AbstractVectorTransportMethod

Specify to use parallel transport as vector transport method within vector_transport_to, vector_transport_direction, or vector_transport_along.

PolarInverseRetraction <: AbstractInverseRetractionMethod

Inverse retractions that are based on a singular value decomposition of the matrix / matrices for point and tangent vector on a Manifold

PolarRetraction <: AbstractRetractionMethod

Retractions that are based on singular value decompositions of the matrix / matrices for point and tangent vector on a Manifold

ProjectionInverseRetraction <: AbstractInverseRetractionMethod

Inverse retractions that are based on a projection (or its inversion).

ProjectionRetraction <: AbstractRetractionMethod

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

ProjectionTransport <: AbstractVectorTransportMethod

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

QRInverseRetraction <: AbstractInverseRetractionMethod

Inverse retractions that are based on a QR decomposition of the matrix / matrices for point and tangent vector on a Manifold

QRRetraction <: AbstractRetractionMethod

Retractions that are based on a QR decomposition of the matrix / matrices for point and tangent vector on a Manifold

TVector

Type for a tangent vector of a manifold. While a Manifold 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.

exp(M::Manifold, p, X)
exp(M::Manifold, p, X, t::Real = 1)

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

isapprox(M::Manifold, p, X, Y; kwargs...)

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

Keyword arguments can be used to specify tolerances.

isapprox(M::Manifold, p, q; kwargs...)

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

Keyword arguments can be used to specify tolerances.

log(M::Manifold, p, q)

Compute the logarithmic map of point q at base point p on the Manifold M.

norm(M::Manifold, p, X)

Compute the norm of tangent vector X at point p from a Manifold M. By default this is computed using inner.

allocate(a)
allocate(a, dims::Integer...)
allocate(a, dims::Tuple)
allocate(a, T::Type)
allocate(a, T::Type, dims::Integer...)
allocate(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.

base_manifold(M::Manifold, depth = Val(-1))

Return the internally stored Manifold 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 Manifold from that level, whether its decorated or not. Any negative value deactivates this depth limit.

check_manifold_point(M::Manifold, p; kwargs...) -> Union{Nothing,String}

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

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

check_tangent_vector(M::Manifold, p, X; kwargs...) -> Union{Nothing,String}

Check whether X is a valid tangent vector in the tangent space of p on the Manifold M. An implementation should first call check_manifold_point(M, p; kwargs...) and then validate X. If it is not a tangent vector, an error string should be returned.

By default, check_tangent_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.

distance(M::Manifold, p, q)

Shortest distance between the points p and q on the Manifold M.

embed!(M::Manifold, Y, p, X)

Embed a tangent vector X at a point p on the Manifold 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.

See also: EmbeddedManifold, project!

embed!(M::Manifold, q, p)

Embed point p from the Manifold M into the ambient space and return the result in q. 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.

See also: EmbeddedManifold, project!

embed(M::Manifold, p, X)

Embed a tangent vector X at a point p on the Manifold 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 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.

See also: EmbeddedManifold, project

embed(M::Manifold, p)

Embed point p from the Manifold 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.

See also: EmbeddedManifold, project

exp!(M::Manifold, q, p, X)
exp!(M::Manifold, q, p, X, t::Real = 1)

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

geodesic(M::Manifold, p, X) -> Function

Get the geodesic with initial point p and velocity X on the Manifold M. The geodesic is the curve of constant velocity that is locally distance-minimizing. This function returns a function of (time) t.

geodesic(M::Manifold, x, v, t::Real)
geodesic(M::Manifold, x, v, T::AbstractVector) -> AbstractVector

Return the point at time t or points at times t in T along the geodesic.

injectivity_radius(M::Manifold, 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::Manifold)

Infimum of the injectivity radius of all manifold points.

injectivity_radius(M::Manifold[, x], method::AbstractRetractionMethod)
injectivity_radius(M::Manifold, 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.

inner(M::Manifold, p, X, Y)

Compute the inner product of tangent vectors X and Y at point p from the Manifold M.

See also: MetricManifold

inverse_retract!(M::Manifold, X, p, q[, method::AbstractInverseRetractionMethod])

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

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

inverse_retract(M::Manifold, x, y)
inverse_retract(M::Manifold, x, y, method::AbstractInverseRetractionMethod

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

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

is_manifold_point(M::Manifold, p, throw_error = false; kwargs...)

Return whether p is a valid point on the Manifold M.

If throw_error is false, the function returns either true or false. If throw_error is true, the function either returns true or throws an error. By default the function calls check_manifold_point(M, p; kwargs...) and checks whether the returned value is nothing or an error.

is_tangent_vector(M::Manifold, p, X, throw_error = false; kwargs...)

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

If throw_error is false, the function returns either true or false. If throw_error is true, the function either returns true or throws an error. By default the function calls check_tangent_vector(M, p, X; kwargs...) and checks whether the returned value is nothing or an error.

log!(M::Manifold, X, p, q)

Compute the logarithmic map of point q at base point p on the Manifold M. The result is saved to X.

manifold_dimension(M::Manifold)

The dimension $n=\dim_{\mathcal M}$ of real space $\mathbb R^n$ to which the neighborhood of each point of the Manifold M is homeomorphic.

number_eltype(x)

Numeric element type of the a nested representation of a point or a vector. To be used in conjuntion with allocate or allocate_result.

project!(M::Manifold, Y, p, X)

Project ambient space representation of a vector X to a tangent vector at point p on the Manifold 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!

project!(M::Manifold, q, p)

Project point p from the ambient space onto the Manifold 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!

project(M::Manifold, p, X)

Project ambient space representation of a vector X to a tangent vector at point p on the Manifold 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

project(M::Manifold, p)

Project point p from the ambient space of the Manifold 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

representation_size(M::Manifold)

The size of an array representing a point on Manifold M.

retract!(M::Manifold, q, p, X)
retract!(M::Manifold, q, p, X, t::Real=1)
retract!(M::Manifold, q, p, X, method::AbstractRetractionMethod)
retract!(M::Manifold, 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 Manifold manifold M. Result is saved to q.

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

retract(M::Manifold, p, X)
retract(M::Manifold, p, X, t::Real=1)
retract(M::Manifold, p, X, method::AbstractRetractionMethod)
retract(M::Manifold, 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 Manifold M.

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

shortest_geodesic(M::Manifold, p, q) -> Function

Get a geodesic $\gamma_{p,q}(t)$ whose length is the shortest path between the points pand q, where $\gamma_{p,q}(0)=p$ and $\gamma_{p,q}(1)=q$. When there are multiple shortest geodesics, there is no guarantee which will be returned.

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

shortest_geodesic(M::Manifold, p, q, t::Real)
shortest_geodesic(M::Manifold, p, q, T::AbstractVector) -> AbstractVector

Return the point at time t or points at times t in T along the shortest geodesic.

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

Transport a vector X from the tangent space at a point p on the Manifold M along the curve c such that c(0) is equal to p to the point c(1) using the method, which defaults to ParallelTransport. The result is saved to Y.

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

Transport a vector X from the tangent space at a point p on the Manifold M along the curve c such that c(0) is equal to p to the point c(1) using the method, which defaults to ParallelTransport.

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

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

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

Transport a vector X from the tangent space at a point p on the Manifold M in the direction indicated by the tangent vector d at p. By default, exp and vector_transport_to! are used with the method, which defaults to ParallelTransport.

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

Transport a vector X from the tangent space at p on the Manifold M by interpreting it as an element of the embedding and then projecting it onto the tangent space at q. This method requires project.

vector_transport_to!(M::Manifold, Y, p, X, q)
vector_transport_to!(M::Manifold, Y, p, X, q, method::AbstractVectorTransportMethod)

Transport a vector X from the tangent space at a point p on the Manifold M along the shortest_geodesic to the tangent space at another point q. By default, the AbstractVectorTransportMethod method is ParallelTransport. The result is saved to Y.

vector_transport_to(M::Manifold, p, X, q)
vector_transport_to(M::Manifold, p, X, q, method::AbstractVectorTransportMethod)

Transport a vector X from the tangent space at a point p on the Manifold M along the shortest_geodesic to the tangent space at another point q. By default, the AbstractVectorTransportMethod method is ParallelTransport.

zero_tangent_vector!(M::Manifold, X, p)

Save to X a vector such that retracting X to the Manifold M at p produces p.

zero_tangent_vector(M::Manifold, p)

Return the tangent vector from the tangent space at p on the Manifold M, that represents the zero vector, i.e. such that a retraction at p produces p.

AbstractEstimationMethod

Abstract type for defining statistical estimation methods.

AbstractVectorTransportMethod

Abstract type for methods for transporting vectors.

angle(M::Manifold, p, X, Y)

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

allocate_result(M::Manifold, f, x...)

Allocate an array for the result of function f on Manifold 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.

allocate_result_type(M::Manifold, f, args::NTuple{N,Any}) where N

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

number_system(M::Manifold{𝔽})

Return the number system the manifold M is based on, i.e. the parameter 𝔽.

real_dimension(𝔽::AbstractNumbers)

Return the real dimension $\dim_ℝ 𝔽$ of the AbstractNumbers system 𝔽. The real dimension is the dimension of a real vector space with which a number in 𝔽 can be identified. For example, ComplexNumbers have a real dimension of 2, and QuaternionNumbers have a real dimension of 4.

AbstractNumbers

An abstract type to represent the number system on which a manifold is built.

This provides concrete number types for dispatch. The two most common number types are the fields RealNumbers (ℝ for short) and ComplexNumbers (ℂ).

ComplexNumbers <: AbstractNumbers
ℂ = ComplexNumbers()

The field of complex numbers.

QuaternionNumbers <: AbstractNumbers
ℍ = QuaternionNumbers()

The division algebra of quaternions.

RealNumbers <: AbstractNumbers
ℝ = RealNumbers()

The field of real numbers.

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

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)

DefaultBasis{𝔽}

An arbitrary basis on a manifold. This will usually be the fastest basis available for a manifold.

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

DefaultOrthogonalBasis{𝔽}

An arbitrary orthogonal basis on a manifold. This will usually be the fastest orthogonal basis available for a manifold.

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

DefaultOrthonormalBasis(𝔽::AbstractNumbers = ℝ)

An arbitrary orthonormal basis on a manifold. This will usually be the fastest orthonormal basis available for a manifold.

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

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

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

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

Constructor

DiagonalizingOrthonormalBasis(frame_direction, 𝔽::AbstractNumbers = ℝ)

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

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

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

Available methods:

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

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

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

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

See also: get_coordinates, get_vector

get_coordinates(M::Manifold, p, X, B::AbstractBasis)
get_coordinates(M::Manifold, 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

get_vector(M::Manifold, p, X, B::AbstractBasis)

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

get_vectors(M::Manifold, p, B::AbstractBasis)

Get the basis vectors of basis B of the tangent space at point p.

hat(M::Manifold, 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:

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.

number_of_coordinates(M::Manifold, B::AbstractBasis)

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

number_system(::AbstractBasis)

The number system for the vectors of the given basis.

vee(M::Manifold, 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:

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.

AbstractBasis{𝔽}

Abstract type that represents a basis on a manifold or a subset of it.

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

AbstractOrthogonalBasis{𝔽}

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

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

AbstractOrthonormalBasis{𝔽}

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

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

allocation_promotion_function(M::Manifold, 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.

AbstractDecoratorManifold{𝔽} <: Manifold{𝔽}

An AbstractDecoratorManifold indicates that to some extent a manifold subtype decorates another Manifold in the sense that it either

• it extends the functionality of a manifold with further features
• it defines a new manifold that internally uses functions from the decorated manifold

with the main intent that several or most functions of Manifold are transparently passed through to the manifold that is decorated. This way a function implemented for a decorator acts transparent on all other decorators, i.e. they just pass them through. If the decorator the function is implemented for is not among the decorators, an error is issued. By default all base manifold functions, for example exp and log are transparent for all decorators.

Transparency of functions with respect to decorators can be specified using the macros @decorator_transparent_fallback, @decorator_transparent_function and @decorator_transparent_signature.

@decorator_transparent_fallback(ex)
@decorator_transparent_fallback(fallback_case = :intransparent, ex)

This macro introduces an additional implementation for a certain additional case. This can especially be used if for an already transparent function and an abstract intermediate type a change in the default is required. For implementing a concrete type, neither this nor any other trick is necessary. One just implements the function as before. Note that a decorator that is_default_decorator still dispatches to the transparent case.

• :transparent states, that the function is transparently passed on to the manifold that is decorated by the AbstractDecoratorManifold M, which is determined using the function decorated_manifold.
• :intransparent states that an implementation for this decorator is required, and if none of the types provides one, an error is issued. Since this macro provides such an implementation, this is the default.
• :parent states, that this function passes on to the supertype instead of to the decorated manifold.

Inline definitions are not supported. The function signature however may contain keyword arguments and a where clause. It does not allow for parameters with default values.

Examples

@decorator_transparent_fallback function log!(M::AbstractGroupManifold, X, p, q)
    log!(decorated_manifold(M), X, p, Q)
end
@decorator_transparent_fallback :transparent function log!(M::AbstractGroupManifold, X, p, q)
    log!(decorated_manifold(M), X, p, Q)
end

@decorator_transparent_function(ex)
@decorator_transparent_function(fallback_case = :intransparent, ex)

Introduce the function specified by ex to act transparently with respect to AbstractDecoratorManifolds. This introduces the possibility to modify the kind of transparency the implementation is done for. This optional first argument, the Symbol within fallback_case. This macro can be used to define a function and introduce it as transparent to other decorators. Note that a decorator that is_default_decorator still dispatches to the transparent case.

The cases of transparency are

• :transparent states, that the function is transparently passed on to the manifold that is decorated by the AbstractDecoratorManifold M, which is determined using the function decorated_manifold.
• :intransparent states that an implementation for this decorator is required, and if none of the types provides one, an error is issued. Since this macro provides such an implementation, this is the default.
• :parent states, that this function passes on to the supertype instead of to the decorated manifold. Passing is performed using the invoke function where the type of manifold is replaced by its supertype.

Innkoline-definitions are not yet covered – the function signature however may contain keyword arguments and a where clause.

Examples

@decorator_transparent_function log!(M::AbstractDecoratorManifold, X, p, q)
    log!(decorated_manifold(M), X, p, Q)
end
@decorator_transparent_function :parent log!(M::AbstractDecoratorManifold, X, p, q)
    log!(decorated_manifold(M), X, p, Q)
end

@decorator_transparent_signature(ex)

Introduces a given function to be transparent with respect to all decorators. The function is adressed by its signature in ex.

Supports standard, keyword arguments and where clauses. Doesn't support parameters with default values. It introduces a dispatch on several transparency modes

The cases of transparency are

• :transparent states, that the function is transparently passed on to the manifold that is decorated by the AbstractDecoratorManifold M, which is determined using the function decorated_manifold. This is the default.
• :intransparent states that an implementation for this decorator is required, and if none of the types provides one, an error is issued.
• :parent states, that this function passes on to the supertype instead of to the decorated manifold.

Inline definitions are not supported. The function signature however may contain keyword arguments and a where clause.

The dispatch kind can later still be set to something different, see decorator_transparent_dispatch

Examples:

@decorator_transparent_signature log!(M::AbstractDecoratorManifold, X, p, q)
@decorator_transparent_signature log!(M::TD, X, p, q) where {TD<:AbstractDecoratorManifold}
@decorator_transparent_signature isapprox(M::AbstractDecoratorManifold, p, q; kwargs...)

decorated_manifold(M::AbstractDecoratorManifold)

Return the manifold decorated by the decorator M. Defaults to M.manifold.

decorator_transparent_dispatch(f, M::Manifold, args...) -> Val

Given a Manifold M and a function f(M,args...), indicate, whether a function is Val(:transparent) or Val(:intransparent) for the (decorated) Manifold M. Another possibility is, that for M and given args... the function f should invoke Ms Val(:parent) implementation, see @decorator_transparent_function for details.

default_decorator_dispatch(M) -> Val

Return whether by default to dispatch the the inner manifold of a decorator (Val(true)) or not (Val(false). For more details see is_decorator_transparent.

is_decorator_transparent(f, M::Manifold, args...) -> Bool

Given a Manifold M and a function f(M, args...), indicate, whether an AbstractDecoratorManifold acts transparently for f. This means, it just passes through down to the internally stored manifold. Transparency is only defined for decorator manifolds and by default all decorators are transparent. A function that is affected by the decorator indicates this by returning false. To change this behaviour, see decorator_transparent_dispatch.

If a decorator manifold is not in general transparent, it might still pass down for the case that a decorator is the default decorator, see is_default_decorator.

is_default_decorator(M) -> Bool

For any manifold that is a subtype of AbstractDecoratorManifold, this function indicates whether a certain manifold M acts as a default decorator.

This yields that all functions are passed through to the decorated Manifold if M is indicated as default. This overwrites all is_decorator_transparent values.

This yields the following advantange: For a manifold one usually implicitly assumes for example a metric. To avoid reimplementation of this metric when introducing a second metric, the first metric can be set to be the default, i.e. its implementaion is already given by the undecorated case.

Value returned by this function is determined by default_decorator_dispatch, which returns a Val-wrapped boolean for type stability of certain functions.

ValidationCoTVector <: CoTVector

Represent a cotangent vector to a point on an ValidationManifold, i.e. on a manifold where data can be represented by arrays. The array is stored internally and semantically. This distinguished the value from ValidationMPoints and ValidationTVectors.

ValidationMPoint <: MPoint

Represent a point on an ValidationManifold, i.e. on a manifold where data can be represented by arrays. The array is stored internally and semantically. This distinguished the value from ValidationTVectors and ValidationCoTVectors.

ValidationManifold{𝔽,M<:Manifold{𝔽}} <: AbstractDecoratorManifold{𝔽}

A manifold to encapsulate manifolds working on array representations of MPoints and TVectors in a transparent way, such that for these manifolds it's not necessary to introduce explicit types for the points and tangent vectors, but they are encapsulated/stripped automatically when needed.

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

ValidationTVector <: TVector

Represent a tangent vector to a point on an ValidationManifold, i.e. on a manifold where data can be represented by arrays. The array is stored internally and semantically. This distinguished the value from ValidationMPoints and ValidationCoTVectors.

array_value(p)

Return the internal array value of an ValidationMPoint, ValidationTVector, or ValidationCoTVector if the value p is encapsulated as such. Return p if it is already an array.

AbstractEmbeddedManifold{𝔽,T<:AbstractEmbeddingType,𝔽} <: AbstractDecoratorManifold{𝔽}

An abstract type for embedded manifolds, which acts as an AbstractDecoratorManifold. The functions of the manifold that is embedded can hence be just passed on to the embedding. The embedding is further specified by an AbstractEmbeddingType.

This means, that technically an embedded manifold is a decorator for the embedding, i.e. functions of this type get, in the semi-transparent way of the AbstractDecoratorManifold, passed on to the embedding.

AbstractEmbeddingType

A type used to specify properties of an AbstractEmbeddedManifold.

DefaultEmbeddingType <: AbstractEmbeddingType

A type of default embedding that does not have any special properties.

DefaultIsometricEmbeddingType <: AbstractIsometricEmbeddingType

An isometric embedding type that acts as a default, i.e. it has no specifig properties beyond its isometric property.

EmbeddedManifold{𝔽, MT <: Manifold, NT <: Manifold, ET} <: AbstractEmbeddedManifold{𝔽, ET}

A type to represent that a Manifold M of type MT is indeed an emebedded manifold and embedded into the manifold N of type NT. Based on the AbstractEmbeddingType ET, this introduces methods for M by passing them through to embedding N.

Fields

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

Constructor

EmbeddedManifold(M, N, e=TransparentIsometricEmbedding())

Generate the EmbeddedManifold of the Manifold M into the Manifold N with AbstractEmbeddingType e that by default is the most transparent TransparentIsometricEmbedding

TransparentIsometricEmbedding <: AbstractIsometricEmbeddingType

Specify that an embedding is the default isometric embedding. This even inherits logarithmic and exponential map as well as retraction and inverse retractions from the embedding.

For an example, see SymmetricMatrices which are isometrically embedded in the Euclidean space of matrices but also inherit exponential and logarithmic maps.

AbstractIsometricEmbeddingType <: AbstractEmbeddingType

Characterizes an embedding as isometric. For this case the inner product is passed from the embedded manifold to the embedding.

base_manifold(M::AbstractEmbeddedManifold, d::Val{N} = Val(-1))

Return the base manifold of M that is enhanced with its embedding. While functions like inner might be overwritten to use the (decorated) manifold representing the embedding, the basemanifold is the manifold itself in the sense that detemining e.g. the [`isdefault_metric](@ref) does not fall back to check with the embedding but with the manifold itself. For this abstract case, justM` is returned.

base_manifold(M::EmbeddedManifold, d::Val{N} = Val(-1))

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

check_manifold_point(M::AbstractEmbeddedManifold, p; kwargs)

check whether a point p is a valid point on the AbstractEmbeddedManifold, i.e. that embed(M, p) is a valid point on the embedded manifold.

check_tangent_vector(M::AbstractEmbeddedManifold, p, X; check_base_point = true, kwargs...)

check that embed(M,p,X) is a valid tangent to embed(p,X), where check_base_point determines whether the validity of p is checked, too.

get_embedding(M::AbstractEmbeddedManifold)

Return the Manifold N an AbstractEmbeddedManifold is embedded into.

default_embedding_dispatch(M::AbstractEmbeddedManifold)

This method indicates that an AbstractEmbeddedManifold is the default and hence acts completely transparently and passes all functions transparently onwards. This is used by the AbstractDecoratorManifold within default_decorator_dispatch. By default this is set to Val(false).

DefaultManifold <: Manifold

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