Differentiation

AbstractDiffBackend

An abstract type for diff backends. See FiniteDifferencesBackend for an example.

CurrentDiffBackend(backend::AbstractDiffBackend)

A mutable struct for storing the current differentiation backend in a global constant _current_default_differential_backend.

See also

AbstractDiffBackend, default_differential_backend, set_default_differential_backend!

_derivative(f, t[, backend::AbstractDiffBackend])

Compute the derivative of a callable f at time t computed using the given backend, an object of type Manifolds.AbstractDiffBackend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.

This function calculates plain Euclidean derivatives, for Riemannian differentiation see for example differential.

_gradient(f, p[, backend::AbstractDiffBackend])

Compute the gradient of a callable f at point p computed using the given backend, an object of type AbstractDiffBackend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.

This function calculates plain Euclidean gradients, for Riemannian gradient calculation see for example gradient.

_hessian(f, p[, backend::AbstractDiffBackend])

Compute the Hessian of a callable f at point p computed using the given backend, an object of type AbstractDiffBackend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.

This function calculates plain Euclidean Hessian.

_jacobian(f, p[, backend::AbstractDiffBackend])

Compute the Jacobian of a callable f at point p computed using the given backend, an object of type AbstractDiffBackend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.

This function calculates plain Euclidean Jacobians, for Riemannian Jacobian calculation see for example gradient.

default_differential_backend() -> AbstractDiffBackend

Get the default differentiation backend.

set_default_differential_backend!(backend::AbstractDiffBackend)

Set current backend for differentiation to backend.

_current_default_differential_backend

The instance of Manifolds.CurrentDiffBackend that stores the globally default differentiation backend.

FiniteDifferencesBackend(method::FiniteDifferenceMethod = central_fdm(5, 1))

Differentiation backend based on the FiniteDifferences package.

AbstractRiemannianDiffBackend

An abstract type for backends for differentiation.

RiemannianProjectionBackend <: AbstractRiemannianDiffBackend

This backend computes the differentiation in the embedding, which is currently limited to the gradient. Let $mathcal M$ denote a manifold embedded in some $R^m$, where $m$ is usually (much) larger than the manifold dimension. Then we require three tools

• A function $f̃: ℝ^m → ℝ$ such that its restriction to the manifold yields the cost function $f$ of interest.
• A project function to project tangent vectors from the embedding (at $T_pℝ^m$) back onto the tangent space $T_p\mathcal M$. This also includes possible changes of the representation of the tangent vector (e.g. in the Lie algebra or in a different data format).
• A change_representer for non-isometrically embedded manifolds, i.e. where the tangent space $T_p\mathcal M$ of the manifold does not inherit the inner product from restriction of the inner product from the tangent space $T_pℝ^m$ of the embedding

For more details see ^{[AbsilMahonySepulchre2008]}, Section 3.6.1 for a derivation on submanifolds.

TangentDiffBackend <: AbstractRiemannianDiffBackend

A backend that uses tangent spaces and bases therein to derive an intrinsic differentiation scheme.

Since it works in tangent spaces at argument and function value, methods might require a retraction and an inverse retraction as well as a basis.

In the tangent space itself, this backend then employs an (Euclidean) AbstractDiffBackend

Constructor

TangentDiffBackend(diff_backend)

where diff_backend is an AbstractDiffBackend to be used on the tangent space.

With the keyword arguments

• retraction an AbstractRetractionMethod (ExponentialRetraction by default)
• inverse_retraction an AbstractInverseRetractionMethod LogarithmicInverseRetraction by default)
• basis_arg an AbstractBasis (DefaultOrthogonalBasis by default)
• basis_val an AbstractBasis (DefaultOrthogonalBasis by default)

differential(M::AbstractManifold, f, t::Real, backend::AbstractDiffBackend)
differential!(M::AbstractManifold, f, X, t::Real, backend::AbstractDiffBackend)

Compute the Riemannian differential of a curve $f: ℝ\to M$ on a manifold M represented by function f at time t using the given backend. It is calculated as the tangent vector equal to $\mathrm{d}f_t(t)[1]$.

The mutating variant computes the differential in place of X.

gradient(M::AbstractManifold, f, p, backend::AbstractRiemannianDiffBackend)
gradient!(M::AbstractManifold, f, X, p, backend::AbstractRiemannianDiffBackend)

Compute the Riemannian gradient $∇f(p)$ of a real-valued function $f:\mathcal M \to ℝ$ at point p on the manifold M using the specified AbstractRiemannianDiffBackend.

The mutating variant computes the gradient in place of X.

gradient(M, f, p, backend::TangentDiffBackend)

This method uses the internal backend.diff_backend (Euclidean) on the function

\[ f(\retr_p(\cdot))\]

which is given on the tangent space. In detail, the gradient can be written in terms of the backend.basis_arg. We illustrate it here for an AbstractOrthonormalBasis, since that simplifies notations:

\[\operatorname{grad}f(p) = \operatorname{grad}f(p) = \sum_{i=1}^{d} g_p(\operatorname{grad}f(p),X_i)X_i = \sum_{i=1}^{d} Df(p)[X_i]X_i\]

where the last equality is due to the definition of the gradient as the Riesz representer of the differential.

If the backend is a forward (or backward) finite difference, these coefficients in the sum can be approximates as

\[DF(p)[Y] ≈ \frac{1}{h}\bigl( f(\exp_p(hY)) - f(p) \bigr)\]

writing $p=\exp_p(0)$ we see that this is a finite difference of $f\circ\exp_p$, i.e. for a function on the tangent space, so we can also use other (Euclidean) backends

ExplicitEmbeddedBackend{TF<:NamedTuple} <: AbstractDiffBackend

A backend to use with the RiemannianProjectionBackend or the TangentDiffBackend, when you have explicit formulae for the gradient in the embedding available.

Constructor

ExplicitEmbeddedBackend(M::AbstractManifold; kwargs)

Construct an ExplicitEmbeddedBackend in the embedding M, where currently the following keywords may be used

• gradient for a(n allocating) gradient function gradient(M, p) defined in the embedding
• gradient! for a mutating gradient function gradient!(M, X, p).

Note that the gradient functions are defined on the embedding manifold M passed to the Backend as well