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.DiagonalizingOrthonormalBasis — Type
DiagonalizingOrthonormalBasis{𝔽,TV} <: AbstractOrthonormalBasis{𝔽,TangentSpaceType}

An orthonormal basis of the tangent space that diagonalizes the curvature tensor.

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 vector with a real-coefficient basis, so that a complex-valued vector representation is allocated.

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 real bases of complex manifolds have real coordinates but it can be overridden by a more specific method.

source
ManifoldsBase.default_basis — Method
default_basis(M::AbstractManifold, ::Type{T}; kwargs...) where {T}
default_basis(M::AbstractManifold; kwargs...)

Provide a default basis for a manifold's tangent space. This can be specific for different points p on M. The global default for both is the DefaultOrthonormalBasis with coefficients in the field given by the field keyword argument.

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

Keyword arguments

source
ManifoldsBase.default_basis — Method
default_basis(M::AbstractManifold, ::Type{T}; kwargs...) where {T}
default_basis(M::AbstractManifold; kwargs...)

Provide a default basis for a manifold's tangent space. This can be specific for different points p on M. The global default for both is the DefaultOrthonormalBasis with coefficients in the field given by the field keyword argument.

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

Keyword arguments

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_coordinates — Function
get_coordinates(M::AbstractManifold, p, X, B::AbstractBasis=default_basis(M, typeof(p)))
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=default_basis(M, typeof(p)))

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, default_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 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.

A vector that is linearly dependent on the previous ones stops the computation with an error, unless skip_linearly_dependent is set to true, in which case it is left out.

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) – whether to return (true) a set that contains fewer vectors than a basis or to throw an error (false, default) in that case

further keyword arguments can be passed to set the accuracy of the independence test. Especially atol defaults to eps(number_eltype(first(V))).

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, Y, 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$ in-place of Y.

See also hat.

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.vee! — Method
vee!(M::AbstractManifold, Y, 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$, in-place of Y.

See also vee.

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