diff --git a/previews/PR54/.documenter-siteinfo.json b/previews/PR54/.documenter-siteinfo.json index 7d0ff06..a8c5d89 100644 --- a/previews/PR54/.documenter-siteinfo.json +++ b/previews/PR54/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-12-02T14:12:17","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-12-02T14:32:54","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/previews/PR54/backends/index.html b/previews/PR54/backends/index.html index 127a57e..cbcfc31 100644 --- a/previews/PR54/backends/index.html +++ b/previews/PR54/backends/index.html @@ -1,2 +1,2 @@ -Backends · ManifoldDiff.jl
GitHub

Differentiation backends

Euclidian backends

Euclidian backend objects can be taken from ADTypes.jl. See the documentation of DifferentiationInterface.jl for the list of supported packages.

EmbeddedDiff

ManifoldDiff.ExplicitEmbeddedBackend — Type
ExplicitEmbeddedBackend{TF<:NamedTuple}

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

source
+Backends · ManifoldDiff.jl
GitHub

Differentiation backends

Euclidian backends

Euclidian backend objects can be taken from ADTypes.jl. See the documentation of DifferentiationInterface.jl for the list of supported packages.

EmbeddedDiff

ManifoldDiff.ExplicitEmbeddedBackend — Type
ExplicitEmbeddedBackend{TF<:NamedTuple}

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

source
diff --git a/previews/PR54/basic_usage/index.html b/previews/PR54/basic_usage/index.html index decf444..5277333 100644 --- a/previews/PR54/basic_usage/index.html +++ b/previews/PR54/basic_usage/index.html @@ -3,9 +3,9 @@ using DifferentiationInterface using Manifolds, FiniteDifferences, ForwardDiff, Zygote -rb_onb_fd51 = ManifoldDiff.TangentDiffBackend(AutoFiniteDifferences(central_fdm(5, 1))) -rb_onb_fwdd = ManifoldDiff.TangentDiffBackend(AutoForwardDiff()) -rb_proj_zyg = ManifoldDiff.RiemannianProjectionBackend(AutoZygote()) +rb_onb_fd51 = TangentDiffBackend(AutoFiniteDifferences(central_fdm(5, 1))) +rb_onb_fwdd = TangentDiffBackend(AutoForwardDiff()) +rb_proj_zyg = RiemannianProjectionBackend(AutoZygote()) s2 = Sphere(2) @@ -18,4 +18,4 @@ println(ManifoldDiff.gradient(s2, f, q, rb_onb_fwdd)) println(ManifoldDiff.gradient(s2, f, q, rb_proj_zyg))
[3.999999999999511, 0.0, 7.999999999999624]
 [4.0, 0.0, 8.0]
-[4.0, 0.0, 8.0]

TangentDiffBackend reduces dimensionality of the problem to the intrinsic dimension of the manifold, while RiemannianProjectionBackend relies on converting Euclidean gradient in the embedding to the Riemannian one.

+[4.0, 0.0, 8.0]

TangentDiffBackend reduces dimensionality of the problem to the intrinsic dimension of the manifold, while RiemannianProjectionBackend relies on converting Euclidean gradient in the embedding to the Riemannian one.

diff --git a/previews/PR54/index.html b/previews/PR54/index.html index c604e6c..da55ca2 100644 --- a/previews/PR54/index.html +++ b/previews/PR54/index.html @@ -1,2 +1,2 @@ -Home · ManifoldDiff.jl
GitHub

ManifoldDiff

The package ManifoldDiff aims to provide automatic calculation of Riemannian gradients of functions defined on manifolds. It builds upon Manifolds.jl.

Naming scheme

Providing a derivative, differential or gradient for a given function, this package adds that information to the function name. For example

  • grad_f for a gradient $\operatorname{grad} f$
  • subgrad_f for a subgradient from the subdifferential$\partial f$
  • differential_f for $Df$ (also called pushforward)
  • differential_f_variable if f has multiple variables / parameters, since a usual writing in math is $f_x$ in this case
  • adjoint_differential_f for pullbacks
  • adjoint_differential_f_variable if f has multiple variables / parameters
  • f_derivative for $f'$
  • jacobian_f for Jacobian matrix of $f$.
  • jacobian_f_variable if f has multiple parameters.

the scheme is not completely fixed but tries to follow the mathematical notation.

+Home · ManifoldDiff.jl
GitHub

ManifoldDiff

The package ManifoldDiff aims to provide automatic calculation of Riemannian gradients of functions defined on manifolds. It builds upon Manifolds.jl.

Naming scheme

Providing a derivative, differential or gradient for a given function, this package adds that information to the function name. For example

  • grad_f for a gradient $\operatorname{grad} f$
  • subgrad_f for a subgradient from the subdifferential$\partial f$
  • differential_f for $Df$ (also called pushforward)
  • differential_f_variable if f has multiple variables / parameters, since a usual writing in math is $f_x$ in this case
  • adjoint_differential_f for pullbacks
  • adjoint_differential_f_variable if f has multiple variables / parameters
  • f_derivative for $f'$
  • jacobian_f for Jacobian matrix of $f$.
  • jacobian_f_variable if f has multiple parameters.

the scheme is not completely fixed but tries to follow the mathematical notation.

diff --git a/previews/PR54/internals/index.html b/previews/PR54/internals/index.html index 1f885cf..23b0530 100644 --- a/previews/PR54/internals/index.html +++ b/previews/PR54/internals/index.html @@ -1,2 +1,2 @@ -Internals · ManifoldDiff.jl
GitHub

Internal functions

ManifoldDiff._hessian — Function
_hessian(f, p[, backend])

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

This function calculates plain Euclidean Hessian.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
ManifoldDiff._jacobian — Function
_jacobian(f, p[, backend])

Compute the Jacobian of a callable f at point p computed using the given backend. 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.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
ManifoldDiff._gradient — Function
_gradient(f, p[, backend])

Compute the gradient of a callable f at point p computed using the given backend. 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.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
ManifoldDiff._derivative — Function
_derivative(f, t[, backend])

Compute the derivative of a callable f at time t computed using the given backend. 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.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
+Internals · ManifoldDiff.jl
GitHub

Internal functions

ManifoldDiff._hessian — Function
_hessian(f, p[, backend])

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

This function calculates plain Euclidean Hessian.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
ManifoldDiff._jacobian — Function
_jacobian(f, p[, backend])

Compute the Jacobian of a callable f at point p computed using the given backend. 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.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
ManifoldDiff._gradient — Function
_gradient(f, p[, backend])

Compute the gradient of a callable f at point p computed using the given backend. 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.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
ManifoldDiff._derivative — Function
_derivative(f, t[, backend])

Compute the derivative of a callable f at time t computed using the given backend. 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.

Note

Not specifying the backend explicitly will usually result in a type instability and decreased performance.

source
diff --git a/previews/PR54/library/index.html b/previews/PR54/library/index.html index baf4fd3..92da840 100644 --- a/previews/PR54/library/index.html +++ b/previews/PR54/library/index.html @@ -1,15 +1,15 @@ Library of functions · ManifoldDiff.jl
GitHub

Different library functions

Documentation for ManifoldDiff.jl's methods and types for finite differences and automatic differentiation.

Derivatives

ManifoldDiff.geodesic_derivative — Method
Y = geodesic_derivative(M, p, X, t::Number; γt = geodesic(M, p, X, t))
-geodesic_derivative!(M, Y, p, X, t::Number; γt = geodesic(M, p, X, t))

Evaluate the derivative of the geodesic $γ(t)$ with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ at $t$. The formula reads

\[\dot γ(t) = \mathcal P_{γ(t) \gets p} X\]

where $\mathcal P$ denotes the parallel transport. This computation can also be done in-place of $Y$.

Optional Parameters

  • γt – (geodesic(M, p, X, t)) the point on the geodesic at $t$. This way if the point was computed earlier it can be resued here.
source
ManifoldDiff.shortest_geodesic_derivative — Method
Y = shortest_geodesic_derivative(M, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))
-shortest_geodesic_derivative!(M, Y, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))

Evaluate the derivative of the shortest geodesic $γ(t)$ with $γ_{p,q}(0) = p$ and $\dot γ_{p,q}(1) = q$ at $t$. The formula reads

\[\dot γ(t) = \mathcal P_{γ(t) \gets p} \log_pq\]

where $\mathcal P$ denotes the parallel transport. This computation can also be done in-place of $Y$.

Optional Parameters

  • γt = geodesic(M, p, X, t) the point on the geodesic at $t$. This way if the point was computed earlier it can be resued here.
source

Differentials and their adjoints

ManifoldDiff.differential_exp_argument_lie_approx — Method
differential_exp_argument_lie_approx(M::AbstractManifold, p, X, Y; n)

Approximate differential of exponential map based on Lie group exponential. The formula reads (see Theorem 1.7 of [Helgason1978])

\[D_X \exp_{p}(X)[Y] = (\mathrm{d}L_{\exp_e(X)})_e\left(\sum_{k=0}^{n}\frac{(-1)^k}{(k+1)!}(\operatorname{ad}_X)^k(Y)\right)\]

where $(\operatorname{ad}_X)^k(Y)$ is defined recursively as $(\operatorname{ad}_X)^0(Y) = Y$, $\operatorname{ad}_X^{k+1}(Y) = [X, \operatorname{ad}_X^k(Y)]$.

source
ManifoldDiff.differential_inverse_retract_argument_fd_approx — Method
differential_inverse_retract_argument_fd_approx(
+geodesic_derivative!(M, Y, p, X, t::Number; γt = geodesic(M, p, X, t))

Evaluate the derivative of the geodesic $γ(t)$ with $γ_{p,X}(0) = p$ and $\dot γ_{p,X}(0) = X$ at $t$. The formula reads

\[\dot γ(t) = \mathcal P_{γ(t) \gets p} X\]

where $\mathcal P$ denotes the parallel transport. This computation can also be done in-place of $Y$.

Optional Parameters

  • γt – (geodesic(M, p, X, t)) the point on the geodesic at $t$. This way if the point was computed earlier it can be resued here.
source
ManifoldDiff.shortest_geodesic_derivative — Method
Y = shortest_geodesic_derivative(M, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))
+shortest_geodesic_derivative!(M, Y, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))

Evaluate the derivative of the shortest geodesic $γ(t)$ with $γ_{p,q}(0) = p$ and $\dot γ_{p,q}(1) = q$ at $t$. The formula reads

\[\dot γ(t) = \mathcal P_{γ(t) \gets p} \log_pq\]

where $\mathcal P$ denotes the parallel transport. This computation can also be done in-place of $Y$.

Optional Parameters

  • γt = geodesic(M, p, X, t) the point on the geodesic at $t$. This way if the point was computed earlier it can be resued here.
source

Differentials and their adjoints

ManifoldDiff.differential_exp_argument_lie_approx — Method
differential_exp_argument_lie_approx(M::AbstractManifold, p, X, Y; n)

Approximate differential of exponential map based on Lie group exponential. The formula reads (see Theorem 1.7 of [Helgason1978])

\[D_X \exp_{p}(X)[Y] = (\mathrm{d}L_{\exp_e(X)})_e\left(\sum_{k=0}^{n}\frac{(-1)^k}{(k+1)!}(\operatorname{ad}_X)^k(Y)\right)\]

where $(\operatorname{ad}_X)^k(Y)$ is defined recursively as $(\operatorname{ad}_X)^0(Y) = Y$, $\operatorname{ad}_X^{k+1}(Y) = [X, \operatorname{ad}_X^k(Y)]$.

source
ManifoldDiff.differential_inverse_retract_argument_fd_approx — Method
differential_inverse_retract_argument_fd_approx(
     M::AbstractManifold,
     p,
     q,
@@ -17,74 +17,74 @@
     retr::AbstractRetractionMethod = default_retraction_method(M),
     invretr::AbstractInverseRetractionMethod = default_inverse_retraction_method(M),
     h::Real=sqrt(eps(eltype(X))),
-)

Approximate the differential of the inverse retraction invretr using a finite difference formula (see Eq. (16) in [Zim20]

\[\frac{\operatorname{retr}^{-1}_q(\operatorname{retr}_p(hX)) - \operatorname{retr}^{-1}_q(\operatorname{retr}_p(-hX))}{2h}\]

where $h$ is the finite difference step h, $\operatorname{retr}^{-1}$ is the inverse retraction invretr and $\operatorname{retr}$ is the retraction retr.

source
ManifoldDiff.AbstractProjector — Type
abstract type AbstractProjector end

An abstract type for projectors on a tangent space $T_pM$ for fixed values of p and M. Calling a projector on a tangent vector returns a new tangent vector:

(Π::AbstractProjector)(X) -> Y

Projectors assume that X is a valid vector from $T_pM$.

source
ManifoldDiff.CoprojectorOntoVector — Type
CoprojectorOntoVector{TM<:AbstractManifold,TP,TX}

A structure that represents projector onto the subspace of the tangent space at p from manifold M othogonal to vector X of unit norm.

Constructor

CoprojectorOntoVector(M::AbstractManifold, p, X)

source
ManifoldDiff.ProjectorOntoVector — Type
ProjectorOntoVector{TM<:AbstractManifold,TP,TX}

A structure that represents projector onto the subspace of the tangent space at p from manifold M spanned by tangent vector X of unit norm.

Constructor

ProjectorOntoVector(M::AbstractManifold, p, X)

source

Gradients

ManifoldDiff.grad_distance — Function
grad_distance(M, q, p[, c=2])
-grad_distance!(M, X, q, p[, c=2])

compute the (sub)gradient of the distance (default: squared), in place of X.

\[f(p) = \frac{1}{c} d^c_{\mathcal M}(p, q)\]

to a fixed point q on the manifold M and c is an integer. The (sub-)gradient reads

\[\operatorname{grad}f(p) = -d_{\mathcal M}^{c-2}(p, q)\log_pq\]

for $c\neq 1$ or $p\neq q$. Note that for the remaining case $c=1$, $p=q$, the function is not differentiable. In this case, the function returns the corresponding zero tangent vector, since this is an element of the subdifferential.

Optional

  • c – (2) the exponent of the distance, i.e. the default is the squared distance
source
ManifoldDiff.subgrad_distance — Function
subgrad_distance(M, q, p[, c = 2; atol = 0])
-subgrad_distance!(M, X, q, p[, c = 2; atol = 0])

compute the subgradient of the distance (in place of X)

\[f(p) = \frac{1}{c} d^c_{\mathcal M}(p, q)\]

to a fixed point q on the manifold M and c is an integer. The subgradient reads

\[\partial f(p) = -d_{\mathcal M}^{c-2}(p, q)\log_pq\]

for $c\neq 1$ or $p\neq q$. Note that for the remaining case $c=1$, $p=q$, the function is not differentiable. In this case, the subgradient is given by a tangent vector at p with norm less than or equal to one.

Optional

  • c – (2) the exponent of the distance, i.e. the default is the distance
  • atol – (0) the tolerance to use when evaluating the distance between p and q.
source

Jacobi fields

ManifoldDiff.adjoint_Jacobi_field — Method
Y = adjoint_Jacobi_field(M, p, q, t, X, β)
-adjoint_Jacobi_field!(M, Y, p, q, t, X, β)

Compute the AdjointJacobiField $J$ along the geodesic $γ_{p,q}$ on the manifold $\mathcal M$ with initial conditions (depending on the application) $X ∈ T_{γ_{p,q}(t)}\mathcal M$ and weights $β$. The result is a vector $Y ∈ T_p\mathcal M$. The main difference to jacobi_field is the, that the input X and the output Y switched tangent spaces. The computation can be done in place of Y.

For details see jacobi_field

source
ManifoldDiff.jacobi_field — Method
Y = jacobi_field(M, p, q, t, X, β)
-jacobi_field!(M, Y, p, q, t, X, β)

compute the Jacobi field $J$ along the geodesic $γ_{p,q}$ on the manifold $\mathcal M$ with initial conditions (depending on the application) $X ∈ T_p\mathcal M$ and weights $β$. The result is a tangent vector Y from $T_{γ_{p,q}(t)}\mathcal M$. The computation can be done in place of Y.

See also

adjoint_Jacobi_field

source
ManifoldDiff.βdifferential_exp_argument — Method
βdifferential_exp_argument(κ,t,d)

weights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point $D_X \exp_p X[Y]$. They are

\[β(κ) = \begin{cases} +)

Approximate the differential of the inverse retraction invretr using a finite difference formula (see Eq. (16) in [Zim20]

\[\frac{\operatorname{retr}^{-1}_q(\operatorname{retr}_p(hX)) - \operatorname{retr}^{-1}_q(\operatorname{retr}_p(-hX))}{2h}\]

where $h$ is the finite difference step h, $\operatorname{retr}^{-1}$ is the inverse retraction invretr and $\operatorname{retr}$ is the retraction retr.

source
ManifoldDiff.AbstractProjector — Type
abstract type AbstractProjector end

An abstract type for projectors on a tangent space $T_pM$ for fixed values of p and M. Calling a projector on a tangent vector returns a new tangent vector:

(Π::AbstractProjector)(X) -> Y

Projectors assume that X is a valid vector from $T_pM$.

source
ManifoldDiff.CoprojectorOntoVector — Type
CoprojectorOntoVector{TM<:AbstractManifold,TP,TX}

A structure that represents projector onto the subspace of the tangent space at p from manifold M othogonal to vector X of unit norm.

Constructor

CoprojectorOntoVector(M::AbstractManifold, p, X)

source
ManifoldDiff.ProjectorOntoVector — Type
ProjectorOntoVector{TM<:AbstractManifold,TP,TX}

A structure that represents projector onto the subspace of the tangent space at p from manifold M spanned by tangent vector X of unit norm.

Constructor

ProjectorOntoVector(M::AbstractManifold, p, X)

source

Gradients

ManifoldDiff.grad_distance — Function
grad_distance(M, q, p[, c=2])
+grad_distance!(M, X, q, p[, c=2])

compute the (sub)gradient of the distance (default: squared), in place of X.

\[f(p) = \frac{1}{c} d^c_{\mathcal M}(p, q)\]

to a fixed point q on the manifold M and c is an integer. The (sub-)gradient reads

\[\operatorname{grad}f(p) = -d_{\mathcal M}^{c-2}(p, q)\log_pq\]

for $c\neq 1$ or $p\neq q$. Note that for the remaining case $c=1$, $p=q$, the function is not differentiable. In this case, the function returns the corresponding zero tangent vector, since this is an element of the subdifferential.

Optional

  • c – (2) the exponent of the distance, i.e. the default is the squared distance
source
ManifoldDiff.subgrad_distance — Function
subgrad_distance(M, q, p[, c = 2; atol = 0])
+subgrad_distance!(M, X, q, p[, c = 2; atol = 0])

compute the subgradient of the distance (in place of X)

\[f(p) = \frac{1}{c} d^c_{\mathcal M}(p, q)\]

to a fixed point q on the manifold M and c is an integer. The subgradient reads

\[\partial f(p) = -d_{\mathcal M}^{c-2}(p, q)\log_pq\]

for $c\neq 1$ or $p\neq q$. Note that for the remaining case $c=1$, $p=q$, the function is not differentiable. In this case, the subgradient is given by a tangent vector at p with norm less than or equal to one.

Optional

  • c – (2) the exponent of the distance, i.e. the default is the distance
  • atol – (0) the tolerance to use when evaluating the distance between p and q.
source

Jacobi fields

ManifoldDiff.adjoint_Jacobi_field — Method
Y = adjoint_Jacobi_field(M, p, q, t, X, β)
+adjoint_Jacobi_field!(M, Y, p, q, t, X, β)

Compute the AdjointJacobiField $J$ along the geodesic $γ_{p,q}$ on the manifold $\mathcal M$ with initial conditions (depending on the application) $X ∈ T_{γ_{p,q}(t)}\mathcal M$ and weights $β$. The result is a vector $Y ∈ T_p\mathcal M$. The main difference to jacobi_field is the, that the input X and the output Y switched tangent spaces. The computation can be done in place of Y.

For details see jacobi_field

source
ManifoldDiff.jacobi_field — Method
Y = jacobi_field(M, p, q, t, X, β)
+jacobi_field!(M, Y, p, q, t, X, β)

compute the Jacobi field $J$ along the geodesic $γ_{p,q}$ on the manifold $\mathcal M$ with initial conditions (depending on the application) $X ∈ T_p\mathcal M$ and weights $β$. The result is a tangent vector Y from $T_{γ_{p,q}(t)}\mathcal M$. The computation can be done in place of Y.

See also

adjoint_Jacobi_field

source
ManifoldDiff.βdifferential_log_argument — Method
βdifferential_log_argument(κ,t,d)

weights for the JacobiField corresponding to the differential of the logarithmic map with respect to its argument $D_q \log_p q[X]$. They are

\[β(κ) = \begin{cases} \frac{ d\sqrt{-κ} }{\sinh(d\sqrt{-κ})}&\text{ if }κ < 0,\\ 1 & \text{ if } κ = 0,\\ \frac{ d\sqrt{κ} }{\sin(d\sqrt{κ})}&\text{ if }κ > 0. -\end{cases}\]

See also

differential_log_basepoint, jacobi_field

source
ManifoldDiff.βdifferential_log_basepoint — Method
βdifferential_log_basepoint(κ,t,d)

weights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point $D_p \log_p q[X]$. They are

\[β(κ) = \begin{cases} -\sqrt{-κ}d\frac{\cosh(d\sqrt{-κ})}{\sinh(d\sqrt{-κ})}&\text{ if }κ < 0,\\ -1 & \text{ if } κ = 0,\\ -\sqrt{κ}d\frac{\cos(d\sqrt{κ})}{\sin(d\sqrt{κ})}&\text{ if }κ > 0. -\end{cases}\]

See also

differential_log_argument, differential_log_argument, jacobi_field

source
ManifoldDiff.βdifferential_shortest_geodesic_startpoint — Method
βdifferential_shortest_geodesic_startpoint(κ,t,d)

weights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point $D_x g(t;p,q)[X]$. They are

\[β(κ) = \begin{cases} \frac{\sinh(d(1-t)\sqrt{-κ})}{\sinh(d\sqrt{-κ})} &\text{ if }κ < 0,\\ 1-t & \text{ if } κ = 0,\\ \frac{\sin((1-t)d\sqrt{κ})}{\sinh(d\sqrt{κ})} &\text{ if }κ > 0. -\end{cases}\]

Due to a symmetry argument, these are also used to compute $D_q g(t; p,q)[η]$

See also

differential_shortest_geodesic_endpoint, differential_shortest_geodesic_startpoint, jacobi_field

source

Jacobians

Jacobians

ManifoldDiff.allocate_jacobian — Method
allocate_jacobian(
     M_domain::AbstractManifold,
     M_codomain::AbstractManifold,
     f,
     p;
     basis_domain::AbstractBasis = DefaultOrthonormalBasis(),
     basis_codomain::AbstractBasis = DefaultOrthonormalBasis(),
-)

Allocate Jacobian of function f with given domain and codomain at point p. basis_domain and basis_codomain denote bases of tangent spaces at, respectively, p and f(p).

source
ManifoldDiff.jacobian_exp_argument — Function
jacobian_exp_argument(
+)

Allocate Jacobian of function f with given domain and codomain at point p. basis_domain and basis_codomain denote bases of tangent spaces at, respectively, p and f(p).

source
ManifoldDiff.jacobian_exp_argument — Function
jacobian_exp_argument(
     M::AbstractManifold,
     p,
     X,
     basis_domain::AbstractBasis=DefaultOrthonormalBasis(),
     basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),
-)

Compute Jacobian of the exponential map with respect to its argument (tangent vector). Differential of the exponential map is here considered as a function from $T_p \mathcal{M}$ to $T_{\exp_p X} \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source
ManifoldDiff.jacobian_exp_basepoint — Function
jacobian_exp_basepoint(
+)

Compute Jacobian of the exponential map with respect to its argument (tangent vector). Differential of the exponential map is here considered as a function from $T_p \mathcal{M}$ to $T_{\exp_p X} \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source
ManifoldDiff.jacobian_exp_basepoint — Function
jacobian_exp_basepoint(
     M::AbstractManifold,
     p,
     X,
     basis_domain::AbstractBasis=DefaultOrthonormalBasis(),
     basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),
-)

Compute Jacobian of the exponential map with respect to the basepoint. Differential of the exponential map is here considered as a function from $T_p \mathcal{M}$ to $T_{\exp_p X} \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source
ManifoldDiff.jacobian_log_argument — Function
jacobian_log_argument(
+)

Compute Jacobian of the exponential map with respect to the basepoint. Differential of the exponential map is here considered as a function from $T_p \mathcal{M}$ to $T_{\exp_p X} \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source
ManifoldDiff.jacobian_log_argument — Function
jacobian_log_argument(
     M::AbstractManifold,
     p,
     q,
     basis_domain::AbstractBasis=DefaultOrthonormalBasis(),
     basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),
-)

Compute Jacobian of the logarithmic map with respect to its argument (point q). Differential of the logarithmic map is here considered as a function from $T_q \mathcal{M}$ to $T_p \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source
ManifoldDiff.jacobian_log_basepoint — Function
jacobian_log_basepoint(
+)

Compute Jacobian of the logarithmic map with respect to its argument (point q). Differential of the logarithmic map is here considered as a function from $T_q \mathcal{M}$ to $T_p \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source
ManifoldDiff.jacobian_log_basepoint — Function
jacobian_log_basepoint(
     M::AbstractManifold,
     p,
     q,
     basis_domain::AbstractBasis=DefaultOrthonormalBasis(),
     basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),
-)

Compute Jacobian of the logarithmic map with respect to the basepoint. Differential of the logarithmic map is here considered as a function from $T_q \mathcal{M}$ to $T_p \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source

Riemannian differentials

ManifoldDiff.RiemannianProjectionBackend — Type
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

see also riemannian_gradient and [AMS08], Section 3.6.1 for a derivation on submanifolds.

source
ManifoldDiff.TangentDiffBackend — Type
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 a (Euclidean) backend.

Constructor

TangentDiffBackend(diff_backend)

where diff_backend is a (Euclidean) backend to be used on the tangent space.

With the keyword arguments

source
ManifoldDiff.differential — Method
differential(M::AbstractManifold, f, t::Real, backend)
-differential!(M::AbstractManifold, f, X, t::Real, backend)

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.

source
ManifoldDiff.gradient — Method
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.

source
ManifoldDiff.gradient — Method
gradient(M, f, p, backend::TangentDiffBackend)

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

\[ f(\operatorname{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

source
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M, p, eG, eH, X)
+)

Compute Jacobian of the logarithmic map with respect to the basepoint. Differential of the logarithmic map is here considered as a function from $T_q \mathcal{M}$ to $T_p \mathcal{M}$. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.

source

Riemannian differentials

ManifoldDiff.RiemannianProjectionBackend — Type
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

see also riemannian_gradient and [AMS08], Section 3.6.1 for a derivation on submanifolds.

source
ManifoldDiff.TangentDiffBackend — Type
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 a (Euclidean) backend.

Constructor

TangentDiffBackend(diff_backend)

where diff_backend is a (Euclidean) backend to be used on the tangent space.

With the keyword arguments

source
ManifoldDiff.differential — Method
differential(M::AbstractManifold, f, t::Real, backend)
+differential!(M::AbstractManifold, f, X, t::Real, backend)

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.

source
ManifoldDiff.gradient — Method
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.

source
ManifoldDiff.gradient — Method
gradient(M, f, p, backend::TangentDiffBackend)

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

\[ f(\operatorname{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

source
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M, p, eG, eH, X)
 riemannian_Hessian!(M, Y, p, eG, eH, X)

Convert the Euclidean Hessian eH=$\operatorname{Hess} \tilde f(p) [X]$ of a function $f \colon \mathcal M \to \mathbb R$, which is the restriction of $\tilde f$ to $\mathcal M$, given additionally the (Euclidean) gradient $\operatorname{grad} \tilde f(p)$.

The Riemannian Hessian is then computed by

\[\operatorname{Hess} f(p)[X] = \operatorname{proj}_{T_p\mathcal M}\bigl(\operatorname{Hess} \tilde f(p)[X]) -+ \mathcal W_p\Bigl( X, \operatorname{proj}_{N_p\mathcal M}\bigl( \operatorname{grad} \tilde f (p) \bigr) \Bigr),\]

where $N_p\mathcal M$ denotes the normal space, i.e. the orthogonal complement of the tangent space in the embedding, and $\mathcal W_p$ denotes the Weingarten map. See [Bou23] for more details

The function is inspired by ehess2rhess in the Matlab package Manopt.

source
ManifoldDiff.riemannian_gradient — Method
riemannian_gradient(M, p, Y; embedding_metric=EuclideanMetric())
++ \mathcal W_p\Bigl( X, \operatorname{proj}_{N_p\mathcal M}\bigl( \operatorname{grad} \tilde f (p) \bigr) \Bigr),\]
where $N_p\mathcal M$ denotes the normal space, i.e. the orthogonal complement of the tangent space in the embedding, and $\mathcal W_p$ denotes the Weingarten map. See [Bou23] for more details
The function is inspired by ehess2rhess in the Matlab package Manopt.
source
ManifoldDiff.riemannian_gradient — Method
riemannian_gradient(M, p, Y; embedding_metric=EuclideanMetric())
 riemannian_gradient!(M, X, p, Y; embedding_metric=EuclideanMetric())

For a given gradient $Y = \operatorname{grad} \tilde f(p)$ in the embedding of a manifold, this function computes the Riemannian gradient $\operatorname{grad} f(p)$ of the function $\tilde f$ restricted to the manifold $M$. This can also be done in place of X.

By default it uses the following computation: Let the projection $Z = \operatorname{proj}_{T_p\mathcal M}(Y)$ of $Y$ onto the tangent space at $p$ be given, that is with respect to the inner product in the embedding. Then

\[⟨Z-Y, W⟩ = 0 \text{ for all } W \in T_p\mathcal M,\]

or rearranged $⟨Y,W⟩ = ⟨Z,W⟩$. We then use the definition of the Riemannian gradient

\[⟨\operatorname{grad} f(p), W⟩_p = Df(p)[X] = ⟨\operatorname{grad}f(p), W⟩ = ⟨\operatorname{proj}_{T_p\mathcal M}(\operatorname{grad}f(p)),W⟩ -\quad\text{for all } W \in T_p\mathcal M.\]

Comparing the first and the last term, the remaining computation is the function change_representer.

This method can also be implemented directly, if a more efficient/stable version is known.

The function is inspired by egrad2rgrad in the Matlab package Manopt.

source

Proximal Maps

Given a convex, lower semi-continuous function $f\colon \mathcal M \to \mathbb R$, its proximal map is defined for some $λ>0$ as [Bac14]

\[\operatorname{prox}_{λf}(p) := \operatorname*{arg\,min}_{q\in\mathcal M} \frac{1}{2λ}d^2_{\mathcal M}(p,q) + f(q).\]

Another name for the proximal map is resolvent. Intuitively this means to minimize the function $f$ while at the same timme “staying close” to the argument $p$.

ManifoldDiff.prox_distance — Function
y = prox_distance(M::AbstractManifold, λ::Real, p_data, p [, r=2])
-prox_distance!(M::AbstractManifold, q, λ::Real, p_data, p [, r=2])

Compute the proximal map $\operatorname{prox}_{λf}$ with parameter λ of $f(p) = \frac{1}{r}d_{\mathcal M}^r(p_{\mathrm{data}},p)$. For the in-place variant the computation is done in place of q.

Input

  • M a manifold M
  • λ the prox parameter, a positive real number.
  • p_data a point on M.
  • p the argument of the proximal map
  • r (2) exponent of the distance.

Output

  • q – the result of the proximal map of $f$

For more details see [WDS14]

source
  • Helgason1978

    S. Helgason, Differential Geometry, Lie Groups, and Symmetric Spaces, First Edition. Academic Press, 1978.

  • SommerFletcherPennec2020

    S. Sommer, T. Fletcher, and X. Pennec, “1 - Introduction to differential and Riemannian geometry,” in Riemannian Geometric Statistics in Medical Image Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 3–37. doi: 10.1016/B978-0-12-814725-2.00008-X.

+\quad\text{for all } W \in T_p\mathcal M.\]

Comparing the first and the last term, the remaining computation is the function change_representer.

This method can also be implemented directly, if a more efficient/stable version is known.

The function is inspired by egrad2rgrad in the Matlab package Manopt.

source

Proximal Maps

Given a convex, lower semi-continuous function $f\colon \mathcal M \to \mathbb R$, its proximal map is defined for some $λ>0$ as [Bac14]

\[\operatorname{prox}_{λf}(p) := \operatorname*{arg\,min}_{q\in\mathcal M} \frac{1}{2λ}d^2_{\mathcal M}(p,q) + f(q).\]

Another name for the proximal map is resolvent. Intuitively this means to minimize the function $f$ while at the same timme “staying close” to the argument $p$.

ManifoldDiff.prox_distance — Function
y = prox_distance(M::AbstractManifold, λ::Real, p_data, p [, r=2])
+prox_distance!(M::AbstractManifold, q, λ::Real, p_data, p [, r=2])

Compute the proximal map $\operatorname{prox}_{λf}$ with parameter λ of $f(p) = \frac{1}{r}d_{\mathcal M}^r(p_{\mathrm{data}},p)$. For the in-place variant the computation is done in place of q.

Input

  • M a manifold M
  • λ the prox parameter, a positive real number.
  • p_data a point on M.
  • p the argument of the proximal map
  • r (2) exponent of the distance.

Output

  • q – the result of the proximal map of $f$

For more details see [WDS14]

source
  • Helgason1978

    S. Helgason, Differential Geometry, Lie Groups, and Symmetric Spaces, First Edition. Academic Press, 1978.

  • SommerFletcherPennec2020

    S. Sommer, T. Fletcher, and X. Pennec, “1 - Introduction to differential and Riemannian geometry,” in Riemannian Geometric Statistics in Medical Image Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 3–37. doi: 10.1016/B978-0-12-814725-2.00008-X.

diff --git a/previews/PR54/references/index.html b/previews/PR54/references/index.html index 1d0823b..2a73795 100644 --- a/previews/PR54/references/index.html +++ b/previews/PR54/references/index.html @@ -1,2 +1,2 @@ -Literature · ManifoldDiff.jl
GitHub

Literature

[AMS08]
P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
[Bac14]
M. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014).
[Bou23]
N. Boumal. An Introduction to Optimization on Smooth Manifolds. First Edition (Cambridge University Press, 2023). Homepage to the book: nicolasboumal.net/book/index.html.
[WDS14]
A. Weinmann, L. Demaret and M. Storath. Total variation regularization for manifold-valued data. SIAM Journal on Imaging Sciences 7, 2226–2257 (2014).
[Zim20]
R. Zimmermann. Hermite Interpolation and Data Processing Errors on Riemannian Matrix Manifolds. SIAM Journal on Scientific Computing 42, A2593-A2619 (2020).
+Literature · ManifoldDiff.jl
GitHub

Literature

[AMS08]
P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
[Bac14]
M. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014).
[Bou23]
N. Boumal. An Introduction to Optimization on Smooth Manifolds. First Edition (Cambridge University Press, 2023). Homepage to the book: nicolasboumal.net/book/index.html.
[WDS14]
A. Weinmann, L. Demaret and M. Storath. Total variation regularization for manifold-valued data. SIAM Journal on Imaging Sciences 7, 2226–2257 (2014).
[Zim20]
R. Zimmermann. Hermite Interpolation and Data Processing Errors on Riemannian Matrix Manifolds. SIAM Journal on Scientific Computing 42, A2593-A2619 (2020).
diff --git a/previews/PR54/search_index.js b/previews/PR54/search_index.js index e7488b8..b391310 100644 --- a/previews/PR54/search_index.js +++ b/previews/PR54/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"references/#Literature","page":"Literature","title":"Literature","text":"","category":"section"},{"location":"references/","page":"Literature","title":"Literature","text":"P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.\n\n\n\nM. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014).\n\n\n\nN. Boumal. An Introduction to Optimization on Smooth Manifolds. First Edition (Cambridge University Press, 2023). Homepage to the book: nicolasboumal.net/book/index.html.\n\n\n\nA. Weinmann, L. Demaret and M. Storath. Total variation regularization for manifold-valued data. SIAM Journal on Imaging Sciences 7, 2226–2257 (2014).\n\n\n\nR. Zimmermann. Hermite Interpolation and Data Processing Errors on Riemannian Matrix Manifolds. SIAM Journal on Scientific Computing 42, A2593-A2619 (2020).\n\n\n\n","category":"page"},{"location":"library/#Different-library-functions","page":"Library of functions","title":"Different library functions","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Documentation for ManifoldDiff.jl's methods and types for finite differences and automatic differentiation.","category":"page"},{"location":"library/#Derivatives","page":"Library of functions","title":"Derivatives","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"derivatives.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.geodesic_derivative-Tuple{Any, Any, Any, Number}","page":"Library of functions","title":"ManifoldDiff.geodesic_derivative","text":"Y = geodesic_derivative(M, p, X, t::Number; γt = geodesic(M, p, X, t))\ngeodesic_derivative!(M, Y, p, X, t::Number; γt = geodesic(M, p, X, t))\n\nEvaluate the derivative of the geodesic γ(t) with γ_pX(0) = p and dot γ_pX(0) = X at t. The formula reads\n\ndot γ(t) = mathcal P_γ(t) gets p X\n\nwhere mathcal P denotes the parallel transport. This computation can also be done in-place of Y.\n\nOptional Parameters\n\nγt – (geodesic(M, p, X, t)) the point on the geodesic at t. This way if the point was computed earlier it can be resued here.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.shortest_geodesic_derivative-Tuple{Any, Any, Any, Number}","page":"Library of functions","title":"ManifoldDiff.shortest_geodesic_derivative","text":"Y = shortest_geodesic_derivative(M, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))\nshortest_geodesic_derivative!(M, Y, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))\n\nEvaluate the derivative of the shortest geodesic γ(t) with γ_pq(0) = p and dot γ_pq(1) = q at t. The formula reads\n\ndot γ(t) = mathcal P_γ(t) gets p log_pq\n\nwhere mathcal P denotes the parallel transport. This computation can also be done in-place of Y.\n\nOptional Parameters\n\nγt = geodesic(M, p, X, t) the point on the geodesic at t. This way if the point was computed earlier it can be resued here.\n\n\n\n\n\n","category":"method"},{"location":"library/#Differentials-and-their-adjoints","page":"Library of functions","title":"Differentials and their adjoints","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"adjoint_differentials.jl\",\"differentials.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.adjoint_differential_exp_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_exp_argument","text":"adjoint_differential_exp_argument(M, p, X, Y)\nadjoint_differential_exp_argument!(M, Z, p, X, Y)\n\nCompute the adjoint of D_Xexp_p XY (in place of Z). Note that X T_p(T_pmathcal M) = T_pmathcal M is still a tangent vector.\n\nSee also\n\ndifferential_exp_argument, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_exp_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_exp_basepoint","text":"adjoint_differential_exp_basepoint(M, p, X, Y)\nadjoint_differential_exp_basepoint!(M, Z, p, X, Y)\n\nComputes the adjoint of D_p exp_p XY (in place of Z).\n\nSee also\n\ndifferential_exp_basepoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_log_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_log_argument","text":"adjoint_differential_log_argument(M, p, q, X)\nadjoint_differential_log_argument!(M, Y, p, q, X)\n\nCompute the adjoint of D_q log_p qX (in place of Y).\n\nSee also\n\ndifferential_log_argument, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_log_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_log_basepoint","text":"adjoint_differential_log_basepoint(M, p, q, X)\nadjoint_differential_log_basepoint!(M, Y, p, q, X)\n\ncomputes the adjoint of D_p log_p qX (in place of Y).\n\nSee also\n\ndifferential_log_basepoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_shortest_geodesic_endpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_shortest_geodesic_endpoint","text":"adjoint_differential_shortest_geodesic_endpoint(M, p, q, t, X)\nadjoint_differential_shortest_geodesic_endpoint!(M, Y, p, q, t, X)\n\nCompute the adjoint of D_q γ(t p q)X (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_endpoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_shortest_geodesic_startpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_shortest_geodesic_startpoint","text":"adjoint_differential_shortest_geodesic_startpoint(M, p, q, t, X)\nadjoint_differential_shortest_geodesic_startpoint!(M, Y, p, q, t, X)\n\nCompute the adjoint of D_p γ(t p q)X (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_startpoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_exp_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_exp_argument","text":"Z = differential_exp_argument(M, p, X, Y)\ndifferential_exp_argument!(M, Z, p, X, Y)\n\nCompute D_Xexp_pXY (in place of Z). Note that X T_X(T_pmathcal M) = T_pmathcal M is still a tangent vector.\n\nSee also\n\ndifferential_exp_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_exp_argument_lie_approx-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_exp_argument_lie_approx","text":"differential_exp_argument_lie_approx(M::AbstractManifold, p, X, Y; n)\n\nApproximate differential of exponential map based on Lie group exponential. The formula reads (see Theorem 1.7 of [Helgason1978])\n\nD_X exp_p(X)Y = (mathrmdL_exp_e(X))_eleft(sum_k=0^nfrac(-1)^k(k+1)(operatornamead_X)^k(Y)right)\n\nwhere (operatornamead_X)^k(Y) is defined recursively as (operatornamead_X)^0(Y) = Y, operatornamead_X^k+1(Y) = X operatornamead_X^k(Y).\n\n[Helgason1978]: S. Helgason, Differential Geometry, Lie Groups, and Symmetric Spaces, First Edition. Academic Press, 1978.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_exp_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_exp_basepoint","text":"Z = differential_exp_basepoint(M, p, X, Y)\ndifferential_exp_basepoint!(M, Z, p, X, Y)\n\nCompute D_pexp_p XY (in place of Z).\n\nSee also\n\ndifferential_exp_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_inverse_retract_argument_fd_approx-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_inverse_retract_argument_fd_approx","text":"differential_inverse_retract_argument_fd_approx(\n M::AbstractManifold,\n p,\n q,\n X;\n retr::AbstractRetractionMethod = default_retraction_method(M),\n invretr::AbstractInverseRetractionMethod = default_inverse_retraction_method(M),\n h::Real=sqrt(eps(eltype(X))),\n)\n\nApproximate the differential of the inverse retraction invretr using a finite difference formula (see Eq. (16) in [Zim20]\n\nfracoperatornameretr^-1_q(operatornameretr_p(hX)) - operatornameretr^-1_q(operatornameretr_p(-hX))2h\n\nwhere h is the finite difference step h, operatornameretr^-1 is the inverse retraction invretr and operatornameretr is the retraction retr.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_log_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_log_argument","text":"Y = differential_log_argument(M, p, q, X)\ndifferential_log_argument!(M, Y, p, q, X)\n\ncomputes D_qlog_pqX (in place of Y).\n\nSee also\n\ndifferential_log_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_log_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_log_basepoint","text":"Y = differential_log_basepoint(M, p, q, X)\ndifferential_log_basepoint!(M, Y, p, q, X)\n\ncomputes D_plog_pqX (in place of Y).\n\nSee also\n\ndifferential_log_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_shortest_geodesic_endpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.differential_shortest_geodesic_endpoint","text":"Y = differential_shortest_geodesic_endpoint(M, p, q, t, X)\ndifferential_shortest_geodesic_endpoint!(M, Y, p, q, t, X)\n\nCompute D_qγ(tpq)X (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_startpoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_shortest_geodesic_startpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.differential_shortest_geodesic_startpoint","text":"Y = differential_shortest_geodesic_startpoint(M, p, q, t, X)\ndifferential_shortest_geodesic_startpoint!(M, Y, p, q, t, X)\n\nCompute D_p γ(tpq)η (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_endpoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"diagonalizing_projectors.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.AbstractProjector","page":"Library of functions","title":"ManifoldDiff.AbstractProjector","text":"abstract type AbstractProjector end\n\nAn abstract type for projectors on a tangent space T_pM for fixed values of p and M. Calling a projector on a tangent vector returns a new tangent vector:\n\n(Π::AbstractProjector)(X) -> Y\n\nProjectors assume that X is a valid vector from T_pM.\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.CoprojectorOntoVector","page":"Library of functions","title":"ManifoldDiff.CoprojectorOntoVector","text":"CoprojectorOntoVector{TM<:AbstractManifold,TP,TX}\n\nA structure that represents projector onto the subspace of the tangent space at p from manifold M othogonal to vector X of unit norm.\n\nConstructor\n\nCoprojectorOntoVector(M::AbstractManifold, p, X)\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.ProjectorOntoVector","page":"Library of functions","title":"ManifoldDiff.ProjectorOntoVector","text":"ProjectorOntoVector{TM<:AbstractManifold,TP,TX}\n\nA structure that represents projector onto the subspace of the tangent space at p from manifold M spanned by tangent vector X of unit norm.\n\nConstructor\n\nProjectorOntoVector(M::AbstractManifold, p, X)\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.diagonalizing_projectors-Tuple{AbstractManifold, Any, Any}","page":"Library of functions","title":"ManifoldDiff.diagonalizing_projectors","text":"diagonalizing_projectors(M::AbstractManifold, p, X)\n\nCompute eigenvalues of the Jacobi operator Y R(YX)X, where R is the curvature endomorphism, together with projectors onto eigenspaces of the operator. Projectors are objects of subtypes of AbstractProjector.\n\nBy default constructs projectors using the DiagonalizingOrthonormalBasis.\n\n\n\n\n\n","category":"method"},{"location":"library/#Gradients","page":"Library of functions","title":"Gradients","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"gradients.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.grad_distance","page":"Library of functions","title":"ManifoldDiff.grad_distance","text":"grad_distance(M, q, p[, c=2])\ngrad_distance!(M, X, q, p[, c=2])\n\ncompute the (sub)gradient of the distance (default: squared), in place of X.\n\nf(p) = frac1c d^c_mathcal M(p q)\n\nto a fixed point q on the manifold M and c is an integer. The (sub-)gradient reads\n\noperatornamegradf(p) = -d_mathcal M^c-2(p q)log_pq\n\nfor cneq 1 or pneq q. Note that for the remaining case c=1, p=q, the function is not differentiable. In this case, the function returns the corresponding zero tangent vector, since this is an element of the subdifferential.\n\nOptional\n\nc – (2) the exponent of the distance, i.e. the default is the squared distance\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.subgrad_distance","page":"Library of functions","title":"ManifoldDiff.subgrad_distance","text":"subgrad_distance(M, q, p[, c = 2; atol = 0])\nsubgrad_distance!(M, X, q, p[, c = 2; atol = 0])\n\ncompute the subgradient of the distance (in place of X)\n\nf(p) = frac1c d^c_mathcal M(p q)\n\nto a fixed point q on the manifold M and c is an integer. The subgradient reads\n\npartial f(p) = -d_mathcal M^c-2(p q)log_pq\n\nfor cneq 1 or pneq q. Note that for the remaining case c=1, p=q, the function is not differentiable. In this case, the subgradient is given by a tangent vector at p with norm less than or equal to one.\n\nOptional\n\nc – (2) the exponent of the distance, i.e. the default is the distance\natol – (0) the tolerance to use when evaluating the distance between p and q.\n\n\n\n\n\n","category":"function"},{"location":"library/#Jacobi-fields","page":"Library of functions","title":"Jacobi fields","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"Jacobi_fields.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.adjoint_Jacobi_field-Union{Tuple{Tβ}, Tuple{AbstractManifold, Any, Any, Any, Any, Tβ}} where Tβ","page":"Library of functions","title":"ManifoldDiff.adjoint_Jacobi_field","text":"Y = adjoint_Jacobi_field(M, p, q, t, X, β)\nadjoint_Jacobi_field!(M, Y, p, q, t, X, β)\n\nCompute the AdjointJacobiField J along the geodesic γ_pq on the manifold mathcal M with initial conditions (depending on the application) X T_γ_pq(t)mathcal M and weights β. The result is a vector Y T_pmathcal M. The main difference to jacobi_field is the, that the input X and the output Y switched tangent spaces. The computation can be done in place of Y.\n\nFor details see jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.jacobi_field-Union{Tuple{Tβ}, Tuple{AbstractManifold, Any, Any, Any, Any, Tβ}} where Tβ","page":"Library of functions","title":"ManifoldDiff.jacobi_field","text":"Y = jacobi_field(M, p, q, t, X, β)\njacobi_field!(M, Y, p, q, t, X, β)\n\ncompute the Jacobi field J along the geodesic γ_pq on the manifold mathcal M with initial conditions (depending on the application) X T_pmathcal M and weights β. The result is a tangent vector Y from T_γ_pq(t)mathcal M. The computation can be done in place of Y.\n\nSee also\n\nadjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_exp_argument-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_exp_argument","text":"βdifferential_exp_argument(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_X exp_p XY. They are\n\nβ(κ) = begincases\nfracsinh(dsqrt-κ)dsqrt-κtext if κ 0\n1 text if κ = 0\nfracsin(dsqrtκ)dsqrtκtext if κ 0\nendcases\n\nSee also\n\ndifferential_exp_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_exp_basepoint-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_exp_basepoint","text":"βdifferential_exp_basepoint(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_p exp_p X Y. They are\n\nβ(κ) = begincases\ncosh(sqrt-κ)text if κ 0\n1 text if κ = 0\ncos(sqrtκ) text if κ 0\nendcases\n\nSee also\n\ndifferential_exp_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_log_argument-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_log_argument","text":"βdifferential_log_argument(κ,t,d)\n\nweights for the JacobiField corresponding to the differential of the logarithmic map with respect to its argument D_q log_p qX. They are\n\nβ(κ) = begincases\nfrac dsqrt-κ sinh(dsqrt-κ)text if κ 0\n1 text if κ = 0\nfrac dsqrtκ sin(dsqrtκ)text if κ 0\nendcases\n\nSee also\n\ndifferential_log_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_log_basepoint-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_log_basepoint","text":"βdifferential_log_basepoint(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_p log_p qX. They are\n\nβ(κ) = begincases\n-sqrt-κdfraccosh(dsqrt-κ)sinh(dsqrt-κ)text if κ 0\n-1 text if κ = 0\n-sqrtκdfraccos(dsqrtκ)sin(dsqrtκ)text if κ 0\nendcases\n\nSee also\n\ndifferential_log_argument, differential_log_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_shortest_geodesic_startpoint-Tuple{Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_shortest_geodesic_startpoint","text":"βdifferential_shortest_geodesic_startpoint(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_x g(tpq)X. They are\n\nβ(κ) = begincases\nfracsinh(d(1-t)sqrt-κ)sinh(dsqrt-κ)\ntext if κ 0\n1-t text if κ = 0\nfracsin((1-t)dsqrtκ)sinh(dsqrtκ)\ntext if κ 0\nendcases\n\nDue to a symmetry argument, these are also used to compute D_q g(t pq)η\n\nSee also\n\ndifferential_shortest_geodesic_endpoint, differential_shortest_geodesic_startpoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#Jacobians","page":"Library of functions","title":"Jacobians","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"jacobians.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.allocate_jacobian-Tuple{AbstractManifold, AbstractManifold, Any, Any}","page":"Library of functions","title":"ManifoldDiff.allocate_jacobian","text":"allocate_jacobian(\n M_domain::AbstractManifold,\n M_codomain::AbstractManifold,\n f,\n p;\n basis_domain::AbstractBasis = DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis = DefaultOrthonormalBasis(),\n)\n\nAllocate Jacobian of function f with given domain and codomain at point p. basis_domain and basis_codomain denote bases of tangent spaces at, respectively, p and f(p).\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.jacobian_exp_argument","page":"Library of functions","title":"ManifoldDiff.jacobian_exp_argument","text":"jacobian_exp_argument(\n M::AbstractManifold,\n p,\n X,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the exponential map with respect to its argument (tangent vector). Differential of the exponential map is here considered as a function from T_p mathcalM to T_exp_p X mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.jacobian_exp_basepoint","page":"Library of functions","title":"ManifoldDiff.jacobian_exp_basepoint","text":"jacobian_exp_basepoint(\n M::AbstractManifold,\n p,\n X,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the exponential map with respect to the basepoint. Differential of the exponential map is here considered as a function from T_p mathcalM to T_exp_p X mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.jacobian_log_argument","page":"Library of functions","title":"ManifoldDiff.jacobian_log_argument","text":"jacobian_log_argument(\n M::AbstractManifold,\n p,\n q,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the logarithmic map with respect to its argument (point q). Differential of the logarithmic map is here considered as a function from T_q mathcalM to T_p mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.jacobian_log_basepoint","page":"Library of functions","title":"ManifoldDiff.jacobian_log_basepoint","text":"jacobian_log_basepoint(\n M::AbstractManifold,\n p,\n q,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the logarithmic map with respect to the basepoint. Differential of the logarithmic map is here considered as a function from T_q mathcalM to T_p mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#Riemannian-differentials","page":"Library of functions","title":"Riemannian differentials","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"riemannian_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.AbstractRiemannianDiffBackend","page":"Library of functions","title":"ManifoldDiff.AbstractRiemannianDiffBackend","text":"AbstractRiemannianDiffBackend\n\nAn abstract type for backends for differentiation.\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.RiemannianProjectionBackend","page":"Library of functions","title":"ManifoldDiff.RiemannianProjectionBackend","text":"RiemannianProjectionBackend <: AbstractRiemannianDiffBackend\n\nThis 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\n\nA function f ℝ^m ℝ such that its restriction to the manifold yields the cost function f of interest.\nA project function to project tangent vectors from the embedding (at T_pℝ^m) back onto the tangent space T_pmathcal 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).\nA change_representer for non-isometrically embedded manifolds, i.e. where the tangent space T_pmathcal 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\n\nsee also riemannian_gradient and [AMS08], Section 3.6.1 for a derivation on submanifolds.\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.TangentDiffBackend","page":"Library of functions","title":"ManifoldDiff.TangentDiffBackend","text":"TangentDiffBackend <: AbstractRiemannianDiffBackend\n\nA backend that uses tangent spaces and bases therein to derive an intrinsic differentiation scheme.\n\nSince it works in tangent spaces at argument and function value, methods might require a retraction and an inverse retraction as well as a basis.\n\nIn the tangent space itself, this backend then employs a (Euclidean) backend.\n\nConstructor\n\nTangentDiffBackend(diff_backend)\n\nwhere diff_backend is a (Euclidean) backend to be used on the tangent space.\n\nWith the keyword arguments\n\nretraction an AbstractRetractionMethod (ExponentialRetraction by default)\ninverse_retraction an AbstractInverseRetractionMethod LogarithmicInverseRetraction by default)\nbasis_arg an AbstractBasis (DefaultOrthogonalBasis by default)\nbasis_val an AbstractBasis (DefaultOrthogonalBasis by default)\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.differential-Tuple{AbstractManifold, Any, Real, ManifoldDiff.AbstractRiemannianDiffBackend}","page":"Library of functions","title":"ManifoldDiff.differential","text":"differential(M::AbstractManifold, f, t::Real, backend)\ndifferential!(M::AbstractManifold, f, X, t::Real, backend)\n\nCompute 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 mathrmdf_t(t)1.\n\nThe mutating variant computes the differential in place of X.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.gradient-Tuple{AbstractManifold, Any, Any, ManifoldDiff.AbstractRiemannianDiffBackend}","page":"Library of functions","title":"ManifoldDiff.gradient","text":"gradient(M::AbstractManifold, f, p, backend::AbstractRiemannianDiffBackend)\ngradient!(M::AbstractManifold, f, X, p, backend::AbstractRiemannianDiffBackend)\n\nCompute the Riemannian gradient f(p) of a real-valued function fmathcal M to ℝ at point p on the manifold M using the specified AbstractRiemannianDiffBackend.\n\nThe mutating variant computes the gradient in place of X.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.gradient-Tuple{AbstractManifold, Any, Any, TangentDiffBackend}","page":"Library of functions","title":"ManifoldDiff.gradient","text":"gradient(M, f, p, backend::TangentDiffBackend)\n\nThis method uses the internal backend.diff_backend (Euclidean) on the function\n\n f(operatornameretr_p(cdot))\n\nwhich 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:\n\noperatornamegradf(p) = operatornamegradf(p) = sum_i=1^d g_p(operatornamegradf(p)X_i)X_i\n\t= sum_i=1^d Df(p)X_iX_i\n\nwhere the last equality is due to the definition of the gradient as the Riesz representer of the differential.\n\nIf the backend is a forward (or backward) finite difference, these coefficients in the sum can be approximates as\n\nDF(p)Y frac1hbigl( f(exp_p(hY)) - f(p) bigr)\n\nwriting p=exp_p(0) we see that this is a finite difference of fcircexp_p, i.e. for a function on the tangent space, so we can also use other (Euclidean) backends\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.hessian-Tuple{AbstractManifold, Any, Any, TangentDiffBackend}","page":"Library of functions","title":"ManifoldDiff.hessian","text":"hessian(M::AbstractManifold, f, p, backend::TangentDiffBackend)\n\nCompute the Hessian of function f at point p using the given backend. The formula for normal coordinate systems from[SommerFletcherPennec2020] is used.\n\n[SommerFletcherPennec2020]: S. Sommer, T. Fletcher, and X. Pennec, “1 - Introduction to differential and Riemannian geometry,” in Riemannian Geometric Statistics in Medical Image Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 3–37. doi: 10.1016/B978-0-12-814725-2.00008-X.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.riemannian_Hessian-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.riemannian_Hessian","text":"riemannian_Hessian(M, p, eG, eH, X)\nriemannian_Hessian!(M, Y, p, eG, eH, X)\n\nConvert the Euclidean Hessian eH=operatornameHess tilde f(p) X of a function f colon mathcal M to mathbb R, which is the restriction of tilde f to mathcal M, given additionally the (Euclidean) gradient operatornamegrad tilde f(p).\n\nThe Riemannian Hessian is then computed by\n\noperatornameHess f(p)X\n= operatornameproj_T_pmathcal Mbigl(operatornameHess tilde f(p)X)\n+ mathcal W_pBigl( X operatornameproj_N_pmathcal Mbigl( operatornamegrad tilde f (p) bigr) Bigr)\n\nwhere N_pmathcal M denotes the normal space, i.e. the orthogonal complement of the tangent space in the embedding, and mathcal W_p denotes the Weingarten map. See [Bou23] for more details\n\nThe function is inspired by ehess2rhess in the Matlab package Manopt.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.riemannian_gradient-Tuple{AbstractManifold, Any, Any}","page":"Library of functions","title":"ManifoldDiff.riemannian_gradient","text":"riemannian_gradient(M, p, Y; embedding_metric=EuclideanMetric())\nriemannian_gradient!(M, X, p, Y; embedding_metric=EuclideanMetric())\n\nFor a given gradient Y = operatornamegrad tilde f(p) in the embedding of a manifold, this function computes the Riemannian gradient operatornamegrad f(p) of the function tilde f restricted to the manifold M. This can also be done in place of X.\n\nBy default it uses the following computation: Let the projection Z = operatornameproj_T_pmathcal M(Y) of Y onto the tangent space at p be given, that is with respect to the inner product in the embedding. Then\n\nZ-Y W = 0 text for all W in T_pmathcal M\n\nor rearranged YW = ZW. We then use the definition of the Riemannian gradient\n\noperatornamegrad f(p) W_p = Df(p)X = operatornamegradf(p) W = operatornameproj_T_pmathcal M(operatornamegradf(p))W\nquadtextfor all W in T_pmathcal M\n\nComparing the first and the last term, the remaining computation is the function change_representer.\n\nThis method can also be implemented directly, if a more efficient/stable version is known.\n\nThe function is inspired by egrad2rgrad in the Matlab package Manopt.\n\n\n\n\n\n","category":"method"},{"location":"library/#Proximal-Maps","page":"Library of functions","title":"Proximal Maps","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Given a convex, lower semi-continuous function fcolon mathcal M to mathbb R, its proximal map is defined for some λ0 as [Bac14]","category":"page"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"operatornameprox_λf(p) = operatorname*argmin_qinmathcal M frac12λd^2_mathcal M(pq) + f(q)","category":"page"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Another name for the proximal map is resolvent. Intuitively this means to minimize the function f while at the same timme “staying close” to the argument p.","category":"page"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"proximal_maps.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.prox_distance","page":"Library of functions","title":"ManifoldDiff.prox_distance","text":"y = prox_distance(M::AbstractManifold, λ::Real, p_data, p [, r=2])\nprox_distance!(M::AbstractManifold, q, λ::Real, p_data, p [, r=2])\n\nCompute the proximal map operatornameprox_λf with parameter λ of f(p) = frac1rd_mathcal M^r(p_mathrmdatap). For the in-place variant the computation is done in place of q.\n\nInput\n\nM a manifold M\nλ the prox parameter, a positive real number.\np_data a point on M.\np the argument of the proximal map\nr (2) exponent of the distance.\n\nOutput\n\nq – the result of the proximal map of f\n\nFor more details see [WDS14]\n\n\n\n\n\n","category":"function"},{"location":"basic_usage/#Basic-usage","page":"Usage","title":"Basic usage","text":"","category":"section"},{"location":"basic_usage/","page":"Usage","title":"Usage","text":"You can calculate Riemannian gradient of a function defined in its embedding in multiple ways. For example, rb_onb_fd51 corresponds to a finite differencing scheme and rb_onb_fwdd calculates gradient using ForwardDiff.jl. DifferentiationInterface.jl is used to select the backend.","category":"page"},{"location":"basic_usage/","page":"Usage","title":"Usage","text":"using ManifoldDiff\nusing DifferentiationInterface\nusing Manifolds, FiniteDifferences, ForwardDiff, Zygote\n\nrb_onb_fd51 = ManifoldDiff.TangentDiffBackend(AutoFiniteDifferences(central_fdm(5, 1)))\nrb_onb_fwdd = ManifoldDiff.TangentDiffBackend(AutoForwardDiff())\nrb_proj_zyg = ManifoldDiff.RiemannianProjectionBackend(AutoZygote())\n\ns2 = Sphere(2)\n\nA = [1.0 2.0 5.0; 2.0 -1.0 4.0; 5.0 4.0 0.0]\n\nf(p) = p' * A * p\nq = [0.0, 1.0, 0.0]\n\nprintln(ManifoldDiff.gradient(s2, f, q, rb_onb_fd51))\nprintln(ManifoldDiff.gradient(s2, f, q, rb_onb_fwdd))\nprintln(ManifoldDiff.gradient(s2, f, q, rb_proj_zyg))","category":"page"},{"location":"basic_usage/","page":"Usage","title":"Usage","text":"TangentDiffBackend reduces dimensionality of the problem to the intrinsic dimension of the manifold, while RiemannianProjectionBackend relies on converting Euclidean gradient in the embedding to the Riemannian one.","category":"page"},{"location":"backends/#Differentiation-backends","page":"Backends","title":"Differentiation backends","text":"","category":"section"},{"location":"backends/","page":"Backends","title":"Backends","text":"set_default_differential_backend!\ndefault_differential_backend","category":"page"},{"location":"backends/#ManifoldDiff.set_default_differential_backend!","page":"Backends","title":"ManifoldDiff.set_default_differential_backend!","text":"set_default_differential_backend!(backend)\n\nSet current backend for differentiation to backend.\n\n\n\n\n\n","category":"function"},{"location":"backends/#ManifoldDiff.default_differential_backend","page":"Backends","title":"ManifoldDiff.default_differential_backend","text":"default_differential_backend()\n\nGet the default differentiation backend.\n\n\n\n\n\n","category":"function"},{"location":"backends/#Euclidian-backends","page":"Backends","title":"Euclidian backends","text":"","category":"section"},{"location":"backends/","page":"Backends","title":"Backends","text":"Euclidian backend objects can be taken from ADTypes.jl. See the documentation of DifferentiationInterface.jl for the list of supported packages.","category":"page"},{"location":"backends/#EmbeddedDiff","page":"Backends","title":"EmbeddedDiff","text":"","category":"section"},{"location":"backends/","page":"Backends","title":"Backends","text":"Modules = [ManifoldDiff]\nPages = [\"embedded_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"backends/#ManifoldDiff.ExplicitEmbeddedBackend","page":"Backends","title":"ManifoldDiff.ExplicitEmbeddedBackend","text":"ExplicitEmbeddedBackend{TF<:NamedTuple}\n\nA backend to use with the RiemannianProjectionBackend or the TangentDiffBackend, when you have explicit formulae for the gradient in the embedding available.\n\nConstructor\n\nExplicitEmbeddedBackend(M::AbstractManifold; kwargs)\n\nConstruct an ExplicitEmbeddedBackend in the embedding M, where currently the following keywords may be used\n\ngradient for a(n allocating) gradient function gradient(M, p) defined in the embedding\ngradient! for a mutating gradient function gradient!(M, X, p).\n\nNote that the gradient functions are defined on the embedding manifold M passed to the Backend as well\n\n\n\n\n\n","category":"type"},{"location":"#ManifoldDiff","page":"Home","title":"ManifoldDiff","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The package ManifoldDiff aims to provide automatic calculation of Riemannian gradients of functions defined on manifolds. It builds upon Manifolds.jl.","category":"page"},{"location":"#Naming-scheme","page":"Home","title":"Naming scheme","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Providing a derivative, differential or gradient for a given function, this package adds that information to the function name. For example","category":"page"},{"location":"","page":"Home","title":"Home","text":"grad_f for a gradient operatornamegrad f\nsubgrad_f for a subgradient from the subdifferentialpartial f\ndifferential_f for Df (also called pushforward)\ndifferential_f_variable if f has multiple variables / parameters, since a usual writing in math is f_x in this case\nadjoint_differential_f for pullbacks\nadjoint_differential_f_variable if f has multiple variables / parameters\nf_derivative for f\njacobian_f for Jacobian matrix of f.\njacobian_f_variable if f has multiple parameters.","category":"page"},{"location":"","page":"Home","title":"Home","text":"the scheme is not completely fixed but tries to follow the mathematical notation.","category":"page"},{"location":"internals/#Internal-functions","page":"Internals","title":"Internal functions","text":"","category":"section"},{"location":"internals/","page":"Internals","title":"Internals","text":"ManifoldDiff.CurrentDiffBackend\nManifoldDiff._current_default_differential_backend\nManifoldDiff._hessian\nManifoldDiff._jacobian\nManifoldDiff._gradient\nManifoldDiff._derivative","category":"page"},{"location":"internals/#ManifoldDiff.CurrentDiffBackend","page":"Internals","title":"ManifoldDiff.CurrentDiffBackend","text":"CurrentDiffBackend(backend)\n\nA mutable struct for storing the current differentiation backend in a global constant _current_default_differential_backend.\n\nSee also\n\ndefault_differential_backend, set_default_differential_backend!\n\n\n\n\n\n","category":"type"},{"location":"internals/#ManifoldDiff._current_default_differential_backend","page":"Internals","title":"ManifoldDiff._current_default_differential_backend","text":"_current_default_differential_backend\n\nThe instance of CurrentDiffBackend that stores the globally default differentiation backend.\n\n\n\n\n\n","category":"constant"},{"location":"internals/#ManifoldDiff._hessian","page":"Internals","title":"ManifoldDiff._hessian","text":"_hessian(f, p[, backend])\n\nCompute the Hessian of a callable f at point p computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean Hessian.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"},{"location":"internals/#ManifoldDiff._jacobian","page":"Internals","title":"ManifoldDiff._jacobian","text":"_jacobian(f, p[, backend])\n\nCompute the Jacobian of a callable f at point p computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean Jacobians, for Riemannian Jacobian calculation see for example gradient.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"},{"location":"internals/#ManifoldDiff._gradient","page":"Internals","title":"ManifoldDiff._gradient","text":"_gradient(f, p[, backend])\n\nCompute the gradient of a callable f at point p computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean gradients, for Riemannian gradient calculation see for example gradient.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"},{"location":"internals/#ManifoldDiff._derivative","page":"Internals","title":"ManifoldDiff._derivative","text":"_derivative(f, t[, backend])\n\nCompute the derivative of a callable f at time t computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean derivatives, for Riemannian differentiation see for example differential.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"}] +[{"location":"references/#Literature","page":"Literature","title":"Literature","text":"","category":"section"},{"location":"references/","page":"Literature","title":"Literature","text":"P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.\n\n\n\nM. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014).\n\n\n\nN. Boumal. An Introduction to Optimization on Smooth Manifolds. First Edition (Cambridge University Press, 2023). Homepage to the book: nicolasboumal.net/book/index.html.\n\n\n\nA. Weinmann, L. Demaret and M. Storath. Total variation regularization for manifold-valued data. SIAM Journal on Imaging Sciences 7, 2226–2257 (2014).\n\n\n\nR. Zimmermann. Hermite Interpolation and Data Processing Errors on Riemannian Matrix Manifolds. SIAM Journal on Scientific Computing 42, A2593-A2619 (2020).\n\n\n\n","category":"page"},{"location":"library/#Different-library-functions","page":"Library of functions","title":"Different library functions","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Documentation for ManifoldDiff.jl's methods and types for finite differences and automatic differentiation.","category":"page"},{"location":"library/#Derivatives","page":"Library of functions","title":"Derivatives","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"derivatives.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.geodesic_derivative-Tuple{Any, Any, Any, Number}","page":"Library of functions","title":"ManifoldDiff.geodesic_derivative","text":"Y = geodesic_derivative(M, p, X, t::Number; γt = geodesic(M, p, X, t))\ngeodesic_derivative!(M, Y, p, X, t::Number; γt = geodesic(M, p, X, t))\n\nEvaluate the derivative of the geodesic γ(t) with γ_pX(0) = p and dot γ_pX(0) = X at t. The formula reads\n\ndot γ(t) = mathcal P_γ(t) gets p X\n\nwhere mathcal P denotes the parallel transport. This computation can also be done in-place of Y.\n\nOptional Parameters\n\nγt – (geodesic(M, p, X, t)) the point on the geodesic at t. This way if the point was computed earlier it can be resued here.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.shortest_geodesic_derivative-Tuple{Any, Any, Any, Number}","page":"Library of functions","title":"ManifoldDiff.shortest_geodesic_derivative","text":"Y = shortest_geodesic_derivative(M, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))\nshortest_geodesic_derivative!(M, Y, p, X, t::Number; γt = shortest_geodesic(M, p, q, t))\n\nEvaluate the derivative of the shortest geodesic γ(t) with γ_pq(0) = p and dot γ_pq(1) = q at t. The formula reads\n\ndot γ(t) = mathcal P_γ(t) gets p log_pq\n\nwhere mathcal P denotes the parallel transport. This computation can also be done in-place of Y.\n\nOptional Parameters\n\nγt = geodesic(M, p, X, t) the point on the geodesic at t. This way if the point was computed earlier it can be resued here.\n\n\n\n\n\n","category":"method"},{"location":"library/#Differentials-and-their-adjoints","page":"Library of functions","title":"Differentials and their adjoints","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"adjoint_differentials.jl\",\"differentials.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.adjoint_differential_exp_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_exp_argument","text":"adjoint_differential_exp_argument(M, p, X, Y)\nadjoint_differential_exp_argument!(M, Z, p, X, Y)\n\nCompute the adjoint of D_Xexp_p XY (in place of Z). Note that X T_p(T_pmathcal M) = T_pmathcal M is still a tangent vector.\n\nSee also\n\ndifferential_exp_argument, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_exp_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_exp_basepoint","text":"adjoint_differential_exp_basepoint(M, p, X, Y)\nadjoint_differential_exp_basepoint!(M, Z, p, X, Y)\n\nComputes the adjoint of D_p exp_p XY (in place of Z).\n\nSee also\n\ndifferential_exp_basepoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_log_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_log_argument","text":"adjoint_differential_log_argument(M, p, q, X)\nadjoint_differential_log_argument!(M, Y, p, q, X)\n\nCompute the adjoint of D_q log_p qX (in place of Y).\n\nSee also\n\ndifferential_log_argument, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_log_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_log_basepoint","text":"adjoint_differential_log_basepoint(M, p, q, X)\nadjoint_differential_log_basepoint!(M, Y, p, q, X)\n\ncomputes the adjoint of D_p log_p qX (in place of Y).\n\nSee also\n\ndifferential_log_basepoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_shortest_geodesic_endpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_shortest_geodesic_endpoint","text":"adjoint_differential_shortest_geodesic_endpoint(M, p, q, t, X)\nadjoint_differential_shortest_geodesic_endpoint!(M, Y, p, q, t, X)\n\nCompute the adjoint of D_q γ(t p q)X (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_endpoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.adjoint_differential_shortest_geodesic_startpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.adjoint_differential_shortest_geodesic_startpoint","text":"adjoint_differential_shortest_geodesic_startpoint(M, p, q, t, X)\nadjoint_differential_shortest_geodesic_startpoint!(M, Y, p, q, t, X)\n\nCompute the adjoint of D_p γ(t p q)X (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_startpoint, adjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_exp_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_exp_argument","text":"Z = differential_exp_argument(M, p, X, Y)\ndifferential_exp_argument!(M, Z, p, X, Y)\n\nCompute D_Xexp_pXY (in place of Z). Note that X T_X(T_pmathcal M) = T_pmathcal M is still a tangent vector.\n\nSee also\n\ndifferential_exp_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_exp_argument_lie_approx-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_exp_argument_lie_approx","text":"differential_exp_argument_lie_approx(M::AbstractManifold, p, X, Y; n)\n\nApproximate differential of exponential map based on Lie group exponential. The formula reads (see Theorem 1.7 of [Helgason1978])\n\nD_X exp_p(X)Y = (mathrmdL_exp_e(X))_eleft(sum_k=0^nfrac(-1)^k(k+1)(operatornamead_X)^k(Y)right)\n\nwhere (operatornamead_X)^k(Y) is defined recursively as (operatornamead_X)^0(Y) = Y, operatornamead_X^k+1(Y) = X operatornamead_X^k(Y).\n\n[Helgason1978]: S. Helgason, Differential Geometry, Lie Groups, and Symmetric Spaces, First Edition. Academic Press, 1978.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_exp_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_exp_basepoint","text":"Z = differential_exp_basepoint(M, p, X, Y)\ndifferential_exp_basepoint!(M, Z, p, X, Y)\n\nCompute D_pexp_p XY (in place of Z).\n\nSee also\n\ndifferential_exp_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_inverse_retract_argument_fd_approx-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_inverse_retract_argument_fd_approx","text":"differential_inverse_retract_argument_fd_approx(\n M::AbstractManifold,\n p,\n q,\n X;\n retr::AbstractRetractionMethod = default_retraction_method(M),\n invretr::AbstractInverseRetractionMethod = default_inverse_retraction_method(M),\n h::Real=sqrt(eps(eltype(X))),\n)\n\nApproximate the differential of the inverse retraction invretr using a finite difference formula (see Eq. (16) in [Zim20]\n\nfracoperatornameretr^-1_q(operatornameretr_p(hX)) - operatornameretr^-1_q(operatornameretr_p(-hX))2h\n\nwhere h is the finite difference step h, operatornameretr^-1 is the inverse retraction invretr and operatornameretr is the retraction retr.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_log_argument-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_log_argument","text":"Y = differential_log_argument(M, p, q, X)\ndifferential_log_argument!(M, Y, p, q, X)\n\ncomputes D_qlog_pqX (in place of Y).\n\nSee also\n\ndifferential_log_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_log_basepoint-Tuple{AbstractManifold, Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.differential_log_basepoint","text":"Y = differential_log_basepoint(M, p, q, X)\ndifferential_log_basepoint!(M, Y, p, q, X)\n\ncomputes D_plog_pqX (in place of Y).\n\nSee also\n\ndifferential_log_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_shortest_geodesic_endpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.differential_shortest_geodesic_endpoint","text":"Y = differential_shortest_geodesic_endpoint(M, p, q, t, X)\ndifferential_shortest_geodesic_endpoint!(M, Y, p, q, t, X)\n\nCompute D_qγ(tpq)X (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_startpoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.differential_shortest_geodesic_startpoint-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.differential_shortest_geodesic_startpoint","text":"Y = differential_shortest_geodesic_startpoint(M, p, q, t, X)\ndifferential_shortest_geodesic_startpoint!(M, Y, p, q, t, X)\n\nCompute D_p γ(tpq)η (in place of Y).\n\nSee also\n\ndifferential_shortest_geodesic_endpoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"diagonalizing_projectors.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.AbstractProjector","page":"Library of functions","title":"ManifoldDiff.AbstractProjector","text":"abstract type AbstractProjector end\n\nAn abstract type for projectors on a tangent space T_pM for fixed values of p and M. Calling a projector on a tangent vector returns a new tangent vector:\n\n(Π::AbstractProjector)(X) -> Y\n\nProjectors assume that X is a valid vector from T_pM.\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.CoprojectorOntoVector","page":"Library of functions","title":"ManifoldDiff.CoprojectorOntoVector","text":"CoprojectorOntoVector{TM<:AbstractManifold,TP,TX}\n\nA structure that represents projector onto the subspace of the tangent space at p from manifold M othogonal to vector X of unit norm.\n\nConstructor\n\nCoprojectorOntoVector(M::AbstractManifold, p, X)\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.ProjectorOntoVector","page":"Library of functions","title":"ManifoldDiff.ProjectorOntoVector","text":"ProjectorOntoVector{TM<:AbstractManifold,TP,TX}\n\nA structure that represents projector onto the subspace of the tangent space at p from manifold M spanned by tangent vector X of unit norm.\n\nConstructor\n\nProjectorOntoVector(M::AbstractManifold, p, X)\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.diagonalizing_projectors-Tuple{AbstractManifold, Any, Any}","page":"Library of functions","title":"ManifoldDiff.diagonalizing_projectors","text":"diagonalizing_projectors(M::AbstractManifold, p, X)\n\nCompute eigenvalues of the Jacobi operator Y R(YX)X, where R is the curvature endomorphism, together with projectors onto eigenspaces of the operator. Projectors are objects of subtypes of AbstractProjector.\n\nBy default constructs projectors using the DiagonalizingOrthonormalBasis.\n\n\n\n\n\n","category":"method"},{"location":"library/#Gradients","page":"Library of functions","title":"Gradients","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"gradients.jl\"]\nOrder = [:type, :function, :constant]\nPrivate = true","category":"page"},{"location":"library/#ManifoldDiff.grad_distance","page":"Library of functions","title":"ManifoldDiff.grad_distance","text":"grad_distance(M, q, p[, c=2])\ngrad_distance!(M, X, q, p[, c=2])\n\ncompute the (sub)gradient of the distance (default: squared), in place of X.\n\nf(p) = frac1c d^c_mathcal M(p q)\n\nto a fixed point q on the manifold M and c is an integer. The (sub-)gradient reads\n\noperatornamegradf(p) = -d_mathcal M^c-2(p q)log_pq\n\nfor cneq 1 or pneq q. Note that for the remaining case c=1, p=q, the function is not differentiable. In this case, the function returns the corresponding zero tangent vector, since this is an element of the subdifferential.\n\nOptional\n\nc – (2) the exponent of the distance, i.e. the default is the squared distance\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.subgrad_distance","page":"Library of functions","title":"ManifoldDiff.subgrad_distance","text":"subgrad_distance(M, q, p[, c = 2; atol = 0])\nsubgrad_distance!(M, X, q, p[, c = 2; atol = 0])\n\ncompute the subgradient of the distance (in place of X)\n\nf(p) = frac1c d^c_mathcal M(p q)\n\nto a fixed point q on the manifold M and c is an integer. The subgradient reads\n\npartial f(p) = -d_mathcal M^c-2(p q)log_pq\n\nfor cneq 1 or pneq q. Note that for the remaining case c=1, p=q, the function is not differentiable. In this case, the subgradient is given by a tangent vector at p with norm less than or equal to one.\n\nOptional\n\nc – (2) the exponent of the distance, i.e. the default is the distance\natol – (0) the tolerance to use when evaluating the distance between p and q.\n\n\n\n\n\n","category":"function"},{"location":"library/#Jacobi-fields","page":"Library of functions","title":"Jacobi fields","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"Jacobi_fields.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.adjoint_Jacobi_field-Union{Tuple{Tβ}, Tuple{AbstractManifold, Any, Any, Any, Any, Tβ}} where Tβ","page":"Library of functions","title":"ManifoldDiff.adjoint_Jacobi_field","text":"Y = adjoint_Jacobi_field(M, p, q, t, X, β)\nadjoint_Jacobi_field!(M, Y, p, q, t, X, β)\n\nCompute the AdjointJacobiField J along the geodesic γ_pq on the manifold mathcal M with initial conditions (depending on the application) X T_γ_pq(t)mathcal M and weights β. The result is a vector Y T_pmathcal M. The main difference to jacobi_field is the, that the input X and the output Y switched tangent spaces. The computation can be done in place of Y.\n\nFor details see jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.jacobi_field-Union{Tuple{Tβ}, Tuple{AbstractManifold, Any, Any, Any, Any, Tβ}} where Tβ","page":"Library of functions","title":"ManifoldDiff.jacobi_field","text":"Y = jacobi_field(M, p, q, t, X, β)\njacobi_field!(M, Y, p, q, t, X, β)\n\ncompute the Jacobi field J along the geodesic γ_pq on the manifold mathcal M with initial conditions (depending on the application) X T_pmathcal M and weights β. The result is a tangent vector Y from T_γ_pq(t)mathcal M. The computation can be done in place of Y.\n\nSee also\n\nadjoint_Jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_exp_argument-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_exp_argument","text":"βdifferential_exp_argument(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_X exp_p XY. They are\n\nβ(κ) = begincases\nfracsinh(dsqrt-κ)dsqrt-κtext if κ 0\n1 text if κ = 0\nfracsin(dsqrtκ)dsqrtκtext if κ 0\nendcases\n\nSee also\n\ndifferential_exp_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_exp_basepoint-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_exp_basepoint","text":"βdifferential_exp_basepoint(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_p exp_p X Y. They are\n\nβ(κ) = begincases\ncosh(sqrt-κ)text if κ 0\n1 text if κ = 0\ncos(sqrtκ) text if κ 0\nendcases\n\nSee also\n\ndifferential_exp_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_log_argument-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_log_argument","text":"βdifferential_log_argument(κ,t,d)\n\nweights for the JacobiField corresponding to the differential of the logarithmic map with respect to its argument D_q log_p qX. They are\n\nβ(κ) = begincases\nfrac dsqrt-κ sinh(dsqrt-κ)text if κ 0\n1 text if κ = 0\nfrac dsqrtκ sin(dsqrtκ)text if κ 0\nendcases\n\nSee also\n\ndifferential_log_basepoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_log_basepoint-Tuple{Any, Number, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_log_basepoint","text":"βdifferential_log_basepoint(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_p log_p qX. They are\n\nβ(κ) = begincases\n-sqrt-κdfraccosh(dsqrt-κ)sinh(dsqrt-κ)text if κ 0\n-1 text if κ = 0\n-sqrtκdfraccos(dsqrtκ)sin(dsqrtκ)text if κ 0\nendcases\n\nSee also\n\ndifferential_log_argument, differential_log_argument, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.βdifferential_shortest_geodesic_startpoint-Tuple{Any, Any, Any}","page":"Library of functions","title":"ManifoldDiff.βdifferential_shortest_geodesic_startpoint","text":"βdifferential_shortest_geodesic_startpoint(κ,t,d)\n\nweights for the jacobi_field corresponding to the differential of the geodesic with respect to its start point D_x g(tpq)X. They are\n\nβ(κ) = begincases\nfracsinh(d(1-t)sqrt-κ)sinh(dsqrt-κ)\ntext if κ 0\n1-t text if κ = 0\nfracsin((1-t)dsqrtκ)sinh(dsqrtκ)\ntext if κ 0\nendcases\n\nDue to a symmetry argument, these are also used to compute D_q g(t pq)η\n\nSee also\n\ndifferential_shortest_geodesic_endpoint, differential_shortest_geodesic_startpoint, jacobi_field\n\n\n\n\n\n","category":"method"},{"location":"library/#Jacobians","page":"Library of functions","title":"Jacobians","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"jacobians.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.allocate_jacobian-Tuple{AbstractManifold, AbstractManifold, Any, Any}","page":"Library of functions","title":"ManifoldDiff.allocate_jacobian","text":"allocate_jacobian(\n M_domain::AbstractManifold,\n M_codomain::AbstractManifold,\n f,\n p;\n basis_domain::AbstractBasis = DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis = DefaultOrthonormalBasis(),\n)\n\nAllocate Jacobian of function f with given domain and codomain at point p. basis_domain and basis_codomain denote bases of tangent spaces at, respectively, p and f(p).\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.jacobian_exp_argument","page":"Library of functions","title":"ManifoldDiff.jacobian_exp_argument","text":"jacobian_exp_argument(\n M::AbstractManifold,\n p,\n X,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the exponential map with respect to its argument (tangent vector). Differential of the exponential map is here considered as a function from T_p mathcalM to T_exp_p X mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.jacobian_exp_basepoint","page":"Library of functions","title":"ManifoldDiff.jacobian_exp_basepoint","text":"jacobian_exp_basepoint(\n M::AbstractManifold,\n p,\n X,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the exponential map with respect to the basepoint. Differential of the exponential map is here considered as a function from T_p mathcalM to T_exp_p X mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.jacobian_log_argument","page":"Library of functions","title":"ManifoldDiff.jacobian_log_argument","text":"jacobian_log_argument(\n M::AbstractManifold,\n p,\n q,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the logarithmic map with respect to its argument (point q). Differential of the logarithmic map is here considered as a function from T_q mathcalM to T_p mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#ManifoldDiff.jacobian_log_basepoint","page":"Library of functions","title":"ManifoldDiff.jacobian_log_basepoint","text":"jacobian_log_basepoint(\n M::AbstractManifold,\n p,\n q,\n basis_domain::AbstractBasis=DefaultOrthonormalBasis(),\n basis_codomain::AbstractBasis=DefaultOrthonormalBasis(),\n)\n\nCompute Jacobian of the logarithmic map with respect to the basepoint. Differential of the logarithmic map is here considered as a function from T_q mathcalM to T_p mathcalM. Jacobian coefficients are represented in basis basis_domain in the domain and in basis_codomain in the codomain.\n\n\n\n\n\n","category":"function"},{"location":"library/#Riemannian-differentials","page":"Library of functions","title":"Riemannian differentials","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"riemannian_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.AbstractRiemannianDiffBackend","page":"Library of functions","title":"ManifoldDiff.AbstractRiemannianDiffBackend","text":"AbstractRiemannianDiffBackend\n\nAn abstract type for backends for differentiation.\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.RiemannianProjectionBackend","page":"Library of functions","title":"ManifoldDiff.RiemannianProjectionBackend","text":"RiemannianProjectionBackend <: AbstractRiemannianDiffBackend\n\nThis 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\n\nA function f ℝ^m ℝ such that its restriction to the manifold yields the cost function f of interest.\nA project function to project tangent vectors from the embedding (at T_pℝ^m) back onto the tangent space T_pmathcal 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).\nA change_representer for non-isometrically embedded manifolds, i.e. where the tangent space T_pmathcal 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\n\nsee also riemannian_gradient and [AMS08], Section 3.6.1 for a derivation on submanifolds.\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.TangentDiffBackend","page":"Library of functions","title":"ManifoldDiff.TangentDiffBackend","text":"TangentDiffBackend <: AbstractRiemannianDiffBackend\n\nA backend that uses tangent spaces and bases therein to derive an intrinsic differentiation scheme.\n\nSince it works in tangent spaces at argument and function value, methods might require a retraction and an inverse retraction as well as a basis.\n\nIn the tangent space itself, this backend then employs a (Euclidean) backend.\n\nConstructor\n\nTangentDiffBackend(diff_backend)\n\nwhere diff_backend is a (Euclidean) backend to be used on the tangent space.\n\nWith the keyword arguments\n\nretraction an AbstractRetractionMethod (ExponentialRetraction by default)\ninverse_retraction an AbstractInverseRetractionMethod LogarithmicInverseRetraction by default)\nbasis_arg an AbstractBasis (DefaultOrthogonalBasis by default)\nbasis_val an AbstractBasis (DefaultOrthogonalBasis by default)\n\n\n\n\n\n","category":"type"},{"location":"library/#ManifoldDiff.differential-Tuple{AbstractManifold, Any, Real, ManifoldDiff.AbstractRiemannianDiffBackend}","page":"Library of functions","title":"ManifoldDiff.differential","text":"differential(M::AbstractManifold, f, t::Real, backend)\ndifferential!(M::AbstractManifold, f, X, t::Real, backend)\n\nCompute 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 mathrmdf_t(t)1.\n\nThe mutating variant computes the differential in place of X.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.gradient-Tuple{AbstractManifold, Any, Any, ManifoldDiff.AbstractRiemannianDiffBackend}","page":"Library of functions","title":"ManifoldDiff.gradient","text":"gradient(M::AbstractManifold, f, p, backend::AbstractRiemannianDiffBackend)\ngradient!(M::AbstractManifold, f, X, p, backend::AbstractRiemannianDiffBackend)\n\nCompute the Riemannian gradient f(p) of a real-valued function fmathcal M to ℝ at point p on the manifold M using the specified AbstractRiemannianDiffBackend.\n\nThe mutating variant computes the gradient in place of X.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.gradient-Tuple{AbstractManifold, Any, Any, TangentDiffBackend}","page":"Library of functions","title":"ManifoldDiff.gradient","text":"gradient(M, f, p, backend::TangentDiffBackend)\n\nThis method uses the internal backend.diff_backend (Euclidean) on the function\n\n f(operatornameretr_p(cdot))\n\nwhich 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:\n\noperatornamegradf(p) = operatornamegradf(p) = sum_i=1^d g_p(operatornamegradf(p)X_i)X_i\n\t= sum_i=1^d Df(p)X_iX_i\n\nwhere the last equality is due to the definition of the gradient as the Riesz representer of the differential.\n\nIf the backend is a forward (or backward) finite difference, these coefficients in the sum can be approximates as\n\nDF(p)Y frac1hbigl( f(exp_p(hY)) - f(p) bigr)\n\nwriting p=exp_p(0) we see that this is a finite difference of fcircexp_p, i.e. for a function on the tangent space, so we can also use other (Euclidean) backends\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.hessian-Tuple{AbstractManifold, Any, Any, TangentDiffBackend}","page":"Library of functions","title":"ManifoldDiff.hessian","text":"hessian(M::AbstractManifold, f, p, backend::TangentDiffBackend)\n\nCompute the Hessian of function f at point p using the given backend. The formula for normal coordinate systems from[SommerFletcherPennec2020] is used.\n\n[SommerFletcherPennec2020]: S. Sommer, T. Fletcher, and X. Pennec, “1 - Introduction to differential and Riemannian geometry,” in Riemannian Geometric Statistics in Medical Image Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 3–37. doi: 10.1016/B978-0-12-814725-2.00008-X.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.riemannian_Hessian-Tuple{AbstractManifold, Vararg{Any, 4}}","page":"Library of functions","title":"ManifoldDiff.riemannian_Hessian","text":"riemannian_Hessian(M, p, eG, eH, X)\nriemannian_Hessian!(M, Y, p, eG, eH, X)\n\nConvert the Euclidean Hessian eH=operatornameHess tilde f(p) X of a function f colon mathcal M to mathbb R, which is the restriction of tilde f to mathcal M, given additionally the (Euclidean) gradient operatornamegrad tilde f(p).\n\nThe Riemannian Hessian is then computed by\n\noperatornameHess f(p)X\n= operatornameproj_T_pmathcal Mbigl(operatornameHess tilde f(p)X)\n+ mathcal W_pBigl( X operatornameproj_N_pmathcal Mbigl( operatornamegrad tilde f (p) bigr) Bigr)\n\nwhere N_pmathcal M denotes the normal space, i.e. the orthogonal complement of the tangent space in the embedding, and mathcal W_p denotes the Weingarten map. See [Bou23] for more details\n\nThe function is inspired by ehess2rhess in the Matlab package Manopt.\n\n\n\n\n\n","category":"method"},{"location":"library/#ManifoldDiff.riemannian_gradient-Tuple{AbstractManifold, Any, Any}","page":"Library of functions","title":"ManifoldDiff.riemannian_gradient","text":"riemannian_gradient(M, p, Y; embedding_metric=EuclideanMetric())\nriemannian_gradient!(M, X, p, Y; embedding_metric=EuclideanMetric())\n\nFor a given gradient Y = operatornamegrad tilde f(p) in the embedding of a manifold, this function computes the Riemannian gradient operatornamegrad f(p) of the function tilde f restricted to the manifold M. This can also be done in place of X.\n\nBy default it uses the following computation: Let the projection Z = operatornameproj_T_pmathcal M(Y) of Y onto the tangent space at p be given, that is with respect to the inner product in the embedding. Then\n\nZ-Y W = 0 text for all W in T_pmathcal M\n\nor rearranged YW = ZW. We then use the definition of the Riemannian gradient\n\noperatornamegrad f(p) W_p = Df(p)X = operatornamegradf(p) W = operatornameproj_T_pmathcal M(operatornamegradf(p))W\nquadtextfor all W in T_pmathcal M\n\nComparing the first and the last term, the remaining computation is the function change_representer.\n\nThis method can also be implemented directly, if a more efficient/stable version is known.\n\nThe function is inspired by egrad2rgrad in the Matlab package Manopt.\n\n\n\n\n\n","category":"method"},{"location":"library/#Proximal-Maps","page":"Library of functions","title":"Proximal Maps","text":"","category":"section"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Given a convex, lower semi-continuous function fcolon mathcal M to mathbb R, its proximal map is defined for some λ0 as [Bac14]","category":"page"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"operatornameprox_λf(p) = operatorname*argmin_qinmathcal M frac12λd^2_mathcal M(pq) + f(q)","category":"page"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Another name for the proximal map is resolvent. Intuitively this means to minimize the function f while at the same timme “staying close” to the argument p.","category":"page"},{"location":"library/","page":"Library of functions","title":"Library of functions","text":"Modules = [ManifoldDiff]\nPages = [\"proximal_maps.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"library/#ManifoldDiff.prox_distance","page":"Library of functions","title":"ManifoldDiff.prox_distance","text":"y = prox_distance(M::AbstractManifold, λ::Real, p_data, p [, r=2])\nprox_distance!(M::AbstractManifold, q, λ::Real, p_data, p [, r=2])\n\nCompute the proximal map operatornameprox_λf with parameter λ of f(p) = frac1rd_mathcal M^r(p_mathrmdatap). For the in-place variant the computation is done in place of q.\n\nInput\n\nM a manifold M\nλ the prox parameter, a positive real number.\np_data a point on M.\np the argument of the proximal map\nr (2) exponent of the distance.\n\nOutput\n\nq – the result of the proximal map of f\n\nFor more details see [WDS14]\n\n\n\n\n\n","category":"function"},{"location":"basic_usage/#Basic-usage","page":"Usage","title":"Basic usage","text":"","category":"section"},{"location":"basic_usage/","page":"Usage","title":"Usage","text":"You can calculate Riemannian gradient of a function defined in its embedding in multiple ways. For example, rb_onb_fd51 corresponds to a finite differencing scheme and rb_onb_fwdd calculates gradient using ForwardDiff.jl. DifferentiationInterface.jl is used to select the backend.","category":"page"},{"location":"basic_usage/","page":"Usage","title":"Usage","text":"using ManifoldDiff\nusing DifferentiationInterface\nusing Manifolds, FiniteDifferences, ForwardDiff, Zygote\n\nrb_onb_fd51 = TangentDiffBackend(AutoFiniteDifferences(central_fdm(5, 1)))\nrb_onb_fwdd = TangentDiffBackend(AutoForwardDiff())\nrb_proj_zyg = RiemannianProjectionBackend(AutoZygote())\n\ns2 = Sphere(2)\n\nA = [1.0 2.0 5.0; 2.0 -1.0 4.0; 5.0 4.0 0.0]\n\nf(p) = p' * A * p\nq = [0.0, 1.0, 0.0]\n\nprintln(ManifoldDiff.gradient(s2, f, q, rb_onb_fd51))\nprintln(ManifoldDiff.gradient(s2, f, q, rb_onb_fwdd))\nprintln(ManifoldDiff.gradient(s2, f, q, rb_proj_zyg))","category":"page"},{"location":"basic_usage/","page":"Usage","title":"Usage","text":"TangentDiffBackend reduces dimensionality of the problem to the intrinsic dimension of the manifold, while RiemannianProjectionBackend relies on converting Euclidean gradient in the embedding to the Riemannian one.","category":"page"},{"location":"backends/#Differentiation-backends","page":"Backends","title":"Differentiation backends","text":"","category":"section"},{"location":"backends/","page":"Backends","title":"Backends","text":"set_default_differential_backend!\ndefault_differential_backend","category":"page"},{"location":"backends/#ManifoldDiff.set_default_differential_backend!","page":"Backends","title":"ManifoldDiff.set_default_differential_backend!","text":"set_default_differential_backend!(backend)\n\nSet current backend for differentiation to backend.\n\n\n\n\n\n","category":"function"},{"location":"backends/#ManifoldDiff.default_differential_backend","page":"Backends","title":"ManifoldDiff.default_differential_backend","text":"default_differential_backend()\n\nGet the default differentiation backend.\n\n\n\n\n\n","category":"function"},{"location":"backends/#Euclidian-backends","page":"Backends","title":"Euclidian backends","text":"","category":"section"},{"location":"backends/","page":"Backends","title":"Backends","text":"Euclidian backend objects can be taken from ADTypes.jl. See the documentation of DifferentiationInterface.jl for the list of supported packages.","category":"page"},{"location":"backends/#EmbeddedDiff","page":"Backends","title":"EmbeddedDiff","text":"","category":"section"},{"location":"backends/","page":"Backends","title":"Backends","text":"Modules = [ManifoldDiff]\nPages = [\"embedded_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"backends/#ManifoldDiff.ExplicitEmbeddedBackend","page":"Backends","title":"ManifoldDiff.ExplicitEmbeddedBackend","text":"ExplicitEmbeddedBackend{TF<:NamedTuple}\n\nA backend to use with the RiemannianProjectionBackend or the TangentDiffBackend, when you have explicit formulae for the gradient in the embedding available.\n\nConstructor\n\nExplicitEmbeddedBackend(M::AbstractManifold; kwargs)\n\nConstruct an ExplicitEmbeddedBackend in the embedding M, where currently the following keywords may be used\n\ngradient for a(n allocating) gradient function gradient(M, p) defined in the embedding\ngradient! for a mutating gradient function gradient!(M, X, p).\n\nNote that the gradient functions are defined on the embedding manifold M passed to the Backend as well\n\n\n\n\n\n","category":"type"},{"location":"#ManifoldDiff","page":"Home","title":"ManifoldDiff","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The package ManifoldDiff aims to provide automatic calculation of Riemannian gradients of functions defined on manifolds. It builds upon Manifolds.jl.","category":"page"},{"location":"#Naming-scheme","page":"Home","title":"Naming scheme","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Providing a derivative, differential or gradient for a given function, this package adds that information to the function name. For example","category":"page"},{"location":"","page":"Home","title":"Home","text":"grad_f for a gradient operatornamegrad f\nsubgrad_f for a subgradient from the subdifferentialpartial f\ndifferential_f for Df (also called pushforward)\ndifferential_f_variable if f has multiple variables / parameters, since a usual writing in math is f_x in this case\nadjoint_differential_f for pullbacks\nadjoint_differential_f_variable if f has multiple variables / parameters\nf_derivative for f\njacobian_f for Jacobian matrix of f.\njacobian_f_variable if f has multiple parameters.","category":"page"},{"location":"","page":"Home","title":"Home","text":"the scheme is not completely fixed but tries to follow the mathematical notation.","category":"page"},{"location":"internals/#Internal-functions","page":"Internals","title":"Internal functions","text":"","category":"section"},{"location":"internals/","page":"Internals","title":"Internals","text":"ManifoldDiff.CurrentDiffBackend\nManifoldDiff._current_default_differential_backend\nManifoldDiff._hessian\nManifoldDiff._jacobian\nManifoldDiff._gradient\nManifoldDiff._derivative","category":"page"},{"location":"internals/#ManifoldDiff.CurrentDiffBackend","page":"Internals","title":"ManifoldDiff.CurrentDiffBackend","text":"CurrentDiffBackend(backend)\n\nA mutable struct for storing the current differentiation backend in a global constant _current_default_differential_backend.\n\nSee also\n\ndefault_differential_backend, set_default_differential_backend!\n\n\n\n\n\n","category":"type"},{"location":"internals/#ManifoldDiff._current_default_differential_backend","page":"Internals","title":"ManifoldDiff._current_default_differential_backend","text":"_current_default_differential_backend\n\nThe instance of CurrentDiffBackend that stores the globally default differentiation backend.\n\n\n\n\n\n","category":"constant"},{"location":"internals/#ManifoldDiff._hessian","page":"Internals","title":"ManifoldDiff._hessian","text":"_hessian(f, p[, backend])\n\nCompute the Hessian of a callable f at point p computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean Hessian.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"},{"location":"internals/#ManifoldDiff._jacobian","page":"Internals","title":"ManifoldDiff._jacobian","text":"_jacobian(f, p[, backend])\n\nCompute the Jacobian of a callable f at point p computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean Jacobians, for Riemannian Jacobian calculation see for example gradient.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"},{"location":"internals/#ManifoldDiff._gradient","page":"Internals","title":"ManifoldDiff._gradient","text":"_gradient(f, p[, backend])\n\nCompute the gradient of a callable f at point p computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean gradients, for Riemannian gradient calculation see for example gradient.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"},{"location":"internals/#ManifoldDiff._derivative","page":"Internals","title":"ManifoldDiff._derivative","text":"_derivative(f, t[, backend])\n\nCompute the derivative of a callable f at time t computed using the given backend. If the backend is not explicitly specified, it is obtained using the function default_differential_backend.\n\nThis function calculates plain Euclidean derivatives, for Riemannian differentiation see for example differential.\n\nnote: Note\nNot specifying the backend explicitly will usually result in a type instability and decreased performance.\n\n\n\n\n\n","category":"function"}] }