The Manifold interface

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.

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.

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.

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.

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, ℝ)

julia> p = [1.0, 0.0, 0.0]
3-element Vector{Float64}:
 1.0
 0.0
 0.0

julia> X = [0.0, 2.0, -1.0]
3-element Vector{Float64}:
  0.0
  2.0
 -1.0

julia> B = DefaultOrthonormalBasis()
DefaultOrthonormalBasis(ℝ)

julia> fX = TFVector(get_coordinates(M, p, X, B), B)
TFVector([2.0, -1.0], DefaultOrthonormalBasis(ℝ))

julia> X_back = get_vector(M, p, fX.data, fX.basis)
3-element Vector{Float64}:
 -0.0
  2.0
 -1.0

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.

vector_space_dimension(M::AbstractManifold, V::VectorSpaceType)

Dimension of the vector space of type V on manifold M.

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.

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:

• allocate,
• copy,
• copyto!,
• number_eltype (only for values, not the type itself),
• similar,
• size,
• ==.

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:

• basic arithmetic (*, /, \, +, -),
• all things from @manifold_element_forwards,
• broadcasting support.

example

@eval @manifold_vector_forwards ValidationFibreVector{TType} TType value

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.

number_system(M::AbstractManifold{𝔽})

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.

TypeParameter{T}

Represents numeric parameters of a manifold type as type parameters, allowing for static specialization of methods.

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.