Metric manifold

A Riemannian manifold always consists of a topological manifold together with a smoothly varying metric tensor $g$. This metric tensor defines an inner product on each tangent space of the manifold. In Manifolds.jl, a concrete implementation of an AbstractManifold has an implicit metric, which we refer to as the default metric. For example on Euclidean space, this is the usual inner product. For the Sphere, this default metric is the metric induced by the embedding in the ambient Euclidean space, restricted to the tangent spaces of the sphere.

Such a default metric is usually not the only possible metric on a manifold.

The MetricManifold decorator allows to introduce further metrics for a manifold by acting as a wrapper. This allows to define further metrics for an existing manifold, while only having to implement functions that depend on the metric. All functions that are independent of the metric are automatically forwarded to the underlying manifold. When wrapping a manifold M with a MetricManifold together with the default metric(M), this wrapper acts completely transparent and passes all function calls to the underlying manifold M.

Metric manifold

Types

Manifolds.DefaultMetric — Type

DefaultMetric <: AbstractMetric

Indicating that a manifold uses the default metric, that one has implicitly assumed when defining the manifold

Manifolds.MetricManifold — Type

MetricManifold{𝔽,M<:AbstractManifold{𝔽},G<:AbstractMetric} <: AbstractDecoratorManifold{𝔽}

Equip a AbstractManifold explicitly with an AbstractMetric G.

For a Metric AbstractManifold, by default, assumes, that you implement the linear form from local_metric in order to evaluate the exponential map.

If the corresponding AbstractMetric G yields closed form formulae for e.g. the exponential map and this is implemented directly (without solving the ode), you can of course still implement that directly.

Constructor

MetricManifold(M, G)

Generate the AbstractManifold M as a manifold with the AbstractMetric G.

Implement Different Metrics on the same Manifold

In order to distinguish different metrics on one manifold, one can introduce two AbstractMetrics and use this type to dispatch on the metric, see SymmetricPositiveDefinite. To avoid overhead, one AbstractMetric can then be marked as being the default, i.e. the one that is used, when no MetricManifold decorator is present. This avoids reimplementation of the first existing metric, access to the metric-dependent functions that were implemented using the undecorated manifold, as well as the transparent fallback of the corresponding MetricManifold with default metric to the undecorated implementations. This does not cause any runtime overhead. Introducing a default AbstractMetric serves a better readability of the code when working with different metrics.

Implementation of Metrics

For the case that a local_metric is implemented as a bilinear form that is positive definite, the following further functions are provided, unless the corresponding AbstractMetric is marked as default – then the fallbacks mentioned in the last section are used for e.g. the exponential map.

Base.log — Method

log(N::MetricManifold{M,G}, p, q)

Compute the logarithmic map on the AbstractManifold M equipped with the AbstractMetric G.

If the metric was declared the default metric, this method falls back to log(M,p,q). Otherwise, you have to provide an implementation for the non-default AbstractMetric G metric within its MetricManifold{M,G}.

Manifolds.det_local_metric — Method

det_local_metric(M::AbstractManifold, p, B::AbstractBasis)

Return the determinant of local matrix representation of the metric tensor $g$, i.e. of the matrix $G(p)$ representing the metric in the tangent space at $p$ with as a matrix.

See also local_metric

Manifolds.einstein_tensor — Method

einstein_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = diff_badefault_differential_backendckend())

Compute the Einstein tensor of the manifold M at the point p, see https://en.wikipedia.org/wiki/Einstein_tensor

Manifolds.flat — Method

flat(N::MetricManifold{M,G}, p, X::TFVector)

Compute the musical isomorphism to transform the tangent vector X from the AbstractManifold M equipped with AbstractMetric G to a cotangent by computing

\[X^♭= G_p X,\]

where $G_p$ is the local matrix representation of G, see local_metric

Manifolds.inverse_local_metric — Method

inverse_local_metric(M::AbstractcManifold{𝔽}, p, B::AbstractBasis)

Return the local matrix representation of the inverse metric (cometric) tensor of the tangent space at p on the AbstractManifold M with respect to the AbstractBasis basis B.

The metric tensor (see local_metric) is usually denoted by $G = (g_{ij}) ∈ 𝔽^{d×d}$, where $d$ is the dimension of the manifold.

Then the inverse local metric is denoted by $G^{-1} = g^{ij}$.

Manifolds.is_default_metric — Method

is_default_metric(M::AbstractManifold, G::AbstractMetric)

returns whether an AbstractMetric is the default metric on the manifold M or not.

If M is a |MetricManifold](@ref) this indicates whether the metric now used is the same as the default one on the wrapped manifold.

Manifolds.local_metric — Method

local_metric(M::AbstractManifold{𝔽}, p, B::AbstractBasis)

Return the local matrix representation at the point p of the metric tensor $g$ with respect to the AbstractBasis B on the AbstractManifold M. Let $d$denote the dimension of the manifold and $b_1,\ldots,b_d$ the basis vectors. Then the local matrix representation is a matrix $G\in 𝔽^{n×n}$ whose entries are given by $g_{ij} = g_p(b_i,b_j), i,j\in\{1,…,d\}$.

This yields the property for two tangent vectors (using Einstein summation convention) $X = X^ib_i, Y=Y^ib_i \in T_p\mathcal M$ we get $g_p(X, Y) = g_{ij} X^i Y^j$.

Manifolds.local_metric_jacobian — Method

local_metric_jacobian(M::AbstractManifold, p, B::AbstractBasis;
backend::AbstractDiffBackend,

)

Get partial derivatives of the local metric of M at p in basis B with respect to the coordinates of p, $\frac{∂}{∂ p^k} g_{ij} = g_{ij,k}$. The dimensions of the resulting multi-dimensional array are ordered $(i,j,k)$.

Manifolds.log_local_metric_density — Method

log_local_metric_density(M::AbstractManifold, p, B::AbstractBasis)

Return the natural logarithm of the metric density $ρ$ of M at p, which is given by $ρ = \log \sqrt{|\det [g_{ij}]|}$ for the metric tensor expressed in basis B.

Manifolds.metric — Method

metric(M::MetricManifold)

Get the metric $g$ of the AbstractManifold(M).

Manifolds.ricci_curvature — Method

ricci_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())

Compute the Ricci scalar curvature of the manifold M at the point p using basis B. The curvature is computed as the trace of the Ricci curvature tensor with respect to the metric, that is $R=g^{ij}R_{ij}$ where $R$ is the scalar Ricci curvature at p, $g^{ij}$ is the inverse local metric (see inverse_local_metric) at p and $R_{ij}$ is the Ricci curvature tensor, see ricci_tensor. Both the tensor and inverse local metric are expressed in local coordinates defined by B, and the formula uses the Einstein summation convention.

Manifolds.sharp — Method

sharp(N::MetricManifold{M,G}, p, ξ::CoTFVector)

Compute the musical isomorphism to transform the cotangent vector ξ from the AbstractManifold M equipped with AbstractMetric G to a tangent by computing

\[ξ^♯ = G_p^{-1} ξ,\]

where $G_p$ is the local matrix representation of G, i.e. one employs inverse_local_metric here to obtain $G_p^{-1}$.

ManifoldsBase.inner — Method

inner(N::MetricManifold{M,G}, p, X, Y)

Compute the inner product of X and Y from the tangent space at p on the AbstractManifold M using the AbstractMetric G.

\[g_p(X, Y) = ⟨X, G_p Y⟩,\]

where $G_p$ is the local matrix representation of the AbstractMetric G.

ManifoldsBase.inverse_retract — Method

inverse_retract(M::MetricManifold, p, q)
inverse_retract!(M::MetricManifold, X, p, q)

Compute the inverse retraction on the MetricManifold M. Since every inverse retraction is an inverse retraction with respect to any logarithmic map (induced by the metric), this method falls back to calling inverse_retract on the base manifold. The two exceptions are the LogarithmicInverseRetraction and ShootingInverseRetraction, in which case the method falls back to the default, that is to calling, respectively, log and inverse_retract_shooting!.

ManifoldsBase.retract — Method

retract(M::MetricManifold, p, X)
retract!(M::MetricManifold, q, p, X)

Compute the retraction on the MetricManifold M. Since every retraction is a retraction with respect to any exponential map (here induced by the metric), this method falls back to calling retract on the inner manifold. The one exception is the ExponentialRetraction, in which case the method falls back to the default, i.e. to calling exp but still on M.

ManifoldsBase.vector_transport_direction — Method

vector_transport_direction(M::MetricManifold, p, X, d)
vector_transport_direction!(M::MetricManifold, Y, p, X, d)

Compute the vector transport of the tangent vector X at point p in the direction d on the MetricManifold M.

Since a vector transport is usually defined with respect to a retraction, cf. e.g. [AMS08], and the vector transport is closely related to an affine connection, it is to some extent metric dependent. Therefore, this method only falls back to calling its corresponding method on the base manifold, if the metric is the default one.

ManifoldsBase.vector_transport_to — Method

vector_transport_to(M::MetricManifold, p, X, d)
vector_transport_to!(M::MetricManifold, Y, p, X, d)

Compute the vector transport of the tangent vector X at point p to a point q on the MetricManifold M.

Since a vector transport is usually defined with respect to a retraction, cf. e.g. [AMS08], and the vector transport is closely related to an affine connection, it is to some extent metric dependent. Therefore, this method only falls back to calling its corresponding method on the base manifold, if the metric is the default one.

Metrics, charts and bases of vector spaces

Metric-related functions, similarly to connection-related functions, need to operate in a basis of a vector space, see here.

Metric-related functions can take bases of associated tangent spaces as arguments. For example local_metric can take the basis of the tangent space it is supposed to operate on instead of a custom basis of the space of symmetric bilinear operators.