diff --git a/previews/PR628/features/atlases.html b/previews/PR628/features/atlases.html index 531a0880ab..5df887c33f 100644 --- a/previews/PR628/features/atlases.html +++ b/previews/PR628/features/atlases.html @@ -1,11 +1,11 @@ -Atlases and charts · Manifolds.jl
Edit on GitHub

Atlases and charts

Atlases on an $n$-dimensional manifold $\mathcal M$ are collections of charts $\mathcal A = \{(U_i, φ_i) \colon i \in I\}$, where $I$ is a (finite or infinte) index family, such that $U_i \subseteq \mathcal M$ is an open set and each chart $φ_i: U_i \to \mathbb{R}^n$ is a homeomorphism. This means, that $φ_i$ is bijective – sometimes also called one-to-one and onto - and continuous, and its inverse $φ_i^{-1}$ is continuous as well. The inverse $φ_i^{-1}$ is called (local) parametrization. The resulting parameters $a=φ(p)$ of $p$ (with respect to the chart $φ$) are in the literature also called “(local) coordinates”. To distinguish the parameter $a$ from get_coordinates in a basis, we use the terminology parameter in this package.

For an atlas $\mathcal A$ we further require that

\[\displaystyle\bigcup_{i\in I} U_i = \mathcal M.\]

We say that $φ_i$ is a chart about $p$, if $p\in U_i$. An atlas provides a connection between a manifold and the Euclidean space $\mathbb{R}^n$, since locally, a chart about $p$ can be used to identify its neighborhood (as long as you stay in $U_i$) with a subset of a Euclidean space. Most manifolds we consider are smooth, i.e. any change of charts $φ_i \circ φ_j^{-1}: \mathbb{R}^n\to\mathbb{R}^n$, where $i,j\in I$, is a smooth function. These changes of charts are also called transition maps.

Most operations on manifolds in Manifolds.jl avoid operating in a chart through appropriate embeddings and formulas derived for particular manifolds, though atlases provide the most general way of working with manifolds. Compared to these approaches, using an atlas is often more technical and time-consuming. They are extensively used in metric-related functions on MetricManifolds.

Atlases are represented by objects of subtypes of AbstractAtlas. There are no type restrictions for indices of charts in atlases.

Operations using atlases and charts are available through the following functions:

  • get_chart_index can be used to select an appropriate chart for the neighborhood of a given point $p$. This function should work deterministically, i.e. for a fixed $p$ always return the same chart.
  • get_parameters converts a point to its parameters with respect to the chart in a chart.
  • get_point converts parameters (local coordinates) in a chart to the point that corresponds to them.
  • induced_basis returns a basis of a given vector space at a point induced by a chart $φ$.
  • transition_map converts coordinates of a point between two charts, e.g. computes $φ_i\circ φ_j^{-1}: \mathbb{R}^n\to\mathbb{R}^n$, $i,j\in I$.

While an atlas could store charts as explicit functions, it is favourable, that the [get_parameters] actually implements a chart $φ$, get_point its inverse, the prametrization $φ^{-1}$.

Manifolds.AbstractAtlas — Type
AbstractAtlas{𝔽}

An abstract class for atlases whith charts that have values in the vector space 𝔽ⁿ for some value of n. 𝔽 is a number system determined by an AbstractNumbers object.

source
Manifolds.InducedBasis — Type
InducedBasis(vs::VectorSpaceType, A::AbstractAtlas, i)

The basis induced by chart with index i from an AbstractAtlas A of vector space of type vs.

For the vs a TangentSpace this works as follows:

Let $n$ denote the dimension of the manifold $\mathcal M$.

Let the parameter $a=φ_i(p) ∈ \mathbb R^n$ and $j∈\{1,…,n\}$. We can look at the $j$th parameter curve $b_j(t) = a + te_j$, where $e_j$ denotes the $j$th unit vector. Using the parametrisation we obtain a curve $c_j(t) = φ_i^{-1}(b_j(t))$ which fulfills $c(0) = p$.

Now taking the derivative(s) with respect to $t$ (and evaluate at $t=0$), we obtain a tangent vector for each $j$ corresponding to an equivalence class of curves (having the same derivative) as

\[X_j = [c_j] = \frac{\mathrm{d}}{\mathrm{d}t} c_i(t) \Bigl|_{t=0}\]

and the set $\{X_1,\ldots,X_n\}$ is the chart-induced basis of $T_p\mathcal M$.

See also

VectorSpaceType, AbstractBasis

source
Manifolds.RetractionAtlas — Type
RetractionAtlas{
+Atlases and charts · Manifolds.jl
Edit on GitHub
Atlases and charts
Atlases on an $n$-dimensional manifold $\mathcal M$ are collections of charts $\mathcal A = \{(U_i, φ_i) \colon i \in I\}$, where $I$ is a (finite or infinte) index family, such that $U_i \subseteq \mathcal M$ is an open set and each chart $φ_i: U_i \to \mathbb{R}^n$ is a homeomorphism. This means, that $φ_i$ is bijective – sometimes also called one-to-one and onto - and continuous, and its inverse $φ_i^{-1}$ is continuous as well. The inverse $φ_i^{-1}$ is called (local) parametrization. The resulting parameters $a=φ(p)$ of $p$ (with respect to the chart $φ$) are in the literature also called “(local) coordinates”. To distinguish the parameter $a$ from  get_coordinates in a basis, we use the terminology parameter in this package.
For an atlas $\mathcal A$ we further require that
\[\displaystyle\bigcup_{i\in I} U_i = \mathcal M.\]
We say that $φ_i$ is a chart about $p$, if $p\in U_i$. An atlas provides a connection between a manifold and the Euclidean space $\mathbb{R}^n$, since locally, a chart about $p$ can be used to identify its neighborhood (as long as you stay in $U_i$) with a subset of a Euclidean space. Most manifolds we consider are smooth, i.e. any change of charts $φ_i \circ φ_j^{-1}: \mathbb{R}^n\to\mathbb{R}^n$, where $i,j\in I$, is a smooth function. These changes of charts are also called transition maps.
Most operations on manifolds in Manifolds.jl avoid operating in a chart through appropriate embeddings and formulas derived for particular manifolds, though atlases provide the most general way of working with manifolds. Compared to these approaches, using an atlas is often more technical and time-consuming. They are extensively used in metric-related functions on MetricManifolds.
Atlases are represented by objects of subtypes of AbstractAtlas. There are no type restrictions for indices of charts in atlases.
Operations using atlases and charts are available through the following functions:
  • get_chart_index can be used to select an appropriate chart for the neighborhood of a given point $p$. This function should work deterministically, i.e. for a fixed $p$ always return the same chart.
  • get_parameters converts a point to its parameters with respect to the chart in a chart.
  • get_point converts parameters (local coordinates) in a chart to the point that corresponds to them.
  • induced_basis returns a basis of a given vector space at a point induced by a chart $φ$.
  • transition_map converts coordinates of a point between two charts, e.g. computes $φ_i\circ φ_j^{-1}: \mathbb{R}^n\to\mathbb{R}^n$, $i,j\in I$.
While an atlas could store charts as explicit functions, it is favourable, that the [get_parameters] actually implements a chart $φ$, get_point its inverse, the prametrization $φ^{-1}$.
Manifolds.AbstractAtlas — Type
AbstractAtlas{𝔽}
An abstract class for atlases whith charts that have values in the vector space 𝔽ⁿ for some value of n. 𝔽 is a number system determined by an AbstractNumbers object.
source
Manifolds.InducedBasis — Type
InducedBasis(vs::VectorSpaceType, A::AbstractAtlas, i)
The basis induced by chart with index i from an AbstractAtlas A of vector space of type vs.
For the vs a TangentSpace this works as  follows:
Let $n$ denote the dimension of the manifold $\mathcal M$.
Let the parameter $a=φ_i(p) ∈ \mathbb R^n$ and $j∈\{1,…,n\}$. We can look at the $j$th parameter curve $b_j(t) = a + te_j$, where $e_j$ denotes the $j$th unit vector. Using the parametrisation we obtain a curve $c_j(t) = φ_i^{-1}(b_j(t))$ which fulfills $c(0) = p$.
Now taking the derivative(s) with respect to $t$ (and evaluate at $t=0$), we obtain a tangent vector for each $j$ corresponding to an equivalence class of curves (having the same derivative) as
\[X_j = [c_j] = \frac{\mathrm{d}}{\mathrm{d}t} c_i(t) \Bigl|_{t=0}\]
and the set $\{X_1,\ldots,X_n\}$ is the chart-induced basis of $T_p\mathcal M$.
See also
VectorSpaceType, AbstractBasis
source
Manifolds.RetractionAtlas — Type
RetractionAtlas{
     𝔽,
     TRetr<:AbstractRetractionMethod,
     TInvRetr<:AbstractInverseRetractionMethod,
     TBasis<:AbstractBasis,
-} <: AbstractAtlas{𝔽}
An atlas indexed by points on a manifold, $\mathcal M = I$ and parameters (local coordinates) are given in $T_p\mathcal M$. This means that a chart $φ_p = \mathrm{cord}\circ\mathrm{retr}_p^{-1}$ is only locally defined (around $p$), where $\mathrm{cord}$ is the decomposition of the tangent vector into coordinates with respect to the given basis of the tangent space, cf. get_coordinates. The parametrization is given by $φ_p^{-1}=\mathrm{retr}_p\circ\mathrm{vec}$, where $\mathrm{vec}$ turns the basis coordinates into a tangent vector, cf. get_vector.
In short: The coordinates with respect to a basis are used together with a retraction as a parametrization.
See also
AbstractAtlas, AbstractInverseRetractionMethod, AbstractRetractionMethod, AbstractBasis
source
LinearAlgebra.norm — Method
norm(M::AbstractManifold, A::AbstractAtlas, i, a, Xc)
Calculate norm on manifold M at point with parameters a in chart i of an AbstractAtlas A of vector with coefficients Xc in induced basis.
source
Manifolds.affine_connection! — Method
affine_connection!(M::AbstractManifold, Zc, A::AbstractAtlas, i, a, Xc, Yc)
Calculate affine connection on manifold M at point with parameters a in chart i of an an AbstractAtlas A of vectors with coefficients Zc and Yc in induced basis and save the result in Zc.
source
Manifolds.affine_connection — Method
affine_connection(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)
Calculate affine connection on manifold M at point with parameters a in chart i of AbstractAtlas A of vectors with coefficients Xc and Yc in induced basis.
source
Manifolds.check_chart_switch — Method
check_chart_switch(M::AbstractManifold, A::AbstractAtlas, i, a)
Determine whether chart should be switched when an operation in chart i from an AbstractAtlas A reaches parameters a in that chart.
By default false is returned.
source
Manifolds.get_chart_index — Method
get_chart_index(M::AbstractManifold, A::AbstractAtlas, i, a)
Select a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point with parametrization a in chart i. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.
See also
get_default_atlas
source
Manifolds.get_chart_index — Method
get_chart_index(M::AbstractManifold, A::AbstractAtlas, p)
Select a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point p. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.
See also
get_default_atlas
source
Manifolds.get_parameters — Method
get_parameters(M::AbstractManifold, A::AbstractAtlas, i, p)
Calculate parameters (local coordinates) of point p on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the chart $φ_i(p), i\in I$. The parameters are in the number system determined by A. If the point $p\notin U_i$ is not in the domain of the chart, this method should throw an error.
See also
get_point, get_chart_index
source
Manifolds.get_point — Method
get_point(M::AbstractManifold, A::AbstractAtlas, i, a)
Calculate point at parameters (local coordinates) a on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the inverse $φ_i^{-1}(a), i\in I$ of a chart, also called a parametrization.
See also
get_parameters, get_chart_index
source
Manifolds.local_metric — Method
local_metric(M::AbstractManifold, p, B::InducedBasis)
Compute the local metric tensor for vectors expressed in terms of coordinates in basis B on manifold M. The point p is not checked.
source
Manifolds.transition_map — Method
transition_map(M::AbstractManifold, A_from::AbstractAtlas, i_from, A_to::AbstractAtlas, i_to, a)
-transition_map(M::AbstractManifold, A::AbstractAtlas, i_from, i_to, a)
Given coordinates a in chart (A_from, i_from) of a point on manifold M, returns coordinates of that point in chart (A_to, i_to). If A_from and A_to are equal, A_to can be omitted.
Mathematically this function is the transition map or change of charts, but it might even be between two atlases $A_{\text{from}} = \{(U_i,φ_i)\}_{i\in I}$ and $A_{\text{to}} = \{(V_j,\psi_j)\}_{j\in J}$, and hence $I, J$ are their index sets. We have $i_{\text{from}}\in I$, $i_{\text{to}}\in J$.
This method then computes
\[\bigl(\psi_{i_{\text{to}}}\circ φ_{i_{\text{from}}}^{-1}\bigr)(a)\]
Note that, similarly to get_parameters, this method should fail the same way if $V_{i_{\text{to}}}\cap U_{i_{\text{from}}}=\emptyset$.
See also
AbstractAtlas, get_parameters, get_point
source
Manifolds.transition_map_diff — Method
transition_map_diff(M::AbstractManifold, A::AbstractAtlas, i_from, a, c, i_to)
Compute differential of transition map from chart i_from to chart i_to from an AbstractAtlas A on manifold M at point with parameters a on tangent vector with coordinates c in the induced basis.
source
ManifoldsBase.inner — Method
inner(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)
Calculate inner product on manifold M at point with parameters a in chart i of an atlas A of vectors with coefficients Xc and Yc in induced basis.
source
Cotangent space and musical isomorphisms
Related to atlases, there is also support for the cotangent space and coefficients of cotangent vectors in bases of the cotangent space.
Functions sharp and flat implement musical isomorphisms for arbitrary vector bundles.
Manifolds.flat — Method
flat(M::AbstractManifold, p, X)
Compute the flat isomorphism (one of the musical isomorphisms) of tangent vector X from the vector space of type M at point p from the underlying AbstractManifold.
The function can be used for example to transform vectors from the tangent bundle to vectors from the cotangent bundle $♭ : T\mathcal M → T^{*}\mathcal M$
source
Manifolds.sharp — Method
sharp(M::AbstractManifold, p, ξ)
Compute the sharp isomorphism (one of the musical isomorphisms) of vector ξ from the vector space M at point p from the underlying AbstractManifold.
The function can be used for example to transform vectors from the cotangent bundle to vectors from the tangent bundle $♯ : T^{*}\mathcal M → T\mathcal M$
source
Computations in charts
Manifolds.IntegratorTerminatorNearChartBoundary — Type
IntegratorTerminatorNearChartBoundary{TKwargs}
An object for determining the point at which integration of a differential equation in a chart on a manifold should be terminated for the purpose of switching a chart.
The value stored in check_chart_switch_kwargs will be passed as keyword arguments to  check_chart_switch. By default an empty tuple is stored.
source
Manifolds.estimate_distance_from_bvp — Function
estimate_distance_from_bvp(
+} <: AbstractAtlas{𝔽}
An atlas indexed by points on a manifold, $\mathcal M = I$ and parameters (local coordinates) are given in $T_p\mathcal M$. This means that a chart $φ_p = \mathrm{cord}\circ\mathrm{retr}_p^{-1}$ is only locally defined (around $p$), where $\mathrm{cord}$ is the decomposition of the tangent vector into coordinates with respect to the given basis of the tangent space, cf. get_coordinates. The parametrization is given by $φ_p^{-1}=\mathrm{retr}_p\circ\mathrm{vec}$, where $\mathrm{vec}$ turns the basis coordinates into a tangent vector, cf. get_vector.
In short: The coordinates with respect to a basis are used together with a retraction as a parametrization.
See also
AbstractAtlas, AbstractInverseRetractionMethod, AbstractRetractionMethod, AbstractBasis
source
LinearAlgebra.norm — Method
norm(M::AbstractManifold, A::AbstractAtlas, i, a, Xc)
Calculate norm on manifold M at point with parameters a in chart i of an AbstractAtlas A of vector with coefficients Xc in induced basis.
source
Manifolds.affine_connection! — Method
affine_connection!(M::AbstractManifold, Zc, A::AbstractAtlas, i, a, Xc, Yc)
Calculate affine connection on manifold M at point with parameters a in chart i of an an AbstractAtlas A of vectors with coefficients Zc and Yc in induced basis and save the result in Zc.
source
Manifolds.affine_connection — Method
affine_connection(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)
Calculate affine connection on manifold M at point with parameters a in chart i of AbstractAtlas A of vectors with coefficients Xc and Yc in induced basis.
source
Manifolds.check_chart_switch — Method
check_chart_switch(M::AbstractManifold, A::AbstractAtlas, i, a)
Determine whether chart should be switched when an operation in chart i from an AbstractAtlas A reaches parameters a in that chart.
By default false is returned.
source
Manifolds.get_chart_index — Method
get_chart_index(M::AbstractManifold, A::AbstractAtlas, i, a)
Select a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point with parametrization a in chart i. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.
See also
get_default_atlas
source
Manifolds.get_chart_index — Method
get_chart_index(M::AbstractManifold, A::AbstractAtlas, p)
Select a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point p. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.
See also
get_default_atlas
source
Manifolds.get_parameters — Method
get_parameters(M::AbstractManifold, A::AbstractAtlas, i, p)
Calculate parameters (local coordinates) of point p on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the chart $φ_i(p), i\in I$. The parameters are in the number system determined by A. If the point $p\notin U_i$ is not in the domain of the chart, this method should throw an error.
See also
get_point, get_chart_index
source
Manifolds.get_point — Method
get_point(M::AbstractManifold, A::AbstractAtlas, i, a)
Calculate point at parameters (local coordinates) a on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the inverse $φ_i^{-1}(a), i\in I$ of a chart, also called a parametrization.
See also
get_parameters, get_chart_index
source
Manifolds.local_metric — Method
local_metric(M::AbstractManifold, p, B::InducedBasis)
Compute the local metric tensor for vectors expressed in terms of coordinates in basis B on manifold M. The point p is not checked.
source
Manifolds.transition_map — Method
transition_map(M::AbstractManifold, A_from::AbstractAtlas, i_from, A_to::AbstractAtlas, i_to, a)
+transition_map(M::AbstractManifold, A::AbstractAtlas, i_from, i_to, a)
Given coordinates a in chart (A_from, i_from) of a point on manifold M, returns coordinates of that point in chart (A_to, i_to). If A_from and A_to are equal, A_to can be omitted.
Mathematically this function is the transition map or change of charts, but it might even be between two atlases $A_{\text{from}} = \{(U_i,φ_i)\}_{i\in I}$ and $A_{\text{to}} = \{(V_j,\psi_j)\}_{j\in J}$, and hence $I, J$ are their index sets. We have $i_{\text{from}}\in I$, $i_{\text{to}}\in J$.
This method then computes
\[\bigl(\psi_{i_{\text{to}}}\circ φ_{i_{\text{from}}}^{-1}\bigr)(a)\]
Note that, similarly to get_parameters, this method should fail the same way if $V_{i_{\text{to}}}\cap U_{i_{\text{from}}}=\emptyset$.
See also
AbstractAtlas, get_parameters, get_point
source
Manifolds.transition_map_diff — Method
transition_map_diff(M::AbstractManifold, A::AbstractAtlas, i_from, a, c, i_to)
Compute differential of transition map from chart i_from to chart i_to from an AbstractAtlas A on manifold M at point with parameters a on tangent vector with coordinates c in the induced basis.
source
ManifoldsBase.inner — Method
inner(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)
Calculate inner product on manifold M at point with parameters a in chart i of an atlas A of vectors with coefficients Xc and Yc in induced basis.
source
Cotangent space and musical isomorphisms
Related to atlases, there is also support for the cotangent space and coefficients of cotangent vectors in bases of the cotangent space.
Functions sharp and flat implement musical isomorphisms for arbitrary vector bundles.
Manifolds.flat — Method
flat(M::AbstractManifold, p, X)
Compute the flat isomorphism (one of the musical isomorphisms) of tangent vector X from the vector space of type M at point p from the underlying AbstractManifold.
The function can be used for example to transform vectors from the tangent bundle to vectors from the cotangent bundle $♭ : T\mathcal M → T^{*}\mathcal M$
source
Manifolds.sharp — Method
sharp(M::AbstractManifold, p, ξ)
Compute the sharp isomorphism (one of the musical isomorphisms) of vector ξ from the vector space M at point p from the underlying AbstractManifold.
The function can be used for example to transform vectors from the cotangent bundle to vectors from the tangent bundle $♯ : T^{*}\mathcal M → T\mathcal M$
source
Computations in charts
Manifolds.IntegratorTerminatorNearChartBoundary — Type
IntegratorTerminatorNearChartBoundary{TKwargs}
An object for determining the point at which integration of a differential equation in a chart on a manifold should be terminated for the purpose of switching a chart.
The value stored in check_chart_switch_kwargs will be passed as keyword arguments to  check_chart_switch. By default an empty tuple is stored.
source
Manifolds.solve_chart_exp_ode — Function
solve_chart_exp_ode(
     M::AbstractManifold,
     a,
     Xc,
@@ -24,7 +24,7 @@
     final_time=1.0,
     check_chart_switch_kwargs=NamedTuple(),
     kwargs...,
-)
Solve geodesic ODE on a manifold M from point of coordinates a in chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.
source
Manifolds.solve_chart_log_bvp — Function
solve_chart_log_bvp(
     M::AbstractManifold,
     a1,
     a2,
@@ -33,7 +33,7 @@
     solver=GeneralMIRK4(),
     dt=0.05,
     kwargs...,
-)
Solve the BVP corresponding to geodesic calculation on AbstractManifold M, between points with parameters a1 and a2 in a chart i of an AbstractAtlas A using solver solver. Geodesic γ is sampled at time interval dt, with γ(0) = a1 and γ(1) = a2.
source
Manifolds.solve_chart_parallel_transport_ode — Function
solve_chart_parallel_transport_ode(
     M::AbstractManifold,
     a,
     Xc,
@@ -44,4 +44,4 @@
     check_chart_switch_kwargs=NamedTuple(),
     final_time=1.0,
     kwargs...,
-)
Parallel transport vector with coordinates Yc along geodesic on a manifold M from point of coordinates a in a chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.
source

+)

Parallel transport vector with coordinates Yc along geodesic on a manifold M from point of coordinates a in a chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.

source
diff --git a/previews/PR628/features/differentiation.html b/previews/PR628/features/differentiation.html index 0b1f544f26..e9f327be89 100644 --- a/previews/PR628/features/differentiation.html +++ b/previews/PR628/features/differentiation.html @@ -1,2 +1,2 @@ -Differentiation · Manifolds.jl
Edit on GitHub
+Differentiation · Manifolds.jl
Edit on GitHub
diff --git a/previews/PR628/features/distributions.html b/previews/PR628/features/distributions.html index 31e9f3eff4..a7c9f36907 100644 --- a/previews/PR628/features/distributions.html +++ b/previews/PR628/features/distributions.html @@ -1,2 +1,2 @@ -Distributions · Manifolds.jl
Edit on GitHub

Distributions

The following functions and types provide support for manifold-valued and tangent space-valued distributions:

Manifolds.FVectorDistribution — Type
FVectorDistribution{TSpace<:VectorBundleFibers, T}

An abstract distribution for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at point x from the given manifold). For example used for tangent vector-valued distributions.

source
Manifolds.FVectorSupport — Type
FVectorSupport(space::AbstractManifold, VectorBundleFibers)

Value support for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at a point from the given manifold). For example used for tangent vector-valued distributions.

source
Manifolds.FVectorvariate — Type
FVectorvariate

Structure that subtypes VariateForm, indicating that a single sample is a vector from a fiber of a vector bundle.

source
Manifolds.MPointvariate — Type
MPointvariate

Structure that subtypes VariateForm, indicating that a single sample is a point on a manifold.

source
Manifolds.ProjectedFVectorDistribution — Type
ProjectedFVectorDistribution(type::VectorBundleFibers, p, d, project!)

Generates a random vector from ambient space of manifold type.manifold at point p and projects it to vector space of type type using function project!, see project for documentation. Generated arrays are of type TResult.

source
Manifolds.ProjectedPointDistribution — Type
ProjectedPointDistribution(M::AbstractManifold, d, proj!, p)

Generates a random point in ambient space of M and projects it to M using function proj!. Generated arrays are of type TResult, which can be specified by providing the p argument.

source
Manifolds.projected_distribution — Function
projected_distribution(M::AbstractManifold, d, [p=rand(d)])

Wrap the standard distribution d into a manifold-valued distribution. Generated points will be of similar type to p. By default, the type is not changed.

source
+Distributions · Manifolds.jl
Edit on GitHub

Distributions

The following functions and types provide support for manifold-valued and tangent space-valued distributions:

Manifolds.FVectorDistribution — Type
FVectorDistribution{TSpace<:VectorBundleFibers, T}

An abstract distribution for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at point x from the given manifold). For example used for tangent vector-valued distributions.

source
Manifolds.FVectorSupport — Type
FVectorSupport(space::AbstractManifold, VectorBundleFibers)

Value support for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at a point from the given manifold). For example used for tangent vector-valued distributions.

source
Manifolds.FVectorvariate — Type
FVectorvariate

Structure that subtypes VariateForm, indicating that a single sample is a vector from a fiber of a vector bundle.

source
Manifolds.MPointvariate — Type
MPointvariate

Structure that subtypes VariateForm, indicating that a single sample is a point on a manifold.

source
Manifolds.ProjectedFVectorDistribution — Type
ProjectedFVectorDistribution(type::VectorBundleFibers, p, d, project!)

Generates a random vector from ambient space of manifold type.manifold at point p and projects it to vector space of type type using function project!, see project for documentation. Generated arrays are of type TResult.

source
Manifolds.ProjectedPointDistribution — Type
ProjectedPointDistribution(M::AbstractManifold, d, proj!, p)

Generates a random point in ambient space of M and projects it to M using function proj!. Generated arrays are of type TResult, which can be specified by providing the p argument.

source
Manifolds.projected_distribution — Function
projected_distribution(M::AbstractManifold, d, [p=rand(d)])

Wrap the standard distribution d into a manifold-valued distribution. Generated points will be of similar type to p. By default, the type is not changed.

source
diff --git a/previews/PR628/features/integration.html b/previews/PR628/features/integration.html index 00d4b379d2..57802a4cb7 100644 --- a/previews/PR628/features/integration.html +++ b/previews/PR628/features/integration.html @@ -1,2 +1,2 @@ -Integration · Manifolds.jl
Edit on GitHub

Integration

Manifolds.manifold_volume — Method
manifold_volume(M::AbstractManifold)

Volume of manifold M defined through integration of Riemannian volume element in a chart. Note that for many manifolds there is no universal agreement over the exact ranges over which the integration should happen. For details see [BoyaSudarshanTilma2003].

source
Manifolds.volume_density — Method
volume_density(M::AbstractManifold, p, X)

Volume density function of manifold M, i.e. determinant of the differential of exponential map exp(M, p, X). Determinant can be understood as computed in a basis, from the matrix of the linear operator said differential corresponds to. Details are available in Section 4.1 of [ChevallierLiLuDunson2022].

Note that volume density is well-defined only for X for which exp(M, p, X) is injective.

source
+Integration · Manifolds.jl
Edit on GitHub

Integration

Manifolds.manifold_volume — Method
manifold_volume(M::AbstractManifold)

Volume of manifold M defined through integration of Riemannian volume element in a chart. Note that for many manifolds there is no universal agreement over the exact ranges over which the integration should happen. For details see [BoyaSudarshanTilma2003].

source
Manifolds.volume_density — Method
volume_density(M::AbstractManifold, p, X)

Volume density function of manifold M, i.e. determinant of the differential of exponential map exp(M, p, X). Determinant can be understood as computed in a basis, from the matrix of the linear operator said differential corresponds to. Details are available in Section 4.1 of [ChevallierLiLuDunson2022].

Note that volume density is well-defined only for X for which exp(M, p, X) is injective.

source
diff --git a/previews/PR628/features/statistics.html b/previews/PR628/features/statistics.html index f0d15c831e..bee9bf649f 100644 --- a/previews/PR628/features/statistics.html +++ b/previews/PR628/features/statistics.html @@ -1,9 +1,9 @@ -Statistics · Manifolds.jl
Edit on GitHub

Statistics

Manifolds.GeodesicInterpolation — Type
GeodesicInterpolation <: AbstractEstimationMethod

Repeated weighted geodesic interpolation method for estimating the Riemannian center of mass.

The algorithm proceeds with the following simple online update:

\[\begin{aligned} +Statistics · Manifolds.jl

Edit on GitHub

Statistics

Manifolds.GeodesicInterpolation — Type
GeodesicInterpolation <: AbstractEstimationMethod

Repeated weighted geodesic interpolation method for estimating the Riemannian center of mass.

The algorithm proceeds with the following simple online update:

\[\begin{aligned} μ_1 &= x_1\\ t_k &= \frac{w_k}{\sum_{i=1}^k w_i}\\ μ_{k} &= γ_{μ_{k-1}}(x_k; t_k), -\end{aligned}\]

where $x_k$ are points, $w_k$ are weights, $μ_k$ is the $k$th estimate of the mean, and $γ_x(y; t)$ is the point at time $t$ along the shortest_geodesic between points $x,y ∈ \mathcal M$. The algorithm terminates when all $x_k$ have been considered. In the Euclidean case, this exactly computes the weighted mean.

The algorithm has been shown to converge asymptotically with the sample size for the following manifolds equipped with their default metrics when all sampled points are in an open geodesic ball about the mean with corresponding radius (see GeodesicInterpolationWithinRadius):

For online variance computation, the algorithm additionally uses an analogous recursion to the weighted Welford algorithm [West1979].

source
Manifolds.default_estimation_method — Method
default_estimation_method(M::AbstractManifold, f)

Specify a default AbstractEstimationMethod for an AbstractManifold for a function f, e.g. the median or the mean.

Note that his function is decorated, so it can inherit from the embedding, for example for the IsEmbeddedSubmanifold trait.

source
Statistics.cov — Method
Statistics.cov(
+\end{aligned}\]
where $x_k$ are points, $w_k$ are weights, $μ_k$ is the $k$th estimate of the mean, and $γ_x(y; t)$ is the point at time $t$ along the shortest_geodesic between points $x,y ∈ \mathcal M$. The algorithm terminates when all $x_k$ have been considered. In the Euclidean case, this exactly computes the weighted mean.
The algorithm has been shown to converge asymptotically with the sample size for the following manifolds equipped with their default metrics when all sampled points are in an open geodesic ball about the mean with corresponding radius (see GeodesicInterpolationWithinRadius):
For online variance computation, the algorithm additionally uses an analogous recursion to the weighted Welford algorithm [West1979].
source
Manifolds.default_estimation_method — Method
default_estimation_method(M::AbstractManifold, f)

Specify a default AbstractEstimationMethod for an AbstractManifold for a function f, e.g. the median or the mean.

Note that his function is decorated, so it can inherit from the embedding, for example for the IsEmbeddedSubmanifold trait.

source
Statistics.cov — Method
Statistics.cov(
     M::AbstractManifold,
     x::AbstractVector;
     basis::AbstractBasis=DefaultOrthonormalBasis(),
@@ -14,7 +14,7 @@
     inverse_retraction_method::AbstractInverseRetractionMethod=default_inverse_retraction_method(
         M, eltype(x),
     ),
-)

Estimate the covariance matrix of a set of points x on manifold M. Since the covariance matrix on a manifold is a rank 2 tensor, the function returns its coefficients in basis induced by the given tangent space basis. See Section 5 of [Pennec2006] for details.

The mean is calculated using the specified mean_estimation_method using [mean](@ref Statistics.mean(::AbstractManifold, ::AbstractVector, ::AbstractEstimationMethod), and tangent vectors at this mean are calculated using the provided inverse_retraction_method. Finally, the covariance matrix in the tangent plane is estimated using the Euclidean space estimator tangent_space_covariance_estimator. The type CovarianceEstimator is defined in StatsBase.jl and examples of covariance estimation methods can be found in CovarianceEstimation.jl.

source
Statistics.mean! — Method
mean!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)
+)

Estimate the covariance matrix of a set of points x on manifold M. Since the covariance matrix on a manifold is a rank 2 tensor, the function returns its coefficients in basis induced by the given tangent space basis. See Section 5 of [Pennec2006] for details.

The mean is calculated using the specified mean_estimation_method using [mean](@ref Statistics.mean(::AbstractManifold, ::AbstractVector, ::AbstractEstimationMethod), and tangent vectors at this mean are calculated using the provided inverse_retraction_method. Finally, the covariance matrix in the tangent plane is estimated using the Euclidean space estimator tangent_space_covariance_estimator. The type CovarianceEstimator is defined in StatsBase.jl and examples of covariance estimation methods can be found in CovarianceEstimation.jl.

source
Statistics.mean! — Method
mean!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)
 mean!(
     M::AbstractManifold,
     y,
@@ -22,19 +22,19 @@
     [w::AbstractWeights,]
     method::AbstractEstimationMethod;
     kwargs...,
-)

Compute the mean in-place in y.

source
Statistics.mean — Method
mean(
     M::AbstractManifold,
     x::AbstractVector,
     [w::AbstractWeights,]
     method::ExtrinsicEstimation;
     kwargs...,
-)

Estimate the Riemannian center of mass of x using ExtrinsicEstimation, i.e. by computing the mean in the embedding and projecting the result back. You can specify an extrinsic_method to specify which mean estimation method to use in the embedding, which defaults to GeodesicInterpolation.

See mean for a description of the remaining kwargs.

source
Statistics.mean — Method
mean(
+)

Estimate the Riemannian center of mass of x using ExtrinsicEstimation, i.e. by computing the mean in the embedding and projecting the result back. You can specify an extrinsic_method to specify which mean estimation method to use in the embedding, which defaults to GeodesicInterpolation.

See mean for a description of the remaining kwargs.

source
Statistics.mean — Method
mean(
     M::AbstractManifold,
     x::AbstractVector,
     [w::AbstractWeights,]
@@ -43,7 +43,7 @@
     retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),
     inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),
     kwargs...,
-)

Estimate the Riemannian center of mass of x in an online fashion using repeated weighted geodesic interpolation. See GeodesicInterpolation for details.

If shuffle_rng is provided, it is used to shuffle the order in which the points are considered for computing the mean.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

source
Statistics.mean — Method
mean(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)

Compute the (optionally weighted) Riemannian center of mass also known as Karcher mean of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer

\[\argmin_{y ∈ \mathcal M} \frac{1}{2 \sum_{i=1}^n w_i} \sum_{i=1}^n w_i\mathrm{d}_{\mathcal M}^2(y,x_i),\]

where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance.

In the general case, the GradientDescentEstimation is used to compute the mean. mean( M::AbstractManifold, x::AbstractVector, [w::AbstractWeights,] method::AbstractEstimationMethod=defaultestimationmethod(M); kwargs..., )

Compute the mean using the specified method.

mean(
+)

Estimate the Riemannian center of mass of x in an online fashion using repeated weighted geodesic interpolation. See GeodesicInterpolation for details.

If shuffle_rng is provided, it is used to shuffle the order in which the points are considered for computing the mean.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

source
Statistics.mean — Method
mean(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)

Compute the (optionally weighted) Riemannian center of mass also known as Karcher mean of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer

\[\argmin_{y ∈ \mathcal M} \frac{1}{2 \sum_{i=1}^n w_i} \sum_{i=1}^n w_i\mathrm{d}_{\mathcal M}^2(y,x_i),\]

where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance.

In the general case, the GradientDescentEstimation is used to compute the mean. mean( M::AbstractManifold, x::AbstractVector, [w::AbstractWeights,] method::AbstractEstimationMethod=defaultestimationmethod(M); kwargs..., )

Compute the mean using the specified method.

mean(
     M::AbstractManifold,
     x::AbstractVector,
     [w::AbstractWeights,]
@@ -53,7 +53,7 @@
     retraction::AbstractRetractionMethod = default_retraction_method(M),
     inverse_retraction::AbstractInverseRetractionMethod = default_retraction_method(M, eltype(x)),
     kwargs...,
-)

Compute the mean using the gradient descent scheme GradientDescentEstimation.

Optionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

The Theory stems from[Karcher1977] and is also described in[PennecArsigny2013] as the exponential barycenter. The algorithm is further described in[Afsari2013].

source
Statistics.median! — Method
median!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)
+)

Compute the mean using the gradient descent scheme GradientDescentEstimation.

Optionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

The Theory stems from[Karcher1977] and is also described in[PennecArsigny2013] as the exponential barycenter. The algorithm is further described in[Afsari2013].

source
Statistics.median! — Method
median!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)
 median!(
     M::AbstractManifold,
     y,
@@ -61,7 +61,7 @@
     [w::AbstractWeights,]
     method::AbstractEstimationMethod;
     kwargs...,
-)

computes the median in-place in y.

source
Statistics.median — Method
median(
     M::AbstractManifold,
     x::AbstractVector,
     [w::AbstractWeights,]
@@ -71,14 +71,14 @@
     retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x),),
     inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x),),
     kwargs...,
-)

Compute the median using CyclicProximalPointEstimation.

Optionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

The algorithm is further described in [Bačák2014].

source
Statistics.median — Method
median(
+)

Compute the median using CyclicProximalPointEstimation.

Optionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

The algorithm is further described in [Bačák2014].

source
Statistics.median — Method
median(
     M::AbstractManifold,
     x::AbstractVector,
     [w::AbstractWeights,]
     method::ExtrinsicEstimation;
     extrinsic_method = CyclicProximalPointEstimation(),
     kwargs...,
-)

Estimate the median of x using ExtrinsicEstimation, i.e. by computing the median in the embedding and projecting the result back. You can specify an extrinsic_method to specify which median estimation method to use in the embedding, which defaults to CyclicProximalPointEstimation.

See median for a description of kwargs.

source
Statistics.median — Method
median(
     M::AbstractManifold,
     x::AbstractVector,
     [w::AbstractWeights,]
@@ -93,28 +93,28 @@
 \quad
 \text{ with }
 \quad
-s = \sum_{i\in I_k} \frac{w_i}{d_{\mathcal M}(q_k,x_i)},\]
and where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance.
Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction, which by default use the exponential and logarithmic map, respectively.
source
Statistics.median — Method
median(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)
+s = \sum_{i\in I_k} \frac{w_i}{d_{\mathcal M}(q_k,x_i)},\]
and where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance.
Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction, which by default use the exponential and logarithmic map, respectively.
source
Statistics.median — Method
median(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)
 median(
     M::AbstractManifold,
     x::AbstractVector,
     [w::AbstractWeights,]
     method::AbstractEstimationMethod;
     kwargs...,
-)

Compute the (optionally weighted) Riemannian median of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer

\[\argmin_{y ∈ \mathcal M} \frac{1}{\sum_{i=1}^n w_i} \sum_{i=1}^n w_i\mathrm{d}_{\mathcal M}(y,x_i),\]

where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance. This function is nonsmooth (i.e nondifferentiable).

In the general case, the CyclicProximalPointEstimation is used to compute the median. However, this default may be overloaded for specific manifolds.

Compute the median using the specified method.

source
Statistics.std — Method
std(M, x, m=mean(M, x); corrected=true, kwargs...)
-std(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false, kwargs...)

compute the optionally weighted standard deviation of a Vector x of n data points on the AbstractManifold M, i.e.

\[\sqrt{\frac{1}{c} \sum_{i=1}^n w_i d_{\mathcal M}^2 (x_i,m)},\]

where c is a correction term, see Statistics.std. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true.

source
Statistics.var — Method
var(M, x, m=mean(M, x); corrected=true)
-var(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false)

compute the (optionally weighted) variance of a Vector x of n data points on the AbstractManifold M, i.e.

\[\frac{1}{c} \sum_{i=1}^n w_i d_{\mathcal M}^2 (x_i,m),\]

where c is a correction term, see Statistics.var. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true. All further kwargs... are passed to the computation of the mean (if that is not provided).

source
StatsBase.kurtosis — Method
kurtosis(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the excess kurtosis of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.

source
StatsBase.mean_and_std — Method
mean_and_std(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, std)

Compute the mean and the standard deviation std simultaneously.

mean_and_std(
+)

Compute the (optionally weighted) Riemannian median of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer

\[\argmin_{y ∈ \mathcal M} \frac{1}{\sum_{i=1}^n w_i} \sum_{i=1}^n w_i\mathrm{d}_{\mathcal M}(y,x_i),\]

where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance. This function is nonsmooth (i.e nondifferentiable).

In the general case, the CyclicProximalPointEstimation is used to compute the median. However, this default may be overloaded for specific manifolds.

Compute the median using the specified method.

source
Statistics.std — Method
std(M, x, m=mean(M, x); corrected=true, kwargs...)
+std(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false, kwargs...)

compute the optionally weighted standard deviation of a Vector x of n data points on the AbstractManifold M, i.e.

\[\sqrt{\frac{1}{c} \sum_{i=1}^n w_i d_{\mathcal M}^2 (x_i,m)},\]

where c is a correction term, see Statistics.std. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true.

source
Statistics.var — Method
var(M, x, m=mean(M, x); corrected=true)
+var(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false)

compute the (optionally weighted) variance of a Vector x of n data points on the AbstractManifold M, i.e.

\[\frac{1}{c} \sum_{i=1}^n w_i d_{\mathcal M}^2 (x_i,m),\]

where c is a correction term, see Statistics.var. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true. All further kwargs... are passed to the computation of the mean (if that is not provided).

source
StatsBase.kurtosis — Method
kurtosis(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the excess kurtosis of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.

source
StatsBase.mean_and_std — Method
mean_and_std(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, std)

Compute the mean and the standard deviation std simultaneously.

mean_and_std(
     M::AbstractManifold,
     x::AbstractVector
     [w::AbstractWeights,]
     method::AbstractEstimationMethod;
     kwargs...,
-) -> (mean, var)

Use the method for simultaneously computing the mean and standard deviation. To use a mean-specific method, call mean and then std.

source
StatsBase.mean_and_var — Method
mean_and_var(
+) -> (mean, var)

Use the method for simultaneously computing the mean and standard deviation. To use a mean-specific method, call mean and then std.

source
StatsBase.mean_and_var — Method
mean_and_var(
     M::AbstractManifold,
     x::AbstractVector
     [w::AbstractWeights,]
     method::GeodesicInterpolationWithinRadius;
     kwargs...,
-) -> (mean, var)

Use repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.

See GeodesicInterpolationWithinRadius and mean_and_var for more information.

source
StatsBase.mean_and_var — Method
mean_and_var(
     M::AbstractManifold,
     x::AbstractVector
     [w::AbstractWeights,]
@@ -123,10 +123,10 @@
     retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),
     inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),
     kwargs...,
-) -> (mean, var)

Use the repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.

If shuffle_rng is provided, it is used to shuffle the order in which the points are considered. Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

See GeodesicInterpolation for details on the geodesic interpolation method.

Note

The Welford algorithm for the variance is experimental and is not guaranteed to give accurate results except on Euclidean.

source
StatsBase.mean_and_var — Method
mean_and_var(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, var)

Compute the mean and the variance simultaneously. See those functions for a description of the arguments.

mean_and_var(
+) -> (mean, var)

Use the repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.

If shuffle_rng is provided, it is used to shuffle the order in which the points are considered. Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

See GeodesicInterpolation for details on the geodesic interpolation method.

Note

The Welford algorithm for the variance is experimental and is not guaranteed to give accurate results except on Euclidean.

source
StatsBase.mean_and_var — Method
mean_and_var(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, var)

Compute the mean and the variance simultaneously. See those functions for a description of the arguments.

mean_and_var(
     M::AbstractManifold,
     x::AbstractVector
     [w::AbstractWeights,]
     method::AbstractEstimationMethod;
     kwargs...,
-) -> (mean, var)

Use the method for simultaneously computing the mean and variance. To use a mean-specific method, call mean and then var.

source
StatsBase.moment — Function
moment(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the kth central moment of points in x on manifold M. Optionally provide weights w and/or a precomputed mean.

source
StatsBase.skewness — Method
skewness(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the standardized skewness of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.

source

Literature

  • Ho2013

    Ho J.; Cheng G.; Salehian H.; Vemuri B. C.; Recursive Karcher expectation estimators and geometric law of large numbers. Proceedings of the 16th International Conference on Artificial Intelligence and Statistics (2013), pp. 325–332. pdf.

  • Salehian2015

    Salehian H.; Chakraborty R.; Ofori E.; Vaillancourt D.; An efficient recursive estimator of the Fréchet mean on a hypersphere with applications to Medical Image Analysis. Mathematical Foundations of Computational Anatomy (2015). pdf.

  • Chakraborty2015

    Chakraborty R.; Vemuri B. C.; Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. Proceedings of the IEEE International Conference on Computer Vision (ICCV) (2015), pp. 4229-4237. doi: 10.1109/ICCV.2015.481, link.

  • Cheng2016

    Cheng G.; Ho J.; Salehian H.; Vemuri B. C.; Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. Riemannian Computing in Computer Vision. Springer, Cham (2016), pp. 21-43. doi: 10.1007/978-3-319-22957-7_2, pdf.

  • Chakraborty2019

    Chakraborty R.; Vemuri B. C.; Statistics on the (compact) Stiefel manifold: Theory and Applications. The Annals of Statistics (2019), 47(1), pp. 415-438. doi: 10.1214/18-AOS1692, arxiv: 1708.00045.

  • West1979

    West D. H. D.; Updating Mean and Variance Estimates: An Improved Method. Communications of the ACM (1979), 22(9), pp. 532–535. doi: 10.1145/359146.359153.

  • Pennec2006

    X. Pennec, “Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements,” J Math Imaging Vis, vol. 25, no. 1, p. 127, Jul. 2006, doi: 10.1007/s10851-006-6228-4.

  • Afsari2013

    Afsari, B; Tron, R.; Vidal, R.: On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass, SIAM Journal on Control and Optimization (2013), 51(3), pp. 2230–2260, doi: 10.1137/12086282X, arxiv: 1201.0925

  • PennecArsigny2013

    Pennec X., Arsigny V.: Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Nielsen F., Bhatia R. (eds) Matrix Information Geometry, (2013), pp. 123-166. doi: 10.1007/978-3-642-30232-9_7, hal: https://hal.inria.fr/hal-00699361/document

  • Karcher1977

    Karcher, H.: Riemannian center of mass and mollifier smoothing. Communications on Pure Applied Mathematics (1977), 30, pp. 509–541. doi 10.1002/cpa.3160300502

  • Bačák2014

    Bačák, M: Computing Medians and Means in Hadamard Spaces. SIAM Journal on Optimization (2014), 24(3), pp. 1542–1566, doi: 10.1137/140953393, arxiv: 1210.2145

  • FletcherVenkatasubramanianJoshi2008

    Fletcher, T., Venkatasubramanian, S., Joshi, S: Robust statistics on Riemannian manifolds via the geometric median 2008 IEEE Conference on Computer Vision and Pattern Recognition, doi: 10.1109/CVPR.2008.4587747,

+) -> (mean, var)

Use the method for simultaneously computing the mean and variance. To use a mean-specific method, call mean and then var.

source
StatsBase.moment — Function
moment(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the kth central moment of points in x on manifold M. Optionally provide weights w and/or a precomputed mean.

source
StatsBase.skewness — Method
skewness(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the standardized skewness of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.

source

Literature

  • Ho2013

    Ho J.; Cheng G.; Salehian H.; Vemuri B. C.; Recursive Karcher expectation estimators and geometric law of large numbers. Proceedings of the 16th International Conference on Artificial Intelligence and Statistics (2013), pp. 325–332. pdf.

  • Salehian2015

    Salehian H.; Chakraborty R.; Ofori E.; Vaillancourt D.; An efficient recursive estimator of the Fréchet mean on a hypersphere with applications to Medical Image Analysis. Mathematical Foundations of Computational Anatomy (2015). pdf.

  • Chakraborty2015

    Chakraborty R.; Vemuri B. C.; Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. Proceedings of the IEEE International Conference on Computer Vision (ICCV) (2015), pp. 4229-4237. doi: 10.1109/ICCV.2015.481, link.

  • Cheng2016

    Cheng G.; Ho J.; Salehian H.; Vemuri B. C.; Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. Riemannian Computing in Computer Vision. Springer, Cham (2016), pp. 21-43. doi: 10.1007/978-3-319-22957-7_2, pdf.

  • Chakraborty2019

    Chakraborty R.; Vemuri B. C.; Statistics on the (compact) Stiefel manifold: Theory and Applications. The Annals of Statistics (2019), 47(1), pp. 415-438. doi: 10.1214/18-AOS1692, arxiv: 1708.00045.

  • West1979

    West D. H. D.; Updating Mean and Variance Estimates: An Improved Method. Communications of the ACM (1979), 22(9), pp. 532–535. doi: 10.1145/359146.359153.

  • Pennec2006

    X. Pennec, “Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements,” J Math Imaging Vis, vol. 25, no. 1, p. 127, Jul. 2006, doi: 10.1007/s10851-006-6228-4.

  • Afsari2013

    Afsari, B; Tron, R.; Vidal, R.: On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass, SIAM Journal on Control and Optimization (2013), 51(3), pp. 2230–2260, doi: 10.1137/12086282X, arxiv: 1201.0925

  • PennecArsigny2013

    Pennec X., Arsigny V.: Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Nielsen F., Bhatia R. (eds) Matrix Information Geometry, (2013), pp. 123-166. doi: 10.1007/978-3-642-30232-9_7, hal: https://hal.inria.fr/hal-00699361/document

  • Karcher1977

    Karcher, H.: Riemannian center of mass and mollifier smoothing. Communications on Pure Applied Mathematics (1977), 30, pp. 509–541. doi 10.1002/cpa.3160300502

  • Bačák2014

    Bačák, M: Computing Medians and Means in Hadamard Spaces. SIAM Journal on Optimization (2014), 24(3), pp. 1542–1566, doi: 10.1137/140953393, arxiv: 1210.2145

  • FletcherVenkatasubramanianJoshi2008

    Fletcher, T., Venkatasubramanian, S., Joshi, S: Robust statistics on Riemannian manifolds via the geometric median 2008 IEEE Conference on Computer Vision and Pattern Recognition, doi: 10.1109/CVPR.2008.4587747,

diff --git a/previews/PR628/features/testing.html b/previews/PR628/features/testing.html index 4ecfc56a33..9c442e71c6 100644 --- a/previews/PR628/features/testing.html +++ b/previews/PR628/features/testing.html @@ -11,7 +11,7 @@ test_mutating_action=true, test_diff = false, test_switch_direction = true, -)

Tests general properties of the action A, given at least three different points that lie on it (contained in a_pts) and three different point that lie on the manifold it acts upon (contained in m_pts).

Arguments

source
Manifolds.test_group — Function
test_group(
+)

Tests general properties of the action A, given at least three different points that lie on it (contained in a_pts) and three different point that lie on the manifold it acts upon (contained in m_pts).

Arguments

  • atol_ident_compose = 0: absolute tolerance for the test that composition with identity doesn't change the group element.
source
Manifolds.test_group — Function
test_group(
     G,
     g_pts::AbstractVector,
     X_pts::AbstractVector = [],
@@ -24,8 +24,8 @@
     test_lie_bracket=false,
     test_adjoint_action=false,
     diff_convs = [(), (LeftForwardAction(),), (RightBackwardAction(),)],
-)

Tests general properties of the group G, given at least three different points elements of it (contained in g_pts). Optionally, specify test_diff to test differentials of translation, using X_pts, which must contain at least one tangent vector at g_pts[1], and the direction conventions specified in diff_convs. Xe_pts should contain tangent vectors at identity for testing Lie algebra operations. If the group is equipped with an invariant metric, test_invariance indicates that the invariance should be checked for the provided points.

source
Manifolds.test_manifold — Function
test_manifold(
+)

Tests general properties of the group G, given at least three different points elements of it (contained in g_pts). Optionally, specify test_diff to test differentials of translation, using X_pts, which must contain at least one tangent vector at g_pts[1], and the direction conventions specified in diff_convs. Xe_pts should contain tangent vectors at identity for testing Lie algebra operations. If the group is equipped with an invariant metric, test_invariance indicates that the invariance should be checked for the provided points.

source
Manifolds.test_manifold — Function
test_manifold(
     M::AbstractManifold,
     pts::AbstractVector;
     args,
-)

Test general properties of manifold M, given at least three different points that lie on it (contained in pts).

Arguments

  • basis_has_specialized_diagonalizing_get = false: if true, assumes that DiagonalizingOrthonormalBasis given in basis_types has get_coordinates and get_vector that work without caching.
  • basis_types_to_from = (): basis types that will be tested based on get_coordinates and get_vector.
  • basis_types_vecs = () : basis types that will be tested based on get_vectors
  • default_inverse_retraction_method = ManifoldsBase.LogarithmicInverseRetraction(): default method for inverse retractions (log.
  • default_retraction_method = ManifoldsBase.ExponentialRetraction(): default method for retractions (exp).
  • exp_log_atol_multiplier = 0: change absolute tolerance of exp/log tests (0 use default, i.e. deactivate atol and use rtol).
  • exp_log_rtol_multiplier = 1: change the relative tolerance of exp/log tests (1 use default). This is deactivated if the exp_log_atol_multiplier is nonzero.
  • expected_dimension_type = Integer: expected type of value returned by manifold_dimension.
  • inverse_retraction_methods = []: inverse retraction methods that will be tested.
  • is_mutating = true: whether mutating variants of functions should be tested.
  • is_point_atol_multiplier = 0: determines atol of is_point checks.
  • is_tangent_atol_multiplier = 0: determines atol of is_vector checks.
  • mid_point12 = test_exp_log ? shortest_geodesic(M, pts[1], pts[2], 0.5) : nothing: if not nothing, then check that mid_point(M, pts[1], pts[2]) is approximately equal to mid_point12. This is by default set to nothing if text_exp_log is set to false.
  • point_distributions = [] : point distributions to test.
  • rand_tvector_atol_multiplier = 0 : chage absolute tolerance in testing random vectors (0 use default, i.e. deactivate atol and use rtol) random tangent vectors are tangent vectors.
  • retraction_atol_multiplier = 0: change absolute tolerance of (inverse) retraction tests (0 use default, i.e. deactivate atol and use rtol).
  • retraction_rtol_multiplier = 1: change the relative tolerance of (inverse) retraction tests (1 use default). This is deactivated if the exp_log_atol_multiplier is nonzero.
  • retraction_methods = []: retraction methods that will be tested.
  • test_atlases = []: Vector or tuple of atlases that should be tested.
  • test_exp_log = true: if true, check that exp is the inverse of log.
  • test_injectivity_radius = true: whether implementation of injectivity_radius should be tested.
  • test_inplace = false : if true check if inplace variants work if they are activated, e.g. check that exp!(M, p, p, X) work if test_exp_log = true. This in general requires is_mutating to be true.
  • test_is_tangent: if true check that the default_inverse_retraction_method actually returns valid tangent vectors.
  • test_musical_isomorphisms = false : test musical isomorphisms.
  • test_mutating_rand = false : test the mutating random function for points on manifolds.
  • test_project_point = false: test projections onto the manifold.
  • test_project_tangent = false : test projections on tangent spaces.
  • test_representation_size = true : test repersentation size of points/tvectprs.
  • test_tangent_vector_broadcasting = true : test boradcasting operators on TangentSpace.
  • test_vector_spaces = true : test Vector bundle of this manifold.
  • test_default_vector_transport = false : test the default vector transport (usually parallel transport).
  • test_vee_hat = false: test vee and hat functions.
  • tvector_distributions = [] : tangent vector distributions to test.
  • vector_transport_methods = []: vector transport methods that should be tested.
  • vector_transport_inverse_retractions = [default_inverse_retraction_method for _ in 1:length(vector_transport_methods)]` inverse retractions to use with the vector transport method (especially the differentiated ones)
  • vector_transport_to = [ true for _ in 1:length(vector_transport_methods)]: whether to check the to variant of vector transport
  • vector_transport_direction = [ true for _ in 1:length(vector_transport_methods)]: whether to check the direction variant of vector transport
source
Manifolds.find_eps — Function
find_eps(x...)

Find an appropriate tolerance for given points or tangent vectors, or their types.

source
Manifolds.test_parallel_transport — Function
test_parallel_transport(M,P; along=false, to=true, diretion=true)

Generic tests for parallel transport on Mgiven at least two pointsin P.

The single functions to transport along (a curve), to (a point) or (towards a) direction are sub-tests that can be activated by the keywords arguemnts

!!! Note Since the interface to specify curves is not yet provided, the along keyword does not have an effect yet

source
+)

Test general properties of manifold M, given at least three different points that lie on it (contained in pts).

Arguments

source
Manifolds.find_eps — Function
find_eps(x...)

Find an appropriate tolerance for given points or tangent vectors, or their types.

source
Manifolds.test_parallel_transport — Function
test_parallel_transport(M,P; along=false, to=true, diretion=true)

Generic tests for parallel transport on Mgiven at least two pointsin P.

The single functions to transport along (a curve), to (a point) or (towards a) direction are sub-tests that can be activated by the keywords arguemnts

!!! Note Since the interface to specify curves is not yet provided, the along keyword does not have an effect yet

source
diff --git a/previews/PR628/features/utilities.html b/previews/PR628/features/utilities.html index ce5614d2ee..3f98674299 100644 --- a/previews/PR628/features/utilities.html +++ b/previews/PR628/features/utilities.html @@ -1,8 +1,8 @@ Utilities · Manifolds.jl
Edit on GitHub

Ease of notation

The following terms introduce a nicer notation for some operations, for example using the ∈ operator, $p ∈ \mathcal M$, to determine whether $p$ is a point on the AbstractManifold $\mathcal M$.

Base.in — Function
Base.in(p, M::AbstractManifold; kwargs...)
-p ∈ M

Check, whether a point p is a valid point (i.e. in) a AbstractManifold M. This method employs is_point deactivating the error throwing option.

source
Base.in(p, TpM::TangentSpaceAtPoint; kwargs...)
-X ∈ TangentSpaceAtPoint(M,p)

Check whether X is a tangent vector from (in) the tangent space $T_p\mathcal M$, i.e. the TangentSpaceAtPoint at p on the AbstractManifold M. This method uses is_vector deactivating the error throw option.

source

Fallback for the exponential map: Solving the corresponding ODE

When additionally loading NLSolve.jl the following fallback for the exponential map is available.

Public documentation

The following functions are of interest for extending and using the ProductManifold.

Manifolds.submanifold_component — Function
submanifold_component(M::AbstractManifold, p, i::Integer)
+p ∈ M

Check, whether a point p is a valid point (i.e. in) a AbstractManifold M. This method employs is_point deactivating the error throwing option.

source
Base.in(p, TpM::TangentSpaceAtPoint; kwargs...)
+X ∈ TangentSpaceAtPoint(M,p)

Check whether X is a tangent vector from (in) the tangent space $T_p\mathcal M$, i.e. the TangentSpaceAtPoint at p on the AbstractManifold M. This method uses is_vector deactivating the error throw option.

source

Fallback for the exponential map: Solving the corresponding ODE

When additionally loading NLSolve.jl the following fallback for the exponential map is available.

Public documentation

The following functions are of interest for extending and using the ProductManifold.

Manifolds.submanifold_component — Function
submanifold_component(M::AbstractManifold, p, i::Integer)
 submanifold_component(M::AbstractManifold, p, ::Val(i)) where {i}
 submanifold_component(p, i::Integer)
-submanifold_component(p, ::Val(i)) where {i}

Project the product array p on M to its ith component. A new array is returned.

source
Manifolds.submanifold_components — Function
submanifold_components(M::AbstractManifold, p)
-submanifold_components(p)

Get the projected components of p on the submanifolds of M. The components are returned in a Tuple.

source
Manifolds.ProductRepr — Type
ProductRepr(parts)

A more general but slower representation of points and tangent vectors on a product manifold.

Example:

A product point on a product manifold Sphere(2) × Euclidean(2) might be created as

ProductRepr([1.0, 0.0, 0.0], [2.0, 3.0])

where [1.0, 0.0, 0.0] is the part corresponding to the sphere factor and [2.0, 3.0] is the part corresponding to the euclidean manifold.

Warning

ProductRepr is deprecated and will be removed in a future release. Please use ArrayPartition instead.

source

Specific exception types

For some manifolds it is useful to keep an extra index, at which point on the manifold, the error occurred as well as to collect all errors that occurred on a manifold. This page contains the manifold-specific error messages this package introduces.

+submanifold_component(p, ::Val(i)) where {i}

Project the product array p on M to its ith component. A new array is returned.

source
Manifolds.submanifold_components — Function
submanifold_components(M::AbstractManifold, p)
+submanifold_components(p)

Get the projected components of p on the submanifolds of M. The components are returned in a Tuple.

source
Manifolds.ProductRepr — Type
ProductRepr(parts)

A more general but slower representation of points and tangent vectors on a product manifold.

Example:

A product point on a product manifold Sphere(2) × Euclidean(2) might be created as

ProductRepr([1.0, 0.0, 0.0], [2.0, 3.0])

where [1.0, 0.0, 0.0] is the part corresponding to the sphere factor and [2.0, 3.0] is the part corresponding to the euclidean manifold.

Warning

ProductRepr is deprecated and will be removed in a future release. Please use ArrayPartition instead.

source

Specific exception types

For some manifolds it is useful to keep an extra index, at which point on the manifold, the error occurred as well as to collect all errors that occurred on a manifold. This page contains the manifold-specific error messages this package introduces.

diff --git a/previews/PR628/index.html b/previews/PR628/index.html index 0fb4f5a1dc..7f4e377a17 100644 --- a/previews/PR628/index.html +++ b/previews/PR628/index.html @@ -1,5 +1,5 @@ -Home · Manifolds.jl
Edit on GitHub

Manifolds

Manifolds.Manifolds — Module

Manifolds.jl provides a library of manifolds aiming for an easy-to-use and fast implementation.

source

The implemented manifolds are accompanied by their mathematical formulae.

The manifolds are implemented using the interface for manifolds given in ManifoldsBase.jl. You can use that interface to implement your own software on manifolds, such that all manifolds based on that interface can be used within your code.

For more information, see the About section.

Getting started

To install the package just type

using Pkg; Pkg.add("Manifolds")

Then you can directly start, for example to stop half way from the north pole on the Sphere to a point on the the equator, you can generate the shortest_geodesic. It internally employs log and exp.

using Manifolds
+Home · Manifolds.jl
Edit on GitHub
Manifolds
Manifolds.Manifolds — Module
Manifolds.jl provides a library of manifolds aiming for an easy-to-use and fast implementation.
source
The implemented manifolds are accompanied by their mathematical formulae.
The manifolds are implemented using the interface for manifolds given in ManifoldsBase.jl. You can use that interface to implement your own software on manifolds, such that all manifolds based on that interface can be used within your code.
For more information, see the About section.
Getting started
To install the package just type
using Pkg; Pkg.add("Manifolds")
Then you can directly start, for example to stop half way from the north pole on the Sphere to a point on the the equator, you can generate the shortest_geodesic. It internally employs log and exp.
using Manifolds
 M = Sphere(2)
 γ = shortest_geodesic(M, [0., 0., 1.], [0., 1., 0.])
 γ(0.5)
3-element Vector{Float64}:
@@ -19,4 +19,4 @@
   Publisher = {Zenodo},
   Year = {2021},
   Copyright = {MIT License}
-}
for the most recent version or a corresponding version specific DOI, see the list of all versions. Note that both citations are in BibLaTeX format.

+}

for the most recent version or a corresponding version specific DOI, see the list of all versions. Note that both citations are in BibLaTeX format.

diff --git a/previews/PR628/manifolds/centeredmatrices.html b/previews/PR628/manifolds/centeredmatrices.html index 879e479bd4..124820c0b8 100644 --- a/previews/PR628/manifolds/centeredmatrices.html +++ b/previews/PR628/manifolds/centeredmatrices.html @@ -1,10 +1,10 @@ -Centered matrices · Manifolds.jl
Edit on GitHub

Centered matrices

Manifolds.CenteredMatrices — Type
CenteredMatrices{m,n,𝔽} <: AbstractDecoratorManifold{𝔽}

The manifold of $m × n$ real-valued or complex-valued matrices whose columns sum to zero, i.e.

\[\bigl\{ p ∈ 𝔽^{m × n}\ \big|\ [1 … 1] * p = [0 … 0] \bigr\},\]

where $𝔽 ∈ \{ℝ,ℂ\}$.

Constructor

CenteredMatrices(m, n[, field=ℝ])

Generate the manifold of m-by-n (field-valued) matrices whose columns sum to zero.

source
ManifoldsBase.check_point — Method
check_point(M::CenteredMatrices{m,n,𝔽}, p; kwargs...)

Check whether the matrix is a valid point on the CenteredMatrices M, i.e. is an m-by-n matrix whose columns sum to zero.

The tolerance for the column sums of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::CenteredMatrices{m,n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the CenteredMatrices M, i.e. that X is a matrix of size (m, n) whose columns sum to zero and its values are from the correct AbstractNumbers. The tolerance for the column sums of p and X can be set using kwargs....

source
ManifoldsBase.project — Method
project(M::CenteredMatrices, p, X)

Project the matrix X onto the tangent space at p on the CenteredMatrices M, i.e.

\[\operatorname{proj}_p(X) = X - \begin{bmatrix} +Centered matrices · Manifolds.jl

Edit on GitHub

Centered matrices

Manifolds.CenteredMatrices — Type
CenteredMatrices{m,n,𝔽} <: AbstractDecoratorManifold{𝔽}

The manifold of $m × n$ real-valued or complex-valued matrices whose columns sum to zero, i.e.

\[\bigl\{ p ∈ 𝔽^{m × n}\ \big|\ [1 … 1] * p = [0 … 0] \bigr\},\]

where $𝔽 ∈ \{ℝ,ℂ\}$.

Constructor

CenteredMatrices(m, n[, field=ℝ])

Generate the manifold of m-by-n (field-valued) matrices whose columns sum to zero.

source
ManifoldsBase.check_point — Method
check_point(M::CenteredMatrices{m,n,𝔽}, p; kwargs...)

Check whether the matrix is a valid point on the CenteredMatrices M, i.e. is an m-by-n matrix whose columns sum to zero.

The tolerance for the column sums of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::CenteredMatrices{m,n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the CenteredMatrices M, i.e. that X is a matrix of size (m, n) whose columns sum to zero and its values are from the correct AbstractNumbers. The tolerance for the column sums of p and X can be set using kwargs....

source
ManifoldsBase.project — Method
project(M::CenteredMatrices, p, X)

Project the matrix X onto the tangent space at p on the CenteredMatrices M, i.e.

\[\operatorname{proj}_p(X) = X - \begin{bmatrix} 1\\ ⋮\\ 1 -\end{bmatrix} * [c_1 \dots c_n],\]

where $c_i = \frac{1}{m}\sum_{j=1}^m x_{j,i}$ for $i = 1, \dots, n$.

source
ManifoldsBase.project — Method
project(M::CenteredMatrices, p)

Projects p from the embedding onto the CenteredMatrices M, i.e.

\[\operatorname{proj}_{\mathcal M}(p) = p - \begin{bmatrix} +\end{bmatrix} * [c_1 \dots c_n],\]

where $c_i = \frac{1}{m}\sum_{j=1}^m x_{j,i}$ for $i = 1, \dots, n$.

source
ManifoldsBase.project — Method
project(M::CenteredMatrices, p)

Projects p from the embedding onto the CenteredMatrices M, i.e.

\[\operatorname{proj}_{\mathcal M}(p) = p - \begin{bmatrix} 1\\ ⋮\\ 1 -\end{bmatrix} * [c_1 \dots c_n],\]

where $c_i = \frac{1}{m}\sum_{j=1}^m p_{j,i}$ for $i = 1, \dots, n$.

source
+\end{bmatrix} * [c_1 \dots c_n],\]

where $c_i = \frac{1}{m}\sum_{j=1}^m p_{j,i}$ for $i = 1, \dots, n$.

source
diff --git a/previews/PR628/manifolds/choleskyspace.html b/previews/PR628/manifolds/choleskyspace.html index 283800d4b1..f7f0ea27fa 100644 --- a/previews/PR628/manifolds/choleskyspace.html +++ b/previews/PR628/manifolds/choleskyspace.html @@ -1,6 +1,6 @@ -Cholesky space · Manifolds.jl
Edit on GitHub

Cholesky space

The Cholesky space is a Riemannian manifold on the lower triangular matrices. Its metric is based on the cholesky decomposition. The CholeskySpace is used to define the LogCholeskyMetric on the manifold of SymmetricPositiveDefinite matrices.

Manifolds.CholeskySpace — Type
CholeskySpace{N} <: AbstractManifold{ℝ}

The manifold of lower triangular matrices with positive diagonal and a metric based on the cholesky decomposition. The formulae for this manifold are for example summarized in Table 1 of [Lin2019].

Constructor

CholeskySpace(n)

Generate the manifold of $n× n$ lower triangular matrices with positive diagonal.

source
Base.exp — Method
exp(M::CholeskySpace, p, X)

Compute the exponential map on the CholeskySpace M emanating from the lower triangular matrix with positive diagonal p towards the lower triangular matrix X The formula reads

\[\exp_p X = ⌊ p ⌋ + ⌊ X ⌋ + \operatorname{diag}(p) -\operatorname{diag}(p)\exp\bigl( \operatorname{diag}(X)\operatorname{diag}(p)^{-1}\bigr),\]

where $⌊\cdot⌋$ denotes the strictly lower triangular matrix, and $\operatorname{diag}$ extracts the diagonal matrix.

source
Base.log — Method
log(M::CholeskySpace, X, p, q)

Compute the logarithmic map on the CholeskySpace M for the geodesic emanating from the lower triangular matrix with positive diagonal p towards q. The formula reads

\[\log_p q = ⌊ p ⌋ - ⌊ q ⌋ + \operatorname{diag}(p)\log\bigl(\operatorname{diag}(q)\operatorname{diag}(p)^{-1}\bigr),\]

where $⌊\cdot⌋$ denotes the strictly lower triangular matrix, and $\operatorname{diag}$ extracts the diagonal matrix.

source
ManifoldsBase.check_point — Method
check_point(M::CholeskySpace, p; kwargs...)

Check whether the matrix p lies on the CholeskySpace M, i.e. it's size fits the manifold, it is a lower triangular matrix and has positive entries on the diagonal. The tolerance for the tests can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::CholeskySpace, p, X; kwargs... )

Check whether v is a tangent vector to p on the CholeskySpace M, i.e. after check_point(M,p), X has to have the same dimension as p and a symmetric matrix. The tolerance for the tests can be set using the kwargs....

source
ManifoldsBase.distance — Method
distance(M::CholeskySpace, p, q)

Compute the Riemannian distance on the CholeskySpace M between two matrices p, q that are lower triangular with positive diagonal. The formula reads

\[d_{\mathcal M}(p,q) = \sqrt{\sum_{i>j} (p_{ij}-q_{ij})^2 + +Cholesky space · Manifolds.jl

Edit on GitHub

Cholesky space

The Cholesky space is a Riemannian manifold on the lower triangular matrices. Its metric is based on the cholesky decomposition. The CholeskySpace is used to define the LogCholeskyMetric on the manifold of SymmetricPositiveDefinite matrices.

Manifolds.CholeskySpace — Type
CholeskySpace{N} <: AbstractManifold{ℝ}

The manifold of lower triangular matrices with positive diagonal and a metric based on the cholesky decomposition. The formulae for this manifold are for example summarized in Table 1 of [Lin2019].

Constructor

CholeskySpace(n)

Generate the manifold of $n× n$ lower triangular matrices with positive diagonal.

source
Base.exp — Method
exp(M::CholeskySpace, p, X)

Compute the exponential map on the CholeskySpace M emanating from the lower triangular matrix with positive diagonal p towards the lower triangular matrix X The formula reads

\[\exp_p X = ⌊ p ⌋ + ⌊ X ⌋ + \operatorname{diag}(p) +\operatorname{diag}(p)\exp\bigl( \operatorname{diag}(X)\operatorname{diag}(p)^{-1}\bigr),\]

where $⌊\cdot⌋$ denotes the strictly lower triangular matrix, and $\operatorname{diag}$ extracts the diagonal matrix.

source
Base.log — Method
log(M::CholeskySpace, X, p, q)

Compute the logarithmic map on the CholeskySpace M for the geodesic emanating from the lower triangular matrix with positive diagonal p towards q. The formula reads

\[\log_p q = ⌊ p ⌋ - ⌊ q ⌋ + \operatorname{diag}(p)\log\bigl(\operatorname{diag}(q)\operatorname{diag}(p)^{-1}\bigr),\]

where $⌊\cdot⌋$ denotes the strictly lower triangular matrix, and $\operatorname{diag}$ extracts the diagonal matrix.

source
ManifoldsBase.check_point — Method
check_point(M::CholeskySpace, p; kwargs...)

Check whether the matrix p lies on the CholeskySpace M, i.e. it's size fits the manifold, it is a lower triangular matrix and has positive entries on the diagonal. The tolerance for the tests can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::CholeskySpace, p, X; kwargs... )

Check whether v is a tangent vector to p on the CholeskySpace M, i.e. after check_point(M,p), X has to have the same dimension as p and a symmetric matrix. The tolerance for the tests can be set using the kwargs....

source
ManifoldsBase.distance — Method
distance(M::CholeskySpace, p, q)

Compute the Riemannian distance on the CholeskySpace M between two matrices p, q that are lower triangular with positive diagonal. The formula reads

\[d_{\mathcal M}(p,q) = \sqrt{\sum_{i>j} (p_{ij}-q_{ij})^2 + \sum_{j=1}^m (\log p_{jj} - \log q_{jj})^2 -}\]

source
ManifoldsBase.inner — Method
inner(M::CholeskySpace, p, X, Y)

Compute the inner product on the CholeskySpace M at the lower triangular matric with positive diagonal p and the two tangent vectors X,Y, i.e they are both lower triangular matrices with arbitrary diagonal. The formula reads

\[g_p(X,Y) = \sum_{i>j} X_{ij}Y_{ij} + \sum_{j=1}^m X_{ii}Y_{ii}p_{ii}^{-2}\]

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::CholeskySpace, p, X, q)

Parallely transport the tangent vector X at p along the geodesic to q on the CholeskySpace manifold M. The formula reads

\[\mathcal P_{q←p}(X) = ⌊ X ⌋ -+ \operatorname{diag}(q)\operatorname{diag}(p)^{-1}\operatorname{diag}(X),\]

where $⌊\cdot⌋$ denotes the strictly lower triangular matrix, and $\operatorname{diag}$ extracts the diagonal matrix.

source

Literature

  • Lin2019

    Lin, Zenhua: Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition, arXiv: 1908.09326.

+}\]

source
ManifoldsBase.inner — Method
inner(M::CholeskySpace, p, X, Y)

Compute the inner product on the CholeskySpace M at the lower triangular matric with positive diagonal p and the two tangent vectors X,Y, i.e they are both lower triangular matrices with arbitrary diagonal. The formula reads

\[g_p(X,Y) = \sum_{i>j} X_{ij}Y_{ij} + \sum_{j=1}^m X_{ii}Y_{ii}p_{ii}^{-2}\]

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::CholeskySpace, p, X, q)

Parallely transport the tangent vector X at p along the geodesic to q on the CholeskySpace manifold M. The formula reads

\[\mathcal P_{q←p}(X) = ⌊ X ⌋ ++ \operatorname{diag}(q)\operatorname{diag}(p)^{-1}\operatorname{diag}(X),\]

where $⌊\cdot⌋$ denotes the strictly lower triangular matrix, and $\operatorname{diag}$ extracts the diagonal matrix.

source

Literature

  • Lin2019

    Lin, Zenhua: Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition, arXiv: 1908.09326.

diff --git a/previews/PR628/manifolds/circle.html b/previews/PR628/manifolds/circle.html index d9abbb5ee5..e04ca4033f 100644 --- a/previews/PR628/manifolds/circle.html +++ b/previews/PR628/manifolds/circle.html @@ -1,3 +1,3 @@ -Circle · Manifolds.jl
Edit on GitHub

Circle

Manifolds.Circle — Type
Circle{𝔽} <: AbstractManifold{𝔽}

The circle $𝕊^1$ is a manifold here represented by real-valued points in $[-π,π)$ or complex-valued points $z ∈ ℂ$ of absolute value $\lvert z\rvert = 1$.

Constructor

Circle(𝔽=ℝ)

Generate the ℝ-valued Circle represented by angles, which alternatively can be set to use the AbstractNumbers 𝔽=ℂ to obtain the circle represented by ℂ-valued circle of unit numbers.

source
Base.exp — Method
exp(M::Circle, p, X)

Compute the exponential map on the Circle.

\[\exp_p X = (p+X)_{2π},\]

where $(\cdot)_{2π}$ is the (symmetric) remainder with respect to division by $2π$, i.e. in $[-π,π)$.

For the complex-valued case, the same formula as for the Sphere $𝕊^1$ is applied to values in the complex plane.

source
Base.log — Method
log(M::Circle, p, q)

Compute the logarithmic map on the Circle M.

\[\log_p q = (q-p)_{2π},\]

where $(\cdot)_{2π}$ is the (symmetric) remainder with respect to division by $2π$, i.e. in $[-π,π)$.

For the complex-valued case, the same formula as for the Sphere $𝕊^1$ is applied to values in the complex plane.

source
Base.rand — Method
Random.rand(M::Circle{ℝ}; vector_at = nothing, σ::Real=1.0)

If vector_at is nothing, return a random point on the Circle $\mathbb S^1$ by picking a random element from $[-\pi,\pi)$ uniformly.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the Circle by using a normal distribution with mean 0 and standard deviation σ.

source
Manifolds.sym_rem — Method
sym_rem(x,[T=π])

Compute symmetric remainder of x with respect to the interall 2*T, i.e. (x+T)%2T, where the default for T is $π$

source
ManifoldsBase.check_point — Method
check_point(M::Circle, p)

Check whether p is a point on the Circle M. For the real-valued case, p is an angle and hence it checks that $p ∈ [-π,π)$. for the complex-valued case, it is a unit number, $p ∈ ℂ$ with $\lvert p \rvert = 1$.

source
ManifoldsBase.check_vector — Method
check_vector(M::Circle, p, X; kwargs...)

Check whether X is a tangent vector in the tangent space of p on the Circle M. For the real-valued case represented by angles, all X are valid, since the tangent space is the whole real line. For the complex-valued case X has to lie on the line parallel to the tangent line at p in the complex plane, i.e. their inner product has to be zero.

source
ManifoldsBase.distance — Method
distance(M::Circle, p, q)

Compute the distance on the Circle M, which is the absolute value of the symmetric remainder of p and q for the real-valued case and the angle between both complex numbers in the Gaussian plane for the complex-valued case.

source
ManifoldsBase.inner — Method
inner(M::Circle, p, X, Y)

Compute the inner product of the two tangent vectors X,Y from the tangent plane at p on the Circle M using the restriction of the metric from the embedding, i.e.

\[g_p(X,Y) = X*Y\]

for the real case and

\[g_p(X,Y) = Y^\mathrm{T}X\]

for the complex case interpreting complex numbers in the Gaussian plane.

source
ManifoldsBase.parallel_transport_to — Method
 parallel_transport_to(M::Circle, p, X, q)

Compute the parallel transport of X from the tangent space at p to the tangent space at q on the Circle M. For the real-valued case this results in the identity. For the complex-valud case, the formula is the same as for the Sphere(1) in the complex plane.

\[\mathcal P_{q←p} X = X - \frac{⟨\log_p q,X⟩_p}{d^2_{ℂ}(p,q)} -\bigl(\log_p q + \log_q p \bigr),\]

where log denotes the logarithmic map on M.

source
ManifoldsBase.project — Method
project(M::Circle, p, X)

Project a value X onto the tangent space of the point p on the Circle M.

For the real-valued case this is just the identity. For the complex valued case X is projected onto the line in the complex plane that is parallel to the tangent to p on the unit circle and contains 0.

source
ManifoldsBase.project — Method
project(M::Circle, p)

Project a point p onto the Circle M. For the real-valued case this is the remainder with respect to modulus $2π$. For the complex-valued case the result is the projection of p onto the unit circle in the complex plane.

source
Statistics.mean — Method
mean(M::Circle{ℂ}, x::AbstractVector[, w::AbstractWeights])

Compute the Riemannian mean of x of points on the Circle $𝕊^1$, reprsented by complex numbers, i.e. embedded in the complex plane. Comuting the sum

\[s = \sum_{i=1}^n x_i\]

the mean is the angle of the complex number $s$, so represented in the complex plane as $\frac{s}{\lvert s \rvert}$, whenever $s \neq 0$.

If the sum $s=0$, the mean is not unique. For example for opposite points or equally spaced angles.

source
Statistics.mean — Method
mean(M::Circle{ℝ}, x::AbstractVector[, w::AbstractWeights])

Compute the Riemannian mean of x of points on the Circle $𝕊^1$, reprsented by real numbers, i.e. the angular mean

\[\operatorname{atan}\Bigl( \sum_{i=1}^n w_i\sin(x_i), \sum_{i=1}^n w_i\sin(x_i) \Bigr).\]

source
+Circle · Manifolds.jl
Edit on GitHub

Circle

Manifolds.Circle — Type
Circle{𝔽} <: AbstractManifold{𝔽}

The circle $𝕊^1$ is a manifold here represented by real-valued points in $[-π,π)$ or complex-valued points $z ∈ ℂ$ of absolute value $\lvert z\rvert = 1$.

Constructor

Circle(𝔽=ℝ)

Generate the ℝ-valued Circle represented by angles, which alternatively can be set to use the AbstractNumbers 𝔽=ℂ to obtain the circle represented by ℂ-valued circle of unit numbers.

source
Base.exp — Method
exp(M::Circle, p, X)

Compute the exponential map on the Circle.

\[\exp_p X = (p+X)_{2π},\]

where $(\cdot)_{2π}$ is the (symmetric) remainder with respect to division by $2π$, i.e. in $[-π,π)$.

For the complex-valued case, the same formula as for the Sphere $𝕊^1$ is applied to values in the complex plane.

source
Base.log — Method
log(M::Circle, p, q)

Compute the logarithmic map on the Circle M.

\[\log_p q = (q-p)_{2π},\]

where $(\cdot)_{2π}$ is the (symmetric) remainder with respect to division by $2π$, i.e. in $[-π,π)$.

For the complex-valued case, the same formula as for the Sphere $𝕊^1$ is applied to values in the complex plane.

source
Base.rand — Method
Random.rand(M::Circle{ℝ}; vector_at = nothing, σ::Real=1.0)

If vector_at is nothing, return a random point on the Circle $\mathbb S^1$ by picking a random element from $[-\pi,\pi)$ uniformly.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the Circle by using a normal distribution with mean 0 and standard deviation σ.

source
Manifolds.sym_rem — Method
sym_rem(x,[T=π])

Compute symmetric remainder of x with respect to the interall 2*T, i.e. (x+T)%2T, where the default for T is $π$

source
ManifoldsBase.check_point — Method
check_point(M::Circle, p)

Check whether p is a point on the Circle M. For the real-valued case, p is an angle and hence it checks that $p ∈ [-π,π)$. for the complex-valued case, it is a unit number, $p ∈ ℂ$ with $\lvert p \rvert = 1$.

source
ManifoldsBase.check_vector — Method
check_vector(M::Circle, p, X; kwargs...)

Check whether X is a tangent vector in the tangent space of p on the Circle M. For the real-valued case represented by angles, all X are valid, since the tangent space is the whole real line. For the complex-valued case X has to lie on the line parallel to the tangent line at p in the complex plane, i.e. their inner product has to be zero.

source
ManifoldsBase.distance — Method
distance(M::Circle, p, q)

Compute the distance on the Circle M, which is the absolute value of the symmetric remainder of p and q for the real-valued case and the angle between both complex numbers in the Gaussian plane for the complex-valued case.

source
ManifoldsBase.inner — Method
inner(M::Circle, p, X, Y)

Compute the inner product of the two tangent vectors X,Y from the tangent plane at p on the Circle M using the restriction of the metric from the embedding, i.e.

\[g_p(X,Y) = X*Y\]

for the real case and

\[g_p(X,Y) = Y^\mathrm{T}X\]

for the complex case interpreting complex numbers in the Gaussian plane.

source
ManifoldsBase.parallel_transport_to — Method
 parallel_transport_to(M::Circle, p, X, q)

Compute the parallel transport of X from the tangent space at p to the tangent space at q on the Circle M. For the real-valued case this results in the identity. For the complex-valud case, the formula is the same as for the Sphere(1) in the complex plane.

\[\mathcal P_{q←p} X = X - \frac{⟨\log_p q,X⟩_p}{d^2_{ℂ}(p,q)} +\bigl(\log_p q + \log_q p \bigr),\]

where log denotes the logarithmic map on M.

source
ManifoldsBase.project — Method
project(M::Circle, p, X)

Project a value X onto the tangent space of the point p on the Circle M.

For the real-valued case this is just the identity. For the complex valued case X is projected onto the line in the complex plane that is parallel to the tangent to p on the unit circle and contains 0.

source
ManifoldsBase.project — Method
project(M::Circle, p)

Project a point p onto the Circle M. For the real-valued case this is the remainder with respect to modulus $2π$. For the complex-valued case the result is the projection of p onto the unit circle in the complex plane.

source
Statistics.mean — Method
mean(M::Circle{ℂ}, x::AbstractVector[, w::AbstractWeights])

Compute the Riemannian mean of x of points on the Circle $𝕊^1$, reprsented by complex numbers, i.e. embedded in the complex plane. Comuting the sum

\[s = \sum_{i=1}^n x_i\]

the mean is the angle of the complex number $s$, so represented in the complex plane as $\frac{s}{\lvert s \rvert}$, whenever $s \neq 0$.

If the sum $s=0$, the mean is not unique. For example for opposite points or equally spaced angles.

source
Statistics.mean — Method
mean(M::Circle{ℝ}, x::AbstractVector[, w::AbstractWeights])

Compute the Riemannian mean of x of points on the Circle $𝕊^1$, reprsented by real numbers, i.e. the angular mean

\[\operatorname{atan}\Bigl( \sum_{i=1}^n w_i\sin(x_i), \sum_{i=1}^n w_i\sin(x_i) \Bigr).\]

source
diff --git a/previews/PR628/manifolds/connection.html b/previews/PR628/manifolds/connection.html index 0d5b944ab6..39a53df314 100644 --- a/previews/PR628/manifolds/connection.html +++ b/previews/PR628/manifolds/connection.html @@ -1,20 +1,20 @@ -Connection manifold · Manifolds.jl
Edit on GitHub

Connection manifold

A connection manifold always consists of a topological manifold together with a connection $\Gamma$.

However, often there is an implicitly assumed (default) connection, like the LeviCivitaConnection connection on a Riemannian manifold. It is not necessary to use this decorator if you implement just one (or the first) connection. If you later introduce a second, the old (first) connection can be used without an explicitly stated connection.

This manifold decorator serves two purposes:

  1. to implement different connections (e.g. in closed form) for one AbstractManifold
  2. to provide a way to compute geodesics on manifolds, where this AbstractAffineConnection does not yield a closed formula.

An example of usage can be found in Cartan-Schouten connections, see AbstractCartanSchoutenConnection.

Types

Manifolds.IsConnectionManifold — Type
IsConnectionManifold <: AbstractTrait

Specify that a certain decorated Manifold is a connection manifold in the sence that it provides explicit connection properties, extending/changing the default connection properties of a manifold.

source

Functions

Base.exp — Method
exp(::TraitList{IsConnectionManifold}, M::AbstractDecoratorManifold, p, X)

Compute the exponential map on a manifold that IsConnectionManifold M equipped with corresponding affine connection.

If M is a MetricManifold with a IsDefaultMetric trait, this method falls back to exp(M, p, X).

Otherwise it numerically integrates the underlying ODE, see solve_exp_ode. Currently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.

source
Manifolds.christoffel_symbols_first — Method
christoffel_symbols_first(
+Connection manifold · Manifolds.jl
Edit on GitHub
Connection manifold
A connection manifold always consists of a topological manifold together with a connection $\Gamma$.
However, often there is an implicitly assumed (default) connection, like the LeviCivitaConnection connection on a Riemannian manifold. It is not necessary to use this decorator if you implement just one (or the first) connection. If you later introduce a second, the old (first) connection can be used without an explicitly stated connection.
This manifold decorator serves two purposes:
  1. to implement different connections (e.g. in closed form) for one AbstractManifold
  2. to provide a way to compute geodesics on manifolds, where this AbstractAffineConnection does not yield a closed formula.
An example of usage can be found in Cartan-Schouten connections, see AbstractCartanSchoutenConnection.
Types
Manifolds.IsConnectionManifold — Type
IsConnectionManifold <: AbstractTrait
Specify that a certain decorated Manifold is a connection manifold in the sence that it provides explicit connection properties, extending/changing the default connection properties of a manifold.
source
Functions
Base.exp — Method
exp(::TraitList{IsConnectionManifold}, M::AbstractDecoratorManifold, p, X)
Compute the exponential map on a manifold that IsConnectionManifold M equipped with corresponding affine connection.
If M is a MetricManifold with a IsDefaultMetric trait, this method falls back to exp(M, p, X).
Otherwise it numerically integrates the underlying ODE, see solve_exp_ode. Currently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.
source
Manifolds.christoffel_symbols_first — Method
christoffel_symbols_first(
     M::AbstractManifold,
     p,
     B::AbstractBasis;
     backend::AbstractDiffBackend = default_differential_backend(),
-)
Compute the Christoffel symbols of the first kind in local coordinates of basis B. The Christoffel symbols are (in Einstein summation convention)
\[Γ_{ijk} = \frac{1}{2} \Bigl[g_{kj,i} + g_{ik,j} - g_{ij,k}\Bigr],\]
where $g_{ij,k}=\frac{∂}{∂ p^k} g_{ij}$ is the coordinate derivative of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered $(i,j,k)$.
source
Manifolds.christoffel_symbols_second — Method
christoffel_symbols_second(
+)
Compute the Christoffel symbols of the first kind in local coordinates of basis B. The Christoffel symbols are (in Einstein summation convention)
\[Γ_{ijk} = \frac{1}{2} \Bigl[g_{kj,i} + g_{ik,j} - g_{ij,k}\Bigr],\]
where $g_{ij,k}=\frac{∂}{∂ p^k} g_{ij}$ is the coordinate derivative of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered $(i,j,k)$.
source
Manifolds.christoffel_symbols_second — Method
christoffel_symbols_second(
     M::AbstractManifold,
     p,
     B::AbstractBasis;
     backend::AbstractDiffBackend = default_differential_backend(),
-)
Compute the Christoffel symbols of the second kind in local coordinates of basis B. For affine connection manifold the Christoffel symbols need to be explicitly implemented while, for a MetricManifold they are computed as (in Einstein summation convention)
\[Γ^{l}_{ij} = g^{kl} Γ_{ijk},\]
where $Γ_{ijk}$ are the Christoffel symbols of the first kind (see christoffel_symbols_first), and $g^{kl}$ is the inverse of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered $(l,i,j)$.
source
Manifolds.christoffel_symbols_second_jacobian — Method
christoffel_symbols_second_jacobian(
+)
Compute the Christoffel symbols of the second kind in local coordinates of basis B. For affine connection manifold the Christoffel symbols need to be explicitly implemented while, for a MetricManifold they are computed as (in Einstein summation convention)
\[Γ^{l}_{ij} = g^{kl} Γ_{ijk},\]
where $Γ_{ijk}$ are the Christoffel symbols of the first kind (see christoffel_symbols_first), and $g^{kl}$ is the inverse of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered $(l,i,j)$.
source
Manifolds.christoffel_symbols_second_jacobian — Method
christoffel_symbols_second_jacobian(
     M::AbstractManifold,
     p,
     B::AbstractBasis;
     backend::AbstractDiffBackend = default_differential_backend(),
-)
Get partial derivatives of the Christoffel symbols of the second kind for manifold M at p with respect to the coordinates of B, i.e.
\[\frac{∂}{∂ p^l} Γ^{k}_{ij} = Γ^{k}_{ij,l}.\]
The dimensions of the resulting multi-dimensional array are ordered $(i,j,k,l)$.
source
Manifolds.gaussian_curvature — Method
gaussian_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())
Compute the Gaussian curvature of the manifold M at the point p using basis B. This is equal to half of the scalar Ricci curvature, see ricci_curvature.
source
Manifolds.solve_exp_ode — Method
solve_exp_ode(
+)
Get partial derivatives of the Christoffel symbols of the second kind for manifold M at p with respect to the coordinates of B, i.e.
\[\frac{∂}{∂ p^l} Γ^{k}_{ij} = Γ^{k}_{ij,l}.\]
The dimensions of the resulting multi-dimensional array are ordered $(i,j,k,l)$.
source
Manifolds.gaussian_curvature — Method
gaussian_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())
Compute the Gaussian curvature of the manifold M at the point p using basis B. This is equal to half of the scalar Ricci curvature, see ricci_curvature.
source
Manifolds.solve_exp_ode — Method
solve_exp_ode(
     M::AbstractConnectionManifold,
     p,
     X,
@@ -23,4 +23,4 @@
     backend::AbstractDiffBackend = default_differential_backend(),
     solver = AutoVern9(Rodas5()),
     kwargs...,
-)
Approximate the exponential map on the manifold by evaluating the ODE descripting the geodesic at 1, assuming the default connection of the given manifold by solving the ordinary differential equation
\[\frac{d^2}{dt^2} p^k + Γ^k_{ij} \frac{d}{dt} p_i \frac{d}{dt} p_j = 0,\]
where $Γ^k_{ij}$ are the Christoffel symbols of the second kind, and the Einstein summation convention is assumed. The argument solver follows the OrdinaryDiffEq conventions. kwargs... specify keyword arguments that will be passed to OrdinaryDiffEq.solve.
Currently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.
Note
This function only works when OrdinaryDiffEq.jl is loaded with
using OrdinaryDiffEq
source
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend=default_differential_backend())
Compute the Riemann tensor $R^l_{ijk}$, also known as the Riemann curvature tensor, at the point p in local coordinates defined by B. The dimensions of the resulting multi-dimensional array are ordered $(l,i,j,k)$.
The function uses the coordinate expression involving the second Christoffel symbol, see https://en.wikipedia.org/wiki/Riemann_curvature_tensor#Coordinate_expression for details.
See also
christoffel_symbols_second, christoffel_symbols_second_jacobian
source
Charts and bases of vector spaces
All connection-related functions take a basis of a vector space as one of the arguments. This is needed because generally there is no way to define these functions without referencing a basis. In some cases there is no need to be explicit about this basis, and then for example a DefaultOrthonormalBasis object can be used. In cases where being explicit about these bases is needed, for example when using multiple charts, a basis can be specified, for example using induced_basis.

+)

Approximate the exponential map on the manifold by evaluating the ODE descripting the geodesic at 1, assuming the default connection of the given manifold by solving the ordinary differential equation

\[\frac{d^2}{dt^2} p^k + Γ^k_{ij} \frac{d}{dt} p_i \frac{d}{dt} p_j = 0,\]

where $Γ^k_{ij}$ are the Christoffel symbols of the second kind, and the Einstein summation convention is assumed. The argument solver follows the OrdinaryDiffEq conventions. kwargs... specify keyword arguments that will be passed to OrdinaryDiffEq.solve.

Currently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.

Note

This function only works when OrdinaryDiffEq.jl is loaded with

using OrdinaryDiffEq
source
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend=default_differential_backend())

Compute the Riemann tensor $R^l_{ijk}$, also known as the Riemann curvature tensor, at the point p in local coordinates defined by B. The dimensions of the resulting multi-dimensional array are ordered $(l,i,j,k)$.

The function uses the coordinate expression involving the second Christoffel symbol, see https://en.wikipedia.org/wiki/Riemann_curvature_tensor#Coordinate_expression for details.

See also

christoffel_symbols_second, christoffel_symbols_second_jacobian

source

Charts and bases of vector spaces

All connection-related functions take a basis of a vector space as one of the arguments. This is needed because generally there is no way to define these functions without referencing a basis. In some cases there is no need to be explicit about this basis, and then for example a DefaultOrthonormalBasis object can be used. In cases where being explicit about these bases is needed, for example when using multiple charts, a basis can be specified, for example using induced_basis.

diff --git a/previews/PR628/manifolds/elliptope.html b/previews/PR628/manifolds/elliptope.html index 92992e6e95..d91f98c33b 100644 --- a/previews/PR628/manifolds/elliptope.html +++ b/previews/PR628/manifolds/elliptope.html @@ -7,4 +7,4 @@ \bigr\}. \end{aligned}\]

And this manifold is working solely on the matrices $q$. Note that this $q$ is not unique, indeed for any orthogonal matrix $A$ we have $(qA)(qA)^{\mathrm{T}} = qq^{\mathrm{T}} = p$, so the manifold implemented here is the quotient manifold. The unit diagonal translates to unit norm columns of $q$.

The tangent space at $p$, denoted $T_p\mathcal E(n,k)$, is also represented by matrices $Y\in ℝ^{n × k}$ and reads as

\[T_p\mathcal E(n,k) = \bigl\{ X ∈ ℝ^{n × n}\,|\,X = qY^{\mathrm{T}} + Yq^{\mathrm{T}} \text{ with } X_{ii} = 0 \text{ for } i=1,\ldots,n -\bigr\}\]

endowed with the Euclidean metric from the embedding, i.e. from the $ℝ^{n × k}$

This manifold was for example investigated in[JourneeBachAbsilSepulchre2010].

Constructor

Elliptope(n,k)

generates the manifold $\mathcal E(n,k) \subset ℝ^{n × n}$.

source
ManifoldsBase.check_point — Method
check_point(M::Elliptope, q; kwargs...)

checks, whether q is a valid reprsentation of a point $p=qq^{\mathrm{T}}$ on the Elliptope M, i.e. is a matrix of size (N,K), such that $p$ is symmetric positive semidefinite and has unit trace. Since by construction $p$ is symmetric, this is not explicitly checked. Since $p$ is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::Elliptope, q, Y; kwargs... )

Check whether $X = qY^{\mathrm{T}} + Yq^{\mathrm{T}}$ is a tangent vector to $p=qq^{\mathrm{T}}$ on the Elliptope M, i.e. Y has to be of same dimension as q and a $X$ has to be a symmetric matrix with zero diagonal.

The tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetric of $X$ holds by construction an is not explicitly checked.

source
ManifoldsBase.is_flat — Method
is_flat(::Elliptope)

Return false. Elliptope is not a flat manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Elliptope)

returns the dimension of Elliptope M$=\mathcal E(n,k), n,k ∈ ℕ$, i.e.

\[\dim \mathcal E(n,k) = n(k-1) - \frac{k(k-1)}{2}.\]

source
ManifoldsBase.project — Method
project(M::Elliptope, q)

project q onto the manifold Elliptope M, by normalizing the rows of q.

source
ManifoldsBase.project — Method
project(M::Elliptope, q, Y)

Project Y onto the tangent space at q, i.e. row-wise onto the oblique manifold.

source
ManifoldsBase.representation_size — Method
representation_size(M::Elliptope)

Return the size of an array representing an element on the Elliptope manifold M, i.e. $n × k$, the size of such factor of $p=qq^{\mathrm{T}}$ on $\mathcal M = \mathcal E(n,k)$.

source
ManifoldsBase.retract — Method
retract(M::Elliptope, q, Y, ::ProjectionRetraction)

compute a projection based retraction by projecting $q+Y$ back onto the manifold.

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Elliptope, p, X, q)

transport the tangent vector X at p to q by projecting it onto the tangent space at q.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::Elliptope,p)

returns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the Elliptope manifold M.

source

Literature

+\bigr\}\]

endowed with the Euclidean metric from the embedding, i.e. from the $ℝ^{n × k}$

This manifold was for example investigated in[JourneeBachAbsilSepulchre2010].

Constructor

Elliptope(n,k)

generates the manifold $\mathcal E(n,k) \subset ℝ^{n × n}$.

source
ManifoldsBase.check_point — Method
check_point(M::Elliptope, q; kwargs...)

checks, whether q is a valid reprsentation of a point $p=qq^{\mathrm{T}}$ on the Elliptope M, i.e. is a matrix of size (N,K), such that $p$ is symmetric positive semidefinite and has unit trace. Since by construction $p$ is symmetric, this is not explicitly checked. Since $p$ is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::Elliptope, q, Y; kwargs... )

Check whether $X = qY^{\mathrm{T}} + Yq^{\mathrm{T}}$ is a tangent vector to $p=qq^{\mathrm{T}}$ on the Elliptope M, i.e. Y has to be of same dimension as q and a $X$ has to be a symmetric matrix with zero diagonal.

The tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetric of $X$ holds by construction an is not explicitly checked.

source
ManifoldsBase.is_flat — Method
is_flat(::Elliptope)

Return false. Elliptope is not a flat manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Elliptope)

returns the dimension of Elliptope M$=\mathcal E(n,k), n,k ∈ ℕ$, i.e.

\[\dim \mathcal E(n,k) = n(k-1) - \frac{k(k-1)}{2}.\]

source
ManifoldsBase.project — Method
project(M::Elliptope, q)

project q onto the manifold Elliptope M, by normalizing the rows of q.

source
ManifoldsBase.project — Method
project(M::Elliptope, q, Y)

Project Y onto the tangent space at q, i.e. row-wise onto the oblique manifold.

source
ManifoldsBase.representation_size — Method
representation_size(M::Elliptope)

Return the size of an array representing an element on the Elliptope manifold M, i.e. $n × k$, the size of such factor of $p=qq^{\mathrm{T}}$ on $\mathcal M = \mathcal E(n,k)$.

source
ManifoldsBase.retract — Method
retract(M::Elliptope, q, Y, ::ProjectionRetraction)

compute a projection based retraction by projecting $q+Y$ back onto the manifold.

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Elliptope, p, X, q)

transport the tangent vector X at p to q by projecting it onto the tangent space at q.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::Elliptope,p)

returns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the Elliptope manifold M.

source

Literature

diff --git a/previews/PR628/manifolds/essentialmanifold.html b/previews/PR628/manifolds/essentialmanifold.html index b13563f8dd..a291167a2b 100644 --- a/previews/PR628/manifolds/essentialmanifold.html +++ b/previews/PR628/manifolds/essentialmanifold.html @@ -1,2 +1,2 @@ -Essential manifold · Manifolds.jl
Edit on GitHub

Essential Manifold

The essential manifold is modeled as an AbstractPowerManifold of the $3\times3$ Rotations and uses NestedPowerRepresentation.

Manifolds.EssentialManifold — Type
EssentialManifold <: AbstractPowerManifold{ℝ}

The essential manifold is the space of the essential matrices which is represented as a quotient space of the Rotations manifold product $\mathrm{SO}(3)^2$.

Let $R_x(θ), R_y(θ), R_x(θ) \in ℝ^{x\times 3}$ denote the rotation around the $z$, $y$, and $x$ axis in $ℝ^3$, respectively, and further the groups

\[H_z = \bigl\{(R_z(θ),R_z(θ))\ \big|\ θ ∈ [-π,π) \bigr\}\]

and

\[H_π = \bigl\{ (I,I), (R_x(π), R_x(π)), (I,R_z(π)), (R_x(π), R_y(π)) \bigr\}\]

acting elementwise on the left from $\mathrm{SO}(3)^2$ (component wise).

Then the unsigned Essential manifold $\mathcal{M}_{\text{E}}$ can be identified with the quotient space

\[\mathcal{M}_{\text{E}} := (\text{SO}(3)×\text{SO}(3))/(H_z × H_π),\]

and for the signed Essential manifold $\mathcal{M}_{\text{Ǝ}}$, the quotient reads

\[\mathcal{M}_{\text{Ǝ}} := (\text{SO}(3)×\text{SO}(3))/(H_z).\]

An essential matrix is defined as

\[E = (R'_1)^T [T'_2 - T'_1]_{×} R'_2,\]

where the poses of two cameras $(R_i', T_i'), i=1,2$, are contained in the space of rigid body transformations $SE(3)$ and the operator $[⋅]_{×}\colon ℝ^3 \to \operatorname{SkewSym}(3)$ denotes the matrix representation of the cross product operator. For more details see [TronDaniilidis2017].

Constructor

EssentialManifold(is_signed=true)

Generate the manifold of essential matrices, either the signed (is_signed=true) or unsigned (is_signed=false) variant.

source

Functions

Base.exp — Method
exp(M::EssentialManifold, p, X)

Compute the exponential map on the EssentialManifold from p into direction X, i.e.

\[\text{exp}_p(X) =\text{exp}_g( \tilde X), \quad g \in \text(SO)(3)^2,\]

where $\tilde X$ is the horizontal lift of $X$[TronDaniilidis2017].

source
Base.log — Method
log(M::EssentialManifold, p, q)

Compute the logarithmic map on the EssentialManifold M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. Here, $p=(R_{p_1},R_{p_2})$ and $q=(R_{q_1},R_{q_2})$ are elements of $SO(3)^2$. We use that any essential matrix can, up to scale, be decomposed to

\[E = R_1^T [e_z]_{×}R_2,\]

where $(R_1,R_2)∈SO(3)^2$. Two points in $SO(3)^2$ are equivalent iff their corresponding essential matrices are equal (up to a sign flip). To compute the logarithm, we first move q to another representative of its equivalence class. For this, we find $t= t_{\text{opt}}$ for which the function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

where $d(⋅,⋅)$ is the distance function in $SO(3)$, is minimized. Further, the group $H_z$ acting on the left on $SO(3)^2$ is defined as

\[H_z = \{(R_z(θ),R_z(θ))\colon θ \in [-π,π) \},\]

where $R_z(θ)$ is the rotation around the z axis with angle $θ$. Points in $H_z$ are denoted by $S_z$. Then, the logarithm is defined as

\[\log_p (S_z(t_{\text{opt}})q) = [\text{Log}(R_{p_i}^T R_z(t_{\text{opt}})R_{b_i})]_{i=1,2},\]

where $\text{Log}$ is the logarithm on $SO(3)$. For more details see [TronDaniilidis2017].

source
ManifoldsBase.check_vector — Method
check_vector(M::EssentialManifold, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the EssentialManifold M, i.e. X has to be a 2-element array of 3-by-3 skew-symmetric matrices.

source
ManifoldsBase.distance — Method
distance(M::EssentialManifold, p, q)

Compute the Riemannian distance between the two points p and q on the EssentialManifold. This is done by computing the distance of the equivalence classes $[p]$ and $[q]$ of the points $p=(R_{p_1},R_{p_2}), q=(R_{q_1},R_{q_2}) ∈ SO(3)^2$, respectively. Two points in $SO(3)^2$ are equivalent iff their corresponding essential matrices, given by

\[E = R_1^T [e_z]_{×}R_2,\]

are equal (up to a sign flip). Using the logarithmic map, the distance is given by

\[\text{dist}([p],[q]) = \| \text{log}_{[p]} [q] \| = \| \log_p (S_z(t_{\text{opt}})q) \|,\]

where $S_z ∈ H_z = \{(R_z(θ),R_z(θ))\colon θ \in [-π,π) \}$ in which $R_z(θ)$ is the rotation around the z axis with angle $θ$ and $t_{\text{opt}}$ is the minimizer of the cost function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

where $d(⋅,⋅)$ is the distance function in $SO(3)$[TronDaniilidis2017].

source
ManifoldsBase.project — Method
project(M::EssentialManifold, p, X)

Project the matrix X onto the tangent space

\[T_{p} \text{SO}(3)^2 = T_{\text{vp}}\text{SO}(3)^2 ⊕ T_{\text{hp}}\text{SO}(3)^2,\]

by first computing its projection onto the vertical space $T_{\text{vp}}\text{SO}(3)^2$ using vert_proj. Then the orthogonal projection of X onto the horizontal space $T_{\text{hp}}\text{SO}(3)^2$ is defined as

\[\Pi_h(X) = X - \frac{\text{vert\_proj}_p(X)}{2} \begin{bmatrix} R_1^T e_z \\ R_2^T e_z \end{bmatrix},\]

with $R_i = R_0 R'_i, i=1,2,$ where $R'_i$ is part of the pose of camera $i$ $g_i = (R'_i,T'_i) ∈ \text{SE}(3)$ and $R_0 ∈ \text{SO}(3)$ such that $R_0(T'_2-T'_1) = e_z$.

source

Internal Functions

Manifolds.dist_min_angle_pair — Method
dist_min_angle_pair(p, q)

This function computes the global minimizer of the function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

for the given values. This is done by finding the discontinuity points $t_{d_i}, i=1,2$ of its derivative and using Newton's method to minimize the function over the intervals $[t_{d_1},t_{d_2}]$ and $[t_{d_2},t_{d_1}+2π]$ separately. Then, the minimizer for which $f$ is minimal is chosen and given back together with the minimal value. For more details see Algorithm 1 in [TronDaniilidis2017].

source
Manifolds.dist_min_angle_pair_df_newton — Method
dist_min_angle_pair_df_newton(m1, Φ1, c1, m2, Φ2, c2, t_min, t_low, t_high)

This function computes the minimizer of the function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

in the interval $[$t_low, t_high$]$ using Newton's method. For more details see [TronDaniilidis2017].

source
Manifolds.dist_min_angle_pair_discontinuity_distance — Method
dist_min_angle_pair_discontinuity_distance(q)

This function computes the point $t_{\text{di}}$ for which the first derivative of

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

does not exist. This is the case for $\sin(θ_i(t_{\text{di}})) = 0$. For more details see Proposition 9 and its proof, as well as Lemma 1 in [TronDaniilidis2017].

source
Manifolds.vert_proj — Method
vert_proj(M::EssentialManifold, p, X)

Project X onto the vertical space $T_{\text{vp}}\text{SO}(3)^2$ with

\[\text{vert\_proj}_p(X) = e_z^T(R_1 X_1 + R_2 X_2),\]

where $e_z$ is the third unit vector, $X_i ∈ T_{p}\text{SO}(3)$ for $i=1,2,$ and it holds $R_i = R_0 R'_i, i=1,2,$ where $R'_i$ is part of the pose of camera $i$ $g_i = (R_i,T'_i) ∈ \text{SE}(3)$ and $R_0 ∈ \text{SO}(3)$ such that $R_0(T'_2-T'_1) = e_z$ [TronDaniilidis2017].

source

Literature

+Essential manifold · Manifolds.jl
Edit on GitHub

Essential Manifold

The essential manifold is modeled as an AbstractPowerManifold of the $3\times3$ Rotations and uses NestedPowerRepresentation.

Manifolds.EssentialManifold — Type
EssentialManifold <: AbstractPowerManifold{ℝ}

The essential manifold is the space of the essential matrices which is represented as a quotient space of the Rotations manifold product $\mathrm{SO}(3)^2$.

Let $R_x(θ), R_y(θ), R_x(θ) \in ℝ^{x\times 3}$ denote the rotation around the $z$, $y$, and $x$ axis in $ℝ^3$, respectively, and further the groups

\[H_z = \bigl\{(R_z(θ),R_z(θ))\ \big|\ θ ∈ [-π,π) \bigr\}\]

and

\[H_π = \bigl\{ (I,I), (R_x(π), R_x(π)), (I,R_z(π)), (R_x(π), R_y(π)) \bigr\}\]

acting elementwise on the left from $\mathrm{SO}(3)^2$ (component wise).

Then the unsigned Essential manifold $\mathcal{M}_{\text{E}}$ can be identified with the quotient space

\[\mathcal{M}_{\text{E}} := (\text{SO}(3)×\text{SO}(3))/(H_z × H_π),\]

and for the signed Essential manifold $\mathcal{M}_{\text{Ǝ}}$, the quotient reads

\[\mathcal{M}_{\text{Ǝ}} := (\text{SO}(3)×\text{SO}(3))/(H_z).\]

An essential matrix is defined as

\[E = (R'_1)^T [T'_2 - T'_1]_{×} R'_2,\]

where the poses of two cameras $(R_i', T_i'), i=1,2$, are contained in the space of rigid body transformations $SE(3)$ and the operator $[⋅]_{×}\colon ℝ^3 \to \operatorname{SkewSym}(3)$ denotes the matrix representation of the cross product operator. For more details see [TronDaniilidis2017].

Constructor

EssentialManifold(is_signed=true)

Generate the manifold of essential matrices, either the signed (is_signed=true) or unsigned (is_signed=false) variant.

source

Functions

Base.exp — Method
exp(M::EssentialManifold, p, X)

Compute the exponential map on the EssentialManifold from p into direction X, i.e.

\[\text{exp}_p(X) =\text{exp}_g( \tilde X), \quad g \in \text(SO)(3)^2,\]

where $\tilde X$ is the horizontal lift of $X$[TronDaniilidis2017].

source
Base.log — Method
log(M::EssentialManifold, p, q)

Compute the logarithmic map on the EssentialManifold M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. Here, $p=(R_{p_1},R_{p_2})$ and $q=(R_{q_1},R_{q_2})$ are elements of $SO(3)^2$. We use that any essential matrix can, up to scale, be decomposed to

\[E = R_1^T [e_z]_{×}R_2,\]

where $(R_1,R_2)∈SO(3)^2$. Two points in $SO(3)^2$ are equivalent iff their corresponding essential matrices are equal (up to a sign flip). To compute the logarithm, we first move q to another representative of its equivalence class. For this, we find $t= t_{\text{opt}}$ for which the function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

where $d(⋅,⋅)$ is the distance function in $SO(3)$, is minimized. Further, the group $H_z$ acting on the left on $SO(3)^2$ is defined as

\[H_z = \{(R_z(θ),R_z(θ))\colon θ \in [-π,π) \},\]

where $R_z(θ)$ is the rotation around the z axis with angle $θ$. Points in $H_z$ are denoted by $S_z$. Then, the logarithm is defined as

\[\log_p (S_z(t_{\text{opt}})q) = [\text{Log}(R_{p_i}^T R_z(t_{\text{opt}})R_{b_i})]_{i=1,2},\]

where $\text{Log}$ is the logarithm on $SO(3)$. For more details see [TronDaniilidis2017].

source
ManifoldsBase.check_vector — Method
check_vector(M::EssentialManifold, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the EssentialManifold M, i.e. X has to be a 2-element array of 3-by-3 skew-symmetric matrices.

source
ManifoldsBase.distance — Method
distance(M::EssentialManifold, p, q)

Compute the Riemannian distance between the two points p and q on the EssentialManifold. This is done by computing the distance of the equivalence classes $[p]$ and $[q]$ of the points $p=(R_{p_1},R_{p_2}), q=(R_{q_1},R_{q_2}) ∈ SO(3)^2$, respectively. Two points in $SO(3)^2$ are equivalent iff their corresponding essential matrices, given by

\[E = R_1^T [e_z]_{×}R_2,\]

are equal (up to a sign flip). Using the logarithmic map, the distance is given by

\[\text{dist}([p],[q]) = \| \text{log}_{[p]} [q] \| = \| \log_p (S_z(t_{\text{opt}})q) \|,\]

where $S_z ∈ H_z = \{(R_z(θ),R_z(θ))\colon θ \in [-π,π) \}$ in which $R_z(θ)$ is the rotation around the z axis with angle $θ$ and $t_{\text{opt}}$ is the minimizer of the cost function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

where $d(⋅,⋅)$ is the distance function in $SO(3)$[TronDaniilidis2017].

source
ManifoldsBase.project — Method
project(M::EssentialManifold, p, X)

Project the matrix X onto the tangent space

\[T_{p} \text{SO}(3)^2 = T_{\text{vp}}\text{SO}(3)^2 ⊕ T_{\text{hp}}\text{SO}(3)^2,\]

by first computing its projection onto the vertical space $T_{\text{vp}}\text{SO}(3)^2$ using vert_proj. Then the orthogonal projection of X onto the horizontal space $T_{\text{hp}}\text{SO}(3)^2$ is defined as

\[\Pi_h(X) = X - \frac{\text{vert\_proj}_p(X)}{2} \begin{bmatrix} R_1^T e_z \\ R_2^T e_z \end{bmatrix},\]

with $R_i = R_0 R'_i, i=1,2,$ where $R'_i$ is part of the pose of camera $i$ $g_i = (R'_i,T'_i) ∈ \text{SE}(3)$ and $R_0 ∈ \text{SO}(3)$ such that $R_0(T'_2-T'_1) = e_z$.

source

Internal Functions

Manifolds.dist_min_angle_pair — Method
dist_min_angle_pair(p, q)

This function computes the global minimizer of the function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

for the given values. This is done by finding the discontinuity points $t_{d_i}, i=1,2$ of its derivative and using Newton's method to minimize the function over the intervals $[t_{d_1},t_{d_2}]$ and $[t_{d_2},t_{d_1}+2π]$ separately. Then, the minimizer for which $f$ is minimal is chosen and given back together with the minimal value. For more details see Algorithm 1 in [TronDaniilidis2017].

source
Manifolds.dist_min_angle_pair_df_newton — Method
dist_min_angle_pair_df_newton(m1, Φ1, c1, m2, Φ2, c2, t_min, t_low, t_high)

This function computes the minimizer of the function

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

in the interval $[$t_low, t_high$]$ using Newton's method. For more details see [TronDaniilidis2017].

source
Manifolds.dist_min_angle_pair_discontinuity_distance — Method
dist_min_angle_pair_discontinuity_distance(q)

This function computes the point $t_{\text{di}}$ for which the first derivative of

\[f(t) = f_1 + f_2, \quad f_i = \frac{1}{2} θ^2_i(t), \quad θ_i(t)=d(R_{p_i},R_z(t)R_{b_i}) \text{ for } i=1,2,\]

does not exist. This is the case for $\sin(θ_i(t_{\text{di}})) = 0$. For more details see Proposition 9 and its proof, as well as Lemma 1 in [TronDaniilidis2017].

source
Manifolds.vert_proj — Method
vert_proj(M::EssentialManifold, p, X)

Project X onto the vertical space $T_{\text{vp}}\text{SO}(3)^2$ with

\[\text{vert\_proj}_p(X) = e_z^T(R_1 X_1 + R_2 X_2),\]

where $e_z$ is the third unit vector, $X_i ∈ T_{p}\text{SO}(3)$ for $i=1,2,$ and it holds $R_i = R_0 R'_i, i=1,2,$ where $R'_i$ is part of the pose of camera $i$ $g_i = (R_i,T'_i) ∈ \text{SE}(3)$ and $R_0 ∈ \text{SO}(3)$ such that $R_0(T'_2-T'_1) = e_z$ [TronDaniilidis2017].

source

Literature

diff --git a/previews/PR628/manifolds/euclidean.html b/previews/PR628/manifolds/euclidean.html index 8363381b66..b0f57c5cb4 100644 --- a/previews/PR628/manifolds/euclidean.html +++ b/previews/PR628/manifolds/euclidean.html @@ -1,3 +1,3 @@ Euclidean · Manifolds.jl
Edit on GitHub

Euclidean space

The Euclidean space $ℝ^n$ is a simple model space, since it has curvature constantly zero everywhere; hence, nearly all operations simplify. The easiest way to generate an Euclidean space is to use a field, i.e. AbstractNumbers, e.g. to create the $ℝ^n$ or $ℝ^{n\times n}$ you can simply type M = ℝ^n or ℝ^(n,n), respectively.

Manifolds.Euclidean — Type
Euclidean{T<:Tuple,𝔽} <: AbstractManifold{𝔽}

Euclidean vector space.

Constructor

Euclidean(n)

Generate the $n$-dimensional vector space $ℝ^n$.

Euclidean(n₁,n₂,...,nᵢ; field=ℝ)
-𝔽^(n₁,n₂,...,nᵢ) = Euclidean(n₁,n₂,...,nᵢ; field=𝔽)

Generate the vector space of $k = n_1 \cdot n_2 \cdot … \cdot n_i$ values, i.e. the manifold $𝔽^{n_1, n_2, …, n_i}$, $𝔽\in\{ℝ,ℂ\}$, whose elements are interpreted as $n_1 × n_2 × … × n_i$ arrays. For $i=2$ we obtain a matrix space. The default field=ℝ can also be set to field=ℂ. The dimension of this space is $k \dim_ℝ 𝔽$, where $\dim_ℝ 𝔽$ is the real_dimension of the field $𝔽$.

Euclidean(; field=ℝ)

Generate the 1D Euclidean manifold for an ℝ-, ℂ-valued real- or complex-valued immutable values (in contrast to 1-element arrays from the constructor above).

source
Base.exp — Method
exp(M::Euclidean, p, X)

Compute the exponential map on the Euclidean manifold M from p in direction X, which in this case is just

\[\exp_p X = p + X.\]

source
Base.log — Method
log(M::Euclidean, p, q)

Compute the logarithmic map on the Euclidean M from p to q, which in this case is just

\[\log_p q = q-p.\]

source
LinearAlgebra.norm — Method
norm(M::Euclidean, p, X)

Compute the norm of a tangent vector X at p on the Euclidean M, i.e. since every tangent space can be identified with M itself in this case, just the (Frobenius) norm of X.

source
ManifoldsBase.distance — Method
distance(M::Euclidean, p, q)

Compute the Euclidean distance between two points on the Euclidean manifold M, i.e. for vectors it's just the norm of the difference, for matrices and higher order arrays, the matrix and ternsor Frobenius norm, respectively.

source
ManifoldsBase.embed — Method
embed(M::Euclidean, p, X)

Embed the tangent vector X at point p in M. Equivalent to an identity map.

source
ManifoldsBase.inner — Method
inner(M::Euclidean, p, X, Y)

Compute the inner product on the Euclidean M, which is just the inner product on the real-valued or complex valued vector space of arrays (or tensors) of size $n_1 × n_2 × … × n_i$, i.e.

\[g_p(X,Y) = \sum_{k ∈ I} \overline{X}_{k} Y_{k},\]

where $I$ is the set of vectors $k ∈ ℕ^i$, such that for all

$i ≤ j ≤ i$ it holds $1 ≤ k_j ≤ n_j$ and $\overline{\cdot}$ denotes the complex conjugate.

For the special case of $i ≤ 2$, i.e. matrices and vectors, this simplifies to

\[g_p(X,Y) = X^{\mathrm{H}}Y,\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::Euclidean, p, X)

Project an arbitrary vector X into the tangent space of a point p on the Euclidean M, which is just the identity, since any tangent space of M can be identified with all of M.

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Euclidean, p, X, q, ::AbstractVectorTransportMethod)

Transport the vector X from the tangent space at p to the tangent space at q on the Euclidean M, which simplifies to the identity.

source
+𝔽^(n₁,n₂,...,nᵢ) = Euclidean(n₁,n₂,...,nᵢ; field=𝔽)

Generate the vector space of $k = n_1 \cdot n_2 \cdot … \cdot n_i$ values, i.e. the manifold $𝔽^{n_1, n_2, …, n_i}$, $𝔽\in\{ℝ,ℂ\}$, whose elements are interpreted as $n_1 × n_2 × … × n_i$ arrays. For $i=2$ we obtain a matrix space. The default field=ℝ can also be set to field=ℂ. The dimension of this space is $k \dim_ℝ 𝔽$, where $\dim_ℝ 𝔽$ is the real_dimension of the field $𝔽$.

Euclidean(; field=ℝ)

Generate the 1D Euclidean manifold for an ℝ-, ℂ-valued real- or complex-valued immutable values (in contrast to 1-element arrays from the constructor above).

source
Base.exp — Method
exp(M::Euclidean, p, X)

Compute the exponential map on the Euclidean manifold M from p in direction X, which in this case is just

\[\exp_p X = p + X.\]

source
Base.log — Method
log(M::Euclidean, p, q)

Compute the logarithmic map on the Euclidean M from p to q, which in this case is just

\[\log_p q = q-p.\]

source
LinearAlgebra.norm — Method
norm(M::Euclidean, p, X)

Compute the norm of a tangent vector X at p on the Euclidean M, i.e. since every tangent space can be identified with M itself in this case, just the (Frobenius) norm of X.

source
Manifolds.manifold_volume — Method
manifold_volume(::Euclidean)

Return volume of the Euclidean manifold, i.e. infinity.

source
Manifolds.volume_density — Method
volume_density(M::Euclidean, p, X)

Return volume density function of Euclidean manifold M, i.e. 1.

source
ManifoldsBase.distance — Method
distance(M::Euclidean, p, q)

Compute the Euclidean distance between two points on the Euclidean manifold M, i.e. for vectors it's just the norm of the difference, for matrices and higher order arrays, the matrix and ternsor Frobenius norm, respectively.

source
ManifoldsBase.embed — Method
embed(M::Euclidean, p, X)

Embed the tangent vector X at point p in M. Equivalent to an identity map.

source
ManifoldsBase.embed — Method
embed(M::Euclidean, p)

Embed the point p in M. Equivalent to an identity map.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(M::Euclidean)

Return the injectivity radius on the Euclidean M, which is $∞$.

source
ManifoldsBase.inner — Method
inner(M::Euclidean, p, X, Y)

Compute the inner product on the Euclidean M, which is just the inner product on the real-valued or complex valued vector space of arrays (or tensors) of size $n_1 × n_2 × … × n_i$, i.e.

\[g_p(X,Y) = \sum_{k ∈ I} \overline{X}_{k} Y_{k},\]

where $I$ is the set of vectors $k ∈ ℕ^i$, such that for all

$i ≤ j ≤ i$ it holds $1 ≤ k_j ≤ n_j$ and $\overline{\cdot}$ denotes the complex conjugate.

For the special case of $i ≤ 2$, i.e. matrices and vectors, this simplifies to

\[g_p(X,Y) = X^{\mathrm{H}}Y,\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.is_flat — Method
is_flat(::Euclidean)

Return true. Euclidean is a flat manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Euclidean)

Return the manifold dimension of the Euclidean M, i.e. the product of all array dimensions and the real_dimension of the underlying number system.

source
ManifoldsBase.parallel_transport_along — Method
parallel_transport_along(M::Euclidean, p, X, c)

the parallel transport on Euclidean is the identiy, i.e. returns X.

source
ManifoldsBase.parallel_transport_direction — Method
parallel_transport_direction(M::Euclidean, p, X, d)

the parallel transport on Euclidean is the identiy, i.e. returns X.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::Euclidean, p, X, q)

the parallel transport on Euclidean is the identiy, i.e. returns X.

source
ManifoldsBase.project — Method
project(M::Euclidean, p, X)

Project an arbitrary vector X into the tangent space of a point p on the Euclidean M, which is just the identity, since any tangent space of M can be identified with all of M.

source
ManifoldsBase.project — Method
project(M::Euclidean, p)

Project an arbitrary point p onto the Euclidean manifold M, which is of course just the identity map.

source
ManifoldsBase.representation_size — Method
representation_size(M::Euclidean)

Return the array dimensions required to represent an element on the Euclidean M, i.e. the vector of all array dimensions.

source
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::Euclidean, p, X, Y, Z)

Compute the Riemann tensor $R(X,Y)Z$ at point p on Euclidean manifold M. Its value is always the zero tangent vector. ````

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Euclidean, p, X, q, ::AbstractVectorTransportMethod)

Transport the vector X from the tangent space at p to the tangent space at q on the Euclidean M, which simplifies to the identity.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::Euclidean, x)

Return the zero vector in the tangent space of x on the Euclidean M, which here is just a zero filled array the same size as x.

source
diff --git a/previews/PR628/manifolds/fixedrankmatrices.html b/previews/PR628/manifolds/fixedrankmatrices.html index 10b8a69cfa..7cb3377a0c 100644 --- a/previews/PR628/manifolds/fixedrankmatrices.html +++ b/previews/PR628/manifolds/fixedrankmatrices.html @@ -6,4 +6,4 @@ \text{ s.t. } U_p^\mathrm{H}U_X = 0_k, V_p^\mathrm{H}V_X = 0_k -\bigr\},\]

where $0_k$ is the $k × k$ zero matrix. See UMVTVector for details.

The (default) metric of this manifold is obtained by restricting the metric on $ℝ^{m × n}$ to the tangent bundle[Vandereycken2013].

Constructor

FixedRankMatrices(m, n, k[, field=ℝ])

Generate the manifold of m-by-n (field-valued) matrices of rank k.

source
Manifolds.SVDMPoint — Type
SVDMPoint <: AbstractManifoldPoint

A point on a certain manifold, where the data is stored in a svd like fashion, i.e. in the form $USV^\mathrm{H}$, where this structure stores $U$, $S$ and $V^\mathrm{H}$. The storage might also be shortened to just $k$ singular values and accordingly shortened $U$ (columns) and $V^\mathrm{H}$ (rows).

Constructors

  • SVDMPoint(A) for a matrix A, stores its svd factors (i.e. implicitly $k=\min\{m,n\}$)
  • SVDMPoint(S) for an SVD object, stores its svd factors (i.e. implicitly $k=\min\{m,n\}$)
  • SVDMPoint(U,S,Vt) for the svd factors to initialize the SVDMPoint(i.e. implicitlyk=\min\{m,n\}`)
  • SVDMPoint(A,k) for a matrix A, stores its svd factors shortened to the best rank $k$ approximation
  • SVDMPoint(S,k) for an SVD object, stores its svd factors shortened to the best rank $k$ approximation
  • SVDMPoint(U,S,Vt,k) for the svd factors to initialize the SVDMPoint, stores its svd factors shortened to the best rank $k$ approximation
source
Manifolds.UMVTVector — Type
UMVTVector <: TVector

A tangent vector that can be described as a product $U_p M V_p^\mathrm{H} + U_X V_p^\mathrm{H} + U_p V_X^\mathrm{H}$, where $X = U_X S V_X^\mathrm{H}$ is its base point, see for example FixedRankMatrices.

The base point $p$ is required for example embedding this point, but it is not stored. The fields of thie tangent vector are U for $U_X$, M and Vt to store $V_X^\mathrm{H}$

Constructors

  • UMVTVector(U,M,Vt) store umv factors to initialize the UMVTVector
  • UMVTVector(U,M,Vt,k) store the umv factors after shortening them down to inner dimensions k.
source
Base.rand — Method
Random.rand(M::FixedRankMatrices; vector_at=nothing, kwargs...)

If vector_at is nothing, return a random point on the FixedRankMatrices manifold. The orthogonal matrices are sampled from the Stiefel manifold and the singular values are sampled uniformly at random.

If vector_at is not nothing, generate a random tangent vector in the tangent space of the point vector_at on the FixedRankMatrices manifold M.

source
ManifoldsBase.check_point — Method
check_point(M::FixedRankMatrices{m,n,k}, p; kwargs...)

Check whether the matrix or SVDMPoint x ids a valid point on the FixedRankMatrices{m,n,k,𝔽} M, i.e. is an m-byn matrix of rank k. For the SVDMPoint the internal representation also has to have the right shape, i.e. p.U and p.Vt have to be unitary. The keyword arguments are passed to the rank function that verifies the rank of p.

source
ManifoldsBase.check_vector — Method
check_vector(M:FixedRankMatrices{m,n,k}, p, X; kwargs...)

Check whether the tangent UMVTVector X is from the tangent space of the SVDMPoint p on the FixedRankMatrices M, i.e. that v.U and v.Vt are (columnwise) orthogonal to x.U and x.Vt, respectively, and its dimensions are consistent with p and X.M, i.e. correspond to m-by-n matrices of rank k.

source
ManifoldsBase.default_inverse_retraction_method — Method
default_inverse_retraction_method(M::FixedRankMatrices)

Return PolarInverseRetraction as the default inverse retraction for the FixedRankMatrices manifold.

source
ManifoldsBase.default_retraction_method — Method
default_retraction_method(M::FixedRankMatrices)

Return PolarRetraction as the default retraction for the FixedRankMatrices manifold.

source
ManifoldsBase.default_vector_transport_method — Method
default_vector_transport_method(M::FixedRankMatrices)

Return the ProjectionTransport as the default vector transport method for the FixedRankMatrices manifold.

source
ManifoldsBase.embed — Method
embed(M::FixedRankMatrices, p, X)

Embed the tangent vector X at point p in M from its UMVTVector representation into the set of $m×n$ matrices.

The formula reads

\[U_pMV_p^{\mathrm{H}} + U_XV_p^{\mathrm{H}} + U_pV_X^{\mathrm{H}}\]

source
ManifoldsBase.embed — Method
embed(::FixedRankMatrices, p::SVDMPoint)

Embed the point p from its SVDMPoint representation into the set of $m×n$ matrices by computing $USV^{\mathrm{H}}$.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(::FixedRankMatrices)

Return the incjectivity radius of the manifold of FixedRankMatrices, i.e. 0. See [HosseiniUschmajew2017].

source
ManifoldsBase.inner — Method
inner(M::FixedRankMatrices, p::SVDMPoint, X::UMVTVector, Y::UMVTVector)

Compute the inner product of X and Y in the tangent space of p on the FixedRankMatrices M, which is inherited from the embedding, i.e. can be computed using dot on the elements (U, Vt, M) of X and Y.

source
ManifoldsBase.is_flat — Method
is_flat(::FixedRankMatrices)

Return false. FixedRankMatrices is not a flat manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::FixedRankMatrices{m,n,k,𝔽})

Return the manifold dimension for the 𝔽-valued FixedRankMatrices M of dimension mxn of rank k, namely

\[\dim(\mathcal M) = k(m + n - k) \dim_ℝ 𝔽,\]

where $\dim_ℝ 𝔽$ is the real_dimension of 𝔽.

source
ManifoldsBase.project — Method
project(M, p, A)

Project the matrix $A ∈ ℝ^{m,n}$ or from the embedding the tangent space at $p$ on the FixedRankMatrices M, further decomposing the result into $X=UMV^\mathrm{H}$, i.e. a UMVTVector.

source
ManifoldsBase.representation_size — Method
representation_size(M::FixedRankMatrices{m,n,k})

Return the element size of a point on the FixedRankMatrices M, i.e. the size of matrices on this manifold $(m,n)$.

source
ManifoldsBase.retract — Method
retract(M, p, X, ::PolarRetraction)

Compute an SVD-based retraction on the FixedRankMatrices M by computing

\[ q = U_kS_kV_k^\mathrm{H},\]

where $U_k S_k V_k^\mathrm{H}$ is the shortened singular value decomposition $USV^\mathrm{H}=p+X$, in the sense that $S_k$ is the diagonal matrix of size $k × k$ with the $k$ largest singular values and $U$ and $V$ are shortened accordingly.

source
ManifoldsBase.vector_transport_to! — Method
vector_transport_to(M::FixedRankMatrices, p, X, q, ::ProjectionTransport)

Compute the vector transport of the tangent vector X at p to q, using the project of X to q.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::FixedRankMatrices, p::SVDMPoint)

Return a UMVTVector representing the zero tangent vector in the tangent space of p on the FixedRankMatrices M, for example all three elements of the resulting structure are zero matrices.

source

Literature

+\bigr\},\]

where $0_k$ is the $k × k$ zero matrix. See UMVTVector for details.

The (default) metric of this manifold is obtained by restricting the metric on $ℝ^{m × n}$ to the tangent bundle[Vandereycken2013].

Constructor

FixedRankMatrices(m, n, k[, field=ℝ])

Generate the manifold of m-by-n (field-valued) matrices of rank k.

source
Manifolds.SVDMPoint — Type
SVDMPoint <: AbstractManifoldPoint

A point on a certain manifold, where the data is stored in a svd like fashion, i.e. in the form $USV^\mathrm{H}$, where this structure stores $U$, $S$ and $V^\mathrm{H}$. The storage might also be shortened to just $k$ singular values and accordingly shortened $U$ (columns) and $V^\mathrm{H}$ (rows).

Constructors

  • SVDMPoint(A) for a matrix A, stores its svd factors (i.e. implicitly $k=\min\{m,n\}$)
  • SVDMPoint(S) for an SVD object, stores its svd factors (i.e. implicitly $k=\min\{m,n\}$)
  • SVDMPoint(U,S,Vt) for the svd factors to initialize the SVDMPoint(i.e. implicitlyk=\min\{m,n\}`)
  • SVDMPoint(A,k) for a matrix A, stores its svd factors shortened to the best rank $k$ approximation
  • SVDMPoint(S,k) for an SVD object, stores its svd factors shortened to the best rank $k$ approximation
  • SVDMPoint(U,S,Vt,k) for the svd factors to initialize the SVDMPoint, stores its svd factors shortened to the best rank $k$ approximation
source
Manifolds.UMVTVector — Type
UMVTVector <: TVector

A tangent vector that can be described as a product $U_p M V_p^\mathrm{H} + U_X V_p^\mathrm{H} + U_p V_X^\mathrm{H}$, where $X = U_X S V_X^\mathrm{H}$ is its base point, see for example FixedRankMatrices.

The base point $p$ is required for example embedding this point, but it is not stored. The fields of thie tangent vector are U for $U_X$, M and Vt to store $V_X^\mathrm{H}$

Constructors

  • UMVTVector(U,M,Vt) store umv factors to initialize the UMVTVector
  • UMVTVector(U,M,Vt,k) store the umv factors after shortening them down to inner dimensions k.
source
Base.rand — Method
Random.rand(M::FixedRankMatrices; vector_at=nothing, kwargs...)

If vector_at is nothing, return a random point on the FixedRankMatrices manifold. The orthogonal matrices are sampled from the Stiefel manifold and the singular values are sampled uniformly at random.

If vector_at is not nothing, generate a random tangent vector in the tangent space of the point vector_at on the FixedRankMatrices manifold M.

source
ManifoldsBase.check_point — Method
check_point(M::FixedRankMatrices{m,n,k}, p; kwargs...)

Check whether the matrix or SVDMPoint x ids a valid point on the FixedRankMatrices{m,n,k,𝔽} M, i.e. is an m-byn matrix of rank k. For the SVDMPoint the internal representation also has to have the right shape, i.e. p.U and p.Vt have to be unitary. The keyword arguments are passed to the rank function that verifies the rank of p.

source
ManifoldsBase.check_vector — Method
check_vector(M:FixedRankMatrices{m,n,k}, p, X; kwargs...)

Check whether the tangent UMVTVector X is from the tangent space of the SVDMPoint p on the FixedRankMatrices M, i.e. that v.U and v.Vt are (columnwise) orthogonal to x.U and x.Vt, respectively, and its dimensions are consistent with p and X.M, i.e. correspond to m-by-n matrices of rank k.

source
ManifoldsBase.default_inverse_retraction_method — Method
default_inverse_retraction_method(M::FixedRankMatrices)

Return PolarInverseRetraction as the default inverse retraction for the FixedRankMatrices manifold.

source
ManifoldsBase.default_retraction_method — Method
default_retraction_method(M::FixedRankMatrices)

Return PolarRetraction as the default retraction for the FixedRankMatrices manifold.

source
ManifoldsBase.default_vector_transport_method — Method
default_vector_transport_method(M::FixedRankMatrices)

Return the ProjectionTransport as the default vector transport method for the FixedRankMatrices manifold.

source
ManifoldsBase.embed — Method
embed(M::FixedRankMatrices, p, X)

Embed the tangent vector X at point p in M from its UMVTVector representation into the set of $m×n$ matrices.

The formula reads

\[U_pMV_p^{\mathrm{H}} + U_XV_p^{\mathrm{H}} + U_pV_X^{\mathrm{H}}\]

source
ManifoldsBase.embed — Method
embed(::FixedRankMatrices, p::SVDMPoint)

Embed the point p from its SVDMPoint representation into the set of $m×n$ matrices by computing $USV^{\mathrm{H}}$.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(::FixedRankMatrices)

Return the incjectivity radius of the manifold of FixedRankMatrices, i.e. 0. See [HosseiniUschmajew2017].

source
ManifoldsBase.inner — Method
inner(M::FixedRankMatrices, p::SVDMPoint, X::UMVTVector, Y::UMVTVector)

Compute the inner product of X and Y in the tangent space of p on the FixedRankMatrices M, which is inherited from the embedding, i.e. can be computed using dot on the elements (U, Vt, M) of X and Y.

source
ManifoldsBase.is_flat — Method
is_flat(::FixedRankMatrices)

Return false. FixedRankMatrices is not a flat manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::FixedRankMatrices{m,n,k,𝔽})

Return the manifold dimension for the 𝔽-valued FixedRankMatrices M of dimension mxn of rank k, namely

\[\dim(\mathcal M) = k(m + n - k) \dim_ℝ 𝔽,\]

where $\dim_ℝ 𝔽$ is the real_dimension of 𝔽.

source
ManifoldsBase.project — Method
project(M, p, A)

Project the matrix $A ∈ ℝ^{m,n}$ or from the embedding the tangent space at $p$ on the FixedRankMatrices M, further decomposing the result into $X=UMV^\mathrm{H}$, i.e. a UMVTVector.

source
ManifoldsBase.representation_size — Method
representation_size(M::FixedRankMatrices{m,n,k})

Return the element size of a point on the FixedRankMatrices M, i.e. the size of matrices on this manifold $(m,n)$.

source
ManifoldsBase.retract — Method
retract(M, p, X, ::PolarRetraction)

Compute an SVD-based retraction on the FixedRankMatrices M by computing

\[ q = U_kS_kV_k^\mathrm{H},\]

where $U_k S_k V_k^\mathrm{H}$ is the shortened singular value decomposition $USV^\mathrm{H}=p+X$, in the sense that $S_k$ is the diagonal matrix of size $k × k$ with the $k$ largest singular values and $U$ and $V$ are shortened accordingly.

source
ManifoldsBase.vector_transport_to! — Method
vector_transport_to(M::FixedRankMatrices, p, X, q, ::ProjectionTransport)

Compute the vector transport of the tangent vector X at p to q, using the project of X to q.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::FixedRankMatrices, p::SVDMPoint)

Return a UMVTVector representing the zero tangent vector in the tangent space of p on the FixedRankMatrices M, for example all three elements of the resulting structure are zero matrices.

source

Literature

diff --git a/previews/PR628/manifolds/flag.html b/previews/PR628/manifolds/flag.html index 0afe0d75c3..c184fbc7ae 100644 --- a/previews/PR628/manifolds/flag.html +++ b/previews/PR628/manifolds/flag.html @@ -1,19 +1,19 @@ -Flag · Manifolds.jl
Edit on GitHub

Flag manifold

Manifolds.Flag — Type
Flag{N,d} <: AbstractDecoratorManifold{ℝ}

Flag manifold of $d$ subspaces of $ℝ^N$[YeWongLim2022]. By default the manifold uses the Stiefel coordinates representation, embedding it in the Stiefel manifold. The other available representation is an embedding in OrthogonalMatrices. It can be utilized using OrthogonalPoint and OrthogonalTVector wrappers.

Tangent space is represented in the block-skew-symmetric form.

Constructor

Flag(N, n1, n2, ..., nd)

Generate the manifold $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ of subspaces

\[𝕍_1 ⊆ 𝕍_2 ⊆ ⋯ ⊆ V_d, \quad \operatorname{dim}(𝕍_i) = n_i\]

where $𝕍_i$ for $i ∈ 1, 2, …, d$ are subspaces of $ℝ^N$ of dimension $\operatorname{dim} 𝕍_i = n_i$.

source
Manifolds.OrthogonalPoint — Type
OrthogonalPoint <: AbstractManifoldPoint

A type to represent points on a manifold Flag in the orthogonal coordinates representation, i.e. a rotation matrix.

source
Manifolds.ZeroTuple — Type
ZeroTuple

Internal structure for representing shape of a Flag manifold. Behaves like a normal tuple, except at index zero returns value 0.

source
Base.convert — Method
convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)

Convert tangent vector from Flag manifold M from orthogonal representation to Stiefel representation.

source
Base.convert — Method
convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint)

Convert point p from Flag manifold M from orthogonal representation to Stiefel representation.

source
Base.convert — Method
convert(::Type{OrthogonalPoint}, M::Flag, p::AbstractMatrix)

Convert point p from Flag manifold M from Stiefel representation to orthogonal representation.

source
Base.convert — Method
convert(::Type{OrthogonalTVector}, M::Flag, p::AbstractMatrix, X::AbstractMatrix)

Convert tangent vector from Flag manifold M from Stiefel representation to orthogonal representation.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Flag)

Return dimension of flag manifold $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$. The formula reads $\sum_{i=1}^d (n_i-n_{i-1})(N-n_i)$.

source

The flag manifold represented as points on the Stiefel manifold

ManifoldsBase.check_vector — Method
check_vector(M::Flag, p::AbstractMatrix, X::AbstractMatrix; kwargs... )

Check whether X is a tangent vector to point p on the Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ in the Stiefel representation, i.e. that X is a matrix of the form

\[X = \begin{bmatrix} +Flag · Manifolds.jl

Edit on GitHub

Flag manifold

Manifolds.Flag — Type
Flag{N,d} <: AbstractDecoratorManifold{ℝ}

Flag manifold of $d$ subspaces of $ℝ^N$[YeWongLim2022]. By default the manifold uses the Stiefel coordinates representation, embedding it in the Stiefel manifold. The other available representation is an embedding in OrthogonalMatrices. It can be utilized using OrthogonalPoint and OrthogonalTVector wrappers.

Tangent space is represented in the block-skew-symmetric form.

Constructor

Flag(N, n1, n2, ..., nd)

Generate the manifold $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ of subspaces

\[𝕍_1 ⊆ 𝕍_2 ⊆ ⋯ ⊆ V_d, \quad \operatorname{dim}(𝕍_i) = n_i\]

where $𝕍_i$ for $i ∈ 1, 2, …, d$ are subspaces of $ℝ^N$ of dimension $\operatorname{dim} 𝕍_i = n_i$.

source
Manifolds.OrthogonalPoint — Type
OrthogonalPoint <: AbstractManifoldPoint

A type to represent points on a manifold Flag in the orthogonal coordinates representation, i.e. a rotation matrix.

source
Manifolds.ZeroTuple — Type
ZeroTuple

Internal structure for representing shape of a Flag manifold. Behaves like a normal tuple, except at index zero returns value 0.

source
Base.convert — Method
convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)

Convert tangent vector from Flag manifold M from orthogonal representation to Stiefel representation.

source
Base.convert — Method
convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint)

Convert point p from Flag manifold M from orthogonal representation to Stiefel representation.

source
Base.convert — Method
convert(::Type{OrthogonalPoint}, M::Flag, p::AbstractMatrix)

Convert point p from Flag manifold M from Stiefel representation to orthogonal representation.

source
Base.convert — Method
convert(::Type{OrthogonalTVector}, M::Flag, p::AbstractMatrix, X::AbstractMatrix)

Convert tangent vector from Flag manifold M from Stiefel representation to orthogonal representation.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Flag)

Return dimension of flag manifold $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$. The formula reads $\sum_{i=1}^d (n_i-n_{i-1})(N-n_i)$.

source

The flag manifold represented as points on the Stiefel manifold

ManifoldsBase.check_vector — Method
check_vector(M::Flag, p::AbstractMatrix, X::AbstractMatrix; kwargs... )

Check whether X is a tangent vector to point p on the Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ in the Stiefel representation, i.e. that X is a matrix of the form

\[X = \begin{bmatrix} 0 & B_{1,2} & \cdots & B_{1,d} \\ -B_{1,2}^\mathrm{T} & 0 & \cdots & B_{2,d} \\ \vdots & \vdots & \ddots & \vdots \\ -B_{1,d}^\mathrm{T} & -B_{2,d}^\mathrm{T} & \cdots & 0 \\ -B_{1,d+1}^\mathrm{T} & -B_{2,d+1}^\mathrm{T} & \cdots & -B_{d,d+1}^\mathrm{T} -\end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

source
ManifoldsBase.project — Method
project(::Flag, p, X)

Project vector X in the Euclidean embedding to the tangent space at point p on Flag manifold. The formula reads[YeWongLim2022]:

\[Y_i = X_i - (p_i p_i^{\mathrm{T}}) X_i + \sum_{j \neq i} p_j X_j^{\mathrm{T}} p_i\]

for $i$ from 1 to $d$ where the resulting vector is $Y = [Y_1, Y_2, …, Y_d]$ and $X = [X_1, X_2, …, X_d]$, $p = [p_1, p_2, …, p_d]$ are decompositions into basis vector matrices for consecutive subspaces of the flag.

source
ManifoldsBase.retract — Method
retract(M::Flag, p, X, ::PolarRetraction)

Compute the SVD-based retraction PolarRetraction on the Flag M. With $USV = p + X$ the retraction reads

\[\operatorname{retr}_p X = UV^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source

The flag manifold represented as orthogonal matrices

ManifoldsBase.check_vector — Method
check_vector(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector; kwargs... )

Check whether X is a tangent vector to point p on the Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ in the orthogonal matrix representation, i.e. that X is block-skew-symmetric with zero diagonal:

\[X = \begin{bmatrix} +\end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

source
ManifoldsBase.project — Method
project(::Flag, p, X)

Project vector X in the Euclidean embedding to the tangent space at point p on Flag manifold. The formula reads[YeWongLim2022]:

\[Y_i = X_i - (p_i p_i^{\mathrm{T}}) X_i + \sum_{j \neq i} p_j X_j^{\mathrm{T}} p_i\]

for $i$ from 1 to $d$ where the resulting vector is $Y = [Y_1, Y_2, …, Y_d]$ and $X = [X_1, X_2, …, X_d]$, $p = [p_1, p_2, …, p_d]$ are decompositions into basis vector matrices for consecutive subspaces of the flag.

source
ManifoldsBase.retract — Method
retract(M::Flag, p, X, ::PolarRetraction)

Compute the SVD-based retraction PolarRetraction on the Flag M. With $USV = p + X$ the retraction reads

\[\operatorname{retr}_p X = UV^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source

The flag manifold represented as orthogonal matrices

ManifoldsBase.check_vector — Method
check_vector(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector; kwargs... )

Check whether X is a tangent vector to point p on the Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ in the orthogonal matrix representation, i.e. that X is block-skew-symmetric with zero diagonal:

\[X = \begin{bmatrix} 0 & B_{1,2} & \cdots & B_{1,d+1} \\ -B_{1,2}^\mathrm{T} & 0 & \cdots & B_{2,d+1} \\ \vdots & \vdots & \ddots & \vdots \\ -B_{1,d+1}^\mathrm{T} & -B_{2,d+1}^\mathrm{T} & \cdots & 0 -\end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

source
ManifoldsBase.project — Method
project(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)

Project vector X to tangent space at point p from Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$, in the orthogonal matrix representation. It works by first projecting X to the space of SkewHermitianMatrices and then setting diagonal blocks to 0:

\[X = \begin{bmatrix} +\end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

source
ManifoldsBase.project — Method
project(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)

Project vector X to tangent space at point p from Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$, in the orthogonal matrix representation. It works by first projecting X to the space of SkewHermitianMatrices and then setting diagonal blocks to 0:

\[X = \begin{bmatrix} 0 & B_{1,2} & \cdots & B_{1,d+1} \\ -B_{1,2}^\mathrm{T} & 0 & \cdots & B_{2,d+1} \\ \vdots & \vdots & \ddots & \vdots \\ -B_{1,d+1}^\mathrm{T} & -B_{2,d+1}^\mathrm{T} & \cdots & 0 -\end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

source
ManifoldsBase.retract — Method
retract(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector, ::QRRetraction)

Compute the QR retraction on the Flag in the orthogonal matrix representation as the first order approximation to the exponential map. Similar to QR retraction for [GeneralUnitaryMatrices].

source
+\end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

source
ManifoldsBase.retract — Method
retract(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector, ::QRRetraction)

Compute the QR retraction on the Flag in the orthogonal matrix representation as the first order approximation to the exponential map. Similar to QR retraction for [GeneralUnitaryMatrices].

source
diff --git a/previews/PR628/manifolds/generalizedgrassmann.html b/previews/PR628/manifolds/generalizedgrassmann.html index c689093bc4..37396ff593 100644 --- a/previews/PR628/manifolds/generalizedgrassmann.html +++ b/previews/PR628/manifolds/generalizedgrassmann.html @@ -1,11 +1,11 @@ Generalized Grassmann · Manifolds.jl
Edit on GitHub

Generalized Grassmann

Manifolds.GeneralizedGrassmann — Type
GeneralizedGrassmann{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}

The generalized Grassmann manifold $\operatorname{Gr}(n,k,B)$ consists of all subspaces spanned by $k$ linear independent vectors $𝔽^n$, where $𝔽 ∈ \{ℝ, ℂ\}$ is either the real- (or complex-) valued vectors. This yields all $k$-dimensional subspaces of $ℝ^n$ for the real-valued case and all $2k$-dimensional subspaces of $ℂ^n$ for the second.

The manifold can be represented as

\[\operatorname{Gr}(n, k, B) := \bigl\{ \operatorname{span}(p)\ \big|\ p ∈ 𝔽^{n × k}, p^\mathrm{H}Bp = I_k\},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate (or Hermitian) transpose and $I_k$ is the $k × k$ identity matrix. This means, that the columns of $p$ form an unitary basis of the subspace with respect to the scaled inner product, that is a point on $\operatorname{Gr}(n,k,B)$, and hence the subspace can actually be represented by a whole equivalence class of representers. For $B=I_n$ this simplifies to the Grassmann manifold.

The tangent space at a point (subspace) $p$ is given by

\[T_x\mathrm{Gr}(n,k,B) = \bigl\{ X ∈ 𝔽^{n × k} : -X^{\mathrm{H}}Bp + p^{\mathrm{H}}BX = 0_{k} \bigr\},\]

where $0_{k}$ denotes the $k × k$ zero matrix.

Note that a point $p ∈ \operatorname{Gr}(n,k,B)$ might be represented by different matrices (i.e. matrices with $B$-unitary column vectors that span the same subspace). Different representations of $p$ also lead to different representation matrices for the tangent space $T_p\mathrm{Gr}(n,k,B)$

The manifold is named after Hermann G. Graßmann (1809-1877).

Constructor

GeneralizedGrassmann(n, k, B=I_n, field=ℝ)

Generate the (real-valued) Generalized Grassmann manifold of $n\times k$ dimensional orthonormal matrices with scalar product B.

source
Base.exp — Method
exp(M::GeneralizedGrassmann, p, X)

Compute the exponential map on the GeneralizedGrassmann M$= \mathrm{Gr}(n,k,B)$ starting in p with tangent vector (direction) X. Let $X^{\mathrm{H}}BX = USV$ denote the SVD decomposition of $X^{\mathrm{H}}BX$. Then the exponential map is written using

\[\exp_p X = p V\cos(S)V^\mathrm{H} + U\sin(S)V^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of $S$.

source
Base.log — Method
log(M::GeneralizedGrassmann, p, q)

Compute the logarithmic map on the GeneralizedGrassmann M$ = \mathcal M=\mathrm{Gr}(n,k,B)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads

\[\log_p q = V\cdot \operatorname{atan}(S) \cdot U^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian. The matrices $U$ and $V$ are the unitary matrices, and $S$ is the diagonal matrix containing the singular values of the SVD-decomposition

\[USV = (q^\mathrm{H}Bp)^{-1} ( q^\mathrm{H} - q^\mathrm{H}Bpp^\mathrm{H}).\]

In this formula the $\operatorname{atan}$ is meant elementwise.

source
Base.rand — Method
rand(::GeneralizedGrassmann; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (Gaussian) point p on the GeneralizedGrassmann manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size $n×k$.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{vector\_at}\mathrm{St}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.

source
ManifoldsBase.change_metric — Method
change_metric(M::GeneralizedGrassmann, ::EuclideanMetric, p X)

Change X to the corresponding vector with respect to the metric of the GeneralizedGrassmann M, i.e. let $B=LL'$ be the Cholesky decomposition of the matrix M.B, then the corresponding vector is $L\X$.

source
ManifoldsBase.change_representer — Method
change_representer(M::GeneralizedGrassmann, ::EuclideanMetric, p, X)

Change X to the corresponding representer of a cotangent vector at p with respect to the scaled metric of the GeneralizedGrassmann M, i.e, since

\[g_p(X,Y) = \operatorname{tr}(Y^{\mathrm{H}}BZ) = \operatorname{tr}(X^{\mathrm{H}}Z) = ⟨X,Z⟩\]

has to hold for all $Z$, where the repreenter X is given, the resulting representer with respect to the metric on the GeneralizedGrassmann is given by $Y = B^{-1}X$.

source
ManifoldsBase.check_point — Method
check_point(M::GeneralizedGrassmann{n,k,𝔽}, p)

Check whether p is representing a point on the GeneralizedGrassmann M, i.e. its a n-by-k matrix of unitary column vectors with respect to the B inner prudct and of correct eltype with respect to 𝔽.

source
ManifoldsBase.check_vector — Method
check_vector(M::GeneralizedGrassmann{n,k,𝔽}, p, X; kwargs...)

Check whether X is a tangent vector in the tangent space of p on the GeneralizedGrassmann M, i.e. that X is of size and type as well as that

\[ p^{\mathrm{H}}BX + \overline{X^{\mathrm{H}}Bp} = 0_k,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, $\overline{\cdot}$ the (elementwise) complex conjugate, and $0_k$ denotes the $k × k$ zero natrix.

source
ManifoldsBase.distance — Method
distance(M::GeneralizedGrassmann, p, q)

Compute the Riemannian distance on GeneralizedGrassmann manifold M$= \mathrm{Gr}(n,k,B)$.

The distance is given by

\[d_{\mathrm{Gr}(n,k,B)}(p,q) = \operatorname{norm}(\log_p(q)).\]

source
ManifoldsBase.inner — Method
inner(M::GeneralizedGrassmann, p, X, Y)

Compute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedGrassmann manifold M. The formula reads

\[g_p(X,Y) = \operatorname{tr}(X^{\mathrm{H}}BY),\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.project — Method
project(M::GeneralizedGrassmann, p, X)

Project the n-by-k X onto the tangent space of p on the GeneralizedGrassmann M, which is computed by

\[\operatorname{proj_p}(X) = X - pp^{\mathrm{H}}B^\mathrm{T}X,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian and $\cdot^{\mathrm{T}}$ the transpose.

source
ManifoldsBase.project — Method
project(M::GeneralizedGrassmann, p)

Project p from the embedding onto the GeneralizedGrassmann M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}}Bq$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose.

source
Statistics.mean — Method
mean(
+X^{\mathrm{H}}Bp + p^{\mathrm{H}}BX = 0_{k} \bigr\},\]
where $0_{k}$ denotes the $k × k$ zero matrix.
Note that a point $p ∈ \operatorname{Gr}(n,k,B)$ might be represented by different matrices (i.e. matrices with $B$-unitary column vectors that span the same subspace). Different representations of $p$ also lead to different representation matrices for the tangent space $T_p\mathrm{Gr}(n,k,B)$
The manifold is named after Hermann G. Graßmann (1809-1877).
Constructor
GeneralizedGrassmann(n, k, B=I_n, field=ℝ)
Generate the (real-valued) Generalized Grassmann manifold of $n\times k$ dimensional orthonormal matrices with scalar product B.
source
Base.exp — Method
exp(M::GeneralizedGrassmann, p, X)

Compute the exponential map on the GeneralizedGrassmann M$= \mathrm{Gr}(n,k,B)$ starting in p with tangent vector (direction) X. Let $X^{\mathrm{H}}BX = USV$ denote the SVD decomposition of $X^{\mathrm{H}}BX$. Then the exponential map is written using

\[\exp_p X = p V\cos(S)V^\mathrm{H} + U\sin(S)V^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of $S$.

source
Base.log — Method
log(M::GeneralizedGrassmann, p, q)

Compute the logarithmic map on the GeneralizedGrassmann M$ = \mathcal M=\mathrm{Gr}(n,k,B)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads

\[\log_p q = V\cdot \operatorname{atan}(S) \cdot U^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian. The matrices $U$ and $V$ are the unitary matrices, and $S$ is the diagonal matrix containing the singular values of the SVD-decomposition

\[USV = (q^\mathrm{H}Bp)^{-1} ( q^\mathrm{H} - q^\mathrm{H}Bpp^\mathrm{H}).\]

In this formula the $\operatorname{atan}$ is meant elementwise.

source
Base.rand — Method
rand(::GeneralizedGrassmann; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (Gaussian) point p on the GeneralizedGrassmann manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size $n×k$.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{vector\_at}\mathrm{St}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.

source
ManifoldsBase.change_metric — Method
change_metric(M::GeneralizedGrassmann, ::EuclideanMetric, p X)

Change X to the corresponding vector with respect to the metric of the GeneralizedGrassmann M, i.e. let $B=LL'$ be the Cholesky decomposition of the matrix M.B, then the corresponding vector is $L\X$.

source
ManifoldsBase.change_representer — Method
change_representer(M::GeneralizedGrassmann, ::EuclideanMetric, p, X)

Change X to the corresponding representer of a cotangent vector at p with respect to the scaled metric of the GeneralizedGrassmann M, i.e, since

\[g_p(X,Y) = \operatorname{tr}(Y^{\mathrm{H}}BZ) = \operatorname{tr}(X^{\mathrm{H}}Z) = ⟨X,Z⟩\]

has to hold for all $Z$, where the repreenter X is given, the resulting representer with respect to the metric on the GeneralizedGrassmann is given by $Y = B^{-1}X$.

source
ManifoldsBase.check_point — Method
check_point(M::GeneralizedGrassmann{n,k,𝔽}, p)

Check whether p is representing a point on the GeneralizedGrassmann M, i.e. its a n-by-k matrix of unitary column vectors with respect to the B inner prudct and of correct eltype with respect to 𝔽.

source
ManifoldsBase.check_vector — Method
check_vector(M::GeneralizedGrassmann{n,k,𝔽}, p, X; kwargs...)

Check whether X is a tangent vector in the tangent space of p on the GeneralizedGrassmann M, i.e. that X is of size and type as well as that

\[ p^{\mathrm{H}}BX + \overline{X^{\mathrm{H}}Bp} = 0_k,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, $\overline{\cdot}$ the (elementwise) complex conjugate, and $0_k$ denotes the $k × k$ zero natrix.

source
ManifoldsBase.distance — Method
distance(M::GeneralizedGrassmann, p, q)

Compute the Riemannian distance on GeneralizedGrassmann manifold M$= \mathrm{Gr}(n,k,B)$.

The distance is given by

\[d_{\mathrm{Gr}(n,k,B)}(p,q) = \operatorname{norm}(\log_p(q)).\]

source
ManifoldsBase.inner — Method
inner(M::GeneralizedGrassmann, p, X, Y)

Compute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedGrassmann manifold M. The formula reads

\[g_p(X,Y) = \operatorname{tr}(X^{\mathrm{H}}BY),\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.project — Method
project(M::GeneralizedGrassmann, p, X)

Project the n-by-k X onto the tangent space of p on the GeneralizedGrassmann M, which is computed by

\[\operatorname{proj_p}(X) = X - pp^{\mathrm{H}}B^\mathrm{T}X,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian and $\cdot^{\mathrm{T}}$ the transpose.

source
ManifoldsBase.project — Method
project(M::GeneralizedGrassmann, p)

Project p from the embedding onto the GeneralizedGrassmann M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}}Bq$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose.

source
+)

Compute the Riemannian mean of x using GeodesicInterpolationWithinRadius.

source diff --git a/previews/PR628/manifolds/generalizedstiefel.html b/previews/PR628/manifolds/generalizedstiefel.html index 8f9c93c403..8594f0502d 100644 --- a/previews/PR628/manifolds/generalizedstiefel.html +++ b/previews/PR628/manifolds/generalizedstiefel.html @@ -1,8 +1,8 @@ -Generalized Stiefel · Manifolds.jl
Edit on GitHub

Generalized Stiefel

Manifolds.GeneralizedStiefel — Type
GeneralizedStiefel{n,k,𝔽,B} <: AbstractDecoratorManifold{𝔽}

The Generalized Stiefel manifold consists of all $n\times k$, $n\geq k$ orthonormal matrices w.r.t. an arbitrary scalar product with symmetric positive definite matrix $B\in R^{n × n}$, i.e.

\[\operatorname{St}(n,k,B) = \bigl\{ p \in \mathbb F^{n × k}\ \big|\ p^{\mathrm{H}} B p = I_k \bigr\},\]

where $𝔽 ∈ \{ℝ, ℂ\}$, $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, and $I_k \in \mathbb R^{k × k}$ denotes the $k × k$ identity matrix.

In the case $B=I_k$ one gets the usual Stiefel manifold.

The tangent space at a point $p\in\mathcal M=\operatorname{St}(n,k,B)$ is given by

\[T_p\mathcal M = \{ X \in 𝔽^{n × k} : p^{\mathrm{H}}BX + X^{\mathrm{H}}Bp=0_n\},\]

where $0_k$ is the $k × k$ zero matrix.

This manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the zero_vector are inherited from the embedding.

The manifold is named after Eduard L. Stiefel (1909–1978).

Constructor

GeneralizedStiefel(n, k, B=I_n, F=ℝ)

Generate the (real-valued) Generalized Stiefel manifold of $n\times k$ dimensional orthonormal matrices with scalar product B.

source
Base.rand — Method
rand(::GeneralizedStiefel; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (Gaussian) point p on the GeneralizedStiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size $n×k$.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{vector\_at}\mathrm{St}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.

source
ManifoldsBase.check_point — Method
check_point(M::GeneralizedStiefel, p; kwargs...)

Check whether p is a valid point on the GeneralizedStiefel M=$\operatorname{St}(n,k,B)$, i.e. that it has the right AbstractNumbers type and $x^{\mathrm{H}}Bx$ is (approximately) the identity, where $\cdot^{\mathrm{H}}$ is the complex conjugate transpose. The settings for approximately can be set with kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::GeneralizedStiefel, p, X; kwargs...)

Check whether X is a valid tangent vector at p on the GeneralizedStiefel M=$\operatorname{St}(n,k,B)$, i.e. the AbstractNumbers fits, p is a valid point on M and it (approximately) holds that $p^{\mathrm{H}}BX + \overline{X^{\mathrm{H}}Bp} = 0$, where kwargs... is passed to the isapprox.

source
ManifoldsBase.inner — Method
inner(M::GeneralizedStiefel, p, X, Y)

Compute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedStiefel manifold M. The formula reads

\[(X, Y)_p = \operatorname{trace}(v^{\mathrm{H}}Bw),\]

i.e. the metric induced by the scalar product B from the embedding, restricted to the tangent space.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::GeneralizedStiefel)

Return the dimension of the GeneralizedStiefel manifold M=$\operatorname{St}(n,k,B,𝔽)$. The dimension is given by

\[\begin{aligned} +Generalized Stiefel · Manifolds.jl

Edit on GitHub

Generalized Stiefel

Manifolds.GeneralizedStiefel — Type
GeneralizedStiefel{n,k,𝔽,B} <: AbstractDecoratorManifold{𝔽}

The Generalized Stiefel manifold consists of all $n\times k$, $n\geq k$ orthonormal matrices w.r.t. an arbitrary scalar product with symmetric positive definite matrix $B\in R^{n × n}$, i.e.

\[\operatorname{St}(n,k,B) = \bigl\{ p \in \mathbb F^{n × k}\ \big|\ p^{\mathrm{H}} B p = I_k \bigr\},\]

where $𝔽 ∈ \{ℝ, ℂ\}$, $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, and $I_k \in \mathbb R^{k × k}$ denotes the $k × k$ identity matrix.

In the case $B=I_k$ one gets the usual Stiefel manifold.

The tangent space at a point $p\in\mathcal M=\operatorname{St}(n,k,B)$ is given by

\[T_p\mathcal M = \{ X \in 𝔽^{n × k} : p^{\mathrm{H}}BX + X^{\mathrm{H}}Bp=0_n\},\]

where $0_k$ is the $k × k$ zero matrix.

This manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the zero_vector are inherited from the embedding.

The manifold is named after Eduard L. Stiefel (1909–1978).

Constructor

GeneralizedStiefel(n, k, B=I_n, F=ℝ)

Generate the (real-valued) Generalized Stiefel manifold of $n\times k$ dimensional orthonormal matrices with scalar product B.

source
Base.rand — Method
rand(::GeneralizedStiefel; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (Gaussian) point p on the GeneralizedStiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size $n×k$.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{vector\_at}\mathrm{St}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.

source
ManifoldsBase.check_point — Method
check_point(M::GeneralizedStiefel, p; kwargs...)

Check whether p is a valid point on the GeneralizedStiefel M=$\operatorname{St}(n,k,B)$, i.e. that it has the right AbstractNumbers type and $x^{\mathrm{H}}Bx$ is (approximately) the identity, where $\cdot^{\mathrm{H}}$ is the complex conjugate transpose. The settings for approximately can be set with kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::GeneralizedStiefel, p, X; kwargs...)

Check whether X is a valid tangent vector at p on the GeneralizedStiefel M=$\operatorname{St}(n,k,B)$, i.e. the AbstractNumbers fits, p is a valid point on M and it (approximately) holds that $p^{\mathrm{H}}BX + \overline{X^{\mathrm{H}}Bp} = 0$, where kwargs... is passed to the isapprox.

source
ManifoldsBase.inner — Method
inner(M::GeneralizedStiefel, p, X, Y)

Compute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedStiefel manifold M. The formula reads

\[(X, Y)_p = \operatorname{trace}(v^{\mathrm{H}}Bw),\]

i.e. the metric induced by the scalar product B from the embedding, restricted to the tangent space.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::GeneralizedStiefel)

Return the dimension of the GeneralizedStiefel manifold M=$\operatorname{St}(n,k,B,𝔽)$. The dimension is given by

\[\begin{aligned} \dim \mathrm{St}(n, k, B, ℝ) &= nk - \frac{1}{2}k(k+1) \\ \dim \mathrm{St}(n, k, B, ℂ) &= 2nk - k^2\\ \dim \mathrm{St}(n, k, B, ℍ) &= 4nk - k(2k-1) -\end{aligned}\]

source
ManifoldsBase.project — Method
project(M:GeneralizedStiefel, p, X)

Project X onto the tangent space of p to the GeneralizedStiefel manifold M. The formula reads

\[\operatorname{proj}_{\operatorname{St}(n,k)}(p,X) = X - p\operatorname{Sym}(p^{\mathrm{H}}BX),\]

where $\operatorname{Sym}(y)$ is the symmetrization of $y$, e.g. by $\operatorname{Sym}(y) = \frac{y^{\mathrm{H}}+y}{2}$.

source
ManifoldsBase.project — Method
project(M::GeneralizedStiefel,p)

Project p from the embedding onto the GeneralizedStiefel M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}}Bq$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M:GeneralizedStiefel, p, X)

Project X onto the tangent space of p to the GeneralizedStiefel manifold M. The formula reads

\[\operatorname{proj}_{\operatorname{St}(n,k)}(p,X) = X - p\operatorname{Sym}(p^{\mathrm{H}}BX),\]

where $\operatorname{Sym}(y)$ is the symmetrization of $y$, e.g. by $\operatorname{Sym}(y) = \frac{y^{\mathrm{H}}+y}{2}$.

source
ManifoldsBase.project — Method
project(M::GeneralizedStiefel,p)

Project p from the embedding onto the GeneralizedStiefel M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}}Bq$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.retract — Method
retract(M::GeneralizedStiefel, p, X)
 retract(M::GeneralizedStiefel, p, X, ::PolarRetraction)
-retract(M::GeneralizedStiefel, p, X, ::ProjectionRetraction)

Compute the SVD-based retraction PolarRetraction on the GeneralizedStiefel manifold M, which in this case is the same as the projection based retraction employing the exponential map in the embedding and projecting the result back to the manifold.

The default retraction for this manifold is the ProjectionRetraction.

source
+retract(M::GeneralizedStiefel, p, X, ::ProjectionRetraction)

Compute the SVD-based retraction PolarRetraction on the GeneralizedStiefel manifold M, which in this case is the same as the projection based retraction employing the exponential map in the embedding and projecting the result back to the manifold.

The default retraction for this manifold is the ProjectionRetraction.

source
diff --git a/previews/PR628/manifolds/generalunitary.html b/previews/PR628/manifolds/generalunitary.html index e81bc5840f..c006c5d103 100644 --- a/previews/PR628/manifolds/generalunitary.html +++ b/previews/PR628/manifolds/generalunitary.html @@ -1,44 +1,44 @@ -Orthogonal and Unitary Matrices · Manifolds.jl
Edit on GitHub

Orthogonal and Unitary matrices

Both OrthogonalMatrices and UnitaryMatrices are quite similar, as are Rotations, as well as unitary matrices with determinant equal to one. So these share a {common implementation}(@ref generalunitarymatrices)

Orthogonal Matrices

Manifolds.OrthogonalMatrices — Type
 OrthogonalMatrices{n} = GeneralUnitaryMatrices{n,ℝ,AbsoluteDeterminantOneMatrices}

The manifold of (real) orthogonal matrices $\mathrm{O}(n)$.

OrthogonalMatrices(n)
source

Unitary Matrices

Manifolds.UnitaryMatrices — Type
const UnitaryMatrices{n,𝔽} = AbstarctUnitaryMatrices{n,𝔽,AbsoluteDeterminantOneMatrices}

The manifold $U(n,𝔽)$ of $n×n$ complex matrices (when 𝔽=ℂ) or quaternionic matrices (when 𝔽=ℍ) such that

$p^{\mathrm{H}}p = \mathrm{I}_n,$

where $\mathrm{I}_n$ is the $n×n$ identity matrix. Such matrices p have a property that $\lVert \det(p) \rVert = 1$.

The tangent spaces are given by

\[ T_pU(n) \coloneqq \bigl\{ +Orthogonal and Unitary Matrices · Manifolds.jl

Edit on GitHub

Orthogonal and Unitary matrices

Both OrthogonalMatrices and UnitaryMatrices are quite similar, as are Rotations, as well as unitary matrices with determinant equal to one. So these share a {common implementation}(@ref generalunitarymatrices)

Orthogonal Matrices

Manifolds.OrthogonalMatrices — Type
 OrthogonalMatrices{n} = GeneralUnitaryMatrices{n,ℝ,AbsoluteDeterminantOneMatrices}

The manifold of (real) orthogonal matrices $\mathrm{O}(n)$.

OrthogonalMatrices(n)
source

Unitary Matrices

Manifolds.UnitaryMatrices — Type
const UnitaryMatrices{n,𝔽} = AbstarctUnitaryMatrices{n,𝔽,AbsoluteDeterminantOneMatrices}

The manifold $U(n,𝔽)$ of $n×n$ complex matrices (when 𝔽=ℂ) or quaternionic matrices (when 𝔽=ℍ) such that

$p^{\mathrm{H}}p = \mathrm{I}_n,$

where $\mathrm{I}_n$ is the $n×n$ identity matrix. Such matrices p have a property that $\lVert \det(p) \rVert = 1$.

The tangent spaces are given by

\[ T_pU(n) \coloneqq \bigl\{ X \big| pY \text{ where } Y \text{ is skew symmetric, i. e. } Y = -Y^{\mathrm{H}} - \bigr\}\]

But note that tangent vectors are represented in the Lie algebra, i.e. just using $Y$ in the representation above.

Constructor

UnitaryMatrices(n, 𝔽::AbstractNumbers=ℂ)

see also OrthogonalMatrices for the real valued case.

source

Common functions

Manifolds.AbsoluteDeterminantOneMatrices — Type
AbsoluteDeterminantOneMatrices <: AbstractMatrixType

A type to indicate that we require (orthogonal / unitary) matrices with normed determinant, i.e. that the absolute value of the determinant is 1.

source
Manifolds.GeneralUnitaryMatrices — Type
GeneralUnitaryMatrices{n,𝔽,S<:AbstractMatrixType} <: AbstractDecoratorManifold

A common parametric type for matrices with a unitary property of size $n×n$ over the field $\mathbb F$ which additionally have the AbstractMatrixType, e.g. are DeterminantOneMatrices.

source
Base.exp — Method
exp(M::Rotations, p, X)
+    \bigr\}\]
But note that tangent vectors are represented in the Lie algebra, i.e. just using $Y$ in the representation above.
Constructor
UnitaryMatrices(n, 𝔽::AbstractNumbers=ℂ)
see also OrthogonalMatrices for the real valued case.
source

Common functions

Manifolds.AbsoluteDeterminantOneMatrices — Type
AbsoluteDeterminantOneMatrices <: AbstractMatrixType

A type to indicate that we require (orthogonal / unitary) matrices with normed determinant, i.e. that the absolute value of the determinant is 1.

source
Manifolds.GeneralUnitaryMatrices — Type
GeneralUnitaryMatrices{n,𝔽,S<:AbstractMatrixType} <: AbstractDecoratorManifold

A common parametric type for matrices with a unitary property of size $n×n$ over the field $\mathbb F$ which additionally have the AbstractMatrixType, e.g. are DeterminantOneMatrices.

source
Base.exp — Method
exp(M::Rotations, p, X)
 exp(M::OrthogonalMatrices, p, X)
-exp(M::UnitaryMatrices, p, X)

Compute the exponential map, that is, since $X$ is represented in the Lie algebra,

exp_p(X) = p\mathrm{e}^X

For different sizes, like $n=2,3,4$ there is specialised implementations

The algorithm used is a more numerically stable form of those proposed in [Gallier2002] and [Andrica2013].

source
Base.log — Method
log(M::Rotations, p, X)
+exp(M::UnitaryMatrices, p, X)

Compute the exponential map, that is, since $X$ is represented in the Lie algebra,

exp_p(X) = p\mathrm{e}^X

For different sizes, like $n=2,3,4$ there is specialised implementations

The algorithm used is a more numerically stable form of those proposed in [Gallier2002] and [Andrica2013].

source
Base.log — Method
log(M::Rotations, p, X)
 log(M::OrthogonalMatrices, p, X)
-log(M::UnitaryMatrices, p, X)

Compute the logarithmic map, that is, since the resulting $X$ is represented in the Lie algebra,

log_p q = \log(p^{\mathrm{H}q)

which is projected onto the skew symmetric matrices for numerical stability.

source
Base.log — Method
log(M::Rotations, p, q)

Compute the logarithmic map on the Rotations manifold M which is given by

\[\log_p q = \operatorname{log}(p^{\mathrm{T}}q)\]

where $\operatorname{Log}$ denotes the matrix logarithm. For numerical stability, the result is projected onto the set of skew symmetric matrices.

For antipodal rotations the function returns deterministically one of the tangent vectors that point at q.

source
Manifolds.cos_angles_4d_rotation_matrix — Method
cos_angles_4d_rotation_matrix(R)

4D rotations can be described by two orthogonal planes that are unchanged by the action of the rotation (vectors within a plane rotate only within the plane). The cosines of the two angles $α,β$ of rotation about these planes may be obtained from the distinct real parts of the eigenvalues of the rotation matrix. This function computes these more efficiently by solving the system

\[\begin{aligned} +log(M::UnitaryMatrices, p, X)

Compute the logarithmic map, that is, since the resulting $X$ is represented in the Lie algebra,

log_p q = \log(p^{\mathrm{H}q)

which is projected onto the skew symmetric matrices for numerical stability.

source
Base.log — Method
log(M::Rotations, p, q)

Compute the logarithmic map on the Rotations manifold M which is given by

\[\log_p q = \operatorname{log}(p^{\mathrm{T}}q)\]

where $\operatorname{Log}$ denotes the matrix logarithm. For numerical stability, the result is projected onto the set of skew symmetric matrices.

For antipodal rotations the function returns deterministically one of the tangent vectors that point at q.

source
Manifolds.cos_angles_4d_rotation_matrix — Method
cos_angles_4d_rotation_matrix(R)

4D rotations can be described by two orthogonal planes that are unchanged by the action of the rotation (vectors within a plane rotate only within the plane). The cosines of the two angles $α,β$ of rotation about these planes may be obtained from the distinct real parts of the eigenvalues of the rotation matrix. This function computes these more efficiently by solving the system

\[\begin{aligned} \cos α + \cos β &= \frac{1}{2} \operatorname{tr}(R)\\ \cos α \cos β &= \frac{1}{8} \operatorname{tr}(R)^2 - \frac{1}{16} \operatorname{tr}((R - R^T)^2) - 1. -\end{aligned}\]

By convention, the returned values are sorted in decreasing order. See also angles_4d_skew_sym_matrix.

source
Manifolds.manifold_volume — Method
manifold_volume(::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}) where {n}

Volume of the manifold of complex general unitary matrices of determinant one. The formula reads [BoyaSudarshanTilma2003]:

\[\sqrt{n 2^{n-1}} π^{(n-1)(n+2)/2} \prod_{k=1}^{n-1}\frac{1}{k!}\]

source
Manifolds.manifold_volume — Method
manifold_volume(::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}) where {n}

Volume of the manifold of complex general unitary matrices of determinant one. The formula reads [BoyaSudarshanTilma2003]:

\[\sqrt{n 2^{n-1}} π^{(n-1)(n+2)/2} \prod_{k=1}^{n-1}\frac{1}{k!}\]

source
Manifolds.manifold_volume — Method
manifold_volume(::GeneralUnitaryMatrices{n,ℝ,AbsoluteDeterminantOneMatrices}) where {n}

Volume of the manifold of real orthogonal matrices of absolute determinant one. The formula reads [BoyaSudarshanTilma2003]:

\[\begin{cases} \frac{2^{k}(2\pi)^{k^2}}{\prod_{s=1}^{k-1} (2s)!} & \text{ if } n = 2k \\ \frac{2^{k+1}(2\pi)^{k(k+1)}}{\prod_{s=1}^{k-1} (2s+1)!} & \text{ if } n = 2k+1 -\end{cases}\]

source
Manifolds.manifold_volume — Method
manifold_volume(::GeneralUnitaryMatrices{n,ℝ,DeterminantOneMatrices}) where {n}

Volume of the manifold of real orthogonal matrices of determinant one. The formula reads [BoyaSudarshanTilma2003]:

\[\begin{cases} 2 & \text{ if } n = 0 \\ \frac{2^{k-1/2}(2\pi)^{k^2}}{\prod_{s=1}^{k-1} (2s)!} & \text{ if } n = 2k+2 \\ \frac{2^{k+1/2}(2\pi)^{k(k+1)}}{\prod_{s=1}^{k-1} (2s+1)!} & \text{ if } n = 2k+1 -\end{cases}\]

It differs from the paper by a factor of sqrt(2) due to a different choice of normalization.

source
Manifolds.manifold_volume — Method
manifold_volume(::GeneralUnitaryMatrices{n,ℂ,AbsoluteDeterminantOneMatrices}) where {n}

Volume of the manifold of complex general unitary matrices of absolute determinant one. The formula reads [BoyaSudarshanTilma2003]:

\[\sqrt{n 2^{n+1}} π^{n(n+1)/2} \prod_{k=1}^{n-1}\frac{1}{k!}\]

source
ManifoldsBase.check_point — Method
check_point(M::Rotations, p; kwargs...)

Check whether p is a valid point on the UnitaryMatrices M, i.e. that $p$ has an determinante of absolute value one, i.e. that $p^{\mathrm{H}}p$

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_point — Method
check_point(M::UnitaryMatrices, p; kwargs...)
+\end{cases}\]
It differs from the paper by a factor of sqrt(2) due to a different choice of normalization.
source
Manifolds.manifold_volume — Method
manifold_volume(::GeneralUnitaryMatrices{n,ℂ,AbsoluteDeterminantOneMatrices}) where {n}

Volume of the manifold of complex general unitary matrices of absolute determinant one. The formula reads [BoyaSudarshanTilma2003]:

\[\sqrt{n 2^{n+1}} π^{n(n+1)/2} \prod_{k=1}^{n-1}\frac{1}{k!}\]

source
ManifoldsBase.check_point — Method
check_point(M::Rotations, p; kwargs...)

Check whether p is a valid point on the UnitaryMatrices M, i.e. that $p$ has an determinante of absolute value one, i.e. that $p^{\mathrm{H}}p$

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_point — Method
check_point(M::UnitaryMatrices, p; kwargs...)
 check_point(M::OrthogonalMatrices, p; kwargs...)
-check_point(M::GeneralUnitaryMatrices{n,𝔽}, p; kwargs...)

Check whether p is a valid point on the UnitaryMatrices or [OrthogonalMatrices] M, i.e. that $p$ has an determinante of absolute value one

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::UnitaryMatrices{n}, p, X; kwargs... )
+check_point(M::GeneralUnitaryMatrices{n,𝔽}, p; kwargs...)

Check whether p is a valid point on the UnitaryMatrices or [OrthogonalMatrices] M, i.e. that $p$ has an determinante of absolute value one

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::UnitaryMatrices{n}, p, X; kwargs... )
 check_vector(M::OrthogonalMatrices{n}, p, X; kwargs... )
 check_vector(M::Rotations{n}, p, X; kwargs... )
-check_vector(M::GeneralUnitaryMatrices{n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to p on the UnitaryMatrices space M, i.e. after check_point(M,p), X has to be skew symmetric (Hermitian) and orthogonal to p.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.embed — Method
embed(M::GeneralUnitaryMatrices{n,𝔽}, p, X)

Embed the tangent vector X at point p in M from its Lie algebra representation (set of skew matrices) into the Riemannian submanifold representation

The formula reads

\[X_{\text{embedded}} = p * X\]

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::Rotations, p, X)
+check_vector(M::GeneralUnitaryMatrices{n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to p on the UnitaryMatrices space M, i.e. after check_point(M,p), X has to be skew symmetric (Hermitian) and orthogonal to p.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.embed — Method
embed(M::GeneralUnitaryMatrices{n,𝔽}, p, X)

Embed the tangent vector X at point p in M from its Lie algebra representation (set of skew matrices) into the Riemannian submanifold representation

The formula reads

\[X_{\text{embedded}} = p * X\]

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::Rotations, p, X)
 get_coordinates(M::OrthogonalMatrices, p, X)
-get_coordinates(M::UnitaryMatrices, p, X)

Extract the unique tangent vector components $X^i$ at point p on Rotations $\mathrm{SO}(n)$ from the matrix representation X of the tangent vector.

The basis on the Lie algebra $𝔰𝔬(n)$ is chosen such that for $\mathrm{SO}(2)$, $X^1 = θ = X_{21}$ is the angle of rotation, and for $\mathrm{SO}(3)$, $(X^1, X^2, X^3) = (X_{32}, X_{13}, X_{21}) = θ u$ is the angular velocity and axis-angle representation, where $u$ is the unit vector along the axis of rotation.

For $\mathrm{SO}(n)$ where $n ≥ 4$, the additional elements of $X^i$ are $X^{j (j - 3)/2 + k + 1} = X_{jk}$, for $j ∈ [4,n], k ∈ [1,j)$.

source
ManifoldsBase.get_embedding — Method
get_embedding(M::OrthogonalMatrices{n})
+get_coordinates(M::UnitaryMatrices, p, X)

Extract the unique tangent vector components $X^i$ at point p on Rotations $\mathrm{SO}(n)$ from the matrix representation X of the tangent vector.

The basis on the Lie algebra $𝔰𝔬(n)$ is chosen such that for $\mathrm{SO}(2)$, $X^1 = θ = X_{21}$ is the angle of rotation, and for $\mathrm{SO}(3)$, $(X^1, X^2, X^3) = (X_{32}, X_{13}, X_{21}) = θ u$ is the angular velocity and axis-angle representation, where $u$ is the unit vector along the axis of rotation.

For $\mathrm{SO}(n)$ where $n ≥ 4$, the additional elements of $X^i$ are $X^{j (j - 3)/2 + k + 1} = X_{jk}$, for $j ∈ [4,n], k ∈ [1,j)$.

source
ManifoldsBase.get_embedding — Method
get_embedding(M::OrthogonalMatrices{n})
 get_embedding(M::Rotations{n})
-get_embedding(M::UnitaryMatrices{n})

Return the embedding, i.e. The $\mathbb F^{n×n}$, where $\mathbb F = \mathbb R$ for the first two and $\mathbb F = \mathbb C$ for the unitary matrices.

source
ManifoldsBase.get_vector — Method
get_vector(M::OrthogonalMatrices, p, Xⁱ, B::DefaultOrthogonalBasis)
-get_vector(M::Rotations, p, Xⁱ, B::DefaultOrthogonalBasis)

Convert the unique tangent vector components Xⁱ at point p on Rotations or OrthogonalMatrices to the matrix representation $X$ of the tangent vector. See get_coordinates for the conventions used.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(G::GeneraliUnitaryMatrices)

Return the injectivity radius for general unitary matrix manifolds, which is[1]

\[ \operatorname{inj}_{\mathrm{U}(n)} = π.\]

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(G::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})

Return the injectivity radius for general complex unitary matrix manifolds, where the determinant is $+1$, which is[1]

\[ \operatorname{inj}_{\mathrm{SU}(n)} = π \sqrt{2}.\]

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(G::SpecialOrthogonal)
+get_embedding(M::UnitaryMatrices{n})

Return the embedding, i.e. The $\mathbb F^{n×n}$, where $\mathbb F = \mathbb R$ for the first two and $\mathbb F = \mathbb C$ for the unitary matrices.

source
ManifoldsBase.get_vector — Method
get_vector(M::OrthogonalMatrices, p, Xⁱ, B::DefaultOrthogonalBasis)
+get_vector(M::Rotations, p, Xⁱ, B::DefaultOrthogonalBasis)

Convert the unique tangent vector components Xⁱ at point p on Rotations or OrthogonalMatrices to the matrix representation $X$ of the tangent vector. See get_coordinates for the conventions used.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(G::GeneraliUnitaryMatrices)

Return the injectivity radius for general unitary matrix manifolds, which is[1]

\[ \operatorname{inj}_{\mathrm{U}(n)} = π.\]

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(G::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})

Return the injectivity radius for general complex unitary matrix manifolds, where the determinant is $+1$, which is[1]

\[ \operatorname{inj}_{\mathrm{SU}(n)} = π \sqrt{2}.\]

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(G::SpecialOrthogonal)
 injectivity_radius(G::Orthogonal)
 injectivity_radius(M::Rotations)
-injectivity_radius(M::Rotations, ::ExponentialRetraction)

Return the radius of injectivity on the Rotations manifold M, which is $π\sqrt{2}$. [1]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})

Return the dimension of the manifold of special unitary matrices.

\[\dim_{\mathrm{SU}(n)} = n^2-1.\]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Rotations)
-manifold_dimension(M::OrthogonalMatrices)

Return the dimension of the manifold orthogonal matrices and of the manifold of rotations

\[\dim_{\mathrm{O}(n)} = \dim_{\mathrm{SO}(n)} = \frac{n(n-1)}{2}.\]

source
ManifoldsBase.project — Method
 project(M::OrthogonalMatrices{n}, p, X)
+injectivity_radius(M::Rotations, ::ExponentialRetraction)

Return the radius of injectivity on the Rotations manifold M, which is $π\sqrt{2}$. [1]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})

Return the dimension of the manifold of special unitary matrices.

\[\dim_{\mathrm{SU}(n)} = n^2-1.\]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Rotations)
+manifold_dimension(M::OrthogonalMatrices)

Return the dimension of the manifold orthogonal matrices and of the manifold of rotations

\[\dim_{\mathrm{O}(n)} = \dim_{\mathrm{SO}(n)} = \frac{n(n-1)}{2}.\]

source
ManifoldsBase.project — Method
 project(M::OrthogonalMatrices{n}, p, X)
  project(M::Rotations{n}, p, X)
- project(M::UnitaryMatrices{n}, p, X)

Orthogonally project the tangent vector $X ∈ 𝔽^{n × n}$, $\mathbb F ∈ \{\mathbb R, \mathbb C\}$ to the tangent space of M at p, and change the representer to use the corresponding Lie algebra, i.e. we compute

\[ \operatorname{proj}_p(X) = \frac{p^{\mathrm{H}} X - (p^{\mathrm{H}} X)^{\mathrm{H}}}{2},\]

source
ManifoldsBase.project — Method
 project(G::UnitaryMatrices{n}, p)
- project(G::OrthogonalMatrices{n}, p)

Project the point $p ∈ 𝔽^{n × n}$ to the nearest point in $\mathrm{U}(n,𝔽)=$Unitary(n,𝔽) under the Frobenius norm. If $p = U S V^\mathrm{H}$ is the singular value decomposition of $p$, then the projection is

\[ \operatorname{proj}_{\mathrm{U}(n,𝔽)} \colon p ↦ U V^\mathrm{H}.\]

source
ManifoldsBase.retract — Method
retract(M::Rotations, p, X, ::PolarRetraction)
-retract(M::OrthogonalMatrices, p, X, ::PolarRetraction)

Compute the SVD-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group) and is a second-order approximation of the exponential map. Let

\[USV = p + pX\]

be the singular value decomposition, then the formula reads

\[\operatorname{retr}_p X = UV^\mathrm{T}.\]

source
ManifoldsBase.retract — Method
retract(M::Rotations, p, X, ::QRRetraction)
-retract(M::OrthogonalMatrices, p. X, ::QRRetraction)

Compute the QR-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group), which is a first-order approximation of the exponential map.

This is also the default retraction on these manifolds.

source
Statistics.mean — Method
mean(
+ project(M::UnitaryMatrices{n}, p, X)

Orthogonally project the tangent vector $X ∈ 𝔽^{n × n}$, $\mathbb F ∈ \{\mathbb R, \mathbb C\}$ to the tangent space of M at p, and change the representer to use the corresponding Lie algebra, i.e. we compute

\[ \operatorname{proj}_p(X) = \frac{p^{\mathrm{H}} X - (p^{\mathrm{H}} X)^{\mathrm{H}}}{2},\]

source
ManifoldsBase.project — Method
 project(G::UnitaryMatrices{n}, p)
+ project(G::OrthogonalMatrices{n}, p)

Project the point $p ∈ 𝔽^{n × n}$ to the nearest point in $\mathrm{U}(n,𝔽)=$Unitary(n,𝔽) under the Frobenius norm. If $p = U S V^\mathrm{H}$ is the singular value decomposition of $p$, then the projection is

\[ \operatorname{proj}_{\mathrm{U}(n,𝔽)} \colon p ↦ U V^\mathrm{H}.\]

source
ManifoldsBase.retract — Method
retract(M::Rotations, p, X, ::PolarRetraction)
+retract(M::OrthogonalMatrices, p, X, ::PolarRetraction)

Compute the SVD-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group) and is a second-order approximation of the exponential map. Let

\[USV = p + pX\]

be the singular value decomposition, then the formula reads

\[\operatorname{retr}_p X = UV^\mathrm{T}.\]

source
ManifoldsBase.retract — Method
retract(M::Rotations, p, X, ::QRRetraction)
+retract(M::OrthogonalMatrices, p. X, ::QRRetraction)

Compute the QR-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group), which is a first-order approximation of the exponential map.

This is also the default retraction on these manifolds.

source

Footnotes and References

+)

Compute the Riemannian mean of x using GeodesicInterpolationWithinRadius.

source

Footnotes and References

diff --git a/previews/PR628/manifolds/graph.html b/previews/PR628/manifolds/graph.html index eee9c7973f..084b82313d 100644 --- a/previews/PR628/manifolds/graph.html +++ b/previews/PR628/manifolds/graph.html @@ -15,4 +15,4 @@ Euclidean(2; field = ℝ)

It supports all AbstractPowerManifold operations (it is based on NestedPowerRepresentation) and furthermore it is possible to compute a graph logarithm:

incident_log(N, p)
3-element Vector{Vector{Float64}}:
  [1.0, 1.0]
  [0.0, 0.0]
- [-1.0, -1.0]

Types and functions

Manifolds.EdgeManifold — Type
EdgeManifoldManifold <: GraphManifoldType

A type for a GraphManifold where the data is given on the edges.

source
Manifolds.GraphManifold — Type
GraphManifold{G,𝔽,M,T} <: AbstractPowerManifold{𝔽,M,NestedPowerRepresentation}

Build a manifold, that is a PowerManifold of the AbstractManifold M either on the edges or vertices of a graph G depending on the GraphManifoldType T.

Fields

  • G is an AbstractSimpleGraph
  • M is a AbstractManifold
source
Manifolds.GraphManifoldType — Type
GraphManifoldType

This type represents the type of data on the graph that the GraphManifold represents.

source
Manifolds.VertexManifold — Type
VectexGraphManifold <: GraphManifoldType

A type for a GraphManifold where the data is given on the vertices.

source
Manifolds.incident_log — Method
incident_log(M::GraphManifold, x)

Return the tangent vector on the (vertex) GraphManifold, where at each node the sum of the logs to incident nodes is computed. For a SimpleGraph, an egde is interpreted as double edge in the corresponding SimpleDiGraph

If the internal graph is a SimpleWeightedGraph the weighted sum of the tangent vectors is computed.

source
ManifoldsBase.check_point — Method
check_point(M::GraphManifold, p)

Check whether p is a valid point on the GraphManifold, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of p passes the check_point test for the base manifold M.manifold.

source
ManifoldsBase.check_vector — Method
check_vector(M::GraphManifold, p, X; kwargs...)

Check whether p is a valid point on the GraphManifold, and X it from its tangent space, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of X together with its corresponding entry of p passes the check_vector test for the base manifold M.manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(N::GraphManifold{G,𝔽,M,EdgeManifold})

returns the manifold dimension of the GraphManifold N on the edges of a graph $G=(V,E)$, i.e.

\[\dim(\mathcal N) = \lvert E \rvert \dim(\mathcal M),\]

where $\mathcal M$ is the manifold of the data on the edges.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(N::GraphManifold{G,𝔽,M,VertexManifold})

returns the manifold dimension of the GraphManifold N on the vertices of a graph $G=(V,E)$, i.e.

\[\dim(\mathcal N) = \lvert V \rvert \dim(\mathcal M),\]

where $\mathcal M$ is the manifold of the data on the nodes.

source
+ [-1.0, -1.0]

Types and functions

Manifolds.EdgeManifold — Type
EdgeManifoldManifold <: GraphManifoldType

A type for a GraphManifold where the data is given on the edges.

source
Manifolds.GraphManifold — Type
GraphManifold{G,𝔽,M,T} <: AbstractPowerManifold{𝔽,M,NestedPowerRepresentation}

Build a manifold, that is a PowerManifold of the AbstractManifold M either on the edges or vertices of a graph G depending on the GraphManifoldType T.

Fields

  • G is an AbstractSimpleGraph
  • M is a AbstractManifold
source
Manifolds.GraphManifoldType — Type
GraphManifoldType

This type represents the type of data on the graph that the GraphManifold represents.

source
Manifolds.VertexManifold — Type
VectexGraphManifold <: GraphManifoldType

A type for a GraphManifold where the data is given on the vertices.

source
Manifolds.incident_log — Method
incident_log(M::GraphManifold, x)

Return the tangent vector on the (vertex) GraphManifold, where at each node the sum of the logs to incident nodes is computed. For a SimpleGraph, an egde is interpreted as double edge in the corresponding SimpleDiGraph

If the internal graph is a SimpleWeightedGraph the weighted sum of the tangent vectors is computed.

source
ManifoldsBase.check_point — Method
check_point(M::GraphManifold, p)

Check whether p is a valid point on the GraphManifold, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of p passes the check_point test for the base manifold M.manifold.

source
ManifoldsBase.check_vector — Method
check_vector(M::GraphManifold, p, X; kwargs...)

Check whether p is a valid point on the GraphManifold, and X it from its tangent space, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of X together with its corresponding entry of p passes the check_vector test for the base manifold M.manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(N::GraphManifold{G,𝔽,M,EdgeManifold})

returns the manifold dimension of the GraphManifold N on the edges of a graph $G=(V,E)$, i.e.

\[\dim(\mathcal N) = \lvert E \rvert \dim(\mathcal M),\]

where $\mathcal M$ is the manifold of the data on the edges.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(N::GraphManifold{G,𝔽,M,VertexManifold})

returns the manifold dimension of the GraphManifold N on the vertices of a graph $G=(V,E)$, i.e.

\[\dim(\mathcal N) = \lvert V \rvert \dim(\mathcal M),\]

where $\mathcal M$ is the manifold of the data on the nodes.

source
diff --git a/previews/PR628/manifolds/grassmann.html b/previews/PR628/manifolds/grassmann.html index a65813f4ea..e6c7cde782 100644 --- a/previews/PR628/manifolds/grassmann.html +++ b/previews/PR628/manifolds/grassmann.html @@ -2,17 +2,17 @@ Grassmann · Manifolds.jl
Edit on GitHub

Grassmannian manifold

Manifolds.Grassmann — Type
Grassmann{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}

The Grassmann manifold $\operatorname{Gr}(n,k)$ consists of all subspaces spanned by $k$ linear independent vectors $𝔽^n$, where $𝔽 ∈ \{ℝ, ℂ\}$ is either the real- (or complex-) valued vectors. This yields all $k$-dimensional subspaces of $ℝ^n$ for the real-valued case and all $2k$-dimensional subspaces of $ℂ^n$ for the second.

The manifold can be represented as

\[\operatorname{Gr}(n,k) := \bigl\{ \operatorname{span}(p) : p ∈ 𝔽^{n × k}, p^\mathrm{H}p = I_k\},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian and $I_k$ is the $k × k$ identity matrix. This means, that the columns of $p$ form an unitary basis of the subspace, that is a point on $\operatorname{Gr}(n,k)$, and hence the subspace can actually be represented by a whole equivalence class of representers. Another interpretation is, that

\[\operatorname{Gr}(n,k) = \operatorname{St}(n,k) / \operatorname{O}(k),\]

i.e the Grassmann manifold is the quotient of the Stiefel manifold and the orthogonal group $\operatorname{O}(k)$ of orthogonal $k × k$ matrices. Note that it doesn't matter whether we start from the Euclidean or canonical metric on the Stiefel manifold, the resulting quotient metric on Grassmann is the same.

The tangent space at a point (subspace) $p$ is given by

\[T_p\mathrm{Gr}(n,k) = \bigl\{ X ∈ 𝔽^{n × k} : X^{\mathrm{H}}p + p^{\mathrm{H}}X = 0_{k} \bigr\},\]

where $0_k$ is the $k × k$ zero matrix.

Note that a point $p ∈ \operatorname{Gr}(n,k)$ might be represented by different matrices (i.e. matrices with unitary column vectors that span the same subspace). Different representations of $p$ also lead to different representation matrices for the tangent space $T_p\mathrm{Gr}(n,k)$

For a representation of points as orthogonal projectors. Here

\[\operatorname{Gr}(n,k) := \bigl\{ p \in \mathbb R^{n×n} : p = p^˜\mathrm{T}, p^2 = p, \operatorname{rank}(p) = k\},\]

with tangent space

\[T_p\mathrm{Gr}(n,k) = \bigl\{ -X ∈ \mathbb R^{n × n} : X=X^{\mathrm{T}} \text{ and } X = pX+Xp \bigr\},\]

see also ProjectorPoint and ProjectorTVector.

The manifold is named after Hermann G. Graßmann (1809-1877).

A good overview can be found in[BendokatZimmermannAbsil2020].

Constructor

Grassmann(n,k,field=ℝ)

Generate the Grassmann manifold $\operatorname{Gr}(n,k)$, where the real-valued case field = ℝ is the default.

source
Base.convert — Method
convert(::Type{ProjectorPoint}, p::AbstractMatrix)

Convert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for

\[ π^{\mathrm{SG}}(p) = pp^{\mathrm{T)}.\]

source
Base.convert — Method
convert(::Type{ProjectorPoint}, ::Stiefelpoint)

Convert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for

\[ π^{\mathrm{SG}}(p) = pp^{\mathrm{T}}.\]

source
ManifoldsBase.change_metric — Method
change_metric(M::Grassmann, ::EuclideanMetric, p X)

Change X to the corresponding vector with respect to the metric of the Grassmann M, which is just the identity, since the manifold is isometrically embedded.

source
ManifoldsBase.change_representer — Method
change_representer(M::Grassmann, ::EuclideanMetric, p, X)

Change X to the corresponding representer of a cotangent vector at p. Since the Grassmann manifold M, is isometrically embedded, this is the identity

source
Base.convert — Method
convert(::Type{ProjectorPoint}, p::AbstractMatrix)

Convert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for

\[ π^{\mathrm{SG}}(p) = pp^{\mathrm{T)}.\]

source
Base.convert — Method
convert(::Type{ProjectorPoint}, ::Stiefelpoint)

Convert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for

\[ π^{\mathrm{SG}}(p) = pp^{\mathrm{T}}.\]

source
ManifoldsBase.change_metric — Method
change_metric(M::Grassmann, ::EuclideanMetric, p X)

Change X to the corresponding vector with respect to the metric of the Grassmann M, which is just the identity, since the manifold is isometrically embedded.

source
ManifoldsBase.change_representer — Method
change_representer(M::Grassmann, ::EuclideanMetric, p, X)

Change X to the corresponding representer of a cotangent vector at p. Since the Grassmann manifold M, is isometrically embedded, this is the identity

source

The Grassmanian represented as points on the Stiefel manifold

Manifolds.StiefelPoint — Type
StiefelPoint <: AbstractManifoldPoint

A point on a Stiefel manifold. This point is mainly used for representing points on the Grassmann where this is also the default representation and hence equivalent to using AbstractMatrices thereon. they can also used be used as points on Stiefel.

source
Manifolds.StiefelTVector — Type
StiefelTVector <: TVector

A tangent vector on the Grassmann manifold represented by a tangent vector from the tangent space of a corresponding point from the Stiefel manifold, see StiefelPoint. This is the default representation so is can be used interchangeably with just abstract matrices.

source
Base.exp — Method
exp(M::Grassmann, p, X)

Compute the exponential map on the Grassmann M$= \mathrm{Gr}(n,k)$ starting in p with tangent vector (direction) X. Let $X = USV$ denote the SVD decomposition of $X$. Then the exponential map is written using

\[z = p V\cos(S)V^\mathrm{H} + U\sin(S)V^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of $S$. A final QR decomposition $z=QR$ is performed for numerical stability reasons, yielding the result as

\[\exp_p X = Q.\]

source
Base.log — Method
log(M::Grassmann, p, q)

Compute the logarithmic map on the Grassmann M$ = \mathcal M=\mathrm{Gr}(n,k)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads

\[\log_p q = V\cdot \operatorname{atan}(S) \cdot U^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian. The matrices $U$ and $V$ are the unitary matrices, and $S$ is the diagonal matrix containing the singular values of the SVD-decomposition

\[USV = (q^\mathrm{H}p)^{-1} ( q^\mathrm{H} - q^\mathrm{H}pp^\mathrm{H}).\]

In this formula the $\operatorname{atan}$ is meant elementwise.

source
Base.rand — Method
rand(M::Grassmann; σ::Real=1.0, vector_at=nothing)

When vector_at is nothing, return a random point p on Grassmann manifold M by generating a random (Gaussian) matrix with standard deviation σ in matching size, which is orthonormal.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_p\mathrm{Gr}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent space at vector_at.

source
Manifolds.uniform_distribution — Method
uniform_distribution(M::Grassmann{n,k,ℝ}, p)

Uniform distribution on given (real-valued) Grassmann M. Specifically, this is the normalized Haar measure on M. Generated points will be of similar type as p.

The implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.2(iii) in [Chikuse2003].

source
ManifoldsBase.distance — Method
distance(M::Grassmann, p, q)

Compute the Riemannian distance on Grassmann manifold M$= \mathrm{Gr}(n,k)$.

The distance is given by

\[d_{\mathrm{Gr}(n,k)}(p,q) = \operatorname{norm}(\log_p(q)).\]

source
ManifoldsBase.inner — Method
inner(M::Grassmann, p, X, Y)

Compute the inner product for two tangent vectors X, Y from the tangent space of p on the Grassmann manifold M. The formula reads

\[g_p(X,Y) = \operatorname{tr}(X^{\mathrm{H}}Y),\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Grassmann, p, q, ::PolarInverseRetraction)

Compute the inverse retraction for the PolarRetraction, on the Grassmann manifold M, i.e.,

\[\operatorname{retr}_p^{-1}q = q*(p^\mathrm{H}q)^{-1} - p,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M, p, q, ::QRInverseRetraction)

Compute the inverse retraction for the QRRetraction, on the Grassmann manifold M, i.e.,

\[\operatorname{retr}_p^{-1}q = q(p^\mathrm{H}q)^{-1} - p,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.project — Method
project(M::Grassmann, p)

Project p from the embedding onto the Grassmann M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}}q$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::Grassmann, p, X)

Project the n-by-k X onto the tangent space of p on the Grassmann M, which is computed by

\[\operatorname{proj_p}(X) = X - pp^{\mathrm{H}}X,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.retract — Method
retract(M::Grassmann, p, X, ::PolarRetraction)

Compute the SVD-based retraction PolarRetraction on the Grassmann M. With $USV = p + X$ the retraction reads

\[\operatorname{retr}_p X = UV^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.retract — Method
retract(M::Grassmann, p, X, ::QRRetraction )

Compute the QR-based retraction QRRetraction on the Grassmann M. With $QR = p + X$ the retraction reads

\[\operatorname{retr}_p X = QD,\]

where D is a $m × n$ matrix with

\[D = \operatorname{diag}\left( \operatorname{sgn}\left(R_{ii}+\frac{1}{2}\right)_{i=1}^n \right).\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Grassmann,p,X,q,::ProjectionTransport)

compute the projection based transport on the Grassmann M by interpreting X from the tangent space at p as a point in the embedding and projecting it onto the tangent space at q.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::Grassmann, p)

Return the zero tangent vector from the tangent space at p on the Grassmann M, which is given by a zero matrix the same size as p.

source

The Grassmannian represented as projectors

Manifolds.ProjectorPoint — Type
ProjectorPoint <: AbstractManifoldPoint

A type to represent points on a manifold Grassmann that are orthogonal projectors, i.e. a matrix $p ∈ \mathbb F^{n,n}$ projecting onto a $k$-dimensional subspace.

source
Base.exp — Method
exp(M::Grassmann, p::ProjectorPoint, X::ProjectorTVector)

Compute the exponential map on the Grassmann as

\[ \exp_pX = \operatorname{Exp}([X,p])p\operatorname{Exp}(-[X,p]),\]

where $\operatorname{Exp}$ denotes the matrix exponential and $[A,B] = AB-BA$ denotes the matrix commutator.

For details, see Proposition 3.2 in [BendokatZimmermannAbsil2020].

source
Manifolds.horizontal_lift — Method
horizontal_lift(N::Stiefel{n,k}, q, X::ProjectorTVector)

Compute the horizontal lift of X from the tangent space at $p=π(q)$ on the Grassmann manifold, i.e.

\[Y = Xq ∈ T_q\mathrm{St}(n,k)\]

source
ManifoldsBase.check_point — Method
check_point(::Grassmann{n,k}, p::ProjectorPoint; kwargs...)

Check whether an orthogonal projector is a point from the Grassmann(n,k) manifold, i.e. the ProjectorPoint $p ∈ \mathbb F^{n×n}$, $\mathbb F ∈ \{\mathbb R, \mathbb C\}$ has to fulfill $p^{\mathrm{T}} = p$, $p^2=p$, and `\operatorname{rank} p = k.

source
ManifoldsBase.check_vector — Method
check_vector(::Grassmann{n,k,𝔽}, p::ProjectorPoint, X::ProjectorTVector; kwargs...) where {n,k,𝔽}

Check whether the ProjectorTVector X is from the tangent space $T_p\operatorname{Gr}(n,k)$ at the ProjectorPoint p on the Grassmann manifold $\operatorname{Gr}(n,k)$. This means that X has to be symmetric and that

\[Xp + pX = X\]

must hold, where the kwargs can be used to check both for symmetrix of $X$` and this equality up to a certain tolerance.

source

The Grassmanian represented as points on the Stiefel manifold

Manifolds.StiefelPoint — Type
StiefelPoint <: AbstractManifoldPoint

A point on a Stiefel manifold. This point is mainly used for representing points on the Grassmann where this is also the default representation and hence equivalent to using AbstractMatrices thereon. they can also used be used as points on Stiefel.

source
Manifolds.StiefelTVector — Type
StiefelTVector <: TVector

A tangent vector on the Grassmann manifold represented by a tangent vector from the tangent space of a corresponding point from the Stiefel manifold, see StiefelPoint. This is the default representation so is can be used interchangeably with just abstract matrices.

source
Base.exp — Method
exp(M::Grassmann, p, X)

Compute the exponential map on the Grassmann M$= \mathrm{Gr}(n,k)$ starting in p with tangent vector (direction) X. Let $X = USV$ denote the SVD decomposition of $X$. Then the exponential map is written using

\[z = p V\cos(S)V^\mathrm{H} + U\sin(S)V^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of $S$. A final QR decomposition $z=QR$ is performed for numerical stability reasons, yielding the result as

\[\exp_p X = Q.\]

source
Base.log — Method
log(M::Grassmann, p, q)

Compute the logarithmic map on the Grassmann M$ = \mathcal M=\mathrm{Gr}(n,k)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads

\[\log_p q = V\cdot \operatorname{atan}(S) \cdot U^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian. The matrices $U$ and $V$ are the unitary matrices, and $S$ is the diagonal matrix containing the singular values of the SVD-decomposition

\[USV = (q^\mathrm{H}p)^{-1} ( q^\mathrm{H} - q^\mathrm{H}pp^\mathrm{H}).\]

In this formula the $\operatorname{atan}$ is meant elementwise.

source
Base.rand — Method
rand(M::Grassmann; σ::Real=1.0, vector_at=nothing)

When vector_at is nothing, return a random point p on Grassmann manifold M by generating a random (Gaussian) matrix with standard deviation σ in matching size, which is orthonormal.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_p\mathrm{Gr}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent space at vector_at.

source
Manifolds.uniform_distribution — Method
uniform_distribution(M::Grassmann{n,k,ℝ}, p)

Uniform distribution on given (real-valued) Grassmann M. Specifically, this is the normalized Haar measure on M. Generated points will be of similar type as p.

The implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.2(iii) in [Chikuse2003].

source
ManifoldsBase.distance — Method
distance(M::Grassmann, p, q)

Compute the Riemannian distance on Grassmann manifold M$= \mathrm{Gr}(n,k)$.

The distance is given by

\[d_{\mathrm{Gr}(n,k)}(p,q) = \operatorname{norm}(\log_p(q)).\]

source
ManifoldsBase.inner — Method
inner(M::Grassmann, p, X, Y)

Compute the inner product for two tangent vectors X, Y from the tangent space of p on the Grassmann manifold M. The formula reads

\[g_p(X,Y) = \operatorname{tr}(X^{\mathrm{H}}Y),\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Grassmann, p, q, ::PolarInverseRetraction)

Compute the inverse retraction for the PolarRetraction, on the Grassmann manifold M, i.e.,

\[\operatorname{retr}_p^{-1}q = q*(p^\mathrm{H}q)^{-1} - p,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M, p, q, ::QRInverseRetraction)

Compute the inverse retraction for the QRRetraction, on the Grassmann manifold M, i.e.,

\[\operatorname{retr}_p^{-1}q = q(p^\mathrm{H}q)^{-1} - p,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.project — Method
project(M::Grassmann, p)

Project p from the embedding onto the Grassmann M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}}q$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::Grassmann, p, X)

Project the n-by-k X onto the tangent space of p on the Grassmann M, which is computed by

\[\operatorname{proj_p}(X) = X - pp^{\mathrm{H}}X,\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.retract — Method
retract(M::Grassmann, p, X, ::PolarRetraction)

Compute the SVD-based retraction PolarRetraction on the Grassmann M. With $USV = p + X$ the retraction reads

\[\operatorname{retr}_p X = UV^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

source
ManifoldsBase.retract — Method
retract(M::Grassmann, p, X, ::QRRetraction )

Compute the QR-based retraction QRRetraction on the Grassmann M. With $QR = p + X$ the retraction reads

\[\operatorname{retr}_p X = QD,\]

where D is a $m × n$ matrix with

\[D = \operatorname{diag}\left( \operatorname{sgn}\left(R_{ii}+\frac{1}{2}\right)_{i=1}^n \right).\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Grassmann,p,X,q,::ProjectionTransport)

compute the projection based transport on the Grassmann M by interpreting X from the tangent space at p as a point in the embedding and projecting it onto the tangent space at q.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::Grassmann, p)

Return the zero tangent vector from the tangent space at p on the Grassmann M, which is given by a zero matrix the same size as p.

source

The Grassmannian represented as projectors

Manifolds.ProjectorPoint — Type
ProjectorPoint <: AbstractManifoldPoint

A type to represent points on a manifold Grassmann that are orthogonal projectors, i.e. a matrix $p ∈ \mathbb F^{n,n}$ projecting onto a $k$-dimensional subspace.

source
Base.exp — Method
exp(M::Grassmann, p::ProjectorPoint, X::ProjectorTVector)

Compute the exponential map on the Grassmann as

\[ \exp_pX = \operatorname{Exp}([X,p])p\operatorname{Exp}(-[X,p]),\]

where $\operatorname{Exp}$ denotes the matrix exponential and $[A,B] = AB-BA$ denotes the matrix commutator.

For details, see Proposition 3.2 in [BendokatZimmermannAbsil2020].

source
Manifolds.horizontal_lift — Method
horizontal_lift(N::Stiefel{n,k}, q, X::ProjectorTVector)

Compute the horizontal lift of X from the tangent space at $p=π(q)$ on the Grassmann manifold, i.e.

\[Y = Xq ∈ T_q\mathrm{St}(n,k)\]

source
ManifoldsBase.check_point — Method
check_point(::Grassmann{n,k}, p::ProjectorPoint; kwargs...)

Check whether an orthogonal projector is a point from the Grassmann(n,k) manifold, i.e. the ProjectorPoint $p ∈ \mathbb F^{n×n}$, $\mathbb F ∈ \{\mathbb R, \mathbb C\}$ has to fulfill $p^{\mathrm{T}} = p$, $p^2=p$, and `\operatorname{rank} p = k.

source
ManifoldsBase.check_vector — Method
check_vector(::Grassmann{n,k,𝔽}, p::ProjectorPoint, X::ProjectorTVector; kwargs...) where {n,k,𝔽}

Check whether the ProjectorTVector X is from the tangent space $T_p\operatorname{Gr}(n,k)$ at the ProjectorPoint p on the Grassmann manifold $\operatorname{Gr}(n,k)$. This means that X has to be symmetric and that

\[Xp + pX = X\]

must hold, where the kwargs can be used to check both for symmetrix of $X$` and this equality up to a certain tolerance.

source
ManifoldsBase.parallel_transport_direction — Method
parallel_transport_direction(
     M::Grassmann,
     p::ProjectorPoint,
     X::ProjectorTVector,
     d::ProjectorTVector
-)

Compute the parallel transport of X from the tangent space at p into direction d, i.e. to $q=\exp_pd$. The formula is given in Proposition 3.5 of [BendokatZimmermannAbsil2020] as

\[\mathcal{P}_{q ← p}(X) = \operatorname{Exp}([d,p])X\operatorname{Exp}(-[d,p]),\]

where $\operatorname{Exp}$ denotes the matrix exponential and $[A,B] = AB-BA$ denotes the matrix commutator.

source
+)

Compute the parallel transport of X from the tangent space at p into direction d, i.e. to $q=\exp_pd$. The formula is given in Proposition 3.5 of [BendokatZimmermannAbsil2020] as

\[\mathcal{P}_{q ← p}(X) = \operatorname{Exp}([d,p])X\operatorname{Exp}(-[d,p]),\]

where $\operatorname{Exp}$ denotes the matrix exponential and $[A,B] = AB-BA$ denotes the matrix commutator.

source
ManifoldsBase.representation_size — Method
representation_size(M::Grassmann{n,k}, p::ProjectorPoint)

Return the represenation size or matrix dimension of a point on the Grassmann M when using ProjectorPoints, i.e. $(n,n)$.

source
diff --git a/previews/PR628/manifolds/group.html b/previews/PR628/manifolds/group.html index 58397f838c..f47dc80093 100644 --- a/previews/PR628/manifolds/group.html +++ b/previews/PR628/manifolds/group.html @@ -1,88 +1,88 @@ Group manifold · Manifolds.jl
Edit on GitHub

Group manifolds and actions

Lie groups, groups that are Riemannian manifolds with a smooth binary group operation AbstractGroupOperation, are implemented as AbstractDecoratorManifold and specifying the group operation using the IsGroupManifold or by decorating an existing manifold with a group operation using GroupManifold.

The common addition and multiplication group operations of AdditionOperation and MultiplicationOperation are provided, though their behavior may be customized for a specific group.

There are short introductions at the beginning of each subsection. They briefly mention what is available with links to more detailed descriptions.

Contents

Groups

The following operations are available for group manifolds:

  • Identity: an allocation-free representation of the identity element of the group.
  • inv: get the inverse of a given element.
  • compose: compose two given elements of a group.
  • identity_element get the identity element of the group, in the representation used by other points from the group.

Group manifold

GroupManifold adds a group structure to the wrapped manifold. It does not affect metric (or connection) structure of the wrapped manifold, however it can to be further wrapped in MetricManifold to get invariant metrics, or in a ConnectionManifold to equip it with a Cartan-Schouten connection.

Manifolds.AbstractGroupOperation — Type
AbstractGroupOperation

Abstract type for smooth binary operations $∘$ on elements of a Lie group $\mathcal{G}$:

\[∘ : \mathcal{G} × \mathcal{G} → \mathcal{G}\]

An operation can be either defined for a specific group manifold over number system 𝔽 or in general, by defining for an operation Op the following methods:

identity_element!(::AbstractDecoratorManifold, q, q)
 inv!(::AbstractDecoratorManifold, q, p)
-_compose!(::AbstractDecoratorManifold, x, p, q)

Note that a manifold is connected with an operation by wrapping it with a decorator, AbstractDecoratorManifold using the IsGroupManifold to specify the operation. For a concrete case the concrete wrapper GroupManifold can be used.

source
Manifolds.ForwardBackwardSwitch — Type
struct ForwardBackwardSwitch <: AbstractDirectionSwitchType end

Switch between forward and backward action, maintaining left/right direction.

source
Manifolds.GroupExponentialRetraction — Type
GroupExponentialRetraction{D<:ActionDirection} <: AbstractRetractionMethod

Retraction using the group exponential exp_lie "translated" to any point on the manifold.

For more details, see retract.

Constructor

GroupExponentialRetraction(conv::ActionDirection = LeftForwardAction())
source
Manifolds.GroupLogarithmicInverseRetraction — Type
GroupLogarithmicInverseRetraction{D<:ActionDirection} <: AbstractInverseRetractionMethod

Retraction using the group logarithm log_lie "translated" to any point on the manifold.

For more details, see inverse_retract.

Constructor

GroupLogarithmicInverseRetraction(conv::ActionDirection = LeftForwardAction())
source
Manifolds.Identity — Type
Identity{O<:AbstractGroupOperation}

Represent the group identity element $e ∈ \mathcal{G}$ on a Lie group $\mathcal G$ with AbstractGroupOperation of type O.

Similar to the philosophy that points are agnostic of their group at hand, the identity does not store the group g it belongs to. However it depends on the type of the AbstractGroupOperation used.

See also identity_element on how to obtain the corresponding AbstractManifoldPoint or array representation.

Constructors

Identity(G::AbstractDecoratorManifold{𝔽})
+_compose!(::AbstractDecoratorManifold, x, p, q)

Note that a manifold is connected with an operation by wrapping it with a decorator, AbstractDecoratorManifold using the IsGroupManifold to specify the operation. For a concrete case the concrete wrapper GroupManifold can be used.

source
Manifolds.ForwardBackwardSwitch — Type
struct ForwardBackwardSwitch <: AbstractDirectionSwitchType end

Switch between forward and backward action, maintaining left/right direction.

source
Manifolds.GroupExponentialRetraction — Type
GroupExponentialRetraction{D<:ActionDirection} <: AbstractRetractionMethod

Retraction using the group exponential exp_lie "translated" to any point on the manifold.

For more details, see retract.

Constructor

GroupExponentialRetraction(conv::ActionDirection = LeftForwardAction())
source
Manifolds.GroupLogarithmicInverseRetraction — Type
GroupLogarithmicInverseRetraction{D<:ActionDirection} <: AbstractInverseRetractionMethod

Retraction using the group logarithm log_lie "translated" to any point on the manifold.

For more details, see inverse_retract.

Constructor

GroupLogarithmicInverseRetraction(conv::ActionDirection = LeftForwardAction())
source
Manifolds.Identity — Type
Identity{O<:AbstractGroupOperation}

Represent the group identity element $e ∈ \mathcal{G}$ on a Lie group $\mathcal G$ with AbstractGroupOperation of type O.

Similar to the philosophy that points are agnostic of their group at hand, the identity does not store the group g it belongs to. However it depends on the type of the AbstractGroupOperation used.

See also identity_element on how to obtain the corresponding AbstractManifoldPoint or array representation.

Constructors

Identity(G::AbstractDecoratorManifold{𝔽})
 Identity(o::O)
-Identity(::Type{O})

create the identity of the corresponding subtype O<:AbstractGroupOperation

source
Manifolds.IsGroupManifold — Type
IsGroupManifold{O<:AbstractGroupOperation} <: AbstractTrait

A trait to declare an AbstractManifold as a manifold with group structure with operation of type O.

Using this trait you can turn a manifold that you implement implictly into a Lie group. If you wish to decorate an existing manifold with one (or different) AbstractGroupActions, see GroupManifold.

Constructor

IsGroupManifold(op)
source
Manifolds.LeftBackwardAction — Type
LeftBackwardAction()

Left action of a group on a manifold. For an action $α: X × G → X$ it is characterized by

\[α(α(x, h), g) = α(x, gh)\]

for all $g, h ∈ G$ and $x ∈ X$.

Note that a left action may still act from the right side in an expression.

source
Manifolds.LeftForwardAction — Type
LeftForwardAction()

Left action of a group on a manifold. For an action $α: G × X → X$ it is characterized by

\[α(g, α(h, x)) = α(gh, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

source
Manifolds.LeftRightSwitch — Type
struct LeftRightSwitch <: AbstractDirectionSwitchType end

Switch between left and right action, maintaining forward/backward direction.

source
Manifolds.RightBackwardAction — Type
RightBackwardAction()

Right action of a group on a manifold. For an action $α: X × G → X$ it is characterized by

\[α(α(x, h), g) = α(x, hg)\]

for all $g, h ∈ G$ and $x ∈ X$.

Note that a right action may still act from the left side in an expression.

source
Manifolds.RightForwardAction — Type
RightForwardAction()

Right action of a group on a manifold. For an action $α: G × X → X$ it is characterized by

\[α(g, α(h, x)) = α(hg, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

Note that a right action may still act from the left side in an expression.

source
Base.inv — Method
inv(G::AbstractDecoratorManifold, p)

Inverse $p^{-1} ∈ \mathcal{G}$ of an element $p ∈ \mathcal{G}$, such that $p \circ p^{-1} = p^{-1} \circ p = e ∈ \mathcal{G}$, where $e$ is the Identity element of $\mathcal{G}$.

source
Manifolds.adjoint_action — Method
adjoint_action(G::AbstractDecoratorManifold, p, X)

Adjoint action of the element p of the Lie group G on the element X of the corresponding Lie algebra.

It is defined as the differential of the group authomorphism $Ψ_p(q) = pqp⁻¹$ at the identity of G.

The formula reads

\[\operatorname{Ad}_p(X) = dΨ_p(e)[X]\]

where $e$ is the identity element of G.

Note that the adjoint representation of a Lie group isn't generally faithful. Notably the adjoint representation of SO(2) is trivial.

source
Manifolds.compose — Method
compose(G::AbstractDecoratorManifold, p, q)

Compose elements $p,q ∈ \mathcal{G}$ using the group operation $p \circ q$.

For implementing composition on a new group manifold, please overload _compose instead so that methods with Identity arguments are not ambiguous.

source
Manifolds.IsGroupManifold — Type
IsGroupManifold{O<:AbstractGroupOperation} <: AbstractTrait

A trait to declare an AbstractManifold as a manifold with group structure with operation of type O.

Using this trait you can turn a manifold that you implement implictly into a Lie group. If you wish to decorate an existing manifold with one (or different) AbstractGroupActions, see GroupManifold.

Constructor

IsGroupManifold(op)
source
Manifolds.LeftBackwardAction — Type
LeftBackwardAction()

Left action of a group on a manifold. For an action $α: X × G → X$ it is characterized by

\[α(α(x, h), g) = α(x, gh)\]

for all $g, h ∈ G$ and $x ∈ X$.

Note that a left action may still act from the right side in an expression.

source
Manifolds.LeftForwardAction — Type
LeftForwardAction()

Left action of a group on a manifold. For an action $α: G × X → X$ it is characterized by

\[α(g, α(h, x)) = α(gh, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

source
Manifolds.LeftRightSwitch — Type
struct LeftRightSwitch <: AbstractDirectionSwitchType end

Switch between left and right action, maintaining forward/backward direction.

source
Manifolds.RightBackwardAction — Type
RightBackwardAction()

Right action of a group on a manifold. For an action $α: X × G → X$ it is characterized by

\[α(α(x, h), g) = α(x, hg)\]

for all $g, h ∈ G$ and $x ∈ X$.

Note that a right action may still act from the left side in an expression.

source
Manifolds.RightForwardAction — Type
RightForwardAction()

Right action of a group on a manifold. For an action $α: G × X → X$ it is characterized by

\[α(g, α(h, x)) = α(hg, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

Note that a right action may still act from the left side in an expression.

source
Base.inv — Method
inv(G::AbstractDecoratorManifold, p)

Inverse $p^{-1} ∈ \mathcal{G}$ of an element $p ∈ \mathcal{G}$, such that $p \circ p^{-1} = p^{-1} \circ p = e ∈ \mathcal{G}$, where $e$ is the Identity element of $\mathcal{G}$.

source
Manifolds.adjoint_action — Method
adjoint_action(G::AbstractDecoratorManifold, p, X)

Adjoint action of the element p of the Lie group G on the element X of the corresponding Lie algebra.

It is defined as the differential of the group authomorphism $Ψ_p(q) = pqp⁻¹$ at the identity of G.

The formula reads

\[\operatorname{Ad}_p(X) = dΨ_p(e)[X]\]

where $e$ is the identity element of G.

Note that the adjoint representation of a Lie group isn't generally faithful. Notably the adjoint representation of SO(2) is trivial.

source
Manifolds.compose — Method
compose(G::AbstractDecoratorManifold, p, q)

Compose elements $p,q ∈ \mathcal{G}$ using the group operation $p \circ q$.

For implementing composition on a new group manifold, please overload _compose instead so that methods with Identity arguments are not ambiguous.

source
Manifolds.exp_lie — Method
exp_lie(G, X)
 exp_lie!(G, q, X)

Compute the group exponential of the Lie algebra element X. It is equivalent to the exponential map defined by the CartanSchoutenMinus connection.

Given an element $X ∈ 𝔤 = T_e \mathcal{G}$, where $e$ is the Identity element of the group $\mathcal{G}$, and $𝔤$ is its Lie algebra, the group exponential is the map

\[\exp : 𝔤 → \mathcal{G},\]

such that for $t,s ∈ ℝ$, $γ(t) = \exp (t X)$ defines a one-parameter subgroup with the following properties. Note that one-parameter subgroups are commutative (see [Suhubi2013], section 3.5), even if the Lie group itself is not commutative.

\[\begin{aligned} γ(t) &= γ(-t)^{-1}\\ γ(t + s) &= γ(t) \circ γ(s) = γ(s) \circ γ(t)\\ γ(0) &= e\\ \lim_{t → 0} \frac{d}{dt} γ(t) &= X. -\end{aligned}\]

Note

In general, the group exponential map is distinct from the Riemannian exponential map exp.

For example for the MultiplicationOperation and either Number or AbstractMatrix the Lie exponential is the numeric/matrix exponential.

\[\exp X = \operatorname{Exp} X = \sum_{n=0}^∞ \frac{1}{n!} X^n.\]

Since this function also depends on the group operation, make sure to implement the corresponding trait version exp_lie(::TraitList{<:IsGroupManifold}, G, X).

source
Manifolds.get_vector_lie — Method
get_vector_lie(G::AbstractDecoratorManifold, a, B::AbstractBasis)

Reconstruct a tangent vector from the Lie algebra of G from cooordinates a of a basis B. This is similar to calling get_vector at the p=Identity(G).

source
Manifolds.identity_element — Method
identity_element(G)

Return a point representation of the Identity on the IsGroupManifold G. By default this representation is the default array or number representation. It should return the corresponding default representation of $e$ as a point on G if points are not represented by arrays.

source
Manifolds.inverse_translate — Method
inverse_translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction())

Inverse translate group element $q$ by $p$ with the inverse translation $τ_p^{-1}$ with the specified convention, either left ($L_p^{-1}$) or right ($R_p^{-1}$), defined as

\[\begin{aligned} +\end{aligned}\]

Note

In general, the group exponential map is distinct from the Riemannian exponential map exp.

For example for the MultiplicationOperation and either Number or AbstractMatrix the Lie exponential is the numeric/matrix exponential.

\[\exp X = \operatorname{Exp} X = \sum_{n=0}^∞ \frac{1}{n!} X^n.\]

Since this function also depends on the group operation, make sure to implement the corresponding trait version exp_lie(::TraitList{<:IsGroupManifold}, G, X).

source
Manifolds.get_vector_lie — Method
get_vector_lie(G::AbstractDecoratorManifold, a, B::AbstractBasis)

Reconstruct a tangent vector from the Lie algebra of G from cooordinates a of a basis B. This is similar to calling get_vector at the p=Identity(G).

source
Manifolds.identity_element — Method
identity_element(G)

Return a point representation of the Identity on the IsGroupManifold G. By default this representation is the default array or number representation. It should return the corresponding default representation of $e$ as a point on G if points are not represented by arrays.

source
Manifolds.inverse_translate — Method
inverse_translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction())

Inverse translate group element $q$ by $p$ with the inverse translation $τ_p^{-1}$ with the specified convention, either left ($L_p^{-1}$) or right ($R_p^{-1}$), defined as

\[\begin{aligned} L_p^{-1} &: q ↦ p^{-1} \circ q\\ R_p^{-1} &: q ↦ q \circ p^{-1}. -\end{aligned}\]

source
Manifolds.inverse_translate_diff — Method
inverse_translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())

For group elements $p, q ∈ \mathcal{G}$ and tangent vector $X ∈ T_q \mathcal{G}$, compute the action on $X$ of the differential of the inverse translation $τ_p$ by $p$, with the specified left or right convention. The differential transports vectors:

\[(\mathrm{d}τ_p^{-1})_q : T_q \mathcal{G} → T_{τ_p^{-1} q} \mathcal{G}\\\]

source
Manifolds.lie_bracket — Method
lie_bracket(G::AbstractDecoratorManifold, X, Y)

Lie bracket between elements X and Y of the Lie algebra corresponding to the Lie group G, cf. IsGroupManifold.

This can be used to compute the adjoint representation of a Lie algebra. Note that this representation isn't generally faithful. Notably the adjoint representation of 𝔰𝔬(2) is trivial.

source
Manifolds.log_lie — Method
log_lie(G, q)
-log_lie!(G, X, q)

Compute the Lie group logarithm of the Lie group element q. It is equivalent to the logarithmic map defined by the CartanSchoutenMinus connection.

Given an element $q ∈ \mathcal{G}$, compute the right inverse of the group exponential map exp_lie, that is, the element $\log q = X ∈ 𝔤 = T_e \mathcal{G}$, such that $q = \exp X$

Note

In general, the group logarithm map is distinct from the Riemannian logarithm map log.

For matrix Lie groups this is equal to the (matrix) logarithm:

\[\log q = \operatorname{Log} q = \sum_{n=1}^∞ \frac{(-1)^{n+1}}{n} (q - e)^n,\]

where $e$ here is the Identity element, that is, $1$ for numeric $q$ or the identity matrix $I_m$ for matrix $q ∈ ℝ^{m × m}$.

Since this function also depends on the group operation, make sure to implement either

  • _log_lie(G, q) and _log_lie!(G, X, q) for the points not being the Identity
  • the trait version log_lie(::TraitList{<:IsGroupManifold}, G, e), log_lie(::TraitList{<:IsGroupManifold}, G, X, e) for own implementations of the identity case.
source
Manifolds.switch_direction — Method
switch_direction(::ActionDirection, type::AbstractDirectionSwitchType = SimultaneousSwitch())

Returns type of action between left and right, forward or backward, or both at the same type, depending on type, which is either of LeftRightSwitch, ForwardBackwardSwitch or SimultaneousSwitch.

source
Manifolds.translate — Method
translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction()])

Translate group element $q$ by $p$ with the translation $τ_p$ with the specified convention, either left forward ($L_p$), left backward ($R'_p$), right backward ($R_p$) or right forward ($L'_p$), defined as

\[\begin{aligned} +\end{aligned}\]

source
Manifolds.inverse_translate_diff — Method
inverse_translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())

For group elements $p, q ∈ \mathcal{G}$ and tangent vector $X ∈ T_q \mathcal{G}$, compute the action on $X$ of the differential of the inverse translation $τ_p$ by $p$, with the specified left or right convention. The differential transports vectors:

\[(\mathrm{d}τ_p^{-1})_q : T_q \mathcal{G} → T_{τ_p^{-1} q} \mathcal{G}\\\]

source
Manifolds.lie_bracket — Method
lie_bracket(G::AbstractDecoratorManifold, X, Y)

Lie bracket between elements X and Y of the Lie algebra corresponding to the Lie group G, cf. IsGroupManifold.

This can be used to compute the adjoint representation of a Lie algebra. Note that this representation isn't generally faithful. Notably the adjoint representation of 𝔰𝔬(2) is trivial.

source
Manifolds.log_lie — Method
log_lie(G, q)
+log_lie!(G, X, q)

Compute the Lie group logarithm of the Lie group element q. It is equivalent to the logarithmic map defined by the CartanSchoutenMinus connection.

Given an element $q ∈ \mathcal{G}$, compute the right inverse of the group exponential map exp_lie, that is, the element $\log q = X ∈ 𝔤 = T_e \mathcal{G}$, such that $q = \exp X$

Note

In general, the group logarithm map is distinct from the Riemannian logarithm map log.

For matrix Lie groups this is equal to the (matrix) logarithm:

\[\log q = \operatorname{Log} q = \sum_{n=1}^∞ \frac{(-1)^{n+1}}{n} (q - e)^n,\]

where $e$ here is the Identity element, that is, $1$ for numeric $q$ or the identity matrix $I_m$ for matrix $q ∈ ℝ^{m × m}$.

Since this function also depends on the group operation, make sure to implement either

  • _log_lie(G, q) and _log_lie!(G, X, q) for the points not being the Identity
  • the trait version log_lie(::TraitList{<:IsGroupManifold}, G, e), log_lie(::TraitList{<:IsGroupManifold}, G, X, e) for own implementations of the identity case.
source
Manifolds.switch_direction — Method
switch_direction(::ActionDirection, type::AbstractDirectionSwitchType = SimultaneousSwitch())

Returns type of action between left and right, forward or backward, or both at the same type, depending on type, which is either of LeftRightSwitch, ForwardBackwardSwitch or SimultaneousSwitch.

source
Manifolds.translate — Method
translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction()])

Translate group element $q$ by $p$ with the translation $τ_p$ with the specified convention, either left forward ($L_p$), left backward ($R'_p$), right backward ($R_p$) or right forward ($L'_p$), defined as

\[\begin{aligned} L_p &: q ↦ p \circ q\\ L'_p &: q ↦ p^{-1} \circ q\\ R_p &: q ↦ q \circ p\\ R'_p &: q ↦ q \circ p^{-1}. -\end{aligned}\]

source
Manifolds.translate_diff — Method
translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())

For group elements $p, q ∈ \mathcal{G}$ and tangent vector $X ∈ T_q \mathcal{G}$, compute the action of the differential of the translation $τ_p$ by $p$ on $X$, with the specified left or right convention. The differential transports vectors:

\[(\mathrm{d}τ_p)_q : T_q \mathcal{G} → T_{τ_p q} \mathcal{G}\\\]

source
ManifoldsBase.hat — Method
hat(M::AbstractDecoratorManifold{𝔽,O}, ::Identity{O}, Xⁱ) where {𝔽,O<:AbstractGroupOperation}

Given a basis $e_i$ on the tangent space at a the Identity and tangent component vector $X^i$, compute the equivalent vector representation ``X=X^i e_i**, where Einstein summation notation is used:

\[∧ : X^i ↦ X^i e_i\]

For array manifolds, this converts a vector representation of the tangent vector to an array representation. The vee map is the hat map's inverse.

source
Manifolds.translate_diff — Method
translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())

For group elements $p, q ∈ \mathcal{G}$ and tangent vector $X ∈ T_q \mathcal{G}$, compute the action of the differential of the translation $τ_p$ by $p$ on $X$, with the specified left or right convention. The differential transports vectors:

\[(\mathrm{d}τ_p)_q : T_q \mathcal{G} → T_{τ_p q} \mathcal{G}\\\]

source
ManifoldsBase.hat — Method
hat(M::AbstractDecoratorManifold{𝔽,O}, ::Identity{O}, Xⁱ) where {𝔽,O<:AbstractGroupOperation}

Given a basis $e_i$ on the tangent space at a the Identity and tangent component vector $X^i$, compute the equivalent vector representation ``X=X^i e_i**, where Einstein summation notation is used:

\[∧ : X^i ↦ X^i e_i\]

For array manifolds, this converts a vector representation of the tangent vector to an array representation. The vee map is the hat map's inverse.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(
     G::AbstractDecoratorManifold,
     p,
     X,
     method::GroupLogarithmicInverseRetraction{<:ActionDirection},
-)

Compute the inverse retraction using the group logarithm log_lie "translated" to any point on the manifold. With a group translation (translate) $τ_p$ in a specified direction, the retraction is

\[\operatorname{retr}_p^{-1} = (\mathrm{d}τ_p)_e \circ \log \circ τ_p^{-1},\]

where $\log$ is the group logarithm (log_lie), and $(\mathrm{d}τ_p)_e$ is the action of the differential of translation $τ_p$ evaluated at the identity element $e$ (see translate_diff).

source
ManifoldsBase.retract — Method
retract(
+)

Compute the inverse retraction using the group logarithm log_lie "translated" to any point on the manifold. With a group translation (translate) $τ_p$ in a specified direction, the retraction is

\[\operatorname{retr}_p^{-1} = (\mathrm{d}τ_p)_e \circ \log \circ τ_p^{-1},\]

where $\log$ is the group logarithm (log_lie), and $(\mathrm{d}τ_p)_e$ is the action of the differential of translation $τ_p$ evaluated at the identity element $e$ (see translate_diff).

source
ManifoldsBase.retract — Method
retract(
     G::AbstractDecoratorManifold,
     p,
     X,
     method::GroupExponentialRetraction{<:ActionDirection},
-)

Compute the retraction using the group exponential exp_lie "translated" to any point on the manifold. With a group translation (translate) $τ_p$ in a specified direction, the retraction is

\[\operatorname{retr}_p = τ_p \circ \exp \circ (\mathrm{d}τ_p^{-1})_p,\]

where $\exp$ is the group exponential (exp_lie), and $(\mathrm{d}τ_p^{-1})_p$ is the action of the differential of inverse translation $τ_p^{-1}$ evaluated at $p$ (see inverse_translate_diff).

source
ManifoldsBase.vee — Method
vee(M::AbstractManifold, p, X)

Given a basis $e_i$ on the tangent space at a point p and tangent vector X, compute the vector components $X^i$, such that $X = X^i e_i$, where Einstein summation notation is used:

\[\vee : X^i e_i ↦ X^i\]

For array manifolds, this converts an array representation of the tangent vector to a vector representation. The hat map is the vee map's inverse.

source

GroupManifold

As a concrete wrapper for manifolds (e.g. when the manifold per se is a group manifold but another group structure should be implemented), there is the GroupManifold

Manifolds.GroupManifold — Type
GroupManifold{𝔽,M<:AbstractManifold{𝔽},O<:AbstractGroupOperation} <: AbstractDecoratorManifold{𝔽}

Decorator for a smooth manifold that equips the manifold with a group operation, thus making it a Lie group. See IsGroupManifold for more details.

Group manifolds by default forward metric-related operations to the wrapped manifold.

Constructor

GroupManifold(manifold, op)
source

Generic Operations

For groups based on an addition operation or a group operation, several default implementations are provided.

Addition Operation

Multiplication Operation

Circle group

General linear group

Manifolds.GeneralLinear — Type
GeneralLinear{n,𝔽} <:
-    AbstractDecoratorManifold{𝔽}

The general linear group, that is, the group of all invertible matrices in $𝔽^{n×n}$.

The default metric is the left-$\mathrm{GL}(n)$-right-$\mathrm{O}(n)$-invariant metric whose inner product is

\[⟨X_p,Y_p⟩_p = ⟨p^{-1}X_p,p^{-1}Y_p⟩_\mathrm{F} = ⟨X_e, Y_e⟩_\mathrm{F},\]

where $X_p, Y_p ∈ T_p \mathrm{GL}(n, 𝔽)$, $X_e = p^{-1}X_p ∈ 𝔤𝔩(n) = T_e \mathrm{GL}(n, 𝔽) = 𝔽^{n×n}$ is the corresponding vector in the Lie algebra, and $⟨⋅,⋅⟩_\mathrm{F}$ denotes the Frobenius inner product.

By default, tangent vectors $X_p$ are represented with their corresponding Lie algebra vectors $X_e = p^{-1}X_p$.

source
Base.log — Method
log(G::GeneralLinear, p, q)

Compute the logarithmic map on the GeneralLinear(n) group.

The algorithm proceeds in two stages. First, the point $r = p^{-1} q$ is projected to the nearest element (under the Frobenius norm) of the direct product subgroup $\mathrm{O}(n) × S^+$, whose logarithmic map is exactly computed using the matrix logarithm. This initial tangent vector is then refined using the NLSolveInverseRetraction.

For GeneralLinear(n, ℂ), the logarithmic map is instead computed on the realified supergroup GeneralLinear(2n) and the resulting tangent vector is then complexified.

Note that this implementation is experimental.

source
Base.rand — Method
Random.rand(G::GeneralLinear; vector_at=nothing, kwargs...)

If vector_at is nothing, return a random point on the GeneralLinear group G by using rand in the embedding.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the GeneralLinear by using by using rand in the embedding.

source

Heisenberg group

Manifolds.HeisenbergGroup — Type
HeisenbergGroup{n} <: AbstractDecoratorManifold{ℝ}

Heisenberg group HeisenbergGroup(n) is the group of $(n+2) × (n+2)$ matrices [BinzPods2008]

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ +)

Compute the retraction using the group exponential exp_lie "translated" to any point on the manifold. With a group translation (translate) $τ_p$ in a specified direction, the retraction is

\[\operatorname{retr}_p = τ_p \circ \exp \circ (\mathrm{d}τ_p^{-1})_p,\]

where $\exp$ is the group exponential (exp_lie), and $(\mathrm{d}τ_p^{-1})_p$ is the action of the differential of inverse translation $τ_p^{-1}$ evaluated at $p$ (see inverse_translate_diff).

source
ManifoldsBase.vee — Method
vee(M::AbstractManifold, p, X)

Given a basis $e_i$ on the tangent space at a point p and tangent vector X, compute the vector components $X^i$, such that $X = X^i e_i$, where Einstein summation notation is used:

\[\vee : X^i e_i ↦ X^i\]

For array manifolds, this converts an array representation of the tangent vector to a vector representation. The hat map is the vee map's inverse.

source

GroupManifold

As a concrete wrapper for manifolds (e.g. when the manifold per se is a group manifold but another group structure should be implemented), there is the GroupManifold

Manifolds.GroupManifold — Type
GroupManifold{𝔽,M<:AbstractManifold{𝔽},O<:AbstractGroupOperation} <: AbstractDecoratorManifold{𝔽}

Decorator for a smooth manifold that equips the manifold with a group operation, thus making it a Lie group. See IsGroupManifold for more details.

Group manifolds by default forward metric-related operations to the wrapped manifold.

Constructor

GroupManifold(manifold, op)
source

Generic Operations

For groups based on an addition operation or a group operation, several default implementations are provided.

Addition Operation

Multiplication Operation

Circle group

General linear group

Manifolds.GeneralLinear — Type
GeneralLinear{n,𝔽} <:
+    AbstractDecoratorManifold{𝔽}

The general linear group, that is, the group of all invertible matrices in $𝔽^{n×n}$.

The default metric is the left-$\mathrm{GL}(n)$-right-$\mathrm{O}(n)$-invariant metric whose inner product is

\[⟨X_p,Y_p⟩_p = ⟨p^{-1}X_p,p^{-1}Y_p⟩_\mathrm{F} = ⟨X_e, Y_e⟩_\mathrm{F},\]

where $X_p, Y_p ∈ T_p \mathrm{GL}(n, 𝔽)$, $X_e = p^{-1}X_p ∈ 𝔤𝔩(n) = T_e \mathrm{GL}(n, 𝔽) = 𝔽^{n×n}$ is the corresponding vector in the Lie algebra, and $⟨⋅,⋅⟩_\mathrm{F}$ denotes the Frobenius inner product.

By default, tangent vectors $X_p$ are represented with their corresponding Lie algebra vectors $X_e = p^{-1}X_p$.

source
Base.log — Method
log(G::GeneralLinear, p, q)

Compute the logarithmic map on the GeneralLinear(n) group.

The algorithm proceeds in two stages. First, the point $r = p^{-1} q$ is projected to the nearest element (under the Frobenius norm) of the direct product subgroup $\mathrm{O}(n) × S^+$, whose logarithmic map is exactly computed using the matrix logarithm. This initial tangent vector is then refined using the NLSolveInverseRetraction.

For GeneralLinear(n, ℂ), the logarithmic map is instead computed on the realified supergroup GeneralLinear(2n) and the resulting tangent vector is then complexified.

Note that this implementation is experimental.

source
Base.rand — Method
Random.rand(G::GeneralLinear; vector_at=nothing, kwargs...)

If vector_at is nothing, return a random point on the GeneralLinear group G by using rand in the embedding.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the GeneralLinear by using by using rand in the embedding.

source

Heisenberg group

Manifolds.HeisenbergGroup — Type
HeisenbergGroup{n} <: AbstractDecoratorManifold{ℝ}

Heisenberg group HeisenbergGroup(n) is the group of $(n+2) × (n+2)$ matrices [BinzPods2008]

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ -0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ unit matrix, $\mathbf{a}$ is a row vector of length $n$, $\mathbf{b}$ is a column vector of length $n$ and $c$ is a real number. The group operation is matrix multiplication.

The left-invariant metric on the manifold is used.

source
Base.exp — Method
exp(M::HeisenbergGroup, p, X)

Exponential map on the HeisenbergGroup M with the left-invariant metric. The expression reads

\[\exp_{\begin{bmatrix} 1 & \mathbf{a}_p & c_p \\ +0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ unit matrix, $\mathbf{a}$ is a row vector of length $n$, $\mathbf{b}$ is a column vector of length $n$ and $c$ is a real number. The group operation is matrix multiplication.

The left-invariant metric on the manifold is used.

source
Base.exp — Method
exp(M::HeisenbergGroup, p, X)

Exponential map on the HeisenbergGroup M with the left-invariant metric. The expression reads

\[\exp_{\begin{bmatrix} 1 & \mathbf{a}_p & c_p \\ \mathbf{0} & I_n & \mathbf{b}_p \\ 0 & \mathbf{0} & 1 \end{bmatrix}}\left(\begin{bmatrix} 0 & \mathbf{a}_X & c_X \\ \mathbf{0} & 0_n & \mathbf{b}_X \\ 0 & \mathbf{0} & 0 \end{bmatrix}\right) = \begin{bmatrix} 1 & \mathbf{a}_p + \mathbf{a}_X & c_p + c_X + \mathbf{a}_X⋅\mathbf{b}_X/2 + \mathbf{a}_p⋅\mathbf{b}_X \\ \mathbf{0} & I_n & \mathbf{b}_p + \mathbf{b}_X \\ -0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
Base.log — Method
log(G::HeisenbergGroup, p, q)

Compute the logarithmic map on the HeisenbergGroup group. The formula reads

\[\log_{\begin{bmatrix} 1 & \mathbf{a}_p & c_p \\ +0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
Base.log — Method
log(G::HeisenbergGroup, p, q)

Compute the logarithmic map on the HeisenbergGroup group. The formula reads

\[\log_{\begin{bmatrix} 1 & \mathbf{a}_p & c_p \\ \mathbf{0} & I_n & \mathbf{b}_p \\ 0 & \mathbf{0} & 1 \end{bmatrix}}\left(\begin{bmatrix} 1 & \mathbf{a}_q & c_q \\ \mathbf{0} & I_n & \mathbf{b}_q \\ 0 & \mathbf{0} & 1 \end{bmatrix}\right) = \begin{bmatrix} 0 & \mathbf{a}_q - \mathbf{a}_p & c_q - c_p + \mathbf{a}_p⋅\mathbf{b}_p - \mathbf{a}_q⋅\mathbf{b}_q - (\mathbf{a}_q - \mathbf{a}_p)⋅(\mathbf{b}_q - \mathbf{b}_p) / 2 \\ \mathbf{0} & 0_n & \mathbf{b}_q - \mathbf{b}_p \\ -0 & \mathbf{0} & 0 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
Base.rand — Method
Random.rand(M::HeisenbergGroup; vector_at = nothing, σ::Real=1.0)

If vector_at is nothing, return a random point on the HeisenbergGroup M by sampling elements of the first row and the last column from the normal distribution with mean 0 and standard deviation σ.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the HeisenbergGroup by using a normal distribution with mean 0 and standard deviation σ.

source
Manifolds.exp_lie — Method
exp_lie(M::HeisenbergGroup, X)

Lie group exponential for the HeisenbergGroup M of the vector X. The formula reads

\[\exp\left(\begin{bmatrix} 0 & \mathbf{a} & c \\ +0 & \mathbf{0} & 0 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
Base.rand — Method
Random.rand(M::HeisenbergGroup; vector_at = nothing, σ::Real=1.0)

If vector_at is nothing, return a random point on the HeisenbergGroup M by sampling elements of the first row and the last column from the normal distribution with mean 0 and standard deviation σ.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the HeisenbergGroup by using a normal distribution with mean 0 and standard deviation σ.

source
Manifolds.exp_lie — Method
exp_lie(M::HeisenbergGroup, X)

Lie group exponential for the HeisenbergGroup M of the vector X. The formula reads

\[\exp\left(\begin{bmatrix} 0 & \mathbf{a} & c \\ \mathbf{0} & 0_n & \mathbf{b} \\ 0 & \mathbf{0} & 0 \end{bmatrix}\right) = \begin{bmatrix} 1 & \mathbf{a} & c + \mathbf{a}⋅\mathbf{b}/2 \\ \mathbf{0} & I_n & \mathbf{b} \\ -0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
Manifolds.log_lie — Method
log_lie(M::HeisenbergGroup, p)

Lie group logarithm for the HeisenbergGroup M of the point p. The formula reads

\[\log\left(\begin{bmatrix} 1 & \mathbf{a} & c \\ +0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
Manifolds.log_lie — Method
log_lie(M::HeisenbergGroup, p)

Lie group logarithm for the HeisenbergGroup M of the point p. The formula reads

\[\log\left(\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ 0 & \mathbf{0} & 1 \end{bmatrix}\right) = \begin{bmatrix} 0 & \mathbf{a} & c - \mathbf{a}⋅\mathbf{b}/2 \\ \mathbf{0} & 0_n & \mathbf{b} \\ -0 & \mathbf{0} & 0 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::HeisenbergGroup, p, X, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})

Get coordinates of tangent vector X at point p from the HeisenbergGroup M. Given a matrix

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ +0 & \mathbf{0} & 0 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::HeisenbergGroup, p, X, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})

Get coordinates of tangent vector X at point p from the HeisenbergGroup M. Given a matrix

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ -0 & \mathbf{0} & 1 \end{bmatrix}\]

the coordinates are concatenated vectors $\mathbf{a}$, $\mathbf{b}$, and number $c$.

source
ManifoldsBase.get_vector — Method
get_vector(M::HeisenbergGroup, p, Xⁱ, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})

Get tangent vector with coordinates Xⁱ at point p from the HeisenbergGroup M. Given a vector of coordinates $\begin{bmatrix}\mathbb{a} & \mathbb{b} & c\end{bmatrix}$ the tangent vector is equal to

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ +0 & \mathbf{0} & 1 \end{bmatrix}\]

the coordinates are concatenated vectors $\mathbf{a}$, $\mathbf{b}$, and number $c$.

source
ManifoldsBase.get_vector — Method
get_vector(M::HeisenbergGroup, p, Xⁱ, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})

Get tangent vector with coordinates Xⁱ at point p from the HeisenbergGroup M. Given a vector of coordinates $\begin{bmatrix}\mathbb{a} & \mathbb{b} & c\end{bmatrix}$ the tangent vector is equal to

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ -0 & \mathbf{0} & 1 \end{bmatrix}\]

source
ManifoldsBase.project — Method
project(M::HeisenbergGroup{n}, p, X)

Project a matrix X in the Euclidean embedding onto the Lie algebra of HeisenbergGroup M. Sets the diagonal elements to 0 and all non-diagonal elements except the first row and the last column to 0.

source
ManifoldsBase.project — Method
project(M::HeisenbergGroup{n}, p)

Project a matrix p in the Euclidean embedding onto the HeisenbergGroup M. Sets the diagonal elements to 1 and all non-diagonal elements except the first row and the last column to 0.

source

(Special) Orthogonal and (Special) Unitary group

Since the orthogonal, unitary and special orthogonal and special unitary groups share many common functions, these are also implemented on a common level.

Common functions

Manifolds.exp_lie — Method
 exp_lie(G::Orthogonal{2}, X)
- exp_lie(G::SpecialOrthogonal{2}, X)

Compute the Lie group exponential map on the Orthogonal(2) or SpecialOrthogonal(2) group. Given $X = \begin{pmatrix} 0 & -θ \\ θ & 0 \end{pmatrix}$, the group exponential is

\[\exp_e \colon X ↦ \begin{pmatrix} \cos θ & -\sin θ \\ \sin θ & \cos θ \end{pmatrix}.\]

source

Orthogonal group

Special orthogonal group

Manifolds.SpecialOrthogonal — Type
SpecialOrthogonal{n} <: GroupManifold{ℝ,Rotations{n},MultiplicationOperation}

Special orthogonal group $\mathrm{SO}(n)$ represented by rotation matrices, see Rotations.

Constructor

SpecialOrthogonal(n)
source

Special unitary group

Manifolds.SpecialUnitary — Type
SpecialUnitary{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}}

The special unitary group $\mathrm{SU}(n)$ represented by unitary matrices of determinant +1.

The tangent spaces are of the form

\[T_p\mathrm{SU}(x) = \bigl\{ X \in \mathbb C^{n×n} \big| X = pY \text{ where } Y = -Y^{\mathrm{H}} \bigr\}\]

and we represent tangent vectors by just storing the SkewHermitianMatrices $Y$, or in other words we represent the tangent spaces employing the Lie algebra $\mathfrak{su}(n)$.

Constructor

SpecialUnitary(n)

Generate the Lie group of $n×n$ unitary matrices with determinant +1.

source
ManifoldsBase.project — Method
project(G::SpecialUnitary, p)

Project p to the nearest point on the SpecialUnitary group G.

Given the singular value decomposition $p = U S V^\mathrm{H}$, with the singular values sorted in descending order, the projection is

\[\operatorname{proj}_{\mathrm{SU}(n)}(p) = -U\operatorname{diag}\left[1,1,…,\det(U V^\mathrm{H})\right] V^\mathrm{H}.\]

The diagonal matrix ensures that the determinant of the result is $+1$.

source

Unitary group

Manifolds.Unitary — Type
 Unitary{n,𝔽} = GeneralUnitaryMultiplicationGroup{n,𝔽,AbsoluteDeterminantOneMatrices}

The group of unitary matrices $\mathrm{U}(n, 𝔽)$, either complex (when 𝔽=ℂ) or quaternionic (when 𝔽=ℍ)

The group consists of all points $p ∈ 𝔽^{n × n}$ where $p^\mathrm{H}p = pp^\mathrm{H} = I$.

The tangent spaces are if the form

\[T_p\mathrm{U}(n) = \bigl\{ X \in 𝔽^{n×n} \big| X = pY \text{ where } Y = -Y^{\mathrm{H}} \bigr\}\]

and we represent tangent vectors by just storing the SkewHermitianMatrices $Y$, or in other words we represent the tangent spaces employing the Lie algebra $\mathfrak{u}(n, 𝔽)$.

Quaternionic unitary group is isomorphic to the compact symplectic group of the same dimension.

Constructor

Unitary(n, 𝔽::AbstractNumbers=ℂ)

Construct $\mathrm{U}(n, 𝔽)$. See also Orthogonal(n) for the real-valued case.

source
Manifolds.exp_lie — Method
exp_lie(G::Unitary{2,ℂ}, X)

Compute the group exponential map on the Unitary(2) group, which is

\[\exp_e \colon X ↦ e^{\operatorname{tr}(X) / 2} \left(\cos θ I + \frac{\sin θ}{θ} \left(X - \frac{\operatorname{tr}(X)}{2} I\right)\right),\]

where $θ = \frac{1}{2} \sqrt{4\det(X) - \operatorname{tr}(X)^2}$.

source

Power group

Manifolds.PowerGroup — Method
PowerGroup{𝔽,T} <: GroupManifold{𝔽,<:AbstractPowerManifold{𝔽,M,RPT},ProductOperation}

Decorate a power manifold with a ProductOperation.

Constituent manifold of the power manifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.

Constructor

PowerGroup(manifold::AbstractPowerManifold)
source

Product group

Manifolds.ProductGroup — Method
ProductGroup{𝔽,T} <: GroupManifold{𝔽,ProductManifold{T},ProductOperation}

Decorate a product manifold with a ProductOperation.

Each submanifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.

Constructor

ProductGroup(manifold::ProductManifold)
source

Semidirect product group

Manifolds.SemidirectProductGroup — Method
SemidirectProductGroup(N::GroupManifold, H::GroupManifold, A::AbstractGroupAction)

A group that is the semidirect product of a normal group $\mathcal{N}$ and a subgroup $\mathcal{H}$, written $\mathcal{G} = \mathcal{N} ⋊_θ \mathcal{H}$, where $θ: \mathcal{H} × \mathcal{N} → \mathcal{N}$ is an automorphism action of $\mathcal{H}$ on $\mathcal{N}$. The group $\mathcal{G}$ has the composition rule

\[g \circ g' = (n, h) \circ (n', h') = (n \circ θ_h(n'), h \circ h')\]

and the inverse

\[g^{-1} = (n, h)^{-1} = (θ_{h^{-1}}(n^{-1}), h^{-1}).\]

source
Manifolds.SemidirectProductOperation — Type
SemidirectProductOperation(action::AbstractGroupAction)

Group operation of a semidirect product group. The operation consists of the operation opN on a normal subgroup N, the operation opH on a subgroup H, and an automorphism action of elements of H on N. Only the action is stored.

source
Manifolds.translate_diff — Method
translate_diff(G::SemidirectProductGroup, p, q, X, conX::LeftForwardAction)

Perform differential of the left translation on the semidirect product group G.

Since the left translation is defined as (cf. SemidirectProductGroup):

\[L_{(n', h')} (n, h) = ( L_{n'} θ_{h'}(n), L_{h'} h)\]

then its differential can be computed as

\[\mathrm{d}L_{(n', h')}(X_n, X_h) = ( \mathrm{d}L_{n'} (\mathrm{d}θ_{h'}(X_n)), \mathrm{d}L_{h'} X_h).\]

source

Special Euclidean group

Manifolds.SpecialEuclidean — Type
SpecialEuclidean(n)

Special Euclidean group $\mathrm{SE}(n)$, the group of rigid motions.

$\mathrm{SE}(n)$ is the semidirect product of the TranslationGroup on $ℝ^n$ and SpecialOrthogonal(n)

\[\mathrm{SE}(n) ≐ \mathrm{T}(n) ⋊_θ \mathrm{SO}(n),\]

where $θ$ is the canonical action of $\mathrm{SO}(n)$ on $\mathrm{T}(n)$ by vector rotation.

This constructor is equivalent to calling

Tn = TranslationGroup(n)
+0 & \mathbf{0} & 1 \end{bmatrix}\]
source
ManifoldsBase.project — Method
project(M::HeisenbergGroup{n}, p, X)

Project a matrix X in the Euclidean embedding onto the Lie algebra of HeisenbergGroup M. Sets the diagonal elements to 0 and all non-diagonal elements except the first row and the last column to 0.

source
ManifoldsBase.project — Method
project(M::HeisenbergGroup{n}, p)

Project a matrix p in the Euclidean embedding onto the HeisenbergGroup M. Sets the diagonal elements to 1 and all non-diagonal elements except the first row and the last column to 0.

source

(Special) Orthogonal and (Special) Unitary group

Since the orthogonal, unitary and special orthogonal and special unitary groups share many common functions, these are also implemented on a common level.

Common functions

Manifolds.exp_lie — Method
 exp_lie(G::Orthogonal{2}, X)
+ exp_lie(G::SpecialOrthogonal{2}, X)

Compute the Lie group exponential map on the Orthogonal(2) or SpecialOrthogonal(2) group. Given $X = \begin{pmatrix} 0 & -θ \\ θ & 0 \end{pmatrix}$, the group exponential is

\[\exp_e \colon X ↦ \begin{pmatrix} \cos θ & -\sin θ \\ \sin θ & \cos θ \end{pmatrix}.\]

source

Orthogonal group

Special orthogonal group

Manifolds.SpecialOrthogonal — Type
SpecialOrthogonal{n} <: GroupManifold{ℝ,Rotations{n},MultiplicationOperation}

Special orthogonal group $\mathrm{SO}(n)$ represented by rotation matrices, see Rotations.

Constructor

SpecialOrthogonal(n)
source

Special unitary group

Manifolds.SpecialUnitary — Type
SpecialUnitary{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}}

The special unitary group $\mathrm{SU}(n)$ represented by unitary matrices of determinant +1.

The tangent spaces are of the form

\[T_p\mathrm{SU}(x) = \bigl\{ X \in \mathbb C^{n×n} \big| X = pY \text{ where } Y = -Y^{\mathrm{H}} \bigr\}\]

and we represent tangent vectors by just storing the SkewHermitianMatrices $Y$, or in other words we represent the tangent spaces employing the Lie algebra $\mathfrak{su}(n)$.

Constructor

SpecialUnitary(n)

Generate the Lie group of $n×n$ unitary matrices with determinant +1.

source
ManifoldsBase.project — Method
project(G::SpecialUnitary, p)

Project p to the nearest point on the SpecialUnitary group G.

Given the singular value decomposition $p = U S V^\mathrm{H}$, with the singular values sorted in descending order, the projection is

\[\operatorname{proj}_{\mathrm{SU}(n)}(p) = +U\operatorname{diag}\left[1,1,…,\det(U V^\mathrm{H})\right] V^\mathrm{H}.\]

The diagonal matrix ensures that the determinant of the result is $+1$.

source

Unitary group

Manifolds.Unitary — Type
 Unitary{n,𝔽} = GeneralUnitaryMultiplicationGroup{n,𝔽,AbsoluteDeterminantOneMatrices}

The group of unitary matrices $\mathrm{U}(n, 𝔽)$, either complex (when 𝔽=ℂ) or quaternionic (when 𝔽=ℍ)

The group consists of all points $p ∈ 𝔽^{n × n}$ where $p^\mathrm{H}p = pp^\mathrm{H} = I$.

The tangent spaces are if the form

\[T_p\mathrm{U}(n) = \bigl\{ X \in 𝔽^{n×n} \big| X = pY \text{ where } Y = -Y^{\mathrm{H}} \bigr\}\]

and we represent tangent vectors by just storing the SkewHermitianMatrices $Y$, or in other words we represent the tangent spaces employing the Lie algebra $\mathfrak{u}(n, 𝔽)$.

Quaternionic unitary group is isomorphic to the compact symplectic group of the same dimension.

Constructor

Unitary(n, 𝔽::AbstractNumbers=ℂ)

Construct $\mathrm{U}(n, 𝔽)$. See also Orthogonal(n) for the real-valued case.

source
Manifolds.exp_lie — Method
exp_lie(G::Unitary{2,ℂ}, X)

Compute the group exponential map on the Unitary(2) group, which is

\[\exp_e \colon X ↦ e^{\operatorname{tr}(X) / 2} \left(\cos θ I + \frac{\sin θ}{θ} \left(X - \frac{\operatorname{tr}(X)}{2} I\right)\right),\]

where $θ = \frac{1}{2} \sqrt{4\det(X) - \operatorname{tr}(X)^2}$.

source

Power group

Manifolds.PowerGroup — Method
PowerGroup{𝔽,T} <: GroupManifold{𝔽,<:AbstractPowerManifold{𝔽,M,RPT},ProductOperation}

Decorate a power manifold with a ProductOperation.

Constituent manifold of the power manifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.

Constructor

PowerGroup(manifold::AbstractPowerManifold)
source

Product group

Manifolds.ProductGroup — Method
ProductGroup{𝔽,T} <: GroupManifold{𝔽,ProductManifold{T},ProductOperation}

Decorate a product manifold with a ProductOperation.

Each submanifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.

Constructor

ProductGroup(manifold::ProductManifold)
source

Semidirect product group

Manifolds.SemidirectProductGroup — Method
SemidirectProductGroup(N::GroupManifold, H::GroupManifold, A::AbstractGroupAction)

A group that is the semidirect product of a normal group $\mathcal{N}$ and a subgroup $\mathcal{H}$, written $\mathcal{G} = \mathcal{N} ⋊_θ \mathcal{H}$, where $θ: \mathcal{H} × \mathcal{N} → \mathcal{N}$ is an automorphism action of $\mathcal{H}$ on $\mathcal{N}$. The group $\mathcal{G}$ has the composition rule

\[g \circ g' = (n, h) \circ (n', h') = (n \circ θ_h(n'), h \circ h')\]

and the inverse

\[g^{-1} = (n, h)^{-1} = (θ_{h^{-1}}(n^{-1}), h^{-1}).\]

source
Manifolds.SemidirectProductOperation — Type
SemidirectProductOperation(action::AbstractGroupAction)

Group operation of a semidirect product group. The operation consists of the operation opN on a normal subgroup N, the operation opH on a subgroup H, and an automorphism action of elements of H on N. Only the action is stored.

source
Manifolds.translate_diff — Method
translate_diff(G::SemidirectProductGroup, p, q, X, conX::LeftForwardAction)

Perform differential of the left translation on the semidirect product group G.

Since the left translation is defined as (cf. SemidirectProductGroup):

\[L_{(n', h')} (n, h) = ( L_{n'} θ_{h'}(n), L_{h'} h)\]

then its differential can be computed as

\[\mathrm{d}L_{(n', h')}(X_n, X_h) = ( \mathrm{d}L_{n'} (\mathrm{d}θ_{h'}(X_n)), \mathrm{d}L_{h'} X_h).\]

source

Special Euclidean group

Manifolds.SpecialEuclidean — Type
SpecialEuclidean(n)

Special Euclidean group $\mathrm{SE}(n)$, the group of rigid motions.

$\mathrm{SE}(n)$ is the semidirect product of the TranslationGroup on $ℝ^n$ and SpecialOrthogonal(n)

\[\mathrm{SE}(n) ≐ \mathrm{T}(n) ⋊_θ \mathrm{SO}(n),\]

where $θ$ is the canonical action of $\mathrm{SO}(n)$ on $\mathrm{T}(n)$ by vector rotation.

This constructor is equivalent to calling

Tn = TranslationGroup(n)
 SOn = SpecialOrthogonal(n)
-SemidirectProductGroup(Tn, SOn, RotationAction(Tn, SOn))

Points on $\mathrm{SE}(n)$ may be represented as points on the underlying product manifold $\mathrm{T}(n) × \mathrm{SO}(n)$. For group-specific functions, they may also be represented as affine matrices with size (n + 1, n + 1) (see affine_matrix), for which the group operation is MultiplicationOperation.

source
Manifolds.SpecialEuclideanInGeneralLinear — Type
SpecialEuclideanInGeneralLinear

An explicit isometric and homomorphic embedding of $\mathrm{SE}(n)$ in $\mathrm{GL}(n+1)$ and $𝔰𝔢(n)$ in $𝔤𝔩(n+1)$. Note that this is not a transparently isometric embedding.

Constructor

SpecialEuclideanInGeneralLinear(n)
source
Manifolds.adjoint_action — Method
adjoint_action(::SpecialEuclidean{3}, p, fX::TFVector{<:Any,VeeOrthogonalBasis{ℝ}})

Adjoint action of the SpecialEuclidean group on the vector with coefficients fX tangent at point p.

The formula for the coefficients reads $t×(R⋅ω) + R⋅r$ for the translation part and $R⋅ω$ for the rotation part, where t is the translation part of p, R is the rotation matrix part of p, r is the translation part of fX and ω is the rotation part of fX, $×$ is the cross product and $⋅$ is the matrix product.

source
Manifolds.affine_matrix — Method
affine_matrix(G::SpecialEuclidean, p) -> AbstractMatrix

Represent the point $p ∈ \mathrm{SE}(n)$ as an affine matrix. For $p = (t, R) ∈ \mathrm{SE}(n)$, where $t ∈ \mathrm{T}(n), R ∈ \mathrm{SO}(n)$, the affine representation is the $n + 1 × n + 1$ matrix

\[\begin{pmatrix} +SemidirectProductGroup(Tn, SOn, RotationAction(Tn, SOn))

Points on $\mathrm{SE}(n)$ may be represented as points on the underlying product manifold $\mathrm{T}(n) × \mathrm{SO}(n)$. For group-specific functions, they may also be represented as affine matrices with size (n + 1, n + 1) (see affine_matrix), for which the group operation is MultiplicationOperation.

source
Manifolds.SpecialEuclideanInGeneralLinear — Type
SpecialEuclideanInGeneralLinear

An explicit isometric and homomorphic embedding of $\mathrm{SE}(n)$ in $\mathrm{GL}(n+1)$ and $𝔰𝔢(n)$ in $𝔤𝔩(n+1)$. Note that this is not a transparently isometric embedding.

Constructor

SpecialEuclideanInGeneralLinear(n)
source
Manifolds.adjoint_action — Method
adjoint_action(::SpecialEuclidean{3}, p, fX::TFVector{<:Any,VeeOrthogonalBasis{ℝ}})

Adjoint action of the SpecialEuclidean group on the vector with coefficients fX tangent at point p.

The formula for the coefficients reads $t×(R⋅ω) + R⋅r$ for the translation part and $R⋅ω$ for the rotation part, where t is the translation part of p, R is the rotation matrix part of p, r is the translation part of fX and ω is the rotation part of fX, $×$ is the cross product and $⋅$ is the matrix product.

source
Manifolds.affine_matrix — Method
affine_matrix(G::SpecialEuclidean, p) -> AbstractMatrix

Represent the point $p ∈ \mathrm{SE}(n)$ as an affine matrix. For $p = (t, R) ∈ \mathrm{SE}(n)$, where $t ∈ \mathrm{T}(n), R ∈ \mathrm{SO}(n)$, the affine representation is the $n + 1 × n + 1$ matrix

\[\begin{pmatrix} R & t \\ 0^\mathrm{T} & 1 -\end{pmatrix}.\]

This function embeds $\mathrm{SE}(n)$ in the general linear group $\mathrm{GL}(n+1)$. It is an isometric embedding and group homomorphism [RicoMartinez1988].

See also screw_matrix for matrix representations of the Lie algebra.

source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{2}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(2)$, where $b ∈ 𝔱(2)$ and $Ω ∈ 𝔰𝔬(2)$:

\[\exp X = (t, R) = (U(θ) b, \exp Ω),\]

where $t ∈ \mathrm{T}(2)$, $R = \exp Ω$ is the group exponential on $\mathrm{SO}(2)$,

\[U(θ) = \frac{\sin θ}{θ} I_2 + \frac{1 - \cos θ}{θ^2} Ω,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{3}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(3)$, where $b ∈ 𝔱(3)$ and $Ω ∈ 𝔰𝔬(3)$:

\[\exp X = (t, R) = (U(θ) b, \exp Ω),\]

where $t ∈ \mathrm{T}(3)$, $R = \exp Ω$ is the group exponential on $\mathrm{SO}(3)$,

\[U(θ) = I_3 + \frac{1 - \cos θ}{θ^2} Ω + \frac{θ - \sin θ}{θ^3} Ω^2,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{n}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(n)$, where $b ∈ 𝔱(n)$ and $Ω ∈ 𝔰𝔬(n)$:

\[\exp X = (t, R),\]

where $t ∈ \mathrm{T}(n)$ and $R = \exp Ω$ is the group exponential on $\mathrm{SO}(n)$.

In the screw_matrix representation, the group exponential is the matrix exponential (see exp_lie).

source
Manifolds.lie_bracket — Method
lie_bracket(G::SpecialEuclidean, X::ProductRepr, Y::ProductRepr)
+\end{pmatrix}.\]
This function embeds $\mathrm{SE}(n)$ in the general linear group $\mathrm{GL}(n+1)$. It is an isometric embedding and group homomorphism [RicoMartinez1988].
See also screw_matrix for matrix representations of the Lie algebra.
source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{2}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(2)$, where $b ∈ 𝔱(2)$ and $Ω ∈ 𝔰𝔬(2)$:

\[\exp X = (t, R) = (U(θ) b, \exp Ω),\]

where $t ∈ \mathrm{T}(2)$, $R = \exp Ω$ is the group exponential on $\mathrm{SO}(2)$,

\[U(θ) = \frac{\sin θ}{θ} I_2 + \frac{1 - \cos θ}{θ^2} Ω,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{3}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(3)$, where $b ∈ 𝔱(3)$ and $Ω ∈ 𝔰𝔬(3)$:

\[\exp X = (t, R) = (U(θ) b, \exp Ω),\]

where $t ∈ \mathrm{T}(3)$, $R = \exp Ω$ is the group exponential on $\mathrm{SO}(3)$,

\[U(θ) = I_3 + \frac{1 - \cos θ}{θ^2} Ω + \frac{θ - \sin θ}{θ^3} Ω^2,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{n}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(n)$, where $b ∈ 𝔱(n)$ and $Ω ∈ 𝔰𝔬(n)$:

\[\exp X = (t, R),\]

where $t ∈ \mathrm{T}(n)$ and $R = \exp Ω$ is the group exponential on $\mathrm{SO}(n)$.

In the screw_matrix representation, the group exponential is the matrix exponential (see exp_lie).

source
Manifolds.lie_bracket — Method
lie_bracket(G::SpecialEuclidean, X::ProductRepr, Y::ProductRepr)
 lie_bracket(G::SpecialEuclidean, X::ArrayPartition, Y::ArrayPartition)
-lie_bracket(G::SpecialEuclidean, X::AbstractMatrix, Y::AbstractMatrix)

Calculate the Lie bracket between elements X and Y of the special Euclidean Lie algebra. For the matrix representation (which can be obtained using screw_matrix) the formula is $[X, Y] = XY-YX$, while in the ProductRepr representation the formula reads $[X, Y] = [(t_1, R_1), (t_2, R_2)] = (R_1 t_2 - R_2 t_1, R_1 R_2 - R_2 R_1)$.

source
Manifolds.log_lie — Method
log_lie(G::SpecialEuclidean{2}, p)

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(2)$, where $t ∈ \mathrm{T}(2)$ and $R ∈ \mathrm{SO}(2)$:

\[\log p = (b, Ω) = (U(θ)^{-1} t, \log R),\]

where $b ∈ 𝔱(2)$, $Ω = \log R ∈ 𝔰𝔬(2)$ is the group logarithm on $\mathrm{SO}(2)$,

\[U(θ) = \frac{\sin θ}{θ} I_2 + \frac{1 - \cos θ}{θ^2} Ω,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.log_lie — Method
log_lie(G::SpecialEuclidean{3}, p)

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(3)$, where $t ∈ \mathrm{T}(3)$ and $R ∈ \mathrm{SO}(3)$:

\[\log p = (b, Ω) = (U(θ)^{-1} t, \log R),\]

where $b ∈ 𝔱(3)$, $Ω = \log R ∈ 𝔰𝔬(3)$ is the group logarithm on $\mathrm{SO}(3)$,

\[U(θ) = I_3 + \frac{1 - \cos θ}{θ^2} Ω + \frac{θ - \sin θ}{θ^3} Ω^2,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.log_lie — Method
log_lie(G::SpecialEuclidean{n}, p) where {n}

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(n)$, where $t ∈ \mathrm{T}(n)$ and $R ∈ \mathrm{SO}(n)$:

\[\log p = (b, Ω),\]

where $b ∈ 𝔱(n)$ and $Ω = \log R ∈ 𝔰𝔬(n)$ is the group logarithm on $\mathrm{SO}(n)$.

In the affine_matrix representation, the group logarithm is the matrix logarithm (see log_lie):

source
Manifolds.screw_matrix — Method
screw_matrix(G::SpecialEuclidean, X) -> AbstractMatrix

Represent the Lie algebra element $X ∈ 𝔰𝔢(n) = T_e \mathrm{SE}(n)$ as a screw matrix. For $X = (b, Ω) ∈ 𝔰𝔢(n)$, where $Ω ∈ 𝔰𝔬(n) = T_e \mathrm{SO}(n)$, the screw representation is the $n + 1 × n + 1$ matrix

\[\begin{pmatrix} +lie_bracket(G::SpecialEuclidean, X::AbstractMatrix, Y::AbstractMatrix)

Calculate the Lie bracket between elements X and Y of the special Euclidean Lie algebra. For the matrix representation (which can be obtained using screw_matrix) the formula is $[X, Y] = XY-YX$, while in the ProductRepr representation the formula reads $[X, Y] = [(t_1, R_1), (t_2, R_2)] = (R_1 t_2 - R_2 t_1, R_1 R_2 - R_2 R_1)$.

source
Manifolds.log_lie — Method
log_lie(G::SpecialEuclidean{2}, p)

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(2)$, where $t ∈ \mathrm{T}(2)$ and $R ∈ \mathrm{SO}(2)$:

\[\log p = (b, Ω) = (U(θ)^{-1} t, \log R),\]

where $b ∈ 𝔱(2)$, $Ω = \log R ∈ 𝔰𝔬(2)$ is the group logarithm on $\mathrm{SO}(2)$,

\[U(θ) = \frac{\sin θ}{θ} I_2 + \frac{1 - \cos θ}{θ^2} Ω,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.log_lie — Method
log_lie(G::SpecialEuclidean{3}, p)

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(3)$, where $t ∈ \mathrm{T}(3)$ and $R ∈ \mathrm{SO}(3)$:

\[\log p = (b, Ω) = (U(θ)^{-1} t, \log R),\]

where $b ∈ 𝔱(3)$, $Ω = \log R ∈ 𝔰𝔬(3)$ is the group logarithm on $\mathrm{SO}(3)$,

\[U(θ) = I_3 + \frac{1 - \cos θ}{θ^2} Ω + \frac{θ - \sin θ}{θ^3} Ω^2,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

source
Manifolds.log_lie — Method
log_lie(G::SpecialEuclidean{n}, p) where {n}

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(n)$, where $t ∈ \mathrm{T}(n)$ and $R ∈ \mathrm{SO}(n)$:

\[\log p = (b, Ω),\]

where $b ∈ 𝔱(n)$ and $Ω = \log R ∈ 𝔰𝔬(n)$ is the group logarithm on $\mathrm{SO}(n)$.

In the affine_matrix representation, the group logarithm is the matrix logarithm (see log_lie):

source
Manifolds.screw_matrix — Method
screw_matrix(G::SpecialEuclidean, X) -> AbstractMatrix

Represent the Lie algebra element $X ∈ 𝔰𝔢(n) = T_e \mathrm{SE}(n)$ as a screw matrix. For $X = (b, Ω) ∈ 𝔰𝔢(n)$, where $Ω ∈ 𝔰𝔬(n) = T_e \mathrm{SO}(n)$, the screw representation is the $n + 1 × n + 1$ matrix

\[\begin{pmatrix} Ω & b \\ 0^\mathrm{T} & 0 -\end{pmatrix}.\]

This function embeds $𝔰𝔢(n)$ in the general linear Lie algebra $𝔤𝔩(n+1)$ but it's not a homomorphic embedding (see SpecialEuclideanInGeneralLinear for a homomorphic one).

See also affine_matrix for matrix representations of the Lie group.

source
Manifolds.translate_diff — Method
translate_diff(G::SpecialEuclidean, p, q, X, ::RightBackwardAction)

Differential of the right action of the SpecialEuclidean group on itself. The formula for the rotation part is the differential of the right rotation action, while the formula for the translation part reads

\[R_q⋅X_R⋅t_p + X_t\]

where $R_q$ is the rotation part of q, $X_R$ is the rotation part of X, $t_p$ is the translation part of p and $X_t$ is the translation part of X.

source
ManifoldsBase.embed — Method
embed(M::SpecialEuclideanInGeneralLinear, p, X)

Embed the tangent vector X at point p on SpecialEuclidean in the GeneralLinear group. Point p can use any representation valid for SpecialEuclidean. The embedding is similar from the one defined by screw_matrix but the translation part is multiplied by inverse of the rotation part.

source

Special linear group

Manifolds.SpecialLinear — Type
SpecialLinear{n,𝔽} <: AbstractDecoratorManifold

The special linear group $\mathrm{SL}(n,𝔽)$ that is, the group of all invertible matrices with unit determinant in $𝔽^{n×n}$.

The Lie algebra $𝔰𝔩(n, 𝔽) = T_e \mathrm{SL}(n,𝔽)$ is the set of all matrices in $𝔽^{n×n}$ with trace of zero. By default, tangent vectors $X_p ∈ T_p \mathrm{SL}(n,𝔽)$ for $p ∈ \mathrm{SL}(n,𝔽)$ are represented with their corresponding Lie algebra vector $X_e = p^{-1}X_p ∈ 𝔰𝔩(n, 𝔽)$.

The default metric is the same left-$\mathrm{GL}(n)$-right-$\mathrm{O}(n)$-invariant metric used for GeneralLinear(n, 𝔽). The resulting geodesic on $\mathrm{GL}(n,𝔽)$ emanating from an element of $\mathrm{SL}(n,𝔽)$ in the direction of an element of $𝔰𝔩(n, 𝔽)$ is a closed subgroup of $\mathrm{SL}(n,𝔽)$. As a result, most metric functions forward to GeneralLinear.

source
ManifoldsBase.project — Method
project(G::SpecialLinear, p, X)

Orthogonally project $X ∈ 𝔽^{n × n}$ onto the tangent space of $p$ to the SpecialLinear $G = \mathrm{SL}(n, 𝔽)$. The formula reads

\[\operatorname{proj}_{p} +\end{pmatrix}.\]

This function embeds $𝔰𝔢(n)$ in the general linear Lie algebra $𝔤𝔩(n+1)$ but it's not a homomorphic embedding (see SpecialEuclideanInGeneralLinear for a homomorphic one).

See also affine_matrix for matrix representations of the Lie group.

source
Manifolds.translate_diff — Method
translate_diff(G::SpecialEuclidean, p, q, X, ::RightBackwardAction)

Differential of the right action of the SpecialEuclidean group on itself. The formula for the rotation part is the differential of the right rotation action, while the formula for the translation part reads

\[R_q⋅X_R⋅t_p + X_t\]

where $R_q$ is the rotation part of q, $X_R$ is the rotation part of X, $t_p$ is the translation part of p and $X_t$ is the translation part of X.

source
ManifoldsBase.embed — Method
embed(M::SpecialEuclideanInGeneralLinear, p, X)

Embed the tangent vector X at point p on SpecialEuclidean in the GeneralLinear group. Point p can use any representation valid for SpecialEuclidean. The embedding is similar from the one defined by screw_matrix but the translation part is multiplied by inverse of the rotation part.

source

Special linear group

Manifolds.SpecialLinear — Type
SpecialLinear{n,𝔽} <: AbstractDecoratorManifold

The special linear group $\mathrm{SL}(n,𝔽)$ that is, the group of all invertible matrices with unit determinant in $𝔽^{n×n}$.

The Lie algebra $𝔰𝔩(n, 𝔽) = T_e \mathrm{SL}(n,𝔽)$ is the set of all matrices in $𝔽^{n×n}$ with trace of zero. By default, tangent vectors $X_p ∈ T_p \mathrm{SL}(n,𝔽)$ for $p ∈ \mathrm{SL}(n,𝔽)$ are represented with their corresponding Lie algebra vector $X_e = p^{-1}X_p ∈ 𝔰𝔩(n, 𝔽)$.

The default metric is the same left-$\mathrm{GL}(n)$-right-$\mathrm{O}(n)$-invariant metric used for GeneralLinear(n, 𝔽). The resulting geodesic on $\mathrm{GL}(n,𝔽)$ emanating from an element of $\mathrm{SL}(n,𝔽)$ in the direction of an element of $𝔰𝔩(n, 𝔽)$ is a closed subgroup of $\mathrm{SL}(n,𝔽)$. As a result, most metric functions forward to GeneralLinear.

source
ManifoldsBase.project — Method
project(G::SpecialLinear, p, X)

Orthogonally project $X ∈ 𝔽^{n × n}$ onto the tangent space of $p$ to the SpecialLinear $G = \mathrm{SL}(n, 𝔽)$. The formula reads

\[\operatorname{proj}_{p} = (\mathrm{d}L_p)_e ∘ \operatorname{proj}_{𝔰𝔩(n, 𝔽)} ∘ (\mathrm{d}L_p^{-1})_p - \colon X ↦ X - \frac{\operatorname{tr}(X)}{n} I,\]

where the last expression uses the tangent space representation as the Lie algebra.

source
ManifoldsBase.project — Method
project(G::SpecialLinear, p)

Project $p ∈ \mathrm{GL}(n, 𝔽)$ to the SpecialLinear group $G=\mathrm{SL}(n, 𝔽)$.

Given the singular value decomposition of $p$, written $p = U S V^\mathrm{H}$, the formula for the projection is

\[\operatorname{proj}_{\mathrm{SL}(n, 𝔽)}(p) = U S D V^\mathrm{H},\]

where

\[D_{ij} = δ_{ij} \begin{cases} + \colon X ↦ X - \frac{\operatorname{tr}(X)}{n} I,\]

where the last expression uses the tangent space representation as the Lie algebra.

source
ManifoldsBase.project — Method
project(G::SpecialLinear, p)

Project $p ∈ \mathrm{GL}(n, 𝔽)$ to the SpecialLinear group $G=\mathrm{SL}(n, 𝔽)$.

Given the singular value decomposition of $p$, written $p = U S V^\mathrm{H}$, the formula for the projection is

\[\operatorname{proj}_{\mathrm{SL}(n, 𝔽)}(p) = U S D V^\mathrm{H},\]

where

\[D_{ij} = δ_{ij} \begin{cases} 1 & \text{ if } i ≠ n \\ \det(p)^{-1} & \text{ if } i = n -\end{cases}.\]

source

Translation group

Manifolds.TranslationGroup — Type
TranslationGroup{T<:Tuple,𝔽} <: GroupManifold{Euclidean{T,𝔽},AdditionOperation}

Translation group $\mathrm{T}(n)$ represented by translation arrays.

Constructor

TranslationGroup(n₁,...,nᵢ; field = 𝔽)

Generate the translation group on $𝔽^{n₁,…,nᵢ}$ = Euclidean(n₁,...,nᵢ; field = 𝔽), which is isomorphic to the group itself.

source

Group actions

Group actions represent actions of a given group on a specified manifold. The following operations are available:

Furthermore, group operation action features the following:

The following group actions are available:

Manifolds.adjoint_apply_diff_group — Method
adjoint_apply_diff_group(A::AbstractGroupAction, a, X, p)

Pullback with respect to group element of group action A.

\[(\mathrm{d}τ^{p,*}) : T_{τ_{a} p} \mathcal M → T_{a} \mathcal G\]

source
Manifolds.apply! — Method
apply!(A::AbstractGroupAction, q, a, p)

Apply action a to the point p with the rule specified by A. The result is saved in q.

source
Manifolds.apply — Method
apply(A::AbstractGroupAction, a, p)

Apply action a to the point p using map $τ_a$, specified by A. Unless otherwise specified, the right action is defined in terms of the left action:

\[\mathrm{R}_a = \mathrm{L}_{a^{-1}}\]

source
Manifolds.apply_diff — Method
apply_diff(A::AbstractGroupAction, a, p, X)

For point $p ∈ \mathcal M$ and tangent vector $X ∈ T_p \mathcal M$, compute the action on $X$ of the differential of the action of $a ∈ \mathcal{G}$, specified by rule A. Written as $(\mathrm{d}τ_a)_p$, with the specified left or right convention, the differential transports vectors

\[(\mathrm{d}τ_a)_p : T_p \mathcal M → T_{τ_a p} \mathcal M\]

source
Manifolds.apply_diff_group — Method
apply_diff_group(A::AbstractGroupAction, a, X, p)

Compute the value of differential of action AbstractGroupAction A on vector X, where element a is acting on p, with respect to the group element.

Let $\mathcal G$ be the group acting on manifold $\mathcal M$ by the action A. The action is of element $g ∈ \mathcal G$ on a point $p ∈ \mathcal M$. The differential transforms vector X from the tangent space at a ∈ \mathcal G, $X ∈ T_a \mathcal G$ into a tangent space of the manifold $\mathcal M$. When action on element p is written as $\mathrm{d}τ^p$, with the specified left or right convention, the differential transforms vectors

\[(\mathrm{d}τ^p) : T_{a} \mathcal G → T_{τ_a p} \mathcal M\]

See also

apply, apply_diff

source

Translation group

Manifolds.TranslationGroup — Type
TranslationGroup{T<:Tuple,𝔽} <: GroupManifold{Euclidean{T,𝔽},AdditionOperation}

Translation group $\mathrm{T}(n)$ represented by translation arrays.

Constructor

TranslationGroup(n₁,...,nᵢ; field = 𝔽)

Generate the translation group on $𝔽^{n₁,…,nᵢ}$ = Euclidean(n₁,...,nᵢ; field = 𝔽), which is isomorphic to the group itself.

source

Group actions

Group actions represent actions of a given group on a specified manifold. The following operations are available:

Furthermore, group operation action features the following:

The following group actions are available:

Manifolds.adjoint_apply_diff_group — Method
adjoint_apply_diff_group(A::AbstractGroupAction, a, X, p)

Pullback with respect to group element of group action A.

\[(\mathrm{d}τ^{p,*}) : T_{τ_{a} p} \mathcal M → T_{a} \mathcal G\]

source
Manifolds.apply! — Method
apply!(A::AbstractGroupAction, q, a, p)

Apply action a to the point p with the rule specified by A. The result is saved in q.

source
Manifolds.apply — Method
apply(A::AbstractGroupAction, a, p)

Apply action a to the point p using map $τ_a$, specified by A. Unless otherwise specified, the right action is defined in terms of the left action:

\[\mathrm{R}_a = \mathrm{L}_{a^{-1}}\]

source
Manifolds.apply_diff — Method
apply_diff(A::AbstractGroupAction, a, p, X)

For point $p ∈ \mathcal M$ and tangent vector $X ∈ T_p \mathcal M$, compute the action on $X$ of the differential of the action of $a ∈ \mathcal{G}$, specified by rule A. Written as $(\mathrm{d}τ_a)_p$, with the specified left or right convention, the differential transports vectors

\[(\mathrm{d}τ_a)_p : T_p \mathcal M → T_{τ_a p} \mathcal M\]

source
Manifolds.apply_diff_group — Method
apply_diff_group(A::AbstractGroupAction, a, X, p)

Compute the value of differential of action AbstractGroupAction A on vector X, where element a is acting on p, with respect to the group element.

Let $\mathcal G$ be the group acting on manifold $\mathcal M$ by the action A. The action is of element $g ∈ \mathcal G$ on a point $p ∈ \mathcal M$. The differential transforms vector X from the tangent space at a ∈ \mathcal G, $X ∈ T_a \mathcal G$ into a tangent space of the manifold $\mathcal M$. When action on element p is written as $\mathrm{d}τ^p$, with the specified left or right convention, the differential transforms vectors

\[(\mathrm{d}τ^p) : T_{a} \mathcal G → T_{τ_a p} \mathcal M\]

See also

apply, apply_diff

source
Manifolds.center_of_orbit — Function
center_of_orbit(
     A::AbstractGroupAction,
     pts,
     p,
     mean_method::AbstractEstimationMethod = GradientDescentEstimation(),
-)

Calculate an action element $a$ of action A that is the mean element of the orbit of p with respect to given set of points pts. The mean is calculated using the method mean_method.

The orbit of $p$ with respect to the action of a group $\mathcal{G}$ is the set

\[O = \{ τ_a p : a ∈ \mathcal{G} \}.\]

This function is useful for computing means on quotients of manifolds by a Lie group action.

source
Manifolds.inverse_apply! — Method
inverse_apply!(A::AbstractGroupAction, q, a, p)

Apply inverse of action a to the point p with the rule specified by A. The result is saved in q.

source
Manifolds.inverse_apply — Method
inverse_apply(A::AbstractGroupAction, a, p)

Apply inverse of action a to the point p. The action is specified by A.

source
Manifolds.inverse_apply_diff — Method
inverse_apply_diff(A::AbstractGroupAction, a, p, X)

For group point $p ∈ \mathcal M$ and tangent vector $X ∈ T_p \mathcal M$, compute the action on $X$ of the differential of the inverse action of $a ∈ \mathcal{G}$, specified by rule A. Written as $(\mathrm{d}τ_a^{-1})_p$, with the specified left or right convention, the differential transports vectors

\[(\mathrm{d}τ_a^{-1})_p : T_p \mathcal M → T_{τ_a^{-1} p} \mathcal M\]

source
Manifolds.optimal_alignment! — Method
optimal_alignment!(A::AbstractGroupAction, x, p, q)

Calculate an action element of action A that acts upon p to produce the element closest to q. The result is written to x.

source
Manifolds.optimal_alignment — Method
optimal_alignment(A::AbstractGroupAction, p, q)

Calculate an action element $a$ of action A that acts upon p to produce the element closest to q in the metric of the G-manifold:

\[\arg\min_{a ∈ \mathcal{G}} d_{\mathcal M}(τ_a p, q)\]

where $\mathcal{G}$ is the group that acts on the G-manifold $\mathcal M$.

source

Group operation action

Manifolds.GroupOperationAction — Type
GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirection = LeftForwardAction())

Action of a group upon itself via left or right translation.

source

Rotation action

Manifolds.ColumnwiseMultiplicationAction — Type
ColumnwiseMultiplicationAction{
+)

Calculate an action element $a$ of action A that is the mean element of the orbit of p with respect to given set of points pts. The mean is calculated using the method mean_method.

The orbit of $p$ with respect to the action of a group $\mathcal{G}$ is the set

\[O = \{ τ_a p : a ∈ \mathcal{G} \}.\]

This function is useful for computing means on quotients of manifolds by a Lie group action.

source
Manifolds.inverse_apply! — Method
inverse_apply!(A::AbstractGroupAction, q, a, p)

Apply inverse of action a to the point p with the rule specified by A. The result is saved in q.

source
Manifolds.inverse_apply — Method
inverse_apply(A::AbstractGroupAction, a, p)

Apply inverse of action a to the point p. The action is specified by A.

source
Manifolds.inverse_apply_diff — Method
inverse_apply_diff(A::AbstractGroupAction, a, p, X)

For group point $p ∈ \mathcal M$ and tangent vector $X ∈ T_p \mathcal M$, compute the action on $X$ of the differential of the inverse action of $a ∈ \mathcal{G}$, specified by rule A. Written as $(\mathrm{d}τ_a^{-1})_p$, with the specified left or right convention, the differential transports vectors

\[(\mathrm{d}τ_a^{-1})_p : T_p \mathcal M → T_{τ_a^{-1} p} \mathcal M\]

source
Manifolds.optimal_alignment! — Method
optimal_alignment!(A::AbstractGroupAction, x, p, q)

Calculate an action element of action A that acts upon p to produce the element closest to q. The result is written to x.

source
Manifolds.optimal_alignment — Method
optimal_alignment(A::AbstractGroupAction, p, q)

Calculate an action element $a$ of action A that acts upon p to produce the element closest to q in the metric of the G-manifold:

\[\arg\min_{a ∈ \mathcal{G}} d_{\mathcal M}(τ_a p, q)\]

where $\mathcal{G}$ is the group that acts on the G-manifold $\mathcal M$.

source

Group operation action

Manifolds.GroupOperationAction — Type
GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirection = LeftForwardAction())

Action of a group upon itself via left or right translation.

source

Rotation action

Manifolds.ColumnwiseMultiplicationAction — Type
ColumnwiseMultiplicationAction{
     TM<:AbstractManifold,
     TO<:GeneralUnitaryMultiplicationGroup,
     TAD<:ActionDirection,
@@ -90,11 +90,11 @@
     M::AbstractManifold,
     On::GeneralUnitaryMultiplicationGroup,
     AD::ActionDirection = LeftForwardAction(),
-)
source
Manifolds.RotationAction — Type
RotationAction(
     M::AbstractManifold,
     SOn::SpecialOrthogonal,
     AD::ActionDirection = LeftForwardAction(),
-)

Space of actions of the SpecialOrthogonal group $\mathrm{SO}(n)$ on a Euclidean-like manifold M of dimension n.

source
Manifolds.RowwiseMultiplicationAction — Type
RowwiseMultiplicationAction{
     TM<:AbstractManifold,
     TO<:GeneralUnitaryMultiplicationGroup,
     TAD<:ActionDirection,
@@ -102,14 +102,14 @@
     M::AbstractManifold,
     On::GeneralUnitaryMultiplicationGroup,
     AD::ActionDirection = LeftForwardAction(),
-)
source
Manifolds.apply — Method
apply(A::RotationAroundAxisAction, θ, p)

Rotate point p from Euclidean(3) manifold around axis A.axis by angle θ. The formula reads

\[p_{rot} = (\cos(θ))p + (k×p) \sin(θ) + k (k⋅p) (1-\cos(θ)),\]

where $k$ is the vector A.axis and ⋅ is the dot product.

source
Manifolds.apply — Method
apply(A::RotationAroundAxisAction, θ, p)

Rotate point p from Euclidean(3) manifold around axis A.axis by angle θ. The formula reads

\[p_{rot} = (\cos(θ))p + (k×p) \sin(θ) + k (k⋅p) (1-\cos(θ)),\]

where $k$ is the vector A.axis and ⋅ is the dot product.

source
Manifolds.optimal_alignment — Method
optimal_alignment(A::LeftColumnwiseMultiplicationAction, p, q)

Compute optimal alignment for the left ColumnwiseMultiplicationAction, i.e. the group element $O^{*}$ that, when it acts on p, returns the point closest to q. Details of computation are described in Section 2.2.1 of [Srivastava2016].

The formula reads

\[O^{*} = \begin{cases} UV^T & \text{if } \operatorname{det}(p q^{\mathrm{T}})\\ U K V^{\mathrm{T}} & \text{otherwise} -\end{cases}\]

where $U \Sigma V^{\mathrm{T}}$ is the SVD decomposition of $p q^{\mathrm{T}}$ and $K$ is the unit diagonal matrix with the last element on the diagonal replaced with -1.

References

source

Translation action

Manifolds.TranslationAction — Type
TranslationAction(
+\end{cases}\]
where $U \Sigma V^{\mathrm{T}}$ is the SVD decomposition of $p q^{\mathrm{T}}$ and $K$ is the unit diagonal matrix with the last element on the diagonal replaced with -1.
References
source

Translation action

Manifolds.TranslationAction — Type
TranslationAction(
     M::AbstractManifold,
     Rn::TranslationGroup,
     AD::ActionDirection = LeftForwardAction(),
-)

Space of actions of the TranslationGroup $\mathrm{T}(n)$ on a Euclidean-like manifold M.

The left and right actions are equivalent.

source

Metrics on groups

Lie groups by default typically forward all metric-related operations like exponential or logarithmic map to the underlying manifold, for example SpecialOrthogonal uses methods for Rotations (which is, incidentally, bi-invariant), or SpecialEuclidean uses product metric of the translation and rotation parts (which is not invariant under group operation).

It is, however, possible to change the metric used by a group by wrapping it in a MetricManifold decorator.

Invariant metrics

Manifolds.direction — Method
direction(::AbstractDecoratorManifold) -> AD

Get the direction of the action a certain Lie group with its implicit metric has

source

Metrics on groups

Lie groups by default typically forward all metric-related operations like exponential or logarithmic map to the underlying manifold, for example SpecialOrthogonal uses methods for Rotations (which is, incidentally, bi-invariant), or SpecialEuclidean uses product metric of the translation and rotation parts (which is not invariant under group operation).

It is, however, possible to change the metric used by a group by wrapping it in a MetricManifold decorator.

Invariant metrics

Manifolds.direction — Method
direction(::AbstractDecoratorManifold) -> AD

Get the direction of the action a certain Lie group with its implicit metric has

source
Manifolds.has_approx_invariant_metric — Method
has_approx_invariant_metric(
     G::AbstractDecoratorManifold,
     p,
     X,
@@ -117,4 +117,4 @@
     qs::AbstractVector,
     conv::ActionDirection = LeftForwardAction();
     kwargs...,
-) -> Bool

Check whether the metric on the group $\mathcal{G}$ is (approximately) invariant using a set of predefined points. Namely, for $p ∈ \mathcal{G}$, $X,Y ∈ T_p \mathcal{G}$, a metric $g$, and a translation map $τ_q$ in the specified direction, check for each $q ∈ \mathcal{G}$ that the following condition holds:

\[g_p(X, Y) ≈ g_{τ_q p}((\mathrm{d}τ_q)_p X, (\mathrm{d}τ_q)_p Y).\]

This is necessary but not sufficient for invariance.

Optionally, kwargs passed to isapprox may be provided.

source

Cartan-Schouten connections

Manifolds.CartanSchoutenMinus — Type
CartanSchoutenMinus

The unique Cartan-Schouten connection such that all left-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.

source
Manifolds.CartanSchoutenPlus — Type
CartanSchoutenPlus

The unique Cartan-Schouten connection such that all right-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.

source
Manifolds.CartanSchoutenZero — Type
CartanSchoutenZero

The unique torsion-free Cartan-Schouten connection. It is biinvariant with respect to the group operation.

If the metric on the underlying manifold is bi-invariant then it is equivalent to the Levi-Civita connection of that metric.

source
Base.exp — Method
exp(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, X) where {𝔽}

Compute the exponential map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.

source
Base.log — Method
log(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, q) where {𝔽}

Compute the logarithmic map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.

source
  • Suhubi2013

    E. Suhubi, Exterior Analysis: Using Applications of Differential Forms, 1st edition. Amsterdam: Academic Press, 2013.

  • AndruchowLarotondaRechtVarela2014

    Andruchow E., Larotonda G., Recht L., and Varela A.: “The left invariant metric in the general linear group”, Journal of Geometry and Physics 86, pp. 241-257, 2014. doi: 10.1016/j.geomphys.2014.08.009, arXiv: 1109.0520v1.

  • MartinNeff2016

    Martin, R. J. and Neff, P.: “Minimal geodesics on GL(n) for left-invariant, right-O(n)-invariant Riemannian metrics”, Journal of Geometric Mechanics 8(3), pp. 323-357, 2016. doi: 10.3934/jgm.2016010, arXiv: 1409.7849v2.

  • BinzPods2008

    E. Binz and S. Pods, The Geometry of Heisenberg Groups: With Applications in Signal Theory, Optics, Quantization, and Field Quantization. American Mathematical Soc., 2008.

  • Gallier2002

    Gallier J.; Xu D.; Computing exponentials of skew-symmetric matrices and logarithms of orthogonal matrices. International Journal of Robotics and Automation (2002), 17(4), pp. 1-11. pdf.

  • Andrica2013

    Andrica D.; Rohan R.-A.; Computing the Rodrigues coefficients of the exponential map of the Lie groups of matrices. Balkan Journal of Geometry and Its Applications (2013), 18(2), pp. 1-2. pdf.

  • RicoMartinez1988

    Rico Martinez, J. M., “Representations of the Euclidean group and its applications to the kinematics of spatial chains,” PhD Thesis, University of Florida, 1988.

  • Srivastava2016

    A. Srivastava and E. P. Klassen, Functional and Shape Data Analysis. Springer New York, 2016. ISBN: 978-1-4939-4018-9. doi: 10.1007/978-1-4939-4020-2.

  • Pennec2020

    X. Pennec and M. Lorenzi, “5 - Beyond Riemannian geometry: The affine connection setting for transformation groups,” in Riemannian Geometric Statistics in Medical Image Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 169–229. doi: 10.1016/B978-0-12-814725-2.00012-1.

+) -> Bool

Check whether the metric on the group $\mathcal{G}$ is (approximately) invariant using a set of predefined points. Namely, for $p ∈ \mathcal{G}$, $X,Y ∈ T_p \mathcal{G}$, a metric $g$, and a translation map $τ_q$ in the specified direction, check for each $q ∈ \mathcal{G}$ that the following condition holds:

\[g_p(X, Y) ≈ g_{τ_q p}((\mathrm{d}τ_q)_p X, (\mathrm{d}τ_q)_p Y).\]

This is necessary but not sufficient for invariance.

Optionally, kwargs passed to isapprox may be provided.

source

Cartan-Schouten connections

Manifolds.AbstractCartanSchoutenConnection — Type
AbstractCartanSchoutenConnection

Abstract type for Cartan-Schouten connections, that is connections whose geodesics going through group identity are one-parameter subgroups. See[Pennec2020] for details.

source
Manifolds.CartanSchoutenMinus — Type
CartanSchoutenMinus

The unique Cartan-Schouten connection such that all left-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.

source
Manifolds.CartanSchoutenPlus — Type
CartanSchoutenPlus

The unique Cartan-Schouten connection such that all right-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.

source
Manifolds.CartanSchoutenZero — Type
CartanSchoutenZero

The unique torsion-free Cartan-Schouten connection. It is biinvariant with respect to the group operation.

If the metric on the underlying manifold is bi-invariant then it is equivalent to the Levi-Civita connection of that metric.

source
Base.exp — Method
exp(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, X) where {𝔽}

Compute the exponential map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.

source
Base.log — Method
log(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, q) where {𝔽}

Compute the logarithmic map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.

source
ManifoldsBase.parallel_transport_direction — Method
parallel_transport_direction(M::CartanSchoutenZeroGroup, ::Identity, X, d)

Transport tangent vector X at identity on the group manifold with the CartanSchoutenZero connection in the direction d. See [Pennec2020] for details.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::CartanSchoutenMinusGroup, p, X, q)

Transport tangent vector X at point p on the group manifold M with the CartanSchoutenMinus connection to point q. See [Pennec2020] for details.

source
ManifoldsBase.parallel_transport_to — Method
vector_transport_to(M::CartanSchoutenPlusGroup, p, X, q)

Transport tangent vector X at point p on the group manifold M with the CartanSchoutenPlus connection to point q. See [Pennec2020] for details.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::CartanSchoutenZeroGroup, p::Identity, X, q)

Transport vector X at identity of group M equipped with the CartanSchoutenZero connection to point q using parallel transport.

source
diff --git a/previews/PR628/manifolds/hyperbolic.html b/previews/PR628/manifolds/hyperbolic.html index 39782389dc..c1d9ebccdc 100644 --- a/previews/PR628/manifolds/hyperbolic.html +++ b/previews/PR628/manifolds/hyperbolic.html @@ -2,6299 +2,6299 @@ Hyperbolic space · Manifolds.jl
Edit on GitHub

Hyperbolic space

The hyperbolic space can be represented in three different models.

In the following the common functions are collected.

A function in this general section uses vectors interpreted as if in the hyperboloid model, and other representations usually just convert to this representation to use these general functions.

Manifolds.Hyperbolic — Type
Hyperbolic{N} <: AbstractDecoratorManifold{ℝ}

The hyperbolic space $\mathcal H^n$ represented by $n+1$-Tuples, i.e. embedded in the Lorentzian manifold equipped with the MinkowskiMetric $⟨\cdot,\cdot⟩_{\mathrm{M}}$. The space is defined as

\[\mathcal H^n = \Bigl\{p ∈ ℝ^{n+1}\ \Big|\ ⟨p,p⟩_{\mathrm{M}}= -p_{n+1}^2 + \displaystyle\sum_{k=1}^n p_k^2 = -1, p_{n+1} > 0\Bigr\},.\]

The tangent space $T_p \mathcal H^n$ is given by

\[T_p \mathcal H^n := \bigl\{ X ∈ ℝ^{n+1} : ⟨p,X⟩_{\mathrm{M}} = 0 -\bigr\}.\]

Note that while the MinkowskiMetric renders the Lorentz manifold (only) pseudo-Riemannian, on the tangent bundle of the Hyperbolic space it induces a Riemannian metric. The corresponding sectional curvature is $-1$.

If p and X are Vectors of length n+1 they are assumed to be a HyperboloidPoint and a HyperboloidTVector, respectively

Other models are the Poincaré ball model, see PoincareBallPoint and PoincareBallTVector, respectiely and the Poincaré half space model, see PoincareHalfSpacePoint and PoincareHalfSpaceTVector, respectively.

Constructor

Hyperbolic(n)

Generate the Hyperbolic manifold of dimension n.

source
Manifolds.HyperboloidPoint — Type
HyperboloidPoint <: AbstractManifoldPoint

In the Hyperboloid model of the Hyperbolic $\mathcal H^n$ points are represented as vectors in $ℝ^{n+1}$ with MinkowskiMetric equal to $-1$.

This representation is the default, i.e. AbstractVectors are assumed to have this repesentation.

source
Manifolds.HyperboloidTVector — Type
HyperboloidTVector <: TVector

In the Hyperboloid model of the Hyperbolic $\mathcal H^n$ tangent vctors are represented as vectors in $ℝ^{n+1}$ with MinkowskiMetric $⟨p,X⟩_{\mathrm{M}}=0$ to their base point $p$.

This representation is the default, i.e. vectors are assumed to have this repesentation.

source
Base.exp — Method
exp(M::Hyperbolic, p, X)

Compute the exponential map on the Hyperbolic space $\mathcal H^n$ emanating from p towards X. The formula reads

\[\exp_p X = \cosh(\sqrt{⟨X,X⟩_{\mathrm{M}}})p -+ \sinh(\sqrt{⟨X,X⟩_{\mathrm{M}}})\frac{X}{\sqrt{⟨X,X⟩_{\mathrm{M}}}},\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

source
Base.log — Method
log(M::Hyperbolic, p, q)

Compute the logarithmic map on the Hyperbolic space $\mathcal H^n$, the tangent vector representing the geodesic starting from p reaches q after time 1. The formula reads for $p ≠ q$

\[\log_p q = d_{\mathcal H^n}(p,q) -\frac{q-⟨p,q⟩_{\mathrm{M}} p}{\lVert q-⟨p,q⟩_{\mathrm{M}} p \rVert_2},\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold. For $p=q$ the logarihmic map is equal to the zero vector.

source
Manifolds.manifold_volume — Method
manifold_dimension(M::Hyperbolic)

Return the volume of the hyperbolic space manifold $\mathcal H^n$, i.e. infinity.

source
ManifoldsBase.check_point — Method
check_point(M::Hyperbolic, p; kwargs...)

Check whether p is a valid point on the Hyperbolic M.

For the HyperboloidPoint or plain vectors this means that, p is a vector of length $n+1$ with inner product in the embedding of -1, see MinkowskiMetric. The tolerance for the last test can be set using the kwargs....

For the PoincareBallPoint a valid point is a vector $p ∈ ℝ^n$ with a norm stricly less than 1.

For the PoincareHalfSpacePoint a valid point is a vector from $p ∈ ℝ^n$ with a positive last entry, i.e. $p_n>0$

source
ManifoldsBase.check_vector — Method
check_vector(M::Hyperbolic{n}, p, X; kwargs... )

Check whether X is a tangent vector to p on the Hyperbolic M, i.e. after check_point(M,p), X has to be of the same dimension as p. The tolerance for the last test can be set using the kwargs....

For a the hyperboloid model or vectors, X has to be orthogonal to p with respect to the inner product from the embedding, see MinkowskiMetric.

For a the Poincaré ball as well as the Poincaré half plane model, X has to be a vector from $ℝ^{n}$.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::Hyperbolic, p, X, q)

Compute the paralllel transport of the X from the tangent space at p on the Hyperbolic space $\mathcal H^n$ to the tangent at q along the geodesic connecting p and q. The formula reads

\[\mathcal P_{q←p}X = X - \frac{⟨\log_p q,X⟩_p}{d^2_{\mathcal H^n}(p,q)} -\bigl(\log_p q + \log_qp \bigr),\]

where $⟨\cdot,\cdot⟩_p$ denotes the inner product in the tangent space at p.

source
ManifoldsBase.project — Method
project(M::Hyperbolic, p, X)

Perform an orthogonal projection with respect to the Minkowski inner product of X onto the tangent space at p of the Hyperbolic space M.

The formula reads

\[Y = X + ⟨p,X⟩_{\mathrm{M}} p,\]

where $⟨\cdot, \cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

Note

Projection is only available for the (default) HyperboloidTVector representation, the others don't have such an embedding

source
Statistics.mean — Method
mean(
+\bigr\}.\]
Note that while the MinkowskiMetric renders the Lorentz manifold (only) pseudo-Riemannian, on the tangent bundle of the Hyperbolic space it induces a Riemannian metric. The corresponding sectional curvature is $-1$.
If p and X are Vectors of length n+1 they are assumed to be a HyperboloidPoint and a HyperboloidTVector, respectively
Other models are the Poincaré ball model, see PoincareBallPoint and PoincareBallTVector, respectiely and the Poincaré half space model, see PoincareHalfSpacePoint and PoincareHalfSpaceTVector, respectively.
Constructor
Hyperbolic(n)
Generate the Hyperbolic manifold of dimension n.
source
Manifolds.HyperboloidPoint — Type
HyperboloidPoint <: AbstractManifoldPoint

In the Hyperboloid model of the Hyperbolic $\mathcal H^n$ points are represented as vectors in $ℝ^{n+1}$ with MinkowskiMetric equal to $-1$.

This representation is the default, i.e. AbstractVectors are assumed to have this repesentation.

source
Manifolds.HyperboloidTVector — Type
HyperboloidTVector <: TVector

In the Hyperboloid model of the Hyperbolic $\mathcal H^n$ tangent vctors are represented as vectors in $ℝ^{n+1}$ with MinkowskiMetric $⟨p,X⟩_{\mathrm{M}}=0$ to their base point $p$.

This representation is the default, i.e. vectors are assumed to have this repesentation.

source
Base.exp — Method
exp(M::Hyperbolic, p, X)

Compute the exponential map on the Hyperbolic space $\mathcal H^n$ emanating from p towards X. The formula reads

\[\exp_p X = \cosh(\sqrt{⟨X,X⟩_{\mathrm{M}}})p ++ \sinh(\sqrt{⟨X,X⟩_{\mathrm{M}}})\frac{X}{\sqrt{⟨X,X⟩_{\mathrm{M}}}},\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

source
Base.log — Method
log(M::Hyperbolic, p, q)

Compute the logarithmic map on the Hyperbolic space $\mathcal H^n$, the tangent vector representing the geodesic starting from p reaches q after time 1. The formula reads for $p ≠ q$

\[\log_p q = d_{\mathcal H^n}(p,q) +\frac{q-⟨p,q⟩_{\mathrm{M}} p}{\lVert q-⟨p,q⟩_{\mathrm{M}} p \rVert_2},\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold. For $p=q$ the logarihmic map is equal to the zero vector.

source
Manifolds.manifold_volume — Method
manifold_dimension(M::Hyperbolic)

Return the volume of the hyperbolic space manifold $\mathcal H^n$, i.e. infinity.

source
ManifoldsBase.check_point — Method
check_point(M::Hyperbolic, p; kwargs...)

Check whether p is a valid point on the Hyperbolic M.

For the HyperboloidPoint or plain vectors this means that, p is a vector of length $n+1$ with inner product in the embedding of -1, see MinkowskiMetric. The tolerance for the last test can be set using the kwargs....

For the PoincareBallPoint a valid point is a vector $p ∈ ℝ^n$ with a norm stricly less than 1.

For the PoincareHalfSpacePoint a valid point is a vector from $p ∈ ℝ^n$ with a positive last entry, i.e. $p_n>0$

source
ManifoldsBase.check_vector — Method
check_vector(M::Hyperbolic{n}, p, X; kwargs... )

Check whether X is a tangent vector to p on the Hyperbolic M, i.e. after check_point(M,p), X has to be of the same dimension as p. The tolerance for the last test can be set using the kwargs....

For a the hyperboloid model or vectors, X has to be orthogonal to p with respect to the inner product from the embedding, see MinkowskiMetric.

For a the Poincaré ball as well as the Poincaré half plane model, X has to be a vector from $ℝ^{n}$.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::Hyperbolic, p, X, q)

Compute the paralllel transport of the X from the tangent space at p on the Hyperbolic space $\mathcal H^n$ to the tangent at q along the geodesic connecting p and q. The formula reads

\[\mathcal P_{q←p}X = X - \frac{⟨\log_p q,X⟩_p}{d^2_{\mathcal H^n}(p,q)} +\bigl(\log_p q + \log_qp \bigr),\]

where $⟨\cdot,\cdot⟩_p$ denotes the inner product in the tangent space at p.

source
ManifoldsBase.project — Method
project(M::Hyperbolic, p, X)

Perform an orthogonal projection with respect to the Minkowski inner product of X onto the tangent space at p of the Hyperbolic space M.

The formula reads

\[Y = X + ⟨p,X⟩_{\mathrm{M}} p,\]

where $⟨\cdot, \cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

Note

Projection is only available for the (default) HyperboloidTVector representation, the others don't have such an embedding

source

hyperboloid model

hyperboloid model

Base.convert — Method
convert(::Type{HyperboloidPoint}, p::PoincareBallPoint)
 convert(::Type{AbstractVector}, p::PoincareBallPoint)

convert a point PoincareBallPoint x (from $ℝ^n$) from the Poincaré ball model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidPoint $π(p) ∈ ℝ^{n+1}$. The isometry is defined by

\[π(p) = \frac{1}{1-\lVert p \rVert^2} -\begin{pmatrix}2p_1\\⋮\\2p_n\\1+\lVert p \rVert^2\end{pmatrix}\]

Note that this is also used, when the type to convert to is a vector.

source
Base.convert — Method
convert(::Type{HyperboloidPoint}, p::PoincareHalfSpacePoint)
-convert(::Type{AbstractVector}, p::PoincareHalfSpacePoint)

convert a point PoincareHalfSpacePoint p (from $ℝ^n$) from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidPoint $π(p) ∈ ℝ^{n+1}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.

source
Base.convert — Method
convert(::Type{HyperboloidTVector}, p::PoincareBallPoint, X::PoincareBallTVector)
+\begin{pmatrix}2p_1\\⋮\\2p_n\\1+\lVert p \rVert^2\end{pmatrix}\]
Note that this is also used, when the type to convert to is a vector.
source
Base.convert — Method
convert(::Type{HyperboloidPoint}, p::PoincareHalfSpacePoint)
+convert(::Type{AbstractVector}, p::PoincareHalfSpacePoint)

convert a point PoincareHalfSpacePoint p (from $ℝ^n$) from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidPoint $π(p) ∈ ℝ^{n+1}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.

source
Base.convert — Method
convert(::Type{HyperboloidTVector}, p::PoincareBallPoint, X::PoincareBallTVector)
 convert(::Type{AbstractVector}, p::PoincareBallPoint, X::PoincareBallTVector)

Convert the PoincareBallTVector X from the tangent space at p to a HyperboloidTVector by computing the push forward of the isometric map, cf. convert(::Type{HyperboloidPoint}, p::PoincareBallPoint).

The push forward $π_*(p)$ maps from $ℝ^n$ to a subspace of $ℝ^{n+1}$, the formula reads

\[π_*(p)[X] = \begin{pmatrix} \frac{2X_1}{1-\lVert p \rVert^2} + \frac{4}{(1-\lVert p \rVert^2)^2}⟨X,p⟩p_1\\ ⋮\\ \frac{2X_n}{1-\lVert p \rVert^2} + \frac{4}{(1-\lVert p \rVert^2)^2}⟨X,p⟩p_n\\ \frac{4}{(1-\lVert p \rVert^2)^2}⟨X,p⟩ -\end{pmatrix}.\]

source
Base.convert — Method
convert(::Type{HyperboloidTVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)
-convert(::Type{AbstractVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)

convert a point PoincareHalfSpaceTVector X (from $ℝ^n$) at p from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidTVector $π(p) ∈ ℝ^{n+1}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.

source
Base.convert — Method
convert(::Type{HyperboloidTVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)
+convert(::Type{AbstractVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)

convert a point PoincareHalfSpaceTVector X (from $ℝ^n$) at p from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a HyperboloidTVector $π(p) ∈ ℝ^{n+1}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.

source
Base.convert — Method
convert(
     ::Type{Tuple{HyperboloidPoint,HyperboloidTVector}}.
     (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}
 )
 convert(
     ::Type{Tuple{P,T}},
     (p, X)::Tuple{PoincareBallPoint,PoincareBallTVector},
-) where {P<:AbstractVector, T <: AbstractVector}

Convert a PoincareBallPoint p and a PoincareBallTVector X to a HyperboloidPoint and a HyperboloidTVector simultaneously, see convert(::Type{HyperboloidPoint}, ::PoincareBallPoint) and convert(::Type{HyperboloidTVector}, ::PoincareBallPoint, ::PoincareBallTVector) for the formulae.

source
Base.convert — Method
convert(
     ::Type{Tuple{HyperboloidPoint,HyperboloidTVector},
     (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}
 )
 convert(
     ::Type{Tuple{T,T},
     (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}
-) where {T<:AbstractVector}

convert a point PoincareHalfSpaceTVector X (from $ℝ^n$) at p from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a tuple of a HyperboloidPoint and a HyperboloidTVector $π(p) ∈ ℝ^{n+1}$ simultaneously.

This is done in two steps, namely transforming it to the Poincare ball model and from there further on to a Hyperboloid.

source
Manifolds.volume_density — Method
volume_density(M::Hyperbolic, p, X)

Compute volume density function of the hyperbolic manifold. The formula reads $(\sinh(\lVert X\rVert)/\lVert X\rVert)^(n-1)$ where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].

source
ManifoldsBase.change_representer — Method
change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p, X)

Change the Eucliden representer X of a cotangent vector at point p. We only have to correct for the metric, which means that the sign of the last entry changes, since for the result $Y$ we are looking for a tangent vector such that

\[ g_p(Y,Z) = -y_{n+1}z_{n+1} + \sum_{i=1}^n y_iz_i = \sum_{i=1}^{n+1} z_ix_i\]

holds, which directly yields $y_i=x_i$ for $i=1,\ldots,n$ and $y_{n+1}=-x_{n+1}$.

source
ManifoldsBase.distance — Method
distance(M::Hyperbolic, p, q)
-distance(M::Hyperbolic, p::HyperboloidPoint, q::HyperboloidPoint)

Compute the distance on the Hyperbolic M, which reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}( - ⟨p, q⟩_{\mathrm{M}}),\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::Hyperbolic, p, X, ::DefaultOrthonormalBasis)

Compute the coordinates of the vector X with respect to the orthogonalized version of the unit vectors from $ℝ^n$, where $n$ is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.

source
ManifoldsBase.get_vector — Method
get_vector(M::Hyperbolic, p, c, ::DefaultOrthonormalBasis)

Compute the vector from the coordinates with respect to the orthogonalized version of the unit vectors from $ℝ^n$, where $n$ is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.

source
ManifoldsBase.inner — Method
inner(M::Hyperbolic{n}, p, X, Y)
-inner(M::Hyperbolic{n}, p::HyperboloidPoint, X::HyperboloidTVector, Y::HyperboloidTVector)

Cmpute the inner product in the Hyperboloid model, i.e. the minkowski_metric in the embedding. The formula reads

\[g_p(X,Y) = ⟨X,Y⟩_{\mathrm{M}} = -X_{n}Y_{n} + \displaystyle\sum_{k=1}^{n-1} X_kY_k.\]

This employs the metric of the embedding, see Lorentz space.

source

Visualization of the Hyperboloid

For the case of Hyperbolic(2) there is plotting available based on a PlottingRecipe. You can easily plot points, connecting geodesics as well as tangent vectors.

Note

The recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.

If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation for the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path.

In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of wires and a wireframe_color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_x or surface_resolution_y) and a surface_color.

using Manifolds, Plots
+) where {T<:AbstractVector}

convert a point PoincareHalfSpaceTVector X (from $ℝ^n$) at p from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a tuple of a HyperboloidPoint and a HyperboloidTVector $π(p) ∈ ℝ^{n+1}$ simultaneously.

This is done in two steps, namely transforming it to the Poincare ball model and from there further on to a Hyperboloid.

source
Manifolds.volume_density — Method
volume_density(M::Hyperbolic, p, X)

Compute volume density function of the hyperbolic manifold. The formula reads $(\sinh(\lVert X\rVert)/\lVert X\rVert)^(n-1)$ where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].

source
ManifoldsBase.change_representer — Method
change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p, X)

Change the Eucliden representer X of a cotangent vector at point p. We only have to correct for the metric, which means that the sign of the last entry changes, since for the result $Y$ we are looking for a tangent vector such that

\[ g_p(Y,Z) = -y_{n+1}z_{n+1} + \sum_{i=1}^n y_iz_i = \sum_{i=1}^{n+1} z_ix_i\]

holds, which directly yields $y_i=x_i$ for $i=1,\ldots,n$ and $y_{n+1}=-x_{n+1}$.

source
ManifoldsBase.distance — Method
distance(M::Hyperbolic, p, q)
+distance(M::Hyperbolic, p::HyperboloidPoint, q::HyperboloidPoint)

Compute the distance on the Hyperbolic M, which reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}( - ⟨p, q⟩_{\mathrm{M}}),\]

where $⟨\cdot,\cdot⟩_{\mathrm{M}}$ denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::Hyperbolic, p, X, ::DefaultOrthonormalBasis)

Compute the coordinates of the vector X with respect to the orthogonalized version of the unit vectors from $ℝ^n$, where $n$ is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.

source
ManifoldsBase.get_vector — Method
get_vector(M::Hyperbolic, p, c, ::DefaultOrthonormalBasis)

Compute the vector from the coordinates with respect to the orthogonalized version of the unit vectors from $ℝ^n$, where $n$ is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.

source
ManifoldsBase.inner — Method
inner(M::Hyperbolic{n}, p, X, Y)
+inner(M::Hyperbolic{n}, p::HyperboloidPoint, X::HyperboloidTVector, Y::HyperboloidTVector)

Cmpute the inner product in the Hyperboloid model, i.e. the minkowski_metric in the embedding. The formula reads

\[g_p(X,Y) = ⟨X,Y⟩_{\mathrm{M}} = -X_{n}Y_{n} + \displaystyle\sum_{k=1}^{n-1} X_kY_k.\]

This employs the metric of the embedding, see Lorentz space.

source

Visualization of the Hyperboloid

For the case of Hyperbolic(2) there is plotting available based on a PlottingRecipe. You can easily plot points, connecting geodesics as well as tangent vectors.

Note

The recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.

If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation for the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path.

In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of wires and a wireframe_color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_x or surface_resolution_y) and a surface_color.

using Manifolds, Plots
 M = Hyperbolic(2)
 pts =  [ [0.85*cos(φ), 0.85*sin(φ), sqrt(0.85^2+1)] for φ ∈ range(0,2π,length=11) ]
 scene = plot(M, pts; geodesic_interpolation=100)
- + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot. Note that we avoid redrawing the wireframe in the following plot! calls.

plot!(scene, M, pts; wireframe=false)
- + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind that a tangent vector in plotting always requires its base point.

pts2 = [ [0.45 .*cos(φ + 6π/11), 0.45 .*sin(φ + 6π/11), sqrt(0.45^2+1) ] for φ ∈ range(0,2π,length=11)]
 vecs = log.(Ref(M),pts,pts2)
 plot!(scene, M, pts, vecs; wireframe=false)
- + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Just to illustrate, for the first point the tangent vector is pointing along the following geodesic

plot!(scene, M, [pts[1], pts2[1]]; geodesic_interpolation=100, wireframe=false)
- + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Internal functions

The following functions are available for internal use to construct points in the hyperboloid model

Manifolds._hyperbolize — Method
_hyperbolize(M, p, Y)

Given the Hyperbolic(n) manifold using the hyperboloid model and a point p thereon, we can put a vector $Y\in ℝ^n$ into the tangent space by computing its last component such that for the resulting p we have that its minkowski_metric is $⟨p,X⟩_{\mathrm{M}} = 0$, i.e. $X_{n+1} = \frac{⟨\tilde p, Y⟩}{p_{n+1}}$, where $\tilde p = (p_1,\ldots,p_n)$.

source
Manifolds._hyperbolize — Method
_hyperbolize(M, q)

Given the Hyperbolic(n) manifold using the hyperboloid model, a point from the $q\in ℝ^n$ can be set onto the manifold by computing its last component such that for the resulting p we have that its minkowski_metric is $⟨p,p⟩_{\mathrm{M}} = - 1$, i.e. $p_{n+1} = \sqrt{\lVert q \rVert^2 - 1}$

source

Poincaré ball model

Base.convert — Method
convert(::Type{PoincareBallPoint}, p::HyperboloidPoint)
-convert(::Type{PoincareBallPoint}, p::T) where {T<:AbstractVector}

convert a HyperboloidPoint $p∈ℝ^{n+1}$ from the hyperboloid model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareBallPoint $π(p)∈ℝ^{n}$ in the Poincaré ball model. The isometry is defined by

\[π(p) = \frac{1}{1+p_{n+1}} \begin{pmatrix}p_1\\⋮\\p_n\end{pmatrix}\]

Note that this is also used, when x is a vector.

source
Base.convert — Method
convert(::Type{PoincareBallPoint}, p::PoincareHalfSpacePoint)

convert a point PoincareHalfSpacePoint p (from $ℝ^n$) from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareBallPoint $π(p) ∈ ℝ^n$. Denote by $\tilde p = (p_1,\ldots,p_{d-1})^{\mathrm{T}}$. Then the isometry is defined by

\[π(p) = \frac{1}{\lVert \tilde p \rVert^2 + (p_n+1)^2} -\begin{pmatrix}2p_1\\⋮\\2p_{n-1}\\\lVert p\rVert^2 - 1\end{pmatrix}.\]

source
Base.convert — Method
convert(::Type{PoincareBallTVector}, p::HyperboloidPoint, X::HyperboloidTVector)
-convert(::Type{PoincareBallTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}

convert a HyperboloidTVector X at p to a PoincareBallTVector on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Hyperboloid to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::HyperboloidPoint).

The formula reads

\[π_*(p)[X] = \frac{1}{p_{n+1}+1}\Bigl(\tilde X - \frac{X_{n+1}}{p_{n+1}+1}\tilde p \Bigl),\]

where $\tilde X = \begin{pmatrix}X_1\\⋮\\X_n\end{pmatrix}$ and $\tilde p = \begin{pmatrix}p_1\\⋮\\p_n\end{pmatrix}$.

source
Base.convert — Method
convert(
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Internal functions
The following functions are available for internal use to construct points in the hyperboloid model
Manifolds._hyperbolize — Method
_hyperbolize(M, p, Y)
Given the Hyperbolic(n) manifold using the hyperboloid model and a point p thereon, we can put a vector $Y\in ℝ^n$  into the tangent space by computing its last component such that for the resulting p we have that its minkowski_metric is $⟨p,X⟩_{\mathrm{M}} = 0$, i.e. $X_{n+1} = \frac{⟨\tilde p, Y⟩}{p_{n+1}}$, where $\tilde p = (p_1,\ldots,p_n)$.
source
Manifolds._hyperbolize — Method
_hyperbolize(M, q)
Given the Hyperbolic(n) manifold using the hyperboloid model, a point from the $q\in ℝ^n$ can be set onto the manifold by computing its last component such that for the resulting p we have that its minkowski_metric is $⟨p,p⟩_{\mathrm{M}} = - 1$, i.e. $p_{n+1} = \sqrt{\lVert q \rVert^2 - 1}$
source
Poincaré ball model
Base.convert — Method
convert(::Type{PoincareBallPoint}, p::HyperboloidPoint)
+convert(::Type{PoincareBallPoint}, p::T) where {T<:AbstractVector}
convert a HyperboloidPoint $p∈ℝ^{n+1}$ from the hyperboloid model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareBallPoint $π(p)∈ℝ^{n}$ in the Poincaré ball model. The isometry is defined by
\[π(p) = \frac{1}{1+p_{n+1}} \begin{pmatrix}p_1\\⋮\\p_n\end{pmatrix}\]
Note that this is also used, when x is a vector.
source
Base.convert — Method
convert(::Type{PoincareBallPoint}, p::PoincareHalfSpacePoint)
convert a point PoincareHalfSpacePoint p (from $ℝ^n$) from the Poincaré half plane model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareBallPoint $π(p) ∈ ℝ^n$. Denote by $\tilde p = (p_1,\ldots,p_{d-1})^{\mathrm{T}}$. Then the isometry is defined by
\[π(p) = \frac{1}{\lVert \tilde p \rVert^2 + (p_n+1)^2}
+\begin{pmatrix}2p_1\\⋮\\2p_{n-1}\\\lVert p\rVert^2 - 1\end{pmatrix}.\]
source
Base.convert — Method
convert(::Type{PoincareBallTVector}, p::HyperboloidPoint, X::HyperboloidTVector)
+convert(::Type{PoincareBallTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}
convert a HyperboloidTVector X at p to a PoincareBallTVector on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Hyperboloid to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::HyperboloidPoint).
The formula reads
\[π_*(p)[X] = \frac{1}{p_{n+1}+1}\Bigl(\tilde X - \frac{X_{n+1}}{p_{n+1}+1}\tilde p \Bigl),\]
where $\tilde X = \begin{pmatrix}X_1\\⋮\\X_n\end{pmatrix}$ and $\tilde p = \begin{pmatrix}p_1\\⋮\\p_n\end{pmatrix}$.
source
Base.convert — Method
convert(
     ::Type{PoincareBallTVector},
     p::PoincareHalfSpacePoint,
     X::PoincareHalfSpaceTVector
@@ -6313,242 +6313,242 @@ 
source
Base.convert — Method
convert(
+\end{pmatrix}\]
where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.
source
Base.convert — Method
convert(
     ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
     (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}
 )
 convert(
     ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
     (p, X)::Tuple{P,T},
-) where {P<:AbstractVector, T <: AbstractVector}
Convert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::HyperboloidPoint) and convert(::Type{PoincareBallTVector}, ::HyperboloidPoint, ::HyperboloidTVector) for the formulae.
source
Base.convert — Method
convert(
     ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
     (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}
 )
 convert(
     ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},
     (p, X)::Tuple{T,T},
-) where {T <: AbstractVector}
Convert a PoincareHalfSpacePoint p and a PoincareHalfSpaceTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint) and convert(::Type{PoincareBallTVector}, ::PoincareHalfSpacePoint, ::PoincareHalfSpaceTVector) for the formulae.
source
ManifoldsBase.change_metric — Method
change_metric(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)
Since in the metric we always have the term $α = \frac{2}{1-\sum_{i=1}^n p_i^2}$ per element, the correction for the metric reads $Z = \frac{1}{α}X$.
source
ManifoldsBase.change_representer — Method
change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)
Since in the metric we have the term $α = \frac{2}{1-\sum_{i=1}^n p_i^2}$ per element, the correction for the gradient reads $Y = \frac{1}{α^2}X$.
source
ManifoldsBase.distance — Method
distance(::Hyperbolic, p::PoincareBallPoint, q::PoincareBallPoint)
Compute the distance on the Hyperbolic manifold $\mathcal H^n$ represented in the Poincaré ball model. The formula reads
\[d_{\mathcal H^n}(p,q) =
+) where {T <: AbstractVector}

Convert a PoincareHalfSpacePoint p and a PoincareHalfSpaceTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint) and convert(::Type{PoincareBallTVector}, ::PoincareHalfSpacePoint, ::PoincareHalfSpaceTVector) for the formulae.

source
ManifoldsBase.change_metric — Method
change_metric(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)

Since in the metric we always have the term $α = \frac{2}{1-\sum_{i=1}^n p_i^2}$ per element, the correction for the metric reads $Z = \frac{1}{α}X$.

source
ManifoldsBase.change_representer — Method
change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)

Since in the metric we have the term $α = \frac{2}{1-\sum_{i=1}^n p_i^2}$ per element, the correction for the gradient reads $Y = \frac{1}{α^2}X$.

source
ManifoldsBase.distance — Method
distance(::Hyperbolic, p::PoincareBallPoint, q::PoincareBallPoint)

Compute the distance on the Hyperbolic manifold $\mathcal H^n$ represented in the Poincaré ball model. The formula reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}\Bigl( 1 + \frac{2\lVert p - q \rVert^2}{(1-\lVert p\rVert^2)(1-\lVert q\rVert^2)} -\Bigr)\]

source
ManifoldsBase.inner — Method
inner(::Hyperbolic, p::PoincareBallPoint, X::PoincareBallTVector, Y::PoincareBallTVector)

Compute the inner producz in the Poincaré ball model. The formula reads

\[g_p(X,Y) = \frac{4}{(1-\lVert p \rVert^2)^2} ⟨X, Y⟩ .\]

source
ManifoldsBase.project — Method
project(::Hyperbolic, ::PoincareBallPoint, ::PoincareBallTVector)

projction of tangent vectors in the Poincaré ball model is just the identity, since the tangent space consists of all $ℝ^n$.

source

Visualization of the Poincaré ball

For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.

Note

The recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.

If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation For the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path. Another keyword argument added is the border of the Poincaré disc, namely circle_points = 720 resolution of the drawn boundary (every hlaf angle) as well as its color, hyperbolic_border_color = RGBA(0.0, 0.0, 0.0, 1.0).

using Manifolds, Plots
+\Bigr)\]
source
ManifoldsBase.inner — Method
inner(::Hyperbolic, p::PoincareBallPoint, X::PoincareBallTVector, Y::PoincareBallTVector)

Compute the inner producz in the Poincaré ball model. The formula reads

\[g_p(X,Y) = \frac{4}{(1-\lVert p \rVert^2)^2} ⟨X, Y⟩ .\]

source
ManifoldsBase.project — Method
project(::Hyperbolic, ::PoincareBallPoint, ::PoincareBallTVector)

projction of tangent vectors in the Poincaré ball model is just the identity, since the tangent space consists of all $ℝ^n$.

source

Visualization of the Poincaré ball

For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.

Note

The recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.

If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation For the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path. Another keyword argument added is the border of the Poincaré disc, namely circle_points = 720 resolution of the drawn boundary (every hlaf angle) as well as its color, hyperbolic_border_color = RGBA(0.0, 0.0, 0.0, 1.0).

using Manifolds, Plots
 M = Hyperbolic(2)
 pts = PoincareBallPoint.( [0.85 .* [cos(φ), sin(φ)] for φ ∈ range(0,2π,length=11)])
 scene = plot(M, pts, geodesic_interpolation = 100)
- + - + - + - + - + - - - - - - + + + + + +

To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot

plot!(scene, M, pts)
- + - + - + - + - + - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + +

We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind, that a tangent vector in plotting always requires its base point

pts2 = PoincareBallPoint.( [0.45 .* [cos(φ + 6π/11), sin(φ + 6π/11)] for φ ∈ range(0,2π,length=11)])
 vecs = log.(Ref(M),pts,pts2)
 plot!(scene, M, pts,vecs)
- + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Just to illustrate, for the first point the tangent vector is pointing along the following geodesic

plot!(scene, M, [pts[1], pts2[1]], geodesic_interpolation=100)
- + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Poincaré half space model

Base.convert — Method
convert(::Type{PoincareHalfSpacePoint}, p::Hyperboloid)
-convert(::Type{PoincareHalfSpacePoint}, p)

convert a HyperboloidPoint or Vectorp (from $ℝ^{n+1}$) from the Hyperboloid model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareHalfSpacePoint $π(x) ∈ ℝ^{n}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a PoincareHalfSpacePoint point.

source
Base.convert — Method
convert(::Type{PoincareHalfSpacePoint}, p::PoincareBallPoint)

convert a point PoincareBallPoint p (from $ℝ^n$) from the Poincaré ball model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareHalfSpacePoint $π(p) ∈ ℝ^n$. Denote by $\tilde p = (p_1,\ldots,p_{n-1})$. Then the isometry is defined by

\[π(p) = \frac{1}{\lVert \tilde p \rVert^2 - (p_n-1)^2} -\begin{pmatrix}2p_1\\⋮\\2p_{n-1}\\1-\lVert p\rVert^2\end{pmatrix}.\]

source
Base.convert — Method
convert(::Type{PoincareHalfSpaceTVector}, p::HyperboloidPoint, ::HyperboloidTVector)
-convert(::Type{PoincareHalfSpaceTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}

convert a HyperboloidTVector X at p to a PoincareHalfSpaceTVector on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Hyperboloid to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint).

This is done similarly to the approach there, i.e. by using the Poincaré ball model as an intermediate step.

source
Base.convert — Method
convert(::Type{PoincareHalfSpaceTVector}, p::PoincareBallPoint, X::PoincareBallTVector)

convert a PoincareBallTVector X at p to a PoincareHalfSpacePoint on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Poincaré ball to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint).

The formula reads

\[π_*(p)[X] = +convert(::Type{PoincareHalfSpacePoint}, p)

convert a HyperboloidPoint or Vectorp (from $ℝ^{n+1}$) from the Hyperboloid model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareHalfSpacePoint $π(x) ∈ ℝ^{n}$.

This is done in two steps, namely transforming it to a Poincare ball point and from there further on to a PoincareHalfSpacePoint point.

source
Base.convert — Method
convert(::Type{PoincareHalfSpacePoint}, p::PoincareBallPoint)

convert a point PoincareBallPoint p (from $ℝ^n$) from the Poincaré ball model of the Hyperbolic manifold $\mathcal H^n$ to a PoincareHalfSpacePoint $π(p) ∈ ℝ^n$. Denote by $\tilde p = (p_1,\ldots,p_{n-1})$. Then the isometry is defined by

\[π(p) = \frac{1}{\lVert \tilde p \rVert^2 - (p_n-1)^2} +\begin{pmatrix}2p_1\\⋮\\2p_{n-1}\\1-\lVert p\rVert^2\end{pmatrix}.\]

source
Base.convert — Method
convert(::Type{PoincareHalfSpaceTVector}, p::HyperboloidPoint, ::HyperboloidTVector)
+convert(::Type{PoincareHalfSpaceTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}

convert a HyperboloidTVector X at p to a PoincareHalfSpaceTVector on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Hyperboloid to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint).

This is done similarly to the approach there, i.e. by using the Poincaré ball model as an intermediate step.

source
Base.convert — Method
convert(::Type{PoincareHalfSpaceTVector}, p::PoincareBallPoint, X::PoincareBallTVector)

convert a PoincareBallTVector X at p to a PoincareHalfSpacePoint on the Hyperbolic manifold $\mathcal H^n$ by computing the push forward $π_*(p)[X]$ of the isometry $π$ that maps from the Poincaré ball to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint).

The formula reads

\[π_*(p)[X] = \frac{1}{\lVert \tilde p\rVert^2 + (1-p_n)^2} \begin{pmatrix} 2X_1\\ @@ -6563,22 +6563,22 @@

source

Base.convert — Method
convert(
+\end{pmatrix}\]
where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.
source
Base.convert — Method
convert(
     ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},
     (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}
 )
 convert(
     ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},
     (p, X)::Tuple{P,T},
-) where {P<:AbstractVector, T <: AbstractVector}

Convert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::Tuple{HyperboloidPoint,HyperboloidTVector}) for the formulae.

source
Base.convert — Method
convert(
+) where {P<:AbstractVector, T <: AbstractVector}

Convert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::Tuple{HyperboloidPoint,HyperboloidTVector}) for the formulae.

source
Base.convert — Method
convert(
     ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},
     (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}
-)

Convert a PoincareBallPoint p and a PoincareBallTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::PoincareBallPoint,::PoincareBallTVector) for the formulae.

source
ManifoldsBase.distance — Method
distance(::Hyperbolic, p::PoincareHalfSpacePoint, q::PoincareHalfSpacePoint)

Compute the distance on the Hyperbolic manifold $\mathcal H^n$ represented in the Poincaré half space model. The formula reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}\Bigl( 1 + \frac{\lVert p - q \rVert^2}{2 p_n q_n} \Bigr)\]

source
ManifoldsBase.inner — Method
inner(
+)

Convert a PoincareBallPoint p and a PoincareBallTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::PoincareBallPoint,::PoincareBallTVector) for the formulae.

source
ManifoldsBase.distance — Method
distance(::Hyperbolic, p::PoincareHalfSpacePoint, q::PoincareHalfSpacePoint)

Compute the distance on the Hyperbolic manifold $\mathcal H^n$ represented in the Poincaré half space model. The formula reads

\[d_{\mathcal H^n}(p,q) = \operatorname{acosh}\Bigl( 1 + \frac{\lVert p - q \rVert^2}{2 p_n q_n} \Bigr)\]

source
ManifoldsBase.inner — Method
inner(
     ::Hyperbolic{n},
     p::PoincareHalfSpacePoint,
     X::PoincareHalfSpaceTVector,
     Y::PoincareHalfSpaceTVector
-)

Compute the inner product in the Poincaré half space model. The formula reads

\[g_p(X,Y) = \frac{⟨X,Y⟩}{p_n^2}.\]

source
ManifoldsBase.project — Method
project(::Hyperbolic, ::PoincareHalfSpacePoint ::PoincareHalfSpaceTVector)

projction of tangent vectors in the Poincaré half space model is just the identity, since the tangent space consists of all $ℝ^n$.

source

Visualization on the Poincaré half plane

For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.

Note

The recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.

We again have two different recipes, one for points, one for tangent vectors, where the first one again can be equipped with geodesics between the points. In the following example we generate 7 points on an ellipse in the Hyperboloid model.

using Manifolds, Plots
+)

Compute the inner product in the Poincaré half space model. The formula reads

\[g_p(X,Y) = \frac{⟨X,Y⟩}{p_n^2}.\]

source
ManifoldsBase.project — Method
project(::Hyperbolic, ::PoincareHalfSpacePoint ::PoincareHalfSpaceTVector)

projction of tangent vectors in the Poincaré half space model is just the identity, since the tangent space consists of all $ℝ^n$.

source

Visualization on the Poincaré half plane

For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.

Note

The recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.

We again have two different recipes, one for points, one for tangent vectors, where the first one again can be equipped with geodesics between the points. In the following example we generate 7 points on an ellipse in the Hyperboloid model.

using Manifolds, Plots
 M = Hyperbolic(2)
 pre_pts = [2.0 .* [5.0*cos(φ), sin(φ)] for φ ∈ range(0,2π,length=7)]
 pts = convert.(
@@ -6588,234 +6588,234 @@ 

 
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot
plot!(scene, M, pts)

 
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind, that a tangent vector in plotting always requires its base point. Here we would like to look at the tangent vectors pointing to the origin
origin = PoincareHalfSpacePoint([0.0,1.0])
 vecs = [log(M,p,origin) for p ∈ pts]
 scene = plot!(scene, M, pts, vecs)

 
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
And we can again look at the corresponding geodesics, for example
plot!(scene, M, [pts[1], origin], geodesic_interpolation=100)
 plot!(scene, M, [pts[2], origin], geodesic_interpolation=100)

 
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
+
 
-  
+  
     
   
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

diff --git a/previews/PR628/manifolds/lorentz.html b/previews/PR628/manifolds/lorentz.html
index 54b442f383..c355a080ee 100644
--- a/previews/PR628/manifolds/lorentz.html
+++ b/previews/PR628/manifolds/lorentz.html
@@ -1,3 +1,3 @@
 
-Lorentzian manifold · Manifolds.jl
Edit on GitHub
Lorentzian Manifold
The Lorentz manifold is a pseudo-Riemannian manifold. It is named after the Dutch physicist Hendrik Lorentz (1853–1928). The default LorentzMetric is the MinkowskiMetric named after the German mathematician Hermann Minkowski (1864–1909).
Within Manifolds.jl it is used as the embedding of the Hyperbolic space.
Manifolds.Lorentz — Type
Lorentz{N} = MetricManifold{Euclidean{N,ℝ},LorentzMetric}
The Lorentz manifold (or Lorentzian) is a pseudo-Riemannian manifold.
Constructor
Lorentz(n[, metric=MinkowskiMetric()])
Generate the Lorentz manifold of dimension n with the LorentzMetric m, which is by default set to the MinkowskiMetric.
source
Manifolds.LorentzMetric — Type
LorentzMetric <: AbstractMetric
Abstract type for Lorentz metrics, which have a single time dimension. These metrics assume the spacelike convention with the time dimension being last, giving the signature $(++...+-)$.
source
Manifolds.minkowski_metric — Method
minkowski_metric(a,b)
Compute the minkowski metric on $\mathbb R^n$ is given by
\[⟨a,b⟩_{\mathrm{M}} = -a_{n}b_{n} +
-\displaystyle\sum_{k=1}^{n-1} a_kb_k.\]
source

+Lorentzian manifold · Manifolds.jl
Edit on GitHub
Lorentzian Manifold
The Lorentz manifold is a pseudo-Riemannian manifold. It is named after the Dutch physicist Hendrik Lorentz (1853–1928). The default LorentzMetric is the MinkowskiMetric named after the German mathematician Hermann Minkowski (1864–1909).
Within Manifolds.jl it is used as the embedding of the Hyperbolic space.
Manifolds.Lorentz — Type
Lorentz{N} = MetricManifold{Euclidean{N,ℝ},LorentzMetric}
The Lorentz manifold (or Lorentzian) is a pseudo-Riemannian manifold.
Constructor
Lorentz(n[, metric=MinkowskiMetric()])
Generate the Lorentz manifold of dimension n with the LorentzMetric m, which is by default set to the MinkowskiMetric.
source
Manifolds.LorentzMetric — Type
LorentzMetric <: AbstractMetric
Abstract type for Lorentz metrics, which have a single time dimension. These metrics assume the spacelike convention with the time dimension being last, giving the signature $(++...+-)$.
source
Manifolds.minkowski_metric — Method
minkowski_metric(a,b)
Compute the minkowski metric on $\mathbb R^n$ is given by
\[⟨a,b⟩_{\mathrm{M}} = -a_{n}b_{n} +
+\displaystyle\sum_{k=1}^{n-1} a_kb_k.\]
source

diff --git a/previews/PR628/manifolds/metric.html b/previews/PR628/manifolds/metric.html
index d2417f727c..6ea4d3a202 100644
--- a/previews/PR628/manifolds/metric.html
+++ b/previews/PR628/manifolds/metric.html
@@ -1,7 +1,7 @@
 
-Metric manifold · Manifolds.jl
Edit on GitHub
Metric manifold
A Riemannian manifold always consists of a topological manifold together with a smoothly varying metric $g$.
However, often there is an implicitly assumed (default) metric, like the usual inner product on Euclidean space. This decorator takes this into account. It is not necessary to use this decorator if you implement just one (or the first) metric. If you later introduce a second, the old (first) metric can be used with the (non MetricManifold) AbstractManifold, i.e. without an explicitly stated metric.
This manifold decorator serves two purposes:
  1. to implement different metrics (e.g. in closed form) for one AbstractManifold
  2. to provide a way to compute geodesics on manifolds, where this AbstractMetric does not yield closed formula.
Note that a metric manifold is has a IsConnectionManifold trait referring to the LeviCivitaConnection of the metric $g$, and thus a large part of metric manifold's functionality relies on this.
Let's first look at the provided types.
Types
Manifolds.IsMetricManifold — Type
IsMetricManifold <: AbstractTrait
Specify that a certain decorated Manifold is a metric manifold in the sence that it provides explicit metric properties, extending/changing the default metric properties of a manifold.
source
Manifolds.MetricManifold — Type
MetricManifold{𝔽,M<:AbstractManifold{𝔽},G<:AbstractMetric} <: AbstractDecoratorManifold{𝔽}
Equip a AbstractManifold explicitly with an AbstractMetric G.
For a Metric AbstractManifold, by default, assumes, that you implement the linear form from local_metric in order to evaluate the exponential map.
If the corresponding AbstractMetric G yields closed form formulae for e.g. the exponential map and this is implemented directly (without solving the ode), you can of course still implement that directly.
Constructor
MetricManifold(M, G)
Generate the AbstractManifold M as a manifold with the AbstractMetric G.
source
Implement Different Metrics on the same Manifold
In order to distinguish different metrics on one manifold, one can introduce two AbstractMetrics and use this type to dispatch on the metric, see SymmetricPositiveDefinite. To avoid overhead, one AbstractMetric can then be marked as being the default, i.e. the one that is used, when no MetricManifold decorator is present. This avoids reimplementation of the first existing metric, access to the metric-dependent functions that were implemented using the undecorated manifold, as well as the transparent fallback of the corresponding MetricManifold with default metric to the undecorated implementations. This does not cause any runtime overhead. Introducing a default AbstractMetric serves a better readability of the code when working with different metrics.
Implementation of Metrics
For the case that a local_metric is implemented as a bilinear form that is positive definite, the following further functions are provided, unless the corresponding AbstractMetric is marked as default – then the fallbacks mentioned in the last section are used for e.g. the exponential map.
Manifolds.det_local_metric — Method
det_local_metric(M::AbstractManifold, p, B::AbstractBasis)
Return the determinant of local matrix representation of the metric tensor $g$, i.e. of the matrix $G(p)$ representing the metric in the tangent space at $p$ with as a matrix.
See also local_metric
source
Manifolds.flat — Method
flat(N::MetricManifold{M,G}, p, X::TFVector)
Compute the musical isomorphism to transform the tangent vector X from the AbstractManifold M equipped with AbstractMetric G to a cotangent by computing
\[X^♭= G_p X,\]
where $G_p$ is the local matrix representation of G, see local_metric
source
Manifolds.inverse_local_metric — Method
inverse_local_metric(M::AbstractcManifold{𝔽}, p, B::AbstractBasis)
Return the local matrix representation of the inverse metric (cometric) tensor of the tangent space at p on the AbstractManifold M with respect to the AbstractBasis basis B.
The metric tensor (see local_metric) is usually denoted by $G = (g_{ij}) ∈ 𝔽^{d×d}$, where $d$ is the dimension of the manifold.
Then the inverse local metric is denoted by $G^{-1} = g^{ij}$.
source
Manifolds.local_metric — Method
local_metric(M::AbstractManifold{𝔽}, p, B::AbstractBasis)
Return the local matrix representation at the point p of the metric tensor $g$ with respect to the AbstractBasis B on the AbstractManifold M. Let $d$denote the dimension of the manifold and $b_1,\ldots,b_d$ the basis vectors. Then the local matrix representation is a matrix $G\in 𝔽^{n\times n}$ whose entries are given by $g_{ij} = g_p(b_i,b_j), i,j\in\{1,…,d\}$.
This yields the property for two tangent vectors (using Einstein summation convention) $X = X^ib_i, Y=Y^ib_i \in T_p\mathcal M$ we get $g_p(X, Y) = g_{ij} X^i Y^j$.
source
Manifolds.local_metric_jacobian — Method
local_metric_jacobian(
+Metric manifold · Manifolds.jl
Edit on GitHub
Metric manifold
A Riemannian manifold always consists of a topological manifold together with a smoothly varying metric $g$.
However, often there is an implicitly assumed (default) metric, like the usual inner product on Euclidean space. This decorator takes this into account. It is not necessary to use this decorator if you implement just one (or the first) metric. If you later introduce a second, the old (first) metric can be used with the (non MetricManifold) AbstractManifold, i.e. without an explicitly stated metric.
This manifold decorator serves two purposes:
  1. to implement different metrics (e.g. in closed form) for one AbstractManifold
  2. to provide a way to compute geodesics on manifolds, where this AbstractMetric does not yield closed formula.
Note that a metric manifold is has a IsConnectionManifold trait referring to the LeviCivitaConnection of the metric $g$, and thus a large part of metric manifold's functionality relies on this.
Let's first look at the provided types.
Types
Manifolds.IsMetricManifold — Type
IsMetricManifold <: AbstractTrait
Specify that a certain decorated Manifold is a metric manifold in the sence that it provides explicit metric properties, extending/changing the default metric properties of a manifold.
source
Manifolds.MetricManifold — Type
MetricManifold{𝔽,M<:AbstractManifold{𝔽},G<:AbstractMetric} <: AbstractDecoratorManifold{𝔽}
Equip a AbstractManifold explicitly with an AbstractMetric G.
For a Metric AbstractManifold, by default, assumes, that you implement the linear form from local_metric in order to evaluate the exponential map.
If the corresponding AbstractMetric G yields closed form formulae for e.g. the exponential map and this is implemented directly (without solving the ode), you can of course still implement that directly.
Constructor
MetricManifold(M, G)
Generate the AbstractManifold M as a manifold with the AbstractMetric G.
source
Implement Different Metrics on the same Manifold
In order to distinguish different metrics on one manifold, one can introduce two AbstractMetrics and use this type to dispatch on the metric, see SymmetricPositiveDefinite. To avoid overhead, one AbstractMetric can then be marked as being the default, i.e. the one that is used, when no MetricManifold decorator is present. This avoids reimplementation of the first existing metric, access to the metric-dependent functions that were implemented using the undecorated manifold, as well as the transparent fallback of the corresponding MetricManifold with default metric to the undecorated implementations. This does not cause any runtime overhead. Introducing a default AbstractMetric serves a better readability of the code when working with different metrics.
Implementation of Metrics
For the case that a local_metric is implemented as a bilinear form that is positive definite, the following further functions are provided, unless the corresponding AbstractMetric is marked as default – then the fallbacks mentioned in the last section are used for e.g. the exponential map.
Manifolds.det_local_metric — Method
det_local_metric(M::AbstractManifold, p, B::AbstractBasis)
Return the determinant of local matrix representation of the metric tensor $g$, i.e. of the matrix $G(p)$ representing the metric in the tangent space at $p$ with as a matrix.
See also local_metric
source
Manifolds.flat — Method
flat(N::MetricManifold{M,G}, p, X::TFVector)
Compute the musical isomorphism to transform the tangent vector X from the AbstractManifold M equipped with AbstractMetric G to a cotangent by computing
\[X^♭= G_p X,\]
where $G_p$ is the local matrix representation of G, see local_metric
source
Manifolds.inverse_local_metric — Method
inverse_local_metric(M::AbstractcManifold{𝔽}, p, B::AbstractBasis)
Return the local matrix representation of the inverse metric (cometric) tensor of the tangent space at p on the AbstractManifold M with respect to the AbstractBasis basis B.
The metric tensor (see local_metric) is usually denoted by $G = (g_{ij}) ∈ 𝔽^{d×d}$, where $d$ is the dimension of the manifold.
Then the inverse local metric is denoted by $G^{-1} = g^{ij}$.
source
Manifolds.local_metric — Method
local_metric(M::AbstractManifold{𝔽}, p, B::AbstractBasis)
Return the local matrix representation at the point p of the metric tensor $g$ with respect to the AbstractBasis B on the AbstractManifold M. Let $d$denote the dimension of the manifold and $b_1,\ldots,b_d$ the basis vectors. Then the local matrix representation is a matrix $G\in 𝔽^{n\times n}$ whose entries are given by $g_{ij} = g_p(b_i,b_j), i,j\in\{1,…,d\}$.
This yields the property for two tangent vectors (using Einstein summation convention) $X = X^ib_i, Y=Y^ib_i \in T_p\mathcal M$ we get $g_p(X, Y) = g_{ij} X^i Y^j$.
source
Manifolds.local_metric_jacobian — Method
local_metric_jacobian(
     M::AbstractManifold,
     p,
     B::AbstractBasis;
     backend::AbstractDiffBackend,
-)
Get partial derivatives of the local metric of M at p in basis B with respect to the coordinates of p, $\frac{∂}{∂ p^k} g_{ij} = g_{ij,k}$. The dimensions of the resulting multi-dimensional array are ordered $(i,j,k)$.
source
Manifolds.log_local_metric_density — Method
log_local_metric_density(M::AbstractManifold, p, B::AbstractBasis)
Return the natural logarithm of the metric density $ρ$ of M at p, which is given by $ρ = \log \sqrt{|\det [g_{ij}]|}$ for the metric tensor expressed in basis B.
source
Manifolds.ricci_curvature — Method
ricci_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())
Compute the Ricci scalar curvature of the manifold M at the point p using basis B. The curvature is computed as the trace of the Ricci curvature tensor with respect to the metric, that is $R=g^{ij}R_{ij}$ where $R$ is the scalar Ricci curvature at p, $g^{ij}$ is the inverse local metric (see inverse_local_metric) at p and $R_{ij}$ is the Riccie curvature tensor, see ricci_tensor. Both the tensor and inverse local metric are expressed in local coordinates defined by B, and the formula uses the Einstein summation convention.
source
Manifolds.sharp — Method
sharp(N::MetricManifold{M,G}, p, ξ::CoTFVector)
Compute the musical isomorphism to transform the cotangent vector ξ from the AbstractManifold M equipped with AbstractMetric G to a tangent by computing
\[ξ^♯ = G_p^{-1} ξ,\]
where $G_p$ is the local matrix representation of G, i.e. one employs inverse_local_metric here to obtain $G_p^{-1}$.
source
ManifoldsBase.inner — Method
inner(N::MetricManifold{M,G}, p, X, Y)
Compute the inner product of X and Y from the tangent space at p on the AbstractManifold M using the AbstractMetric G. If M has G as its IsDefaultMetric trait, this is done using inner(M, p, X, Y), otherwise the local_metric(M, p) is employed as
\[g_p(X, Y) = ⟨X, G_p Y⟩,\]
where $G_p$ is the loal matrix representation of the AbstractMetric G.
source
Metrics, charts and bases of vector spaces
Metric-related functions, similarly to connection-related functions, need to operate in a basis of a vector space, see here.
Metric-related functions can take bases of associated tangent spaces as arguments. For example local_metric can take the basis of the tangent space it is supposed to operate on instead of a custom basis of the space of symmetric bilinear operators.

+)
Get partial derivatives of the local metric of M at p in basis B with respect to the coordinates of p, $\frac{∂}{∂ p^k} g_{ij} = g_{ij,k}$. The dimensions of the resulting multi-dimensional array are ordered $(i,j,k)$.
source
Manifolds.log_local_metric_density — Method
log_local_metric_density(M::AbstractManifold, p, B::AbstractBasis)
Return the natural logarithm of the metric density $ρ$ of M at p, which is given by $ρ = \log \sqrt{|\det [g_{ij}]|}$ for the metric tensor expressed in basis B.
source
Manifolds.ricci_curvature — Method
ricci_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())
Compute the Ricci scalar curvature of the manifold M at the point p using basis B. The curvature is computed as the trace of the Ricci curvature tensor with respect to the metric, that is $R=g^{ij}R_{ij}$ where $R$ is the scalar Ricci curvature at p, $g^{ij}$ is the inverse local metric (see inverse_local_metric) at p and $R_{ij}$ is the Riccie curvature tensor, see ricci_tensor. Both the tensor and inverse local metric are expressed in local coordinates defined by B, and the formula uses the Einstein summation convention.
source
Manifolds.sharp — Method
sharp(N::MetricManifold{M,G}, p, ξ::CoTFVector)
Compute the musical isomorphism to transform the cotangent vector ξ from the AbstractManifold M equipped with AbstractMetric G to a tangent by computing
\[ξ^♯ = G_p^{-1} ξ,\]
where $G_p$ is the local matrix representation of G, i.e. one employs inverse_local_metric here to obtain $G_p^{-1}$.
source
ManifoldsBase.inner — Method
inner(N::MetricManifold{M,G}, p, X, Y)
Compute the inner product of X and Y from the tangent space at p on the AbstractManifold M using the AbstractMetric G. If M has G as its IsDefaultMetric trait, this is done using inner(M, p, X, Y), otherwise the local_metric(M, p) is employed as
\[g_p(X, Y) = ⟨X, G_p Y⟩,\]
where $G_p$ is the loal matrix representation of the AbstractMetric G.
source
Metrics, charts and bases of vector spaces
Metric-related functions, similarly to connection-related functions, need to operate in a basis of a vector space, see here.
Metric-related functions can take bases of associated tangent spaces as arguments. For example local_metric can take the basis of the tangent space it is supposed to operate on instead of a custom basis of the space of symmetric bilinear operators.

diff --git a/previews/PR628/manifolds/multinomial.html b/previews/PR628/manifolds/multinomial.html
index daf1e57753..eecdb4c82b 100644
--- a/previews/PR628/manifolds/multinomial.html
+++ b/previews/PR628/manifolds/multinomial.html
@@ -1,2 +1,2 @@
 
-Multinomial matrices · Manifolds.jl
Edit on GitHub
Multinomial matrices
Manifolds.MultinomialMatrices — Type
MultinomialMatrices{n,m} <: AbstractPowerManifold{ℝ}
The multinomial manifold consists of m column vectors, where each column is of length n and unit norm, i.e.
\[\mathcal{MN}(n,m) \coloneqq \bigl\{ p ∈ ℝ^{n×m}\ \big|\ p_{i,j} > 0 \text{ for all } i=1,…,n, j=1,…,m \text{ and } p^{\mathrm{T}}\mathbb{1}_m = \mathbb{1}_n\bigr\},\]
where $\mathbb{1}_k$ is the vector of length $k$ containing ones.
This yields exactly the same metric as considering the product metric of the probablity vectors, i.e. PowerManifold of the $(n-1)$-dimensional ProbabilitySimplex.
The ProbabilitySimplex is stored internally within M.manifold, such that all functions of AbstractPowerManifold  can be used directly.
Constructor
MultinomialMatrices(n, m)
Generate the manifold of matrices $\mathbb R^{n×m}$ such that the $m$ columns are discrete probability distributions, i.e. sum up to one.
source
Functions
Most functions are directly implemented for an AbstractPowerManifold  with ArrayPowerRepresentation except the following special cases:

+Multinomial matrices · Manifolds.jl
Edit on GitHub
Multinomial matrices
Manifolds.MultinomialMatrices — Type
MultinomialMatrices{n,m} <: AbstractPowerManifold{ℝ}
The multinomial manifold consists of m column vectors, where each column is of length n and unit norm, i.e.
\[\mathcal{MN}(n,m) \coloneqq \bigl\{ p ∈ ℝ^{n×m}\ \big|\ p_{i,j} > 0 \text{ for all } i=1,…,n, j=1,…,m \text{ and } p^{\mathrm{T}}\mathbb{1}_m = \mathbb{1}_n\bigr\},\]
where $\mathbb{1}_k$ is the vector of length $k$ containing ones.
This yields exactly the same metric as considering the product metric of the probablity vectors, i.e. PowerManifold of the $(n-1)$-dimensional ProbabilitySimplex.
The ProbabilitySimplex is stored internally within M.manifold, such that all functions of AbstractPowerManifold  can be used directly.
Constructor
MultinomialMatrices(n, m)
Generate the manifold of matrices $\mathbb R^{n×m}$ such that the $m$ columns are discrete probability distributions, i.e. sum up to one.
source
Functions
Most functions are directly implemented for an AbstractPowerManifold  with ArrayPowerRepresentation except the following special cases:

diff --git a/previews/PR628/manifolds/multinomialdoublystochastic.html b/previews/PR628/manifolds/multinomialdoublystochastic.html
index 3cfff337f8..30918966e2 100644
--- a/previews/PR628/manifolds/multinomialdoublystochastic.html
+++ b/previews/PR628/manifolds/multinomialdoublystochastic.html
@@ -1,17 +1,17 @@
 
-Multinomial doubly stochastic matrices · Manifolds.jl
Edit on GitHub
Multinomial doubly stochastic matrices
Manifolds.MultinomialDoubleStochastic — Type
MultinomialDoublyStochastic{n} <: AbstractMultinomialDoublyStochastic{N}
The set of doubly stochastic multinomial matrices consists of all $n×n$ matrices with stochastic columns and rows, i.e.
\[\begin{aligned}
+Multinomial doubly stochastic matrices · Manifolds.jl
Edit on GitHub
Multinomial doubly stochastic matrices
Manifolds.MultinomialDoubleStochastic — Type
MultinomialDoublyStochastic{n} <: AbstractMultinomialDoublyStochastic{N}
The set of doubly stochastic multinomial matrices consists of all $n×n$ matrices with stochastic columns and rows, i.e.
\[\begin{aligned}
 \mathcal{DP}(n) \coloneqq \bigl\{p ∈ ℝ^{n×n}\ \big|\ &p_{i,j} > 0 \text{ for all } i=1,…,n, j=1,…,m,\\
 & p\mathbf{1}_n = p^{\mathrm{T}}\mathbf{1}_n = \mathbf{1}_n
 \bigr\},
 \end{aligned}\]
where $\mathbf{1}_n$ is the vector of length $n$ containing ones.
The tangent space can be written as
\[T_p\mathcal{DP}(n) \coloneqq \bigl\{
 X ∈ ℝ^{n×n}\ \big|\ X = X^{\mathrm{T}} \text{ and }
 X\mathbf{1}_n = X^{\mathrm{T}}\mathbf{1}_n = \mathbf{0}_n
-\bigr\},\]
where $\mathbf{0}_n$ is the vector of length $n$ containing zeros.
More details can be found in Section III[DouikHassibi2019].
Constructor
MultinomialDoubleStochastic(n)
Generate the manifold of matrices $\mathbb R^{n×n}$ that are doubly stochastic and symmetric.
source
ManifoldsBase.project — Method
project(
+\bigr\},\]
where $\mathbf{0}_n$ is the vector of length $n$ containing zeros.
More details can be found in Section III[DouikHassibi2019].
Constructor
MultinomialDoubleStochastic(n)
Generate the manifold of matrices $\mathbb R^{n×n}$ that are doubly stochastic and symmetric.
source
ManifoldsBase.project — Method
project(
     M::AbstractMultinomialDoublyStochastic,
     p;
     maxiter = 100,
     tolerance = eps(eltype(p))
-)
project a matrix p with positive entries applying Sinkhorn's algorithm. Note that this projct method – different from the usual case, accepts keywords.
source
ManifoldsBase.project — Method
project(M::MultinomialDoubleStochastic{n}, p, Y) where {n}
Project Y onto the tangent space at p on the MultinomialDoubleStochastic M, return the result in X. The formula reads
\[    \operatorname{proj}_p(Y) = Y - (α\mathbf{1}_n^{\mathrm{T}} + \mathbf{1}_nβ^{\mathrm{T}}) ⊙ p,\]
where $⊙$ denotes the Hadamard or elementwise product and $\mathbb{1}_n$ is the vector of length $n$ containing ones. The two vectors $α,β ∈ ℝ^{n×n}$ are computed as a solution (typically using the left pseudo inverse) of
\[    \begin{pmatrix} I_n & p\\p^{\mathrm{T}} & I_n \end{pmatrix}
+)

project a matrix p with positive entries applying Sinkhorn's algorithm. Note that this projct method – different from the usual case, accepts keywords.

source
ManifoldsBase.project — Method
project(M::MultinomialDoubleStochastic{n}, p, Y) where {n}

Project Y onto the tangent space at p on the MultinomialDoubleStochastic M, return the result in X. The formula reads

\[ \operatorname{proj}_p(Y) = Y - (α\mathbf{1}_n^{\mathrm{T}} + \mathbf{1}_nβ^{\mathrm{T}}) ⊙ p,\]

where $⊙$ denotes the Hadamard or elementwise product and $\mathbb{1}_n$ is the vector of length $n$ containing ones. The two vectors $α,β ∈ ℝ^{n×n}$ are computed as a solution (typically using the left pseudo inverse) of

\[ \begin{pmatrix} I_n & p\\p^{\mathrm{T}} & I_n \end{pmatrix} \begin{pmatrix} α\\ β\end{pmatrix} = - \begin{pmatrix} Y\mathbf{1}\\Y^{\mathrm{T}}\mathbf{1}\end{pmatrix},\]

where $I_n$ is the $n×n$ unit matrix and $\mathbf{1}_n$ is the vector of length $n$ containing ones.

source
ManifoldsBase.retract — Method
retract(M::MultinomialDoubleStochastic, p, X, ::ProjectionRetraction)

compute a projection based retraction by projecting $p\odot\exp(X⨸p)$ back onto the manifold, where $⊙,⨸$ are elementwise multiplication and division, respectively. Similarly, $\exp$ refers to the elementwise exponentiation.

source

Literature

  • DouikHassibi2019

    A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.

+ \begin{pmatrix} Y\mathbf{1}\\Y^{\mathrm{T}}\mathbf{1}\end{pmatrix},\]

where $I_n$ is the $n×n$ unit matrix and $\mathbf{1}_n$ is the vector of length $n$ containing ones.

source
ManifoldsBase.retract — Method
retract(M::MultinomialDoubleStochastic, p, X, ::ProjectionRetraction)

compute a projection based retraction by projecting $p\odot\exp(X⨸p)$ back onto the manifold, where $⊙,⨸$ are elementwise multiplication and division, respectively. Similarly, $\exp$ refers to the elementwise exponentiation.

source

Literature

  • DouikHassibi2019

    A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.

diff --git a/previews/PR628/manifolds/multinomialsymmetric.html b/previews/PR628/manifolds/multinomialsymmetric.html index e9e0a6511a..4aee101e18 100644 --- a/previews/PR628/manifolds/multinomialsymmetric.html +++ b/previews/PR628/manifolds/multinomialsymmetric.html @@ -7,4 +7,4 @@ \end{aligned}\]

where $\mathbf{1}_n$ is the vector of length $n$ containing ones.

It is modeled as IsIsometricEmbeddedManifold. via the AbstractMultinomialDoublyStochastic type, since it shares a few functions also with AbstractMultinomialDoublyStochastic, most and foremost projection of a point from the embedding onto the manifold.

The tangent space can be written as

\[T_p\mathcal{SP}(n) \coloneqq \bigl\{ X ∈ ℝ^{n×n}\ \big|\ X = X^{\mathrm{T}} \text{ and } X\mathbf{1}_n = \mathbf{0}_n -\bigr\},\]

where $\mathbf{0}_n$ is the vector of length $n$ containing zeros.

More details can be found in Section IV[DouikHassibi2019].

Constructor

MultinomialSymmetric(n)

Generate the manifold of matrices $\mathbb R^{n×n}$ that are doubly stochastic and symmetric.

source
ManifoldsBase.check_vector — Method
check_vector(M::MultinomialSymmetric p, X; kwargs...)

Checks whether X is a valid tangent vector to p on the MultinomialSymmetric M. This means, that p is valid, that X is of correct dimension, symmetric, and sums to zero along any row.

source
ManifoldsBase.project — Method
project(M::MultinomialSymmetric{n}, p, Y) where {n}

Project Y onto the tangent space at p on the MultinomialSymmetric M, return the result in X. The formula reads

\[ \operatorname{proj}_p(Y) = Y - (α\mathbf{1}_n^{\mathrm{T}} + \mathbf{1}_n α^{\mathrm{T}}) ⊙ p,\]

where $⊙$ denotes the Hadamard or elementwise product and $\mathbb{1}_n$ is the vector of length $n$ containing ones. The two vector $α ∈ ℝ^{n×n}$ is given by solving

\[ (I_n+p)α = Y\mathbf{1},\]

where $I_n$ is teh $n×n$ unit matrix and $\mathbf{1}_n$ is the vector of length $n$ containing ones.

source
ManifoldsBase.retract — Method
retract(M::MultinomialSymmetric, p, X, ::ProjectionRetraction)

compute a projection based retraction by projecting $p\odot\exp(X⨸p)$ back onto the manifold, where $⊙,⨸$ are elementwise multiplication and division, respectively. Similarly, $\exp$ refers to the elementwise exponentiation.

source

Literature

  • DouikHassibi2019

    A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.

+\bigr\},\]

where $\mathbf{0}_n$ is the vector of length $n$ containing zeros.

More details can be found in Section IV[DouikHassibi2019].

Constructor

MultinomialSymmetric(n)

Generate the manifold of matrices $\mathbb R^{n×n}$ that are doubly stochastic and symmetric.

source
ManifoldsBase.check_vector — Method
check_vector(M::MultinomialSymmetric p, X; kwargs...)

Checks whether X is a valid tangent vector to p on the MultinomialSymmetric M. This means, that p is valid, that X is of correct dimension, symmetric, and sums to zero along any row.

source
ManifoldsBase.project — Method
project(M::MultinomialSymmetric{n}, p, Y) where {n}

Project Y onto the tangent space at p on the MultinomialSymmetric M, return the result in X. The formula reads

\[ \operatorname{proj}_p(Y) = Y - (α\mathbf{1}_n^{\mathrm{T}} + \mathbf{1}_n α^{\mathrm{T}}) ⊙ p,\]

where $⊙$ denotes the Hadamard or elementwise product and $\mathbb{1}_n$ is the vector of length $n$ containing ones. The two vector $α ∈ ℝ^{n×n}$ is given by solving

\[ (I_n+p)α = Y\mathbf{1},\]

where $I_n$ is teh $n×n$ unit matrix and $\mathbf{1}_n$ is the vector of length $n$ containing ones.

source
ManifoldsBase.retract — Method
retract(M::MultinomialSymmetric, p, X, ::ProjectionRetraction)

compute a projection based retraction by projecting $p\odot\exp(X⨸p)$ back onto the manifold, where $⊙,⨸$ are elementwise multiplication and division, respectively. Similarly, $\exp$ refers to the elementwise exponentiation.

source

Literature

  • DouikHassibi2019

    A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.

diff --git a/previews/PR628/manifolds/oblique.html b/previews/PR628/manifolds/oblique.html index 8401ad27f4..b91f5b7dcd 100644 --- a/previews/PR628/manifolds/oblique.html +++ b/previews/PR628/manifolds/oblique.html @@ -1,2 +1,2 @@ -Oblique manifold · Manifolds.jl
Edit on GitHub

Oblique manifold

The oblique manifold $\mathcal{OB}(n,m)$ is modeled as an AbstractPowerManifold of the (real-valued) Sphere and uses ArrayPowerRepresentation. Points on the torus are hence matrices, $x ∈ ℝ^{n,m}$.

Manifolds.Oblique — Type
Oblique{N,M,𝔽} <: AbstractPowerManifold{𝔽}

The oblique manifold $\mathcal{OB}(n,m)$ is the set of 𝔽-valued matrices with unit norm column endowed with the metric from the embedding. This yields exactly the same metric as considering the product metric of the unit norm vectors, i.e. PowerManifold of the $(n-1)$-dimensional Sphere.

The Sphere is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.

Constructor

Oblique(n,m)

Generate the manifold of matrices $\mathbb R^{n × m}$ such that the $m$ columns are unit vectors, i.e. from the Sphere(n-1).

source

Functions

Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:

ManifoldsBase.check_point — Method
check_point(M::Oblique{n,m},p)

Checks whether p is a valid point on the Oblique{m,n} M, i.e. is a matrix of m unit columns from $\mathbb R^{n}$, i.e. each column is a point from Sphere(n-1).

source
ManifoldsBase.check_vector — Method
check_vector(M::Oblique p, X; kwargs...)

Checks whether X is a valid tangent vector to p on the Oblique M. This means, that p is valid, that X is of correct dimension and columnswise a tangent vector to the columns of p on the Sphere.

source
+Oblique manifold · Manifolds.jl
Edit on GitHub

Oblique manifold

The oblique manifold $\mathcal{OB}(n,m)$ is modeled as an AbstractPowerManifold of the (real-valued) Sphere and uses ArrayPowerRepresentation. Points on the torus are hence matrices, $x ∈ ℝ^{n,m}$.

Manifolds.Oblique — Type
Oblique{N,M,𝔽} <: AbstractPowerManifold{𝔽}

The oblique manifold $\mathcal{OB}(n,m)$ is the set of 𝔽-valued matrices with unit norm column endowed with the metric from the embedding. This yields exactly the same metric as considering the product metric of the unit norm vectors, i.e. PowerManifold of the $(n-1)$-dimensional Sphere.

The Sphere is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.

Constructor

Oblique(n,m)

Generate the manifold of matrices $\mathbb R^{n × m}$ such that the $m$ columns are unit vectors, i.e. from the Sphere(n-1).

source

Functions

Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:

ManifoldsBase.check_point — Method
check_point(M::Oblique{n,m},p)

Checks whether p is a valid point on the Oblique{m,n} M, i.e. is a matrix of m unit columns from $\mathbb R^{n}$, i.e. each column is a point from Sphere(n-1).

source
ManifoldsBase.check_vector — Method
check_vector(M::Oblique p, X; kwargs...)

Checks whether X is a valid tangent vector to p on the Oblique M. This means, that p is valid, that X is of correct dimension and columnswise a tangent vector to the columns of p on the Sphere.

source
diff --git a/previews/PR628/manifolds/positivenumbers.html b/previews/PR628/manifolds/positivenumbers.html index 08b53f3199..3de1680eda 100644 --- a/previews/PR628/manifolds/positivenumbers.html +++ b/previews/PR628/manifolds/positivenumbers.html @@ -1,2 +1,2 @@ -Positive numbers · Manifolds.jl
Edit on GitHub

Positive Numbers

The manifold PositiveNumbers represents positive numbers with hyperbolic geometry. Additionally, there are also short forms for its corresponding PowerManifolds, i.e. PositiveVectors, PositiveMatrices, and PositiveArrays.

Manifolds.PositiveNumbers — Type
PositiveNumbers <: AbstractManifold{ℝ}

The hyperbolic manifold of positive numbers $H^1$ is a the hyperbolic manifold represented by just positive numbers.

Constructor

PositiveNumbers()

Generate the ℝ-valued hyperbolic model represented by positive positive numbers. To use this with arrays (1-element arrays), please use SymmetricPositiveDefinite(1).

source
Base.exp — Method
exp(M::PositiveNumbers, p, X)

Compute the exponential map on the PositiveNumbers M.

\[\exp_p X = p\operatorname{exp}(X/p).\]

source
ManifoldsBase.change_metric — Method
change_metric(M::PositiveNumbers, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric of PositiveNumbers M.

For all $Z,Y$ we are looking for the function $c$ on the tangent space at $p$ such that

\[ ⟨Z,Y⟩ = XY = \frac{c(Z)c(Y)}{p^2} = g_p(c(Y),c(Z))\]

and hence $C(X) = pX$.

source
ManifoldsBase.change_representer — Method
change_representer(M::PositiveNumbers, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric representation of PositiveNumbers M.

For all tangent vectors $Y$ the result $Z$ has to fulfill

\[ ⟨X,Y⟩ = XY = \frac{ZY}{p^2} = g_p(YZ)\]

and hence $Z = p^2X$

source
ManifoldsBase.check_vector — Method
check_vector(M::PositiveNumbers, p, X; kwargs...)

Check whether X is a tangent vector in the tangent space of p on the PositiveNumbers M. For the real-valued case represented by positive numbers, all X are valid, since the tangent space is the whole real line. For the complex-valued case X [...]

source
ManifoldsBase.inner — Method
inner(M::PositiveNumbers, p, X, Y)

Compute the inner product of the two tangent vectors X,Y from the tangent plane at p on the PositiveNumbers M, i.e.

\[g_p(X,Y) = \frac{XY}{p^2}.\]

source
+Positive numbers · Manifolds.jl
Edit on GitHub

Positive Numbers

The manifold PositiveNumbers represents positive numbers with hyperbolic geometry. Additionally, there are also short forms for its corresponding PowerManifolds, i.e. PositiveVectors, PositiveMatrices, and PositiveArrays.

Manifolds.PositiveNumbers — Type
PositiveNumbers <: AbstractManifold{ℝ}

The hyperbolic manifold of positive numbers $H^1$ is a the hyperbolic manifold represented by just positive numbers.

Constructor

PositiveNumbers()

Generate the ℝ-valued hyperbolic model represented by positive positive numbers. To use this with arrays (1-element arrays), please use SymmetricPositiveDefinite(1).

source
Base.exp — Method
exp(M::PositiveNumbers, p, X)

Compute the exponential map on the PositiveNumbers M.

\[\exp_p X = p\operatorname{exp}(X/p).\]

source
ManifoldsBase.change_metric — Method
change_metric(M::PositiveNumbers, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric of PositiveNumbers M.

For all $Z,Y$ we are looking for the function $c$ on the tangent space at $p$ such that

\[ ⟨Z,Y⟩ = XY = \frac{c(Z)c(Y)}{p^2} = g_p(c(Y),c(Z))\]

and hence $C(X) = pX$.

source
ManifoldsBase.change_representer — Method
change_representer(M::PositiveNumbers, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric representation of PositiveNumbers M.

For all tangent vectors $Y$ the result $Z$ has to fulfill

\[ ⟨X,Y⟩ = XY = \frac{ZY}{p^2} = g_p(YZ)\]

and hence $Z = p^2X$

source
ManifoldsBase.check_vector — Method
check_vector(M::PositiveNumbers, p, X; kwargs...)

Check whether X is a tangent vector in the tangent space of p on the PositiveNumbers M. For the real-valued case represented by positive numbers, all X are valid, since the tangent space is the whole real line. For the complex-valued case X [...]

source
ManifoldsBase.inner — Method
inner(M::PositiveNumbers, p, X, Y)

Compute the inner product of the two tangent vectors X,Y from the tangent plane at p on the PositiveNumbers M, i.e.

\[g_p(X,Y) = \frac{XY}{p^2}.\]

source
diff --git a/previews/PR628/manifolds/power.html b/previews/PR628/manifolds/power.html index f011bd2456..c57231fc4e 100644 --- a/previews/PR628/manifolds/power.html +++ b/previews/PR628/manifolds/power.html @@ -51,4 +51,4 @@ ProductRepr{Tuple{StaticArraysCore.SVector{2, Float64}, StaticArraysCore.SMatrix{2, 2, Float64, 4}}}(([0.0, 0.0], [0.0 -2.2831853071795862; 2.2831853071795862 0.0])) ProductRepr{Tuple{StaticArraysCore.SVector{2, Float64}, StaticArraysCore.SMatrix{2, 2, Float64, 4}}}(([0.0, 0.0], [0.0 -0.28318530717958645; 0.28318530717958645 0.0])) ProductRepr{Tuple{StaticArraysCore.SVector{2, Float64}, StaticArraysCore.SMatrix{2, 2, Float64, 4}}}(([0.0, 0.0], [0.0 1.7168146928204135; -1.7168146928204135 0.0])) - ProductRepr{Tuple{StaticArraysCore.SVector{2, Float64}, StaticArraysCore.SMatrix{2, 2, Float64, 4}}}(([0.0, 0.0], [0.0 -2.566370614359173; 2.566370614359173 0.0]))

Types and Functions

Manifolds.ArrayPowerRepresentation — Type
ArrayPowerRepresentation

Representation of points and tangent vectors on a power manifold using multidimensional arrays where first dimensions are equal to representation_size of the wrapped manifold and the following ones are equal to the number of elements in each direction.

Torus uses this representation.

source
Manifolds.PowerFVectorDistribution — Type
PowerFVectorDistribution([type::VectorBundleFibers], [x], distr)

Generates a random vector at a point from vector space (a fiber of a tangent bundle) of type type using the power distribution of distr.

Vector space type and point can be automatically inferred from distribution distr.

source
Manifolds.PowerMetric — Type
PowerMetric <: AbstractMetric

Represent the AbstractMetric on an AbstractPowerManifold, i.e. the inner product on the tangent space is the sum of the inner product of each elements tangent space of the power manifold.

source
Manifolds.flat — Method
flat(M::AbstractPowerManifold, p, X)

use the musical isomorphism to transform the tangent vector X from the tangent space at p on an AbstractPowerManifold M to a cotangent vector. This can be done elementwise for each entry of X (and p).

source
Manifolds.sharp — Method
sharp(M::AbstractPowerManifold, p, ξ::RieszRepresenterCotangentVector)

Use the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on an AbstractPowerManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p).

source
ManifoldsBase.change_metric — Method
change_metric(M::AbstractPowerManifold, ::AbstractMetric, p, X)

Since the metric on a power manifold decouples, the change of metric can be done elementwise.

source
ManifoldsBase.change_representer — Method
change_representer(M::AbstractPowerManifold, ::AbstractMetric, p, X)

Since the metric on a power manifold decouples, the change of a representer can be done elementwise

source
+ ProductRepr{Tuple{StaticArraysCore.SVector{2, Float64}, StaticArraysCore.SMatrix{2, 2, Float64, 4}}}(([0.0, 0.0], [0.0 -2.566370614359173; 2.566370614359173 0.0]))

Types and Functions

Manifolds.ArrayPowerRepresentation — Type
ArrayPowerRepresentation

Representation of points and tangent vectors on a power manifold using multidimensional arrays where first dimensions are equal to representation_size of the wrapped manifold and the following ones are equal to the number of elements in each direction.

Torus uses this representation.

source
Manifolds.PowerFVectorDistribution — Type
PowerFVectorDistribution([type::VectorBundleFibers], [x], distr)

Generates a random vector at a point from vector space (a fiber of a tangent bundle) of type type using the power distribution of distr.

Vector space type and point can be automatically inferred from distribution distr.

source
Manifolds.PowerMetric — Type
PowerMetric <: AbstractMetric

Represent the AbstractMetric on an AbstractPowerManifold, i.e. the inner product on the tangent space is the sum of the inner product of each elements tangent space of the power manifold.

source
Manifolds.PowerPointDistribution — Type
PowerPointDistribution(M::AbstractPowerManifold, distribution)

Power distribution on manifold M, based on distribution.

source
Manifolds.flat — Method
flat(M::AbstractPowerManifold, p, X)

use the musical isomorphism to transform the tangent vector X from the tangent space at p on an AbstractPowerManifold M to a cotangent vector. This can be done elementwise for each entry of X (and p).

source
Manifolds.manifold_volume — Method
manifold_volume(M::PowerManifold)

Return the manifold volume of an PowerManifold M.

source
Manifolds.sharp — Method
sharp(M::AbstractPowerManifold, p, ξ::RieszRepresenterCotangentVector)

Use the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on an AbstractPowerManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p).

source
Manifolds.volume_density — Method
volume_density(M::PowerManifold, p, X)

Return volume density on the PowerManifold M, i.e. product of constituent volume densities.

source
ManifoldsBase.change_metric — Method
change_metric(M::AbstractPowerManifold, ::AbstractMetric, p, X)

Since the metric on a power manifold decouples, the change of metric can be done elementwise.

source
ManifoldsBase.change_representer — Method
change_representer(M::AbstractPowerManifold, ::AbstractMetric, p, X)

Since the metric on a power manifold decouples, the change of a representer can be done elementwise

source
diff --git a/previews/PR628/manifolds/probabilitysimplex.html b/previews/PR628/manifolds/probabilitysimplex.html index b4f815c5fe..50dad34bbf 100644 --- a/previews/PR628/manifolds/probabilitysimplex.html +++ b/previews/PR628/manifolds/probabilitysimplex.html @@ -1,13 +1,13 @@ -Probability simplex · Manifolds.jl
Edit on GitHub

The probability simplex

Manifolds.FisherRaoMetric — Type
FisherRaoMetric <: AbstractMetric

The Fisher-Rao metric or Fisher information metric is a particular Riemannian metric which can be defined on a smooth statistical manifold, i.e., a smooth manifold whose points are probability measures defined on a common probability space.

See for example the ProbabilitySimplex.

source
Manifolds.ProbabilitySimplex — Type
ProbabilitySimplex{n,boundary} <: AbstractDecoratorManifold{𝔽}

The (relative interior of) the probability simplex is the set

\[Δ^n := \biggl\{ p ∈ ℝ^{n+1}\ \big|\ p_i > 0 \text{ for all } i=1,…,n+1, +Probability simplex · Manifolds.jl

Edit on GitHub

The probability simplex

Manifolds.FisherRaoMetric — Type
FisherRaoMetric <: AbstractMetric

The Fisher-Rao metric or Fisher information metric is a particular Riemannian metric which can be defined on a smooth statistical manifold, i.e., a smooth manifold whose points are probability measures defined on a common probability space.

See for example the ProbabilitySimplex.

source
Manifolds.ProbabilitySimplex — Type
ProbabilitySimplex{n,boundary} <: AbstractDecoratorManifold{𝔽}

The (relative interior of) the probability simplex is the set

\[Δ^n := \biggl\{ p ∈ ℝ^{n+1}\ \big|\ p_i > 0 \text{ for all } i=1,…,n+1, \text{ and } ⟨\mathbb{1},p⟩ = \sum_{i=1}^{n+1} p_i = 1\biggr\},\]

where $\mathbb{1}=(1,…,1)^{\mathrm{T}}∈ ℝ^{n+1}$ denotes the vector containing only ones.

If boundary is set to :open, then the object represents an open simplex. Otherwise, that is when boundary is set to :closed, the boundary is also included:

\[\hat{Δ}^n := \biggl\{ p ∈ ℝ^{n+1}\ \big|\ p_i \geq 0 \text{ for all } i=1,…,n+1, -\text{ and } ⟨\mathbb{1},p⟩ = \sum_{i=1}^{n+1} p_i = 1\biggr\},\]

This set is also called the unit simplex or standard simplex.

The tangent space is given by

\[T_pΔ^n = \biggl\{ X ∈ ℝ^{n+1}\ \big|\ ⟨\mathbb{1},X⟩ = \sum_{i=1}^{n+1} X_i = 0 \biggr\}\]

The manifold is implemented assuming the Fisher-Rao metric for the multinomial distribution, which is equivalent to the induced metric from isometrically embedding the probability simplex in the $n$-sphere of radius 2. The corresponding diffeomorphism $\varphi: \mathbb Δ^n → \mathcal N$, where $\mathcal N \subset 2𝕊^n$ is given by $\varphi(p) = 2\sqrt{p}$.

This implementation follows the notation in [ÅströmPetraSchmitzerSchnörr2017].

Constructor

ProbabilitySimplex(n::Int; boundary::Symbol=:open)
source
Base.exp — Method
exp(M::ProbabilitySimplex, p, X)

Compute the exponential map on the probability simplex.

\[\exp_pX = \frac{1}{2}\Bigl(p+\frac{X_p^2}{\lVert X_p \rVert^2}\Bigr) +\text{ and } ⟨\mathbb{1},p⟩ = \sum_{i=1}^{n+1} p_i = 1\biggr\},\]

This set is also called the unit simplex or standard simplex.

The tangent space is given by

\[T_pΔ^n = \biggl\{ X ∈ ℝ^{n+1}\ \big|\ ⟨\mathbb{1},X⟩ = \sum_{i=1}^{n+1} X_i = 0 \biggr\}\]

The manifold is implemented assuming the Fisher-Rao metric for the multinomial distribution, which is equivalent to the induced metric from isometrically embedding the probability simplex in the $n$-sphere of radius 2. The corresponding diffeomorphism $\varphi: \mathbb Δ^n → \mathcal N$, where $\mathcal N \subset 2𝕊^n$ is given by $\varphi(p) = 2\sqrt{p}$.

This implementation follows the notation in [ÅströmPetraSchmitzerSchnörr2017].

Constructor

ProbabilitySimplex(n::Int; boundary::Symbol=:open)
source
Base.exp — Method
exp(M::ProbabilitySimplex, p, X)

Compute the exponential map on the probability simplex.

\[\exp_pX = \frac{1}{2}\Bigl(p+\frac{X_p^2}{\lVert X_p \rVert^2}\Bigr) + \frac{1}{2}\Bigl(p - \frac{X_p^2}{\lVert X_p \rVert^2}\Bigr)\cos(\lVert X_p\rVert) -+ \frac{1}{\lVert X_p \rVert}\sqrt{p}\sin(\lVert X_p\rVert),\]

where $X_p = \frac{X}{\sqrt{p}}$, with its division meant elementwise, as well as for the operations $X_p^2$ and $\sqrt{p}$.

source
Base.log — Method
log(M::ProbabilitySimplex, p, q)

Compute the logarithmic map of p and q on the ProbabilitySimplex M.

\[\log_pq = \frac{d_{Δ^n}(p,q)}{\sqrt{1-⟨\sqrt{p},\sqrt{q}⟩}}(\sqrt{pq} - ⟨\sqrt{p},\sqrt{q}⟩p),\]

where $pq$ and $\sqrt{p}$ is meant elementwise.

source
Base.rand — Method
rand(::ProbabilitySimplex; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (uniform over the Fisher-Rao metric; that is, uniform with respect to the n-sphere whose positive orthant is mapped to the simplex). point x on the ProbabilitySimplex manifold M according to the isometric embedding into the n-sphere by normalizing the vector length of a sample from a multivariate Gaussian. See [Marsaglia1972].

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{p}\mathrm{\Delta}^n$by shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.

source
ManifoldDiff.riemannian_gradient — Method
X = riemannian_gradient(M::ProbabilitySimplex{n}, p, Y)
-riemannian_gradient!(M::ProbabilitySimplex{n}, X, p, Y)

Given a gradient $Y = \operatorname{grad} \tilde f(p)$ in the embedding $ℝ^{n+1}$ of the ProbabilitySimplex $Δ^n$, this function computes the Riemannian gradient $X = \operatorname{grad} f(p)$ where $f$ is the function $\tilde f$ restricted to the manifold.

The formula reads

\[ X = p ⊙ Y - ⟨p, Y⟩p,\]

where $⊙$ denotes the emelementwise product.

source
Manifolds.volume_density — Method
volume_density(M::ProbabilitySimplex{N}, p, X) where {N}

Compute the volume density at point p on ProbabilitySimplex M for tangent vector X. It is computed using isometry with positive orthant of a sphere.

source
ManifoldsBase.change_metric — Method
change_metric(M::ProbabilitySimplex, ::EuclideanMetric, p, X)

To change the metric, we are looking for a function $c\colon T_pΔ^n \to T_pΔ^n$ such that for all $X,Y ∈ T_pΔ^n$ This can be achieved by rewriting representer change in matrix form as (Diagonal(p) - p * p') * X and taking square root of the matrix

source
ManifoldsBase.change_representer — Method
change_representer(M::ProbabilitySimplex, ::EuclideanMetric, p, X)

Given a tangent vector with respect to the metric from the embedding, the EuclideanMetric, the representer of a linear functional on the tangent space is adapted as $Z = p .* X .- p .* dot(p, X)$. The first part “compensates” for the divsion by $p$ in the Riemannian metric on the ProbabilitySimplex and the second part performs appropriate projection to keep the vector tangent.

For details see Proposition 2.3 in [ÅströmPetraSchmitzerSchnörr2017].

source
ManifoldsBase.check_point — Method
check_point(M::ProbabilitySimplex, p; kwargs...)

Check whether p is a valid point on the ProbabilitySimplex M, i.e. is a point in the embedding with positive entries that sum to one The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::ProbabilitySimplex, p, X; kwargs... )

Check whether X is a tangent vector to p on the ProbabilitySimplex M, i.e. after check_point(M,p), X has to be of same dimension as p and its elements have to sum to one. The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.inner — Method
inner(M::ProbabilitySimplex, p, X, Y)

Compute the inner product of two tangent vectors X, Y from the tangent space $T_pΔ^n$ at p. The formula reads

\[g_p(X,Y) = \sum_{i=1}^{n+1}\frac{X_iY_i}{p_i}\]

When M includes boundary, we can just skip coordinates where $p_i$ is equal to 0, see Proposition 2.1 in [AyJostLeSchwachhöfer2017].

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::ProbabilitySimplex, p, q, ::SoftmaxInverseRetraction)

Compute a first order approximation by projection. The formula reads

\[\operatorname{retr}^{-1}_p q = \bigl( I_{n+1} - \frac{1}{n}\mathbb{1}^{n+1,n+1} \bigr)(\log(q)-\log(p))\]

where $\mathbb{1}^{m,n}$ is the size (m,n) matrix containing ones, and $\log$ is applied elementwise.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::ProbabilitySimplex{n})

Returns the manifold dimension of the probability simplex in $ℝ^{n+1}$, i.e.

\[ \dim_{Δ^n} = n.\]

source
ManifoldsBase.project — Method
project(M::ProbabilitySimplex, p, Y)

Project Y from the embedding onto the tangent space at p on the ProbabilitySimplex M. The formula reads

`math \operatorname{proj}_{Δ^n}(p,Y) = Y - \bar{Y} where $\bar{Y}$ denotes mean of $Y$.

source
ManifoldsBase.project — Method
project(M::ProbabilitySimplex, p)

project p from the embedding onto the ProbabilitySimplex M. The formula reads

\[\operatorname{proj}_{Δ^n}(p) = \frac{1}{⟨\mathbb 1,p⟩}p,\]

where $\mathbb 1 ∈ ℝ$ denotes the vector of ones. Not that this projection is only well-defined if $p$ has positive entries.

source
ManifoldsBase.representation_size — Method
representation_size(::ProbabilitySimplex{n})

Return the representation size of points in the $n$-dimensional probability simplex, i.e. an array size of (n+1,).

source
ManifoldsBase.retract — Method
retract(M::ProbabilitySimplex, p, X, ::SoftmaxRetraction)

Compute a first order approximation by applying the softmax function. The formula reads

\[\operatorname{retr}_p X = \frac{p\mathrm{e}^X}{⟨p,\mathrm{e}^X⟩},\]

where multiplication, exponentiation and division are meant elementwise.

source
Statistics.mean — Method
mean(
++ \frac{1}{\lVert X_p \rVert}\sqrt{p}\sin(\lVert X_p\rVert),\]
where $X_p = \frac{X}{\sqrt{p}}$, with its division meant elementwise, as well as for the operations $X_p^2$ and $\sqrt{p}$.
source
Base.log — Method
log(M::ProbabilitySimplex, p, q)

Compute the logarithmic map of p and q on the ProbabilitySimplex M.

\[\log_pq = \frac{d_{Δ^n}(p,q)}{\sqrt{1-⟨\sqrt{p},\sqrt{q}⟩}}(\sqrt{pq} - ⟨\sqrt{p},\sqrt{q}⟩p),\]

where $pq$ and $\sqrt{p}$ is meant elementwise.

source
Base.rand — Method
rand(::ProbabilitySimplex; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (uniform over the Fisher-Rao metric; that is, uniform with respect to the n-sphere whose positive orthant is mapped to the simplex). point x on the ProbabilitySimplex manifold M according to the isometric embedding into the n-sphere by normalizing the vector length of a sample from a multivariate Gaussian. See [Marsaglia1972].

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{p}\mathrm{\Delta}^n$by shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.

source
ManifoldDiff.riemannian_gradient — Method
X = riemannian_gradient(M::ProbabilitySimplex{n}, p, Y)
+riemannian_gradient!(M::ProbabilitySimplex{n}, X, p, Y)

Given a gradient $Y = \operatorname{grad} \tilde f(p)$ in the embedding $ℝ^{n+1}$ of the ProbabilitySimplex $Δ^n$, this function computes the Riemannian gradient $X = \operatorname{grad} f(p)$ where $f$ is the function $\tilde f$ restricted to the manifold.

The formula reads

\[ X = p ⊙ Y - ⟨p, Y⟩p,\]

where $⊙$ denotes the emelementwise product.

source
Manifolds.volume_density — Method
volume_density(M::ProbabilitySimplex{N}, p, X) where {N}

Compute the volume density at point p on ProbabilitySimplex M for tangent vector X. It is computed using isometry with positive orthant of a sphere.

source
ManifoldsBase.change_metric — Method
change_metric(M::ProbabilitySimplex, ::EuclideanMetric, p, X)

To change the metric, we are looking for a function $c\colon T_pΔ^n \to T_pΔ^n$ such that for all $X,Y ∈ T_pΔ^n$ This can be achieved by rewriting representer change in matrix form as (Diagonal(p) - p * p') * X and taking square root of the matrix

source
ManifoldsBase.change_representer — Method
change_representer(M::ProbabilitySimplex, ::EuclideanMetric, p, X)

Given a tangent vector with respect to the metric from the embedding, the EuclideanMetric, the representer of a linear functional on the tangent space is adapted as $Z = p .* X .- p .* dot(p, X)$. The first part “compensates” for the divsion by $p$ in the Riemannian metric on the ProbabilitySimplex and the second part performs appropriate projection to keep the vector tangent.

For details see Proposition 2.3 in [ÅströmPetraSchmitzerSchnörr2017].

source
ManifoldsBase.check_point — Method
check_point(M::ProbabilitySimplex, p; kwargs...)

Check whether p is a valid point on the ProbabilitySimplex M, i.e. is a point in the embedding with positive entries that sum to one The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::ProbabilitySimplex, p, X; kwargs... )

Check whether X is a tangent vector to p on the ProbabilitySimplex M, i.e. after check_point(M,p), X has to be of same dimension as p and its elements have to sum to one. The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.inner — Method
inner(M::ProbabilitySimplex, p, X, Y)

Compute the inner product of two tangent vectors X, Y from the tangent space $T_pΔ^n$ at p. The formula reads

\[g_p(X,Y) = \sum_{i=1}^{n+1}\frac{X_iY_i}{p_i}\]

When M includes boundary, we can just skip coordinates where $p_i$ is equal to 0, see Proposition 2.1 in [AyJostLeSchwachhöfer2017].

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::ProbabilitySimplex, p, q, ::SoftmaxInverseRetraction)

Compute a first order approximation by projection. The formula reads

\[\operatorname{retr}^{-1}_p q = \bigl( I_{n+1} - \frac{1}{n}\mathbb{1}^{n+1,n+1} \bigr)(\log(q)-\log(p))\]

where $\mathbb{1}^{m,n}$ is the size (m,n) matrix containing ones, and $\log$ is applied elementwise.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::ProbabilitySimplex{n})

Returns the manifold dimension of the probability simplex in $ℝ^{n+1}$, i.e.

\[ \dim_{Δ^n} = n.\]

source
ManifoldsBase.project — Method
project(M::ProbabilitySimplex, p, Y)

Project Y from the embedding onto the tangent space at p on the ProbabilitySimplex M. The formula reads

`math \operatorname{proj}_{Δ^n}(p,Y) = Y - \bar{Y} where $\bar{Y}$ denotes mean of $Y$.

source
ManifoldsBase.project — Method
project(M::ProbabilitySimplex, p)

project p from the embedding onto the ProbabilitySimplex M. The formula reads

\[\operatorname{proj}_{Δ^n}(p) = \frac{1}{⟨\mathbb 1,p⟩}p,\]

where $\mathbb 1 ∈ ℝ$ denotes the vector of ones. Not that this projection is only well-defined if $p$ has positive entries.

source
ManifoldsBase.representation_size — Method
representation_size(::ProbabilitySimplex{n})

Return the representation size of points in the $n$-dimensional probability simplex, i.e. an array size of (n+1,).

source
ManifoldsBase.retract — Method
retract(M::ProbabilitySimplex, p, X, ::SoftmaxRetraction)

Compute a first order approximation by applying the softmax function. The formula reads

\[\operatorname{retr}_p X = \frac{p\mathrm{e}^X}{⟨p,\mathrm{e}^X⟩},\]

where multiplication, exponentiation and division are meant elementwise.

source
Base.rand — Method
rand(::MetricManifold{ℝ,<:ProbabilitySimplex,<:EuclideanMetric}; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (uniform) point x on the ProbabilitySimplex with the Euclidean metric manifold M by normalizing independent exponential draws to unit sum, see [Devroye1986], Theorems 2.1 and 2.2 on p. 207 and 208, respectively.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{p}\mathrm{\Delta}^n$by shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.

source
Manifolds.manifold_volume — Method
manifold_volume(::MetricManifold{ℝ,<:ProbabilitySimplex{n},<:EuclideanMetric})) where {n}

Return the volume of the ProbabilitySimplex with the Euclidean metric. The formula reads $\frac{\sqrt{n+1}}{n!}$

source

Real probability amplitudes

An isometric embedding of interior of ProbabilitySimplex in positive orthant of the Sphere is established through functions simplex_to_amplitude and amplitude_to_simplex. Some properties extend to the boundary but not all.

This embedding isometrically maps the Fisher-Rao metric on the open probability simplex to the sphere of radius 1 with Euclidean metric. More details can be found in Section 2.2 of [AyJostLeSchwachhöfer2017].

The name derives from the notion of probability amplitudes in quantum mechanics. They are complex-valued and their squared norm corresponds to probability. This construction restricted to real valued amplitudes results in this embedding.

Manifolds.amplitude_to_simplex — Method
amplitude_to_simplex(M::ProbabilitySimplex{N}, p) where {N}

Convert point (real) probability amplitude p on to a point on ProbabilitySimplex. The formula reads $(p_1^2, p_2^2, …, p_{N+1}^2)$. This is an isometry from the interior of the positive orthant of a sphere to interior of the probability simplex.

source
Manifolds.simplex_to_amplitude — Method
simplex_to_amplitude(M::ProbabilitySimplex, p)

Convert point p on ProbabilitySimplex to (real) probability amplitude. The formula reads $(\sqrt{p_1}, \sqrt{p_2}, …, \sqrt{p_{N+1}})$. This is an isometry from the interior of the probability simplex to the interior of the positive orthant of a sphere.

source

Literature

+)

Compute the Riemannian mean of x using GeodesicInterpolation.

source
Base.rand — Method
rand(::MetricManifold{ℝ,<:ProbabilitySimplex,<:EuclideanMetric}; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (uniform) point x on the ProbabilitySimplex with the Euclidean metric manifold M by normalizing independent exponential draws to unit sum, see [Devroye1986], Theorems 2.1 and 2.2 on p. 207 and 208, respectively.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{p}\mathrm{\Delta}^n$by shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.

source
Manifolds.manifold_volume — Method
manifold_volume(::MetricManifold{ℝ,<:ProbabilitySimplex{n},<:EuclideanMetric})) where {n}

Return the volume of the ProbabilitySimplex with the Euclidean metric. The formula reads $\frac{\sqrt{n+1}}{n!}$

source

Real probability amplitudes

An isometric embedding of interior of ProbabilitySimplex in positive orthant of the Sphere is established through functions simplex_to_amplitude and amplitude_to_simplex. Some properties extend to the boundary but not all.

This embedding isometrically maps the Fisher-Rao metric on the open probability simplex to the sphere of radius 1 with Euclidean metric. More details can be found in Section 2.2 of [AyJostLeSchwachhöfer2017].

The name derives from the notion of probability amplitudes in quantum mechanics. They are complex-valued and their squared norm corresponds to probability. This construction restricted to real valued amplitudes results in this embedding.

Manifolds.amplitude_to_simplex — Method
amplitude_to_simplex(M::ProbabilitySimplex{N}, p) where {N}

Convert point (real) probability amplitude p on to a point on ProbabilitySimplex. The formula reads $(p_1^2, p_2^2, …, p_{N+1}^2)$. This is an isometry from the interior of the positive orthant of a sphere to interior of the probability simplex.

source
Manifolds.simplex_to_amplitude — Method
simplex_to_amplitude(M::ProbabilitySimplex, p)

Convert point p on ProbabilitySimplex to (real) probability amplitude. The formula reads $(\sqrt{p_1}, \sqrt{p_2}, …, \sqrt{p_{N+1}})$. This is an isometry from the interior of the probability simplex to the interior of the positive orthant of a sphere.

source

Literature

diff --git a/previews/PR628/manifolds/product.html b/previews/PR628/manifolds/product.html index c048778b59..ea99e92cf4 100644 --- a/previews/PR628/manifolds/product.html +++ b/previews/PR628/manifolds/product.html @@ -1,8 +1,8 @@ -Product manifold · Manifolds.jl
Edit on GitHub

Product manifold

Product manifold $\mathcal M = \mathcal{M}_1 × \mathcal{M}_2 × … × \mathcal{M}_n$ of manifolds $\mathcal{M}_1, \mathcal{M}_2, …, \mathcal{M}_n$. Points on the product manifold can be constructed using ProductRepr with canonical projections $Π_i : \mathcal{M} → \mathcal{M}_i$ for $i ∈ 1, 2, …, n$ provided by submanifold_component.

Manifolds.ProductFVectorDistribution — Type
ProductFVectorDistribution([type::VectorBundleFibers], [x], distrs...)

Generates a random vector at point x from vector space (a fiber of a tangent bundle) of type type using the product distribution of given distributions.

Vector space type and x can be automatically inferred from distributions distrs.

source
Manifolds.ProductManifold — Type
ProductManifold{𝔽,TM<:Tuple} <: AbstractManifold{𝔽}

Product manifold $M_1 × M_2 × … × M_n$ with product geometry.

Constructor

ProductManifold(M_1, M_2, ..., M_n)

generates the product manifold $M_1 × M_2 × … × M_n$. Alternatively, the same manifold can be contructed using the × operator: M_1 × M_2 × M_3.

source
Base.exp — Method
exp(M::ProductManifold, p, X)

compute the exponential map from p in the direction of X on the ProductManifold M, which is the elementwise exponential map on the internal manifolds that build M.

source
Base.getindex — Method
getindex(p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})
-p[M::ProductManifold, i]

Access the element(s) at index i of a point p on a ProductManifold M by linear indexing. See also Array Indexing in Julia.

source
Base.log — Method
log(M::ProductManifold, p, q)

Compute the logarithmic map from p to q on the ProductManifold M, which can be computed using the logarithmic maps of the manifolds elementwise.

source
Base.rand — Method
rand(M::ProductManifold; parts_kwargs = map(_ -> (;), M.manifolds))

Return a random point on ProductManifold M. parts_kwargs is a tuple of keyword arguments for rand on each manifold in M.manifolds.

source
Base.setindex! — Method
setindex!(q, p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})
-q[M::ProductManifold,i...] = p

set the element [i...] of a point q on a ProductManifold by linear indexing to q. See also Array Indexing in Julia.

source
LinearAlgebra.cross — Method
cross(M, N)
-cross(M1, M2, M3,...)

Return the ProductManifold For two AbstractManifolds M and N, where for the case that one of them is a ProductManifold itself, the other is either prepended (if N is a product) or appenden (if M) is. If both are product manifold, they are combined into one product manifold, keeping the order.

For the case that more than one is a product manifold of these is build with the same approach as above

source
LinearAlgebra.norm — Method
norm(M::ProductManifold, p, X)

Compute the norm of X from the tangent space of p on the ProductManifold, i.e. from the element wise norms the 2-norm is computed.

source
Manifolds.flat — Method
flat(M::ProductManifold, p, X::FVector{TangentSpaceType})

use the musical isomorphism to transform the tangent vector X from the tangent space at p on the ProductManifold M to a cotangent vector. This can be done elementwise for every entry of X (with respect to the corresponding entry in p) separately.

source
Manifolds.sharp — Method
sharp(M::ProductManifold, p, ξ::FVector{CotangentSpaceType})

Use the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on the ProductManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p) separately

source
Manifolds.submanifold — Method
submanifold(M::ProductManifold, i::Val)
-submanifold(M::ProductManifold, i::AbstractVector)

Extract the factor of the product manifold M indicated by indices in i. For example, for i equal to Val((1, 3)) the product manifold constructed from the first and the third factor is returned.

The version with AbstractVector is not type-stable, for better preformance use Val.

source
ManifoldsBase.change_metric — Method
change_metric(M::ProductManifold, ::AbstractMetric, p, X)

Since the metric on a product manifold decouples, the change of metric can be done elementwise.

source
ManifoldsBase.change_representer — Method
change_representer(M::ProductManifold, ::AbstractMetric, p, X)

Since the metric on a product manifold decouples, the change of a representer can be done elementwise

source
ManifoldsBase.check_point — Method
check_point(M::ProductManifold, p; kwargs...)

Check whether p is a valid point on the ProductManifold M. If p is not a point on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_size — Method
check_size(M::ProductManifold, p; kwargs...)

Check whether p is of valid size on the ProductManifold M. If p has components of wrong size a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::ProductManifold, p, X; kwargs... )

Check whether X is a tangent vector to p on the ProductManifold M, i.e. all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.distance — Method
distance(M::ProductManifold, p, q)

Compute the distance between two points p and q on the ProductManifold M, which is the 2-norm of the elementwise distances on the internal manifolds that build M.

source
ManifoldsBase.inner — Method
inner(M::ProductManifold, p, X, Y)

compute the inner product of two tangent vectors X, Y from the tangent space at p on the ProductManifold M, which is just the sum of the internal manifolds that build M.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::ProductManifold, p, q, m::InverseProductRetraction)

Compute the inverse retraction from p with respect to q on the ProductManifold M using an InverseProductRetraction, which by default encapsulates a inverse retraction for each manifold of the product. Then this method is performed elementwise, so the encapsulated inverse retraction methods have to be available per factor.

source
ManifoldsBase.retract — Method
retract(M::ProductManifold, p, X, m::ProductRetraction)

Compute the retraction from p with tangent vector X on the ProductManifold M using an ProductRetraction, which by default encapsulates retractions of the base manifolds. Then this method is performed elementwise, so the encapsulated retractions method has to be one that is available on the manifolds.

source
+Product manifold · Manifolds.jl
Edit on GitHub

Product manifold

Product manifold $\mathcal M = \mathcal{M}_1 × \mathcal{M}_2 × … × \mathcal{M}_n$ of manifolds $\mathcal{M}_1, \mathcal{M}_2, …, \mathcal{M}_n$. Points on the product manifold can be constructed using ProductRepr with canonical projections $Π_i : \mathcal{M} → \mathcal{M}_i$ for $i ∈ 1, 2, …, n$ provided by submanifold_component.

Manifolds.ProductFVectorDistribution — Type
ProductFVectorDistribution([type::VectorBundleFibers], [x], distrs...)

Generates a random vector at point x from vector space (a fiber of a tangent bundle) of type type using the product distribution of given distributions.

Vector space type and x can be automatically inferred from distributions distrs.

source
Manifolds.ProductManifold — Type
ProductManifold{𝔽,TM<:Tuple} <: AbstractManifold{𝔽}

Product manifold $M_1 × M_2 × … × M_n$ with product geometry.

Constructor

ProductManifold(M_1, M_2, ..., M_n)

generates the product manifold $M_1 × M_2 × … × M_n$. Alternatively, the same manifold can be contructed using the × operator: M_1 × M_2 × M_3.

source
Base.exp — Method
exp(M::ProductManifold, p, X)

compute the exponential map from p in the direction of X on the ProductManifold M, which is the elementwise exponential map on the internal manifolds that build M.

source
Base.getindex — Method
getindex(p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})
+p[M::ProductManifold, i]

Access the element(s) at index i of a point p on a ProductManifold M by linear indexing. See also Array Indexing in Julia.

source
Base.log — Method
log(M::ProductManifold, p, q)

Compute the logarithmic map from p to q on the ProductManifold M, which can be computed using the logarithmic maps of the manifolds elementwise.

source
Base.rand — Method
rand(M::ProductManifold; parts_kwargs = map(_ -> (;), M.manifolds))

Return a random point on ProductManifold M. parts_kwargs is a tuple of keyword arguments for rand on each manifold in M.manifolds.

source
Base.setindex! — Method
setindex!(q, p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})
+q[M::ProductManifold,i...] = p

set the element [i...] of a point q on a ProductManifold by linear indexing to q. See also Array Indexing in Julia.

source
LinearAlgebra.cross — Method
cross(M, N)
+cross(M1, M2, M3,...)

Return the ProductManifold For two AbstractManifolds M and N, where for the case that one of them is a ProductManifold itself, the other is either prepended (if N is a product) or appenden (if M) is. If both are product manifold, they are combined into one product manifold, keeping the order.

For the case that more than one is a product manifold of these is build with the same approach as above

source
LinearAlgebra.norm — Method
norm(M::ProductManifold, p, X)

Compute the norm of X from the tangent space of p on the ProductManifold, i.e. from the element wise norms the 2-norm is computed.

source
Manifolds.flat — Method
flat(M::ProductManifold, p, X::FVector{TangentSpaceType})

use the musical isomorphism to transform the tangent vector X from the tangent space at p on the ProductManifold M to a cotangent vector. This can be done elementwise for every entry of X (with respect to the corresponding entry in p) separately.

source
Manifolds.sharp — Method
sharp(M::ProductManifold, p, ξ::FVector{CotangentSpaceType})

Use the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on the ProductManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p) separately

source
Manifolds.submanifold — Method
submanifold(M::ProductManifold, i::Val)
+submanifold(M::ProductManifold, i::AbstractVector)

Extract the factor of the product manifold M indicated by indices in i. For example, for i equal to Val((1, 3)) the product manifold constructed from the first and the third factor is returned.

The version with AbstractVector is not type-stable, for better preformance use Val.

source
ManifoldsBase.change_metric — Method
change_metric(M::ProductManifold, ::AbstractMetric, p, X)

Since the metric on a product manifold decouples, the change of metric can be done elementwise.

source
ManifoldsBase.change_representer — Method
change_representer(M::ProductManifold, ::AbstractMetric, p, X)

Since the metric on a product manifold decouples, the change of a representer can be done elementwise

source
ManifoldsBase.check_point — Method
check_point(M::ProductManifold, p; kwargs...)

Check whether p is a valid point on the ProductManifold M. If p is not a point on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_size — Method
check_size(M::ProductManifold, p; kwargs...)

Check whether p is of valid size on the ProductManifold M. If p has components of wrong size a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::ProductManifold, p, X; kwargs... )

Check whether X is a tangent vector to p on the ProductManifold M, i.e. all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.

The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.distance — Method
distance(M::ProductManifold, p, q)

Compute the distance between two points p and q on the ProductManifold M, which is the 2-norm of the elementwise distances on the internal manifolds that build M.

source
ManifoldsBase.inner — Method
inner(M::ProductManifold, p, X, Y)

compute the inner product of two tangent vectors X, Y from the tangent space at p on the ProductManifold M, which is just the sum of the internal manifolds that build M.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::ProductManifold, p, q, m::InverseProductRetraction)

Compute the inverse retraction from p with respect to q on the ProductManifold M using an InverseProductRetraction, which by default encapsulates a inverse retraction for each manifold of the product. Then this method is performed elementwise, so the encapsulated inverse retraction methods have to be available per factor.

source
ManifoldsBase.retract — Method
retract(M::ProductManifold, p, X, m::ProductRetraction)

Compute the retraction from p with tangent vector X on the ProductManifold M using an ProductRetraction, which by default encapsulates retractions of the base manifolds. Then this method is performed elementwise, so the encapsulated retractions method has to be one that is available on the manifolds.

source
diff --git a/previews/PR628/manifolds/projectivespace.html b/previews/PR628/manifolds/projectivespace.html index 6203dc4abd..fababcc67a 100644 --- a/previews/PR628/manifolds/projectivespace.html +++ b/previews/PR628/manifolds/projectivespace.html @@ -1,12 +1,12 @@ -Projective space · Manifolds.jl
Edit on GitHub

Projective space

Manifolds.AbstractProjectiveSpace — Type
AbstractProjectiveSpace{𝔽} <: AbstractDecoratorManifold{𝔽}

An abstract type to represent a projective space over 𝔽 that is represented isometrically in the embedding.

source
Manifolds.ArrayProjectiveSpace — Type
ArrayProjectiveSpace{T<:Tuple,𝔽} <: AbstractProjectiveSpace{𝔽}

The projective space $𝔽ℙ^{n₁,n₂,…,nᵢ}$ is the manifold of all lines in $𝔽^{n₁,n₂,…,nᵢ}$. The default representation is in the embedding, i.e. as unit (Frobenius) norm matrices in $𝔽^{n₁,n₂,…,nᵢ}$:

\[𝔽ℙ^{n_1, n_2, …, n_i} := \bigl\{ [p] ⊂ 𝔽^{n_1, n_2, …, n_i} \ \big|\ \lVert p \rVert_{\mathrm{F}} = 1, λ ∈ 𝔽, |λ| = 1, p ∼ p λ \bigr\}.\]

where $[p]$ is an equivalence class of points $p$, $\sim$ indicates equivalence, and $\lVert ⋅ \rVert_{\mathrm{F}}$ is the Frobenius norm. Note that unlike ProjectiveSpace, the argument for ArrayProjectiveSpace is given by the size of the embedding. This means that ProjectiveSpace(2) and ArrayProjectiveSpace(3) are the same manifold. Additionally, ArrayProjectiveSpace(n,1;field=𝔽) and Grassmann(n,1;field=𝔽) are the same.

The tangent space at point $p$ is given by

\[T_p 𝔽ℙ^{n_1, n_2, …, n_i} := \bigl\{ X ∈ 𝔽^{n_1, n_2, …, n_i}\ |\ ⟨p,X⟩_{\mathrm{F}} = 0 \bigr \},\]

where $⟨⋅,⋅⟩_{\mathrm{F}}$ denotes the (Frobenius) inner product in the embedding $𝔽^{n_1, n_2, …, n_i}$.

Constructor

ArrayProjectiveSpace(n₁,n₂,...,nᵢ; field=ℝ)

Generate the projective space $𝔽ℙ^{n_1, n_2, …, n_i}$, defaulting to the real projective space, where field can also be used to generate the complex- and right-quaternionic projective spaces.

source
Manifolds.ProjectiveSpace — Type
ProjectiveSpace{n,𝔽} <: AbstractProjectiveSpace{𝔽}

The projective space $𝔽ℙ^n$ is the manifold of all lines in $𝔽^{n+1}$. The default representation is in the embedding, i.e. as unit norm vectors in $𝔽^{n+1}$:

\[𝔽ℙ^n := \bigl\{ [p] ⊂ 𝔽^{n+1} \ \big|\ \lVert p \rVert = 1, λ ∈ 𝔽, |λ| = 1, p ∼ p λ \bigr\},\]

where $[p]$ is an equivalence class of points $p$, and $∼$ indicates equivalence. For example, the real projective space $ℝℙ^n$ is represented as the unit sphere $𝕊^n$, where antipodal points are considered equivalent.

The tangent space at point $p$ is given by

\[T_p 𝔽ℙ^{n} := \bigl\{ X ∈ 𝔽^{n+1}\ \big|\ ⟨p,X⟩ = 0 \bigr \},\]

where $⟨⋅,⋅⟩$ denotes the inner product in the embedding $𝔽^{n+1}$.

When $𝔽 = ℍ$, this implementation of $ℍℙ^n$ is the right-quaternionic projective space.

Constructor

ProjectiveSpace(n[, field=ℝ])

Generate the projective space $𝔽ℙ^{n} ⊂ 𝔽^{n+1}$, defaulting to the real projective space $ℝℙ^n$, where field can also be used to generate the complex- and right-quaternionic projective spaces.

source
Base.log — Method
log(M::AbstractProjectiveSpace, p, q)

Compute the logarithmic map on AbstractProjectiveSpace M$ = 𝔽ℙ^n$, i.e. the tangent vector whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads

\[\log_p q = (q λ - \cos θ p) \frac{θ}{\sin θ},\]

where $θ = \arccos|⟨q, p⟩_{\mathrm{F}}|$ is the distance between $p$ and $q$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ is the Frobenius inner product, and $λ = \frac{⟨q, p⟩_{\mathrm{F}}}{|⟨q, p⟩_{\mathrm{F}}|} ∈ 𝔽$ is the unit scalar that minimizes $d_{𝔽^{n+1}}(p - q λ)$. That is, $q λ$ is the member of the equivalence class $[q]$ that is closest to $p$ in the embedding. As a result, $\exp_p \circ \log_p \colon q ↦ q λ$.

The logarithmic maps for the real AbstractSphere $𝕊^n$ and the real projective space $ℝℙ^n$ are identical when $p$ and $q$ are in the same hemisphere.

source
ManifoldsBase._isapprox — Method
isapprox(M::AbstractProjectiveSpace, p, q; kwargs...)

Check that points p and q on the AbstractProjectiveSpace M$=𝔽ℙ^n$ are members of the same equivalence class, i.e. that $p = q λ$ for some element $λ ∈ 𝔽$ with unit absolute value, that is, $|λ| = 1$. This is equivalent to the Riemannian distance being 0.

source
ManifoldsBase.check_point — Method
check_point(M::AbstractProjectiveSpace, p; kwargs...)

Check whether p is a valid point on the AbstractProjectiveSpace M, i.e. that it has the same size as elements of the embedding and has unit Frobenius norm. The tolerance for the norm check can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractProjectiveSpace, p, X; kwargs... )

Check whether X is a tangent vector in the tangent space of p on the AbstractProjectiveSpace M, i.e. that X has the same size as elements of the tangent space of the embedding and that the Frobenius inner product $⟨p, X⟩_{\mathrm{F}} = 0$.

source
ManifoldsBase.distance — Method
distance(M::AbstractProjectiveSpace, p, q)

Compute the Riemannian distance on AbstractProjectiveSpace M$=𝔽ℙ^n$ between points p and q, i.e.

\[d_{𝔽ℙ^n}(p, q) = \arccos\bigl| ⟨p, q⟩_{\mathrm{F}} \bigr|.\]

Note that this definition is similar to that of the AbstractSphere. However, the absolute value ensures that all equivalent p and q have the same pairwise distance.

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})

Represent the tangent vector $X$ at point $p$ from the AbstractProjectiveSpace $M = 𝔽ℙ^n$ in an orthonormal basis by unitarily transforming the hyperplane containing $X$, whose normal is $p$, to the hyperplane whose normal is the $x$-axis.

Given $q = p \overline{λ} + x$, where $λ = \frac{⟨x, p⟩_{\mathrm{F}}}{|⟨x, p⟩_{\mathrm{F}}|}$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, and $\overline{⋅}$ denotes complex or quaternionic conjugation, the formula for $Y$ is

\[\begin{pmatrix}0 \\ Y\end{pmatrix} = \left(X - q\frac{2 ⟨q, X⟩_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}\right)\overline{λ}.\]

source
ManifoldsBase.get_vector — Method
get_vector(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})

Convert a one-dimensional vector of coefficients $X$ in the basis B of the tangent space at $p$ on the AbstractProjectiveSpace $M=𝔽ℙ^n$ to a tangent vector $Y$ at $p$ by unitarily transforming the hyperplane containing $X$, whose normal is the $x$-axis, to the hyperplane whose normal is $p$.

Given $q = p \overline{λ} + x$, where $λ = \frac{⟨x, p⟩_{\mathrm{F}}}{|⟨x, p⟩_{\mathrm{F}}|}$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, and $\overline{⋅}$ denotes complex or quaternionic conjugation, the formula for $Y$ is

\[Y = \left(X - q\frac{2 \left\langle q, \begin{pmatrix}0 \\ X\end{pmatrix}\right\rangle_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}\right) λ.\]

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::AbstractProjectiveSpace, p, q, method::ProjectionInverseRetraction)
+Projective space · Manifolds.jl
Edit on GitHub
Projective space
Manifolds.AbstractProjectiveSpace — Type
AbstractProjectiveSpace{𝔽} <: AbstractDecoratorManifold{𝔽}
An abstract type to represent a projective space over 𝔽 that is represented isometrically in the embedding.
source
Manifolds.ArrayProjectiveSpace — Type
ArrayProjectiveSpace{T<:Tuple,𝔽} <: AbstractProjectiveSpace{𝔽}
The projective space $𝔽ℙ^{n₁,n₂,…,nᵢ}$ is the manifold of all lines in $𝔽^{n₁,n₂,…,nᵢ}$. The default representation is in the embedding, i.e. as unit (Frobenius) norm matrices in $𝔽^{n₁,n₂,…,nᵢ}$:
\[𝔽ℙ^{n_1, n_2, …, n_i} := \bigl\{ [p] ⊂ 𝔽^{n_1, n_2, …, n_i} \ \big|\ \lVert p \rVert_{\mathrm{F}} = 1, λ ∈ 𝔽, |λ| = 1, p ∼ p λ \bigr\}.\]
where $[p]$ is an equivalence class of points $p$, $\sim$ indicates equivalence, and $\lVert ⋅ \rVert_{\mathrm{F}}$ is the Frobenius norm. Note that unlike ProjectiveSpace, the argument for ArrayProjectiveSpace is given by the size of the embedding. This means that ProjectiveSpace(2) and ArrayProjectiveSpace(3) are the same manifold. Additionally, ArrayProjectiveSpace(n,1;field=𝔽) and Grassmann(n,1;field=𝔽) are the same.
The tangent space at point $p$ is given by
\[T_p 𝔽ℙ^{n_1, n_2, …, n_i} := \bigl\{ X ∈ 𝔽^{n_1, n_2, …, n_i}\ |\ ⟨p,X⟩_{\mathrm{F}} = 0 \bigr \},\]
where $⟨⋅,⋅⟩_{\mathrm{F}}$ denotes the (Frobenius) inner product in the embedding $𝔽^{n_1, n_2, …, n_i}$.
Constructor
ArrayProjectiveSpace(n₁,n₂,...,nᵢ; field=ℝ)
Generate the projective space $𝔽ℙ^{n_1, n_2, …, n_i}$, defaulting to the real projective space, where field can also be used to generate the complex- and right-quaternionic projective spaces.
source
Manifolds.ProjectiveSpace — Type
ProjectiveSpace{n,𝔽} <: AbstractProjectiveSpace{𝔽}
The projective space $𝔽ℙ^n$ is the manifold of all lines in $𝔽^{n+1}$. The default representation is in the embedding, i.e. as unit norm vectors in $𝔽^{n+1}$:
\[𝔽ℙ^n := \bigl\{ [p] ⊂ 𝔽^{n+1} \ \big|\ \lVert p \rVert = 1, λ ∈ 𝔽, |λ| = 1, p ∼ p λ \bigr\},\]
where $[p]$ is an equivalence class of points $p$, and $∼$ indicates equivalence. For example, the real projective space $ℝℙ^n$ is represented as the unit sphere $𝕊^n$, where antipodal points are considered equivalent.
The tangent space at point $p$ is given by
\[T_p 𝔽ℙ^{n} := \bigl\{ X ∈ 𝔽^{n+1}\ \big|\ ⟨p,X⟩ = 0 \bigr \},\]
where $⟨⋅,⋅⟩$ denotes the inner product in the embedding $𝔽^{n+1}$.
When $𝔽 = ℍ$, this implementation of $ℍℙ^n$ is the right-quaternionic projective space.
Constructor
ProjectiveSpace(n[, field=ℝ])
Generate the projective space $𝔽ℙ^{n} ⊂ 𝔽^{n+1}$, defaulting to the real projective space $ℝℙ^n$, where field can also be used to generate the complex- and right-quaternionic projective spaces.
source
Base.log — Method
log(M::AbstractProjectiveSpace, p, q)
Compute the logarithmic map on AbstractProjectiveSpace M$ = 𝔽ℙ^n$, i.e. the tangent vector whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads
\[\log_p q = (q λ - \cos θ p) \frac{θ}{\sin θ},\]
where $θ = \arccos|⟨q, p⟩_{\mathrm{F}}|$ is the distance between $p$ and $q$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ is the Frobenius inner product, and $λ = \frac{⟨q, p⟩_{\mathrm{F}}}{|⟨q, p⟩_{\mathrm{F}}|} ∈ 𝔽$ is the unit scalar that minimizes $d_{𝔽^{n+1}}(p - q λ)$. That is, $q λ$ is the member of the equivalence class $[q]$ that is closest to $p$ in the embedding. As a result, $\exp_p \circ \log_p \colon q ↦ q λ$.
The logarithmic maps for the real AbstractSphere $𝕊^n$ and the real projective space $ℝℙ^n$ are identical when $p$ and $q$ are in the same hemisphere.
source
ManifoldsBase._isapprox — Method
isapprox(M::AbstractProjectiveSpace, p, q; kwargs...)
Check that points p and q on the AbstractProjectiveSpace M$=𝔽ℙ^n$ are members of the same equivalence class, i.e. that $p = q λ$ for some element $λ ∈ 𝔽$ with unit absolute value, that is, $|λ| = 1$. This is equivalent to the Riemannian distance being 0.
source
ManifoldsBase.check_point — Method
check_point(M::AbstractProjectiveSpace, p; kwargs...)
Check whether p is a valid point on the AbstractProjectiveSpace M, i.e. that it has the same size as elements of the embedding and has unit Frobenius norm. The tolerance for the norm check can be set using the kwargs....
source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractProjectiveSpace, p, X; kwargs... )
Check whether X is a tangent vector in the tangent space of p on the AbstractProjectiveSpace M, i.e. that X has the same size as elements of the tangent space of the embedding and that the Frobenius inner product $⟨p, X⟩_{\mathrm{F}} = 0$.
source
ManifoldsBase.distance — Method
distance(M::AbstractProjectiveSpace, p, q)
Compute the Riemannian distance on AbstractProjectiveSpace M$=𝔽ℙ^n$ between points p and q, i.e.
\[d_{𝔽ℙ^n}(p, q) = \arccos\bigl| ⟨p, q⟩_{\mathrm{F}} \bigr|.\]
Note that this definition is similar to that of the AbstractSphere. However, the absolute value ensures that all equivalent p and q have the same pairwise distance.
source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})
Represent the tangent vector $X$ at point $p$ from the AbstractProjectiveSpace $M = 𝔽ℙ^n$ in an orthonormal basis by unitarily transforming the hyperplane containing $X$, whose normal is $p$, to the hyperplane whose normal is the $x$-axis.
Given $q = p \overline{λ} + x$, where $λ = \frac{⟨x, p⟩_{\mathrm{F}}}{|⟨x, p⟩_{\mathrm{F}}|}$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, and $\overline{⋅}$ denotes complex or quaternionic conjugation, the formula for $Y$ is
\[\begin{pmatrix}0 \\ Y\end{pmatrix} = \left(X - q\frac{2 ⟨q, X⟩_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}\right)\overline{λ}.\]
source
ManifoldsBase.get_vector — Method
get_vector(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})
Convert a one-dimensional vector of coefficients $X$ in the basis B of the tangent space at $p$ on the AbstractProjectiveSpace $M=𝔽ℙ^n$ to a tangent vector $Y$ at $p$ by unitarily transforming the hyperplane containing $X$, whose normal is the $x$-axis, to the hyperplane whose normal is $p$.
Given $q = p \overline{λ} + x$, where $λ = \frac{⟨x, p⟩_{\mathrm{F}}}{|⟨x, p⟩_{\mathrm{F}}|}$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, and $\overline{⋅}$ denotes complex or quaternionic conjugation, the formula for $Y$ is
\[Y = \left(X - q\frac{2 \left\langle q, \begin{pmatrix}0 \\ X\end{pmatrix}\right\rangle_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}\right) λ.\]
source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::AbstractProjectiveSpace, p, q, method::ProjectionInverseRetraction)
 inverse_retract(M::AbstractProjectiveSpace, p, q, method::PolarInverseRetraction)
-inverse_retract(M::AbstractProjectiveSpace, p, q, method::QRInverseRetraction)
Compute the equivalent inverse retraction ProjectionInverseRetraction, PolarInverseRetraction, and QRInverseRetraction on the AbstractProjectiveSpace manifold M$=𝔽ℙ^n$, i.e.
\[\operatorname{retr}_p^{-1} q = q \frac{1}{⟨p, q⟩_{\mathrm{F}}} - p,\]
where $⟨⋅, ⋅⟩_{\mathrm{F}}$ is the Frobenius inner product.
Note that this inverse retraction is equivalent to the three corresponding inverse retractions on Grassmann(n+1,1,𝔽), where the three inverse retractions in this case coincide. For $ℝℙ^n$, it is the same as the ProjectionInverseRetraction on the real Sphere.
source
ManifoldsBase.parallel_transport_direction — Method
parallel_transport_direction(M::AbstractProjectiveSpace, p, X, d)
Parallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M along the geodesic in the direction indicated by the tangent vector d, i.e.
\[\mathcal{P}_{\exp_p (d) ← p}(X) = X - \left(p \frac{\sin θ}{θ} + d \frac{1 - \cos θ}{θ^2}\right) ⟨d, X⟩_p,\]
where $θ = \lVert d \rVert$, and $⟨⋅, ⋅⟩_p$ is the inner product at the point $p$. For the real projective space, this is equivalent to the same vector transport on the real AbstractSphere.
source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::AbstractProjectiveSpace, p, X, q)
Parallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M$=𝔽ℙ^n$ to the tangent space at another point q.
This implementation proceeds by transporting $X$ to $T_{q λ} M$ using the same approach as parallel_transport_direction, where $λ = \frac{⟨q, p⟩_{\mathrm{F}}}{|⟨q, p⟩_{\mathrm{F}}|} ∈ 𝔽$ is the unit scalar that takes $q$ to the member $q λ$ of its equivalence class $[q]$ closest to $p$ in the embedding. It then maps the transported vector from $T_{q λ} M$ to $T_{q} M$. The resulting transport to $T_{q} M$ is
\[\mathcal{P}_{q ← p}(X) = \left(X - \left(p \frac{\sin θ}{θ} + d \frac{1 - \cos θ}{θ^2}\right) ⟨d, X⟩_p\right) \overline{λ},\]
where $d = \log_p q$ is the direction of the transport, $θ = \lVert d \rVert_p$ is the distance between $p$ and $q$, and $\overline{⋅}$ denotes complex or quaternionic conjugation.
source
ManifoldsBase.project — Method
project(M::AbstractProjectiveSpace, p, X)
Orthogonally project the point X onto the tangent space at p on the AbstractProjectiveSpace M:
\[\operatorname{proj}_p (X) = X - p⟨p, X⟩_{\mathrm{F}},\]
where $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product. For the real AbstractSphere and AbstractProjectiveSpace, this projection is the same.
source
ManifoldsBase.project — Method
project(M::AbstractProjectiveSpace, p)
Orthogonally project the point p from the embedding onto the AbstractProjectiveSpace M:
\[\operatorname{proj}(p) = \frac{p}{\lVert p \rVert}_{\mathrm{F}},\]
where $\lVert ⋅ \rVert_{\mathrm{F}}$ denotes the Frobenius norm. This is identical to projection onto the AbstractSphere.
source
ManifoldsBase.retract — Method
retract(M::AbstractProjectiveSpace, p, X, method::ProjectionRetraction)
+inverse_retract(M::AbstractProjectiveSpace, p, q, method::QRInverseRetraction)
Compute the equivalent inverse retraction ProjectionInverseRetraction, PolarInverseRetraction, and QRInverseRetraction on the AbstractProjectiveSpace manifold M$=𝔽ℙ^n$, i.e.
\[\operatorname{retr}_p^{-1} q = q \frac{1}{⟨p, q⟩_{\mathrm{F}}} - p,\]
where $⟨⋅, ⋅⟩_{\mathrm{F}}$ is the Frobenius inner product.
Note that this inverse retraction is equivalent to the three corresponding inverse retractions on Grassmann(n+1,1,𝔽), where the three inverse retractions in this case coincide. For $ℝℙ^n$, it is the same as the ProjectionInverseRetraction on the real Sphere.
source
ManifoldsBase.parallel_transport_direction — Method
parallel_transport_direction(M::AbstractProjectiveSpace, p, X, d)
Parallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M along the geodesic in the direction indicated by the tangent vector d, i.e.
\[\mathcal{P}_{\exp_p (d) ← p}(X) = X - \left(p \frac{\sin θ}{θ} + d \frac{1 - \cos θ}{θ^2}\right) ⟨d, X⟩_p,\]
where $θ = \lVert d \rVert$, and $⟨⋅, ⋅⟩_p$ is the inner product at the point $p$. For the real projective space, this is equivalent to the same vector transport on the real AbstractSphere.
source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::AbstractProjectiveSpace, p, X, q)
Parallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M$=𝔽ℙ^n$ to the tangent space at another point q.
This implementation proceeds by transporting $X$ to $T_{q λ} M$ using the same approach as parallel_transport_direction, where $λ = \frac{⟨q, p⟩_{\mathrm{F}}}{|⟨q, p⟩_{\mathrm{F}}|} ∈ 𝔽$ is the unit scalar that takes $q$ to the member $q λ$ of its equivalence class $[q]$ closest to $p$ in the embedding. It then maps the transported vector from $T_{q λ} M$ to $T_{q} M$. The resulting transport to $T_{q} M$ is
\[\mathcal{P}_{q ← p}(X) = \left(X - \left(p \frac{\sin θ}{θ} + d \frac{1 - \cos θ}{θ^2}\right) ⟨d, X⟩_p\right) \overline{λ},\]
where $d = \log_p q$ is the direction of the transport, $θ = \lVert d \rVert_p$ is the distance between $p$ and $q$, and $\overline{⋅}$ denotes complex or quaternionic conjugation.
source
ManifoldsBase.project — Method
project(M::AbstractProjectiveSpace, p, X)
Orthogonally project the point X onto the tangent space at p on the AbstractProjectiveSpace M:
\[\operatorname{proj}_p (X) = X - p⟨p, X⟩_{\mathrm{F}},\]
where $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product. For the real AbstractSphere and AbstractProjectiveSpace, this projection is the same.
source
ManifoldsBase.project — Method
project(M::AbstractProjectiveSpace, p)
Orthogonally project the point p from the embedding onto the AbstractProjectiveSpace M:
\[\operatorname{proj}(p) = \frac{p}{\lVert p \rVert}_{\mathrm{F}},\]
where $\lVert ⋅ \rVert_{\mathrm{F}}$ denotes the Frobenius norm. This is identical to projection onto the AbstractSphere.
source
ManifoldsBase.retract — Method
retract(M::AbstractProjectiveSpace, p, X, method::ProjectionRetraction)
 retract(M::AbstractProjectiveSpace, p, X, method::PolarRetraction)
-retract(M::AbstractProjectiveSpace, p, X, method::QRRetraction)
Compute the equivalent retraction ProjectionRetraction, PolarRetraction, and QRRetraction on the AbstractProjectiveSpace manifold M$=𝔽ℙ^n$, i.e.
\[\operatorname{retr}_p X = \operatorname{proj}_p(p + X).\]
Note that this retraction is equivalent to the three corresponding retractions on Grassmann(n+1,1,𝔽), where in this case they coincide. For $ℝℙ^n$, it is the same as the ProjectionRetraction on the real Sphere.
source
Statistics.mean — Method
mean(
+retract(M::AbstractProjectiveSpace, p, X, method::QRRetraction)
Compute the equivalent retraction ProjectionRetraction, PolarRetraction, and QRRetraction on the AbstractProjectiveSpace manifold M$=𝔽ℙ^n$, i.e.
\[\operatorname{retr}_p X = \operatorname{proj}_p(p + X).\]
Note that this retraction is equivalent to the three corresponding retractions on Grassmann(n+1,1,𝔽), where in this case they coincide. For $ℝℙ^n$, it is the same as the ProjectionRetraction on the real Sphere.
source

+)

Compute the Riemannian mean of points in vector x using GeodesicInterpolationWithinRadius.

source
diff --git a/previews/PR628/manifolds/quotient.html b/previews/PR628/manifolds/quotient.html index 22c2738dce..d5f2992790 100644 --- a/previews/PR628/manifolds/quotient.html +++ b/previews/PR628/manifolds/quotient.html @@ -1,4 +1,4 @@ -Quotient manifold · Manifolds.jl
Edit on GitHub

Quotient manifold

Manifolds.QuotientManifold — Type
QuotientManifold{M <: AbstractManifold{𝔽}, N} <: AbstractManifold{𝔽}

Equip a manifold $\mathcal M$ explicitly with the property of being a quotient manifold.

A manifold $\mathcal M$ is then a a quotient manifold of another manifold $\mathcal N$, i.e. for an equivalence relation $∼$ on $\mathcal N$ we have

\[ \mathcal M = \mathcal N / ∼ = \bigl\{ [p] : p ∈ \mathcal N \bigr\},\]

where $[p] ≔ \{ q ∈ \mathcal N : q ∼ p\}$ denotes the equivalence class containing $p$. For more details see Subsection 3.4.1[AbsilMahonySepulchre2008].

This manifold type models an explicit quotient structure. This should be done if either the default implementation of $\mathcal M$ uses another representation different from the quotient structure or if it provides a (default) quotient structure that is different from the one introduced here.

Fields

  • manifold – the manifold $\mathcal M$ in the introduction above.
  • total_space – the manifold $\mathcal N$ in the introduction above.

Constructor

QuotientManifold(M,N)

Create a manifold where M is the quotient manifold and Nis its total space.

source

Provided functions

Manifolds.canonical_project — Method
canonical_project(M, p)

Compute the canonical projection $π$ on a manifold $\mathcal M$ that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection $π$ from the total space $\mathcal N$ onto $\mathcal M$ given by

\[ π = π_{\mathcal N, \mathcal M} : \mathcal N → \mathcal M, p ↦ π_{\mathcal N, \mathcal M}(p) = [p].\]

in other words, this function implicitly assumes, that the total space $\mathcal N$ is given, for example explicitly when M is a QuotientManifold and p is a point on N.

source
Manifolds.differential_canonical_project — Method
differential_canonical_project(M, p, X)

Compute the differential of the canonical projection $π$ on a manifold $\mathcal M$ that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection $π$ from the total space $\mathcal N$ onto $\mathcal M$, such that its differential

\[ Dπ(p) : T_p\mathcal N → T_{π(p)}\mathcal M\]

where again the total space might be implicitly assumed, or explicitly when using a QuotientManifold M. So here p is a point on N and X is from $T_p\mathcal N$.

source
Manifolds.get_orbit_action — Method
get_orbit_action(M::AbstractDecoratorManifold)

Return the group action that generates the orbit of an equivalence class of the quotient manifold M for which equivalence classes are orbits of an action of a Lie group. For the case that

\[\mathcal M = \mathcal N / \mathcal O,\]

where $\mathcal O$ is a Lie group with its group action generating the orbit.

source
Manifolds.horizontal_component — Method
horizontal_component(N::AbstractManifold, p, X)

Compute the horizontal component of tangent vector X at point p in the total space of quotient manifold N.

source
Manifolds.horizontal_lift — Method
horizontal_lift(N::AbstractManifold, q, X)
-horizontal_lift(::QuotientManifold{𝔽,MT<:AbstractManifold{𝔽},NT<:AbstractManifold}, p, X) where {𝔽}

Given a point q in total space of quotient manifold N such that $p=π(q)$ is a point on a quotient manifold M (implicitly given for the first case) and a tangent vector X this method computes a tangent vector Y on the horizontal space of $T_q\mathcal N$, i.e. the subspace that is orthogonal to the kernel of $Dπ(q)$.

source
Manifolds.vertical_component — Method
vertical_component(N::AbstractManifold, p, X)

Compute the vertical component of tangent vector X at point p in the total space of quotient manifold N.

source
+Quotient manifold · Manifolds.jl
Edit on GitHub

Quotient manifold

Manifolds.QuotientManifold — Type
QuotientManifold{M <: AbstractManifold{𝔽}, N} <: AbstractManifold{𝔽}

Equip a manifold $\mathcal M$ explicitly with the property of being a quotient manifold.

A manifold $\mathcal M$ is then a a quotient manifold of another manifold $\mathcal N$, i.e. for an equivalence relation $∼$ on $\mathcal N$ we have

\[ \mathcal M = \mathcal N / ∼ = \bigl\{ [p] : p ∈ \mathcal N \bigr\},\]

where $[p] ≔ \{ q ∈ \mathcal N : q ∼ p\}$ denotes the equivalence class containing $p$. For more details see Subsection 3.4.1[AbsilMahonySepulchre2008].

This manifold type models an explicit quotient structure. This should be done if either the default implementation of $\mathcal M$ uses another representation different from the quotient structure or if it provides a (default) quotient structure that is different from the one introduced here.

Fields

  • manifold – the manifold $\mathcal M$ in the introduction above.
  • total_space – the manifold $\mathcal N$ in the introduction above.

Constructor

QuotientManifold(M,N)

Create a manifold where M is the quotient manifold and Nis its total space.

source

Provided functions

Manifolds.canonical_project — Method
canonical_project(M, p)

Compute the canonical projection $π$ on a manifold $\mathcal M$ that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection $π$ from the total space $\mathcal N$ onto $\mathcal M$ given by

\[ π = π_{\mathcal N, \mathcal M} : \mathcal N → \mathcal M, p ↦ π_{\mathcal N, \mathcal M}(p) = [p].\]

in other words, this function implicitly assumes, that the total space $\mathcal N$ is given, for example explicitly when M is a QuotientManifold and p is a point on N.

source
Manifolds.differential_canonical_project — Method
differential_canonical_project(M, p, X)

Compute the differential of the canonical projection $π$ on a manifold $\mathcal M$ that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection $π$ from the total space $\mathcal N$ onto $\mathcal M$, such that its differential

\[ Dπ(p) : T_p\mathcal N → T_{π(p)}\mathcal M\]

where again the total space might be implicitly assumed, or explicitly when using a QuotientManifold M. So here p is a point on N and X is from $T_p\mathcal N$.

source
Manifolds.get_orbit_action — Method
get_orbit_action(M::AbstractDecoratorManifold)

Return the group action that generates the orbit of an equivalence class of the quotient manifold M for which equivalence classes are orbits of an action of a Lie group. For the case that

\[\mathcal M = \mathcal N / \mathcal O,\]

where $\mathcal O$ is a Lie group with its group action generating the orbit.

source
Manifolds.horizontal_component — Method
horizontal_component(N::AbstractManifold, p, X)

Compute the horizontal component of tangent vector X at point p in the total space of quotient manifold N.

source
Manifolds.horizontal_lift — Method
horizontal_lift(N::AbstractManifold, q, X)
+horizontal_lift(::QuotientManifold{𝔽,MT<:AbstractManifold{𝔽},NT<:AbstractManifold}, p, X) where {𝔽}

Given a point q in total space of quotient manifold N such that $p=π(q)$ is a point on a quotient manifold M (implicitly given for the first case) and a tangent vector X this method computes a tangent vector Y on the horizontal space of $T_q\mathcal N$, i.e. the subspace that is orthogonal to the kernel of $Dπ(q)$.

source
Manifolds.vertical_component — Method
vertical_component(N::AbstractManifold, p, X)

Compute the vertical component of tangent vector X at point p in the total space of quotient manifold N.

source
diff --git a/previews/PR628/manifolds/rotations.html b/previews/PR628/manifolds/rotations.html index ff15388c17..b25aa7b4d2 100644 --- a/previews/PR628/manifolds/rotations.html +++ b/previews/PR628/manifolds/rotations.html @@ -1,5 +1,5 @@ Rotations · Manifolds.jl
Edit on GitHub

Rotations

The manifold $\mathrm{SO}(n)$ of orthogonal matrices with determinant $+1$ in $ℝ^{n × n}$, i.e.

\[\mathrm{SO}(n) = \bigl\{R ∈ ℝ^{n × n} \big| R R^{\mathrm{T}} = -R^{\mathrm{T}}R = I_n, \det(R) = 1 \bigr\}\]

The Lie group $\mathrm{SO}(n)$ is a subgroup of the orthogonal group $\mathrm{O}(n)$ and also known as the special orthogonal group or the set of rotations group. See also SpecialOrthogonal, which is this manifold equipped with the group operation.

The tangent space to a point $p ∈ \mathrm{SO}(n)$ is given by

\[T_p\mathrm{SO}(n) = \{X : X=pY,\qquad Y=-Y^{\mathrm{T}}\},\]

i.e. all vectors that are a product of a skew symmetric matrix multiplied with $p$.

Since the orthogonal matrices $\mathrm{SO}(n)$ are a Lie group, tangent vectors can also be represented by elements of the corresponding Lie algebra, which is the tangent space at the identity element. In the notation above, this means we just store the component $Y$ of $X$.

This convention allows for more efficient operations on tangent vectors. Tangent spaces at different points are different vector spaces.

Let $L_R: \mathrm{SO}(n) → \mathrm{SO}(n)$ where $R ∈ \mathrm{SO}(n)$ be the left-multiplication by $R$, that is $L_R(S) = RS$. The tangent space at rotation $R$, $T_R \mathrm{SO}(n)$, is related to the tangent space at the identity rotation $I_n$ by the differential of $L_R$ at identity, $(\mathrm{d}L_R)_{I_n} : T_{I_n} \mathrm{SO}(n) → T_R \mathrm{SO}(n)$. To convert the tangent vector representation at the identity rotation $X ∈ T_{I_n} \mathrm{SO}(n)$ (i.e., the default) to the matrix representation of the corresponding tangent vector $Y$ at a rotation $R$ use the embed which implements the following multiplication: $Y = RX ∈ T_R \mathrm{SO}(n)$. You can compare the functions log and exp to see how it works in practice.

Several common functions are also implemented together with orthogonal and unitary matrices.

Manifolds.Rotations — Type
Rotations{N} <: AbstractManifold{ℝ}

The manifold of rotation matrices of sice $n × n$, i.e. real-valued orthogonal matrices with determinant $+1$.

Constructor

Rotations(n)

Generate the manifold of $n × n$ rotation matrices.

source
Manifolds.angles_4d_skew_sym_matrix — Method
angles_4d_skew_sym_matrix(A)

The Lie algebra of Rotations(4) in $ℝ^{4 × 4}$, $𝔰𝔬(4)$, consists of $4 × 4$ skew-symmetric matrices. The unique imaginary components of their eigenvalues are the angles of the two plane rotations. This function computes these more efficiently than eigvals.

By convention, the returned values are sorted in decreasing order (corresponding to the same ordering of angles as cos_angles_4d_rotation_matrix).

source
Manifolds.normal_rotation_distribution — Method
normal_rotation_distribution(M::Rotations, p, σ::Real)

Return a random point on the manifold Rotations M by generating a (Gaussian) random orthogonal matrix with determinant $+1$. Let

\[QR = A\]

be the QR decomposition of a random matrix $A$, then the formula reads

\[p = QD\]

where $D$ is a diagonal matrix with the signs of the diagonal entries of $R$, i.e.

\[D_{ij}=\begin{cases} \operatorname{sgn}(R_{ij}) & \text{if} \; i=j \\ 0 & \, \text{otherwise} \end{cases}.\]

It can happen that the matrix gets -1 as a determinant. In this case, the first and second columns are swapped.

The argument p is used to determine the type of returned points.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M, p, q, ::PolarInverseRetraction)

Compute a vector from the tangent space $T_p\mathrm{SO}(n)$ of the point p on the Rotations manifold M with which the point q can be reached by the PolarRetraction from the point p after time 1.

The formula reads

\[\operatorname{retr}^{-1}_p(q) -= -\frac{1}{2}(p^{\mathrm{T}}qs - (p^{\mathrm{T}}qs)^{\mathrm{T}})\]

where $s$ is the solution to the Sylvester equation

\[p^{\mathrm{T}}qs + s(p^{\mathrm{T}}q)^{\mathrm{T}} + 2I_n = 0.\]

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Rotations, p, q, ::QRInverseRetraction)

Compute a vector from the tangent space $T_p\mathrm{SO}(n)$ of the point p on the Rotations manifold M with which the point q can be reached by the QRRetraction from the point q after time 1.

source
ManifoldsBase.parallel_transport_direction — Method
parallel_transport_direction(M::Rotations, p, X, d)

Compute parallel transport of vector X tangent at p on the Rotations manifold in the direction d. The formula, provided in [Rentmeesters2011], reads:

\[\mathcal P_{q\gets p}X = q^\mathrm{T}p \operatorname{Exp}(d/2) X \operatorname{Exp}(d/2)\]

where $q=\exp_p d$.

The formula simplifies to identity for 2-D rotations.

source
ManifoldsBase.project — Method
project(M::Rotations, p; check_det = true)

Project p to the nearest point on manifold M.

Given the singular value decomposition $p = U Σ V^\mathrm{T}$, with the singular values sorted in descending order, the projection is

\[\operatorname{proj}_{\mathrm{SO}(n)}(p) = -U\operatorname{diag}\left[1,1,…,\det(U V^\mathrm{T})\right] V^\mathrm{T}\]

The diagonal matrix ensures that the determinant of the result is $+1$. If p is expected to be almost special orthogonal, then you may avoid this check with check_det = false.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::Rotations, p)

Return the zero tangent vector from the tangent space art p on the Rotations as an element of the Lie group, i.e. the zero matrix.

source

Literature

  • Rentmeesters2011

    Rentmeesters Q., “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.

+R^{\mathrm{T}}R = I_n, \det(R) = 1 \bigr\}\]

The Lie group $\mathrm{SO}(n)$ is a subgroup of the orthogonal group $\mathrm{O}(n)$ and also known as the special orthogonal group or the set of rotations group. See also SpecialOrthogonal, which is this manifold equipped with the group operation.

The tangent space to a point $p ∈ \mathrm{SO}(n)$ is given by

\[T_p\mathrm{SO}(n) = \{X : X=pY,\qquad Y=-Y^{\mathrm{T}}\},\]

i.e. all vectors that are a product of a skew symmetric matrix multiplied with $p$.

Since the orthogonal matrices $\mathrm{SO}(n)$ are a Lie group, tangent vectors can also be represented by elements of the corresponding Lie algebra, which is the tangent space at the identity element. In the notation above, this means we just store the component $Y$ of $X$.

This convention allows for more efficient operations on tangent vectors. Tangent spaces at different points are different vector spaces.

Let $L_R: \mathrm{SO}(n) → \mathrm{SO}(n)$ where $R ∈ \mathrm{SO}(n)$ be the left-multiplication by $R$, that is $L_R(S) = RS$. The tangent space at rotation $R$, $T_R \mathrm{SO}(n)$, is related to the tangent space at the identity rotation $I_n$ by the differential of $L_R$ at identity, $(\mathrm{d}L_R)_{I_n} : T_{I_n} \mathrm{SO}(n) → T_R \mathrm{SO}(n)$. To convert the tangent vector representation at the identity rotation $X ∈ T_{I_n} \mathrm{SO}(n)$ (i.e., the default) to the matrix representation of the corresponding tangent vector $Y$ at a rotation $R$ use the embed which implements the following multiplication: $Y = RX ∈ T_R \mathrm{SO}(n)$. You can compare the functions log and exp to see how it works in practice.

Several common functions are also implemented together with orthogonal and unitary matrices.

Manifolds.NormalRotationDistribution — Type
NormalRotationDistribution(M::Rotations, d::Distribution, x::TResult)

Distribution that returns a random point on the manifold Rotations M. Random point is generated using base distribution d and the type of the result is adjusted to TResult.

See normal_rotation_distribution for details.

source
Manifolds.Rotations — Type
Rotations{N} <: AbstractManifold{ℝ}

The manifold of rotation matrices of sice $n × n$, i.e. real-valued orthogonal matrices with determinant $+1$.

Constructor

Rotations(n)

Generate the manifold of $n × n$ rotation matrices.

source
Manifolds.angles_4d_skew_sym_matrix — Method
angles_4d_skew_sym_matrix(A)

The Lie algebra of Rotations(4) in $ℝ^{4 × 4}$, $𝔰𝔬(4)$, consists of $4 × 4$ skew-symmetric matrices. The unique imaginary components of their eigenvalues are the angles of the two plane rotations. This function computes these more efficiently than eigvals.

By convention, the returned values are sorted in decreasing order (corresponding to the same ordering of angles as cos_angles_4d_rotation_matrix).

source
Manifolds.normal_rotation_distribution — Method
normal_rotation_distribution(M::Rotations, p, σ::Real)

Return a random point on the manifold Rotations M by generating a (Gaussian) random orthogonal matrix with determinant $+1$. Let

\[QR = A\]

be the QR decomposition of a random matrix $A$, then the formula reads

\[p = QD\]

where $D$ is a diagonal matrix with the signs of the diagonal entries of $R$, i.e.

\[D_{ij}=\begin{cases} \operatorname{sgn}(R_{ij}) & \text{if} \; i=j \\ 0 & \, \text{otherwise} \end{cases}.\]

It can happen that the matrix gets -1 as a determinant. In this case, the first and second columns are swapped.

The argument p is used to determine the type of returned points.

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(M::Rotations, ::PolarRetraction)

Return the radius of injectivity for the PolarRetraction on the Rotations M which is $\frac{π}{\sqrt{2}}$.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M, p, q, ::PolarInverseRetraction)

Compute a vector from the tangent space $T_p\mathrm{SO}(n)$ of the point p on the Rotations manifold M with which the point q can be reached by the PolarRetraction from the point p after time 1.

The formula reads

\[\operatorname{retr}^{-1}_p(q) += -\frac{1}{2}(p^{\mathrm{T}}qs - (p^{\mathrm{T}}qs)^{\mathrm{T}})\]

where $s$ is the solution to the Sylvester equation

\[p^{\mathrm{T}}qs + s(p^{\mathrm{T}}q)^{\mathrm{T}} + 2I_n = 0.\]

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Rotations, p, q, ::QRInverseRetraction)

Compute a vector from the tangent space $T_p\mathrm{SO}(n)$ of the point p on the Rotations manifold M with which the point q can be reached by the QRRetraction from the point q after time 1.

source
ManifoldsBase.parallel_transport_direction — Method
parallel_transport_direction(M::Rotations, p, X, d)

Compute parallel transport of vector X tangent at p on the Rotations manifold in the direction d. The formula, provided in [Rentmeesters2011], reads:

\[\mathcal P_{q\gets p}X = q^\mathrm{T}p \operatorname{Exp}(d/2) X \operatorname{Exp}(d/2)\]

where $q=\exp_p d$.

The formula simplifies to identity for 2-D rotations.

source
ManifoldsBase.project — Method
project(M::Rotations, p; check_det = true)

Project p to the nearest point on manifold M.

Given the singular value decomposition $p = U Σ V^\mathrm{T}$, with the singular values sorted in descending order, the projection is

\[\operatorname{proj}_{\mathrm{SO}(n)}(p) = +U\operatorname{diag}\left[1,1,…,\det(U V^\mathrm{T})\right] V^\mathrm{T}\]

The diagonal matrix ensures that the determinant of the result is $+1$. If p is expected to be almost special orthogonal, then you may avoid this check with check_det = false.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::Rotations, p)

Return the zero tangent vector from the tangent space art p on the Rotations as an element of the Lie group, i.e. the zero matrix.

source

Literature

diff --git a/previews/PR628/manifolds/shapespace.html b/previews/PR628/manifolds/shapespace.html index 29bd522991..e9d1685608 100644 --- a/previews/PR628/manifolds/shapespace.html +++ b/previews/PR628/manifolds/shapespace.html @@ -22,57 +22,57 @@ scatter!(fig, rot_q[1,:], rot_q[2,:], label="q aligned to p") - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

A more extensive usage example is available in the hand_gestures.jl tutorial.

Manifolds.KendallsPreShapeSpace — Type
KendallsPreShapeSpace{n,k} <: AbstractSphere{ℝ}

Kendall's pre-shape space of $k$ landmarks in $ℝ^n$ represented by n×k matrices. In each row the sum of elements of a matrix is equal to 0. The Frobenius norm of the matrix is equal to 1 [Kendall1984][Kendall1989].

The space can be interpreted as tuples of $k$ points in $ℝ^n$ up to simultaneous translation and scaling of all points, so this can be thought of as a quotient manifold.

Constructor

KendallsPreShapeSpace(n::Int, k::Int)

See also

KendallsShapeSpace, esp. for the references

source
Manifolds.KendallsShapeSpace — Type
KendallsShapeSpace{n,k} <: AbstractDecoratorManifold{ℝ}

Kendall's shape space, defined as quotient of a KendallsPreShapeSpace (represented by n×k matrices) by the action ColumnwiseMultiplicationAction.

The space can be interpreted as tuples of $k$ points in $ℝ^n$ up to simultaneous translation and scaling and rotation of all points [Kendall1984][Kendall1989].

This manifold possesses the IsQuotientManifold trait.

Constructor

KendallsShapeSpace(n::Int, k::Int)

References

source

Provided functions

ManifoldsBase.check_point — Method
check_point(M::KendallsPreShapeSpace, p; atol=sqrt(max_eps(X, Y)), kwargs...)

Check whether p is a valid point on KendallsPreShapeSpace, i.e. whether each row has zero mean. Other conditions are checked via embedding in ArraySphere.

source
ManifoldsBase.check_vector — Method
check_vector(M::KendallsPreShapeSpace, p, X; kwargs... )

Check whether X is a valid tangent vector on KendallsPreShapeSpace, i.e. whether each row has zero mean. Other conditions are checked via embedding in ArraySphere.

source
ManifoldsBase.get_embedding — Method
get_embedding(M::KendallsPreShapeSpace)

Return the space KendallsPreShapeSpace M is embedded in, i.e. ArraySphere of matrices of the same shape.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::KendallsPreShapeSpace)

Return the dimension of the KendallsPreShapeSpace manifold M. The dimension is given by $n(k - 1) - 1$.

source
ManifoldsBase.project — Method
project(M::KendallsPreShapeSpace, p, X)

Project tangent vector X at point p from the embedding to KendallsPreShapeSpace by selecting the right element from the tangent space to orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.

References

source
ManifoldsBase.project — Method
project(M::KendallsPreShapeSpace, p)

Project point p from the embedding to KendallsPreShapeSpace by selecting the right element from the orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.

The method computes the mean of the landmarks and moves them to make their mean zero; afterwards the Frobenius norm of the landmarks (as a matrix) is normalised to fix the scaling.

source
Base.exp — Method
exp(M::KendallsShapeSpace, p, X)

Compute the exponential map on KendallsShapeSpace M. See [Guigui2021] for discussion about its computation.

source
Base.log — Method
log(M::KendallsShapeSpace, p, q)

Compute the logarithmic map on KendallsShapeSpace M. See the [exp](@ref exp(::KendallsShapeSpace, ::Any, ::Any)onential map for more details

source
Base.rand — Method
rand(::KendallsShapeSpace; vector_at=nothing)

When vector_at is nothing, return a random point x on the KendallsShapeSpace manifold M by generating a random point in the embedding.

When vector_at is not nothing, return a random vector from the tangent space with mean zero and standard deviation σ.

source
Manifolds.get_total_space — Method
get_total_space(::Grassmann{n,k})

Return the total space of the KendallsShapeSpace manifold, which is the KendallsPreShapeSpace manifold.

source
Manifolds.horizontal_component — Method
horizontal_component(::KendallsShapeSpace, p, X)

Compute the horizontal component of tangent vector X at p on KendallsShapeSpace M. See [Guigui2021], Section 2.3 for details.

source
ManifoldsBase.get_embedding — Method
get_embedding(M::KendallsShapeSpace)

Get the manifold in which KendallsShapeSpace M is embedded, i.e. KendallsPreShapeSpace of matrices of the same shape.

source
ManifoldsBase.is_flat — Method
is_flat(::KendallsShapeSpace)

Return false. KendallsShapeSpace is not a flat manifold.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::KendallsShapeSpace)

Return the dimension of the KendallsShapeSpace manifold M. The dimension is given by $n(k - 1) - 1 - n(n - 1)/2$ in the typical case where $k \geq n+1$, and $(k + 1)(k - 2) / 2$ otherwise, unless $k$ is equal to 1, in which case the dimension is 0. See [Kendall1984] for a discussion of the over-dimensioned case.

source
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

A more extensive usage example is available in the hand_gestures.jl tutorial.

Manifolds.KendallsPreShapeSpace — Type
KendallsPreShapeSpace{n,k} <: AbstractSphere{ℝ}

Kendall's pre-shape space of $k$ landmarks in $ℝ^n$ represented by n×k matrices. In each row the sum of elements of a matrix is equal to 0. The Frobenius norm of the matrix is equal to 1 [Kendall1984][Kendall1989].

The space can be interpreted as tuples of $k$ points in $ℝ^n$ up to simultaneous translation and scaling of all points, so this can be thought of as a quotient manifold.

Constructor

KendallsPreShapeSpace(n::Int, k::Int)

See also

KendallsShapeSpace, esp. for the references

source
Manifolds.KendallsShapeSpace — Type
KendallsShapeSpace{n,k} <: AbstractDecoratorManifold{ℝ}

Kendall's shape space, defined as quotient of a KendallsPreShapeSpace (represented by n×k matrices) by the action ColumnwiseMultiplicationAction.

The space can be interpreted as tuples of $k$ points in $ℝ^n$ up to simultaneous translation and scaling and rotation of all points [Kendall1984][Kendall1989].

This manifold possesses the IsQuotientManifold trait.

Constructor

KendallsShapeSpace(n::Int, k::Int)

References

source

Provided functions

ManifoldsBase.project — Method
project(M::KendallsPreShapeSpace, p, X)

Project tangent vector X at point p from the embedding to KendallsPreShapeSpace by selecting the right element from the tangent space to orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.

References

source
ManifoldsBase.project — Method
project(M::KendallsPreShapeSpace, p)

Project point p from the embedding to KendallsPreShapeSpace by selecting the right element from the orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.

The method computes the mean of the landmarks and moves them to make their mean zero; afterwards the Frobenius norm of the landmarks (as a matrix) is normalised to fix the scaling.

source
Base.log — Method
log(M::KendallsShapeSpace, p, q)

Compute the logarithmic map on KendallsShapeSpace M. See the [exp](@ref exp(::KendallsShapeSpace, ::Any, ::Any)onential map for more details

source
Base.rand — Method
rand(::KendallsShapeSpace; vector_at=nothing)

When vector_at is nothing, return a random point x on the KendallsShapeSpace manifold M by generating a random point in the embedding.

When vector_at is not nothing, return a random vector from the tangent space with mean zero and standard deviation σ.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::KendallsShapeSpace)

Return the dimension of the KendallsShapeSpace manifold M. The dimension is given by $n(k - 1) - 1 - n(n - 1)/2$ in the typical case where $k \geq n+1$, and $(k + 1)(k - 2) / 2$ otherwise, unless $k$ is equal to 1, in which case the dimension is 0. See [Kendall1984] for a discussion of the over-dimensioned case.

source
  • Kendall1989

    D. G. Kendall, “A Survey of the Statistical Theory of Shape,” Statist. Sci., vol. 4, no. 2, pp. 87–99, May 1989 doi: 10.1214/ss/1177012582.

  • Kendall1984

    D. G. Kendall, “Shape Manifolds, Procrustean Metrics, and Complex Projective Spaces,” Bull. London Math. Soc., vol. 16, no. 2, pp. 81–121, Mar. 1984 doi: 10.1112/blms/16.2.81.

  • Srivastava2016

    A. Srivastava and E. P. Klassen, Functional and Shape Data Analysis. Springer New York, 2016. ISBN: 978-1-4939-4018-9. doi: 10.1007/978-1-4939-4020-2.

  • Guigui2021

    N. Guigui, E. Maignant, A. Trouvé, and X. Pennec, “Parallel Transport on Kendall Shape Spaces,” in Geometric Science of Information, Cham, 2021, pp. 103–110. doi: 10.1007/978-3-030-80209-7_12.

diff --git a/previews/PR628/manifolds/skewhermitian.html b/previews/PR628/manifolds/skewhermitian.html index ddc8bab7fe..032d726434 100644 --- a/previews/PR628/manifolds/skewhermitian.html +++ b/previews/PR628/manifolds/skewhermitian.html @@ -1,2 +1,2 @@ -Skew-Hermitian matrices · Manifolds.jl
Edit on GitHub

Skew-hermitian matrices

Manifolds.SkewHermitianMatrices — Type
SkewHermitianMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}

The AbstractManifold $ \operatorname{SkewHerm}(n)$ consisting of the real- or complex-valued skew-hermitian matrices of size $n × n$, i.e. the set

\[\operatorname{SkewHerm}(n) = \bigl\{p ∈ 𝔽^{n × n}\ \big|\ p^{\mathrm{H}} = -p \bigr\},\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose, and the field $𝔽 ∈ \{ ℝ, ℂ, ℍ\}$.

Though it is slightly redundant, usually the matrices are stored as $n × n$ arrays.

Note that in this representation, the real-valued part of the diagonal must be zero, which is also reflected in the manifold_dimension.

Constructor

SkewHermitianMatrices(n::Int, field::AbstractNumbers=ℝ)

Generate the manifold of $n × n$ skew-hermitian matrices.

source
ManifoldsBase.check_point — Method
check_point(M::SkewHermitianMatrices{n,𝔽}, p; kwargs...)

Check whether p is a valid manifold point on the SkewHermitianMatrices M, i.e. whether p is a skew-hermitian matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.

The tolerance for the skew-symmetry of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SkewHermitianMatrices{n}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SkewHermitianMatrices M, i.e. X must be a skew-hermitian matrix of size (n,n) and its values have to be from the correct AbstractNumbers. The tolerance for the skew-symmetry of p and X can be set using kwargs....

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SkewHermitianMatrices{n,𝔽})

Return the dimension of the SkewHermitianMatrices matrix M over the number system 𝔽, i.e.

\[\dim \mathrm{SkewHerm}(n,ℝ) = \frac{n(n+1)}{2} \dim_ℝ 𝔽 - n,\]

where $\dim_ℝ 𝔽$ is the real_dimension of $𝔽$. The first term corresponds to only the upper triangular elements of the matrix being unique, and the second term corresponds to the constraint that the real part of the diagonal be zero.

source
ManifoldsBase.project — Method
project(M::SkewHermitianMatrices, p, X)

Project the matrix X onto the tangent space at p on the SkewHermitianMatrices M,

\[\operatorname{proj}_p(X) = \frac{1}{2} \bigl( X - X^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::SkewHermitianMatrices, p)

Projects p from the embedding onto the SkewHermitianMatrices M, i.e.

\[\operatorname{proj}_{\operatorname{SkewHerm}(n)}(p) = \frac{1}{2} \bigl( p - p^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
+Skew-Hermitian matrices · Manifolds.jl
Edit on GitHub

Skew-hermitian matrices

Manifolds.SkewHermitianMatrices — Type
SkewHermitianMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}

The AbstractManifold $ \operatorname{SkewHerm}(n)$ consisting of the real- or complex-valued skew-hermitian matrices of size $n × n$, i.e. the set

\[\operatorname{SkewHerm}(n) = \bigl\{p ∈ 𝔽^{n × n}\ \big|\ p^{\mathrm{H}} = -p \bigr\},\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose, and the field $𝔽 ∈ \{ ℝ, ℂ, ℍ\}$.

Though it is slightly redundant, usually the matrices are stored as $n × n$ arrays.

Note that in this representation, the real-valued part of the diagonal must be zero, which is also reflected in the manifold_dimension.

Constructor

SkewHermitianMatrices(n::Int, field::AbstractNumbers=ℝ)

Generate the manifold of $n × n$ skew-hermitian matrices.

source
ManifoldsBase.check_point — Method
check_point(M::SkewHermitianMatrices{n,𝔽}, p; kwargs...)

Check whether p is a valid manifold point on the SkewHermitianMatrices M, i.e. whether p is a skew-hermitian matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.

The tolerance for the skew-symmetry of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SkewHermitianMatrices{n}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SkewHermitianMatrices M, i.e. X must be a skew-hermitian matrix of size (n,n) and its values have to be from the correct AbstractNumbers. The tolerance for the skew-symmetry of p and X can be set using kwargs....

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SkewHermitianMatrices{n,𝔽})

Return the dimension of the SkewHermitianMatrices matrix M over the number system 𝔽, i.e.

\[\dim \mathrm{SkewHerm}(n,ℝ) = \frac{n(n+1)}{2} \dim_ℝ 𝔽 - n,\]

where $\dim_ℝ 𝔽$ is the real_dimension of $𝔽$. The first term corresponds to only the upper triangular elements of the matrix being unique, and the second term corresponds to the constraint that the real part of the diagonal be zero.

source
ManifoldsBase.project — Method
project(M::SkewHermitianMatrices, p, X)

Project the matrix X onto the tangent space at p on the SkewHermitianMatrices M,

\[\operatorname{proj}_p(X) = \frac{1}{2} \bigl( X - X^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::SkewHermitianMatrices, p)

Projects p from the embedding onto the SkewHermitianMatrices M, i.e.

\[\operatorname{proj}_{\operatorname{SkewHerm}(n)}(p) = \frac{1}{2} \bigl( p - p^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
diff --git a/previews/PR628/manifolds/spdfixeddeterminant.html b/previews/PR628/manifolds/spdfixeddeterminant.html index 5ddc2ba7f0..75786a117e 100644 --- a/previews/PR628/manifolds/spdfixeddeterminant.html +++ b/previews/PR628/manifolds/spdfixeddeterminant.html @@ -6,6 +6,6 @@ \bigr\}.\]

This manifold is modelled as a submanifold of SymmetricPositiveDefinite(n).

These matrices are sometimes also called isochoric, which refers to the interpretation of the matrix representing an ellipsoid. All ellipsoids that represent points on this manifold have the same volume.

The tangent space is modelled the same as for SymmetricPositiveDefinite(n) and consists of all symmetric matrices with zero trace

\[ T_p\mathcal P_d(n) = \bigl\{ X \in \mathbb R^{n×n} \big|\ X=X^\mathrm{T} \text{ and } \operatorname{tr}(p) = 0 - \bigr\},\]

since for a constant determinant we require that 0 = D\det(p)[Z] = \det(p)\operatorname{tr}(p^{-1}Z) for all tangent vectors $Z$. Additionally we store the tangent vectors as X=p^{-1}Z, i.e. symmetric matrices.

Constructor

SPDFixedDeterminant(n::Int, d::Real=1.0)

generates the manifold $\mathcal P_d(n) \subset \mathcal P(n)$ of determinant $d$, which defaults to 1.

source

This manifold can is a submanifold of the symmetric positive definite matrices and hence inherits most properties therefrom.

The differences are the functions

ManifoldsBase.check_vector — Method
check_vector(M::SPDFixedDeterminant, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SPDFixedDeterminant M, i.e. X has to be a tangent vector on SymmetricPositiveDefinite, so a symmetric matrix, and additionally fulfill $\operatorname{tr}(X) = 0$.

The tolerance for the trace check of X can be set using kwargs..., which influences the isapprox-check.

source
ManifoldsBase.project — Method
Y = project(M::SPDFixedDeterminant{n}, p, X)
-project!(M::SPDFixedDeterminant{n}, Y, p, X)

Project the symmetric matrix X onto the tangent space at p of the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of Y), by setting its diagonal (and hence its trace) to zero.

source
ManifoldsBase.project — Method
q = project(M::SPDFixedDeterminant{n}, p)
-project!(M::SPDFixedDeterminant{n}, q, p)

Project the symmetric positive definite (s.p.d.) matrix p from the embedding onto the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of q).

The formula reads

\[q = \Bigl(\frac{d}{\det(p)}\Bigr)^{\frac{1}{n}}p\]

source
+ \bigr\},\]

since for a constant determinant we require that 0 = D\det(p)[Z] = \det(p)\operatorname{tr}(p^{-1}Z) for all tangent vectors $Z$. Additionally we store the tangent vectors as X=p^{-1}Z, i.e. symmetric matrices.

Constructor

SPDFixedDeterminant(n::Int, d::Real=1.0)

generates the manifold $\mathcal P_d(n) \subset \mathcal P(n)$ of determinant $d$, which defaults to 1.

source

This manifold can is a submanifold of the symmetric positive definite matrices and hence inherits most properties therefrom.

The differences are the functions

ManifoldsBase.check_vector — Method
check_vector(M::SPDFixedDeterminant, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SPDFixedDeterminant M, i.e. X has to be a tangent vector on SymmetricPositiveDefinite, so a symmetric matrix, and additionally fulfill $\operatorname{tr}(X) = 0$.

The tolerance for the trace check of X can be set using kwargs..., which influences the isapprox-check.

source
ManifoldsBase.project — Method
Y = project(M::SPDFixedDeterminant{n}, p, X)
+project!(M::SPDFixedDeterminant{n}, Y, p, X)

Project the symmetric matrix X onto the tangent space at p of the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of Y), by setting its diagonal (and hence its trace) to zero.

source
ManifoldsBase.project — Method
q = project(M::SPDFixedDeterminant{n}, p)
+project!(M::SPDFixedDeterminant{n}, q, p)

Project the symmetric positive definite (s.p.d.) matrix p from the embedding onto the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of q).

The formula reads

\[q = \Bigl(\frac{d}{\det(p)}\Bigr)^{\frac{1}{n}}p\]

source
diff --git a/previews/PR628/manifolds/spectrahedron.html b/previews/PR628/manifolds/spectrahedron.html index 5a5c3d5301..30628af13e 100644 --- a/previews/PR628/manifolds/spectrahedron.html +++ b/previews/PR628/manifolds/spectrahedron.html @@ -9,4 +9,4 @@ \end{aligned}\]

This manifold is working solely on the matrices $q$. Note that this $q$ is not unique, indeed for any orthogonal matrix $A$ we have $(qA)(qA)^{\mathrm{T}} = qq^{\mathrm{T}} = p$, so the manifold implemented here is the quotient manifold. The unit trace translates to unit frobenius norm of $q$.

The tangent space at $p$, denoted $T_p\mathcal E(n,k)$, is also represented by matrices $Y\in ℝ^{n × k}$ and reads as

\[T_p\mathcal S(n,k) = \bigl\{ X ∈ ℝ^{n × n}\,|\,X = qY^{\mathrm{T}} + Yq^{\mathrm{T}} \text{ with } \operatorname{tr}(X) = \sum_{i=1}^{n}X_{ii} = 0 -\bigr\}\]

endowed with the Euclidean metric from the embedding, i.e. from the $ℝ^{n × k}$

This manifold was for example investigated in[JourneeBachAbsilSepulchre2010].

Constructor

Spectrahedron(n,k)

generates the manifold $\mathcal S(n,k) \subset ℝ^{n × n}$.

source
ManifoldsBase.check_point — Method
check_point(M::Spectrahedron, q; kwargs...)

checks, whether q is a valid reprsentation of a point $p=qq^{\mathrm{T}}$ on the Spectrahedron M, i.e. is a matrix of size (N,K), such that $p$ is symmetric positive semidefinite and has unit trace, i.e. $q$ has to have unit frobenius norm. Since by construction $p$ is symmetric, this is not explicitly checked. Since $p$ is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::Spectrahedron, q, Y; kwargs...)

Check whether $X = qY^{\mathrm{T}} + Yq^{\mathrm{T}}$ is a tangent vector to $p=qq^{\mathrm{T}}$ on the Spectrahedron M, i.e. atfer check_point of q, Y has to be of same dimension as q and a $X$ has to be a symmetric matrix with trace. The tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetry of $X$ holds by construction and is not explicitly checked.

source
ManifoldsBase.project — Method
project(M::Spectrahedron, q, Y)

Project Y onto the tangent space at q, i.e. row-wise onto the Spectrahedron manifold.

source
ManifoldsBase.representation_size — Method
representation_size(M::Spectrahedron)

Return the size of an array representing an element on the Spectrahedron manifold M, i.e. $n × k$, the size of such factor of $p=qq^{\mathrm{T}}$ on $\mathcal M = \mathcal S(n,k)$.

source
ManifoldsBase.retract — Method
retract(M::Spectrahedron, q, Y, ::ProjectionRetraction)

compute a projection based retraction by projecting $q+Y$ back onto the manifold.

source

Literature

+\bigr\}\]

endowed with the Euclidean metric from the embedding, i.e. from the $ℝ^{n × k}$

This manifold was for example investigated in[JourneeBachAbsilSepulchre2010].

Constructor

Spectrahedron(n,k)

generates the manifold $\mathcal S(n,k) \subset ℝ^{n × n}$.

source
ManifoldsBase.check_point — Method
check_point(M::Spectrahedron, q; kwargs...)

checks, whether q is a valid reprsentation of a point $p=qq^{\mathrm{T}}$ on the Spectrahedron M, i.e. is a matrix of size (N,K), such that $p$ is symmetric positive semidefinite and has unit trace, i.e. $q$ has to have unit frobenius norm. Since by construction $p$ is symmetric, this is not explicitly checked. Since $p$ is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::Spectrahedron, q, Y; kwargs...)

Check whether $X = qY^{\mathrm{T}} + Yq^{\mathrm{T}}$ is a tangent vector to $p=qq^{\mathrm{T}}$ on the Spectrahedron M, i.e. atfer check_point of q, Y has to be of same dimension as q and a $X$ has to be a symmetric matrix with trace. The tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetry of $X$ holds by construction and is not explicitly checked.

source
ManifoldsBase.project — Method
project(M::Spectrahedron, q, Y)

Project Y onto the tangent space at q, i.e. row-wise onto the Spectrahedron manifold.

source
ManifoldsBase.representation_size — Method
representation_size(M::Spectrahedron)

Return the size of an array representing an element on the Spectrahedron manifold M, i.e. $n × k$, the size of such factor of $p=qq^{\mathrm{T}}$ on $\mathcal M = \mathcal S(n,k)$.

source
ManifoldsBase.retract — Method
retract(M::Spectrahedron, q, Y, ::ProjectionRetraction)

compute a projection based retraction by projecting $q+Y$ back onto the manifold.

source

Literature

diff --git a/previews/PR628/manifolds/sphere.html b/previews/PR628/manifolds/sphere.html index 073e7a118f..98baf83949 100644 --- a/previews/PR628/manifolds/sphere.html +++ b/previews/PR628/manifolds/sphere.html @@ -1,12 +1,12 @@ -Sphere · Manifolds.jl
Edit on GitHub

Sphere and unit norm arrays

Manifolds.AbstractSphere — Type
AbstractSphere{𝔽} <: AbstractDecoratorManifold{𝔽}

An abstract type to represent a unit sphere that is represented isometrically in the embedding.

source

The classical sphere, i.e. unit norm (real- or complex-valued) vectors can be generated as usual: to create the 2-dimensional sphere (in $ℝ^3$), use Sphere(2) and Sphere(2,ℂ), respectively.

Manifolds.Sphere — Type
Sphere{n,𝔽} <: AbstractSphere{𝔽}

The (unit) sphere manifold $𝕊^{n}$ is the set of all unit norm vectors in $𝔽^{n+1}$. The sphere is represented in the embedding, i.e.

\[𝕊^{n} := \bigl\{ p \in 𝔽^{n+1}\ \big|\ \lVert p \rVert = 1 \bigr\}\]

where $𝔽\in\{ℝ,ℂ,ℍ\}$. Note that compared to the ArraySphere, here the argument n of the manifold is the dimension of the manifold, i.e. $𝕊^{n} ⊂ 𝔽^{n+1}$, $n\in ℕ$.

The tangent space at point $p$ is given by

\[T_p𝕊^{n} := \bigl\{ X ∈ 𝔽^{n+1}\ |\ \Re(⟨p,X⟩) = 0 \bigr \},\]

where $𝔽\in\{ℝ,ℂ,ℍ\}$ and $⟨\cdot,\cdot⟩$ denotes the inner product in the embedding $𝔽^{n+1}$.

For $𝔽=ℂ$, the manifold is the complex sphere, written $ℂ𝕊^n$, embedded in $ℂ^{n+1}$. $ℂ𝕊^n$ is the complexification of the real sphere $𝕊^{2n+1}$. Likewise, the quaternionic sphere $ℍ𝕊^n$ is the quaternionification of the real sphere $𝕊^{4n+3}$. Consequently, $ℂ𝕊^0$ is equivalent to $𝕊^1$ and Circle, while $ℂ𝕊^1$ and $ℍ𝕊^0$ are equivalent to $𝕊^3$, though with different default representations.

This manifold is modeled as a special case of the more general case, i.e. as an embedded manifold to the Euclidean, and several functions like the inner product and the zero_vector are inherited from the embedding.

Constructor

Sphere(n[, field=ℝ])

Generate the (real-valued) sphere $𝕊^{n} ⊂ ℝ^{n+1}$, where field can also be used to generate the complex- and quaternionic-valued sphere.

source

For the higher-dimensional arrays, for example unit (Frobenius) norm matrices, the manifold is generated using the size of the matrix. To create the unit sphere of $3×2$ real-valued matrices, write ArraySphere(3,2) and the complex case is done – as for the Euclidean case – with an keyword argument ArraySphere(3,2; field = ℂ). This case also covers the classical sphere as a special case, but you specify the size of the vectors/embedding instead: The 2-sphere can here be generated ArraySphere(3).

Manifolds.ArraySphere — Type
ArraySphere{T<:Tuple,𝔽} <: AbstractSphere{𝔽}

The (unit) sphere manifold $𝕊^{n₁,n₂,...,nᵢ}$ is the set of all unit (Frobenius) norm elements of $𝔽^{n₁,n₂,...,nᵢ}$, where 𝔽\in{ℝ,ℂ,ℍ}. The generalized sphere is represented in the embedding, and supports arbitrary sized arrays or in other words arbitrary tensors of unit norm. The set formally reads

\[𝕊^{n_1, n_2, …, n_i} := \bigl\{ p \in 𝔽^{n_1, n_2, …, n_i}\ \big|\ \lVert p \rVert = 1 \bigr\}\]

where $𝔽\in\{ℝ,ℂ,ℍ\}$. Setting $i=1$ and $𝔽=ℝ$ this simplifies to unit vectors in $ℝ^n$, see Sphere for this special case. Note that compared to this classical case, the argument for the generalized case here is given by the dimension of the embedding. This means that Sphere(2) and ArraySphere(3) are the same manifold.

The tangent space at point $p$ is given by

\[T_p 𝕊^{n_1, n_2, …, n_i} := \bigl\{ X ∈ 𝔽^{n_1, n_2, …, n_i}\ |\ \Re(⟨p,X⟩) = 0 \bigr \},\]

where $𝔽\in\{ℝ,ℂ,ℍ\}$ and $⟨\cdot,\cdot⟩$ denotes the (Frobenius) inner product in the embedding $𝔽^{n_1, n_2, …, n_i}$.

This manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.

Constructor

ArraySphere(n₁,n₂,...,nᵢ; field=ℝ)

Generate sphere in $𝔽^{n_1, n_2, …, n_i}$, where $𝔽$ defaults to the real-valued case $ℝ$.

source

There is also one atlas available on the sphere.

Manifolds.StereographicAtlas — Type
StereographicAtlas()

The stereographic atlas of $S^n$ with two charts: one with the singular point (-1, 0, ..., 0) (called :north) and one with the singular point (1, 0, ..., 0) (called :south).

source

Functions on unit spheres

Base.exp — Method
exp(M::AbstractSphere, p, X)

Compute the exponential map from p in the tangent direction X on the AbstractSphere M by following the great arc eminating from p in direction X.

\[\exp_p X = \cos(\lVert X \rVert_p)p + \sin(\lVert X \rVert_p)\frac{X}{\lVert X \rVert_p},\]

where $\lVert X \rVert_p$ is the norm on the tangent space at p of the AbstractSphere M.

source
Base.log — Method
log(M::AbstractSphere, p, q)

Compute the logarithmic map on the AbstractSphere M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. The formula reads for $x ≠ -y$

\[\log_p q = d_{𝕊}(p,q) \frac{q-\Re(⟨p,q⟩) p}{\lVert q-\Re(⟨p,q⟩) p \rVert_2},\]

and a deterministic choice from the set of tangent vectors is returned if $x=-y$, i.e. for opposite points.

source
Manifolds.local_metric — Method
local_metric(M::Sphere{n}, p, ::DefaultOrthonormalBasis)

return the local representation of the metric in a DefaultOrthonormalBasis, namely the diagonal matrix of size $n×n$ with ones on the diagonal, since the metric is obtained from the embedding by restriction to the tangent space $T_p\mathcal M$ at $p$.

source
Manifolds.volume_density — Method
volume_density(M::AbstractSphere{ℝ}, p, X)

Compute volume density function of a sphere, i.e. determinant of the differential of exponential map exp(M, p, X). The formula reads $(\sin(\lVert X\rVert)/\lVert X\rVert)^(n-1)$ where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].

source
ManifoldsBase.check_point — Method
check_point(M::AbstractSphere, p; kwargs...)

Check whether p is a valid point on the AbstractSphere M, i.e. is a point in the embedding of unit length. The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractSphere, p, X; kwargs... )

Check whether X is a tangent vector to p on the AbstractSphere M, i.e. after check_point(M,p), X has to be of same dimension as p and orthogonal to p. The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.distance — Method
distance(M::AbstractSphere, p, q)

Compute the geodesic distance betweeen p and q on the AbstractSphere M. The formula is given by the (shorter) great arc length on the (or a) great circle both p and q lie on.

\[d_{𝕊}(p,q) = \arccos(\Re(⟨p,q⟩)).\]

source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)

Represent the tangent vector X at point p from the AbstractSphere M in an orthonormal basis by rotating the hyperplane containing X to a hyperplane whose normal is the $x$-axis.

Given $q = p λ + x$, where $λ = \operatorname{sgn}(⟨x, p⟩)$, and $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, the formula for $Y$ is

\[\begin{pmatrix}0 \\ Y\end{pmatrix} = X - q\frac{2 ⟨q, X⟩_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}.\]

source
ManifoldsBase.get_vector — Method
get_vector(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)

Convert a one-dimensional vector of coefficients X in the basis B of the tangent space at p on the AbstractSphere M to a tangent vector Y at p by rotating the hyperplane containing X, whose normal is the $x$-axis, to the hyperplane whose normal is p.

Given $q = p λ + x$, where $λ = \operatorname{sgn}(⟨x, p⟩)$, and $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, the formula for $Y$ is

\[Y = X - q\frac{2 \left\langle q, \begin{pmatrix}0 \\ X\end{pmatrix}\right\rangle_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}.\]

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::AbstractSphere, p, q, ::ProjectionInverseRetraction)

Compute the inverse of the projection based retraction on the AbstractSphere M, i.e. rearranging $p+X = q\lVert p+X\rVert_2$ yields since $\Re(⟨p,X⟩) = 0$ and when $d_{𝕊^2}(p,q) ≤ \frac{π}{2}$ that

\[\operatorname{retr}_p^{-1}(q) = \frac{q}{\Re(⟨p, q⟩)} - p.\]

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::AbstractSphere, p, X, q)

Compute the parallel transport on the Sphere of the tangent vector X at p to q, provided, the geodesic between p and q is unique. The formula reads

\[P_{p←q}(X) = X - \frac{\Re(⟨\log_p q,X⟩_p)}{d^2_𝕊(p,q)} -\bigl(\log_p q + \log_q p \bigr).\]

source
ManifoldsBase.project — Method
project(M::AbstractSphere, p, X)

Project the point X onto the tangent space at p on the Sphere M.

\[\operatorname{proj}_{p}(X) = X - \Re(⟨p, X⟩)p\]

source
ManifoldsBase.project — Method
project(M::AbstractSphere, p)

Project the point p from the embedding onto the Sphere M.

\[\operatorname{proj}(p) = \frac{p}{\lVert p \rVert},\]

where $\lVert\cdot\rVert$ denotes the usual 2-norm for vectors if $m=1$ and the Frobenius norm for the case $m>1$.

source
ManifoldsBase.retract — Method
retract(M::AbstractSphere, p, X, ::ProjectionRetraction)

Compute the retraction that is based on projection, i.e.

\[\operatorname{retr}_p(X) = \frac{p+X}{\lVert p+X \rVert_2}\]

source
Statistics.mean — Method
mean(
+Sphere · Manifolds.jl
Edit on GitHub
Sphere and unit norm arrays
Manifolds.AbstractSphere — Type
AbstractSphere{𝔽} <: AbstractDecoratorManifold{𝔽}
An abstract type to represent a unit sphere that is represented isometrically in the embedding.
source
The classical sphere, i.e. unit norm (real- or complex-valued) vectors can be generated as usual: to create the 2-dimensional sphere (in $ℝ^3$), use Sphere(2) and Sphere(2,ℂ), respectively.
Manifolds.Sphere — Type
Sphere{n,𝔽} <: AbstractSphere{𝔽}
The (unit) sphere manifold $𝕊^{n}$ is the set of all unit norm vectors in $𝔽^{n+1}$. The sphere is represented in the embedding, i.e.
\[𝕊^{n} := \bigl\{ p \in 𝔽^{n+1}\ \big|\ \lVert p \rVert = 1 \bigr\}\]
where $𝔽\in\{ℝ,ℂ,ℍ\}$. Note that compared to the ArraySphere, here the argument n of the manifold is the dimension of the manifold, i.e. $𝕊^{n} ⊂ 𝔽^{n+1}$, $n\in ℕ$.
The tangent space at point $p$ is given by
\[T_p𝕊^{n} := \bigl\{ X ∈ 𝔽^{n+1}\ |\ \Re(⟨p,X⟩) = 0 \bigr \},\]
where $𝔽\in\{ℝ,ℂ,ℍ\}$ and $⟨\cdot,\cdot⟩$ denotes the inner product in the embedding $𝔽^{n+1}$.
For $𝔽=ℂ$, the manifold is the complex sphere, written $ℂ𝕊^n$, embedded in $ℂ^{n+1}$. $ℂ𝕊^n$ is the complexification of the real sphere $𝕊^{2n+1}$. Likewise, the quaternionic sphere $ℍ𝕊^n$ is the quaternionification of the real sphere $𝕊^{4n+3}$. Consequently, $ℂ𝕊^0$ is equivalent to $𝕊^1$ and Circle, while $ℂ𝕊^1$ and $ℍ𝕊^0$ are equivalent to $𝕊^3$, though with different default representations.
This manifold is modeled as a special case of the more general case, i.e. as an embedded manifold to the Euclidean, and several functions like the inner product and the zero_vector are inherited from the embedding.
Constructor
Sphere(n[, field=ℝ])
Generate the (real-valued) sphere $𝕊^{n} ⊂ ℝ^{n+1}$, where field can also be used to generate the complex- and quaternionic-valued sphere.
source
For the higher-dimensional arrays, for example unit (Frobenius) norm matrices, the manifold is generated using the size of the matrix. To create the unit sphere of $3×2$ real-valued matrices, write ArraySphere(3,2) and the complex case is done – as for the Euclidean case – with an keyword argument ArraySphere(3,2; field = ℂ). This case also covers the classical sphere as a special case, but you specify the size of the vectors/embedding instead: The 2-sphere can here be generated ArraySphere(3).
Manifolds.ArraySphere — Type
ArraySphere{T<:Tuple,𝔽} <: AbstractSphere{𝔽}
The (unit) sphere manifold $𝕊^{n₁,n₂,...,nᵢ}$ is the set of all unit (Frobenius) norm elements of $𝔽^{n₁,n₂,...,nᵢ}$, where 𝔽\in{ℝ,ℂ,ℍ}. The generalized sphere is represented in the embedding, and supports arbitrary sized arrays or in other words arbitrary tensors of unit norm. The set formally reads
\[𝕊^{n_1, n_2, …, n_i} := \bigl\{ p \in 𝔽^{n_1, n_2, …, n_i}\ \big|\ \lVert p \rVert = 1 \bigr\}\]
where $𝔽\in\{ℝ,ℂ,ℍ\}$. Setting $i=1$ and $𝔽=ℝ$  this  simplifies to unit vectors in $ℝ^n$, see Sphere for this special case. Note that compared to this classical case, the argument for the generalized case here is given by the dimension of the embedding. This means that Sphere(2) and ArraySphere(3) are the same manifold.
The tangent space at point $p$ is given by
\[T_p 𝕊^{n_1, n_2, …, n_i} := \bigl\{ X ∈ 𝔽^{n_1, n_2, …, n_i}\ |\ \Re(⟨p,X⟩) = 0 \bigr \},\]
where $𝔽\in\{ℝ,ℂ,ℍ\}$ and $⟨\cdot,\cdot⟩$ denotes the (Frobenius) inner product in the embedding $𝔽^{n_1, n_2, …, n_i}$.
This manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.
Constructor
ArraySphere(n₁,n₂,...,nᵢ; field=ℝ)
Generate sphere in $𝔽^{n_1, n_2, …, n_i}$, where $𝔽$ defaults to the real-valued case $ℝ$.
source
There is also one atlas available on the sphere.
Manifolds.StereographicAtlas — Type
StereographicAtlas()
The stereographic atlas of $S^n$ with two charts: one with the singular point (-1, 0, ..., 0) (called :north) and one with the singular point (1, 0, ..., 0) (called :south).
source
Functions on unit spheres
Base.exp — Method
exp(M::AbstractSphere, p, X)
Compute the exponential map from p in the tangent direction X on the AbstractSphere M by following the great arc eminating from p in direction X.
\[\exp_p X = \cos(\lVert X \rVert_p)p + \sin(\lVert X \rVert_p)\frac{X}{\lVert X \rVert_p},\]
where $\lVert X \rVert_p$ is the norm on the tangent space at p of the AbstractSphere M.
source
Base.log — Method
log(M::AbstractSphere, p, q)
Compute the logarithmic map on the AbstractSphere M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. The formula reads for $x ≠ -y$
\[\log_p q = d_{𝕊}(p,q) \frac{q-\Re(⟨p,q⟩) p}{\lVert q-\Re(⟨p,q⟩) p \rVert_2},\]
and a deterministic choice from the set of tangent vectors is returned if $x=-y$, i.e. for opposite points.
source
Manifolds.local_metric — Method
local_metric(M::Sphere{n}, p, ::DefaultOrthonormalBasis)
return the local representation of the metric in a DefaultOrthonormalBasis, namely the diagonal matrix of size $n×n$ with ones on the diagonal, since the metric is obtained from the embedding by restriction to the tangent space $T_p\mathcal M$ at $p$.
source
Manifolds.volume_density — Method
volume_density(M::AbstractSphere{ℝ}, p, X)
Compute volume density function of a sphere, i.e. determinant of the differential of exponential map exp(M, p, X). The formula reads $(\sin(\lVert X\rVert)/\lVert X\rVert)^(n-1)$ where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].
source
ManifoldsBase.check_point — Method
check_point(M::AbstractSphere, p; kwargs...)
Check whether p is a valid point on the AbstractSphere M, i.e. is a point in the embedding of unit length. The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.check_vector — Method
check_vector(M::AbstractSphere, p, X; kwargs... )
Check whether X is a tangent vector to p on the AbstractSphere M, i.e. after check_point(M,p), X has to be of same dimension as p and orthogonal to p. The tolerance for the last test can be set using the kwargs....
source
ManifoldsBase.distance — Method
distance(M::AbstractSphere, p, q)
Compute the geodesic distance betweeen p and q on the AbstractSphere M. The formula is given by the (shorter) great arc length on the (or a) great circle both p and q lie on.
\[d_{𝕊}(p,q) = \arccos(\Re(⟨p,q⟩)).\]
source
ManifoldsBase.get_coordinates — Method
get_coordinates(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)
Represent the tangent vector X at point p from the AbstractSphere M in an orthonormal basis by rotating the hyperplane containing X to a hyperplane whose normal is the $x$-axis.
Given $q = p λ + x$, where $λ = \operatorname{sgn}(⟨x, p⟩)$, and $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, the formula for $Y$ is
\[\begin{pmatrix}0 \\ Y\end{pmatrix} = X - q\frac{2 ⟨q, X⟩_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}.\]
source
ManifoldsBase.get_vector — Method
get_vector(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)
Convert a one-dimensional vector of coefficients X in the basis B of the tangent space at p on the AbstractSphere M to a tangent vector Y at p by rotating the hyperplane containing X, whose normal is the $x$-axis, to the hyperplane whose normal is p.
Given $q = p λ + x$, where $λ = \operatorname{sgn}(⟨x, p⟩)$, and $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, the formula for $Y$ is
\[Y = X - q\frac{2 \left\langle q, \begin{pmatrix}0 \\ X\end{pmatrix}\right\rangle_{\mathrm{F}}}{⟨q, q⟩_{\mathrm{F}}}.\]
source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::AbstractSphere, p, q, ::ProjectionInverseRetraction)
Compute the inverse of the projection based retraction on the AbstractSphere M, i.e. rearranging $p+X = q\lVert p+X\rVert_2$ yields since $\Re(⟨p,X⟩) = 0$ and when $d_{𝕊^2}(p,q) ≤ \frac{π}{2}$ that
\[\operatorname{retr}_p^{-1}(q) = \frac{q}{\Re(⟨p, q⟩)} - p.\]
source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::AbstractSphere, p, X, q)
Compute the parallel transport on the Sphere of the tangent vector X at p to q, provided, the geodesic between p and q is unique. The formula reads
\[P_{p←q}(X) = X - \frac{\Re(⟨\log_p q,X⟩_p)}{d^2_𝕊(p,q)}
+\bigl(\log_p q + \log_q p \bigr).\]
source
ManifoldsBase.project — Method
project(M::AbstractSphere, p, X)
Project the point X onto the tangent space at p on the Sphere M.
\[\operatorname{proj}_{p}(X) = X - \Re(⟨p, X⟩)p\]
source
ManifoldsBase.project — Method
project(M::AbstractSphere, p)
Project the point p from the embedding onto the Sphere M.
\[\operatorname{proj}(p) = \frac{p}{\lVert p \rVert},\]
where $\lVert\cdot\rVert$ denotes the usual 2-norm for vectors if $m=1$ and the Frobenius norm for the case $m>1$.
source
ManifoldsBase.retract — Method
retract(M::AbstractSphere, p, X, ::ProjectionRetraction)
Compute the retraction that is based on projection, i.e.
\[\operatorname{retr}_p(X) = \frac{p+X}{\lVert p+X \rVert_2}\]
source
Visualization on Sphere{2,ℝ}
You can visualize both points and tangent vectors on the sphere.
Note
There seems to be no unified way to draw spheres in the backends of Plots.jl. This recipe currently uses the seriestype wireframe and surface, which does not yet work with the default backend GR.
In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of the wires and a wireframe_color for their color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_lat or surface_resolution_lon) and a surface_color.
using Manifolds, Plots
+)
Compute the Riemannian mean of x using GeodesicInterpolationWithinRadius.
source

Visualization on Sphere{2,ℝ}

You can visualize both points and tangent vectors on the sphere.

Note

There seems to be no unified way to draw spheres in the backends of Plots.jl. This recipe currently uses the seriestype wireframe and surface, which does not yet work with the default backend GR.

In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of the wires and a wireframe_color for their color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_lat or surface_resolution_lon) and a surface_color.

using Manifolds, Plots
 pythonplot()
 M = Sphere(2)
 pts = [ [1.0, 0.0, 0.0], [0.0, -1.0, 0.0], [0.0, 0.0, 1.0], [1.0, 0.0, 0.0] ]
@@ -18,11 +18,11 @@
   
    
     
-    2023-07-11T21:39:01.558535
+    2023-08-19T19:13:14.841907
     image/svg+xml
     
      
-      Matplotlib v3.7.1, https://matplotlib.org/
+      Matplotlib v3.7.2, https://matplotlib.org/
      
     
    
@@ -390,7 +390,7 @@
   
    
     
-     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
    
    
@@ -449,7 +449,7 @@
 L 233.847468 197.143894 
 L 226.865322 195.9051 
 L 219.81528 194.129688 
-" clip-path="url(#pbb72f8b572)" style="fill: none; stroke: #cccccc"/>
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6bd182edb4)" style="fill: none; stroke: #cccccc"/>
    
    
     
@@ -2672,7 +2672,7 @@
     
     
      
-      
      
      
-      
+      
      
     
     
@@ -2742,7 +2742,7 @@
   
  
  
-  
+  
    
   
  
@@ -2755,11 +2755,11 @@
   
    
     
-    2023-07-11T21:39:03.412463
+    2023-08-19T19:13:16.226645
     image/svg+xml
     
      
-      Matplotlib v3.7.1, https://matplotlib.org/
+      Matplotlib v3.7.2, https://matplotlib.org/
      
     
    
@@ -3127,7 +3127,7 @@
   
    
     
-     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
    
    
@@ -3224,7 +3224,7 @@
 L 291.733205 160.106695 
 L 291.741904 160.948148 
 L 291.741904 160.948148 
-" clip-path="url(#p852ee69f8c)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/>
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/>
    
    
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p0d17865cfc)" style="fill: none; stroke: #cccccc"/>
    
    
     
@@ -5483,7 +5483,7 @@
     
     
      
-      
      
      
-      
+      
      
     
     
@@ -5553,7 +5553,7 @@
   
  
  
-  
+  
    
   
  
@@ -5569,11 +5569,11 @@
   
    
     
-    2023-07-11T21:39:04.884918
+    2023-08-19T19:13:17.314796
     image/svg+xml
     
      
-      Matplotlib v3.7.1, https://matplotlib.org/
+      Matplotlib v3.7.2, https://matplotlib.org/
      
     
    
@@ -5941,7 +5941,7 @@
   
    
     
-     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
-    
-     
+    
+     
     
    
    
@@ -6038,7 +6038,7 @@
 L 291.733205 160.106695 
 L 291.741904 160.948148 
 L 291.741904 160.948148 
-" clip-path="url(#pd178c54085)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/>
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/>
    
    
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #cccccc"/>
    
    
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #c371d2; stroke-width: 1.5"/>
    
    
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #c371d2; stroke-width: 1.5"/>
    
    
     
+" clip-path="url(#p6d92f3586c)" style="fill: none; stroke: #c371d2; stroke-width: 1.5"/>
    
    
     
@@ -8312,7 +8312,7 @@
     
     
      
-      
      
      
-      
+      
      
     
     
@@ -8382,9 +8382,9 @@
   
  
  
-  
+  
    
   
  
 
-
+
diff --git a/previews/PR628/manifolds/spheresymmetricmatrices.html b/previews/PR628/manifolds/spheresymmetricmatrices.html index b7a9e6561f..a8d62cf8ad 100644 --- a/previews/PR628/manifolds/spheresymmetricmatrices.html +++ b/previews/PR628/manifolds/spheresymmetricmatrices.html @@ -1,5 +1,5 @@ -Unit-norm symmetric matrices · Manifolds.jl
Edit on GitHub

Unit-norm symmetric matrices

Manifolds.SphereSymmetricMatrices — Type
SphereSymmetricMatrices{n,𝔽} <: AbstractEmbeddedManifold{ℝ,TransparentIsometricEmbedding}

The AbstractManifold consisting of the $n × n$ symmetric matrices of unit Frobenius norm, i.e.

\[\mathcal{S}_{\text{sym}} :=\bigl\{p ∈ 𝔽^{n × n}\ \big|\ p^{\mathrm{H}} = p, \lVert p \rVert = 1 \bigr\},\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose, and the field $𝔽 ∈ \{ ℝ, ℂ\}$.

Constructor

SphereSymmetricMatrices(n[, field=ℝ])

Generate the manifold of n-by-n symmetric matrices of unit Frobenius norm.

source
ManifoldsBase.check_point — Method
check_point(M::SphereSymmetricMatrices{n,𝔽}, p; kwargs...)

Check whether the matrix is a valid point on the SphereSymmetricMatrices M, i.e. is an n-by-n symmetric matrix of unit Frobenius norm.

The tolerance for the symmetry of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SphereSymmetricMatrices{n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SphereSymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) of unit Frobenius norm.

The tolerance for the symmetry of p and X can be set using kwargs....

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SphereSymmetricMatrices{n,𝔽})

Return the manifold dimension of the SphereSymmetricMatrices n-by-n symmetric matrix M of unit Frobenius norm over the number system 𝔽, i.e.

\[\begin{aligned} +Unit-norm symmetric matrices · Manifolds.jl

Edit on GitHub

Unit-norm symmetric matrices

Manifolds.SphereSymmetricMatrices — Type
SphereSymmetricMatrices{n,𝔽} <: AbstractEmbeddedManifold{ℝ,TransparentIsometricEmbedding}

The AbstractManifold consisting of the $n × n$ symmetric matrices of unit Frobenius norm, i.e.

\[\mathcal{S}_{\text{sym}} :=\bigl\{p ∈ 𝔽^{n × n}\ \big|\ p^{\mathrm{H}} = p, \lVert p \rVert = 1 \bigr\},\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose, and the field $𝔽 ∈ \{ ℝ, ℂ\}$.

Constructor

SphereSymmetricMatrices(n[, field=ℝ])

Generate the manifold of n-by-n symmetric matrices of unit Frobenius norm.

source
ManifoldsBase.check_point — Method
check_point(M::SphereSymmetricMatrices{n,𝔽}, p; kwargs...)

Check whether the matrix is a valid point on the SphereSymmetricMatrices M, i.e. is an n-by-n symmetric matrix of unit Frobenius norm.

The tolerance for the symmetry of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SphereSymmetricMatrices{n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SphereSymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) of unit Frobenius norm.

The tolerance for the symmetry of p and X can be set using kwargs....

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SphereSymmetricMatrices{n,𝔽})

Return the manifold dimension of the SphereSymmetricMatrices n-by-n symmetric matrix M of unit Frobenius norm over the number system 𝔽, i.e.

\[\begin{aligned} \dim(\mathcal{S}_{\text{sym}})(n,ℝ) &= \frac{n(n+1)}{2} - 1,\\ \dim(\mathcal{S}_{\text{sym}})(n,ℂ) &= 2\frac{n(n+1)}{2} - n -1. -\end{aligned}\]

source
ManifoldsBase.project — Method
project(M::SphereSymmetricMatrices, p, X)

Project the matrix X onto the tangent space at p on the SphereSymmetricMatrices M, i.e.

\[\operatorname{proj}_p(X) = \frac{X + X^{\mathrm{H}}}{2} - ⟨p, \frac{X + X^{\mathrm{H}}}{2}⟩p,\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::SphereSymmetricMatrices, p)

Projects p from the embedding onto the SphereSymmetricMatrices M, i.e.

\[\operatorname{proj}_{\mathcal{S}_{\text{sym}}}(p) = \frac{1}{2} \bigl( p + p^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
+\end{aligned}\]

source
ManifoldsBase.project — Method
project(M::SphereSymmetricMatrices, p, X)

Project the matrix X onto the tangent space at p on the SphereSymmetricMatrices M, i.e.

\[\operatorname{proj}_p(X) = \frac{X + X^{\mathrm{H}}}{2} - ⟨p, \frac{X + X^{\mathrm{H}}}{2}⟩p,\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::SphereSymmetricMatrices, p)

Projects p from the embedding onto the SphereSymmetricMatrices M, i.e.

\[\operatorname{proj}_{\mathcal{S}_{\text{sym}}}(p) = \frac{1}{2} \bigl( p + p^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
diff --git a/previews/PR628/manifolds/stiefel.html b/previews/PR628/manifolds/stiefel.html index 27d4a90aba..b9f4087b9c 100644 --- a/previews/PR628/manifolds/stiefel.html +++ b/previews/PR628/manifolds/stiefel.html @@ -1,28 +1,28 @@ -Stiefel · Manifolds.jl
Edit on GitHub

Stiefel

Common and metric independent functions

Manifolds.Stiefel — Type
Stiefel{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}

The Stiefel manifold consists of all $n × k$, $n ≥ k$ unitary matrices, i.e.

\[\operatorname{St}(n,k) = \bigl\{ p ∈ 𝔽^{n × k}\ \big|\ p^{\mathrm{H}}p = I_k \bigr\},\]

where $𝔽 ∈ \{ℝ, ℂ\}$, $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, and $I_k ∈ ℝ^{k × k}$ denotes the $k × k$ identity matrix.

The tangent space at a point $p ∈ \mathcal M$ is given by

\[T_p \mathcal M = \{ X ∈ 𝔽^{n × k} : p^{\mathrm{H}}X + \overline{X^{\mathrm{H}}p} = 0_k\},\]

where $0_k$ is the $k × k$ zero matrix and $\overline{\cdot}$ the (elementwise) complex conjugate.

This manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.

The manifold is named after Eduard L. Stiefel (1909–1978).

Constructor

Stiefel(n, k, field = ℝ)

Generate the (real-valued) Stiefel manifold of $n × k$ dimensional orthonormal matrices.

source
Base.rand — Method
rand(::Stiefel; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (Gaussian) point x on the Stiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the orthogonalized version, i.e. return the Q component of the QR decomposition of the random matrix of size $n×k$.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{vector\_at}\mathrm{St}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.

source
Manifolds.uniform_distribution — Method
uniform_distribution(M::Stiefel{n,k,ℝ}, p)

Uniform distribution on given (real-valued) Stiefel M. Specifically, this is the normalized Haar and Hausdorff measure on M. Generated points will be of similar type as p.

The implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.1(iii) in [Chikuse2003].

source
ManifoldsBase.change_metric — Method
change_metric(M::Stiefel, ::EuclideanMetric, p X)

Change X to the corresponding vector with respect to the metric of the Stiefel M, which is just the identity, since the manifold is isometrically embedded.

source
ManifoldsBase.change_representer — Method
change_representer(M::Stiefel, ::EuclideanMetric, p, X)

Change X to the corresponding representer of a cotangent vector at p. Since the Stiefel manifold M, is isometrically embedded, this is the identity

source
ManifoldsBase.check_point — Method
check_point(M::Stiefel, p; kwargs...)

Check whether p is a valid point on the Stiefel M=$\operatorname{St}(n,k)$, i.e. that it has the right AbstractNumbers type and $p^{\mathrm{H}}p$ is (approximately) the identity, where $\cdot^{\mathrm{H}}$ is the complex conjugate transpose. The settings for approximately can be set with kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::Stiefel, p, X; kwargs...)

Checks whether X is a valid tangent vector at p on the Stiefel M=$\operatorname{St}(n,k)$, i.e. the AbstractNumbers fits and it (approximately) holds that $p^{\mathrm{H}}X + \overline{X^{\mathrm{H}}p} = 0$, where $\cdot^{\mathrm{H}}$ denotes the Hermitian and $\overline{\cdot}$ the (elementwise) complex conjugate. The settings for approximately can be set with kwargs....

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Stiefel, p, q, ::PolarInverseRetraction)

Compute the inverse retraction based on a singular value decomposition for two points p, q on the Stiefel manifold M. This follows the folloing approach: From the Polar retraction we know that

\[\operatorname{retr}_p^{-1}q = qs - t\]

if such a symmetric positive definite $k × k$ matrix exists. Since $qs - t$ is also a tangent vector at $p$ we obtain

\[p^{\mathrm{H}}qs + s(p^{\mathrm{H}}q)^{\mathrm{H}} + 2I_k = 0,\]

which can either be solved by a Lyapunov approach or a continuous-time algebraic Riccati equation.

This implementation follows the Lyapunov approach.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Stiefel)

Return the dimension of the Stiefel manifold M=$\operatorname{St}(n,k,𝔽)$. The dimension is given by

\[\begin{aligned} +Stiefel · Manifolds.jl

Edit on GitHub

Stiefel

Common and metric independent functions

Manifolds.Stiefel — Type
Stiefel{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}

The Stiefel manifold consists of all $n × k$, $n ≥ k$ unitary matrices, i.e.

\[\operatorname{St}(n,k) = \bigl\{ p ∈ 𝔽^{n × k}\ \big|\ p^{\mathrm{H}}p = I_k \bigr\},\]

where $𝔽 ∈ \{ℝ, ℂ\}$, $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, and $I_k ∈ ℝ^{k × k}$ denotes the $k × k$ identity matrix.

The tangent space at a point $p ∈ \mathcal M$ is given by

\[T_p \mathcal M = \{ X ∈ 𝔽^{n × k} : p^{\mathrm{H}}X + \overline{X^{\mathrm{H}}p} = 0_k\},\]

where $0_k$ is the $k × k$ zero matrix and $\overline{\cdot}$ the (elementwise) complex conjugate.

This manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.

The manifold is named after Eduard L. Stiefel (1909–1978).

Constructor

Stiefel(n, k, field = ℝ)

Generate the (real-valued) Stiefel manifold of $n × k$ dimensional orthonormal matrices.

source
Base.rand — Method
rand(::Stiefel; vector_at=nothing, σ::Real=1.0)

When vector_at is nothing, return a random (Gaussian) point x on the Stiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the orthogonalized version, i.e. return the Q component of the QR decomposition of the random matrix of size $n×k$.

When vector_at is not nothing, return a (Gaussian) random vector from the tangent space $T_{vector\_at}\mathrm{St}(n,k)$ with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.

source
Manifolds.uniform_distribution — Method
uniform_distribution(M::Stiefel{n,k,ℝ}, p)

Uniform distribution on given (real-valued) Stiefel M. Specifically, this is the normalized Haar and Hausdorff measure on M. Generated points will be of similar type as p.

The implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.1(iii) in [Chikuse2003].

source
ManifoldsBase.change_metric — Method
change_metric(M::Stiefel, ::EuclideanMetric, p X)

Change X to the corresponding vector with respect to the metric of the Stiefel M, which is just the identity, since the manifold is isometrically embedded.

source
ManifoldsBase.change_representer — Method
change_representer(M::Stiefel, ::EuclideanMetric, p, X)

Change X to the corresponding representer of a cotangent vector at p. Since the Stiefel manifold M, is isometrically embedded, this is the identity

source
ManifoldsBase.check_point — Method
check_point(M::Stiefel, p; kwargs...)

Check whether p is a valid point on the Stiefel M=$\operatorname{St}(n,k)$, i.e. that it has the right AbstractNumbers type and $p^{\mathrm{H}}p$ is (approximately) the identity, where $\cdot^{\mathrm{H}}$ is the complex conjugate transpose. The settings for approximately can be set with kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::Stiefel, p, X; kwargs...)

Checks whether X is a valid tangent vector at p on the Stiefel M=$\operatorname{St}(n,k)$, i.e. the AbstractNumbers fits and it (approximately) holds that $p^{\mathrm{H}}X + \overline{X^{\mathrm{H}}p} = 0$, where $\cdot^{\mathrm{H}}$ denotes the Hermitian and $\overline{\cdot}$ the (elementwise) complex conjugate. The settings for approximately can be set with kwargs....

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Stiefel, p, q, ::PolarInverseRetraction)

Compute the inverse retraction based on a singular value decomposition for two points p, q on the Stiefel manifold M. This follows the folloing approach: From the Polar retraction we know that

\[\operatorname{retr}_p^{-1}q = qs - t\]

if such a symmetric positive definite $k × k$ matrix exists. Since $qs - t$ is also a tangent vector at $p$ we obtain

\[p^{\mathrm{H}}qs + s(p^{\mathrm{H}}q)^{\mathrm{H}} + 2I_k = 0,\]

which can either be solved by a Lyapunov approach or a continuous-time algebraic Riccati equation.

This implementation follows the Lyapunov approach.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::Stiefel)

Return the dimension of the Stiefel manifold M=$\operatorname{St}(n,k,𝔽)$. The dimension is given by

\[\begin{aligned} \dim \mathrm{St}(n, k, ℝ) &= nk - \frac{1}{2}k(k+1)\\ \dim \mathrm{St}(n, k, ℂ) &= 2nk - k^2\\ \dim \mathrm{St}(n, k, ℍ) &= 4nk - k(2k-1) -\end{aligned}\]

source
ManifoldsBase.retract — Method
retract(::Stiefel, p, X, ::CayleyRetraction)

Compute the retraction on the Stiefel that is based on the Cayley transform[Zhu2017]. Using

\[ W_{p,X} = \operatorname{P}_pXp^{\mathrm{H}} - pX^{\mathrm{H}}\operatorname{P_p} +\end{aligned}\]

source
ManifoldsBase.retract — Method
retract(::Stiefel, p, X, ::CayleyRetraction)

Compute the retraction on the Stiefel that is based on the Cayley transform[Zhu2017]. Using

\[ W_{p,X} = \operatorname{P}_pXp^{\mathrm{H}} - pX^{\mathrm{H}}\operatorname{P_p} \quad\text{where}  - \operatorname{P}_p = I - \frac{1}{2}pp^{\mathrm{H}}\]

the formula reads

\[ \operatorname{retr}_pX = \Bigl(I - \frac{1}{2}W_{p,X}\Bigr)^{-1}\Bigl(I + \frac{1}{2}W_{p,X}\Bigr)p.\]

It is implemented as the case $m=1$ of the PadeRetraction.

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, ::PadeRetraction{m})

Compute the retraction on the Stiefel manifold M based on the Padé approximation of order $m$[ZhuDuan2018]. Let $p_m$ and $q_m$ be defined for any matrix $A ∈ ℝ^{n×x}$ as

\[ p_m(A) = \sum_{k=0}^m \frac{(2m-k)!m!}{(2m)!(m-k)!}\frac{A^k}{k!}\]

and

\[ q_m(A) = \sum_{k=0}^m \frac{(2m-k)!m!}{(2m)!(m-k)!}\frac{(-A)^k}{k!}\]

respectively. Then the Padé approximation (of the matrix exponential $\exp(A)$) reads

\[ r_m(A) = q_m(A)^{-1}p_m(A)\]

Defining further

\[ W_{p,X} = \operatorname{P}_pXp^{\mathrm{H}} - pX^{\mathrm{H}}\operatorname{P_p} + \operatorname{P}_p = I - \frac{1}{2}pp^{\mathrm{H}}\]

the formula reads

\[ \operatorname{retr}_pX = \Bigl(I - \frac{1}{2}W_{p,X}\Bigr)^{-1}\Bigl(I + \frac{1}{2}W_{p,X}\Bigr)p.\]

It is implemented as the case $m=1$ of the PadeRetraction.

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, ::PadeRetraction{m})

Compute the retraction on the Stiefel manifold M based on the Padé approximation of order $m$[ZhuDuan2018]. Let $p_m$ and $q_m$ be defined for any matrix $A ∈ ℝ^{n×x}$ as

\[ p_m(A) = \sum_{k=0}^m \frac{(2m-k)!m!}{(2m)!(m-k)!}\frac{A^k}{k!}\]

and

\[ q_m(A) = \sum_{k=0}^m \frac{(2m-k)!m!}{(2m)!(m-k)!}\frac{(-A)^k}{k!}\]

respectively. Then the Padé approximation (of the matrix exponential $\exp(A)$) reads

\[ r_m(A) = q_m(A)^{-1}p_m(A)\]

Defining further

\[ W_{p,X} = \operatorname{P}_pXp^{\mathrm{H}} - pX^{\mathrm{H}}\operatorname{P_p} \quad\text{where } - \operatorname{P}_p = I - \frac{1}{2}pp^{\mathrm{H}}\]

the retraction reads

\[ \operatorname{retr}_pX = r_m(W_{p,X})p\]

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, ::PolarRetraction)

Compute the SVD-based retraction PolarRetraction on the Stiefel manifold M. With $USV = p + X$ the retraction reads

\[\operatorname{retr}_p X = U\bar{V}^\mathrm{H}.\]

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, ::QRRetraction)

Compute the QR-based retraction QRRetraction on the Stiefel manifold M. With $QR = p + X$ the retraction reads

\[\operatorname{retr}_p X = QD,\]

where $D$ is a $n × k$ matrix with

\[D = \operatorname{diag}\bigl(\operatorname{sgn}(R_{ii}+0,5)_{i=1}^k \bigr),\]

where $\operatorname{sgn}(p) = \begin{cases} 1 & \text{ for } p > 0,\\ + \operatorname{P}_p = I - \frac{1}{2}pp^{\mathrm{H}}\]

the retraction reads

\[ \operatorname{retr}_pX = r_m(W_{p,X})p\]

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, ::PolarRetraction)

Compute the SVD-based retraction PolarRetraction on the Stiefel manifold M. With $USV = p + X$ the retraction reads

\[\operatorname{retr}_p X = U\bar{V}^\mathrm{H}.\]

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, ::QRRetraction)

Compute the QR-based retraction QRRetraction on the Stiefel manifold M. With $QR = p + X$ the retraction reads

\[\operatorname{retr}_p X = QD,\]

where $D$ is a $n × k$ matrix with

\[D = \operatorname{diag}\bigl(\operatorname{sgn}(R_{ii}+0,5)_{i=1}^k \bigr),\]

where $\operatorname{sgn}(p) = \begin{cases} 1 & \text{ for } p > 0,\\ 0 & \text{ for } p = 0,\\ --1& \text{ for } p < 0. \end{cases}$

source
ManifoldsBase.vector_transport_direction — Method
vector_transport_direction(::Stiefel, p, X, d, ::DifferentiatedRetractionVectorTransport{CayleyRetraction})

Compute the vector transport given by the differentiated retraction of the CayleyRetraction, cf. [Zhu2017] Equation (17).

The formula reads

\[\operatorname{T}_{p,d}(X) = +-1& \text{ for } p < 0. \end{cases}$

source
ManifoldsBase.vector_transport_direction — Method
vector_transport_direction(::Stiefel, p, X, d, ::DifferentiatedRetractionVectorTransport{CayleyRetraction})

Compute the vector transport given by the differentiated retraction of the CayleyRetraction, cf. [Zhu2017] Equation (17).

The formula reads

\[\operatorname{T}_{p,d}(X) = \Bigl(I - \frac{1}{2}W_{p,d}\Bigr)^{-1}W_{p,X}\Bigl(I - \frac{1}{2}W_{p,d}\Bigr)^{-1}p,\]

with

\[ W_{p,X} = \operatorname{P}_pXp^{\mathrm{H}} - pX^{\mathrm{H}}\operatorname{P_p} \quad\text{where } - \operatorname{P}_p = I - \frac{1}{2}pp^{\mathrm{H}}\]

Since this is the differentiated retraction as a vector transport, the result will be in the tangent space at $q=\operatorname{retr}_p(d)$ using the CayleyRetraction.

source
ManifoldsBase.vector_transport_direction — Method
vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{PolarRetraction})

Compute the vector transport by computing the push forward of retract(::Stiefel, ::Any, ::Any, ::PolarRetraction) Section 3.5 of [Zhu2017]:

\[T_{p,d}^{\text{Pol}}(X) = q*Λ + (I-qq^{\mathrm{T}})X(1+d^\mathrm{T}d)^{-\frac{1}{2}},\]

where $q = \operatorname{retr}^{\mathrm{Pol}}_p(d)$, and $Λ$ is the unique solution of the Sylvester equation

\[ Λ(I+d^\mathrm{T}d)^{\frac{1}{2}} + (I + d^\mathrm{T}d)^{\frac{1}{2}} = q^\mathrm{T}X - X^\mathrm{T}q\]

source
ManifoldsBase.vector_transport_direction — Method
vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{QRRetraction})

Compute the vector transport by computing the push forward of the retract(::Stiefel, ::Any, ::Any, ::QRRetraction), See [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].

\[T_{p,d}^{\text{QR}}(X) = q*\rho_{\mathrm{s}}(q^\mathrm{T}XR^{-1}) + (I-qq^{\mathrm{T}})XR^{-1},\]

where $q = \operatorname{retr}^{\mathrm{QR}}_p(d)$, $R$ is the $R$ factor of the QR decomposition of $p + d$, and

\[\bigl( \rho_{\mathrm{s}}(A) \bigr)_{ij} + \operatorname{P}_p = I - \frac{1}{2}pp^{\mathrm{H}}\]

Since this is the differentiated retraction as a vector transport, the result will be in the tangent space at $q=\operatorname{retr}_p(d)$ using the CayleyRetraction.

source
ManifoldsBase.vector_transport_direction — Method
vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{PolarRetraction})

Compute the vector transport by computing the push forward of retract(::Stiefel, ::Any, ::Any, ::PolarRetraction) Section 3.5 of [Zhu2017]:

\[T_{p,d}^{\text{Pol}}(X) = q*Λ + (I-qq^{\mathrm{T}})X(1+d^\mathrm{T}d)^{-\frac{1}{2}},\]

where $q = \operatorname{retr}^{\mathrm{Pol}}_p(d)$, and $Λ$ is the unique solution of the Sylvester equation

\[ Λ(I+d^\mathrm{T}d)^{\frac{1}{2}} + (I + d^\mathrm{T}d)^{\frac{1}{2}} = q^\mathrm{T}X - X^\mathrm{T}q\]

source
ManifoldsBase.vector_transport_direction — Method
vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{QRRetraction})

Compute the vector transport by computing the push forward of the retract(::Stiefel, ::Any, ::Any, ::QRRetraction), See [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].

\[T_{p,d}^{\text{QR}}(X) = q*\rho_{\mathrm{s}}(q^\mathrm{T}XR^{-1}) + (I-qq^{\mathrm{T}})XR^{-1},\]

where $q = \operatorname{retr}^{\mathrm{QR}}_p(d)$, $R$ is the $R$ factor of the QR decomposition of $p + d$, and

\[\bigl( \rho_{\mathrm{s}}(A) \bigr)_{ij} = \begin{cases} A_{ij}&\text{ if } i > j\\ 0 \text{ if } i = j\\ -A_{ji} \text{ if } i < j.\\ -\end{cases}\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{PolarRetraction})

Compute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::PolarRetraction), see Section 4 of [HuangGallivanAbsil2015] or Section 3.5 of [Zhu2017]:

\[T_{q\gets p}^{\text{Pol}}(X) = q*Λ + (I-qq^{\mathrm{T}})X(1+d^\mathrm{T}d)^{-\frac{1}{2}},\]

where $d = \bigl( \operatorname{retr}^{\mathrm{Pol}}_p\bigr)^{-1}(q)$, and $Λ$ is the unique solution of the Sylvester equation

\[ Λ(I+d^\mathrm{T}d)^{\frac{1}{2}} + (I + d^\mathrm{T}d)^{\frac{1}{2}} = q^\mathrm{T}X - X^\mathrm{T}q\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{QRRetraction})

Compute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::QRRetraction), see [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].

\[T_{q \gets p}^{\text{QR}}(X) = q*\rho_{\mathrm{s}}(q^\mathrm{T}XR^{-1}) + (I-qq^{\mathrm{T}})XR^{-1},\]

where $d = \bigl(\operatorname{retr}^{\mathrm{QR}}\bigr)^{-1}_p(q)$, $R$ is the $R$ factor of the QR decomposition of $p+X$, and

\[\bigl( \rho_{\mathrm{s}}(A) \bigr)_{ij} +\end{cases}\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{PolarRetraction})

Compute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::PolarRetraction), see Section 4 of [HuangGallivanAbsil2015] or Section 3.5 of [Zhu2017]:

\[T_{q\gets p}^{\text{Pol}}(X) = q*Λ + (I-qq^{\mathrm{T}})X(1+d^\mathrm{T}d)^{-\frac{1}{2}},\]

where $d = \bigl( \operatorname{retr}^{\mathrm{Pol}}_p\bigr)^{-1}(q)$, and $Λ$ is the unique solution of the Sylvester equation

\[ Λ(I+d^\mathrm{T}d)^{\frac{1}{2}} + (I + d^\mathrm{T}d)^{\frac{1}{2}} = q^\mathrm{T}X - X^\mathrm{T}q\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{QRRetraction})

Compute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::QRRetraction), see [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].

\[T_{q \gets p}^{\text{QR}}(X) = q*\rho_{\mathrm{s}}(q^\mathrm{T}XR^{-1}) + (I-qq^{\mathrm{T}})XR^{-1},\]

where $d = \bigl(\operatorname{retr}^{\mathrm{QR}}\bigr)^{-1}_p(q)$, $R$ is the $R$ factor of the QR decomposition of $p+X$, and

\[\bigl( \rho_{\mathrm{s}}(A) \bigr)_{ij} = \begin{cases} A_{ij}&\text{ if } i > j\\ 0 \text{ if } i = j\\ -A_{ji} \text{ if } i < j.\\ -\end{cases}\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Stiefel, p, X, q, ::ProjectionTransport)

Compute a vector transport by projection, i.e. project X from the tangent space at p by projection it onto the tangent space at q.

source

Default metric: the Euclidean metric

The EuclideanMetric is obtained from the embedding of the Stiefel manifold in $ℝ^{n,k}$.

Base.exp — Method
exp(M::Stiefel, p, X)

Compute the exponential map on the Stiefel{n,k,𝔽}() manifold M emanating from p in tangent direction X.

\[\exp_p X = \begin{pmatrix} +\end{cases}\]

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::Stiefel, p, X, q, ::ProjectionTransport)

Compute a vector transport by projection, i.e. project X from the tangent space at p by projection it onto the tangent space at q.

source

Default metric: the Euclidean metric

The EuclideanMetric is obtained from the embedding of the Stiefel manifold in $ℝ^{n,k}$.

Base.exp — Method
exp(M::Stiefel, p, X)

Compute the exponential map on the Stiefel{n,k,𝔽}() manifold M emanating from p in tangent direction X.

\[\exp_p X = \begin{pmatrix} p\\X \end{pmatrix} \operatorname{Exp} @@ -30,11 +30,11 @@ \begin{pmatrix} p^{\mathrm{H}}X & - X^{\mathrm{H}}X\\ I_n & p^{\mathrm{H}}X\end{pmatrix} \right) -\begin{pmatrix} \exp( -p^{\mathrm{H}}X) \\ 0_n\end{pmatrix},\]

where $\operatorname{Exp}$ denotes matrix exponential, $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, and $I_k$ and $0_k$ are the identity matrix and the zero matrix of dimension $k × k$, respectively.

source
ManifoldsBase.get_basis — Method
get_basis(M::Stiefel{n,k,ℝ}, p, B::DefaultOrthonormalBasis) where {n,k}

Create the default basis using the parametrization for any $X ∈ T_p\mathcal M$. Set $p_\bot \in ℝ^{n\times(n-k)}$ the matrix such that the $n\times n$ matrix of the common columns $[p\ p_\bot]$ is an ONB. For any skew symmetric matrix $a ∈ ℝ^{k\times k}$ and any $b ∈ ℝ^{(n-k)\times k}$ the matrix

\[X = pa + p_\bot b ∈ T_p\mathcal M\]

and we can use the $\frac{1}{2}k(k-1) + (n-k)k = nk-\frac{1}{2}k(k+1)$ entries of $a$ and $b$ to specify a basis for the tangent space. using unit vectors for constructing both the upper matrix of $a$ to build a skew symmetric matrix and the matrix b, the default basis is constructed.

Since $[p\ p_\bot]$ is an automorphism on $ℝ^{n\times p}$ the elements of $a$ and $b$ are orthonormal coordinates for the tangent space. To be precise exactly one element in the upper trangular entries of $a$ is set to $1$ its symmetric entry to $-1$ and we normalize with the factor $\frac{1}{\sqrt{2}}$ and for $b$ one can just use unit vectors reshaped to a matrix to obtain orthonormal set of parameters.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Stiefel, p, q, method::ProjectionInverseRetraction)

Compute a projection-based inverse retraction.

The inverse retraction is computed by projecting the logarithm map in the embedding to the tangent space at $p$.

source
ManifoldsBase.project — Method
project(M::Stiefel,p)

Projects p from the embedding onto the Stiefel M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}q$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::Stiefel, p, X)

Project X onto the tangent space of p to the Stiefel manifold M. The formula reads

\[\operatorname{proj}_{\mathcal M}(p, X) = X - p \operatorname{Sym}(p^{\mathrm{H}}X),\]

where $\operatorname{Sym}(q)$ is the symmetrization of $q$, e.g. by $\operatorname{Sym}(q) = \frac{q^{\mathrm{H}}+q}{2}$.

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, method::ProjectionRetraction)

Compute a projection-based retraction.

The retraction is computed by projecting the exponential map in the embedding to M.

source

The canonical metric

Any $X∈T_p\mathcal M$, $p∈\mathcal M$, can be written as

\[X = pA + (I_n-pp^{\mathrm{T}})B, +\begin{pmatrix} \exp( -p^{\mathrm{H}}X) \\ 0_n\end{pmatrix},\]

where $\operatorname{Exp}$ denotes matrix exponential, $\cdot^{\mathrm{H}}$ denotes the complex conjugate transpose or Hermitian, and $I_k$ and $0_k$ are the identity matrix and the zero matrix of dimension $k × k$, respectively.

source
ManifoldsBase.get_basis — Method
get_basis(M::Stiefel{n,k,ℝ}, p, B::DefaultOrthonormalBasis) where {n,k}

Create the default basis using the parametrization for any $X ∈ T_p\mathcal M$. Set $p_\bot \in ℝ^{n\times(n-k)}$ the matrix such that the $n\times n$ matrix of the common columns $[p\ p_\bot]$ is an ONB. For any skew symmetric matrix $a ∈ ℝ^{k\times k}$ and any $b ∈ ℝ^{(n-k)\times k}$ the matrix

\[X = pa + p_\bot b ∈ T_p\mathcal M\]

and we can use the $\frac{1}{2}k(k-1) + (n-k)k = nk-\frac{1}{2}k(k+1)$ entries of $a$ and $b$ to specify a basis for the tangent space. using unit vectors for constructing both the upper matrix of $a$ to build a skew symmetric matrix and the matrix b, the default basis is constructed.

Since $[p\ p_\bot]$ is an automorphism on $ℝ^{n\times p}$ the elements of $a$ and $b$ are orthonormal coordinates for the tangent space. To be precise exactly one element in the upper trangular entries of $a$ is set to $1$ its symmetric entry to $-1$ and we normalize with the factor $\frac{1}{\sqrt{2}}$ and for $b$ one can just use unit vectors reshaped to a matrix to obtain orthonormal set of parameters.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Stiefel, p, q, method::ProjectionInverseRetraction)

Compute a projection-based inverse retraction.

The inverse retraction is computed by projecting the logarithm map in the embedding to the tangent space at $p$.

source
ManifoldsBase.project — Method
project(M::Stiefel,p)

Projects p from the embedding onto the Stiefel M, i.e. compute q as the polar decomposition of $p$ such that $q^{\mathrm{H}q$ is the identity, where $\cdot^{\mathrm{H}}$ denotes the hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::Stiefel, p, X)

Project X onto the tangent space of p to the Stiefel manifold M. The formula reads

\[\operatorname{proj}_{\mathcal M}(p, X) = X - p \operatorname{Sym}(p^{\mathrm{H}}X),\]

where $\operatorname{Sym}(q)$ is the symmetrization of $q$, e.g. by $\operatorname{Sym}(q) = \frac{q^{\mathrm{H}}+q}{2}$.

source
ManifoldsBase.retract — Method
retract(M::Stiefel, p, X, method::ProjectionRetraction)

Compute a projection-based retraction.

The retraction is computed by projecting the exponential map in the embedding to M.

source

The canonical metric

Any $X∈T_p\mathcal M$, $p∈\mathcal M$, can be written as

\[X = pA + (I_n-pp^{\mathrm{T}})B, \quad A ∈ ℝ^{p×p} \text{ skew-symmetric}, \quad -B ∈ ℝ^{n×p} \text{ arbitrary.}\]

In the EuclideanMetric, the elements from $A$ are counted twice (i.e. weighted with a factor of 2). The canonical metric avoids this.

Base.exp — Method
q = exp(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, X)
+B ∈ ℝ^{n×p} \text{ arbitrary.}\]
In the EuclideanMetric, the elements from $A$ are counted twice (i.e. weighted with a factor of 2). The canonical metric avoids this.
Base.exp — Method
q = exp(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, X)
 exp!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, q, CanonicalMetric}, p, X)
Compute the exponential map on the Stiefel(n,k) manifold with respect to the CanonicalMetric.
First, decompose The tangent vector $X$ into its horizontal and vertical component with respect to $p$, i.e.
\[X = pp^{\mathrm{T}}X + (I_n-pp^{\mathrm{T}})X,\]
where $I_n$ is the $n\times n$ identity matrix. We introduce $A=p^{\mathrm{T}}X$ and $QR = (I_n-pp^{\mathrm{T}})X$ the qr decomposition of the vertical component. Then using the matrix exponential $\operatorname{Exp}$ we introduce $B$ and $C$ as
\[\begin{pmatrix}
 B\\C
 \end{pmatrix}
@@ -44,12 +44,12 @@
 A & -R^{\mathrm{T}}\\ R & 0
 \end{pmatrix}
 \right)
-\begin{pmatrix}I_k\\0\end{pmatrix}\]
the exponential map reads
\[q = \exp_p X = pC + QB.\]
For more details, see [EdelmanAriasSmith1998][Zimmermann2017].
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, X, Y)
Compute the inner product on the Stiefel manifold with respect to the CanonicalMetric. The formula reads
\[g_p(X,Y) = \operatorname{tr}\bigl( X^{\mathrm{T}}(I_n - \frac{1}{2}pp^{\mathrm{T}})Y \bigr).\]
source
ManifoldsBase.inverse_retract — Method
X = inverse_retract(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)
-inverse_retract!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)
Compute an approximation to the logarithmic map on the Stiefel(n,k) manifold with respect to the CanonicalMetric using a matrix-algebraic based approach to an iterative inversion of the formula of the exp.
The algorithm is derived in[Zimmermann2017] and it uses the max_iterations and the tolerance field from the ApproximateLogarithmicMap.
source
The submersion or normal metric
Manifolds.StiefelSubmersionMetric — Type
StiefelSubmersionMetric{T<:Real} <: RiemannianMetric
The submersion (or normal) metric family on the Stiefel manifold.
The family, with a single real parameter $α>-1$, has two special cases:
The family was described in [HüperMarkinaLeite2021]. This implementation follows the description in [ZimmermanHüper2022].
Constructor
StiefelSubmersionMetric(α)
Construct the submersion metric on the Stiefel manifold with the parameter $α$.
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, X, Y)
Compute the inner product on the Stiefel manifold with respect to the CanonicalMetric. The formula reads
\[g_p(X,Y) = \operatorname{tr}\bigl( X^{\mathrm{T}}(I_n - \frac{1}{2}pp^{\mathrm{T}})Y \bigr).\]
source
ManifoldsBase.inverse_retract — Method
X = inverse_retract(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)
+inverse_retract!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)
Compute an approximation to the logarithmic map on the Stiefel(n,k) manifold with respect to the CanonicalMetric using a matrix-algebraic based approach to an iterative inversion of the formula of the exp.
The algorithm is derived in[Zimmermann2017] and it uses the max_iterations and the tolerance field from the ApproximateLogarithmicMap.
source
The submersion or normal metric
Manifolds.StiefelSubmersionMetric — Type
StiefelSubmersionMetric{T<:Real} <: RiemannianMetric
The submersion (or normal) metric family on the Stiefel manifold.
The family, with a single real parameter $α>-1$, has two special cases:
The family was described in [HüperMarkinaLeite2021]. This implementation follows the description in [ZimmermanHüper2022].
Constructor
StiefelSubmersionMetric(α)
Construct the submersion metric on the Stiefel manifold with the parameter $α$.
source
Base.exp — Method
q = exp(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, <:StiefelSubmersionMetric}, p, X)
 exp!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, q, <:StiefelSubmersionMetric}, p, X)
Compute the exponential map on the Stiefel(n,k) manifold with respect to the StiefelSubmersionMetric.
The exponential map is given by
\[\exp_p X = \operatorname{Exp}\bigl(
     -\frac{2α+1}{α+1} p p^\mathrm{T} X p^\mathrm{T} +
     X p^\mathrm{T} - p X^\mathrm{T}
-\bigr) p \operatorname{Exp}\bigl(\frac{\alpha}{\alpha+1} p^\mathrm{T} X\bigr)\]
This implementation is based on [ZimmermanHüper2022].
For $k < \frac{n}{2}$ the exponential is computed more efficiently using StiefelFactorization.
source
Base.log — Method
log(M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric}, p, q; kwargs...)
Compute the logarithmic map on the Stiefel(n,k) manifold with respect to the StiefelSubmersionMetric.
The logarithmic map is computed using ShootingInverseRetraction. For $k ≤ \lfloor\frac{n}{2}\rfloor$, this is sped up using the $k$-shooting method of [ZimmermanHüper2022]. Keyword arguments are forwarded to ShootingInverseRetraction; see that documentation for details. Their defaults are:
  • num_transport_points=4
  • tolerance=sqrt(eps())
  • max_iterations=1_000
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, <:StiefelSubmersionMetric}, p, X, Y)
Compute the inner product on the Stiefel manifold with respect to the StiefelSubmersionMetric. The formula reads
\[g_p(X,Y) = \operatorname{tr}\bigl( X^{\mathrm{T}}(I_n - \frac{2α+1}{2(α+1)}pp^{\mathrm{T}})Y \bigr),\]
where $α$ is the parameter of the metric.
source
Base.log — Method
log(M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric}, p, q; kwargs...)
Compute the logarithmic map on the Stiefel(n,k) manifold with respect to the StiefelSubmersionMetric.
The logarithmic map is computed using ShootingInverseRetraction. For $k ≤ \lfloor\frac{n}{2}\rfloor$, this is sped up using the $k$-shooting method of [ZimmermanHüper2022]. Keyword arguments are forwarded to ShootingInverseRetraction; see that documentation for details. Their defaults are:
  • num_transport_points=4
  • tolerance=sqrt(eps())
  • max_iterations=1_000
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, <:StiefelSubmersionMetric}, p, X, Y)
Compute the inner product on the Stiefel manifold with respect to the StiefelSubmersionMetric. The formula reads
\[g_p(X,Y) = \operatorname{tr}\bigl( X^{\mathrm{T}}(I_n - \frac{2α+1}{2(α+1)}pp^{\mathrm{T}})Y \bigr),\]
where $α$ is the parameter of the metric.
source
ManifoldsBase.inverse_retract — Method
inverse_retract(
     M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric},
     p,
     q,
@@ -63,7 +63,7 @@
         ProjectionInverseRetraction,
         <:Union{ProjectionTransport,ScaledVectorTransport{ProjectionTransport}},
     },
-)
Compute the inverse retraction using ShootingInverseRetraction more efficiently.
For $k < \frac{n}{2}$ the retraction is computed more efficiently using StiefelFactorization.
source
Internal types and functions
Manifolds.StiefelFactorization — Type
StiefelFactorization{UT,XT} <: AbstractManifoldPoint
Represent points (and vectors) on Stiefel(n, k) with $2k × k$ factors.[ZimmermanHüper2022]
Given a point $p ∈ \mathrm{St}(n, k)$ and another matrix $B ∈ ℝ^{n × k}$ for $k ≤ \lfloor\frac{n}{2}\rfloor$ the factorization is
\[\begin{aligned}
+)

Compute the inverse retraction using ShootingInverseRetraction more efficiently.

For $k < \frac{n}{2}$ the retraction is computed more efficiently using StiefelFactorization.

source

Internal types and functions

Manifolds.StiefelFactorization — Type
StiefelFactorization{UT,XT} <: AbstractManifoldPoint

Represent points (and vectors) on Stiefel(n, k) with $2k × k$ factors.[ZimmermanHüper2022]

Given a point $p ∈ \mathrm{St}(n, k)$ and another matrix $B ∈ ℝ^{n × k}$ for $k ≤ \lfloor\frac{n}{2}\rfloor$ the factorization is

\[\begin{aligned} B &= UZ\\ U &= \begin{bmatrix}p & Q\end{bmatrix} ∈ \mathrm{St}(n, 2k)\\ Z &= \begin{bmatrix}Z_1 \\ Z_2\end{bmatrix}, \quad Z_1,Z_2 ∈ ℝ^{k × k}. @@ -71,4 +71,4 @@ A &= UZ\\ Z_1 &= p^\mathrm{T} A \\ Q Z_2 &= (I - p p^\mathrm{T}) A, -\end{aligned}\]

where here $Q Z_2$ is the any decomposition that produces $Q ∈ \mathrm{St}(n, k)$, for which we choose the QR decomposition.

This factorization is useful because it is closed under addition, subtraction, scaling, projection, and the Riemannian exponential and logarithm under the StiefelSubmersionMetric. That is, if all matrices involved are factorized to have the same $U$, then all of these operations and any algorithm that depends only on them can be performed in terms of the $2k × k$ matrices $Z$. For $n ≫ k$, this can be much more efficient than working with the full matrices.

Warning

This type is intended strictly for internal use and should not be directly used.

source

Literature

+\end{aligned}\]

where here $Q Z_2$ is the any decomposition that produces $Q ∈ \mathrm{St}(n, k)$, for which we choose the QR decomposition.

This factorization is useful because it is closed under addition, subtraction, scaling, projection, and the Riemannian exponential and logarithm under the StiefelSubmersionMetric. That is, if all matrices involved are factorized to have the same $U$, then all of these operations and any algorithm that depends only on them can be performed in terms of the $2k × k$ matrices $Z$. For $n ≫ k$, this can be much more efficient than working with the full matrices.

Warning

This type is intended strictly for internal use and should not be directly used.

source

Literature

diff --git a/previews/PR628/manifolds/symmetric.html b/previews/PR628/manifolds/symmetric.html index 130f9e9d7a..147fc40c13 100644 --- a/previews/PR628/manifolds/symmetric.html +++ b/previews/PR628/manifolds/symmetric.html @@ -1,5 +1,5 @@ -Symmetric matrices · Manifolds.jl
Edit on GitHub

Symmetric matrices

Manifolds.SymmetricMatrices — Type
SymmetricMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}

The AbstractManifold $ \operatorname{Sym}(n)$ consisting of the real- or complex-valued symmetric matrices of size $n × n$, i.e. the set

\[\operatorname{Sym}(n) = \bigl\{p ∈ 𝔽^{n × n}\ \big|\ p^{\mathrm{H}} = p \bigr\},\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose, and the field $𝔽 ∈ \{ ℝ, ℂ\}$.

Though it is slightly redundant, usually the matrices are stored as $n × n$ arrays.

Note that in this representation, the complex valued case has to have a real-valued diagonal, which is also reflected in the manifold_dimension.

Constructor

SymmetricMatrices(n::Int, field::AbstractNumbers=ℝ)

Generate the manifold of $n × n$ symmetric matrices.

source
ManifoldsBase.check_point — Method
check_point(M::SymmetricMatrices{n,𝔽}, p; kwargs...)

Check whether p is a valid manifold point on the SymmetricMatrices M, i.e. whether p is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.

The tolerance for the symmetry of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SymmetricMatrices{n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.

The tolerance for the symmetry of X can be set using kwargs....

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SymmetricMatrices{n,𝔽})

Return the dimension of the SymmetricMatrices matrix M over the number system 𝔽, i.e.

\[\begin{aligned} +Symmetric matrices · Manifolds.jl

Edit on GitHub

Symmetric matrices

Manifolds.SymmetricMatrices — Type
SymmetricMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}

The AbstractManifold $ \operatorname{Sym}(n)$ consisting of the real- or complex-valued symmetric matrices of size $n × n$, i.e. the set

\[\operatorname{Sym}(n) = \bigl\{p ∈ 𝔽^{n × n}\ \big|\ p^{\mathrm{H}} = p \bigr\},\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose, and the field $𝔽 ∈ \{ ℝ, ℂ\}$.

Though it is slightly redundant, usually the matrices are stored as $n × n$ arrays.

Note that in this representation, the complex valued case has to have a real-valued diagonal, which is also reflected in the manifold_dimension.

Constructor

SymmetricMatrices(n::Int, field::AbstractNumbers=ℝ)

Generate the manifold of $n × n$ symmetric matrices.

source
ManifoldsBase.check_point — Method
check_point(M::SymmetricMatrices{n,𝔽}, p; kwargs...)

Check whether p is a valid manifold point on the SymmetricMatrices M, i.e. whether p is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.

The tolerance for the symmetry of p can be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SymmetricMatrices{n,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.

The tolerance for the symmetry of X can be set using kwargs....

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SymmetricMatrices{n,𝔽})

Return the dimension of the SymmetricMatrices matrix M over the number system 𝔽, i.e.

\[\begin{aligned} \dim \mathrm{Sym}(n,ℝ) &= \frac{n(n+1)}{2},\\ \dim \mathrm{Sym}(n,ℂ) &= 2\frac{n(n+1)}{2} - n = n^2, -\end{aligned}\]

where the last $-n$ is due to the zero imaginary part for Hermitian matrices

source
ManifoldsBase.project — Method
project(M::SymmetricMatrices, p, X)

Project the matrix X onto the tangent space at p on the SymmetricMatrices M,

\[\operatorname{proj}_p(X) = \frac{1}{2} \bigl( X + X^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::SymmetricMatrices, p)

Projects p from the embedding onto the SymmetricMatrices M, i.e.

\[\operatorname{proj}_{\operatorname{Sym}(n)}(p) = \frac{1}{2} \bigl( p + p^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
+\end{aligned}\]

where the last $-n$ is due to the zero imaginary part for Hermitian matrices

source
ManifoldsBase.project — Method
project(M::SymmetricMatrices, p, X)

Project the matrix X onto the tangent space at p on the SymmetricMatrices M,

\[\operatorname{proj}_p(X) = \frac{1}{2} \bigl( X + X^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
ManifoldsBase.project — Method
project(M::SymmetricMatrices, p)

Projects p from the embedding onto the SymmetricMatrices M, i.e.

\[\operatorname{proj}_{\operatorname{Sym}(n)}(p) = \frac{1}{2} \bigl( p + p^{\mathrm{H}} \bigr),\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transposed.

source
diff --git a/previews/PR628/manifolds/symmetricpositivedefinite.html b/previews/PR628/manifolds/symmetricpositivedefinite.html index 2ceee2896b..493628afd4 100644 --- a/previews/PR628/manifolds/symmetricpositivedefinite.html +++ b/previews/PR628/manifolds/symmetricpositivedefinite.html @@ -5,23 +5,23 @@ \bigr\}\]

The tangent space at $T_p\mathcal P(n)$ reads

\[ T_p\mathcal P(n) = \bigl\{ X \in \mathbb R^{n×n} \big|\ X=X^\mathrm{T} - \bigr\},\]

i.e. the set of symmetric matrices,

Constructor

SymmetricPositiveDefinite(n)

generates the manifold $\mathcal P(n) \subset ℝ^{n × n}$

source

This manifold can – for example – be illustrated as ellipsoids: since the eigenvalues are all positive they can be taken as lengths of the axes of an ellipsoids while the directions are given by the eigenvectors.

An example set of data

The manifold can be equipped with different metrics

Common and metric independent functions

Base.convert — Method
convert(::Type{AbstractMatrix}, p::SPDPoint)

return the point p as a matrix. The matrix is either stored within the SPDPoint or reconstructed from p.eigen.

source
Base.rand — Method
rand(M::SymmetricPositiveDefinite; σ::Real=1)

Generate a random symmetric positive definite matrix on the SymmetricPositiveDefinite manifold M.

source
ManifoldsBase.check_point — Method
check_point(M::SymmetricPositiveDefinite, p; kwargs...)

checks, whether p is a valid point on the SymmetricPositiveDefinite M, i.e. is a matrix of size (N,N), symmetric and positive definite. The tolerance for the second to last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SymmetricPositiveDefinite, p, X; kwargs... )

Check whether X is a tangent vector to p on the SymmetricPositiveDefinite M, i.e. atfer check_point(M,p), X has to be of same dimension as p and a symmetric matrix, i.e. this stores tangent vetors as elements of the corresponding Lie group. The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.injectivity_radius — Method
injectivity_radius(M::SymmetricPositiveDefinite[, p])
+    \bigr\},\]
i.e. the set of symmetric matrices,
Constructor
SymmetricPositiveDefinite(n)
generates the manifold $\mathcal P(n) \subset ℝ^{n × n}$
source

This manifold can – for example – be illustrated as ellipsoids: since the eigenvalues are all positive they can be taken as lengths of the axes of an ellipsoids while the directions are given by the eigenvectors.

An example set of data

The manifold can be equipped with different metrics

Common and metric independent functions

Base.convert — Method
convert(::Type{AbstractMatrix}, p::SPDPoint)

return the point p as a matrix. The matrix is either stored within the SPDPoint or reconstructed from p.eigen.

source
Base.rand — Method
rand(M::SymmetricPositiveDefinite; σ::Real=1)

Generate a random symmetric positive definite matrix on the SymmetricPositiveDefinite manifold M.

source
ManifoldsBase.check_point — Method
check_point(M::SymmetricPositiveDefinite, p; kwargs...)

checks, whether p is a valid point on the SymmetricPositiveDefinite M, i.e. is a matrix of size (N,N), symmetric and positive definite. The tolerance for the second to last test can be set using the kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SymmetricPositiveDefinite, p, X; kwargs... )

Check whether X is a tangent vector to p on the SymmetricPositiveDefinite M, i.e. atfer check_point(M,p), X has to be of same dimension as p and a symmetric matrix, i.e. this stores tangent vetors as elements of the corresponding Lie group. The tolerance for the last test can be set using the kwargs....

source

Default metric: the affine invariant metric

Manifolds.AffineInvariantMetric — Type
AffineInvariantMetric <: AbstractMetric

The linear affine metric is the metric for symmetric positive definite matrices, that employs matrix logarithms and exponentials, which yields a linear and affine metric.

source

This metric is also the default metric, i.e. any call of the following functions with P=SymmetricPositiveDefinite(3) will result in MetricManifold(P,AffineInvariantMetric())and hence yield the formulae described in this seciton.

Base.exp — Method
exp(M::SymmetricPositiveDefinite, p, X)
-exp(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, X)

Compute the exponential map from p with tangent vector X on the SymmetricPositiveDefinite M with its default MetricManifold having the AffineInvariantMetric. The formula reads

\[\exp_p X = p^{\frac{1}{2}}\operatorname{Exp}(p^{-\frac{1}{2}} X p^{-\frac{1}{2}})p^{\frac{1}{2}},\]

where $\operatorname{Exp}$ denotes to the matrix exponential.

source

Default metric: the affine invariant metric

Manifolds.AffineInvariantMetric — Type
AffineInvariantMetric <: AbstractMetric

The linear affine metric is the metric for symmetric positive definite matrices, that employs matrix logarithms and exponentials, which yields a linear and affine metric.

source

This metric is also the default metric, i.e. any call of the following functions with P=SymmetricPositiveDefinite(3) will result in MetricManifold(P,AffineInvariantMetric())and hence yield the formulae described in this seciton.

Base.exp — Method
exp(M::SymmetricPositiveDefinite, p, X)
+exp(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, X)

Compute the exponential map from p with tangent vector X on the SymmetricPositiveDefinite M with its default MetricManifold having the AffineInvariantMetric. The formula reads

\[\exp_p X = p^{\frac{1}{2}}\operatorname{Exp}(p^{-\frac{1}{2}} X p^{-\frac{1}{2}})p^{\frac{1}{2}},\]

where $\operatorname{Exp}$ denotes to the matrix exponential.

source
Base.log — Method
log(M::SymmetricPositiveDefinite, p, q)
 log(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)

Compute the logarithmic map from p to q on the SymmetricPositiveDefinite as a MetricManifold with AffineInvariantMetric. The formula reads

\[\log_p q = -p^{\frac{1}{2}}\operatorname{Log}(p^{-\frac{1}{2}}qp^{-\frac{1}{2}})p^{\frac{1}{2}},\]

where $\operatorname{Log}$ denotes to the matrix logarithm.

source
ManifoldsBase.change_metric — Method
change_metric(M::SymmetricPositiveDefinite{n}, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal P(n)$ with respect to the EuclideanMetric g_E, this function changes into the AffineInvariantMetric (default) metric on the SymmetricPositiveDefinite M.

To be precise we are looking for $c\colon T_p\mathcal P(n) \to T_p\mathcal P(n)$ such that for all $Y,Z ∈ T_p\mathcal P(n)$` it holds

\[⟨Y,Z⟩ = \operatorname{tr}(YZ) = \operatorname{tr}(p^{-1}c(Y)p^{-1}c(Z)) = g_p(c(Z),c(Y))\]

and hence $c(X) = pX$ is computed.

source
ManifoldsBase.change_representer — Method
change_representer(M::SymmetricPositiveDefinite, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the AffineInvariantMetric on the SymmetricPositiveDefinite M.

To be precise we are looking for $Z∈T_p\mathcal P(n)$ such that for all $Y∈T_p\mathcal P(n)$` it holds

\[⟨X,Y⟩ = \operatorname{tr}(XY) = \operatorname{tr}(p^{-1}Zp^{-1}Y) = g_p(Z,Y)\]

and hence $Z = pXp$.

source
ManifoldsBase.distance — Method
distance(M::SymmetricPositiveDefinite, p, q)
+p^{\frac{1}{2}}\operatorname{Log}(p^{-\frac{1}{2}}qp^{-\frac{1}{2}})p^{\frac{1}{2}},\]
where $\operatorname{Log}$ denotes to the matrix logarithm.
source
ManifoldsBase.change_metric — Method
change_metric(M::SymmetricPositiveDefinite{n}, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal P(n)$ with respect to the EuclideanMetric g_E, this function changes into the AffineInvariantMetric (default) metric on the SymmetricPositiveDefinite M.

To be precise we are looking for $c\colon T_p\mathcal P(n) \to T_p\mathcal P(n)$ such that for all $Y,Z ∈ T_p\mathcal P(n)$` it holds

\[⟨Y,Z⟩ = \operatorname{tr}(YZ) = \operatorname{tr}(p^{-1}c(Y)p^{-1}c(Z)) = g_p(c(Z),c(Y))\]

and hence $c(X) = pX$ is computed.

source
ManifoldsBase.change_representer — Method
change_representer(M::SymmetricPositiveDefinite, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the AffineInvariantMetric on the SymmetricPositiveDefinite M.

To be precise we are looking for $Z∈T_p\mathcal P(n)$ such that for all $Y∈T_p\mathcal P(n)$` it holds

\[⟨X,Y⟩ = \operatorname{tr}(XY) = \operatorname{tr}(p^{-1}Zp^{-1}Y) = g_p(Z,Y)\]

and hence $Z = pXp$.

source
ManifoldsBase.distance — Method
distance(M::SymmetricPositiveDefinite, p, q)
 distance(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)

Compute the distance on the SymmetricPositiveDefinite manifold between p and q, as a MetricManifold with AffineInvariantMetric. The formula reads

\[d_{\mathcal P(n)}(p,q) -= \lVert \operatorname{Log}(p^{-\frac{1}{2}}qp^{-\frac{1}{2}})\rVert_{\mathrm{F}}.,\]

where $\operatorname{Log}$ denotes the matrix logarithm and $\lVert\cdot\rVert_{\mathrm{F}}$ denotes the matrix Frobenius norm.

source
ManifoldsBase.get_basis — Method
[Ξ,κ] = get_basis(M::SymmetricPositiveDefinite, p, B::DefaultOrthonormalBasis)
+= \lVert \operatorname{Log}(p^{-\frac{1}{2}}qp^{-\frac{1}{2}})\rVert_{\mathrm{F}}.,\]
where $\operatorname{Log}$ denotes the matrix logarithm and $\lVert\cdot\rVert_{\mathrm{F}}$ denotes the matrix Frobenius norm.
source
ManifoldsBase.get_basis — Method
[Ξ,κ] = get_basis(M::SymmetricPositiveDefinite, p, B::DefaultOrthonormalBasis)
 [Ξ,κ] = get_basis(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, B::DefaultOrthonormalBasis)

Return a default ONB for the tangent space $T_p\mathcal P(n)$ of the SymmetricPositiveDefinite with respect to the AffineInvariantMetric.

\[ g_p(X,Y) = \operatorname{tr}(p^{-1} X p^{-1} Y),\]

The basis constructed here is based on the ONB for symmetric matrices constructed as follows. Let

\[\Delta_{i,j} = (a_{k,l})_{k,l=1}^n \quad \text{ with } a_{k,l} = \begin{cases} 1 & \mbox{ for } k=l \text{ if } i=j\\ \frac{1}{\sqrt{2}} & \mbox{ for } k=i, l=j \text{ or } k=j, l=i\\ 0 & \text{ else.} -\end{cases}\]

which forms an ONB for the space of symmetric matrices.

We then form the ONB by

\[ \Xi_{i,j} = p^{\frac{1}{2}}\Delta_{i,j}p^{\frac{1}{2}},\qquad i=1,\ldots,n, j=i,\ldots,n.\]

source
ManifoldsBase.get_basis_diagonalizing — Method
[Ξ,κ] = get_basis_diagonalizing(M::SymmetricPositiveDefinite, p, B::DiagonalizingOrthonormalBasis)
-[Ξ,κ] = get_basis_diagonalizing(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, B::DiagonalizingOrthonormalBasis)

Return a orthonormal basis Ξ as a vector of tangent vectors (of length manifold_dimension of M) in the tangent space of p on the MetricManifold of SymmetricPositiveDefinite manifold M with AffineInvariantMetric that diagonalizes the curvature tensor $R(u,v)w$ with eigenvalues κ and where the direction B.frame_direction $V$ has curvature 0.

The construction is based on an ONB for the symmetric matrices similar to get_basis(::SymmetricPositiveDefinite, p, ::DefaultOrthonormalBasis just that the ONB here is build from the eigen vectors of $p^{\frac{1}{2}}Vp^{\frac{1}{2}}$.

source
ManifoldsBase.get_coordinates — Method
get_coordinates(::SymmetricPositiveDefinite, p, X, ::DefaultOrthonormalBasis)

Using the basis from get_basis the coordinates with respect to this ONB can be simplified to

\[ c_k = \mathrm{tr}(p^{-\frac{1}{2}}\Delta_{i,j} X)\]

where $k$ is trhe linearized index of the $i=1,\ldots,n, j=i,\ldots,n$.

source
ManifoldsBase.get_vector — Method
get_vector(::SymmetricPositiveDefinite, p, c, ::DefaultOrthonormalBasis)

Using the basis from get_basis the vector reconstruction with respect to this ONB can be simplified to

\[ X = p^{\frac{1}{2}} \Biggl( \sum_{i=1,j=i}^n c_k \Delta_{i,j} \Biggr) p^{\frac{1}{2}}\]

where $k$ is the linearized index of the $i=1,\ldots,n, j=i,\ldots,n$.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::SymmetricPositiveDefinite, p, X, q)
+\end{cases}\]
which forms an ONB for the space of symmetric matrices.
We then form the ONB by
\[   \Xi_{i,j} = p^{\frac{1}{2}}\Delta_{i,j}p^{\frac{1}{2}},\qquad i=1,\ldots,n, j=i,\ldots,n.\]
source
ManifoldsBase.get_basis_diagonalizing — Method
[Ξ,κ] = get_basis_diagonalizing(M::SymmetricPositiveDefinite, p, B::DiagonalizingOrthonormalBasis)
+[Ξ,κ] = get_basis_diagonalizing(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, B::DiagonalizingOrthonormalBasis)

Return a orthonormal basis Ξ as a vector of tangent vectors (of length manifold_dimension of M) in the tangent space of p on the MetricManifold of SymmetricPositiveDefinite manifold M with AffineInvariantMetric that diagonalizes the curvature tensor $R(u,v)w$ with eigenvalues κ and where the direction B.frame_direction $V$ has curvature 0.

The construction is based on an ONB for the symmetric matrices similar to get_basis(::SymmetricPositiveDefinite, p, ::DefaultOrthonormalBasis just that the ONB here is build from the eigen vectors of $p^{\frac{1}{2}}Vp^{\frac{1}{2}}$.

source
ManifoldsBase.get_coordinates — Method
get_coordinates(::SymmetricPositiveDefinite, p, X, ::DefaultOrthonormalBasis)

Using the basis from get_basis the coordinates with respect to this ONB can be simplified to

\[ c_k = \mathrm{tr}(p^{-\frac{1}{2}}\Delta_{i,j} X)\]

where $k$ is trhe linearized index of the $i=1,\ldots,n, j=i,\ldots,n$.

source
ManifoldsBase.get_vector — Method
get_vector(::SymmetricPositiveDefinite, p, c, ::DefaultOrthonormalBasis)

Using the basis from get_basis the vector reconstruction with respect to this ONB can be simplified to

\[ X = p^{\frac{1}{2}} \Biggl( \sum_{i=1,j=i}^n c_k \Delta_{i,j} \Biggr) p^{\frac{1}{2}}\]

where $k$ is the linearized index of the $i=1,\ldots,n, j=i,\ldots,n$.

source
ManifoldsBase.parallel_transport_to — Method
parallel_transport_to(M::SymmetricPositiveDefinite, p, X, q)
 parallel_transport_to(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, X, y)

Compute the parallel transport of X from the tangent space at p to the tangent space at q on the SymmetricPositiveDefinite as a MetricManifold with the AffineInvariantMetric. The formula reads

\[\mathcal P_{q←p}X = p^{\frac{1}{2}} \operatorname{Exp}\bigl( \frac{1}{2}p^{-\frac{1}{2}}\log_p(q)p^{-\frac{1}{2}} @@ -30,22 +30,22 @@ \operatorname{Exp}\bigl( \frac{1}{2}p^{-\frac{1}{2}}\log_p(q)p^{-\frac{1}{2}} \bigr) -p^{\frac{1}{2}},\]

where $\operatorname{Exp}$ denotes the matrix exponential and log the logarithmic map on SymmetricPositiveDefinite (again with respect to the AffineInvariantMetric).

source
ManifoldsBase.riemann_tensor — Method
riemann_tensor(::SymmetricPositiveDefinite, p, X, Y, Z)

Compute the value of Riemann tensor on the SymmetricPositiveDefinite manifold. The formula reads[Rentmeesters2011] $R(X,Y)Z=p^{1/2}R(X_I, Y_I)Z_Ip^{1/2}$, where $R_I(X_I, Y_I)Z_I=\frac{1}{4}[Z_I, [X_I, Y_I]]$, $X_I=p^{-1/2}Xp^{-1/2}$, $Y_I=p^{-1/2}Yp^{-1/2}$ and $Z_I=p^{-1/2}Zp^{-1/2}$.

source

Bures-Wasserstein metric

Base.exp — Method
exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X)

Compute the exponential map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by

\[ \exp_p(X) = p+X+L_p(X)pL_p(X)\]

where $q=L_p(X)$ denotes the Lyapunov operator, i.e. it solves $pq + qp = X$.

source
Base.log — Method
log(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)

Compute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by

\[ \log_p(q) = (pq)^{\frac{1}{2}} + (qp)^{\frac{1}{2}} - 2 p\]

where $q=L_p(X)$ denotes the Lyapunov operator, i.e. it solves $pq + qp = X$.

source
ManifoldsBase.change_representer — Method
change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the BuresWassersteinMetric on the SymmetricPositiveDefinite M.

To be precise we are looking for $Z∈T_p\mathcal P(n)$ such that for all $Y∈T_p\mathcal P(n)$` it holds

\[⟨X,Y⟩ = \operatorname{tr}(XY) = ⟨Z,Y⟩_{\mathrm{BW}}\]

for all $Y$ and hence we get $Z$= 2(A+A^{\mathrm{T}})$with$A=Xp``.

source
ManifoldsBase.distance — Method
distance(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)

Compute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.

\[d(p,q) = - \operatorname{tr}(p) + \operatorname{tr}(q) - 2\operatorname{tr}\Bigl( (p^{\frac{1}{2}}qp^{\frac{1}{2}} \bigr)^\frac{1}{2} \Bigr),\]

where the last trace can be simplified (by rotating the matrix products in the trace) to $\operatorname{tr}(pq)$.

source

Generalized Bures-Wasserstein metric

Manifolds.GeneralizedBuresWassersteinMetric — Type
GeneralizedBurresWassertseinMetric{T<:AbstractMatrix} <: AbstractMetric

The generalized Bures Wasserstein metric for symmetric positive definite matrices, see[HanMishraJawanpuriaGao2021].

This metric internally stores the symmetric positive definite matrix $M$ to generalise the metric, where the name also follows the mentioned preprint.

source
Base.exp — Method
exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, X)

Compute the exponential map on SymmetricPositiveDefinite with respect to the GeneralizedBuresWassersteinMetric given by

\[ \exp_p(X) = p+X+\mathcal ML_{p,M}(X)pML_{p,M}(X)\]

where $q=L_{M,p}(X)$ denotes the generalized Lyapunov operator, i.e. it solves $pqM + Mqp = X$.

source
Base.log — Method
log(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)

Compute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by

\[ \log_p(q) = M(M^{-1}pM^{-1}q)^{\frac{1}{2}} + (qM^{-1}pM^{-1})^{\frac{1}{2}}M - 2 p.\]

source
ManifoldsBase.change_representer — Method
change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the GeneralizedBuresWassersteinMetric on the SymmetricPositiveDefinite M.

To be precise we are looking for $Z∈T_p\mathcal P(n)$ such that for all $Y∈T_p\mathcal P(n)$ it holds

\[⟨X,Y⟩ = \operatorname{tr}(XY) = ⟨Z,Y⟩_{\mathrm{BW}}\]

for all $Y$ and hence we get $Z = 2pXM + 2MXp$.

source
ManifoldsBase.distance — Method
distance(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)

Compute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.

\[d(p,q) = \operatorname{tr}(M^{-1}p) + \operatorname{tr}(M^{-1}q) - - 2\operatorname{tr}\bigl( (p^{\frac{1}{2}}M^{-1}qM^{-1}p^{\frac{1}{2}} \bigr)^{\frac{1}{2}},\]

source

Log-Euclidean metric

Manifolds.LogEuclideanMetric — Type
LogEuclideanMetric <: RiemannianMetric

The LogEuclidean Metric consists of the Euclidean metric applied to all elements after mapping them into the Lie Algebra, i.e. performing a matrix logarithm beforehand.

source
ManifoldsBase.distance — Method
distance(M::MetricManifold{SymmetricPositiveDefinite{N},LogEuclideanMetric}, p, q)

Compute the distance on the SymmetricPositiveDefinite manifold between p and q as a MetricManifold with LogEuclideanMetric. The formula reads

\[ d_{\mathcal P(n)}(p,q) = \lVert \operatorname{Log} p - \operatorname{Log} q \rVert_{\mathrm{F}}\]

where $\operatorname{Log}$ denotes the matrix logarithm and $\lVert\cdot\rVert_{\mathrm{F}}$ denotes the matrix Frobenius norm.

source

Log-Cholesky metric

Base.exp — Method
exp(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, X)

Compute the exponential map on the SymmetricPositiveDefinite M with LogCholeskyMetric from p into direction X. The formula reads

\[\exp_p X = (\exp_y W)(\exp_y W)^\mathrm{T}\]

where $\exp_xW$ is the exponential map on CholeskySpace, $y$ is the cholesky decomposition of $p$, $W = y(y^{-1}Xy^{-\mathrm{T}})_\frac{1}{2}$, and $(\cdot)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$.

source
Base.log — Method
log(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)

Compute the logarithmic map on SymmetricPositiveDefinite M with respect to the LogCholeskyMetric emanating from p to q. The formula can be adapted from the CholeskySpace as

\[\log_p q = xW^{\mathrm{T}} + Wx^{\mathrm{T}},\]

where $x$ is the cholesky factor of $p$ and $W=\log_x y$ for $y$ the cholesky factor of $q$ and the just mentioned logarithmic map is the one on CholeskySpace.

source
ManifoldsBase.distance — Method
distance(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)

Compute the distance on the manifold of SymmetricPositiveDefinite nmatrices, i.e. between two symmetric positive definite matrices p and q with respect to the LogCholeskyMetric. The formula reads

\[d_{\mathcal P(n)}(p,q) = \sqrt{ +p^{\frac{1}{2}},\]

where $\operatorname{Exp}$ denotes the matrix exponential and log the logarithmic map on SymmetricPositiveDefinite (again with respect to the AffineInvariantMetric).

source
ManifoldsBase.riemann_tensor — Method
riemann_tensor(::SymmetricPositiveDefinite, p, X, Y, Z)

Compute the value of Riemann tensor on the SymmetricPositiveDefinite manifold. The formula reads[Rentmeesters2011] $R(X,Y)Z=p^{1/2}R(X_I, Y_I)Z_Ip^{1/2}$, where $R_I(X_I, Y_I)Z_I=\frac{1}{4}[Z_I, [X_I, Y_I]]$, $X_I=p^{-1/2}Xp^{-1/2}$, $Y_I=p^{-1/2}Yp^{-1/2}$ and $Z_I=p^{-1/2}Zp^{-1/2}$.

source

Bures-Wasserstein metric

Base.exp — Method
exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X)

Compute the exponential map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by

\[ \exp_p(X) = p+X+L_p(X)pL_p(X)\]

where $q=L_p(X)$ denotes the Lyapunov operator, i.e. it solves $pq + qp = X$.

source
Base.log — Method
log(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)

Compute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by

\[ \log_p(q) = (pq)^{\frac{1}{2}} + (qp)^{\frac{1}{2}} - 2 p\]

where $q=L_p(X)$ denotes the Lyapunov operator, i.e. it solves $pq + qp = X$.

source
ManifoldsBase.change_representer — Method
change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the BuresWassersteinMetric on the SymmetricPositiveDefinite M.

To be precise we are looking for $Z∈T_p\mathcal P(n)$ such that for all $Y∈T_p\mathcal P(n)$` it holds

\[⟨X,Y⟩ = \operatorname{tr}(XY) = ⟨Z,Y⟩_{\mathrm{BW}}\]

for all $Y$ and hence we get $Z$= 2(A+A^{\mathrm{T}})$with$A=Xp``.

source
ManifoldsBase.distance — Method
distance(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)

Compute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.

\[d(p,q) = + \operatorname{tr}(p) + \operatorname{tr}(q) - 2\operatorname{tr}\Bigl( (p^{\frac{1}{2}}qp^{\frac{1}{2}} \bigr)^\frac{1}{2} \Bigr),\]

where the last trace can be simplified (by rotating the matrix products in the trace) to $\operatorname{tr}(pq)$.

source

Generalized Bures-Wasserstein metric

Manifolds.GeneralizedBuresWassersteinMetric — Type
GeneralizedBurresWassertseinMetric{T<:AbstractMatrix} <: AbstractMetric

The generalized Bures Wasserstein metric for symmetric positive definite matrices, see[HanMishraJawanpuriaGao2021].

This metric internally stores the symmetric positive definite matrix $M$ to generalise the metric, where the name also follows the mentioned preprint.

source
Base.exp — Method
exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, X)

Compute the exponential map on SymmetricPositiveDefinite with respect to the GeneralizedBuresWassersteinMetric given by

\[ \exp_p(X) = p+X+\mathcal ML_{p,M}(X)pML_{p,M}(X)\]

where $q=L_{M,p}(X)$ denotes the generalized Lyapunov operator, i.e. it solves $pqM + Mqp = X$.

source
Base.log — Method
log(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)

Compute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by

\[ \log_p(q) = M(M^{-1}pM^{-1}q)^{\frac{1}{2}} + (qM^{-1}pM^{-1})^{\frac{1}{2}}M - 2 p.\]

source
ManifoldsBase.change_representer — Method
change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, E::EuclideanMetric, p, X)

Given a tangent vector $X ∈ T_p\mathcal M$ representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the GeneralizedBuresWassersteinMetric on the SymmetricPositiveDefinite M.

To be precise we are looking for $Z∈T_p\mathcal P(n)$ such that for all $Y∈T_p\mathcal P(n)$ it holds

\[⟨X,Y⟩ = \operatorname{tr}(XY) = ⟨Z,Y⟩_{\mathrm{BW}}\]

for all $Y$ and hence we get $Z = 2pXM + 2MXp$.

source
ManifoldsBase.distance — Method
distance(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)

Compute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.

\[d(p,q) = \operatorname{tr}(M^{-1}p) + \operatorname{tr}(M^{-1}q) + - 2\operatorname{tr}\bigl( (p^{\frac{1}{2}}M^{-1}qM^{-1}p^{\frac{1}{2}} \bigr)^{\frac{1}{2}},\]

source

Log-Euclidean metric

Manifolds.LogEuclideanMetric — Type
LogEuclideanMetric <: RiemannianMetric

The LogEuclidean Metric consists of the Euclidean metric applied to all elements after mapping them into the Lie Algebra, i.e. performing a matrix logarithm beforehand.

source
ManifoldsBase.distance — Method
distance(M::MetricManifold{SymmetricPositiveDefinite{N},LogEuclideanMetric}, p, q)

Compute the distance on the SymmetricPositiveDefinite manifold between p and q as a MetricManifold with LogEuclideanMetric. The formula reads

\[ d_{\mathcal P(n)}(p,q) = \lVert \operatorname{Log} p - \operatorname{Log} q \rVert_{\mathrm{F}}\]

where $\operatorname{Log}$ denotes the matrix logarithm and $\lVert\cdot\rVert_{\mathrm{F}}$ denotes the matrix Frobenius norm.

source

Log-Cholesky metric

Base.exp — Method
exp(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, X)

Compute the exponential map on the SymmetricPositiveDefinite M with LogCholeskyMetric from p into direction X. The formula reads

\[\exp_p X = (\exp_y W)(\exp_y W)^\mathrm{T}\]

where $\exp_xW$ is the exponential map on CholeskySpace, $y$ is the cholesky decomposition of $p$, $W = y(y^{-1}Xy^{-\mathrm{T}})_\frac{1}{2}$, and $(\cdot)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$.

source
Base.log — Method
log(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)

Compute the logarithmic map on SymmetricPositiveDefinite M with respect to the LogCholeskyMetric emanating from p to q. The formula can be adapted from the CholeskySpace as

\[\log_p q = xW^{\mathrm{T}} + Wx^{\mathrm{T}},\]

where $x$ is the cholesky factor of $p$ and $W=\log_x y$ for $y$ the cholesky factor of $q$ and the just mentioned logarithmic map is the one on CholeskySpace.

source
ManifoldsBase.distance — Method
distance(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)

Compute the distance on the manifold of SymmetricPositiveDefinite nmatrices, i.e. between two symmetric positive definite matrices p and q with respect to the LogCholeskyMetric. The formula reads

\[d_{\mathcal P(n)}(p,q) = \sqrt{ \lVert ⌊ x ⌋ - ⌊ y ⌋ \rVert_{\mathrm{F}}^2 - + \lVert \log(\operatorname{diag}(x)) - \log(\operatorname{diag}(y))\rVert_{\mathrm{F}}^2 }\ \ ,\]

where $x$ and $y$ are the cholesky factors of $p$ and $q$, respectively, $⌊\cdot⌋$ denbotes the strictly lower triangular matrix of its argument, and $\lVert\cdot\rVert_{\mathrm{F}}$ the Frobenius norm.

source
ManifoldsBase.inner — Method
inner(M::MetricManifold{LogCholeskyMetric,ℝ,SymmetricPositiveDefinite}, p, X, Y)

Compute the inner product of two matrices X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with LogCholeskyMetric. The formula reads

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

where $⟨\cdot,\cdot⟩_x$ denotes inner product on the CholeskySpace, $z$ is the cholesky factor of $p$, $a_z(W) = z (z^{-1}Wz^{-\mathrm{T}})_{\frac{1}{2}}$, and $(\cdot)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$

source
ManifoldsBase.parallel_transport_to — Method
vector_transport_to(
+ + \lVert \log(\operatorname{diag}(x)) - \log(\operatorname{diag}(y))\rVert_{\mathrm{F}}^2 }\ \ ,\]
where $x$ and $y$ are the cholesky factors of $p$ and $q$, respectively, $⌊\cdot⌋$ denbotes the strictly lower triangular matrix of its argument, and $\lVert\cdot\rVert_{\mathrm{F}}$ the Frobenius norm.
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{LogCholeskyMetric,ℝ,SymmetricPositiveDefinite}, p, X, Y)

Compute the inner product of two matrices X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with LogCholeskyMetric. The formula reads

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

where $⟨\cdot,\cdot⟩_x$ denotes inner product on the CholeskySpace, $z$ is the cholesky factor of $p$, $a_z(W) = z (z^{-1}Wz^{-\mathrm{T}})_{\frac{1}{2}}$, and $(\cdot)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$

source
ManifoldsBase.parallel_transport_to — Method
vector_transport_to(
     M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric},
     p,
     X,
     q,
     ::ParallelTransport,
-)

Parallel transport the tangent vector X at p along the geodesic to q with respect to the SymmetricPositiveDefinite manifold M and LogCholeskyMetric. The parallel transport is based on the parallel transport on CholeskySpace: Let $x$ and $y$ denote the cholesky factors of p and q, respectively and $W = x(x^{-1}Xx^{-\mathrm{T}})_\frac{1}{2}$, where $(\cdot)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$. With $V$ the parallel transport on CholeskySpace from $x$ to $y$. The formula hear reads

\[\mathcal P_{q←p}X = yV^{\mathrm{T}} + Vy^{\mathrm{T}}.\]

source

Statistics

Statistics.mean — Method
mean(
+)

Parallel transport the tangent vector X at p along the geodesic to q with respect to the SymmetricPositiveDefinite manifold M and LogCholeskyMetric. The parallel transport is based on the parallel transport on CholeskySpace: Let $x$ and $y$ denote the cholesky factors of p and q, respectively and $W = x(x^{-1}Xx^{-\mathrm{T}})_\frac{1}{2}$, where $(\cdot)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$. With $V$ the parallel transport on CholeskySpace from $x$ to $y$. The formula hear reads

\[\mathcal P_{q←p}X = yV^{\mathrm{T}} + Vy^{\mathrm{T}}.\]

source

Statistics

Efficient representation

When a point p is used in several occasions, it might be beneficial to store the eigenvalues and vectors of p and optionally its square root and the inverse of the square root. The SPDPoint can be used for exactly that.

Manifolds.SPDPoint — Type
SPDPoint <: AbstractManifoldsPoint

Store the result of eigen(p) of an SPD matrix and (optionally) $p^{1/2}$ and $p^{-1/2}$ to avoid their repeated computations.

This result only has the result of eigen as a mandatory storage, the other three can be stored. If they are not stored they are computed and returned (but then still not stored) when required.

Constructor

SPDPoint(p::AbstractMatrix; store_p=true, store_sqrt=true, store_sqrt_inv=true)

Create an SPD point using an symmetric positive defincite matrix p, where you can optionally store p, sqrt and sqrt_inv

source

and there are three internal functions to be able to use SPDPoint interchangeably with the default representation as a matrix.

Manifolds.spd_sqrt — Function
spd_sqrt(p::AbstractMatrix)
-spd_sqrt(p::SPDPoint)

return $p^{\frac{1}{2}}$ by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.

This method assumes that p represents an spd matrix.

source
Manifolds.spd_sqrt_inv — Function
spd_sqrt_inv(p::SPDPoint)

return $p^{-\frac{1}{2}}$ by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.

This method assumes that p represents an spd matrix.

source
Manifolds.spd_sqrt_and_sqrt_inv — Function
spd_sqrt_and_sqrt_inv(p::AbstractMatrix)
-spd_sqrt_and_sqrt_inv(p::SPDPoint)

return $p^{\frac{1}{2}}$ and $p^{-\frac{1}{2}}$ by either computing them (if they are missing or for the AbstractMatrix) or returning their stored value from within the SPDPoint.

Compared to calling single methods spd_sqrt and spd_sqrt_inv this method only computes the eigenvectors once for the case of the AbstractMatrix or if both are missing.

This method assumes that p represents an spd matrix.

source

Literature

  • ChevallierKalungaAngulo2017

    E. Chevallier, E. Kalunga, and J. Angulo, “Kernel Density Estimation on Spaces of Gaussian Distributions and Symmetric Positive Definite Matrices,” SIAM J. Imaging Sci., vol. 10, no. 1, pp. 191–215, Jan. 2017, doi: 10.1137/15M1053566.

  • Rentmeesters2011

    Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.

  • MalagoMontruccioPistone2018

    Malagò, L., Montrucchio, L., Pistone, G.: Wasserstein Riemannian geometry of Gaussian densities. Information Geometry, 1, pp. 137–179, 2018. doi: 10.1007/s41884-018-0014-4

  • HanMishraJawanpuriaGao2021

    Han, A., Mishra, B., Jawanpuria, P., Gao, J.: Generalized Bures-Wasserstein geometry for positive definite matrices. arXiv: 2110.10464.

  • Lin2019

    Lin, Zenhua: "Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition", arXiv: 1908.09326.

+)

Compute the Riemannian mean of x using GeodesicInterpolation.

source

Efficient representation

When a point p is used in several occasions, it might be beneficial to store the eigenvalues and vectors of p and optionally its square root and the inverse of the square root. The SPDPoint can be used for exactly that.

Manifolds.SPDPoint — Type
SPDPoint <: AbstractManifoldsPoint

Store the result of eigen(p) of an SPD matrix and (optionally) $p^{1/2}$ and $p^{-1/2}$ to avoid their repeated computations.

This result only has the result of eigen as a mandatory storage, the other three can be stored. If they are not stored they are computed and returned (but then still not stored) when required.

Constructor

SPDPoint(p::AbstractMatrix; store_p=true, store_sqrt=true, store_sqrt_inv=true)

Create an SPD point using an symmetric positive defincite matrix p, where you can optionally store p, sqrt and sqrt_inv

source

and there are three internal functions to be able to use SPDPoint interchangeably with the default representation as a matrix.

Manifolds.spd_sqrt — Function
spd_sqrt(p::AbstractMatrix)
+spd_sqrt(p::SPDPoint)

return $p^{\frac{1}{2}}$ by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.

This method assumes that p represents an spd matrix.

source
Manifolds.spd_sqrt_inv — Function
spd_sqrt_inv(p::SPDPoint)

return $p^{-\frac{1}{2}}$ by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.

This method assumes that p represents an spd matrix.

source
Manifolds.spd_sqrt_and_sqrt_inv — Function
spd_sqrt_and_sqrt_inv(p::AbstractMatrix)
+spd_sqrt_and_sqrt_inv(p::SPDPoint)

return $p^{\frac{1}{2}}$ and $p^{-\frac{1}{2}}$ by either computing them (if they are missing or for the AbstractMatrix) or returning their stored value from within the SPDPoint.

Compared to calling single methods spd_sqrt and spd_sqrt_inv this method only computes the eigenvectors once for the case of the AbstractMatrix or if both are missing.

This method assumes that p represents an spd matrix.

source

Literature

  • ChevallierKalungaAngulo2017

    E. Chevallier, E. Kalunga, and J. Angulo, “Kernel Density Estimation on Spaces of Gaussian Distributions and Symmetric Positive Definite Matrices,” SIAM J. Imaging Sci., vol. 10, no. 1, pp. 191–215, Jan. 2017, doi: 10.1137/15M1053566.

  • Rentmeesters2011

    Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.

  • MalagoMontruccioPistone2018

    Malagò, L., Montrucchio, L., Pistone, G.: Wasserstein Riemannian geometry of Gaussian densities. Information Geometry, 1, pp. 137–179, 2018. doi: 10.1007/s41884-018-0014-4

  • HanMishraJawanpuriaGao2021

    Han, A., Mishra, B., Jawanpuria, P., Gao, J.: Generalized Bures-Wasserstein geometry for positive definite matrices. arXiv: 2110.10464.

  • Lin2019

    Lin, Zenhua: "Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition", arXiv: 1908.09326.

diff --git a/previews/PR628/manifolds/symmetricpsdfixedrank.html b/previews/PR628/manifolds/symmetricpsdfixedrank.html index 1f737a5da2..ac2cc78bf6 100644 --- a/previews/PR628/manifolds/symmetricpsdfixedrank.html +++ b/previews/PR628/manifolds/symmetricpsdfixedrank.html @@ -5,7 +5,7 @@ \text{ and } \operatorname{rank}(p) = k\bigr\},\]

where $\cdot^{\mathrm{H}}$ denotes the Hermitian, i.e. complex conjugate transpose, and the field $𝔽 ∈ \{ ℝ, ℂ\}$. We sometimes $\operatorname{SPS}_{k,𝔽}(n)$, when distinguishing the real- and complex-valued manifold is important.

An element is represented by $q ∈ 𝔽^{n × k}$ from the factorization $p = qq^{\mathrm{H}}$. Note that since for any unitary (orthogonal) $A ∈ 𝔽^{n × n}$ we have $(Aq)(Aq)^{\mathrm{H}} = qq^{\mathrm{H}} = p$, the representation is not unique, or in other words, the manifold is a quotient manifold of $𝔽^{n × k}$.

The tangent space at $p$, $T_p\operatorname{SPS}_k(n)$, is also represented by matrices $Y ∈ 𝔽^{n × k}$ and reads as

\[T_p\operatorname{SPS}_k(n) = \bigl\{ X ∈ 𝔽^{n × n}\,|\,X = qY^{\mathrm{H}} + Yq^{\mathrm{H}} \text{ i.e. } X = X^{\mathrm{H}} -\bigr\}.\]

Note that the metric used yields a non-complete manifold. The metric was used in[JourneeBachAbsilSepulchre2010][MassartAbsil2020].

Constructor

SymmetricPositiveSemidefiniteFixedRank(n::Int, k::Int, field::AbstractNumbers=ℝ)

Generate the manifold of $n × n$ symmetric positive semidefinite matrices of rank $k$ over the field of real numbers ℝ or complex numbers ℂ.

source
Base.exp — Method
exp(M::SymmetricPositiveSemidefiniteFixedRank, q, Y)

Compute the exponential map on the SymmetricPositiveSemidefiniteFixedRank, which just reads

\[ \exp_q Y = q+Y.\]

Note

Since the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing

\[ q_2 = \exp_p(\log_pq)\]

might yield a matrix $q_2\neq q$, but they represent the same point on the quotient manifold, i.e. $d_{\operatorname{SPS}_k(n)}(q_2,q) = 0$.

source
Base.log — Method
log(M::SymmetricPositiveSemidefiniteFixedRank, q, p)

Compute the logarithmic map on the SymmetricPositiveSemidefiniteFixedRank manifold by minimizing $\lVert p - qY\rVert$ with respect to $Y$.

Note

Since the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing

\[ q_2 = \exp_p(\log_pq)\]

might yield a matrix $q_2\neq q$, but they represent the same point on the quotient manifold, i.e. $d_{\operatorname{SPS}_k(n)}(q_2,q) = 0$.

source
ManifoldsBase._isapprox — Method
isapprox(M::SymmetricPositiveSemidefiniteFixedRank, p, q; kwargs...)

test, whether two points p, q are (approximately) nearly the same. Since this is a quotient manifold in the embedding, the test is performed by checking their distance, if they are not the same, i.e. that $d_{\mathcal M}(p,q) \approx 0$, where the comparison is performed with the classical isapprox. The kwargs... are passed on to this accordingly.

source
ManifoldsBase.check_point — Method
check_point(M::SymmetricPositiveSemidefiniteFixedRank{n,𝔽}, q; kwargs...)

Check whether q is a valid manifold point on the SymmetricPositiveSemidefiniteFixedRank M, i.e. whether p=q*q' is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽. The symmetry of p is not explicitly checked since by using q p is symmetric by construction. The tolerance for the symmetry of p can and the rank of q*q' be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SymmetricPositiveSemidefiniteFixedRank M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.

Due to the reduced representation this is fulfilled as soon as the matrix is of correct size.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽})

Return the dimension of the SymmetricPositiveSemidefiniteFixedRank matrix M over the number system 𝔽, i.e.

\[\begin{aligned} +\bigr\}.\]

Note that the metric used yields a non-complete manifold. The metric was used in[JourneeBachAbsilSepulchre2010][MassartAbsil2020].

Constructor

SymmetricPositiveSemidefiniteFixedRank(n::Int, k::Int, field::AbstractNumbers=ℝ)

Generate the manifold of $n × n$ symmetric positive semidefinite matrices of rank $k$ over the field of real numbers ℝ or complex numbers ℂ.

source
Base.exp — Method
exp(M::SymmetricPositiveSemidefiniteFixedRank, q, Y)

Compute the exponential map on the SymmetricPositiveSemidefiniteFixedRank, which just reads

\[ \exp_q Y = q+Y.\]

Note

Since the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing

\[ q_2 = \exp_p(\log_pq)\]

might yield a matrix $q_2\neq q$, but they represent the same point on the quotient manifold, i.e. $d_{\operatorname{SPS}_k(n)}(q_2,q) = 0$.

source
Base.log — Method
log(M::SymmetricPositiveSemidefiniteFixedRank, q, p)

Compute the logarithmic map on the SymmetricPositiveSemidefiniteFixedRank manifold by minimizing $\lVert p - qY\rVert$ with respect to $Y$.

Note

Since the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing

\[ q_2 = \exp_p(\log_pq)\]

might yield a matrix $q_2\neq q$, but they represent the same point on the quotient manifold, i.e. $d_{\operatorname{SPS}_k(n)}(q_2,q) = 0$.

source
ManifoldsBase._isapprox — Method
isapprox(M::SymmetricPositiveSemidefiniteFixedRank, p, q; kwargs...)

test, whether two points p, q are (approximately) nearly the same. Since this is a quotient manifold in the embedding, the test is performed by checking their distance, if they are not the same, i.e. that $d_{\mathcal M}(p,q) \approx 0$, where the comparison is performed with the classical isapprox. The kwargs... are passed on to this accordingly.

source
ManifoldsBase.check_point — Method
check_point(M::SymmetricPositiveSemidefiniteFixedRank{n,𝔽}, q; kwargs...)

Check whether q is a valid manifold point on the SymmetricPositiveSemidefiniteFixedRank M, i.e. whether p=q*q' is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽. The symmetry of p is not explicitly checked since by using q p is symmetric by construction. The tolerance for the symmetry of p can and the rank of q*q' be set using kwargs....

source
ManifoldsBase.check_vector — Method
check_vector(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽}, p, X; kwargs... )

Check whether X is a tangent vector to manifold point p on the SymmetricPositiveSemidefiniteFixedRank M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.

Due to the reduced representation this is fulfilled as soon as the matrix is of correct size.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽})

Return the dimension of the SymmetricPositiveSemidefiniteFixedRank matrix M over the number system 𝔽, i.e.

\[\begin{aligned} \dim \operatorname{SPS}_{k,ℝ}(n) &= kn - \frac{k(k-1)}{2},\\ \dim \operatorname{SPS}_{k,ℂ}(n) &= 2kn - k^2, -\end{aligned}\]

where the last $k^2$ is due to the zero imaginary part for Hermitian matrices diagonal

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::SymmetricPositiveSemidefiniteFixedRank, p, X, q)

transport the tangent vector X at p to q by projecting it onto the tangent space at q.

source
+\end{aligned}\]

where the last $k^2$ is due to the zero imaginary part for Hermitian matrices diagonal

source
ManifoldsBase.vector_transport_to — Method
vector_transport_to(M::SymmetricPositiveSemidefiniteFixedRank, p, X, q)

transport the tangent vector X at p to q by projecting it onto the tangent space at q.

source
diff --git a/previews/PR628/manifolds/symplectic.html b/previews/PR628/manifolds/symplectic.html index bc9cb5e5c4..33b7d1ea1e 100644 --- a/previews/PR628/manifolds/symplectic.html +++ b/previews/PR628/manifolds/symplectic.html @@ -4,10 +4,10 @@ 0_n & I_n \\ -I_n & 0_n \end{bmatrix}.\]

That means that an element $p \in \operatorname{Sp}(2n)$ must fulfill the requirement that

\[ \omega (p x, p y) = x^T(p^TQp)y = x^TQy = \omega(x, y),\]

leading to the requirement on $p$ that $p^TQp = Q$.

The symplectic manifold also forms a group under matrix multiplication, called the $\textit{symplectic group}$. Since all the symplectic matrices necessarily have determinant one, the symplectic group $\operatorname{Sp}(2n, \mathbb{F})$ is a subgroup of the special linear group, $\operatorname{SL}(2n, \mathbb{F})$. When the underlying field is either $\mathbb{R}$ or $\mathbb{C}$ the symplectic group with a manifold structure constitutes a Lie group, with the Lie Algebra

\[ \mathfrak{sp}(2n,F) = \{H \in \mathbb{F}^{2n \times 2n} \;|\; Q H + H^{T} Q = 0\}.\]

This set is also known as the Hamiltonian matrices, which have the property that $(QH)^T = QH$ and are commonly used in physics.

Manifolds.ExtendedSymplecticMetric — Type
ExtendedSymplecticMetric <: AbstractMetric

The extension of the RealSymplecticMetric at a point p \in \operatorname{Sp}(2n) as an inner product over the embedding space $ℝ^{2n \times 2n}$, i.e.

\[ \langle x, y \rangle_{p} = \langle p^{-1}x, p^{-1}\rangle_{\operatorname{Fr}} - = \operatorname{tr}(x^{\mathrm{T}}(pp^{\mathrm{T}})^{-1}y), \;\forall\; x, y \in ℝ^{2n \times 2n}.\]

source
Manifolds.RealSymplecticMetric — Type
RealSymplecticMetric <: RiemannianMetric

The canonical Riemannian metric on the symplectic manifold, defined pointwise for $p \in \operatorname{Sp}(2n)$ by [Fiori2011]

\[\begin{align*} + = \operatorname{tr}(x^{\mathrm{T}}(pp^{\mathrm{T}})^{-1}y), \;\forall\; x, y \in ℝ^{2n \times 2n}.\]

source
Manifolds.RealSymplecticMetric — Type
RealSymplecticMetric <: RiemannianMetric

The canonical Riemannian metric on the symplectic manifold, defined pointwise for $p \in \operatorname{Sp}(2n)$ by [Fiori2011]

\[\begin{align*} & g_p \colon T_p\operatorname{Sp}(2n) \times T_p\operatorname{Sp}(2n) \rightarrow ℝ, \\ & g_p(Z_1, Z_2) = \operatorname{tr}((p^{-1}Z_1)^{\mathrm{T}} (p^{-1}Z_2)). -\end{align*}\]

This metric is also the default metric for the Symplectic manifold.

source
Manifolds.Symplectic — Type
Symplectic{n, 𝔽} <: AbstractEmbeddedManifold{𝔽, DefaultIsometricEmbeddingType}

The symplectic manifold consists of all $2n \times 2n$ matrices which preserve the canonical symplectic form over $𝔽^{2n × 2n} \times 𝔽^{2n × 2n}$,

\[ \omega\colon 𝔽^{2n × 2n} \times 𝔽^{2n × 2n} \rightarrow 𝔽, +\end{align*}\]

This metric is also the default metric for the Symplectic manifold.

source
Manifolds.Symplectic — Type
Symplectic{n, 𝔽} <: AbstractEmbeddedManifold{𝔽, DefaultIsometricEmbeddingType}

The symplectic manifold consists of all $2n \times 2n$ matrices which preserve the canonical symplectic form over $𝔽^{2n × 2n} \times 𝔽^{2n × 2n}$,

\[ \omega\colon 𝔽^{2n × 2n} \times 𝔽^{2n × 2n} \rightarrow 𝔽, \quad \omega(x, y) = p^{\mathrm{T}} Q_{2n} q, \; x, y \in 𝔽^{2n × 2n},\]

where

\[Q_{2n} = \begin{bmatrix} 0_n & I_n \\ @@ -16,13 +16,13 @@ T_p\operatorname{Sp}(2n) &= \{X \in \mathbb{R}^{2n \times 2n} \;|\; p^{T}Q_{2n}X + X^{T}Q_{2n}p = 0 \}, \\ &= \{X = pQS \;|\; S ∈ R^{2n × 2n}, S^{\mathrm{T}} = S \}. -\end{align*}\]

Constructor

Symplectic(2n, field=ℝ) -> Symplectic{div(2n, 2), field}()

Generate the (real-valued) symplectic manifold of $2n \times 2n$ symplectic matrices. The constructor for the Symplectic manifold accepts the even column/row embedding dimension $2n$ for the real symplectic manifold, $ℝ^{2n × 2n}$.

source
Manifolds.SymplecticMatrix — Type
SymplecticMatrix{T}

A lightweight structure to represent the action of the matrix representation of the canonical symplectic form,

\[Q_{2n}(λ) = λ +\end{align*}\]

Constructor

Symplectic(2n, field=ℝ) -> Symplectic{div(2n, 2), field}()

Generate the (real-valued) symplectic manifold of $2n \times 2n$ symplectic matrices. The constructor for the Symplectic manifold accepts the even column/row embedding dimension $2n$ for the real symplectic manifold, $ℝ^{2n × 2n}$.

source
Manifolds.SymplecticMatrix — Type
SymplecticMatrix{T}

A lightweight structure to represent the action of the matrix representation of the canonical symplectic form,

\[Q_{2n}(λ) = λ \begin{bmatrix} 0_n & I_n \\ -I_n & 0_n -\end{bmatrix} \quad \in ℝ^{2n \times 2n},\]

such that the canonical symplectic form is represented by

\[\omega_{2n}(x, y) = x^{\mathrm{T}}Q_{2n}(1)y, \quad x, y \in ℝ^{2n}.\]

The entire matrix is however not instantiated in memory, instead a scalar $λ$ of type T is stored, which is used to keep track of scaling and transpose operations applied to each SymplecticMatrix. For example, given Q = SymplecticMatrix(1.0) represented as 1.0*[0 I; -I 0], the adjoint Q' returns SymplecticMatrix(-1.0) = (-1.0)*[0 I; -I 0].

source
Base.exp — Method
exp(M::Symplectic, p, X)
+\end{bmatrix} \quad \in ℝ^{2n \times 2n},\]
such that the canonical symplectic form is represented by
\[\omega_{2n}(x, y) = x^{\mathrm{T}}Q_{2n}(1)y, \quad x, y \in ℝ^{2n}.\]
The entire matrix is however not instantiated in memory, instead a scalar $λ$ of type T is stored, which is used to keep track of scaling and transpose operations applied  to each SymplecticMatrix. For example, given Q = SymplecticMatrix(1.0) represented as 1.0*[0 I; -I 0], the adjoint Q' returns SymplecticMatrix(-1.0) = (-1.0)*[0 I; -I 0].
source
Base.exp — Method
exp(M::Symplectic, p, X)
 exp!(M::Symplectic, q, p, X)

The Exponential mapping on the Symplectic manifold with the RealSymplecticMetric Riemannian metric.

For the point $p \in \operatorname{Sp}(2n)$ the exponential mapping along the tangent vector $X \in T_p\operatorname{Sp}(2n)$ is computed as [WangSunFiori2018]

\[ \operatorname{exp}_p(X) = p \operatorname{Exp}((p^{-1}X)^{\mathrm{T}}) - \operatorname{Exp}(p^{-1}X - (p^{-1}X)^{\mathrm{T}}),\]

where $\operatorname{Exp}(\cdot)$ denotes the matrix exponential.

source
Base.inv — Method
inv(::Symplectic, A)
+                                \operatorname{Exp}(p^{-1}X - (p^{-1}X)^{\mathrm{T}}),\]
where $\operatorname{Exp}(\cdot)$ denotes the matrix exponential.
source
Base.inv — Method
inv(::Symplectic, A)
 inv!(::Symplectic, A)

Compute the symplectic inverse $A^+$ of matrix $A ∈ ℝ^{2n × 2n}$. Given a matrix

\[A ∈ ℝ^{2n × 2n},\quad A = \begin{bmatrix} @@ -36,29 +36,29 @@ \begin{bmatrix} A_{2, 2}^{\mathrm{T}} & -A_{1, 2}^{\mathrm{T}} \\[1.2mm] -A_{2, 1}^{\mathrm{T}} & A_{1, 1}^{\mathrm{T}} -\end{bmatrix}.\]

source
Base.rand — Method
rand(::SymplecticStiefel; vector_at=nothing,
+\end{bmatrix}.\]
source
Base.rand — Method
rand(::SymplecticStiefel; vector_at=nothing,
     hamiltonian_norm = (vector_at === nothing ? 1/2 : 1.0))

Generate a random point on $\operatorname{Sp}(2n)$ or a random tangent vector $X \in T_p\operatorname{Sp}(2n)$ if vector_at is set to a point $p \in \operatorname{Sp}(2n)$.

A random point on $\operatorname{Sp}(2n)$ is constructed by generating a random Hamiltonian matrix $Ω \in \mathfrak{sp}(2n,F)$ with norm hamiltonian_norm, and then transforming it to a symplectic matrix by applying the Cayley transform

\[ \operatorname{cay}\colon \mathfrak{sp}(2n,F) \rightarrow \operatorname{Sp}(2n), - \; \Omega \mapsto (I - \Omega)^{-1}(I + \Omega).\]

To generate a random tangent vector in $T_p\operatorname{Sp}(2n)$, this code employs the second tangent vector space parametrization of Symplectic. It first generates a random symmetric matrix $S$ by S = randn(2n, 2n) and then symmetrizes it as S = S + S'. Then $S$ is normalized to have Frobenius norm of hamiltonian_norm and X = pQS is returned, where Q is the SymplecticMatrix.

source
ManifoldDiff.gradient — Method
gradient(M::Symplectic, f, p, backend::RiemannianProjectionBackend;
+    \; \Omega \mapsto (I - \Omega)^{-1}(I + \Omega).\]
To generate a random tangent vector in $T_p\operatorname{Sp}(2n)$, this code employs the second tangent vector space parametrization of Symplectic. It first generates a random symmetric matrix $S$ by S = randn(2n, 2n) and then symmetrizes it as S = S + S'. Then $S$ is normalized to have Frobenius norm of hamiltonian_norm and X = pQS is returned, where Q is the SymplecticMatrix.
source
ManifoldDiff.gradient — Method
gradient(M::Symplectic, f, p, backend::RiemannianProjectionBackend;
          extended_metric=true)
 gradient!(M::Symplectic, f, p, backend::RiemannianProjectionBackend;
-         extended_metric=true)

Compute the manifold gradient $\text{grad}f(p)$ of a scalar function $f \colon \operatorname{Sp}(2n) \rightarrow ℝ$ at $p \in \operatorname{Sp}(2n)$.

The element $\text{grad}f(p)$ is found as the Riesz representer of the differential $\text{D}f(p) \colon T_p\operatorname{Sp}(2n) \rightarrow ℝ$ w.r.t. the Riemannian metric inner product at $p$ [Fiori2011]. That is, $\text{grad}f(p) \in T_p\operatorname{Sp}(2n)$ solves the relation

\[ g_p(\text{grad}f(p), X) = \text{D}f(p) \quad\forall\; X \in T_p\operatorname{Sp}(2n).\]

The default behaviour is to first change the representation of the Euclidean gradient from the Euclidean metric to the RealSymplecticMetric at $p$, and then we projecting the result onto the correct tangent tangent space $T_p\operatorname{Sp}(2n, ℝ)$ w.r.t the Riemannian metric $g_p$ extended to the entire embedding space.

Arguments:

  • extended_metric = true: If true, compute the gradient $\text{grad}f(p)$ by first changing the representer of the Euclidean gradient of a smooth extension of $f$, $∇f(p)$, w.r.t. the RealSymplecticMetric at $p$ extended to the entire embedding space, before projecting onto the correct tangent vector space w.r.t. the same extended metric $g_p$. If false, compute the gradient by first projecting $∇f(p)$ onto the tangent vector space, before changing the representer in the tangent vector space to comply with the RealSymplecticMetric.
source
Manifolds.project_normal! — Method
project_normal!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X)

Project onto the normal of the tangent space $(T_p\operatorname{Sp}(2n))^{\perp_g}$ at a point $p ∈ \operatorname{Sp}(2n)$, relative to the riemannian metric $g$ RealSymplecticMetric. That is,

\[(T_p\operatorname{Sp}(2n))^{\perp_g} = \{Y \in \mathbb{R}^{2n \times 2n} : - g_p(Y, X) = 0 \;\forall\; X \in T_p\operatorname{Sp}(2n)\}.\]

The closed form projection operator onto the normal space is given by [GaoSonAbsilStykel2021]

\[\operatorname{P}^{(T_p\operatorname{Sp}(2n))\perp}_{g_p}(X) = pQ\operatorname{skew}(p^{\mathrm{T}}Q^{\mathrm{T}}X),\]

where $\operatorname{skew}(A) = \frac{1}{2}(A - A^{\mathrm{T}})$. This function is not exported.

source
Manifolds.symplectic_inverse_times — Method
symplectic_inverse_times(::Symplectic, p, q)
-symplectic_inverse_times!(::Symplectic, A, p, q)

Directly compute the symplectic inverse of $p \in \operatorname{Sp}(2n)$, multiplied with $q \in \operatorname{Sp}(2n)$. That is, this function efficiently computes $p^+q = (Q_{2n}p^{\mathrm{T}}Q_{2n})q \in ℝ^{2n \times 2n}$, where $Q_{2n}$ is the SymplecticMatrix of size $2n \times 2n$.

source
ManifoldsBase.change_representer — Method
change_representer(::Symplectic, ::EuclideanMetric, p, X)
+         extended_metric=true)

Compute the manifold gradient $\text{grad}f(p)$ of a scalar function $f \colon \operatorname{Sp}(2n) \rightarrow ℝ$ at $p \in \operatorname{Sp}(2n)$.

The element $\text{grad}f(p)$ is found as the Riesz representer of the differential $\text{D}f(p) \colon T_p\operatorname{Sp}(2n) \rightarrow ℝ$ w.r.t. the Riemannian metric inner product at $p$ [Fiori2011]. That is, $\text{grad}f(p) \in T_p\operatorname{Sp}(2n)$ solves the relation

\[ g_p(\text{grad}f(p), X) = \text{D}f(p) \quad\forall\; X \in T_p\operatorname{Sp}(2n).\]

The default behaviour is to first change the representation of the Euclidean gradient from the Euclidean metric to the RealSymplecticMetric at $p$, and then we projecting the result onto the correct tangent tangent space $T_p\operatorname{Sp}(2n, ℝ)$ w.r.t the Riemannian metric $g_p$ extended to the entire embedding space.

Arguments:

  • extended_metric = true: If true, compute the gradient $\text{grad}f(p)$ by first changing the representer of the Euclidean gradient of a smooth extension of $f$, $∇f(p)$, w.r.t. the RealSymplecticMetric at $p$ extended to the entire embedding space, before projecting onto the correct tangent vector space w.r.t. the same extended metric $g_p$. If false, compute the gradient by first projecting $∇f(p)$ onto the tangent vector space, before changing the representer in the tangent vector space to comply with the RealSymplecticMetric.
source
Manifolds.project_normal! — Method
project_normal!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X)

Project onto the normal of the tangent space $(T_p\operatorname{Sp}(2n))^{\perp_g}$ at a point $p ∈ \operatorname{Sp}(2n)$, relative to the riemannian metric $g$ RealSymplecticMetric. That is,

\[(T_p\operatorname{Sp}(2n))^{\perp_g} = \{Y \in \mathbb{R}^{2n \times 2n} : + g_p(Y, X) = 0 \;\forall\; X \in T_p\operatorname{Sp}(2n)\}.\]

The closed form projection operator onto the normal space is given by [GaoSonAbsilStykel2021]

\[\operatorname{P}^{(T_p\operatorname{Sp}(2n))\perp}_{g_p}(X) = pQ\operatorname{skew}(p^{\mathrm{T}}Q^{\mathrm{T}}X),\]

where $\operatorname{skew}(A) = \frac{1}{2}(A - A^{\mathrm{T}})$. This function is not exported.

source
Manifolds.symplectic_inverse_times — Method
symplectic_inverse_times(::Symplectic, p, q)
+symplectic_inverse_times!(::Symplectic, A, p, q)

Directly compute the symplectic inverse of $p \in \operatorname{Sp}(2n)$, multiplied with $q \in \operatorname{Sp}(2n)$. That is, this function efficiently computes $p^+q = (Q_{2n}p^{\mathrm{T}}Q_{2n})q \in ℝ^{2n \times 2n}$, where $Q_{2n}$ is the SymplecticMatrix of size $2n \times 2n$.

source
ManifoldsBase.change_representer — Method
change_representer(::Symplectic, ::EuclideanMetric, p, X)
 change_representer!(::Symplectic, Y, ::EuclideanMetric, p, X)

Compute the representation of a tangent vector $ξ ∈ T_p\operatorname{Sp}(2n, ℝ)$ s.t.

\[ g_p(c_p(ξ), η) = ⟨ξ, η⟩^{\text{Euc}} \;∀\; η ∈ T_p\operatorname{Sp}(2n, ℝ).\]

with the conversion function

\[ c_p : T_p\operatorname{Sp}(2n, ℝ) \rightarrow T_p\operatorname{Sp}(2n, ℝ), \quad c_p(ξ) = \frac{1}{2} pp^{\mathrm{T}} ξ + \frac{1}{2} pQ ξ^{\mathrm{T}} pQ.\]

Each of the terms $c_p^1(ξ) = p p^{\mathrm{T}} ξ$ and $c_p^2(ξ) = pQ ξ^{\mathrm{T}} pQ$ from the above definition of $c_p(η)$ are themselves metric compatible in the sense that

\[ c_p^i : T_p\operatorname{Sp}(2n, ℝ) \rightarrow \mathbb{R}^{2n \times 2n}\quad - g_p^i(c_p(ξ), η) = ⟨ξ, η⟩^{\text{Euc}} \;∀\; η ∈ T_p\operatorname{Sp}(2n, ℝ),\]

for $i \in {1, 2}$. However the range of each function alone is not confined to $T_p\operatorname{Sp}(2n, ℝ)$, but the convex combination

\[ c_p(ξ) = \frac{1}{2}c_p^1(ξ) + \frac{1}{2}c_p^2(ξ)\]

does have the correct range $T_p\operatorname{Sp}(2n, ℝ)$.

source
ManifoldsBase.change_representer — Method
change_representer(MetMan::MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric},
+    g_p^i(c_p(ξ), η) = ⟨ξ, η⟩^{\text{Euc}} \;∀\; η ∈ T_p\operatorname{Sp}(2n, ℝ),\]
for $i \in {1, 2}$. However the range of each function alone is not confined to $T_p\operatorname{Sp}(2n, ℝ)$, but the convex combination
\[    c_p(ξ) = \frac{1}{2}c_p^1(ξ) + \frac{1}{2}c_p^2(ξ)\]
does have the correct range $T_p\operatorname{Sp}(2n, ℝ)$.
source
ManifoldsBase.change_representer — Method
change_representer(MetMan::MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric},
                    EucMet::EuclideanMetric, p, X)
 change_representer!(MetMan::MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric},
                     Y, EucMet::EuclideanMetric, p, X)

Change the representation of a matrix $ξ ∈ \mathbb{R}^{2n \times 2n}$ into the inner product space $(ℝ^{2n \times 2n}, g_p)$ where the inner product is given by $g_p(ξ, η) = \langle p^{-1}ξ, p^{-1}η \rangle = \operatorname{tr}(ξ^{\mathrm{T}}(pp^{\mathrm{T}})^{-1}η)$, as the extension of the RealSymplecticMetric onto the entire embedding space.

By changing the representation we mean to apply a mapping

\[ c_p : \mathbb{R}^{2n \times 2n} \rightarrow \mathbb{R}^{2n \times 2n},\]

defined by requiring that it satisfy the metric compatibility condition

\[ g_p(c_p(ξ), η) = ⟨p^{-1}c_p(ξ), p^{-1}η⟩ = ⟨ξ, η⟩^{\text{Euc}} - \;∀\; η ∈ T_p\operatorname{Sp}(2n, ℝ).\]

In this case, we compute the mapping

\[ c_p(ξ) = pp^{\mathrm{T}} ξ.\]

source
ManifoldsBase.check_point — Method
check_point(M::Symplectic, p; kwargs...)

Check whether p is a valid point on the Symplectic M=$\operatorname{Sp}(2n)$, i.e. that it has the right AbstractNumbers type and $p^{+}p$ is (approximately) the identity, where $A^{+} = Q_{2n}^{\mathrm{T}}A^{\mathrm{T}}Q_{2n}$ is the symplectic inverse, with

\[Q_{2n} = + \;∀\; η ∈ T_p\operatorname{Sp}(2n, ℝ).\]

In this case, we compute the mapping

\[ c_p(ξ) = pp^{\mathrm{T}} ξ.\]

source
ManifoldsBase.check_point — Method
check_point(M::Symplectic, p; kwargs...)

Check whether p is a valid point on the Symplectic M=$\operatorname{Sp}(2n)$, i.e. that it has the right AbstractNumbers type and $p^{+}p$ is (approximately) the identity, where $A^{+} = Q_{2n}^{\mathrm{T}}A^{\mathrm{T}}Q_{2n}$ is the symplectic inverse, with

\[Q_{2n} = \begin{bmatrix} 0_n & I_n \\ -I_n & 0_n -\end{bmatrix}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.check_vector — Method
check_vector(M::Symplectic, p, X; kwargs...)

Checks whether X is a valid tangent vector at p on the Symplectic M=$\operatorname{Sp}(2n)$, i.e. the AbstractNumbers fits and it (approximately) holds that $p^{T}Q_{2n}X + X^{T}Q_{2n}p = 0$, where

\[Q_{2n} = +\end{bmatrix}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.check_vector — Method
check_vector(M::Symplectic, p, X; kwargs...)

Checks whether X is a valid tangent vector at p on the Symplectic M=$\operatorname{Sp}(2n)$, i.e. the AbstractNumbers fits and it (approximately) holds that $p^{T}Q_{2n}X + X^{T}Q_{2n}p = 0$, where

\[Q_{2n} = \begin{bmatrix} 0_n & I_n \\ -I_n & 0_n -\end{bmatrix}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.distance — Method
distance(M::Symplectic, p, q)

Compute an approximate geodesic distance between two Symplectic matrices $p, q \in \operatorname{Sp}(2n)$, as done in [WangSunFiori2018].

\[ \operatorname{dist}(p, q) +\end{bmatrix}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.distance — Method
distance(M::Symplectic, p, q)

Compute an approximate geodesic distance between two Symplectic matrices $p, q \in \operatorname{Sp}(2n)$, as done in [WangSunFiori2018].

\[ \operatorname{dist}(p, q) ≈ ||\operatorname{Log}(p^+q)||_{\operatorname{Fr}},\]

where the $\operatorname{Log}(\cdot)$ operator is the matrix logarithm.

This approximation is justified by first recalling the Baker-Campbell-Hausdorf formula,

\[\operatorname{Log}(\operatorname{Exp}(A)\operatorname{Exp}(B)) = A + B + \frac{1}{2}[A, B] + \frac{1}{12}[A, [A, B]] + \frac{1}{12}[B, [B, A]] + \ldots \;.\]

Then we write the expression for the exponential map from $p$ to $q$ as

\[ q = @@ -75,15 +75,15 @@ &= ||p^{+}X + \frac{1}{2}[(p^{+}X)^{\mathrm{T}}, p^{+}X - (p^{+}X)^{\mathrm{T}}] + \ldots ||_{\operatorname{Fr}} \\ &≈ ||p^{+}X||_{\operatorname{Fr}} = \operatorname{dist}(p, q). - \end{align*}\]

source
ManifoldsBase.inner — Method
inner(::Symplectic{n, ℝ}, p, X, Y)

Compute the canonical Riemannian inner product RealSymplecticMetric

\[ g_p(X, Y) = \operatorname{tr}((p^{-1}X)^{\mathrm{T}} (p^{-1}Y))\]

between the two tangent vectors $X, Y \in T_p\operatorname{Sp}(2n)$.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Symplectic, p, q, ::CayleyInverseRetraction)

Compute the Cayley Inverse Retraction $X = \mathcal{L}_p^{\operatorname{Sp}}(q)$ such that the Cayley Retraction from $p$ along $X$ lands at $q$, i.e. $\mathcal{R}_p(X) = q$ [BendokatZimmermann2021].

First, recall the definition the standard symplectic matrix

\[Q = + \end{align*}\]

source
ManifoldsBase.inner — Method
inner(::Symplectic{n, ℝ}, p, X, Y)

Compute the canonical Riemannian inner product RealSymplecticMetric

\[ g_p(X, Y) = \operatorname{tr}((p^{-1}X)^{\mathrm{T}} (p^{-1}Y))\]

between the two tangent vectors $X, Y \in T_p\operatorname{Sp}(2n)$.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Symplectic, p, q, ::CayleyInverseRetraction)

Compute the Cayley Inverse Retraction $X = \mathcal{L}_p^{\operatorname{Sp}}(q)$ such that the Cayley Retraction from $p$ along $X$ lands at $q$, i.e. $\mathcal{R}_p(X) = q$ [BendokatZimmermann2021].

First, recall the definition the standard symplectic matrix

\[Q = \begin{bmatrix} 0 & I \\ -I & 0 \end{bmatrix}\]

as well as the symplectic inverse of a matrix $A$, $A^{+} = Q^{\mathrm{T}} A^{\mathrm{T}} Q$.

For $p, q ∈ \operatorname{Sp}(2n, ℝ)$ then, we can then define the inverse cayley retraction as long as the following matrices exist.

\[ U = (I + p^+ q)^{-1}, \quad V = (I + q^+ p)^{-1}.\]

If that is the case, the inverse cayley retration at $p$ applied to $q$ is

\[\mathcal{L}_p^{\operatorname{Sp}}(q) = 2p\bigl(V - U\bigr) + 2\bigl((p + q)U - p\bigr) - ∈ T_p\operatorname{Sp}(2n).\]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(::Symplectic{n})

Returns the dimension of the symplectic manifold embedded in $ℝ^{2n \times 2n}$, i.e.

\[ \operatorname{dim}(\operatorname{Sp}(2n)) = (2n + 1)n.\]

source
ManifoldsBase.project! — Method
project!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X) where {𝔽}

Compute the projection of $X ∈ R^{2n × 2n}$ onto $T_p\operatorname{Sp}(2n, ℝ)$ w.r.t. the Riemannian metric $g$ RealSymplecticMetric. The closed form projection mapping is given by [GaoSonAbsilStykel2021]

\[ \operatorname{P}^{T_p\operatorname{Sp}(2n)}_{g_p}(X) = pQ\operatorname{sym}(p^{\mathrm{T}}Q^{\mathrm{T}}X),\]

where $\operatorname{sym}(A) = \frac{1}{2}(A + A^{\mathrm{T}})$. This function is not exported.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(::Symplectic{n})

Returns the dimension of the symplectic manifold embedded in $ℝ^{2n \times 2n}$, i.e.

\[ \operatorname{dim}(\operatorname{Sp}(2n)) = (2n + 1)n.\]

source
ManifoldsBase.project! — Method
project!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X) where {𝔽}

Compute the projection of $X ∈ R^{2n × 2n}$ onto $T_p\operatorname{Sp}(2n, ℝ)$ w.r.t. the Riemannian metric $g$ RealSymplecticMetric. The closed form projection mapping is given by [GaoSonAbsilStykel2021]

\[ \operatorname{P}^{T_p\operatorname{Sp}(2n)}_{g_p}(X) = pQ\operatorname{sym}(p^{\mathrm{T}}Q^{\mathrm{T}}X),\]

where $\operatorname{sym}(A) = \frac{1}{2}(A + A^{\mathrm{T}})$. This function is not exported.

source
ManifoldsBase.project — Method
project(::Symplectic, p, A)
 project!(::Symplectic, Y, p, A)

Given a point $p \in \operatorname{Sp}(2n)$, project an element $A \in \mathbb{R}^{2n \times 2n}$ onto the tangent space $T_p\operatorname{Sp}(2n)$ relative to the euclidean metric of the embedding $\mathbb{R}^{2n \times 2n}$.

That is, we find the element $X \in T_p\operatorname{SpSt}(2n, 2k)$ which solves the constrained optimization problem

\[ \operatorname{min}_{X \in \mathbb{R}^{2n \times 2n}} \frac{1}{2}||X - A||^2, \quad \text{s.t.}\; - h(X) \colon= X^{\mathrm{T}} Q p + p^{\mathrm{T}} Q X = 0,\]

where $h\colon\mathbb{R}^{2n \times 2n} \rightarrow \operatorname{skew}(2n)$ defines the restriction of $X$ onto the tangent space $T_p\operatorname{SpSt}(2n, 2k)$.

source
ManifoldsBase.retract — Method
retract(::Symplectic, p, X, ::CayleyRetraction)
+    h(X) \colon= X^{\mathrm{T}} Q p + p^{\mathrm{T}} Q X = 0,\]
where $h\colon\mathbb{R}^{2n \times 2n} \rightarrow \operatorname{skew}(2n)$ defines the restriction of $X$ onto the tangent space $T_p\operatorname{SpSt}(2n, 2k)$.
source
ManifoldsBase.retract — Method
retract(::Symplectic, p, X, ::CayleyRetraction)
 retract!(::Symplectic, q, p, X, ::CayleyRetraction)

Compute the Cayley retraction on $p ∈ \operatorname{Sp}(2n, ℝ)$ in the direction of tangent vector $X ∈ T_p\operatorname{Sp}(2n, ℝ)$, as defined in by Birtea et al in proposition 2 [BirteaCaşuComănescu2020].

Using the symplectic inverse of a matrix $A \in ℝ^{2n \times 2n}$, $A^{+} := Q_{2n}^{\mathrm{T}} A^{\mathrm{T}} Q_{2n}$ where

\[Q_{2n} = \begin{bmatrix} 0_n & I_n \\ @@ -92,4 +92,4 @@ \mathcal{R}_p(X) &= p \operatorname{cay}\left(\frac{1}{2}p^{+}X\right), \\ &= p \operatorname{exp}_{1/1}(p^{+}X), \\ &= p (2I - p^{+}X)^{-1}(2I + p^{+}X). -\end{align*}\]

Here $\operatorname{exp}_{1/1}(z) = (2 - z)^{-1}(2 + z)$ denotes the Padé (1, 1) approximation to $\operatorname{exp}(z)$.

source

Literature

  • WangSunFiori2018

    Wang, Jing and Sun, Huafei and Fiori, Simone: A Riemannian-steepest-descent approach for optimization on the real symplectic group, Mathematical Methods in the Applied Sciences, 41(11) pp. 4273-4286, 2018 doi 10.1002/mma.4890

  • Fiori2011

    Simone Fiori: Solving minimal-distance problems over the manifold of real-symplectic matrices, SIAM Journal on Matrix Analysis and Applications 32(3), pp. 938-968, 2011. doi 10.1137/100817115.

  • GaoSonAbsilStykel2021

    Gao, Bin and Son, Nguyen Thanh and Absil, P-A and Stykel, Tatjana: Riemannian optimization on the symplectic Stiefel manifold, SIAM Journal on Optimization 31(2), pp. 1546-1575, 2021. doi 10.1137/20M1348522

  • BendokatZimmermann2021

    Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.

  • BirteaCaşuComănescu2020

    Birtea, Petre and Caşu, Ioan and Comănescu, Dan: Optimization on the real symplectic group, Monatshefte f{"u}r Mathematik, Springer, 2020. doi 10.1007/s00605-020-01369-9

+\end{align*}\]

Here $\operatorname{exp}_{1/1}(z) = (2 - z)^{-1}(2 + z)$ denotes the Padé (1, 1) approximation to $\operatorname{exp}(z)$.

source

Literature

  • WangSunFiori2018

    Wang, Jing and Sun, Huafei and Fiori, Simone: A Riemannian-steepest-descent approach for optimization on the real symplectic group, Mathematical Methods in the Applied Sciences, 41(11) pp. 4273-4286, 2018 doi 10.1002/mma.4890

  • Fiori2011

    Simone Fiori: Solving minimal-distance problems over the manifold of real-symplectic matrices, SIAM Journal on Matrix Analysis and Applications 32(3), pp. 938-968, 2011. doi 10.1137/100817115.

  • GaoSonAbsilStykel2021

    Gao, Bin and Son, Nguyen Thanh and Absil, P-A and Stykel, Tatjana: Riemannian optimization on the symplectic Stiefel manifold, SIAM Journal on Optimization 31(2), pp. 1546-1575, 2021. doi 10.1137/20M1348522

  • BendokatZimmermann2021

    Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.

  • BirteaCaşuComănescu2020

    Birtea, Petre and Caşu, Ioan and Comănescu, Dan: Optimization on the real symplectic group, Monatshefte f{"u}r Mathematik, Springer, 2020. doi 10.1007/s00605-020-01369-9

diff --git a/previews/PR628/manifolds/symplecticstiefel.html b/previews/PR628/manifolds/symplecticstiefel.html index 3b3ac76bdc..b28997deee 100644 --- a/previews/PR628/manifolds/symplecticstiefel.html +++ b/previews/PR628/manifolds/symplecticstiefel.html @@ -15,7 +15,7 @@ Ω ∈ ℝ^{2k × 2k}, Ω^+ = -Ω, \\ &\; p^s ∈ \operatorname{SpSt}(2n, 2(n- k)), B ∈ ℝ^{2(n-k) × 2k}, \}, \end{align*}\]

where $Ω \in \mathfrak{sp}(2n,F)$ is Hamiltonian and $p^s$ means the symplectic complement of $p$ s.t. $p^{+}p^{s} = 0$.

Constructor

SymplecticStiefel(2n::Int, 2k::Int, field::AbstractNumbers=ℝ)
-    -> SymplecticStiefel{div(2n, 2), div(2k, 2), field}()

Generate the (real-valued) symplectic Stiefel manifold of $2n \times 2k$ matrices which span a $2k$ dimensional symplectic subspace of $ℝ^{2n \times 2n}$. The constructor for the SymplecticStiefel manifold accepts the even column dimension $2n$ and an even number of columns $2k$ for the real symplectic Stiefel manifold with elements $p \in ℝ^{2n × 2k}$.

source
Base.exp — Method
exp(::SymplecticStiefel, p, X)
+    -> SymplecticStiefel{div(2n, 2), div(2k, 2), field}()

Generate the (real-valued) symplectic Stiefel manifold of $2n \times 2k$ matrices which span a $2k$ dimensional symplectic subspace of $ℝ^{2n \times 2n}$. The constructor for the SymplecticStiefel manifold accepts the even column dimension $2n$ and an even number of columns $2k$ for the real symplectic Stiefel manifold with elements $p \in ℝ^{2n × 2k}$.

source
Base.exp — Method
exp(::SymplecticStiefel, p, X)
 exp!(M::SymplecticStiefel, q, p, X)

Compute the exponential mapping

\[ \operatorname{exp}\colon T\operatorname{SpSt}(2n, 2k) \rightarrow \operatorname{SpSt}(2n, 2k)\]

at a point $p \in \operatorname{SpSt}(2n, 2k)$ in the direction of $X \in T_p\operatorname{SpSt}(2n, 2k)$.

The tangent vector $X$ can be written in the form $X = \bar{\Omega}p$ [BendokatZimmermann2021], with

\[ \bar{\Omega} = X (p^{\mathrm{T}}p)^{-1}p^{\mathrm{T}} + Q_{2n}p(p^{\mathrm{T}}p)^{-1}X^{\mathrm{T}}(I_{2n} - Q_{2n}^{\mathrm{T}}p(p^{\mathrm{T}}p)^{-1}p^{\mathrm{T}}Q_{2n})Q_{2n} @@ -34,7 +34,7 @@ \begin{bmatrix} 0_{2k} \\ I_{2k} - \end{bmatrix}.\]

which only requires computing the matrix exponentials of $ΛΓ^{\mathrm{T}} \in ℝ^{8k \times 8k}$ and $λγ^{\mathrm{T}} \in ℝ^{4k \times 4k}$.

source
Base.inv — Method
inv(::SymplecticStiefel{n, k}, A)
+        \end{bmatrix}.\]
which only requires computing the matrix exponentials of $ΛΓ^{\mathrm{T}} \in ℝ^{8k \times 8k}$ and $λγ^{\mathrm{T}} \in ℝ^{4k \times 4k}$.
source
Base.inv — Method
inv(::SymplecticStiefel{n, k}, A)
 inv!(::SymplecticStiefel{n, k}, q, p)

Compute the symplectic inverse $A^+$ of matrix $A ∈ ℝ^{2n × 2k}$. Given a matrix

\[A ∈ ℝ^{2n × 2k},\quad A = \begin{bmatrix} @@ -48,21 +48,21 @@ \begin{bmatrix} A_{2, 2}^{\mathrm{T}} & -A_{1, 2}^{\mathrm{T}} \\[1.2mm] -A_{2, 1}^{\mathrm{T}} & A_{1, 1}^{\mathrm{T}} -\end{bmatrix}.\]

source
Base.rand — Method
rand(M::SymplecticStiefel; vector_at=nothing,
-    hamiltonian_norm=(vector_at === nothing ? 1/2 : 1.0))

Generate a random point $p \in \operatorname{SpSt}(2n, 2k)$ or a random tangent vector $X \in T_p\operatorname{SpSt}(2n, 2k)$ if vector_at is set to a point $p \in \operatorname{Sp}(2n)$.

A random point on $\operatorname{SpSt}(2n, 2k)$ is found by first generating a random point on the symplectic manifold $\operatorname{Sp}(2n)$, and then projecting onto the Symplectic Stiefel manifold using the canonical_project $π_{\operatorname{SpSt}(2n, 2k)}$. That is, $p = π_{\operatorname{SpSt}(2n, 2k)}(p_{\operatorname{Sp}})$.

To generate a random tangent vector in $T_p\operatorname{SpSt}(2n, 2k)$ this code exploits the second tangent vector space parametrization of SymplecticStiefel, showing that any $X \in T_p\operatorname{SpSt}(2n, 2k)$ can be written as $X = pΩ_X + p^sB_X$. To generate random tangent vectors at $p$ then, this function sets $B_X = 0$ and generates a random Hamiltonian matrix $Ω_X \in \mathfrak{sp}(2n,F)$ with Frobenius norm of hamiltonian_norm before returning $X = pΩ_X$.

source
ManifoldDiff.riemannian_gradient — Method
X = riemannian_gradient(::SymplecticStiefel, f, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())
-riemannian_gradient!(::SymplecticStiefel, f, X, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())

Compute the riemannian gradient X of f on SymplecticStiefel at a point p, provided that the gradient of the function $\tilde f$, which is f continued into the embedding is given by Y. The metric in the embedding is the Euclidean metric.

The manifold gradient X is computed from Y as

\[ X = Yp^{\mathrm{T}}p + Q_{2n}pY^{\mathrm{T}}Q_{2n}p,\]

where $Q_{2n}$ is the SymplecticMatrix.

source
Manifolds.canonical_project — Method
canonical_project(::SymplecticStiefel, p_Sp)
-canonical_project!(::SymplecticStiefel{n,k}, p, p_Sp)

Define the canonical projection from $\operatorname{Sp}(2n, 2n)$ onto $\operatorname{SpSt}(2n, 2k)$, by projecting onto the first $k$ columns and the $n + 1$'th onto the $n + k$'th columns [BendokatZimmermann2021].

It is assumed that the point $p$ is on $\operatorname{Sp}(2n, 2n)$.

source
Manifolds.symplectic_inverse_times — Method
symplectic_inverse_times(::SymplecticStiefel, p, q)
-symplectic_inverse_times!(::SymplecticStiefel, A, p, q)

Directly compute the symplectic inverse of $p \in \operatorname{SpSt}(2n, 2k)$, multiplied with $q \in \operatorname{SpSt}(2n, 2k)$. That is, this function efficiently computes $p^+q = (Q_{2k}p^{\mathrm{T}}Q_{2n})q \in ℝ^{2k \times 2k}$, where $Q_{2n}, Q_{2k}$ are the SymplecticMatrix of sizes $2n \times 2n$ and $2k \times 2k$ respectively.

This function performs this common operation without allocating more than a $2k \times 2k$ matrix to store the result in, or in the case of the in-place function, without allocating memory at all.

source
ManifoldsBase.check_point — Method
check_point(M::SymplecticStiefel, p; kwargs...)

Check whether p is a valid point on the SymplecticStiefel, $\operatorname{SpSt}(2n, 2k)$ manifold. That is, the point has the right AbstractNumbers type and $p^{+}p$ is (approximately) the identity, where for $A \in \mathbb{R}^{2n \times 2k}$, $A^{+} = Q_{2k}^{\mathrm{T}}A^{\mathrm{T}}Q_{2n}$ is the symplectic inverse, with

\[Q_{2n} = +\end{bmatrix}.\]

source
Base.rand — Method
rand(M::SymplecticStiefel; vector_at=nothing,
+    hamiltonian_norm=(vector_at === nothing ? 1/2 : 1.0))

Generate a random point $p \in \operatorname{SpSt}(2n, 2k)$ or a random tangent vector $X \in T_p\operatorname{SpSt}(2n, 2k)$ if vector_at is set to a point $p \in \operatorname{Sp}(2n)$.

A random point on $\operatorname{SpSt}(2n, 2k)$ is found by first generating a random point on the symplectic manifold $\operatorname{Sp}(2n)$, and then projecting onto the Symplectic Stiefel manifold using the canonical_project $π_{\operatorname{SpSt}(2n, 2k)}$. That is, $p = π_{\operatorname{SpSt}(2n, 2k)}(p_{\operatorname{Sp}})$.

To generate a random tangent vector in $T_p\operatorname{SpSt}(2n, 2k)$ this code exploits the second tangent vector space parametrization of SymplecticStiefel, showing that any $X \in T_p\operatorname{SpSt}(2n, 2k)$ can be written as $X = pΩ_X + p^sB_X$. To generate random tangent vectors at $p$ then, this function sets $B_X = 0$ and generates a random Hamiltonian matrix $Ω_X \in \mathfrak{sp}(2n,F)$ with Frobenius norm of hamiltonian_norm before returning $X = pΩ_X$.

source
ManifoldDiff.riemannian_gradient — Method
X = riemannian_gradient(::SymplecticStiefel, f, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())
+riemannian_gradient!(::SymplecticStiefel, f, X, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())

Compute the riemannian gradient X of f on SymplecticStiefel at a point p, provided that the gradient of the function $\tilde f$, which is f continued into the embedding is given by Y. The metric in the embedding is the Euclidean metric.

The manifold gradient X is computed from Y as

\[ X = Yp^{\mathrm{T}}p + Q_{2n}pY^{\mathrm{T}}Q_{2n}p,\]

where $Q_{2n}$ is the SymplecticMatrix.

source
Manifolds.canonical_project — Method
canonical_project(::SymplecticStiefel, p_Sp)
+canonical_project!(::SymplecticStiefel{n,k}, p, p_Sp)

Define the canonical projection from $\operatorname{Sp}(2n, 2n)$ onto $\operatorname{SpSt}(2n, 2k)$, by projecting onto the first $k$ columns and the $n + 1$'th onto the $n + k$'th columns [BendokatZimmermann2021].

It is assumed that the point $p$ is on $\operatorname{Sp}(2n, 2n)$.

source
Manifolds.symplectic_inverse_times — Method
symplectic_inverse_times(::SymplecticStiefel, p, q)
+symplectic_inverse_times!(::SymplecticStiefel, A, p, q)

Directly compute the symplectic inverse of $p \in \operatorname{SpSt}(2n, 2k)$, multiplied with $q \in \operatorname{SpSt}(2n, 2k)$. That is, this function efficiently computes $p^+q = (Q_{2k}p^{\mathrm{T}}Q_{2n})q \in ℝ^{2k \times 2k}$, where $Q_{2n}, Q_{2k}$ are the SymplecticMatrix of sizes $2n \times 2n$ and $2k \times 2k$ respectively.

This function performs this common operation without allocating more than a $2k \times 2k$ matrix to store the result in, or in the case of the in-place function, without allocating memory at all.

source
ManifoldsBase.check_point — Method
check_point(M::SymplecticStiefel, p; kwargs...)

Check whether p is a valid point on the SymplecticStiefel, $\operatorname{SpSt}(2n, 2k)$ manifold. That is, the point has the right AbstractNumbers type and $p^{+}p$ is (approximately) the identity, where for $A \in \mathbb{R}^{2n \times 2k}$, $A^{+} = Q_{2k}^{\mathrm{T}}A^{\mathrm{T}}Q_{2n}$ is the symplectic inverse, with

\[Q_{2n} = \begin{bmatrix} 0_n & I_n \\ -I_n & 0_n -\end{bmatrix}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.check_vector — Method
check_vector(M::Symplectic, p, X; kwargs...)

Checks whether X is a valid tangent vector at p on the SymplecticStiefel, $\operatorname{SpSt}(2n, 2k)$ manifold. First recall the definition of the symplectic inverse for $A \in \mathbb{R}^{2n \times 2k}$, $A^{+} = Q_{2k}^{\mathrm{T}}A^{\mathrm{T}}Q_{2n}$ is the symplectic inverse, with

\[ Q_{2n} = +\end{bmatrix}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.check_vector — Method
check_vector(M::Symplectic, p, X; kwargs...)

Checks whether X is a valid tangent vector at p on the SymplecticStiefel, $\operatorname{SpSt}(2n, 2k)$ manifold. First recall the definition of the symplectic inverse for $A \in \mathbb{R}^{2n \times 2k}$, $A^{+} = Q_{2k}^{\mathrm{T}}A^{\mathrm{T}}Q_{2n}$ is the symplectic inverse, with

\[ Q_{2n} = \begin{bmatrix} 0_n & I_n \\ -I_n & 0_n -\end{bmatrix}.\]

The we check that $H = p^{+}X \in 𝔤_{2k}$, where $𝔤$ is the Lie Algebra of the symplectic group $\operatorname{Sp}(2k)$, characterized as [BendokatZimmermann2021],

\[ 𝔤_{2k} = \{H \in ℝ^{2k \times 2k} \;|\; H^+ = -H \}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.inner — Method
inner(M::SymplecticStiefel{n, k}, p, X. Y)

Compute the Riemannian inner product $g^{\operatorname{SpSt}}$ at $p \in \operatorname{SpSt}$ between tangent vectors $X, X \in T_p\operatorname{SpSt}$. Given by Proposition 3.10 in [BendokatZimmermann2021].

\[g^{\operatorname{SpSt}}_p(X, Y) +\end{bmatrix}.\]

The we check that $H = p^{+}X \in 𝔤_{2k}$, where $𝔤$ is the Lie Algebra of the symplectic group $\operatorname{Sp}(2k)$, characterized as [BendokatZimmermann2021],

\[ 𝔤_{2k} = \{H \in ℝ^{2k \times 2k} \;|\; H^+ = -H \}.\]

The tolerance can be set with kwargs... (e.g. atol = 1.0e-14).

source
ManifoldsBase.inner — Method
inner(M::SymplecticStiefel{n, k}, p, X. Y)

Compute the Riemannian inner product $g^{\operatorname{SpSt}}$ at $p \in \operatorname{SpSt}$ between tangent vectors $X, X \in T_p\operatorname{SpSt}$. Given by Proposition 3.10 in [BendokatZimmermann2021].

\[g^{\operatorname{SpSt}}_p(X, Y) = \operatorname{tr}\left(X^{\mathrm{T}}\left(I_{2n} - - \frac{1}{2}Q_{2n}^{\mathrm{T}}p(p^{\mathrm{T}}p)^{-1}p^{\mathrm{T}}Q_{2n}\right)Y(p^{\mathrm{T}}p)^{-1}\right).\]

source
ManifoldsBase.inverse_retract — Method
inverse_retract(::SymplecticStiefel, p, q, ::CayleyInverseRetraction)
+        \frac{1}{2}Q_{2n}^{\mathrm{T}}p(p^{\mathrm{T}}p)^{-1}p^{\mathrm{T}}Q_{2n}\right)Y(p^{\mathrm{T}}p)^{-1}\right).\]
source
ManifoldsBase.inverse_retract — Method
inverse_retract(::SymplecticStiefel, p, q, ::CayleyInverseRetraction)
 inverse_retract!(::SymplecticStiefel, q, p, X, ::CayleyInverseRetraction)

Compute the Cayley Inverse Retraction $X = \mathcal{L}_p^{\operatorname{SpSt}}(q)$ such that the Cayley Retraction from $p$ along $X$ lands at $q$, i.e. $\mathcal{R}_p(X) = q$ [BendokatZimmermann2021].

First, recall the definition the standard symplectic matrix

\[Q = \begin{bmatrix} 0 & I \\ @@ -70,9 +70,9 @@ \end{bmatrix}\]

as well as the symplectic inverse of a matrix $A$, $A^{+} = Q^{\mathrm{T}} A^{\mathrm{T}} Q$.

For $p, q ∈ \operatorname{SpSt}(2n, 2k, ℝ)$ then, we can define the inverse cayley retraction as long as the following matrices exist.

\[ U = (I + p^+ q)^{-1} \in ℝ^{2k \times 2k}, \quad V = (I + q^+ p)^{-1} \in ℝ^{2k \times 2k}.\]

If that is the case, the inverse cayley retration at $p$ applied to $q$ is

\[\mathcal{L}_p^{\operatorname{Sp}}(q) = 2p\bigl(V - U\bigr) + 2\bigl((p + q)U - p\bigr) - ∈ T_p\operatorname{Sp}(2n).\]

source
ManifoldsBase.project — Method
project(::SymplecticStiefel, p, A)
 project!(::SymplecticStiefel, Y, p, A)

Given a point $p \in \operatorname{SpSt}(2n, 2k)$, project an element $A \in \mathbb{R}^{2n \times 2k}$ onto the tangent space $T_p\operatorname{SpSt}(2n, 2k)$ relative to the euclidean metric of the embedding $\mathbb{R}^{2n \times 2k}$.

That is, we find the element $X \in T_p\operatorname{SpSt}(2n, 2k)$ which solves the constrained optimization problem

\[ \operatorname{min}_{X \in \mathbb{R}^{2n \times 2k}} \frac{1}{2}||X - A||^2, \quad \text{s.t.}\; - h(X)\colon= X^{\mathrm{T}} Q p + p^{\mathrm{T}} Q X = 0,\]

where $h : \mathbb{R}^{2n \times 2k} \rightarrow \operatorname{skew}(2k)$ defines the restriction of $X$ onto the tangent space $T_p\operatorname{SpSt}(2n, 2k)$.

source
ManifoldsBase.retract — Method
retract(::SymplecticStiefel, p, X, ::CayleyRetraction)
+    h(X)\colon= X^{\mathrm{T}} Q p + p^{\mathrm{T}} Q X = 0,\]
where $h : \mathbb{R}^{2n \times 2k} \rightarrow \operatorname{skew}(2k)$ defines the restriction of $X$ onto the tangent space $T_p\operatorname{SpSt}(2n, 2k)$.
source
ManifoldsBase.retract — Method
retract(::SymplecticStiefel, p, X, ::CayleyRetraction)
 retract!(::SymplecticStiefel, q, p, X, ::CayleyRetraction)

Compute the Cayley retraction on the Symplectic Stiefel manifold, computed inplace of q from p along X.

Given a point $p \in \operatorname{SpSt}(2n, 2k)$, every tangent vector $X \in T_p\operatorname{SpSt}(2n, 2k)$ is of the form $X = \tilde{\Omega}p$, with

\[ \tilde{\Omega} = \left(I_{2n} - \frac{1}{2}pp^+\right)Xp^+ - - pX^+\left(I_{2n} - \frac{1}{2}pp^+\right) \in ℝ^{2n \times 2n},\]

as shown in Proposition 3.5 of [BendokatZimmermann2021]. Using this representation of $X$, the Cayley retraction on $\operatorname{SpSt}(2n, 2k)$ is defined pointwise as

\[ \mathcal{R}_p(X) = \operatorname{cay}\left(\frac{1}{2}\tilde{\Omega}\right)p.\]

The operator $\operatorname{cay}(A) = (I - A)^{-1}(I + A)$ is the Cayley transform.

However, the computation of an $2n \times 2n$ matrix inverse in the expression above can be reduced down to inverting a $2k \times 2k$ matrix due to Proposition 5.2 of [BendokatZimmermann2021].

Let $A = p^+X$ and $H = X - pA$. Then an equivalent expression for the Cayley retraction defined pointwise above is

\[ \mathcal{R}_p(X) = -p + (H + 2p)(H^+H/4 - A/2 + I_{2k})^{-1}.\]

It is this expression we compute inplace of q.

source

Literature

  • BendokatZimmermann2021

    Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.

+ pX^+\left(I_{2n} - \frac{1}{2}pp^+\right) \in ℝ^{2n \times 2n},\]

as shown in Proposition 3.5 of [BendokatZimmermann2021]. Using this representation of $X$, the Cayley retraction on $\operatorname{SpSt}(2n, 2k)$ is defined pointwise as

\[ \mathcal{R}_p(X) = \operatorname{cay}\left(\frac{1}{2}\tilde{\Omega}\right)p.\]

The operator $\operatorname{cay}(A) = (I - A)^{-1}(I + A)$ is the Cayley transform.

However, the computation of an $2n \times 2n$ matrix inverse in the expression above can be reduced down to inverting a $2k \times 2k$ matrix due to Proposition 5.2 of [BendokatZimmermann2021].

Let $A = p^+X$ and $H = X - pA$. Then an equivalent expression for the Cayley retraction defined pointwise above is

\[ \mathcal{R}_p(X) = -p + (H + 2p)(H^+H/4 - A/2 + I_{2k})^{-1}.\]

It is this expression we compute inplace of q.

source

Literature

  • BendokatZimmermann2021

    Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.

diff --git a/previews/PR628/manifolds/torus.html b/previews/PR628/manifolds/torus.html index 0bfa495756..b52c29e351 100644 --- a/previews/PR628/manifolds/torus.html +++ b/previews/PR628/manifolds/torus.html @@ -6,8 +6,8 @@ X = log(M, p, q)
3-element Vector{Float64}:
  -0.5
   0.5
-  1.0

Types and functions

Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:

ManifoldsBase.check_vector — Method
check_vector(M::Torus{n}, p, X; kwargs...)

Checks whether X is a valid tangent vector to p on the Torus M. This means, that p is valid, that X is of correct dimension and elementwise a tangent vector to the elements of p on the Circle.

source

Embedded Torus

Two-dimensional torus embedded in $ℝ^3$.

Manifolds.DefaultTorusAtlas — Type
DefaultTorusAtlas()

Atlas for torus with charts indexed by two angles numbers $θ₀, φ₀ ∈ [-π, π)$. Inverse of a chart $(θ₀, φ₀)$ is given by

\[x(θ, φ) = (R + r\cos(θ + θ₀))\cos(φ + φ₀) \\ + 1.0

Types and functions

Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:

ManifoldsBase.check_vector — Method
check_vector(M::Torus{n}, p, X; kwargs...)

Checks whether X is a valid tangent vector to p on the Torus M. This means, that p is valid, that X is of correct dimension and elementwise a tangent vector to the elements of p on the Circle.

source

Embedded Torus

Two-dimensional torus embedded in $ℝ^3$.

Manifolds.DefaultTorusAtlas — Type
DefaultTorusAtlas()

Atlas for torus with charts indexed by two angles numbers $θ₀, φ₀ ∈ [-π, π)$. Inverse of a chart $(θ₀, φ₀)$ is given by

\[x(θ, φ) = (R + r\cos(θ + θ₀))\cos(φ + φ₀) \\ y(θ, φ) = (R + r\cos(θ + θ₀))\sin(φ + φ₀) \\ -z(θ, φ) = r\sin(θ + θ₀)\]

source
Manifolds.EmbeddedTorus — Type
EmbeddedTorus{TR<:Real} <: AbstractDecoratorManifold{ℝ}

Surface in ℝ³ described by parametric equations:

\[x(θ, φ) = (R + r\cos θ)\cos φ \\ +z(θ, φ) = r\sin(θ + θ₀)\]

source
Manifolds.EmbeddedTorus — Type
EmbeddedTorus{TR<:Real} <: AbstractDecoratorManifold{ℝ}

Surface in ℝ³ described by parametric equations:

\[x(θ, φ) = (R + r\cos θ)\cos φ \\ y(θ, φ) = (R + r\cos θ)\sin φ \\ -z(θ, φ) = r\sin θ\]

for θ, φ in $[-π, π)$. It is assumed that $R > r > 0$.

Alternative names include anchor ring, donut and doughnut.

Constructor

EmbeddedTorus(R, r)
source
Manifolds.check_chart_switch — Method
check_chart_switch(::EmbeddedTorus, A::DefaultTorusAtlas, i, a; ϵ = pi/3)

Return true if parameters a lie closer than ϵ to chart boundary.

source
ManifoldsBase.check_point — Method
check_point(M::EmbeddedTorus, p; kwargs...)

Check whether p is a valid point on the EmbeddedTorus M. The tolerance for the last test can be set using the kwargs....

The method checks if $(p_1^2 + p_2^2 + p_3^2 + R^2 - r^2)^2$ is apprximately equal to $4R^2(p_1^2 + p_2^2)$.

source
ManifoldsBase.check_vector — Method
check_vector(M::EmbeddedTorus, p, X; atol=eps(eltype(p)), kwargs...)

Check whether X is a valid vector tangent to p on the EmbeddedTorus M. The method checks if the vector X is orthogonal to the vector normal to the torus, see normal_vector. Absolute tolerance can be set using atol.

source
ManifoldsBase.inner — Method
inner(M::EmbeddedTorus, ::DefaultTorusAtlas, i, a, Xc, Yc)

Inner product on EmbeddedTorus in chart i in the DefaultTorusAtlas. between vectors with coordinates Xc and Yc tangent at point with parameters a. Vector coordinates must be given in the induced basis.

source
+z(θ, φ) = r\sin θ\]

for θ, φ in $[-π, π)$. It is assumed that $R > r > 0$.

Alternative names include anchor ring, donut and doughnut.

Constructor

EmbeddedTorus(R, r)
source
Manifolds.check_chart_switch — Method
check_chart_switch(::EmbeddedTorus, A::DefaultTorusAtlas, i, a; ϵ = pi/3)

Return true if parameters a lie closer than ϵ to chart boundary.

source
ManifoldsBase.check_point — Method
check_point(M::EmbeddedTorus, p; kwargs...)

Check whether p is a valid point on the EmbeddedTorus M. The tolerance for the last test can be set using the kwargs....

The method checks if $(p_1^2 + p_2^2 + p_3^2 + R^2 - r^2)^2$ is apprximately equal to $4R^2(p_1^2 + p_2^2)$.

source
ManifoldsBase.check_vector — Method
check_vector(M::EmbeddedTorus, p, X; atol=eps(eltype(p)), kwargs...)

Check whether X is a valid vector tangent to p on the EmbeddedTorus M. The method checks if the vector X is orthogonal to the vector normal to the torus, see normal_vector. Absolute tolerance can be set using atol.

source
ManifoldsBase.inner — Method
inner(M::EmbeddedTorus, ::DefaultTorusAtlas, i, a, Xc, Yc)

Inner product on EmbeddedTorus in chart i in the DefaultTorusAtlas. between vectors with coordinates Xc and Yc tangent at point with parameters a. Vector coordinates must be given in the induced basis.

source
diff --git a/previews/PR628/manifolds/tucker.html b/previews/PR628/manifolds/tucker.html index e3f8b80eeb..07fc37150e 100644 --- a/previews/PR628/manifolds/tucker.html +++ b/previews/PR628/manifolds/tucker.html @@ -6,12 +6,12 @@ (U_1, \dots, U_{d-1}, U_d^\prime, U_{d+1}, \dots, U_D) \cdot \mathcal{C} \bigr) -\bigr\}\]

where $\mathcal{C}^\prime$ is arbitrary, $U_d^{\mathrm{H}}$ is the Hermitian adjoint of $U_d$, and $U_d^{\mathrm{H}} U_d^\prime = 0$ for all $d$.

Constructor

Tucker(N::NTuple{D, Int}, R::NTuple{D, Int}[, field = ℝ])

Generate the manifold of field-valued tensors of dimensions N[1] × … × N[D] and multilinear rank R = (R[1], …, R[D]).

source
Manifolds.TuckerPoint — Type
TuckerPoint{T,D}

An order D tensor of fixed multilinear rank and entries of type T, which makes it a point on the Tucker manifold. The tensor is represented in HOSVD form.

Constructors:

TuckerPoint(core::AbstractArray{T,D}, factors::Vararg{<:AbstractMatrix{T},D}) where {T,D}

Construct an order D tensor of element type T that can be represented as the multilinear product (factors[1], …, factors[D]) ⋅ core. It is assumed that the dimensions of the core are the multilinear rank of the tensor and that the matrices factors each have full rank. No further assumptions are made.

TuckerPoint(p::AbstractArray{T,D}, mlrank::NTuple{D,Int}) where {T,D}

The low-multilinear rank tensor arising from the sequentially truncated the higher-order singular value decomposition of the D-dimensional array p of type T. The singular values are truncated to get a multilinear rank mlrank [Vannieuwenhoven2012].

source
Manifolds.TuckerTVector — Type
TuckerTVector{T, D} <: TVector

Tangent vector to the D-th order Tucker manifold at $p = (U_1,\dots,U_D) ⋅ \mathcal{C}$. The numbers are of type T and the vector is represented as

\[X = +\bigr\}\]

where $\mathcal{C}^\prime$ is arbitrary, $U_d^{\mathrm{H}}$ is the Hermitian adjoint of $U_d$, and $U_d^{\mathrm{H}} U_d^\prime = 0$ for all $d$.

Constructor

Tucker(N::NTuple{D, Int}, R::NTuple{D, Int}[, field = ℝ])

Generate the manifold of field-valued tensors of dimensions N[1] × … × N[D] and multilinear rank R = (R[1], …, R[D]).

source
Manifolds.TuckerPoint — Type
TuckerPoint{T,D}

An order D tensor of fixed multilinear rank and entries of type T, which makes it a point on the Tucker manifold. The tensor is represented in HOSVD form.

Constructors:

TuckerPoint(core::AbstractArray{T,D}, factors::Vararg{<:AbstractMatrix{T},D}) where {T,D}

Construct an order D tensor of element type T that can be represented as the multilinear product (factors[1], …, factors[D]) ⋅ core. It is assumed that the dimensions of the core are the multilinear rank of the tensor and that the matrices factors each have full rank. No further assumptions are made.

TuckerPoint(p::AbstractArray{T,D}, mlrank::NTuple{D,Int}) where {T,D}

The low-multilinear rank tensor arising from the sequentially truncated the higher-order singular value decomposition of the D-dimensional array p of type T. The singular values are truncated to get a multilinear rank mlrank [Vannieuwenhoven2012].

source
Manifolds.TuckerTVector — Type
TuckerTVector{T, D} <: TVector

Tangent vector to the D-th order Tucker manifold at $p = (U_1,\dots,U_D) ⋅ \mathcal{C}$. The numbers are of type T and the vector is represented as

\[X = (U_1,\dots,U_D) \cdot \mathcal{C}^\prime + -\sum_{d=1}^D (U_1,\dots,U_{d-1},U_d^\prime,U_{d+1},\dots,U_D) \cdot \mathcal{C}\]

where $U_d^\mathrm{H} U_d^\prime = 0$.

Constructor

TuckerTVector(C′::Array{T,D}, U′::NTuple{D,Matrix{T}}) where {T,D}

Constructs a Dth order TuckerTVector of number type T with $C^\prime$ and $U^\prime$, so that, together with a TuckerPoint $p$ as above, the tangent vector can be represented as $X$ in the above expression.

source
Base.convert — Method
Base.convert(::Type{Matrix{T}}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}
-Base.convert(::Type{Matrix}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}

Convert a HOSVD-derived cached basis from [Dewaele2021] of the Dth order Tucker manifold with number type T to a matrix. The columns of this matrix are the vectorisations of the embeddings of the basis vectors.

source
Base.foreach — Function
Base.foreach(f, M::Tucker, p::TuckerPoint, basis::AbstractBasis, indices=1:manifold_dimension(M))

Let basis be and AbstractBasis at a point p on M. Suppose f is a function that takes an index and a vector as an argument. This function applies f to i and the ith basis vector sequentially for each i in indices. Using a CachedBasis may speed up the computation.

NOTE: The i'th basis vector is overwritten in each iteration. If any information about the vector is to be stored, f must make a copy.

source
Base.ndims — Method
Base.ndims(p::TuckerPoint{T,D}) where {T,D}

The order of the tensor corresponding to the TuckerPoint p, i.e., D.

source
ManifoldsBase.check_point — Method
check_point(M::Tucker{N,R,D}, p; kwargs...) where {N,R,D}

Check whether the multidimensional array or TuckerPoint p is a point on the Tucker manifold, i.e. it is a Dth order N[1] × … × N[D] tensor of multilinear rank (R[1], …, R[D]). The keyword arguments are passed to the matrix rank function applied to the unfoldings. For a TuckerPoint it is checked that the point is in correct HOSVD form.

source
ManifoldsBase.check_vector — Method
check_vector(M::Tucker{N,R,D}, p::TuckerPoint{T,D}, X::TuckerTVector) where {N,R,T,D}

Check whether a TuckerTVector X is is in the tangent space to the Dth order Tucker manifold M at the Dth order TuckerPoint p. This is the case when the dimensions of the factors in X agree with those of p and the factor matrices of X are in the orthogonal complement of the HOSVD factors of p.

source
ManifoldsBase.embed — Method
embed(::Tucker{N,R,D}, p::TuckerPoint) where {N,R,D}

Convert a TuckerPoint p on the rank R Tucker manifold to a full N[1] × … × N[D]-array by evaluating the Tucker decomposition.

embed(::Tucker{N,R,D}, p::TuckerPoint, X::TuckerTVector) where {N,R,D}

Convert a tangent vector X with base point p on the rank R Tucker manifold to a full tensor, represented as an N[1] × … × N[D]-array.

source
ManifoldsBase.get_basis — Method
get_basis(:: Tucker, p::TuckerPoint, basisType::DefaultOrthonormalBasis{𝔽, TangentSpaceType}) where 𝔽

An implicitly stored basis of the tangent space to the Tucker manifold. Assume $p = (U_1,\dots,U_D) \cdot \mathcal{C}$ is in HOSVD format and that, for $d=1,\dots,D$, the singular values of the $d$'th unfolding are $\sigma_{dj}$, with $j = 1,\dots,R_d$. The basis of the tangent space is as follows: [Dewaele2021]

\[\bigl\{ +\sum_{d=1}^D (U_1,\dots,U_{d-1},U_d^\prime,U_{d+1},\dots,U_D) \cdot \mathcal{C}\]

where $U_d^\mathrm{H} U_d^\prime = 0$.

Constructor

TuckerTVector(C′::Array{T,D}, U′::NTuple{D,Matrix{T}}) where {T,D}

Constructs a Dth order TuckerTVector of number type T with $C^\prime$ and $U^\prime$, so that, together with a TuckerPoint $p$ as above, the tangent vector can be represented as $X$ in the above expression.

source
Base.convert — Method
Base.convert(::Type{Matrix{T}}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}
+Base.convert(::Type{Matrix}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}

Convert a HOSVD-derived cached basis from [Dewaele2021] of the Dth order Tucker manifold with number type T to a matrix. The columns of this matrix are the vectorisations of the embeddings of the basis vectors.

source
Base.foreach — Function
Base.foreach(f, M::Tucker, p::TuckerPoint, basis::AbstractBasis, indices=1:manifold_dimension(M))

Let basis be and AbstractBasis at a point p on M. Suppose f is a function that takes an index and a vector as an argument. This function applies f to i and the ith basis vector sequentially for each i in indices. Using a CachedBasis may speed up the computation.

NOTE: The i'th basis vector is overwritten in each iteration. If any information about the vector is to be stored, f must make a copy.

source
Base.ndims — Method
Base.ndims(p::TuckerPoint{T,D}) where {T,D}

The order of the tensor corresponding to the TuckerPoint p, i.e., D.

source
ManifoldsBase.check_point — Method
check_point(M::Tucker{N,R,D}, p; kwargs...) where {N,R,D}

Check whether the multidimensional array or TuckerPoint p is a point on the Tucker manifold, i.e. it is a Dth order N[1] × … × N[D] tensor of multilinear rank (R[1], …, R[D]). The keyword arguments are passed to the matrix rank function applied to the unfoldings. For a TuckerPoint it is checked that the point is in correct HOSVD form.

source
ManifoldsBase.check_vector — Method
check_vector(M::Tucker{N,R,D}, p::TuckerPoint{T,D}, X::TuckerTVector) where {N,R,T,D}

Check whether a TuckerTVector X is is in the tangent space to the Dth order Tucker manifold M at the Dth order TuckerPoint p. This is the case when the dimensions of the factors in X agree with those of p and the factor matrices of X are in the orthogonal complement of the HOSVD factors of p.

source
ManifoldsBase.embed — Method
embed(::Tucker{N,R,D}, p::TuckerPoint) where {N,R,D}

Convert a TuckerPoint p on the rank R Tucker manifold to a full N[1] × … × N[D]-array by evaluating the Tucker decomposition.

embed(::Tucker{N,R,D}, p::TuckerPoint, X::TuckerTVector) where {N,R,D}

Convert a tangent vector X with base point p on the rank R Tucker manifold to a full tensor, represented as an N[1] × … × N[D]-array.

source
ManifoldsBase.get_basis — Method
get_basis(:: Tucker, p::TuckerPoint, basisType::DefaultOrthonormalBasis{𝔽, TangentSpaceType}) where 𝔽

An implicitly stored basis of the tangent space to the Tucker manifold. Assume $p = (U_1,\dots,U_D) \cdot \mathcal{C}$ is in HOSVD format and that, for $d=1,\dots,D$, the singular values of the $d$'th unfolding are $\sigma_{dj}$, with $j = 1,\dots,R_d$. The basis of the tangent space is as follows: [Dewaele2021]

\[\bigl\{ (U_1,\dots,U_D) e_i \bigr\} \cup \bigl\{ (U_1,\dots, \sigma_{dj}^{-1} U_d^{\perp} e_i e_j^T,\dots,U_D) \cdot \mathcal{C} -\bigr\}\]

for all $d = 1,\dots,D$ and all canonical basis vectors $e_i$ and $e_j$. Every $U_d^\perp$ is such that $[U_d \quad U_d^{\perp}]$ forms an orthonormal basis of $\mathbb{R}^{N_d}$.

source
ManifoldsBase.inner — Method
inner(M::Tucker, p::TuckerPoint, X::TuckerTVector, Y::TuckerTVector)

The Euclidean inner product between tangent vectors X and X at the point p on the Tucker manifold. This is equal to embed(M, p, X) ⋅ embed(M, p, Y).

inner(::Tucker, A::TuckerPoint, X::TuckerTVector, Y)
-inner(::Tucker, A::TuckerPoint, X, Y::TuckerTVector)

The Euclidean inner product between X and Y where X is a vector tangent to the Tucker manifold at p and Y is a vector in the ambient space or vice versa. The vector in the ambient space is represented as a full tensor, i.e., a multidimensional array.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Tucker, p::TuckerPoint, q::TuckerPoint, ::ProjectionInverseRetraction)

The projection inverse retraction on the Tucker manifold interprets q as a point in the ambient Euclidean space (see embed) and projects it onto the tangent space at to M at p.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(::Tucker{N,R,D}) where {N,R,D}

The dimension of the manifold of $N_1 \times \dots \times N_D$ tensors of multilinear rank $(R_1, \dots, R_D)$, i.e.

\[\mathrm{dim}(\mathcal{M}) = \prod_{d=1}^D R_d + \sum_{d=1}^D R_d (N_d - R_d).\]

source
ManifoldsBase.project — Method
project(M::Tucker, p::TuckerPoint, X)

The least-squares projection of a dense tensor X onto the tangent space to M at p.

source
ManifoldsBase.retract — Method
retract(::Tucker, p::TuckerPoint, X::TuckerTVector, ::PolarRetraction)

The truncated HOSVD-based retraction [Kressner2014] to the Tucker manifold, i.e. the result is the sequentially tuncated HOSVD approximation of $p + X$.

In the exceptional case that the multilinear rank of $p + X$ is lower than that of $p$, this retraction produces a boundary point, which is outside the manifold.

source

Literature

  • DeLathauwer2000

    Lieven De Lathauwer, Bart De Moor, Joos Vandewalle: "A multilinear singular value decomposition" SIAM Journal on Matrix Analysis and Applications, 21(4), pp. 1253-1278, 2000 doi: 10.1137/S0895479896305696

  • Koch2010

    Othmar Koch, Christian Lubic, "Dynamical Tensor approximation" SIAM Journal on Matrix Analysis and Applications, 31(5), pp. 2360-2375, 2010 doi: 10.1137/09076578X

  • Vannieuwenhoven2012

    Nick Vannieuwenhoven, Raf Vandebril, Karl Meerbergen: "A new truncation strategy for the higher-order singular value decomposition" SIAM Journal on Scientific Computing, 34(2), pp. 1027-1052, 2012 doi: 10.1137/110836067

  • Dewaele2021

    Nick Dewaele, Paul Breiding, Nick Vannieuwenhoven, "The condition number of many tensor decompositions is invariant under Tucker compression" arxiv: 2106.13034

  • Kressner2014

    Daniel Kressner, Michael Steinlechner, Bart Vandereycken: "Low-rank tensor completion by Riemannian optimization" BIT Numerical Mathematics, 54(2), pp. 447-468, 2014 doi: 10.1007/s10543-013-0455-z

+\bigr\}\]

for all $d = 1,\dots,D$ and all canonical basis vectors $e_i$ and $e_j$. Every $U_d^\perp$ is such that $[U_d \quad U_d^{\perp}]$ forms an orthonormal basis of $\mathbb{R}^{N_d}$.

source
ManifoldsBase.inner — Method
inner(M::Tucker, p::TuckerPoint, X::TuckerTVector, Y::TuckerTVector)

The Euclidean inner product between tangent vectors X and X at the point p on the Tucker manifold. This is equal to embed(M, p, X) ⋅ embed(M, p, Y).

inner(::Tucker, A::TuckerPoint, X::TuckerTVector, Y)
+inner(::Tucker, A::TuckerPoint, X, Y::TuckerTVector)

The Euclidean inner product between X and Y where X is a vector tangent to the Tucker manifold at p and Y is a vector in the ambient space or vice versa. The vector in the ambient space is represented as a full tensor, i.e., a multidimensional array.

source
ManifoldsBase.inverse_retract — Method
inverse_retract(M::Tucker, p::TuckerPoint, q::TuckerPoint, ::ProjectionInverseRetraction)

The projection inverse retraction on the Tucker manifold interprets q as a point in the ambient Euclidean space (see embed) and projects it onto the tangent space at to M at p.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(::Tucker{N,R,D}) where {N,R,D}

The dimension of the manifold of $N_1 \times \dots \times N_D$ tensors of multilinear rank $(R_1, \dots, R_D)$, i.e.

\[\mathrm{dim}(\mathcal{M}) = \prod_{d=1}^D R_d + \sum_{d=1}^D R_d (N_d - R_d).\]

source
ManifoldsBase.project — Method
project(M::Tucker, p::TuckerPoint, X)

The least-squares projection of a dense tensor X onto the tangent space to M at p.

source
ManifoldsBase.retract — Method
retract(::Tucker, p::TuckerPoint, X::TuckerTVector, ::PolarRetraction)

The truncated HOSVD-based retraction [Kressner2014] to the Tucker manifold, i.e. the result is the sequentially tuncated HOSVD approximation of $p + X$.

In the exceptional case that the multilinear rank of $p + X$ is lower than that of $p$, this retraction produces a boundary point, which is outside the manifold.

source

Literature

  • DeLathauwer2000

    Lieven De Lathauwer, Bart De Moor, Joos Vandewalle: "A multilinear singular value decomposition" SIAM Journal on Matrix Analysis and Applications, 21(4), pp. 1253-1278, 2000 doi: 10.1137/S0895479896305696

  • Koch2010

    Othmar Koch, Christian Lubic, "Dynamical Tensor approximation" SIAM Journal on Matrix Analysis and Applications, 31(5), pp. 2360-2375, 2010 doi: 10.1137/09076578X

  • Vannieuwenhoven2012

    Nick Vannieuwenhoven, Raf Vandebril, Karl Meerbergen: "A new truncation strategy for the higher-order singular value decomposition" SIAM Journal on Scientific Computing, 34(2), pp. 1027-1052, 2012 doi: 10.1137/110836067

  • Dewaele2021

    Nick Dewaele, Paul Breiding, Nick Vannieuwenhoven, "The condition number of many tensor decompositions is invariant under Tucker compression" arxiv: 2106.13034

  • Kressner2014

    Daniel Kressner, Michael Steinlechner, Bart Vandereycken: "Low-rank tensor completion by Riemannian optimization" BIT Numerical Mathematics, 54(2), pp. 447-468, 2014 doi: 10.1007/s10543-013-0455-z

diff --git a/previews/PR628/manifolds/vector_bundle.html b/previews/PR628/manifolds/vector_bundle.html index 395f38e0a3..13fb159232 100644 --- a/previews/PR628/manifolds/vector_bundle.html +++ b/previews/PR628/manifolds/vector_bundle.html @@ -1,21 +1,21 @@ -Vector bundle · Manifolds.jl
Edit on GitHub

Vector bundles

Vector bundle $E$ is a manifold that is built on top of another manifold $\mathcal M$ (base space). It is characterized by a continuous function $Π : E → \mathcal M$, such that for each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$, has a structure of a vector space. These vector spaces are called fibers. Bundle projection can be performed using function bundle_projection.

Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point $x$. An object representing a tangent bundle can be obtained using the constructor called TangentBundle.

Fibers of a vector bundle are represented by the type VectorBundleFibers. The important difference between functions operating on VectorBundle and VectorBundleFibers is that in the first case both a point on the underlying manifold and the vector are represented together (by a single argument) while in the second case only the vector part is present, while the point is supplied in a different argument where needed.

VectorBundleFibers refers to the whole set of fibers of a vector bundle. There is also another type, VectorSpaceAtPoint, that represents a specific fiber at a given point. This distinction is made to reduce the need to repeatedly construct objects of type VectorSpaceAtPoint in certain usage scenarios. This is also considered a manifold.

FVector

For cases where confusion between different types of vectors is possible, the type FVector can be used to express which type of vector space the vector belongs to. It is used for example in musical isomorphisms (the flat and sharp functions) that are used to go from a tangent space to cotangent space and vice versa.

Documentation

Manifolds.SasakiRetraction — Type
struct SasakiRetraction <: AbstractRetractionMethod end

Exponential map on TangentBundle computed via Euler integration as described in [Muralidharan2012]. The system of equations for $\gamma : ℝ \to T\mathcal M$ such that $\gamma(1) = \exp_{p,X}(X_M, X_F)$ and $\gamma(0)=(p, X)$ reads

\[\dot{\gamma}(t) = (\dot{p}(t), \dot{X}(t)) = (R(X(t), \dot{X}(t))\dot{p}(t), 0)\]

where $R$ is the Riemann curvature tensor (see riemann_tensor).

Constructor

SasakiRetraction(L::Int)

In this constructor L is the number of integration steps.

source
Manifolds.TangentBundle — Type
TangentBundle{𝔽,M} = VectorBundle{𝔽,TangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}

Tangent bundle for manifold of type M, as a manifold with the Sasaki metric [Sasaki1958].

Exact retraction and inverse retraction can be approximated using VectorBundleProductRetraction, VectorBundleInverseProductRetraction and SasakiRetraction. VectorBundleProductVectorTransport can be used as a vector transport.

Constructors

TangentBundle(M::AbstractManifold)
-TangentBundle(M::AbstractManifold, vtm::VectorBundleProductVectorTransport)
source
Manifolds.TensorProductType — Type
TensorProductType(spaces::VectorSpaceType...)

Vector space type corresponding to the tensor product of given vector space types.

source
Manifolds.VectorBundleFibers — Type
VectorBundleFibers(fiber::VectorSpaceType, M::AbstractManifold)

Type representing a family of vector spaces (fibers) of a vector bundle over M with vector spaces of type fiber. In contrast with VectorBundle, operations on VectorBundleFibers expect point-like and vector-like parts to be passed separately instead of being bundled together. It can be thought of as a representation of vector spaces from a vector bundle but without storing the point at which a vector space is attached (which is specified separately in various functions).

source
Manifolds.VectorBundleInverseProductRetraction — Type
struct VectorBundleInverseProductRetraction <: AbstractInverseRetractionMethod end

Inverse retraction of the point y at point p from vector bundle B over manifold B.fiber (denoted $\mathcal M$). The inverse retraction is derived as a product manifold-style approximation to the logarithmic map in the Sasaki metric. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.

Notation:

  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$. Similarly, $q = (x_q, V_q)$.

The inverse retraction is calculated as

\[\operatorname{retr}^{-1}_p q = (\operatorname{retr}^{-1}_{x_p}(x_q), V_{\operatorname{retr}^{-1}} - V_p)\]

where $V_{\operatorname{retr}^{-1}}$ is the result of vector transport of $V_q$ to the point $x_p$. The difference $V_{\operatorname{retr}^{-1}} - V_p$ corresponds to the logarithmic map in the vector space $F$.

See also VectorBundleProductRetraction.

source
Manifolds.VectorBundleProductRetraction — Type
struct VectorBundleProductRetraction <: AbstractRetractionMethod end

Product retraction map of tangent vector $X$ at point $p$ from vector bundle B over manifold B.fiber (denoted $\mathcal M$). The retraction is derived as a product manifold-style approximation to the exponential map in the Sasaki metric. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.

Notation:

  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
  • The tangent vector $X = (V_{X,M}, V_{X,F}) ∈ T_pB$ where $V_{X,M}$ is a tangent vector from the tangent space $T_{x_p}\mathcal M$ and $V_{X,F}$ is a tangent vector from the tangent space $T_{V_p}F$ (isomorphic to $F$).

The retraction is calculated as

\[\operatorname{retr}_p(X) = (\exp_{x_p}(V_{X,M}), V_{\exp})\]

where $V_{\exp}$ is the result of vector transport of $V_p + V_{X,F}$ to the point $\exp_{x_p}(V_{X,M})$. The sum $V_p + V_{X,F}$ corresponds to the exponential map in the vector space $F$.

See also VectorBundleInverseProductRetraction.

source
Manifolds.VectorBundleProductVectorTransport — Type
VectorBundleProductVectorTransport{
+Vector bundle · Manifolds.jl
Edit on GitHub
Vector bundles
Vector bundle $E$ is a manifold that is built on top of another manifold $\mathcal M$ (base space). It is characterized by a continuous function $Π : E → \mathcal M$, such that for each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$, has a structure of a vector space. These vector spaces are called fibers. Bundle projection can be performed using function bundle_projection.
Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point $x$. An object representing a tangent bundle can be obtained using the constructor called TangentBundle.
Fibers of a vector bundle are represented by the type VectorBundleFibers. The important difference between functions operating on VectorBundle and VectorBundleFibers is that in the first case both a point on the underlying manifold and the vector are represented together (by a single argument) while in the second case only the vector part is present, while the point is supplied in a different argument where needed.
VectorBundleFibers refers to the whole set of fibers of a vector bundle. There is also another type, VectorSpaceAtPoint, that represents a specific fiber at a given point. This distinction is made to reduce the need to repeatedly construct objects of type VectorSpaceAtPoint in certain usage scenarios. This is also considered a manifold.
FVector
For cases where confusion between different types of vectors is possible, the type FVector can be used to express which type of vector space the vector belongs to. It is used for example in musical isomorphisms (the flat and sharp functions) that are used to go from a tangent space to cotangent space and vice versa.
Documentation
Manifolds.SasakiRetraction — Type
struct SasakiRetraction <: AbstractRetractionMethod end
Exponential map on TangentBundle computed via Euler integration as described in [Muralidharan2012]. The system of equations for $\gamma : ℝ \to T\mathcal M$ such that $\gamma(1) = \exp_{p,X}(X_M, X_F)$ and $\gamma(0)=(p, X)$ reads
\[\dot{\gamma}(t) = (\dot{p}(t), \dot{X}(t)) = (R(X(t), \dot{X}(t))\dot{p}(t), 0)\]
where $R$ is the Riemann curvature tensor (see riemann_tensor).
Constructor
SasakiRetraction(L::Int)
In this constructor L is the number of integration steps.
source
Manifolds.TangentBundle — Type
TangentBundle{𝔽,M} = VectorBundle{𝔽,TangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}
Tangent bundle for manifold of type M, as a manifold with the Sasaki metric [Sasaki1958].
Exact retraction and inverse retraction can be approximated using VectorBundleProductRetraction, VectorBundleInverseProductRetraction and SasakiRetraction. VectorBundleProductVectorTransport can be used as a vector transport.
Constructors
TangentBundle(M::AbstractManifold)
+TangentBundle(M::AbstractManifold, vtm::VectorBundleProductVectorTransport)
source
Manifolds.TensorProductType — Type
TensorProductType(spaces::VectorSpaceType...)
Vector space type corresponding to the tensor product of given vector space types.
source
Manifolds.VectorBundleFibers — Type
VectorBundleFibers(fiber::VectorSpaceType, M::AbstractManifold)
Type representing a family of vector spaces (fibers) of a vector bundle over M with vector spaces of type fiber. In contrast with VectorBundle, operations on VectorBundleFibers expect point-like and vector-like parts to be passed separately instead of being bundled together. It can be thought of as a representation of vector spaces from a vector bundle but without storing the point at which a vector space is attached (which is specified separately in various functions).
source
Manifolds.VectorBundleInverseProductRetraction — Type
struct VectorBundleInverseProductRetraction <: AbstractInverseRetractionMethod end
Inverse retraction of the point y at point p from vector bundle B over manifold B.fiber (denoted $\mathcal M$). The inverse retraction is derived as a product manifold-style approximation to the logarithmic map in the Sasaki metric. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.
Notation:
  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$. Similarly, $q = (x_q, V_q)$.
The inverse retraction is calculated as
\[\operatorname{retr}^{-1}_p q = (\operatorname{retr}^{-1}_{x_p}(x_q), V_{\operatorname{retr}^{-1}} - V_p)\]
where $V_{\operatorname{retr}^{-1}}$ is the result of vector transport of $V_q$ to the point $x_p$. The difference $V_{\operatorname{retr}^{-1}} - V_p$ corresponds to the logarithmic map in the vector space $F$.
See also VectorBundleProductRetraction.
source
Manifolds.VectorBundleProductRetraction — Type
struct VectorBundleProductRetraction <: AbstractRetractionMethod end
Product retraction map of tangent vector $X$ at point $p$ from vector bundle B over manifold B.fiber (denoted $\mathcal M$). The retraction is derived as a product manifold-style approximation to the exponential map in the Sasaki metric. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.
Notation:
  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
  • The tangent vector $X = (V_{X,M}, V_{X,F}) ∈ T_pB$ where $V_{X,M}$ is a tangent vector from the tangent space $T_{x_p}\mathcal M$ and $V_{X,F}$ is a tangent vector from the tangent space $T_{V_p}F$ (isomorphic to $F$).
The retraction is calculated as
\[\operatorname{retr}_p(X) = (\exp_{x_p}(V_{X,M}), V_{\exp})\]
where $V_{\exp}$ is the result of vector transport of $V_p + V_{X,F}$ to the point $\exp_{x_p}(V_{X,M})$. The sum $V_p + V_{X,F}$ corresponds to the exponential map in the vector space $F$.
See also VectorBundleInverseProductRetraction.
source
Manifolds.VectorBundleProductVectorTransport — Type
VectorBundleProductVectorTransport{
     TMP<:AbstractVectorTransportMethod,
     TMV<:AbstractVectorTransportMethod,
 } <: AbstractVectorTransportMethod
Vector transport type on VectorBundle. method_point is used for vector transport of the point part and method_vector is used for transport of the vector part.
The vector transport is derived as a product manifold-style vector transport. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.
Constructor
VectorBundleProductVectorTransport(
     method_point::AbstractVectorTransportMethod,
     method_vector::AbstractVectorTransportMethod,
 )
-VectorBundleProductVectorTransport()
By default both methods are set to ParallelTransport.
source
Manifolds.VectorSpaceAtPoint — Type
VectorSpaceAtPoint{
     𝔽,
     TFiber<:VectorBundleFibers{<:VectorSpaceType,<:AbstractManifold{𝔽}},
     TX,
-} <: AbstractManifold{𝔽}
A vector space at a point p on the manifold. This is modelled using VectorBundleFibers with only a vector-like part and fixing the point-like part to be just p.
This vector space itself is also a manifold. Especially, it's flat and hence isometric to the Euclidean manifold.
Constructor
VectorSpaceAtPoint(fiber::VectorBundleFibers, p)
A vector space (fiber type fiber of a vector bundle) at point p from the manifold fiber.manifold.
source
Base.exp — Method
exp(M::TangentSpaceAtPoint, p, X)
Exponential map of tangent vectors X and p from the tangent space M. It is calculated as their sum.
source
Base.getindex — Method
getindex(p::ArrayPartition, M::VectorBundle, s::Symbol)
-p[M::VectorBundle, s]
Access the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.
source
Base.getindex — Method
getindex(p::ProductRepr, M::VectorBundle, s::Symbol)
-p[M::VectorBundle, s]
Access the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.
source
Base.log — Method
log(M::TangentSpaceAtPoint, p, q)
Logarithmic map on the tangent space manifold M, calculated as the difference of tangent vectors q and p from M.
source
Base.setindex! — Method
setindex!(p::ArrayPartition, val, M::VectorBundle, s::Symbol)
-p[M::VectorBundle, s] = val
Set the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.
Note
The content of element of p is replaced, not the element itself.
source
Base.setindex! — Method
setindex!(p::ProductRepr, val, M::VectorBundle, s::Symbol)
-p[M::VectorBundle, s] = val
Set the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.
Note
The content of element of p is replaced, not the element itself.
source
LinearAlgebra.norm — Method
norm(B::VectorBundleFibers, p, q)
Norm of the vector X from the vector space of type B.fiber at point p from manifold B.manifold.
source
Manifolds.bundle_projection — Method
bundle_projection(B::VectorBundle, p::ArrayPartition)
Projection of point p from the bundle M to the base manifold. Returns the point on the base manifold B.manifold at which the vector part of p is attached.
source
Manifolds.vector_bundle_transport — Method
vector_bundle_transport(fiber::VectorSpaceType, M::AbstractManifold)
Determine the vector tranport used for exp and log maps on a vector bundle with vector space type fiber and manifold M.
source
ManifoldsBase.allocate_result — Method
allocate_result(B::VectorBundleFibers, f, x...)
Allocates an array for the result of function f that is an element of the vector space of type B.fiber on manifold B.manifold and arguments x... for implementing the non-modifying operation using the modifying operation.
source
ManifoldsBase.allocate_result_type — Method
allocate_result_type(B::VectorBundleFibers, f, args::NTuple{N,Any}) where N
Return type of element of the array that will represent the result of function f for representing an operation with result in the vector space fiber for manifold M on given arguments (passed at a tuple).
source
ManifoldsBase.distance — Method
distance(M::TangentSpaceAtPoint, p, q)
Distance between vectors p and q from the vector space M. It is calculated as the norm of their difference.
source
ManifoldsBase.distance — Method
distance(B::VectorBundleFibers, p, X, Y)
Distance between vectors X and Y from the vector space at point p from the manifold B.manifold, that is the base manifold of M.
source
ManifoldsBase.inner — Method
inner(M::TangentSpaceAtPoint, p, X, Y)
Inner product of vectors X and Y from the tangent space at M.
source
ManifoldsBase.inner — Method
inner(B::VectorBundle, p, X, Y)
Inner product of tangent vectors X and Y at point p from the vector bundle B over manifold B.fiber (denoted $\mathcal M$).
Notation:
  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
  • The tangent vector $v = (V_{X,M}, V_{X,F}) ∈ T_{x}B$ where $V_{X,M}$ is a tangent vector from the tangent space $T_{x_p}\mathcal M$ and $V_{X,F}$ is a tangent vector from the tangent space $T_{V_p}F$ (isomorphic to $F$). Similarly for the other tangent vector $w = (V_{Y,M}, V_{Y,F}) ∈ T_{x}B$.
The inner product is calculated as
\[⟨X, Y⟩_p = ⟨V_{X,M}, V_{Y,M}⟩_{x_p} + ⟨V_{X,F}, V_{Y,F}⟩_{V_p}.\]
source
ManifoldsBase.inner — Method
inner(B::VectorBundleFibers, p, X, Y)
Inner product of vectors X and Y from the vector space of type B.fiber at point p from manifold B.manifold.
source
ManifoldsBase.project — Method
project(M::TangentSpaceAtPoint, p, X)
Project the vector X from the tangent space M, that is project the vector X tangent at M.point.
source
ManifoldsBase.project — Method
project(M::TangentSpaceAtPoint, p)
Project the point p from the tangent space M, that is project the vector p tangent at M.point.
source
ManifoldsBase.project — Method
project(B::VectorBundle, p, X)
Project the element X of the ambient space of the tangent space $T_p B$ to the tangent space $T_p B$.
Notation:
  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
  • The vector $x = (V_{X,M}, V_{X,F})$ where $x_p$ belongs to the ambient space of $T_{x_p}\mathcal M$ and $V_{X,F}$ belongs to the ambient space of the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
The projection is calculated by projecting $V_{X,M}$ to tangent space $T_{x_p}\mathcal M$ and then projecting the vector $V_{X,F}$ to the fiber $F$.
source
ManifoldsBase.project — Method
project(B::VectorBundle, p)
Project the point p from the ambient space of the vector bundle B over manifold B.fiber (denoted $\mathcal M$) to the vector bundle.
Notation:
  • The point $p = (x_p, V_p)$ where $x_p$ belongs to the ambient space of $\mathcal M$ and $V_p$ belongs to the ambient space of the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
The projection is calculated by projecting the point $x_p$ to the manifold $\mathcal M$ and then projecting the vector $V_p$ to the tangent space $T_{x_p}\mathcal M$.
source
ManifoldsBase.project — Method
project(B::VectorBundleFibers, p, X)
Project vector X from the vector space of type B.fiber at point p.
source
ManifoldsBase.zero_vector! — Method
zero_vector!(B::VectorBundleFibers, X, p)
Save the zero vector from the vector space of type B.fiber at point p from manifold B.manifold to X.
source
ManifoldsBase.zero_vector — Method
zero_vector(M::TangentSpaceAtPoint, p)
Zero tangent vector at point p from the tangent space M, that is the zero tangent vector at point M.point.
source
ManifoldsBase.zero_vector — Method
zero_vector(B::VectorBundle, p)
Zero tangent vector at point p from the vector bundle B over manifold B.fiber (denoted $\mathcal M$). The zero vector belongs to the space $T_{p}B$
Notation:
  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
The zero vector is calculated as
\[\mathbf{0}_{p} = (\mathbf{0}_{x_p}, \mathbf{0}_F)\]
where $\mathbf{0}_{x_p}$ is the zero tangent vector from $T_{x_p}\mathcal M$ and $\mathbf{0}_F$ is the zero element of the vector space $F$.
source
ManifoldsBase.zero_vector — Method
zero_vector(B::VectorBundleFibers, p)
Compute the zero vector from the vector space of type B.fiber at point p from manifold B.manifold.
source
Example
The following code defines a point on the tangent bundle of the sphere $S^2$ and a tangent vector to that point.
using Manifolds
+} <: AbstractManifold{𝔽}
A vector space at a point p on the manifold. This is modelled using VectorBundleFibers with only a vector-like part and fixing the point-like part to be just p.
This vector space itself is also a manifold. Especially, it's flat and hence isometric to the Euclidean manifold.
Constructor
VectorSpaceAtPoint(fiber::VectorBundleFibers, p)
A vector space (fiber type fiber of a vector bundle) at point p from the manifold fiber.manifold.
source
Base.exp — Method
exp(M::TangentSpaceAtPoint, p, X)

Exponential map of tangent vectors X and p from the tangent space M. It is calculated as their sum.

source
Base.getindex — Method
getindex(p::ArrayPartition, M::VectorBundle, s::Symbol)
+p[M::VectorBundle, s]

Access the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.

source
Base.getindex — Method
getindex(p::ProductRepr, M::VectorBundle, s::Symbol)
+p[M::VectorBundle, s]

Access the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.

source
Base.log — Method
log(M::TangentSpaceAtPoint, p, q)

Logarithmic map on the tangent space manifold M, calculated as the difference of tangent vectors q and p from M.

source
Base.setindex! — Method
setindex!(p::ArrayPartition, val, M::VectorBundle, s::Symbol)
+p[M::VectorBundle, s] = val

Set the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.

Note

The content of element of p is replaced, not the element itself.

source
Base.setindex! — Method
setindex!(p::ProductRepr, val, M::VectorBundle, s::Symbol)
+p[M::VectorBundle, s] = val

Set the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.

Note

The content of element of p is replaced, not the element itself.

source
LinearAlgebra.norm — Method
norm(B::VectorBundleFibers, p, q)

Norm of the vector X from the vector space of type B.fiber at point p from manifold B.manifold.

source
Manifolds.bundle_projection — Method
bundle_projection(B::VectorBundle, p::ArrayPartition)

Projection of point p from the bundle M to the base manifold. Returns the point on the base manifold B.manifold at which the vector part of p is attached.

source
Manifolds.vector_bundle_transport — Method
vector_bundle_transport(fiber::VectorSpaceType, M::AbstractManifold)

Determine the vector tranport used for exp and log maps on a vector bundle with vector space type fiber and manifold M.

source
ManifoldsBase.allocate_result — Method
allocate_result(B::VectorBundleFibers, f, x...)

Allocates an array for the result of function f that is an element of the vector space of type B.fiber on manifold B.manifold and arguments x... for implementing the non-modifying operation using the modifying operation.

source
ManifoldsBase.allocate_result_type — Method
allocate_result_type(B::VectorBundleFibers, f, args::NTuple{N,Any}) where N

Return type of element of the array that will represent the result of function f for representing an operation with result in the vector space fiber for manifold M on given arguments (passed at a tuple).

source
ManifoldsBase.distance — Method
distance(M::TangentSpaceAtPoint, p, q)

Distance between vectors p and q from the vector space M. It is calculated as the norm of their difference.

source
ManifoldsBase.distance — Method
distance(B::VectorBundleFibers, p, X, Y)

Distance between vectors X and Y from the vector space at point p from the manifold B.manifold, that is the base manifold of M.

source
ManifoldsBase.inner — Method
inner(M::TangentSpaceAtPoint, p, X, Y)

Inner product of vectors X and Y from the tangent space at M.

source
ManifoldsBase.inner — Method
inner(B::VectorBundle, p, X, Y)

Inner product of tangent vectors X and Y at point p from the vector bundle B over manifold B.fiber (denoted $\mathcal M$).

Notation:

  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
  • The tangent vector $v = (V_{X,M}, V_{X,F}) ∈ T_{x}B$ where $V_{X,M}$ is a tangent vector from the tangent space $T_{x_p}\mathcal M$ and $V_{X,F}$ is a tangent vector from the tangent space $T_{V_p}F$ (isomorphic to $F$). Similarly for the other tangent vector $w = (V_{Y,M}, V_{Y,F}) ∈ T_{x}B$.

The inner product is calculated as

\[⟨X, Y⟩_p = ⟨V_{X,M}, V_{Y,M}⟩_{x_p} + ⟨V_{X,F}, V_{Y,F}⟩_{V_p}.\]

source
ManifoldsBase.inner — Method
inner(B::VectorBundleFibers, p, X, Y)

Inner product of vectors X and Y from the vector space of type B.fiber at point p from manifold B.manifold.

source
ManifoldsBase.project — Method
project(M::TangentSpaceAtPoint, p, X)

Project the vector X from the tangent space M, that is project the vector X tangent at M.point.

source
ManifoldsBase.project — Method
project(M::TangentSpaceAtPoint, p)

Project the point p from the tangent space M, that is project the vector p tangent at M.point.

source
ManifoldsBase.project — Method
project(B::VectorBundle, p, X)

Project the element X of the ambient space of the tangent space $T_p B$ to the tangent space $T_p B$.

Notation:

  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
  • The vector $x = (V_{X,M}, V_{X,F})$ where $x_p$ belongs to the ambient space of $T_{x_p}\mathcal M$ and $V_{X,F}$ belongs to the ambient space of the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.

The projection is calculated by projecting $V_{X,M}$ to tangent space $T_{x_p}\mathcal M$ and then projecting the vector $V_{X,F}$ to the fiber $F$.

source
ManifoldsBase.project — Method
project(B::VectorBundle, p)

Project the point p from the ambient space of the vector bundle B over manifold B.fiber (denoted $\mathcal M$) to the vector bundle.

Notation:

  • The point $p = (x_p, V_p)$ where $x_p$ belongs to the ambient space of $\mathcal M$ and $V_p$ belongs to the ambient space of the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.

The projection is calculated by projecting the point $x_p$ to the manifold $\mathcal M$ and then projecting the vector $V_p$ to the tangent space $T_{x_p}\mathcal M$.

source
ManifoldsBase.project — Method
project(B::VectorBundleFibers, p, X)

Project vector X from the vector space of type B.fiber at point p.

source
ManifoldsBase.zero_vector! — Method
zero_vector!(B::VectorBundleFibers, X, p)

Save the zero vector from the vector space of type B.fiber at point p from manifold B.manifold to X.

source
ManifoldsBase.zero_vector — Method
zero_vector(M::TangentSpaceAtPoint, p)

Zero tangent vector at point p from the tangent space M, that is the zero tangent vector at point M.point.

source
ManifoldsBase.zero_vector — Method
zero_vector(B::VectorBundle, p)

Zero tangent vector at point p from the vector bundle B over manifold B.fiber (denoted $\mathcal M$). The zero vector belongs to the space $T_{p}B$

Notation:

  • The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.

The zero vector is calculated as

\[\mathbf{0}_{p} = (\mathbf{0}_{x_p}, \mathbf{0}_F)\]

where $\mathbf{0}_{x_p}$ is the zero tangent vector from $T_{x_p}\mathcal M$ and $\mathbf{0}_F$ is the zero element of the vector space $F$.

source
ManifoldsBase.zero_vector — Method
zero_vector(B::VectorBundleFibers, p)

Compute the zero vector from the vector space of type B.fiber at point p from manifold B.manifold.

source

Example

The following code defines a point on the tangent bundle of the sphere $S^2$ and a tangent vector to that point.

using Manifolds
 M = Sphere(2)
 TB = TangentBundle(M)
 p = ProductRepr([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])
@@ -30,4 +30,4 @@
     0.0
     0.0
    -2.0

An approximation of the exponential in the Sasaki metric using 1000 steps can be calculated as follows.

q = retract(TB, p, X, SasakiRetraction(1000))
-println("Approximation of the exponential map: ", q)
Approximation of the exponential map: ProductRepr{Tuple{Vector{Float64}, Vector{Float64}}}(([0.6759570857309888, 0.35241486404386485, 0.6472138609849252], [-1.0318269583261073, 0.6273324630574116, 0.7360618920075961]))
  • Muralidharan2012

    P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012, pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.

  • Sasaki1958

    S. Sasaki, “On the differential geometry of tangent bundles of Riemannian manifolds,” Tohoku Math. J. (2), vol. 10, no. 3, pp. 338–354, 1958, doi: 10.2748/tmj/1178244668.

+println("Approximation of the exponential map: ", q)
Approximation of the exponential map: ProductRepr{Tuple{Vector{Float64}, Vector{Float64}}}(([0.6759570857309881, 0.352414864043865, 0.6472138609849256], [-1.031826958326108, 0.6273324630574114, 0.7360618920075952]))
  • Muralidharan2012

    P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012, pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.

  • Sasaki1958

    S. Sasaki, “On the differential geometry of tangent bundles of Riemannian manifolds,” Tohoku Math. J. (2), vol. 10, no. 3, pp. 338–354, 1958, doi: 10.2748/tmj/1178244668.

diff --git a/previews/PR628/misc/about.html b/previews/PR628/misc/about.html index e59affa5a4..2795db2060 100644 --- a/previews/PR628/misc/about.html +++ b/previews/PR628/misc/about.html @@ -1,2 +1,2 @@ -About · Manifolds.jl
Edit on GitHub
+About · Manifolds.jl
Edit on GitHub
diff --git a/previews/PR628/misc/contributing.html b/previews/PR628/misc/contributing.html index 62f12097fa..a518facd6e 100644 --- a/previews/PR628/misc/contributing.html +++ b/previews/PR628/misc/contributing.html @@ -6,4 +6,4 @@ Describe the function. """ -exp(::MyManifold, ::Any...)

Code style

We try to follow the documentation guidelines from the Julia documentation as well as Blue Style. We run JuliaFormatter.jl on the repo in the way set in the .JuliaFormatter.toml file, which enforces a number of conventions consistent with the Blue Style.

We also follow a few internal conventions:

  • It is preferred that the AbstractManifold's struct contain a reference to the general theory.
  • Any implemented function should be accompanied by its mathematical formulae if a closed form exists.
  • Within the source code of one manifold, the type of the manifold should be the first element of the file, and an alphabetical order of the functions is preferable.
  • The above implies that the in-place variant of a function follows the non-mutating variant.
  • There should be no dangling = signs.
  • Always add a newline between things of different types (struct/method/const).
  • Always add a newline between methods for different functions (including in-place/nonmutating variants).
  • Prefer to have no newline between methods for the same function; when reasonable, merge the docstrings.
  • All import/using/include should be in the main module file.
+exp(::MyManifold, ::Any...)

Code style

We try to follow the documentation guidelines from the Julia documentation as well as Blue Style. We run JuliaFormatter.jl on the repo in the way set in the .JuliaFormatter.toml file, which enforces a number of conventions consistent with the Blue Style.

We also follow a few internal conventions:

  • It is preferred that the AbstractManifold's struct contain a reference to the general theory.
  • Any implemented function should be accompanied by its mathematical formulae if a closed form exists.
  • Within the source code of one manifold, the type of the manifold should be the first element of the file, and an alphabetical order of the functions is preferable.
  • The above implies that the in-place variant of a function follows the non-mutating variant.
  • There should be no dangling = signs.
  • Always add a newline between things of different types (struct/method/const).
  • Always add a newline between methods for different functions (including in-place/nonmutating variants).
  • Prefer to have no newline between methods for the same function; when reasonable, merge the docstrings.
  • All import/using/include should be in the main module file.
diff --git a/previews/PR628/misc/internals.html b/previews/PR628/misc/internals.html index f67fa23a24..1a61180256 100644 --- a/previews/PR628/misc/internals.html +++ b/previews/PR628/misc/internals.html @@ -1,8 +1,8 @@ -Internals · Manifolds.jl
Edit on GitHub

Internal documentation

This page documents the internal types and methods of Manifolds.jl's that might be of use for writing your own manifold.

Functions

Manifolds.eigen_safe — Function
eigen_safe(x)

Compute the eigendecomposition of x. If x is a StaticMatrix, it is converted to a Matrix before the decomposition.

source
Manifolds.isnormal — Function
isnormal(x; kwargs...) -> Bool

Check if the matrix or number x is normal, that is, if it commutes with its adjoint:

\[x x^\mathrm{H} = x^\mathrm{H} x.\]

By default, this is an equality check. Provide kwargs for isapprox to perform an approximate check.

source
Manifolds.log_safe — Function
log_safe(x)

Compute the matrix logarithm of x. If x is a StaticMatrix, it is converted to a Matrix before computing the log.

source
Manifolds.log_safe! — Function
log_safe!(y, x)

Compute the matrix logarithm of x. If the eltype of y is real, then the imaginary part of x is ignored, and a DomainError is raised if real(x) has no real logarithm.

source
Manifolds.mul!_safe — Function
mul!_safe(Y, A, B) -> Y

Call mul! safely, that is, A and/or B are permitted to alias with Y.

source
Manifolds.nzsign — Function
nzsign(z[, absz])

Compute a modified sign(z) that is always nonzero, i.e. where

\[\operatorname(nzsign)(z) = \begin{cases} +Internals · Manifolds.jl

Edit on GitHub

Internal documentation

This page documents the internal types and methods of Manifolds.jl's that might be of use for writing your own manifold.

Functions

Manifolds.eigen_safe — Function
eigen_safe(x)

Compute the eigendecomposition of x. If x is a StaticMatrix, it is converted to a Matrix before the decomposition.

source
Manifolds.isnormal — Function
isnormal(x; kwargs...) -> Bool

Check if the matrix or number x is normal, that is, if it commutes with its adjoint:

\[x x^\mathrm{H} = x^\mathrm{H} x.\]

By default, this is an equality check. Provide kwargs for isapprox to perform an approximate check.

source
Manifolds.log_safe — Function
log_safe(x)

Compute the matrix logarithm of x. If x is a StaticMatrix, it is converted to a Matrix before computing the log.

source
Manifolds.log_safe! — Function
log_safe!(y, x)

Compute the matrix logarithm of x. If the eltype of y is real, then the imaginary part of x is ignored, and a DomainError is raised if real(x) has no real logarithm.

source
Manifolds.mul!_safe — Function
mul!_safe(Y, A, B) -> Y

Call mul! safely, that is, A and/or B are permitted to alias with Y.

source
Manifolds.nzsign — Function
nzsign(z[, absz])

Compute a modified sign(z) that is always nonzero, i.e. where

\[\operatorname(nzsign)(z) = \begin{cases} 1 & \text{if } z = 0\\ \frac{z}{|z|} & \text{otherwise} -\end{cases}\]

source
Manifolds.realify — Function
realify(X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers) -> Y::AbstractMatrix{<:Real}

Given a matrix $X ∈ 𝔽^{n × n}$, compute $Y ∈ ℝ^{m × m}$, where $m = n \operatorname{dim}_𝔽$, and $\operatorname{dim}_𝔽$ is the real_dimension of the number field $𝔽$, using the map $ϕ \colon X ↦ Y$, that preserves the matrix product, so that for all $C,D ∈ 𝔽^{n × n}$,

\[ϕ(C) ϕ(D) = ϕ(CD).\]

See realify! for an in-place version, and unrealify! to compute the inverse of $ϕ$.

source
Manifolds.realify! — Function
realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers)

In-place version of realify.

source
realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{<:Complex}, ::typeof(ℂ))

Given a complex matrix $X = A + iB ∈ ℂ^{n × n}$, compute its realified matrix $Y ∈ ℝ^{2n × 2n}$, written where

\[Y = \begin{pmatrix}A & -B \\ B & A \end{pmatrix}.\]

source
Manifolds.select_from_tuple — Function
select_from_tuple(t::NTuple{N, Any}, positions::Val{P})

Selects elements of tuple t at positions specified by the second argument. For example select_from_tuple(("a", "b", "c"), Val((3, 1, 1))) returns ("c", "a", "a").

source
Manifolds.unrealify! — Function
unrealify!(X::AbstractMatrix{T𝔽}, Y::AbstractMatrix{<:Real}, 𝔽::AbstractNumbers[, n])

Given a real matrix $Y ∈ ℝ^{m × m}$, where $m = n \operatorname{dim}_𝔽$, and $\operatorname{dim}_𝔽$ is the real_dimension of the number field $𝔽$, compute in-place its equivalent matrix $X ∈ 𝔽^{n × n}$. Note that this function does not check that $Y$ has a valid structure to be un-realified.

See realify! for the inverse of this function.

source
Manifolds.usinc — Function
usinc(θ::Real)

Unnormalized version of sinc function, i.e. $\operatorname{usinc}(θ) = \frac{\sin(θ)}{θ}$. This is equivalent to sinc(θ/π).

source
Manifolds.usinc_from_cos — Function
usinc_from_cos(x::Real)

Unnormalized version of sinc function, i.e. $\operatorname{usinc}(θ) = \frac{\sin(θ)}{θ}$, computed from $x = cos(θ)$.

source
Manifolds.vec2skew! — Function
vec2skew!(X, v, k)

create a skew symmetric matrix inplace in X of size $k\times k$ from a vector v, for example for v=[1,2,3] and k=3 this yields

[  0  1  2;
+\end{cases}\]
source
Manifolds.realify — Function
realify(X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers) -> Y::AbstractMatrix{<:Real}

Given a matrix $X ∈ 𝔽^{n × n}$, compute $Y ∈ ℝ^{m × m}$, where $m = n \operatorname{dim}_𝔽$, and $\operatorname{dim}_𝔽$ is the real_dimension of the number field $𝔽$, using the map $ϕ \colon X ↦ Y$, that preserves the matrix product, so that for all $C,D ∈ 𝔽^{n × n}$,

\[ϕ(C) ϕ(D) = ϕ(CD).\]

See realify! for an in-place version, and unrealify! to compute the inverse of $ϕ$.

source
Manifolds.realify! — Function
realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers)

In-place version of realify.

source
realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{<:Complex}, ::typeof(ℂ))

Given a complex matrix $X = A + iB ∈ ℂ^{n × n}$, compute its realified matrix $Y ∈ ℝ^{2n × 2n}$, written where

\[Y = \begin{pmatrix}A & -B \\ B & A \end{pmatrix}.\]

source
Manifolds.select_from_tuple — Function
select_from_tuple(t::NTuple{N, Any}, positions::Val{P})

Selects elements of tuple t at positions specified by the second argument. For example select_from_tuple(("a", "b", "c"), Val((3, 1, 1))) returns ("c", "a", "a").

source
Manifolds.unrealify! — Function
unrealify!(X::AbstractMatrix{T𝔽}, Y::AbstractMatrix{<:Real}, 𝔽::AbstractNumbers[, n])

Given a real matrix $Y ∈ ℝ^{m × m}$, where $m = n \operatorname{dim}_𝔽$, and $\operatorname{dim}_𝔽$ is the real_dimension of the number field $𝔽$, compute in-place its equivalent matrix $X ∈ 𝔽^{n × n}$. Note that this function does not check that $Y$ has a valid structure to be un-realified.

See realify! for the inverse of this function.

source
Manifolds.usinc — Function
usinc(θ::Real)

Unnormalized version of sinc function, i.e. $\operatorname{usinc}(θ) = \frac{\sin(θ)}{θ}$. This is equivalent to sinc(θ/π).

source
Manifolds.usinc_from_cos — Function
usinc_from_cos(x::Real)

Unnormalized version of sinc function, i.e. $\operatorname{usinc}(θ) = \frac{\sin(θ)}{θ}$, computed from $x = cos(θ)$.

source
Manifolds.vec2skew! — Function
vec2skew!(X, v, k)

create a skew symmetric matrix inplace in X of size $k\times k$ from a vector v, for example for v=[1,2,3] and k=3 this yields

[  0  1  2;
   -1  0  3;
   -2 -3  0
-]
source
Manifolds.ziptuples — Function
ziptuples(a, b[, c[, d[, e]]])

Zips tuples a, b, and remaining in a fast, type-stable way. If they have different lengths, the result is trimmed to the length of the shorter tuple.

source
+]
source
Manifolds.ziptuples — Function
ziptuples(a, b[, c[, d[, e]]])

Zips tuples a, b, and remaining in a fast, type-stable way. If they have different lengths, the result is trimmed to the length of the shorter tuple.

source
diff --git a/previews/PR628/misc/notation.html b/previews/PR628/misc/notation.html index 591fca40ba..5b0318145f 100644 --- a/previews/PR628/misc/notation.html +++ b/previews/PR628/misc/notation.html @@ -1,2 +1,2 @@ -Notation · Manifolds.jl
Edit on GitHub

Notation overview

Since manifolds include a reasonable amount of elements and functions, the following list tries to keep an overview of used notation throughout Manifolds.jl. The order is alphabetical by name. They might be used in a plain form within the code or when referring to that code. This is for example the case with the calligraphic symbols.

Within the documented functions, the utf8 symbols are used whenever possible, as long as that renders correctly in $\TeX$ within this documentation.

SymbolDescriptionAlso usedComment
$\tau_p$action map by group element $p$$\mathrm{L}_p$, $\mathrm{R}_p$either left or right
$\operatorname{Ad}_p(X)$adjoint action of element $p$ of a Lie group on the element $X$ of the corresponding Lie algebra
$\times$Cartesian product of two manifoldssee ProductManifold
$^{\wedge}$(n-ary) Cartesian power of a manifoldsee PowerManifold
$\cdot^\mathrm{H}$conjugate/Hermitian transpose
$a$coordinates of a point in a chartsee get_parameters
$\frac{\mathrm{D}}{\mathrm{d}t}$covariant derivative of a vector field $X(t)$
$T^*_p \mathcal M$the cotangent space at $p$
$ξ$a cotangent vector from $T^*_p \mathcal M$$ξ_1, ξ_2,… ,η,\zeta$sometimes written with base point $ξ_p$.
$\mathrm{d}\phi_p(q)$Differential of a map $\phi: \mathcal M \to \mathcal N$ with respect to $p$ at a point $q$. For functions of multiple variables, for example $\phi(p, p_1)$ where $p \in \mathcal M$ and $p_1 \in \mathcal M_1$, variable $p$ is explicitly stated to specify with respect to which argument the differential is calculated.$\mathrm{d}\phi_q$, $(\mathrm{d}\phi)_q$, $(\phi_*)_q$, $D_p\phi(q)$pushes tangent vectors $X \in T_q \mathcal M$ forward to $\mathrm{d}\phi_p(q)[X] \in T_{\phi(q)} \mathcal N$
$n$dimension (of a manifold)$n_1,n_2,\ldots,m, \dim(\mathcal M)$for the real dimension sometimes also $\dim_{\mathbb R}(\mathcal M)$
$d(\cdot,\cdot)$(Riemannian) distance$d_{\mathcal M}(\cdot,\cdot)$
$\exp_p X$exponential map at $p \in \mathcal M$ of a vector $X \in T_p \mathcal M$$\exp_p(X)$
$F$a fibersee VectorBundleFibers
$\mathbb F$a field, usually $\mathbb F \in \{\mathbb R,\mathbb C, \mathbb H\}$, i.e. the real, complex, and quaternion numbers, respectively.field a manifold or a basis is based on
$\gamma$a geodesic$\gamma_{p;q}$, $\gamma_{p,X}$connecting two points $p,q$ or starting in $p$ with velocity $X$.
$∇ f(p)$gradient of function $f \colon \mathcal{M} \to \mathbb{R}$ at $p \in \mathcal{M}$
$\circ$a group operation
$\cdot^\mathrm{H}$Hermitian or conjugate transposed for both complex or quaternion matrices
$e$identity element of a group
$I_k$identity matrix of size $k\times k$
$k$indices$i,j$
$\langle\cdot,\cdot\rangle$inner product (in $T_p \mathcal M$)$\langle\cdot,\cdot\rangle_p, g_p(\cdot,\cdot)$
$\operatorname{retr}^{-1}_pq$an inverse retraction
$\mathfrak g$a Lie algebra
$\mathcal{G}$a (Lie) group
$\log_p q$logarithmic map at $p \in \mathcal M$ of a point $q \in \mathcal M$$\log_p(q)$
$\mathcal M$a manifold$\mathcal M_1, \mathcal M_2,\ldots,\mathcal N$
$\operatorname{Exp}$the matrix exponential
$\operatorname{Log}$the matrix logarithm
$\mathcal P_{q\gets p}X$parallel transportof the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$
$\mathcal P_{p,Y}X$parallel transport in direction $Y$of the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$, $q = \exp_pY$
$\mathcal P_{t_1\gets t_0}^cX$parallel transport along the curve $c$$\mathcal P^cX=\mathcal P_{1\gets 0}^cX$of the vector $X$ from $p=c(0)$ to $c(1)$
$p$a point on $\mathcal M$$p_1, p_2, \ldots,q$for 3 points one might use $x,y,z$
$\operatorname{retr}_pX$a retraction
$ξ$a set of tangent vectors$\{X_1,\ldots,X_n\}$
$T_p \mathcal M$the tangent space at $p$
$X$a tangent vector from $T_p \mathcal M$$X_1,X_2,\ldots,Y,Z$sometimes written with base point $X_p$
$\operatorname{tr}$trace (of a matrix)
$\cdot^\mathrm{T}$transposed
$e_i \in \mathbb R^n$the $i$th unit vector$e_i^n$the space dimension ($n$) is omited, when clear from context
$B$a vector bundle
$\mathcal T_{q\gets p}X$vector transportof the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$
$\mathcal T_{p,Y}X$vector transport in direction $Y$of the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$, where $q$ is deretmined by $Y$, for example using the exponential map or some retraction.
$\operatorname{Vol}(\mathcal M)$volume of manifold $\mathcal M$
$\theta_p(X)$volume density for vector $X$ tangent at point $p$
$0_k$the $k\times k$ zero matrix.
+Notation · Manifolds.jl
Edit on GitHub

Notation overview

Since manifolds include a reasonable amount of elements and functions, the following list tries to keep an overview of used notation throughout Manifolds.jl. The order is alphabetical by name. They might be used in a plain form within the code or when referring to that code. This is for example the case with the calligraphic symbols.

Within the documented functions, the utf8 symbols are used whenever possible, as long as that renders correctly in $\TeX$ within this documentation.

SymbolDescriptionAlso usedComment
$\tau_p$action map by group element $p$$\mathrm{L}_p$, $\mathrm{R}_p$either left or right
$\operatorname{Ad}_p(X)$adjoint action of element $p$ of a Lie group on the element $X$ of the corresponding Lie algebra
$\times$Cartesian product of two manifoldssee ProductManifold
$^{\wedge}$(n-ary) Cartesian power of a manifoldsee PowerManifold
$\cdot^\mathrm{H}$conjugate/Hermitian transpose
$a$coordinates of a point in a chartsee get_parameters
$\frac{\mathrm{D}}{\mathrm{d}t}$covariant derivative of a vector field $X(t)$
$T^*_p \mathcal M$the cotangent space at $p$
$ξ$a cotangent vector from $T^*_p \mathcal M$$ξ_1, ξ_2,… ,η,\zeta$sometimes written with base point $ξ_p$.
$\mathrm{d}\phi_p(q)$Differential of a map $\phi: \mathcal M \to \mathcal N$ with respect to $p$ at a point $q$. For functions of multiple variables, for example $\phi(p, p_1)$ where $p \in \mathcal M$ and $p_1 \in \mathcal M_1$, variable $p$ is explicitly stated to specify with respect to which argument the differential is calculated.$\mathrm{d}\phi_q$, $(\mathrm{d}\phi)_q$, $(\phi_*)_q$, $D_p\phi(q)$pushes tangent vectors $X \in T_q \mathcal M$ forward to $\mathrm{d}\phi_p(q)[X] \in T_{\phi(q)} \mathcal N$
$n$dimension (of a manifold)$n_1,n_2,\ldots,m, \dim(\mathcal M)$for the real dimension sometimes also $\dim_{\mathbb R}(\mathcal M)$
$d(\cdot,\cdot)$(Riemannian) distance$d_{\mathcal M}(\cdot,\cdot)$
$\exp_p X$exponential map at $p \in \mathcal M$ of a vector $X \in T_p \mathcal M$$\exp_p(X)$
$F$a fibersee VectorBundleFibers
$\mathbb F$a field, usually $\mathbb F \in \{\mathbb R,\mathbb C, \mathbb H\}$, i.e. the real, complex, and quaternion numbers, respectively.field a manifold or a basis is based on
$\gamma$a geodesic$\gamma_{p;q}$, $\gamma_{p,X}$connecting two points $p,q$ or starting in $p$ with velocity $X$.
$∇ f(p)$gradient of function $f \colon \mathcal{M} \to \mathbb{R}$ at $p \in \mathcal{M}$
$\circ$a group operation
$\cdot^\mathrm{H}$Hermitian or conjugate transposed for both complex or quaternion matrices
$e$identity element of a group
$I_k$identity matrix of size $k\times k$
$k$indices$i,j$
$\langle\cdot,\cdot\rangle$inner product (in $T_p \mathcal M$)$\langle\cdot,\cdot\rangle_p, g_p(\cdot,\cdot)$
$\operatorname{retr}^{-1}_pq$an inverse retraction
$\mathfrak g$a Lie algebra
$\mathcal{G}$a (Lie) group
$\log_p q$logarithmic map at $p \in \mathcal M$ of a point $q \in \mathcal M$$\log_p(q)$
$\mathcal M$a manifold$\mathcal M_1, \mathcal M_2,\ldots,\mathcal N$
$\operatorname{Exp}$the matrix exponential
$\operatorname{Log}$the matrix logarithm
$\mathcal P_{q\gets p}X$parallel transportof the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$
$\mathcal P_{p,Y}X$parallel transport in direction $Y$of the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$, $q = \exp_pY$
$\mathcal P_{t_1\gets t_0}^cX$parallel transport along the curve $c$$\mathcal P^cX=\mathcal P_{1\gets 0}^cX$of the vector $X$ from $p=c(0)$ to $c(1)$
$p$a point on $\mathcal M$$p_1, p_2, \ldots,q$for 3 points one might use $x,y,z$
$\operatorname{retr}_pX$a retraction
$ξ$a set of tangent vectors$\{X_1,\ldots,X_n\}$
$T_p \mathcal M$the tangent space at $p$
$X$a tangent vector from $T_p \mathcal M$$X_1,X_2,\ldots,Y,Z$sometimes written with base point $X_p$
$\operatorname{tr}$trace (of a matrix)
$\cdot^\mathrm{T}$transposed
$e_i \in \mathbb R^n$the $i$th unit vector$e_i^n$the space dimension ($n$) is omited, when clear from context
$B$a vector bundle
$\mathcal T_{q\gets p}X$vector transportof the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$
$\mathcal T_{p,Y}X$vector transport in direction $Y$of the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$, where $q$ is deretmined by $Y$, for example using the exponential map or some retraction.
$\operatorname{Vol}(\mathcal M)$volume of manifold $\mathcal M$
$\theta_p(X)$volume density for vector $X$ tangent at point $p$
$0_k$the $k\times k$ zero matrix.
diff --git a/previews/PR628/search.html b/previews/PR628/search.html index 96307c8a01..be65f4017e 100644 --- a/previews/PR628/search.html +++ b/previews/PR628/search.html @@ -1,2 +1,2 @@ -Search · Manifolds.jl +Search · Manifolds.jl diff --git a/previews/PR628/search_index.js b/previews/PR628/search_index.js index d0af7002ca..850600f8cc 100644 --- a/previews/PR628/search_index.js +++ b/previews/PR628/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"tutorials/hand-gestures.html#Hand-gesture-analysis","page":"perform Hand gesture analysis","title":"Hand gesture analysis","text":"","category":"section"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"In this tutorial we will learn how to use Kendall’s shape space to analyze hand gesture data.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Let’s start by loading libraries required for our work.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"using Manifolds, CSV, DataFrames, Plots, MultivariateStats","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"[ Info: Precompiling ManifoldsRecipesBaseExt [37da849e-34ab-54fd-a5a4-b22599bd6cb0]","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Our first function loads dataset of hand gestures, described here.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"function load_hands()\n hands_url = \"https://raw.githubusercontent.com/geomstats/geomstats/master/geomstats/datasets/data/hands/hands.txt\"\n hand_labels_url = \"https://raw.githubusercontent.com/geomstats/geomstats/master/geomstats/datasets/data/hands/labels.txt\"\n\n hands = Matrix(CSV.read(download(hands_url), DataFrame, header=false))\n hands = reshape(hands, size(hands, 1), 3, 22)\n hand_labels = CSV.read(download(hand_labels_url), DataFrame, header=false).Column1\n return hands, hand_labels\nend","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"load_hands (generic function with 1 method)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"The following code plots a sample gesture as a 3D scatter plot of points.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"hands, hand_labels = load_hands()\nscatter3d(hands[1, 1, :], hands[1, 2, :], hands[1, 3, :])","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Each gesture is represented by 22 landmarks in ℝ³, so we use the appropriate Kendall’s shape space","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Mshape = KendallsShapeSpace(3, 22)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"KendallsShapeSpace{3, 22}()","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Hands read from the dataset are projected to the shape space to remove translation and scaling variability. Rotational variability is then handled using the quotient structure of KendallsShapeSpace","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"hands_projected = [project(Mshape, hands[i, :, :]) for i in axes(hands, 1)]","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"In the next part let’s do tangent space PCA. This starts with computing a mean point and computing logithmic maps at mean to each point in the dataset.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"mean_hand = mean(Mshape, hands_projected)\nhand_logs = [log(Mshape, mean_hand, p) for p in hands_projected]","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"For a tangent PCA, we need coordinates in a basis. Some libraries skip this step because the representation of tangent vectors forms a linear subspace of an Euclidean space so PCA automatically detects which directions have no variance but this is a more generic way to solve this issue.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"B = get_basis(Mshape, mean_hand, ProjectedOrthonormalBasis(:svd))\nhand_log_coordinates = [get_coordinates(Mshape, mean_hand, X, B) for X in hand_logs]","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"This code prepares data for MultivariateStats – mean=0 is set because we’ve centered the data geometrically to mean_hand in the code above.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"red_coords = reduce(hcat, hand_log_coordinates)\nfp = fit(PCA, red_coords; mean=0)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"PCA(indim = 59, outdim = 19, principalratio = 0.9912988285103255)\n\nPattern matrix (unstandardized loadings):\n────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n PC1 PC2 PC3 PC4 PC5 PC6 PC7 PC8 PC9 PC10 PC11 PC12 PC13 PC14 PC15 PC16 PC17 PC18 PC19\n────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n1 0.0173855 0.000636845 -0.0161893 -0.0245499 -0.00981021 0.0108967 0.00480455 -0.00160225 0.00965055 0.00308236 -0.00718659 -0.000243068 -0.00278085 0.000614788 -9.15296e-5 -0.000505545 0.00195782 0.00250739 0.000594843\n2 0.00414129 0.000334051 -0.00621444 0.00790698 0.0175519 -0.0097201 -0.00241452 0.00218353 0.00804002 -0.0049976 -0.00514098 0.00217929 -0.000189061 0.00306193 0.0045976 -0.00290717 0.0027132 0.000826467 0.000683271\n3 -0.00278452 0.0327623 -0.00106001 -0.00522848 -0.00599399 0.00897585 0.0109365 0.00154308 -0.00510698 -0.0118133 -0.000394887 -0.00861796 -0.000921745 -0.00186573 0.00624982 -0.00378874 0.00282378 -0.00101771 -0.00286378\n4 0.00227632 -0.0205855 -0.00370886 -0.00918484 -0.00281422 -0.00511051 -0.015321 0.00120702 -0.006792 -0.00168908 8.68548e-6 0.00402992 -0.00324521 0.00280144 0.00255311 -0.00160794 0.000180003 -0.000551923 0.00130734\n5 -0.0049244 0.0121741 -0.0119137 0.0118437 0.00064937 0.0129349 -0.00160643 0.00385634 -0.00686451 0.00113489 -0.000602382 0.000139858 0.00439824 0.000576411 0.00406128 0.000175348 -0.00222317 -0.00454532 0.00239012\n6 0.0022564 0.00405703 -0.0147493 0.00479343 0.00099672 -0.0037997 0.00427197 -0.00492114 -0.00751233 0.00635193 -0.0046186 -0.00386301 -0.000190645 -0.000564171 -0.000725947 0.00416211 0.000130641 0.00255604 -0.00126336\n7 -0.00849223 0.0185022 0.010854 0.0155381 0.00220708 0.000408101 -0.00732174 -0.00679773 0.0012842 0.00746195 -0.00570278 -0.00230826 0.00379148 0.00122698 0.00123253 -0.00166504 0.00307727 0.000367742 0.00210109\n8 0.0364754 0.00356004 0.00864952 -0.00313843 0.0128588 0.000392635 0.000367246 0.00971228 -0.00555784 0.00454216 0.000805735 0.000455146 -0.00178109 -0.0059085 -0.000704806 0.00202109 -0.00231604 -0.00145624 -0.00135686\n9 -0.00642437 0.0193549 -0.011419 0.000886165 0.0166549 0.00515056 -0.000280578 0.00361531 0.00435576 0.00122792 -0.00134617 -0.000851905 -0.0104828 -0.00184189 0.000607793 0.00344577 0.0057421 0.000522023 0.000591562\n10 0.0375757 -0.00015996 0.0407193 0.018211 -0.0211973 0.0109156 0.00528872 -0.00438362 -0.00573709 -0.00167852 0.000278635 -0.0022946 0.00153229 -0.000445404 0.00259449 0.00224609 -0.000574173 0.00274393 0.000188819\n11 0.0277787 0.00780307 -0.0166318 -0.00376651 -0.0083135 -0.00195865 -0.000493546 -0.00024609 -0.00567971 -0.00532441 -0.00212507 0.00602551 0.00386 0.00193343 4.23417e-5 -0.00476551 0.000403882 0.00184378 0.000899672\n12 0.10427 0.0111309 -0.015799 -0.000302332 0.00516824 -0.00532884 -0.0014996 -7.30056e-5 -0.00240161 0.00172376 0.00687669 -0.00625024 -0.00639534 0.00295592 0.00113749 -0.000466109 -0.000286855 0.00130816 -0.00023168\n13 0.0349156 -0.0259781 9.64139e-5 0.00413941 0.00930036 0.0120427 -0.00544059 -0.0130528 0.0092189 0.00781286 0.00541738 0.00122035 0.00472085 -0.00313777 0.00420017 -0.00330501 0.00263946 0.00114665 -0.00191432\n14 0.0406743 -0.0145554 0.00847745 -0.008102 -0.0146731 0.0122504 0.00151511 0.0119469 0.00645629 -0.00484009 0.00357907 0.0022329 0.00315935 -0.00342815 0.00112121 0.000716972 -0.000267723 0.00102893 0.00226669\n15 -0.00930256 -0.0167858 0.00611584 0.024959 -0.00635687 0.00927873 0.00612683 0.0137937 0.00355393 0.00435918 -0.00352841 0.00155106 -0.000587037 0.0032852 -0.00115968 -0.00459812 0.000365738 0.00152501 -0.00220028\n16 -0.00443594 -0.00281474 0.00505291 -0.00342471 0.0178561 -0.00334566 0.00749361 -0.00705821 0.00378162 -0.00416412 -0.00867159 0.0033906 0.00257508 0.00611411 0.00313804 -0.00166894 -0.000486449 -0.000684733 -0.000431136\n17 0.0116867 0.0190841 0.00768291 0.00226264 -0.0023963 -0.0120551 -0.0108479 0.00923083 0.00173054 0.00319921 0.000263058 0.00831246 0.00149357 -0.00341414 0.00165869 -0.000452325 0.00122167 0.000489292 -0.000724031\n18 0.0267767 -0.0159784 0.0133608 -0.0147061 0.0162533 0.00217607 -0.00086192 0.00502474 -0.00327539 0.00389318 0.00760878 0.000559328 0.00246694 0.00188893 0.00119427 -0.00116627 -0.000328369 0.00330999 0.000683408\n19 0.0178674 0.00678508 0.00622795 0.00252456 0.0101081 -0.00520374 -0.00394873 -0.00857975 0.00459688 0.00264695 0.00338812 -0.00368184 -0.00100438 -0.0019011 0.000770851 0.00044916 -0.00450338 0.000428239 -0.00173068\n20 0.0142149 -0.0102457 -0.00720102 -0.00827252 -0.000194544 -0.00904612 0.00656784 -0.00288506 -0.00337141 -0.000904713 0.00562513 0.00267589 0.00346339 -0.00100621 -0.00310453 0.00179422 0.000962525 -0.000278243 0.00176121\n21 -0.0236419 -0.0249401 -0.00224796 -0.00102043 -0.00730152 0.00452086 0.00427695 0.00706512 -0.00260505 0.00724108 0.00013085 -0.000635022 -0.0044843 0.0065385 0.0038201 0.0021496 -0.00239896 -0.00176404 -0.000719906\n22 -0.0321825 -0.00425879 0.0225478 0.0109337 0.0145482 0.0158751 -0.00235927 0.00364776 0.000820952 0.00241549 0.0041401 -0.000768498 -0.00151804 -0.00103051 -0.000977858 0.00102485 0.00302874 -0.00154859 0.000908919\n23 -0.0547437 0.00957327 -0.0296533 -0.00785133 0.0046406 0.0125083 -0.003309 -0.00971159 -0.00520429 0.000105352 0.0123953 0.00298409 -0.00098002 -0.00107685 0.00212605 -0.00222586 -2.45066e-5 0.00179058 -0.00341318\n24 -0.0459331 0.0277414 0.0177563 -0.00757283 -0.00154994 0.00419174 0.000228397 0.0047202 -0.00719053 0.00425062 0.00842774 0.00407616 0.00221613 -0.00192485 0.000413624 -0.00184245 -0.000469158 0.00126403 0.000520384\n25 0.0137253 0.0330938 -0.00259305 -0.0173027 5.76481e-5 0.0133787 -0.00258063 0.00199686 0.00372244 0.00811022 0.000803248 -0.00177067 0.00209383 -0.000529693 0.00128358 -0.0037069 -0.00514658 -0.00184888 -0.000194885\n26 -0.0603615 -0.0119161 0.00882267 0.00514721 0.00529219 -0.0122092 0.00736956 -0.00682808 0.000558328 0.00834601 0.0116706 -0.00351252 -0.00185182 -0.000584981 0.000266096 -0.0040918 0.000738611 -0.000967152 0.00238475\n27 0.0336629 0.0104236 0.0261054 -0.0152452 -0.00252001 -0.00504679 -0.0123813 -0.00272042 0.00297605 -0.00692167 0.00454449 0.00353461 -0.00250126 0.00216841 -0.00364534 0.000924378 -0.00102377 0.000628113 0.000155479\n28 0.0422619 -0.00242415 0.00194491 -0.00269802 -0.00745415 -0.0151133 0.00447106 0.00282524 -0.00353172 0.00314076 0.00584346 -0.0046243 -0.00235677 0.00768856 0.000553617 0.00217504 0.000911649 -0.00247882 -0.000685967\n29 0.00883288 -0.00162966 0.018317 -0.00091465 -0.0117905 -0.0143036 -0.00415359 -0.0102138 -0.00610175 0.00279988 -0.00565156 0.0046463 0.00197636 -0.00129791 0.00400266 -0.00288579 -0.0019277 0.000179645 -0.00116481\n30 -0.0167029 0.00911663 -0.00133306 0.00854662 -0.0196894 -0.00125151 0.00519147 -0.00662994 0.0116743 -0.00286996 0.00369844 -0.00142735 0.00241535 0.00170889 -0.00332472 -0.000731511 6.42406e-5 -0.00392972 -0.00221066\n31 0.0185643 -0.00511788 0.00897978 -0.0059246 0.0069449 0.00488395 -0.0036883 0.000884436 -0.00130671 0.00485091 -0.00602461 -0.00157791 0.000661809 0.00128482 -0.0022535 0.000643781 -0.00137816 0.00138855 0.00177414\n32 0.0318392 -0.0241056 -0.00183089 0.00331854 -0.00112742 0.00427225 0.00690474 -0.0114143 0.0135192 0.00089417 0.00105723 -0.00176937 0.00226368 -0.00349391 -0.000954307 0.00145221 -0.00236592 0.000190196 0.00329855\n33 -0.0323147 0.053425 0.0372678 -0.0105732 0.0132107 -0.00339071 -0.000764724 -0.00172247 0.010934 -0.00426652 0.00350433 -0.00285683 0.00615795 0.00285417 -0.0014361 0.00537323 0.00181549 0.0011817 0.000144893\n34 0.0102755 -0.0254688 0.000576695 -0.0157286 -0.00370359 0.00639325 -0.0100209 -0.00130888 -0.00169533 -0.00640355 -0.00161379 -0.00620737 0.00465267 -0.00542501 0.00221331 0.00467989 -0.000154791 -0.00357667 -0.00174044\n35 -0.0187921 -0.0278792 0.00762221 0.0203661 -0.00522219 -0.00496367 0.0026507 0.00309316 -0.00263494 -0.0023065 0.00230521 -0.0021306 0.00317717 -0.0011341 0.00171337 0.00253469 0.00173667 0.00472356 -0.00325254\n36 -0.0281434 0.00692303 0.0135576 0.0150621 -3.45035e-5 0.00692872 -0.00213414 0.00749015 0.00013037 -0.00161564 0.0014149 0.00355391 -0.00353628 0.00186856 -0.0040984 -0.000762863 -0.00374575 -0.00286227 0.00239549\n37 0.0444518 0.0140451 -0.0177105 0.00747961 0.000690187 0.0143313 -0.00211967 -0.00148993 0.00697546 -0.00192432 0.00286409 0.00458382 -0.000210551 0.00431424 0.000836407 0.00198358 0.000554871 -0.00185297 -0.000933994\n38 0.0427542 0.0198576 -0.00795449 0.0115803 -0.00629815 0.000958173 -0.000670645 0.00184352 -0.0014269 -0.00182662 0.00286294 -0.00191824 0.00346162 -0.00172646 -0.0048974 -0.00372581 0.00120087 0.0019076 0.00402424\n39 0.0229225 -0.00426749 0.0223177 -0.00606517 -0.000464169 -0.00294724 0.0133813 -0.0024651 0.00602226 0.00279229 0.000209127 0.00209029 -0.00436785 -0.00112376 0.00524927 -0.00139411 0.00203064 -0.00387777 0.00210721\n40 0.00340627 -0.002551 0.00468302 0.016922 -0.00087532 0.00381858 -0.00115579 -0.00982067 -0.000953865 -0.0107195 -0.00149229 0.00567459 -0.00950229 -0.00649935 -0.00401252 -0.00142877 6.51574e-5 -0.001418 -0.0007485\n41 -0.00252943 -0.0154656 -0.0185877 -0.00503709 0.0196475 0.000757621 0.0083016 -0.00139321 -0.0122729 -0.00334757 0.000134299 0.0025698 0.00693995 0.000106431 -0.00570021 0.001442 0.00234008 -0.00351234 0.00105664\n42 -0.0197534 -0.0420968 0.00903828 -0.0126781 -0.00700759 0.00315487 0.00215178 -0.00277645 -0.00241088 0.00403162 -0.00370267 -0.00432386 0.00329252 0.00108784 -0.00355877 0.000312319 0.00117976 -0.00111906 -0.00100037\n43 -0.0165414 0.00141539 -0.0137025 0.00235394 0.0100988 -0.00772571 0.0161823 0.0080184 0.0109971 -0.0068699 0.00472434 -0.000858139 0.00166438 0.000621182 0.00347287 -0.00042774 -0.00578248 0.00116141 -0.000969362\n44 0.00327356 0.00732386 -0.0172391 0.00208018 -0.00439327 -0.0129229 -0.00222108 0.0138643 0.00446419 0.000994211 0.0015694 0.00304331 0.00744581 -0.00213839 0.00202703 0.00250179 0.00141239 -0.000133561 -0.00230411\n45 -0.000888326 0.0259359 -0.0130999 0.00421491 0.00342141 0.0144244 0.00336686 -0.00102413 -0.00817201 0.00386964 -0.00406899 0.00163275 0.00427038 -0.000788569 0.00357643 0.00316951 0.000309124 0.00150524 0.00161125\n46 -0.0042722 0.00307551 0.00358086 0.00270541 -0.0161164 -0.00118439 -0.00450004 0.00302117 0.00390437 0.00333273 0.003588 0.00229504 6.91777e-5 0.000371144 0.000325992 0.00111262 0.00341049 -0.00107284 -0.000469154\n47 -0.0272713 0.0117052 0.0030402 0.00528473 -0.000105286 -0.00283541 -0.00784446 0.00565022 0.00170229 0.00394462 -0.00513521 -0.00819901 0.000136608 0.00181311 -0.00200453 -0.00178317 0.00129039 -0.00147405 -0.000814289\n48 -0.0134193 -0.0186634 0.000326505 -0.00455047 -0.00159784 0.00490561 -0.00164247 -0.00449218 0.00307453 0.000120946 0.00248512 0.00924946 0.00107424 0.00620751 0.00352128 0.0032275 0.00195177 -0.00125506 0.00112995\n49 -0.00241856 -0.0212005 0.0255376 -0.0142958 0.0108332 0.00804346 0.00190185 0.00388918 -0.00871033 -0.00484363 0.000815342 -0.000501167 -0.00667201 0.000774967 -6.7004e-5 -0.00134048 2.77396e-5 0.00200935 -0.00124611\n50 0.0186602 -0.0137507 -0.00215632 0.0148877 0.0130769 0.00787733 -0.00673317 0.00375946 0.0104502 0.00157273 -0.0016547 0.00151579 0.000143324 0.00199503 -0.00527869 0.00035693 -0.00175686 0.000878632 -0.00360001\n51 -0.0466559 -0.0141001 -0.00849404 0.00284194 0.00635534 -0.002886 -0.00521712 0.00171564 0.00357409 -0.0056073 -0.00483095 -0.00512542 -0.00101796 -0.00138773 0.00397766 0.000947478 -0.00312091 0.00327453 0.00558783\n52 0.016956 0.0109322 -0.00785692 0.0191416 -0.00204687 0.00622328 -0.00116895 -0.0092148 -0.00570974 -0.00132407 0.00384308 0.00255672 -0.0011175 0.00740385 -0.000415327 0.00502273 -0.00236483 0.00208774 0.000171655\n53 0.0290288 -0.0180278 0.00561411 0.000300885 -0.00347658 0.00636645 0.000726997 0.00533765 -0.000322152 -0.00590684 0.00667851 -0.00364209 0.00171821 0.00474059 0.00310052 -0.00152966 0.00284979 0.000256984 0.00251753\n54 -0.0177287 -0.000415008 -0.0179228 -0.00752319 -0.0143941 -0.00299678 0.0134179 0.00368634 0.00596021 0.00644779 0.00176823 0.00466333 -0.00528731 -0.00497389 -0.00206298 0.00309406 0.00107216 0.00205944 0.00182448\n55 0.0568136 0.00919571 0.0250636 0.00058887 0.0142726 -0.000612628 0.0206662 2.20095e-5 -0.00422504 0.00328228 -0.00575157 0.00741408 0.00125492 -0.00202048 0.00106353 0.000523687 -0.000235755 -0.000703685 -0.00181743\n56 -0.0710828 0.01179 0.0078574 -0.0235474 -0.0129393 0.00685923 0.00325491 -0.003256 0.00267407 -0.000496581 -0.00414493 0.00346954 -0.00180817 0.00410908 -0.000452841 0.000890347 -0.00112818 0.0023644 -0.0011635\n57 -0.00737688 0.0227088 -0.00145208 0.00822139 -0.00305843 -0.00168834 0.0109569 -0.00435245 -0.006992 -0.000592417 0.00111379 -0.00090976 0.0011256 0.00241324 -0.00434676 -0.000758851 0.00038675 0.00101628 0.000880843\n58 0.00230222 0.0190556 -6.60482e-5 0.0108511 -0.00704239 -0.00533839 -0.00472773 -0.00333405 -0.00175351 0.00266828 -0.000361014 0.000837679 -0.00489893 -0.00248396 0.00804991 0.00362131 -0.000867214 -0.00137022 0.00092548\n59 -0.0478689 -0.0216948 0.0024752 0.0145396 0.00704264 -0.00198715 9.93362e-5 0.000922192 -0.00090266 -0.00454114 0.00377277 0.00257683 0.00161294 -0.00247874 0.00418941 0.00181706 -0.000826388 1.92124e-5 0.000363471\n────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n\nImportance of components:\n────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n PC1 PC2 PC3 PC4 PC5 PC6 PC7 PC8 PC9 PC10 PC11 PC12 PC13 PC14 PC15 PC16 PC17 PC18 PC19\n────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\nSS Loadings (Eigenvalues) 0.0572506 0.0191037 0.0120201 0.00706941 0.00554948 0.00374734 0.002738 0.00220153 0.00208836 0.00128335 0.00123065 0.000879446 0.000798525 0.000599247 0.000553266 0.000362632 0.000274384 0.000230071 0.00020263\nVariance explained 0.480209 0.160239 0.100823 0.0592971 0.0465482 0.0314321 0.0229659 0.0184661 0.0175169 0.0107646 0.0103225 0.00737666 0.00669791 0.00502639 0.00464071 0.0030417 0.00230149 0.0019298 0.00169963\nCumulative variance 0.480209 0.640448 0.741271 0.800568 0.847116 0.878549 0.901515 0.919981 0.937497 0.948262 0.958585 0.965961 0.972659 0.977686 0.982326 0.985368 0.987669 0.989599 0.991299\nProportion explained 0.484424 0.161645 0.101708 0.0598176 0.0469567 0.031708 0.0231675 0.0186282 0.0176706 0.0108591 0.0104131 0.00744141 0.0067567 0.00507051 0.00468145 0.0030684 0.00232169 0.00194674 0.00171455\nCumulative proportion 0.484424 0.64607 0.747778 0.807595 0.854552 0.88626 0.909428 0.928056 0.945726 0.956585 0.966999 0.97444 0.981197 0.986267 0.990949 0.994017 0.996339 0.998285 1.0\n────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Now let’s show explained variance of each principal component.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"plot(principalvars(fp), title=\"explained variance\", label=\"Tangent PCA\")","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"The next plot shows how projections on the first two pricipal components look like.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"fig = plot(; title=\"coordinates per gesture of the first two principal components\")\nfor label_num in [0, 1]\n mask = hand_labels .== label_num\n cur_hand_logs = red_coords[:, mask]\n cur_t = MultivariateStats.transform(fp, cur_hand_logs)\n scatter!(fig, cur_t[1, :], cur_t[2, :], label=\"gesture \" * string(label_num))\nend\nxlabel!(fig, \"principal component 1\")\nylabel!(fig, \"principal component 2\")\nfig","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"The following heatmap displays pairwise distances between gestures. We can use them for clustering, classification, etc.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"hand_distances = [\n distance(Mshape, hands_projected[i], hands_projected[j]) for\n i in eachindex(hands_projected), j in eachindex(hands_projected)\n]\nheatmap(hand_distances, aspect_ratio=:equal)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"features/statistics.html#Statistics","page":"Statistics","title":"Statistics","text":"","category":"section"},{"location":"features/statistics.html","page":"Statistics","title":"Statistics","text":"Modules = [Manifolds,ManifoldsBase]\nPages = [\"statistics.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/statistics.html#Manifolds.AbstractEstimationMethod","page":"Statistics","title":"Manifolds.AbstractEstimationMethod","text":"AbstractEstimationMethod\n\nAbstract type for defining statistical estimation methods.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.CyclicProximalPointEstimation","page":"Statistics","title":"Manifolds.CyclicProximalPointEstimation","text":"CyclicProximalPointEstimation <: AbstractEstimationMethod\n\nMethod for estimation using the cyclic proximal point technique.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.ExtrinsicEstimation","page":"Statistics","title":"Manifolds.ExtrinsicEstimation","text":"ExtrinsicEstimation <: AbstractEstimationMethod\n\nMethod for estimation in the ambient space and projecting to the manifold.\n\nFor mean estimation, GeodesicInterpolation is used for mean estimation in the ambient space.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.GeodesicInterpolation","page":"Statistics","title":"Manifolds.GeodesicInterpolation","text":"GeodesicInterpolation <: AbstractEstimationMethod\n\nRepeated weighted geodesic interpolation method for estimating the Riemannian center of mass.\n\nThe algorithm proceeds with the following simple online update:\n\nbeginaligned\nμ_1 = x_1\nt_k = fracw_ksum_i=1^k w_i\nμ_k = γ_μ_k-1(x_k t_k)\nendaligned\n\nwhere x_k are points, w_k are weights, μ_k is the kth estimate of the mean, and γ_x(y t) is the point at time t along the shortest_geodesic between points xy mathcal M. The algorithm terminates when all x_k have been considered. In the Euclidean case, this exactly computes the weighted mean.\n\nThe algorithm has been shown to converge asymptotically with the sample size for the following manifolds equipped with their default metrics when all sampled points are in an open geodesic ball about the mean with corresponding radius (see GeodesicInterpolationWithinRadius):\n\nAll simply connected complete Riemannian manifolds with non-positive sectional curvature at radius [Cheng2016], in particular:\nEuclidean\nSymmetricPositiveDefinite [Ho2013]\nOther manifolds:\nSphere: fracπ2 [Salehian2015]\nGrassmann: fracπ4 [Chakraborty2015]\nStiefel/Rotations: fracπ2 sqrt 2 [Chakraborty2019]\n\nFor online variance computation, the algorithm additionally uses an analogous recursion to the weighted Welford algorithm [West1979].\n\n[Ho2013]: Ho J.; Cheng G.; Salehian H.; Vemuri B. C.; Recursive Karcher expectation estimators and geometric law of large numbers. Proceedings of the 16th International Conference on Artificial Intelligence and Statistics (2013), pp. 325–332. pdf.\n\n[Salehian2015]: Salehian H.; Chakraborty R.; Ofori E.; Vaillancourt D.; An efficient recursive estimator of the Fréchet mean on a hypersphere with applications to Medical Image Analysis. Mathematical Foundations of Computational Anatomy (2015). pdf.\n\n[Chakraborty2015]: Chakraborty R.; Vemuri B. C.; Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. Proceedings of the IEEE International Conference on Computer Vision (ICCV) (2015), pp. 4229-4237. doi: 10.1109/ICCV.2015.481, link.\n\n[Cheng2016]: Cheng G.; Ho J.; Salehian H.; Vemuri B. C.; Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. Riemannian Computing in Computer Vision. Springer, Cham (2016), pp. 21-43. doi: 10.1007/978-3-319-22957-7_2, pdf.\n\n[Chakraborty2019]: Chakraborty R.; Vemuri B. C.; Statistics on the (compact) Stiefel manifold: Theory and Applications. The Annals of Statistics (2019), 47(1), pp. 415-438. doi: 10.1214/18-AOS1692, arxiv: 1708.00045.\n\n[West1979]: West D. H. D.; Updating Mean and Variance Estimates: An Improved Method. Communications of the ACM (1979), 22(9), pp. 532–535. doi: 10.1145/359146.359153.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.GeodesicInterpolationWithinRadius","page":"Statistics","title":"Manifolds.GeodesicInterpolationWithinRadius","text":"GeodesicInterpolationWithinRadius{T} <: AbstractEstimationMethod\n\nEstimation of Riemannian center of mass using GeodesicInterpolation with fallback to GradientDescentEstimation if any points are outside of a geodesic ball of specified radius around the mean.\n\nConstructor\n\nGeodesicInterpolationWithinRadius(radius)\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.GradientDescentEstimation","page":"Statistics","title":"Manifolds.GradientDescentEstimation","text":"GradientDescentEstimation <: AbstractEstimationMethod\n\nMethod for estimation using gradient descent.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.WeiszfeldEstimation","page":"Statistics","title":"Manifolds.WeiszfeldEstimation","text":"WeiszfeldEstimation <: AbstractEstimationMethod\n\nMethod for estimation using the Weiszfeld algorithm for the median\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.default_estimation_method-Tuple{AbstractManifold, Any}","page":"Statistics","title":"Manifolds.default_estimation_method","text":"default_estimation_method(M::AbstractManifold, f)\n\nSpecify a default AbstractEstimationMethod for an AbstractManifold for a function f, e.g. the median or the mean.\n\nNote that his function is decorated, so it can inherit from the embedding, for example for the IsEmbeddedSubmanifold trait.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.cov-Tuple{AbstractManifold, AbstractVector}","page":"Statistics","title":"Statistics.cov","text":"Statistics.cov(\n M::AbstractManifold,\n x::AbstractVector;\n basis::AbstractBasis=DefaultOrthonormalBasis(),\n tangent_space_covariance_estimator::CovarianceEstimator=SimpleCovariance(;\n corrected=true,\n ),\n mean_estimation_method::AbstractEstimationMethod=GradientDescentEstimation(),\n inverse_retraction_method::AbstractInverseRetractionMethod=default_inverse_retraction_method(\n M, eltype(x),\n ),\n)\n\nEstimate the covariance matrix of a set of points x on manifold M. Since the covariance matrix on a manifold is a rank 2 tensor, the function returns its coefficients in basis induced by the given tangent space basis. See Section 5 of [Pennec2006] for details.\n\nThe mean is calculated using the specified mean_estimation_method using [mean](@ref Statistics.mean(::AbstractManifold, ::AbstractVector, ::AbstractEstimationMethod), and tangent vectors at this mean are calculated using the provided inverse_retraction_method. Finally, the covariance matrix in the tangent plane is estimated using the Euclidean space estimator tangent_space_covariance_estimator. The type CovarianceEstimator is defined in StatsBase.jl and examples of covariance estimation methods can be found in CovarianceEstimation.jl.\n\n[Pennec2006]: X. Pennec, “Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements,” J Math Imaging Vis, vol. 25, no. 1, p. 127, Jul. 2006, doi: 10.1007/s10851-006-6228-4.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean!-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.mean!","text":"mean!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)\nmean!(\n M::AbstractManifold,\n y,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n)\n\nCompute the mean in-place in y.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, AbstractVector, AbstractVector, ExtrinsicEstimation}","page":"Statistics","title":"Statistics.mean","text":"mean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::ExtrinsicEstimation;\n kwargs...,\n)\n\nEstimate the Riemannian center of mass of x using ExtrinsicEstimation, i.e. by computing the mean in the embedding and projecting the result back. You can specify an extrinsic_method to specify which mean estimation method to use in the embedding, which defaults to GeodesicInterpolation.\n\nSee mean for a description of the remaining kwargs.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, AbstractVector, AbstractVector, GeodesicInterpolationWithinRadius}","page":"Statistics","title":"Statistics.mean","text":"mean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::GeodesicInterpolationWithinRadius;\n kwargs...,\n)\n\nEstimate the Riemannian center of mass of x using GeodesicInterpolationWithinRadius.\n\nSee mean for a description of kwargs.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, AbstractVector, AbstractVector, GeodesicInterpolation}","page":"Statistics","title":"Statistics.mean","text":"mean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::GeodesicInterpolation;\n shuffle_rng=nothing,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),\n kwargs...,\n)\n\nEstimate the Riemannian center of mass of x in an online fashion using repeated weighted geodesic interpolation. See GeodesicInterpolation for details.\n\nIf shuffle_rng is provided, it is used to shuffle the order in which the points are considered for computing the mean.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.mean","text":"mean(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)\n\nCompute the (optionally weighted) Riemannian center of mass also known as Karcher mean of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer\n\nargmin_y mathcal M frac12 sum_i=1^n w_i sum_i=1^n w_imathrmd_mathcal M^2(yx_i)\n\nwhere mathrmd_mathcal M denotes the Riemannian distance.\n\nIn the general case, the GradientDescentEstimation is used to compute the mean. mean( M::AbstractManifold, x::AbstractVector, [w::AbstractWeights,] method::AbstractEstimationMethod=defaultestimationmethod(M); kwargs..., )\n\nCompute the mean using the specified method.\n\nmean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::GradientDescentEstimation;\n p0=x[1],\n stop_iter=100,\n retraction::AbstractRetractionMethod = default_retraction_method(M),\n inverse_retraction::AbstractInverseRetractionMethod = default_retraction_method(M, eltype(x)),\n kwargs...,\n)\n\nCompute the mean using the gradient descent scheme GradientDescentEstimation.\n\nOptionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\nThe Theory stems from[Karcher1977] and is also described in[PennecArsigny2013] as the exponential barycenter. The algorithm is further described in[Afsari2013].\n\n[Afsari2013]: Afsari, B; Tron, R.; Vidal, R.: On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass, SIAM Journal on Control and Optimization (2013), 51(3), pp. 2230–2260, doi: 10.1137/12086282X, arxiv: 1201.0925\n\n[PennecArsigny2013]: Pennec X., Arsigny V.: Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Nielsen F., Bhatia R. (eds) Matrix Information Geometry, (2013), pp. 123-166. doi: 10.1007/978-3-642-30232-9_7, hal: https://hal.inria.fr/hal-00699361/document\n\n[Karcher1977]: Karcher, H.: Riemannian center of mass and mollifier smoothing. Communications on Pure Applied Mathematics (1977), 30, pp. 509–541. doi 10.1002/cpa.3160300502\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median!-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.median!","text":"median!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)\nmedian!(\n M::AbstractManifold,\n y,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n)\n\ncomputes the median in-place in y.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, AbstractVector, AbstractVector, CyclicProximalPointEstimation}","page":"Statistics","title":"Statistics.median","text":"median(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::CyclicProximalPointEstimation;\n p0=x[1],\n stop_iter=1000000,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x),),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x),),\n kwargs...,\n)\n\nCompute the median using CyclicProximalPointEstimation.\n\nOptionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\nThe algorithm is further described in [Bačák2014].\n\n[Bačák2014]: Bačák, M: Computing Medians and Means in Hadamard Spaces. SIAM Journal on Optimization (2014), 24(3), pp. 1542–1566, doi: 10.1137/140953393, arxiv: 1210.2145\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, AbstractVector, AbstractVector, ExtrinsicEstimation}","page":"Statistics","title":"Statistics.median","text":"median(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::ExtrinsicEstimation;\n extrinsic_method = CyclicProximalPointEstimation(),\n kwargs...,\n)\n\nEstimate the median of x using ExtrinsicEstimation, i.e. by computing the median in the embedding and projecting the result back. You can specify an extrinsic_method to specify which median estimation method to use in the embedding, which defaults to CyclicProximalPointEstimation.\n\nSee median for a description of kwargs.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, AbstractVector, AbstractVector, Manifolds.WeiszfeldEstimation}","page":"Statistics","title":"Statistics.median","text":"median(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::WeiszfeldEstimation;\n α = 1.0,\n p0=x[1],\n stop_iter=2000,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),\n kwargs...,\n)\n\nCompute the median using WeiszfeldEstimation.\n\nOptionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.\n\nThe parameter αin (02 is a step size.\n\nThe algorithm is further described in [FletcherVenkatasubramanianJoshi2008], especially the update rule in Eq. (6), i.e. Let q_k denote the current iterate, n the number of points x_1ldotsx_n, and\n\nI_k = bigl i in 1ldotsn big x_i neq q_k bigr\n\nall indices of points that are not equal to the current iterate. Then the update reads q_k+1 = exp_q_k(αX), where\n\nX = frac1ssum_iin I_k fracw_id_mathcal M(q_kx_i)log_q_kx_i\nquad\ntext with \nquad\ns = sum_iin I_k fracw_id_mathcal M(q_kx_i)\n\nand where mathrmd_mathcal M denotes the Riemannian distance.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction, which by default use the exponential and logarithmic map, respectively.\n\n[FletcherVenkatasubramanianJoshi2008]: Fletcher, T., Venkatasubramanian, S., Joshi, S: Robust statistics on Riemannian manifolds via the geometric median 2008 IEEE Conference on Computer Vision and Pattern Recognition, doi: 10.1109/CVPR.2008.4587747,\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.median","text":"median(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)\nmedian(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n)\n\nCompute the (optionally weighted) Riemannian median of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer\n\nargmin_y mathcal M frac1sum_i=1^n w_i sum_i=1^n w_imathrmd_mathcal M(yx_i)\n\nwhere mathrmd_mathcal M denotes the Riemannian distance. This function is nonsmooth (i.e nondifferentiable).\n\nIn the general case, the CyclicProximalPointEstimation is used to compute the median. However, this default may be overloaded for specific manifolds.\n\nCompute the median using the specified method.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.std-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.std","text":"std(M, x, m=mean(M, x); corrected=true, kwargs...)\nstd(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false, kwargs...)\n\ncompute the optionally weighted standard deviation of a Vector x of n data points on the AbstractManifold M, i.e.\n\nsqrtfrac1c sum_i=1^n w_i d_mathcal M^2 (x_im)\n\nwhere c is a correction term, see Statistics.std. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.var-Tuple{AbstractManifold, Any}","page":"Statistics","title":"Statistics.var","text":"var(M, x, m=mean(M, x); corrected=true)\nvar(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false)\n\ncompute the (optionally weighted) variance of a Vector x of n data points on the AbstractManifold M, i.e.\n\nfrac1c sum_i=1^n w_i d_mathcal M^2 (x_im)\n\nwhere c is a correction term, see Statistics.var. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true. All further kwargs... are passed to the computation of the mean (if that is not provided).\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.kurtosis-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights}","page":"Statistics","title":"StatsBase.kurtosis","text":"kurtosis(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))\n\nCompute the excess kurtosis of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_std-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"StatsBase.mean_and_std","text":"mean_and_std(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, std)\n\nCompute the mean and the standard deviation std simultaneously.\n\nmean_and_std(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n) -> (mean, var)\n\nUse the method for simultaneously computing the mean and standard deviation. To use a mean-specific method, call mean and then std.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_var-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights, GeodesicInterpolationWithinRadius}","page":"Statistics","title":"StatsBase.mean_and_var","text":"mean_and_var(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::GeodesicInterpolationWithinRadius;\n kwargs...,\n) -> (mean, var)\n\nUse repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.\n\nSee GeodesicInterpolationWithinRadius and mean_and_var for more information.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_var-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights, GeodesicInterpolation}","page":"Statistics","title":"StatsBase.mean_and_var","text":"mean_and_var(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::GeodesicInterpolation;\n shuffle_rng::Union{AbstractRNG,Nothing} = nothing,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),\n kwargs...,\n) -> (mean, var)\n\nUse the repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.\n\nIf shuffle_rng is provided, it is used to shuffle the order in which the points are considered. Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\nSee GeodesicInterpolation for details on the geodesic interpolation method.\n\nnote: Note\nThe Welford algorithm for the variance is experimental and is not guaranteed to give accurate results except on Euclidean.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_var-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"StatsBase.mean_and_var","text":"mean_and_var(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, var)\n\nCompute the mean and the variance simultaneously. See those functions for a description of the arguments.\n\nmean_and_var(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n) -> (mean, var)\n\nUse the method for simultaneously computing the mean and variance. To use a mean-specific method, call mean and then var.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.moment","page":"Statistics","title":"StatsBase.moment","text":"moment(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))\n\nCompute the kth central moment of points in x on manifold M. Optionally provide weights w and/or a precomputed mean.\n\n\n\n\n\n","category":"function"},{"location":"features/statistics.html#StatsBase.skewness-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights}","page":"Statistics","title":"StatsBase.skewness","text":"skewness(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))\n\nCompute the standardized skewness of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Literature","page":"Statistics","title":"Literature","text":"","category":"section"},{"location":"manifolds/spectrahedron.html#Spectrahedron","page":"Spectrahedron","title":"Spectrahedron","text":"","category":"section"},{"location":"manifolds/spectrahedron.html","page":"Spectrahedron","title":"Spectrahedron","text":"Modules = [Manifolds]\nPages = [\"manifolds/Spectrahedron.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/spectrahedron.html#Manifolds.Spectrahedron","page":"Spectrahedron","title":"Manifolds.Spectrahedron","text":"Spectrahedron{N,K} <: AbstractDecoratorManifold{ℝ}\n\nThe Spectrahedron manifold, also known as the set of correlation matrices (symmetric positive semidefinite matrices) of rank k with unit trace.\n\nbeginaligned\nmathcal S(nk) =\nbiglp ℝ^n n big a^mathrmTpa geq 0 text for all a ℝ^n\noperatornametr(p) = sum_i=1^n p_ii = 1\ntextand p = qq^mathrmT text for q in ℝ^n k\ntext with operatornamerank(p) = operatornamerank(q) = k\nbigr\nendaligned\n\nThis manifold is working solely on the matrices q. Note that this q is not unique, indeed for any orthogonal matrix A we have (qA)(qA)^mathrmT = qq^mathrmT = p, so the manifold implemented here is the quotient manifold. The unit trace translates to unit frobenius norm of q.\n\nThe tangent space at p, denoted T_pmathcal E(nk), is also represented by matrices Yin ℝ^n k and reads as\n\nT_pmathcal S(nk) = bigl\nX ℝ^n nX = qY^mathrmT + Yq^mathrmT\ntext with operatornametr(X) = sum_i=1^nX_ii = 0\nbigr\n\nendowed with the Euclidean metric from the embedding, i.e. from the ℝ^n k\n\nThis manifold was for example investigated in[JourneeBachAbsilSepulchre2010].\n\nConstructor\n\nSpectrahedron(n,k)\n\ngenerates the manifold mathcal S(nk) subset ℝ^n n.\n\n[JourneeBachAbsilSepulchre2010]: Journée, M., Bach, F., Absil, P.-A., and Sepulchre, R.: “Low-Rank Optimization on the Cone of Positive Semidefinite Matrices”, SIAM Journal on Optimization (20)5, pp. 2327–2351, 2010. doi: 10.1137/080731359, arXiv: 0807.4423.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.check_point-Union{Tuple{K}, Tuple{N}, Tuple{Spectrahedron{N, K}, Any}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.check_point","text":"check_point(M::Spectrahedron, q; kwargs...)\n\nchecks, whether q is a valid reprsentation of a point p=qq^mathrmT on the Spectrahedron M, i.e. is a matrix of size (N,K), such that p is symmetric positive semidefinite and has unit trace, i.e. q has to have unit frobenius norm. Since by construction p is symmetric, this is not explicitly checked. Since p is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.check_vector-Union{Tuple{K}, Tuple{N}, Tuple{Spectrahedron{N, K}, Any, Any}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.check_vector","text":"check_vector(M::Spectrahedron, q, Y; kwargs...)\n\nCheck whether X = qY^mathrmT + Yq^mathrmT is a tangent vector to p=qq^mathrmT on the Spectrahedron M, i.e. atfer check_point of q, Y has to be of same dimension as q and a X has to be a symmetric matrix with trace. The tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetry of X holds by construction and is not explicitly checked.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.is_flat-Tuple{Spectrahedron}","page":"Spectrahedron","title":"ManifoldsBase.is_flat","text":"is_flat(::Spectrahedron)\n\nReturn false. Spectrahedron is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.manifold_dimension-Union{Tuple{Spectrahedron{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Spectrahedron)\n\nreturns the dimension of Spectrahedron M=mathcal S(nk) nk ℕ, i.e.\n\ndim mathcal S(nk) = nk - 1 - frack(k-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.project-Tuple{Spectrahedron, Any}","page":"Spectrahedron","title":"ManifoldsBase.project","text":"project(M::Spectrahedron, q)\n\nproject q onto the manifold Spectrahedron M, by normalizing w.r.t. the Frobenius norm\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.project-Tuple{Spectrahedron, Vararg{Any}}","page":"Spectrahedron","title":"ManifoldsBase.project","text":"project(M::Spectrahedron, q, Y)\n\nProject Y onto the tangent space at q, i.e. row-wise onto the Spectrahedron manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.representation_size-Union{Tuple{Spectrahedron{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.representation_size","text":"representation_size(M::Spectrahedron)\n\nReturn the size of an array representing an element on the Spectrahedron manifold M, i.e. n k, the size of such factor of p=qq^mathrmT on mathcal M = mathcal S(nk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.retract-Tuple{Spectrahedron, Any, Any, ProjectionRetraction}","page":"Spectrahedron","title":"ManifoldsBase.retract","text":"retract(M::Spectrahedron, q, Y, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting q+Y back onto the manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.vector_transport_to-Tuple{Spectrahedron, Any, Any, Any, ProjectionTransport}","page":"Spectrahedron","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Spectrahedron, p, X, q)\n\ntransport the tangent vector X at p to q by projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.zero_vector-Tuple{Spectrahedron, Vararg{Any}}","page":"Spectrahedron","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Spectrahedron,p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the Spectrahedron manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#Literature","page":"Spectrahedron","title":"Literature","text":"","category":"section"},{"location":"manifolds/choleskyspace.html#Cholesky-space","page":"Cholesky space","title":"Cholesky space","text":"","category":"section"},{"location":"manifolds/choleskyspace.html","page":"Cholesky space","title":"Cholesky space","text":"The Cholesky space is a Riemannian manifold on the lower triangular matrices. Its metric is based on the cholesky decomposition. The CholeskySpace is used to define the LogCholeskyMetric on the manifold of SymmetricPositiveDefinite matrices.","category":"page"},{"location":"manifolds/choleskyspace.html","page":"Cholesky space","title":"Cholesky space","text":"Modules = [Manifolds]\nPages = [\"manifolds/CholeskySpace.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/choleskyspace.html#Manifolds.CholeskySpace","page":"Cholesky space","title":"Manifolds.CholeskySpace","text":"CholeskySpace{N} <: AbstractManifold{ℝ}\n\nThe manifold of lower triangular matrices with positive diagonal and a metric based on the cholesky decomposition. The formulae for this manifold are for example summarized in Table 1 of [Lin2019].\n\nConstructor\n\nCholeskySpace(n)\n\nGenerate the manifold of n n lower triangular matrices with positive diagonal.\n\n[Lin2019]: Lin, Zenhua: Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition, arXiv: 1908.09326.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/choleskyspace.html","page":"Cholesky space","title":"Cholesky space","text":"Modules = [Manifolds]\nPages = [\"manifolds/CholeskySpace.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/choleskyspace.html#Base.exp-Tuple{CholeskySpace, Vararg{Any}}","page":"Cholesky space","title":"Base.exp","text":"exp(M::CholeskySpace, p, X)\n\nCompute the exponential map on the CholeskySpace M emanating from the lower triangular matrix with positive diagonal p towards the lower triangular matrix X The formula reads\n\nexp_p X = p + X + operatornamediag(p)\noperatornamediag(p)expbigl( operatornamediag(X)operatornamediag(p)^-1bigr)\n\nwhere cdot denotes the strictly lower triangular matrix, and operatornamediag extracts the diagonal matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#Base.log-Tuple{LinearAlgebra.Cholesky, Vararg{Any}}","page":"Cholesky space","title":"Base.log","text":"log(M::CholeskySpace, X, p, q)\n\nCompute the logarithmic map on the CholeskySpace M for the geodesic emanating from the lower triangular matrix with positive diagonal p towards q. The formula reads\n\nlog_p q = p - q + operatornamediag(p)logbigl(operatornamediag(q)operatornamediag(p)^-1bigr)\n\nwhere cdot denotes the strictly lower triangular matrix, and operatornamediag extracts the diagonal matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.check_point-Tuple{CholeskySpace, Any}","page":"Cholesky space","title":"ManifoldsBase.check_point","text":"check_point(M::CholeskySpace, p; kwargs...)\n\nCheck whether the matrix p lies on the CholeskySpace M, i.e. it's size fits the manifold, it is a lower triangular matrix and has positive entries on the diagonal. The tolerance for the tests can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.check_vector-Tuple{CholeskySpace, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.check_vector","text":"check_vector(M::CholeskySpace, p, X; kwargs... )\n\nCheck whether v is a tangent vector to p on the CholeskySpace M, i.e. after check_point(M,p), X has to have the same dimension as p and a symmetric matrix. The tolerance for the tests can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.distance-Tuple{CholeskySpace, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.distance","text":"distance(M::CholeskySpace, p, q)\n\nCompute the Riemannian distance on the CholeskySpace M between two matrices p, q that are lower triangular with positive diagonal. The formula reads\n\nd_mathcal M(pq) = sqrtsum_ij (p_ij-q_ij)^2 +\nsum_j=1^m (log p_jj - log q_jj)^2\n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.inner-Tuple{CholeskySpace, Any, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.inner","text":"inner(M::CholeskySpace, p, X, Y)\n\nCompute the inner product on the CholeskySpace M at the lower triangular matric with positive diagonal p and the two tangent vectors X,Y, i.e they are both lower triangular matrices with arbitrary diagonal. The formula reads\n\ng_p(XY) = sum_ij X_ijY_ij + sum_j=1^m X_iiY_iip_ii^-2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.is_flat-Tuple{CholeskySpace}","page":"Cholesky space","title":"ManifoldsBase.is_flat","text":"is_flat(::CholeskySpace)\n\nReturn false. CholeskySpace is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.manifold_dimension-Union{Tuple{CholeskySpace{N}}, Tuple{N}} where N","page":"Cholesky space","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::CholeskySpace)\n\nReturn the manifold dimension for the CholeskySpace M, i.e.\n\n dim(mathcal M) = fracN(N+1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.parallel_transport_to-Tuple{CholeskySpace, Any, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::CholeskySpace, p, X, q)\n\nParallely transport the tangent vector X at p along the geodesic to q on the CholeskySpace manifold M. The formula reads\n\nmathcal P_qp(X) = X \n+ operatornamediag(q)operatornamediag(p)^-1operatornamediag(X)\n\nwhere cdot denotes the strictly lower triangular matrix, and operatornamediag extracts the diagonal matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.representation_size-Union{Tuple{CholeskySpace{N}}, Tuple{N}} where N","page":"Cholesky space","title":"ManifoldsBase.representation_size","text":"representation_size(M::CholeskySpace)\n\nReturn the representation size for the CholeskySpace{N} M, i.e. (N,N).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.zero_vector-Tuple{CholeskySpace, Vararg{Any}}","page":"Cholesky space","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::CholeskySpace, p)\n\nReturn the zero tangent vector on the CholeskySpace M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#Literature","page":"Cholesky space","title":"Literature","text":"","category":"section"},{"location":"features/utilities.html#Ease-of-notation","page":"Utilities","title":"Ease of notation","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"The following terms introduce a nicer notation for some operations, for example using the ∈ operator, p mathcal M, to determine whether p is a point on the AbstractManifold mathcal M.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"in\nTangentSpace","category":"page"},{"location":"features/utilities.html#Base.in","page":"Utilities","title":"Base.in","text":"Base.in(p, M::AbstractManifold; kwargs...)\np ∈ M\n\nCheck, whether a point p is a valid point (i.e. in) a AbstractManifold M. This method employs is_point deactivating the error throwing option.\n\n\n\n\n\nBase.in(p, TpM::TangentSpaceAtPoint; kwargs...)\nX ∈ TangentSpaceAtPoint(M,p)\n\nCheck whether X is a tangent vector from (in) the tangent space T_pmathcal M, i.e. the TangentSpaceAtPoint at p on the AbstractManifold M. This method uses is_vector deactivating the error throw option.\n\n\n\n\n\n","category":"function"},{"location":"features/utilities.html#ManifoldsBase.TangentSpace","page":"Utilities","title":"ManifoldsBase.TangentSpace","text":"TangentSpace(M::AbstractManifold, p)\n\nReturn a TangentSpaceAtPoint representing tangent space at p on the AbstractManifold M.\n\n\n\n\n\n","category":"constant"},{"location":"features/utilities.html#Fallback-for-the-exponential-map:-Solving-the-corresponding-ODE","page":"Utilities","title":"Fallback for the exponential map: Solving the corresponding ODE","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"When additionally loading NLSolve.jl the following fallback for the exponential map is available.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"Modules = [Manifolds]\nPages = [\"nlsolve.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/utilities.html#Public-documentation","page":"Utilities","title":"Public documentation","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"The following functions are of interest for extending and using the ProductManifold.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"submanifold_component\nsubmanifold_components\nProductRepr","category":"page"},{"location":"features/utilities.html#Manifolds.submanifold_component","page":"Utilities","title":"Manifolds.submanifold_component","text":"submanifold_component(M::AbstractManifold, p, i::Integer)\nsubmanifold_component(M::AbstractManifold, p, ::Val(i)) where {i}\nsubmanifold_component(p, i::Integer)\nsubmanifold_component(p, ::Val(i)) where {i}\n\nProject the product array p on M to its ith component. A new array is returned.\n\n\n\n\n\n","category":"function"},{"location":"features/utilities.html#Manifolds.submanifold_components","page":"Utilities","title":"Manifolds.submanifold_components","text":"submanifold_components(M::AbstractManifold, p)\nsubmanifold_components(p)\n\nGet the projected components of p on the submanifolds of M. The components are returned in a Tuple.\n\n\n\n\n\n","category":"function"},{"location":"features/utilities.html#Manifolds.ProductRepr","page":"Utilities","title":"Manifolds.ProductRepr","text":"ProductRepr(parts)\n\nA more general but slower representation of points and tangent vectors on a product manifold.\n\nExample:\n\nA product point on a product manifold Sphere(2) × Euclidean(2) might be created as\n\nProductRepr([1.0, 0.0, 0.0], [2.0, 3.0])\n\nwhere [1.0, 0.0, 0.0] is the part corresponding to the sphere factor and [2.0, 3.0] is the part corresponding to the euclidean manifold.\n\nwarning: Warning\nProductRepr is deprecated and will be removed in a future release. Please use ArrayPartition instead.\n\n\n\n\n\n","category":"type"},{"location":"features/utilities.html#Specific-exception-types","page":"Utilities","title":"Specific exception types","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"For some manifolds it is useful to keep an extra index, at which point on the manifold, the error occurred as well as to collect all errors that occurred on a manifold. This page contains the manifold-specific error messages this package introduces.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"Modules = [Manifolds]\nPages = [\"errors.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/oblique.html#Oblique-manifold","page":"Oblique manifold","title":"Oblique manifold","text":"","category":"section"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"The oblique manifold mathcalOB(nm) is modeled as an AbstractPowerManifold of the (real-valued) Sphere and uses ArrayPowerRepresentation. Points on the torus are hence matrices, x ℝ^nm.","category":"page"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/Oblique.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/oblique.html#Manifolds.Oblique","page":"Oblique manifold","title":"Manifolds.Oblique","text":"Oblique{N,M,𝔽} <: AbstractPowerManifold{𝔽}\n\nThe oblique manifold mathcalOB(nm) is the set of 𝔽-valued matrices with unit norm column endowed with the metric from the embedding. This yields exactly the same metric as considering the product metric of the unit norm vectors, i.e. PowerManifold of the (n-1)-dimensional Sphere.\n\nThe Sphere is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.\n\nConstructor\n\nOblique(n,m)\n\nGenerate the manifold of matrices mathbb R^n m such that the m columns are unit vectors, i.e. from the Sphere(n-1).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/oblique.html#Functions","page":"Oblique manifold","title":"Functions","text":"","category":"section"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:","category":"page"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/Oblique.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/oblique.html#ManifoldsBase.check_point-Tuple{Oblique, Any}","page":"Oblique manifold","title":"ManifoldsBase.check_point","text":"check_point(M::Oblique{n,m},p)\n\nChecks whether p is a valid point on the Oblique{m,n} M, i.e. is a matrix of m unit columns from mathbb R^n, i.e. each column is a point from Sphere(n-1).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/oblique.html#ManifoldsBase.check_vector-Union{Tuple{m}, Tuple{n}, Tuple{Oblique{n, m}, Any, Any}} where {n, m}","page":"Oblique manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::Oblique p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the Oblique M. This means, that p is valid, that X is of correct dimension and columnswise a tangent vector to the columns of p on the Sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/oblique.html#ManifoldsBase.parallel_transport_to-Tuple{Oblique, Any, Any, Any}","page":"Oblique manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::Oblique, p, X, q)\n\nCompute the parallel transport on the Oblique manifold by doing a column wise parallel transport on the Sphere\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Orthogonal-and-Unitary-matrices","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary matrices","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Both OrthogonalMatrices and UnitaryMatrices are quite similar, as are Rotations, as well as unitary matrices with determinant equal to one. So these share a {common implementation}(@ref generalunitarymatrices)","category":"page"},{"location":"manifolds/generalunitary.html#Orthogonal-Matrices","page":"Orthogonal and Unitary Matrices","title":"Orthogonal Matrices","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Orthogonal.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/generalunitary.html#Manifolds.OrthogonalMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.OrthogonalMatrices","text":" OrthogonalMatrices{n} = GeneralUnitaryMatrices{n,ℝ,AbsoluteDeterminantOneMatrices}\n\nThe manifold of (real) orthogonal matrices mathrmO(n).\n\nOrthogonalMatrices(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Unitary-Matrices","page":"Orthogonal and Unitary Matrices","title":"Unitary Matrices","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Unitary.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/generalunitary.html#Manifolds.UnitaryMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.UnitaryMatrices","text":"const UnitaryMatrices{n,𝔽} = AbstarctUnitaryMatrices{n,𝔽,AbsoluteDeterminantOneMatrices}\n\nThe manifold U(n𝔽) of nn complex matrices (when 𝔽=ℂ) or quaternionic matrices (when 𝔽=ℍ) such that\n\np^mathrmHp = mathrmI_n\n\nwhere mathrmI_n is the nn identity matrix. Such matrices p have a property that lVert det(p) rVert = 1.\n\nThe tangent spaces are given by\n\n T_pU(n) coloneqq bigl\n X big pY text where Y text is skew symmetric i e Y = -Y^mathrmH\n bigr\n\nBut note that tangent vectors are represented in the Lie algebra, i.e. just using Y in the representation above.\n\nConstructor\n\nUnitaryMatrices(n, 𝔽::AbstractNumbers=ℂ)\n\nsee also OrthogonalMatrices for the real valued case.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{UnitaryMatrices{n, ℂ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::UnitaryMatrices{n,ℂ}) where {n}\n\nReturn the dimension of the manifold unitary matrices.\n\ndim_mathrmU(n) = n^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{UnitaryMatrices{n, ℍ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::UnitaryMatrices{n,ℍ})\n\nReturn the dimension of the manifold unitary matrices.\n\ndim_mathrmU(n ℍ) = n(2n+1)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#generalunitarymatrices","page":"Orthogonal and Unitary Matrices","title":"Common functions","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/GeneralUnitaryMatrices.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/generalunitary.html#Manifolds.AbsoluteDeterminantOneMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.AbsoluteDeterminantOneMatrices","text":"AbsoluteDeterminantOneMatrices <: AbstractMatrixType\n\nA type to indicate that we require (orthogonal / unitary) matrices with normed determinant, i.e. that the absolute value of the determinant is 1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Manifolds.AbstractMatrixType","page":"Orthogonal and Unitary Matrices","title":"Manifolds.AbstractMatrixType","text":"AbstractMatrixType\n\nA plain type to distinguish different types of matrices, for example DeterminantOneMatrices and AbsoluteDeterminantOneMatrices\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Manifolds.DeterminantOneMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.DeterminantOneMatrices","text":"DeterminantOneMatrices <: AbstractMatrixType\n\nA type to indicate that we require special (orthogonal / unitary) matrices, i.e. of determinant 1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Manifolds.GeneralUnitaryMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.GeneralUnitaryMatrices","text":"GeneralUnitaryMatrices{n,𝔽,S<:AbstractMatrixType} <: AbstractDecoratorManifold\n\nA common parametric type for matrices with a unitary property of size nn over the field mathbb F which additionally have the AbstractMatrixType, e.g. are DeterminantOneMatrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Base.exp-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Base.exp","text":"exp(M::Rotations, p, X)\nexp(M::OrthogonalMatrices, p, X)\nexp(M::UnitaryMatrices, p, X)\n\nCompute the exponential map, that is, since X is represented in the Lie algebra,\n\nexp_p(X) = p\\mathrm{e}^X\n\nFor different sizes, like n=234 there is specialised implementations\n\nThe algorithm used is a more numerically stable form of those proposed in [Gallier2002] and [Andrica2013].\n\n[Gallier2002]: Gallier J.; Xu D.; Computing exponentials of skew-symmetric matrices and logarithms of orthogonal matrices. International Journal of Robotics and Automation (2002), 17(4), pp. 1-11. pdf.\n\n[Andrica2013]: Andrica D.; Rohan R.-A.; Computing the Rodrigues coefficients of the exponential map of the Lie groups of matrices. Balkan Journal of Geometry and Its Applications (2013), 18(2), pp. 1-2. pdf.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Base.log-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Base.log","text":"log(M::Rotations, p, X)\nlog(M::OrthogonalMatrices, p, X)\nlog(M::UnitaryMatrices, p, X)\n\nCompute the logarithmic map, that is, since the resulting X is represented in the Lie algebra,\n\nlog_p q = \\log(p^{\\mathrm{H}q)\n\nwhich is projected onto the skew symmetric matrices for numerical stability.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Base.log-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Vararg{Any}}} where n","page":"Orthogonal and Unitary Matrices","title":"Base.log","text":"log(M::Rotations, p, q)\n\nCompute the logarithmic map on the Rotations manifold M which is given by\n\nlog_p q = operatornamelog(p^mathrmTq)\n\nwhere operatornameLog denotes the matrix logarithm. For numerical stability, the result is projected onto the set of skew symmetric matrices.\n\nFor antipodal rotations the function returns deterministically one of the tangent vectors that point at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.cos_angles_4d_rotation_matrix-Tuple{Any}","page":"Orthogonal and Unitary Matrices","title":"Manifolds.cos_angles_4d_rotation_matrix","text":"cos_angles_4d_rotation_matrix(R)\n\n4D rotations can be described by two orthogonal planes that are unchanged by the action of the rotation (vectors within a plane rotate only within the plane). The cosines of the two angles αβ of rotation about these planes may be obtained from the distinct real parts of the eigenvalues of the rotation matrix. This function computes these more efficiently by solving the system\n\nbeginaligned\ncos α + cos β = frac12 operatornametr(R)\ncos α cos β = frac18 operatornametr(R)^2\n - frac116 operatornametr((R - R^T)^2) - 1\nendaligned\n\nBy convention, the returned values are sorted in decreasing order. See also angles_4d_skew_sym_matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℂ, Manifolds.DeterminantOneMatrices}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}) where {n}\n\nVolume of the manifold of complex general unitary matrices of determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nsqrtn 2^n-1 π^(n-1)(n+2)2 prod_k=1^n-1frac1k\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ, Manifolds.AbsoluteDeterminantOneMatrices}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℝ,AbsoluteDeterminantOneMatrices}) where {n}\n\nVolume of the manifold of real orthogonal matrices of absolute determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nbegincases\nfrac2^k(2pi)^k^2prod_s=1^k-1 (2s) text if n = 2k \nfrac2^k+1(2pi)^k(k+1)prod_s=1^k-1 (2s+1) text if n = 2k+1\nendcases\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{Rotations{n}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℝ,DeterminantOneMatrices}) where {n}\n\nVolume of the manifold of real orthogonal matrices of determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nbegincases\n2 text if n = 0 \nfrac2^k-12(2pi)^k^2prod_s=1^k-1 (2s) text if n = 2k+2 \nfrac2^k+12(2pi)^k(k+1)prod_s=1^k-1 (2s+1) text if n = 2k+1\nendcases\n\nIt differs from the paper by a factor of sqrt(2) due to a different choice of normalization.\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{UnitaryMatrices{n, ℂ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℂ,AbsoluteDeterminantOneMatrices}) where {n}\n\nVolume of the manifold of complex general unitary matrices of absolute determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nsqrtn 2^n+1 π^n(n+1)2 prod_k=1^n-1frac1k\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.volume_density-Tuple{Manifolds.GeneralUnitaryMatrices{2, ℝ}, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Manifolds.volume_density","text":"volume_density(M::GeneralUnitaryMatrices{2,ℝ}, p, X)\n\nVolume density on O(2)/SO(2) is equal to 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.volume_density-Tuple{Manifolds.GeneralUnitaryMatrices{3, ℝ}, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Manifolds.volume_density","text":"volume_density(M::GeneralUnitaryMatrices{3,ℝ}, p, X)\n\nCompute the volume density on O(3)/SO(3). The formula reads [FalorsideHaanDavidsonForré2019]:\n\nfrac1-1cos(sqrt2lVert X rVert)lVert X rVert^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.volume_density-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Any, Any}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.volume_density","text":"volume_density(M::GeneralUnitaryMatrices{n,ℝ}, p, X) where {n}\n\nCompute volume density function of a sphere, i.e. determinant of the differential of exponential map exp(M, p, X). It is derived from Eq. (4.1) and Corollary 4.4 in [ChevallierLiLuDunson2022]. See also Theorem 4.1 in [FalorsideHaanDavidsonForré2019], (note that it uses a different convention).\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n[FalorsideHaanDavidsonForré2019]: L. Falorsi, P. de Haan, T. R. Davidson, and P. Forré, “Reparameterizing Distributions on Lie Groups,” arXiv:1903.02958 [cs, math, stat], Mar. 2019 doi: 10.48550/arXiv.1903.02958\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽, Manifolds.DeterminantOneMatrices}, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.check_point","text":"check_point(M::Rotations, p; kwargs...)\n\nCheck whether p is a valid point on the UnitaryMatrices M, i.e. that p has an determinante of absolute value one, i.e. that p^mathrmHp\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{UnitaryMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.check_point","text":"check_point(M::UnitaryMatrices, p; kwargs...)\ncheck_point(M::OrthogonalMatrices, p; kwargs...)\ncheck_point(M::GeneralUnitaryMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether p is a valid point on the UnitaryMatrices or [OrthogonalMatrices] M, i.e. that p has an determinante of absolute value one\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}, Any, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::UnitaryMatrices{n}, p, X; kwargs... )\ncheck_vector(M::OrthogonalMatrices{n}, p, X; kwargs... )\ncheck_vector(M::Rotations{n}, p, X; kwargs... )\ncheck_vector(M::GeneralUnitaryMatrices{n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the UnitaryMatrices space M, i.e. after check_point(M,p), X has to be skew symmetric (Hermitian) and orthogonal to p.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.embed-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.embed","text":"embed(M::GeneralUnitaryMatrices{n,𝔽}, p, X)\n\nEmbed the tangent vector X at point p in M from its Lie algebra representation (set of skew matrices) into the Riemannian submanifold representation\n\nThe formula reads\n\nX_textembedded = p * X\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.get_coordinates-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Vararg{Any}}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::Rotations, p, X)\nget_coordinates(M::OrthogonalMatrices, p, X)\nget_coordinates(M::UnitaryMatrices, p, X)\n\nExtract the unique tangent vector components X^i at point p on Rotations mathrmSO(n) from the matrix representation X of the tangent vector.\n\nThe basis on the Lie algebra 𝔰𝔬(n) is chosen such that for mathrmSO(2), X^1 = θ = X_21 is the angle of rotation, and for mathrmSO(3), (X^1 X^2 X^3) = (X_32 X_13 X_21) = θ u is the angular velocity and axis-angle representation, where u is the unit vector along the axis of rotation.\n\nFor mathrmSO(n) where n 4, the additional elements of X^i are X^j (j - 3)2 + k + 1 = X_jk, for j 4n k 1j).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.get_embedding-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}}, Tuple{𝔽}, Tuple{n}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::OrthogonalMatrices{n})\nget_embedding(M::Rotations{n})\nget_embedding(M::UnitaryMatrices{n})\n\nReturn the embedding, i.e. The mathbb F^nn, where mathbb F = mathbb R for the first two and mathbb F = mathbb C for the unitary matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.get_vector-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Vararg{Any}}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.get_vector","text":"get_vector(M::OrthogonalMatrices, p, Xⁱ, B::DefaultOrthogonalBasis)\nget_vector(M::Rotations, p, Xⁱ, B::DefaultOrthogonalBasis)\n\nConvert the unique tangent vector components Xⁱ at point p on Rotations or OrthogonalMatrices to the matrix representation X of the tangent vector. See get_coordinates for the conventions used.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.injectivity_radius-Tuple{Manifolds.GeneralUnitaryMatrices}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(G::GeneraliUnitaryMatrices)\n\nReturn the injectivity radius for general unitary matrix manifolds, which is[1]\n\n operatornameinj_mathrmU(n) = π\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.injectivity_radius-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℂ, Manifolds.DeterminantOneMatrices}}, Tuple{ℂ}, Tuple{n}} where {n, ℂ}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(G::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})\n\nReturn the injectivity radius for general complex unitary matrix manifolds, where the determinant is +1, which is[1]\n\n operatornameinj_mathrmSU(n) = π sqrt2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.injectivity_radius-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(G::SpecialOrthogonal)\ninjectivity_radius(G::Orthogonal)\ninjectivity_radius(M::Rotations)\ninjectivity_radius(M::Rotations, ::ExponentialRetraction)\n\nReturn the radius of injectivity on the Rotations manifold M, which is πsqrt2. [1]\n\n[1]: For a derivation of the injectivity radius, see sethaxen.com/blog/2023/02/the-injectivity-radii-of-the-unitary-groups/.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.is_flat-Tuple{Manifolds.GeneralUnitaryMatrices}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.is_flat","text":"is_flat(M::GeneralUnitaryMatrices)\n\nReturn true if GeneralUnitaryMatrices M is SO(2) or U(1) and false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℂ, Manifolds.DeterminantOneMatrices}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})\n\nReturn the dimension of the manifold of special unitary matrices.\n\ndim_mathrmSU(n) = n^2-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Rotations)\nmanifold_dimension(M::OrthogonalMatrices)\n\nReturn the dimension of the manifold orthogonal matrices and of the manifold of rotations\n\ndim_mathrmO(n) = dim_mathrmSO(n) = fracn(n-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.project-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.project","text":" project(M::OrthogonalMatrices{n}, p, X)\n project(M::Rotations{n}, p, X)\n project(M::UnitaryMatrices{n}, p, X)\n\nOrthogonally project the tangent vector X 𝔽^n n, mathbb F mathbb R mathbb C to the tangent space of M at p, and change the representer to use the corresponding Lie algebra, i.e. we compute\n\n operatornameproj_p(X) = fracp^mathrmH X - (p^mathrmH X)^mathrmH2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.project-Union{Tuple{𝔽}, Tuple{n}, Tuple{UnitaryMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.project","text":" project(G::UnitaryMatrices{n}, p)\n project(G::OrthogonalMatrices{n}, p)\n\nProject the point p 𝔽^n n to the nearest point in mathrmU(n𝔽)=Unitary(n,𝔽) under the Frobenius norm. If p = U S V^mathrmH is the singular value decomposition of p, then the projection is\n\n operatornameproj_mathrmU(n𝔽) colon p U V^mathrmH\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.retract-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}, Any, Any, PolarRetraction}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.retract","text":"retract(M::Rotations, p, X, ::PolarRetraction)\nretract(M::OrthogonalMatrices, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group) and is a second-order approximation of the exponential map. Let\n\nUSV = p + pX\n\nbe the singular value decomposition, then the formula reads\n\noperatornameretr_p X = UV^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.retract-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}, Any, Any, QRRetraction}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.retract","text":"retract(M::Rotations, p, X, ::QRRetraction)\nretract(M::OrthogonalMatrices, p. X, ::QRRetraction)\n\nCompute the QR-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group), which is a first-order approximation of the exponential map.\n\nThis is also the default retraction on these manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.riemann_tensor-Tuple{Manifolds.GeneralUnitaryMatrices, Vararg{Any, 4}}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::GeneralUnitaryMatrices, p, X, Y, Z)\n\nCompute the value of Riemann tensor on the GeneralUnitaryMatrices manifold. The formula reads[Rentmeesters2011] R(XY)Z=frac14Z X Y.\n\n[Rentmeesters2011]: Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Statistics.mean-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Any}} where n","page":"Orthogonal and Unitary Matrices","title":"Statistics.mean","text":"mean(\n M::Rotations,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/2/√2);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Footnotes-and-References","page":"Orthogonal and Unitary Matrices","title":"Footnotes and References","text":"","category":"section"},{"location":"tutorials/integration.html#Integration","page":"integrate on manifolds and handle probability densities","title":"Integration","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"This part of documentation covers integration of scalar functions defined on manifolds f colon mathcalM to mathbbR:","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"int_mathcal M f(p) mathrmdp","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"The basic concepts are derived from geometric measure theory. In principle, there are many ways in which a manifold can be equipped with a measure that can be later used to define an integral. One of the most popular ways is based on pushing the Lebesgue measure on a tangent space through the exponential map. Any other suitable atlas could be used, not just the one defined by normal coordinates, though each one requires different volume density corrections due to the Jacobian determinant of the pushforward. Manifolds.jl provides the function volume_density that calculates that quantity, denoted theta_p(X). See for example [1], Definition 11, for a precise description using Jacobi fields.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"While many sources define volume density as a function of two points, Manifolds.jl decided to use the more general point-tangent vector formulation. The two-points variant can be implemented as","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"using Manifolds\nvolume_density_two_points(M::AbstractManifold, p, q) = volume_density(M, p, log(M, p, q))","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"volume_density_two_points (generic function with 1 method)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"The simplest way to of integrating a function on a compact manifold is through a 📖 Monte Carlo integrator. A simple variant can be implemented as follows (assuming uniform distribution of rand):","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"using LinearAlgebra, Distributions, SpecialFunctions\nfunction simple_mc_integrate(M::AbstractManifold, f; N::Int = 1000)\n V = manifold_volume(M)\n sum = 0.0\n q = rand(M)\n for i in 1:N\n sum += f(M, q)\n rand!(M, q)\n end\n return V * sum/N\nend","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"simple_mc_integrate (generic function with 1 method)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"We used the function manifold_volume to get the volume of the set over which integration is performed, as described in the linked Wikipedia article.","category":"page"},{"location":"tutorials/integration.html#Distributions","page":"integrate on manifolds and handle probability densities","title":"Distributions","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"We will now try to verify that volume density correction correctly changes probability density of an exponential-wrapped normal distribution. pdf_tangent_space represents probability density of a normally distributed random variable X_T in the tangent space T_p mathcalM. Its probability density (with respect to the Lebesgue measure of the tangent space) is f_X_Tcolon T_p mathcalM to mathbbR.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"pdf_manifold refers to the probability density of the distribution X_M from the tangent space T_p mathcalM wrapped using exponential map on the manifold. The formula for probability density with respect to pushforward measure of the Lebesgue measure in the tangent space reads","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"f_X_M(q) = sum_X in T_pmathcalM exp_p(X)=q fracf_X_T(X)theta_p(X)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"volume_density function calculates the correction theta_p(X).","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"function pdf_tangent_space(M::AbstractManifold, p)\n return pdf(MvNormal(zeros(manifold_dimension(M)), 0.2*I), p)\nend\n\nfunction pdf_manifold(M::AbstractManifold, q)\n p = [1.0, 0.0, 0.0]\n X = log(M, p, q)\n Xc = get_coordinates(M, p, X, DefaultOrthonormalBasis())\n vd = abs(volume_density(M, p, X))\n if vd > eps()\n return pdf_tangent_space(M, Xc) / vd\n else\n return 0.0\n end\nend\n\nprintln(simple_mc_integrate(Sphere(2), pdf_manifold; N=1000000))","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"1.0007420406021186","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"The function simple_mc_integrate, defined in the previous section, is used to verify that the density integrates to 1 over the manifold.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Note that our pdf_manifold implements a simplified version of f_X_M which assumes that the probability mass of pdf_tangent_space outside of (local) injectivity radius at p is negligible. In such case there is only one non-zero summand in the formula for f_X_M(q), namely X=log_p(q). Otherwise we would have to consider other vectors Yin T_p mathcalM such that exp_p(Y) = q in that sum.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Remarkably, exponential-wrapped distributions possess three important qualities [2]:","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Densities of X_M are explicit. There is no normalization constant that needs to be computed like in truncated distributions.\nSampling from X_M is easy. It suffices to get a sample from X_T and pass it to the exponential map.\nIf mean of X_T is 0, then there is a simple correspondence between moments of X_M and X_T, for example p is the mean of X_M.","category":"page"},{"location":"tutorials/integration.html#Kernel-density-estimation","page":"integrate on manifolds and handle probability densities","title":"Kernel density estimation","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"We can also make a Pelletier’s isotropic kernel density estimator. Given points p_1 p_2 dots p_n on d-dimensional manifold mathcal M the density at point q is defined as","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"f(q) = frac1n h^d sum_i=1^n frac1theta_q(log_q(p_i))Kleft( fracd(q p_i)h right)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"where h is the bandwidth, a small positive number less than the injectivity radius of mathcal M and KcolonmathbbRtomathbbR is a kernel function. Note that Pelletier’s estimator can only use radially-symmetric kernels. The radially symmetric multivariate Epanechnikov kernel used in the example below is described in [3].","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"struct PelletierKDE{TM<:AbstractManifold,TPts<:AbstractVector}\n M::TM\n bandwidth::Float64\n pts::TPts\nend\n\n(kde::PelletierKDE)(::AbstractManifold, p) = kde(p)\nfunction (kde::PelletierKDE)(p)\n n = length(kde.pts)\n d = manifold_dimension(kde.M)\n sum_kde = 0.0\n function epanechnikov_kernel(x)\n if x < 1\n return gamma(2+d/2) * (1-x^2)/(π^(d/2))\n else\n return 0.0\n end\n end\n for i in 1:n\n X = log(kde.M, p, kde.pts[i])\n Xn = norm(kde.M, p, X)\n sum_kde += epanechnikov_kernel(Xn / kde.bandwidth) / volume_density(kde.M, p, X)\n end\n sum_kde /= n * kde.bandwidth^d\n return sum_kde\nend\n\nM = Sphere(2)\npts = rand(M, 8)\nkde = PelletierKDE(M, 0.7, pts)\nprintln(simple_mc_integrate(Sphere(2), kde; N=1000000))\nprintln(kde(rand(M)))","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"0.9994072759685285\n0.0","category":"page"},{"location":"tutorials/integration.html#Technical-notes","page":"integrate on manifolds and handle probability densities","title":"Technical notes","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"This section contains a few technical notes that are relevant to the problem of integration on manifolds but can be freely skipped on the first read of the tutorial.","category":"page"},{"location":"tutorials/integration.html#Conflicting-statements-about-volume-of-a-manifold","page":"integrate on manifolds and handle probability densities","title":"Conflicting statements about volume of a manifold","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"manifold_volume and volume_density are closely related to each other, though very few sources explore this connection, and some even claiming a certain level of arbitrariness in defining manifold_volume. Volume is sometimes considered arbitrary because Riemannian metrics on some spaces like the manifold of rotations are defined with arbitrary constants. However, once a constant is picked (and it must be picked before any useful computation can be performed), all geometric operations must follow in a consistent way: inner products, exponential and logarithmic maps, volume densities, etc. Manifolds.jl consistently picks such constants and provides a unified framework, though it sometimes results in picking a different constant than what is the most popular in some sub-communities.","category":"page"},{"location":"tutorials/integration.html#Haar-measures","page":"integrate on manifolds and handle probability densities","title":"Haar measures","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"On Lie groups the situation regarding integration is more complicated. Invariance under left or right group action is a desired property that leads one to consider Haar measures [4]. It is, however, unclear what are the practical benefits of considering Haar measures over the Lebesgue measure of the underlying manifold, which often turns out to be invariant anyway.","category":"page"},{"location":"tutorials/integration.html#Integration-in-charts","page":"integrate on manifolds and handle probability densities","title":"Integration in charts","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Integration through charts is an approach currently not supported by Manifolds.jl. One has to define a suitable set of disjoint charts covering the entire manifold and use a method for multivariate Euclidean integration. Note that ranges of parameters have to be adjusted for each manifold and scaling based on the metric needs to be applied. See [5] for some considerations on symmetric spaces.","category":"page"},{"location":"tutorials/integration.html#References","page":"integrate on manifolds and handle probability densities","title":"References","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[1]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"A. le Brigant and S. Puechmorel, “Approximation of Densities on Riemannian Manifolds,” Entropy, vol. 21, no. 1, Art. no. 1, Jan. 2019, doi: 10.3390/e21010043.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[2]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[3]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"N. Langrené and X. Warin, “Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating,” Journal of Computational and Graphical Statistics, vol. 28, no. 3, pp. 596–608, Jul. 2019, doi: 10.1080/10618600.2018.1549052.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[4]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"S. Tornier, “Haar Measures.” arXiv, Jun. 19, 2020. doi: 10.48550/arXiv.2006.10956.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[5]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1","category":"page"},{"location":"manifolds/multinomialdoublystochastic.html#Multinomial-doubly-stochastic-matrices","page":"Multinomial doubly stochastic matrices","title":"Multinomial doubly stochastic matrices","text":"","category":"section"},{"location":"manifolds/multinomialdoublystochastic.html","page":"Multinomial doubly stochastic matrices","title":"Multinomial doubly stochastic matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/MultinomialDoublyStochastic.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/multinomialdoublystochastic.html#Manifolds.AbstractMultinomialDoublyStochastic","page":"Multinomial doubly stochastic matrices","title":"Manifolds.AbstractMultinomialDoublyStochastic","text":"AbstractMultinomialDoublyStochastic{N} <: AbstractDecoratorManifold{ℝ}\n\nA common type for manifolds that are doubly stochastic, for example by direct constraint MultinomialDoubleStochastic or by symmetry MultinomialSymmetric, as long as they are also modeled as IsIsometricEmbeddedManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomialdoublystochastic.html#Manifolds.MultinomialDoubleStochastic","page":"Multinomial doubly stochastic matrices","title":"Manifolds.MultinomialDoubleStochastic","text":"MultinomialDoublyStochastic{n} <: AbstractMultinomialDoublyStochastic{N}\n\nThe set of doubly stochastic multinomial matrices consists of all nn matrices with stochastic columns and rows, i.e.\n\nbeginaligned\nmathcalDP(n) coloneqq biglp ℝ^nn big p_ij 0 text for all i=1n j=1m\n pmathbf1_n = p^mathrmTmathbf1_n = mathbf1_n\nbigr\nendaligned\n\nwhere mathbf1_n is the vector of length n containing ones.\n\nThe tangent space can be written as\n\nT_pmathcalDP(n) coloneqq bigl\nX ℝ^nn big X = X^mathrmT text and \nXmathbf1_n = X^mathrmTmathbf1_n = mathbf0_n\nbigr\n\nwhere mathbf0_n is the vector of length n containing zeros.\n\nMore details can be found in Section III[DouikHassibi2019].\n\nConstructor\n\nMultinomialDoubleStochastic(n)\n\nGenerate the manifold of matrices mathbb R^nn that are doubly stochastic and symmetric.\n\n[DouikHassibi2019]: A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.check_point-Union{Tuple{n}, Tuple{MultinomialDoubleStochastic{n}, Any}} where n","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.check_point","text":"check_point(M::MultinomialDoubleStochastic, p)\n\nChecks whether p is a valid point on the MultinomialDoubleStochastic(n) M, i.e. is a matrix with positive entries whose rows and columns sum to one.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.check_vector-Union{Tuple{n}, Tuple{MultinomialDoubleStochastic{n}, Any, Any}} where n","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::MultinomialDoubleStochastic p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the MultinomialDoubleStochastic M. This means, that p is valid, that X is of correct dimension and sums to zero along any column or row.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.is_flat-Tuple{MultinomialDoubleStochastic}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::MultinomialDoubleStochastic)\n\nReturn false. MultinomialDoubleStochastic is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.manifold_dimension-Union{Tuple{MultinomialDoubleStochastic{n}}, Tuple{n}} where n","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::MultinomialDoubleStochastic{n}) where {n}\n\nreturns the dimension of the MultinomialDoubleStochastic manifold namely\n\noperatornamedim_mathcalDP(n) = (n-1)^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.project-Tuple{Manifolds.AbstractMultinomialDoublyStochastic, Any}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.project","text":"project(\n M::AbstractMultinomialDoublyStochastic,\n p;\n maxiter = 100,\n tolerance = eps(eltype(p))\n)\n\nproject a matrix p with positive entries applying Sinkhorn's algorithm. Note that this projct method – different from the usual case, accepts keywords.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.project-Tuple{MultinomialDoubleStochastic, Any, Any}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.project","text":"project(M::MultinomialDoubleStochastic{n}, p, Y) where {n}\n\nProject Y onto the tangent space at p on the MultinomialDoubleStochastic M, return the result in X. The formula reads\n\n operatornameproj_p(Y) = Y - (αmathbf1_n^mathrmT + mathbf1_nβ^mathrmT) p\n\nwhere denotes the Hadamard or elementwise product and mathbb1_n is the vector of length n containing ones. The two vectors αβ ℝ^nn are computed as a solution (typically using the left pseudo inverse) of\n\n beginpmatrix I_n pp^mathrmT I_n endpmatrix\n beginpmatrix α βendpmatrix\n =\n beginpmatrix Ymathbf1Y^mathrmTmathbf1endpmatrix\n\nwhere I_n is the nn unit matrix and mathbf1_n is the vector of length n containing ones.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.retract-Tuple{MultinomialDoubleStochastic, Any, Any, ProjectionRetraction}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.retract","text":"retract(M::MultinomialDoubleStochastic, p, X, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting podotexp(Xp) back onto the manifold, where are elementwise multiplication and division, respectively. Similarly, exp refers to the elementwise exponentiation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#Literature","page":"Multinomial doubly stochastic matrices","title":"Literature","text":"","category":"section"},{"location":"manifolds/product.html#ProductManifoldSection","page":"Product manifold","title":"Product manifold","text":"","category":"section"},{"location":"manifolds/product.html","page":"Product manifold","title":"Product manifold","text":"Product manifold mathcal M = mathcalM_1 mathcalM_2 mathcalM_n of manifolds mathcalM_1 mathcalM_2 mathcalM_n. Points on the product manifold can be constructed using ProductRepr with canonical projections Π_i mathcalM mathcalM_i for i 1 2 n provided by submanifold_component.","category":"page"},{"location":"manifolds/product.html","page":"Product manifold","title":"Product manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProductManifold.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/product.html#Manifolds.InverseProductRetraction","page":"Product manifold","title":"Manifolds.InverseProductRetraction","text":"InverseProductRetraction(retractions::AbstractInverseRetractionMethod...)\n\nProduct inverse retraction of inverse retractions. Works on ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductBasisData","page":"Product manifold","title":"Manifolds.ProductBasisData","text":"ProductBasisData\n\nA typed tuple to store tuples of data of stored/precomputed bases for a ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductFVectorDistribution","page":"Product manifold","title":"Manifolds.ProductFVectorDistribution","text":"ProductFVectorDistribution([type::VectorBundleFibers], [x], distrs...)\n\nGenerates a random vector at point x from vector space (a fiber of a tangent bundle) of type type using the product distribution of given distributions.\n\nVector space type and x can be automatically inferred from distributions distrs.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductManifold","page":"Product manifold","title":"Manifolds.ProductManifold","text":"ProductManifold{𝔽,TM<:Tuple} <: AbstractManifold{𝔽}\n\nProduct manifold M_1 M_2 M_n with product geometry.\n\nConstructor\n\nProductManifold(M_1, M_2, ..., M_n)\n\ngenerates the product manifold M_1 M_2 M_n. Alternatively, the same manifold can be contructed using the × operator: M_1 × M_2 × M_3.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductMetric","page":"Product manifold","title":"Manifolds.ProductMetric","text":"ProductMetric <: AbstractMetric\n\nA type to represent the product of metrics for a ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductPointDistribution","page":"Product manifold","title":"Manifolds.ProductPointDistribution","text":"ProductPointDistribution(M::ProductManifold, distributions)\n\nProduct distribution on manifold M, combined from distributions.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductRetraction","page":"Product manifold","title":"Manifolds.ProductRetraction","text":"ProductRetraction(retractions::AbstractRetractionMethod...)\n\nProduct retraction of retractions. Works on ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductVectorTransport","page":"Product manifold","title":"Manifolds.ProductVectorTransport","text":"ProductVectorTransport(methods::AbstractVectorTransportMethod...)\n\nProduct vector transport type of methods. Works on ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Base.exp-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Base.exp","text":"exp(M::ProductManifold, p, X)\n\ncompute the exponential map from p in the direction of X on the ProductManifold M, which is the elementwise exponential map on the internal manifolds that build M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.getindex-Tuple{ProductManifold, Integer}","page":"Product manifold","title":"Base.getindex","text":"getindex(M::ProductManifold, i)\nM[i]\n\naccess the ith manifold component from the ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.getindex-Tuple{ProductRepr, ProductManifold, Union{Colon, Integer, Val, AbstractVector}}","page":"Product manifold","title":"Base.getindex","text":"getindex(p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})\np[M::ProductManifold, i]\n\nAccess the element(s) at index i of a point p on a ProductManifold M by linear indexing. See also Array Indexing in Julia.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.log-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Base.log","text":"log(M::ProductManifold, p, q)\n\nCompute the logarithmic map from p to q on the ProductManifold M, which can be computed using the logarithmic maps of the manifolds elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.rand-Tuple{ProductManifold}","page":"Product manifold","title":"Base.rand","text":"rand(M::ProductManifold; parts_kwargs = map(_ -> (;), M.manifolds))\n\nReturn a random point on ProductManifold M. parts_kwargs is a tuple of keyword arguments for rand on each manifold in M.manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.setindex!-Tuple{Union{ProductRepr, ArrayPartition}, Any, ProductManifold, Union{Colon, Integer, Val, AbstractVector}}","page":"Product manifold","title":"Base.setindex!","text":"setindex!(q, p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})\nq[M::ProductManifold,i...] = p\n\nset the element [i...] of a point q on a ProductManifold by linear indexing to q. See also Array Indexing in Julia.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#LinearAlgebra.cross-Tuple{Vararg{AbstractManifold}}","page":"Product manifold","title":"LinearAlgebra.cross","text":"cross(M, N)\ncross(M1, M2, M3,...)\n\nReturn the ProductManifold For two AbstractManifolds M and N, where for the case that one of them is a ProductManifold itself, the other is either prepended (if N is a product) or appenden (if M) is. If both are product manifold, they are combined into one product manifold, keeping the order.\n\nFor the case that more than one is a product manifold of these is build with the same approach as above\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#LinearAlgebra.norm-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"LinearAlgebra.norm","text":"norm(M::ProductManifold, p, X)\n\nCompute the norm of X from the tangent space of p on the ProductManifold, i.e. from the element wise norms the 2-norm is computed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.flat-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Manifolds.flat","text":"flat(M::ProductManifold, p, X::FVector{TangentSpaceType})\n\nuse the musical isomorphism to transform the tangent vector X from the tangent space at p on the ProductManifold M to a cotangent vector. This can be done elementwise for every entry of X (with respect to the corresponding entry in p) separately.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.manifold_volume-Tuple{ProductManifold}","page":"Product manifold","title":"Manifolds.manifold_volume","text":"manifold_dimension(M::ProductManifold)\n\nReturn the volume of ProductManifold M, i.e. product of volumes of the manifolds M is constructed from.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.number_of_components-Union{Tuple{ProductManifold{𝔽, <:Tuple{Vararg{Any, N}}}}, Tuple{N}, Tuple{𝔽}} where {𝔽, N}","page":"Product manifold","title":"Manifolds.number_of_components","text":"number_of_components(M::ProductManifold{<:NTuple{N,Any}}) where {N}\n\nCalculate the number of manifolds multiplied in the given ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.sharp-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Manifolds.sharp","text":"sharp(M::ProductManifold, p, ξ::FVector{CotangentSpaceType})\n\nUse the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on the ProductManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p) separately\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.submanifold-Tuple{ProductManifold, Integer}","page":"Product manifold","title":"Manifolds.submanifold","text":"submanifold(M::ProductManifold, i::Integer)\n\nExtract the ith factor of the product manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.submanifold-Tuple{ProductManifold, Val}","page":"Product manifold","title":"Manifolds.submanifold","text":"submanifold(M::ProductManifold, i::Val)\nsubmanifold(M::ProductManifold, i::AbstractVector)\n\nExtract the factor of the product manifold M indicated by indices in i. For example, for i equal to Val((1, 3)) the product manifold constructed from the first and the third factor is returned.\n\nThe version with AbstractVector is not type-stable, for better preformance use Val.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.volume_density-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"Manifolds.volume_density","text":"volume_density(M::ProductManifold, p, X)\n\nReturn volume density on the ProductManifold M, i.e. product of constituent volume densities.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.change_metric-Tuple{ProductManifold, AbstractMetric, Any, Any}","page":"Product manifold","title":"ManifoldsBase.change_metric","text":"change_metric(M::ProductManifold, ::AbstractMetric, p, X)\n\nSince the metric on a product manifold decouples, the change of metric can be done elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.change_representer-Tuple{ProductManifold, AbstractMetric, Any, Any}","page":"Product manifold","title":"ManifoldsBase.change_representer","text":"change_representer(M::ProductManifold, ::AbstractMetric, p, X)\n\nSince the metric on a product manifold decouples, the change of a representer can be done elementwise\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.check_point-Tuple{ProductManifold, Union{ProductRepr, ArrayPartition}}","page":"Product manifold","title":"ManifoldsBase.check_point","text":"check_point(M::ProductManifold, p; kwargs...)\n\nCheck whether p is a valid point on the ProductManifold M. If p is not a point on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.check_size-Tuple{ProductManifold, Union{ProductRepr, ArrayPartition}}","page":"Product manifold","title":"ManifoldsBase.check_size","text":"check_size(M::ProductManifold, p; kwargs...)\n\nCheck whether p is of valid size on the ProductManifold M. If p has components of wrong size a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.check_vector-Tuple{ProductManifold, Union{ProductRepr, ArrayPartition}, Union{ProductRepr, ArrayPartition}}","page":"Product manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::ProductManifold, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the ProductManifold M, i.e. all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.distance-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"ManifoldsBase.distance","text":"distance(M::ProductManifold, p, q)\n\nCompute the distance between two points p and q on the ProductManifold M, which is the 2-norm of the elementwise distances on the internal manifolds that build M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.get_component-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"ManifoldsBase.get_component","text":"get_component(M::ProductManifold, p, i)\n\nGet the ith component of a point p on a ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.injectivity_radius-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::ProductManifold)\ninjectivity_radius(M::ProductManifold, x)\n\nCompute the injectivity radius on the ProductManifold, which is the minimum of the factor manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.inner-Tuple{ProductManifold, Any, Any, Any}","page":"Product manifold","title":"ManifoldsBase.inner","text":"inner(M::ProductManifold, p, X, Y)\n\ncompute the inner product of two tangent vectors X, Y from the tangent space at p on the ProductManifold M, which is just the sum of the internal manifolds that build M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.inverse_retract-Tuple{ProductManifold, Any, Any, Any, Manifolds.InverseProductRetraction}","page":"Product manifold","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::ProductManifold, p, q, m::InverseProductRetraction)\n\nCompute the inverse retraction from p with respect to q on the ProductManifold M using an InverseProductRetraction, which by default encapsulates a inverse retraction for each manifold of the product. Then this method is performed elementwise, so the encapsulated inverse retraction methods have to be available per factor.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.is_flat-Tuple{ProductManifold}","page":"Product manifold","title":"ManifoldsBase.is_flat","text":"is_flat(::ProductManifold)\n\nReturn true if and only if all component manifolds of ProductManifold M are flat.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.manifold_dimension-Tuple{ProductManifold}","page":"Product manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::ProductManifold)\n\nReturn the manifold dimension of the ProductManifold, which is the sum of the manifold dimensions the product is made of.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.retract-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"ManifoldsBase.retract","text":"retract(M::ProductManifold, p, X, m::ProductRetraction)\n\nCompute the retraction from p with tangent vector X on the ProductManifold M using an ProductRetraction, which by default encapsulates retractions of the base manifolds. Then this method is performed elementwise, so the encapsulated retractions method has to be one that is available on the manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.riemann_tensor-Tuple{ProductManifold, Vararg{Any, 4}}","page":"Product manifold","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::ProductManifold, p, X, Y, Z)\n\nCompute the Riemann tensor at point from p with tangent vectors X, Y and Z on the ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.set_component!-Tuple{ProductManifold, Any, Any, Any}","page":"Product manifold","title":"ManifoldsBase.set_component!","text":"set_component!(M::ProductManifold, q, p, i)\n\nSet the ith component of a point q on a ProductManifold M to p, where p is a point on the AbstractManifold this factor of the product manifold consists of.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.vector_transport_to-Tuple{ProductManifold, Any, Any, Any, ProductVectorTransport}","page":"Product manifold","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::ProductManifold, p, X, q, m::ProductVectorTransport)\n\nCompute the vector transport the tangent vector Xat p to q on the ProductManifold M using an ProductVectorTransport m. This method is performed elementwise, i.e. the method m has to be implemented on the base manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#SPDFixedDeterminantSection","page":"SPD, fixed determinant","title":"Symmetric positive definite matrices of fixed determinant","text":"","category":"section"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"SPDFixedDeterminant","category":"page"},{"location":"manifolds/spdfixeddeterminant.html#Manifolds.SPDFixedDeterminant","page":"SPD, fixed determinant","title":"Manifolds.SPDFixedDeterminant","text":"SPDFixedDeterminant{N,D} <: AbstractDecoratorManifold{ℝ}\n\nThe manifold of symmetric positive definite matrices of fixed determinant d 0, i.e.\n\nmathcal P_d(n) =\nbigl\np ℝ^n n big a^mathrmTpa 0 text for all a ℝ^nbackslash0\n text and det(p) = d\nbigr\n\nThis manifold is modelled as a submanifold of SymmetricPositiveDefinite(n).\n\nThese matrices are sometimes also called isochoric, which refers to the interpretation of the matrix representing an ellipsoid. All ellipsoids that represent points on this manifold have the same volume.\n\nThe tangent space is modelled the same as for SymmetricPositiveDefinite(n) and consists of all symmetric matrices with zero trace\n\n T_pmathcal P_d(n) =\n bigl\n X in mathbb R^nn big X=X^mathrmT text and operatornametr(p) = 0\n bigr\n\nsince for a constant determinant we require that 0 = D\\det(p)[Z] = \\det(p)\\operatorname{tr}(p^{-1}Z) for all tangent vectors Z. Additionally we store the tangent vectors as X=p^{-1}Z, i.e. symmetric matrices.\n\nConstructor\n\nSPDFixedDeterminant(n::Int, d::Real=1.0)\n\ngenerates the manifold mathcal P_d(n) subset mathcal P(n) of determinant d, which defaults to 1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"This manifold can is a submanifold of the symmetric positive definite matrices and hence inherits most properties therefrom.","category":"page"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"The differences are the functions","category":"page"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"Modules = [Manifolds]\nPages = [\"manifolds/SPDFixedDeterminant.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.check_point-Union{Tuple{n}, Tuple{SPDFixedDeterminant{n}, Any}} where n","page":"SPD, fixed determinant","title":"ManifoldsBase.check_point","text":"check_point(M::SPDFixedDeterminant{n}, p; kwargs...)\n\nCheck whether p is a valid manifold point on the SPDFixedDeterminant(n,d) M, i.e. whether p is a SymmetricPositiveDefinite matrix of size (n, n)\n\nwith determinant det(p) =M.d.\n\nThe tolerance for the determinant of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.check_vector-Tuple{SPDFixedDeterminant, Any, Any}","page":"SPD, fixed determinant","title":"ManifoldsBase.check_vector","text":"check_vector(M::SPDFixedDeterminant, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SPDFixedDeterminant M, i.e. X has to be a tangent vector on SymmetricPositiveDefinite, so a symmetric matrix, and additionally fulfill operatornametr(X) = 0.\n\nThe tolerance for the trace check of X can be set using kwargs..., which influences the isapprox-check.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.project-Tuple{SPDFixedDeterminant, Any, Any}","page":"SPD, fixed determinant","title":"ManifoldsBase.project","text":"Y = project(M::SPDFixedDeterminant{n}, p, X)\nproject!(M::SPDFixedDeterminant{n}, Y, p, X)\n\nProject the symmetric matrix X onto the tangent space at p of the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of Y), by setting its diagonal (and hence its trace) to zero.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.project-Tuple{SPDFixedDeterminant, Any}","page":"SPD, fixed determinant","title":"ManifoldsBase.project","text":"q = project(M::SPDFixedDeterminant{n}, p)\nproject!(M::SPDFixedDeterminant{n}, q, p)\n\nProject the symmetric positive definite (s.p.d.) matrix p from the embedding onto the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of q).\n\nThe formula reads\n\nq = Bigl(fracddet(p)Bigr)^frac1np\n\n\n\n\n\n","category":"method"},{"location":"features/distributions.html#Distributions","page":"Distributions","title":"Distributions","text":"","category":"section"},{"location":"features/distributions.html","page":"Distributions","title":"Distributions","text":"The following functions and types provide support for manifold-valued and tangent space-valued distributions:","category":"page"},{"location":"features/distributions.html","page":"Distributions","title":"Distributions","text":"Modules = [Manifolds]\nPages = [\"distributions.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/distributions.html#Manifolds.FVectorDistribution","page":"Distributions","title":"Manifolds.FVectorDistribution","text":"FVectorDistribution{TSpace<:VectorBundleFibers, T}\n\nAn abstract distribution for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at point x from the given manifold). For example used for tangent vector-valued distributions.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.FVectorSupport","page":"Distributions","title":"Manifolds.FVectorSupport","text":"FVectorSupport(space::AbstractManifold, VectorBundleFibers)\n\nValue support for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at a point from the given manifold). For example used for tangent vector-valued distributions.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.FVectorvariate","page":"Distributions","title":"Manifolds.FVectorvariate","text":"FVectorvariate\n\nStructure that subtypes VariateForm, indicating that a single sample is a vector from a fiber of a vector bundle.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.MPointDistribution","page":"Distributions","title":"Manifolds.MPointDistribution","text":"MPointDistribution{TM<:AbstractManifold}\n\nAn abstract distribution for points on manifold of type TM.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.MPointSupport","page":"Distributions","title":"Manifolds.MPointSupport","text":"MPointSupport(M::AbstractManifold)\n\nValue support for manifold-valued distributions (values from given AbstractManifold M).\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.MPointvariate","page":"Distributions","title":"Manifolds.MPointvariate","text":"MPointvariate\n\nStructure that subtypes VariateForm, indicating that a single sample is a point on a manifold.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Distributions.support-Tuple{T} where T<:Manifolds.FVectorDistribution","page":"Distributions","title":"Distributions.support","text":"support(d::FVectorDistribution)\n\nGet the object of type FVectorSupport for the distribution d.\n\n\n\n\n\n","category":"method"},{"location":"features/distributions.html","page":"Distributions","title":"Distributions","text":"Modules = [Manifolds]\nPages = [\"projected_distribution.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/distributions.html#Manifolds.ProjectedFVectorDistribution","page":"Distributions","title":"Manifolds.ProjectedFVectorDistribution","text":"ProjectedFVectorDistribution(type::VectorBundleFibers, p, d, project!)\n\nGenerates a random vector from ambient space of manifold type.manifold at point p and projects it to vector space of type type using function project!, see project for documentation. Generated arrays are of type TResult.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.ProjectedPointDistribution","page":"Distributions","title":"Manifolds.ProjectedPointDistribution","text":"ProjectedPointDistribution(M::AbstractManifold, d, proj!, p)\n\nGenerates a random point in ambient space of M and projects it to M using function proj!. Generated arrays are of type TResult, which can be specified by providing the p argument.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.normal_tvector_distribution-Tuple{AbstractManifold, Any, Any}","page":"Distributions","title":"Manifolds.normal_tvector_distribution","text":"normal_tvector_distribution(M::Euclidean, p, σ)\n\nNormal distribution in ambient space with standard deviation σ projected to tangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"features/distributions.html#Manifolds.projected_distribution","page":"Distributions","title":"Manifolds.projected_distribution","text":"projected_distribution(M::AbstractManifold, d, [p=rand(d)])\n\nWrap the standard distribution d into a manifold-valued distribution. Generated points will be of similar type to p. By default, the type is not changed.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/fixedrankmatrices.html#FixedRankMatrices","page":"Fixed-rank matrices","title":"Fixed-rank matrices","text":"","category":"section"},{"location":"manifolds/fixedrankmatrices.html","page":"Fixed-rank matrices","title":"Fixed-rank matrices","text":"Modules = [Manifolds]\nPages = [\"FixedRankMatrices.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/fixedrankmatrices.html#Manifolds.FixedRankMatrices","page":"Fixed-rank matrices","title":"Manifolds.FixedRankMatrices","text":"FixedRankMatrices{m,n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe manifold of m n real-valued or complex-valued matrices of fixed rank k, i.e.\n\nbigl p 𝔽^m n big operatornamerank(p) = k bigr\n\nwhere 𝔽 ℝℂ and the rank is the number of linearly independent columns of a matrix.\n\nRepresentation with 3 matrix factors\n\nA point p mathcal M can be stored using unitary matrices U 𝔽^m k, V 𝔽^n k as well as the k singular values of p = U_p S V_p^mathrmH, where cdot^mathrmH denotes the complex conjugate transpose or Hermitian. In other words, U and V are from the manifolds Stiefel(m,k,𝔽) and Stiefel(n,k,𝔽), respectively; see SVDMPoint for details.\n\nThe tangent space T_p mathcal M at a point p mathcal M with p=U_p S V_p^mathrmH is given by\n\nT_pmathcal M = bigl U_p M V_p^mathrmH + U_X V_p^mathrmH + U_p V_X^mathrmH \n M 𝔽^k k\n U_X 𝔽^m k\n V_X 𝔽^n k\n text st \n U_p^mathrmHU_X = 0_k\n V_p^mathrmHV_X = 0_k\nbigr\n\nwhere 0_k is the k k zero matrix. See UMVTVector for details.\n\nThe (default) metric of this manifold is obtained by restricting the metric on ℝ^m n to the tangent bundle[Vandereycken2013].\n\nConstructor\n\nFixedRankMatrices(m, n, k[, field=ℝ])\n\nGenerate the manifold of m-by-n (field-valued) matrices of rank k.\n\n[Vandereycken2013]: Bart Vandereycken: \"Low-rank matrix completion by Riemannian Optimization, SIAM Journal on Optiomoization, 23(2), pp. 1214–1236, 2013. doi: 10.1137/110845768, arXiv: 1209.3834.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/fixedrankmatrices.html#Manifolds.SVDMPoint","page":"Fixed-rank matrices","title":"Manifolds.SVDMPoint","text":"SVDMPoint <: AbstractManifoldPoint\n\nA point on a certain manifold, where the data is stored in a svd like fashion, i.e. in the form USV^mathrmH, where this structure stores U, S and V^mathrmH. The storage might also be shortened to just k singular values and accordingly shortened U (columns) and V^mathrmH (rows).\n\nConstructors\n\nSVDMPoint(A) for a matrix A, stores its svd factors (i.e. implicitly k=minmn)\nSVDMPoint(S) for an SVD object, stores its svd factors (i.e. implicitly k=minmn)\nSVDMPoint(U,S,Vt) for the svd factors to initialize the SVDMPoint(i.e. implicitlyk=\\min\\{m,n\\}`)\nSVDMPoint(A,k) for a matrix A, stores its svd factors shortened to the best rank k approximation\nSVDMPoint(S,k) for an SVD object, stores its svd factors shortened to the best rank k approximation\nSVDMPoint(U,S,Vt,k) for the svd factors to initialize the SVDMPoint, stores its svd factors shortened to the best rank k approximation\n\n\n\n\n\n","category":"type"},{"location":"manifolds/fixedrankmatrices.html#Manifolds.UMVTVector","page":"Fixed-rank matrices","title":"Manifolds.UMVTVector","text":"UMVTVector <: TVector\n\nA tangent vector that can be described as a product U_p M V_p^mathrmH + U_X V_p^mathrmH + U_p V_X^mathrmH, where X = U_X S V_X^mathrmH is its base point, see for example FixedRankMatrices.\n\nThe base point p is required for example embedding this point, but it is not stored. The fields of thie tangent vector are U for U_X, M and Vt to store V_X^mathrmH\n\nConstructors\n\nUMVTVector(U,M,Vt) store umv factors to initialize the UMVTVector\nUMVTVector(U,M,Vt,k) store the umv factors after shortening them down to inner dimensions k.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/fixedrankmatrices.html#Base.rand-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"Base.rand","text":"Random.rand(M::FixedRankMatrices; vector_at=nothing, kwargs...)\n\nIf vector_at is nothing, return a random point on the FixedRankMatrices manifold. The orthogonal matrices are sampled from the Stiefel manifold and the singular values are sampled uniformly at random.\n\nIf vector_at is not nothing, generate a random tangent vector in the tangent space of the point vector_at on the FixedRankMatrices manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.check_point-Union{Tuple{k}, Tuple{n}, Tuple{m}, Tuple{FixedRankMatrices{m, n, k}, Any}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.check_point","text":"check_point(M::FixedRankMatrices{m,n,k}, p; kwargs...)\n\nCheck whether the matrix or SVDMPoint x ids a valid point on the FixedRankMatrices{m,n,k,𝔽} M, i.e. is an m-byn matrix of rank k. For the SVDMPoint the internal representation also has to have the right shape, i.e. p.U and p.Vt have to be unitary. The keyword arguments are passed to the rank function that verifies the rank of p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.check_vector-Union{Tuple{k}, Tuple{n}, Tuple{m}, Tuple{FixedRankMatrices{m, n, k}, SVDMPoint, UMVTVector}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M:FixedRankMatrices{m,n,k}, p, X; kwargs...)\n\nCheck whether the tangent UMVTVector X is from the tangent space of the SVDMPoint p on the FixedRankMatrices M, i.e. that v.U and v.Vt are (columnwise) orthogonal to x.U and x.Vt, respectively, and its dimensions are consistent with p and X.M, i.e. correspond to m-by-n matrices of rank k.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.default_inverse_retraction_method-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.default_inverse_retraction_method","text":"default_inverse_retraction_method(M::FixedRankMatrices)\n\nReturn PolarInverseRetraction as the default inverse retraction for the FixedRankMatrices manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.default_retraction_method-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::FixedRankMatrices)\n\nReturn PolarRetraction as the default retraction for the FixedRankMatrices manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.default_vector_transport_method-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::FixedRankMatrices)\n\nReturn the ProjectionTransport as the default vector transport method for the FixedRankMatrices manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.embed-Tuple{FixedRankMatrices, SVDMPoint, UMVTVector}","page":"Fixed-rank matrices","title":"ManifoldsBase.embed","text":"embed(M::FixedRankMatrices, p, X)\n\nEmbed the tangent vector X at point p in M from its UMVTVector representation into the set of mn matrices.\n\nThe formula reads\n\nU_pMV_p^mathrmH + U_XV_p^mathrmH + U_pV_X^mathrmH\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.embed-Tuple{FixedRankMatrices, SVDMPoint}","page":"Fixed-rank matrices","title":"ManifoldsBase.embed","text":"embed(::FixedRankMatrices, p::SVDMPoint)\n\nEmbed the point p from its SVDMPoint representation into the set of mn matrices by computing USV^mathrmH.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.injectivity_radius-Union{Tuple{FixedRankMatrices{m, n, k}}, Tuple{k}, Tuple{n}, Tuple{m}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(::FixedRankMatrices)\n\nReturn the incjectivity radius of the manifold of FixedRankMatrices, i.e. 0. See [HosseiniUschmajew2017].\n\n[HosseiniUschmajew2017]: S. Hosseini and A. Uschmajew, “A Riemannian Gradient Sampling Algorithm for Nonsmooth Optimization on Manifolds,” SIAM J. Optim., vol. 27, no. 1, pp. 173–189, Jan. 2017, doi: 10.1137/16M1069298.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.inner-Tuple{FixedRankMatrices, SVDMPoint, UMVTVector, UMVTVector}","page":"Fixed-rank matrices","title":"ManifoldsBase.inner","text":"inner(M::FixedRankMatrices, p::SVDMPoint, X::UMVTVector, Y::UMVTVector)\n\nCompute the inner product of X and Y in the tangent space of p on the FixedRankMatrices M, which is inherited from the embedding, i.e. can be computed using dot on the elements (U, Vt, M) of X and Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.is_flat-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::FixedRankMatrices)\n\nReturn false. FixedRankMatrices is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.manifold_dimension-Union{Tuple{FixedRankMatrices{m, n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{m}} where {m, n, k, 𝔽}","page":"Fixed-rank matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::FixedRankMatrices{m,n,k,𝔽})\n\nReturn the manifold dimension for the 𝔽-valued FixedRankMatrices M of dimension mxn of rank k, namely\n\ndim(mathcal M) = k(m + n - k) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.project-Tuple{FixedRankMatrices, Any, Any}","page":"Fixed-rank matrices","title":"ManifoldsBase.project","text":"project(M, p, A)\n\nProject the matrix A ℝ^mn or from the embedding the tangent space at p on the FixedRankMatrices M, further decomposing the result into X=UMV^mathrmH, i.e. a UMVTVector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.representation_size-Union{Tuple{FixedRankMatrices{m, n}}, Tuple{n}, Tuple{m}} where {m, n}","page":"Fixed-rank matrices","title":"ManifoldsBase.representation_size","text":"representation_size(M::FixedRankMatrices{m,n,k})\n\nReturn the element size of a point on the FixedRankMatrices M, i.e. the size of matrices on this manifold (mn).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.retract-Tuple{FixedRankMatrices, Any, Any, PolarRetraction}","page":"Fixed-rank matrices","title":"ManifoldsBase.retract","text":"retract(M, p, X, ::PolarRetraction)\n\nCompute an SVD-based retraction on the FixedRankMatrices M by computing\n\n q = U_kS_kV_k^mathrmH\n\nwhere U_k S_k V_k^mathrmH is the shortened singular value decomposition USV^mathrmH=p+X, in the sense that S_k is the diagonal matrix of size k k with the k largest singular values and U and V are shortened accordingly.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.vector_transport_to!-Tuple{FixedRankMatrices, Any, Any, Any, ProjectionTransport}","page":"Fixed-rank matrices","title":"ManifoldsBase.vector_transport_to!","text":"vector_transport_to(M::FixedRankMatrices, p, X, q, ::ProjectionTransport)\n\nCompute the vector transport of the tangent vector X at p to q, using the project of X to q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.zero_vector-Union{Tuple{k}, Tuple{n}, Tuple{m}, Tuple{FixedRankMatrices{m, n, k}, SVDMPoint}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::FixedRankMatrices, p::SVDMPoint)\n\nReturn a UMVTVector representing the zero tangent vector in the tangent space of p on the FixedRankMatrices M, for example all three elements of the resulting structure are zero matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#Literature","page":"Fixed-rank matrices","title":"Literature","text":"","category":"section"},{"location":"manifolds/stiefel.html#Stiefel","page":"Stiefel","title":"Stiefel","text":"","category":"section"},{"location":"manifolds/stiefel.html#Common-and-metric-independent-functions","page":"Stiefel","title":"Common and metric independent functions","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/Stiefel.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.Stiefel","page":"Stiefel","title":"Manifolds.Stiefel","text":"Stiefel{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe Stiefel manifold consists of all n k, n k unitary matrices, i.e.\n\noperatornameSt(nk) = bigl p 𝔽^n k big p^mathrmHp = I_k bigr\n\nwhere 𝔽 ℝ ℂ, cdot^mathrmH denotes the complex conjugate transpose or Hermitian, and I_k ℝ^k k denotes the k k identity matrix.\n\nThe tangent space at a point p mathcal M is given by\n\nT_p mathcal M = X 𝔽^n k p^mathrmHX + overlineX^mathrmHp = 0_k\n\nwhere 0_k is the k k zero matrix and overlinecdot the (elementwise) complex conjugate.\n\nThis manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.\n\nThe manifold is named after Eduard L. Stiefel (1909–1978).\n\nConstructor\n\nStiefel(n, k, field = ℝ)\n\nGenerate the (real-valued) Stiefel manifold of n k dimensional orthonormal matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Base.rand-Tuple{Stiefel}","page":"Stiefel","title":"Base.rand","text":"rand(::Stiefel; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (Gaussian) point x on the Stiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the orthogonalized version, i.e. return the Q component of the QR decomposition of the random matrix of size nk.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_vector_atmathrmSt(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Manifolds.uniform_distribution-Union{Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, ℝ}, Any}} where {n, k}","page":"Stiefel","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::Stiefel{n,k,ℝ}, p)\n\nUniform distribution on given (real-valued) Stiefel M. Specifically, this is the normalized Haar and Hausdorff measure on M. Generated points will be of similar type as p.\n\nThe implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.1(iii) in [Chikuse2003].\n\n[Chikuse2003]: Y. Chikuse: \"Statistics on Special Manifolds\", Springer New York, 2003, doi: 10.1007/978-0-387-21540-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.change_metric-Tuple{Stiefel, EuclideanMetric, Any, Any}","page":"Stiefel","title":"ManifoldsBase.change_metric","text":"change_metric(M::Stiefel, ::EuclideanMetric, p X)\n\nChange X to the corresponding vector with respect to the metric of the Stiefel M, which is just the identity, since the manifold is isometrically embedded.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.change_representer-Tuple{Stiefel, EuclideanMetric, Any, Any}","page":"Stiefel","title":"ManifoldsBase.change_representer","text":"change_representer(M::Stiefel, ::EuclideanMetric, p, X)\n\nChange X to the corresponding representer of a cotangent vector at p. Since the Stiefel manifold M, is isometrically embedded, this is the identity\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Stiefel","title":"ManifoldsBase.check_point","text":"check_point(M::Stiefel, p; kwargs...)\n\nCheck whether p is a valid point on the Stiefel M=operatornameSt(nk), i.e. that it has the right AbstractNumbers type and p^mathrmHp is (approximately) the identity, where cdot^mathrmH is the complex conjugate transpose. The settings for approximately can be set with kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, 𝔽}, Any, Any}} where {n, k, 𝔽}","page":"Stiefel","title":"ManifoldsBase.check_vector","text":"check_vector(M::Stiefel, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector at p on the Stiefel M=operatornameSt(nk), i.e. the AbstractNumbers fits and it (approximately) holds that p^mathrmHX + overlineX^mathrmHp = 0, where cdot^mathrmH denotes the Hermitian and overlinecdot the (elementwise) complex conjugate. The settings for approximately can be set with kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.default_inverse_retraction_method-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.default_inverse_retraction_method","text":"default_inverse_retraction_method(M::Stiefel)\n\nReturn PolarInverseRetraction as the default inverse retraction for the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.default_retraction_method-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Stiefel)\n\nReturn PolarRetraction as the default retraction for the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.default_vector_transport_method-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::Stiefel)\n\nReturn the DifferentiatedRetractionVectorTransport of the [PolarRetraction](PolarRetraction as the default vector transport method for the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{Stiefel, Any, Any, PolarInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Stiefel, p, q, ::PolarInverseRetraction)\n\nCompute the inverse retraction based on a singular value decomposition for two points p, q on the Stiefel manifold M. This follows the folloing approach: From the Polar retraction we know that\n\noperatornameretr_p^-1q = qs - t\n\nif such a symmetric positive definite k k matrix exists. Since qs - t is also a tangent vector at p we obtain\n\np^mathrmHqs + s(p^mathrmHq)^mathrmH + 2I_k = 0\n\nwhich can either be solved by a Lyapunov approach or a continuous-time algebraic Riccati equation.\n\nThis implementation follows the Lyapunov approach.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{Stiefel, Any, Any, QRInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Stiefel, p, q, ::QRInverseRetraction)\n\nCompute the inverse retraction based on a qr decomposition for two points p, q on the Stiefel manifold M and return the resulting tangent vector in X. The computation follows Algorithm 1 in [KanekoFioriTanaka2013].\n\n[KanekoFioriTanaka2013]: T. Kaneko, S. Fiori, T. Tanaka: \"Empirical Arithmetic Averaging over the Compact Stiefel AbstractManifold\", IEEE Transactions on Signal Processing, 2013, doi: 10.1109/TSP.2012.2226167.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.is_flat-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.is_flat","text":"is_flat(M::Stiefel)\n\nReturn true if Stiefel M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.manifold_dimension-Union{Tuple{Stiefel{n, k, ℝ}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Stiefel)\n\nReturn the dimension of the Stiefel manifold M=operatornameSt(nk𝔽). The dimension is given by\n\nbeginaligned\ndim mathrmSt(n k ℝ) = nk - frac12k(k+1)\ndim mathrmSt(n k ℂ) = 2nk - k^2\ndim mathrmSt(n k ℍ) = 4nk - k(2k-1)\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.representation_size-Union{Tuple{Stiefel{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.representation_size","text":"representation_size(M::Stiefel)\n\nReturns the representation size of the Stiefel M=operatornameSt(nk), i.e. (n,k), which is the matrix dimensions.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, CayleyRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(::Stiefel, p, X, ::CayleyRetraction)\n\nCompute the retraction on the Stiefel that is based on the Cayley transform[Zhu2017]. Using\n\n W_pX = operatornameP_pXp^mathrmH - pX^mathrmHoperatornameP_p\n quadtextwhere \n operatornameP_p = I - frac12pp^mathrmH\n\nthe formula reads\n\n operatornameretr_pX = Bigl(I - frac12W_pXBigr)^-1Bigl(I + frac12W_pXBigr)p\n\nIt is implemented as the case m=1 of the PadeRetraction.\n\n[Zhu2017]: X. Zhu: A Riemannian conjugate gradient method for optimizazion on the Stiefel manifold, Computational Optimization and Applications 67(1), pp. 73–110, 2017. doi 10.1007/s10589-016-9883-4.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, PadeRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, ::PadeRetraction{m})\n\nCompute the retraction on the Stiefel manifold M based on the Padé approximation of order m[ZhuDuan2018]. Let p_m and q_m be defined for any matrix A ℝ^nx as\n\n p_m(A) = sum_k=0^m frac(2m-k)m(2m)(m-k)fracA^kk\n\nand\n\n q_m(A) = sum_k=0^m frac(2m-k)m(2m)(m-k)frac(-A)^kk\n\nrespectively. Then the Padé approximation (of the matrix exponential exp(A)) reads\n\n r_m(A) = q_m(A)^-1p_m(A)\n\nDefining further\n\n W_pX = operatornameP_pXp^mathrmH - pX^mathrmHoperatornameP_p\n quadtextwhere \n operatornameP_p = I - frac12pp^mathrmH\n\nthe retraction reads\n\n operatornameretr_pX = r_m(W_pX)p\n\n[ZhuDuan2018]: X. Zhu, C. Duan: On matrix exponentials and their approximations related to optimization on the Stiefel manifold, Optimizazion Letters 13(5), pp. 1069–1083, 2018. doi 10.1007/s11590-018-1341-z.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, PolarRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the Stiefel manifold M. With USV = p + X the retraction reads\n\noperatornameretr_p X = UbarV^mathrmH\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, QRRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, ::QRRetraction)\n\nCompute the QR-based retraction QRRetraction on the Stiefel manifold M. With QR = p + X the retraction reads\n\noperatornameretr_p X = QD\n\nwhere D is a n k matrix with\n\nD = operatornamediagbigl(operatornamesgn(R_ii+05)_i=1^k bigr)\n\nwhere operatornamesgn(p) = begincases 1 text for p 0\n0 text for p = 0\n-1 text for p 0 endcases\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_direction-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{CayleyRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_direction","text":"vector_transport_direction(::Stiefel, p, X, d, ::DifferentiatedRetractionVectorTransport{CayleyRetraction})\n\nCompute the vector transport given by the differentiated retraction of the CayleyRetraction, cf. [Zhu2017] Equation (17).\n\nThe formula reads\n\noperatornameT_pd(X) =\nBigl(I - frac12W_pdBigr)^-1W_pXBigl(I - frac12W_pdBigr)^-1p\n\nwith\n\n W_pX = operatornameP_pXp^mathrmH - pX^mathrmHoperatornameP_p\n quadtextwhere \n operatornameP_p = I - frac12pp^mathrmH\n\nSince this is the differentiated retraction as a vector transport, the result will be in the tangent space at q=operatornameretr_p(d) using the CayleyRetraction.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_direction-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{PolarRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_direction","text":"vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{PolarRetraction})\n\nCompute the vector transport by computing the push forward of retract(::Stiefel, ::Any, ::Any, ::PolarRetraction) Section 3.5 of [Zhu2017]:\n\nT_pd^textPol(X) = q*Λ + (I-qq^mathrmT)X(1+d^mathrmTd)^-frac12\n\nwhere q = operatornameretr^mathrmPol_p(d), and Λ is the unique solution of the Sylvester equation\n\n Λ(I+d^mathrmTd)^frac12 + (I + d^mathrmTd)^frac12 = q^mathrmTX - X^mathrmTq\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_direction-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{QRRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_direction","text":"vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{QRRetraction})\n\nCompute the vector transport by computing the push forward of the retract(::Stiefel, ::Any, ::Any, ::QRRetraction), See [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].\n\nT_pd^textQR(X) = q*rho_mathrms(q^mathrmTXR^-1) + (I-qq^mathrmT)XR^-1\n\nwhere q = operatornameretr^mathrmQR_p(d), R is the R factor of the QR decomposition of p + d, and\n\nbigl( rho_mathrms(A) bigr)_ij\n= begincases\nA_ijtext if i j\n0 text if i = j\n-A_ji text if i j\nendcases\n\n[AbsilMahonySepulchre2008]: Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_to-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{PolarRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{PolarRetraction})\n\nCompute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::PolarRetraction), see Section 4 of [HuangGallivanAbsil2015] or Section 3.5 of [Zhu2017]:\n\nT_qgets p^textPol(X) = q*Λ + (I-qq^mathrmT)X(1+d^mathrmTd)^-frac12\n\nwhere d = bigl( operatornameretr^mathrmPol_pbigr)^-1(q), and Λ is the unique solution of the Sylvester equation\n\n Λ(I+d^mathrmTd)^frac12 + (I + d^mathrmTd)^frac12 = q^mathrmTX - X^mathrmTq\n\n[HuangGallivanAbsil2015]: Huang, W., Gallivan, K. A., and Absil, P.-A.: A Broyden class of quasi-Newton methods for Riemannian optimization SIAM Journal of Optimization, 2015, Vol. 25, No. 3, pp. 1660–1685 doi: 10.1137/140955483 pdf: tech. report\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_to-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{QRRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{QRRetraction})\n\nCompute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::QRRetraction), see [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].\n\nT_q gets p^textQR(X) = q*rho_mathrms(q^mathrmTXR^-1) + (I-qq^mathrmT)XR^-1\n\nwhere d = bigl(operatornameretr^mathrmQRbigr)^-1_p(q), R is the R factor of the QR decomposition of p+X, and\n\nbigl( rho_mathrms(A) bigr)_ij\n= begincases\nA_ijtext if i j\n0 text if i = j\n-A_ji text if i j\nendcases\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_to-Tuple{Stiefel, Any, Any, Any, ProjectionTransport}","page":"Stiefel","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Stiefel, p, X, q, ::ProjectionTransport)\n\nCompute a vector transport by projection, i.e. project X from the tangent space at p by projection it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Default-metric:-the-Euclidean-metric","page":"Stiefel","title":"Default metric: the Euclidean metric","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"The EuclideanMetric is obtained from the embedding of the Stiefel manifold in ℝ^nk.","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelEuclideanMetric.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/stiefel.html#Base.exp-Tuple{Stiefel, Vararg{Any}}","page":"Stiefel","title":"Base.exp","text":"exp(M::Stiefel, p, X)\n\nCompute the exponential map on the Stiefel{n,k,𝔽}() manifold M emanating from p in tangent direction X.\n\nexp_p X = beginpmatrix\n pX\n endpmatrix\n operatornameExp\n left(\n beginpmatrix p^mathrmHX - X^mathrmHX\n I_n p^mathrmHXendpmatrix\n right)\nbeginpmatrix exp( -p^mathrmHX) 0_nendpmatrix\n\nwhere operatornameExp denotes matrix exponential, cdot^mathrmH denotes the complex conjugate transpose or Hermitian, and I_k and 0_k are the identity matrix and the zero matrix of dimension k k, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.get_basis-Union{Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, ℝ}, Any, DefaultOrthonormalBasis{ℝ, ManifoldsBase.TangentSpaceType}}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.get_basis","text":"get_basis(M::Stiefel{n,k,ℝ}, p, B::DefaultOrthonormalBasis) where {n,k}\n\nCreate the default basis using the parametrization for any X T_pmathcal M. Set p_bot in ℝ^ntimes(n-k) the matrix such that the ntimes n matrix of the common columns p p_bot is an ONB. For any skew symmetric matrix a ℝ^ktimes k and any b ℝ^(n-k)times k the matrix\n\nX = pa + p_bot b T_pmathcal M\n\nand we can use the frac12k(k-1) + (n-k)k = nk-frac12k(k+1) entries of a and b to specify a basis for the tangent space. using unit vectors for constructing both the upper matrix of a to build a skew symmetric matrix and the matrix b, the default basis is constructed.\n\nSince p p_bot is an automorphism on ℝ^ntimes p the elements of a and b are orthonormal coordinates for the tangent space. To be precise exactly one element in the upper trangular entries of a is set to 1 its symmetric entry to -1 and we normalize with the factor frac1sqrt2 and for b one can just use unit vectors reshaped to a matrix to obtain orthonormal set of parameters.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{Stiefel, Any, Any, ProjectionInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Stiefel, p, q, method::ProjectionInverseRetraction)\n\nCompute a projection-based inverse retraction.\n\nThe inverse retraction is computed by projecting the logarithm map in the embedding to the tangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.project-Tuple{Stiefel, Any, Any}","page":"Stiefel","title":"ManifoldsBase.project","text":"project(M::Stiefel,p)\n\nProjects p from the embedding onto the Stiefel M, i.e. compute q as the polar decomposition of p such that q^mathrmHq is the identity, where cdot^mathrmH denotes the hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.project-Tuple{Stiefel, Vararg{Any}}","page":"Stiefel","title":"ManifoldsBase.project","text":"project(M::Stiefel, p, X)\n\nProject X onto the tangent space of p to the Stiefel manifold M. The formula reads\n\noperatornameproj_mathcal M(p X) = X - p operatornameSym(p^mathrmHX)\n\nwhere operatornameSym(q) is the symmetrization of q, e.g. by operatornameSym(q) = fracq^mathrmH+q2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, ProjectionRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, method::ProjectionRetraction)\n\nCompute a projection-based retraction.\n\nThe retraction is computed by projecting the exponential map in the embedding to M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#The-canonical-metric","page":"Stiefel","title":"The canonical metric","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Any XT_pmathcal M, pmathcal M, can be written as","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"X = pA + (I_n-pp^mathrmT)B\nquad\nA ℝ^pp text skew-symmetric\nquad\nB ℝ^np text arbitrary","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"In the EuclideanMetric, the elements from A are counted twice (i.e. weighted with a factor of 2). The canonical metric avoids this.","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelCanonicalMetric.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.ApproximateLogarithmicMap","page":"Stiefel","title":"Manifolds.ApproximateLogarithmicMap","text":"ApproximateLogarithmicMap <: ApproximateInverseRetraction\n\nAn approximate implementation of the logarithmic map, which is an inverse_retraction. See inverse_retract(::MetricManifold{ℝ,Stiefel{n,k,ℝ},CanonicalMetric}, ::Any, ::Any, ::ApproximateLogarithmicMap) where {n,k} for a use case.\n\nFields\n\nmax_iterations – maximal number of iterations used in the approximation\ntolerance – a tolerance used as a stopping criterion\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Manifolds.CanonicalMetric","page":"Stiefel","title":"Manifolds.CanonicalMetric","text":"CanonicalMetric <: AbstractMetric\n\nThe Canonical Metric refers to a metric for the Stiefel manifold, see[EdelmanAriasSmith1998].\n\n[EdelmanAriasSmith1998]: Edelman, A., Ariar, T. A., Smith, S. T.: The Geometry of Algorihthms with Orthogonality Constraints, SIAM Journal on Matrix Analysis and Applications (20(2), pp. 303–353, 1998. doi: 10.1137/S0895479895290954 arxiv: 9806030\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelCanonicalMetric.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/stiefel.html#Base.exp-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, CanonicalMetric}, Vararg{Any}}} where {n, k}","page":"Stiefel","title":"Base.exp","text":"q = exp(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, X)\nexp!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, q, CanonicalMetric}, p, X)\n\nCompute the exponential map on the Stiefel(n,k) manifold with respect to the CanonicalMetric.\n\nFirst, decompose The tangent vector X into its horizontal and vertical component with respect to p, i.e.\n\nX = pp^mathrmTX + (I_n-pp^mathrmT)X\n\nwhere I_n is the ntimes n identity matrix. We introduce A=p^mathrmTX and QR = (I_n-pp^mathrmT)X the qr decomposition of the vertical component. Then using the matrix exponential operatornameExp we introduce B and C as\n\nbeginpmatrix\nBC\nendpmatrix\ncoloneqq\noperatornameExpleft(\nbeginpmatrix\nA -R^mathrmT R 0\nendpmatrix\nright)\nbeginpmatrixI_k0endpmatrix\n\nthe exponential map reads\n\nq = exp_p X = pC + QB\n\nFor more details, see [EdelmanAriasSmith1998][Zimmermann2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, CanonicalMetric}, Any, Any, Any}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.inner","text":"inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, X, Y)\n\nCompute the inner product on the Stiefel manifold with respect to the CanonicalMetric. The formula reads\n\ng_p(XY) = operatornametrbigl( X^mathrmT(I_n - frac12pp^mathrmT)Y bigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, CanonicalMetric}, Any, Any, ApproximateLogarithmicMap}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"X = inverse_retract(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)\ninverse_retract!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)\n\nCompute an approximation to the logarithmic map on the Stiefel(n,k) manifold with respect to the CanonicalMetric using a matrix-algebraic based approach to an iterative inversion of the formula of the exp.\n\nThe algorithm is derived in[Zimmermann2017] and it uses the max_iterations and the tolerance field from the ApproximateLogarithmicMap.\n\n[Zimmermann2017]: Zimmermann, R.: _A matrix-algebraic algorithm for the Riemannian logarithm on the Stiefel manifold under the canoncial metric. SIAM Journal on Matrix Analysis and Applications 28(2), pp. 322-342, 2017. doi: 10.1137/16M1074485, arXiv: 1604.05054.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#The-submersion-or-normal-metric","page":"Stiefel","title":"The submersion or normal metric","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelSubmersionMetric.jl\"]\nOrder = [:type, :function]\nPublic = true\nPrivate = false","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.StiefelSubmersionMetric","page":"Stiefel","title":"Manifolds.StiefelSubmersionMetric","text":"StiefelSubmersionMetric{T<:Real} <: RiemannianMetric\n\nThe submersion (or normal) metric family on the Stiefel manifold.\n\nThe family, with a single real parameter α-1, has two special cases:\n\nα = -frac12: EuclideanMetric\nα = 0: CanonicalMetric\n\nThe family was described in [HüperMarkinaLeite2021]. This implementation follows the description in [ZimmermanHüper2022].\n\n[HüperMarkinaLeite2021]: Hüper, M., Markina, A., Leite, R. T. (2021) \"A Lagrangian approach to extremal curves on Stiefel manifolds\" Journal of Geometric Mechanics, 13(1): 55-72. doi: 10.3934/jgm.2020031\n\n[ZimmermanHüper2022]: Ralf Zimmerman and Knut Hüper. (2022). \"Computing the Riemannian logarithm on the Stiefel manifold: metrics, methods and performance.\" arXiv: 2103.12046\n\nConstructor\n\nStiefelSubmersionMetric(α)\n\nConstruct the submersion metric on the Stiefel manifold with the parameter α.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Base.exp-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, <:StiefelSubmersionMetric}, Vararg{Any}}} where {n, k}","page":"Stiefel","title":"Base.exp","text":"q = exp(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, <:StiefelSubmersionMetric}, p, X)\nexp!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, q, <:StiefelSubmersionMetric}, p, X)\n\nCompute the exponential map on the Stiefel(n,k) manifold with respect to the StiefelSubmersionMetric.\n\nThe exponential map is given by\n\nexp_p X = operatornameExpbigl(\n -frac2α+1α+1 p p^mathrmT X p^mathrmT +\n X p^mathrmT - p X^mathrmT\nbigr) p operatornameExpbigl(fracalphaalpha+1 p^mathrmT Xbigr)\n\nThis implementation is based on [ZimmermanHüper2022].\n\nFor k fracn2 the exponential is computed more efficiently using StiefelFactorization.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Base.log-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, <:StiefelSubmersionMetric}, Any, Any}} where {n, k}","page":"Stiefel","title":"Base.log","text":"log(M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric}, p, q; kwargs...)\n\nCompute the logarithmic map on the Stiefel(n,k) manifold with respect to the StiefelSubmersionMetric.\n\nThe logarithmic map is computed using ShootingInverseRetraction. For k lfloorfracn2rfloor, this is sped up using the k-shooting method of [ZimmermanHüper2022]. Keyword arguments are forwarded to ShootingInverseRetraction; see that documentation for details. Their defaults are:\n\nnum_transport_points=4\ntolerance=sqrt(eps())\nmax_iterations=1_000\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, <:StiefelSubmersionMetric}, Any, Any, Any}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.inner","text":"inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, <:StiefelSubmersionMetric}, p, X, Y)\n\nCompute the inner product on the Stiefel manifold with respect to the StiefelSubmersionMetric. The formula reads\n\ng_p(XY) = operatornametrbigl( X^mathrmT(I_n - frac2α+12(α+1)pp^mathrmT)Y bigr)\n\nwhere α is the parameter of the metric.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{MetricManifold{ℝ, <:Stiefel, <:StiefelSubmersionMetric}, Any, Any, ShootingInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(\n M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric},\n p,\n q,\n method::ShootingInverseRetraction,\n)\n\nCompute the inverse retraction using ShootingInverseRetraction.\n\nIn general the retraction is computed using the generic shooting method.\n\ninverse_retract(\n M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric},\n p,\n q,\n method::ShootingInverseRetraction{\n ExponentialRetraction,\n ProjectionInverseRetraction,\n <:Union{ProjectionTransport,ScaledVectorTransport{ProjectionTransport}},\n },\n)\n\nCompute the inverse retraction using ShootingInverseRetraction more efficiently.\n\nFor k fracn2 the retraction is computed more efficiently using StiefelFactorization.\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Internal-types-and-functions","page":"Stiefel","title":"Internal types and functions","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelSubmersionMetric.jl\"]\nOrder = [:type, :function]\nPublic = false\nPrivate = true","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.StiefelFactorization","page":"Stiefel","title":"Manifolds.StiefelFactorization","text":"StiefelFactorization{UT,XT} <: AbstractManifoldPoint\n\nRepresent points (and vectors) on Stiefel(n, k) with 2k k factors.[ZimmermanHüper2022]\n\nGiven a point p mathrmSt(n k) and another matrix B ℝ^n k for k lfloorfracn2rfloor the factorization is\n\nbeginaligned\nB = UZ\nU = beginbmatrixp Qendbmatrix mathrmSt(n 2k)\nZ = beginbmatrixZ_1 Z_2endbmatrix quad Z_1Z_2 ℝ^k k\nendaligned\n\nIf B mathrmSt(n k), then Z mathrmSt(2k k). Note that not every matrix B can be factorized in this way.\n\nFor a fixed U, if r mathrmSt(n k) has the factor Z_r mathrmSt(2k k), then X_r T_r mathrmSt(n k) has the factor Z_X_r T_Z_r mathrmSt(2k k).\n\nQ is determined by choice of a second matrix A ℝ^n k with the decomposition\n\nbeginaligned\nA = UZ\nZ_1 = p^mathrmT A \nQ Z_2 = (I - p p^mathrmT) A\nendaligned\n\nwhere here Q Z_2 is the any decomposition that produces Q mathrmSt(n k), for which we choose the QR decomposition.\n\nThis factorization is useful because it is closed under addition, subtraction, scaling, projection, and the Riemannian exponential and logarithm under the StiefelSubmersionMetric. That is, if all matrices involved are factorized to have the same U, then all of these operations and any algorithm that depends only on them can be performed in terms of the 2k k matrices Z. For n k, this can be much more efficient than working with the full matrices.\n\nwarning: Warning\nThis type is intended strictly for internal use and should not be directly used.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Manifolds.stiefel_factorization-Tuple{Any, Any}","page":"Stiefel","title":"Manifolds.stiefel_factorization","text":"stiefel_factorization(p, x) -> StiefelFactorization\n\nCompute the StiefelFactorization of x relative to the point p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Literature","page":"Stiefel","title":"Literature","text":"","category":"section"},{"location":"manifolds/circle.html#Circle","page":"Circle","title":"Circle","text":"","category":"section"},{"location":"manifolds/circle.html","page":"Circle","title":"Circle","text":"Modules = [Manifolds]\nPages = [\"manifolds/Circle.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/circle.html#Manifolds.Circle","page":"Circle","title":"Manifolds.Circle","text":"Circle{𝔽} <: AbstractManifold{𝔽}\n\nThe circle 𝕊^1 is a manifold here represented by real-valued points in -ππ) or complex-valued points z ℂ of absolute value lvert zrvert = 1.\n\nConstructor\n\nCircle(𝔽=ℝ)\n\nGenerate the ℝ-valued Circle represented by angles, which alternatively can be set to use the AbstractNumbers 𝔽=ℂ to obtain the circle represented by ℂ-valued circle of unit numbers.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/circle.html#Base.exp-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"Base.exp","text":"exp(M::Circle, p, X)\n\nCompute the exponential map on the Circle.\n\nexp_p X = (p+X)_2π\n\nwhere (cdot)_2π is the (symmetric) remainder with respect to division by 2π, i.e. in -ππ).\n\nFor the complex-valued case, the same formula as for the Sphere 𝕊^1 is applied to values in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Base.log-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"Base.log","text":"log(M::Circle, p, q)\n\nCompute the logarithmic map on the Circle M.\n\nlog_p q = (q-p)_2π\n\nwhere (cdot)_2π is the (symmetric) remainder with respect to division by 2π, i.e. in -ππ).\n\nFor the complex-valued case, the same formula as for the Sphere 𝕊^1 is applied to values in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Base.rand-Tuple{Circle}","page":"Circle","title":"Base.rand","text":"Random.rand(M::Circle{ℝ}; vector_at = nothing, σ::Real=1.0)\n\nIf vector_at is nothing, return a random point on the Circle mathbb S^1 by picking a random element from -pipi) uniformly.\n\nIf vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the Circle by using a normal distribution with mean 0 and standard deviation σ.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.complex_dot-Tuple{Any, Any}","page":"Circle","title":"Manifolds.complex_dot","text":"complex_dot(a, b)\n\nCompute the inner product of two (complex) numbers with in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.manifold_volume-Tuple{Circle}","page":"Circle","title":"Manifolds.manifold_volume","text":"manifold_volume(M::Circle)\n\nReturn the volume of the Circle M, i.e. 2π.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.sym_rem-Union{Tuple{N}, Tuple{N, Any}} where N<:Number","page":"Circle","title":"Manifolds.sym_rem","text":"sym_rem(x,[T=π])\n\nCompute symmetric remainder of x with respect to the interall 2*T, i.e. (x+T)%2T, where the default for T is π\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.volume_density-Tuple{Circle, Any, Any}","page":"Circle","title":"Manifolds.volume_density","text":"volume_density(::Circle, p, X)\n\nReturn volume density of Circle, i.e. 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.check_point-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.check_point","text":"check_point(M::Circle, p)\n\nCheck whether p is a point on the Circle M. For the real-valued case, p is an angle and hence it checks that p -ππ). for the complex-valued case, it is a unit number, p ℂ with lvert p rvert = 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.check_vector-Tuple{Circle{ℝ}, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.check_vector","text":"check_vector(M::Circle, p, X; kwargs...)\n\nCheck whether X is a tangent vector in the tangent space of p on the Circle M. For the real-valued case represented by angles, all X are valid, since the tangent space is the whole real line. For the complex-valued case X has to lie on the line parallel to the tangent line at p in the complex plane, i.e. their inner product has to be zero.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.distance-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.distance","text":"distance(M::Circle, p, q)\n\nCompute the distance on the Circle M, which is the absolute value of the symmetric remainder of p and q for the real-valued case and the angle between both complex numbers in the Gaussian plane for the complex-valued case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.embed-Tuple{Circle, Any, Any}","page":"Circle","title":"ManifoldsBase.embed","text":"embed(M::Circle, p, X)\n\nEmbed a tangent vector X at p on Circle M in the ambient space. It returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.embed-Tuple{Circle, Any}","page":"Circle","title":"ManifoldsBase.embed","text":"embed(M::Circle, p)\n\nEmbed a point p on Circle M in the ambient space. It returns p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.get_coordinates-Tuple{Circle{ℂ}, Any, Any, DefaultOrthonormalBasis{<:Any, ManifoldsBase.TangentSpaceType}}","page":"Circle","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::Circle{ℂ}, p, X, B::DefaultOrthonormalBasis)\n\nReturn tangent vector coordinates in the Lie algebra of the Circle.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.get_vector_orthonormal-Tuple{Circle{ℂ}, Any, Any, ManifoldsBase.RealNumbers}","page":"Circle","title":"ManifoldsBase.get_vector_orthonormal","text":"get_vector(M::Circle{ℂ}, p, X, B::DefaultOrthonormalBasis)\n\nReturn tangent vector from the coordinates in the Lie algebra of the Circle.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.injectivity_radius-Tuple{Circle}","page":"Circle","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Circle[, p])\n\nReturn the injectivity radius on the Circle M, i.e. π.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.inner-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.inner","text":"inner(M::Circle, p, X, Y)\n\nCompute the inner product of the two tangent vectors X,Y from the tangent plane at p on the Circle M using the restriction of the metric from the embedding, i.e.\n\ng_p(XY) = X*Y\n\nfor the real case and\n\ng_p(XY) = Y^mathrmTX\n\nfor the complex case interpreting complex numbers in the Gaussian plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.is_flat-Tuple{Circle}","page":"Circle","title":"ManifoldsBase.is_flat","text":"is_flat(::Circle)\n\nReturn true. Circle is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.manifold_dimension-Tuple{Circle}","page":"Circle","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Circle)\n\nReturn the dimension of the Circle M, i.e. dim(𝕊^1) = 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.parallel_transport_to-Tuple{Circle, Any, Any, Any}","page":"Circle","title":"ManifoldsBase.parallel_transport_to","text":" parallel_transport_to(M::Circle, p, X, q)\n\nCompute the parallel transport of X from the tangent space at p to the tangent space at q on the Circle M. For the real-valued case this results in the identity. For the complex-valud case, the formula is the same as for the Sphere(1) in the complex plane.\n\nmathcal P_qp X = X - fraclog_p qX_pd^2_ℂ(pq)\nbigl(log_p q + log_q p bigr)\n\nwhere log denotes the logarithmic map on M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.project-Tuple{Circle, Any, Any}","page":"Circle","title":"ManifoldsBase.project","text":"project(M::Circle, p, X)\n\nProject a value X onto the tangent space of the point p on the Circle M.\n\nFor the real-valued case this is just the identity. For the complex valued case X is projected onto the line in the complex plane that is parallel to the tangent to p on the unit circle and contains 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.project-Tuple{Circle, Any}","page":"Circle","title":"ManifoldsBase.project","text":"project(M::Circle, p)\n\nProject a point p onto the Circle M. For the real-valued case this is the remainder with respect to modulus 2π. For the complex-valued case the result is the projection of p onto the unit circle in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Statistics.mean-Tuple{Circle{ℂ}, Any}","page":"Circle","title":"Statistics.mean","text":"mean(M::Circle{ℂ}, x::AbstractVector[, w::AbstractWeights])\n\nCompute the Riemannian mean of x of points on the Circle 𝕊^1, reprsented by complex numbers, i.e. embedded in the complex plane. Comuting the sum\n\ns = sum_i=1^n x_i\n\nthe mean is the angle of the complex number s, so represented in the complex plane as fracslvert s rvert, whenever s neq 0.\n\nIf the sum s=0, the mean is not unique. For example for opposite points or equally spaced angles.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Statistics.mean-Tuple{Circle{ℝ}, Any}","page":"Circle","title":"Statistics.mean","text":"mean(M::Circle{ℝ}, x::AbstractVector[, w::AbstractWeights])\n\nCompute the Riemannian mean of x of points on the Circle 𝕊^1, reprsented by real numbers, i.e. the angular mean\n\noperatornameatanBigl( sum_i=1^n w_isin(x_i) sum_i=1^n w_isin(x_i) Bigr)\n\n\n\n\n\n","category":"method"},{"location":"misc/about.html#About-Manifolds.jl","page":"About","title":"About Manifolds.jl","text":"","category":"section"},{"location":"misc/about.html#License","page":"About","title":"License","text":"","category":"section"},{"location":"misc/about.html","page":"About","title":"About","text":"MIT License","category":"page"},{"location":"misc/about.html#Core-Developers","page":"About","title":"Core Developers","text":"","category":"section"},{"location":"misc/about.html","page":"About","title":"About","text":"Seth Axen\nMateusz Baran\nRonny Bergmann","category":"page"},{"location":"misc/about.html#Contributors","page":"About","title":"Contributors","text":"","category":"section"},{"location":"misc/about.html","page":"About","title":"About","text":"See the GitHub contributors page.","category":"page"},{"location":"misc/about.html","page":"About","title":"About","text":"Contributions are welcome!","category":"page"},{"location":"features/testing.html#Testing","page":"Testing","title":"Testing","text":"","category":"section"},{"location":"features/testing.html","page":"Testing","title":"Testing","text":"Documentation for testing utilities for Manifolds.jl. The function test_manifold can be used to verify that your manifold correctly implements the Manifolds.jl interface. Similarly test_group and test_action can be used to verify implementation of groups and group actions.","category":"page"},{"location":"features/testing.html","page":"Testing","title":"Testing","text":"Manifolds.test_action\nManifolds.test_group\nManifolds.test_manifold\nManifolds.find_eps\nManifolds.test_parallel_transport","category":"page"},{"location":"features/testing.html#Manifolds.test_action","page":"Testing","title":"Manifolds.test_action","text":"test_action(\n A::AbstractGroupAction,\n a_pts::AbstractVector,\n m_pts::AbstractVector,\n X_pts = [];\n atol = 1e-10,\n atol_ident_compose = 0,\n test_optimal_alignment = false,\n test_mutating_group=true,\n test_mutating_action=true,\n test_diff = false,\n test_switch_direction = true,\n)\n\nTests general properties of the action A, given at least three different points that lie on it (contained in a_pts) and three different point that lie on the manifold it acts upon (contained in m_pts).\n\nArguments\n\natol_ident_compose = 0: absolute tolerance for the test that composition with identity doesn't change the group element.\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.test_group","page":"Testing","title":"Manifolds.test_group","text":"test_group(\n G,\n g_pts::AbstractVector,\n X_pts::AbstractVector = [],\n Xe_pts::AbstractVector = [];\n atol = 1e-10,\n test_mutating = true,\n test_exp_lie_log = true,\n test_diff = false,\n test_invariance = false,\n test_lie_bracket=false,\n test_adjoint_action=false,\n diff_convs = [(), (LeftForwardAction(),), (RightBackwardAction(),)],\n)\n\nTests general properties of the group G, given at least three different points elements of it (contained in g_pts). Optionally, specify test_diff to test differentials of translation, using X_pts, which must contain at least one tangent vector at g_pts[1], and the direction conventions specified in diff_convs. Xe_pts should contain tangent vectors at identity for testing Lie algebra operations. If the group is equipped with an invariant metric, test_invariance indicates that the invariance should be checked for the provided points.\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.test_manifold","page":"Testing","title":"Manifolds.test_manifold","text":"test_manifold(\n M::AbstractManifold,\n pts::AbstractVector;\n args,\n)\n\nTest general properties of manifold M, given at least three different points that lie on it (contained in pts).\n\nArguments\n\nbasis_has_specialized_diagonalizing_get = false: if true, assumes that DiagonalizingOrthonormalBasis given in basis_types has get_coordinates and get_vector that work without caching.\nbasis_types_to_from = (): basis types that will be tested based on get_coordinates and get_vector.\nbasis_types_vecs = () : basis types that will be tested based on get_vectors\ndefault_inverse_retraction_method = ManifoldsBase.LogarithmicInverseRetraction(): default method for inverse retractions (log.\ndefault_retraction_method = ManifoldsBase.ExponentialRetraction(): default method for retractions (exp).\nexp_log_atol_multiplier = 0: change absolute tolerance of exp/log tests (0 use default, i.e. deactivate atol and use rtol).\nexp_log_rtol_multiplier = 1: change the relative tolerance of exp/log tests (1 use default). This is deactivated if the exp_log_atol_multiplier is nonzero.\nexpected_dimension_type = Integer: expected type of value returned by manifold_dimension.\ninverse_retraction_methods = []: inverse retraction methods that will be tested.\nis_mutating = true: whether mutating variants of functions should be tested.\nis_point_atol_multiplier = 0: determines atol of is_point checks.\nis_tangent_atol_multiplier = 0: determines atol of is_vector checks.\nmid_point12 = test_exp_log ? shortest_geodesic(M, pts[1], pts[2], 0.5) : nothing: if not nothing, then check that mid_point(M, pts[1], pts[2]) is approximately equal to mid_point12. This is by default set to nothing if text_exp_log is set to false.\npoint_distributions = [] : point distributions to test.\nrand_tvector_atol_multiplier = 0 : chage absolute tolerance in testing random vectors (0 use default, i.e. deactivate atol and use rtol) random tangent vectors are tangent vectors.\nretraction_atol_multiplier = 0: change absolute tolerance of (inverse) retraction tests (0 use default, i.e. deactivate atol and use rtol).\nretraction_rtol_multiplier = 1: change the relative tolerance of (inverse) retraction tests (1 use default). This is deactivated if the exp_log_atol_multiplier is nonzero.\nretraction_methods = []: retraction methods that will be tested.\ntest_atlases = []: Vector or tuple of atlases that should be tested.\ntest_exp_log = true: if true, check that exp is the inverse of log.\ntest_injectivity_radius = true: whether implementation of injectivity_radius should be tested.\ntest_inplace = false : if true check if inplace variants work if they are activated, e.g. check that exp!(M, p, p, X) work if test_exp_log = true. This in general requires is_mutating to be true.\ntest_is_tangent: if true check that the default_inverse_retraction_method actually returns valid tangent vectors.\ntest_musical_isomorphisms = false : test musical isomorphisms.\ntest_mutating_rand = false : test the mutating random function for points on manifolds.\ntest_project_point = false: test projections onto the manifold.\ntest_project_tangent = false : test projections on tangent spaces.\ntest_representation_size = true : test repersentation size of points/tvectprs.\ntest_tangent_vector_broadcasting = true : test boradcasting operators on TangentSpace.\ntest_vector_spaces = true : test Vector bundle of this manifold.\ntest_default_vector_transport = false : test the default vector transport (usually parallel transport).\ntest_vee_hat = false: test vee and hat functions.\ntvector_distributions = [] : tangent vector distributions to test.\nvector_transport_methods = []: vector transport methods that should be tested.\nvector_transport_inverse_retractions = [default_inverse_retraction_method for _ in 1:length(vector_transport_methods)]` inverse retractions to use with the vector transport method (especially the differentiated ones)\nvector_transport_to = [ true for _ in 1:length(vector_transport_methods)]: whether to check the to variant of vector transport\nvector_transport_direction = [ true for _ in 1:length(vector_transport_methods)]: whether to check the direction variant of vector transport\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.find_eps","page":"Testing","title":"Manifolds.find_eps","text":"find_eps(x...)\n\nFind an appropriate tolerance for given points or tangent vectors, or their types.\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.test_parallel_transport","page":"Testing","title":"Manifolds.test_parallel_transport","text":"test_parallel_transport(M,P; along=false, to=true, diretion=true)\n\nGeneric tests for parallel transport on Mgiven at least two pointsin P.\n\nThe single functions to transport along (a curve), to (a point) or (towards a) direction are sub-tests that can be activated by the keywords arguemnts\n\n!!! Note Since the interface to specify curves is not yet provided, the along keyword does not have an effect yet\n\n\n\n\n\n","category":"function"},{"location":"misc/notation.html#Notation-overview","page":"Notation","title":"Notation overview","text":"","category":"section"},{"location":"misc/notation.html","page":"Notation","title":"Notation","text":"Since manifolds include a reasonable amount of elements and functions, the following list tries to keep an overview of used notation throughout Manifolds.jl. The order is alphabetical by name. They might be used in a plain form within the code or when referring to that code. This is for example the case with the calligraphic symbols.","category":"page"},{"location":"misc/notation.html","page":"Notation","title":"Notation","text":"Within the documented functions, the utf8 symbols are used whenever possible, as long as that renders correctly in TeX within this documentation.","category":"page"},{"location":"misc/notation.html","page":"Notation","title":"Notation","text":"Symbol Description Also used Comment\ntau_p action map by group element p mathrmL_p, mathrmR_p either left or right\noperatornameAd_p(X) adjoint action of element p of a Lie group on the element X of the corresponding Lie algebra \ntimes Cartesian product of two manifolds see ProductManifold\n^wedge (n-ary) Cartesian power of a manifold see PowerManifold\ncdot^mathrmH conjugate/Hermitian transpose \na coordinates of a point in a chart see get_parameters\nfracmathrmDmathrmdt covariant derivative of a vector field X(t) \nT^*_p mathcal M the cotangent space at p \nξ a cotangent vector from T^*_p mathcal M ξ_1 ξ_2 ηzeta sometimes written with base point ξ_p.\nmathrmdphi_p(q) Differential of a map phi mathcal M to mathcal N with respect to p at a point q. For functions of multiple variables, for example phi(p p_1) where p in mathcal M and p_1 in mathcal M_1, variable p is explicitly stated to specify with respect to which argument the differential is calculated. mathrmdphi_q, (mathrmdphi)_q, (phi_*)_q, D_pphi(q) pushes tangent vectors X in T_q mathcal M forward to mathrmdphi_p(q)X in T_phi(q) mathcal N\nn dimension (of a manifold) n_1n_2ldotsm dim(mathcal M) for the real dimension sometimes also dim_mathbb R(mathcal M)\nd(cdotcdot) (Riemannian) distance d_mathcal M(cdotcdot) \nexp_p X exponential map at p in mathcal M of a vector X in T_p mathcal M exp_p(X) \nF a fiber see VectorBundleFibers\nmathbb F a field, usually mathbb F in mathbb Rmathbb C mathbb H, i.e. the real, complex, and quaternion numbers, respectively. field a manifold or a basis is based on\ngamma a geodesic gamma_pq, gamma_pX connecting two points pq or starting in p with velocity X.\n f(p) gradient of function f colon mathcalM to mathbbR at p in mathcalM \ncirc a group operation \ncdot^mathrmH Hermitian or conjugate transposed for both complex or quaternion matrices \ne identity element of a group \nI_k identity matrix of size ktimes k \nk indices ij \nlanglecdotcdotrangle inner product (in T_p mathcal M) langlecdotcdotrangle_p g_p(cdotcdot) \noperatornameretr^-1_pq an inverse retraction \nmathfrak g a Lie algebra \nmathcalG a (Lie) group \nlog_p q logarithmic map at p in mathcal M of a point q in mathcal M log_p(q) \nmathcal M a manifold mathcal M_1 mathcal M_2ldotsmathcal N \noperatornameExp the matrix exponential \noperatornameLog the matrix logarithm \nmathcal P_qgets pX parallel transport of the vector X from T_pmathcal M to T_qmathcal M\nmathcal P_pYX parallel transport in direction Y of the vector X from T_pmathcal M to T_qmathcal M, q = exp_pY\nmathcal P_t_1gets t_0^cX parallel transport along the curve c mathcal P^cX=mathcal P_1gets 0^cX of the vector X from p=c(0) to c(1)\np a point on mathcal M p_1 p_2 ldotsq for 3 points one might use xyz\noperatornameretr_pX a retraction \nξ a set of tangent vectors X_1ldotsX_n \nT_p mathcal M the tangent space at p \nX a tangent vector from T_p mathcal M X_1X_2ldotsYZ sometimes written with base point X_p\noperatornametr trace (of a matrix) \ncdot^mathrmT transposed \ne_i in mathbb R^n the ith unit vector e_i^n the space dimension (n) is omited, when clear from context\nB a vector bundle \nmathcal T_qgets pX vector transport of the vector X from T_pmathcal M to T_qmathcal M\nmathcal T_pYX vector transport in direction Y of the vector X from T_pmathcal M to T_qmathcal M, where q is deretmined by Y, for example using the exponential map or some retraction.\noperatornameVol(mathcal M) volume of manifold mathcal M \ntheta_p(X) volume density for vector X tangent at point p \n0_k the ktimes k zero matrix. ","category":"page"},{"location":"manifolds/symmetricpsdfixedrank.html#Symmetric-Positive-Semidefinite-Matrices-of-Fixed-Rank","page":"Symmetric positive semidefinite fixed rank","title":"Symmetric Positive Semidefinite Matrices of Fixed Rank","text":"","category":"section"},{"location":"manifolds/symmetricpsdfixedrank.html","page":"Symmetric positive semidefinite fixed rank","title":"Symmetric positive semidefinite fixed rank","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveSemidefiniteFixedRank.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpsdfixedrank.html#Manifolds.SymmetricPositiveSemidefiniteFixedRank","page":"Symmetric positive semidefinite fixed rank","title":"Manifolds.SymmetricPositiveSemidefiniteFixedRank","text":"SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe AbstractManifold $ \\operatorname{SPS}_k(n)$ consisting of the real- or complex-valued symmetric positive semidefinite matrices of size n n and rank k, i.e. the set\n\noperatornameSPS_k(n) = bigl\np 𝔽^n n big p^mathrmH = p\napa^mathrmH geq 0 text for all a 𝔽\ntext and operatornamerank(p) = kbigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ. We sometimes operatornameSPS_k𝔽(n), when distinguishing the real- and complex-valued manifold is important.\n\nAn element is represented by q 𝔽^n k from the factorization p = qq^mathrmH. Note that since for any unitary (orthogonal) A 𝔽^n n we have (Aq)(Aq)^mathrmH = qq^mathrmH = p, the representation is not unique, or in other words, the manifold is a quotient manifold of 𝔽^n k.\n\nThe tangent space at p, T_poperatornameSPS_k(n), is also represented by matrices Y 𝔽^n k and reads as\n\nT_poperatornameSPS_k(n) = bigl\nX 𝔽^n nX = qY^mathrmH + Yq^mathrmH\ntext ie X = X^mathrmH\nbigr\n\nNote that the metric used yields a non-complete manifold. The metric was used in[JourneeBachAbsilSepulchre2010][MassartAbsil2020].\n\nConstructor\n\nSymmetricPositiveSemidefiniteFixedRank(n::Int, k::Int, field::AbstractNumbers=ℝ)\n\nGenerate the manifold of n n symmetric positive semidefinite matrices of rank k over the field of real numbers ℝ or complex numbers ℂ.\n\n[JourneeBachAbsilSepulchre2010]: Journée, M., Bach, F., Absil, P.-A., and Sepulchre, R.: “Low-Rank Optimization on the Cone of Positive Semidefinite Matrices”, SIAM Journal on Optimization (20)5, pp. 2327–2351, 2010. doi: 10.1137/080731359, arXiv: 0807.4423.\n\n[MassartAbsil2020]: Massart, E., Absil, P.-A.: \"Quotient Geometry with Simple Geodesics for the AbstractManifold of Fixed-Rank Positive-Semidefinite Matrices\", SIAM Journal on Matrix Analysis and Applications (41)1, pp. 171–198, 2020. doi: 10.1137/18m1231389, preprint: sites.uclouvain.be/absil/2018.06.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpsdfixedrank.html#Base.exp-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"Base.exp","text":"exp(M::SymmetricPositiveSemidefiniteFixedRank, q, Y)\n\nCompute the exponential map on the SymmetricPositiveSemidefiniteFixedRank, which just reads\n\n exp_q Y = q+Y\n\nnote: Note\nSince the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing q_2 = exp_p(log_pq)might yield a matrix q_2neq q, but they represent the same point on the quotient manifold, i.e. d_operatornameSPS_k(n)(q_2q) = 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#Base.log-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"Base.log","text":"log(M::SymmetricPositiveSemidefiniteFixedRank, q, p)\n\nCompute the logarithmic map on the SymmetricPositiveSemidefiniteFixedRank manifold by minimizing lVert p - qYrVert with respect to Y.\n\nnote: Note\nSince the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing q_2 = exp_p(log_pq)might yield a matrix q_2neq q, but they represent the same point on the quotient manifold, i.e. d_operatornameSPS_k(n)(q_2q) = 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase._isapprox-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase._isapprox","text":"isapprox(M::SymmetricPositiveSemidefiniteFixedRank, p, q; kwargs...)\n\ntest, whether two points p, q are (approximately) nearly the same. Since this is a quotient manifold in the embedding, the test is performed by checking their distance, if they are not the same, i.e. that d_mathcal M(pq) approx 0, where the comparison is performed with the classical isapprox. The kwargs... are passed on to this accordingly.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{SymmetricPositiveSemidefiniteFixedRank{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.check_point","text":"check_point(M::SymmetricPositiveSemidefiniteFixedRank{n,𝔽}, q; kwargs...)\n\nCheck whether q is a valid manifold point on the SymmetricPositiveSemidefiniteFixedRank M, i.e. whether p=q*q' is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽. The symmetry of p is not explicitly checked since by using q p is symmetric by construction. The tolerance for the symmetry of p can and the rank of q*q' be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.check_vector-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.check_vector","text":"check_vector(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SymmetricPositiveSemidefiniteFixedRank M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.\n\nDue to the reduced representation this is fulfilled as soon as the matrix is of correct size.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.distance-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.distance","text":"distance(M::SymmetricPositiveSemidefiniteFixedRank, p, q)\n\nCompute the distance between two points p, q on the SymmetricPositiveSemidefiniteFixedRank, which is the Frobenius norm of Y which minimizes lVert p - qYrVert with respect to Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.is_flat-Tuple{SymmetricPositiveSemidefiniteFixedRank}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.is_flat","text":"is_flat(::SymmetricPositiveSemidefiniteFixedRank)\n\nReturn false. SymmetricPositiveSemidefiniteFixedRank is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.manifold_dimension-Tuple{SymmetricPositiveSemidefiniteFixedRank}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽})\n\nReturn the dimension of the SymmetricPositiveSemidefiniteFixedRank matrix M over the number system 𝔽, i.e.\n\nbeginaligned\ndim operatornameSPS_kℝ(n) = kn - frack(k-1)2\ndim operatornameSPS_kℂ(n) = 2kn - k^2\nendaligned\n\nwhere the last k^2 is due to the zero imaginary part for Hermitian matrices diagonal\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.vector_transport_to-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any, Any, ProjectionTransport}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::SymmetricPositiveSemidefiniteFixedRank, p, X, q)\n\ntransport the tangent vector X at p to q by projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.zero_vector-Tuple{SymmetricPositiveSemidefiniteFixedRank, Vararg{Any}}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.zero_vector","text":" zero_vector(M::SymmetricPositiveSemidefiniteFixedRank, p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the SymmetricPositiveSemidefiniteFixedRank manifold M.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#atlases_and_charts","page":"Atlases and charts","title":"Atlases and charts","text":"","category":"section"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Atlases on an n-dimensional manifold mathcal M are collections of charts mathcal A = (U_i φ_i) colon i in I, where I is a (finite or infinte) index family, such that U_i subseteq mathcal M is an open set and each chart φ_i U_i to mathbbR^n is a homeomorphism. This means, that φ_i is bijective – sometimes also called one-to-one and onto - and continuous, and its inverse φ_i^-1 is continuous as well. The inverse φ_i^-1 is called (local) parametrization. The resulting parameters a=φ(p) of p (with respect to the chart φ) are in the literature also called “(local) coordinates”. To distinguish the parameter a from get_coordinates in a basis, we use the terminology parameter in this package.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"For an atlas mathcal A we further require that","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"displaystylebigcup_iin I U_i = mathcal M","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"We say that φ_i is a chart about p, if pin U_i. An atlas provides a connection between a manifold and the Euclidean space mathbbR^n, since locally, a chart about p can be used to identify its neighborhood (as long as you stay in U_i) with a subset of a Euclidean space. Most manifolds we consider are smooth, i.e. any change of charts φ_i circ φ_j^-1 mathbbR^ntomathbbR^n, where ijin I, is a smooth function. These changes of charts are also called transition maps.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Most operations on manifolds in Manifolds.jl avoid operating in a chart through appropriate embeddings and formulas derived for particular manifolds, though atlases provide the most general way of working with manifolds. Compared to these approaches, using an atlas is often more technical and time-consuming. They are extensively used in metric-related functions on MetricManifolds.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Atlases are represented by objects of subtypes of AbstractAtlas. There are no type restrictions for indices of charts in atlases.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Operations using atlases and charts are available through the following functions:","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"get_chart_index can be used to select an appropriate chart for the neighborhood of a given point p. This function should work deterministically, i.e. for a fixed p always return the same chart.\nget_parameters converts a point to its parameters with respect to the chart in a chart.\nget_point converts parameters (local coordinates) in a chart to the point that corresponds to them.\ninduced_basis returns a basis of a given vector space at a point induced by a chart φ.\ntransition_map converts coordinates of a point between two charts, e.g. computes φ_icirc φ_j^-1 mathbbR^ntomathbbR^n, ijin I.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"While an atlas could store charts as explicit functions, it is favourable, that the [get_parameters] actually implements a chart φ, get_point its inverse, the prametrization φ^-1.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Modules = [Manifolds,ManifoldsBase]\nPages = [\"atlases.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/atlases.html#Manifolds.AbstractAtlas","page":"Atlases and charts","title":"Manifolds.AbstractAtlas","text":"AbstractAtlas{𝔽}\n\nAn abstract class for atlases whith charts that have values in the vector space 𝔽ⁿ for some value of n. 𝔽 is a number system determined by an AbstractNumbers object.\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.InducedBasis","page":"Atlases and charts","title":"Manifolds.InducedBasis","text":"InducedBasis(vs::VectorSpaceType, A::AbstractAtlas, i)\n\nThe basis induced by chart with index i from an AbstractAtlas A of vector space of type vs.\n\nFor the vs a TangentSpace this works as follows:\n\nLet n denote the dimension of the manifold mathcal M.\n\nLet the parameter a=φ_i(p) mathbb R^n and j1n. We can look at the jth parameter curve b_j(t) = a + te_j, where e_j denotes the jth unit vector. Using the parametrisation we obtain a curve c_j(t) = φ_i^-1(b_j(t)) which fulfills c(0) = p.\n\nNow taking the derivative(s) with respect to t (and evaluate at t=0), we obtain a tangent vector for each j corresponding to an equivalence class of curves (having the same derivative) as\n\nX_j = c_j = fracmathrmdmathrmdt c_i(t) Bigl_t=0\n\nand the set X_1ldotsX_n is the chart-induced basis of T_pmathcal M.\n\nSee also\n\nVectorSpaceType, AbstractBasis\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.RetractionAtlas","page":"Atlases and charts","title":"Manifolds.RetractionAtlas","text":"RetractionAtlas{\n 𝔽,\n TRetr<:AbstractRetractionMethod,\n TInvRetr<:AbstractInverseRetractionMethod,\n TBasis<:AbstractBasis,\n} <: AbstractAtlas{𝔽}\n\nAn atlas indexed by points on a manifold, mathcal M = I and parameters (local coordinates) are given in T_pmathcal M. This means that a chart φ_p = mathrmcordcircmathrmretr_p^-1 is only locally defined (around p), where mathrmcord is the decomposition of the tangent vector into coordinates with respect to the given basis of the tangent space, cf. get_coordinates. The parametrization is given by φ_p^-1=mathrmretr_pcircmathrmvec, where mathrmvec turns the basis coordinates into a tangent vector, cf. get_vector.\n\nIn short: The coordinates with respect to a basis are used together with a retraction as a parametrization.\n\nSee also\n\nAbstractAtlas, AbstractInverseRetractionMethod, AbstractRetractionMethod, AbstractBasis\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#LinearAlgebra.norm-Tuple{AbstractManifold, AbstractAtlas, Any, Any, Any}","page":"Atlases and charts","title":"LinearAlgebra.norm","text":"norm(M::AbstractManifold, A::AbstractAtlas, i, a, Xc)\n\nCalculate norm on manifold M at point with parameters a in chart i of an AbstractAtlas A of vector with coefficients Xc in induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.affine_connection!-Tuple{AbstractManifold, Any, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"Manifolds.affine_connection!","text":"affine_connection!(M::AbstractManifold, Zc, A::AbstractAtlas, i, a, Xc, Yc)\n\nCalculate affine connection on manifold M at point with parameters a in chart i of an an AbstractAtlas A of vectors with coefficients Zc and Yc in induced basis and save the result in Zc.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.affine_connection-Tuple{AbstractManifold, Vararg{Any, 5}}","page":"Atlases and charts","title":"Manifolds.affine_connection","text":"affine_connection(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)\n\nCalculate affine connection on manifold M at point with parameters a in chart i of AbstractAtlas A of vectors with coefficients Xc and Yc in induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.check_chart_switch-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.check_chart_switch","text":"check_chart_switch(M::AbstractManifold, A::AbstractAtlas, i, a)\n\nDetermine whether chart should be switched when an operation in chart i from an AbstractAtlas A reaches parameters a in that chart.\n\nBy default false is returned.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_chart_index-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.get_chart_index","text":"get_chart_index(M::AbstractManifold, A::AbstractAtlas, i, a)\n\nSelect a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point with parametrization a in chart i. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.\n\nSee also\n\nget_default_atlas\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_chart_index-Tuple{AbstractManifold, AbstractAtlas, Any}","page":"Atlases and charts","title":"Manifolds.get_chart_index","text":"get_chart_index(M::AbstractManifold, A::AbstractAtlas, p)\n\nSelect a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point p. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.\n\nSee also\n\nget_default_atlas\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_default_atlas-Tuple{AbstractManifold}","page":"Atlases and charts","title":"Manifolds.get_default_atlas","text":"get_default_atlas(::AbstractManifold)\n\nDetermine the default real-valued atlas for the given manifold.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_parameters-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.get_parameters","text":"get_parameters(M::AbstractManifold, A::AbstractAtlas, i, p)\n\nCalculate parameters (local coordinates) of point p on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the chart φ_i(p) iin I. The parameters are in the number system determined by A. If the point pnotin U_i is not in the domain of the chart, this method should throw an error.\n\nSee also\n\nget_point, get_chart_index\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_point-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.get_point","text":"get_point(M::AbstractManifold, A::AbstractAtlas, i, a)\n\nCalculate point at parameters (local coordinates) a on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the inverse φ_i^-1(a) iin I of a chart, also called a parametrization.\n\nSee also\n\nget_parameters, get_chart_index\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.induced_basis-Tuple{AbstractManifold, AbstractAtlas, Any, VectorSpaceType}","page":"Atlases and charts","title":"Manifolds.induced_basis","text":"induced_basis(M::AbstractManifold, A::AbstractAtlas, i, p, VST::VectorSpaceType)\n\nBasis of vector space of type VST at point p from manifold M induced by chart (A, i).\n\nSee also\n\nVectorSpaceType, AbstractAtlas\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.induced_basis-Union{Tuple{𝔽}, Tuple{AbstractManifold{𝔽}, AbstractAtlas, Any}, Tuple{AbstractManifold{𝔽}, AbstractAtlas, Any, VectorSpaceType}} where 𝔽","page":"Atlases and charts","title":"Manifolds.induced_basis","text":"induced_basis(::AbstractManifold, A::AbstractAtlas, i, VST::VectorSpaceType = TangentSpace)\n\nGet the basis induced by chart with index i from an AbstractAtlas A of vector space of type vs. Returns an object of type InducedBasis.\n\nSee also\n\nVectorSpaceType, AbstractBasis\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.inverse_chart_injectivity_radius-Tuple{AbstractManifold, AbstractAtlas, Any}","page":"Atlases and charts","title":"Manifolds.inverse_chart_injectivity_radius","text":"inverse_chart_injectivity_radius(M::AbstractManifold, A::AbstractAtlas, i)\n\nInjectivity radius of get_point for chart i from an AbstractAtlas A of a manifold M.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.local_metric-Tuple{AbstractManifold, Any, InducedBasis}","page":"Atlases and charts","title":"Manifolds.local_metric","text":"local_metric(M::AbstractManifold, p, B::InducedBasis)\n\nCompute the local metric tensor for vectors expressed in terms of coordinates in basis B on manifold M. The point p is not checked.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.transition_map-Tuple{AbstractManifold, AbstractAtlas, Any, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.transition_map","text":"transition_map(M::AbstractManifold, A_from::AbstractAtlas, i_from, A_to::AbstractAtlas, i_to, a)\ntransition_map(M::AbstractManifold, A::AbstractAtlas, i_from, i_to, a)\n\nGiven coordinates a in chart (A_from, i_from) of a point on manifold M, returns coordinates of that point in chart (A_to, i_to). If A_from and A_to are equal, A_to can be omitted.\n\nMathematically this function is the transition map or change of charts, but it might even be between two atlases A_textfrom = (U_iφ_i)_iin I and A_textto = (V_jpsi_j)_jin J, and hence I J are their index sets. We have i_textfromin I, i_texttoin J.\n\nThis method then computes\n\nbigl(psi_i_texttocirc φ_i_textfrom^-1bigr)(a)\n\nNote that, similarly to get_parameters, this method should fail the same way if V_i_texttocap U_i_textfrom=emptyset.\n\nSee also\n\nAbstractAtlas, get_parameters, get_point\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.transition_map_diff!-Tuple{AbstractManifold, Any, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"Manifolds.transition_map_diff!","text":"transition_map_diff!(M::AbstractManifold, c_out, A::AbstractAtlas, i_from, a, c, i_to)\n\nCompute transition_map_diff on given arguments and save the result in c_out.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.transition_map_diff-Tuple{AbstractManifold, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"Manifolds.transition_map_diff","text":"transition_map_diff(M::AbstractManifold, A::AbstractAtlas, i_from, a, c, i_to)\n\nCompute differential of transition map from chart i_from to chart i_to from an AbstractAtlas A on manifold M at point with parameters a on tangent vector with coordinates c in the induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#ManifoldsBase.inner-Tuple{AbstractManifold, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"ManifoldsBase.inner","text":"inner(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)\n\nCalculate inner product on manifold M at point with parameters a in chart i of an atlas A of vectors with coefficients Xc and Yc in induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Cotangent-space-and-musical-isomorphisms","page":"Atlases and charts","title":"Cotangent space and musical isomorphisms","text":"","category":"section"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Related to atlases, there is also support for the cotangent space and coefficients of cotangent vectors in bases of the cotangent space.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Functions sharp and flat implement musical isomorphisms for arbitrary vector bundles.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Modules = [Manifolds,ManifoldsBase]\nPages = [\"cotangent_space.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/atlases.html#Manifolds.RieszRepresenterCotangentVector","page":"Atlases and charts","title":"Manifolds.RieszRepresenterCotangentVector","text":"RieszRepresenterCotangentVector(M::AbstractManifold, p, X)\n\nCotangent vector in Riesz representer form on manifold M at point p with Riesz representer X.\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.flat-Tuple{AbstractManifold, Any, Any}","page":"Atlases and charts","title":"Manifolds.flat","text":"flat(M::AbstractManifold, p, X)\n\nCompute the flat isomorphism (one of the musical isomorphisms) of tangent vector X from the vector space of type M at point p from the underlying AbstractManifold.\n\nThe function can be used for example to transform vectors from the tangent bundle to vectors from the cotangent bundle Tmathcal M T^*mathcal M\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.sharp-Tuple{AbstractManifold, Any, Any}","page":"Atlases and charts","title":"Manifolds.sharp","text":"sharp(M::AbstractManifold, p, ξ)\n\nCompute the sharp isomorphism (one of the musical isomorphisms) of vector ξ from the vector space M at point p from the underlying AbstractManifold.\n\nThe function can be used for example to transform vectors from the cotangent bundle to vectors from the tangent bundle T^*mathcal M Tmathcal M\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Computations-in-charts","page":"Atlases and charts","title":"Computations in charts","text":"","category":"section"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Manifolds.IntegratorTerminatorNearChartBoundary\nManifolds.estimate_distance_from_bvp\nManifolds.solve_chart_exp_ode\nManifolds.solve_chart_log_bvp\nManifolds.solve_chart_parallel_transport_ode","category":"page"},{"location":"features/atlases.html#Manifolds.IntegratorTerminatorNearChartBoundary","page":"Atlases and charts","title":"Manifolds.IntegratorTerminatorNearChartBoundary","text":"IntegratorTerminatorNearChartBoundary{TKwargs}\n\nAn object for determining the point at which integration of a differential equation in a chart on a manifold should be terminated for the purpose of switching a chart.\n\nThe value stored in check_chart_switch_kwargs will be passed as keyword arguments to check_chart_switch. By default an empty tuple is stored.\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.estimate_distance_from_bvp","page":"Atlases and charts","title":"Manifolds.estimate_distance_from_bvp","text":"estimate_distance_from_bvp(\n M::AbstractManifold,\n a1,\n a2,\n A::AbstractAtlas,\n i;\n solver=GeneralMIRK4(),\n dt=0.05,\n kwargs...,\n)\n\nEstimate distance between points on AbstractManifold M with parameters a1 and a2 in chart i of AbstractAtlas A using solver solver, employing solve_chart_log_bvp to solve the geodesic BVP.\n\n\n\n\n\n","category":"function"},{"location":"features/atlases.html#Manifolds.solve_chart_exp_ode","page":"Atlases and charts","title":"Manifolds.solve_chart_exp_ode","text":"solve_chart_exp_ode(\n M::AbstractManifold,\n a,\n Xc,\n A::AbstractAtlas,\n i0;\n solver=AutoVern9(Rodas5()),\n final_time=1.0,\n check_chart_switch_kwargs=NamedTuple(),\n kwargs...,\n)\n\nSolve geodesic ODE on a manifold M from point of coordinates a in chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.\n\n\n\n\n\n","category":"function"},{"location":"features/atlases.html#Manifolds.solve_chart_log_bvp","page":"Atlases and charts","title":"Manifolds.solve_chart_log_bvp","text":"solve_chart_log_bvp(\n M::AbstractManifold,\n a1,\n a2,\n A::AbstractAtlas,\n i;\n solver=GeneralMIRK4(),\n dt=0.05,\n kwargs...,\n)\n\nSolve the BVP corresponding to geodesic calculation on AbstractManifold M, between points with parameters a1 and a2 in a chart i of an AbstractAtlas A using solver solver. Geodesic γ is sampled at time interval dt, with γ(0) = a1 and γ(1) = a2.\n\n\n\n\n\n","category":"function"},{"location":"features/atlases.html#Manifolds.solve_chart_parallel_transport_ode","page":"Atlases and charts","title":"Manifolds.solve_chart_parallel_transport_ode","text":"solve_chart_parallel_transport_ode(\n M::AbstractManifold,\n a,\n Xc,\n A::AbstractAtlas,\n i0,\n Yc;\n solver=AutoVern9(Rodas5()),\n check_chart_switch_kwargs=NamedTuple(),\n final_time=1.0,\n kwargs...,\n)\n\nParallel transport vector with coordinates Yc along geodesic on a manifold M from point of coordinates a in a chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.\n\n\n\n\n\n","category":"function"},{"location":"features/differentiation.html#Differentiation","page":"Differentiation","title":"Differentiation","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Documentation for Manifolds.jl's methods and types for finite differences and automatic differentiation.","category":"page"},{"location":"features/differentiation.html#Differentiation-backends","page":"Differentiation","title":"Differentiation backends","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/differentiation.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Further differentiation backends and features are available in ManifoldDiff.jl.","category":"page"},{"location":"features/differentiation.html#FiniteDifferenes.jl","page":"Differentiation","title":"FiniteDifferenes.jl","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/finite_differences.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"features/differentiation.html#Riemannian-differentiation-backends","page":"Differentiation","title":"Riemannian differentiation backends","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/riemannian_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/embedded_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"manifolds/flag.html#Flag-manifold","page":"Flag","title":"Flag manifold","text":"","category":"section"},{"location":"manifolds/flag.html","page":"Flag","title":"Flag","text":"Modules = [Manifolds]\nPages = [\"manifolds/Flag.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/flag.html#Manifolds.Flag","page":"Flag","title":"Manifolds.Flag","text":"Flag{N,d} <: AbstractDecoratorManifold{ℝ}\n\nFlag manifold of d subspaces of ℝ^N[YeWongLim2022]. By default the manifold uses the Stiefel coordinates representation, embedding it in the Stiefel manifold. The other available representation is an embedding in OrthogonalMatrices. It can be utilized using OrthogonalPoint and OrthogonalTVector wrappers.\n\nTangent space is represented in the block-skew-symmetric form.\n\nConstructor\n\nFlag(N, n1, n2, ..., nd)\n\nGenerate the manifold operatornameFlag(n_1 n_2 n_d N) of subspaces\n\n𝕍_1 𝕍_2 V_d quad operatornamedim(𝕍_i) = n_i\n\nwhere 𝕍_i for i 1 2 d are subspaces of ℝ^N of dimension operatornamedim 𝕍_i = n_i.\n\n[YeWongLim2022]: K. Ye, K. S.-W. Wong, and L.-H. Lim, “Optimization on flag manifolds,” Math. Program., vol. 194, no. 1, pp. 621–660, Jul. 2022, doi: 10.1007/s10107-021-01640-3.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Manifolds.OrthogonalPoint","page":"Flag","title":"Manifolds.OrthogonalPoint","text":"OrthogonalPoint <: AbstractManifoldPoint\n\nA type to represent points on a manifold Flag in the orthogonal coordinates representation, i.e. a rotation matrix.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Manifolds.OrthogonalTVector","page":"Flag","title":"Manifolds.OrthogonalTVector","text":"OrthogonalTVector <: TVector\n\nA type to represent tangent vectors to points on a Flag manifold in the orthogonal coordinates representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Manifolds.ZeroTuple","page":"Flag","title":"Manifolds.ZeroTuple","text":"ZeroTuple\n\nInternal structure for representing shape of a Flag manifold. Behaves like a normal tuple, except at index zero returns value 0.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{AbstractMatrix}, Flag, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector}","page":"Flag","title":"Base.convert","text":"convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)\n\nConvert tangent vector from Flag manifold M from orthogonal representation to Stiefel representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{AbstractMatrix}, Flag, Manifolds.OrthogonalPoint}","page":"Flag","title":"Base.convert","text":"convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint)\n\nConvert point p from Flag manifold M from orthogonal representation to Stiefel representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{Manifolds.OrthogonalPoint}, Flag, AbstractMatrix}","page":"Flag","title":"Base.convert","text":"convert(::Type{OrthogonalPoint}, M::Flag, p::AbstractMatrix)\n\nConvert point p from Flag manifold M from Stiefel representation to orthogonal representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{Manifolds.OrthogonalTVector}, Flag, AbstractMatrix, AbstractMatrix}","page":"Flag","title":"Base.convert","text":"convert(::Type{OrthogonalTVector}, M::Flag, p::AbstractMatrix, X::AbstractMatrix)\n\nConvert tangent vector from Flag manifold M from Stiefel representation to orthogonal representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.get_embedding-Union{Tuple{Flag{N, dp1}}, Tuple{dp1}, Tuple{N}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::Flag)\n\nGet the embedding of the Flag manifold M, i.e. the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.injectivity_radius-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Flag)\ninjectivity_radius(M::Flag, p)\n\nReturn the injectivity radius on the Flag M, which is fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.manifold_dimension-Union{Tuple{Flag{N, dp1}}, Tuple{dp1}, Tuple{N}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Flag)\n\nReturn dimension of flag manifold operatornameFlag(n_1 n_2 n_d N). The formula reads sum_i=1^d (n_i-n_i-1)(N-n_i).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#The-flag-manifold-represented-as-points-on-the-[Stiefel](@ref)-manifold","page":"Flag","title":"The flag manifold represented as points on the Stiefel manifold","text":"","category":"section"},{"location":"manifolds/flag.html","page":"Flag","title":"Flag","text":"Modules = [Manifolds]\nPages = [\"manifolds/FlagStiefel.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/flag.html#ManifoldsBase.check_vector-Union{Tuple{dp1}, Tuple{N}, Tuple{Flag{N, dp1}, AbstractMatrix, AbstractMatrix}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.check_vector","text":"check_vector(M::Flag, p::AbstractMatrix, X::AbstractMatrix; kwargs... )\n\nCheck whether X is a tangent vector to point p on the Flag manifold M operatornameFlag(n_1 n_2 n_d N) in the Stiefel representation, i.e. that X is a matrix of the form\n\nX = beginbmatrix\n0 B_12 cdots B_1d \n-B_12^mathrmT 0 cdots B_2d \nvdots vdots ddots vdots \n-B_1d^mathrmT -B_2d^mathrmT cdots 0 \n-B_1d+1^mathrmT -B_2d+1^mathrmT cdots -B_dd+1^mathrmT\nendbmatrix\n\nwhere B_ij ℝ^(n_i - n_i-1) (n_j - n_j-1), for 1 i j d+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.default_inverse_retraction_method-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.default_inverse_retraction_method","text":"default_inverse_retraction_method(M::Flag)\n\nReturn PolarInverseRetraction as the default inverse retraction for the Flag manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.default_retraction_method-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Flag)\n\nReturn PolarRetraction as the default retraction for the Flag manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.default_vector_transport_method-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::Flag)\n\nReturn the ProjectionTransport as the default vector transport method for the Flag manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.inverse_retract-Tuple{Flag, Any, Any, PolarInverseRetraction}","page":"Flag","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Flag, p, q, ::PolarInverseRetraction)\n\nCompute the inverse retraction for the PolarRetraction, on the Flag manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.project-Tuple{Flag, Any, Any}","page":"Flag","title":"ManifoldsBase.project","text":"project(::Flag, p, X)\n\nProject vector X in the Euclidean embedding to the tangent space at point p on Flag manifold. The formula reads[YeWongLim2022]:\n\nY_i = X_i - (p_i p_i^mathrmT) X_i + sum_j neq i p_j X_j^mathrmT p_i\n\nfor i from 1 to d where the resulting vector is Y = Y_1 Y_2 Y_d and X = X_1 X_2 X_d, p = p_1 p_2 p_d are decompositions into basis vector matrices for consecutive subspaces of the flag.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.retract-Tuple{Flag, Any, Any, PolarRetraction}","page":"Flag","title":"ManifoldsBase.retract","text":"retract(M::Flag, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the Flag M. With USV = p + X the retraction reads\n\noperatornameretr_p X = UV^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#The-flag-manifold-represented-as-orthogonal-matrices","page":"Flag","title":"The flag manifold represented as orthogonal matrices","text":"","category":"section"},{"location":"manifolds/flag.html","page":"Flag","title":"Flag","text":"Modules = [Manifolds]\nPages = [\"manifolds/FlagOrthogonal.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/flag.html#ManifoldsBase.check_vector-Union{Tuple{dp1}, Tuple{N}, Tuple{Flag{N, dp1}, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.check_vector","text":"check_vector(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector; kwargs... )\n\nCheck whether X is a tangent vector to point p on the Flag manifold M operatornameFlag(n_1 n_2 n_d N) in the orthogonal matrix representation, i.e. that X is block-skew-symmetric with zero diagonal:\n\nX = beginbmatrix\n0 B_12 cdots B_1d+1 \n-B_12^mathrmT 0 cdots B_2d+1 \nvdots vdots ddots vdots \n-B_1d+1^mathrmT -B_2d+1^mathrmT cdots 0 \nendbmatrix\n\nwhere B_ij ℝ^(n_i - n_i-1) (n_j - n_j-1), for 1 i j d+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.get_embedding-Union{Tuple{N}, Tuple{Flag{N}, Manifolds.OrthogonalPoint}} where N","page":"Flag","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::Flag, p::OrthogonalPoint)\n\nGet embedding of Flag manifold M, i.e. the manifold OrthogonalMatrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.project-Union{Tuple{dp1}, Tuple{N}, Tuple{Flag{N, dp1}, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.project","text":"project(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)\n\nProject vector X to tangent space at point p from Flag manifold M operatornameFlag(n_1 n_2 n_d N), in the orthogonal matrix representation. It works by first projecting X to the space of SkewHermitianMatrices and then setting diagonal blocks to 0:\n\nX = beginbmatrix\n0 B_12 cdots B_1d+1 \n-B_12^mathrmT 0 cdots B_2d+1 \nvdots vdots ddots vdots \n-B_1d+1^mathrmT -B_2d+1^mathrmT cdots 0 \nendbmatrix\n\nwhere B_ij ℝ^(n_i - n_i-1) (n_j - n_j-1), for 1 i j d+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.retract-Tuple{Flag, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector, QRRetraction}","page":"Flag","title":"ManifoldsBase.retract","text":"retract(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector, ::QRRetraction)\n\nCompute the QR retraction on the Flag in the orthogonal matrix representation as the first order approximation to the exponential map. Similar to QR retraction for [GeneralUnitaryMatrices].\n\n\n\n\n\n","category":"method"},{"location":"tutorials/working-in-charts.html#Working-in-charts","page":"work in charts","title":"Working in charts","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"In this tutorial we will learn how to use charts for basic geometric operations like exponential map, logarithmic map and parallel transport.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"There are two conceptually different approaches to working on a manifold: working in charts and chart-free representations.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The first one, widespread in differential geometry textbooks, is based on defining an atlas on the manifold and performing computations in selected charts. This approach, while generic, is not ideally suitable in all circumstances. For example, working in charts that do not cover the entire manifold causes issues with having to switch charts when operating on a manifold.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The second one is beneficital, if there exist a representation of points and tangent vectors for a manifold, which allow for efficient closed-form formulas for standard functions like the exponential map or Riemannian distance in this representation. These computations are then chart-free. Manifolds.jl supports both approaches, although the chart-free approach is the main focus of the library.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"In this tutorial we focus on chart-based computation.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"using Manifolds, RecursiveArrayTools, OrdinaryDiffEq, DiffEqCallbacks, BoundaryValueDiffEq","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The manifold we consider is the M is the torus in form of the EmbeddedTorus, that is the representation defined as a surface of revolution of a circle of radius 2 around a circle of radius 3. The atlas we will perform computations in is its DefaultTorusAtlas A, consistting of a family of charts indexed by two angles, that specify the base point of the chart.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We will draw geodesics time between 0 and t_end, and then sample the solution at multiples of dt and draw a line connecting sampled points.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"M = Manifolds.EmbeddedTorus(3, 2)\nA = Manifolds.DefaultTorusAtlas()","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"Manifolds.DefaultTorusAtlas()","category":"page"},{"location":"tutorials/working-in-charts.html#Setup","page":"work in charts","title":"Setup","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We will first set up our plot with an empty torus. param_points are points on the surface of the torus that will be used for basic surface shape in Makie.jl. The torus will be colored according to its Gaussian curvature stored in gcs. We later want to have a color scale that has negative curvature blue, zero curvature white and positive curvature red so gcs_mm is the largest absolute value of the curvature that will be needed to properly set range of curvature values.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"In the documentation this tutorial represents a static situation (without interactivity). Makie.jl rendering is turned off.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"# using GLMakie, Makie\n# GLMakie.activate!()\n\n\"\"\"\n torus_figure()\n\nThis function generates a simple plot of a torus and returns the new figure containing the plot.\n\"\"\"\nfunction torus_figure()\n fig = Figure(resolution=(1400, 1000), fontsize=16)\n ax = LScene(fig[1, 1], show_axis=true)\n ϴs, φs = LinRange(-π, π, 50), LinRange(-π, π, 50)\n param_points = [Manifolds._torus_param(M, θ, φ) for θ in ϴs, φ in φs]\n X1, Y1, Z1 = [[p[i] for p in param_points] for i in 1:3]\n gcs = [gaussian_curvature(M, p) for p in param_points]\n gcs_mm = max(abs(minimum(gcs)), abs(maximum(gcs)))\n pltobj = surface!(\n ax,\n X1,\n Y1,\n Z1;\n shading=true,\n ambient=Vec3f(0.65, 0.65, 0.65),\n backlight=1.0f0,\n color=gcs,\n colormap=Reverse(:RdBu),\n colorrange=(-gcs_mm, gcs_mm),\n transparency=true,\n )\n wireframe!(ax, X1, Y1, Z1; transparency=true, color=:gray, linewidth=0.5)\n zoom!(ax.scene, cameracontrols(ax.scene), 0.98)\n Colorbar(fig[1, 2], pltobj, height=Relative(0.5), label=\"Gaussian curvature\")\n return ax, fig\nend","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"torus_figure","category":"page"},{"location":"tutorials/working-in-charts.html#Values-for-the-geodesic","page":"work in charts","title":"Values for the geodesic","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"solve_for is a helper function that solves a parallel transport along geodesic problem on the torus M. p0x is the (theta varphi) parametrization of the point from which we will transport the vector. We first calculate the coordinates in the embedding of p0x and store it as p, and then get the initial chart from atlas A appropriate for starting working at point p. The vector we transport has coordinates Y_transp in the induced tangent space basis of chart i_p0x. The function returns the full solution to the parallel transport problem, containing the sequence of charts that was used and solutions of differential equations computed using OrdinaryDiffEq.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"bvp_i is needed later for a different purpose, it is the chart index we will use for solving the logarithmic map boundary value problem in.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"Next we solve the vector transport problem solve_for([θₚ, φₚ], [θₓ, φₓ], [θy, φy]), sample the result at the selected time steps and store the result in geo. The solution includes the geodesic which we extract and convert to a sequence of points digestible by Makie.jl, geo_ps. [θₚ, φₚ] is the parametrization in chart (0, 0) of the starting point of the geodesic. The direction of the geodesic is determined by [θₓ, φₓ], coordinates of the tangent vector at the starting point expressed in the induced basis of chart i_p0x (which depends on the initial point). Finally, [θy, φy] are the coordinates of the tangent vector that will be transported along the geodesic, which are also expressed in same basis as [θₓ, φₓ].","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We won’t draw the transported vector at every point as there would be too many arrows, which is why we select every 100th point only for that purpose with pt_indices. Then, geo_ps_pt contains points at which the transported vector is tangent to and geo_Ys the transported vector at that point, represented in the embedding.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The logarithmic map will be solved between points with parametrization bvp_a1 and bvp_a2 in chart bvp_i. The result is assigned to variable bvp_sol and then sampled with time step 0.05. The result of this sampling is converted from parameters in chart bvp_i to point in the embedding and stored in geo_r.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"function solve_for(p0x, X_p0x, Y_transp, T)\n p = [Manifolds._torus_param(M, p0x...)...]\n i_p0x = Manifolds.get_chart_index(M, A, p)\n p_exp = Manifolds.solve_chart_parallel_transport_ode(\n M,\n [0.0, 0.0],\n X_p0x,\n A,\n i_p0x,\n Y_transp;\n final_time=T,\n )\n return p_exp\nend;","category":"page"},{"location":"tutorials/working-in-charts.html#Solving-parallel-Transport-ODE","page":"work in charts","title":"Solving parallel Transport ODE","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We set the end time t_end and time step dt.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"t_end = 2.0\ndt = 1e-1","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"0.1","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We also parametrise the start point and direction.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"θₚ = π/10\nφₚ = -π/4\nθₓ = π/2\nφₓ = 0.7\nθy = 0.2\nφy = -0.1\n\ngeo = solve_for([θₚ, φₚ], [θₓ, φₓ], [θy, φy], t_end)(0.0:dt:t_end);\n# geo_ps = [Point3f(s[1]) for s in geo]\n# pt_indices = 1:div(length(geo), 10):length(geo)\n# geo_ps_pt = [Point3f(s[1]) for s in geo[pt_indices]]\n# geo_Ys = [Point3f(s[3]) for s in geo[pt_indices]]\n\n# ax1, fig1 = torus_figure()\n# arrows!(ax1, geo_ps_pt, geo_Ys, linewidth=0.05, color=:blue)\n# lines!(geo_ps; linewidth=4.0, color=:green)\n# fig1","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"(Image: fig-pt)","category":"page"},{"location":"tutorials/working-in-charts.html#Solving-the-logairthmic-map-ODE","page":"work in charts","title":"Solving the logairthmic map ODE","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"θ₁=π/2\nφ₁=-1.0\nθ₂=-π/8\nφ₂=π/2\n\nbvp_i = (0, 0)\nbvp_a1 = [θ₁, φ₁]\nbvp_a2 = [θ₂, φ₂]\nbvp_sol = Manifolds.solve_chart_log_bvp(M, bvp_a1, bvp_a2, A, bvp_i);\n# geo_r = [Point3f(get_point(M, A, bvp_i, p[1:2])) for p in bvp_sol(0.0:0.05:1.0)]\n\n# ax2, fig2 = torus_figure()\n# lines!(geo_r; linewidth=4.0, color=:green)\n# fig2","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"(Image: fig-geodesic)","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"An interactive Pluto version of this tutorial is available in file tutorials/working-in-charts.jl.","category":"page"},{"location":"tutorials/getstarted.html#Get-Started-with-Manifolds.jl","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This is a short overview of Manifolds.jl and how to get started working with your first Manifold. we first need to install the package, using for example","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"using Pkg; Pkg.add(\"Manifolds\")","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Then you can load the package with","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"using Manifolds","category":"page"},{"location":"tutorials/getstarted.html#Using-the-Library-of-Manifolds","page":"🚀 Get Started with Manifolds.jl","title":"Using the Library of Manifolds","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Manifolds.jl is first of all a library of manifolds, see the list in the menu here under “basic manifolds”.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Let’s look at three examples together with the first few functions on manifolds.","category":"page"},{"location":"tutorials/getstarted.html#.-[The-Euclidean-space](https://juliamanifolds.github.io/Manifolds.jl/latest/manifolds/euclidean.html)","page":"🚀 Get Started with Manifolds.jl","title":"1. The Euclidean space","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The Euclidean Space Euclidean brings us (back) into linear case of vectors, so in terms of manifolds, this is a very simple one. It is often useful to compare to classical algorithms, or implementations.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₁ = Euclidean(3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Euclidean(3; field = ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Since a manifold is a type in Julia, we write it in CamelCase. Its parameters are first a dimension or size parameter of the manifold, sometimes optional is a field the manifold is defined over.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"For example the above definition is the same as the real-valued case","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₁ === Euclidean(3, field=ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But we even introduced a short hand notation, since ℝ is also just a symbol/variable to use”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₁ === ℝ^3","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"And similarly here are two ways to create the manifold of vectors of length two with complex entries – or mathematically the space mathbb C^2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Euclidean(2, field=ℂ) === ℂ^2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The easiest to check is the dimension of a manifold. Here we have three “directions to walk into” at every point pin mathbb R ^3 so 🔗 manifold_dimension) is","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"manifold_dimension(M₁)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3","category":"page"},{"location":"tutorials/getstarted.html#.-[The-hyperpolic-space](@ref-HyperbolicSpace)","page":"🚀 Get Started with Manifolds.jl","title":"2. The hyperpolic space","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The d-dimensional hyperbolic space is usually represented in mathbb R^d+1 as the set of points pinmathbb R^3 fulfilling","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p_1^2+p_2^2+cdots+p_d^2-p_d+1^2 = -1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We define the manifold using","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₂ = Hyperbolic(2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Hyperbolic(2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"And we can again just start with looking at the manifold dimension of M₂","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"manifold_dimension(M₂)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"A next useful function is to check, whether some pmathbb R^3 is a point on the manifold M₂. We can check","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₂, [0, 0, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"or","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₂, [1, 0, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"false","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Keyword arguments are passed on to any numerical checks, for example an absolute tolerance when checking the above equiality.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But in an interactive session an error message might be helpful. A positional (third) argument is present to activate this. Setting this parameter to true, we obtain an error message that gives insight into why the point is not a point on M₂. Note that the LoadError: is due to quarto, on REPL you would just get the DomainError.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₂, [0, 0, 1.001], true)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"LoadError: DomainError with -1.0020009999999997:\nThe point [0.0, 0.0, 1.001] does not lie on Hyperbolic(2) since its Minkowski inner product is not -1.","category":"page"},{"location":"tutorials/getstarted.html#.-[The-sphere](@ref-SphereSection)","page":"🚀 Get Started with Manifolds.jl","title":"3. The sphere","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The sphere mathbb S^d is the d-dimensional sphere represented in its embedded form, that is unit vectors p in mathbb R^d+1 with unit norm lVert p rVert_2 = 1.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₃ = Sphere(2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Sphere(2, ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"If we only have a point that is approximately on the manifold, we can allow for a tolerance. Usually these are the same values of atol and rtol alowed in isapprox, i.e. we get","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₃, [0, 0, 1.001]; atol=1e-3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Here we can show a last nice check: 🔗 is_vector to check whether a tangent vector X is a representation of a tangent vector XT_pmathcal M to a point p on the manifold.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This function has two positional asrguments, the first to again indicate whether to throw an error, the second to disable the check that p is a valid point on the manifold. Usually this validity is essential for the tangent check, but if it was for example performed before, it can be turned off to spare time.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"For example in our first example the point is not of unit norm","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_vector(M₃, [2, 0, 0], [0, 1, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"false","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But the orthogonality of p and X is still valid, we can disable the point check, but even setting the error to true we get here","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_vector(M₃, [2, 0, 0], [0, 1, 1], true, false)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But of course it is better to use a valid point in the first place","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_vector(M₃, [1, 0, 0], [0, 1, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"and for these we again get informative error messages","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"@expect_error is_vector(M₃, [1, 0, 0], [0.1, 1, 1], true) DomainError","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"LoadError: LoadError: UndefVarError: `@expect_error` not defined\nin expression starting at In[19]:1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To learn about how to define a manifold youself check out the 🔗 How to define your own manifold tutorial of 🔗 ManifoldsBase.jl.”","category":"page"},{"location":"tutorials/getstarted.html#Building-more-advanced-manifolds","page":"🚀 Get Started with Manifolds.jl","title":"Building more advanced manifolds","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Based on these basic manifolds we can directly build more advanced manifolds.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The first one concerns vectors or matrices of data on a manifold, the PowerManifold.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₄ = M₂^2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"PowerManifold(Hyperbolic(2), 2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Then points are represented by arrays, where the power manifold dimension is added in the end. In other words – for the hyperbolic manifold here, we have a matrix with 2 columns, where each column is a valid point on hyperbolic space.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p = [0 0; 0 1; 1 sqrt(2)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3×2 Matrix{Float64}:\n 0.0 0.0\n 0.0 1.0\n 1.0 1.41421","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[is_point(M₂, p[:, 1]), is_point(M₂, p[:, 2])]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Bool}:\n 1\n 1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But of course the method we used previously also works for power manifolds:","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₄, p)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Note that nested power manifolds are combined into one as in","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₄₂ = M₄^4","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"PowerManifold(Hyperbolic(2), 2, 4)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"which represents 2times 4 – matrices of hyperbolic points represented in 3times 2times 4 arrays.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We can – alternatively – use a power manifold with nested arrays","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₅ = PowerManifold(M₃, NestedPowerRepresentation(), 2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"PowerManifold(Sphere(2, ℝ), NestedPowerRepresentation(), 2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"which emphasizes that we have vectors of length 2 that contain points, so we store them that way.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₂ = [[0.0, 0.0, 1.0], [0.0, 1.0, 0.0]]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Vector{Float64}}:\n [0.0, 0.0, 1.0]\n [0.0, 1.0, 0.0]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To unify both representations, elements of the power manifold can also be accessed in the classical indexing fashion, if we start with the corresponding manifold first. This way one can implement algorithms also independent of which representation is used.”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p[M₄, 1]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3-element Vector{Float64}:\n 0.0\n 0.0\n 1.0","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₂[M₅, 2]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3-element Vector{Float64}:\n 0.0\n 1.0\n 0.0","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Another construtor is the ProductManifold to combine different manifolds. Here of course the order matters. First we construct these using ","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₆ = M₂ × M₃","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"ProductManifold with 2 submanifolds:\n Hyperbolic(2)\n Sphere(2, ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Since now the representations might differ from element to element, we have to encapsulate these in their own type.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₃ = Manifolds.ArrayPartition([0, 0, 1], [0, 1, 0])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"([0, 0, 1], [0, 1, 0])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Here ArrayPartition taken from 🔗 RecursiveArrayTools.jl to store the point on the product manifold efficiently in one array, still allowing efficient access to the product elements.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₆, p₃, true)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But accessing single components still works the same.”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₃[M₆, 1]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3-element Vector{Int64}:\n 0\n 0\n 1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Finally, also the TangentBundle, the manifold collecting all tangent spaces on a manifold is available as”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₇ = TangentBundle(M₃)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"TangentBundle(Sphere(2, ℝ))","category":"page"},{"location":"tutorials/getstarted.html#Implementing-generic-Functions","page":"🚀 Get Started with Manifolds.jl","title":"Implementing generic Functions","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"In this section we take a look how to implement generic functions on manifolds.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"For our example here, we want to implement the so-called 📖 Bézier curve using the so-called 📖 de-Casteljau algorithm. The linked algorithm can easily be generalised to manifolds by replacing lines with geodesics. This was for example used in [1] and the following example is an extended version of an example from [2].","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The algorithm works recursively. For the case that we have a Bézier curve with just two points, the algorithm just evaluates the geodesic connecting both at some time point t01. The function to evaluate a shortest geodesic (it might not be unique, but then a deterministic choice is taken) between two points p and q on a manifold M 🔗 shortest_geodesic(M, p, q, t).","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function de_Casteljau(M::AbstractManifold, t, pts::NTuple{2})\n return shortest_geodesic(M, pts[1], pts[2], t)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"de_Casteljau (generic function with 1 method)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function de_Casteljau(M::AbstractManifold, t, pts::NTuple)\n p = de_Casteljau(M, t, pts[1:(end - 1)])\n q = de_Casteljau(M, t, pts[2:end])\n return shortest_geodesic(M, p, q, t)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"de_Casteljau (generic function with 2 methods)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Which can now be used on any manifold where the shortest geodesic is implemented","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Now on several manifolds the 📖 exponential map and its (locally defined) inverse, the logarithmic map might not be available in an implementation. So one way to generalise this, is the use of a retraction (see [3], Def. 4.1.1 for details) and its (local) inverse.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The function itself is quite similar to the expponential map, just that 🔗 retract(M, p, X, m) has one further parameter, the type of retraction to take, so m is a subtype of AbstractRetractionMethod m, the same for the 🔗 inverse_retract(M, p, q, n) with an AbstractInverseRetractionMethod n.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Thinking of a generic implementation, we would like to have a way to specify one, that is available. This can be done by using 🔗 default_retraction_method and 🔗 default_inverse_retraction_method, respectively. We implement","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function generic_de_Casteljau(\n M::AbstractManifold,\n t,\n pts::NTuple{2};\n m::AbstractRetractionMethod=default_retraction_method(M),\n n::AbstractInverseRetractionMethod=default_inverse_retraction_method(M),\n)\n X = inverse_retract(M, pts[1], pts[2], n)\n return retract(M, pts[1], X, t, m)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"generic_de_Casteljau (generic function with 1 method)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"and for the recursion","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function generic_de_Casteljau(\n M::AbstractManifold,\n t,\n pts::NTuple;\n m::AbstractRetractionMethod=default_retraction_method(M),\n n::AbstractInverseRetractionMethod=default_inverse_retraction_method(M),\n)\n p = generic_de_Casteljau(M, t, pts[1:(end - 1)]; m=m, n=n)\n q = generic_de_Casteljau(M, t, pts[2:end]; m=m, n=n)\n X = inverse_retract(M, p, q, n)\n return retract(M, p, X, t, m)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"generic_de_Casteljau (generic function with 2 methods)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Note that on a manifold M where the exponential map is implemented, the default_retraction_method(M) returns 🔗 ExponentialRetraction, which yields that the retract function falls back to calling exp.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The same mechanism exists for 🔗 parallel_transport_to(M, p, X, q) and the more general 🔗 vector_transport_to(M, p, X, q, m) whose 🔗 AbstractVectorTransportMethod m has a default defined by 🔗 default_vector_transport_method(M).","category":"page"},{"location":"tutorials/getstarted.html#Allocating-and-in-place-computations","page":"🚀 Get Started with Manifolds.jl","title":"Allocating and in-place computations","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Memory allocation is a 🔗 critical performace issue when programming in Julia. To take this into account, Manifolds.jl provides special functions to reduce the amount of allocations.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We again look at the 📖 exponential map. On a manifold M the exponential map needs a point p (to start from) and a tangent vector X, which can be seen as direction to “walk into” as well as the length to walk into this direction. In Manifolds.jl the function can then be called with q = exp(M, p, X) (see 🔗 exp(M, p, X)). This function returns the resulting point q, which requires to allocate new memory.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To avoid this allocation, the function 🔗 exp!(M, q, p, X) can be called. Here q is allocated beforehand and is passed as the memory, where the result is returned in. It might be used even for interims computations, as long as it does not introduce side effects. Thas means that even with exp!(M, p, p, X) the result is correct.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Let’s look at an example.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We take another look at the Sphere, but now a high-dimensional one. We can also illustrate how to generate radnom points and tangent vectors.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M = Sphere(10000)\np₄ = rand(M)\nX = rand(M; vector_at=p₄)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Looking at the allocations required we get","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"@allocated exp(M, p₄, X)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"17791918","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"While if we have already allocated memory for the resulting point on the manifold, for example","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"q₂ = zero(p₄);","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"There are no new memory allocations necessary if we use the in-place function.”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"@allocated exp!(M, q₂, p₄, X)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"0","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This methodology is used for all functions that compute a new point or tangent vector. By default all allocating functions allocate memory and call the in-place function. This also means that if you implement a new manifold, you just have to implement the in-place version.","category":"page"},{"location":"tutorials/getstarted.html#Decorating-a-manifold","page":"🚀 Get Started with Manifolds.jl","title":"Decorating a manifold","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"As you saw until now, an 🔗 AbstractManifold describes a Riemannian manifold. For completeness, this also includes the chosen 📖 Riemannian metric tensor or inner product on the tangent spaces.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"In Manifolds.jl these are assumed to be a “reasonable default”. For example on the Sphere(n) we used above, the default metric is the one inherited from restricting the inner product from the embedding space onto each tangent space.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Consider a manifold like","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₈ = SymmetricPositiveDefinite(3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"SymmetricPositiveDefinite(3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"which is the manifold of 33 matrices that are symmetric and positive definite. which has a default as well, the affine invariant AffineInvariantMetric, but also has several different metrics.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To switch the metric, we use the idea of a 📖 decorator pattern approach. Defining","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₈₂ = MetricManifold(M₈, BuresWassersteinMetric())","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"MetricManifold(SymmetricPositiveDefinite(3), BuresWassersteinMetric())","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"changes the manifold to use the BuresWassersteinMetric.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This changes all functions that depend on the metric, most prominently the Riemannian matric, but also the exponential and logarithmic map and hence also geodesics.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"All functions that are not dependent on a metric – for example the manifold dimension, the tests of points and vectors we already looked at, but also all retractions – stay unchanged. This means that for example","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[manifold_dimension(M₈₂), manifold_dimension(M₈)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Int64}:\n 6\n 6","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"both calls the same underlying function. On the other hand with","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₅, X₅ = one(zeros(3, 3)), [1.0 0.0 1.0; 0.0 1.0 0.0; 1.0 0.0 1.0]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"([1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0], [1.0 0.0 1.0; 0.0 1.0 0.0; 1.0 0.0 1.0])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"but for example the exponential map and the norm yield different results","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[exp(M₈, p₅, X₅), exp(M₈₂, p₅, X₅)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Matrix{Float64}}:\n [4.194528049465325 0.0 3.194528049465325; 0.0 2.718281828459045 0.0; 3.194528049465325 0.0 4.194528049465328]\n [2.5 0.0 1.5; 0.0 2.25 0.0; 1.5 0.0 2.5]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[norm(M₈, p₅, X₅), norm(M₈₂, p₅, X₅)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Float64}:\n 2.23606797749979\n 1.118033988749895","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Technically this done using Traits – the trait here is the IsMetricManifold trait. Our trait system allows to combine traits but also to inherit properties in a hierarchical way, see 🔗 here for the technical details.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The same approach is used for","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"specifying a different connection\nspecifying a manifold as a certain quotient manifold\nspecifying a certain 🔗 embeddings\nspecify a certain group action","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Again, for all of these, the concrete types only have to be used if you want to do a second, different from the details, property, for example a second way to embed a manfiold. If a manifold is (in its usual representation) an embedded manifold, this works with the default manifold type already, since then it is again set as the reasonable default.","category":"page"},{"location":"tutorials/getstarted.html#References","page":"🚀 Get Started with Manifolds.jl","title":"References","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[1]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Bergmann, R. and Gousenbourger, P.-Y.: A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics, 2018. doi: 10.3389/fams.2018.00059, arXiv: 1807.10090","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[2]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Axen, S. D., Baran, M., Bergmann, R. and Rzecki, K: Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds, arXiv preprint, 2022, 2106.08777","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[3]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access","category":"page"},{"location":"manifolds/hyperbolic.html#HyperbolicSpace","page":"Hyperbolic space","title":"Hyperbolic space","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"The hyperbolic space can be represented in three different models.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Hyperboloid which is the default model, i.e. is used when using arbitrary array types for points and tangent vectors\nPoincaré ball with separate types for points and tangent vectors and a visualization for the two-dimensional case\nPoincaré half space with separate types for points and tangent vectors and a visualization for the two-dimensional cae.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"In the following the common functions are collected.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"A function in this general section uses vectors interpreted as if in the hyperboloid model, and other representations usually just convert to this representation to use these general functions.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPages = [\"manifolds/Hyperbolic.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Manifolds.Hyperbolic","page":"Hyperbolic space","title":"Manifolds.Hyperbolic","text":"Hyperbolic{N} <: AbstractDecoratorManifold{ℝ}\n\nThe hyperbolic space mathcal H^n represented by n+1-Tuples, i.e. embedded in the Lorentzian manifold equipped with the MinkowskiMetric cdotcdot_mathrmM. The space is defined as\n\nmathcal H^n = Biglp ℝ^n+1 Big pp_mathrmM= -p_n+1^2\n + displaystylesum_k=1^n p_k^2 = -1 p_n+1 0Bigr\n\nThe tangent space T_p mathcal H^n is given by\n\nT_p mathcal H^n = bigl\nX ℝ^n+1 pX_mathrmM = 0\nbigr\n\nNote that while the MinkowskiMetric renders the Lorentz manifold (only) pseudo-Riemannian, on the tangent bundle of the Hyperbolic space it induces a Riemannian metric. The corresponding sectional curvature is -1.\n\nIf p and X are Vectors of length n+1 they are assumed to be a HyperboloidPoint and a HyperboloidTVector, respectively\n\nOther models are the Poincaré ball model, see PoincareBallPoint and PoincareBallTVector, respectiely and the Poincaré half space model, see PoincareHalfSpacePoint and PoincareHalfSpaceTVector, respectively.\n\nConstructor\n\nHyperbolic(n)\n\nGenerate the Hyperbolic manifold of dimension n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.HyperboloidPoint","page":"Hyperbolic space","title":"Manifolds.HyperboloidPoint","text":"HyperboloidPoint <: AbstractManifoldPoint\n\nIn the Hyperboloid model of the Hyperbolic mathcal H^n points are represented as vectors in ℝ^n+1 with MinkowskiMetric equal to -1.\n\nThis representation is the default, i.e. AbstractVectors are assumed to have this repesentation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.HyperboloidTVector","page":"Hyperbolic space","title":"Manifolds.HyperboloidTVector","text":"HyperboloidTVector <: TVector\n\nIn the Hyperboloid model of the Hyperbolic mathcal H^n tangent vctors are represented as vectors in ℝ^n+1 with MinkowskiMetric pX_mathrmM=0 to their base point p.\n\nThis representation is the default, i.e. vectors are assumed to have this repesentation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareBallPoint","page":"Hyperbolic space","title":"Manifolds.PoincareBallPoint","text":"PoincareBallPoint <: AbstractManifoldPoint\n\nA point on the Hyperbolic manifold mathcal H^n can be represented as a vector of norm less than one in mathbb R^n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareBallTVector","page":"Hyperbolic space","title":"Manifolds.PoincareBallTVector","text":"PoincareBallTVector <: TVector\n\nIn the Poincaré ball model of the Hyperbolic mathcal H^n tangent vectors are represented as vectors in ℝ^n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareHalfSpacePoint","page":"Hyperbolic space","title":"Manifolds.PoincareHalfSpacePoint","text":"PoincareHalfSpacePoint <: AbstractManifoldPoint\n\nA point on the Hyperbolic manifold mathcal H^n can be represented as a vector in the half plane, i.e. x ℝ^n with x_d 0.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareHalfSpaceTVector","page":"Hyperbolic space","title":"Manifolds.PoincareHalfSpaceTVector","text":"PoincareHalfPlaneTVector <: TVector\n\nIn the Poincaré half plane model of the Hyperbolic mathcal H^n tangent vectors are represented as vectors in ℝ^n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Base.exp-Tuple{Hyperbolic, Vararg{Any}}","page":"Hyperbolic space","title":"Base.exp","text":"exp(M::Hyperbolic, p, X)\n\nCompute the exponential map on the Hyperbolic space mathcal H^n emanating from p towards X. The formula reads\n\nexp_p X = cosh(sqrtXX_mathrmM)p\n+ sinh(sqrtXX_mathrmM)fracXsqrtXX_mathrmM\n\nwhere cdotcdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.log-Tuple{Hyperbolic, Vararg{Any}}","page":"Hyperbolic space","title":"Base.log","text":"log(M::Hyperbolic, p, q)\n\nCompute the logarithmic map on the Hyperbolic space mathcal H^n, the tangent vector representing the geodesic starting from p reaches q after time 1. The formula reads for p q\n\nlog_p q = d_mathcal H^n(pq)\nfracq-pq_mathrmM plVert q-pq_mathrmM p rVert_2\n\nwhere cdotcdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold. For p=q the logarihmic map is equal to the zero vector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Manifolds.manifold_volume-Tuple{Hyperbolic}","page":"Hyperbolic space","title":"Manifolds.manifold_volume","text":"manifold_dimension(M::Hyperbolic)\n\nReturn the volume of the hyperbolic space manifold mathcal H^n, i.e. infinity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.check_point-Tuple{Hyperbolic, Any}","page":"Hyperbolic space","title":"ManifoldsBase.check_point","text":"check_point(M::Hyperbolic, p; kwargs...)\n\nCheck whether p is a valid point on the Hyperbolic M.\n\nFor the HyperboloidPoint or plain vectors this means that, p is a vector of length n+1 with inner product in the embedding of -1, see MinkowskiMetric. The tolerance for the last test can be set using the kwargs....\n\nFor the PoincareBallPoint a valid point is a vector p ℝ^n with a norm stricly less than 1.\n\nFor the PoincareHalfSpacePoint a valid point is a vector from p ℝ^n with a positive last entry, i.e. p_n0\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.check_vector-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.check_vector","text":"check_vector(M::Hyperbolic{n}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the Hyperbolic M, i.e. after check_point(M,p), X has to be of the same dimension as p. The tolerance for the last test can be set using the kwargs....\n\nFor a the hyperboloid model or vectors, X has to be orthogonal to p with respect to the inner product from the embedding, see MinkowskiMetric.\n\nFor a the Poincaré ball as well as the Poincaré half plane model, X has to be a vector from ℝ^n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.injectivity_radius-Tuple{Hyperbolic}","page":"Hyperbolic space","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Hyperbolic)\ninjectivity_radius(M::Hyperbolic, p)\n\nReturn the injectivity radius on the Hyperbolic, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.is_flat-Tuple{Hyperbolic}","page":"Hyperbolic space","title":"ManifoldsBase.is_flat","text":"is_flat(::Hyperbolic)\n\nReturn false. Hyperbolic is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.manifold_dimension-Union{Tuple{Hyperbolic{N}}, Tuple{N}} where N","page":"Hyperbolic space","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Hyperbolic)\n\nReturn the dimension of the hyperbolic space manifold mathcal H^n, i.e. dim(mathcal H^n) = n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.parallel_transport_to-Tuple{Hyperbolic, Any, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::Hyperbolic, p, X, q)\n\nCompute the paralllel transport of the X from the tangent space at p on the Hyperbolic space mathcal H^n to the tangent at q along the geodesic connecting p and q. The formula reads\n\nmathcal P_qpX = X - fraclog_p qX_pd^2_mathcal H^n(pq)\nbigl(log_p q + log_qp bigr)\n\nwhere cdotcdot_p denotes the inner product in the tangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.project-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.project","text":"project(M::Hyperbolic, p, X)\n\nPerform an orthogonal projection with respect to the Minkowski inner product of X onto the tangent space at p of the Hyperbolic space M.\n\nThe formula reads\n\nY = X + pX_mathrmM p\n\nwhere cdot cdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.\n\nnote: Note\nProjection is only available for the (default) HyperboloidTVector representation, the others don't have such an embedding\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Statistics.mean-Tuple{Hyperbolic, Vararg{Any}}","page":"Hyperbolic space","title":"Statistics.mean","text":"mean(\n M::Hyperbolic,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = CyclicProximalPointEstimation();\n kwargs...,\n)\n\nCompute the Riemannian mean of x on the Hyperbolic space using CyclicProximalPointEstimation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#hyperboloid_model","page":"Hyperbolic space","title":"hyperboloid model","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPrivate = false\nPages = [\"manifolds/HyperbolicHyperboloid.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidPoint}, PoincareBallPoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidPoint}, p::PoincareBallPoint)\nconvert(::Type{AbstractVector}, p::PoincareBallPoint)\n\nconvert a point PoincareBallPoint x (from ℝ^n) from the Poincaré ball model of the Hyperbolic manifold mathcal H^n to a HyperboloidPoint π(p) ℝ^n+1. The isometry is defined by\n\nπ(p) = frac11-lVert p rVert^2\nbeginpmatrix2p_12p_n1+lVert p rVert^2endpmatrix\n\nNote that this is also used, when the type to convert to is a vector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidPoint}, PoincareHalfSpacePoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidPoint}, p::PoincareHalfSpacePoint)\nconvert(::Type{AbstractVector}, p::PoincareHalfSpacePoint)\n\nconvert a point PoincareHalfSpacePoint p (from ℝ^n) from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a HyperboloidPoint π(p) ℝ^n+1.\n\nThis is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidTVector}, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidTVector}, p::PoincareBallPoint, X::PoincareBallTVector)\nconvert(::Type{AbstractVector}, p::PoincareBallPoint, X::PoincareBallTVector)\n\nConvert the PoincareBallTVector X from the tangent space at p to a HyperboloidTVector by computing the push forward of the isometric map, cf. convert(::Type{HyperboloidPoint}, p::PoincareBallPoint).\n\nThe push forward π_*(p) maps from ℝ^n to a subspace of ℝ^n+1, the formula reads\n\nπ_*(p)X = beginpmatrix\n frac2X_11-lVert p rVert^2 + frac4(1-lVert p rVert^2)^2Xpp_1\n \n frac2X_n1-lVert p rVert^2 + frac4(1-lVert p rVert^2)^2Xpp_n\n frac4(1-lVert p rVert^2)^2Xp\nendpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidTVector}, PoincareHalfSpacePoint, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidTVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)\nconvert(::Type{AbstractVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)\n\nconvert a point PoincareHalfSpaceTVector X (from ℝ^n) at p from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a HyperboloidTVector π(p) ℝ^n+1.\n\nThis is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{HyperboloidPoint, HyperboloidTVector}}, Tuple{PoincareBallPoint, PoincareBallTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{HyperboloidPoint,HyperboloidTVector}}.\n (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}\n)\nconvert(\n ::Type{Tuple{P,T}},\n (p, X)::Tuple{PoincareBallPoint,PoincareBallTVector},\n) where {P<:AbstractVector, T <: AbstractVector}\n\nConvert a PoincareBallPoint p and a PoincareBallTVector X to a HyperboloidPoint and a HyperboloidTVector simultaneously, see convert(::Type{HyperboloidPoint}, ::PoincareBallPoint) and convert(::Type{HyperboloidTVector}, ::PoincareBallPoint, ::PoincareBallTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{HyperboloidPoint, HyperboloidTVector}}, Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{HyperboloidPoint,HyperboloidTVector},\n (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}\n)\nconvert(\n ::Type{Tuple{T,T},\n (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}\n) where {T<:AbstractVector}\n\nconvert a point PoincareHalfSpaceTVector X (from ℝ^n) at p from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a tuple of a HyperboloidPoint and a HyperboloidTVector π(p) ℝ^n+1 simultaneously.\n\nThis is done in two steps, namely transforming it to the Poincare ball model and from there further on to a Hyperboloid.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Manifolds.volume_density-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"Manifolds.volume_density","text":"volume_density(M::Hyperbolic, p, X)\n\nCompute volume density function of the hyperbolic manifold. The formula reads (sinh(lVert XrVert)lVert XrVert)^(n-1) where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.change_representer-Tuple{Hyperbolic, EuclideanMetric, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.change_representer","text":"change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p, X)\n\nChange the Eucliden representer X of a cotangent vector at point p. We only have to correct for the metric, which means that the sign of the last entry changes, since for the result Y we are looking for a tangent vector such that\n\n g_p(YZ) = -y_n+1z_n+1 + sum_i=1^n y_iz_i = sum_i=1^n+1 z_ix_i\n\nholds, which directly yields y_i=x_i for i=1ldotsn and y_n+1=-x_n+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.distance-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.distance","text":"distance(M::Hyperbolic, p, q)\ndistance(M::Hyperbolic, p::HyperboloidPoint, q::HyperboloidPoint)\n\nCompute the distance on the Hyperbolic M, which reads\n\nd_mathcal H^n(pq) = operatornameacosh( - p q_mathrmM)\n\nwhere cdotcdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.get_coordinates-Tuple{Hyperbolic, Any, Any, DefaultOrthonormalBasis}","page":"Hyperbolic space","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::Hyperbolic, p, X, ::DefaultOrthonormalBasis)\n\nCompute the coordinates of the vector X with respect to the orthogonalized version of the unit vectors from ℝ^n, where n is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.get_vector-Tuple{Hyperbolic, Any, Any, DefaultOrthonormalBasis}","page":"Hyperbolic space","title":"ManifoldsBase.get_vector","text":"get_vector(M::Hyperbolic, p, c, ::DefaultOrthonormalBasis)\n\nCompute the vector from the coordinates with respect to the orthogonalized version of the unit vectors from ℝ^n, where n is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.inner-Tuple{Hyperbolic, Any, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.inner","text":"inner(M::Hyperbolic{n}, p, X, Y)\ninner(M::Hyperbolic{n}, p::HyperboloidPoint, X::HyperboloidTVector, Y::HyperboloidTVector)\n\nCmpute the inner product in the Hyperboloid model, i.e. the minkowski_metric in the embedding. The formula reads\n\ng_p(XY) = XY_mathrmM = -X_nY_n + displaystylesum_k=1^n-1 X_kY_k\n\nThis employs the metric of the embedding, see Lorentz space.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#hyperboloid_plot","page":"Hyperbolic space","title":"Visualization of the Hyperboloid","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"For the case of Hyperbolic(2) there is plotting available based on a PlottingRecipe. You can easily plot points, connecting geodesics as well as tangent vectors.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"note: Note\nThe recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation for the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of wires and a wireframe_color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_x or surface_resolution_y) and a surface_color.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"using Manifolds, Plots\nM = Hyperbolic(2)\npts = [ [0.85*cos(φ), 0.85*sin(φ), sqrt(0.85^2+1)] for φ ∈ range(0,2π,length=11) ]\nscene = plot(M, pts; geodesic_interpolation=100)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot. Note that we avoid redrawing the wireframe in the following plot! calls.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, pts; wireframe=false)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind that a tangent vector in plotting always requires its base point.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"pts2 = [ [0.45 .*cos(φ + 6π/11), 0.45 .*sin(φ + 6π/11), sqrt(0.45^2+1) ] for φ ∈ range(0,2π,length=11)]\nvecs = log.(Ref(M),pts,pts2)\nplot!(scene, M, pts, vecs; wireframe=false)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Just to illustrate, for the first point the tangent vector is pointing along the following geodesic","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, [pts[1], pts2[1]]; geodesic_interpolation=100, wireframe=false)","category":"page"},{"location":"manifolds/hyperbolic.html#Internal-functions","page":"Hyperbolic space","title":"Internal functions","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"The following functions are available for internal use to construct points in the hyperboloid model","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPublic = false\nPages = [\"manifolds/HyperbolicHyperboloid.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Manifolds._hyperbolize-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"Manifolds._hyperbolize","text":"_hyperbolize(M, p, Y)\n\nGiven the Hyperbolic(n) manifold using the hyperboloid model and a point p thereon, we can put a vector Yin ℝ^n into the tangent space by computing its last component such that for the resulting p we have that its minkowski_metric is pX_mathrmM = 0, i.e. X_n+1 = fractilde p Yp_n+1, where tilde p = (p_1ldotsp_n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Manifolds._hyperbolize-Tuple{Hyperbolic, Any}","page":"Hyperbolic space","title":"Manifolds._hyperbolize","text":"_hyperbolize(M, q)\n\nGiven the Hyperbolic(n) manifold using the hyperboloid model, a point from the qin ℝ^n can be set onto the manifold by computing its last component such that for the resulting p we have that its minkowski_metric is pp_mathrmM = - 1, i.e. p_n+1 = sqrtlVert q rVert^2 - 1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#poincare_ball","page":"Hyperbolic space","title":"Poincaré ball model","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPages = [\"manifolds/HyperbolicPoincareBall.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallPoint}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareBallPoint}, p::HyperboloidPoint)\nconvert(::Type{PoincareBallPoint}, p::T) where {T<:AbstractVector}\n\nconvert a HyperboloidPoint pℝ^n+1 from the hyperboloid model of the Hyperbolic manifold mathcal H^n to a PoincareBallPoint π(p)ℝ^n in the Poincaré ball model. The isometry is defined by\n\nπ(p) = frac11+p_n+1 beginpmatrixp_1p_nendpmatrix\n\nNote that this is also used, when x is a vector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallPoint}, PoincareHalfSpacePoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareBallPoint}, p::PoincareHalfSpacePoint)\n\nconvert a point PoincareHalfSpacePoint p (from ℝ^n) from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a PoincareBallPoint π(p) ℝ^n. Denote by tilde p = (p_1ldotsp_d-1)^mathrmT. Then the isometry is defined by\n\nπ(p) = frac1lVert tilde p rVert^2 + (p_n+1)^2\nbeginpmatrix2p_12p_n-1lVert prVert^2 - 1endpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallTVector}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareBallTVector}, p::HyperboloidPoint, X::HyperboloidTVector)\nconvert(::Type{PoincareBallTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}\n\nconvert a HyperboloidTVector X at p to a PoincareBallTVector on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Hyperboloid to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::HyperboloidPoint).\n\nThe formula reads\n\nπ_*(p)X = frac1p_n+1+1Bigl(tilde X - fracX_n+1p_n+1+1tilde p Bigl)\n\nwhere tilde X = beginpmatrixX_1X_nendpmatrix and tilde p = beginpmatrixp_1p_nendpmatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallTVector}, PoincareHalfSpacePoint, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{PoincareBallTVector},\n p::PoincareHalfSpacePoint,\n X::PoincareHalfSpaceTVector\n)\n\nconvert a PoincareHalfSpaceTVector X at p to a PoincareBallTVector on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Poincaré half space to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint).\n\nThe formula reads\n\nπ_*(p)X =\nfrac1lVert tilde prVert^2 + (1+p_n)^2\nbeginpmatrix\n2X_1\n\n2X_n-1\n2Xp\nendpmatrix\n-\nfrac2(lVert tilde prVert^2 + (1+p_n)^2)^2\nbeginpmatrix\n2p_1(Xp+X_n)\n\n2p_n-1(Xp+X_n)\n(lVert p rVert^2-1)(Xp+X_n)\nendpmatrix\n\nwhere tilde p = beginpmatrixp_1p_n-1endpmatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareBallPoint, PoincareBallTVector}}, Tuple{HyperboloidPoint, HyperboloidTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}\n)\nconvert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p, X)::Tuple{P,T},\n) where {P<:AbstractVector, T <: AbstractVector}\n\nConvert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::HyperboloidPoint) and convert(::Type{PoincareBallTVector}, ::HyperboloidPoint, ::HyperboloidTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareBallPoint, PoincareBallTVector}}, Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}\n)\nconvert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p, X)::Tuple{T,T},\n) where {T <: AbstractVector}\n\nConvert a PoincareHalfSpacePoint p and a PoincareHalfSpaceTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint) and convert(::Type{PoincareBallTVector}, ::PoincareHalfSpacePoint, ::PoincareHalfSpaceTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.change_metric-Tuple{Hyperbolic, EuclideanMetric, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.change_metric","text":"change_metric(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)\n\nSince in the metric we always have the term α = frac21-sum_i=1^n p_i^2 per element, the correction for the metric reads Z = frac1αX.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.change_representer-Tuple{Hyperbolic, EuclideanMetric, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.change_representer","text":"change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)\n\nSince in the metric we have the term α = frac21-sum_i=1^n p_i^2 per element, the correction for the gradient reads Y = frac1α^2X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.distance-Tuple{Hyperbolic, PoincareBallPoint, PoincareBallPoint}","page":"Hyperbolic space","title":"ManifoldsBase.distance","text":"distance(::Hyperbolic, p::PoincareBallPoint, q::PoincareBallPoint)\n\nCompute the distance on the Hyperbolic manifold mathcal H^n represented in the Poincaré ball model. The formula reads\n\nd_mathcal H^n(pq) =\noperatornameacoshBigl(\n 1 + frac2lVert p - q rVert^2(1-lVert prVert^2)(1-lVert qrVert^2)\nBigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.inner-Tuple{Hyperbolic, PoincareBallPoint, PoincareBallTVector, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.inner","text":"inner(::Hyperbolic, p::PoincareBallPoint, X::PoincareBallTVector, Y::PoincareBallTVector)\n\nCompute the inner producz in the Poincaré ball model. The formula reads\n\ng_p(XY) = frac4(1-lVert p rVert^2)^2 X Y \n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.project-Tuple{Hyperbolic, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.project","text":"project(::Hyperbolic, ::PoincareBallPoint, ::PoincareBallTVector)\n\nprojction of tangent vectors in the Poincaré ball model is just the identity, since the tangent space consists of all ℝ^n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#poincare_ball_plot","page":"Hyperbolic space","title":"Visualization of the Poincaré ball","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"note: Note\nThe recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation For the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path. Another keyword argument added is the border of the Poincaré disc, namely circle_points = 720 resolution of the drawn boundary (every hlaf angle) as well as its color, hyperbolic_border_color = RGBA(0.0, 0.0, 0.0, 1.0).","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"using Manifolds, Plots\nM = Hyperbolic(2)\npts = PoincareBallPoint.( [0.85 .* [cos(φ), sin(φ)] for φ ∈ range(0,2π,length=11)])\nscene = plot(M, pts, geodesic_interpolation = 100)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, pts)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind, that a tangent vector in plotting always requires its base point","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"pts2 = PoincareBallPoint.( [0.45 .* [cos(φ + 6π/11), sin(φ + 6π/11)] for φ ∈ range(0,2π,length=11)])\nvecs = log.(Ref(M),pts,pts2)\nplot!(scene, M, pts,vecs)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Just to illustrate, for the first point the tangent vector is pointing along the following geodesic","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, [pts[1], pts2[1]], geodesic_interpolation=100)","category":"page"},{"location":"manifolds/hyperbolic.html#poincare_halfspace","page":"Hyperbolic space","title":"Poincaré half space model","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPages = [\"manifolds/HyperbolicPoincareHalfspace.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpacePoint}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpacePoint}, p::Hyperboloid)\nconvert(::Type{PoincareHalfSpacePoint}, p)\n\nconvert a HyperboloidPoint or Vectorp (from ℝ^n+1) from the Hyperboloid model of the Hyperbolic manifold mathcal H^n to a PoincareHalfSpacePoint π(x) ℝ^n.\n\nThis is done in two steps, namely transforming it to a Poincare ball point and from there further on to a PoincareHalfSpacePoint point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpacePoint}, PoincareBallPoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpacePoint}, p::PoincareBallPoint)\n\nconvert a point PoincareBallPoint p (from ℝ^n) from the Poincaré ball model of the Hyperbolic manifold mathcal H^n to a PoincareHalfSpacePoint π(p) ℝ^n. Denote by tilde p = (p_1ldotsp_n-1). Then the isometry is defined by\n\nπ(p) = frac1lVert tilde p rVert^2 - (p_n-1)^2\nbeginpmatrix2p_12p_n-11-lVert prVert^2endpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpaceTVector}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpaceTVector}, p::HyperboloidPoint, ::HyperboloidTVector)\nconvert(::Type{PoincareHalfSpaceTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}\n\nconvert a HyperboloidTVector X at p to a PoincareHalfSpaceTVector on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Hyperboloid to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint).\n\nThis is done similarly to the approach there, i.e. by using the Poincaré ball model as an intermediate step.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpaceTVector}, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpaceTVector}, p::PoincareBallPoint, X::PoincareBallTVector)\n\nconvert a PoincareBallTVector X at p to a PoincareHalfSpacePoint on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Poincaré ball to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint).\n\nThe formula reads\n\nπ_*(p)X =\nfrac1lVert tilde prVert^2 + (1-p_n)^2\nbeginpmatrix\n2X_1\n\n2X_n-1\n-2Xp\nendpmatrix\n-\nfrac2(lVert tilde prVert^2 + (1-p_n)^2)^2\nbeginpmatrix\n2p_1(Xp-X_n)\n\n2p_n-1(Xp-X_n)\n(lVert p rVert^2-1)(Xp-X_n)\nendpmatrix\n\nwhere tilde p = beginpmatrixp_1p_n-1endpmatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}, Tuple{HyperboloidPoint, HyperboloidTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},\n (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}\n)\nconvert(\n ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},\n (p, X)::Tuple{P,T},\n) where {P<:AbstractVector, T <: AbstractVector}\n\nConvert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::Tuple{HyperboloidPoint,HyperboloidTVector}) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}, Tuple{PoincareBallPoint, PoincareBallTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},\n (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}\n)\n\nConvert a PoincareBallPoint p and a PoincareBallTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::PoincareBallPoint,::PoincareBallTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.distance-Tuple{Hyperbolic, PoincareHalfSpacePoint, PoincareHalfSpacePoint}","page":"Hyperbolic space","title":"ManifoldsBase.distance","text":"distance(::Hyperbolic, p::PoincareHalfSpacePoint, q::PoincareHalfSpacePoint)\n\nCompute the distance on the Hyperbolic manifold mathcal H^n represented in the Poincaré half space model. The formula reads\n\nd_mathcal H^n(pq) = operatornameacoshBigl( 1 + fraclVert p - q rVert^22 p_n q_n Bigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.inner-Tuple{Hyperbolic, PoincareHalfSpacePoint, PoincareHalfSpaceTVector, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"ManifoldsBase.inner","text":"inner(\n ::Hyperbolic{n},\n p::PoincareHalfSpacePoint,\n X::PoincareHalfSpaceTVector,\n Y::PoincareHalfSpaceTVector\n)\n\nCompute the inner product in the Poincaré half space model. The formula reads\n\ng_p(XY) = fracXYp_n^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.project-Tuple{Hyperbolic, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"ManifoldsBase.project","text":"project(::Hyperbolic, ::PoincareHalfSpacePoint ::PoincareHalfSpaceTVector)\n\nprojction of tangent vectors in the Poincaré half space model is just the identity, since the tangent space consists of all ℝ^n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#poincare_half_plane_plot","page":"Hyperbolic space","title":"Visualization on the Poincaré half plane","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"note: Note\nThe recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We again have two different recipes, one for points, one for tangent vectors, where the first one again can be equipped with geodesics between the points. In the following example we generate 7 points on an ellipse in the Hyperboloid model.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"using Manifolds, Plots\nM = Hyperbolic(2)\npre_pts = [2.0 .* [5.0*cos(φ), sin(φ)] for φ ∈ range(0,2π,length=7)]\npts = convert.(\n Ref(PoincareHalfSpacePoint),\n Manifolds._hyperbolize.(Ref(M), pre_pts)\n)\nscene = plot(M, pts, geodesic_interpolation = 100)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, pts)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind, that a tangent vector in plotting always requires its base point. Here we would like to look at the tangent vectors pointing to the origin","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"origin = PoincareHalfSpacePoint([0.0,1.0])\nvecs = [log(M,p,origin) for p ∈ pts]\nscene = plot!(scene, M, pts, vecs)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"And we can again look at the corresponding geodesics, for example","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, [pts[1], origin], geodesic_interpolation=100)\nplot!(scene, M, [pts[2], origin], geodesic_interpolation=100)","category":"page"},{"location":"manifolds/projectivespace.html#Projective-space","page":"Projective space","title":"Projective space","text":"","category":"section"},{"location":"manifolds/projectivespace.html","page":"Projective space","title":"Projective space","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProjectiveSpace.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/projectivespace.html#Manifolds.AbstractProjectiveSpace","page":"Projective space","title":"Manifolds.AbstractProjectiveSpace","text":"AbstractProjectiveSpace{𝔽} <: AbstractDecoratorManifold{𝔽}\n\nAn abstract type to represent a projective space over 𝔽 that is represented isometrically in the embedding.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/projectivespace.html#Manifolds.ArrayProjectiveSpace","page":"Projective space","title":"Manifolds.ArrayProjectiveSpace","text":"ArrayProjectiveSpace{T<:Tuple,𝔽} <: AbstractProjectiveSpace{𝔽}\n\nThe projective space 𝔽ℙ^n₁n₂nᵢ is the manifold of all lines in 𝔽^n₁n₂nᵢ. The default representation is in the embedding, i.e. as unit (Frobenius) norm matrices in 𝔽^n₁n₂nᵢ:\n\n𝔽ℙ^n_1 n_2 n_i = bigl p 𝔽^n_1 n_2 n_i big lVert p rVert_mathrmF = 1 λ 𝔽 λ = 1 p p λ bigr\n\nwhere p is an equivalence class of points p, sim indicates equivalence, and lVert rVert_mathrmF is the Frobenius norm. Note that unlike ProjectiveSpace, the argument for ArrayProjectiveSpace is given by the size of the embedding. This means that ProjectiveSpace(2) and ArrayProjectiveSpace(3) are the same manifold. Additionally, ArrayProjectiveSpace(n,1;field=𝔽) and Grassmann(n,1;field=𝔽) are the same.\n\nThe tangent space at point p is given by\n\nT_p 𝔽ℙ^n_1 n_2 n_i = bigl X 𝔽^n_1 n_2 n_i pX_mathrmF = 0 bigr \n\nwhere _mathrmF denotes the (Frobenius) inner product in the embedding 𝔽^n_1 n_2 n_i.\n\nConstructor\n\nArrayProjectiveSpace(n₁,n₂,...,nᵢ; field=ℝ)\n\nGenerate the projective space 𝔽ℙ^n_1 n_2 n_i, defaulting to the real projective space, where field can also be used to generate the complex- and right-quaternionic projective spaces.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/projectivespace.html#Manifolds.ProjectiveSpace","page":"Projective space","title":"Manifolds.ProjectiveSpace","text":"ProjectiveSpace{n,𝔽} <: AbstractProjectiveSpace{𝔽}\n\nThe projective space 𝔽ℙ^n is the manifold of all lines in 𝔽^n+1. The default representation is in the embedding, i.e. as unit norm vectors in 𝔽^n+1:\n\n𝔽ℙ^n = bigl p 𝔽^n+1 big lVert p rVert = 1 λ 𝔽 λ = 1 p p λ bigr\n\nwhere p is an equivalence class of points p, and indicates equivalence. For example, the real projective space ℝℙ^n is represented as the unit sphere 𝕊^n, where antipodal points are considered equivalent.\n\nThe tangent space at point p is given by\n\nT_p 𝔽ℙ^n = bigl X 𝔽^n+1 big pX = 0 bigr \n\nwhere denotes the inner product in the embedding 𝔽^n+1.\n\nWhen 𝔽 = ℍ, this implementation of ℍℙ^n is the right-quaternionic projective space.\n\nConstructor\n\nProjectiveSpace(n[, field=ℝ])\n\nGenerate the projective space 𝔽ℙ^n 𝔽^n+1, defaulting to the real projective space ℝℙ^n, where field can also be used to generate the complex- and right-quaternionic projective spaces.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/projectivespace.html#Base.log-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"Base.log","text":"log(M::AbstractProjectiveSpace, p, q)\n\nCompute the logarithmic map on AbstractProjectiveSpace M$ = 𝔽ℙ^n$, i.e. the tangent vector whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads\n\nlog_p q = (q λ - cos θ p) fracθsin θ\n\nwhere θ = arccosq p_mathrmF is the distance between p and q, _mathrmF is the Frobenius inner product, and λ = fracq p_mathrmFq p_mathrmF 𝔽 is the unit scalar that minimizes d_𝔽^n+1(p - q λ). That is, q λ is the member of the equivalence class q that is closest to p in the embedding. As a result, exp_p circ log_p colon q q λ.\n\nThe logarithmic maps for the real AbstractSphere 𝕊^n and the real projective space ℝℙ^n are identical when p and q are in the same hemisphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#Manifolds.manifold_volume-Tuple{AbstractProjectiveSpace{ℝ}}","page":"Projective space","title":"Manifolds.manifold_volume","text":"manifold_volume(M::AbstractProjectiveSpace{ℝ})\n\nVolume of the n-dimensional AbstractProjectiveSpace M. The formula reads:\n\nfracpi^(n+1)2Γ((n+1)2)\n\nwhere Γ denotes the Gamma function. For details see [BoyaSudarshanTilma2003].\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#Manifolds.uniform_distribution-Union{Tuple{n}, Tuple{ProjectiveSpace{n, ℝ}, Any}} where n","page":"Projective space","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::ProjectiveSpace{n,ℝ}, p) where {n}\n\nUniform distribution on given ProjectiveSpace M. Generated points will be of similar type as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase._isapprox-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase._isapprox","text":"isapprox(M::AbstractProjectiveSpace, p, q; kwargs...)\n\nCheck that points p and q on the AbstractProjectiveSpace M=𝔽ℙ^n are members of the same equivalence class, i.e. that p = q λ for some element λ 𝔽 with unit absolute value, that is, λ = 1. This is equivalent to the Riemannian distance being 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.check_point-Tuple{AbstractProjectiveSpace, Any}","page":"Projective space","title":"ManifoldsBase.check_point","text":"check_point(M::AbstractProjectiveSpace, p; kwargs...)\n\nCheck whether p is a valid point on the AbstractProjectiveSpace M, i.e. that it has the same size as elements of the embedding and has unit Frobenius norm. The tolerance for the norm check can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.check_vector-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase.check_vector","text":"check_vector(M::AbstractProjectiveSpace, p, X; kwargs... )\n\nCheck whether X is a tangent vector in the tangent space of p on the AbstractProjectiveSpace M, i.e. that X has the same size as elements of the tangent space of the embedding and that the Frobenius inner product p X_mathrmF = 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.distance-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase.distance","text":"distance(M::AbstractProjectiveSpace, p, q)\n\nCompute the Riemannian distance on AbstractProjectiveSpace M=𝔽ℙ^n between points p and q, i.e.\n\nd_𝔽ℙ^n(p q) = arccosbigl p q_mathrmF bigr\n\nNote that this definition is similar to that of the AbstractSphere. However, the absolute value ensures that all equivalent p and q have the same pairwise distance.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.get_coordinates-Tuple{AbstractProjectiveSpace{ℝ}, Any, Any, DefaultOrthonormalBasis}","page":"Projective space","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})\n\nRepresent the tangent vector X at point p from the AbstractProjectiveSpace M = 𝔽ℙ^n in an orthonormal basis by unitarily transforming the hyperplane containing X, whose normal is p, to the hyperplane whose normal is the x-axis.\n\nGiven q = p overlineλ + x, where λ = fracx p_mathrmFx p_mathrmF, _mathrmF denotes the Frobenius inner product, and overline denotes complex or quaternionic conjugation, the formula for Y is\n\nbeginpmatrix0 Yendpmatrix = left(X - qfrac2 q X_mathrmFq q_mathrmFright)overlineλ\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.get_vector-Tuple{AbstractProjectiveSpace, Any, Any, DefaultOrthonormalBasis{ℝ}}","page":"Projective space","title":"ManifoldsBase.get_vector","text":"get_vector(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})\n\nConvert a one-dimensional vector of coefficients X in the basis B of the tangent space at p on the AbstractProjectiveSpace M=𝔽ℙ^n to a tangent vector Y at p by unitarily transforming the hyperplane containing X, whose normal is the x-axis, to the hyperplane whose normal is p.\n\nGiven q = p overlineλ + x, where λ = fracx p_mathrmFx p_mathrmF, _mathrmF denotes the Frobenius inner product, and overline denotes complex or quaternionic conjugation, the formula for Y is\n\nY = left(X - qfrac2 leftlangle q beginpmatrix0 Xendpmatrixrightrangle_mathrmFq q_mathrmFright) λ\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.inverse_retract-Tuple{AbstractProjectiveSpace, Any, Any, Union{PolarInverseRetraction, ProjectionInverseRetraction, QRInverseRetraction}}","page":"Projective space","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::AbstractProjectiveSpace, p, q, method::ProjectionInverseRetraction)\ninverse_retract(M::AbstractProjectiveSpace, p, q, method::PolarInverseRetraction)\ninverse_retract(M::AbstractProjectiveSpace, p, q, method::QRInverseRetraction)\n\nCompute the equivalent inverse retraction ProjectionInverseRetraction, PolarInverseRetraction, and QRInverseRetraction on the AbstractProjectiveSpace manifold M=𝔽ℙ^n, i.e.\n\noperatornameretr_p^-1 q = q frac1p q_mathrmF - p\n\nwhere _mathrmF is the Frobenius inner product.\n\nNote that this inverse retraction is equivalent to the three corresponding inverse retractions on Grassmann(n+1,1,𝔽), where the three inverse retractions in this case coincide. For ℝℙ^n, it is the same as the ProjectionInverseRetraction on the real Sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.is_flat-Tuple{AbstractProjectiveSpace}","page":"Projective space","title":"ManifoldsBase.is_flat","text":"is_flat(M::AbstractProjectiveSpace)\n\nReturn true if AbstractProjectiveSpace is of dimension 1 and false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.manifold_dimension-Union{Tuple{AbstractProjectiveSpace{𝔽}}, Tuple{𝔽}} where 𝔽","page":"Projective space","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::AbstractProjectiveSpace{𝔽}) where {𝔽}\n\nReturn the real dimension of the AbstractProjectiveSpace M, respectively i.e. the real dimension of the embedding minus the real dimension of the field 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.parallel_transport_direction-Tuple{AbstractProjectiveSpace, Any, Any, Any}","page":"Projective space","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::AbstractProjectiveSpace, p, X, d)\n\nParallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M along the geodesic in the direction indicated by the tangent vector d, i.e.\n\nmathcalP_exp_p (d) p(X) = X - left(p fracsin θθ + d frac1 - cos θθ^2right) d X_p\n\nwhere θ = lVert d rVert, and _p is the inner product at the point p. For the real projective space, this is equivalent to the same vector transport on the real AbstractSphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.parallel_transport_to-Tuple{AbstractProjectiveSpace, Any, Any, Any}","page":"Projective space","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::AbstractProjectiveSpace, p, X, q)\n\nParallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M=𝔽ℙ^n to the tangent space at another point q.\n\nThis implementation proceeds by transporting X to T_q λ M using the same approach as parallel_transport_direction, where λ = fracq p_mathrmFq p_mathrmF 𝔽 is the unit scalar that takes q to the member q λ of its equivalence class q closest to p in the embedding. It then maps the transported vector from T_q λ M to T_q M. The resulting transport to T_q M is\n\nmathcalP_q p(X) = left(X - left(p fracsin θθ + d frac1 - cos θθ^2right) d X_pright) overlineλ\n\nwhere d = log_p q is the direction of the transport, θ = lVert d rVert_p is the distance between p and q, and overline denotes complex or quaternionic conjugation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.project-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase.project","text":"project(M::AbstractProjectiveSpace, p, X)\n\nOrthogonally project the point X onto the tangent space at p on the AbstractProjectiveSpace M:\n\noperatornameproj_p (X) = X - pp X_mathrmF\n\nwhere _mathrmF denotes the Frobenius inner product. For the real AbstractSphere and AbstractProjectiveSpace, this projection is the same.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.project-Tuple{AbstractProjectiveSpace, Any}","page":"Projective space","title":"ManifoldsBase.project","text":"project(M::AbstractProjectiveSpace, p)\n\nOrthogonally project the point p from the embedding onto the AbstractProjectiveSpace M:\n\noperatornameproj(p) = fracplVert p rVert_mathrmF\n\nwhere lVert rVert_mathrmF denotes the Frobenius norm. This is identical to projection onto the AbstractSphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.representation_size-Union{Tuple{ArrayProjectiveSpace{N}}, Tuple{N}} where N","page":"Projective space","title":"ManifoldsBase.representation_size","text":"representation_size(M::AbstractProjectiveSpace)\n\nReturn the size points on the AbstractProjectiveSpace M are represented as, i.e., the representation size of the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.retract-Tuple{AbstractProjectiveSpace, Any, Any, Union{PolarRetraction, ProjectionRetraction, QRRetraction}}","page":"Projective space","title":"ManifoldsBase.retract","text":"retract(M::AbstractProjectiveSpace, p, X, method::ProjectionRetraction)\nretract(M::AbstractProjectiveSpace, p, X, method::PolarRetraction)\nretract(M::AbstractProjectiveSpace, p, X, method::QRRetraction)\n\nCompute the equivalent retraction ProjectionRetraction, PolarRetraction, and QRRetraction on the AbstractProjectiveSpace manifold M=𝔽ℙ^n, i.e.\n\noperatornameretr_p X = operatornameproj_p(p + X)\n\nNote that this retraction is equivalent to the three corresponding retractions on Grassmann(n+1,1,𝔽), where in this case they coincide. For ℝℙ^n, it is the same as the ProjectionRetraction on the real Sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#Statistics.mean-Tuple{AbstractProjectiveSpace, Vararg{Any}}","page":"Projective space","title":"Statistics.mean","text":"mean(\n M::AbstractProjectiveSpace,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/4);\n kwargs...,\n)\n\nCompute the Riemannian mean of points in vector x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#VectorBundleSection","page":"Vector bundle","title":"Vector bundles","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Vector bundle E is a manifold that is built on top of another manifold mathcal M (base space). It is characterized by a continuous function Π E mathcal M, such that for each point p mathcal M the preimage of p by Π, Π^-1(p), has a structure of a vector space. These vector spaces are called fibers. Bundle projection can be performed using function bundle_projection.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point x. An object representing a tangent bundle can be obtained using the constructor called TangentBundle.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Fibers of a vector bundle are represented by the type VectorBundleFibers. The important difference between functions operating on VectorBundle and VectorBundleFibers is that in the first case both a point on the underlying manifold and the vector are represented together (by a single argument) while in the second case only the vector part is present, while the point is supplied in a different argument where needed.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"VectorBundleFibers refers to the whole set of fibers of a vector bundle. There is also another type, VectorSpaceAtPoint, that represents a specific fiber at a given point. This distinction is made to reduce the need to repeatedly construct objects of type VectorSpaceAtPoint in certain usage scenarios. This is also considered a manifold.","category":"page"},{"location":"manifolds/vector_bundle.html#FVector","page":"Vector bundle","title":"FVector","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"For cases where confusion between different types of vectors is possible, the type FVector can be used to express which type of vector space the vector belongs to. It is used for example in musical isomorphisms (the flat and sharp functions) that are used to go from a tangent space to cotangent space and vice versa.","category":"page"},{"location":"manifolds/vector_bundle.html#Documentation","page":"Vector bundle","title":"Documentation","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/VectorBundle.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.TangentSpace-Tuple{AbstractManifold, Any}","page":"Vector bundle","title":"ManifoldsBase.TangentSpace","text":"TangentSpace(M::AbstractManifold, p)\n\nReturn a TangentSpaceAtPoint representing tangent space at p on the AbstractManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.CotangentSpaceAtPoint-Tuple{AbstractManifold, Any}","page":"Vector bundle","title":"Manifolds.CotangentSpaceAtPoint","text":"CotangentSpaceAtPoint(M::AbstractManifold, p)\n\nReturn an object of type VectorSpaceAtPoint representing cotangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.SasakiRetraction","page":"Vector bundle","title":"Manifolds.SasakiRetraction","text":"struct SasakiRetraction <: AbstractRetractionMethod end\n\nExponential map on TangentBundle computed via Euler integration as described in [Muralidharan2012]. The system of equations for gamma ℝ to Tmathcal M such that gamma(1) = exp_pX(X_M X_F) and gamma(0)=(p X) reads\n\ndotgamma(t) = (dotp(t) dotX(t)) = (R(X(t) dotX(t))dotp(t) 0)\n\nwhere R is the Riemann curvature tensor (see riemann_tensor).\n\nConstructor\n\nSasakiRetraction(L::Int)\n\nIn this constructor L is the number of integration steps.\n\n[Muralidharan2012]: P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012, pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.TangentBundle","page":"Vector bundle","title":"Manifolds.TangentBundle","text":"TangentBundle{𝔽,M} = VectorBundle{𝔽,TangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}\n\nTangent bundle for manifold of type M, as a manifold with the Sasaki metric [Sasaki1958].\n\nExact retraction and inverse retraction can be approximated using VectorBundleProductRetraction, VectorBundleInverseProductRetraction and SasakiRetraction. VectorBundleProductVectorTransport can be used as a vector transport.\n\n[Sasaki1958]: S. Sasaki, “On the differential geometry of tangent bundles of Riemannian manifolds,” Tohoku Math. J. (2), vol. 10, no. 3, pp. 338–354, 1958, doi: 10.2748/tmj/1178244668.\n\nConstructors\n\nTangentBundle(M::AbstractManifold)\nTangentBundle(M::AbstractManifold, vtm::VectorBundleProductVectorTransport)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.TangentSpaceAtPoint","page":"Vector bundle","title":"Manifolds.TangentSpaceAtPoint","text":"TangentSpaceAtPoint{M}\n\nAlias for VectorSpaceAtPoint for the tangent space at a point.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.TangentSpaceAtPoint-Tuple{AbstractManifold, Any}","page":"Vector bundle","title":"Manifolds.TangentSpaceAtPoint","text":"TangentSpaceAtPoint(M::AbstractManifold, p)\n\nReturn an object of type VectorSpaceAtPoint representing tangent space at p on the AbstractManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.TensorProductType","page":"Vector bundle","title":"Manifolds.TensorProductType","text":"TensorProductType(spaces::VectorSpaceType...)\n\nVector space type corresponding to the tensor product of given vector space types.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundle","page":"Vector bundle","title":"Manifolds.VectorBundle","text":"VectorBundle{𝔽,TVS<:VectorSpaceType,TM<:AbstractManifold{𝔽}} <: AbstractManifold{𝔽}\n\nVector bundle on a AbstractManifold M of type VectorSpaceType.\n\nConstructor\n\nVectorBundle(M::AbstractManifold, type::VectorSpaceType)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleFibers","page":"Vector bundle","title":"Manifolds.VectorBundleFibers","text":"VectorBundleFibers(fiber::VectorSpaceType, M::AbstractManifold)\n\nType representing a family of vector spaces (fibers) of a vector bundle over M with vector spaces of type fiber. In contrast with VectorBundle, operations on VectorBundleFibers expect point-like and vector-like parts to be passed separately instead of being bundled together. It can be thought of as a representation of vector spaces from a vector bundle but without storing the point at which a vector space is attached (which is specified separately in various functions).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleInverseProductRetraction","page":"Vector bundle","title":"Manifolds.VectorBundleInverseProductRetraction","text":"struct VectorBundleInverseProductRetraction <: AbstractInverseRetractionMethod end\n\nInverse retraction of the point y at point p from vector bundle B over manifold B.fiber (denoted mathcal M). The inverse retraction is derived as a product manifold-style approximation to the logarithmic map in the Sasaki metric. The considered product manifold is the product between the manifold mathcal M and the topological vector space isometric to the fiber.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B. Similarly, q = (x_q V_q).\n\nThe inverse retraction is calculated as\n\noperatornameretr^-1_p q = (operatornameretr^-1_x_p(x_q) V_operatornameretr^-1 - V_p)\n\nwhere V_operatornameretr^-1 is the result of vector transport of V_q to the point x_p. The difference V_operatornameretr^-1 - V_p corresponds to the logarithmic map in the vector space F.\n\nSee also VectorBundleProductRetraction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleProductRetraction","page":"Vector bundle","title":"Manifolds.VectorBundleProductRetraction","text":"struct VectorBundleProductRetraction <: AbstractRetractionMethod end\n\nProduct retraction map of tangent vector X at point p from vector bundle B over manifold B.fiber (denoted mathcal M). The retraction is derived as a product manifold-style approximation to the exponential map in the Sasaki metric. The considered product manifold is the product between the manifold mathcal M and the topological vector space isometric to the fiber.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\nThe tangent vector X = (V_XM V_XF) T_pB where V_XM is a tangent vector from the tangent space T_x_pmathcal M and V_XF is a tangent vector from the tangent space T_V_pF (isomorphic to F).\n\nThe retraction is calculated as\n\noperatornameretr_p(X) = (exp_x_p(V_XM) V_exp)\n\nwhere V_exp is the result of vector transport of V_p + V_XF to the point exp_x_p(V_XM). The sum V_p + V_XF corresponds to the exponential map in the vector space F.\n\nSee also VectorBundleInverseProductRetraction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleProductVectorTransport","page":"Vector bundle","title":"Manifolds.VectorBundleProductVectorTransport","text":"VectorBundleProductVectorTransport{\n TMP<:AbstractVectorTransportMethod,\n TMV<:AbstractVectorTransportMethod,\n} <: AbstractVectorTransportMethod\n\nVector transport type on VectorBundle. method_point is used for vector transport of the point part and method_vector is used for transport of the vector part.\n\nThe vector transport is derived as a product manifold-style vector transport. The considered product manifold is the product between the manifold mathcal M and the topological vector space isometric to the fiber.\n\nConstructor\n\nVectorBundleProductVectorTransport(\n method_point::AbstractVectorTransportMethod,\n method_vector::AbstractVectorTransportMethod,\n)\nVectorBundleProductVectorTransport()\n\nBy default both methods are set to ParallelTransport.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleVectorTransport","page":"Vector bundle","title":"Manifolds.VectorBundleVectorTransport","text":"const VectorBundleVectorTransport = VectorBundleProductVectorTransport\n\nDeprecated: an alias for VectorBundleProductVectorTransport.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorSpaceAtPoint","page":"Vector bundle","title":"Manifolds.VectorSpaceAtPoint","text":"VectorSpaceAtPoint{\n 𝔽,\n TFiber<:VectorBundleFibers{<:VectorSpaceType,<:AbstractManifold{𝔽}},\n TX,\n} <: AbstractManifold{𝔽}\n\nA vector space at a point p on the manifold. This is modelled using VectorBundleFibers with only a vector-like part and fixing the point-like part to be just p.\n\nThis vector space itself is also a manifold. Especially, it's flat and hence isometric to the Euclidean manifold.\n\nConstructor\n\nVectorSpaceAtPoint(fiber::VectorBundleFibers, p)\n\nA vector space (fiber type fiber of a vector bundle) at point p from the manifold fiber.manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Base.exp-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any}","page":"Vector bundle","title":"Base.exp","text":"exp(M::TangentSpaceAtPoint, p, X)\n\nExponential map of tangent vectors X and p from the tangent space M. It is calculated as their sum.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.getindex-Tuple{ArrayPartition, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.getindex","text":"getindex(p::ArrayPartition, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s]\n\nAccess the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.getindex-Tuple{ProductRepr, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.getindex","text":"getindex(p::ProductRepr, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s]\n\nAccess the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.log-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Vararg{Any}}","page":"Vector bundle","title":"Base.log","text":"log(M::TangentSpaceAtPoint, p, q)\n\nLogarithmic map on the tangent space manifold M, calculated as the difference of tangent vectors q and p from M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.setindex!-Tuple{ArrayPartition, Any, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.setindex!","text":"setindex!(p::ArrayPartition, val, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s] = val\n\nSet the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.\n\nnote: Note\nThe content of element of p is replaced, not the element itself.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.setindex!-Tuple{ProductRepr, Any, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.setindex!","text":"setindex!(p::ProductRepr, val, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s] = val\n\nSet the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.\n\nnote: Note\nThe content of element of p is replaced, not the element itself.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#LinearAlgebra.norm-Tuple{VectorBundleFibers, Any, Any}","page":"Vector bundle","title":"LinearAlgebra.norm","text":"norm(B::VectorBundleFibers, p, q)\n\nNorm of the vector X from the vector space of type B.fiber at point p from manifold B.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.bundle_projection-Tuple{VectorBundle, Any}","page":"Vector bundle","title":"Manifolds.bundle_projection","text":"bundle_projection(B::VectorBundle, p::ArrayPartition)\n\nProjection of point p from the bundle M to the base manifold. Returns the point on the base manifold B.manifold at which the vector part of p is attached.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.inverse_retract_product-Tuple{VectorBundle, Any, Any}","page":"Vector bundle","title":"Manifolds.inverse_retract_product","text":"inverse_retract_product(M::VectorBundle, p, q)\n\nCompute the allocating variant of the VectorBundleInverseProductRetraction, which by default allocates and calls inverse_retract_product!.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.retract_product-Tuple{VectorBundle, Any, Any, Number}","page":"Vector bundle","title":"Manifolds.retract_product","text":"retract_product(M::VectorBundle, p, q, t::Number)\n\nCompute the allocating variant of the VectorBundleProductRetraction, which by default allocates and calls retract_product!.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.retract_sasaki-Tuple{AbstractManifold, Any, Any, Number, SasakiRetraction}","page":"Vector bundle","title":"Manifolds.retract_sasaki","text":"retract_sasaki(M::AbstractManifold, p, X, t::Number, m::SasakiRetraction)\n\nCompute the allocating variant of the SasakiRetraction, which by default allocates and calls retract_sasaki!.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.vector_bundle_transport-Tuple{VectorSpaceType, AbstractManifold}","page":"Vector bundle","title":"Manifolds.vector_bundle_transport","text":"vector_bundle_transport(fiber::VectorSpaceType, M::AbstractManifold)\n\nDetermine the vector tranport used for exp and log maps on a vector bundle with vector space type fiber and manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.allocate_result-Union{Tuple{TF}, Tuple{VectorBundleFibers, TF, Vararg{Any}}} where TF","page":"Vector bundle","title":"ManifoldsBase.allocate_result","text":"allocate_result(B::VectorBundleFibers, f, x...)\n\nAllocates an array for the result of function f that is an element of the vector space of type B.fiber on manifold B.manifold and arguments x... for implementing the non-modifying operation using the modifying operation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.allocate_result_type-Union{Tuple{N}, Tuple{TF}, Tuple{VectorBundleFibers, TF, Tuple{Vararg{Any, N}}}} where {TF, N}","page":"Vector bundle","title":"ManifoldsBase.allocate_result_type","text":"allocate_result_type(B::VectorBundleFibers, f, args::NTuple{N,Any}) where N\n\nReturn type of element of the array that will represent the result of function f for representing an operation with result in the vector space fiber for manifold M on given arguments (passed at a tuple).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.distance-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.distance","text":"distance(M::TangentSpaceAtPoint, p, q)\n\nDistance between vectors p and q from the vector space M. It is calculated as the norm of their difference.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.distance-Tuple{VectorBundleFibers, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.distance","text":"distance(B::VectorBundleFibers, p, X, Y)\n\nDistance between vectors X and Y from the vector space at point p from the manifold B.manifold, that is the base manifold of M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.injectivity_radius-Tuple{TangentBundle{𝔽} where 𝔽}","page":"Vector bundle","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::TangentBundle)\n\nInjectivity radius of TangentBundle manifold is infinite if the base manifold is flat and 0 otherwise. See https://mathoverflow.net/questions/94322/injectivity-radius-of-the-sasaki-metric.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.injectivity_radius-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽}","page":"Vector bundle","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::TangentSpaceAtPoint)\n\nReturn the injectivity radius on the TangentSpaceAtPoint M, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.inner-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.inner","text":"inner(M::TangentSpaceAtPoint, p, X, Y)\n\nInner product of vectors X and Y from the tangent space at M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.inner-Tuple{VectorBundle, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.inner","text":"inner(B::VectorBundle, p, X, Y)\n\nInner product of tangent vectors X and Y at point p from the vector bundle B over manifold B.fiber (denoted mathcal M).\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\nThe tangent vector v = (V_XM V_XF) T_xB where V_XM is a tangent vector from the tangent space T_x_pmathcal M and V_XF is a tangent vector from the tangent space T_V_pF (isomorphic to F). Similarly for the other tangent vector w = (V_YM V_YF) T_xB.\n\nThe inner product is calculated as\n\nX Y_p = V_XM V_YM_x_p + V_XF V_YF_V_p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.inner-Tuple{VectorBundleFibers, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.inner","text":"inner(B::VectorBundleFibers, p, X, Y)\n\nInner product of vectors X and Y from the vector space of type B.fiber at point p from manifold B.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.is_flat-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽}","page":"Vector bundle","title":"ManifoldsBase.is_flat","text":"is_flat(::TangentSpaceAtPoint)\n\nReturn true. TangentSpaceAtPoint is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.is_flat-Tuple{VectorBundle}","page":"Vector bundle","title":"ManifoldsBase.is_flat","text":"is_flat(::VectorBundle)\n\nReturn true if the underlying manifold of VectorBundle M is flat.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(M::TangentSpaceAtPoint, p, X)\n\nProject the vector X from the tangent space M, that is project the vector X tangent at M.point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(M::TangentSpaceAtPoint, p)\n\nProject the point p from the tangent space M, that is project the vector p tangent at M.point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{VectorBundle, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(B::VectorBundle, p, X)\n\nProject the element X of the ambient space of the tangent space T_p B to the tangent space T_p B.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\nThe vector x = (V_XM V_XF) where x_p belongs to the ambient space of T_x_pmathcal M and V_XF belongs to the ambient space of the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\n\nThe projection is calculated by projecting V_XM to tangent space T_x_pmathcal M and then projecting the vector V_XF to the fiber F.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{VectorBundle, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(B::VectorBundle, p)\n\nProject the point p from the ambient space of the vector bundle B over manifold B.fiber (denoted mathcal M) to the vector bundle.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p belongs to the ambient space of mathcal M and V_p belongs to the ambient space of the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\n\nThe projection is calculated by projecting the point x_p to the manifold mathcal M and then projecting the vector V_p to the tangent space T_x_pmathcal M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{VectorBundleFibers, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(B::VectorBundleFibers, p, X)\n\nProject vector X from the vector space of type B.fiber at point p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.vector_transport_to-Tuple{VectorBundle, Any, Any, Any, Manifolds.VectorBundleProductVectorTransport}","page":"Vector bundle","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::VectorBundle, p, X, q, m::VectorBundleProductVectorTransport)\n\nCompute the vector transport the tangent vector Xat p to q on the VectorBundle M using the VectorBundleProductVectorTransport m.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector!-Tuple{VectorBundleFibers, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.zero_vector!","text":"zero_vector!(B::VectorBundleFibers, X, p)\n\nSave the zero vector from the vector space of type B.fiber at point p from manifold B.manifold to X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Vararg{Any}}","page":"Vector bundle","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::TangentSpaceAtPoint, p)\n\nZero tangent vector at point p from the tangent space M, that is the zero tangent vector at point M.point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector-Tuple{VectorBundle, Vararg{Any}}","page":"Vector bundle","title":"ManifoldsBase.zero_vector","text":"zero_vector(B::VectorBundle, p)\n\nZero tangent vector at point p from the vector bundle B over manifold B.fiber (denoted mathcal M). The zero vector belongs to the space T_pB\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\n\nThe zero vector is calculated as\n\nmathbf0_p = (mathbf0_x_p mathbf0_F)\n\nwhere mathbf0_x_p is the zero tangent vector from T_x_pmathcal M and mathbf0_F is the zero element of the vector space F.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector-Tuple{VectorBundleFibers, Any}","page":"Vector bundle","title":"ManifoldsBase.zero_vector","text":"zero_vector(B::VectorBundleFibers, p)\n\nCompute the zero vector from the vector space of type B.fiber at point p from manifold B.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Example","page":"Vector bundle","title":"Example","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"The following code defines a point on the tangent bundle of the sphere S^2 and a tangent vector to that point.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"using Manifolds\nM = Sphere(2)\nTB = TangentBundle(M)\np = ProductRepr([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])\nX = ProductRepr([0.0, 1.0, 0.0], [0.0, 0.0, -2.0])","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"An approximation of the exponential in the Sasaki metric using 1000 steps can be calculated as follows.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"q = retract(TB, p, X, SasakiRetraction(1000))\nprintln(\"Approximation of the exponential map: \", q)","category":"page"},{"location":"manifolds/spheresymmetricmatrices.html#Unit-norm-symmetric-matrices","page":"Unit-norm symmetric matrices","title":"Unit-norm symmetric matrices","text":"","category":"section"},{"location":"manifolds/spheresymmetricmatrices.html","page":"Unit-norm symmetric matrices","title":"Unit-norm symmetric matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/SphereSymmetricMatrices.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/spheresymmetricmatrices.html#Manifolds.SphereSymmetricMatrices","page":"Unit-norm symmetric matrices","title":"Manifolds.SphereSymmetricMatrices","text":"SphereSymmetricMatrices{n,𝔽} <: AbstractEmbeddedManifold{ℝ,TransparentIsometricEmbedding}\n\nThe AbstractManifold consisting of the n n symmetric matrices of unit Frobenius norm, i.e.\n\nmathcalS_textsym =biglp 𝔽^n n big p^mathrmH = p lVert p rVert = 1 bigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ.\n\nConstructor\n\nSphereSymmetricMatrices(n[, field=ℝ])\n\nGenerate the manifold of n-by-n symmetric matrices of unit Frobenius norm.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{SphereSymmetricMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.check_point","text":"check_point(M::SphereSymmetricMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether the matrix is a valid point on the SphereSymmetricMatrices M, i.e. is an n-by-n symmetric matrix of unit Frobenius norm.\n\nThe tolerance for the symmetry of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{SphereSymmetricMatrices{n, 𝔽}, Any, Any}} where {n, 𝔽}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::SphereSymmetricMatrices{n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SphereSymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) of unit Frobenius norm.\n\nThe tolerance for the symmetry of p and X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.is_flat-Tuple{SphereSymmetricMatrices}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::SphereSymmetricMatrices)\n\nReturn false. SphereSymmetricMatrices is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.manifold_dimension-Union{Tuple{SphereSymmetricMatrices{n, 𝔽}}, Tuple{𝔽}, Tuple{n}} where {n, 𝔽}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SphereSymmetricMatrices{n,𝔽})\n\nReturn the manifold dimension of the SphereSymmetricMatrices n-by-n symmetric matrix M of unit Frobenius norm over the number system 𝔽, i.e.\n\nbeginaligned\ndim(mathcalS_textsym)(nℝ) = fracn(n+1)2 - 1\ndim(mathcalS_textsym)(nℂ) = 2fracn(n+1)2 - n -1\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.project-Tuple{SphereSymmetricMatrices, Any, Any}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SphereSymmetricMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the SphereSymmetricMatrices M, i.e.\n\noperatornameproj_p(X) = fracX + X^mathrmH2 - p fracX + X^mathrmH2p\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.project-Tuple{SphereSymmetricMatrices, Any}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SphereSymmetricMatrices, p)\n\nProjects p from the embedding onto the SphereSymmetricMatrices M, i.e.\n\noperatornameproj_mathcalS_textsym(p) = frac12 bigl( p + p^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Positive-Numbers","page":"Positive numbers","title":"Positive Numbers","text":"","category":"section"},{"location":"manifolds/positivenumbers.html","page":"Positive numbers","title":"Positive numbers","text":"The manifold PositiveNumbers represents positive numbers with hyperbolic geometry. Additionally, there are also short forms for its corresponding PowerManifolds, i.e. PositiveVectors, PositiveMatrices, and PositiveArrays.","category":"page"},{"location":"manifolds/positivenumbers.html","page":"Positive numbers","title":"Positive numbers","text":"Modules = [Manifolds]\nPages = [\"manifolds/PositiveNumbers.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveNumbers","page":"Positive numbers","title":"Manifolds.PositiveNumbers","text":"PositiveNumbers <: AbstractManifold{ℝ}\n\nThe hyperbolic manifold of positive numbers H^1 is a the hyperbolic manifold represented by just positive numbers.\n\nConstructor\n\nPositiveNumbers()\n\nGenerate the ℝ-valued hyperbolic model represented by positive positive numbers. To use this with arrays (1-element arrays), please use SymmetricPositiveDefinite(1).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/positivenumbers.html#Base.exp-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"Base.exp","text":"exp(M::PositiveNumbers, p, X)\n\nCompute the exponential map on the PositiveNumbers M.\n\nexp_p X = poperatornameexp(Xp)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Base.log-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"Base.log","text":"log(M::PositiveNumbers, p, q)\n\nCompute the logarithmic map on the PositiveNumbers M.\n\nlog_p q = plogfracqp\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveArrays-Union{Tuple{Vararg{Int64, I}}, Tuple{I}} where I","page":"Positive numbers","title":"Manifolds.PositiveArrays","text":"PositiveArrays(n₁,n₂,...,nᵢ)\n\nGenerate the manifold of i-dimensional arrays with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveMatrices-Tuple{Integer, Integer}","page":"Positive numbers","title":"Manifolds.PositiveMatrices","text":"PositiveMatrices(m,n)\n\nGenerate the manifold of matrices with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveVectors-Tuple{Integer}","page":"Positive numbers","title":"Manifolds.PositiveVectors","text":"PositiveVectors(n)\n\nGenerate the manifold of vectors with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.manifold_volume-Tuple{PositiveNumbers}","page":"Positive numbers","title":"Manifolds.manifold_volume","text":"manifold_volume(M::PositiveNumbers)\n\nReturn volume of PositiveNumbers M, i.e. Inf.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.volume_density-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"Manifolds.volume_density","text":"volume_density(M::PositiveNumbers, p, X)\n\nCompute volume density function of PositiveNumbers. The formula reads\n\ntheta_p(X) = exp(X p)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.change_metric-Tuple{PositiveNumbers, EuclideanMetric, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.change_metric","text":"change_metric(M::PositiveNumbers, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric of PositiveNumbers M.\n\nFor all ZY we are looking for the function c on the tangent space at p such that\n\n ZY = XY = fracc(Z)c(Y)p^2 = g_p(c(Y)c(Z))\n\nand hence C(X) = pX.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.change_representer-Tuple{PositiveNumbers, EuclideanMetric, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.change_representer","text":"change_representer(M::PositiveNumbers, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric representation of PositiveNumbers M.\n\nFor all tangent vectors Y the result Z has to fulfill\n\n XY = XY = fracZYp^2 = g_p(YZ)\n\nand hence Z = p^2X\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.check_point-Tuple{PositiveNumbers, Any}","page":"Positive numbers","title":"ManifoldsBase.check_point","text":"check_point(M::PositiveNumbers, p)\n\nCheck whether p is a point on the PositiveNumbers M, i.e. p0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.check_vector-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.check_vector","text":"check_vector(M::PositiveNumbers, p, X; kwargs...)\n\nCheck whether X is a tangent vector in the tangent space of p on the PositiveNumbers M. For the real-valued case represented by positive numbers, all X are valid, since the tangent space is the whole real line. For the complex-valued case X [...]\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.distance-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.distance","text":"distance(M::PositiveNumbers, p, q)\n\nCompute the distance on the PositiveNumbers M, which is\n\nd(pq) = Bigllvert log fracpq Bigrrvert = lvert log p - log qrvert\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.get_coordinates-Tuple{PositiveNumbers, Any, Any, DefaultOrthonormalBasis{ℝ}}","page":"Positive numbers","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(::PositiveNumbers, p, X, ::DefaultOrthonormalBasis{ℝ})\n\nCompute the coordinate of vector X which is tangent to p on the PositiveNumbers manifold. The formula is X p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.get_vector-Tuple{PositiveNumbers, Any, Any, DefaultOrthonormalBasis{ℝ}}","page":"Positive numbers","title":"ManifoldsBase.get_vector","text":"get_vector(::PositiveNumbers, p, c, ::DefaultOrthonormalBasis{ℝ})\n\nCompute the vector with coordinate c which is tangent to p on the PositiveNumbers manifold. The formula is p * c.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.injectivity_radius-Tuple{PositiveNumbers}","page":"Positive numbers","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::PositiveNumbers[, p])\n\nReturn the injectivity radius on the PositiveNumbers M, i.e. infty.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.inner-Tuple{PositiveNumbers, Vararg{Any}}","page":"Positive numbers","title":"ManifoldsBase.inner","text":"inner(M::PositiveNumbers, p, X, Y)\n\nCompute the inner product of the two tangent vectors X,Y from the tangent plane at p on the PositiveNumbers M, i.e.\n\ng_p(XY) = fracXYp^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.is_flat-Tuple{PositiveNumbers}","page":"Positive numbers","title":"ManifoldsBase.is_flat","text":"is_flat(::PositiveNumbers)\n\nReturn false. PositiveNumbers is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.manifold_dimension-Tuple{PositiveNumbers}","page":"Positive numbers","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::PositiveNumbers)\n\nReturn the dimension of the PositiveNumbers M, i.e. of the 1-dimensional hyperbolic space,\n\ndim(H^1) = 1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.parallel_transport_to-Tuple{PositiveNumbers, Any, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::PositiveNumbers, p, X, q)\n\nCompute the parallel transport of X from the tangent space at p to the tangent space at q on the PositiveNumbers M.\n\nmathcal P_qgets p(X) = Xcdotfracqp\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.project-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.project","text":"project(M::PositiveNumbers, p, X)\n\nProject a value X onto the tangent space of the point p on the PositiveNumbers M, which is just the identity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Torus","page":"Torus","title":"Torus","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"The torus 𝕋^d -ππ)^d is modeled as an AbstractPowerManifold of the (real-valued) Circle and uses ArrayPowerRepresentation. Points on the torus are hence row vectors, x ℝ^d.","category":"page"},{"location":"manifolds/torus.html#Example","page":"Torus","title":"Example","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"The following code can be used to make a three-dimensional torus 𝕋^3 and compute a tangent vector:","category":"page"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"using Manifolds\nM = Torus(3)\np = [0.5, 0.0, 0.0]\nq = [0.0, 0.5, 1.0]\nX = log(M, p, q)","category":"page"},{"location":"manifolds/torus.html#Types-and-functions","page":"Torus","title":"Types and functions","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:","category":"page"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Modules = [Manifolds]\nPages = [\"manifolds/Torus.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/torus.html#Manifolds.Torus","page":"Torus","title":"Manifolds.Torus","text":"Torus{N} <: AbstractPowerManifold\n\nThe n-dimensional torus is the n-dimensional product of the Circle.\n\nThe Circle is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/torus.html#ManifoldsBase.check_point-Tuple{Torus, Any}","page":"Torus","title":"ManifoldsBase.check_point","text":"check_point(M::Torus{n},p)\n\nChecks whether p is a valid point on the Torus M, i.e. each of its entries is a valid point on the Circle and the length of x is n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.check_vector-Union{Tuple{N}, Tuple{Torus{N}, Any, Any}} where N","page":"Torus","title":"ManifoldsBase.check_vector","text":"check_vector(M::Torus{n}, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the Torus M. This means, that p is valid, that X is of correct dimension and elementwise a tangent vector to the elements of p on the Circle.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Embedded-Torus","page":"Torus","title":"Embedded Torus","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Two-dimensional torus embedded in ℝ^3.","category":"page"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Modules = [Manifolds]\nPages = [\"manifolds/EmbeddedTorus.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/torus.html#Manifolds.DefaultTorusAtlas","page":"Torus","title":"Manifolds.DefaultTorusAtlas","text":"DefaultTorusAtlas()\n\nAtlas for torus with charts indexed by two angles numbers θ₀ φ₀ -π π). Inverse of a chart (θ₀ φ₀) is given by\n\nx(θ φ) = (R + rcos(θ + θ₀))cos(φ + φ₀) \ny(θ φ) = (R + rcos(θ + θ₀))sin(φ + φ₀) \nz(θ φ) = rsin(θ + θ₀)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/torus.html#Manifolds.EmbeddedTorus","page":"Torus","title":"Manifolds.EmbeddedTorus","text":"EmbeddedTorus{TR<:Real} <: AbstractDecoratorManifold{ℝ}\n\nSurface in ℝ³ described by parametric equations:\n\nx(θ φ) = (R + rcos θ)cos φ \ny(θ φ) = (R + rcos θ)sin φ \nz(θ φ) = rsin θ\n\nfor θ, φ in -π π). It is assumed that R r 0.\n\nAlternative names include anchor ring, donut and doughnut.\n\nConstructor\n\nEmbeddedTorus(R, r)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/torus.html#Manifolds.affine_connection-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Vararg{Any, 4}}","page":"Torus","title":"Manifolds.affine_connection","text":"affine_connection(M::EmbeddedTorus, A::DefaultTorusAtlas, i, a, Xc, Yc)\n\nAffine connection on EmbeddedTorus M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.check_chart_switch-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Any, Any}","page":"Torus","title":"Manifolds.check_chart_switch","text":"check_chart_switch(::EmbeddedTorus, A::DefaultTorusAtlas, i, a; ϵ = pi/3)\n\nReturn true if parameters a lie closer than ϵ to chart boundary.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.gaussian_curvature-Tuple{Manifolds.EmbeddedTorus, Any}","page":"Torus","title":"Manifolds.gaussian_curvature","text":"gaussian_curvature(M::EmbeddedTorus, p)\n\nGaussian curvature at point p from EmbeddedTorus M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.inverse_chart_injectivity_radius-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Any}","page":"Torus","title":"Manifolds.inverse_chart_injectivity_radius","text":"inverse_chart_injectivity_radius(M::AbstractManifold, A::AbstractAtlas, i)\n\nInjectivity radius of get_point for chart i from the DefaultTorusAtlas A of the EmbeddedTorus.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.normal_vector-Tuple{Manifolds.EmbeddedTorus, Any}","page":"Torus","title":"Manifolds.normal_vector","text":"normal_vector(M::EmbeddedTorus, p)\n\nOutward-pointing normal vector on the EmbeddedTorus at the point p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.check_point-Tuple{Manifolds.EmbeddedTorus, Any}","page":"Torus","title":"ManifoldsBase.check_point","text":"check_point(M::EmbeddedTorus, p; kwargs...)\n\nCheck whether p is a valid point on the EmbeddedTorus M. The tolerance for the last test can be set using the kwargs....\n\nThe method checks if (p_1^2 + p_2^2 + p_3^2 + R^2 - r^2)^2 is apprximately equal to 4R^2(p_1^2 + p_2^2).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.check_vector-Tuple{Manifolds.EmbeddedTorus, Any, Any}","page":"Torus","title":"ManifoldsBase.check_vector","text":"check_vector(M::EmbeddedTorus, p, X; atol=eps(eltype(p)), kwargs...)\n\nCheck whether X is a valid vector tangent to p on the EmbeddedTorus M. The method checks if the vector X is orthogonal to the vector normal to the torus, see normal_vector. Absolute tolerance can be set using atol.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.inner-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Vararg{Any, 4}}","page":"Torus","title":"ManifoldsBase.inner","text":"inner(M::EmbeddedTorus, ::DefaultTorusAtlas, i, a, Xc, Yc)\n\nInner product on EmbeddedTorus in chart i in the DefaultTorusAtlas. between vectors with coordinates Xc and Yc tangent at point with parameters a. Vector coordinates must be given in the induced basis.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.is_flat-Tuple{Manifolds.EmbeddedTorus}","page":"Torus","title":"ManifoldsBase.is_flat","text":"is_flat(::EmbeddedTorus)\n\nReturn false. EmbeddedTorus is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.manifold_dimension-Tuple{Manifolds.EmbeddedTorus}","page":"Torus","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::EmbeddedTorus)\n\nReturn the dimension of the EmbeddedTorus M that is 2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#The-probability-simplex","page":"Probability simplex","title":"The probability simplex","text":"","category":"section"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProbabilitySimplex.jl\"]\nOrder = [:type, :function]\nPrivate=false\nPublic=true","category":"page"},{"location":"manifolds/probabilitysimplex.html#Manifolds.FisherRaoMetric","page":"Probability simplex","title":"Manifolds.FisherRaoMetric","text":"FisherRaoMetric <: AbstractMetric\n\nThe Fisher-Rao metric or Fisher information metric is a particular Riemannian metric which can be defined on a smooth statistical manifold, i.e., a smooth manifold whose points are probability measures defined on a common probability space.\n\nSee for example the ProbabilitySimplex.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/probabilitysimplex.html#Manifolds.ProbabilitySimplex","page":"Probability simplex","title":"Manifolds.ProbabilitySimplex","text":"ProbabilitySimplex{n,boundary} <: AbstractDecoratorManifold{𝔽}\n\nThe (relative interior of) the probability simplex is the set\n\nΔ^n = biggl p ℝ^n+1 big p_i 0 text for all i=1n+1\ntext and mathbb1p = sum_i=1^n+1 p_i = 1biggr\n\nwhere mathbb1=(11)^mathrmT ℝ^n+1 denotes the vector containing only ones.\n\nIf boundary is set to :open, then the object represents an open simplex. Otherwise, that is when boundary is set to :closed, the boundary is also included:\n\nhatΔ^n = biggl p ℝ^n+1 big p_i geq 0 text for all i=1n+1\ntext and mathbb1p = sum_i=1^n+1 p_i = 1biggr\n\nThis set is also called the unit simplex or standard simplex.\n\nThe tangent space is given by\n\nT_pΔ^n = biggl X ℝ^n+1 big mathbb1X = sum_i=1^n+1 X_i = 0 biggr\n\nThe manifold is implemented assuming the Fisher-Rao metric for the multinomial distribution, which is equivalent to the induced metric from isometrically embedding the probability simplex in the n-sphere of radius 2. The corresponding diffeomorphism varphi mathbb Δ^n mathcal N, where mathcal N subset 2𝕊^n is given by varphi(p) = 2sqrtp.\n\nThis implementation follows the notation in [ÅströmPetraSchmitzerSchnörr2017].\n\nConstructor\n\nProbabilitySimplex(n::Int; boundary::Symbol=:open)\n\n[ÅströmPetraSchmitzerSchnörr2017]: F. Åström, S. Petra, B. Schmitzer, C. Schnörr: “Image Labeling by Assignment”, Journal of Mathematical Imaging and Vision, 58(2), pp. 221–238, 2017. doi: 10.1007/s10851-016-0702-4 arxiv: 1603.05285.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/probabilitysimplex.html#Base.exp-Tuple{ProbabilitySimplex, Vararg{Any}}","page":"Probability simplex","title":"Base.exp","text":"exp(M::ProbabilitySimplex, p, X)\n\nCompute the exponential map on the probability simplex.\n\nexp_pX = frac12Bigl(p+fracX_p^2lVert X_p rVert^2Bigr)\n+ frac12Bigl(p - fracX_p^2lVert X_p rVert^2Bigr)cos(lVert X_prVert)\n+ frac1lVert X_p rVertsqrtpsin(lVert X_prVert)\n\nwhere X_p = fracXsqrtp, with its division meant elementwise, as well as for the operations X_p^2 and sqrtp.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Base.log-Tuple{ProbabilitySimplex, Vararg{Any}}","page":"Probability simplex","title":"Base.log","text":"log(M::ProbabilitySimplex, p, q)\n\nCompute the logarithmic map of p and q on the ProbabilitySimplex M.\n\nlog_pq = fracd_Δ^n(pq)sqrt1-sqrtpsqrtq(sqrtpq - sqrtpsqrtqp)\n\nwhere pq and sqrtp is meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Base.rand-Tuple{ProbabilitySimplex}","page":"Probability simplex","title":"Base.rand","text":"rand(::ProbabilitySimplex; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (uniform over the Fisher-Rao metric; that is, uniform with respect to the n-sphere whose positive orthant is mapped to the simplex). point x on the ProbabilitySimplex manifold M according to the isometric embedding into the n-sphere by normalizing the vector length of a sample from a multivariate Gaussian. See [Marsaglia1972].\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_pmathrmDelta^nby shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.\n\n[Marsaglia1972]: Marsaglia, G.: Choosing a Point from the Surface of a Sphere. Annals of Mathematical Statistics, 43 (2): 645–646, 1972. doi: 10.1214/aoms/1177692644\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldDiff.riemannian_gradient-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldDiff.riemannian_gradient","text":"X = riemannian_gradient(M::ProbabilitySimplex{n}, p, Y)\nriemannian_gradient!(M::ProbabilitySimplex{n}, X, p, Y)\n\nGiven a gradient Y = operatornamegrad tilde f(p) in the embedding ℝ^n+1 of the ProbabilitySimplex Δ^n, this function computes the Riemannian gradient X = operatornamegrad f(p) where f is the function tilde f restricted to the manifold.\n\nThe formula reads\n\n X = p Y - p Yp\n\nwhere denotes the emelementwise product.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.manifold_volume-Union{Tuple{ProbabilitySimplex{n}}, Tuple{n}} where n","page":"Probability simplex","title":"Manifolds.manifold_volume","text":"manifold_volume(::ProbabilitySimplex{n}) where {n}\n\nReturn the volume of the ProbabilitySimplex, i.e. volume of the n-dimensional Sphere divided by 2^n+1, corresponding to the volume of its positive orthant.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.volume_density-Union{Tuple{N}, Tuple{ProbabilitySimplex{N}, Any, Any}} where N","page":"Probability simplex","title":"Manifolds.volume_density","text":"volume_density(M::ProbabilitySimplex{N}, p, X) where {N}\n\nCompute the volume density at point p on ProbabilitySimplex M for tangent vector X. It is computed using isometry with positive orthant of a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.change_metric-Tuple{ProbabilitySimplex, EuclideanMetric, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.change_metric","text":"change_metric(M::ProbabilitySimplex, ::EuclideanMetric, p, X)\n\nTo change the metric, we are looking for a function ccolon T_pΔ^n to T_pΔ^n such that for all XY T_pΔ^n This can be achieved by rewriting representer change in matrix form as (Diagonal(p) - p * p') * X and taking square root of the matrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.change_representer-Tuple{ProbabilitySimplex, EuclideanMetric, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.change_representer","text":"change_representer(M::ProbabilitySimplex, ::EuclideanMetric, p, X)\n\nGiven a tangent vector with respect to the metric from the embedding, the EuclideanMetric, the representer of a linear functional on the tangent space is adapted as Z = p * X - p * dot(p X). The first part “compensates” for the divsion by p in the Riemannian metric on the ProbabilitySimplex and the second part performs appropriate projection to keep the vector tangent.\n\nFor details see Proposition 2.3 in [ÅströmPetraSchmitzerSchnörr2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.check_point-Union{Tuple{boundary}, Tuple{n}, Tuple{ProbabilitySimplex{n, boundary}, Any}} where {n, boundary}","page":"Probability simplex","title":"ManifoldsBase.check_point","text":"check_point(M::ProbabilitySimplex, p; kwargs...)\n\nCheck whether p is a valid point on the ProbabilitySimplex M, i.e. is a point in the embedding with positive entries that sum to one The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.check_vector-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.check_vector","text":"check_vector(M::ProbabilitySimplex, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the ProbabilitySimplex M, i.e. after check_point(M,p), X has to be of same dimension as p and its elements have to sum to one. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.distance-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.distance","text":"distance(M, p, q)\n\nCompute the distance between two points on the ProbabilitySimplex M. The formula reads\n\nd_Δ^n(pq) = 2arccos biggl( sum_i=1^n+1 sqrtp_i q_i biggr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.injectivity_radius-Union{Tuple{n}, Tuple{ProbabilitySimplex{n}, Any}} where n","page":"Probability simplex","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M, p)\n\nCompute the injectivity radius on the ProbabilitySimplex M at the point p, i.e. the distanceradius to a point near/on the boundary, that could be reached by following the geodesic.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.inner-Union{Tuple{boundary}, Tuple{n}, Tuple{ProbabilitySimplex{n, boundary}, Any, Any, Any}} where {n, boundary}","page":"Probability simplex","title":"ManifoldsBase.inner","text":"inner(M::ProbabilitySimplex, p, X, Y)\n\nCompute the inner product of two tangent vectors X, Y from the tangent space T_pΔ^n at p. The formula reads\n\ng_p(XY) = sum_i=1^n+1fracX_iY_ip_i\n\nWhen M includes boundary, we can just skip coordinates where p_i is equal to 0, see Proposition 2.1 in [AyJostLeSchwachhöfer2017].\n\n[AyJostLeSchwachhöfer2017]: N. Ay, J. Jost, H. V. Le, and L. Schwachhöfer, Information Geometry. in Ergebnisse der Mathematik und ihrer Grenzgebiete. 3. Folge / A Series of Modern Surveys in Mathematics. Springer International Publishing, 2017. doi: 10.1007/978-3-319-56478-4\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.inverse_retract-Tuple{ProbabilitySimplex, Any, Any, SoftmaxInverseRetraction}","page":"Probability simplex","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::ProbabilitySimplex, p, q, ::SoftmaxInverseRetraction)\n\nCompute a first order approximation by projection. The formula reads\n\noperatornameretr^-1_p q = bigl( I_n+1 - frac1nmathbb1^n+1n+1 bigr)(log(q)-log(p))\n\nwhere mathbb1^mn is the size (m,n) matrix containing ones, and log is applied elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.is_flat-Tuple{ProbabilitySimplex}","page":"Probability simplex","title":"ManifoldsBase.is_flat","text":"is_flat(::ProbabilitySimplex)\n\nReturn false. ProbabilitySimplex is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.manifold_dimension-Union{Tuple{ProbabilitySimplex{n}}, Tuple{n}} where n","page":"Probability simplex","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::ProbabilitySimplex{n})\n\nReturns the manifold dimension of the probability simplex in ℝ^n+1, i.e.\n\n dim_Δ^n = n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.project-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.project","text":"project(M::ProbabilitySimplex, p, Y)\n\nProject Y from the embedding onto the tangent space at p on the ProbabilitySimplex M. The formula reads\n\n`math \\operatorname{proj}_{Δ^n}(p,Y) = Y - \\bar{Y} where barY denotes mean of Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.project-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"ManifoldsBase.project","text":"project(M::ProbabilitySimplex, p)\n\nproject p from the embedding onto the ProbabilitySimplex M. The formula reads\n\noperatornameproj_Δ^n(p) = frac1mathbb 1pp\n\nwhere mathbb 1 ℝ denotes the vector of ones. Not that this projection is only well-defined if p has positive entries.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.representation_size-Union{Tuple{ProbabilitySimplex{n}}, Tuple{n}} where n","page":"Probability simplex","title":"ManifoldsBase.representation_size","text":"representation_size(::ProbabilitySimplex{n})\n\nReturn the representation size of points in the n-dimensional probability simplex, i.e. an array size of (n+1,).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.retract-Tuple{ProbabilitySimplex, Any, Any, SoftmaxRetraction}","page":"Probability simplex","title":"ManifoldsBase.retract","text":"retract(M::ProbabilitySimplex, p, X, ::SoftmaxRetraction)\n\nCompute a first order approximation by applying the softmax function. The formula reads\n\noperatornameretr_p X = fracpmathrme^Xpmathrme^X\n\nwhere multiplication, exponentiation and division are meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.riemann_tensor-Tuple{ProbabilitySimplex, Vararg{Any, 4}}","page":"Probability simplex","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::ProbabilitySimplex, p, X, Y, Z)\n\nCompute the Riemann tensor R(XY)Z at point p on ProbabilitySimplex M. It is computed using isometry with positive orthant of a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.zero_vector-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::ProbabilitySimplex, p)\n\nReturn the zero tangent vector in the tangent space of the point p from the ProbabilitySimplex M, i.e. its representation by the zero vector in the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Statistics.mean-Tuple{ProbabilitySimplex, Vararg{Any}}","page":"Probability simplex","title":"Statistics.mean","text":"mean(\n M::ProbabilitySimplex,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolation();\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProbabilitySimplexEuclideanMetric.jl\"]\nOrder = [:type, :function]\nPrivate=false\nPublic=true","category":"page"},{"location":"manifolds/probabilitysimplex.html#Base.rand-Tuple{MetricManifold{ℝ, <:ProbabilitySimplex, <:EuclideanMetric}}","page":"Probability simplex","title":"Base.rand","text":"rand(::MetricManifold{ℝ,<:ProbabilitySimplex,<:EuclideanMetric}; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (uniform) point x on the ProbabilitySimplex with the Euclidean metric manifold M by normalizing independent exponential draws to unit sum, see [Devroye1986], Theorems 2.1 and 2.2 on p. 207 and 208, respectively.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_pmathrmDelta^nby shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.\n\n[Devroye1986]: Devroye, L.: Non-Uniform Random Variate Generation. Springer New York, NY, 1986. doi: 10.1007/978-1-4613-8643-8\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.manifold_volume-Union{Tuple{MetricManifold{ℝ, <:ProbabilitySimplex{n}, <:EuclideanMetric}}, Tuple{n}} where n","page":"Probability simplex","title":"Manifolds.manifold_volume","text":"manifold_volume(::MetricManifold{ℝ,<:ProbabilitySimplex{n},<:EuclideanMetric})) where {n}\n\nReturn the volume of the ProbabilitySimplex with the Euclidean metric. The formula reads fracsqrtn+1n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.volume_density-Tuple{MetricManifold{ℝ, <:ProbabilitySimplex, <:EuclideanMetric}, Any, Any}","page":"Probability simplex","title":"Manifolds.volume_density","text":"volume_density(::MetricManifold{ℝ,<:ProbabilitySimplex,<:EuclideanMetric}, p, X)\n\nCompute the volume density at point p on ProbabilitySimplex M for tangent vector X. It is equal to 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Real-probability-amplitudes","page":"Probability simplex","title":"Real probability amplitudes","text":"","category":"section"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"An isometric embedding of interior of ProbabilitySimplex in positive orthant of the Sphere is established through functions simplex_to_amplitude and amplitude_to_simplex. Some properties extend to the boundary but not all.","category":"page"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"This embedding isometrically maps the Fisher-Rao metric on the open probability simplex to the sphere of radius 1 with Euclidean metric. More details can be found in Section 2.2 of [AyJostLeSchwachhöfer2017].","category":"page"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"The name derives from the notion of probability amplitudes in quantum mechanics. They are complex-valued and their squared norm corresponds to probability. This construction restricted to real valued amplitudes results in this embedding.","category":"page"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProbabilitySimplex.jl\"]\nOrder = [:type, :function]\nPrivate=true\nPublic=false","category":"page"},{"location":"manifolds/probabilitysimplex.html#Manifolds.amplitude_to_simplex-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"Manifolds.amplitude_to_simplex","text":"amplitude_to_simplex(M::ProbabilitySimplex{N}, p) where {N}\n\nConvert point (real) probability amplitude p on to a point on ProbabilitySimplex. The formula reads (p_1^2 p_2^2 p_N+1^2). This is an isometry from the interior of the positive orthant of a sphere to interior of the probability simplex.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.amplitude_to_simplex_diff-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"Manifolds.amplitude_to_simplex_diff","text":"amplitude_to_simplex_diff(M::ProbabilitySimplex, p, X)\n\nCompute differential of amplitude_to_simplex of a point p on ProbabilitySimplex at tangent vector X from the tangent space at p from a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.simplex_to_amplitude-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"Manifolds.simplex_to_amplitude","text":"simplex_to_amplitude(M::ProbabilitySimplex, p)\n\nConvert point p on ProbabilitySimplex to (real) probability amplitude. The formula reads (sqrtp_1 sqrtp_2 sqrtp_N+1). This is an isometry from the interior of the probability simplex to the interior of the positive orthant of a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.simplex_to_amplitude_diff-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"Manifolds.simplex_to_amplitude_diff","text":"simplex_to_amplitude_diff(M::ProbabilitySimplex, p, X)\n\nCompute differential of simplex_to_amplitude of a point on p one ProbabilitySimplex at tangent vector X from the tangent space at p from a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Literature","page":"Probability simplex","title":"Literature","text":"","category":"section"},{"location":"manifolds/generalizedstiefel.html#Generalized-Stiefel","page":"Generalized Stiefel","title":"Generalized Stiefel","text":"","category":"section"},{"location":"manifolds/generalizedstiefel.html","page":"Generalized Stiefel","title":"Generalized Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/GeneralizedStiefel.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/generalizedstiefel.html#Manifolds.GeneralizedStiefel","page":"Generalized Stiefel","title":"Manifolds.GeneralizedStiefel","text":"GeneralizedStiefel{n,k,𝔽,B} <: AbstractDecoratorManifold{𝔽}\n\nThe Generalized Stiefel manifold consists of all ntimes k, ngeq k orthonormal matrices w.r.t. an arbitrary scalar product with symmetric positive definite matrix Bin R^n n, i.e.\n\noperatornameSt(nkB) = bigl p in mathbb F^n k big p^mathrmH B p = I_k bigr\n\nwhere 𝔽 ℝ ℂ, cdot^mathrmH denotes the complex conjugate transpose or Hermitian, and I_k in mathbb R^k k denotes the k k identity matrix.\n\nIn the case B=I_k one gets the usual Stiefel manifold.\n\nThe tangent space at a point pinmathcal M=operatornameSt(nkB) is given by\n\nT_pmathcal M = X in 𝔽^n k p^mathrmHBX + X^mathrmHBp=0_n\n\nwhere 0_k is the k k zero matrix.\n\nThis manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the zero_vector are inherited from the embedding.\n\nThe manifold is named after Eduard L. Stiefel (1909–1978).\n\nConstructor\n\nGeneralizedStiefel(n, k, B=I_n, F=ℝ)\n\nGenerate the (real-valued) Generalized Stiefel manifold of ntimes k dimensional orthonormal matrices with scalar product B.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalizedstiefel.html#Base.rand-Tuple{GeneralizedStiefel}","page":"Generalized Stiefel","title":"Base.rand","text":"rand(::GeneralizedStiefel; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (Gaussian) point p on the GeneralizedStiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size nk.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_vector_atmathrmSt(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedStiefel{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Generalized Stiefel","title":"ManifoldsBase.check_point","text":"check_point(M::GeneralizedStiefel, p; kwargs...)\n\nCheck whether p is a valid point on the GeneralizedStiefel M=operatornameSt(nkB), i.e. that it has the right AbstractNumbers type and x^mathrmHBx is (approximately) the identity, where cdot^mathrmH is the complex conjugate transpose. The settings for approximately can be set with kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedStiefel{n, k, 𝔽}, Any, Any}} where {n, k, 𝔽}","page":"Generalized Stiefel","title":"ManifoldsBase.check_vector","text":"check_vector(M::GeneralizedStiefel, p, X; kwargs...)\n\nCheck whether X is a valid tangent vector at p on the GeneralizedStiefel M=operatornameSt(nkB), i.e. the AbstractNumbers fits, p is a valid point on M and it (approximately) holds that p^mathrmHBX + overlineX^mathrmHBp = 0, where kwargs... is passed to the isapprox.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.inner-Tuple{GeneralizedStiefel, Any, Any, Any}","page":"Generalized Stiefel","title":"ManifoldsBase.inner","text":"inner(M::GeneralizedStiefel, p, X, Y)\n\nCompute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedStiefel manifold M. The formula reads\n\n(X Y)_p = operatornametrace(v^mathrmHBw)\n\ni.e. the metric induced by the scalar product B from the embedding, restricted to the tangent space.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.is_flat-Tuple{GeneralizedStiefel}","page":"Generalized Stiefel","title":"ManifoldsBase.is_flat","text":"is_flat(M::GeneralizedStiefel)\n\nReturn true if GeneralizedStiefel M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.manifold_dimension-Union{Tuple{GeneralizedStiefel{n, k, ℝ}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Generalized Stiefel","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::GeneralizedStiefel)\n\nReturn the dimension of the GeneralizedStiefel manifold M=operatornameSt(nkB𝔽). The dimension is given by\n\nbeginaligned\ndim mathrmSt(n k B ℝ) = nk - frac12k(k+1) \ndim mathrmSt(n k B ℂ) = 2nk - k^2\ndim mathrmSt(n k B ℍ) = 4nk - k(2k-1)\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.project-Tuple{GeneralizedStiefel, Any, Any}","page":"Generalized Stiefel","title":"ManifoldsBase.project","text":"project(M:GeneralizedStiefel, p, X)\n\nProject X onto the tangent space of p to the GeneralizedStiefel manifold M. The formula reads\n\noperatornameproj_operatornameSt(nk)(pX) = X - poperatornameSym(p^mathrmHBX)\n\nwhere operatornameSym(y) is the symmetrization of y, e.g. by operatornameSym(y) = fracy^mathrmH+y2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.project-Tuple{GeneralizedStiefel, Any}","page":"Generalized Stiefel","title":"ManifoldsBase.project","text":"project(M::GeneralizedStiefel,p)\n\nProject p from the embedding onto the GeneralizedStiefel M, i.e. compute q as the polar decomposition of p such that q^mathrmHBq is the identity, where cdot^mathrmH denotes the hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.retract-Tuple{GeneralizedStiefel, Vararg{Any}}","page":"Generalized Stiefel","title":"ManifoldsBase.retract","text":"retract(M::GeneralizedStiefel, p, X)\nretract(M::GeneralizedStiefel, p, X, ::PolarRetraction)\nretract(M::GeneralizedStiefel, p, X, ::ProjectionRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the GeneralizedStiefel manifold M, which in this case is the same as the projection based retraction employing the exponential map in the embedding and projecting the result back to the manifold.\n\nThe default retraction for this manifold is the ProjectionRetraction.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Symplectic-Stiefel","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"","category":"section"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"The SymplecticStiefel manifold, denoted operatornameSpSt(2n 2k), represents canonical symplectic bases of 2k dimensonal symplectic subspaces of mathbbR^2n times 2n. This means that the columns of each element p in operatornameSpSt(2n 2k) subset mathbbR^2n times 2k constitute a canonical symplectic basis of operatornamespan(p). The canonical symplectic form is a non-degenerate, bilinear, and skew symmetric map omega_2kcolon mathbbF^2k times mathbbF^2k rightarrow mathbbF, given by omega_2k(x y) = x^T Q_2k y for elements x y in mathbbF^2k, with","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":" Q_2k = \n beginbmatrix\n 0_k I_k \n -I_k 0_k\n endbmatrix","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"Specifically given an element p in operatornameSpSt(2n 2k) we require that","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":" omega_2n (p x p y) = x^T(p^TQ_2np)y = x^TQ_2ky = omega_2k(x y) forall x y in mathbbF^2k","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"leading to the requirement on p that p^TQ_2np = Q_2k. In the case that k = n, this manifold reduces to the Symplectic manifold, which is also known as the symplectic group.","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymplecticStiefel.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symplecticstiefel.html#Manifolds.SymplecticStiefel","page":"Symplectic Stiefel","title":"Manifolds.SymplecticStiefel","text":"SymplecticStiefel{n, k, 𝔽} <: AbstractEmbeddedManifold{𝔽, DefaultIsometricEmbeddingType}\n\nThe symplectic Stiefel manifold consists of all 2n 2k n geq k matrices satisfying the requirement\n\noperatornameSpSt(2n 2k ℝ)\n = bigl p ℝ^2n 2n big p^mathrmTQ_2np = Q_2k bigr\n\nwhere\n\nQ_2n =\nbeginbmatrix\n 0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe symplectic Stiefel tangent space at p can be parametrized as [BendokatZimmermann2021]\n\n beginalign*\n T_poperatornameSpSt(2n 2k)\n = X in mathbbR^2n times 2k p^TQ_2nX + X^TQ_2np = 0 \n = X = pΩ + p^sB \n Ω ℝ^2k 2k Ω^+ = -Ω \n p^s operatornameSpSt(2n 2(n- k)) B ℝ^2(n-k) 2k \n endalign*\n\nwhere Ω in mathfraksp(2nF) is Hamiltonian and p^s means the symplectic complement of p s.t. p^+p^s = 0.\n\nConstructor\n\nSymplecticStiefel(2n::Int, 2k::Int, field::AbstractNumbers=ℝ)\n -> SymplecticStiefel{div(2n, 2), div(2k, 2), field}()\n\nGenerate the (real-valued) symplectic Stiefel manifold of 2n times 2k matrices which span a 2k dimensional symplectic subspace of ℝ^2n times 2n. The constructor for the SymplecticStiefel manifold accepts the even column dimension 2n and an even number of columns 2k for the real symplectic Stiefel manifold with elements p in ℝ^2n 2k.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplecticstiefel.html#Base.exp-Tuple{SymplecticStiefel, Any, Any}","page":"Symplectic Stiefel","title":"Base.exp","text":"exp(::SymplecticStiefel, p, X)\nexp!(M::SymplecticStiefel, q, p, X)\n\nCompute the exponential mapping\n\n operatornameexpcolon ToperatornameSpSt(2n 2k)\n rightarrow operatornameSpSt(2n 2k)\n\nat a point p in operatornameSpSt(2n 2k) in the direction of X in T_poperatornameSpSt(2n 2k).\n\nThe tangent vector X can be written in the form X = barOmegap [BendokatZimmermann2021], with\n\n barOmega = X (p^mathrmTp)^-1p^mathrmT\n + Q_2np(p^mathrmTp)^-1X^mathrmT(I_2n - Q_2n^mathrmTp(p^mathrmTp)^-1p^mathrmTQ_2n)Q_2n\n in ℝ^2n times 2n\n\nwhere Q_2n is the SymplecticMatrix. Using this expression for X, the exponential mapping can be computed as\n\n operatornameexp_p(X) = operatornameExp(barOmega - barOmega^mathrmT)\n operatornameExp(barOmega^mathrmT)p\n\nwhere operatornameExp(cdot) denotes the matrix exponential.\n\nComputing the above mapping directly however, requires taking matrix exponentials of two 2n times 2n matrices, which is computationally expensive when n increases. Therefore we instead follow [BendokatZimmermann2021] who express the above exponential mapping in a way which only requires taking matrix exponentials of an 8k times 8k matrix and a 4k times 4k matrix.\n\nTo this end, first define\n\nbarA = Q_2kp^mathrmTX(p^mathrmTp)^-1Q_2k +\n (p^mathrmTp)^-1X^mathrmT(p - Q_2n^mathrmTp(p^mathrmTp)^-1Q_2k) in ℝ^2k times 2k\n\nand\n\nbarH = (I_2n - pp^+)Q_2nX(p^mathrmTp)^-1Q_2k in ℝ^2n times 2k\n\nWe then let barDelta = pbarA + barH, and define the matrices\n\n γ = leftleft(I_2n - frac12pp^+right)barDelta quad\n -p right in ℝ^2n times 4k\n\nand\n\n λ = leftQ_2n^mathrmTpQ_2k quad\n left(barDelta^+left(I_2n\n - frac12pp^+right)right)^mathrmTright in ℝ^2n times 4k\n\nWith the above defined matrices it holds that barOmega = λγ^mathrmT. As a last preliminary step, concatenate γ and λ to define the matrices Γ = λ quad -γ in ℝ^2n times 8k and Λ = γ quad λ in ℝ^2n times 8k.\n\nWith these matrix constructions done, we can compute the exponential mapping as\n\n operatornameexp_p(X) =\n Γ operatornameExp(ΛΓ^mathrmT)\n beginbmatrix\n 0_4k \n I_4k\n endbmatrix\n operatornameExp(λγ^mathrmT)\n beginbmatrix\n 0_2k \n I_2k\n endbmatrix\n\nwhich only requires computing the matrix exponentials of ΛΓ^mathrmT in ℝ^8k times 8k and λγ^mathrmT in ℝ^4k times 4k.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Base.inv-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any}} where {n, k}","page":"Symplectic Stiefel","title":"Base.inv","text":"inv(::SymplecticStiefel{n, k}, A)\ninv!(::SymplecticStiefel{n, k}, q, p)\n\nCompute the symplectic inverse A^+ of matrix A ℝ^2n 2k. Given a matrix\n\nA ℝ^2n 2kquad\nA =\nbeginbmatrix\nA_1 1 A_1 2 \nA_2 1 A_2 2\nendbmatrix A_i j in ℝ^2n 2k\n\nthe symplectic inverse is defined as:\n\nA^+ = Q_2k^mathrmT A^mathrmT Q_2n\n\nwhere\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nFor any p in operatornameSpSt(2n 2k) we have that p^+p = I_2k.\n\nThe symplectic inverse of a matrix A can be expressed explicitly as:\n\nA^+ =\nbeginbmatrix\n A_2 2^mathrmT -A_1 2^mathrmT 12mm\n -A_2 1^mathrmT A_1 1^mathrmT\nendbmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Base.rand-Union{Tuple{SymplecticStiefel{n}}, Tuple{n}} where n","page":"Symplectic Stiefel","title":"Base.rand","text":"rand(M::SymplecticStiefel; vector_at=nothing,\n hamiltonian_norm=(vector_at === nothing ? 1/2 : 1.0))\n\nGenerate a random point p in operatornameSpSt(2n 2k) or a random tangent vector X in T_poperatornameSpSt(2n 2k) if vector_at is set to a point p in operatornameSp(2n).\n\nA random point on operatornameSpSt(2n 2k) is found by first generating a random point on the symplectic manifold operatornameSp(2n), and then projecting onto the Symplectic Stiefel manifold using the canonical_project π_operatornameSpSt(2n 2k). That is, p = π_operatornameSpSt(2n 2k)(p_operatornameSp).\n\nTo generate a random tangent vector in T_poperatornameSpSt(2n 2k) this code exploits the second tangent vector space parametrization of SymplecticStiefel, showing that any X in T_poperatornameSpSt(2n 2k) can be written as X = pΩ_X + p^sB_X. To generate random tangent vectors at p then, this function sets B_X = 0 and generates a random Hamiltonian matrix Ω_X in mathfraksp(2nF) with Frobenius norm of hamiltonian_norm before returning X = pΩ_X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldDiff.riemannian_gradient-Tuple{SymplecticStiefel, Any, Any}","page":"Symplectic Stiefel","title":"ManifoldDiff.riemannian_gradient","text":"X = riemannian_gradient(::SymplecticStiefel, f, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())\nriemannian_gradient!(::SymplecticStiefel, f, X, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())\n\nCompute the riemannian gradient X of f on SymplecticStiefel at a point p, provided that the gradient of the function tilde f, which is f continued into the embedding is given by Y. The metric in the embedding is the Euclidean metric.\n\nThe manifold gradient X is computed from Y as\n\n X = Yp^mathrmTp + Q_2npY^mathrmTQ_2np\n\nwhere Q_2n is the SymplecticMatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Manifolds.canonical_project-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any}} where {n, k}","page":"Symplectic Stiefel","title":"Manifolds.canonical_project","text":"canonical_project(::SymplecticStiefel, p_Sp)\ncanonical_project!(::SymplecticStiefel{n,k}, p, p_Sp)\n\nDefine the canonical projection from operatornameSp(2n 2n) onto operatornameSpSt(2n 2k), by projecting onto the first k columns and the n + 1'th onto the n + k'th columns [BendokatZimmermann2021].\n\nIt is assumed that the point p is on operatornameSp(2n 2n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Manifolds.get_total_space-Union{Tuple{SymplecticStiefel{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Symplectic Stiefel","title":"Manifolds.get_total_space","text":"get_total_space(::SymplecticStiefel)\n\nReturn the total space of the SymplecticStiefel manifold, which is the corresponding Symplectic manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Manifolds.symplectic_inverse_times-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any, Any}} where {n, k}","page":"Symplectic Stiefel","title":"Manifolds.symplectic_inverse_times","text":"symplectic_inverse_times(::SymplecticStiefel, p, q)\nsymplectic_inverse_times!(::SymplecticStiefel, A, p, q)\n\nDirectly compute the symplectic inverse of p in operatornameSpSt(2n 2k), multiplied with q in operatornameSpSt(2n 2k). That is, this function efficiently computes p^+q = (Q_2kp^mathrmTQ_2n)q in ℝ^2k times 2k, where Q_2n Q_2k are the SymplecticMatrix of sizes 2n times 2n and 2k times 2k respectively.\n\nThis function performs this common operation without allocating more than a 2k times 2k matrix to store the result in, or in the case of the in-place function, without allocating memory at all.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.check_point-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any}} where {n, k}","page":"Symplectic Stiefel","title":"ManifoldsBase.check_point","text":"check_point(M::SymplecticStiefel, p; kwargs...)\n\nCheck whether p is a valid point on the SymplecticStiefel, operatornameSpSt(2n 2k) manifold. That is, the point has the right AbstractNumbers type and p^+p is (approximately) the identity, where for A in mathbbR^2n times 2k, A^+ = Q_2k^mathrmTA^mathrmTQ_2n is the symplectic inverse, with\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.check_vector-Tuple{SymplecticStiefel, Vararg{Any}}","page":"Symplectic Stiefel","title":"ManifoldsBase.check_vector","text":"check_vector(M::Symplectic, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector at p on the SymplecticStiefel, operatornameSpSt(2n 2k) manifold. First recall the definition of the symplectic inverse for A in mathbbR^2n times 2k, A^+ = Q_2k^mathrmTA^mathrmTQ_2n is the symplectic inverse, with\n\n Q_2n =\n beginbmatrix\n 0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe we check that H = p^+X in 𝔤_2k, where 𝔤 is the Lie Algebra of the symplectic group operatornameSp(2k), characterized as [BendokatZimmermann2021],\n\n 𝔤_2k = H in ℝ^2k times 2k H^+ = -H \n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any, Any, Any}} where {n, k}","page":"Symplectic Stiefel","title":"ManifoldsBase.inner","text":"inner(M::SymplecticStiefel{n, k}, p, X. Y)\n\nCompute the Riemannian inner product g^operatornameSpSt at p in operatornameSpSt between tangent vectors X X in T_poperatornameSpSt. Given by Proposition 3.10 in [BendokatZimmermann2021].\n\ng^operatornameSpSt_p(X Y)\n = operatornametrleft(X^mathrmTleft(I_2n -\n frac12Q_2n^mathrmTp(p^mathrmTp)^-1p^mathrmTQ_2nright)Y(p^mathrmTp)^-1right)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.inverse_retract-Tuple{SymplecticStiefel, Any, Any, CayleyInverseRetraction}","page":"Symplectic Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(::SymplecticStiefel, p, q, ::CayleyInverseRetraction)\ninverse_retract!(::SymplecticStiefel, q, p, X, ::CayleyInverseRetraction)\n\nCompute the Cayley Inverse Retraction X = mathcalL_p^operatornameSpSt(q) such that the Cayley Retraction from p along X lands at q, i.e. mathcalR_p(X) = q [BendokatZimmermann2021].\n\nFirst, recall the definition the standard symplectic matrix\n\nQ =\nbeginbmatrix\n 0 I \n-I 0\nendbmatrix\n\nas well as the symplectic inverse of a matrix A, A^+ = Q^mathrmT A^mathrmT Q.\n\nFor p q operatornameSpSt(2n 2k ℝ) then, we can define the inverse cayley retraction as long as the following matrices exist.\n\n U = (I + p^+ q)^-1 in ℝ^2k times 2k\n quad\n V = (I + q^+ p)^-1 in ℝ^2k times 2k\n\nIf that is the case, the inverse cayley retration at p applied to q is\n\nmathcalL_p^operatornameSp(q) = 2pbigl(V - Ubigr) + 2bigl((p + q)U - pbigr)\n T_poperatornameSp(2n)\n\n[BendokatZimmermann2021]: Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.is_flat-Tuple{SymplecticStiefel}","page":"Symplectic Stiefel","title":"ManifoldsBase.is_flat","text":"is_flat(::SymplecticStiefel)\n\nReturn false. SymplecticStiefel is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.manifold_dimension-Union{Tuple{SymplecticStiefel{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Symplectic Stiefel","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(::SymplecticStiefel{n, k})\n\nReturns the dimension of the symplectic Stiefel manifold embedded in ℝ^2n times 2k, i.e. [BendokatZimmermann2021]\n\n operatornamedim(operatornameSpSt(2n 2k)) = (4n - 2k + 1)k\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.project-Tuple{SymplecticStiefel, Any, Any}","page":"Symplectic Stiefel","title":"ManifoldsBase.project","text":"project(::SymplecticStiefel, p, A)\nproject!(::SymplecticStiefel, Y, p, A)\n\nGiven a point p in operatornameSpSt(2n 2k), project an element A in mathbbR^2n times 2k onto the tangent space T_poperatornameSpSt(2n 2k) relative to the euclidean metric of the embedding mathbbR^2n times 2k.\n\nThat is, we find the element X in T_poperatornameSpSt(2n 2k) which solves the constrained optimization problem\n\n operatornamemin_X in mathbbR^2n times 2k frac12X - A^2 quad\n textst\n h(X)colon= X^mathrmT Q p + p^mathrmT Q X = 0\n\nwhere h mathbbR^2n times 2k rightarrow operatornameskew(2k) defines the restriction of X onto the tangent space T_poperatornameSpSt(2n 2k).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.retract-Tuple{SymplecticStiefel, Any, Any, CayleyRetraction}","page":"Symplectic Stiefel","title":"ManifoldsBase.retract","text":"retract(::SymplecticStiefel, p, X, ::CayleyRetraction)\nretract!(::SymplecticStiefel, q, p, X, ::CayleyRetraction)\n\nCompute the Cayley retraction on the Symplectic Stiefel manifold, computed inplace of q from p along X.\n\nGiven a point p in operatornameSpSt(2n 2k), every tangent vector X in T_poperatornameSpSt(2n 2k) is of the form X = tildeOmegap, with\n\n tildeOmega = left(I_2n - frac12pp^+right)Xp^+ -\n pX^+left(I_2n - frac12pp^+right) in ℝ^2n times 2n\n\nas shown in Proposition 3.5 of [BendokatZimmermann2021]. Using this representation of X, the Cayley retraction on operatornameSpSt(2n 2k) is defined pointwise as\n\n mathcalR_p(X) = operatornamecayleft(frac12tildeOmegaright)p\n\nThe operator operatornamecay(A) = (I - A)^-1(I + A) is the Cayley transform.\n\nHowever, the computation of an 2n times 2n matrix inverse in the expression above can be reduced down to inverting a 2k times 2k matrix due to Proposition 5.2 of [BendokatZimmermann2021].\n\nLet A = p^+X and H = X - pA. Then an equivalent expression for the Cayley retraction defined pointwise above is\n\n mathcalR_p(X) = -p + (H + 2p)(H^+H4 - A2 + I_2k)^-1\n\nIt is this expression we compute inplace of q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Literature","page":"Symplectic Stiefel","title":"Literature","text":"","category":"section"},{"location":"manifolds/connection.html#ConnectionSection","page":"Connection manifold","title":"Connection manifold","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"A connection manifold always consists of a topological manifold together with a connection Gamma.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"However, often there is an implicitly assumed (default) connection, like the LeviCivitaConnection connection on a Riemannian manifold. It is not necessary to use this decorator if you implement just one (or the first) connection. If you later introduce a second, the old (first) connection can be used without an explicitly stated connection.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"This manifold decorator serves two purposes:","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"to implement different connections (e.g. in closed form) for one AbstractManifold\nto provide a way to compute geodesics on manifolds, where this AbstractAffineConnection does not yield a closed formula.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"An example of usage can be found in Cartan-Schouten connections, see AbstractCartanSchoutenConnection.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"Pages = [\"connection.md\"]\nDepth = 2","category":"page"},{"location":"manifolds/connection.html#Types","page":"Connection manifold","title":"Types","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/ConnectionManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/connection.html#Manifolds.AbstractAffineConnection","page":"Connection manifold","title":"Manifolds.AbstractAffineConnection","text":"AbstractAffineConnection\n\nAbstract type for affine connections on a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.ConnectionManifold","page":"Connection manifold","title":"Manifolds.ConnectionManifold","text":"ConnectionManifold{𝔽,,M<:AbstractManifold{𝔽},G<:AbstractAffineConnection} <: AbstractDecoratorManifold{𝔽}\n\nConstructor\n\nConnectionManifold(M, C)\n\nDecorate the AbstractManifold M with AbstractAffineConnection C.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.IsConnectionManifold","page":"Connection manifold","title":"Manifolds.IsConnectionManifold","text":"IsConnectionManifold <: AbstractTrait\n\nSpecify that a certain decorated Manifold is a connection manifold in the sence that it provides explicit connection properties, extending/changing the default connection properties of a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.IsDefaultConnection","page":"Connection manifold","title":"Manifolds.IsDefaultConnection","text":"IsDefaultConnection{G<:AbstractAffineConnection}\n\nSpecify that a certain AbstractAffineConnection is the default connection for a manifold. This way the corresponding ConnectionManifold falls back to the default methods of the manifold it decorates.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.LeviCivitaConnection","page":"Connection manifold","title":"Manifolds.LeviCivitaConnection","text":"LeviCivitaConnection\n\nThe Levi-Civita connection of a Riemannian manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Functions","page":"Connection manifold","title":"Functions","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/ConnectionManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/connection.html#Base.exp-Tuple{ManifoldsBase.TraitList{IsConnectionManifold}, AbstractDecoratorManifold, Any, Any}","page":"Connection manifold","title":"Base.exp","text":"exp(::TraitList{IsConnectionManifold}, M::AbstractDecoratorManifold, p, X)\n\nCompute the exponential map on a manifold that IsConnectionManifold M equipped with corresponding affine connection.\n\nIf M is a MetricManifold with a IsDefaultMetric trait, this method falls back to exp(M, p, X).\n\nOtherwise it numerically integrates the underlying ODE, see solve_exp_ode. Currently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.christoffel_symbols_first-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.christoffel_symbols_first","text":"christoffel_symbols_first(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n)\n\nCompute the Christoffel symbols of the first kind in local coordinates of basis B. The Christoffel symbols are (in Einstein summation convention)\n\nΓ_ijk = frac12 Biglg_kji + g_ikj - g_ijkBigr\n\nwhere g_ijk=frac p^k g_ij is the coordinate derivative of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered (ijk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.christoffel_symbols_second-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.christoffel_symbols_second","text":"christoffel_symbols_second(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n)\n\nCompute the Christoffel symbols of the second kind in local coordinates of basis B. For affine connection manifold the Christoffel symbols need to be explicitly implemented while, for a MetricManifold they are computed as (in Einstein summation convention)\n\nΓ^l_ij = g^kl Γ_ijk\n\nwhere Γ_ijk are the Christoffel symbols of the first kind (see christoffel_symbols_first), and g^kl is the inverse of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered (lij).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.christoffel_symbols_second_jacobian-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.christoffel_symbols_second_jacobian","text":"christoffel_symbols_second_jacobian(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n)\n\nGet partial derivatives of the Christoffel symbols of the second kind for manifold M at p with respect to the coordinates of B, i.e.\n\nfrac p^l Γ^k_ij = Γ^k_ijl\n\nThe dimensions of the resulting multi-dimensional array are ordered (ijkl).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.connection-Tuple{AbstractManifold}","page":"Connection manifold","title":"Manifolds.connection","text":"connection(M::AbstractManifold)\n\nGet the connection (an object of a subtype of AbstractAffineConnection) of AbstractManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.connection-Tuple{ConnectionManifold}","page":"Connection manifold","title":"Manifolds.connection","text":"connection(M::ConnectionManifold)\n\nReturn the connection associated with ConnectionManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.gaussian_curvature-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.gaussian_curvature","text":"gaussian_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())\n\nCompute the Gaussian curvature of the manifold M at the point p using basis B. This is equal to half of the scalar Ricci curvature, see ricci_curvature.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.is_default_connection-Tuple{AbstractManifold, AbstractAffineConnection}","page":"Connection manifold","title":"Manifolds.is_default_connection","text":"is_default_connection(M::AbstractManifold, G::AbstractAffineConnection)\n\nreturns whether an AbstractAffineConnection is the default metric on the manifold M or not. This can be set by defining this function, or setting the IsDefaultConnection trait for an AbstractDecoratorManifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.ricci_tensor-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.ricci_tensor","text":"ricci_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())\n\nCompute the Ricci tensor, also known as the Ricci curvature tensor, of the manifold M at the point p using basis B, see https://en.wikipedia.org/wiki/Ricci_curvature#Introduction_and_local_definition.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.solve_exp_ode-Tuple{AbstractManifold, Any, Any, Number}","page":"Connection manifold","title":"Manifolds.solve_exp_ode","text":"solve_exp_ode(\n M::AbstractConnectionManifold,\n p,\n X,\n t::Number,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n solver = AutoVern9(Rodas5()),\n kwargs...,\n)\n\nApproximate the exponential map on the manifold by evaluating the ODE descripting the geodesic at 1, assuming the default connection of the given manifold by solving the ordinary differential equation\n\nfracd^2dt^2 p^k + Γ^k_ij fracddt p_i fracddt p_j = 0\n\nwhere Γ^k_ij are the Christoffel symbols of the second kind, and the Einstein summation convention is assumed. The argument solver follows the OrdinaryDiffEq conventions. kwargs... specify keyword arguments that will be passed to OrdinaryDiffEq.solve.\n\nCurrently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.\n\nnote: Note\nThis function only works when OrdinaryDiffEq.jl is loaded withusing OrdinaryDiffEq\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#ManifoldsBase.riemann_tensor-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend=default_differential_backend())\n\nCompute the Riemann tensor R^l_ijk, also known as the Riemann curvature tensor, at the point p in local coordinates defined by B. The dimensions of the resulting multi-dimensional array are ordered (lijk).\n\nThe function uses the coordinate expression involving the second Christoffel symbol, see https://en.wikipedia.org/wiki/Riemann_curvature_tensor#Coordinate_expression for details.\n\nSee also\n\nchristoffel_symbols_second, christoffel_symbols_second_jacobian\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#connections_charts","page":"Connection manifold","title":"Charts and bases of vector spaces","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"All connection-related functions take a basis of a vector space as one of the arguments. This is needed because generally there is no way to define these functions without referencing a basis. In some cases there is no need to be explicit about this basis, and then for example a DefaultOrthonormalBasis object can be used. In cases where being explicit about these bases is needed, for example when using multiple charts, a basis can be specified, for example using induced_basis.","category":"page"},{"location":"index.html#Manifolds","page":"Home","title":"Manifolds","text":"","category":"section"},{"location":"index.html","page":"Home","title":"Home","text":"Manifolds.Manifolds","category":"page"},{"location":"index.html#Manifolds.Manifolds","page":"Home","title":"Manifolds.Manifolds","text":"Manifolds.jl provides a library of manifolds aiming for an easy-to-use and fast implementation.\n\n\n\n\n\n","category":"module"},{"location":"index.html","page":"Home","title":"Home","text":"The implemented manifolds are accompanied by their mathematical formulae.","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"The manifolds are implemented using the interface for manifolds given in ManifoldsBase.jl. You can use that interface to implement your own software on manifolds, such that all manifolds based on that interface can be used within your code.","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"For more information, see the About section.","category":"page"},{"location":"index.html#Getting-started","page":"Home","title":"Getting started","text":"","category":"section"},{"location":"index.html","page":"Home","title":"Home","text":"To install the package just type","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"using Pkg; Pkg.add(\"Manifolds\")","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"Then you can directly start, for example to stop half way from the north pole on the Sphere to a point on the the equator, you can generate the shortest_geodesic. It internally employs log and exp.","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"using Manifolds\nM = Sphere(2)\nγ = shortest_geodesic(M, [0., 0., 1.], [0., 1., 0.])\nγ(0.5)","category":"page"},{"location":"index.html#Citation","page":"Home","title":"Citation","text":"","category":"section"},{"location":"index.html","page":"Home","title":"Home","text":"If you use Manifolds.jl in your work, please cite the following","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"@online{2106.08777,\n Author = {Seth D. Axen and Mateusz Baran and Ronny Bergmann and Krzysztof Rzecki},\n Title = {Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds},\n Year = {2021},\n Eprint = {2106.08777},\n Eprinttype = {arXiv},\n}","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"To refer to a certain version we recommend to also cite for example","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"@software{manifoldsjl-zenodo-mostrecent,\n Author = {Seth D. Axen and Mateusz Baran and Ronny Bergmann},\n Title = {Manifolds.jl},\n Doi = {10.5281/ZENODO.4292129},\n Url = {https://zenodo.org/record/4292129},\n Publisher = {Zenodo},\n Year = {2021},\n Copyright = {MIT License}\n}","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"for the most recent version or a corresponding version specific DOI, see the list of all versions. Note that both citations are in BibLaTeX format.","category":"page"},{"location":"manifolds/lorentz.html#Lorentzian-Manifold","page":"Lorentzian manifold","title":"Lorentzian Manifold","text":"","category":"section"},{"location":"manifolds/lorentz.html","page":"Lorentzian manifold","title":"Lorentzian manifold","text":"The Lorentz manifold is a pseudo-Riemannian manifold. It is named after the Dutch physicist Hendrik Lorentz (1853–1928). The default LorentzMetric is the MinkowskiMetric named after the German mathematician Hermann Minkowski (1864–1909).","category":"page"},{"location":"manifolds/lorentz.html","page":"Lorentzian manifold","title":"Lorentzian manifold","text":"Within Manifolds.jl it is used as the embedding of the Hyperbolic space.","category":"page"},{"location":"manifolds/lorentz.html","page":"Lorentzian manifold","title":"Lorentzian manifold","text":"Modules = [Manifolds]\nPages = [\"Lorentz.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/lorentz.html#Manifolds.Lorentz","page":"Lorentzian manifold","title":"Manifolds.Lorentz","text":"Lorentz{N} = MetricManifold{Euclidean{N,ℝ},LorentzMetric}\n\nThe Lorentz manifold (or Lorentzian) is a pseudo-Riemannian manifold.\n\nConstructor\n\nLorentz(n[, metric=MinkowskiMetric()])\n\nGenerate the Lorentz manifold of dimension n with the LorentzMetric m, which is by default set to the MinkowskiMetric.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/lorentz.html#Manifolds.LorentzMetric","page":"Lorentzian manifold","title":"Manifolds.LorentzMetric","text":"LorentzMetric <: AbstractMetric\n\nAbstract type for Lorentz metrics, which have a single time dimension. These metrics assume the spacelike convention with the time dimension being last, giving the signature (+++-).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/lorentz.html#Manifolds.MinkowskiMetric","page":"Lorentzian manifold","title":"Manifolds.MinkowskiMetric","text":"MinkowskiMetric <: LorentzMetric\n\nAs a special metric of signature (+++-), i.e. a LorentzMetric, see minkowski_metric for the formula.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/lorentz.html#Manifolds.minkowski_metric-Tuple{Any, Any}","page":"Lorentzian manifold","title":"Manifolds.minkowski_metric","text":"minkowski_metric(a,b)\n\nCompute the minkowski metric on mathbb R^n is given by\n\nab_mathrmM = -a_nb_n +\ndisplaystylesum_k=1^n-1 a_kb_k\n\n\n\n\n\n","category":"method"},{"location":"misc/internals.html#Internal-documentation","page":"Internals","title":"Internal documentation","text":"","category":"section"},{"location":"misc/internals.html","page":"Internals","title":"Internals","text":"This page documents the internal types and methods of Manifolds.jl's that might be of use for writing your own manifold.","category":"page"},{"location":"misc/internals.html#Functions","page":"Internals","title":"Functions","text":"","category":"section"},{"location":"misc/internals.html","page":"Internals","title":"Internals","text":"Manifolds.eigen_safe\nManifolds.isnormal\nManifolds.log_safe\nManifolds.log_safe!\nManifolds.mul!_safe\nManifolds.nzsign\nManifolds.realify\nManifolds.realify!\nManifolds.select_from_tuple\nManifolds.unrealify!\nManifolds.usinc\nManifolds.usinc_from_cos\nManifolds.vec2skew!\nManifolds.ziptuples","category":"page"},{"location":"misc/internals.html#Manifolds.eigen_safe","page":"Internals","title":"Manifolds.eigen_safe","text":"eigen_safe(x)\n\nCompute the eigendecomposition of x. If x is a StaticMatrix, it is converted to a Matrix before the decomposition.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.isnormal","page":"Internals","title":"Manifolds.isnormal","text":"isnormal(x; kwargs...) -> Bool\n\nCheck if the matrix or number x is normal, that is, if it commutes with its adjoint:\n\nx x^mathrmH = x^mathrmH x\n\nBy default, this is an equality check. Provide kwargs for isapprox to perform an approximate check.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.log_safe","page":"Internals","title":"Manifolds.log_safe","text":"log_safe(x)\n\nCompute the matrix logarithm of x. If x is a StaticMatrix, it is converted to a Matrix before computing the log.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.log_safe!","page":"Internals","title":"Manifolds.log_safe!","text":"log_safe!(y, x)\n\nCompute the matrix logarithm of x. If the eltype of y is real, then the imaginary part of x is ignored, and a DomainError is raised if real(x) has no real logarithm.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.mul!_safe","page":"Internals","title":"Manifolds.mul!_safe","text":"mul!_safe(Y, A, B) -> Y\n\nCall mul! safely, that is, A and/or B are permitted to alias with Y.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.nzsign","page":"Internals","title":"Manifolds.nzsign","text":"nzsign(z[, absz])\n\nCompute a modified sign(z) that is always nonzero, i.e. where\n\noperatorname(nzsign)(z) = begincases\n 1 textif z = 0\n fraczz textotherwise\nendcases\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.realify","page":"Internals","title":"Manifolds.realify","text":"realify(X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers) -> Y::AbstractMatrix{<:Real}\n\nGiven a matrix X 𝔽^n n, compute Y ℝ^m m, where m = n operatornamedim_𝔽, and operatornamedim_𝔽 is the real_dimension of the number field 𝔽, using the map ϕ colon X Y, that preserves the matrix product, so that for all CD 𝔽^n n,\n\nϕ(C) ϕ(D) = ϕ(CD)\n\nSee realify! for an in-place version, and unrealify! to compute the inverse of ϕ.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.realify!","page":"Internals","title":"Manifolds.realify!","text":"realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers)\n\nIn-place version of realify.\n\n\n\n\n\nrealify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{<:Complex}, ::typeof(ℂ))\n\nGiven a complex matrix X = A + iB ℂ^n n, compute its realified matrix Y ℝ^2n 2n, written where\n\nY = beginpmatrixA -B B A endpmatrix\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.select_from_tuple","page":"Internals","title":"Manifolds.select_from_tuple","text":"select_from_tuple(t::NTuple{N, Any}, positions::Val{P})\n\nSelects elements of tuple t at positions specified by the second argument. For example select_from_tuple((\"a\", \"b\", \"c\"), Val((3, 1, 1))) returns (\"c\", \"a\", \"a\").\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.unrealify!","page":"Internals","title":"Manifolds.unrealify!","text":"unrealify!(X::AbstractMatrix{T𝔽}, Y::AbstractMatrix{<:Real}, 𝔽::AbstractNumbers[, n])\n\nGiven a real matrix Y ℝ^m m, where m = n operatornamedim_𝔽, and operatornamedim_𝔽 is the real_dimension of the number field 𝔽, compute in-place its equivalent matrix X 𝔽^n n. Note that this function does not check that Y has a valid structure to be un-realified.\n\nSee realify! for the inverse of this function.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.usinc","page":"Internals","title":"Manifolds.usinc","text":"usinc(θ::Real)\n\nUnnormalized version of sinc function, i.e. operatornameusinc(θ) = fracsin(θ)θ. This is equivalent to sinc(θ/π).\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.usinc_from_cos","page":"Internals","title":"Manifolds.usinc_from_cos","text":"usinc_from_cos(x::Real)\n\nUnnormalized version of sinc function, i.e. operatornameusinc(θ) = fracsin(θ)θ, computed from x = cos(θ).\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.vec2skew!","page":"Internals","title":"Manifolds.vec2skew!","text":"vec2skew!(X, v, k)\n\ncreate a skew symmetric matrix inplace in X of size ktimes k from a vector v, for example for v=[1,2,3] and k=3 this yields\n\n[ 0 1 2;\n -1 0 3;\n -2 -3 0\n]\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.ziptuples","page":"Internals","title":"Manifolds.ziptuples","text":"ziptuples(a, b[, c[, d[, e]]])\n\nZips tuples a, b, and remaining in a fast, type-stable way. If they have different lengths, the result is trimmed to the length of the shorter tuple.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/sphere.html#SphereSection","page":"Sphere","title":"Sphere and unit norm arrays","text":"","category":"section"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"AbstractSphere","category":"page"},{"location":"manifolds/sphere.html#Manifolds.AbstractSphere","page":"Sphere","title":"Manifolds.AbstractSphere","text":"AbstractSphere{𝔽} <: AbstractDecoratorManifold{𝔽}\n\nAn abstract type to represent a unit sphere that is represented isometrically in the embedding.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"The classical sphere, i.e. unit norm (real- or complex-valued) vectors can be generated as usual: to create the 2-dimensional sphere (in ℝ^3), use Sphere(2) and Sphere(2,ℂ), respectively.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"Sphere","category":"page"},{"location":"manifolds/sphere.html#Manifolds.Sphere","page":"Sphere","title":"Manifolds.Sphere","text":"Sphere{n,𝔽} <: AbstractSphere{𝔽}\n\nThe (unit) sphere manifold 𝕊^n is the set of all unit norm vectors in 𝔽^n+1. The sphere is represented in the embedding, i.e.\n\n𝕊^n = bigl p in 𝔽^n+1 big lVert p rVert = 1 bigr\n\nwhere 𝔽inℝℂℍ. Note that compared to the ArraySphere, here the argument n of the manifold is the dimension of the manifold, i.e. 𝕊^n 𝔽^n+1, nin ℕ.\n\nThe tangent space at point p is given by\n\nT_p𝕊^n = bigl X 𝔽^n+1 Re(pX) = 0 bigr \n\nwhere 𝔽inℝℂℍ and cdotcdot denotes the inner product in the embedding 𝔽^n+1.\n\nFor 𝔽=ℂ, the manifold is the complex sphere, written ℂ𝕊^n, embedded in ℂ^n+1. ℂ𝕊^n is the complexification of the real sphere 𝕊^2n+1. Likewise, the quaternionic sphere ℍ𝕊^n is the quaternionification of the real sphere 𝕊^4n+3. Consequently, ℂ𝕊^0 is equivalent to 𝕊^1 and Circle, while ℂ𝕊^1 and ℍ𝕊^0 are equivalent to 𝕊^3, though with different default representations.\n\nThis manifold is modeled as a special case of the more general case, i.e. as an embedded manifold to the Euclidean, and several functions like the inner product and the zero_vector are inherited from the embedding.\n\nConstructor\n\nSphere(n[, field=ℝ])\n\nGenerate the (real-valued) sphere 𝕊^n ℝ^n+1, where field can also be used to generate the complex- and quaternionic-valued sphere.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"For the higher-dimensional arrays, for example unit (Frobenius) norm matrices, the manifold is generated using the size of the matrix. To create the unit sphere of 32 real-valued matrices, write ArraySphere(3,2) and the complex case is done – as for the Euclidean case – with an keyword argument ArraySphere(3,2; field = ℂ). This case also covers the classical sphere as a special case, but you specify the size of the vectors/embedding instead: The 2-sphere can here be generated ArraySphere(3).","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"ArraySphere","category":"page"},{"location":"manifolds/sphere.html#Manifolds.ArraySphere","page":"Sphere","title":"Manifolds.ArraySphere","text":"ArraySphere{T<:Tuple,𝔽} <: AbstractSphere{𝔽}\n\nThe (unit) sphere manifold 𝕊^n₁n₂nᵢ is the set of all unit (Frobenius) norm elements of 𝔽^n₁n₂nᵢ, where 𝔽\\in{ℝ,ℂ,ℍ}. The generalized sphere is represented in the embedding, and supports arbitrary sized arrays or in other words arbitrary tensors of unit norm. The set formally reads\n\n𝕊^n_1 n_2 n_i = bigl p in 𝔽^n_1 n_2 n_i big lVert p rVert = 1 bigr\n\nwhere 𝔽inℝℂℍ. Setting i=1 and 𝔽=ℝ this simplifies to unit vectors in ℝ^n, see Sphere for this special case. Note that compared to this classical case, the argument for the generalized case here is given by the dimension of the embedding. This means that Sphere(2) and ArraySphere(3) are the same manifold.\n\nThe tangent space at point p is given by\n\nT_p 𝕊^n_1 n_2 n_i = bigl X 𝔽^n_1 n_2 n_i Re(pX) = 0 bigr \n\nwhere 𝔽inℝℂℍ and cdotcdot denotes the (Frobenius) inner product in the embedding 𝔽^n_1 n_2 n_i.\n\nThis manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.\n\nConstructor\n\nArraySphere(n₁,n₂,...,nᵢ; field=ℝ)\n\nGenerate sphere in 𝔽^n_1 n_2 n_i, where 𝔽 defaults to the real-valued case ℝ.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"There is also one atlas available on the sphere.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"Manifolds.StereographicAtlas","category":"page"},{"location":"manifolds/sphere.html#Manifolds.StereographicAtlas","page":"Sphere","title":"Manifolds.StereographicAtlas","text":"StereographicAtlas()\n\nThe stereographic atlas of S^n with two charts: one with the singular point (-1, 0, ..., 0) (called :north) and one with the singular point (1, 0, ..., 0) (called :south).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html#Functions-on-unit-spheres","page":"Sphere","title":"Functions on unit spheres","text":"","category":"section"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"Modules = [Manifolds]\nPages = [\"manifolds/Sphere.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/sphere.html#Base.exp-Tuple{AbstractSphere, Vararg{Any}}","page":"Sphere","title":"Base.exp","text":"exp(M::AbstractSphere, p, X)\n\nCompute the exponential map from p in the tangent direction X on the AbstractSphere M by following the great arc eminating from p in direction X.\n\nexp_p X = cos(lVert X rVert_p)p + sin(lVert X rVert_p)fracXlVert X rVert_p\n\nwhere lVert X rVert_p is the norm on the tangent space at p of the AbstractSphere M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Base.log-Tuple{AbstractSphere, Vararg{Any}}","page":"Sphere","title":"Base.log","text":"log(M::AbstractSphere, p, q)\n\nCompute the logarithmic map on the AbstractSphere M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. The formula reads for x -y\n\nlog_p q = d_𝕊(pq) fracq-Re(pq) plVert q-Re(pq) p rVert_2\n\nand a deterministic choice from the set of tangent vectors is returned if x=-y, i.e. for opposite points.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.local_metric-Union{Tuple{n}, Tuple{Sphere{n, ℝ}, Any, DefaultOrthonormalBasis}} where n","page":"Sphere","title":"Manifolds.local_metric","text":"local_metric(M::Sphere{n}, p, ::DefaultOrthonormalBasis)\n\nreturn the local representation of the metric in a DefaultOrthonormalBasis, namely the diagonal matrix of size nn with ones on the diagonal, since the metric is obtained from the embedding by restriction to the tangent space T_pmathcal M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.manifold_volume-Tuple{AbstractSphere{ℝ}}","page":"Sphere","title":"Manifolds.manifold_volume","text":"manifold_volume(M::AbstractSphere{ℝ})\n\nVolume of the n-dimensional Sphere M. The formula reads\n\noperatornameVol(𝕊^n) = frac2pi^(n+1)2Γ((n+1)2)\n\nwhere Γ denotes the Gamma function.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.uniform_distribution-Union{Tuple{n}, Tuple{Sphere{n, ℝ}, Any}} where n","page":"Sphere","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::Sphere{n,ℝ}, p) where {n}\n\nUniform distribution on given Sphere M. Generated points will be of similar type as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.volume_density-Tuple{AbstractSphere{ℝ}, Any, Any}","page":"Sphere","title":"Manifolds.volume_density","text":"volume_density(M::AbstractSphere{ℝ}, p, X)\n\nCompute volume density function of a sphere, i.e. determinant of the differential of exponential map exp(M, p, X). The formula reads (sin(lVert XrVert)lVert XrVert)^(n-1) where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.check_point-Tuple{AbstractSphere, Any}","page":"Sphere","title":"ManifoldsBase.check_point","text":"check_point(M::AbstractSphere, p; kwargs...)\n\nCheck whether p is a valid point on the AbstractSphere M, i.e. is a point in the embedding of unit length. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.check_vector-Tuple{AbstractSphere, Any, Any}","page":"Sphere","title":"ManifoldsBase.check_vector","text":"check_vector(M::AbstractSphere, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the AbstractSphere M, i.e. after check_point(M,p), X has to be of same dimension as p and orthogonal to p. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.distance-Tuple{AbstractSphere, Any, Any}","page":"Sphere","title":"ManifoldsBase.distance","text":"distance(M::AbstractSphere, p, q)\n\nCompute the geodesic distance betweeen p and q on the AbstractSphere M. The formula is given by the (shorter) great arc length on the (or a) great circle both p and q lie on.\n\nd_𝕊(pq) = arccos(Re(pq))\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.get_coordinates-Tuple{AbstractSphere{ℝ}, Any, Any, DefaultOrthonormalBasis}","page":"Sphere","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)\n\nRepresent the tangent vector X at point p from the AbstractSphere M in an orthonormal basis by rotating the hyperplane containing X to a hyperplane whose normal is the x-axis.\n\nGiven q = p λ + x, where λ = operatornamesgn(x p), and _mathrmF denotes the Frobenius inner product, the formula for Y is\n\nbeginpmatrix0 Yendpmatrix = X - qfrac2 q X_mathrmFq q_mathrmF\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.get_vector-Tuple{AbstractSphere{ℝ}, Any, Any, DefaultOrthonormalBasis}","page":"Sphere","title":"ManifoldsBase.get_vector","text":"get_vector(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)\n\nConvert a one-dimensional vector of coefficients X in the basis B of the tangent space at p on the AbstractSphere M to a tangent vector Y at p by rotating the hyperplane containing X, whose normal is the x-axis, to the hyperplane whose normal is p.\n\nGiven q = p λ + x, where λ = operatornamesgn(x p), and _mathrmF denotes the Frobenius inner product, the formula for Y is\n\nY = X - qfrac2 leftlangle q beginpmatrix0 Xendpmatrixrightrangle_mathrmFq q_mathrmF\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.injectivity_radius-Tuple{AbstractSphere}","page":"Sphere","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::AbstractSphere[, p])\n\nReturn the injectivity radius for the AbstractSphere M, which is globally π.\n\ninjectivity_radius(M::Sphere, x, ::ProjectionRetraction)\n\nReturn the injectivity radius for the ProjectionRetraction on the AbstractSphere, which is globally fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.inverse_retract-Tuple{AbstractSphere, Any, Any, ProjectionInverseRetraction}","page":"Sphere","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::AbstractSphere, p, q, ::ProjectionInverseRetraction)\n\nCompute the inverse of the projection based retraction on the AbstractSphere M, i.e. rearranging p+X = qlVert p+XrVert_2 yields since Re(pX) = 0 and when d_𝕊^2(pq) fracπ2 that\n\noperatornameretr_p^-1(q) = fracqRe(p q) - p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.is_flat-Tuple{AbstractSphere}","page":"Sphere","title":"ManifoldsBase.is_flat","text":"is_flat(M::AbstractSphere)\n\nReturn true if AbstractSphere is of dimension 1 and false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.manifold_dimension-Tuple{AbstractSphere}","page":"Sphere","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::AbstractSphere)\n\nReturn the dimension of the AbstractSphere M, respectively i.e. the dimension of the embedding -1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.parallel_transport_to-Tuple{AbstractSphere, Vararg{Any, 4}}","page":"Sphere","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::AbstractSphere, p, X, q)\n\nCompute the parallel transport on the Sphere of the tangent vector X at p to q, provided, the geodesic between p and q is unique. The formula reads\n\nP_pq(X) = X - fracRe(log_p qX_p)d^2_𝕊(pq)\nbigl(log_p q + log_q p bigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.project-Tuple{AbstractSphere, Any, Any}","page":"Sphere","title":"ManifoldsBase.project","text":"project(M::AbstractSphere, p, X)\n\nProject the point X onto the tangent space at p on the Sphere M.\n\noperatornameproj_p(X) = X - Re(p X)p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.project-Tuple{AbstractSphere, Any}","page":"Sphere","title":"ManifoldsBase.project","text":"project(M::AbstractSphere, p)\n\nProject the point p from the embedding onto the Sphere M.\n\noperatornameproj(p) = fracplVert p rVert\n\nwhere lVertcdotrVert denotes the usual 2-norm for vectors if m=1 and the Frobenius norm for the case m1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.representation_size-Union{Tuple{ArraySphere{N}}, Tuple{N}} where N","page":"Sphere","title":"ManifoldsBase.representation_size","text":"representation_size(M::AbstractSphere)\n\nReturn the size points on the AbstractSphere M are represented as, i.e., the representation size of the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.retract-Tuple{AbstractSphere, Any, Any, ProjectionRetraction}","page":"Sphere","title":"ManifoldsBase.retract","text":"retract(M::AbstractSphere, p, X, ::ProjectionRetraction)\n\nCompute the retraction that is based on projection, i.e.\n\noperatornameretr_p(X) = fracp+XlVert p+X rVert_2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.riemann_tensor-Tuple{AbstractSphere{ℝ}, Vararg{Any, 4}}","page":"Sphere","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::AbstractSphere{ℝ}, p, X, Y, Z)\n\nCompute the Riemann tensor R(XY)Z at point p on AbstractSphere M. The formula reads [MuralidharanFletcher2021] (though note that a different convention is used in that paper than in Manifolds.jl):\n\nR(XY)Z = langle Z Y rangle X - langle Z X rangle Y\n\n[MuralidharanFletcher2021]: P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012, pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Statistics.mean-Tuple{AbstractSphere, Vararg{Any}}","page":"Sphere","title":"Statistics.mean","text":"mean(\n S::AbstractSphere,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/2);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Visualization-on-Sphere{2,ℝ}","page":"Sphere","title":"Visualization on Sphere{2,ℝ}","text":"","category":"section"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"You can visualize both points and tangent vectors on the sphere.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"note: Note\nThere seems to be no unified way to draw spheres in the backends of Plots.jl. This recipe currently uses the seriestype wireframe and surface, which does not yet work with the default backend GR.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of the wires and a wireframe_color for their color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_lat or surface_resolution_lon) and a surface_color.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"using Manifolds, Plots\npythonplot()\nM = Sphere(2)\npts = [ [1.0, 0.0, 0.0], [0.0, -1.0, 0.0], [0.0, 0.0, 1.0], [1.0, 0.0, 0.0] ]\nscene = plot(M, pts; wireframe_color=colorant\"#CCCCCC\", markersize=10)","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"which scatters our points. We can also draw connecting geodesics, which here is a geodesic triangle. Here we discretize each geodesic with 100 points along the geodesic. The default value is geodesic_interpolation=-1 which switches to scatter plot of the data.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"plot!(scene, M, pts; wireframe=false, geodesic_interpolation=100, linewidth=2)","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"And we can also add tangent vectors, for example tangents pointing towards the geometric center of given points.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"pts2 = [ [1.0, 0.0, 0.0], [0.0, -1.0, 0.0], [0.0, 0.0, 1.0] ]\np3 = 1/sqrt(3) .* [1.0, -1.0, 1.0]\nvecs = log.(Ref(M), pts2, Ref(p3))\nplot!(scene, M, pts2, vecs; wireframe = false, linewidth=1.5)","category":"page"},{"location":"manifolds/shapespace.html#Shape-spaces","page":"Shape spaces","title":"Shape spaces","text":"","category":"section"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Shape spaces are spaces of k points in mathbbR^n up to simultaneous action of a group on all points. The most commonly encountered are Kendall's pre-shape and shape spaces. In the case of the Kendall's pre-shape spaces the action is translation and scaling. In the case of the Kendall's shape spaces the action is translation, scaling and rotation.","category":"page"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"using Manifolds, Plots\n\nM = KendallsShapeSpace(2, 3)\n# two random point on the shape space\np = [\n 0.4385117672460505 -0.6877826444042382 0.24927087715818771\n -0.3830259932279294 0.35347460720654283 0.029551386021386548\n]\nq = [\n -0.42693314765896473 -0.3268567431952937 0.7537898908542584\n 0.3054740561061169 -0.18962848284149897 -0.11584557326461796\n]\n# let's plot them as triples of points on a plane\nfig = scatter(p[1,:], p[2,:], label=\"p\", aspect_ratio=:equal)\nscatter!(fig, q[1,:], q[2,:], label=\"q\")\n\n# aligning q to p\nA = get_orbit_action(M)\na = optimal_alignment(A, p, q)\nrot_q = apply(A, a, q)\nscatter!(fig, rot_q[1,:], rot_q[2,:], label=\"q aligned to p\")","category":"page"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"A more extensive usage example is available in the hand_gestures.jl tutorial.","category":"page"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsPreShapeSpace.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/shapespace.html#Manifolds.KendallsPreShapeSpace","page":"Shape spaces","title":"Manifolds.KendallsPreShapeSpace","text":"KendallsPreShapeSpace{n,k} <: AbstractSphere{ℝ}\n\nKendall's pre-shape space of k landmarks in ℝ^n represented by n×k matrices. In each row the sum of elements of a matrix is equal to 0. The Frobenius norm of the matrix is equal to 1 [Kendall1984][Kendall1989].\n\nThe space can be interpreted as tuples of k points in ℝ^n up to simultaneous translation and scaling of all points, so this can be thought of as a quotient manifold.\n\nConstructor\n\nKendallsPreShapeSpace(n::Int, k::Int)\n\nSee also\n\nKendallsShapeSpace, esp. for the references\n\n\n\n\n\n","category":"type"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsShapeSpace.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/shapespace.html#Manifolds.KendallsShapeSpace","page":"Shape spaces","title":"Manifolds.KendallsShapeSpace","text":"KendallsShapeSpace{n,k} <: AbstractDecoratorManifold{ℝ}\n\nKendall's shape space, defined as quotient of a KendallsPreShapeSpace (represented by n×k matrices) by the action ColumnwiseMultiplicationAction.\n\nThe space can be interpreted as tuples of k points in ℝ^n up to simultaneous translation and scaling and rotation of all points [Kendall1984][Kendall1989].\n\nThis manifold possesses the IsQuotientManifold trait.\n\nConstructor\n\nKendallsShapeSpace(n::Int, k::Int)\n\nReferences\n\n[Kendall1989]: D. G. Kendall, “A Survey of the Statistical Theory of Shape,” Statist. Sci., vol. 4, no. 2, pp. 87–99, May 1989 doi: 10.1214/ss/1177012582.\n\n[Kendall1984]: D. G. Kendall, “Shape Manifolds, Procrustean Metrics, and Complex Projective Spaces,” Bull. London Math. Soc., vol. 16, no. 2, pp. 81–121, Mar. 1984 doi: 10.1112/blms/16.2.81.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/shapespace.html#Provided-functions","page":"Shape spaces","title":"Provided functions","text":"","category":"section"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsPreShapeSpace.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/shapespace.html#ManifoldsBase.check_point-Tuple{KendallsPreShapeSpace, Any}","page":"Shape spaces","title":"ManifoldsBase.check_point","text":"check_point(M::KendallsPreShapeSpace, p; atol=sqrt(max_eps(X, Y)), kwargs...)\n\nCheck whether p is a valid point on KendallsPreShapeSpace, i.e. whether each row has zero mean. Other conditions are checked via embedding in ArraySphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.check_vector-Tuple{KendallsPreShapeSpace, Any, Any}","page":"Shape spaces","title":"ManifoldsBase.check_vector","text":"check_vector(M::KendallsPreShapeSpace, p, X; kwargs... )\n\nCheck whether X is a valid tangent vector on KendallsPreShapeSpace, i.e. whether each row has zero mean. Other conditions are checked via embedding in ArraySphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.get_embedding-Union{Tuple{KendallsPreShapeSpace{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Shape spaces","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::KendallsPreShapeSpace)\n\nReturn the space KendallsPreShapeSpace M is embedded in, i.e. ArraySphere of matrices of the same shape.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.manifold_dimension-Union{Tuple{KendallsPreShapeSpace{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Shape spaces","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::KendallsPreShapeSpace)\n\nReturn the dimension of the KendallsPreShapeSpace manifold M. The dimension is given by n(k - 1) - 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.project-Tuple{KendallsPreShapeSpace, Any, Any}","page":"Shape spaces","title":"ManifoldsBase.project","text":"project(M::KendallsPreShapeSpace, p, X)\n\nProject tangent vector X at point p from the embedding to KendallsPreShapeSpace by selecting the right element from the tangent space to orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.\n\nReferences\n\n[Srivastava2016]: A. Srivastava and E. P. Klassen, Functional and Shape Data Analysis. Springer New York, 2016. ISBN: 978-1-4939-4018-9. doi: 10.1007/978-1-4939-4020-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.project-Tuple{KendallsPreShapeSpace, Any}","page":"Shape spaces","title":"ManifoldsBase.project","text":"project(M::KendallsPreShapeSpace, p)\n\nProject point p from the embedding to KendallsPreShapeSpace by selecting the right element from the orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.\n\nThe method computes the mean of the landmarks and moves them to make their mean zero; afterwards the Frobenius norm of the landmarks (as a matrix) is normalised to fix the scaling.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsShapeSpace.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/shapespace.html#Base.exp-Tuple{KendallsShapeSpace, Any, Any}","page":"Shape spaces","title":"Base.exp","text":"exp(M::KendallsShapeSpace, p, X)\n\nCompute the exponential map on KendallsShapeSpace M. See [Guigui2021] for discussion about its computation.\n\n[Guigui2021]: N. Guigui, E. Maignant, A. Trouvé, and X. Pennec, “Parallel Transport on Kendall Shape Spaces,” in Geometric Science of Information, Cham, 2021, pp. 103–110. doi: 10.1007/978-3-030-80209-7_12.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Base.log-Tuple{KendallsShapeSpace, Any, Any}","page":"Shape spaces","title":"Base.log","text":"log(M::KendallsShapeSpace, p, q)\n\nCompute the logarithmic map on KendallsShapeSpace M. See the [exp](@ref exp(::KendallsShapeSpace, ::Any, ::Any)onential map for more details\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Base.rand-Tuple{KendallsShapeSpace}","page":"Shape spaces","title":"Base.rand","text":"rand(::KendallsShapeSpace; vector_at=nothing)\n\nWhen vector_at is nothing, return a random point x on the KendallsShapeSpace manifold M by generating a random point in the embedding.\n\nWhen vector_at is not nothing, return a random vector from the tangent space with mean zero and standard deviation σ.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Manifolds.get_total_space-Union{Tuple{KendallsShapeSpace{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Shape spaces","title":"Manifolds.get_total_space","text":"get_total_space(::Grassmann{n,k})\n\nReturn the total space of the KendallsShapeSpace manifold, which is the KendallsPreShapeSpace manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Manifolds.horizontal_component-Tuple{KendallsShapeSpace, Any, Any}","page":"Shape spaces","title":"Manifolds.horizontal_component","text":"horizontal_component(::KendallsShapeSpace, p, X)\n\nCompute the horizontal component of tangent vector X at p on KendallsShapeSpace M. See [Guigui2021], Section 2.3 for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.get_embedding-Union{Tuple{KendallsShapeSpace{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Shape spaces","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::KendallsShapeSpace)\n\nGet the manifold in which KendallsShapeSpace M is embedded, i.e. KendallsPreShapeSpace of matrices of the same shape.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.is_flat-Tuple{KendallsShapeSpace}","page":"Shape spaces","title":"ManifoldsBase.is_flat","text":"is_flat(::KendallsShapeSpace)\n\nReturn false. KendallsShapeSpace is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.manifold_dimension-Union{Tuple{KendallsShapeSpace{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Shape spaces","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::KendallsShapeSpace)\n\nReturn the dimension of the KendallsShapeSpace manifold M. The dimension is given by n(k - 1) - 1 - n(n - 1)2 in the typical case where k geq n+1, and (k + 1)(k - 2) 2 otherwise, unless k is equal to 1, in which case the dimension is 0. See [Kendall1984] for a discussion of the over-dimensioned case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#Graph-manifold","page":"Graph manifold","title":"Graph manifold","text":"","category":"section"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"For a given graph G(VE) implemented using Graphs.jl, the GraphManifold models a PowerManifold either on the nodes or edges of the graph, depending on the GraphManifoldType. i.e., it's either a mathcal M^lvert V rvert for the case of a vertex manifold or a mathcal M^lvert E rvert for the case of a edge manifold.","category":"page"},{"location":"manifolds/graph.html#Example","page":"Graph manifold","title":"Example","text":"","category":"section"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"To make a graph manifold over ℝ^2 with three vertices and two edges, one can use","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"using Manifolds\nusing Graphs\nM = Euclidean(2)\np = [[1., 4.], [2., 5.], [3., 6.]]\nq = [[4., 5.], [6., 7.], [8., 9.]]\nx = [[6., 5.], [4., 3.], [2., 8.]]\nG = SimpleGraph(3)\nadd_edge!(G, 1, 2)\nadd_edge!(G, 2, 3)\nN = GraphManifold(G, M, VertexManifold())","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"It supports all AbstractPowerManifold operations (it is based on NestedPowerRepresentation) and furthermore it is possible to compute a graph logarithm:","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"using Manifolds\nusing Graphs\nM = Euclidean(2)\np = [[1., 4.], [2., 5.], [3., 6.]]\nq = [[4., 5.], [6., 7.], [8., 9.]]\nx = [[6., 5.], [4., 3.], [2., 8.]]\nG = SimpleGraph(3)\nadd_edge!(G, 1, 2)\nadd_edge!(G, 2, 3)\nN = GraphManifold(G, M, VertexManifold())","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"incident_log(N, p)","category":"page"},{"location":"manifolds/graph.html#Types-and-functions","page":"Graph manifold","title":"Types and functions","text":"","category":"section"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/GraphManifold.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/graph.html#Manifolds.EdgeManifold","page":"Graph manifold","title":"Manifolds.EdgeManifold","text":"EdgeManifoldManifold <: GraphManifoldType\n\nA type for a GraphManifold where the data is given on the edges.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.GraphManifold","page":"Graph manifold","title":"Manifolds.GraphManifold","text":"GraphManifold{G,𝔽,M,T} <: AbstractPowerManifold{𝔽,M,NestedPowerRepresentation}\n\nBuild a manifold, that is a PowerManifold of the AbstractManifold M either on the edges or vertices of a graph G depending on the GraphManifoldType T.\n\nFields\n\nG is an AbstractSimpleGraph\nM is a AbstractManifold\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.GraphManifoldType","page":"Graph manifold","title":"Manifolds.GraphManifoldType","text":"GraphManifoldType\n\nThis type represents the type of data on the graph that the GraphManifold represents.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.VertexManifold","page":"Graph manifold","title":"Manifolds.VertexManifold","text":"VectexGraphManifold <: GraphManifoldType\n\nA type for a GraphManifold where the data is given on the vertices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.incident_log-Tuple{GraphManifold{<:Graphs.AbstractGraph, 𝔽, <:AbstractManifold{𝔽}, VertexManifold} where 𝔽, Any}","page":"Graph manifold","title":"Manifolds.incident_log","text":"incident_log(M::GraphManifold, x)\n\nReturn the tangent vector on the (vertex) GraphManifold, where at each node the sum of the logs to incident nodes is computed. For a SimpleGraph, an egde is interpreted as double edge in the corresponding SimpleDiGraph\n\nIf the internal graph is a SimpleWeightedGraph the weighted sum of the tangent vectors is computed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.check_point-Tuple{GraphManifold, Vararg{Any}}","page":"Graph manifold","title":"ManifoldsBase.check_point","text":"check_point(M::GraphManifold, p)\n\nCheck whether p is a valid point on the GraphManifold, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of p passes the check_point test for the base manifold M.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.check_vector-Tuple{GraphManifold, Vararg{Any}}","page":"Graph manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::GraphManifold, p, X; kwargs...)\n\nCheck whether p is a valid point on the GraphManifold, and X it from its tangent space, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of X together with its corresponding entry of p passes the check_vector test for the base manifold M.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.manifold_dimension-Tuple{GraphManifold{<:Graphs.AbstractGraph, 𝔽, <:AbstractManifold{𝔽}, EdgeManifold} where 𝔽}","page":"Graph manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(N::GraphManifold{G,𝔽,M,EdgeManifold})\n\nreturns the manifold dimension of the GraphManifold N on the edges of a graph G=(VE), i.e.\n\ndim(mathcal N) = lvert E rvert dim(mathcal M)\n\nwhere mathcal M is the manifold of the data on the edges.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.manifold_dimension-Tuple{GraphManifold{<:Graphs.AbstractGraph, 𝔽, <:AbstractManifold{𝔽}, VertexManifold} where 𝔽}","page":"Graph manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(N::GraphManifold{G,𝔽,M,VertexManifold})\n\nreturns the manifold dimension of the GraphManifold N on the vertices of a graph G=(VE), i.e.\n\ndim(mathcal N) = lvert V rvert dim(mathcal M)\n\nwhere mathcal M is the manifold of the data on the nodes.\n\n\n\n\n\n","category":"method"},{"location":"features/integration.html#Integration","page":"Integration","title":"Integration","text":"","category":"section"},{"location":"features/integration.html","page":"Integration","title":"Integration","text":"manifold_volume(::AbstractManifold)\nvolume_density(::AbstractManifold, ::Any, ::Any)","category":"page"},{"location":"features/integration.html#Manifolds.manifold_volume-Tuple{AbstractManifold}","page":"Integration","title":"Manifolds.manifold_volume","text":"manifold_volume(M::AbstractManifold)\n\nVolume of manifold M defined through integration of Riemannian volume element in a chart. Note that for many manifolds there is no universal agreement over the exact ranges over which the integration should happen. For details see [BoyaSudarshanTilma2003].\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"features/integration.html#Manifolds.volume_density-Tuple{AbstractManifold, Any, Any}","page":"Integration","title":"Manifolds.volume_density","text":"volume_density(M::AbstractManifold, p, X)\n\nVolume density function of manifold M, i.e. determinant of the differential of exponential map exp(M, p, X). Determinant can be understood as computed in a basis, from the matrix of the linear operator said differential corresponds to. Details are available in Section 4.1 of [ChevallierLiLuDunson2022].\n\nNote that volume density is well-defined only for X for which exp(M, p, X) is injective.\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#EuclideanSection","page":"Euclidean","title":"Euclidean space","text":"","category":"section"},{"location":"manifolds/euclidean.html","page":"Euclidean","title":"Euclidean","text":"The Euclidean space ℝ^n is a simple model space, since it has curvature constantly zero everywhere; hence, nearly all operations simplify. The easiest way to generate an Euclidean space is to use a field, i.e. AbstractNumbers, e.g. to create the ℝ^n or ℝ^ntimes n you can simply type M = ℝ^n or ℝ^(n,n), respectively.","category":"page"},{"location":"manifolds/euclidean.html","page":"Euclidean","title":"Euclidean","text":"Modules = [Manifolds]\nPages = [\"manifolds/Euclidean.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/euclidean.html#Manifolds.Euclidean","page":"Euclidean","title":"Manifolds.Euclidean","text":"Euclidean{T<:Tuple,𝔽} <: AbstractManifold{𝔽}\n\nEuclidean vector space.\n\nConstructor\n\nEuclidean(n)\n\nGenerate the n-dimensional vector space ℝ^n.\n\nEuclidean(n₁,n₂,...,nᵢ; field=ℝ)\n𝔽^(n₁,n₂,...,nᵢ) = Euclidean(n₁,n₂,...,nᵢ; field=𝔽)\n\nGenerate the vector space of k = n_1 cdot n_2 cdot cdot n_i values, i.e. the manifold 𝔽^n_1 n_2 n_i, 𝔽inℝℂ, whose elements are interpreted as n_1 n_2 n_i arrays. For i=2 we obtain a matrix space. The default field=ℝ can also be set to field=ℂ. The dimension of this space is k dim_ℝ 𝔽, where dim_ℝ 𝔽 is the real_dimension of the field 𝔽.\n\nEuclidean(; field=ℝ)\n\nGenerate the 1D Euclidean manifold for an ℝ-, ℂ-valued real- or complex-valued immutable values (in contrast to 1-element arrays from the constructor above).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/euclidean.html#Base.exp-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"Base.exp","text":"exp(M::Euclidean, p, X)\n\nCompute the exponential map on the Euclidean manifold M from p in direction X, which in this case is just\n\nexp_p X = p + X\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#Base.log-Tuple{Euclidean, Vararg{Any}}","page":"Euclidean","title":"Base.log","text":"log(M::Euclidean, p, q)\n\nCompute the logarithmic map on the Euclidean M from p to q, which in this case is just\n\nlog_p q = q-p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#LinearAlgebra.norm-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"LinearAlgebra.norm","text":"norm(M::Euclidean, p, X)\n\nCompute the norm of a tangent vector X at p on the Euclidean M, i.e. since every tangent space can be identified with M itself in this case, just the (Frobenius) norm of X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#Manifolds.manifold_volume-Tuple{Euclidean}","page":"Euclidean","title":"Manifolds.manifold_volume","text":"manifold_volume(::Euclidean)\n\nReturn volume of the Euclidean manifold, i.e. infinity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#Manifolds.volume_density-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"Manifolds.volume_density","text":"volume_density(M::Euclidean, p, X)\n\nReturn volume density function of Euclidean manifold M, i.e. 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.distance-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"ManifoldsBase.distance","text":"distance(M::Euclidean, p, q)\n\nCompute the Euclidean distance between two points on the Euclidean manifold M, i.e. for vectors it's just the norm of the difference, for matrices and higher order arrays, the matrix and ternsor Frobenius norm, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.embed-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"ManifoldsBase.embed","text":"embed(M::Euclidean, p, X)\n\nEmbed the tangent vector X at point p in M. Equivalent to an identity map.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.embed-Tuple{Euclidean, Any}","page":"Euclidean","title":"ManifoldsBase.embed","text":"embed(M::Euclidean, p)\n\nEmbed the point p in M. Equivalent to an identity map.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.injectivity_radius-Tuple{Euclidean}","page":"Euclidean","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Euclidean)\n\nReturn the injectivity radius on the Euclidean M, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.inner-Tuple{Euclidean, Vararg{Any}}","page":"Euclidean","title":"ManifoldsBase.inner","text":"inner(M::Euclidean, p, X, Y)\n\nCompute the inner product on the Euclidean M, which is just the inner product on the real-valued or complex valued vector space of arrays (or tensors) of size n_1 n_2 n_i, i.e.\n\ng_p(XY) = sum_k I overlineX_k Y_k\n\nwhere I is the set of vectors k ℕ^i, such that for all\n\ni j i it holds 1 k_j n_j and overlinecdot denotes the complex conjugate.\n\nFor the special case of i 2, i.e. matrices and vectors, this simplifies to\n\ng_p(XY) = X^mathrmHY\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.is_flat-Tuple{Euclidean}","page":"Euclidean","title":"ManifoldsBase.is_flat","text":"is_flat(::Euclidean)\n\nReturn true. Euclidean is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.manifold_dimension-Union{Tuple{Euclidean{N, 𝔽}}, Tuple{𝔽}, Tuple{N}} where {N, 𝔽}","page":"Euclidean","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Euclidean)\n\nReturn the manifold dimension of the Euclidean M, i.e. the product of all array dimensions and the real_dimension of the underlying number system.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.parallel_transport_along-Tuple{Euclidean, Any, Any, AbstractVector}","page":"Euclidean","title":"ManifoldsBase.parallel_transport_along","text":"parallel_transport_along(M::Euclidean, p, X, c)\n\nthe parallel transport on Euclidean is the identiy, i.e. returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.parallel_transport_direction-Tuple{Euclidean, Any, Any, Any}","page":"Euclidean","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::Euclidean, p, X, d)\n\nthe parallel transport on Euclidean is the identiy, i.e. returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.parallel_transport_to-Tuple{Euclidean, Any, Any, Any}","page":"Euclidean","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::Euclidean, p, X, q)\n\nthe parallel transport on Euclidean is the identiy, i.e. returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.project-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"ManifoldsBase.project","text":"project(M::Euclidean, p, X)\n\nProject an arbitrary vector X into the tangent space of a point p on the Euclidean M, which is just the identity, since any tangent space of M can be identified with all of M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.project-Tuple{Euclidean, Any}","page":"Euclidean","title":"ManifoldsBase.project","text":"project(M::Euclidean, p)\n\nProject an arbitrary point p onto the Euclidean manifold M, which is of course just the identity map.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.representation_size-Union{Tuple{Euclidean{N}}, Tuple{N}} where N","page":"Euclidean","title":"ManifoldsBase.representation_size","text":"representation_size(M::Euclidean)\n\nReturn the array dimensions required to represent an element on the Euclidean M, i.e. the vector of all array dimensions.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.riemann_tensor-Tuple{Euclidean, Vararg{Any, 4}}","page":"Euclidean","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::Euclidean, p, X, Y, Z)\n\nCompute the Riemann tensor R(XY)Z at point p on Euclidean manifold M. Its value is always the zero tangent vector. ````\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.vector_transport_to-Tuple{Euclidean, Any, Any, Any, AbstractVectorTransportMethod}","page":"Euclidean","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Euclidean, p, X, q, ::AbstractVectorTransportMethod)\n\nTransport the vector X from the tangent space at p to the tangent space at q on the Euclidean M, which simplifies to the identity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.zero_vector-Tuple{Euclidean, Vararg{Any}}","page":"Euclidean","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Euclidean, x)\n\nReturn the zero vector in the tangent space of x on the Euclidean M, which here is just a zero filled array the same size as x.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#Multinomial-symmetric-matrices","page":"Multinomial symmetric matrices","title":"Multinomial symmetric matrices","text":"","category":"section"},{"location":"manifolds/multinomialsymmetric.html","page":"Multinomial symmetric matrices","title":"Multinomial symmetric matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/MultinomialSymmetric.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/multinomialsymmetric.html#Manifolds.MultinomialSymmetric","page":"Multinomial symmetric matrices","title":"Manifolds.MultinomialSymmetric","text":"MultinomialSymmetric{n} <: AbstractMultinomialDoublyStochastic{N}\n\nThe multinomial symmetric matrices manifold consists of all symmetric nn matrices with positive entries such that each column sums to one, i.e.\n\nbeginaligned\nmathcalSP(n) coloneqq biglp ℝ^nn big p_ij 0 text for all i=1n j=1m\n p^mathrmT = p\n pmathbf1_n = mathbf1_n\nbigr\nendaligned\n\nwhere mathbf1_n is the vector of length n containing ones.\n\nIt is modeled as IsIsometricEmbeddedManifold. via the AbstractMultinomialDoublyStochastic type, since it shares a few functions also with AbstractMultinomialDoublyStochastic, most and foremost projection of a point from the embedding onto the manifold.\n\nThe tangent space can be written as\n\nT_pmathcalSP(n) coloneqq bigl\nX ℝ^nn big X = X^mathrmT text and \nXmathbf1_n = mathbf0_n\nbigr\n\nwhere mathbf0_n is the vector of length n containing zeros.\n\nMore details can be found in Section IV[DouikHassibi2019].\n\nConstructor\n\nMultinomialSymmetric(n)\n\nGenerate the manifold of matrices mathbb R^nn that are doubly stochastic and symmetric.\n\n[DouikHassibi2019]: A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.check_point-Union{Tuple{n}, Tuple{MultinomialSymmetric{n}, Any}} where n","page":"Multinomial symmetric matrices","title":"ManifoldsBase.check_point","text":"check_point(M::MultinomialSymmetric, p)\n\nChecks whether p is a valid point on the MultinomialSymmetric(m,n) M, i.e. is a symmetric matrix with positive entries whose rows sum to one.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.check_vector-Union{Tuple{n}, Tuple{MultinomialSymmetric{n}, Any, Any}} where n","page":"Multinomial symmetric matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::MultinomialSymmetric p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the MultinomialSymmetric M. This means, that p is valid, that X is of correct dimension, symmetric, and sums to zero along any row.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.is_flat-Tuple{MultinomialSymmetric}","page":"Multinomial symmetric matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::MultinomialSymmetric)\n\nReturn false. MultinomialSymmetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.manifold_dimension-Union{Tuple{MultinomialSymmetric{n}}, Tuple{n}} where n","page":"Multinomial symmetric matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::MultinomialSymmetric{n}) where {n}\n\nreturns the dimension of the MultinomialSymmetric manifold namely\n\noperatornamedim_mathcalSP(n) = fracn(n-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.project-Tuple{MultinomialSymmetric, Any, Any}","page":"Multinomial symmetric matrices","title":"ManifoldsBase.project","text":"project(M::MultinomialSymmetric{n}, p, Y) where {n}\n\nProject Y onto the tangent space at p on the MultinomialSymmetric M, return the result in X. The formula reads\n\n operatornameproj_p(Y) = Y - (αmathbf1_n^mathrmT + mathbf1_n α^mathrmT) p\n\nwhere denotes the Hadamard or elementwise product and mathbb1_n is the vector of length n containing ones. The two vector α ℝ^nn is given by solving\n\n (I_n+p)α = Ymathbf1\n\nwhere I_n is teh nn unit matrix and mathbf1_n is the vector of length n containing ones.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.retract-Tuple{MultinomialSymmetric, Any, Any, ProjectionRetraction}","page":"Multinomial symmetric matrices","title":"ManifoldsBase.retract","text":"retract(M::MultinomialSymmetric, p, X, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting podotexp(Xp) back onto the manifold, where are elementwise multiplication and division, respectively. Similarly, exp refers to the elementwise exponentiation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#Literature","page":"Multinomial symmetric matrices","title":"Literature","text":"","category":"section"},{"location":"manifolds/quotient.html#QuotientManifoldSection","page":"Quotient manifold","title":"Quotient manifold","text":"","category":"section"},{"location":"manifolds/quotient.html","page":"Quotient manifold","title":"Quotient manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/QuotientManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/quotient.html#Manifolds.IsQuotientManifold","page":"Quotient manifold","title":"Manifolds.IsQuotientManifold","text":"IsQuotientManifold <: AbstractTrait\n\nSpecify that a certain decorated manifold is a quotient manifold in the sense that it provides implicitly (or explicitly through QuotientManifold properties of a quotient manifold.\n\nSee QuotientManifold for more details.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/quotient.html#Manifolds.QuotientManifold","page":"Quotient manifold","title":"Manifolds.QuotientManifold","text":"QuotientManifold{M <: AbstractManifold{𝔽}, N} <: AbstractManifold{𝔽}\n\nEquip a manifold mathcal M explicitly with the property of being a quotient manifold.\n\nA manifold mathcal M is then a a quotient manifold of another manifold mathcal N, i.e. for an equivalence relation on mathcal N we have\n\n mathcal M = mathcal N = bigl p p mathcal N bigr\n\nwhere p q mathcal N q p denotes the equivalence class containing p. For more details see Subsection 3.4.1[AbsilMahonySepulchre2008].\n\nThis manifold type models an explicit quotient structure. This should be done if either the default implementation of mathcal M uses another representation different from the quotient structure or if it provides a (default) quotient structure that is different from the one introduced here.\n\nFields\n\nmanifold – the manifold mathcal M in the introduction above.\ntotal_space – the manifold mathcal N in the introduction above.\n\nConstructor\n\nQuotientManifold(M,N)\n\nCreate a manifold where M is the quotient manifold and Nis its total space.\n\n[AbsilMahonySepulchre2008]: Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access\n\n\n\n\n\n","category":"type"},{"location":"manifolds/quotient.html#Provided-functions","page":"Quotient manifold","title":"Provided functions","text":"","category":"section"},{"location":"manifolds/quotient.html","page":"Quotient manifold","title":"Quotient manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/QuotientManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/quotient.html#Manifolds.canonical_project!-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.canonical_project!","text":"canonical_project!(M, q, p)\n\nCompute the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold in place of q.\n\nSee canonical_project for more details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.canonical_project-Tuple{AbstractManifold, Any}","page":"Quotient manifold","title":"Manifolds.canonical_project","text":"canonical_project(M, p)\n\nCompute the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection π from the total space mathcal N onto mathcal M given by\n\n π = π_mathcal N mathcal M mathcal N mathcal M p π_mathcal N mathcal M(p) = p\n\nin other words, this function implicitly assumes, that the total space mathcal N is given, for example explicitly when M is a QuotientManifold and p is a point on N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.differential_canonical_project!-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.differential_canonical_project!","text":"differential_canonical_project!(M, Y, p, X)\n\nCompute the differential of the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold. See differential_canonical_project for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.differential_canonical_project-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.differential_canonical_project","text":"differential_canonical_project(M, p, X)\n\nCompute the differential of the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection π from the total space mathcal N onto mathcal M, such that its differential\n\n Dπ(p) T_pmathcal N T_π(p)mathcal M\n\nwhere again the total space might be implicitly assumed, or explicitly when using a QuotientManifold M. So here p is a point on N and X is from T_pmathcal N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.get_orbit_action-Tuple{AbstractManifold}","page":"Quotient manifold","title":"Manifolds.get_orbit_action","text":"get_orbit_action(M::AbstractDecoratorManifold)\n\nReturn the group action that generates the orbit of an equivalence class of the quotient manifold M for which equivalence classes are orbits of an action of a Lie group. For the case that\n\nmathcal M = mathcal N mathcal O\n\nwhere mathcal O is a Lie group with its group action generating the orbit.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.get_total_space-Tuple{AbstractManifold}","page":"Quotient manifold","title":"Manifolds.get_total_space","text":"get_total_space(M::AbstractDecoratorManifold)\n\nReturn the total space of a manifold that IsQuotientManifold, e.g. a QuotientManifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.horizontal_component-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.horizontal_component","text":"horizontal_component(N::AbstractManifold, p, X)\n\nCompute the horizontal component of tangent vector X at point p in the total space of quotient manifold N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.horizontal_lift!-Tuple{AbstractManifold, Any, Any, Any}","page":"Quotient manifold","title":"Manifolds.horizontal_lift!","text":"horizontal_lift!(N, Y, q, X)\nhorizontal_lift!(QuotientManifold{M,N}, Y, p, X)\n\nCompute the horizontal_lift of X from T_pmathcal M, p=π(q). to `T_q\\mathcal N in place of Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.horizontal_lift-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.horizontal_lift","text":"horizontal_lift(N::AbstractManifold, q, X)\nhorizontal_lift(::QuotientManifold{𝔽,MT<:AbstractManifold{𝔽},NT<:AbstractManifold}, p, X) where {𝔽}\n\nGiven a point q in total space of quotient manifold N such that p=π(q) is a point on a quotient manifold M (implicitly given for the first case) and a tangent vector X this method computes a tangent vector Y on the horizontal space of T_qmathcal N, i.e. the subspace that is orthogonal to the kernel of Dπ(q).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.vertical_component-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.vertical_component","text":"vertical_component(N::AbstractManifold, p, X)\n\nCompute the vertical component of tangent vector X at point p in the total space of quotient manifold N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#Centered-matrices","page":"Centered matrices","title":"Centered matrices","text":"","category":"section"},{"location":"manifolds/centeredmatrices.html","page":"Centered matrices","title":"Centered matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/CenteredMatrices.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/centeredmatrices.html#Manifolds.CenteredMatrices","page":"Centered matrices","title":"Manifolds.CenteredMatrices","text":"CenteredMatrices{m,n,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe manifold of m n real-valued or complex-valued matrices whose columns sum to zero, i.e.\n\nbigl p 𝔽^m n big 1 1 * p = 0 0 bigr\n\nwhere 𝔽 ℝℂ.\n\nConstructor\n\nCenteredMatrices(m, n[, field=ℝ])\n\nGenerate the manifold of m-by-n (field-valued) matrices whose columns sum to zero.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{CenteredMatrices{m, n, 𝔽}, Any}} where {m, n, 𝔽}","page":"Centered matrices","title":"ManifoldsBase.check_point","text":"check_point(M::CenteredMatrices{m,n,𝔽}, p; kwargs...)\n\nCheck whether the matrix is a valid point on the CenteredMatrices M, i.e. is an m-by-n matrix whose columns sum to zero.\n\nThe tolerance for the column sums of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{CenteredMatrices{m, n, 𝔽}, Any, Any}} where {m, n, 𝔽}","page":"Centered matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::CenteredMatrices{m,n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the CenteredMatrices M, i.e. that X is a matrix of size (m, n) whose columns sum to zero and its values are from the correct AbstractNumbers. The tolerance for the column sums of p and X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.is_flat-Tuple{CenteredMatrices}","page":"Centered matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::CenteredMatrices)\n\nReturn true. CenteredMatrices is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.manifold_dimension-Union{Tuple{CenteredMatrices{m, n, 𝔽}}, Tuple{𝔽}, Tuple{n}, Tuple{m}} where {m, n, 𝔽}","page":"Centered matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::CenteredMatrices{m,n,𝔽})\n\nReturn the manifold dimension of the CenteredMatrices m-by-n matrix M over the number system 𝔽, i.e.\n\ndim(mathcal M) = (m*n - n) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.project-Tuple{CenteredMatrices, Any, Any}","page":"Centered matrices","title":"ManifoldsBase.project","text":"project(M::CenteredMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the CenteredMatrices M, i.e.\n\noperatornameproj_p(X) = X - beginbmatrix\n1\n\n1\nendbmatrix * c_1 dots c_n\n\nwhere c_i = frac1msum_j=1^m x_ji for i = 1 dots n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.project-Tuple{CenteredMatrices, Any}","page":"Centered matrices","title":"ManifoldsBase.project","text":"project(M::CenteredMatrices, p)\n\nProjects p from the embedding onto the CenteredMatrices M, i.e.\n\noperatornameproj_mathcal M(p) = p - beginbmatrix\n1\n\n1\nendbmatrix * c_1 dots c_n\n\nwhere c_i = frac1msum_j=1^m p_ji for i = 1 dots n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#GroupManifoldSection","page":"Group manifold","title":"Group manifolds and actions","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Lie groups, groups that are Riemannian manifolds with a smooth binary group operation AbstractGroupOperation, are implemented as AbstractDecoratorManifold and specifying the group operation using the IsGroupManifold or by decorating an existing manifold with a group operation using GroupManifold.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"The common addition and multiplication group operations of AdditionOperation and MultiplicationOperation are provided, though their behavior may be customized for a specific group.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"There are short introductions at the beginning of each subsection. They briefly mention what is available with links to more detailed descriptions.","category":"page"},{"location":"manifolds/group.html#Contents","page":"Group manifold","title":"Contents","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Pages = [\"group.md\"]\nDepth = 3","category":"page"},{"location":"manifolds/group.html#Groups","page":"Group manifold","title":"Groups","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"The following operations are available for group manifolds:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Identity: an allocation-free representation of the identity element of the group.\ninv: get the inverse of a given element.\ncompose: compose two given elements of a group.\nidentity_element get the identity element of the group, in the representation used by other points from the group.","category":"page"},{"location":"manifolds/group.html#Group-manifold","page":"Group manifold","title":"Group manifold","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"GroupManifold adds a group structure to the wrapped manifold. It does not affect metric (or connection) structure of the wrapped manifold, however it can to be further wrapped in MetricManifold to get invariant metrics, or in a ConnectionManifold to equip it with a Cartan-Schouten connection.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/group.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AbstractGroupOperation","page":"Group manifold","title":"Manifolds.AbstractGroupOperation","text":"AbstractGroupOperation\n\nAbstract type for smooth binary operations on elements of a Lie group mathcalG:\n\n mathcalG mathcalG mathcalG\n\nAn operation can be either defined for a specific group manifold over number system 𝔽 or in general, by defining for an operation Op the following methods:\n\nidentity_element!(::AbstractDecoratorManifold, q, q)\ninv!(::AbstractDecoratorManifold, q, p)\n_compose!(::AbstractDecoratorManifold, x, p, q)\n\nNote that a manifold is connected with an operation by wrapping it with a decorator, AbstractDecoratorManifold using the IsGroupManifold to specify the operation. For a concrete case the concrete wrapper GroupManifold can be used.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.AbstractInvarianceTrait","page":"Group manifold","title":"Manifolds.AbstractInvarianceTrait","text":"AbstractInvarianceTrait <: AbstractTrait\n\nA common supertype for anz AbstractTrait related to metric invariance\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.ActionDirection","page":"Group manifold","title":"Manifolds.ActionDirection","text":"ActionDirection\n\nDirection of action on a manifold, either LeftForwardAction, LeftBackwardAction, RightForwardAction or RightBackwardAction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.ForwardBackwardSwitch","page":"Group manifold","title":"Manifolds.ForwardBackwardSwitch","text":"struct ForwardBackwardSwitch <: AbstractDirectionSwitchType end\n\nSwitch between forward and backward action, maintaining left/right direction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.GroupExponentialRetraction","page":"Group manifold","title":"Manifolds.GroupExponentialRetraction","text":"GroupExponentialRetraction{D<:ActionDirection} <: AbstractRetractionMethod\n\nRetraction using the group exponential exp_lie \"translated\" to any point on the manifold.\n\nFor more details, see retract.\n\nConstructor\n\nGroupExponentialRetraction(conv::ActionDirection = LeftForwardAction())\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.GroupLogarithmicInverseRetraction","page":"Group manifold","title":"Manifolds.GroupLogarithmicInverseRetraction","text":"GroupLogarithmicInverseRetraction{D<:ActionDirection} <: AbstractInverseRetractionMethod\n\nRetraction using the group logarithm log_lie \"translated\" to any point on the manifold.\n\nFor more details, see inverse_retract.\n\nConstructor\n\nGroupLogarithmicInverseRetraction(conv::ActionDirection = LeftForwardAction())\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.HasBiinvariantMetric","page":"Group manifold","title":"Manifolds.HasBiinvariantMetric","text":"HasBiinvariantMetric <: AbstractInvarianceTrait\n\nSpecify that a certain the metric of a GroupManifold is a bi-invariant metric\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.HasLeftInvariantMetric","page":"Group manifold","title":"Manifolds.HasLeftInvariantMetric","text":"HasLeftInvariantMetric <: AbstractInvarianceTrait\n\nSpecify that a certain the metric of a GroupManifold is a left-invariant metric\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.HasRightInvariantMetric","page":"Group manifold","title":"Manifolds.HasRightInvariantMetric","text":"HasRightInvariantMetric <: AbstractInvarianceTrait\n\nSpecify that a certain the metric of a GroupManifold is a right-invariant metric\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.Identity","page":"Group manifold","title":"Manifolds.Identity","text":"Identity{O<:AbstractGroupOperation}\n\nRepresent the group identity element e mathcalG on a Lie group mathcal G with AbstractGroupOperation of type O.\n\nSimilar to the philosophy that points are agnostic of their group at hand, the identity does not store the group g it belongs to. However it depends on the type of the AbstractGroupOperation used.\n\nSee also identity_element on how to obtain the corresponding AbstractManifoldPoint or array representation.\n\nConstructors\n\nIdentity(G::AbstractDecoratorManifold{𝔽})\nIdentity(o::O)\nIdentity(::Type{O})\n\ncreate the identity of the corresponding subtype O<:AbstractGroupOperation\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.IsGroupManifold","page":"Group manifold","title":"Manifolds.IsGroupManifold","text":"IsGroupManifold{O<:AbstractGroupOperation} <: AbstractTrait\n\nA trait to declare an AbstractManifold as a manifold with group structure with operation of type O.\n\nUsing this trait you can turn a manifold that you implement implictly into a Lie group. If you wish to decorate an existing manifold with one (or different) AbstractGroupActions, see GroupManifold.\n\nConstructor\n\nIsGroupManifold(op)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.LeftBackwardAction","page":"Group manifold","title":"Manifolds.LeftBackwardAction","text":"LeftBackwardAction()\n\nLeft action of a group on a manifold. For an action α X G X it is characterized by \n\nα(α(x h) g) = α(x gh)\n\nfor all g h G and x X.\n\nNote that a left action may still act from the right side in an expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.LeftForwardAction","page":"Group manifold","title":"Manifolds.LeftForwardAction","text":"LeftForwardAction()\n\nLeft action of a group on a manifold. For an action α G X X it is characterized by \n\nα(g α(h x)) = α(gh x)\n\nfor all g h G and x X.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.LeftRightSwitch","page":"Group manifold","title":"Manifolds.LeftRightSwitch","text":"struct LeftRightSwitch <: AbstractDirectionSwitchType end\n\nSwitch between left and right action, maintaining forward/backward direction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RightBackwardAction","page":"Group manifold","title":"Manifolds.RightBackwardAction","text":"RightBackwardAction()\n\nRight action of a group on a manifold. For an action α X G X it is characterized by \n\nα(α(x h) g) = α(x hg)\n\nfor all g h G and x X.\n\nNote that a right action may still act from the left side in an expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RightForwardAction","page":"Group manifold","title":"Manifolds.RightForwardAction","text":"RightForwardAction()\n\nRight action of a group on a manifold. For an action α G X X it is characterized by \n\nα(g α(h x)) = α(hg x)\n\nfor all g h G and x X.\n\nNote that a right action may still act from the left side in an expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.SimultaneousSwitch","page":"Group manifold","title":"Manifolds.SimultaneousSwitch","text":"struct LeftRightSwitch <: AbstractDirectionSwitchType end\n\nSimultaneously switch left/right and forward/backward directions.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.inv-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Base.inv","text":"inv(G::AbstractDecoratorManifold, p)\n\nInverse p^-1 mathcalG of an element p mathcalG, such that p circ p^-1 = p^-1 circ p = e mathcalG, where e is the Identity element of mathcalG.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.adjoint_action-Tuple{AbstractDecoratorManifold, Any, Any}","page":"Group manifold","title":"Manifolds.adjoint_action","text":"adjoint_action(G::AbstractDecoratorManifold, p, X)\n\nAdjoint action of the element p of the Lie group G on the element X of the corresponding Lie algebra.\n\nIt is defined as the differential of the group authomorphism Ψ_p(q) = pqp¹ at the identity of G.\n\nThe formula reads\n\noperatornameAd_p(X) = dΨ_p(e)X\n\nwhere e is the identity element of G.\n\nNote that the adjoint representation of a Lie group isn't generally faithful. Notably the adjoint representation of SO(2) is trivial.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.compose-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.compose","text":"compose(G::AbstractDecoratorManifold, p, q)\n\nCompose elements pq mathcalG using the group operation p circ q.\n\nFor implementing composition on a new group manifold, please overload _compose instead so that methods with Identity arguments are not ambiguous.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{AbstractManifold, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G, X)\nexp_lie!(G, q, X)\n\nCompute the group exponential of the Lie algebra element X. It is equivalent to the exponential map defined by the CartanSchoutenMinus connection.\n\nGiven an element X 𝔤 = T_e mathcalG, where e is the Identity element of the group mathcalG, and 𝔤 is its Lie algebra, the group exponential is the map\n\nexp 𝔤 mathcalG\n\nsuch that for ts ℝ, γ(t) = exp (t X) defines a one-parameter subgroup with the following properties. Note that one-parameter subgroups are commutative (see [Suhubi2013], section 3.5), even if the Lie group itself is not commutative.\n\nbeginaligned\nγ(t) = γ(-t)^-1\nγ(t + s) = γ(t) circ γ(s) = γ(s) circ γ(t)\nγ(0) = e\nlim_t 0 fracddt γ(t) = X\nendaligned\n\nnote: Note\nIn general, the group exponential map is distinct from the Riemannian exponential map exp.\n\nFor example for the MultiplicationOperation and either Number or AbstractMatrix the Lie exponential is the numeric/matrix exponential.\n\nexp X = operatornameExp X = sum_n=0^ frac1n X^n\n\nSince this function also depends on the group operation, make sure to implement the corresponding trait version exp_lie(::TraitList{<:IsGroupManifold}, G, X).\n\n[Suhubi2013]: E. Suhubi, Exterior Analysis: Using Applications of Differential Forms, 1st edition. Amsterdam: Academic Press, 2013.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.get_coordinates_lie-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractManifold, Any, AbstractBasis}","page":"Group manifold","title":"Manifolds.get_coordinates_lie","text":"get_coordinates_lie(G::AbstractManifold, X, B::AbstractBasis)\n\nGet the coordinates of an element X from the Lie algebra og G with respect to a basis B. This is similar to calling get_coordinates at the p=Identity(G).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.get_vector_lie-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractManifold, Any, AbstractBasis}","page":"Group manifold","title":"Manifolds.get_vector_lie","text":"get_vector_lie(G::AbstractDecoratorManifold, a, B::AbstractBasis)\n\nReconstruct a tangent vector from the Lie algebra of G from cooordinates a of a basis B. This is similar to calling get_vector at the p=Identity(G).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.identity_element-Tuple{AbstractDecoratorManifold, Any}","page":"Group manifold","title":"Manifolds.identity_element","text":"identity_element(G::AbstractDecoratorManifold, p)\n\nReturn a point representation of the Identity on the IsGroupManifold G, where p indicates the type to represent the identity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.identity_element-Tuple{AbstractDecoratorManifold}","page":"Group manifold","title":"Manifolds.identity_element","text":"identity_element(G)\n\nReturn a point representation of the Identity on the IsGroupManifold G. By default this representation is the default array or number representation. It should return the corresponding default representation of e as a point on G if points are not represented by arrays.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_translate-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.inverse_translate","text":"inverse_translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction())\n\nInverse translate group element q by p with the inverse translation τ_p^-1 with the specified convention, either left (L_p^-1) or right (R_p^-1), defined as\n\nbeginaligned\nL_p^-1 q p^-1 circ q\nR_p^-1 q q circ p^-1\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_translate_diff-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.inverse_translate_diff","text":"inverse_translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())\n\nFor group elements p q mathcalG and tangent vector X T_q mathcalG, compute the action on X of the differential of the inverse translation τ_p by p, with the specified left or right convention. The differential transports vectors:\n\n(mathrmdτ_p^-1)_q T_q mathcalG T_τ_p^-1 q mathcalG\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.is_group_manifold-Tuple{AbstractManifold, AbstractGroupOperation}","page":"Group manifold","title":"Manifolds.is_group_manifold","text":"is_group_manifold(G::GroupManifold)\nis_group_manifoldd(G::AbstractManifold, o::AbstractGroupOperation)\n\nreturns whether an AbstractDecoratorManifold is a group manifold with AbstractGroupOperation o. For a GroupManifold G this checks whether the right operations is stored within G.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.is_identity-Tuple{AbstractDecoratorManifold, Any}","page":"Group manifold","title":"Manifolds.is_identity","text":"is_identity(G::AbstractDecoratorManifold, q; kwargs)\n\nCheck whether q is the identity on the IsGroupManifold G, i.e. it is either the Identity{O} with the corresponding AbstractGroupOperation O, or (approximately) the correct point representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.lie_bracket-Tuple{AbstractDecoratorManifold, Any, Any}","page":"Group manifold","title":"Manifolds.lie_bracket","text":"lie_bracket(G::AbstractDecoratorManifold, X, Y)\n\nLie bracket between elements X and Y of the Lie algebra corresponding to the Lie group G, cf. IsGroupManifold.\n\nThis can be used to compute the adjoint representation of a Lie algebra. Note that this representation isn't generally faithful. Notably the adjoint representation of 𝔰𝔬(2) is trivial.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{AbstractDecoratorManifold, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G, q)\nlog_lie!(G, X, q)\n\nCompute the Lie group logarithm of the Lie group element q. It is equivalent to the logarithmic map defined by the CartanSchoutenMinus connection.\n\nGiven an element q mathcalG, compute the right inverse of the group exponential map exp_lie, that is, the element log q = X 𝔤 = T_e mathcalG, such that q = exp X\n\nnote: Note\nIn general, the group logarithm map is distinct from the Riemannian logarithm map log.For matrix Lie groups this is equal to the (matrix) logarithm:\n\nlog q = operatornameLog q = sum_n=1^ frac(-1)^n+1n (q - e)^n\n\nwhere e here is the Identity element, that is, 1 for numeric q or the identity matrix I_m for matrix q ℝ^m m.\n\nSince this function also depends on the group operation, make sure to implement either\n\n_log_lie(G, q) and _log_lie!(G, X, q) for the points not being the Identity\nthe trait version log_lie(::TraitList{<:IsGroupManifold}, G, e), log_lie(::TraitList{<:IsGroupManifold}, G, X, e) for own implementations of the identity case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.switch_direction-Tuple{ActionDirection, Manifolds.AbstractDirectionSwitchType}","page":"Group manifold","title":"Manifolds.switch_direction","text":"switch_direction(::ActionDirection, type::AbstractDirectionSwitchType = SimultaneousSwitch())\n\nReturns type of action between left and right, forward or backward, or both at the same type, depending on type, which is either of LeftRightSwitch, ForwardBackwardSwitch or SimultaneousSwitch.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.translate","text":"translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction()])\n\nTranslate group element q by p with the translation τ_p with the specified convention, either left forward (L_p), left backward (R_p), right backward (R_p) or right forward (L_p), defined as\n\nbeginaligned\nL_p q p circ q\nL_p q p^-1 circ q\nR_p q q circ p\nR_p q q circ p^-1\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate_diff-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.translate_diff","text":"translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())\n\nFor group elements p q mathcalG and tangent vector X T_q mathcalG, compute the action of the differential of the translation τ_p by p on X, with the specified left or right convention. The differential transports vectors:\n\n(mathrmdτ_p)_q T_q mathcalG T_τ_p q mathcalG\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.hat-Union{Tuple{O}, Tuple{ManifoldsBase.TraitList{IsGroupManifold{O}}, AbstractDecoratorManifold, Identity{O}, Any}} where O<:AbstractGroupOperation","page":"Group manifold","title":"ManifoldsBase.hat","text":"hat(M::AbstractDecoratorManifold{𝔽,O}, ::Identity{O}, Xⁱ) where {𝔽,O<:AbstractGroupOperation}\n\nGiven a basis e_i on the tangent space at a the Identity and tangent component vector X^i, compute the equivalent vector representation ``X=X^i e_i**, where Einstein summation notation is used:\n\n X^i X^i e_i\n\nFor array manifolds, this converts a vector representation of the tangent vector to an array representation. The vee map is the hat map's inverse.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.inverse_retract-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractDecoratorManifold, Any, Any, Manifolds.GroupLogarithmicInverseRetraction}","page":"Group manifold","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(\n G::AbstractDecoratorManifold,\n p,\n X,\n method::GroupLogarithmicInverseRetraction{<:ActionDirection},\n)\n\nCompute the inverse retraction using the group logarithm log_lie \"translated\" to any point on the manifold. With a group translation (translate) τ_p in a specified direction, the retraction is\n\noperatornameretr_p^-1 = (mathrmdτ_p)_e circ log circ τ_p^-1\n\nwhere log is the group logarithm (log_lie), and (mathrmdτ_p)_e is the action of the differential of translation τ_p evaluated at the identity element e (see translate_diff).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.retract-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractDecoratorManifold, Any, Any, Manifolds.GroupExponentialRetraction}","page":"Group manifold","title":"ManifoldsBase.retract","text":"retract(\n G::AbstractDecoratorManifold,\n p,\n X,\n method::GroupExponentialRetraction{<:ActionDirection},\n)\n\nCompute the retraction using the group exponential exp_lie \"translated\" to any point on the manifold. With a group translation (translate) τ_p in a specified direction, the retraction is\n\noperatornameretr_p = τ_p circ exp circ (mathrmdτ_p^-1)_p\n\nwhere exp is the group exponential (exp_lie), and (mathrmdτ_p^-1)_p is the action of the differential of inverse translation τ_p^-1 evaluated at p (see inverse_translate_diff).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.vee-Union{Tuple{O}, Tuple{ManifoldsBase.TraitList{IsGroupManifold{O}}, AbstractDecoratorManifold, Identity{O}, Any}} where O<:AbstractGroupOperation","page":"Group manifold","title":"ManifoldsBase.vee","text":"vee(M::AbstractManifold, p, X)\n\nGiven a basis e_i on the tangent space at a point p and tangent vector X, compute the vector components X^i, such that X = X^i e_i, where Einstein summation notation is used:\n\nvee X^i e_i X^i\n\nFor array manifolds, this converts an array representation of the tangent vector to a vector representation. The hat map is the vee map's inverse.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#GroupManifold","page":"Group manifold","title":"GroupManifold","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"As a concrete wrapper for manifolds (e.g. when the manifold per se is a group manifold but another group structure should be implemented), there is the GroupManifold","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/GroupManifold.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GroupManifold","page":"Group manifold","title":"Manifolds.GroupManifold","text":"GroupManifold{𝔽,M<:AbstractManifold{𝔽},O<:AbstractGroupOperation} <: AbstractDecoratorManifold{𝔽}\n\nDecorator for a smooth manifold that equips the manifold with a group operation, thus making it a Lie group. See IsGroupManifold for more details.\n\nGroup manifolds by default forward metric-related operations to the wrapped manifold.\n\nConstructor\n\nGroupManifold(manifold, op)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Generic-Operations","page":"Group manifold","title":"Generic Operations","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"For groups based on an addition operation or a group operation, several default implementations are provided.","category":"page"},{"location":"manifolds/group.html#Addition-Operation","page":"Group manifold","title":"Addition Operation","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/addition_operation.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AdditionOperation","page":"Group manifold","title":"Manifolds.AdditionOperation","text":"AdditionOperation <: AbstractGroupOperation\n\nGroup operation that consists of simple addition.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Multiplication-Operation","page":"Group manifold","title":"Multiplication Operation","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/multiplication_operation.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.MultiplicationOperation","page":"Group manifold","title":"Manifolds.MultiplicationOperation","text":"MultiplicationOperation <: AbstractGroupOperation\n\nGroup operation that consists of multiplication.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Circle-group","page":"Group manifold","title":"Circle group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/circle_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.CircleGroup","page":"Group manifold","title":"Manifolds.CircleGroup","text":"CircleGroup <: GroupManifold{Circle{ℂ},MultiplicationOperation}\n\nThe circle group is the complex circle (Circle(ℂ)) equipped with the group operation of complex multiplication (MultiplicationOperation).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RealCircleGroup","page":"Group manifold","title":"Manifolds.RealCircleGroup","text":"RealCircleGroup <: GroupManifold{Circle{ℝ},AdditionOperation}\n\nThe real circle group is the real circle (Circle(ℝ)) equipped with the group operation of addition (AdditionOperation).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#General-linear-group","page":"Group manifold","title":"General linear group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/general_linear.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GeneralLinear","page":"Group manifold","title":"Manifolds.GeneralLinear","text":"GeneralLinear{n,𝔽} <:\n AbstractDecoratorManifold{𝔽}\n\nThe general linear group, that is, the group of all invertible matrices in 𝔽^nn.\n\nThe default metric is the left-mathrmGL(n)-right-mathrmO(n)-invariant metric whose inner product is\n\nX_pY_p_p = p^-1X_pp^-1Y_p_mathrmF = X_e Y_e_mathrmF\n\nwhere X_p Y_p T_p mathrmGL(n 𝔽), X_e = p^-1X_p 𝔤𝔩(n) = T_e mathrmGL(n 𝔽) = 𝔽^nn is the corresponding vector in the Lie algebra, and _mathrmF denotes the Frobenius inner product.\n\nBy default, tangent vectors X_p are represented with their corresponding Lie algebra vectors X_e = p^-1X_p.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.exp-Tuple{GeneralLinear, Any, Any}","page":"Group manifold","title":"Base.exp","text":"exp(G::GeneralLinear, p, X)\n\nCompute the exponential map on the GeneralLinear group.\n\nThe exponential map is\n\nexp_p colon X p operatornameExp(X^mathrmH) operatornameExp(X - X^mathrmH)\n\nwhere operatornameExp() denotes the matrix exponential, and ^mathrmH is the conjugate transpose. [AndruchowLarotondaRechtVarela2014][MartinNeff2016]\n\n[AndruchowLarotondaRechtVarela2014]: Andruchow E., Larotonda G., Recht L., and Varela A.: “The left invariant metric in the general linear group”, Journal of Geometry and Physics 86, pp. 241-257, 2014. doi: 10.1016/j.geomphys.2014.08.009, arXiv: 1109.0520v1.\n\n[MartinNeff2016]: Martin, R. J. and Neff, P.: “Minimal geodesics on GL(n) for left-invariant, right-O(n)-invariant Riemannian metrics”, Journal of Geometric Mechanics 8(3), pp. 323-357, 2016. doi: 10.3934/jgm.2016010, arXiv: 1409.7849v2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.log-Tuple{GeneralLinear, Any, Any}","page":"Group manifold","title":"Base.log","text":"log(G::GeneralLinear, p, q)\n\nCompute the logarithmic map on the GeneralLinear(n) group.\n\nThe algorithm proceeds in two stages. First, the point r = p^-1 q is projected to the nearest element (under the Frobenius norm) of the direct product subgroup mathrmO(n) S^+, whose logarithmic map is exactly computed using the matrix logarithm. This initial tangent vector is then refined using the NLSolveInverseRetraction.\n\nFor GeneralLinear(n, ℂ), the logarithmic map is instead computed on the realified supergroup GeneralLinear(2n) and the resulting tangent vector is then complexified.\n\nNote that this implementation is experimental.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.rand-Tuple{GeneralLinear}","page":"Group manifold","title":"Base.rand","text":"Random.rand(G::GeneralLinear; vector_at=nothing, kwargs...)\n\nIf vector_at is nothing, return a random point on the GeneralLinear group G by using rand in the embedding.\n\nIf vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the GeneralLinear by using by using rand in the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Heisenberg-group","page":"Group manifold","title":"Heisenberg group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/heisenberg.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.HeisenbergGroup","page":"Group manifold","title":"Manifolds.HeisenbergGroup","text":"HeisenbergGroup{n} <: AbstractDecoratorManifold{ℝ}\n\nHeisenberg group HeisenbergGroup(n) is the group of (n+2) (n+2) matrices [BinzPods2008]\n\nbeginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\nwhere I_n is the nn unit matrix, mathbfa is a row vector of length n, mathbfb is a column vector of length n and c is a real number. The group operation is matrix multiplication.\n\nThe left-invariant metric on the manifold is used.\n\n[BinzPods2008]: E. Binz and S. Pods, The Geometry of Heisenberg Groups: With Applications in Signal Theory, Optics, Quantization, and Field Quantization. American Mathematical Soc., 2008.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.exp-Tuple{HeisenbergGroup, Any, Any}","page":"Group manifold","title":"Base.exp","text":"exp(M::HeisenbergGroup, p, X)\n\nExponential map on the HeisenbergGroup M with the left-invariant metric. The expression reads\n\nexp_beginbmatrix 1 mathbfa_p c_p \nmathbf0 I_n mathbfb_p \n0 mathbf0 1 endbmatrixleft(beginbmatrix 0 mathbfa_X c_X \nmathbf0 0_n mathbfb_X \n0 mathbf0 0 endbmatrixright) =\nbeginbmatrix 1 mathbfa_p + mathbfa_X c_p + c_X + mathbfa_Xmathbfb_X2 + mathbfa_pmathbfb_X \nmathbf0 I_n mathbfb_p + mathbfb_X \n0 mathbf0 1 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.log-Tuple{HeisenbergGroup, Any, Any}","page":"Group manifold","title":"Base.log","text":"log(G::HeisenbergGroup, p, q)\n\nCompute the logarithmic map on the HeisenbergGroup group. The formula reads\n\nlog_beginbmatrix 1 mathbfa_p c_p \nmathbf0 I_n mathbfb_p \n0 mathbf0 1 endbmatrixleft(beginbmatrix 1 mathbfa_q c_q \nmathbf0 I_n mathbfb_q \n0 mathbf0 1 endbmatrixright) =\nbeginbmatrix 0 mathbfa_q - mathbfa_p c_q - c_p + mathbfa_pmathbfb_p - mathbfa_qmathbfb_q - (mathbfa_q - mathbfa_p)(mathbfb_q - mathbfb_p) 2 \nmathbf0 0_n mathbfb_q - mathbfb_p \n0 mathbf0 0 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.rand-Tuple{HeisenbergGroup}","page":"Group manifold","title":"Base.rand","text":"Random.rand(M::HeisenbergGroup; vector_at = nothing, σ::Real=1.0)\n\nIf vector_at is nothing, return a random point on the HeisenbergGroup M by sampling elements of the first row and the last column from the normal distribution with mean 0 and standard deviation σ.\n\nIf vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the HeisenbergGroup by using a normal distribution with mean 0 and standard deviation σ.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{HeisenbergGroup, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(M::HeisenbergGroup, X)\n\nLie group exponential for the HeisenbergGroup M of the vector X. The formula reads\n\nexpleft(beginbmatrix 0 mathbfa c \nmathbf0 0_n mathbfb \n0 mathbf0 0 endbmatrixright) = beginbmatrix 1 mathbfa c + mathbfamathbfb2 \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{HeisenbergGroup, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(M::HeisenbergGroup, p)\n\nLie group logarithm for the HeisenbergGroup M of the point p. The formula reads\n\nlogleft(beginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrixright) =\nbeginbmatrix 0 mathbfa c - mathbfamathbfb2 \nmathbf0 0_n mathbfb \n0 mathbf0 0 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.get_coordinates-Tuple{HeisenbergGroup, Any, Any, DefaultOrthonormalBasis{ℝ, ManifoldsBase.TangentSpaceType}}","page":"Group manifold","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::HeisenbergGroup, p, X, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})\n\nGet coordinates of tangent vector X at point p from the HeisenbergGroup M. Given a matrix\n\nbeginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\nthe coordinates are concatenated vectors mathbfa, mathbfb, and number c.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.get_vector-Tuple{HeisenbergGroup, Any, Any, DefaultOrthonormalBasis{ℝ, ManifoldsBase.TangentSpaceType}}","page":"Group manifold","title":"ManifoldsBase.get_vector","text":"get_vector(M::HeisenbergGroup, p, Xⁱ, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})\n\nGet tangent vector with coordinates Xⁱ at point p from the HeisenbergGroup M. Given a vector of coordinates beginbmatrixmathbba mathbbb cendbmatrix the tangent vector is equal to\n\nbeginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.injectivity_radius-Tuple{HeisenbergGroup}","page":"Group manifold","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::HeisenbergGroup)\n\nReturn the injectivity radius on the HeisenbergGroup M, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Union{Tuple{n}, Tuple{HeisenbergGroup{n}, Any, Any}} where n","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::HeisenbergGroup{n}, p, X)\n\nProject a matrix X in the Euclidean embedding onto the Lie algebra of HeisenbergGroup M. Sets the diagonal elements to 0 and all non-diagonal elements except the first row and the last column to 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Union{Tuple{n}, Tuple{HeisenbergGroup{n}, Any}} where n","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::HeisenbergGroup{n}, p)\n\nProject a matrix p in the Euclidean embedding onto the HeisenbergGroup M. Sets the diagonal elements to 1 and all non-diagonal elements except the first row and the last column to 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#(Special)-Orthogonal-and-(Special)-Unitary-group","page":"Group manifold","title":"(Special) Orthogonal and (Special) Unitary group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Since the orthogonal, unitary and special orthogonal and special unitary groups share many common functions, these are also implemented on a common level.","category":"page"},{"location":"manifolds/group.html#Common-functions","page":"Group manifold","title":"Common functions","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/general_unitary_groups.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GeneralUnitaryMultiplicationGroup","page":"Group manifold","title":"Manifolds.GeneralUnitaryMultiplicationGroup","text":"GeneralUnitaryMultiplicationGroup{n,𝔽,M} = GroupManifold{𝔽,M,MultiplicationOperation}\n\nA generic type for Lie groups based on a unitary property and matrix multiplcation, see e.g. Orthogonal, SpecialOrthogonal, Unitary, and SpecialUnitary\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{Manifolds.GeneralUnitaryMultiplicationGroup{2, ℝ}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":" exp_lie(G::Orthogonal{2}, X)\n exp_lie(G::SpecialOrthogonal{2}, X)\n\nCompute the Lie group exponential map on the Orthogonal(2) or SpecialOrthogonal(2) group. Given X = beginpmatrix 0 -θ θ 0 endpmatrix, the group exponential is\n\nexp_e colon X beginpmatrix cos θ -sin θ sin θ cos θ endpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{Manifolds.GeneralUnitaryMultiplicationGroup{4, ℝ}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":" exp_lie(G::Orthogonal{4}, X)\n exp_lie(G::SpecialOrthogonal{4}, X)\n\nCompute the group exponential map on the Orthogonal(4) or the SpecialOrthogonal group. The algorithm used is a more numerically stable form of those proposed in [Gallier2002], [Andrica2013].\n\n[Gallier2002]: Gallier J.; Xu D.; Computing exponentials of skew-symmetric matrices and logarithms of orthogonal matrices. International Journal of Robotics and Automation (2002), 17(4), pp. 1-11. pdf.\n\n[Andrica2013]: Andrica D.; Rohan R.-A.; Computing the Rodrigues coefficients of the exponential map of the Lie groups of matrices. Balkan Journal of Geometry and Its Applications (2013), 18(2), pp. 1-2. pdf.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Orthogonal-group","page":"Group manifold","title":"Orthogonal group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/orthogonal.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.Orthogonal","page":"Group manifold","title":"Manifolds.Orthogonal","text":"Orthogonal{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,AbsoluteDeterminantOneMatrices}\n\nOrthogonal group mathrmO(n) represented by OrthogonalMatrices.\n\nConstructor\n\nOrthogonal(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Special-orthogonal-group","page":"Group manifold","title":"Special orthogonal group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_orthogonal.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialOrthogonal","page":"Group manifold","title":"Manifolds.SpecialOrthogonal","text":"SpecialOrthogonal{n} <: GroupManifold{ℝ,Rotations{n},MultiplicationOperation}\n\nSpecial orthogonal group mathrmSO(n) represented by rotation matrices, see Rotations.\n\nConstructor\n\nSpecialOrthogonal(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Special-unitary-group","page":"Group manifold","title":"Special unitary group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_unitary.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialUnitary","page":"Group manifold","title":"Manifolds.SpecialUnitary","text":"SpecialUnitary{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}}\n\nThe special unitary group mathrmSU(n) represented by unitary matrices of determinant +1.\n\nThe tangent spaces are of the form\n\nT_pmathrmSU(x) = bigl X in mathbb C^nn big X = pY text where Y = -Y^mathrmH bigr\n\nand we represent tangent vectors by just storing the SkewHermitianMatrices Y, or in other words we represent the tangent spaces employing the Lie algebra mathfraksu(n).\n\nConstructor\n\nSpecialUnitary(n)\n\nGenerate the Lie group of nn unitary matrices with determinant +1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{SpecialUnitary, Vararg{Any}}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(G::SpecialUnitary, p)\n\nProject p to the nearest point on the SpecialUnitary group G.\n\nGiven the singular value decomposition p = U S V^mathrmH, with the singular values sorted in descending order, the projection is\n\noperatornameproj_mathrmSU(n)(p) =\nUoperatornamediagleft11det(U V^mathrmH)right V^mathrmH\n\nThe diagonal matrix ensures that the determinant of the result is +1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Unitary-group","page":"Group manifold","title":"Unitary group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/unitary.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.Unitary","page":"Group manifold","title":"Manifolds.Unitary","text":" Unitary{n,𝔽} = GeneralUnitaryMultiplicationGroup{n,𝔽,AbsoluteDeterminantOneMatrices}\n\nThe group of unitary matrices mathrmU(n 𝔽), either complex (when 𝔽=ℂ) or quaternionic (when 𝔽=ℍ)\n\nThe group consists of all points p 𝔽^n n where p^mathrmHp = pp^mathrmH = I.\n\nThe tangent spaces are if the form\n\nT_pmathrmU(n) = bigl X in 𝔽^nn big X = pY text where Y = -Y^mathrmH bigr\n\nand we represent tangent vectors by just storing the SkewHermitianMatrices Y, or in other words we represent the tangent spaces employing the Lie algebra mathfraku(n 𝔽).\n\nQuaternionic unitary group is isomorphic to the compact symplectic group of the same dimension.\n\nConstructor\n\nUnitary(n, 𝔽::AbstractNumbers=ℂ)\n\nConstruct mathrmU(n 𝔽). See also Orthogonal(n) for the real-valued case.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{Unitary{2, ℂ}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::Unitary{2,ℂ}, X)\n\nCompute the group exponential map on the Unitary(2) group, which is\n\nexp_e colon X e^operatornametr(X) 2 left(cos θ I + fracsin θθ left(X - fracoperatornametr(X)2 Iright)right)\n\nwhere θ = frac12 sqrt4det(X) - operatornametr(X)^2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Power-group","page":"Group manifold","title":"Power group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/power_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.PowerGroup-Tuple{AbstractPowerManifold}","page":"Group manifold","title":"Manifolds.PowerGroup","text":"PowerGroup{𝔽,T} <: GroupManifold{𝔽,<:AbstractPowerManifold{𝔽,M,RPT},ProductOperation}\n\nDecorate a power manifold with a ProductOperation.\n\nConstituent manifold of the power manifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.\n\nConstructor\n\nPowerGroup(manifold::AbstractPowerManifold)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.PowerGroupNested","page":"Group manifold","title":"Manifolds.PowerGroupNested","text":"PowerGroupNested\n\nAlias to PowerGroup with NestedPowerRepresentation representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.PowerGroupNestedReplacing","page":"Group manifold","title":"Manifolds.PowerGroupNestedReplacing","text":"PowerGroupNestedReplacing\n\nAlias to PowerGroup with NestedReplacingPowerRepresentation representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Product-group","page":"Group manifold","title":"Product group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/product_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.ProductGroup-Union{Tuple{ProductManifold{𝔽}}, Tuple{𝔽}} where 𝔽","page":"Group manifold","title":"Manifolds.ProductGroup","text":"ProductGroup{𝔽,T} <: GroupManifold{𝔽,ProductManifold{T},ProductOperation}\n\nDecorate a product manifold with a ProductOperation.\n\nEach submanifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.\n\nConstructor\n\nProductGroup(manifold::ProductManifold)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.ProductOperation","page":"Group manifold","title":"Manifolds.ProductOperation","text":"ProductOperation <: AbstractGroupOperation\n\nDirect product group operation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Semidirect-product-group","page":"Group manifold","title":"Semidirect product group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/semidirect_product_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SemidirectProductGroup-Union{Tuple{𝔽}, Tuple{AbstractDecoratorManifold{𝔽}, AbstractDecoratorManifold{𝔽}, AbstractGroupAction}} where 𝔽","page":"Group manifold","title":"Manifolds.SemidirectProductGroup","text":"SemidirectProductGroup(N::GroupManifold, H::GroupManifold, A::AbstractGroupAction)\n\nA group that is the semidirect product of a normal group mathcalN and a subgroup mathcalH, written mathcalG = mathcalN _θ mathcalH, where θ mathcalH mathcalN mathcalN is an automorphism action of mathcalH on mathcalN. The group mathcalG has the composition rule\n\ng circ g = (n h) circ (n h) = (n circ θ_h(n) h circ h)\n\nand the inverse\n\ng^-1 = (n h)^-1 = (θ_h^-1(n^-1) h^-1)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.SemidirectProductOperation","page":"Group manifold","title":"Manifolds.SemidirectProductOperation","text":"SemidirectProductOperation(action::AbstractGroupAction)\n\nGroup operation of a semidirect product group. The operation consists of the operation opN on a normal subgroup N, the operation opH on a subgroup H, and an automorphism action of elements of H on N. Only the action is stored.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.identity_element-Tuple{SemidirectProductGroup}","page":"Group manifold","title":"Manifolds.identity_element","text":"identity_element(G::SemidirectProductGroup)\n\nGet the identity element of SemidirectProductGroup G. Uses ArrayPartition from RecursiveArrayTools.jl to represent the point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate_diff-Tuple{SemidirectProductGroup, Any, Any, Any, LeftForwardAction}","page":"Group manifold","title":"Manifolds.translate_diff","text":"translate_diff(G::SemidirectProductGroup, p, q, X, conX::LeftForwardAction)\n\nPerform differential of the left translation on the semidirect product group G.\n\nSince the left translation is defined as (cf. SemidirectProductGroup):\n\nL_(n h) (n h) = ( L_n θ_h(n) L_h h)\n\nthen its differential can be computed as\n\nmathrmdL_(n h)(X_n X_h) = ( mathrmdL_n (mathrmdθ_h(X_n)) mathrmdL_h X_h)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Special-Euclidean-group","page":"Group manifold","title":"Special Euclidean group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_euclidean.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialEuclidean","page":"Group manifold","title":"Manifolds.SpecialEuclidean","text":"SpecialEuclidean(n)\n\nSpecial Euclidean group mathrmSE(n), the group of rigid motions.\n\nmathrmSE(n) is the semidirect product of the TranslationGroup on ℝ^n and SpecialOrthogonal(n)\n\nmathrmSE(n) mathrmT(n) _θ mathrmSO(n)\n\nwhere θ is the canonical action of mathrmSO(n) on mathrmT(n) by vector rotation.\n\nThis constructor is equivalent to calling\n\nTn = TranslationGroup(n)\nSOn = SpecialOrthogonal(n)\nSemidirectProductGroup(Tn, SOn, RotationAction(Tn, SOn))\n\nPoints on mathrmSE(n) may be represented as points on the underlying product manifold mathrmT(n) mathrmSO(n). For group-specific functions, they may also be represented as affine matrices with size (n + 1, n + 1) (see affine_matrix), for which the group operation is MultiplicationOperation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.SpecialEuclideanInGeneralLinear","page":"Group manifold","title":"Manifolds.SpecialEuclideanInGeneralLinear","text":"SpecialEuclideanInGeneralLinear\n\nAn explicit isometric and homomorphic embedding of mathrmSE(n) in mathrmGL(n+1) and 𝔰𝔢(n) in 𝔤𝔩(n+1). Note that this is not a transparently isometric embedding.\n\nConstructor\n\nSpecialEuclideanInGeneralLinear(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.adjoint_action-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}, LeftForwardAction}}}, Any, TFVector{<:Any, VeeOrthogonalBasis{ℝ}}}","page":"Group manifold","title":"Manifolds.adjoint_action","text":"adjoint_action(::SpecialEuclidean{3}, p, fX::TFVector{<:Any,VeeOrthogonalBasis{ℝ}})\n\nAdjoint action of the SpecialEuclidean group on the vector with coefficients fX tangent at point p.\n\nThe formula for the coefficients reads t(Rω) + Rr for the translation part and Rω for the rotation part, where t is the translation part of p, R is the rotation matrix part of p, r is the translation part of fX and ω is the rotation part of fX, is the cross product and is the matrix product.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.affine_matrix-Union{Tuple{n}, Tuple{SpecialEuclidean{n}, Any}} where n","page":"Group manifold","title":"Manifolds.affine_matrix","text":"affine_matrix(G::SpecialEuclidean, p) -> AbstractMatrix\n\nRepresent the point p mathrmSE(n) as an affine matrix. For p = (t R) mathrmSE(n), where t mathrmT(n) R mathrmSO(n), the affine representation is the n + 1 n + 1 matrix\n\nbeginpmatrix\nR t \n0^mathrmT 1\nendpmatrix\n\nThis function embeds mathrmSE(n) in the general linear group mathrmGL(n+1). It is an isometric embedding and group homomorphism [RicoMartinez1988].\n\nSee also screw_matrix for matrix representations of the Lie algebra.\n\n[RicoMartinez1988]: Rico Martinez, J. M., “Representations of the Euclidean group and its applications to the kinematics of spatial chains,” PhD Thesis, University of Florida, 1988.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::SpecialEuclidean{2}, X)\n\nCompute the group exponential of X = (b Ω) 𝔰𝔢(2), where b 𝔱(2) and Ω 𝔰𝔬(2):\n\nexp X = (t R) = (U(θ) b exp Ω)\n\nwhere t mathrmT(2), R = exp Ω is the group exponential on mathrmSO(2),\n\nU(θ) = fracsin θθ I_2 + frac1 - cos θθ^2 Ω\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::SpecialEuclidean{3}, X)\n\nCompute the group exponential of X = (b Ω) 𝔰𝔢(3), where b 𝔱(3) and Ω 𝔰𝔬(3):\n\nexp X = (t R) = (U(θ) b exp Ω)\n\nwhere t mathrmT(3), R = exp Ω is the group exponential on mathrmSO(3),\n\nU(θ) = I_3 + frac1 - cos θθ^2 Ω + fracθ - sin θθ^3 Ω^2\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{SpecialEuclidean, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::SpecialEuclidean{n}, X)\n\nCompute the group exponential of X = (b Ω) 𝔰𝔢(n), where b 𝔱(n) and Ω 𝔰𝔬(n):\n\nexp X = (t R)\n\nwhere t mathrmT(n) and R = exp Ω is the group exponential on mathrmSO(n).\n\nIn the screw_matrix representation, the group exponential is the matrix exponential (see exp_lie).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.lie_bracket-Tuple{SpecialEuclidean, ProductRepr, ProductRepr}","page":"Group manifold","title":"Manifolds.lie_bracket","text":"lie_bracket(G::SpecialEuclidean, X::ProductRepr, Y::ProductRepr)\nlie_bracket(G::SpecialEuclidean, X::ArrayPartition, Y::ArrayPartition)\nlie_bracket(G::SpecialEuclidean, X::AbstractMatrix, Y::AbstractMatrix)\n\nCalculate the Lie bracket between elements X and Y of the special Euclidean Lie algebra. For the matrix representation (which can be obtained using screw_matrix) the formula is X Y = XY-YX, while in the ProductRepr representation the formula reads X Y = (t_1 R_1) (t_2 R_2) = (R_1 t_2 - R_2 t_1 R_1 R_2 - R_2 R_1).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G::SpecialEuclidean{2}, p)\n\nCompute the group logarithm of p = (t R) mathrmSE(2), where t mathrmT(2) and R mathrmSO(2):\n\nlog p = (b Ω) = (U(θ)^-1 t log R)\n\nwhere b 𝔱(2), Ω = log R 𝔰𝔬(2) is the group logarithm on mathrmSO(2),\n\nU(θ) = fracsin θθ I_2 + frac1 - cos θθ^2 Ω\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G::SpecialEuclidean{3}, p)\n\nCompute the group logarithm of p = (t R) mathrmSE(3), where t mathrmT(3) and R mathrmSO(3):\n\nlog p = (b Ω) = (U(θ)^-1 t log R)\n\nwhere b 𝔱(3), Ω = log R 𝔰𝔬(3) is the group logarithm on mathrmSO(3),\n\nU(θ) = I_3 + frac1 - cos θθ^2 Ω + fracθ - sin θθ^3 Ω^2\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{SpecialEuclidean, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G::SpecialEuclidean{n}, p) where {n}\n\nCompute the group logarithm of p = (t R) mathrmSE(n), where t mathrmT(n) and R mathrmSO(n):\n\nlog p = (b Ω)\n\nwhere b 𝔱(n) and Ω = log R 𝔰𝔬(n) is the group logarithm on mathrmSO(n).\n\nIn the affine_matrix representation, the group logarithm is the matrix logarithm (see log_lie):\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.screw_matrix-Union{Tuple{n}, Tuple{SpecialEuclidean{n}, Any}} where n","page":"Group manifold","title":"Manifolds.screw_matrix","text":"screw_matrix(G::SpecialEuclidean, X) -> AbstractMatrix\n\nRepresent the Lie algebra element X 𝔰𝔢(n) = T_e mathrmSE(n) as a screw matrix. For X = (b Ω) 𝔰𝔢(n), where Ω 𝔰𝔬(n) = T_e mathrmSO(n), the screw representation is the n + 1 n + 1 matrix\n\nbeginpmatrix\nΩ b \n0^mathrmT 0\nendpmatrix\n\nThis function embeds 𝔰𝔢(n) in the general linear Lie algebra 𝔤𝔩(n+1) but it's not a homomorphic embedding (see SpecialEuclideanInGeneralLinear for a homomorphic one).\n\nSee also affine_matrix for matrix representations of the Lie group.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate_diff-Tuple{SpecialEuclidean, Any, Any, Any, RightBackwardAction}","page":"Group manifold","title":"Manifolds.translate_diff","text":"translate_diff(G::SpecialEuclidean, p, q, X, ::RightBackwardAction)\n\nDifferential of the right action of the SpecialEuclidean group on itself. The formula for the rotation part is the differential of the right rotation action, while the formula for the translation part reads\n\nR_qX_Rt_p + X_t\n\nwhere R_q is the rotation part of q, X_R is the rotation part of X, t_p is the translation part of p and X_t is the translation part of X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.embed-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any, Any}","page":"Group manifold","title":"ManifoldsBase.embed","text":"embed(M::SpecialEuclideanInGeneralLinear, p, X)\n\nEmbed the tangent vector X at point p on SpecialEuclidean in the GeneralLinear group. Point p can use any representation valid for SpecialEuclidean. The embedding is similar from the one defined by screw_matrix but the translation part is multiplied by inverse of the rotation part.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.embed-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any}","page":"Group manifold","title":"ManifoldsBase.embed","text":"embed(M::SpecialEuclideanInGeneralLinear, p)\n\nEmbed the point p on SpecialEuclidean in the GeneralLinear group. The embedding is calculated using affine_matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::SpecialEuclideanInGeneralLinear, p, X)\n\nProject tangent vector X at point p in GeneralLinear to the SpecialEuclidean Lie algebra. This reverses the transformation performed by embed\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::SpecialEuclideanInGeneralLinear, p)\n\nProject point p in GeneralLinear to the SpecialEuclidean group. This is performed by extracting the rotation and translation part as in affine_matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Special-linear-group","page":"Group manifold","title":"Special linear group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_linear.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialLinear","page":"Group manifold","title":"Manifolds.SpecialLinear","text":"SpecialLinear{n,𝔽} <: AbstractDecoratorManifold\n\nThe special linear group mathrmSL(n𝔽) that is, the group of all invertible matrices with unit determinant in 𝔽^nn.\n\nThe Lie algebra 𝔰𝔩(n 𝔽) = T_e mathrmSL(n𝔽) is the set of all matrices in 𝔽^nn with trace of zero. By default, tangent vectors X_p T_p mathrmSL(n𝔽) for p mathrmSL(n𝔽) are represented with their corresponding Lie algebra vector X_e = p^-1X_p 𝔰𝔩(n 𝔽).\n\nThe default metric is the same left-mathrmGL(n)-right-mathrmO(n)-invariant metric used for GeneralLinear(n, 𝔽). The resulting geodesic on mathrmGL(n𝔽) emanating from an element of mathrmSL(n𝔽) in the direction of an element of 𝔰𝔩(n 𝔽) is a closed subgroup of mathrmSL(n𝔽). As a result, most metric functions forward to GeneralLinear.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{SpecialLinear, Any, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(G::SpecialLinear, p, X)\n\nOrthogonally project X 𝔽^n n onto the tangent space of p to the SpecialLinear G = mathrmSL(n 𝔽). The formula reads\n\noperatornameproj_p\n = (mathrmdL_p)_e operatornameproj_𝔰𝔩(n 𝔽) (mathrmdL_p^-1)_p\n colon X X - fracoperatornametr(X)n I\n\nwhere the last expression uses the tangent space representation as the Lie algebra.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{SpecialLinear, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(G::SpecialLinear, p)\n\nProject p mathrmGL(n 𝔽) to the SpecialLinear group G=mathrmSL(n 𝔽).\n\nGiven the singular value decomposition of p, written p = U S V^mathrmH, the formula for the projection is\n\noperatornameproj_mathrmSL(n 𝔽)(p) = U S D V^mathrmH\n\nwhere\n\nD_ij = δ_ij begincases\n 1 text if i n \n det(p)^-1 text if i = n\nendcases\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Translation-group","page":"Group manifold","title":"Translation group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/translation_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.TranslationGroup","page":"Group manifold","title":"Manifolds.TranslationGroup","text":"TranslationGroup{T<:Tuple,𝔽} <: GroupManifold{Euclidean{T,𝔽},AdditionOperation}\n\nTranslation group mathrmT(n) represented by translation arrays.\n\nConstructor\n\nTranslationGroup(n₁,...,nᵢ; field = 𝔽)\n\nGenerate the translation group on 𝔽^n₁nᵢ = Euclidean(n₁,...,nᵢ; field = 𝔽), which is isomorphic to the group itself.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Group-actions","page":"Group manifold","title":"Group actions","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Group actions represent actions of a given group on a specified manifold. The following operations are available:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"apply: performs given action of an element of the group on an object of compatible type.\napply_diff: differential of apply with respect to the object it acts upon.\ndirection: tells whether a given action is LeftForwardAction, RightForwardAction, LeftBackwardAction or RightBackwardAction.\ninverse_apply: performs given action of the inverse of an element of the group on an object of compatible type. By default inverts the element and calls apply but it may be have a faster implementation for some actions.\ninverse_apply_diff: counterpart of apply_diff for inverse_apply.\noptimal_alignment: determine the element of a group that, when it acts upon a point, produces the element closest to another given point in the metric of the G-manifold.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Furthermore, group operation action features the following:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"translate: an operation that performs either left (LeftForwardAction) or right (RightBackwardAction) translation, or actions by inverses of elements (RightForwardAction and LeftBackwardAction). This is by default performed by calling compose with appropriate order of arguments. This function is separated from compose mostly to easily represent its differential, translate_diff.\ntranslate_diff: differential of translate with respect to the point being translated.\nadjoint_action: adjoint action of a given element of a Lie group on an element of its Lie algebra.\nlie_bracket: Lie bracket of two vectors from a Lie algebra corresponding to a given group.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"The following group actions are available:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Group operation action GroupOperationAction that describes action of a group on itself.\nRotationAction, that is action of SpecialOrthogonal group on different manifolds.\nTranslationAction, which is the action of TranslationGroup group on different manifolds.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/group_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AbstractGroupAction","page":"Group manifold","title":"Manifolds.AbstractGroupAction","text":"AbstractGroupAction\n\nAn abstract group action on a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.adjoint_apply_diff_group-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.adjoint_apply_diff_group","text":"adjoint_apply_diff_group(A::AbstractGroupAction, a, X, p)\n\nPullback with respect to group element of group action A.\n\n(mathrmdτ^p*) T_τ_a p mathcal M T_a mathcal G\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply!-Tuple{AbstractGroupAction{LeftForwardAction}, Any, Any, Any}","page":"Group manifold","title":"Manifolds.apply!","text":"apply!(A::AbstractGroupAction, q, a, p)\n\nApply action a to the point p with the rule specified by A. The result is saved in q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply-Tuple{AbstractGroupAction, Any, Any}","page":"Group manifold","title":"Manifolds.apply","text":"apply(A::AbstractGroupAction, a, p)\n\nApply action a to the point p using map τ_a, specified by A. Unless otherwise specified, the right action is defined in terms of the left action:\n\nmathrmR_a = mathrmL_a^-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply_diff-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.apply_diff","text":"apply_diff(A::AbstractGroupAction, a, p, X)\n\nFor point p mathcal M and tangent vector X T_p mathcal M, compute the action on X of the differential of the action of a mathcalG, specified by rule A. Written as (mathrmdτ_a)_p, with the specified left or right convention, the differential transports vectors\n\n(mathrmdτ_a)_p T_p mathcal M T_τ_a p mathcal M\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply_diff_group-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.apply_diff_group","text":"apply_diff_group(A::AbstractGroupAction, a, X, p)\n\nCompute the value of differential of action AbstractGroupAction A on vector X, where element a is acting on p, with respect to the group element.\n\nLet mathcal G be the group acting on manifold mathcal M by the action A. The action is of element g mathcal G on a point p mathcal M. The differential transforms vector X from the tangent space at a ∈ \\mathcal G, X T_a mathcal G into a tangent space of the manifold mathcal M. When action on element p is written as mathrmdτ^p, with the specified left or right convention, the differential transforms vectors\n\n(mathrmdτ^p) T_a mathcal G T_τ_a p mathcal M\n\nSee also\n\napply, apply_diff\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.base_group-Tuple{AbstractGroupAction}","page":"Group manifold","title":"Manifolds.base_group","text":"base_group(A::AbstractGroupAction)\n\nThe group that acts in action A.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.center_of_orbit","page":"Group manifold","title":"Manifolds.center_of_orbit","text":"center_of_orbit(\n A::AbstractGroupAction,\n pts,\n p,\n mean_method::AbstractEstimationMethod = GradientDescentEstimation(),\n)\n\nCalculate an action element a of action A that is the mean element of the orbit of p with respect to given set of points pts. The mean is calculated using the method mean_method.\n\nThe orbit of p with respect to the action of a group mathcalG is the set\n\nO = τ_a p a mathcalG \n\nThis function is useful for computing means on quotients of manifolds by a Lie group action.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/group.html#Manifolds.direction-Union{Tuple{AbstractGroupAction{AD}}, Tuple{AD}} where AD","page":"Group manifold","title":"Manifolds.direction","text":"direction(::AbstractGroupAction{AD}) -> AD\n\nGet the direction of the action\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.group_manifold-Tuple{AbstractGroupAction}","page":"Group manifold","title":"Manifolds.group_manifold","text":"group_manifold(A::AbstractGroupAction)\n\nThe manifold the action A acts upon.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_apply!-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.inverse_apply!","text":"inverse_apply!(A::AbstractGroupAction, q, a, p)\n\nApply inverse of action a to the point p with the rule specified by A. The result is saved in q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_apply-Tuple{AbstractGroupAction, Any, Any}","page":"Group manifold","title":"Manifolds.inverse_apply","text":"inverse_apply(A::AbstractGroupAction, a, p)\n\nApply inverse of action a to the point p. The action is specified by A.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_apply_diff-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.inverse_apply_diff","text":"inverse_apply_diff(A::AbstractGroupAction, a, p, X)\n\nFor group point p mathcal M and tangent vector X T_p mathcal M, compute the action on X of the differential of the inverse action of a mathcalG, specified by rule A. Written as (mathrmdτ_a^-1)_p, with the specified left or right convention, the differential transports vectors\n\n(mathrmdτ_a^-1)_p T_p mathcal M T_τ_a^-1 p mathcal M\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.optimal_alignment!-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.optimal_alignment!","text":"optimal_alignment!(A::AbstractGroupAction, x, p, q)\n\nCalculate an action element of action A that acts upon p to produce the element closest to q. The result is written to x.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.optimal_alignment-Tuple{AbstractGroupAction, Any, Any}","page":"Group manifold","title":"Manifolds.optimal_alignment","text":"optimal_alignment(A::AbstractGroupAction, p, q)\n\nCalculate an action element a of action A that acts upon p to produce the element closest to q in the metric of the G-manifold:\n\nargmin_a mathcalG d_mathcal M(τ_a p q)\n\nwhere mathcalG is the group that acts on the G-manifold mathcal M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Group-operation-action","page":"Group manifold","title":"Group operation action","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/group_operation_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GroupOperationAction","page":"Group manifold","title":"Manifolds.GroupOperationAction","text":"GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirection = LeftForwardAction())\n\nAction of a group upon itself via left or right translation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Rotation-action","page":"Group manifold","title":"Rotation action","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/rotation_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.ColumnwiseMultiplicationAction","page":"Group manifold","title":"Manifolds.ColumnwiseMultiplicationAction","text":"ColumnwiseMultiplicationAction{\n TM<:AbstractManifold,\n TO<:GeneralUnitaryMultiplicationGroup,\n TAD<:ActionDirection,\n} <: AbstractGroupAction{TAD}\n\nAction of the (special) unitary or orthogonal group GeneralUnitaryMultiplicationGroup of type On columns of points on a matrix manifold M.\n\nConstructor\n\nColumnwiseMultiplicationAction(\n M::AbstractManifold,\n On::GeneralUnitaryMultiplicationGroup,\n AD::ActionDirection = LeftForwardAction(),\n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RotationAction","page":"Group manifold","title":"Manifolds.RotationAction","text":"RotationAction(\n M::AbstractManifold,\n SOn::SpecialOrthogonal,\n AD::ActionDirection = LeftForwardAction(),\n)\n\nSpace of actions of the SpecialOrthogonal group mathrmSO(n) on a Euclidean-like manifold M of dimension n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RotationAroundAxisAction","page":"Group manifold","title":"Manifolds.RotationAroundAxisAction","text":"RotationAroundAxisAction(axis::AbstractVector)\n\nSpace of actions of the circle group RealCircleGroup on ℝ^3 around given axis.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RowwiseMultiplicationAction","page":"Group manifold","title":"Manifolds.RowwiseMultiplicationAction","text":"RowwiseMultiplicationAction{\n TM<:AbstractManifold,\n TO<:GeneralUnitaryMultiplicationGroup,\n TAD<:ActionDirection,\n} <: AbstractGroupAction{TAD}\n\nAction of the (special) unitary or orthogonal group GeneralUnitaryMultiplicationGroup of type On columns of points on a matrix manifold M.\n\nConstructor\n\nRowwiseMultiplicationAction(\n M::AbstractManifold,\n On::GeneralUnitaryMultiplicationGroup,\n AD::ActionDirection = LeftForwardAction(),\n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.apply-Tuple{Manifolds.RotationAroundAxisAction, Any, Any}","page":"Group manifold","title":"Manifolds.apply","text":"apply(A::RotationAroundAxisAction, θ, p)\n\nRotate point p from Euclidean(3) manifold around axis A.axis by angle θ. The formula reads\n\np_rot = (cos(θ))p + (kp) sin(θ) + k (kp) (1-cos(θ))\n\nwhere k is the vector A.axis and ⋅ is the dot product.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.optimal_alignment-Tuple{Manifolds.ColumnwiseMultiplicationAction{TM, TO, LeftForwardAction} where {TM<:AbstractManifold, TO<:Manifolds.GeneralUnitaryMultiplicationGroup}, Any, Any}","page":"Group manifold","title":"Manifolds.optimal_alignment","text":"optimal_alignment(A::LeftColumnwiseMultiplicationAction, p, q)\n\nCompute optimal alignment for the left ColumnwiseMultiplicationAction, i.e. the group element O^* that, when it acts on p, returns the point closest to q. Details of computation are described in Section 2.2.1 of [Srivastava2016].\n\nThe formula reads\n\nO^* = begincases\nUV^T textif operatornamedet(p q^mathrmT)\nU K V^mathrmT textotherwise\nendcases\n\nwhere U Sigma V^mathrmT is the SVD decomposition of p q^mathrmT and K is the unit diagonal matrix with the last element on the diagonal replaced with -1.\n\nReferences\n\n[Srivastava2016]: A. Srivastava and E. P. Klassen, Functional and Shape Data Analysis. Springer New York, 2016. ISBN: 978-1-4939-4018-9. doi: 10.1007/978-1-4939-4020-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Translation-action","page":"Group manifold","title":"Translation action","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/translation_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.TranslationAction","page":"Group manifold","title":"Manifolds.TranslationAction","text":"TranslationAction(\n M::AbstractManifold,\n Rn::TranslationGroup,\n AD::ActionDirection = LeftForwardAction(),\n)\n\nSpace of actions of the TranslationGroup mathrmT(n) on a Euclidean-like manifold M.\n\nThe left and right actions are equivalent.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Metrics-on-groups","page":"Group manifold","title":"Metrics on groups","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Lie groups by default typically forward all metric-related operations like exponential or logarithmic map to the underlying manifold, for example SpecialOrthogonal uses methods for Rotations (which is, incidentally, bi-invariant), or SpecialEuclidean uses product metric of the translation and rotation parts (which is not invariant under group operation).","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"It is, however, possible to change the metric used by a group by wrapping it in a MetricManifold decorator.","category":"page"},{"location":"manifolds/group.html#Invariant-metrics","page":"Group manifold","title":"Invariant metrics","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/metric.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.LeftInvariantMetric","page":"Group manifold","title":"Manifolds.LeftInvariantMetric","text":"LeftInvariantMetric <: AbstractMetric\n\nAn AbstractMetric that changes the metric of a Lie group to the left-invariant metric obtained by left-translations to the identity. Adds the HasLeftInvariantMetric trait.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RightInvariantMetric","page":"Group manifold","title":"Manifolds.RightInvariantMetric","text":"RightInvariantMetric <: AbstractMetric\n\nAn AbstractMetric that changes the metric of a Lie group to the right-invariant metric obtained by right-translations to the identity. Adds the HasRightInvariantMetric trait.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.direction-Tuple{AbstractDecoratorManifold}","page":"Group manifold","title":"Manifolds.direction","text":"direction(::AbstractDecoratorManifold) -> AD\n\nGet the direction of the action a certain Lie group with its implicit metric has\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.has_approx_invariant_metric-Tuple{AbstractDecoratorManifold, Any, Any, Any, Any, ActionDirection}","page":"Group manifold","title":"Manifolds.has_approx_invariant_metric","text":"has_approx_invariant_metric(\n G::AbstractDecoratorManifold,\n p,\n X,\n Y,\n qs::AbstractVector,\n conv::ActionDirection = LeftForwardAction();\n kwargs...,\n) -> Bool\n\nCheck whether the metric on the group mathcalG is (approximately) invariant using a set of predefined points. Namely, for p mathcalG, XY T_p mathcalG, a metric g, and a translation map τ_q in the specified direction, check for each q mathcalG that the following condition holds:\n\ng_p(X Y) g_τ_q p((mathrmdτ_q)_p X (mathrmdτ_q)_p Y)\n\nThis is necessary but not sufficient for invariance.\n\nOptionally, kwargs passed to isapprox may be provided.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Cartan-Schouten-connections","page":"Group manifold","title":"Cartan-Schouten connections","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/connections.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AbstractCartanSchoutenConnection","page":"Group manifold","title":"Manifolds.AbstractCartanSchoutenConnection","text":"AbstractCartanSchoutenConnection\n\nAbstract type for Cartan-Schouten connections, that is connections whose geodesics going through group identity are one-parameter subgroups. See[Pennec2020] for details.\n\n[Pennec2020]: X. Pennec and M. Lorenzi, “5 - Beyond Riemannian geometry: The affine connection setting for transformation groups,” in Riemannian Geometric Statistics in Medical Image Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 169–229. doi: 10.1016/B978-0-12-814725-2.00012-1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.CartanSchoutenMinus","page":"Group manifold","title":"Manifolds.CartanSchoutenMinus","text":"CartanSchoutenMinus\n\nThe unique Cartan-Schouten connection such that all left-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.CartanSchoutenPlus","page":"Group manifold","title":"Manifolds.CartanSchoutenPlus","text":"CartanSchoutenPlus\n\nThe unique Cartan-Schouten connection such that all right-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.CartanSchoutenZero","page":"Group manifold","title":"Manifolds.CartanSchoutenZero","text":"CartanSchoutenZero\n\nThe unique torsion-free Cartan-Schouten connection. It is biinvariant with respect to the group operation.\n\nIf the metric on the underlying manifold is bi-invariant then it is equivalent to the Levi-Civita connection of that metric.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.exp-Union{Tuple{𝔽}, Tuple{ConnectionManifold{𝔽, <:AbstractDecoratorManifold{𝔽}, <:AbstractCartanSchoutenConnection}, Any, Any}} where 𝔽","page":"Group manifold","title":"Base.exp","text":"exp(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, X) where {𝔽}\n\nCompute the exponential map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.log-Union{Tuple{𝔽}, Tuple{ConnectionManifold{𝔽, <:AbstractDecoratorManifold{𝔽}, <:AbstractCartanSchoutenConnection}, Any, Any}} where 𝔽","page":"Group manifold","title":"Base.log","text":"log(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, q) where {𝔽}\n\nCompute the logarithmic map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_direction-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenZero} where {𝔽, M}, Identity, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::CartanSchoutenZeroGroup, ::Identity, X, d)\n\nTransport tangent vector X at identity on the group manifold with the CartanSchoutenZero connection in the direction d. See [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_to-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenMinus} where {𝔽, M}, Any, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::CartanSchoutenMinusGroup, p, X, q)\n\nTransport tangent vector X at point p on the group manifold M with the CartanSchoutenMinus connection to point q. See [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_to-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenPlus} where {𝔽, M}, Any, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_to","text":"vector_transport_to(M::CartanSchoutenPlusGroup, p, X, q)\n\nTransport tangent vector X at point p on the group manifold M with the CartanSchoutenPlus connection to point q. See [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_to-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenZero} where {𝔽, M}, Identity, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::CartanSchoutenZeroGroup, p::Identity, X, q)\n\nTransport vector X at identity of group M equipped with the CartanSchoutenZero connection to point q using parallel transport.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Metric-manifold","page":"Metric manifold","title":"Metric manifold","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"A Riemannian manifold always consists of a topological manifold together with a smoothly varying metric g.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"However, often there is an implicitly assumed (default) metric, like the usual inner product on Euclidean space. This decorator takes this into account. It is not necessary to use this decorator if you implement just one (or the first) metric. If you later introduce a second, the old (first) metric can be used with the (non MetricManifold) AbstractManifold, i.e. without an explicitly stated metric.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"This manifold decorator serves two purposes:","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"to implement different metrics (e.g. in closed form) for one AbstractManifold\nto provide a way to compute geodesics on manifolds, where this AbstractMetric does not yield closed formula.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Pages = [\"metric.md\"]\nDepth = 2","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Note that a metric manifold is has a IsConnectionManifold trait referring to the LeviCivitaConnection of the metric g, and thus a large part of metric manifold's functionality relies on this.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Let's first look at the provided types.","category":"page"},{"location":"manifolds/metric.html#Types","page":"Metric manifold","title":"Types","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/MetricManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/metric.html#Manifolds.IsDefaultMetric","page":"Metric manifold","title":"Manifolds.IsDefaultMetric","text":"IsDefaultMetric{G<:AbstractMetric}\n\nSpecify that a certain AbstractMetric is the default metric for a manifold. This way the corresponding MetricManifold falls back to the default methods of the manifold it decorates.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/metric.html#Manifolds.IsMetricManifold","page":"Metric manifold","title":"Manifolds.IsMetricManifold","text":"IsMetricManifold <: AbstractTrait\n\nSpecify that a certain decorated Manifold is a metric manifold in the sence that it provides explicit metric properties, extending/changing the default metric properties of a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/metric.html#Manifolds.MetricManifold","page":"Metric manifold","title":"Manifolds.MetricManifold","text":"MetricManifold{𝔽,M<:AbstractManifold{𝔽},G<:AbstractMetric} <: AbstractDecoratorManifold{𝔽}\n\nEquip a AbstractManifold explicitly with an AbstractMetric G.\n\nFor a Metric AbstractManifold, by default, assumes, that you implement the linear form from local_metric in order to evaluate the exponential map.\n\nIf the corresponding AbstractMetric G yields closed form formulae for e.g. the exponential map and this is implemented directly (without solving the ode), you can of course still implement that directly.\n\nConstructor\n\nMetricManifold(M, G)\n\nGenerate the AbstractManifold M as a manifold with the AbstractMetric G.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/metric.html#Implement-Different-Metrics-on-the-same-Manifold","page":"Metric manifold","title":"Implement Different Metrics on the same Manifold","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"In order to distinguish different metrics on one manifold, one can introduce two AbstractMetrics and use this type to dispatch on the metric, see SymmetricPositiveDefinite. To avoid overhead, one AbstractMetric can then be marked as being the default, i.e. the one that is used, when no MetricManifold decorator is present. This avoids reimplementation of the first existing metric, access to the metric-dependent functions that were implemented using the undecorated manifold, as well as the transparent fallback of the corresponding MetricManifold with default metric to the undecorated implementations. This does not cause any runtime overhead. Introducing a default AbstractMetric serves a better readability of the code when working with different metrics.","category":"page"},{"location":"manifolds/metric.html#Implementation-of-Metrics","page":"Metric manifold","title":"Implementation of Metrics","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"For the case that a local_metric is implemented as a bilinear form that is positive definite, the following further functions are provided, unless the corresponding AbstractMetric is marked as default – then the fallbacks mentioned in the last section are used for e.g. the exponential map.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/MetricManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/metric.html#Base.log-Tuple{MetricManifold, Vararg{Any}}","page":"Metric manifold","title":"Base.log","text":"log(N::MetricManifold{M,G}, p, q)\n\nCopute the logarithmic map on the AbstractManifold M equipped with the AbstractMetric G.\n\nIf the metric was declared the default metric using the IsDefaultMetric trait or is_default_metric, this method falls back to log(M,p,q). Otherwise, you have to provide an implementation for the non-default AbstractMetric G metric within its MetricManifold{M,G}.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.connection-Tuple{MetricManifold}","page":"Metric manifold","title":"Manifolds.connection","text":"connection(::MetricManifold)\n\nReturn the LeviCivitaConnection for a metric manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.det_local_metric-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.det_local_metric","text":"det_local_metric(M::AbstractManifold, p, B::AbstractBasis)\n\nReturn the determinant of local matrix representation of the metric tensor g, i.e. of the matrix G(p) representing the metric in the tangent space at p with as a matrix.\n\nSee also local_metric\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.einstein_tensor-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.einstein_tensor","text":"einstein_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = diff_badefault_differential_backendckend())\n\nCompute the Einstein tensor of the manifold M at the point p, see https://en.wikipedia.org/wiki/Einstein_tensor\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.flat-Tuple{MetricManifold, Any, TFVector}","page":"Metric manifold","title":"Manifolds.flat","text":"flat(N::MetricManifold{M,G}, p, X::TFVector)\n\nCompute the musical isomorphism to transform the tangent vector X from the AbstractManifold M equipped with AbstractMetric G to a cotangent by computing\n\nX^= G_p X\n\nwhere G_p is the local matrix representation of G, see local_metric\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.inverse_local_metric-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.inverse_local_metric","text":"inverse_local_metric(M::AbstractcManifold{𝔽}, p, B::AbstractBasis)\n\nReturn the local matrix representation of the inverse metric (cometric) tensor of the tangent space at p on the AbstractManifold M with respect to the AbstractBasis basis B.\n\nThe metric tensor (see local_metric) is usually denoted by G = (g_ij) 𝔽^dd, where d is the dimension of the manifold.\n\nThen the inverse local metric is denoted by G^-1 = g^ij.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.is_default_metric-Tuple{AbstractManifold, AbstractMetric}","page":"Metric manifold","title":"Manifolds.is_default_metric","text":"is_default_metric(M::AbstractManifold, G::AbstractMetric)\n\nreturns whether an AbstractMetric is the default metric on the manifold M or not. This can be set by defining this function, or setting the IsDefaultMetric trait for an AbstractDecoratorManifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.local_metric-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.local_metric","text":"local_metric(M::AbstractManifold{𝔽}, p, B::AbstractBasis)\n\nReturn the local matrix representation at the point p of the metric tensor g with respect to the AbstractBasis B on the AbstractManifold M. Let ddenote the dimension of the manifold and b_1ldotsb_d the basis vectors. Then the local matrix representation is a matrix Gin 𝔽^ntimes n whose entries are given by g_ij = g_p(b_ib_j) ijin1d.\n\nThis yields the property for two tangent vectors (using Einstein summation convention) X = X^ib_i Y=Y^ib_i in T_pmathcal M we get g_p(X Y) = g_ij X^i Y^j.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.local_metric_jacobian-Tuple{AbstractManifold, Any, AbstractBasis, ManifoldDiff.AbstractDiffBackend}","page":"Metric manifold","title":"Manifolds.local_metric_jacobian","text":"local_metric_jacobian(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend,\n)\n\nGet partial derivatives of the local metric of M at p in basis B with respect to the coordinates of p, frac p^k g_ij = g_ijk. The dimensions of the resulting multi-dimensional array are ordered (ijk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.log_local_metric_density-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.log_local_metric_density","text":"log_local_metric_density(M::AbstractManifold, p, B::AbstractBasis)\n\nReturn the natural logarithm of the metric density ρ of M at p, which is given by ρ = log sqrtdet g_ij for the metric tensor expressed in basis B.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.metric-Tuple{MetricManifold}","page":"Metric manifold","title":"Manifolds.metric","text":"metric(M::MetricManifold)\n\nGet the metric g of the manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.ricci_curvature-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.ricci_curvature","text":"ricci_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())\n\nCompute the Ricci scalar curvature of the manifold M at the point p using basis B. The curvature is computed as the trace of the Ricci curvature tensor with respect to the metric, that is R=g^ijR_ij where R is the scalar Ricci curvature at p, g^ij is the inverse local metric (see inverse_local_metric) at p and R_ij is the Riccie curvature tensor, see ricci_tensor. Both the tensor and inverse local metric are expressed in local coordinates defined by B, and the formula uses the Einstein summation convention.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.sharp-Tuple{MetricManifold, Any, CoTFVector}","page":"Metric manifold","title":"Manifolds.sharp","text":"sharp(N::MetricManifold{M,G}, p, ξ::CoTFVector)\n\nCompute the musical isomorphism to transform the cotangent vector ξ from the AbstractManifold M equipped with AbstractMetric G to a tangent by computing\n\nξ^ = G_p^-1 ξ\n\nwhere G_p is the local matrix representation of G, i.e. one employs inverse_local_metric here to obtain G_p^-1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#ManifoldsBase.inner-Tuple{MetricManifold, Any, Any, Any}","page":"Metric manifold","title":"ManifoldsBase.inner","text":"inner(N::MetricManifold{M,G}, p, X, Y)\n\nCompute the inner product of X and Y from the tangent space at p on the AbstractManifold M using the AbstractMetric G. If M has G as its IsDefaultMetric trait, this is done using inner(M, p, X, Y), otherwise the local_metric(M, p) is employed as\n\ng_p(X Y) = X G_p Y\n\nwhere G_p is the loal matrix representation of the AbstractMetric G.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Metrics,-charts-and-bases-of-vector-spaces","page":"Metric manifold","title":"Metrics, charts and bases of vector spaces","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Metric-related functions, similarly to connection-related functions, need to operate in a basis of a vector space, see here.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Metric-related functions can take bases of associated tangent spaces as arguments. For example local_metric can take the basis of the tangent space it is supposed to operate on instead of a custom basis of the space of symmetric bilinear operators.","category":"page"},{"location":"manifolds/symmetric.html#Symmetric-matrices","page":"Symmetric matrices","title":"Symmetric matrices","text":"","category":"section"},{"location":"manifolds/symmetric.html","page":"Symmetric matrices","title":"Symmetric matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Symmetric.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetric.html#Manifolds.SymmetricMatrices","page":"Symmetric matrices","title":"Manifolds.SymmetricMatrices","text":"SymmetricMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe AbstractManifold $ \\operatorname{Sym}(n)$ consisting of the real- or complex-valued symmetric matrices of size n n, i.e. the set\n\noperatornameSym(n) = biglp 𝔽^n n big p^mathrmH = p bigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ.\n\nThough it is slightly redundant, usually the matrices are stored as n n arrays.\n\nNote that in this representation, the complex valued case has to have a real-valued diagonal, which is also reflected in the manifold_dimension.\n\nConstructor\n\nSymmetricMatrices(n::Int, field::AbstractNumbers=ℝ)\n\nGenerate the manifold of n n symmetric matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetric.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{SymmetricMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Symmetric matrices","title":"ManifoldsBase.check_point","text":"check_point(M::SymmetricMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether p is a valid manifold point on the SymmetricMatrices M, i.e. whether p is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.\n\nThe tolerance for the symmetry of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{SymmetricMatrices{n, 𝔽}, Any, Any}} where {n, 𝔽}","page":"Symmetric matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::SymmetricMatrices{n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.\n\nThe tolerance for the symmetry of X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.is_flat-Tuple{SymmetricMatrices}","page":"Symmetric matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::SymmetricMatrices)\n\nReturn true. SymmetricMatrices is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.manifold_dimension-Union{Tuple{SymmetricMatrices{N, 𝔽}}, Tuple{𝔽}, Tuple{N}} where {N, 𝔽}","page":"Symmetric matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SymmetricMatrices{n,𝔽})\n\nReturn the dimension of the SymmetricMatrices matrix M over the number system 𝔽, i.e.\n\nbeginaligned\ndim mathrmSym(nℝ) = fracn(n+1)2\ndim mathrmSym(nℂ) = 2fracn(n+1)2 - n = n^2\nendaligned\n\nwhere the last -n is due to the zero imaginary part for Hermitian matrices\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.project-Tuple{SymmetricMatrices, Any, Any}","page":"Symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SymmetricMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the SymmetricMatrices M,\n\noperatornameproj_p(X) = frac12 bigl( X + X^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.project-Tuple{SymmetricMatrices, Any}","page":"Symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SymmetricMatrices, p)\n\nProjects p from the embedding onto the SymmetricMatrices M, i.e.\n\noperatornameproj_operatornameSym(n)(p) = frac12 bigl( p + p^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Grassmannian-manifold","page":"Grassmann","title":"Grassmannian manifold","text":"","category":"section"},{"location":"manifolds/grassmann.html","page":"Grassmann","title":"Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/Grassmann.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/grassmann.html#Manifolds.Grassmann","page":"Grassmann","title":"Manifolds.Grassmann","text":"Grassmann{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe Grassmann manifold operatornameGr(nk) consists of all subspaces spanned by k linear independent vectors 𝔽^n, where 𝔽 ℝ ℂ is either the real- (or complex-) valued vectors. This yields all k-dimensional subspaces of ℝ^n for the real-valued case and all 2k-dimensional subspaces of ℂ^n for the second.\n\nThe manifold can be represented as\n\noperatornameGr(nk) = bigl operatornamespan(p) p 𝔽^n k p^mathrmHp = I_k\n\nwhere cdot^mathrmH denotes the complex conjugate transpose or Hermitian and I_k is the k k identity matrix. This means, that the columns of p form an unitary basis of the subspace, that is a point on operatornameGr(nk), and hence the subspace can actually be represented by a whole equivalence class of representers. Another interpretation is, that\n\noperatornameGr(nk) = operatornameSt(nk) operatornameO(k)\n\ni.e the Grassmann manifold is the quotient of the Stiefel manifold and the orthogonal group operatornameO(k) of orthogonal k k matrices. Note that it doesn't matter whether we start from the Euclidean or canonical metric on the Stiefel manifold, the resulting quotient metric on Grassmann is the same.\n\nThe tangent space at a point (subspace) p is given by\n\nT_pmathrmGr(nk) = bigl\nX 𝔽^n k \nX^mathrmHp + p^mathrmHX = 0_k bigr\n\nwhere 0_k is the k k zero matrix.\n\nNote that a point p operatornameGr(nk) might be represented by different matrices (i.e. matrices with unitary column vectors that span the same subspace). Different representations of p also lead to different representation matrices for the tangent space T_pmathrmGr(nk)\n\nFor a representation of points as orthogonal projectors. Here\n\noperatornameGr(nk) = bigl p in mathbb R^nn p = p^mathrmT p^2 = p operatornamerank(p) = k\n\nwith tangent space\n\nT_pmathrmGr(nk) = bigl\nX mathbb R^n n X=X^mathrmT text and X = pX+Xp bigr\n\nsee also ProjectorPoint and ProjectorTVector.\n\nThe manifold is named after Hermann G. Graßmann (1809-1877).\n\nA good overview can be found in[BendokatZimmermannAbsil2020].\n\nConstructor\n\nGrassmann(n,k,field=ℝ)\n\nGenerate the Grassmann manifold operatornameGr(nk), where the real-valued case field = ℝ is the default.\n\n[BendokatZimmermannAbsil2020]: T. Bendokat, R. Zimmermann, and P. -A. Absil: A Grassmann Manifold Handbook: Basic Geometry and Computational Aspects, arXiv preprint 2011.13699, 2020.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Base.convert-Tuple{Type{ProjectorPoint}, AbstractMatrix}","page":"Grassmann","title":"Base.convert","text":"convert(::Type{ProjectorPoint}, p::AbstractMatrix)\n\nConvert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for\n\n π^mathrmSG(p) = pp^mathrmT)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Base.convert-Tuple{Type{ProjectorPoint}, StiefelPoint}","page":"Grassmann","title":"Base.convert","text":"convert(::Type{ProjectorPoint}, ::Stiefelpoint)\n\nConvert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for\n\n π^mathrmSG(p) = pp^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.get_total_space-Union{Tuple{Grassmann{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Grassmann","title":"Manifolds.get_total_space","text":"get_total_space(::Grassmann{n,k})\n\nReturn the total space of the Grassmann manifold, which is the corresponding Stiefel manifold, independent of whether the points are represented already in the total space or as ProjectorPoints.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.change_metric-Tuple{Grassmann, EuclideanMetric, Any, Any}","page":"Grassmann","title":"ManifoldsBase.change_metric","text":"change_metric(M::Grassmann, ::EuclideanMetric, p X)\n\nChange X to the corresponding vector with respect to the metric of the Grassmann M, which is just the identity, since the manifold is isometrically embedded.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.change_representer-Tuple{Grassmann, EuclideanMetric, Any, Any}","page":"Grassmann","title":"ManifoldsBase.change_representer","text":"change_representer(M::Grassmann, ::EuclideanMetric, p, X)\n\nChange X to the corresponding representer of a cotangent vector at p. Since the Grassmann manifold M, is isometrically embedded, this is the identity\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.default_retraction_method-Tuple{Grassmann, Type{ProjectorPoint}}","page":"Grassmann","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Grassmann, ::Type{ProjectorPoint})\n\nReturn ExponentialRetraction as the default on the Grassmann manifold with projection matrices\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.default_retraction_method-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Grassmann)\ndefault_retraction_method(M::Grassmann, ::Type{StiefelPoint})\n\nReturn PolarRetracion as the default on the Grassmann manifold with projection matrices\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.default_vector_transport_method-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::Grassmann)\n\nReturn the ProjectionTransport as the default vector transport method for the Grassmann manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.injectivity_radius-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Grassmann)\ninjectivity_radius(M::Grassmann, p)\n\nReturn the injectivity radius on the Grassmann M, which is fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.is_flat-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.is_flat","text":"is_flat(M::Grassmann)\n\nReturn true if Grassmann M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.manifold_dimension-Union{Tuple{Grassmann{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Grassmann)\n\nReturn the dimension of the Grassmann(n,k,𝔽) manifold M, i.e.\n\ndim operatornameGr(nk) = k(n-k) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Statistics.mean-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"Statistics.mean","text":"mean(\n M::Grassmann,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/4);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#The-Grassmanian-represented-as-points-on-the-[Stiefel](@ref)-manifold","page":"Grassmann","title":"The Grassmanian represented as points on the Stiefel manifold","text":"","category":"section"},{"location":"manifolds/grassmann.html","page":"Grassmann","title":"Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/GrassmannStiefel.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/grassmann.html#Manifolds.StiefelPoint","page":"Grassmann","title":"Manifolds.StiefelPoint","text":"StiefelPoint <: AbstractManifoldPoint\n\nA point on a Stiefel manifold. This point is mainly used for representing points on the Grassmann where this is also the default representation and hence equivalent to using AbstractMatrices thereon. they can also used be used as points on Stiefel.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Manifolds.StiefelTVector","page":"Grassmann","title":"Manifolds.StiefelTVector","text":"StiefelTVector <: TVector\n\nA tangent vector on the Grassmann manifold represented by a tangent vector from the tangent space of a corresponding point from the Stiefel manifold, see StiefelPoint. This is the default representation so is can be used interchangeably with just abstract matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Base.exp-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"Base.exp","text":"exp(M::Grassmann, p, X)\n\nCompute the exponential map on the Grassmann M= mathrmGr(nk) starting in p with tangent vector (direction) X. Let X = USV denote the SVD decomposition of X. Then the exponential map is written using\n\nz = p Vcos(S)V^mathrmH + Usin(S)V^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of S. A final QR decomposition z=QR is performed for numerical stability reasons, yielding the result as\n\nexp_p X = Q\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Base.log-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"Base.log","text":"log(M::Grassmann, p, q)\n\nCompute the logarithmic map on the Grassmann M$ = \\mathcal M=\\mathrm{Gr}(n,k)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads\n\nlog_p q = Vcdot operatornameatan(S) cdot U^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian. The matrices U and V are the unitary matrices, and S is the diagonal matrix containing the singular values of the SVD-decomposition\n\nUSV = (q^mathrmHp)^-1 ( q^mathrmH - q^mathrmHpp^mathrmH)\n\nIn this formula the operatornameatan is meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Base.rand-Tuple{Grassmann}","page":"Grassmann","title":"Base.rand","text":"rand(M::Grassmann; σ::Real=1.0, vector_at=nothing)\n\nWhen vector_at is nothing, return a random point p on Grassmann manifold M by generating a random (Gaussian) matrix with standard deviation σ in matching size, which is orthonormal.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_pmathrmGr(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent space at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.uniform_distribution-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, ℝ}, Any}} where {n, k}","page":"Grassmann","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::Grassmann{n,k,ℝ}, p)\n\nUniform distribution on given (real-valued) Grassmann M. Specifically, this is the normalized Haar measure on M. Generated points will be of similar type as p.\n\nThe implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.2(iii) in [Chikuse2003].\n\n[Chikuse2003]: Y. Chikuse: \"Statistics on Special Manifolds\", Springer New York, 2003, doi: 10.1007/978-0-387-21540-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.distance-Tuple{Grassmann, Any, Any}","page":"Grassmann","title":"ManifoldsBase.distance","text":"distance(M::Grassmann, p, q)\n\nCompute the Riemannian distance on Grassmann manifold M= mathrmGr(nk).\n\nThe distance is given by\n\nd_mathrmGr(nk)(pq) = operatornamenorm(log_p(q))\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.inner-Tuple{Grassmann, Any, Any, Any}","page":"Grassmann","title":"ManifoldsBase.inner","text":"inner(M::Grassmann, p, X, Y)\n\nCompute the inner product for two tangent vectors X, Y from the tangent space of p on the Grassmann manifold M. The formula reads\n\ng_p(XY) = operatornametr(X^mathrmHY)\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.inverse_retract-Tuple{Grassmann, Any, Any, PolarInverseRetraction}","page":"Grassmann","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Grassmann, p, q, ::PolarInverseRetraction)\n\nCompute the inverse retraction for the PolarRetraction, on the Grassmann manifold M, i.e.,\n\noperatornameretr_p^-1q = q*(p^mathrmHq)^-1 - p\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.inverse_retract-Tuple{Grassmann, Any, Any, QRInverseRetraction}","page":"Grassmann","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M, p, q, ::QRInverseRetraction)\n\nCompute the inverse retraction for the QRRetraction, on the Grassmann manifold M, i.e.,\n\noperatornameretr_p^-1q = q(p^mathrmHq)^-1 - p\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.project-Tuple{Grassmann, Any}","page":"Grassmann","title":"ManifoldsBase.project","text":"project(M::Grassmann, p)\n\nProject p from the embedding onto the Grassmann M, i.e. compute q as the polar decomposition of p such that q^mathrmHq is the identity, where cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.project-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"ManifoldsBase.project","text":"project(M::Grassmann, p, X)\n\nProject the n-by-k X onto the tangent space of p on the Grassmann M, which is computed by\n\noperatornameproj_p(X) = X - pp^mathrmHX\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.representation_size-Union{Tuple{Grassmann{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Grassmann","title":"ManifoldsBase.representation_size","text":"representation_size(M::Grassmann{n,k})\n\nReturn the represenation size or matrix dimension of a point on the Grassmann M, i.e. (nk) for both the real-valued and the complex value case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.retract-Tuple{Grassmann, Any, Any, PolarRetraction}","page":"Grassmann","title":"ManifoldsBase.retract","text":"retract(M::Grassmann, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the Grassmann M. With USV = p + X the retraction reads\n\noperatornameretr_p X = UV^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.retract-Tuple{Grassmann, Any, Any, QRRetraction}","page":"Grassmann","title":"ManifoldsBase.retract","text":"retract(M::Grassmann, p, X, ::QRRetraction )\n\nCompute the QR-based retraction QRRetraction on the Grassmann M. With QR = p + X the retraction reads\n\noperatornameretr_p X = QD\n\nwhere D is a m n matrix with\n\nD = operatornamediagleft( operatornamesgnleft(R_ii+frac12right)_i=1^n right)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.riemann_tensor-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, ℝ}, Vararg{Any, 4}}} where {n, k}","page":"Grassmann","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::Grassmann{n,k,ℝ}, p, X, Y, Z) where {n,k}\n\nCompute the value of Riemann tensor on the real Grassmann manifold. The formula reads[Rentmeesters2011] R(XY)Z = (XY^mathrmT - YX^mathrmT)Z + Z(Y^mathrmTX - X^mathrmTY).\n\n[Rentmeesters2011]: Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.vector_transport_to-Tuple{Grassmann, Any, Any, Any, ProjectionTransport}","page":"Grassmann","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Grassmann,p,X,q,::ProjectionTransport)\n\ncompute the projection based transport on the Grassmann M by interpreting X from the tangent space at p as a point in the embedding and projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.zero_vector-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Grassmann, p)\n\nReturn the zero tangent vector from the tangent space at p on the Grassmann M, which is given by a zero matrix the same size as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#The-Grassmannian-represented-as-projectors","page":"Grassmann","title":"The Grassmannian represented as projectors","text":"","category":"section"},{"location":"manifolds/grassmann.html","page":"Grassmann","title":"Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/GrassmannProjector.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/grassmann.html#Manifolds.ProjectorPoint","page":"Grassmann","title":"Manifolds.ProjectorPoint","text":"ProjectorPoint <: AbstractManifoldPoint\n\nA type to represent points on a manifold Grassmann that are orthogonal projectors, i.e. a matrix p mathbb F^nn projecting onto a k-dimensional subspace.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Manifolds.ProjectorTVector","page":"Grassmann","title":"Manifolds.ProjectorTVector","text":"ProjectorTVector <: TVector\n\nA type to represent tangent vectors to points on a Grassmann manifold that are orthogonal projectors.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Base.exp-Tuple{Grassmann, ProjectorPoint, ProjectorTVector}","page":"Grassmann","title":"Base.exp","text":"exp(M::Grassmann, p::ProjectorPoint, X::ProjectorTVector)\n\nCompute the exponential map on the Grassmann as\n\n exp_pX = operatornameExp(Xp)poperatornameExp(-Xp)\n\nwhere operatornameExp denotes the matrix exponential and AB = AB-BA denotes the matrix commutator.\n\nFor details, see Proposition 3.2 in [BendokatZimmermannAbsil2020].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.canonical_project!-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k}, ProjectorPoint, Any}} where {n, k}","page":"Grassmann","title":"Manifolds.canonical_project!","text":"canonical_project!(M::Grassmann{n,k}, q::ProjectorPoint, p)\n\nCompute the canonical projection π(p) from the Stiefel manifold onto the Grassmann manifold when represented as ProjectorPoint, i.e.\n\n π^mathrmSG(p) = pp^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.differential_canonical_project!-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k}, ProjectorTVector, Any, Any}} where {n, k}","page":"Grassmann","title":"Manifolds.differential_canonical_project!","text":"canonical_project!(M::Grassmann{n,k}, q::ProjectorPoint, p)\n\nCompute the canonical projection π(p) from the Stiefel manifold onto the Grassmann manifold when represented as ProjectorPoint, i.e.\n\n Dπ^mathrmSG(p)X = Xp^mathrmT + pX^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.horizontal_lift-Tuple{Stiefel, Any, ProjectorTVector}","page":"Grassmann","title":"Manifolds.horizontal_lift","text":"horizontal_lift(N::Stiefel{n,k}, q, X::ProjectorTVector)\n\nCompute the horizontal lift of X from the tangent space at p=π(q) on the Grassmann manifold, i.e.\n\nY = Xq T_qmathrmSt(nk)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.check_point","text":"check_point(::Grassmann{n,k}, p::ProjectorPoint; kwargs...)\n\nCheck whether an orthogonal projector is a point from the Grassmann(n,k) manifold, i.e. the ProjectorPoint p mathbb F^nn, mathbb F mathbb R mathbb C has to fulfill p^mathrmT = p, p^2=p, and `\\operatorname{rank} p = k.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.check_size-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.check_size","text":"check_size(M::Grassmann{n,k,𝔽}, p::ProjectorPoint; kwargs...) where {n,k}\n\nCheck that the ProjectorPoint is of correct size, i.e. from mathbb F^nn\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint, ProjectorTVector}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.check_vector","text":"check_vector(::Grassmann{n,k,𝔽}, p::ProjectorPoint, X::ProjectorTVector; kwargs...) where {n,k,𝔽}\n\nCheck whether the ProjectorTVector X is from the tangent space T_poperatornameGr(nk) at the ProjectorPoint p on the Grassmann manifold operatornameGr(nk). This means that X has to be symmetric and that\n\nXp + pX = X\n\nmust hold, where the kwargs can be used to check both for symmetrix of X` and this equality up to a certain tolerance.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.get_embedding-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::Grassmann{n,k,𝔽}, p::ProjectorPoint) where {n,k,𝔽}\n\nReturn the embedding of the ProjectorPoint representation of the Grassmann manifold, i.e. the Euclidean space mathbb F^nn.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.parallel_transport_direction-Tuple{Grassmann, ProjectorPoint, ProjectorTVector, ProjectorTVector}","page":"Grassmann","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(\n M::Grassmann,\n p::ProjectorPoint,\n X::ProjectorTVector,\n d::ProjectorTVector\n)\n\nCompute the parallel transport of X from the tangent space at p into direction d, i.e. to q=exp_pd. The formula is given in Proposition 3.5 of [BendokatZimmermannAbsil2020] as\n\nmathcalP_q p(X) = operatornameExp(dp)XoperatornameExp(-dp)\n\nwhere operatornameExp denotes the matrix exponential and AB = AB-BA denotes the matrix commutator.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.representation_size-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k}, ProjectorPoint}} where {n, k}","page":"Grassmann","title":"ManifoldsBase.representation_size","text":"representation_size(M::Grassmann{n,k}, p::ProjectorPoint)\n\nReturn the represenation size or matrix dimension of a point on the Grassmann M when using ProjectorPoints, i.e. (nn).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Essential-Manifold","page":"Essential manifold","title":"Essential Manifold","text":"","category":"section"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"The essential manifold is modeled as an AbstractPowerManifold of the 3times3 Rotations and uses NestedPowerRepresentation.","category":"page"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/EssentialManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/essentialmanifold.html#Manifolds.EssentialManifold","page":"Essential manifold","title":"Manifolds.EssentialManifold","text":"EssentialManifold <: AbstractPowerManifold{ℝ}\n\nThe essential manifold is the space of the essential matrices which is represented as a quotient space of the Rotations manifold product mathrmSO(3)^2.\n\nLet R_x(θ) R_y(θ) R_x(θ) in ℝ^xtimes 3 denote the rotation around the z, y, and x axis in ℝ^3, respectively, and further the groups\n\nH_z = bigl(R_z(θ)R_z(θ)) big θ -ππ) bigr\n\nand\n\nH_π = bigl (II) (R_x(π) R_x(π)) (IR_z(π)) (R_x(π) R_y(π)) bigr\n\nacting elementwise on the left from mathrmSO(3)^2 (component wise).\n\nThen the unsigned Essential manifold mathcalM_textE can be identified with the quotient space\n\nmathcalM_textE = (textSO(3)textSO(3))(H_z H_π)\n\nand for the signed Essential manifold mathcalM_textƎ, the quotient reads\n\nmathcalM_textƎ = (textSO(3)textSO(3))(H_z)\n\nAn essential matrix is defined as\n\nE = (R_1)^T T_2 - T_1_ R_2\n\nwhere the poses of two cameras (R_i T_i) i=12, are contained in the space of rigid body transformations SE(3) and the operator _colon ℝ^3 to operatornameSkewSym(3) denotes the matrix representation of the cross product operator. For more details see [TronDaniilidis2017].\n\nConstructor\n\nEssentialManifold(is_signed=true)\n\nGenerate the manifold of essential matrices, either the signed (is_signed=true) or unsigned (is_signed=false) variant.\n\n[TronDaniilidis2017]: Tron R.; Daniilidis K.; The Space of Essential Matrices as a Riemannian Quotient AbstractManifold. SIAM Journal on Imaging Sciences (2017), DOI: 10.1137/16M1091332, PDF: https://www.cis.upenn.edu/~kostas/mypub.dir/tron17siam.pdf.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/essentialmanifold.html#Functions","page":"Essential manifold","title":"Functions","text":"","category":"section"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"Modules = [Manifolds]\nPrivate = false\nPages = [\"manifolds/EssentialManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/essentialmanifold.html#Base.exp-Tuple{EssentialManifold, Vararg{Any}}","page":"Essential manifold","title":"Base.exp","text":"exp(M::EssentialManifold, p, X)\n\nCompute the exponential map on the EssentialManifold from p into direction X, i.e.\n\ntextexp_p(X) =textexp_g( tilde X) quad g in text(SO)(3)^2\n\nwhere tilde X is the horizontal lift of X[TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Base.log-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"Base.log","text":"log(M::EssentialManifold, p, q)\n\nCompute the logarithmic map on the EssentialManifold M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. Here, p=(R_p_1R_p_2) and q=(R_q_1R_q_2) are elements of SO(3)^2. We use that any essential matrix can, up to scale, be decomposed to\n\nE = R_1^T e_z_R_2\n\nwhere (R_1R_2)SO(3)^2. Two points in SO(3)^2 are equivalent iff their corresponding essential matrices are equal (up to a sign flip). To compute the logarithm, we first move q to another representative of its equivalence class. For this, we find t= t_textopt for which the function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nwhere d() is the distance function in SO(3), is minimized. Further, the group H_z acting on the left on SO(3)^2 is defined as\n\nH_z = (R_z(θ)R_z(θ))colon θ in -ππ) \n\nwhere R_z(θ) is the rotation around the z axis with angle θ. Points in H_z are denoted by S_z. Then, the logarithm is defined as\n\nlog_p (S_z(t_textopt)q) = textLog(R_p_i^T R_z(t_textopt)R_b_i)_i=12\n\nwhere textLog is the logarithm on SO(3). For more details see [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.check_point-Tuple{EssentialManifold, Any}","page":"Essential manifold","title":"ManifoldsBase.check_point","text":"check_point(M::EssentialManifold, p; kwargs...)\n\nCheck whether the matrix is a valid point on the EssentialManifold M, i.e. a 2-element array containing SO(3) matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.check_vector-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::EssentialManifold, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the EssentialManifold M, i.e. X has to be a 2-element array of 3-by-3 skew-symmetric matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.distance-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.distance","text":"distance(M::EssentialManifold, p, q)\n\nCompute the Riemannian distance between the two points p and q on the EssentialManifold. This is done by computing the distance of the equivalence classes p and q of the points p=(R_p_1R_p_2) q=(R_q_1R_q_2) SO(3)^2, respectively. Two points in SO(3)^2 are equivalent iff their corresponding essential matrices, given by\n\nE = R_1^T e_z_R_2\n\nare equal (up to a sign flip). Using the logarithmic map, the distance is given by\n\ntextdist(pq) = textlog_p q = log_p (S_z(t_textopt)q) \n\nwhere S_z H_z = (R_z(θ)R_z(θ))colon θ in -ππ) in which R_z(θ) is the rotation around the z axis with angle θ and t_textopt is the minimizer of the cost function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nwhere d() is the distance function in SO(3)[TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.is_flat-Tuple{EssentialManifold}","page":"Essential manifold","title":"ManifoldsBase.is_flat","text":"is_flat(::EssentialManifold)\n\nReturn false. EssentialManifold is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.manifold_dimension-Tuple{EssentialManifold}","page":"Essential manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::EssentialManifold{is_signed, ℝ})\n\nReturn the manifold dimension of the EssentialManifold, which is 5[TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.parallel_transport_to-Tuple{EssentialManifold, Any, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::EssentialManifold, p, X, q)\n\nCompute the vector transport of the tangent vector X at p to q on the EssentialManifold M using left translation of the ambient group.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.project-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.project","text":"project(M::EssentialManifold, p, X)\n\nProject the matrix X onto the tangent space\n\nT_p textSO(3)^2 = T_textvptextSO(3)^2 T_texthptextSO(3)^2\n\nby first computing its projection onto the vertical space T_textvptextSO(3)^2 using vert_proj. Then the orthogonal projection of X onto the horizontal space T_texthptextSO(3)^2 is defined as\n\nPi_h(X) = X - fractextvert_proj_p(X)2 beginbmatrix R_1^T e_z R_2^T e_z endbmatrix\n\nwith R_i = R_0 R_i i=12 where R_i is part of the pose of camera i g_i = (R_iT_i) textSE(3) and R_0 textSO(3) such that R_0(T_2-T_1) = e_z.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Internal-Functions","page":"Essential manifold","title":"Internal Functions","text":"","category":"section"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"Modules = [Manifolds]\nPublic = false\nPages = [\"manifolds/EssentialManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair-Tuple{Any, Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair","text":"dist_min_angle_pair(p, q)\n\nThis function computes the global minimizer of the function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nfor the given values. This is done by finding the discontinuity points t_d_i i=12 of its derivative and using Newton's method to minimize the function over the intervals t_d_1t_d_2 and t_d_2t_d_1+2π separately. Then, the minimizer for which f is minimal is chosen and given back together with the minimal value. For more details see Algorithm 1 in [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair_compute_df_break-Tuple{Any, Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair_compute_df_break","text":"dist_min_angle_pair_compute_df_break(t_break, q)\n\nThis function computes the derivatives of each term f_i i=12 at discontinuity point t_break. For more details see [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair_df_newton-NTuple{9, Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair_df_newton","text":"dist_min_angle_pair_df_newton(m1, Φ1, c1, m2, Φ2, c2, t_min, t_low, t_high)\n\nThis function computes the minimizer of the function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nin the interval t_low, t_high using Newton's method. For more details see [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair_discontinuity_distance-Tuple{Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair_discontinuity_distance","text":"dist_min_angle_pair_discontinuity_distance(q)\n\nThis function computes the point t_textdi for which the first derivative of\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\ndoes not exist. This is the case for sin(θ_i(t_textdi)) = 0. For more details see Proposition 9 and its proof, as well as Lemma 1 in [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.vert_proj-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"Manifolds.vert_proj","text":"vert_proj(M::EssentialManifold, p, X)\n\nProject X onto the vertical space T_textvptextSO(3)^2 with\n\ntextvert_proj_p(X) = e_z^T(R_1 X_1 + R_2 X_2)\n\nwhere e_z is the third unit vector, X_i T_ptextSO(3) for i=12 and it holds R_i = R_0 R_i i=12 where R_i is part of the pose of camera i g_i = (R_iT_i) textSE(3) and R_0 textSO(3) such that R_0(T_2-T_1) = e_z [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Literature","page":"Essential manifold","title":"Literature","text":"","category":"section"},{"location":"manifolds/power.html#PowerManifoldSection","page":"Power manifold","title":"Power manifold","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"A power manifold is based on a AbstractManifold mathcal M to build a mathcal M^n_1 times n_2 times cdots times n_m. In the case where m=1 we can represent a manifold-valued vector of data of length n_1, for example a time series. The case where m=2 is useful for representing manifold-valued matrices of data of size n_1 times n_2, for example certain types of images.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"There are three available representations for points and vectors on a power manifold:","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"ArrayPowerRepresentation (the default one), very efficient but only applicable when points on the underlying manifold are represented using plain AbstractArrays.\nNestedPowerRepresentation, applicable to any manifold. It assumes that points on the underlying manifold are represented using mutable data types.\nNestedReplacingPowerRepresentation, applicable to any manifold. It does not mutate points on the underlying manifold, replacing them instead when appropriate.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"Below are some examples of usage of these representations.","category":"page"},{"location":"manifolds/power.html#Example","page":"Power manifold","title":"Example","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"There are two ways to store the data: in a multidimensional array or in a nested array.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"Let's look at an example for both. Let mathcal M be Sphere(2) the 2-sphere and we want to look at vectors of length 4.","category":"page"},{"location":"manifolds/power.html#ArrayPowerRepresentation","page":"Power manifold","title":"ArrayPowerRepresentation","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"For the default, the ArrayPowerRepresentation, we store the data in a multidimensional array,","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds\nM = PowerManifold(Sphere(2), 4)\np = cat([1.0, 0.0, 0.0],\n [1/sqrt(2.0), 1/sqrt(2.0), 0.0],\n [1/sqrt(2.0), 0.0, 1/sqrt(2.0)],\n [0.0, 1.0, 0.0]\n ,dims=2)","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"which is a valid point i.e.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"is_point(M, p)","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"This can also be used in combination with HybridArrays.jl and StaticArrays.jl, by setting","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using HybridArrays, StaticArrays\nq = HybridArray{Tuple{3,StaticArrays.Dynamic()},Float64,2}(p)","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"which is still a valid point on M and PowerManifold works with these, too.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"An advantage of this representation is that it is quite efficient, especially when a HybridArray (from the HybridArrays.jl package) is used to represent a point on the power manifold. A disadvantage is not being able to easily identify parts of the multidimensional array that correspond to a single point on the base manifold. Another problem is, that accessing a single point is p[:, 1] which might be unintuitive.","category":"page"},{"location":"manifolds/power.html#NestedPowerRepresentation","page":"Power manifold","title":"NestedPowerRepresentation","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"For the NestedPowerRepresentation we can now do","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds\nM = PowerManifold(Sphere(2), NestedPowerRepresentation(), 4)\np = [ [1.0, 0.0, 0.0],\n [1/sqrt(2.0), 1/sqrt(2.0), 0.0],\n [1/sqrt(2.0), 0.0, 1/sqrt(2.0)],\n [0.0, 1.0, 0.0],\n ]","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"which is again a valid point so is_point(M, p) here also yields true. A disadvantage might be that with nested arrays one loses a little bit of performance. The data however is nicely encapsulated. Accessing the first data item is just p[1].","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"For accessing points on power manifolds in both representations you can use get_component and set_component! functions. They work work both point representations.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds\nM = PowerManifold(Sphere(2), NestedPowerRepresentation(), 4)\np = [ [1.0, 0.0, 0.0],\n [1/sqrt(2.0), 1/sqrt(2.0), 0.0],\n [1/sqrt(2.0), 0.0, 1/sqrt(2.0)],\n [0.0, 1.0, 0.0],\n ]\nset_component!(M, p, [0.0, 0.0, 1.0], 4)\nget_component(M, p, 4)","category":"page"},{"location":"manifolds/power.html#NestedReplacingPowerRepresentation","page":"Power manifold","title":"NestedReplacingPowerRepresentation","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"The final representation is the NestedReplacingPowerRepresentation. It is similar to the NestedPowerRepresentation but it does not perform in-place operations on the points on the underlying manifold. The example below uses this representation to store points on a power manifold of the SpecialEuclidean group in-line in an Vector for improved efficiency. When having a mixture of both, i.e. an array structure that is nested (like ´NestedPowerRepresentation) in the sense that the elements of the main vector are immutable, then changing the elements can not be done in an in-place way and hence NestedReplacingPowerRepresentation has to be used.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds, StaticArrays\nR2 = Rotations(2)\n\nG = SpecialEuclidean(2)\nN = 5\nGN = PowerManifold(G, NestedReplacingPowerRepresentation(), N)\n\nq = [1.0 0.0; 0.0 1.0]\np1 = [ProductRepr(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, i)))) for i in 1:N]\np2 = [ProductRepr(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, -i)))) for i in 1:N]\n\nX = similar(p1);\n\nlog!(GN, X, p1, p2)","category":"page"},{"location":"manifolds/power.html#Types-and-Functions","page":"Power manifold","title":"Types and Functions","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/PowerManifold.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/power.html#Manifolds.ArrayPowerRepresentation","page":"Power manifold","title":"Manifolds.ArrayPowerRepresentation","text":"ArrayPowerRepresentation\n\nRepresentation of points and tangent vectors on a power manifold using multidimensional arrays where first dimensions are equal to representation_size of the wrapped manifold and the following ones are equal to the number of elements in each direction.\n\nTorus uses this representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.PowerFVectorDistribution","page":"Power manifold","title":"Manifolds.PowerFVectorDistribution","text":"PowerFVectorDistribution([type::VectorBundleFibers], [x], distr)\n\nGenerates a random vector at a point from vector space (a fiber of a tangent bundle) of type type using the power distribution of distr.\n\nVector space type and point can be automatically inferred from distribution distr.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.PowerMetric","page":"Power manifold","title":"Manifolds.PowerMetric","text":"PowerMetric <: AbstractMetric\n\nRepresent the AbstractMetric on an AbstractPowerManifold, i.e. the inner product on the tangent space is the sum of the inner product of each elements tangent space of the power manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.PowerPointDistribution","page":"Power manifold","title":"Manifolds.PowerPointDistribution","text":"PowerPointDistribution(M::AbstractPowerManifold, distribution)\n\nPower distribution on manifold M, based on distribution.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.flat-Tuple{AbstractPowerManifold, Vararg{Any}}","page":"Power manifold","title":"Manifolds.flat","text":"flat(M::AbstractPowerManifold, p, X)\n\nuse the musical isomorphism to transform the tangent vector X from the tangent space at p on an AbstractPowerManifold M to a cotangent vector. This can be done elementwise for each entry of X (and p).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#Manifolds.manifold_volume-Union{Tuple{PowerManifold{𝔽, <:AbstractManifold, TSize}}, Tuple{TSize}, Tuple{𝔽}} where {𝔽, TSize}","page":"Power manifold","title":"Manifolds.manifold_volume","text":"manifold_volume(M::PowerManifold)\n\nReturn the manifold volume of an PowerManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#Manifolds.sharp-Tuple{AbstractPowerManifold, Vararg{Any}}","page":"Power manifold","title":"Manifolds.sharp","text":"sharp(M::AbstractPowerManifold, p, ξ::RieszRepresenterCotangentVector)\n\nUse the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on an AbstractPowerManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#Manifolds.volume_density-Tuple{PowerManifold, Any, Any}","page":"Power manifold","title":"Manifolds.volume_density","text":"volume_density(M::PowerManifold, p, X)\n\nReturn volume density on the PowerManifold M, i.e. product of constituent volume densities.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#ManifoldsBase.change_metric-Tuple{AbstractPowerManifold, AbstractMetric, Any, Any}","page":"Power manifold","title":"ManifoldsBase.change_metric","text":"change_metric(M::AbstractPowerManifold, ::AbstractMetric, p, X)\n\nSince the metric on a power manifold decouples, the change of metric can be done elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#ManifoldsBase.change_representer-Tuple{AbstractPowerManifold, AbstractMetric, Any, Any}","page":"Power manifold","title":"ManifoldsBase.change_representer","text":"change_representer(M::AbstractPowerManifold, ::AbstractMetric, p, X)\n\nSince the metric on a power manifold decouples, the change of a representer can be done elementwise\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#Rotations","page":"Rotations","title":"Rotations","text":"","category":"section"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"The manifold mathrmSO(n) of orthogonal matrices with determinant +1 in ℝ^n n, i.e.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"mathrmSO(n) = biglR ℝ^n n big R R^mathrmT =\nR^mathrmTR = I_n det(R) = 1 bigr","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"The Lie group mathrmSO(n) is a subgroup of the orthogonal group mathrmO(n) and also known as the special orthogonal group or the set of rotations group. See also SpecialOrthogonal, which is this manifold equipped with the group operation.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"The tangent space to a point p mathrmSO(n) is given by","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"T_pmathrmSO(n) = X X=pYqquad Y=-Y^mathrmT","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"i.e. all vectors that are a product of a skew symmetric matrix multiplied with p.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Since the orthogonal matrices mathrmSO(n) are a Lie group, tangent vectors can also be represented by elements of the corresponding Lie algebra, which is the tangent space at the identity element. In the notation above, this means we just store the component Y of X.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"This convention allows for more efficient operations on tangent vectors. Tangent spaces at different points are different vector spaces.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Let L_R mathrmSO(n) mathrmSO(n) where R mathrmSO(n) be the left-multiplication by R, that is L_R(S) = RS. The tangent space at rotation R, T_R mathrmSO(n), is related to the tangent space at the identity rotation I_n by the differential of L_R at identity, (mathrmdL_R)_I_n T_I_n mathrmSO(n) T_R mathrmSO(n). To convert the tangent vector representation at the identity rotation X T_I_n mathrmSO(n) (i.e., the default) to the matrix representation of the corresponding tangent vector Y at a rotation R use the embed which implements the following multiplication: Y = RX T_R mathrmSO(n). You can compare the functions log and exp to see how it works in practice.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Several common functions are also implemented together with orthogonal and unitary matrices.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Modules = [Manifolds]\nPages = [\"manifolds/Rotations.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/rotations.html#Manifolds.NormalRotationDistribution","page":"Rotations","title":"Manifolds.NormalRotationDistribution","text":"NormalRotationDistribution(M::Rotations, d::Distribution, x::TResult)\n\nDistribution that returns a random point on the manifold Rotations M. Random point is generated using base distribution d and the type of the result is adjusted to TResult.\n\nSee normal_rotation_distribution for details.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/rotations.html#Manifolds.Rotations","page":"Rotations","title":"Manifolds.Rotations","text":"Rotations{N} <: AbstractManifold{ℝ}\n\nThe manifold of rotation matrices of sice n n, i.e. real-valued orthogonal matrices with determinant +1.\n\nConstructor\n\nRotations(n)\n\nGenerate the manifold of n n rotation matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/rotations.html#Manifolds.angles_4d_skew_sym_matrix-Tuple{Any}","page":"Rotations","title":"Manifolds.angles_4d_skew_sym_matrix","text":"angles_4d_skew_sym_matrix(A)\n\nThe Lie algebra of Rotations(4) in ℝ^4 4, 𝔰𝔬(4), consists of 4 4 skew-symmetric matrices. The unique imaginary components of their eigenvalues are the angles of the two plane rotations. This function computes these more efficiently than eigvals.\n\nBy convention, the returned values are sorted in decreasing order (corresponding to the same ordering of angles as cos_angles_4d_rotation_matrix).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#Manifolds.normal_rotation_distribution-Union{Tuple{N}, Tuple{Rotations{N}, Any, Real}} where N","page":"Rotations","title":"Manifolds.normal_rotation_distribution","text":"normal_rotation_distribution(M::Rotations, p, σ::Real)\n\nReturn a random point on the manifold Rotations M by generating a (Gaussian) random orthogonal matrix with determinant +1. Let\n\nQR = A\n\nbe the QR decomposition of a random matrix A, then the formula reads\n\np = QD\n\nwhere D is a diagonal matrix with the signs of the diagonal entries of R, i.e.\n\nD_ij=begincases operatornamesgn(R_ij) textif i=j 0 textotherwise endcases\n\nIt can happen that the matrix gets -1 as a determinant. In this case, the first and second columns are swapped.\n\nThe argument p is used to determine the type of returned points.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.injectivity_radius-Tuple{Rotations, PolarRetraction}","page":"Rotations","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Rotations, ::PolarRetraction)\n\nReturn the radius of injectivity for the PolarRetraction on the Rotations M which is fracπsqrt2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.inverse_retract-Tuple{Rotations, Any, Any, PolarInverseRetraction}","page":"Rotations","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M, p, q, ::PolarInverseRetraction)\n\nCompute a vector from the tangent space T_pmathrmSO(n) of the point p on the Rotations manifold M with which the point q can be reached by the PolarRetraction from the point p after time 1.\n\nThe formula reads\n\noperatornameretr^-1_p(q)\n= -frac12(p^mathrmTqs - (p^mathrmTqs)^mathrmT)\n\nwhere s is the solution to the Sylvester equation\n\np^mathrmTqs + s(p^mathrmTq)^mathrmT + 2I_n = 0\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.inverse_retract-Tuple{Rotations, Any, Any, QRInverseRetraction}","page":"Rotations","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Rotations, p, q, ::QRInverseRetraction)\n\nCompute a vector from the tangent space T_pmathrmSO(n) of the point p on the Rotations manifold M with which the point q can be reached by the QRRetraction from the point q after time 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.parallel_transport_direction-Tuple{Rotations, Any, Any, Any}","page":"Rotations","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::Rotations, p, X, d)\n\nCompute parallel transport of vector X tangent at p on the Rotations manifold in the direction d. The formula, provided in [Rentmeesters2011], reads:\n\nmathcal P_qgets pX = q^mathrmTp operatornameExp(d2) X operatornameExp(d2)\n\nwhere q=exp_p d.\n\nThe formula simplifies to identity for 2-D rotations.\n\n[Rentmeesters2011]: Rentmeesters Q., “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.project-Tuple{Rotations, Any}","page":"Rotations","title":"ManifoldsBase.project","text":"project(M::Rotations, p; check_det = true)\n\nProject p to the nearest point on manifold M.\n\nGiven the singular value decomposition p = U Σ V^mathrmT, with the singular values sorted in descending order, the projection is\n\noperatornameproj_mathrmSO(n)(p) =\nUoperatornamediagleft11det(U V^mathrmT)right V^mathrmT\n\nThe diagonal matrix ensures that the determinant of the result is +1. If p is expected to be almost special orthogonal, then you may avoid this check with check_det = false.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.zero_vector-Tuple{Rotations, Any}","page":"Rotations","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Rotations, p)\n\nReturn the zero tangent vector from the tangent space art p on the Rotations as an element of the Lie group, i.e. the zero matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#Literature","page":"Rotations","title":"Literature","text":"","category":"section"},{"location":"manifolds/generalizedgrassmann.html#Generalized-Grassmann","page":"Generalized Grassmann","title":"Generalized Grassmann","text":"","category":"section"},{"location":"manifolds/generalizedgrassmann.html","page":"Generalized Grassmann","title":"Generalized Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/GeneralizedGrassmann.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/generalizedgrassmann.html#Manifolds.GeneralizedGrassmann","page":"Generalized Grassmann","title":"Manifolds.GeneralizedGrassmann","text":"GeneralizedGrassmann{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe generalized Grassmann manifold operatornameGr(nkB) consists of all subspaces spanned by k linear independent vectors 𝔽^n, where 𝔽 ℝ ℂ is either the real- (or complex-) valued vectors. This yields all k-dimensional subspaces of ℝ^n for the real-valued case and all 2k-dimensional subspaces of ℂ^n for the second.\n\nThe manifold can be represented as\n\noperatornameGr(n k B) = bigl operatornamespan(p) big p 𝔽^n k p^mathrmHBp = I_k\n\nwhere cdot^mathrmH denotes the complex conjugate (or Hermitian) transpose and I_k is the k k identity matrix. This means, that the columns of p form an unitary basis of the subspace with respect to the scaled inner product, that is a point on operatornameGr(nkB), and hence the subspace can actually be represented by a whole equivalence class of representers. For B=I_n this simplifies to the Grassmann manifold.\n\nThe tangent space at a point (subspace) p is given by\n\nT_xmathrmGr(nkB) = bigl\nX 𝔽^n k \nX^mathrmHBp + p^mathrmHBX = 0_k bigr\n\nwhere 0_k denotes the k k zero matrix.\n\nNote that a point p operatornameGr(nkB) might be represented by different matrices (i.e. matrices with B-unitary column vectors that span the same subspace). Different representations of p also lead to different representation matrices for the tangent space T_pmathrmGr(nkB)\n\nThe manifold is named after Hermann G. Graßmann (1809-1877).\n\nConstructor\n\nGeneralizedGrassmann(n, k, B=I_n, field=ℝ)\n\nGenerate the (real-valued) Generalized Grassmann manifold of ntimes k dimensional orthonormal matrices with scalar product B.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalizedgrassmann.html#Base.exp-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"Base.exp","text":"exp(M::GeneralizedGrassmann, p, X)\n\nCompute the exponential map on the GeneralizedGrassmann M= mathrmGr(nkB) starting in p with tangent vector (direction) X. Let X^mathrmHBX = USV denote the SVD decomposition of X^mathrmHBX. Then the exponential map is written using\n\nexp_p X = p Vcos(S)V^mathrmH + Usin(S)V^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of S.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#Base.log-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"Base.log","text":"log(M::GeneralizedGrassmann, p, q)\n\nCompute the logarithmic map on the GeneralizedGrassmann M$ = \\mathcal M=\\mathrm{Gr}(n,k,B)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads\n\nlog_p q = Vcdot operatornameatan(S) cdot U^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian. The matrices U and V are the unitary matrices, and S is the diagonal matrix containing the singular values of the SVD-decomposition\n\nUSV = (q^mathrmHBp)^-1 ( q^mathrmH - q^mathrmHBpp^mathrmH)\n\nIn this formula the operatornameatan is meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#Base.rand-Tuple{GeneralizedGrassmann}","page":"Generalized Grassmann","title":"Base.rand","text":"rand(::GeneralizedGrassmann; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (Gaussian) point p on the GeneralizedGrassmann manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size nk.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_vector_atmathrmSt(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.change_metric-Tuple{GeneralizedGrassmann, EuclideanMetric, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.change_metric","text":"change_metric(M::GeneralizedGrassmann, ::EuclideanMetric, p X)\n\nChange X to the corresponding vector with respect to the metric of the GeneralizedGrassmann M, i.e. let B=LL be the Cholesky decomposition of the matrix M.B, then the corresponding vector is LX.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.change_representer-Tuple{GeneralizedGrassmann, EuclideanMetric, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.change_representer","text":"change_representer(M::GeneralizedGrassmann, ::EuclideanMetric, p, X)\n\nChange X to the corresponding representer of a cotangent vector at p with respect to the scaled metric of the GeneralizedGrassmann M, i.e, since\n\ng_p(XY) = operatornametr(Y^mathrmHBZ) = operatornametr(X^mathrmHZ) = XZ\n\nhas to hold for all Z, where the repreenter X is given, the resulting representer with respect to the metric on the GeneralizedGrassmann is given by Y = B^-1X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedGrassmann{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Generalized Grassmann","title":"ManifoldsBase.check_point","text":"check_point(M::GeneralizedGrassmann{n,k,𝔽}, p)\n\nCheck whether p is representing a point on the GeneralizedGrassmann M, i.e. its a n-by-k matrix of unitary column vectors with respect to the B inner prudct and of correct eltype with respect to 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedGrassmann{n, k, 𝔽}, Any, Any}} where {n, k, 𝔽}","page":"Generalized Grassmann","title":"ManifoldsBase.check_vector","text":"check_vector(M::GeneralizedGrassmann{n,k,𝔽}, p, X; kwargs...)\n\nCheck whether X is a tangent vector in the tangent space of p on the GeneralizedGrassmann M, i.e. that X is of size and type as well as that\n\n p^mathrmHBX + overlineX^mathrmHBp = 0_k\n\nwhere cdot^mathrmH denotes the complex conjugate transpose or Hermitian, overlinecdot the (elementwise) complex conjugate, and 0_k denotes the k k zero natrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.distance-Tuple{GeneralizedGrassmann, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.distance","text":"distance(M::GeneralizedGrassmann, p, q)\n\nCompute the Riemannian distance on GeneralizedGrassmann manifold M= mathrmGr(nkB).\n\nThe distance is given by\n\nd_mathrmGr(nkB)(pq) = operatornamenorm(log_p(q))\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.injectivity_radius-Tuple{GeneralizedGrassmann}","page":"Generalized Grassmann","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::GeneralizedGrassmann)\ninjectivity_radius(M::GeneralizedGrassmann, p)\n\nReturn the injectivity radius on the GeneralizedGrassmann M, which is fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{GeneralizedGrassmann{n, k}, Any, Any, Any}} where {n, k}","page":"Generalized Grassmann","title":"ManifoldsBase.inner","text":"inner(M::GeneralizedGrassmann, p, X, Y)\n\nCompute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedGrassmann manifold M. The formula reads\n\ng_p(XY) = operatornametr(X^mathrmHBY)\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.is_flat-Tuple{GeneralizedGrassmann}","page":"Generalized Grassmann","title":"ManifoldsBase.is_flat","text":"is_flat(M::GeneralizedGrassmann)\n\nReturn true if GeneralizedGrassmann M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.manifold_dimension-Union{Tuple{GeneralizedGrassmann{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Generalized Grassmann","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::GeneralizedGrassmann)\n\nReturn the dimension of the GeneralizedGrassmann(n,k,𝔽) manifold M, i.e.\n\ndim operatornameGr(nkB) = k(n-k) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.project-Tuple{GeneralizedGrassmann, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.project","text":"project(M::GeneralizedGrassmann, p, X)\n\nProject the n-by-k X onto the tangent space of p on the GeneralizedGrassmann M, which is computed by\n\noperatornameproj_p(X) = X - pp^mathrmHB^mathrmTX\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian and cdot^mathrmT the transpose.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.project-Tuple{GeneralizedGrassmann, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.project","text":"project(M::GeneralizedGrassmann, p)\n\nProject p from the embedding onto the GeneralizedGrassmann M, i.e. compute q as the polar decomposition of p such that q^mathrmHBq is the identity, where cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.representation_size-Union{Tuple{GeneralizedGrassmann{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Generalized Grassmann","title":"ManifoldsBase.representation_size","text":"representation_size(M::GeneralizedGrassmann{n,k})\n\nReturn the represenation size or matrix dimension of a point on the GeneralizedGrassmann M, i.e. (nk) for both the real-valued and the complex value case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.retract-Tuple{GeneralizedGrassmann, Any, Any, PolarRetraction}","page":"Generalized Grassmann","title":"ManifoldsBase.retract","text":"retract(M::GeneralizedGrassmann, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the GeneralizedGrassmann M, by projecting p + X onto M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.zero_vector-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::GeneralizedGrassmann, p)\n\nReturn the zero tangent vector from the tangent space at p on the GeneralizedGrassmann M, which is given by a zero matrix the same size as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#Statistics.mean-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"Statistics.mean","text":"mean(\n M::GeneralizedGrassmann,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/4);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#Skew-hermitian-matrices","page":"Skew-Hermitian matrices","title":"Skew-hermitian matrices","text":"","category":"section"},{"location":"manifolds/skewhermitian.html","page":"Skew-Hermitian matrices","title":"Skew-Hermitian matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/SkewHermitian.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/skewhermitian.html#Manifolds.SkewHermitianMatrices","page":"Skew-Hermitian matrices","title":"Manifolds.SkewHermitianMatrices","text":"SkewHermitianMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe AbstractManifold $ \\operatorname{SkewHerm}(n)$ consisting of the real- or complex-valued skew-hermitian matrices of size n n, i.e. the set\n\noperatornameSkewHerm(n) = biglp 𝔽^n n big p^mathrmH = -p bigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ ℍ.\n\nThough it is slightly redundant, usually the matrices are stored as n n arrays.\n\nNote that in this representation, the real-valued part of the diagonal must be zero, which is also reflected in the manifold_dimension.\n\nConstructor\n\nSkewHermitianMatrices(n::Int, field::AbstractNumbers=ℝ)\n\nGenerate the manifold of n n skew-hermitian matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/skewhermitian.html#Manifolds.SkewSymmetricMatrices","page":"Skew-Hermitian matrices","title":"Manifolds.SkewSymmetricMatrices","text":"SkewSymmetricMatrices{n}\n\nGenerate the manifold of n n real skew-symmetric matrices. This is equivalent to SkewHermitianMatrices(n, ℝ).\n\nConstructor\n\nSkewSymmetricMatrices(n::Int)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{SkewHermitianMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.check_point","text":"check_point(M::SkewHermitianMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether p is a valid manifold point on the SkewHermitianMatrices M, i.e. whether p is a skew-hermitian matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.\n\nThe tolerance for the skew-symmetry of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.check_vector-Tuple{SkewHermitianMatrices, Any, Any}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::SkewHermitianMatrices{n}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SkewHermitianMatrices M, i.e. X must be a skew-hermitian matrix of size (n,n) and its values have to be from the correct AbstractNumbers. The tolerance for the skew-symmetry of p and X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.is_flat-Tuple{SkewHermitianMatrices}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::SkewHermitianMatrices)\n\nReturn true. SkewHermitianMatrices is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.manifold_dimension-Union{Tuple{SkewHermitianMatrices{N, 𝔽}}, Tuple{𝔽}, Tuple{N}} where {N, 𝔽}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SkewHermitianMatrices{n,𝔽})\n\nReturn the dimension of the SkewHermitianMatrices matrix M over the number system 𝔽, i.e.\n\ndim mathrmSkewHerm(nℝ) = fracn(n+1)2 dim_ℝ 𝔽 - n\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽. The first term corresponds to only the upper triangular elements of the matrix being unique, and the second term corresponds to the constraint that the real part of the diagonal be zero.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.project-Tuple{SkewHermitianMatrices, Any, Any}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.project","text":"project(M::SkewHermitianMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the SkewHermitianMatrices M,\n\noperatornameproj_p(X) = frac12 bigl( X - X^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.project-Tuple{SkewHermitianMatrices, Any}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.project","text":"project(M::SkewHermitianMatrices, p)\n\nProjects p from the embedding onto the SkewHermitianMatrices M, i.e.\n\noperatornameproj_operatornameSkewHerm(n)(p) = frac12 bigl( p - p^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Tucker","page":"Tucker","title":"Tucker manifold","text":"","category":"section"},{"location":"manifolds/tucker.html","page":"Tucker","title":"Tucker","text":"Modules = [Manifolds]\nPages = [\"Tucker.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/tucker.html#Manifolds.Tucker","page":"Tucker","title":"Manifolds.Tucker","text":"Tucker{N, R, D, 𝔽} <: AbstractManifold{𝔽}\n\nThe manifold of N_1 times dots times N_D real-valued or complex-valued tensors of fixed multilinear rank (R_1 dots R_D) . If R_1 = dots = R_D = 1, this is the Segre manifold, i.e., the set of rank-1 tensors.\n\nRepresentation in HOSVD format\n\nLet mathbbF be the real or complex numbers. Any tensor p on the Tucker manifold can be represented as a multilinear product in HOSVD [DeLathauwer2000] form\n\np = (U_1dotsU_D) cdot mathcalC\n\nwhere mathcal C in mathbbF^R_1 times dots times R_D and, for d=1dotsD, the matrix U_d in mathbbF^N_d times R_d contains the singular vectors of the dth unfolding of mathcalA\n\nTangent space\n\nThe tangent space to the Tucker manifold at p = (U_1dotsU_D) cdot mathcalC is [Koch2010]\n\nT_p mathcalM =\nbigl\n(U_1dotsU_D) cdot mathcalC^prime\n+ sum_d=1^D bigl(\n (U_1 dots U_d-1 U_d^prime U_d+1 dots U_D)\n cdot mathcalC\nbigr)\nbigr\n\nwhere mathcalC^prime is arbitrary, U_d^mathrmH is the Hermitian adjoint of U_d, and U_d^mathrmH U_d^prime = 0 for all d.\n\nConstructor\n\nTucker(N::NTuple{D, Int}, R::NTuple{D, Int}[, field = ℝ])\n\nGenerate the manifold of field-valued tensors of dimensions N[1] × … × N[D] and multilinear rank R = (R[1], …, R[D]).\n\n[DeLathauwer2000]: Lieven De Lathauwer, Bart De Moor, Joos Vandewalle: \"A multilinear singular value decomposition\" SIAM Journal on Matrix Analysis and Applications, 21(4), pp. 1253-1278, 2000 doi: 10.1137/S0895479896305696\n\n[Koch2010]: Othmar Koch, Christian Lubic, \"Dynamical Tensor approximation\" SIAM Journal on Matrix Analysis and Applications, 31(5), pp. 2360-2375, 2010 doi: 10.1137/09076578X\n\n\n\n\n\n","category":"type"},{"location":"manifolds/tucker.html#Manifolds.TuckerPoint","page":"Tucker","title":"Manifolds.TuckerPoint","text":"TuckerPoint{T,D}\n\nAn order D tensor of fixed multilinear rank and entries of type T, which makes it a point on the Tucker manifold. The tensor is represented in HOSVD form.\n\nConstructors:\n\nTuckerPoint(core::AbstractArray{T,D}, factors::Vararg{<:AbstractMatrix{T},D}) where {T,D}\n\nConstruct an order D tensor of element type T that can be represented as the multilinear product (factors[1], …, factors[D]) ⋅ core. It is assumed that the dimensions of the core are the multilinear rank of the tensor and that the matrices factors each have full rank. No further assumptions are made.\n\nTuckerPoint(p::AbstractArray{T,D}, mlrank::NTuple{D,Int}) where {T,D}\n\nThe low-multilinear rank tensor arising from the sequentially truncated the higher-order singular value decomposition of the D-dimensional array p of type T. The singular values are truncated to get a multilinear rank mlrank [Vannieuwenhoven2012].\n\n[Vannieuwenhoven2012]: Nick Vannieuwenhoven, Raf Vandebril, Karl Meerbergen: \"A new truncation strategy for the higher-order singular value decomposition\" SIAM Journal on Scientific Computing, 34(2), pp. 1027-1052, 2012 doi: 10.1137/110836067\n\n\n\n\n\n","category":"type"},{"location":"manifolds/tucker.html#Manifolds.TuckerTVector","page":"Tucker","title":"Manifolds.TuckerTVector","text":"TuckerTVector{T, D} <: TVector\n\nTangent vector to the D-th order Tucker manifold at p = (U_1dotsU_D) mathcalC. The numbers are of type T and the vector is represented as\n\nX =\n(U_1dotsU_D) cdot mathcalC^prime +\nsum_d=1^D (U_1dotsU_d-1U_d^primeU_d+1dotsU_D) cdot mathcalC\n\nwhere U_d^mathrmH U_d^prime = 0.\n\nConstructor\n\nTuckerTVector(C′::Array{T,D}, U′::NTuple{D,Matrix{T}}) where {T,D}\n\nConstructs a Dth order TuckerTVector of number type T with C^prime and U^prime, so that, together with a TuckerPoint p as above, the tangent vector can be represented as X in the above expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/tucker.html#Base.convert-Union{Tuple{D}, Tuple{T}, Tuple{𝔽}, Tuple{Type{Matrix{T}}, CachedBasis{𝔽, DefaultOrthonormalBasis{𝔽, ManifoldsBase.TangentSpaceType}, Manifolds.HOSVDBasis{T, D}}}} where {𝔽, T, D}","page":"Tucker","title":"Base.convert","text":"Base.convert(::Type{Matrix{T}}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}\nBase.convert(::Type{Matrix}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}\n\nConvert a HOSVD-derived cached basis from [Dewaele2021] of the Dth order Tucker manifold with number type T to a matrix. The columns of this matrix are the vectorisations of the embeddings of the basis vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Base.foreach","page":"Tucker","title":"Base.foreach","text":"Base.foreach(f, M::Tucker, p::TuckerPoint, basis::AbstractBasis, indices=1:manifold_dimension(M))\n\nLet basis be and AbstractBasis at a point p on M. Suppose f is a function that takes an index and a vector as an argument. This function applies f to i and the ith basis vector sequentially for each i in indices. Using a CachedBasis may speed up the computation.\n\nNOTE: The i'th basis vector is overwritten in each iteration. If any information about the vector is to be stored, f must make a copy.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/tucker.html#Base.ndims-Union{Tuple{TuckerPoint{T, D}}, Tuple{D}, Tuple{T}} where {T, D}","page":"Tucker","title":"Base.ndims","text":"Base.ndims(p::TuckerPoint{T,D}) where {T,D}\n\nThe order of the tensor corresponding to the TuckerPoint p, i.e., D.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Base.size-Tuple{TuckerPoint}","page":"Tucker","title":"Base.size","text":"Base.size(p::TuckerPoint)\n\nThe dimensions of a TuckerPoint p, when regarded as a full tensor (see embed).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.check_point-Union{Tuple{D}, Tuple{R}, Tuple{N}, Tuple{Tucker{N, R, D}, Any}} where {N, R, D}","page":"Tucker","title":"ManifoldsBase.check_point","text":"check_point(M::Tucker{N,R,D}, p; kwargs...) where {N,R,D}\n\nCheck whether the multidimensional array or TuckerPoint p is a point on the Tucker manifold, i.e. it is a Dth order N[1] × … × N[D] tensor of multilinear rank (R[1], …, R[D]). The keyword arguments are passed to the matrix rank function applied to the unfoldings. For a TuckerPoint it is checked that the point is in correct HOSVD form.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.check_vector-Union{Tuple{D}, Tuple{T}, Tuple{R}, Tuple{N}, Tuple{Tucker{N, R, D}, TuckerPoint{T, D}, TuckerTVector}} where {N, R, T, D}","page":"Tucker","title":"ManifoldsBase.check_vector","text":"check_vector(M::Tucker{N,R,D}, p::TuckerPoint{T,D}, X::TuckerTVector) where {N,R,T,D}\n\nCheck whether a TuckerTVector X is is in the tangent space to the Dth order Tucker manifold M at the Dth order TuckerPoint p. This is the case when the dimensions of the factors in X agree with those of p and the factor matrices of X are in the orthogonal complement of the HOSVD factors of p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.embed-Tuple{Tucker, Any, TuckerPoint}","page":"Tucker","title":"ManifoldsBase.embed","text":"embed(::Tucker{N,R,D}, p::TuckerPoint) where {N,R,D}\n\nConvert a TuckerPoint p on the rank R Tucker manifold to a full N[1] × … × N[D]-array by evaluating the Tucker decomposition.\n\nembed(::Tucker{N,R,D}, p::TuckerPoint, X::TuckerTVector) where {N,R,D}\n\nConvert a tangent vector X with base point p on the rank R Tucker manifold to a full tensor, represented as an N[1] × … × N[D]-array.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.get_basis-Union{Tuple{𝔽}, Tuple{Tucker, TuckerPoint}, Tuple{Tucker, TuckerPoint, DefaultOrthonormalBasis{𝔽, ManifoldsBase.TangentSpaceType}}} where 𝔽","page":"Tucker","title":"ManifoldsBase.get_basis","text":"get_basis(:: Tucker, p::TuckerPoint, basisType::DefaultOrthonormalBasis{𝔽, TangentSpaceType}) where 𝔽\n\nAn implicitly stored basis of the tangent space to the Tucker manifold. Assume p = (U_1dotsU_D) cdot mathcalC is in HOSVD format and that, for d=1dotsD, the singular values of the d'th unfolding are sigma_dj, with j = 1dotsR_d. The basis of the tangent space is as follows: [Dewaele2021]\n\nbigl\n(U_1dotsU_D) e_i\nbigr cup bigl\n(U_1dots sigma_dj^-1 U_d^perp e_i e_j^TdotsU_D) cdot mathcalC\nbigr\n\nfor all d = 1dotsD and all canonical basis vectors e_i and e_j. Every U_d^perp is such that U_d quad U_d^perp forms an orthonormal basis of mathbbR^N_d.\n\n[Dewaele2021]: Nick Dewaele, Paul Breiding, Nick Vannieuwenhoven, \"The condition number of many tensor decompositions is invariant under Tucker compression\" arxiv: 2106.13034\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.inner-Tuple{Tucker, TuckerPoint, TuckerTVector, TuckerTVector}","page":"Tucker","title":"ManifoldsBase.inner","text":"inner(M::Tucker, p::TuckerPoint, X::TuckerTVector, Y::TuckerTVector)\n\nThe Euclidean inner product between tangent vectors X and X at the point p on the Tucker manifold. This is equal to embed(M, p, X) ⋅ embed(M, p, Y).\n\ninner(::Tucker, A::TuckerPoint, X::TuckerTVector, Y)\ninner(::Tucker, A::TuckerPoint, X, Y::TuckerTVector)\n\nThe Euclidean inner product between X and Y where X is a vector tangent to the Tucker manifold at p and Y is a vector in the ambient space or vice versa. The vector in the ambient space is represented as a full tensor, i.e., a multidimensional array.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.inverse_retract-Tuple{Tucker, Any, TuckerPoint, TuckerPoint, ProjectionInverseRetraction}","page":"Tucker","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Tucker, p::TuckerPoint, q::TuckerPoint, ::ProjectionInverseRetraction)\n\nThe projection inverse retraction on the Tucker manifold interprets q as a point in the ambient Euclidean space (see embed) and projects it onto the tangent space at to M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.is_flat-Tuple{Tucker}","page":"Tucker","title":"ManifoldsBase.is_flat","text":"is_flat(::Tucker)\n\nReturn false. Tucker is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.manifold_dimension-Union{Tuple{Tucker{n⃗, r⃗}}, Tuple{r⃗}, Tuple{n⃗}} where {n⃗, r⃗}","page":"Tucker","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(::Tucker{N,R,D}) where {N,R,D}\n\nThe dimension of the manifold of N_1 times dots times N_D tensors of multilinear rank (R_1 dots R_D), i.e.\n\nmathrmdim(mathcalM) = prod_d=1^D R_d + sum_d=1^D R_d (N_d - R_d)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.project-Tuple{Tucker, Any, TuckerPoint, Any}","page":"Tucker","title":"ManifoldsBase.project","text":"project(M::Tucker, p::TuckerPoint, X)\n\nThe least-squares projection of a dense tensor X onto the tangent space to M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.retract-Tuple{Tucker, Any, Any, PolarRetraction}","page":"Tucker","title":"ManifoldsBase.retract","text":"retract(::Tucker, p::TuckerPoint, X::TuckerTVector, ::PolarRetraction)\n\nThe truncated HOSVD-based retraction [Kressner2014] to the Tucker manifold, i.e. the result is the sequentially tuncated HOSVD approximation of p + X.\n\nIn the exceptional case that the multilinear rank of p + X is lower than that of p, this retraction produces a boundary point, which is outside the manifold.\n\n[Kressner2014]: Daniel Kressner, Michael Steinlechner, Bart Vandereycken: \"Low-rank tensor completion by Riemannian optimization\" BIT Numerical Mathematics, 54(2), pp. 447-468, 2014 doi: 10.1007/s10543-013-0455-z\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.zero_vector-Tuple{Tucker, TuckerPoint}","page":"Tucker","title":"ManifoldsBase.zero_vector","text":"zero_vector(::Tucker, p::TuckerPoint)\n\nThe zero element in the tangent space to p on the Tucker manifold, represented as a TuckerTVector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Literature","page":"Tucker","title":"Literature","text":"","category":"section"},{"location":"manifolds/elliptope.html#Elliptope","page":"Elliptope","title":"Elliptope","text":"","category":"section"},{"location":"manifolds/elliptope.html","page":"Elliptope","title":"Elliptope","text":"Modules = [Manifolds]\nPages = [\"manifolds/Elliptope.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/elliptope.html#Manifolds.Elliptope","page":"Elliptope","title":"Manifolds.Elliptope","text":"Elliptope{N,K} <: AbstractDecoratorManifold{ℝ}\n\nThe Elliptope manifold, also known as the set of correlation matrices, consists of all symmetric positive semidefinite matrices of rank k with unit diagonal, i.e.,\n\nbeginaligned\nmathcal E(nk) =\nbiglp ℝ^n n big a^mathrmTpa geq 0 text for all a ℝ^n\np_ii = 1 text for all i=1ldotsn\ntextand p = qq^mathrmT text for q in ℝ^n k text with operatornamerank(p) = operatornamerank(q) = k\nbigr\nendaligned\n\nAnd this manifold is working solely on the matrices q. Note that this q is not unique, indeed for any orthogonal matrix A we have (qA)(qA)^mathrmT = qq^mathrmT = p, so the manifold implemented here is the quotient manifold. The unit diagonal translates to unit norm columns of q.\n\nThe tangent space at p, denoted T_pmathcal E(nk), is also represented by matrices Yin ℝ^n k and reads as\n\nT_pmathcal E(nk) = bigl\nX ℝ^n nX = qY^mathrmT + Yq^mathrmT text with X_ii = 0 text for i=1ldotsn\nbigr\n\nendowed with the Euclidean metric from the embedding, i.e. from the ℝ^n k\n\nThis manifold was for example investigated in[JourneeBachAbsilSepulchre2010].\n\nConstructor\n\nElliptope(n,k)\n\ngenerates the manifold mathcal E(nk) subset ℝ^n n.\n\n[JourneeBachAbsilSepulchre2010]: Journée, M., Bach, F., Absil, P.-A., and Sepulchre, R.: “Low-Rank Optimization on the Cone of Positive Semidefinite Matrices”, SIAM Journal on Optimization (20)5, pp. 2327–2351, 2010. doi: 10.1137/080731359, arXiv: 0807.4423.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/elliptope.html#ManifoldsBase.check_point-Union{Tuple{K}, Tuple{N}, Tuple{Elliptope{N, K}, Any}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.check_point","text":"check_point(M::Elliptope, q; kwargs...)\n\nchecks, whether q is a valid reprsentation of a point p=qq^mathrmT on the Elliptope M, i.e. is a matrix of size (N,K), such that p is symmetric positive semidefinite and has unit trace. Since by construction p is symmetric, this is not explicitly checked. Since p is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.check_vector-Union{Tuple{K}, Tuple{N}, Tuple{Elliptope{N, K}, Any, Any}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.check_vector","text":"check_vector(M::Elliptope, q, Y; kwargs... )\n\nCheck whether X = qY^mathrmT + Yq^mathrmT is a tangent vector to p=qq^mathrmT on the Elliptope M, i.e. Y has to be of same dimension as q and a X has to be a symmetric matrix with zero diagonal.\n\nThe tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetric of X holds by construction an is not explicitly checked.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.is_flat-Tuple{Elliptope}","page":"Elliptope","title":"ManifoldsBase.is_flat","text":"is_flat(::Elliptope)\n\nReturn false. Elliptope is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.manifold_dimension-Union{Tuple{Elliptope{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Elliptope)\n\nreturns the dimension of Elliptope M=mathcal E(nk) nk ℕ, i.e.\n\ndim mathcal E(nk) = n(k-1) - frack(k-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.project-Tuple{Elliptope, Any}","page":"Elliptope","title":"ManifoldsBase.project","text":"project(M::Elliptope, q)\n\nproject q onto the manifold Elliptope M, by normalizing the rows of q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.project-Tuple{Elliptope, Vararg{Any}}","page":"Elliptope","title":"ManifoldsBase.project","text":"project(M::Elliptope, q, Y)\n\nProject Y onto the tangent space at q, i.e. row-wise onto the oblique manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.representation_size-Union{Tuple{Elliptope{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.representation_size","text":"representation_size(M::Elliptope)\n\nReturn the size of an array representing an element on the Elliptope manifold M, i.e. n k, the size of such factor of p=qq^mathrmT on mathcal M = mathcal E(nk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.retract-Tuple{Elliptope, Any, Any, ProjectionRetraction}","page":"Elliptope","title":"ManifoldsBase.retract","text":"retract(M::Elliptope, q, Y, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting q+Y back onto the manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.vector_transport_to-Tuple{Elliptope, Any, Any, Any, ProjectionTransport}","page":"Elliptope","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Elliptope, p, X, q)\n\ntransport the tangent vector X at p to q by projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.zero_vector-Tuple{Elliptope, Vararg{Any}}","page":"Elliptope","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Elliptope,p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the Elliptope manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#Literature","page":"Elliptope","title":"Literature","text":"","category":"section"},{"location":"manifolds/multinomial.html#Multinomial-matrices","page":"Multinomial matrices","title":"Multinomial matrices","text":"","category":"section"},{"location":"manifolds/multinomial.html","page":"Multinomial matrices","title":"Multinomial matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Multinomial.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/multinomial.html#Manifolds.MultinomialMatrices","page":"Multinomial matrices","title":"Manifolds.MultinomialMatrices","text":"MultinomialMatrices{n,m} <: AbstractPowerManifold{ℝ}\n\nThe multinomial manifold consists of m column vectors, where each column is of length n and unit norm, i.e.\n\nmathcalMN(nm) coloneqq bigl p ℝ^nm big p_ij 0 text for all i=1n j=1m text and p^mathrmTmathbb1_m = mathbb1_nbigr\n\nwhere mathbb1_k is the vector of length k containing ones.\n\nThis yields exactly the same metric as considering the product metric of the probablity vectors, i.e. PowerManifold of the (n-1)-dimensional ProbabilitySimplex.\n\nThe ProbabilitySimplex is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.\n\nConstructor\n\nMultinomialMatrices(n, m)\n\nGenerate the manifold of matrices mathbb R^nm such that the m columns are discrete probability distributions, i.e. sum up to one.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomial.html#Functions","page":"Multinomial matrices","title":"Functions","text":"","category":"section"},{"location":"manifolds/multinomial.html","page":"Multinomial matrices","title":"Multinomial matrices","text":"Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:","category":"page"},{"location":"manifolds/multinomial.html","page":"Multinomial matrices","title":"Multinomial matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Multinomial.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/multinomial.html#ManifoldsBase.check_point-Tuple{MultinomialMatrices, Any}","page":"Multinomial matrices","title":"ManifoldsBase.check_point","text":"check_point(M::MultinomialMatrices, p)\n\nChecks whether p is a valid point on the MultinomialMatrices(m,n) M, i.e. is a matrix of m discrete probability distributions as columns from mathbb R^n, i.e. each column is a point from ProbabilitySimplex(n-1).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomial.html#ManifoldsBase.check_vector-Union{Tuple{m}, Tuple{n}, Tuple{MultinomialMatrices{n, m}, Any, Any}} where {n, m}","page":"Multinomial matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::MultinomialMatrices p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the MultinomialMatrices M. This means, that p is valid, that X is of correct dimension and columnswise a tangent vector to the columns of p on the ProbabilitySimplex.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Symplectic","page":"Symplectic","title":"Symplectic","text":"","category":"section"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"The Symplectic manifold, denoted operatornameSp(2n mathbbF), is a closed, embedded, submanifold of mathbbF^2n times 2n that represents transformations into symplectic subspaces which keep the canonical symplectic form over mathbbF^2n times 2n invariant under the standard embedding inner product. The canonical symplectic form is a non-degenerate bilinear and skew symmetric map omegacolon mathbbF^2n times mathbbF^2n rightarrow mathbbF, given by omega(x y) = x^T Q_2n y for elements x y in mathbbF^2n, with","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":" Q_2n = \n beginbmatrix\n 0_n I_n \n -I_n 0_n\n endbmatrix","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"That means that an element p in operatornameSp(2n) must fulfill the requirement that ","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":" omega (p x p y) = x^T(p^TQp)y = x^TQy = omega(x y)","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"leading to the requirement on p that p^TQp = Q.","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"The symplectic manifold also forms a group under matrix multiplication, called the textitsymplectic group. Since all the symplectic matrices necessarily have determinant one, the symplectic group operatornameSp(2n mathbbF) is a subgroup of the special linear group, operatornameSL(2n mathbbF). When the underlying field is either mathbbR or mathbbC the symplectic group with a manifold structure constitutes a Lie group, with the Lie Algebra ","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":" mathfraksp(2nF) = H in mathbbF^2n times 2n Q H + H^T Q = 0","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"This set is also known as the Hamiltonian matrices, which have the property that (QH)^T = QH and are commonly used in physics.","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"Modules = [Manifolds]\nPages = [\"manifolds/Symplectic.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symplectic.html#Manifolds.ExtendedSymplecticMetric","page":"Symplectic","title":"Manifolds.ExtendedSymplecticMetric","text":"ExtendedSymplecticMetric <: AbstractMetric\n\nThe extension of the RealSymplecticMetric at a point p \\in \\operatorname{Sp}(2n) as an inner product over the embedding space ℝ^2n times 2n, i.e.\n\n langle x y rangle_p = langle p^-1x p^-1rangle_operatornameFr\n = operatornametr(x^mathrmT(pp^mathrmT)^-1y) forall x y in ℝ^2n times 2n\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Manifolds.RealSymplecticMetric","page":"Symplectic","title":"Manifolds.RealSymplecticMetric","text":"RealSymplecticMetric <: RiemannianMetric\n\nThe canonical Riemannian metric on the symplectic manifold, defined pointwise for p in operatornameSp(2n) by [Fiori2011]\n\nbeginalign*\n g_p colon T_poperatornameSp(2n) times T_poperatornameSp(2n) rightarrow ℝ \n g_p(Z_1 Z_2) = operatornametr((p^-1Z_1)^mathrmT (p^-1Z_2))\nendalign*\n\nThis metric is also the default metric for the Symplectic manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Manifolds.Symplectic","page":"Symplectic","title":"Manifolds.Symplectic","text":"Symplectic{n, 𝔽} <: AbstractEmbeddedManifold{𝔽, DefaultIsometricEmbeddingType}\n\nThe symplectic manifold consists of all 2n times 2n matrices which preserve the canonical symplectic form over 𝔽^2n 2n times 𝔽^2n 2n,\n\n omegacolon 𝔽^2n 2n times 𝔽^2n 2n rightarrow 𝔽\n quad omega(x y) = p^mathrmT Q_2n q x y in 𝔽^2n 2n\n\nwhere\n\nQ_2n =\nbeginbmatrix\n 0_n I_n \n -I_n 0_n\nendbmatrix\n\nThat is, the symplectic manifold consists of\n\noperatornameSp(2n ℝ) = bigl p ℝ^2n 2n big p^mathrmTQ_2np = Q_2n bigr\n\nwith 0_n and I_n denoting the n n zero-matrix and indentity matrix in ℝ^n times n respectively.\n\nThe tangent space at a point p is given by [BendokatZimmermann2021]\n\nbeginalign*\n T_poperatornameSp(2n)\n = X in mathbbR^2n times 2n p^TQ_2nX + X^TQ_2np = 0 \n = X = pQS S R^2n 2n S^mathrmT = S \nendalign*\n\nConstructor\n\nSymplectic(2n, field=ℝ) -> Symplectic{div(2n, 2), field}()\n\nGenerate the (real-valued) symplectic manifold of 2n times 2n symplectic matrices. The constructor for the Symplectic manifold accepts the even column/row embedding dimension 2n for the real symplectic manifold, ℝ^2n 2n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Manifolds.SymplecticMatrix","page":"Symplectic","title":"Manifolds.SymplecticMatrix","text":"SymplecticMatrix{T}\n\nA lightweight structure to represent the action of the matrix representation of the canonical symplectic form,\n\nQ_2n(λ) = λ\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix quad in ℝ^2n times 2n\n\nsuch that the canonical symplectic form is represented by\n\nomega_2n(x y) = x^mathrmTQ_2n(1)y quad x y in ℝ^2n\n\nThe entire matrix is however not instantiated in memory, instead a scalar λ of type T is stored, which is used to keep track of scaling and transpose operations applied to each SymplecticMatrix. For example, given Q = SymplecticMatrix(1.0) represented as 1.0*[0 I; -I 0], the adjoint Q' returns SymplecticMatrix(-1.0) = (-1.0)*[0 I; -I 0].\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Base.exp-Tuple{Symplectic, Vararg{Any}}","page":"Symplectic","title":"Base.exp","text":"exp(M::Symplectic, p, X)\nexp!(M::Symplectic, q, p, X)\n\nThe Exponential mapping on the Symplectic manifold with the RealSymplecticMetric Riemannian metric.\n\nFor the point p in operatornameSp(2n) the exponential mapping along the tangent vector X in T_poperatornameSp(2n) is computed as [WangSunFiori2018]\n\n operatornameexp_p(X) = p operatornameExp((p^-1X)^mathrmT)\n operatornameExp(p^-1X - (p^-1X)^mathrmT)\n\nwhere operatornameExp(cdot) denotes the matrix exponential.\n\n[WangSunFiori2018]: Wang, Jing and Sun, Huafei and Fiori, Simone: A Riemannian-steepest-descent approach for optimization on the real symplectic group, Mathematical Methods in the Applied Sciences, 41(11) pp. 4273-4286, 2018 doi 10.1002/mma.4890\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Base.inv-Union{Tuple{n}, Tuple{Symplectic{n, ℝ}, Any}} where n","page":"Symplectic","title":"Base.inv","text":"inv(::Symplectic, A)\ninv!(::Symplectic, A)\n\nCompute the symplectic inverse A^+ of matrix A ℝ^2n 2n. Given a matrix\n\nA ℝ^2n 2nquad\nA =\nbeginbmatrix\nA_11 A_12 \nA_21 A_2 2\nendbmatrix\n\nthe symplectic inverse is defined as:\n\nA^+ = Q_2n^mathrmT A^mathrmT Q_2n\n\nwhere\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe symplectic inverse of A can be expressed explicitly as:\n\nA^+ =\nbeginbmatrix\n A_2 2^mathrmT -A_1 2^mathrmT 12mm\n -A_2 1^mathrmT A_1 1^mathrmT\nendbmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Base.rand-Tuple{Symplectic}","page":"Symplectic","title":"Base.rand","text":"rand(::SymplecticStiefel; vector_at=nothing,\n hamiltonian_norm = (vector_at === nothing ? 1/2 : 1.0))\n\nGenerate a random point on operatornameSp(2n) or a random tangent vector X in T_poperatornameSp(2n) if vector_at is set to a point p in operatornameSp(2n).\n\nA random point on operatornameSp(2n) is constructed by generating a random Hamiltonian matrix Ω in mathfraksp(2nF) with norm hamiltonian_norm, and then transforming it to a symplectic matrix by applying the Cayley transform\n\n operatornamecaycolon mathfraksp(2nF) rightarrow operatornameSp(2n)\n Omega mapsto (I - Omega)^-1(I + Omega)\n\nTo generate a random tangent vector in T_poperatornameSp(2n), this code employs the second tangent vector space parametrization of Symplectic. It first generates a random symmetric matrix S by S = randn(2n, 2n) and then symmetrizes it as S = S + S'. Then S is normalized to have Frobenius norm of hamiltonian_norm and X = pQS is returned, where Q is the SymplecticMatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldDiff.gradient-Tuple{Symplectic, Any, Any, ManifoldDiff.RiemannianProjectionBackend}","page":"Symplectic","title":"ManifoldDiff.gradient","text":"gradient(M::Symplectic, f, p, backend::RiemannianProjectionBackend;\n extended_metric=true)\ngradient!(M::Symplectic, f, p, backend::RiemannianProjectionBackend;\n extended_metric=true)\n\nCompute the manifold gradient textgradf(p) of a scalar function f colon operatornameSp(2n) rightarrow ℝ at p in operatornameSp(2n).\n\nThe element textgradf(p) is found as the Riesz representer of the differential textDf(p) colon T_poperatornameSp(2n) rightarrow ℝ w.r.t. the Riemannian metric inner product at p [Fiori2011]. That is, textgradf(p) in T_poperatornameSp(2n) solves the relation\n\n g_p(textgradf(p) X) = textDf(p) quadforall X in T_poperatornameSp(2n)\n\nThe default behaviour is to first change the representation of the Euclidean gradient from the Euclidean metric to the RealSymplecticMetric at p, and then we projecting the result onto the correct tangent tangent space T_poperatornameSp(2n ℝ) w.r.t the Riemannian metric g_p extended to the entire embedding space.\n\nArguments:\n\nextended_metric = true: If true, compute the gradient textgradf(p) by first changing the representer of the Euclidean gradient of a smooth extension of f, f(p), w.r.t. the RealSymplecticMetric at p extended to the entire embedding space, before projecting onto the correct tangent vector space w.r.t. the same extended metric g_p. If false, compute the gradient by first projecting f(p) onto the tangent vector space, before changing the representer in the tangent vector space to comply with the RealSymplecticMetric.\n\n[Fiori2011]: Simone Fiori: Solving minimal-distance problems over the manifold of real-symplectic matrices, SIAM Journal on Matrix Analysis and Applications 32(3), pp. 938-968, 2011. doi 10.1137/100817115.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Manifolds.project_normal!-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric}, Any, Any, Any}} where {m, n, 𝔽}","page":"Symplectic","title":"Manifolds.project_normal!","text":"project_normal!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X)\n\nProject onto the normal of the tangent space (T_poperatornameSp(2n))^perp_g at a point p operatornameSp(2n), relative to the riemannian metric g RealSymplecticMetric. That is,\n\n(T_poperatornameSp(2n))^perp_g = Y in mathbbR^2n times 2n \n g_p(Y X) = 0 forall X in T_poperatornameSp(2n)\n\nThe closed form projection operator onto the normal space is given by [GaoSonAbsilStykel2021]\n\noperatornameP^(T_poperatornameSp(2n))perp_g_p(X) = pQoperatornameskew(p^mathrmTQ^mathrmTX)\n\nwhere operatornameskew(A) = frac12(A - A^mathrmT). This function is not exported.\n\n[GaoSonAbsilStykel2021]: Gao, Bin and Son, Nguyen Thanh and Absil, P-A and Stykel, Tatjana: Riemannian optimization on the symplectic Stiefel manifold, SIAM Journal on Optimization 31(2), pp. 1546-1575, 2021. doi 10.1137/20M1348522\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Manifolds.symplectic_inverse_times-Union{Tuple{n}, Tuple{Symplectic{n}, Any, Any}} where n","page":"Symplectic","title":"Manifolds.symplectic_inverse_times","text":"symplectic_inverse_times(::Symplectic, p, q)\nsymplectic_inverse_times!(::Symplectic, A, p, q)\n\nDirectly compute the symplectic inverse of p in operatornameSp(2n), multiplied with q in operatornameSp(2n). That is, this function efficiently computes p^+q = (Q_2np^mathrmTQ_2n)q in ℝ^2n times 2n, where Q_2n is the SymplecticMatrix of size 2n times 2n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.change_representer-Tuple{Symplectic, EuclideanMetric, Any, Any}","page":"Symplectic","title":"ManifoldsBase.change_representer","text":"change_representer(::Symplectic, ::EuclideanMetric, p, X)\nchange_representer!(::Symplectic, Y, ::EuclideanMetric, p, X)\n\nCompute the representation of a tangent vector ξ T_poperatornameSp(2n ℝ) s.t.\n\n g_p(c_p(ξ) η) = ξ η^textEuc η T_poperatornameSp(2n ℝ)\n\nwith the conversion function\n\n c_p T_poperatornameSp(2n ℝ) rightarrow T_poperatornameSp(2n ℝ) quad\n c_p(ξ) = frac12 pp^mathrmT ξ + frac12 pQ ξ^mathrmT pQ\n\nEach of the terms c_p^1(ξ) = p p^mathrmT ξ and c_p^2(ξ) = pQ ξ^mathrmT pQ from the above definition of c_p(η) are themselves metric compatible in the sense that\n\n c_p^i T_poperatornameSp(2n ℝ) rightarrow mathbbR^2n times 2nquad\n g_p^i(c_p(ξ) η) = ξ η^textEuc η T_poperatornameSp(2n ℝ)\n\nfor i in 1 2. However the range of each function alone is not confined to T_poperatornameSp(2n ℝ), but the convex combination\n\n c_p(ξ) = frac12c_p^1(ξ) + frac12c_p^2(ξ)\n\ndoes have the correct range T_poperatornameSp(2n ℝ).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.change_representer-Union{Tuple{n}, Tuple{m}, Tuple{𝔽}, Tuple{MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric}, EuclideanMetric, Any, Any}} where {𝔽, m, n}","page":"Symplectic","title":"ManifoldsBase.change_representer","text":"change_representer(MetMan::MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric},\n EucMet::EuclideanMetric, p, X)\nchange_representer!(MetMan::MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric},\n Y, EucMet::EuclideanMetric, p, X)\n\nChange the representation of a matrix ξ mathbbR^2n times 2n into the inner product space (ℝ^2n times 2n g_p) where the inner product is given by g_p(ξ η) = langle p^-1ξ p^-1η rangle = operatornametr(ξ^mathrmT(pp^mathrmT)^-1η), as the extension of the RealSymplecticMetric onto the entire embedding space.\n\nBy changing the representation we mean to apply a mapping\n\n c_p mathbbR^2n times 2n rightarrow mathbbR^2n times 2n\n\ndefined by requiring that it satisfy the metric compatibility condition\n\n g_p(c_p(ξ) η) = p^-1c_p(ξ) p^-1η = ξ η^textEuc\n η T_poperatornameSp(2n ℝ)\n\nIn this case, we compute the mapping\n\n c_p(ξ) = pp^mathrmT ξ\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.check_point-Union{Tuple{ℝ}, Tuple{n}, Tuple{Symplectic{n, ℝ}, Any}} where {n, ℝ}","page":"Symplectic","title":"ManifoldsBase.check_point","text":"check_point(M::Symplectic, p; kwargs...)\n\nCheck whether p is a valid point on the Symplectic M=operatornameSp(2n), i.e. that it has the right AbstractNumbers type and p^+p is (approximately) the identity, where A^+ = Q_2n^mathrmTA^mathrmTQ_2n is the symplectic inverse, with\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.check_vector-Tuple{Symplectic, Vararg{Any}}","page":"Symplectic","title":"ManifoldsBase.check_vector","text":"check_vector(M::Symplectic, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector at p on the Symplectic M=operatornameSp(2n), i.e. the AbstractNumbers fits and it (approximately) holds that p^TQ_2nX + X^TQ_2np = 0, where\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.distance-Union{Tuple{n}, Tuple{Symplectic{n}, Any, Any}} where n","page":"Symplectic","title":"ManifoldsBase.distance","text":"distance(M::Symplectic, p, q)\n\nCompute an approximate geodesic distance between two Symplectic matrices p q in operatornameSp(2n), as done in [WangSunFiori2018].\n\n operatornamedist(p q)\n operatornameLog(p^+q)_operatornameFr\n\nwhere the operatornameLog(cdot) operator is the matrix logarithm.\n\nThis approximation is justified by first recalling the Baker-Campbell-Hausdorf formula,\n\noperatornameLog(operatornameExp(A)operatornameExp(B))\n = A + B + frac12A B + frac112A A B + frac112B B A\n + ldots \n\nThen we write the expression for the exponential map from p to q as\n\n q =\n operatornameexp_p(X)\n =\n p operatornameExp((p^+X)^mathrmT)\n operatornameExp(p^+X - (p^+X)^mathrmT)\n X in T_poperatornameSp\n\nand with the geodesic distance between p and q given by operatornamedist(p q) = X_p = p^+X_operatornameFr we see that\n\n beginalign*\n operatornameLog(p^+q)_operatornameFr\n = operatornameLogleft(\n operatornameExp((p^+X)^mathrmT)\n operatornameExp(p^+X - (p^+X)^mathrmT)\n right)_operatornameFr \n = p^+X + frac12(p^+X)^mathrmT p^+X - (p^+X)^mathrmT\n + ldots _operatornameFr \n p^+X_operatornameFr = operatornamedist(p q)\n endalign*\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.inner-Union{Tuple{n}, Tuple{Symplectic{n, ℝ}, Any, Any, Any}} where n","page":"Symplectic","title":"ManifoldsBase.inner","text":"inner(::Symplectic{n, ℝ}, p, X, Y)\n\nCompute the canonical Riemannian inner product RealSymplecticMetric\n\n g_p(X Y) = operatornametr((p^-1X)^mathrmT (p^-1Y))\n\nbetween the two tangent vectors X Y in T_poperatornameSp(2n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.inverse_retract-Tuple{Symplectic, Any, Any, CayleyInverseRetraction}","page":"Symplectic","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Symplectic, p, q, ::CayleyInverseRetraction)\n\nCompute the Cayley Inverse Retraction X = mathcalL_p^operatornameSp(q) such that the Cayley Retraction from p along X lands at q, i.e. mathcalR_p(X) = q [BendokatZimmermann2021].\n\nFirst, recall the definition the standard symplectic matrix\n\nQ =\nbeginbmatrix\n 0 I \n-I 0\nendbmatrix\n\nas well as the symplectic inverse of a matrix A, A^+ = Q^mathrmT A^mathrmT Q.\n\nFor p q operatornameSp(2n ℝ) then, we can then define the inverse cayley retraction as long as the following matrices exist.\n\n U = (I + p^+ q)^-1 quad V = (I + q^+ p)^-1\n\nIf that is the case, the inverse cayley retration at p applied to q is\n\nmathcalL_p^operatornameSp(q) = 2pbigl(V - Ubigr) + 2bigl((p + q)U - pbigr)\n T_poperatornameSp(2n)\n\n[BendokatZimmermann2021]: Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.is_flat-Tuple{Symplectic}","page":"Symplectic","title":"ManifoldsBase.is_flat","text":"is_flat(::Symplectic)\n\nReturn false. Symplectic is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.manifold_dimension-Union{Tuple{Symplectic{n}}, Tuple{n}} where n","page":"Symplectic","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(::Symplectic{n})\n\nReturns the dimension of the symplectic manifold embedded in ℝ^2n times 2n, i.e.\n\n operatornamedim(operatornameSp(2n)) = (2n + 1)n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.project!-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric}, Any, Any, Any}} where {m, n, 𝔽}","page":"Symplectic","title":"ManifoldsBase.project!","text":"project!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X) where {𝔽}\n\nCompute the projection of X R^2n 2n onto T_poperatornameSp(2n ℝ) w.r.t. the Riemannian metric g RealSymplecticMetric. The closed form projection mapping is given by [GaoSonAbsilStykel2021]\n\n operatornameP^T_poperatornameSp(2n)_g_p(X) = pQoperatornamesym(p^mathrmTQ^mathrmTX)\n\nwhere operatornamesym(A) = frac12(A + A^mathrmT). This function is not exported.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.project-Tuple{Symplectic, Any, Any}","page":"Symplectic","title":"ManifoldsBase.project","text":"project(::Symplectic, p, A)\nproject!(::Symplectic, Y, p, A)\n\nGiven a point p in operatornameSp(2n), project an element A in mathbbR^2n times 2n onto the tangent space T_poperatornameSp(2n) relative to the euclidean metric of the embedding mathbbR^2n times 2n.\n\nThat is, we find the element X in T_poperatornameSpSt(2n 2k) which solves the constrained optimization problem\n\n operatornamemin_X in mathbbR^2n times 2n frac12X - A^2 quad\n textst\n h(X) colon= X^mathrmT Q p + p^mathrmT Q X = 0\n\nwhere hcolonmathbbR^2n times 2n rightarrow operatornameskew(2n) defines the restriction of X onto the tangent space T_poperatornameSpSt(2n 2k).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.retract-Tuple{Symplectic, Any, Any}","page":"Symplectic","title":"ManifoldsBase.retract","text":"retract(::Symplectic, p, X, ::CayleyRetraction)\nretract!(::Symplectic, q, p, X, ::CayleyRetraction)\n\nCompute the Cayley retraction on p operatornameSp(2n ℝ) in the direction of tangent vector X T_poperatornameSp(2n ℝ), as defined in by Birtea et al in proposition 2 [BirteaCaşuComănescu2020].\n\nUsing the symplectic inverse of a matrix A in ℝ^2n times 2n, A^+ = Q_2n^mathrmT A^mathrmT Q_2n where\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nthe retraction mathcalRcolon ToperatornameSp(2n) rightarrow operatornameSp(2n) is defined pointwise as\n\nbeginalign*\nmathcalR_p(X) = p operatornamecayleft(frac12p^+Xright) \n = p operatornameexp_11(p^+X) \n = p (2I - p^+X)^-1(2I + p^+X)\nendalign*\n\nHere operatornameexp_11(z) = (2 - z)^-1(2 + z) denotes the Padé (1, 1) approximation to operatornameexp(z).\n\n[BirteaCaşuComănescu2020]: Birtea, Petre and Caşu, Ioan and Comănescu, Dan: Optimization on the real symplectic group, Monatshefte f{\"u}r Mathematik, Springer, 2020. doi 10.1007/s00605-020-01369-9\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Literature","page":"Symplectic","title":"Literature","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html#SymmetricPositiveDefiniteSection","page":"Symmetric positive definite","title":"Symmetric positive definite matrices","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"SymmetricPositiveDefinite","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.SymmetricPositiveDefinite","page":"Symmetric positive definite","title":"Manifolds.SymmetricPositiveDefinite","text":"SymmetricPositiveDefinite{N} <: AbstractDecoratorManifold{ℝ}\n\nThe manifold of symmetric positive definite matrices, i.e.\n\nmathcal P(n) =\nbigl\np ℝ^n n big a^mathrmTpa 0 text for all a ℝ^nbackslash0\nbigr\n\nThe tangent space at T_pmathcal P(n) reads\n\n T_pmathcal P(n) =\n bigl\n X in mathbb R^nn big X=X^mathrmT\n bigr\n\ni.e. the set of symmetric matrices,\n\nConstructor\n\nSymmetricPositiveDefinite(n)\n\ngenerates the manifold mathcal P(n) subset ℝ^n n\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"This manifold can – for example – be illustrated as ellipsoids: since the eigenvalues are all positive they can be taken as lengths of the axes of an ellipsoids while the directions are given by the eigenvectors.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"(Image: An example set of data)","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"The manifold can be equipped with different metrics","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Common-and-metric-independent-functions","page":"Symmetric positive definite","title":"Common and metric independent functions","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefinite.jl\"]\nOrder = [:function]\nPublic=true\nPrivate=false\nFilter = t -> t !== mean","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Base.convert-Tuple{Type{AbstractMatrix}, SPDPoint}","page":"Symmetric positive definite","title":"Base.convert","text":"convert(::Type{AbstractMatrix}, p::SPDPoint)\n\nreturn the point p as a matrix. The matrix is either stored within the SPDPoint or reconstructed from p.eigen.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.rand-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"Base.rand","text":"rand(M::SymmetricPositiveDefinite; σ::Real=1)\n\nGenerate a random symmetric positive definite matrix on the SymmetricPositiveDefinite manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.check_point-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.check_point","text":"check_point(M::SymmetricPositiveDefinite, p; kwargs...)\n\nchecks, whether p is a valid point on the SymmetricPositiveDefinite M, i.e. is a matrix of size (N,N), symmetric and positive definite. The tolerance for the second to last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.check_vector-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.check_vector","text":"check_vector(M::SymmetricPositiveDefinite, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the SymmetricPositiveDefinite M, i.e. atfer check_point(M,p), X has to be of same dimension as p and a symmetric matrix, i.e. this stores tangent vetors as elements of the corresponding Lie group. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.injectivity_radius-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::SymmetricPositiveDefinite[, p])\ninjectivity_radius(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}[, p])\ninjectivity_radius(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}[, p])\n\nReturn the injectivity radius of the SymmetricPositiveDefinite. Since M is a Hadamard manifold with respect to the AffineInvariantMetric and the LogCholeskyMetric, the injectivity radius is globally .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::SymmetricPositiveDefinite)\n\nReturn false. SymmetricPositiveDefinite is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.manifold_dimension-Union{Tuple{SymmetricPositiveDefinite{N}}, Tuple{N}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SymmetricPositiveDefinite)\n\nreturns the dimension of SymmetricPositiveDefinite M=mathcal P(n) n ℕ, i.e.\n\ndim mathcal P(n) = fracn(n+1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.project-Tuple{SymmetricPositiveDefinite, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.project","text":"project(M::SymmetricPositiveDefinite, p, X)\n\nproject a matrix from the embedding onto the tangent space T_pmathcal P(n) of the SymmetricPositiveDefinite matrices, i.e. the set of symmetric matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.representation_size-Union{Tuple{SymmetricPositiveDefinite{N}}, Tuple{N}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.representation_size","text":"representation_size(M::SymmetricPositiveDefinite)\n\nReturn the size of an array representing an element on the SymmetricPositiveDefinite manifold M, i.e. n n, the size of such a symmetric positive definite matrix on mathcal M = mathcal P(n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.zero_vector-Tuple{SymmetricPositiveDefinite, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::SymmetricPositiveDefinite, p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the SymmetricPositiveDefinite manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Default-metric:-the-affine-invariant-metric","page":"Symmetric positive definite","title":"Default metric: the affine invariant metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteAffineInvariant.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.AffineInvariantMetric","page":"Symmetric positive definite","title":"Manifolds.AffineInvariantMetric","text":"AffineInvariantMetric <: AbstractMetric\n\nThe linear affine metric is the metric for symmetric positive definite matrices, that employs matrix logarithms and exponentials, which yields a linear and affine metric.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"This metric is also the default metric, i.e. any call of the following functions with P=SymmetricPositiveDefinite(3) will result in MetricManifold(P,AffineInvariantMetric())and hence yield the formulae described in this seciton.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteAffineInvariant.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{SymmetricPositiveDefinite, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(M::SymmetricPositiveDefinite, p, X)\nexp(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, X)\n\nCompute the exponential map from p with tangent vector X on the SymmetricPositiveDefinite M with its default MetricManifold having the AffineInvariantMetric. The formula reads\n\nexp_p X = p^frac12operatornameExp(p^-frac12 X p^-frac12)p^frac12\n\nwhere operatornameExp denotes to the matrix exponential.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{SymmetricPositiveDefinite, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.log","text":"log(M::SymmetricPositiveDefinite, p, q)\nlog(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)\n\nCompute the logarithmic map from p to q on the SymmetricPositiveDefinite as a MetricManifold with AffineInvariantMetric. The formula reads\n\nlog_p q =\np^frac12operatornameLog(p^-frac12qp^-frac12)p^frac12\n\nwhere operatornameLog denotes to the matrix logarithm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.manifold_volume-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"Manifolds.manifold_volume","text":"manifold_volume(::SymmetricPositiveDefinite)\n\nReturn volume of the SymmetricPositiveDefinite manifold, i.e. infinity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.volume_density-Union{Tuple{n}, Tuple{SymmetricPositiveDefinite{n}, Any, Any}} where n","page":"Symmetric positive definite","title":"Manifolds.volume_density","text":"volume_density(::SymmetricPositiveDefinite{n}, p, X) where {n}\n\nCompute the volume density of the SymmetricPositiveDefinite manifold at p in direction X. See [ChevallierKalungaAngulo2017], Section 6.2 for details. Note that metric in Manifolds.jl has a different scaling factor than the reference.\n\n[ChevallierKalungaAngulo2017]: E. Chevallier, E. Kalunga, and J. Angulo, “Kernel Density Estimation on Spaces of Gaussian Distributions and Symmetric Positive Definite Matrices,” SIAM J. Imaging Sci., vol. 10, no. 1, pp. 191–215, Jan. 2017, doi: 10.1137/15M1053566.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_metric-Tuple{SymmetricPositiveDefinite, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_metric","text":"change_metric(M::SymmetricPositiveDefinite{n}, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal P(n) with respect to the EuclideanMetric g_E, this function changes into the AffineInvariantMetric (default) metric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ccolon T_pmathcal P(n) to T_pmathcal P(n) such that for all YZ T_pmathcal P(n)` it holds\n\nYZ = operatornametr(YZ) = operatornametr(p^-1c(Y)p^-1c(Z)) = g_p(c(Z)c(Y))\n\nand hence c(X) = pX is computed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_representer-Tuple{SymmetricPositiveDefinite, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_representer","text":"change_representer(M::SymmetricPositiveDefinite, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the AffineInvariantMetric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ZT_pmathcal P(n) such that for all YT_pmathcal P(n)` it holds\n\nXY = operatornametr(XY) = operatornametr(p^-1Zp^-1Y) = g_p(ZY)\n\nand hence Z = pXp.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(M::SymmetricPositiveDefinite, p, q)\ndistance(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)\n\nCompute the distance on the SymmetricPositiveDefinite manifold between p and q, as a MetricManifold with AffineInvariantMetric. The formula reads\n\nd_mathcal P(n)(pq)\n= lVert operatornameLog(p^-frac12qp^-frac12)rVert_mathrmF\n\nwhere operatornameLog denotes the matrix logarithm and lVertcdotrVert_mathrmF denotes the matrix Frobenius norm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_basis-Tuple{SymmetricPositiveDefinite, Any, DefaultOrthonormalBasis}","page":"Symmetric positive definite","title":"ManifoldsBase.get_basis","text":"[Ξ,κ] = get_basis(M::SymmetricPositiveDefinite, p, B::DefaultOrthonormalBasis)\n[Ξ,κ] = get_basis(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, B::DefaultOrthonormalBasis)\n\nReturn a default ONB for the tangent space T_pmathcal P(n) of the SymmetricPositiveDefinite with respect to the AffineInvariantMetric.\n\n g_p(XY) = operatornametr(p^-1 X p^-1 Y)\n\nThe basis constructed here is based on the ONB for symmetric matrices constructed as follows. Let\n\nDelta_ij = (a_kl)_kl=1^n quad text with \na_kl =\nbegincases\n 1 mbox for k=l text if i=j\n frac1sqrt2 mbox for k=i l=j text or k=j l=i\n 0 text else\nendcases\n\nwhich forms an ONB for the space of symmetric matrices.\n\nWe then form the ONB by\n\n Xi_ij = p^frac12Delta_ijp^frac12qquad i=1ldotsn j=ildotsn\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_basis_diagonalizing-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any, DiagonalizingOrthonormalBasis}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.get_basis_diagonalizing","text":"[Ξ,κ] = get_basis_diagonalizing(M::SymmetricPositiveDefinite, p, B::DiagonalizingOrthonormalBasis)\n[Ξ,κ] = get_basis_diagonalizing(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, B::DiagonalizingOrthonormalBasis)\n\nReturn a orthonormal basis Ξ as a vector of tangent vectors (of length manifold_dimension of M) in the tangent space of p on the MetricManifold of SymmetricPositiveDefinite manifold M with AffineInvariantMetric that diagonalizes the curvature tensor R(uv)w with eigenvalues κ and where the direction B.frame_direction V has curvature 0.\n\nThe construction is based on an ONB for the symmetric matrices similar to get_basis(::SymmetricPositiveDefinite, p, ::DefaultOrthonormalBasis just that the ONB here is build from the eigen vectors of p^frac12Vp^frac12.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_coordinates-Tuple{SymmetricPositiveDefinite, Any, Any, Any, DefaultOrthonormalBasis}","page":"Symmetric positive definite","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(::SymmetricPositiveDefinite, p, X, ::DefaultOrthonormalBasis)\n\nUsing the basis from get_basis the coordinates with respect to this ONB can be simplified to\n\n c_k = mathrmtr(p^-frac12Delta_ij X)\n\nwhere k is trhe linearized index of the i=1ldotsn j=ildotsn.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_vector-Tuple{SymmetricPositiveDefinite, Any, Any, Any, DefaultOrthonormalBasis}","page":"Symmetric positive definite","title":"ManifoldsBase.get_vector","text":"get_vector(::SymmetricPositiveDefinite, p, c, ::DefaultOrthonormalBasis)\n\nUsing the basis from get_basis the vector reconstruction with respect to this ONB can be simplified to\n\n X = p^frac12 Biggl( sum_i=1j=i^n c_k Delta_ij Biggr) p^frac12\n\nwhere k is the linearized index of the i=1ldotsn j=ildotsn.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Tuple{SymmetricPositiveDefinite, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(M::SymmetricPositiveDefinite, p, X, Y)\ninner(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, X, Y)\n\nCompute the inner product of X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with AffineInvariantMetric. The formula reads\n\ng_p(XY) = operatornametr(p^-1 X p^-1 Y)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, AffineInvariantMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,AffineInvariantMetric})\n\nReturn false. SymmetricPositiveDefinite with AffineInvariantMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.parallel_transport_to-Tuple{SymmetricPositiveDefinite, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::SymmetricPositiveDefinite, p, X, q)\nparallel_transport_to(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, X, y)\n\nCompute the parallel transport of X from the tangent space at p to the tangent space at q on the SymmetricPositiveDefinite as a MetricManifold with the AffineInvariantMetric. The formula reads\n\nmathcal P_qpX = p^frac12\noperatornameExpbigl(\nfrac12p^-frac12log_p(q)p^-frac12\nbigr)\np^-frac12X p^-frac12\noperatornameExpbigl(\nfrac12p^-frac12log_p(q)p^-frac12\nbigr)\np^frac12\n\nwhere operatornameExp denotes the matrix exponential and log the logarithmic map on SymmetricPositiveDefinite (again with respect to the AffineInvariantMetric).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.riemann_tensor-Tuple{SymmetricPositiveDefinite, Vararg{Any, 4}}","page":"Symmetric positive definite","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::SymmetricPositiveDefinite, p, X, Y, Z)\n\nCompute the value of Riemann tensor on the SymmetricPositiveDefinite manifold. The formula reads[Rentmeesters2011] R(XY)Z=p^12R(X_I Y_I)Z_Ip^12, where R_I(X_I Y_I)Z_I=frac14Z_I X_I Y_I, X_I=p^-12Xp^-12, Y_I=p^-12Yp^-12 and Z_I=p^-12Zp^-12.\n\n[Rentmeesters2011]: Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#BuresWassersteinMetricSection","page":"Symmetric positive definite","title":"Bures-Wasserstein metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteBuresWasserstein.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.BuresWassersteinMetric","page":"Symmetric positive definite","title":"Manifolds.BuresWassersteinMetric","text":"BurresWassertseinMetric <: AbstractMetric\n\nThe Bures Wasserstein metric for symmetric positive definite matrices[MalagoMontruccioPistone2018].\n\n[MalagoMontruccioPistone2018]: Malagò, L., Montrucchio, L., Pistone, G.: Wasserstein Riemannian geometry of Gaussian densities. Information Geometry, 1, pp. 137–179, 2018. doi: 10.1007/s41884-018-0014-4\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X)\n\nCompute the exponential map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n exp_p(X) = p+X+L_p(X)pL_p(X)\n\nwhere q=L_p(X) denotes the Lyapunov operator, i.e. it solves pq + qp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.log","text":"log(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)\n\nCompute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n log_p(q) = (pq)^frac12 + (qp)^frac12 - 2 p\n\nwhere q=L_p(X) denotes the Lyapunov operator, i.e. it solves pq + qp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_representer-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, BuresWassersteinMetric}, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_representer","text":"change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the BuresWassersteinMetric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ZT_pmathcal P(n) such that for all YT_pmathcal P(n)` it holds\n\nXY = operatornametr(XY) = ZY_mathrmBW\n\nfor all Y and hence we get Z= 2(A+A^{\\mathrm{T}})withA=Xp``.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)\n\nCompute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.\n\nd(pq) =\n operatornametr(p) + operatornametr(q) - 2operatornametrBigl( (p^frac12qp^frac12 bigr)^frac12 Bigr)\n\nwhere the last trace can be simplified (by rotating the matrix products in the trace) to operatornametr(pq).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(::MetricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X, Y)\n\nCompute the inner product SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n XY = frac12operatornametr(L_p(X)Y)\n\nwhere q=L_p(X) denotes the Lyapunov operator, i.e. it solves pq + qp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, BuresWassersteinMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,BuresWassersteinMetric})\n\nReturn false. SymmetricPositiveDefinite with BuresWassersteinMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Generalized-Bures-Wasserstein-metric","page":"Symmetric positive definite","title":"Generalized Bures-Wasserstein metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteGeneralizedBuresWasserstein.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.GeneralizedBuresWassersteinMetric","page":"Symmetric positive definite","title":"Manifolds.GeneralizedBuresWassersteinMetric","text":"GeneralizedBurresWassertseinMetric{T<:AbstractMatrix} <: AbstractMetric\n\nThe generalized Bures Wasserstein metric for symmetric positive definite matrices, see[HanMishraJawanpuriaGao2021].\n\nThis metric internally stores the symmetric positive definite matrix M to generalise the metric, where the name also follows the mentioned preprint.\n\n[HanMishraJawanpuriaGao2021]: Han, A., Mishra, B., Jawanpuria, P., Gao, J.: Generalized Bures-Wasserstein geometry for positive definite matrices. arXiv: 2110.10464.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, GeneralizedBuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, X)\n\nCompute the exponential map on SymmetricPositiveDefinite with respect to the GeneralizedBuresWassersteinMetric given by\n\n exp_p(X) = p+X+mathcal ML_pM(X)pML_pM(X)\n\nwhere q=L_Mp(X) denotes the generalized Lyapunov operator, i.e. it solves pqM + Mqp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, GeneralizedBuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.log","text":"log(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)\n\nCompute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n log_p(q) = M(M^-1pM^-1q)^frac12 + (qM^-1pM^-1)^frac12M - 2 p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_representer-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, GeneralizedBuresWassersteinMetric}, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_representer","text":"change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the GeneralizedBuresWassersteinMetric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ZT_pmathcal P(n) such that for all YT_pmathcal P(n) it holds\n\nXY = operatornametr(XY) = ZY_mathrmBW\n\nfor all Y and hence we get Z = 2pXM + 2MXp.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, <:GeneralizedBuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)\n\nCompute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.\n\nd(pq) = operatornametr(M^-1p) + operatornametr(M^-1q)\n - 2operatornametrbigl( (p^frac12M^-1qM^-1p^frac12 bigr)^frac12\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, <:GeneralizedBuresWassersteinMetric}, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(::MetricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, X, Y)\n\nCompute the inner product SymmetricPositiveDefinite with respect to the GeneralizedBuresWassersteinMetric given by\n\n XY = frac12operatornametr(L_pM(X)Y)\n\nwhere q=L_Mp(X) denotes the generalized Lyapunov operator, i.e. it solves pqM + Mqp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, <:GeneralizedBuresWassersteinMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric})\n\nReturn false. SymmetricPositiveDefinite with GeneralizedBuresWassersteinMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Log-Euclidean-metric","page":"Symmetric positive definite","title":"Log-Euclidean metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteLogEuclidean.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.LogEuclideanMetric","page":"Symmetric positive definite","title":"Manifolds.LogEuclideanMetric","text":"LogEuclideanMetric <: RiemannianMetric\n\nThe LogEuclidean Metric consists of the Euclidean metric applied to all elements after mapping them into the Lie Algebra, i.e. performing a matrix logarithm beforehand.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Union{Tuple{N}, Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite{N}, LogEuclideanMetric}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(M::MetricManifold{SymmetricPositiveDefinite{N},LogEuclideanMetric}, p, q)\n\nCompute the distance on the SymmetricPositiveDefinite manifold between p and q as a MetricManifold with LogEuclideanMetric. The formula reads\n\n d_mathcal P(n)(pq) = lVert operatornameLog p - operatornameLog q rVert_mathrmF\n\nwhere operatornameLog denotes the matrix logarithm and lVertcdotrVert_mathrmF denotes the matrix Frobenius norm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, LogEuclideanMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,LogEuclideanMetric})\n\nReturn false. SymmetricPositiveDefinite with LogEuclideanMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Log-Cholesky-metric","page":"Symmetric positive definite","title":"Log-Cholesky metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteLogCholesky.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.LogCholeskyMetric","page":"Symmetric positive definite","title":"Manifolds.LogCholeskyMetric","text":"LogCholeskyMetric <: RiemannianMetric\n\nThe Log-Cholesky metric imposes a metric based on the Cholesky decomposition as introduced by [Lin2019].\n\n[Lin2019]: Lin, Zenhua: \"Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition\", arXiv: 1908.09326.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, LogCholeskyMetric}, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, X)\n\nCompute the exponential map on the SymmetricPositiveDefinite M with LogCholeskyMetric from p into direction X. The formula reads\n\nexp_p X = (exp_y W)(exp_y W)^mathrmT\n\nwhere exp_xW is the exponential map on CholeskySpace, y is the cholesky decomposition of p, W = y(y^-1Xy^-mathrmT)_frac12, and (cdot)_frac12 denotes the lower triangular matrix with the diagonal multiplied by frac12.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, LogCholeskyMetric}, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.log","text":"log(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)\n\nCompute the logarithmic map on SymmetricPositiveDefinite M with respect to the LogCholeskyMetric emanating from p to q. The formula can be adapted from the CholeskySpace as\n\nlog_p q = xW^mathrmT + Wx^mathrmT\n\nwhere x is the cholesky factor of p and W=log_x y for y the cholesky factor of q and the just mentioned logarithmic map is the one on CholeskySpace.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Union{Tuple{N}, Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite{N}, LogCholeskyMetric}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)\n\nCompute the distance on the manifold of SymmetricPositiveDefinite nmatrices, i.e. between two symmetric positive definite matrices p and q with respect to the LogCholeskyMetric. The formula reads\n\nd_mathcal P(n)(pq) = sqrt\n lVert x - y rVert_mathrmF^2\n + lVert log(operatornamediag(x)) - log(operatornamediag(y))rVert_mathrmF^2 \n\nwhere x and y are the cholesky factors of p and q, respectively, cdot denbotes the strictly lower triangular matrix of its argument, and lVertcdotrVert_mathrmF the Frobenius norm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Union{Tuple{N}, Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite{N}, LogCholeskyMetric}, Any, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(M::MetricManifold{LogCholeskyMetric,ℝ,SymmetricPositiveDefinite}, p, X, Y)\n\nCompute the inner product of two matrices X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with LogCholeskyMetric. The formula reads\n\n g_p(XY) = a_z(X)a_z(Y)_z\n\nwhere cdotcdot_x denotes inner product on the CholeskySpace, z is the cholesky factor of p, a_z(W) = z (z^-1Wz^-mathrmT)_frac12, and (cdot)_frac12 denotes the lower triangular matrix with the diagonal multiplied by frac12\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, LogCholeskyMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,LogCholeskyMetric})\n\nReturn false. SymmetricPositiveDefinite with LogCholeskyMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.parallel_transport_to-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, LogCholeskyMetric}, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.parallel_transport_to","text":"vector_transport_to(\n M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric},\n p,\n X,\n q,\n ::ParallelTransport,\n)\n\nParallel transport the tangent vector X at p along the geodesic to q with respect to the SymmetricPositiveDefinite manifold M and LogCholeskyMetric. The parallel transport is based on the parallel transport on CholeskySpace: Let x and y denote the cholesky factors of p and q, respectively and W = x(x^-1Xx^-mathrmT)_frac12, where (cdot)_frac12 denotes the lower triangular matrix with the diagonal multiplied by frac12. With V the parallel transport on CholeskySpace from x to y. The formula hear reads\n\nmathcal P_qpX = yV^mathrmT + Vy^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Statistics","page":"Symmetric positive definite","title":"Statistics","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"SymmetricPositiveDefinite.jl\"]\nOrder = [:function]\nFilter = t -> t === mean","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Statistics.mean-Tuple{SymmetricPositiveDefinite, Any}","page":"Symmetric positive definite","title":"Statistics.mean","text":"mean(\n M::SymmetricPositiveDefinite,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolation();\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Efficient-representation","page":"Symmetric positive definite","title":"Efficient representation","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"When a point p is used in several occasions, it might be beneficial to store the eigenvalues and vectors of p and optionally its square root and the inverse of the square root. The SPDPoint can be used for exactly that.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"SPDPoint","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.SPDPoint","page":"Symmetric positive definite","title":"Manifolds.SPDPoint","text":"SPDPoint <: AbstractManifoldsPoint\n\nStore the result of eigen(p) of an SPD matrix and (optionally) p^12 and p^-12 to avoid their repeated computations.\n\nThis result only has the result of eigen as a mandatory storage, the other three can be stored. If they are not stored they are computed and returned (but then still not stored) when required.\n\nConstructor\n\nSPDPoint(p::AbstractMatrix; store_p=true, store_sqrt=true, store_sqrt_inv=true)\n\nCreate an SPD point using an symmetric positive defincite matrix p, where you can optionally store p, sqrt and sqrt_inv\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"and there are three internal functions to be able to use SPDPoint interchangeably with the default representation as a matrix.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Manifolds.spd_sqrt\nManifolds.spd_sqrt_inv\nManifolds.spd_sqrt_and_sqrt_inv","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.spd_sqrt","page":"Symmetric positive definite","title":"Manifolds.spd_sqrt","text":"spd_sqrt(p::AbstractMatrix)\nspd_sqrt(p::SPDPoint)\n\nreturn p^frac12 by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.\n\nThis method assumes that p represents an spd matrix.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.spd_sqrt_inv","page":"Symmetric positive definite","title":"Manifolds.spd_sqrt_inv","text":"spd_sqrt_inv(p::SPDPoint)\n\nreturn p^-frac12 by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.\n\nThis method assumes that p represents an spd matrix.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.spd_sqrt_and_sqrt_inv","page":"Symmetric positive definite","title":"Manifolds.spd_sqrt_and_sqrt_inv","text":"spd_sqrt_and_sqrt_inv(p::AbstractMatrix)\nspd_sqrt_and_sqrt_inv(p::SPDPoint)\n\nreturn p^frac12 and p^-frac12 by either computing them (if they are missing or for the AbstractMatrix) or returning their stored value from within the SPDPoint.\n\nCompared to calling single methods spd_sqrt and spd_sqrt_inv this method only computes the eigenvectors once for the case of the AbstractMatrix or if both are missing.\n\nThis method assumes that p represents an spd matrix.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/symmetricpositivedefinite.html#Literature","page":"Symmetric positive definite","title":"Literature","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"EditURL = \"https://github.com/JuliaManifolds/Manifolds.jl/blob/master/CONTRIBUTING.md\"","category":"page"},{"location":"misc/contributing.html#Contributing-to-Manifolds.jl","page":"Contributing","title":"Contributing to Manifolds.jl","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"First, thanks for taking the time to contribute. Any contribution is appreciated and welcome.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"The following is a set of guidelines to Manifolds.jl.","category":"page"},{"location":"misc/contributing.html#Table-of-Contents","page":"Contributing","title":"Table of Contents","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"Contributing to Manifolds.jl - Table of Contents\nI just have a question\nHow can I file an issue?\nHow can I contribute?\nAdd a missing method\nProvide a new manifold\nCode style","category":"page"},{"location":"misc/contributing.html#I-just-have-a-question","page":"Contributing","title":"I just have a question","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"The developers can most easily be reached in the Julia Slack channel #manifolds. You can apply for the Julia Slack workspace here if you haven't joined yet. You can also ask your question on discourse.julialang.org.","category":"page"},{"location":"misc/contributing.html#How-can-I-file-an-issue?","page":"Contributing","title":"How can I file an issue?","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"If you found a bug or want to propose a feature, we track our issues within the GitHub repository.","category":"page"},{"location":"misc/contributing.html#How-can-I-contribute?","page":"Contributing","title":"How can I contribute?","text":"","category":"section"},{"location":"misc/contributing.html#Add-a-missing-method","page":"Contributing","title":"Add a missing method","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"Not all methods from our interface ManifoldsBase.jl have been implemented for every manifold. If you notice a method missing and can contribute an implementation, please do so! Even providing a single new method is a good contribution.","category":"page"},{"location":"misc/contributing.html#Provide-a-new-manifold","page":"Contributing","title":"Provide a new manifold","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"A main contribution you can provide is another manifold that is not yet included in the package. A manifold is a concrete type of AbstractManifold from ManifoldsBase.jl. This package also provides the main set of functions a manifold can/should implement. Don't worry if you can only implement some of the functions. If the application you have in mind only requires a subset of these functions, implement those. The ManifoldsBase.jl interface provides concrete error messages for the remaining unimplemented functions.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"One important detail is that the interface usually provides an in-place as well as a non-mutating variant See for example exp! and exp. The non-mutating one (e.g. exp) always falls back to use the in-place one, so in most cases it should suffice to implement the in-place one (e.g. exp!).","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"Note that since the first argument is always the AbstractManifold, the mutated argument is always the second one in the signature. In the example we have exp(M, p, X, t) for the exponential map and exp!(M, q, p, X, t) for the in-place one, which stores the result in q.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"On the other hand, the user will most likely look for the documentation of the non-mutating version, so we recommend adding the docstring for the non-mutating one, where all different signatures should be collected in one string when reasonable. This can best be achieved by adding a docstring to the method with a general signature with the first argument being your manifold:","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"struct MyManifold <: AbstractManifold end\n\n@doc raw\"\"\"\n exp(M::MyManifold, p, X)\n\nDescribe the function.\n\"\"\"\nexp(::MyManifold, ::Any...)","category":"page"},{"location":"misc/contributing.html#Code-style","page":"Contributing","title":"Code style","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"We try to follow the documentation guidelines from the Julia documentation as well as Blue Style. We run JuliaFormatter.jl on the repo in the way set in the .JuliaFormatter.toml file, which enforces a number of conventions consistent with the Blue Style.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"We also follow a few internal conventions:","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"It is preferred that the AbstractManifold's struct contain a reference to the general theory.\nAny implemented function should be accompanied by its mathematical formulae if a closed form exists.\nWithin the source code of one manifold, the type of the manifold should be the first element of the file, and an alphabetical order of the functions is preferable.\nThe above implies that the in-place variant of a function follows the non-mutating variant.\nThere should be no dangling = signs.\nAlways add a newline between things of different types (struct/method/const).\nAlways add a newline between methods for different functions (including in-place/nonmutating variants).\nPrefer to have no newline between methods for the same function; when reasonable, merge the docstrings.\nAll import/using/include should be in the main module file.","category":"page"}] +[{"location":"tutorials/hand-gestures.html#Hand-gesture-analysis","page":"perform Hand gesture analysis","title":"Hand gesture analysis","text":"","category":"section"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"In this tutorial we will learn how to use Kendall’s shape space to analyze hand gesture data.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Let’s start by loading libraries required for our work.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"using Manifolds, CSV, DataFrames, Plots, MultivariateStats","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Our first function loads dataset of hand gestures, described here.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"function load_hands()\n hands_url = \"https://raw.githubusercontent.com/geomstats/geomstats/master/geomstats/datasets/data/hands/hands.txt\"\n hand_labels_url = \"https://raw.githubusercontent.com/geomstats/geomstats/master/geomstats/datasets/data/hands/labels.txt\"\n\n hands = Matrix(CSV.read(download(hands_url), DataFrame, header=false))\n hands = reshape(hands, size(hands, 1), 3, 22)\n hand_labels = CSV.read(download(hand_labels_url), DataFrame, header=false).Column1\n return hands, hand_labels\nend","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"load_hands (generic function with 1 method)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"The following code plots a sample gesture as a 3D scatter plot of points.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"hands, hand_labels = load_hands()\nscatter3d(hands[1, 1, :], hands[1, 2, :], hands[1, 3, :])","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Each gesture is represented by 22 landmarks in ℝ³, so we use the appropriate Kendall’s shape space","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Mshape = KendallsShapeSpace(3, 22)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"KendallsShapeSpace{3, 22}()","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Hands read from the dataset are projected to the shape space to remove translation and scaling variability. Rotational variability is then handled using the quotient structure of KendallsShapeSpace","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"hands_projected = [project(Mshape, hands[i, :, :]) for i in axes(hands, 1)]","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"In the next part let’s do tangent space PCA. This starts with computing a mean point and computing logithmic maps at mean to each point in the dataset.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"mean_hand = mean(Mshape, hands_projected)\nhand_logs = [log(Mshape, mean_hand, p) for p in hands_projected]","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"For a tangent PCA, we need coordinates in a basis. Some libraries skip this step because the representation of tangent vectors forms a linear subspace of an Euclidean space so PCA automatically detects which directions have no variance but this is a more generic way to solve this issue.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"B = get_basis(Mshape, mean_hand, ProjectedOrthonormalBasis(:svd))\nhand_log_coordinates = [get_coordinates(Mshape, mean_hand, X, B) for X in hand_logs]","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"This code prepares data for MultivariateStats – mean=0 is set because we’ve centered the data geometrically to mean_hand in the code above.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"red_coords = reduce(hcat, hand_log_coordinates)\nfp = fit(PCA, red_coords; mean=0)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"PCA(indim = 59, outdim = 18, principalratio = 0.9900213563800988)\n\nPattern matrix (unstandardized loadings):\n─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n PC1 PC2 PC3 PC4 PC5 PC6 PC7 PC8 PC9 PC10 PC11 PC12 PC13 PC14 PC15 PC16 PC17 PC18\n─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n1 -0.0290105 0.0208927 -0.01643 0.00190549 0.00901145 0.000643771 -0.00363047 -0.00217327 0.00312554 -0.00356053 0.00478045 0.00165704 0.00218866 0.0037857 0.000320345 -0.00145212 0.000948335 -0.00184176\n2 0.0172527 0.0165863 -0.0168821 -0.0183233 0.0121555 0.00833736 0.00187667 -0.000648234 0.00706323 0.00583622 -0.0044018 0.0012355 0.00118376 -0.00246016 0.00446684 -0.00498993 -0.0028049 -0.00259758\n3 0.0447499 -0.00487667 -0.00247071 -0.00148697 -0.00200127 -0.00795338 0.00905314 0.00687454 0.0114088 -0.000998774 0.00459101 0.00645948 0.00073043 0.00591995 -0.00520394 0.00129428 -0.000463386 -0.00207384\n4 -0.00881422 -0.0341713 0.00749624 0.00795209 -0.00260601 0.00356386 0.00204456 -0.00905276 0.00826807 0.00012095 0.000768538 -0.000460691 0.00411022 -0.00216294 -0.000650028 0.00251224 0.00149784 -0.00181133\n5 0.0325794 -0.023796 0.000642765 0.00509869 0.00759807 0.00483368 -0.00252952 0.00656179 0.00322274 -0.000313146 0.00143493 -0.000676479 0.000146354 -0.00266203 0.00353957 0.0021415 -0.00457168 0.00282965\n6 -0.00617763 6.91201e-5 0.00765638 0.00183758 0.00157382 0.00184956 -0.00797935 0.000700457 0.0087012 0.00992564 0.00263642 0.00294279 -0.0092 0.00133877 0.00145735 -0.0014816 0.00235123 -0.00039541\n7 -0.0183122 0.0131045 0.0125222 -0.00638021 -0.006709 -0.00013628 0.00858169 -0.00159031 -0.00585433 -0.0032447 0.00880912 -0.00149308 0.000724205 0.00469925 0.00432005 0.0012382 -0.00251638 6.89878e-5\n8 0.0392874 -0.0152552 -0.00404674 -0.0183856 -0.0054739 0.000203488 0.00687526 0.00989129 -0.00570517 0.00234255 -0.00221344 -0.00514796 0.000658069 0.00220789 7.02581e-5 0.000380265 0.0007751 0.00234631\n9 -0.00525049 -0.0181427 -0.00473895 -0.0128126 0.000405834 -0.00936332 -0.000781745 0.011196 -0.00498502 0.00199077 0.00355555 -0.00334398 0.00763648 0.000311697 -0.000844841 -0.00526438 -0.00201977 0.00188678\n10 0.0771681 0.0248294 -0.00375548 -0.0138712 -0.0126479 -0.00543573 -0.0136609 -0.00408721 -0.00445726 -0.00407287 0.00696664 -0.00158737 -0.00201909 -0.00211184 0.000907502 0.00235338 -0.00259266 0.00114594\n11 -0.0013693 0.0125762 -0.00145726 0.0119688 -0.00362363 0.00954477 0.000894749 0.00311196 0.000186917 0.00923739 0.0036434 0.00484736 0.000288834 -0.00269382 -0.00194147 -0.000702207 -0.00245996 -0.000458531\n12 0.00497523 0.0154863 0.0409999 -0.00832204 -0.00216091 0.0149159 0.011796 0.0121391 -0.00292353 -0.00532504 -0.00427894 0.000550893 -0.00408841 0.000520159 -0.00344571 0.000625647 0.000271049 -0.00165807\n13 -0.0541357 -0.0291498 0.0140122 0.00292223 0.00128359 0.00301256 -0.00581861 -0.00397323 0.000588485 0.0025976 -0.00442985 -0.00603182 0.00326815 0.00326603 0.000384467 -0.00134404 -0.00160027 -0.00261985\n14 -0.0493144 0.0120223 -0.0163111 0.0103746 -0.0126512 -0.011453 0.00488614 -0.00586095 0.0027455 -0.00434342 0.00203457 -0.000941868 -0.00426973 -0.00447805 -0.00239537 -0.00320013 0.000877498 0.000673572\n15 -0.00654048 0.00225524 -0.028207 0.00306531 0.00321072 -0.000599231 0.00320363 -0.0059508 -0.00586048 0.0031903 -0.00613799 0.00471076 -0.00101853 0.00294667 -0.000548534 0.00402922 0.000405583 2.6607e-5\n16 0.0300802 0.0075843 0.00364836 -0.00205771 -0.0148831 0.0211394 -0.000508637 0.0036868 0.0109845 -0.00574404 -0.00920237 0.0007153 0.000544823 -0.00209521 0.000474541 -0.00052208 0.00180017 0.00202094\n17 -0.0110775 0.0373997 -0.00242133 0.00827109 -0.000567586 -0.0141686 -0.000939656 0.00843637 -0.00590348 0.00649057 0.00259619 -0.000897277 0.00443368 -0.0047585 -0.00160148 0.000335684 0.00152076 -0.00300398\n18 0.0391783 0.0248007 0.0308429 0.00118303 0.00981074 0.00261316 -0.00100239 -0.0062546 -0.00491006 -0.00506867 0.00441608 -0.00367774 -0.00481009 -0.000493728 -0.00329753 0.000419403 0.000711267 0.000406243\n19 0.0138738 -0.0443171 -0.00598066 0.00585226 0.00596223 0.00680714 -0.0079294 -0.00269779 -0.00426069 -0.00718608 0.00761514 0.00336824 -0.00295577 -0.00264683 0.00316699 -0.000418376 -0.00240164 -0.00413196\n20 0.0173164 -0.0215417 0.000863689 -0.0205664 0.00121695 0.00307745 0.00191828 -0.00849558 -0.00147893 0.00180504 0.00814434 0.00372913 0.00188294 -0.00170647 -0.00451407 -0.00100769 -0.000238128 -0.000257117\n21 0.00338984 0.00237562 0.0237069 -0.0129184 0.00148197 -0.000855367 0.00148785 0.00142366 0.00320966 0.00781237 0.000800995 -0.000516126 0.00440079 -0.0079143 0.00215576 0.00201592 -0.000335618 0.00337192\n22 -0.00746071 -0.0116344 0.0021644 0.0152239 0.00723169 0.0120803 -0.000485058 0.00653526 0.0026666 0.00152026 0.0135607 -0.00247612 0.00348543 3.45051e-6 0.0017885 0.000179426 -0.000524643 -0.000805656\n23 0.0478442 -0.0227649 -0.0113793 -0.00367693 0.0106966 0.00169994 0.0135303 -0.00344929 0.000128235 0.00063693 -0.00225447 0.000880574 -0.00665083 -0.0050547 -0.00295617 -0.00422433 0.00166798 -0.00189465\n24 -0.0142467 0.0166931 0.00516018 0.00593988 -0.0210703 0.00438546 0.00643305 0.00174866 0.00505729 0.000463517 0.00763753 -0.00417294 -0.00156206 0.00540319 -0.00301265 -0.00408336 -0.00144362 -0.000137294\n25 0.00108012 0.0195339 0.011519 0.0110158 0.00193433 0.0107534 -0.00146174 0.000236797 0.00226925 -0.00744152 0.00199678 -0.00445237 0.00273993 -0.000207735 -0.00191042 0.00121896 0.00195283 -0.00274164\n26 0.0123466 0.0083253 0.00519553 -0.00196478 0.0137825 -0.00233978 -0.00771765 -0.00232805 -0.00279333 0.00340724 0.0012353 -0.00362154 -0.0013554 0.000632953 -2.37112e-5 0.00141247 -0.000568908 -0.000973567\n27 -0.00893091 0.00641791 0.0087648 0.00424429 -0.000824081 -0.00761539 -0.0152518 0.00995065 0.00317758 8.84094e-5 -0.00419563 -0.00124495 -0.00589762 -0.000929293 0.00477719 0.00377025 0.00267074 0.000761405\n28 0.0378644 -0.0125169 0.012799 0.0178141 0.00260966 -0.00752201 0.00299546 -0.00777486 0.00426756 0.00566038 0.00107451 -0.000215202 -0.00470252 0.00209217 -0.000578698 0.00150591 -0.00148331 0.00229085\n29 0.00205475 0.0304241 -0.0354979 0.00394855 -0.00350914 0.00725592 -0.00678139 0.000307436 -0.00315394 -0.00689183 0.000456785 0.00368637 0.00277269 -0.00277076 -0.00422942 0.00223455 0.0015448 -0.00234455\n30 0.0749975 -0.00999942 0.00367276 0.0100629 -0.00671752 -0.011357 0.00301586 0.000408736 0.00259563 0.000303288 -0.000111357 -0.00159763 0.00161827 -0.000545339 0.00377406 0.00268094 0.00406555 -0.00203144\n31 0.0209729 0.00213421 0.00669869 0.016557 0.00403684 -0.0178951 0.0107244 0.0111298 0.00610797 -0.00390215 -0.00353771 -0.00178467 0.00235713 0.000973802 0.000274041 0.00218045 -0.00215689 -0.00158819\n32 -0.0244084 -0.0371206 0.0192767 -0.000685794 0.0158289 -0.001451 -0.00509477 0.00577056 -0.00513049 -0.00950968 -0.00158958 0.000989458 -0.000699212 0.00122133 -0.000191417 0.000911926 0.00209233 -6.04374e-5\n33 0.00565764 -0.0172793 0.00401092 -0.00793658 0.00504771 -0.00220381 0.00224319 0.0071918 -0.0124133 0.00175162 0.00348751 0.00633021 -0.00260535 0.00565187 -0.00186287 -0.000238933 0.000666333 0.00250607\n34 0.00185581 -0.0166196 -0.0197269 0.00699341 0.00647246 -0.00303065 -0.000117067 0.00490106 0.00667588 -0.00855122 0.00302462 0.00173228 0.00553969 -0.00468124 0.00121978 0.0005079 0.000420239 0.00253235\n35 0.0199811 0.0267965 0.0129649 0.00264194 0.000195136 -0.00349662 0.00294599 -0.00187851 0.00177767 -0.0053757 -0.00330811 -0.00295473 0.00208629 -6.97773e-5 -0.00153972 -0.000773065 -0.00157575 -0.000197057\n36 0.0175704 0.0191343 -0.0116551 0.00882917 -0.0104714 0.0103777 0.00118041 -0.000696881 0.00192364 0.00744034 0.00497109 -0.00164206 0.00162482 -0.00139405 0.00167977 0.000693101 -0.00132024 0.00297973\n37 -0.00462744 -0.013417 0.00735863 0.0138801 -0.0058212 -0.00238145 -0.00576575 0.00188503 0.00101854 0.0035232 0.0016009 0.00106877 -0.00593854 -0.0015165 -0.00563642 -0.000339869 0.00216456 0.002153\n38 -0.0218719 0.00531191 0.00305154 0.0241393 0.0234907 0.00316473 0.0020773 -0.00469298 -0.00845531 0.00456344 -0.000534739 0.00131404 -0.00166945 -0.000113877 -0.00168502 0.00333815 -0.00307554 0.00114466\n39 -0.00848638 0.0208304 0.00949937 0.0226454 0.0052942 -0.000851704 0.00632965 2.91971e-5 0.00329463 6.28469e-5 0.00660731 0.00235582 -0.00130279 -0.00141865 0.00530658 -0.00248136 0.000456183 0.00125713\n40 -0.0887529 -0.0108083 -0.00348235 -0.0197061 -0.00851786 -0.00490488 0.00159713 0.00351037 0.0148414 -0.00401737 0.00779929 0.00245023 -0.00253298 -0.000226246 -0.000206421 0.00510786 0.00148421 0.00186788\n41 0.00130006 0.00193007 -0.00297337 0.0070658 0.00888416 0.00665004 -0.013746 0.000961125 0.00363303 0.00316905 0.000576911 -0.00659932 0.00136165 0.0013939 -0.00380487 -0.00444913 0.00366095 0.00144111\n42 -0.0207553 0.0174796 -0.00445662 -0.0117613 0.0273261 -0.00065484 0.00296882 0.00593266 0.00162045 -0.00318673 0.0066341 -0.0053347 0.000440878 -0.000644585 -0.00244859 0.00184264 0.00345959 -0.000426283\n43 0.0413948 0.00307635 -0.00665062 -0.00226029 0.017443 -0.00424136 0.00950125 -0.00429922 0.00148225 -0.000166312 0.00294757 -0.00069645 0.000696539 0.000366659 0.00282844 -0.00230084 0.0053369 0.00238474\n44 0.00449575 0.0201137 0.03094 -0.0058886 -0.00146264 0.0101428 -0.00516029 0.00543426 -0.00941967 0.000969442 -0.000431407 0.0064443 0.00115545 -0.00181689 0.00364823 -0.000426309 0.000849352 -0.00167685\n45 -0.0205292 -0.00157548 0.013357 -0.00792343 0.00744915 0.00216668 -0.00243796 0.00180573 0.01512 0.00713893 -0.00283512 0.00430074 0.000788886 0.0049491 0.0029426 -0.00139686 0.00105337 -0.00239361\n46 -0.0215505 -0.0112917 0.013841 0.0111599 -0.0105729 0.00953035 0.0113897 -0.00673481 -0.0100248 0.00344613 0.00262901 0.0047878 0.00566946 -6.60172e-5 0.00414744 0.00111141 0.00450865 -0.00145945\n47 -0.0171993 0.0180146 0.00810394 -0.00791244 0.0061704 0.00923438 0.000727892 -0.0152243 0.00748635 -0.00599911 -0.00175649 0.00265434 -8.49398e-5 0.00305952 -0.00198115 0.00274446 -0.0028668 0.00323797\n48 0.0587549 0.0116068 -0.00915491 0.00448539 0.0104133 0.00457871 0.00126112 0.00499596 0.00964989 -0.00404286 0.000207311 0.003728 -0.000433589 -0.000303131 0.00412588 0.000467283 -0.000916261 -0.00103631\n49 -0.00166257 0.0250389 0.00797097 0.000683472 -0.000895449 -0.0133557 -0.00573426 0.000680622 0.00069621 0.00638431 -0.00245348 0.00498899 0.00507946 0.0057863 -0.00069408 0.0014596 0.000877213 -0.000692365\n50 -0.0355097 0.0143079 -0.00981991 0.00946907 -0.00422843 -0.00254884 0.00491884 0.00651818 -0.00548423 -0.0071809 9.81603e-5 0.00390103 -0.00712449 0.0013088 0.00694234 -0.00320143 0.000147409 0.00234526\n51 0.0456319 -0.0188437 0.00614929 0.01619 -0.0156405 0.00353768 -0.00911906 0.000874972 -0.00121217 -0.00403428 -0.000414905 0.00681573 0.00859836 0.00350106 -0.00263157 -0.00122084 0.00183226 0.00257702\n52 0.00746721 0.0133773 -0.0340613 -0.0139034 0.00655522 0.00929538 0.000770716 -0.000483502 -0.00600155 0.00201797 0.0011251 0.00179484 -2.38878e-5 0.00486216 0.00282832 0.00255029 0.00367921 0.00129338\n53 0.00823236 -0.00600734 -0.0200329 0.00202998 -0.0011313 0.0105144 0.00321895 0.00687414 0.000987698 0.00431901 0.000760463 -0.00635147 -0.00119575 0.00474285 4.40898e-5 0.00580837 -0.00332298 -0.00201341\n54 -0.043754 -0.00171994 -0.00111157 0.00123094 -0.00428039 0.0027972 0.00934907 -0.00596239 -0.00226019 0.001642 -0.00513074 -0.00589632 0.00344517 -0.0042949 0.0025378 0.00306413 0.00186166 0.00125999\n55 0.0430398 -0.000525733 0.0081576 -0.00839141 -0.00347855 -0.00933299 0.00251806 -0.0126012 0.002086 0.00272973 0.00204035 -0.000224255 -0.000607192 -0.000454776 -0.000157181 0.00250081 0.00145433 -0.00163108\n56 0.0305092 -0.00319322 -0.010629 0.0139009 0.00442941 0.00855659 0.00087527 -0.00330425 0.000399393 -0.000737765 -0.00150343 -0.00754475 0.000704529 0.00851631 0.00185909 -0.00126123 0.00232031 0.00223781\n57 0.00321453 -0.0190408 -0.0279848 0.00741802 -0.0157076 0.00592558 0.0020086 0.00843992 -0.00442316 0.00325392 -0.002545 -0.00268433 -0.00623548 -0.00142257 -0.00199612 0.0016597 0.000405685 -0.00229266\n58 0.0156328 -0.0074322 0.0066988 -0.0114629 -0.0168092 0.00328227 -0.00226964 -0.00110748 0.000440872 0.00227572 0.00827165 -0.00488151 -0.00316671 -2.58046e-5 0.00360288 0.00115025 0.00316887 -0.00204823\n59 -0.00151264 0.00426245 0.00115303 0.00338067 0.00957651 0.0116283 0.00361068 0.0102905 0.00246382 0.00700902 0.00252521 0.00257786 0.000578243 -0.00384276 -0.00597088 0.00283491 0.00171675 0.00226962\n─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n\nImportance of components:\n──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n PC1 PC2 PC3 PC4 PC5 PC6 PC7 PC8 PC9 PC10 PC11 PC12 PC13 PC14 PC15 PC16 PC17 PC18\n──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\nSS Loadings (Eigenvalues) 0.0559745 0.0192925 0.0128414 0.00672244 0.0055061 0.00364815 0.00229962 0.00223028 0.00206984 0.00135745 0.00119 0.000805397 0.000775895 0.000619591 0.00052072 0.000351929 0.000282879 0.000224033\nVariance explained 0.474806 0.16365 0.108928 0.0570235 0.0467058 0.0309456 0.0195066 0.0189185 0.0175575 0.0115146 0.0100942 0.00683182 0.00658157 0.00525572 0.00441704 0.00298526 0.00239954 0.00190038\nCumulative variance 0.474806 0.638456 0.747384 0.804407 0.851113 0.882059 0.901565 0.920484 0.938041 0.949556 0.95965 0.966482 0.973063 0.978319 0.982736 0.985721 0.988121 0.990021\nProportion explained 0.479592 0.165299 0.110026 0.0575982 0.0471765 0.0312575 0.0197032 0.0191092 0.0177345 0.0116307 0.010196 0.00690068 0.00664791 0.00530869 0.00446156 0.00301535 0.00242373 0.00191953\nCumulative proportion 0.479592 0.644891 0.754917 0.812515 0.859692 0.890949 0.910652 0.929761 0.947496 0.959127 0.969323 0.976223 0.982871 0.98818 0.992641 0.995657 0.99808 1.0\n──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"Now let’s show explained variance of each principal component.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"plot(principalvars(fp), title=\"explained variance\", label=\"Tangent PCA\")","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"The next plot shows how projections on the first two pricipal components look like.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"fig = plot(; title=\"coordinates per gesture of the first two principal components\")\nfor label_num in [0, 1]\n mask = hand_labels .== label_num\n cur_hand_logs = red_coords[:, mask]\n cur_t = MultivariateStats.transform(fp, cur_hand_logs)\n scatter!(fig, cur_t[1, :], cur_t[2, :], label=\"gesture \" * string(label_num))\nend\nxlabel!(fig, \"principal component 1\")\nylabel!(fig, \"principal component 2\")\nfig","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"The following heatmap displays pairwise distances between gestures. We can use them for clustering, classification, etc.","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"hand_distances = [\n distance(Mshape, hands_projected[i], hands_projected[j]) for\n i in eachindex(hands_projected), j in eachindex(hands_projected)\n]\nheatmap(hand_distances, aspect_ratio=:equal)","category":"page"},{"location":"tutorials/hand-gestures.html","page":"perform Hand gesture analysis","title":"perform Hand gesture analysis","text":"(Image: )","category":"page"},{"location":"features/statistics.html#Statistics","page":"Statistics","title":"Statistics","text":"","category":"section"},{"location":"features/statistics.html","page":"Statistics","title":"Statistics","text":"Modules = [Manifolds,ManifoldsBase]\nPages = [\"statistics.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/statistics.html#Manifolds.AbstractEstimationMethod","page":"Statistics","title":"Manifolds.AbstractEstimationMethod","text":"AbstractEstimationMethod\n\nAbstract type for defining statistical estimation methods.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.CyclicProximalPointEstimation","page":"Statistics","title":"Manifolds.CyclicProximalPointEstimation","text":"CyclicProximalPointEstimation <: AbstractEstimationMethod\n\nMethod for estimation using the cyclic proximal point technique.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.ExtrinsicEstimation","page":"Statistics","title":"Manifolds.ExtrinsicEstimation","text":"ExtrinsicEstimation <: AbstractEstimationMethod\n\nMethod for estimation in the ambient space and projecting to the manifold.\n\nFor mean estimation, GeodesicInterpolation is used for mean estimation in the ambient space.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.GeodesicInterpolation","page":"Statistics","title":"Manifolds.GeodesicInterpolation","text":"GeodesicInterpolation <: AbstractEstimationMethod\n\nRepeated weighted geodesic interpolation method for estimating the Riemannian center of mass.\n\nThe algorithm proceeds with the following simple online update:\n\nbeginaligned\nμ_1 = x_1\nt_k = fracw_ksum_i=1^k w_i\nμ_k = γ_μ_k-1(x_k t_k)\nendaligned\n\nwhere x_k are points, w_k are weights, μ_k is the kth estimate of the mean, and γ_x(y t) is the point at time t along the shortest_geodesic between points xy mathcal M. The algorithm terminates when all x_k have been considered. In the Euclidean case, this exactly computes the weighted mean.\n\nThe algorithm has been shown to converge asymptotically with the sample size for the following manifolds equipped with their default metrics when all sampled points are in an open geodesic ball about the mean with corresponding radius (see GeodesicInterpolationWithinRadius):\n\nAll simply connected complete Riemannian manifolds with non-positive sectional curvature at radius [Cheng2016], in particular:\nEuclidean\nSymmetricPositiveDefinite [Ho2013]\nOther manifolds:\nSphere: fracπ2 [Salehian2015]\nGrassmann: fracπ4 [Chakraborty2015]\nStiefel/Rotations: fracπ2 sqrt 2 [Chakraborty2019]\n\nFor online variance computation, the algorithm additionally uses an analogous recursion to the weighted Welford algorithm [West1979].\n\n[Ho2013]: Ho J.; Cheng G.; Salehian H.; Vemuri B. C.; Recursive Karcher expectation estimators and geometric law of large numbers. Proceedings of the 16th International Conference on Artificial Intelligence and Statistics (2013), pp. 325–332. pdf.\n\n[Salehian2015]: Salehian H.; Chakraborty R.; Ofori E.; Vaillancourt D.; An efficient recursive estimator of the Fréchet mean on a hypersphere with applications to Medical Image Analysis. Mathematical Foundations of Computational Anatomy (2015). pdf.\n\n[Chakraborty2015]: Chakraborty R.; Vemuri B. C.; Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. Proceedings of the IEEE International Conference on Computer Vision (ICCV) (2015), pp. 4229-4237. doi: 10.1109/ICCV.2015.481, link.\n\n[Cheng2016]: Cheng G.; Ho J.; Salehian H.; Vemuri B. C.; Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. Riemannian Computing in Computer Vision. Springer, Cham (2016), pp. 21-43. doi: 10.1007/978-3-319-22957-7_2, pdf.\n\n[Chakraborty2019]: Chakraborty R.; Vemuri B. C.; Statistics on the (compact) Stiefel manifold: Theory and Applications. The Annals of Statistics (2019), 47(1), pp. 415-438. doi: 10.1214/18-AOS1692, arxiv: 1708.00045.\n\n[West1979]: West D. H. D.; Updating Mean and Variance Estimates: An Improved Method. Communications of the ACM (1979), 22(9), pp. 532–535. doi: 10.1145/359146.359153.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.GeodesicInterpolationWithinRadius","page":"Statistics","title":"Manifolds.GeodesicInterpolationWithinRadius","text":"GeodesicInterpolationWithinRadius{T} <: AbstractEstimationMethod\n\nEstimation of Riemannian center of mass using GeodesicInterpolation with fallback to GradientDescentEstimation if any points are outside of a geodesic ball of specified radius around the mean.\n\nConstructor\n\nGeodesicInterpolationWithinRadius(radius)\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.GradientDescentEstimation","page":"Statistics","title":"Manifolds.GradientDescentEstimation","text":"GradientDescentEstimation <: AbstractEstimationMethod\n\nMethod for estimation using gradient descent.\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.WeiszfeldEstimation","page":"Statistics","title":"Manifolds.WeiszfeldEstimation","text":"WeiszfeldEstimation <: AbstractEstimationMethod\n\nMethod for estimation using the Weiszfeld algorithm for the median\n\n\n\n\n\n","category":"type"},{"location":"features/statistics.html#Manifolds.default_estimation_method-Tuple{AbstractManifold, Any}","page":"Statistics","title":"Manifolds.default_estimation_method","text":"default_estimation_method(M::AbstractManifold, f)\n\nSpecify a default AbstractEstimationMethod for an AbstractManifold for a function f, e.g. the median or the mean.\n\nNote that his function is decorated, so it can inherit from the embedding, for example for the IsEmbeddedSubmanifold trait.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.cov-Tuple{AbstractManifold, AbstractVector}","page":"Statistics","title":"Statistics.cov","text":"Statistics.cov(\n M::AbstractManifold,\n x::AbstractVector;\n basis::AbstractBasis=DefaultOrthonormalBasis(),\n tangent_space_covariance_estimator::CovarianceEstimator=SimpleCovariance(;\n corrected=true,\n ),\n mean_estimation_method::AbstractEstimationMethod=GradientDescentEstimation(),\n inverse_retraction_method::AbstractInverseRetractionMethod=default_inverse_retraction_method(\n M, eltype(x),\n ),\n)\n\nEstimate the covariance matrix of a set of points x on manifold M. Since the covariance matrix on a manifold is a rank 2 tensor, the function returns its coefficients in basis induced by the given tangent space basis. See Section 5 of [Pennec2006] for details.\n\nThe mean is calculated using the specified mean_estimation_method using [mean](@ref Statistics.mean(::AbstractManifold, ::AbstractVector, ::AbstractEstimationMethod), and tangent vectors at this mean are calculated using the provided inverse_retraction_method. Finally, the covariance matrix in the tangent plane is estimated using the Euclidean space estimator tangent_space_covariance_estimator. The type CovarianceEstimator is defined in StatsBase.jl and examples of covariance estimation methods can be found in CovarianceEstimation.jl.\n\n[Pennec2006]: X. Pennec, “Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements,” J Math Imaging Vis, vol. 25, no. 1, p. 127, Jul. 2006, doi: 10.1007/s10851-006-6228-4.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean!-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.mean!","text":"mean!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)\nmean!(\n M::AbstractManifold,\n y,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n)\n\nCompute the mean in-place in y.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, AbstractVector, AbstractVector, ExtrinsicEstimation}","page":"Statistics","title":"Statistics.mean","text":"mean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::ExtrinsicEstimation;\n kwargs...,\n)\n\nEstimate the Riemannian center of mass of x using ExtrinsicEstimation, i.e. by computing the mean in the embedding and projecting the result back. You can specify an extrinsic_method to specify which mean estimation method to use in the embedding, which defaults to GeodesicInterpolation.\n\nSee mean for a description of the remaining kwargs.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, AbstractVector, AbstractVector, GeodesicInterpolationWithinRadius}","page":"Statistics","title":"Statistics.mean","text":"mean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::GeodesicInterpolationWithinRadius;\n kwargs...,\n)\n\nEstimate the Riemannian center of mass of x using GeodesicInterpolationWithinRadius.\n\nSee mean for a description of kwargs.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, AbstractVector, AbstractVector, GeodesicInterpolation}","page":"Statistics","title":"Statistics.mean","text":"mean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::GeodesicInterpolation;\n shuffle_rng=nothing,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),\n kwargs...,\n)\n\nEstimate the Riemannian center of mass of x in an online fashion using repeated weighted geodesic interpolation. See GeodesicInterpolation for details.\n\nIf shuffle_rng is provided, it is used to shuffle the order in which the points are considered for computing the mean.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.mean-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.mean","text":"mean(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)\n\nCompute the (optionally weighted) Riemannian center of mass also known as Karcher mean of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer\n\nargmin_y mathcal M frac12 sum_i=1^n w_i sum_i=1^n w_imathrmd_mathcal M^2(yx_i)\n\nwhere mathrmd_mathcal M denotes the Riemannian distance.\n\nIn the general case, the GradientDescentEstimation is used to compute the mean. mean( M::AbstractManifold, x::AbstractVector, [w::AbstractWeights,] method::AbstractEstimationMethod=defaultestimationmethod(M); kwargs..., )\n\nCompute the mean using the specified method.\n\nmean(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::GradientDescentEstimation;\n p0=x[1],\n stop_iter=100,\n retraction::AbstractRetractionMethod = default_retraction_method(M),\n inverse_retraction::AbstractInverseRetractionMethod = default_retraction_method(M, eltype(x)),\n kwargs...,\n)\n\nCompute the mean using the gradient descent scheme GradientDescentEstimation.\n\nOptionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\nThe Theory stems from[Karcher1977] and is also described in[PennecArsigny2013] as the exponential barycenter. The algorithm is further described in[Afsari2013].\n\n[Afsari2013]: Afsari, B; Tron, R.; Vidal, R.: On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass, SIAM Journal on Control and Optimization (2013), 51(3), pp. 2230–2260, doi: 10.1137/12086282X, arxiv: 1201.0925\n\n[PennecArsigny2013]: Pennec X., Arsigny V.: Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Nielsen F., Bhatia R. (eds) Matrix Information Geometry, (2013), pp. 123-166. doi: 10.1007/978-3-642-30232-9_7, hal: https://hal.inria.fr/hal-00699361/document\n\n[Karcher1977]: Karcher, H.: Riemannian center of mass and mollifier smoothing. Communications on Pure Applied Mathematics (1977), 30, pp. 509–541. doi 10.1002/cpa.3160300502\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median!-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.median!","text":"median!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)\nmedian!(\n M::AbstractManifold,\n y,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n)\n\ncomputes the median in-place in y.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, AbstractVector, AbstractVector, CyclicProximalPointEstimation}","page":"Statistics","title":"Statistics.median","text":"median(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::CyclicProximalPointEstimation;\n p0=x[1],\n stop_iter=1000000,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x),),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x),),\n kwargs...,\n)\n\nCompute the median using CyclicProximalPointEstimation.\n\nOptionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\nThe algorithm is further described in [Bačák2014].\n\n[Bačák2014]: Bačák, M: Computing Medians and Means in Hadamard Spaces. SIAM Journal on Optimization (2014), 24(3), pp. 1542–1566, doi: 10.1137/140953393, arxiv: 1210.2145\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, AbstractVector, AbstractVector, ExtrinsicEstimation}","page":"Statistics","title":"Statistics.median","text":"median(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::ExtrinsicEstimation;\n extrinsic_method = CyclicProximalPointEstimation(),\n kwargs...,\n)\n\nEstimate the median of x using ExtrinsicEstimation, i.e. by computing the median in the embedding and projecting the result back. You can specify an extrinsic_method to specify which median estimation method to use in the embedding, which defaults to CyclicProximalPointEstimation.\n\nSee median for a description of kwargs.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, AbstractVector, AbstractVector, Manifolds.WeiszfeldEstimation}","page":"Statistics","title":"Statistics.median","text":"median(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::WeiszfeldEstimation;\n α = 1.0,\n p0=x[1],\n stop_iter=2000,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),\n kwargs...,\n)\n\nCompute the median using WeiszfeldEstimation.\n\nOptionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.\n\nThe parameter αin (02 is a step size.\n\nThe algorithm is further described in [FletcherVenkatasubramanianJoshi2008], especially the update rule in Eq. (6), i.e. Let q_k denote the current iterate, n the number of points x_1ldotsx_n, and\n\nI_k = bigl i in 1ldotsn big x_i neq q_k bigr\n\nall indices of points that are not equal to the current iterate. Then the update reads q_k+1 = exp_q_k(αX), where\n\nX = frac1ssum_iin I_k fracw_id_mathcal M(q_kx_i)log_q_kx_i\nquad\ntext with \nquad\ns = sum_iin I_k fracw_id_mathcal M(q_kx_i)\n\nand where mathrmd_mathcal M denotes the Riemannian distance.\n\nOptionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction, which by default use the exponential and logarithmic map, respectively.\n\n[FletcherVenkatasubramanianJoshi2008]: Fletcher, T., Venkatasubramanian, S., Joshi, S: Robust statistics on Riemannian manifolds via the geometric median 2008 IEEE Conference on Computer Vision and Pattern Recognition, doi: 10.1109/CVPR.2008.4587747,\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.median-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.median","text":"median(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)\nmedian(\n M::AbstractManifold,\n x::AbstractVector,\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n)\n\nCompute the (optionally weighted) Riemannian median of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer\n\nargmin_y mathcal M frac1sum_i=1^n w_i sum_i=1^n w_imathrmd_mathcal M(yx_i)\n\nwhere mathrmd_mathcal M denotes the Riemannian distance. This function is nonsmooth (i.e nondifferentiable).\n\nIn the general case, the CyclicProximalPointEstimation is used to compute the median. However, this default may be overloaded for specific manifolds.\n\nCompute the median using the specified method.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.std-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"Statistics.std","text":"std(M, x, m=mean(M, x); corrected=true, kwargs...)\nstd(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false, kwargs...)\n\ncompute the optionally weighted standard deviation of a Vector x of n data points on the AbstractManifold M, i.e.\n\nsqrtfrac1c sum_i=1^n w_i d_mathcal M^2 (x_im)\n\nwhere c is a correction term, see Statistics.std. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Statistics.var-Tuple{AbstractManifold, Any}","page":"Statistics","title":"Statistics.var","text":"var(M, x, m=mean(M, x); corrected=true)\nvar(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false)\n\ncompute the (optionally weighted) variance of a Vector x of n data points on the AbstractManifold M, i.e.\n\nfrac1c sum_i=1^n w_i d_mathcal M^2 (x_im)\n\nwhere c is a correction term, see Statistics.var. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true. All further kwargs... are passed to the computation of the mean (if that is not provided).\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.kurtosis-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights}","page":"Statistics","title":"StatsBase.kurtosis","text":"kurtosis(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))\n\nCompute the excess kurtosis of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_std-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"StatsBase.mean_and_std","text":"mean_and_std(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, std)\n\nCompute the mean and the standard deviation std simultaneously.\n\nmean_and_std(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n) -> (mean, var)\n\nUse the method for simultaneously computing the mean and standard deviation. To use a mean-specific method, call mean and then std.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_var-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights, GeodesicInterpolationWithinRadius}","page":"Statistics","title":"StatsBase.mean_and_var","text":"mean_and_var(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::GeodesicInterpolationWithinRadius;\n kwargs...,\n) -> (mean, var)\n\nUse repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.\n\nSee GeodesicInterpolationWithinRadius and mean_and_var for more information.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_var-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights, GeodesicInterpolation}","page":"Statistics","title":"StatsBase.mean_and_var","text":"mean_and_var(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::GeodesicInterpolation;\n shuffle_rng::Union{AbstractRNG,Nothing} = nothing,\n retraction::AbstractRetractionMethod = default_retraction_method(M, eltype(x)),\n inverse_retraction::AbstractInverseRetractionMethod = default_inverse_retraction_method(M, eltype(x)),\n kwargs...,\n) -> (mean, var)\n\nUse the repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.\n\nIf shuffle_rng is provided, it is used to shuffle the order in which the points are considered. Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.\n\nSee GeodesicInterpolation for details on the geodesic interpolation method.\n\nnote: Note\nThe Welford algorithm for the variance is experimental and is not guaranteed to give accurate results except on Euclidean.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.mean_and_var-Tuple{AbstractManifold, Vararg{Any}}","page":"Statistics","title":"StatsBase.mean_and_var","text":"mean_and_var(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, var)\n\nCompute the mean and the variance simultaneously. See those functions for a description of the arguments.\n\nmean_and_var(\n M::AbstractManifold,\n x::AbstractVector\n [w::AbstractWeights,]\n method::AbstractEstimationMethod;\n kwargs...,\n) -> (mean, var)\n\nUse the method for simultaneously computing the mean and variance. To use a mean-specific method, call mean and then var.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#StatsBase.moment","page":"Statistics","title":"StatsBase.moment","text":"moment(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))\n\nCompute the kth central moment of points in x on manifold M. Optionally provide weights w and/or a precomputed mean.\n\n\n\n\n\n","category":"function"},{"location":"features/statistics.html#StatsBase.skewness-Tuple{AbstractManifold, AbstractVector, StatsBase.AbstractWeights}","page":"Statistics","title":"StatsBase.skewness","text":"skewness(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))\n\nCompute the standardized skewness of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.\n\n\n\n\n\n","category":"method"},{"location":"features/statistics.html#Literature","page":"Statistics","title":"Literature","text":"","category":"section"},{"location":"manifolds/spectrahedron.html#Spectrahedron","page":"Spectrahedron","title":"Spectrahedron","text":"","category":"section"},{"location":"manifolds/spectrahedron.html","page":"Spectrahedron","title":"Spectrahedron","text":"Modules = [Manifolds]\nPages = [\"manifolds/Spectrahedron.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/spectrahedron.html#Manifolds.Spectrahedron","page":"Spectrahedron","title":"Manifolds.Spectrahedron","text":"Spectrahedron{N,K} <: AbstractDecoratorManifold{ℝ}\n\nThe Spectrahedron manifold, also known as the set of correlation matrices (symmetric positive semidefinite matrices) of rank k with unit trace.\n\nbeginaligned\nmathcal S(nk) =\nbiglp ℝ^n n big a^mathrmTpa geq 0 text for all a ℝ^n\noperatornametr(p) = sum_i=1^n p_ii = 1\ntextand p = qq^mathrmT text for q in ℝ^n k\ntext with operatornamerank(p) = operatornamerank(q) = k\nbigr\nendaligned\n\nThis manifold is working solely on the matrices q. Note that this q is not unique, indeed for any orthogonal matrix A we have (qA)(qA)^mathrmT = qq^mathrmT = p, so the manifold implemented here is the quotient manifold. The unit trace translates to unit frobenius norm of q.\n\nThe tangent space at p, denoted T_pmathcal E(nk), is also represented by matrices Yin ℝ^n k and reads as\n\nT_pmathcal S(nk) = bigl\nX ℝ^n nX = qY^mathrmT + Yq^mathrmT\ntext with operatornametr(X) = sum_i=1^nX_ii = 0\nbigr\n\nendowed with the Euclidean metric from the embedding, i.e. from the ℝ^n k\n\nThis manifold was for example investigated in[JourneeBachAbsilSepulchre2010].\n\nConstructor\n\nSpectrahedron(n,k)\n\ngenerates the manifold mathcal S(nk) subset ℝ^n n.\n\n[JourneeBachAbsilSepulchre2010]: Journée, M., Bach, F., Absil, P.-A., and Sepulchre, R.: “Low-Rank Optimization on the Cone of Positive Semidefinite Matrices”, SIAM Journal on Optimization (20)5, pp. 2327–2351, 2010. doi: 10.1137/080731359, arXiv: 0807.4423.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.check_point-Union{Tuple{K}, Tuple{N}, Tuple{Spectrahedron{N, K}, Any}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.check_point","text":"check_point(M::Spectrahedron, q; kwargs...)\n\nchecks, whether q is a valid reprsentation of a point p=qq^mathrmT on the Spectrahedron M, i.e. is a matrix of size (N,K), such that p is symmetric positive semidefinite and has unit trace, i.e. q has to have unit frobenius norm. Since by construction p is symmetric, this is not explicitly checked. Since p is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.check_vector-Union{Tuple{K}, Tuple{N}, Tuple{Spectrahedron{N, K}, Any, Any}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.check_vector","text":"check_vector(M::Spectrahedron, q, Y; kwargs...)\n\nCheck whether X = qY^mathrmT + Yq^mathrmT is a tangent vector to p=qq^mathrmT on the Spectrahedron M, i.e. atfer check_point of q, Y has to be of same dimension as q and a X has to be a symmetric matrix with trace. The tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetry of X holds by construction and is not explicitly checked.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.is_flat-Tuple{Spectrahedron}","page":"Spectrahedron","title":"ManifoldsBase.is_flat","text":"is_flat(::Spectrahedron)\n\nReturn false. Spectrahedron is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.manifold_dimension-Union{Tuple{Spectrahedron{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Spectrahedron)\n\nreturns the dimension of Spectrahedron M=mathcal S(nk) nk ℕ, i.e.\n\ndim mathcal S(nk) = nk - 1 - frack(k-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.project-Tuple{Spectrahedron, Any}","page":"Spectrahedron","title":"ManifoldsBase.project","text":"project(M::Spectrahedron, q)\n\nproject q onto the manifold Spectrahedron M, by normalizing w.r.t. the Frobenius norm\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.project-Tuple{Spectrahedron, Vararg{Any}}","page":"Spectrahedron","title":"ManifoldsBase.project","text":"project(M::Spectrahedron, q, Y)\n\nProject Y onto the tangent space at q, i.e. row-wise onto the Spectrahedron manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.representation_size-Union{Tuple{Spectrahedron{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Spectrahedron","title":"ManifoldsBase.representation_size","text":"representation_size(M::Spectrahedron)\n\nReturn the size of an array representing an element on the Spectrahedron manifold M, i.e. n k, the size of such factor of p=qq^mathrmT on mathcal M = mathcal S(nk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.retract-Tuple{Spectrahedron, Any, Any, ProjectionRetraction}","page":"Spectrahedron","title":"ManifoldsBase.retract","text":"retract(M::Spectrahedron, q, Y, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting q+Y back onto the manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.vector_transport_to-Tuple{Spectrahedron, Any, Any, Any, ProjectionTransport}","page":"Spectrahedron","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Spectrahedron, p, X, q)\n\ntransport the tangent vector X at p to q by projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#ManifoldsBase.zero_vector-Tuple{Spectrahedron, Vararg{Any}}","page":"Spectrahedron","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Spectrahedron,p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the Spectrahedron manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spectrahedron.html#Literature","page":"Spectrahedron","title":"Literature","text":"","category":"section"},{"location":"manifolds/choleskyspace.html#Cholesky-space","page":"Cholesky space","title":"Cholesky space","text":"","category":"section"},{"location":"manifolds/choleskyspace.html","page":"Cholesky space","title":"Cholesky space","text":"The Cholesky space is a Riemannian manifold on the lower triangular matrices. Its metric is based on the cholesky decomposition. The CholeskySpace is used to define the LogCholeskyMetric on the manifold of SymmetricPositiveDefinite matrices.","category":"page"},{"location":"manifolds/choleskyspace.html","page":"Cholesky space","title":"Cholesky space","text":"Modules = [Manifolds]\nPages = [\"manifolds/CholeskySpace.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/choleskyspace.html#Manifolds.CholeskySpace","page":"Cholesky space","title":"Manifolds.CholeskySpace","text":"CholeskySpace{N} <: AbstractManifold{ℝ}\n\nThe manifold of lower triangular matrices with positive diagonal and a metric based on the cholesky decomposition. The formulae for this manifold are for example summarized in Table 1 of [Lin2019].\n\nConstructor\n\nCholeskySpace(n)\n\nGenerate the manifold of n n lower triangular matrices with positive diagonal.\n\n[Lin2019]: Lin, Zenhua: Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition, arXiv: 1908.09326.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/choleskyspace.html","page":"Cholesky space","title":"Cholesky space","text":"Modules = [Manifolds]\nPages = [\"manifolds/CholeskySpace.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/choleskyspace.html#Base.exp-Tuple{CholeskySpace, Vararg{Any}}","page":"Cholesky space","title":"Base.exp","text":"exp(M::CholeskySpace, p, X)\n\nCompute the exponential map on the CholeskySpace M emanating from the lower triangular matrix with positive diagonal p towards the lower triangular matrix X The formula reads\n\nexp_p X = p + X + operatornamediag(p)\noperatornamediag(p)expbigl( operatornamediag(X)operatornamediag(p)^-1bigr)\n\nwhere cdot denotes the strictly lower triangular matrix, and operatornamediag extracts the diagonal matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#Base.log-Tuple{LinearAlgebra.Cholesky, Vararg{Any}}","page":"Cholesky space","title":"Base.log","text":"log(M::CholeskySpace, X, p, q)\n\nCompute the logarithmic map on the CholeskySpace M for the geodesic emanating from the lower triangular matrix with positive diagonal p towards q. The formula reads\n\nlog_p q = p - q + operatornamediag(p)logbigl(operatornamediag(q)operatornamediag(p)^-1bigr)\n\nwhere cdot denotes the strictly lower triangular matrix, and operatornamediag extracts the diagonal matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.check_point-Tuple{CholeskySpace, Any}","page":"Cholesky space","title":"ManifoldsBase.check_point","text":"check_point(M::CholeskySpace, p; kwargs...)\n\nCheck whether the matrix p lies on the CholeskySpace M, i.e. it's size fits the manifold, it is a lower triangular matrix and has positive entries on the diagonal. The tolerance for the tests can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.check_vector-Tuple{CholeskySpace, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.check_vector","text":"check_vector(M::CholeskySpace, p, X; kwargs... )\n\nCheck whether v is a tangent vector to p on the CholeskySpace M, i.e. after check_point(M,p), X has to have the same dimension as p and a symmetric matrix. The tolerance for the tests can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.distance-Tuple{CholeskySpace, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.distance","text":"distance(M::CholeskySpace, p, q)\n\nCompute the Riemannian distance on the CholeskySpace M between two matrices p, q that are lower triangular with positive diagonal. The formula reads\n\nd_mathcal M(pq) = sqrtsum_ij (p_ij-q_ij)^2 +\nsum_j=1^m (log p_jj - log q_jj)^2\n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.inner-Tuple{CholeskySpace, Any, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.inner","text":"inner(M::CholeskySpace, p, X, Y)\n\nCompute the inner product on the CholeskySpace M at the lower triangular matric with positive diagonal p and the two tangent vectors X,Y, i.e they are both lower triangular matrices with arbitrary diagonal. The formula reads\n\ng_p(XY) = sum_ij X_ijY_ij + sum_j=1^m X_iiY_iip_ii^-2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.is_flat-Tuple{CholeskySpace}","page":"Cholesky space","title":"ManifoldsBase.is_flat","text":"is_flat(::CholeskySpace)\n\nReturn false. CholeskySpace is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.manifold_dimension-Union{Tuple{CholeskySpace{N}}, Tuple{N}} where N","page":"Cholesky space","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::CholeskySpace)\n\nReturn the manifold dimension for the CholeskySpace M, i.e.\n\n dim(mathcal M) = fracN(N+1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.parallel_transport_to-Tuple{CholeskySpace, Any, Any, Any}","page":"Cholesky space","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::CholeskySpace, p, X, q)\n\nParallely transport the tangent vector X at p along the geodesic to q on the CholeskySpace manifold M. The formula reads\n\nmathcal P_qp(X) = X \n+ operatornamediag(q)operatornamediag(p)^-1operatornamediag(X)\n\nwhere cdot denotes the strictly lower triangular matrix, and operatornamediag extracts the diagonal matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.representation_size-Union{Tuple{CholeskySpace{N}}, Tuple{N}} where N","page":"Cholesky space","title":"ManifoldsBase.representation_size","text":"representation_size(M::CholeskySpace)\n\nReturn the representation size for the CholeskySpace{N} M, i.e. (N,N).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#ManifoldsBase.zero_vector-Tuple{CholeskySpace, Vararg{Any}}","page":"Cholesky space","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::CholeskySpace, p)\n\nReturn the zero tangent vector on the CholeskySpace M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/choleskyspace.html#Literature","page":"Cholesky space","title":"Literature","text":"","category":"section"},{"location":"features/utilities.html#Ease-of-notation","page":"Utilities","title":"Ease of notation","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"The following terms introduce a nicer notation for some operations, for example using the ∈ operator, p mathcal M, to determine whether p is a point on the AbstractManifold mathcal M.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"in\nTangentSpace","category":"page"},{"location":"features/utilities.html#Base.in","page":"Utilities","title":"Base.in","text":"Base.in(p, M::AbstractManifold; kwargs...)\np ∈ M\n\nCheck, whether a point p is a valid point (i.e. in) a AbstractManifold M. This method employs is_point deactivating the error throwing option.\n\n\n\n\n\nBase.in(p, TpM::TangentSpaceAtPoint; kwargs...)\nX ∈ TangentSpaceAtPoint(M,p)\n\nCheck whether X is a tangent vector from (in) the tangent space T_pmathcal M, i.e. the TangentSpaceAtPoint at p on the AbstractManifold M. This method uses is_vector deactivating the error throw option.\n\n\n\n\n\n","category":"function"},{"location":"features/utilities.html#ManifoldsBase.TangentSpace","page":"Utilities","title":"ManifoldsBase.TangentSpace","text":"TangentSpace(M::AbstractManifold, p)\n\nReturn a TangentSpaceAtPoint representing tangent space at p on the AbstractManifold M.\n\n\n\n\n\n","category":"constant"},{"location":"features/utilities.html#Fallback-for-the-exponential-map:-Solving-the-corresponding-ODE","page":"Utilities","title":"Fallback for the exponential map: Solving the corresponding ODE","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"When additionally loading NLSolve.jl the following fallback for the exponential map is available.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"Modules = [Manifolds]\nPages = [\"nlsolve.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/utilities.html#Public-documentation","page":"Utilities","title":"Public documentation","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"The following functions are of interest for extending and using the ProductManifold.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"submanifold_component\nsubmanifold_components\nProductRepr","category":"page"},{"location":"features/utilities.html#Manifolds.submanifold_component","page":"Utilities","title":"Manifolds.submanifold_component","text":"submanifold_component(M::AbstractManifold, p, i::Integer)\nsubmanifold_component(M::AbstractManifold, p, ::Val(i)) where {i}\nsubmanifold_component(p, i::Integer)\nsubmanifold_component(p, ::Val(i)) where {i}\n\nProject the product array p on M to its ith component. A new array is returned.\n\n\n\n\n\n","category":"function"},{"location":"features/utilities.html#Manifolds.submanifold_components","page":"Utilities","title":"Manifolds.submanifold_components","text":"submanifold_components(M::AbstractManifold, p)\nsubmanifold_components(p)\n\nGet the projected components of p on the submanifolds of M. The components are returned in a Tuple.\n\n\n\n\n\n","category":"function"},{"location":"features/utilities.html#Manifolds.ProductRepr","page":"Utilities","title":"Manifolds.ProductRepr","text":"ProductRepr(parts)\n\nA more general but slower representation of points and tangent vectors on a product manifold.\n\nExample:\n\nA product point on a product manifold Sphere(2) × Euclidean(2) might be created as\n\nProductRepr([1.0, 0.0, 0.0], [2.0, 3.0])\n\nwhere [1.0, 0.0, 0.0] is the part corresponding to the sphere factor and [2.0, 3.0] is the part corresponding to the euclidean manifold.\n\nwarning: Warning\nProductRepr is deprecated and will be removed in a future release. Please use ArrayPartition instead.\n\n\n\n\n\n","category":"type"},{"location":"features/utilities.html#Specific-exception-types","page":"Utilities","title":"Specific exception types","text":"","category":"section"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"For some manifolds it is useful to keep an extra index, at which point on the manifold, the error occurred as well as to collect all errors that occurred on a manifold. This page contains the manifold-specific error messages this package introduces.","category":"page"},{"location":"features/utilities.html","page":"Utilities","title":"Utilities","text":"Modules = [Manifolds]\nPages = [\"errors.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/oblique.html#Oblique-manifold","page":"Oblique manifold","title":"Oblique manifold","text":"","category":"section"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"The oblique manifold mathcalOB(nm) is modeled as an AbstractPowerManifold of the (real-valued) Sphere and uses ArrayPowerRepresentation. Points on the torus are hence matrices, x ℝ^nm.","category":"page"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/Oblique.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/oblique.html#Manifolds.Oblique","page":"Oblique manifold","title":"Manifolds.Oblique","text":"Oblique{N,M,𝔽} <: AbstractPowerManifold{𝔽}\n\nThe oblique manifold mathcalOB(nm) is the set of 𝔽-valued matrices with unit norm column endowed with the metric from the embedding. This yields exactly the same metric as considering the product metric of the unit norm vectors, i.e. PowerManifold of the (n-1)-dimensional Sphere.\n\nThe Sphere is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.\n\nConstructor\n\nOblique(n,m)\n\nGenerate the manifold of matrices mathbb R^n m such that the m columns are unit vectors, i.e. from the Sphere(n-1).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/oblique.html#Functions","page":"Oblique manifold","title":"Functions","text":"","category":"section"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:","category":"page"},{"location":"manifolds/oblique.html","page":"Oblique manifold","title":"Oblique manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/Oblique.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/oblique.html#ManifoldsBase.check_point-Tuple{Oblique, Any}","page":"Oblique manifold","title":"ManifoldsBase.check_point","text":"check_point(M::Oblique{n,m},p)\n\nChecks whether p is a valid point on the Oblique{m,n} M, i.e. is a matrix of m unit columns from mathbb R^n, i.e. each column is a point from Sphere(n-1).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/oblique.html#ManifoldsBase.check_vector-Union{Tuple{m}, Tuple{n}, Tuple{Oblique{n, m}, Any, Any}} where {n, m}","page":"Oblique manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::Oblique p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the Oblique M. This means, that p is valid, that X is of correct dimension and columnswise a tangent vector to the columns of p on the Sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/oblique.html#ManifoldsBase.parallel_transport_to-Tuple{Oblique, Any, Any, Any}","page":"Oblique manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::Oblique, p, X, q)\n\nCompute the parallel transport on the Oblique manifold by doing a column wise parallel transport on the Sphere\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Orthogonal-and-Unitary-matrices","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary matrices","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Both OrthogonalMatrices and UnitaryMatrices are quite similar, as are Rotations, as well as unitary matrices with determinant equal to one. So these share a {common implementation}(@ref generalunitarymatrices)","category":"page"},{"location":"manifolds/generalunitary.html#Orthogonal-Matrices","page":"Orthogonal and Unitary Matrices","title":"Orthogonal Matrices","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Orthogonal.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/generalunitary.html#Manifolds.OrthogonalMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.OrthogonalMatrices","text":" OrthogonalMatrices{n} = GeneralUnitaryMatrices{n,ℝ,AbsoluteDeterminantOneMatrices}\n\nThe manifold of (real) orthogonal matrices mathrmO(n).\n\nOrthogonalMatrices(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Unitary-Matrices","page":"Orthogonal and Unitary Matrices","title":"Unitary Matrices","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Unitary.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/generalunitary.html#Manifolds.UnitaryMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.UnitaryMatrices","text":"const UnitaryMatrices{n,𝔽} = AbstarctUnitaryMatrices{n,𝔽,AbsoluteDeterminantOneMatrices}\n\nThe manifold U(n𝔽) of nn complex matrices (when 𝔽=ℂ) or quaternionic matrices (when 𝔽=ℍ) such that\n\np^mathrmHp = mathrmI_n\n\nwhere mathrmI_n is the nn identity matrix. Such matrices p have a property that lVert det(p) rVert = 1.\n\nThe tangent spaces are given by\n\n T_pU(n) coloneqq bigl\n X big pY text where Y text is skew symmetric i e Y = -Y^mathrmH\n bigr\n\nBut note that tangent vectors are represented in the Lie algebra, i.e. just using Y in the representation above.\n\nConstructor\n\nUnitaryMatrices(n, 𝔽::AbstractNumbers=ℂ)\n\nsee also OrthogonalMatrices for the real valued case.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{UnitaryMatrices{n, ℂ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::UnitaryMatrices{n,ℂ}) where {n}\n\nReturn the dimension of the manifold unitary matrices.\n\ndim_mathrmU(n) = n^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{UnitaryMatrices{n, ℍ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::UnitaryMatrices{n,ℍ})\n\nReturn the dimension of the manifold unitary matrices.\n\ndim_mathrmU(n ℍ) = n(2n+1)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#generalunitarymatrices","page":"Orthogonal and Unitary Matrices","title":"Common functions","text":"","category":"section"},{"location":"manifolds/generalunitary.html","page":"Orthogonal and Unitary Matrices","title":"Orthogonal and Unitary Matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/GeneralUnitaryMatrices.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/generalunitary.html#Manifolds.AbsoluteDeterminantOneMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.AbsoluteDeterminantOneMatrices","text":"AbsoluteDeterminantOneMatrices <: AbstractMatrixType\n\nA type to indicate that we require (orthogonal / unitary) matrices with normed determinant, i.e. that the absolute value of the determinant is 1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Manifolds.AbstractMatrixType","page":"Orthogonal and Unitary Matrices","title":"Manifolds.AbstractMatrixType","text":"AbstractMatrixType\n\nA plain type to distinguish different types of matrices, for example DeterminantOneMatrices and AbsoluteDeterminantOneMatrices\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Manifolds.DeterminantOneMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.DeterminantOneMatrices","text":"DeterminantOneMatrices <: AbstractMatrixType\n\nA type to indicate that we require special (orthogonal / unitary) matrices, i.e. of determinant 1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Manifolds.GeneralUnitaryMatrices","page":"Orthogonal and Unitary Matrices","title":"Manifolds.GeneralUnitaryMatrices","text":"GeneralUnitaryMatrices{n,𝔽,S<:AbstractMatrixType} <: AbstractDecoratorManifold\n\nA common parametric type for matrices with a unitary property of size nn over the field mathbb F which additionally have the AbstractMatrixType, e.g. are DeterminantOneMatrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalunitary.html#Base.exp-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Base.exp","text":"exp(M::Rotations, p, X)\nexp(M::OrthogonalMatrices, p, X)\nexp(M::UnitaryMatrices, p, X)\n\nCompute the exponential map, that is, since X is represented in the Lie algebra,\n\nexp_p(X) = p\\mathrm{e}^X\n\nFor different sizes, like n=234 there is specialised implementations\n\nThe algorithm used is a more numerically stable form of those proposed in [Gallier2002] and [Andrica2013].\n\n[Gallier2002]: Gallier J.; Xu D.; Computing exponentials of skew-symmetric matrices and logarithms of orthogonal matrices. International Journal of Robotics and Automation (2002), 17(4), pp. 1-11. pdf.\n\n[Andrica2013]: Andrica D.; Rohan R.-A.; Computing the Rodrigues coefficients of the exponential map of the Lie groups of matrices. Balkan Journal of Geometry and Its Applications (2013), 18(2), pp. 1-2. pdf.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Base.log-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Base.log","text":"log(M::Rotations, p, X)\nlog(M::OrthogonalMatrices, p, X)\nlog(M::UnitaryMatrices, p, X)\n\nCompute the logarithmic map, that is, since the resulting X is represented in the Lie algebra,\n\nlog_p q = \\log(p^{\\mathrm{H}q)\n\nwhich is projected onto the skew symmetric matrices for numerical stability.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Base.log-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Vararg{Any}}} where n","page":"Orthogonal and Unitary Matrices","title":"Base.log","text":"log(M::Rotations, p, q)\n\nCompute the logarithmic map on the Rotations manifold M which is given by\n\nlog_p q = operatornamelog(p^mathrmTq)\n\nwhere operatornameLog denotes the matrix logarithm. For numerical stability, the result is projected onto the set of skew symmetric matrices.\n\nFor antipodal rotations the function returns deterministically one of the tangent vectors that point at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.cos_angles_4d_rotation_matrix-Tuple{Any}","page":"Orthogonal and Unitary Matrices","title":"Manifolds.cos_angles_4d_rotation_matrix","text":"cos_angles_4d_rotation_matrix(R)\n\n4D rotations can be described by two orthogonal planes that are unchanged by the action of the rotation (vectors within a plane rotate only within the plane). The cosines of the two angles αβ of rotation about these planes may be obtained from the distinct real parts of the eigenvalues of the rotation matrix. This function computes these more efficiently by solving the system\n\nbeginaligned\ncos α + cos β = frac12 operatornametr(R)\ncos α cos β = frac18 operatornametr(R)^2\n - frac116 operatornametr((R - R^T)^2) - 1\nendaligned\n\nBy convention, the returned values are sorted in decreasing order. See also angles_4d_skew_sym_matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℂ, Manifolds.DeterminantOneMatrices}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}) where {n}\n\nVolume of the manifold of complex general unitary matrices of determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nsqrtn 2^n-1 π^(n-1)(n+2)2 prod_k=1^n-1frac1k\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ, Manifolds.AbsoluteDeterminantOneMatrices}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℝ,AbsoluteDeterminantOneMatrices}) where {n}\n\nVolume of the manifold of real orthogonal matrices of absolute determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nbegincases\nfrac2^k(2pi)^k^2prod_s=1^k-1 (2s) text if n = 2k \nfrac2^k+1(2pi)^k(k+1)prod_s=1^k-1 (2s+1) text if n = 2k+1\nendcases\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{Rotations{n}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℝ,DeterminantOneMatrices}) where {n}\n\nVolume of the manifold of real orthogonal matrices of determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nbegincases\n2 text if n = 0 \nfrac2^k-12(2pi)^k^2prod_s=1^k-1 (2s) text if n = 2k+2 \nfrac2^k+12(2pi)^k(k+1)prod_s=1^k-1 (2s+1) text if n = 2k+1\nendcases\n\nIt differs from the paper by a factor of sqrt(2) due to a different choice of normalization.\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.manifold_volume-Union{Tuple{UnitaryMatrices{n, ℂ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.manifold_volume","text":"manifold_volume(::GeneralUnitaryMatrices{n,ℂ,AbsoluteDeterminantOneMatrices}) where {n}\n\nVolume of the manifold of complex general unitary matrices of absolute determinant one. The formula reads [BoyaSudarshanTilma2003]:\n\nsqrtn 2^n+1 π^n(n+1)2 prod_k=1^n-1frac1k\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.volume_density-Tuple{Manifolds.GeneralUnitaryMatrices{2, ℝ}, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Manifolds.volume_density","text":"volume_density(M::GeneralUnitaryMatrices{2,ℝ}, p, X)\n\nVolume density on O(2)/SO(2) is equal to 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.volume_density-Tuple{Manifolds.GeneralUnitaryMatrices{3, ℝ}, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"Manifolds.volume_density","text":"volume_density(M::GeneralUnitaryMatrices{3,ℝ}, p, X)\n\nCompute the volume density on O(3)/SO(3). The formula reads [FalorsideHaanDavidsonForré2019]:\n\nfrac1-1cos(sqrt2lVert X rVert)lVert X rVert^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Manifolds.volume_density-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Any, Any}} where n","page":"Orthogonal and Unitary Matrices","title":"Manifolds.volume_density","text":"volume_density(M::GeneralUnitaryMatrices{n,ℝ}, p, X) where {n}\n\nCompute volume density function of a sphere, i.e. determinant of the differential of exponential map exp(M, p, X). It is derived from Eq. (4.1) and Corollary 4.4 in [ChevallierLiLuDunson2022]. See also Theorem 4.1 in [FalorsideHaanDavidsonForré2019], (note that it uses a different convention).\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n[FalorsideHaanDavidsonForré2019]: L. Falorsi, P. de Haan, T. R. Davidson, and P. Forré, “Reparameterizing Distributions on Lie Groups,” arXiv:1903.02958 [cs, math, stat], Mar. 2019 doi: 10.48550/arXiv.1903.02958\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽, Manifolds.DeterminantOneMatrices}, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.check_point","text":"check_point(M::Rotations, p; kwargs...)\n\nCheck whether p is a valid point on the UnitaryMatrices M, i.e. that p has an determinante of absolute value one, i.e. that p^mathrmHp\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{UnitaryMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.check_point","text":"check_point(M::UnitaryMatrices, p; kwargs...)\ncheck_point(M::OrthogonalMatrices, p; kwargs...)\ncheck_point(M::GeneralUnitaryMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether p is a valid point on the UnitaryMatrices or [OrthogonalMatrices] M, i.e. that p has an determinante of absolute value one\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}, Any, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::UnitaryMatrices{n}, p, X; kwargs... )\ncheck_vector(M::OrthogonalMatrices{n}, p, X; kwargs... )\ncheck_vector(M::Rotations{n}, p, X; kwargs... )\ncheck_vector(M::GeneralUnitaryMatrices{n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the UnitaryMatrices space M, i.e. after check_point(M,p), X has to be skew symmetric (Hermitian) and orthogonal to p.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.embed-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.embed","text":"embed(M::GeneralUnitaryMatrices{n,𝔽}, p, X)\n\nEmbed the tangent vector X at point p in M from its Lie algebra representation (set of skew matrices) into the Riemannian submanifold representation\n\nThe formula reads\n\nX_textembedded = p * X\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.get_coordinates-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Vararg{Any}}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::Rotations, p, X)\nget_coordinates(M::OrthogonalMatrices, p, X)\nget_coordinates(M::UnitaryMatrices, p, X)\n\nExtract the unique tangent vector components X^i at point p on Rotations mathrmSO(n) from the matrix representation X of the tangent vector.\n\nThe basis on the Lie algebra 𝔰𝔬(n) is chosen such that for mathrmSO(2), X^1 = θ = X_21 is the angle of rotation, and for mathrmSO(3), (X^1 X^2 X^3) = (X_32 X_13 X_21) = θ u is the angular velocity and axis-angle representation, where u is the unit vector along the axis of rotation.\n\nFor mathrmSO(n) where n 4, the additional elements of X^i are X^j (j - 3)2 + k + 1 = X_jk, for j 4n k 1j).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.get_embedding-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}}, Tuple{𝔽}, Tuple{n}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::OrthogonalMatrices{n})\nget_embedding(M::Rotations{n})\nget_embedding(M::UnitaryMatrices{n})\n\nReturn the embedding, i.e. The mathbb F^nn, where mathbb F = mathbb R for the first two and mathbb F = mathbb C for the unitary matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.get_vector-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Vararg{Any}}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.get_vector","text":"get_vector(M::OrthogonalMatrices, p, Xⁱ, B::DefaultOrthogonalBasis)\nget_vector(M::Rotations, p, Xⁱ, B::DefaultOrthogonalBasis)\n\nConvert the unique tangent vector components Xⁱ at point p on Rotations or OrthogonalMatrices to the matrix representation X of the tangent vector. See get_coordinates for the conventions used.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.injectivity_radius-Tuple{Manifolds.GeneralUnitaryMatrices}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(G::GeneraliUnitaryMatrices)\n\nReturn the injectivity radius for general unitary matrix manifolds, which is[1]\n\n operatornameinj_mathrmU(n) = π\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.injectivity_radius-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℂ, Manifolds.DeterminantOneMatrices}}, Tuple{ℂ}, Tuple{n}} where {n, ℂ}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(G::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})\n\nReturn the injectivity radius for general complex unitary matrix manifolds, where the determinant is +1, which is[1]\n\n operatornameinj_mathrmSU(n) = π sqrt2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.injectivity_radius-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(G::SpecialOrthogonal)\ninjectivity_radius(G::Orthogonal)\ninjectivity_radius(M::Rotations)\ninjectivity_radius(M::Rotations, ::ExponentialRetraction)\n\nReturn the radius of injectivity on the Rotations manifold M, which is πsqrt2. [1]\n\n[1]: For a derivation of the injectivity radius, see sethaxen.com/blog/2023/02/the-injectivity-radii-of-the-unitary-groups/.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.is_flat-Tuple{Manifolds.GeneralUnitaryMatrices}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.is_flat","text":"is_flat(M::GeneralUnitaryMatrices)\n\nReturn true if GeneralUnitaryMatrices M is SO(2) or U(1) and false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℂ, Manifolds.DeterminantOneMatrices}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})\n\nReturn the dimension of the manifold of special unitary matrices.\n\ndim_mathrmSU(n) = n^2-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.manifold_dimension-Union{Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}}, Tuple{n}} where n","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Rotations)\nmanifold_dimension(M::OrthogonalMatrices)\n\nReturn the dimension of the manifold orthogonal matrices and of the manifold of rotations\n\ndim_mathrmO(n) = dim_mathrmSO(n) = fracn(n-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.project-Tuple{Manifolds.GeneralUnitaryMatrices, Any, Any}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.project","text":" project(M::OrthogonalMatrices{n}, p, X)\n project(M::Rotations{n}, p, X)\n project(M::UnitaryMatrices{n}, p, X)\n\nOrthogonally project the tangent vector X 𝔽^n n, mathbb F mathbb R mathbb C to the tangent space of M at p, and change the representer to use the corresponding Lie algebra, i.e. we compute\n\n operatornameproj_p(X) = fracp^mathrmH X - (p^mathrmH X)^mathrmH2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.project-Union{Tuple{𝔽}, Tuple{n}, Tuple{UnitaryMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.project","text":" project(G::UnitaryMatrices{n}, p)\n project(G::OrthogonalMatrices{n}, p)\n\nProject the point p 𝔽^n n to the nearest point in mathrmU(n𝔽)=Unitary(n,𝔽) under the Frobenius norm. If p = U S V^mathrmH is the singular value decomposition of p, then the projection is\n\n operatornameproj_mathrmU(n𝔽) colon p U V^mathrmH\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.retract-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}, Any, Any, PolarRetraction}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.retract","text":"retract(M::Rotations, p, X, ::PolarRetraction)\nretract(M::OrthogonalMatrices, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group) and is a second-order approximation of the exponential map. Let\n\nUSV = p + pX\n\nbe the singular value decomposition, then the formula reads\n\noperatornameretr_p X = UV^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.retract-Union{Tuple{𝔽}, Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, 𝔽}, Any, Any, QRRetraction}} where {n, 𝔽}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.retract","text":"retract(M::Rotations, p, X, ::QRRetraction)\nretract(M::OrthogonalMatrices, p. X, ::QRRetraction)\n\nCompute the QR-based retraction on the Rotations and OrthogonalMatrices M from p in direction X (as an element of the Lie group), which is a first-order approximation of the exponential map.\n\nThis is also the default retraction on these manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#ManifoldsBase.riemann_tensor-Tuple{Manifolds.GeneralUnitaryMatrices, Vararg{Any, 4}}","page":"Orthogonal and Unitary Matrices","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::GeneralUnitaryMatrices, p, X, Y, Z)\n\nCompute the value of Riemann tensor on the GeneralUnitaryMatrices manifold. The formula reads[Rentmeesters2011] R(XY)Z=frac14Z X Y.\n\n[Rentmeesters2011]: Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Statistics.mean-Union{Tuple{n}, Tuple{Manifolds.GeneralUnitaryMatrices{n, ℝ}, Any}} where n","page":"Orthogonal and Unitary Matrices","title":"Statistics.mean","text":"mean(\n M::Rotations,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/2/√2);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalunitary.html#Footnotes-and-References","page":"Orthogonal and Unitary Matrices","title":"Footnotes and References","text":"","category":"section"},{"location":"tutorials/integration.html#Integration","page":"integrate on manifolds and handle probability densities","title":"Integration","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"This part of documentation covers integration of scalar functions defined on manifolds f colon mathcalM to mathbbR:","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"int_mathcal M f(p) mathrmdp","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"The basic concepts are derived from geometric measure theory. In principle, there are many ways in which a manifold can be equipped with a measure that can be later used to define an integral. One of the most popular ways is based on pushing the Lebesgue measure on a tangent space through the exponential map. Any other suitable atlas could be used, not just the one defined by normal coordinates, though each one requires different volume density corrections due to the Jacobian determinant of the pushforward. Manifolds.jl provides the function volume_density that calculates that quantity, denoted theta_p(X). See for example [1], Definition 11, for a precise description using Jacobi fields.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"While many sources define volume density as a function of two points, Manifolds.jl decided to use the more general point-tangent vector formulation. The two-points variant can be implemented as","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"using Manifolds\nvolume_density_two_points(M::AbstractManifold, p, q) = volume_density(M, p, log(M, p, q))","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"volume_density_two_points (generic function with 1 method)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"The simplest way to of integrating a function on a compact manifold is through a 📖 Monte Carlo integrator. A simple variant can be implemented as follows (assuming uniform distribution of rand):","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"using LinearAlgebra, Distributions, SpecialFunctions\nfunction simple_mc_integrate(M::AbstractManifold, f; N::Int = 1000)\n V = manifold_volume(M)\n sum = 0.0\n q = rand(M)\n for i in 1:N\n sum += f(M, q)\n rand!(M, q)\n end\n return V * sum/N\nend","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"simple_mc_integrate (generic function with 1 method)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"We used the function manifold_volume to get the volume of the set over which the integration is performed, as described in the linked Wikipedia article.","category":"page"},{"location":"tutorials/integration.html#Distributions","page":"integrate on manifolds and handle probability densities","title":"Distributions","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"We will now try to verify that volume density correction correctly changes probability density of an exponential-wrapped normal distribution. pdf_tangent_space represents probability density of a normally distributed random variable X_T in the tangent space T_p mathcalM. Its probability density (with respect to the Lebesgue measure of the tangent space) is f_X_Tcolon T_p mathcalM to mathbbR.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"pdf_manifold refers to the probability density of the distribution X_M from the tangent space T_p mathcalM wrapped using exponential map on the manifold. The formula for probability density with respect to pushforward measure of the Lebesgue measure in the tangent space reads","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"f_X_M(q) = sum_X in T_pmathcalM exp_p(X)=q fracf_X_T(X)theta_p(X)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"volume_density function calculates the correction theta_p(X).","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"function pdf_tangent_space(M::AbstractManifold, p)\n return pdf(MvNormal(zeros(manifold_dimension(M)), 0.2*I), p)\nend\n\nfunction pdf_manifold(M::AbstractManifold, q)\n p = [1.0, 0.0, 0.0]\n X = log(M, p, q)\n Xc = get_coordinates(M, p, X, DefaultOrthonormalBasis())\n vd = abs(volume_density(M, p, X))\n if vd > eps()\n return pdf_tangent_space(M, Xc) / vd\n else\n return 0.0\n end\nend\n\nprintln(simple_mc_integrate(Sphere(2), pdf_manifold; N=1000000))","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"0.9988842504754084","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"The function simple_mc_integrate, defined in the previous section, is used to verify that the density integrates to 1 over the manifold.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Note that our pdf_manifold implements a simplified version of f_X_M which assumes that the probability mass of pdf_tangent_space outside of (local) injectivity radius at p is negligible. In such case there is only one non-zero summand in the formula for f_X_M(q), namely X=log_p(q). Otherwise we would have to consider other vectors Yin T_p mathcalM such that exp_p(Y) = q in that sum.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Remarkably, exponential-wrapped distributions possess three important qualities [2]:","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Densities of X_M are explicit. There is no normalization constant that needs to be computed like in truncated distributions.\nSampling from X_M is easy. It suffices to get a sample from X_T and pass it to the exponential map.\nIf mean of X_T is 0, then there is a simple correspondence between moments of X_M and X_T, for example p is the mean of X_M.","category":"page"},{"location":"tutorials/integration.html#Kernel-density-estimation","page":"integrate on manifolds and handle probability densities","title":"Kernel density estimation","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"We can also make a Pelletier’s isotropic kernel density estimator. Given points p_1 p_2 dots p_n on d-dimensional manifold mathcal M the density at point q is defined as","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"f(q) = frac1n h^d sum_i=1^n frac1theta_q(log_q(p_i))Kleft( fracd(q p_i)h right)","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"where h is the bandwidth, a small positive number less than the injectivity radius of mathcal M and KcolonmathbbRtomathbbR is a kernel function. Note that Pelletier’s estimator can only use radially-symmetric kernels. The radially symmetric multivariate Epanechnikov kernel used in the example below is described in [3].","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"struct PelletierKDE{TM<:AbstractManifold,TPts<:AbstractVector}\n M::TM\n bandwidth::Float64\n pts::TPts\nend\n\n(kde::PelletierKDE)(::AbstractManifold, p) = kde(p)\nfunction (kde::PelletierKDE)(p)\n n = length(kde.pts)\n d = manifold_dimension(kde.M)\n sum_kde = 0.0\n function epanechnikov_kernel(x)\n if x < 1\n return gamma(2+d/2) * (1-x^2)/(π^(d/2))\n else\n return 0.0\n end\n end\n for i in 1:n\n X = log(kde.M, p, kde.pts[i])\n Xn = norm(kde.M, p, X)\n sum_kde += epanechnikov_kernel(Xn / kde.bandwidth) / volume_density(kde.M, p, X)\n end\n sum_kde /= n * kde.bandwidth^d\n return sum_kde\nend\n\nM = Sphere(2)\npts = rand(M, 8)\nkde = PelletierKDE(M, 0.7, pts)\nprintln(simple_mc_integrate(Sphere(2), kde; N=1000000))\nprintln(kde(rand(M)))","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"0.9988319869387484\n0.0","category":"page"},{"location":"tutorials/integration.html#Technical-notes","page":"integrate on manifolds and handle probability densities","title":"Technical notes","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"This section contains a few technical notes that are relevant to the problem of integration on manifolds but can be freely skipped on the first read of the tutorial.","category":"page"},{"location":"tutorials/integration.html#Conflicting-statements-about-volume-of-a-manifold","page":"integrate on manifolds and handle probability densities","title":"Conflicting statements about volume of a manifold","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"manifold_volume and volume_density are closely related to each other, though very few sources explore this connection, and some even claiming a certain level of arbitrariness in defining manifold_volume. Volume is sometimes considered arbitrary because Riemannian metrics on some spaces like the manifold of rotations are defined with arbitrary constants. However, once a constant is picked (and it must be picked before any useful computation can be performed), all geometric operations must follow in a consistent way: inner products, exponential and logarithmic maps, volume densities, etc. Manifolds.jl consistently picks such constants and provides a unified framework, though it sometimes results in picking a different constant than what is the most popular in some sub-communities.","category":"page"},{"location":"tutorials/integration.html#Haar-measures","page":"integrate on manifolds and handle probability densities","title":"Haar measures","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"On Lie groups the situation regarding integration is more complicated. Invariance under left or right group action is a desired property that leads one to consider Haar measures [4]. It is, however, unclear what are the practical benefits of considering Haar measures over the Lebesgue measure of the underlying manifold, which often turns out to be invariant anyway.","category":"page"},{"location":"tutorials/integration.html#Integration-in-charts","page":"integrate on manifolds and handle probability densities","title":"Integration in charts","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"Integration through charts is an approach currently not supported by Manifolds.jl. One has to define a suitable set of disjoint charts covering the entire manifold and use a method for multivariate Euclidean integration. Note that ranges of parameters have to be adjusted for each manifold and scaling based on the metric needs to be applied. See [5] for some considerations on symmetric spaces.","category":"page"},{"location":"tutorials/integration.html#References","page":"integrate on manifolds and handle probability densities","title":"References","text":"","category":"section"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[1]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"A. le Brigant and S. Puechmorel, “Approximation of Densities on Riemannian Manifolds,” Entropy, vol. 21, no. 1, Art. no. 1, Jan. 2019, doi: 10.3390/e21010043.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[2]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[3]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"N. Langrené and X. Warin, “Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating,” Journal of Computational and Graphical Statistics, vol. 28, no. 3, pp. 596–608, Jul. 2019, doi: 10.1080/10618600.2018.1549052.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[4]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"S. Tornier, “Haar Measures.” arXiv, Jun. 19, 2020. doi: 10.48550/arXiv.2006.10956.","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"[5]","category":"page"},{"location":"tutorials/integration.html","page":"integrate on manifolds and handle probability densities","title":"integrate on manifolds and handle probability densities","text":"L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1","category":"page"},{"location":"manifolds/multinomialdoublystochastic.html#Multinomial-doubly-stochastic-matrices","page":"Multinomial doubly stochastic matrices","title":"Multinomial doubly stochastic matrices","text":"","category":"section"},{"location":"manifolds/multinomialdoublystochastic.html","page":"Multinomial doubly stochastic matrices","title":"Multinomial doubly stochastic matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/MultinomialDoublyStochastic.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/multinomialdoublystochastic.html#Manifolds.AbstractMultinomialDoublyStochastic","page":"Multinomial doubly stochastic matrices","title":"Manifolds.AbstractMultinomialDoublyStochastic","text":"AbstractMultinomialDoublyStochastic{N} <: AbstractDecoratorManifold{ℝ}\n\nA common type for manifolds that are doubly stochastic, for example by direct constraint MultinomialDoubleStochastic or by symmetry MultinomialSymmetric, as long as they are also modeled as IsIsometricEmbeddedManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomialdoublystochastic.html#Manifolds.MultinomialDoubleStochastic","page":"Multinomial doubly stochastic matrices","title":"Manifolds.MultinomialDoubleStochastic","text":"MultinomialDoublyStochastic{n} <: AbstractMultinomialDoublyStochastic{N}\n\nThe set of doubly stochastic multinomial matrices consists of all nn matrices with stochastic columns and rows, i.e.\n\nbeginaligned\nmathcalDP(n) coloneqq biglp ℝ^nn big p_ij 0 text for all i=1n j=1m\n pmathbf1_n = p^mathrmTmathbf1_n = mathbf1_n\nbigr\nendaligned\n\nwhere mathbf1_n is the vector of length n containing ones.\n\nThe tangent space can be written as\n\nT_pmathcalDP(n) coloneqq bigl\nX ℝ^nn big X = X^mathrmT text and \nXmathbf1_n = X^mathrmTmathbf1_n = mathbf0_n\nbigr\n\nwhere mathbf0_n is the vector of length n containing zeros.\n\nMore details can be found in Section III[DouikHassibi2019].\n\nConstructor\n\nMultinomialDoubleStochastic(n)\n\nGenerate the manifold of matrices mathbb R^nn that are doubly stochastic and symmetric.\n\n[DouikHassibi2019]: A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.check_point-Union{Tuple{n}, Tuple{MultinomialDoubleStochastic{n}, Any}} where n","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.check_point","text":"check_point(M::MultinomialDoubleStochastic, p)\n\nChecks whether p is a valid point on the MultinomialDoubleStochastic(n) M, i.e. is a matrix with positive entries whose rows and columns sum to one.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.check_vector-Union{Tuple{n}, Tuple{MultinomialDoubleStochastic{n}, Any, Any}} where n","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::MultinomialDoubleStochastic p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the MultinomialDoubleStochastic M. This means, that p is valid, that X is of correct dimension and sums to zero along any column or row.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.is_flat-Tuple{MultinomialDoubleStochastic}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::MultinomialDoubleStochastic)\n\nReturn false. MultinomialDoubleStochastic is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.manifold_dimension-Union{Tuple{MultinomialDoubleStochastic{n}}, Tuple{n}} where n","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::MultinomialDoubleStochastic{n}) where {n}\n\nreturns the dimension of the MultinomialDoubleStochastic manifold namely\n\noperatornamedim_mathcalDP(n) = (n-1)^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.project-Tuple{Manifolds.AbstractMultinomialDoublyStochastic, Any}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.project","text":"project(\n M::AbstractMultinomialDoublyStochastic,\n p;\n maxiter = 100,\n tolerance = eps(eltype(p))\n)\n\nproject a matrix p with positive entries applying Sinkhorn's algorithm. Note that this projct method – different from the usual case, accepts keywords.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.project-Tuple{MultinomialDoubleStochastic, Any, Any}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.project","text":"project(M::MultinomialDoubleStochastic{n}, p, Y) where {n}\n\nProject Y onto the tangent space at p on the MultinomialDoubleStochastic M, return the result in X. The formula reads\n\n operatornameproj_p(Y) = Y - (αmathbf1_n^mathrmT + mathbf1_nβ^mathrmT) p\n\nwhere denotes the Hadamard or elementwise product and mathbb1_n is the vector of length n containing ones. The two vectors αβ ℝ^nn are computed as a solution (typically using the left pseudo inverse) of\n\n beginpmatrix I_n pp^mathrmT I_n endpmatrix\n beginpmatrix α βendpmatrix\n =\n beginpmatrix Ymathbf1Y^mathrmTmathbf1endpmatrix\n\nwhere I_n is the nn unit matrix and mathbf1_n is the vector of length n containing ones.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#ManifoldsBase.retract-Tuple{MultinomialDoubleStochastic, Any, Any, ProjectionRetraction}","page":"Multinomial doubly stochastic matrices","title":"ManifoldsBase.retract","text":"retract(M::MultinomialDoubleStochastic, p, X, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting podotexp(Xp) back onto the manifold, where are elementwise multiplication and division, respectively. Similarly, exp refers to the elementwise exponentiation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialdoublystochastic.html#Literature","page":"Multinomial doubly stochastic matrices","title":"Literature","text":"","category":"section"},{"location":"manifolds/product.html#ProductManifoldSection","page":"Product manifold","title":"Product manifold","text":"","category":"section"},{"location":"manifolds/product.html","page":"Product manifold","title":"Product manifold","text":"Product manifold mathcal M = mathcalM_1 mathcalM_2 mathcalM_n of manifolds mathcalM_1 mathcalM_2 mathcalM_n. Points on the product manifold can be constructed using ProductRepr with canonical projections Π_i mathcalM mathcalM_i for i 1 2 n provided by submanifold_component.","category":"page"},{"location":"manifolds/product.html","page":"Product manifold","title":"Product manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProductManifold.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/product.html#Manifolds.InverseProductRetraction","page":"Product manifold","title":"Manifolds.InverseProductRetraction","text":"InverseProductRetraction(retractions::AbstractInverseRetractionMethod...)\n\nProduct inverse retraction of inverse retractions. Works on ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductBasisData","page":"Product manifold","title":"Manifolds.ProductBasisData","text":"ProductBasisData\n\nA typed tuple to store tuples of data of stored/precomputed bases for a ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductFVectorDistribution","page":"Product manifold","title":"Manifolds.ProductFVectorDistribution","text":"ProductFVectorDistribution([type::VectorBundleFibers], [x], distrs...)\n\nGenerates a random vector at point x from vector space (a fiber of a tangent bundle) of type type using the product distribution of given distributions.\n\nVector space type and x can be automatically inferred from distributions distrs.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductManifold","page":"Product manifold","title":"Manifolds.ProductManifold","text":"ProductManifold{𝔽,TM<:Tuple} <: AbstractManifold{𝔽}\n\nProduct manifold M_1 M_2 M_n with product geometry.\n\nConstructor\n\nProductManifold(M_1, M_2, ..., M_n)\n\ngenerates the product manifold M_1 M_2 M_n. Alternatively, the same manifold can be contructed using the × operator: M_1 × M_2 × M_3.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductMetric","page":"Product manifold","title":"Manifolds.ProductMetric","text":"ProductMetric <: AbstractMetric\n\nA type to represent the product of metrics for a ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductPointDistribution","page":"Product manifold","title":"Manifolds.ProductPointDistribution","text":"ProductPointDistribution(M::ProductManifold, distributions)\n\nProduct distribution on manifold M, combined from distributions.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductRetraction","page":"Product manifold","title":"Manifolds.ProductRetraction","text":"ProductRetraction(retractions::AbstractRetractionMethod...)\n\nProduct retraction of retractions. Works on ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Manifolds.ProductVectorTransport","page":"Product manifold","title":"Manifolds.ProductVectorTransport","text":"ProductVectorTransport(methods::AbstractVectorTransportMethod...)\n\nProduct vector transport type of methods. Works on ProductManifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/product.html#Base.exp-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Base.exp","text":"exp(M::ProductManifold, p, X)\n\ncompute the exponential map from p in the direction of X on the ProductManifold M, which is the elementwise exponential map on the internal manifolds that build M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.getindex-Tuple{ProductManifold, Integer}","page":"Product manifold","title":"Base.getindex","text":"getindex(M::ProductManifold, i)\nM[i]\n\naccess the ith manifold component from the ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.getindex-Tuple{ProductRepr, ProductManifold, Union{Colon, Integer, Val, AbstractVector}}","page":"Product manifold","title":"Base.getindex","text":"getindex(p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})\np[M::ProductManifold, i]\n\nAccess the element(s) at index i of a point p on a ProductManifold M by linear indexing. See also Array Indexing in Julia.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.log-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Base.log","text":"log(M::ProductManifold, p, q)\n\nCompute the logarithmic map from p to q on the ProductManifold M, which can be computed using the logarithmic maps of the manifolds elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.rand-Tuple{ProductManifold}","page":"Product manifold","title":"Base.rand","text":"rand(M::ProductManifold; parts_kwargs = map(_ -> (;), M.manifolds))\n\nReturn a random point on ProductManifold M. parts_kwargs is a tuple of keyword arguments for rand on each manifold in M.manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Base.setindex!-Tuple{Union{ProductRepr, ArrayPartition}, Any, ProductManifold, Union{Colon, Integer, Val, AbstractVector}}","page":"Product manifold","title":"Base.setindex!","text":"setindex!(q, p, M::ProductManifold, i::Union{Integer,Colon,AbstractVector})\nq[M::ProductManifold,i...] = p\n\nset the element [i...] of a point q on a ProductManifold by linear indexing to q. See also Array Indexing in Julia.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#LinearAlgebra.cross-Tuple{Vararg{AbstractManifold}}","page":"Product manifold","title":"LinearAlgebra.cross","text":"cross(M, N)\ncross(M1, M2, M3,...)\n\nReturn the ProductManifold For two AbstractManifolds M and N, where for the case that one of them is a ProductManifold itself, the other is either prepended (if N is a product) or appenden (if M) is. If both are product manifold, they are combined into one product manifold, keeping the order.\n\nFor the case that more than one is a product manifold of these is build with the same approach as above\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#LinearAlgebra.norm-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"LinearAlgebra.norm","text":"norm(M::ProductManifold, p, X)\n\nCompute the norm of X from the tangent space of p on the ProductManifold, i.e. from the element wise norms the 2-norm is computed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.flat-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Manifolds.flat","text":"flat(M::ProductManifold, p, X::FVector{TangentSpaceType})\n\nuse the musical isomorphism to transform the tangent vector X from the tangent space at p on the ProductManifold M to a cotangent vector. This can be done elementwise for every entry of X (with respect to the corresponding entry in p) separately.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.manifold_volume-Tuple{ProductManifold}","page":"Product manifold","title":"Manifolds.manifold_volume","text":"manifold_dimension(M::ProductManifold)\n\nReturn the volume of ProductManifold M, i.e. product of volumes of the manifolds M is constructed from.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.number_of_components-Union{Tuple{ProductManifold{𝔽, <:Tuple{Vararg{Any, N}}}}, Tuple{N}, Tuple{𝔽}} where {𝔽, N}","page":"Product manifold","title":"Manifolds.number_of_components","text":"number_of_components(M::ProductManifold{<:NTuple{N,Any}}) where {N}\n\nCalculate the number of manifolds multiplied in the given ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.sharp-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"Manifolds.sharp","text":"sharp(M::ProductManifold, p, ξ::FVector{CotangentSpaceType})\n\nUse the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on the ProductManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p) separately\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.submanifold-Tuple{ProductManifold, Integer}","page":"Product manifold","title":"Manifolds.submanifold","text":"submanifold(M::ProductManifold, i::Integer)\n\nExtract the ith factor of the product manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.submanifold-Tuple{ProductManifold, Val}","page":"Product manifold","title":"Manifolds.submanifold","text":"submanifold(M::ProductManifold, i::Val)\nsubmanifold(M::ProductManifold, i::AbstractVector)\n\nExtract the factor of the product manifold M indicated by indices in i. For example, for i equal to Val((1, 3)) the product manifold constructed from the first and the third factor is returned.\n\nThe version with AbstractVector is not type-stable, for better preformance use Val.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#Manifolds.volume_density-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"Manifolds.volume_density","text":"volume_density(M::ProductManifold, p, X)\n\nReturn volume density on the ProductManifold M, i.e. product of constituent volume densities.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.change_metric-Tuple{ProductManifold, AbstractMetric, Any, Any}","page":"Product manifold","title":"ManifoldsBase.change_metric","text":"change_metric(M::ProductManifold, ::AbstractMetric, p, X)\n\nSince the metric on a product manifold decouples, the change of metric can be done elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.change_representer-Tuple{ProductManifold, AbstractMetric, Any, Any}","page":"Product manifold","title":"ManifoldsBase.change_representer","text":"change_representer(M::ProductManifold, ::AbstractMetric, p, X)\n\nSince the metric on a product manifold decouples, the change of a representer can be done elementwise\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.check_point-Tuple{ProductManifold, Union{ProductRepr, ArrayPartition}}","page":"Product manifold","title":"ManifoldsBase.check_point","text":"check_point(M::ProductManifold, p; kwargs...)\n\nCheck whether p is a valid point on the ProductManifold M. If p is not a point on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.check_size-Tuple{ProductManifold, Union{ProductRepr, ArrayPartition}}","page":"Product manifold","title":"ManifoldsBase.check_size","text":"check_size(M::ProductManifold, p; kwargs...)\n\nCheck whether p is of valid size on the ProductManifold M. If p has components of wrong size a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.check_vector-Tuple{ProductManifold, Union{ProductRepr, ArrayPartition}, Union{ProductRepr, ArrayPartition}}","page":"Product manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::ProductManifold, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the ProductManifold M, i.e. all projections to base manifolds must be respective tangent vectors. If X is not a tangent vector to p on M a CompositeManifoldError.consisting of all error messages of the components, for which the tests fail is returned.\n\nThe tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.distance-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"ManifoldsBase.distance","text":"distance(M::ProductManifold, p, q)\n\nCompute the distance between two points p and q on the ProductManifold M, which is the 2-norm of the elementwise distances on the internal manifolds that build M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.get_component-Tuple{ProductManifold, Any, Any}","page":"Product manifold","title":"ManifoldsBase.get_component","text":"get_component(M::ProductManifold, p, i)\n\nGet the ith component of a point p on a ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.injectivity_radius-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::ProductManifold)\ninjectivity_radius(M::ProductManifold, x)\n\nCompute the injectivity radius on the ProductManifold, which is the minimum of the factor manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.inner-Tuple{ProductManifold, Any, Any, Any}","page":"Product manifold","title":"ManifoldsBase.inner","text":"inner(M::ProductManifold, p, X, Y)\n\ncompute the inner product of two tangent vectors X, Y from the tangent space at p on the ProductManifold M, which is just the sum of the internal manifolds that build M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.inverse_retract-Tuple{ProductManifold, Any, Any, Any, Manifolds.InverseProductRetraction}","page":"Product manifold","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::ProductManifold, p, q, m::InverseProductRetraction)\n\nCompute the inverse retraction from p with respect to q on the ProductManifold M using an InverseProductRetraction, which by default encapsulates a inverse retraction for each manifold of the product. Then this method is performed elementwise, so the encapsulated inverse retraction methods have to be available per factor.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.is_flat-Tuple{ProductManifold}","page":"Product manifold","title":"ManifoldsBase.is_flat","text":"is_flat(::ProductManifold)\n\nReturn true if and only if all component manifolds of ProductManifold M are flat.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.manifold_dimension-Tuple{ProductManifold}","page":"Product manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::ProductManifold)\n\nReturn the manifold dimension of the ProductManifold, which is the sum of the manifold dimensions the product is made of.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.retract-Tuple{ProductManifold, Vararg{Any}}","page":"Product manifold","title":"ManifoldsBase.retract","text":"retract(M::ProductManifold, p, X, m::ProductRetraction)\n\nCompute the retraction from p with tangent vector X on the ProductManifold M using an ProductRetraction, which by default encapsulates retractions of the base manifolds. Then this method is performed elementwise, so the encapsulated retractions method has to be one that is available on the manifolds.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.riemann_tensor-Tuple{ProductManifold, Vararg{Any, 4}}","page":"Product manifold","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::ProductManifold, p, X, Y, Z)\n\nCompute the Riemann tensor at point from p with tangent vectors X, Y and Z on the ProductManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.set_component!-Tuple{ProductManifold, Any, Any, Any}","page":"Product manifold","title":"ManifoldsBase.set_component!","text":"set_component!(M::ProductManifold, q, p, i)\n\nSet the ith component of a point q on a ProductManifold M to p, where p is a point on the AbstractManifold this factor of the product manifold consists of.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/product.html#ManifoldsBase.vector_transport_to-Tuple{ProductManifold, Any, Any, Any, ProductVectorTransport}","page":"Product manifold","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::ProductManifold, p, X, q, m::ProductVectorTransport)\n\nCompute the vector transport the tangent vector Xat p to q on the ProductManifold M using an ProductVectorTransport m. This method is performed elementwise, i.e. the method m has to be implemented on the base manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#SPDFixedDeterminantSection","page":"SPD, fixed determinant","title":"Symmetric positive definite matrices of fixed determinant","text":"","category":"section"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"SPDFixedDeterminant","category":"page"},{"location":"manifolds/spdfixeddeterminant.html#Manifolds.SPDFixedDeterminant","page":"SPD, fixed determinant","title":"Manifolds.SPDFixedDeterminant","text":"SPDFixedDeterminant{N,D} <: AbstractDecoratorManifold{ℝ}\n\nThe manifold of symmetric positive definite matrices of fixed determinant d 0, i.e.\n\nmathcal P_d(n) =\nbigl\np ℝ^n n big a^mathrmTpa 0 text for all a ℝ^nbackslash0\n text and det(p) = d\nbigr\n\nThis manifold is modelled as a submanifold of SymmetricPositiveDefinite(n).\n\nThese matrices are sometimes also called isochoric, which refers to the interpretation of the matrix representing an ellipsoid. All ellipsoids that represent points on this manifold have the same volume.\n\nThe tangent space is modelled the same as for SymmetricPositiveDefinite(n) and consists of all symmetric matrices with zero trace\n\n T_pmathcal P_d(n) =\n bigl\n X in mathbb R^nn big X=X^mathrmT text and operatornametr(p) = 0\n bigr\n\nsince for a constant determinant we require that 0 = D\\det(p)[Z] = \\det(p)\\operatorname{tr}(p^{-1}Z) for all tangent vectors Z. Additionally we store the tangent vectors as X=p^{-1}Z, i.e. symmetric matrices.\n\nConstructor\n\nSPDFixedDeterminant(n::Int, d::Real=1.0)\n\ngenerates the manifold mathcal P_d(n) subset mathcal P(n) of determinant d, which defaults to 1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"This manifold can is a submanifold of the symmetric positive definite matrices and hence inherits most properties therefrom.","category":"page"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"The differences are the functions","category":"page"},{"location":"manifolds/spdfixeddeterminant.html","page":"SPD, fixed determinant","title":"SPD, fixed determinant","text":"Modules = [Manifolds]\nPages = [\"manifolds/SPDFixedDeterminant.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.check_point-Union{Tuple{n}, Tuple{SPDFixedDeterminant{n}, Any}} where n","page":"SPD, fixed determinant","title":"ManifoldsBase.check_point","text":"check_point(M::SPDFixedDeterminant{n}, p; kwargs...)\n\nCheck whether p is a valid manifold point on the SPDFixedDeterminant(n,d) M, i.e. whether p is a SymmetricPositiveDefinite matrix of size (n, n)\n\nwith determinant det(p) =M.d.\n\nThe tolerance for the determinant of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.check_vector-Tuple{SPDFixedDeterminant, Any, Any}","page":"SPD, fixed determinant","title":"ManifoldsBase.check_vector","text":"check_vector(M::SPDFixedDeterminant, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SPDFixedDeterminant M, i.e. X has to be a tangent vector on SymmetricPositiveDefinite, so a symmetric matrix, and additionally fulfill operatornametr(X) = 0.\n\nThe tolerance for the trace check of X can be set using kwargs..., which influences the isapprox-check.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.project-Tuple{SPDFixedDeterminant, Any, Any}","page":"SPD, fixed determinant","title":"ManifoldsBase.project","text":"Y = project(M::SPDFixedDeterminant{n}, p, X)\nproject!(M::SPDFixedDeterminant{n}, Y, p, X)\n\nProject the symmetric matrix X onto the tangent space at p of the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of Y), by setting its diagonal (and hence its trace) to zero.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spdfixeddeterminant.html#ManifoldsBase.project-Tuple{SPDFixedDeterminant, Any}","page":"SPD, fixed determinant","title":"ManifoldsBase.project","text":"q = project(M::SPDFixedDeterminant{n}, p)\nproject!(M::SPDFixedDeterminant{n}, q, p)\n\nProject the symmetric positive definite (s.p.d.) matrix p from the embedding onto the (sub-)manifold of s.p.d. matrices of determinant M.d (in place of q).\n\nThe formula reads\n\nq = Bigl(fracddet(p)Bigr)^frac1np\n\n\n\n\n\n","category":"method"},{"location":"features/distributions.html#Distributions","page":"Distributions","title":"Distributions","text":"","category":"section"},{"location":"features/distributions.html","page":"Distributions","title":"Distributions","text":"The following functions and types provide support for manifold-valued and tangent space-valued distributions:","category":"page"},{"location":"features/distributions.html","page":"Distributions","title":"Distributions","text":"Modules = [Manifolds]\nPages = [\"distributions.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/distributions.html#Manifolds.FVectorDistribution","page":"Distributions","title":"Manifolds.FVectorDistribution","text":"FVectorDistribution{TSpace<:VectorBundleFibers, T}\n\nAn abstract distribution for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at point x from the given manifold). For example used for tangent vector-valued distributions.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.FVectorSupport","page":"Distributions","title":"Manifolds.FVectorSupport","text":"FVectorSupport(space::AbstractManifold, VectorBundleFibers)\n\nValue support for vector bundle fiber-valued distributions (values from a fiber of a vector bundle at a point from the given manifold). For example used for tangent vector-valued distributions.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.FVectorvariate","page":"Distributions","title":"Manifolds.FVectorvariate","text":"FVectorvariate\n\nStructure that subtypes VariateForm, indicating that a single sample is a vector from a fiber of a vector bundle.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.MPointDistribution","page":"Distributions","title":"Manifolds.MPointDistribution","text":"MPointDistribution{TM<:AbstractManifold}\n\nAn abstract distribution for points on manifold of type TM.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.MPointSupport","page":"Distributions","title":"Manifolds.MPointSupport","text":"MPointSupport(M::AbstractManifold)\n\nValue support for manifold-valued distributions (values from given AbstractManifold M).\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.MPointvariate","page":"Distributions","title":"Manifolds.MPointvariate","text":"MPointvariate\n\nStructure that subtypes VariateForm, indicating that a single sample is a point on a manifold.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Distributions.support-Tuple{T} where T<:Manifolds.FVectorDistribution","page":"Distributions","title":"Distributions.support","text":"support(d::FVectorDistribution)\n\nGet the object of type FVectorSupport for the distribution d.\n\n\n\n\n\n","category":"method"},{"location":"features/distributions.html","page":"Distributions","title":"Distributions","text":"Modules = [Manifolds]\nPages = [\"projected_distribution.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/distributions.html#Manifolds.ProjectedFVectorDistribution","page":"Distributions","title":"Manifolds.ProjectedFVectorDistribution","text":"ProjectedFVectorDistribution(type::VectorBundleFibers, p, d, project!)\n\nGenerates a random vector from ambient space of manifold type.manifold at point p and projects it to vector space of type type using function project!, see project for documentation. Generated arrays are of type TResult.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.ProjectedPointDistribution","page":"Distributions","title":"Manifolds.ProjectedPointDistribution","text":"ProjectedPointDistribution(M::AbstractManifold, d, proj!, p)\n\nGenerates a random point in ambient space of M and projects it to M using function proj!. Generated arrays are of type TResult, which can be specified by providing the p argument.\n\n\n\n\n\n","category":"type"},{"location":"features/distributions.html#Manifolds.normal_tvector_distribution-Tuple{AbstractManifold, Any, Any}","page":"Distributions","title":"Manifolds.normal_tvector_distribution","text":"normal_tvector_distribution(M::Euclidean, p, σ)\n\nNormal distribution in ambient space with standard deviation σ projected to tangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"features/distributions.html#Manifolds.projected_distribution","page":"Distributions","title":"Manifolds.projected_distribution","text":"projected_distribution(M::AbstractManifold, d, [p=rand(d)])\n\nWrap the standard distribution d into a manifold-valued distribution. Generated points will be of similar type to p. By default, the type is not changed.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/fixedrankmatrices.html#FixedRankMatrices","page":"Fixed-rank matrices","title":"Fixed-rank matrices","text":"","category":"section"},{"location":"manifolds/fixedrankmatrices.html","page":"Fixed-rank matrices","title":"Fixed-rank matrices","text":"Modules = [Manifolds]\nPages = [\"FixedRankMatrices.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/fixedrankmatrices.html#Manifolds.FixedRankMatrices","page":"Fixed-rank matrices","title":"Manifolds.FixedRankMatrices","text":"FixedRankMatrices{m,n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe manifold of m n real-valued or complex-valued matrices of fixed rank k, i.e.\n\nbigl p 𝔽^m n big operatornamerank(p) = k bigr\n\nwhere 𝔽 ℝℂ and the rank is the number of linearly independent columns of a matrix.\n\nRepresentation with 3 matrix factors\n\nA point p mathcal M can be stored using unitary matrices U 𝔽^m k, V 𝔽^n k as well as the k singular values of p = U_p S V_p^mathrmH, where cdot^mathrmH denotes the complex conjugate transpose or Hermitian. In other words, U and V are from the manifolds Stiefel(m,k,𝔽) and Stiefel(n,k,𝔽), respectively; see SVDMPoint for details.\n\nThe tangent space T_p mathcal M at a point p mathcal M with p=U_p S V_p^mathrmH is given by\n\nT_pmathcal M = bigl U_p M V_p^mathrmH + U_X V_p^mathrmH + U_p V_X^mathrmH \n M 𝔽^k k\n U_X 𝔽^m k\n V_X 𝔽^n k\n text st \n U_p^mathrmHU_X = 0_k\n V_p^mathrmHV_X = 0_k\nbigr\n\nwhere 0_k is the k k zero matrix. See UMVTVector for details.\n\nThe (default) metric of this manifold is obtained by restricting the metric on ℝ^m n to the tangent bundle[Vandereycken2013].\n\nConstructor\n\nFixedRankMatrices(m, n, k[, field=ℝ])\n\nGenerate the manifold of m-by-n (field-valued) matrices of rank k.\n\n[Vandereycken2013]: Bart Vandereycken: \"Low-rank matrix completion by Riemannian Optimization, SIAM Journal on Optiomoization, 23(2), pp. 1214–1236, 2013. doi: 10.1137/110845768, arXiv: 1209.3834.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/fixedrankmatrices.html#Manifolds.SVDMPoint","page":"Fixed-rank matrices","title":"Manifolds.SVDMPoint","text":"SVDMPoint <: AbstractManifoldPoint\n\nA point on a certain manifold, where the data is stored in a svd like fashion, i.e. in the form USV^mathrmH, where this structure stores U, S and V^mathrmH. The storage might also be shortened to just k singular values and accordingly shortened U (columns) and V^mathrmH (rows).\n\nConstructors\n\nSVDMPoint(A) for a matrix A, stores its svd factors (i.e. implicitly k=minmn)\nSVDMPoint(S) for an SVD object, stores its svd factors (i.e. implicitly k=minmn)\nSVDMPoint(U,S,Vt) for the svd factors to initialize the SVDMPoint(i.e. implicitlyk=\\min\\{m,n\\}`)\nSVDMPoint(A,k) for a matrix A, stores its svd factors shortened to the best rank k approximation\nSVDMPoint(S,k) for an SVD object, stores its svd factors shortened to the best rank k approximation\nSVDMPoint(U,S,Vt,k) for the svd factors to initialize the SVDMPoint, stores its svd factors shortened to the best rank k approximation\n\n\n\n\n\n","category":"type"},{"location":"manifolds/fixedrankmatrices.html#Manifolds.UMVTVector","page":"Fixed-rank matrices","title":"Manifolds.UMVTVector","text":"UMVTVector <: TVector\n\nA tangent vector that can be described as a product U_p M V_p^mathrmH + U_X V_p^mathrmH + U_p V_X^mathrmH, where X = U_X S V_X^mathrmH is its base point, see for example FixedRankMatrices.\n\nThe base point p is required for example embedding this point, but it is not stored. The fields of thie tangent vector are U for U_X, M and Vt to store V_X^mathrmH\n\nConstructors\n\nUMVTVector(U,M,Vt) store umv factors to initialize the UMVTVector\nUMVTVector(U,M,Vt,k) store the umv factors after shortening them down to inner dimensions k.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/fixedrankmatrices.html#Base.rand-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"Base.rand","text":"Random.rand(M::FixedRankMatrices; vector_at=nothing, kwargs...)\n\nIf vector_at is nothing, return a random point on the FixedRankMatrices manifold. The orthogonal matrices are sampled from the Stiefel manifold and the singular values are sampled uniformly at random.\n\nIf vector_at is not nothing, generate a random tangent vector in the tangent space of the point vector_at on the FixedRankMatrices manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.check_point-Union{Tuple{k}, Tuple{n}, Tuple{m}, Tuple{FixedRankMatrices{m, n, k}, Any}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.check_point","text":"check_point(M::FixedRankMatrices{m,n,k}, p; kwargs...)\n\nCheck whether the matrix or SVDMPoint x ids a valid point on the FixedRankMatrices{m,n,k,𝔽} M, i.e. is an m-byn matrix of rank k. For the SVDMPoint the internal representation also has to have the right shape, i.e. p.U and p.Vt have to be unitary. The keyword arguments are passed to the rank function that verifies the rank of p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.check_vector-Union{Tuple{k}, Tuple{n}, Tuple{m}, Tuple{FixedRankMatrices{m, n, k}, SVDMPoint, UMVTVector}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M:FixedRankMatrices{m,n,k}, p, X; kwargs...)\n\nCheck whether the tangent UMVTVector X is from the tangent space of the SVDMPoint p on the FixedRankMatrices M, i.e. that v.U and v.Vt are (columnwise) orthogonal to x.U and x.Vt, respectively, and its dimensions are consistent with p and X.M, i.e. correspond to m-by-n matrices of rank k.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.default_inverse_retraction_method-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.default_inverse_retraction_method","text":"default_inverse_retraction_method(M::FixedRankMatrices)\n\nReturn PolarInverseRetraction as the default inverse retraction for the FixedRankMatrices manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.default_retraction_method-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::FixedRankMatrices)\n\nReturn PolarRetraction as the default retraction for the FixedRankMatrices manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.default_vector_transport_method-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::FixedRankMatrices)\n\nReturn the ProjectionTransport as the default vector transport method for the FixedRankMatrices manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.embed-Tuple{FixedRankMatrices, SVDMPoint, UMVTVector}","page":"Fixed-rank matrices","title":"ManifoldsBase.embed","text":"embed(M::FixedRankMatrices, p, X)\n\nEmbed the tangent vector X at point p in M from its UMVTVector representation into the set of mn matrices.\n\nThe formula reads\n\nU_pMV_p^mathrmH + U_XV_p^mathrmH + U_pV_X^mathrmH\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.embed-Tuple{FixedRankMatrices, SVDMPoint}","page":"Fixed-rank matrices","title":"ManifoldsBase.embed","text":"embed(::FixedRankMatrices, p::SVDMPoint)\n\nEmbed the point p from its SVDMPoint representation into the set of mn matrices by computing USV^mathrmH.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.injectivity_radius-Union{Tuple{FixedRankMatrices{m, n, k}}, Tuple{k}, Tuple{n}, Tuple{m}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(::FixedRankMatrices)\n\nReturn the incjectivity radius of the manifold of FixedRankMatrices, i.e. 0. See [HosseiniUschmajew2017].\n\n[HosseiniUschmajew2017]: S. Hosseini and A. Uschmajew, “A Riemannian Gradient Sampling Algorithm for Nonsmooth Optimization on Manifolds,” SIAM J. Optim., vol. 27, no. 1, pp. 173–189, Jan. 2017, doi: 10.1137/16M1069298.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.inner-Tuple{FixedRankMatrices, SVDMPoint, UMVTVector, UMVTVector}","page":"Fixed-rank matrices","title":"ManifoldsBase.inner","text":"inner(M::FixedRankMatrices, p::SVDMPoint, X::UMVTVector, Y::UMVTVector)\n\nCompute the inner product of X and Y in the tangent space of p on the FixedRankMatrices M, which is inherited from the embedding, i.e. can be computed using dot on the elements (U, Vt, M) of X and Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.is_flat-Tuple{FixedRankMatrices}","page":"Fixed-rank matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::FixedRankMatrices)\n\nReturn false. FixedRankMatrices is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.manifold_dimension-Union{Tuple{FixedRankMatrices{m, n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{m}} where {m, n, k, 𝔽}","page":"Fixed-rank matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::FixedRankMatrices{m,n,k,𝔽})\n\nReturn the manifold dimension for the 𝔽-valued FixedRankMatrices M of dimension mxn of rank k, namely\n\ndim(mathcal M) = k(m + n - k) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.project-Tuple{FixedRankMatrices, Any, Any}","page":"Fixed-rank matrices","title":"ManifoldsBase.project","text":"project(M, p, A)\n\nProject the matrix A ℝ^mn or from the embedding the tangent space at p on the FixedRankMatrices M, further decomposing the result into X=UMV^mathrmH, i.e. a UMVTVector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.representation_size-Union{Tuple{FixedRankMatrices{m, n}}, Tuple{n}, Tuple{m}} where {m, n}","page":"Fixed-rank matrices","title":"ManifoldsBase.representation_size","text":"representation_size(M::FixedRankMatrices{m,n,k})\n\nReturn the element size of a point on the FixedRankMatrices M, i.e. the size of matrices on this manifold (mn).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.retract-Tuple{FixedRankMatrices, Any, Any, PolarRetraction}","page":"Fixed-rank matrices","title":"ManifoldsBase.retract","text":"retract(M, p, X, ::PolarRetraction)\n\nCompute an SVD-based retraction on the FixedRankMatrices M by computing\n\n q = U_kS_kV_k^mathrmH\n\nwhere U_k S_k V_k^mathrmH is the shortened singular value decomposition USV^mathrmH=p+X, in the sense that S_k is the diagonal matrix of size k k with the k largest singular values and U and V are shortened accordingly.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.vector_transport_to!-Tuple{FixedRankMatrices, Any, Any, Any, ProjectionTransport}","page":"Fixed-rank matrices","title":"ManifoldsBase.vector_transport_to!","text":"vector_transport_to(M::FixedRankMatrices, p, X, q, ::ProjectionTransport)\n\nCompute the vector transport of the tangent vector X at p to q, using the project of X to q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#ManifoldsBase.zero_vector-Union{Tuple{k}, Tuple{n}, Tuple{m}, Tuple{FixedRankMatrices{m, n, k}, SVDMPoint}} where {m, n, k}","page":"Fixed-rank matrices","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::FixedRankMatrices, p::SVDMPoint)\n\nReturn a UMVTVector representing the zero tangent vector in the tangent space of p on the FixedRankMatrices M, for example all three elements of the resulting structure are zero matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/fixedrankmatrices.html#Literature","page":"Fixed-rank matrices","title":"Literature","text":"","category":"section"},{"location":"manifolds/stiefel.html#Stiefel","page":"Stiefel","title":"Stiefel","text":"","category":"section"},{"location":"manifolds/stiefel.html#Common-and-metric-independent-functions","page":"Stiefel","title":"Common and metric independent functions","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/Stiefel.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.Stiefel","page":"Stiefel","title":"Manifolds.Stiefel","text":"Stiefel{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe Stiefel manifold consists of all n k, n k unitary matrices, i.e.\n\noperatornameSt(nk) = bigl p 𝔽^n k big p^mathrmHp = I_k bigr\n\nwhere 𝔽 ℝ ℂ, cdot^mathrmH denotes the complex conjugate transpose or Hermitian, and I_k ℝ^k k denotes the k k identity matrix.\n\nThe tangent space at a point p mathcal M is given by\n\nT_p mathcal M = X 𝔽^n k p^mathrmHX + overlineX^mathrmHp = 0_k\n\nwhere 0_k is the k k zero matrix and overlinecdot the (elementwise) complex conjugate.\n\nThis manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.\n\nThe manifold is named after Eduard L. Stiefel (1909–1978).\n\nConstructor\n\nStiefel(n, k, field = ℝ)\n\nGenerate the (real-valued) Stiefel manifold of n k dimensional orthonormal matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Base.rand-Tuple{Stiefel}","page":"Stiefel","title":"Base.rand","text":"rand(::Stiefel; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (Gaussian) point x on the Stiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the orthogonalized version, i.e. return the Q component of the QR decomposition of the random matrix of size nk.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_vector_atmathrmSt(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Manifolds.uniform_distribution-Union{Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, ℝ}, Any}} where {n, k}","page":"Stiefel","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::Stiefel{n,k,ℝ}, p)\n\nUniform distribution on given (real-valued) Stiefel M. Specifically, this is the normalized Haar and Hausdorff measure on M. Generated points will be of similar type as p.\n\nThe implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.1(iii) in [Chikuse2003].\n\n[Chikuse2003]: Y. Chikuse: \"Statistics on Special Manifolds\", Springer New York, 2003, doi: 10.1007/978-0-387-21540-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.change_metric-Tuple{Stiefel, EuclideanMetric, Any, Any}","page":"Stiefel","title":"ManifoldsBase.change_metric","text":"change_metric(M::Stiefel, ::EuclideanMetric, p X)\n\nChange X to the corresponding vector with respect to the metric of the Stiefel M, which is just the identity, since the manifold is isometrically embedded.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.change_representer-Tuple{Stiefel, EuclideanMetric, Any, Any}","page":"Stiefel","title":"ManifoldsBase.change_representer","text":"change_representer(M::Stiefel, ::EuclideanMetric, p, X)\n\nChange X to the corresponding representer of a cotangent vector at p. Since the Stiefel manifold M, is isometrically embedded, this is the identity\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Stiefel","title":"ManifoldsBase.check_point","text":"check_point(M::Stiefel, p; kwargs...)\n\nCheck whether p is a valid point on the Stiefel M=operatornameSt(nk), i.e. that it has the right AbstractNumbers type and p^mathrmHp is (approximately) the identity, where cdot^mathrmH is the complex conjugate transpose. The settings for approximately can be set with kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, 𝔽}, Any, Any}} where {n, k, 𝔽}","page":"Stiefel","title":"ManifoldsBase.check_vector","text":"check_vector(M::Stiefel, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector at p on the Stiefel M=operatornameSt(nk), i.e. the AbstractNumbers fits and it (approximately) holds that p^mathrmHX + overlineX^mathrmHp = 0, where cdot^mathrmH denotes the Hermitian and overlinecdot the (elementwise) complex conjugate. The settings for approximately can be set with kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.default_inverse_retraction_method-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.default_inverse_retraction_method","text":"default_inverse_retraction_method(M::Stiefel)\n\nReturn PolarInverseRetraction as the default inverse retraction for the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.default_retraction_method-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Stiefel)\n\nReturn PolarRetraction as the default retraction for the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.default_vector_transport_method-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::Stiefel)\n\nReturn the DifferentiatedRetractionVectorTransport of the [PolarRetraction](PolarRetraction as the default vector transport method for the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{Stiefel, Any, Any, PolarInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Stiefel, p, q, ::PolarInverseRetraction)\n\nCompute the inverse retraction based on a singular value decomposition for two points p, q on the Stiefel manifold M. This follows the folloing approach: From the Polar retraction we know that\n\noperatornameretr_p^-1q = qs - t\n\nif such a symmetric positive definite k k matrix exists. Since qs - t is also a tangent vector at p we obtain\n\np^mathrmHqs + s(p^mathrmHq)^mathrmH + 2I_k = 0\n\nwhich can either be solved by a Lyapunov approach or a continuous-time algebraic Riccati equation.\n\nThis implementation follows the Lyapunov approach.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{Stiefel, Any, Any, QRInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Stiefel, p, q, ::QRInverseRetraction)\n\nCompute the inverse retraction based on a qr decomposition for two points p, q on the Stiefel manifold M and return the resulting tangent vector in X. The computation follows Algorithm 1 in [KanekoFioriTanaka2013].\n\n[KanekoFioriTanaka2013]: T. Kaneko, S. Fiori, T. Tanaka: \"Empirical Arithmetic Averaging over the Compact Stiefel AbstractManifold\", IEEE Transactions on Signal Processing, 2013, doi: 10.1109/TSP.2012.2226167.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.is_flat-Tuple{Stiefel}","page":"Stiefel","title":"ManifoldsBase.is_flat","text":"is_flat(M::Stiefel)\n\nReturn true if Stiefel M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.manifold_dimension-Union{Tuple{Stiefel{n, k, ℝ}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Stiefel)\n\nReturn the dimension of the Stiefel manifold M=operatornameSt(nk𝔽). The dimension is given by\n\nbeginaligned\ndim mathrmSt(n k ℝ) = nk - frac12k(k+1)\ndim mathrmSt(n k ℂ) = 2nk - k^2\ndim mathrmSt(n k ℍ) = 4nk - k(2k-1)\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.representation_size-Union{Tuple{Stiefel{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.representation_size","text":"representation_size(M::Stiefel)\n\nReturns the representation size of the Stiefel M=operatornameSt(nk), i.e. (n,k), which is the matrix dimensions.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, CayleyRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(::Stiefel, p, X, ::CayleyRetraction)\n\nCompute the retraction on the Stiefel that is based on the Cayley transform[Zhu2017]. Using\n\n W_pX = operatornameP_pXp^mathrmH - pX^mathrmHoperatornameP_p\n quadtextwhere \n operatornameP_p = I - frac12pp^mathrmH\n\nthe formula reads\n\n operatornameretr_pX = Bigl(I - frac12W_pXBigr)^-1Bigl(I + frac12W_pXBigr)p\n\nIt is implemented as the case m=1 of the PadeRetraction.\n\n[Zhu2017]: X. Zhu: A Riemannian conjugate gradient method for optimizazion on the Stiefel manifold, Computational Optimization and Applications 67(1), pp. 73–110, 2017. doi 10.1007/s10589-016-9883-4.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, PadeRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, ::PadeRetraction{m})\n\nCompute the retraction on the Stiefel manifold M based on the Padé approximation of order m[ZhuDuan2018]. Let p_m and q_m be defined for any matrix A ℝ^nx as\n\n p_m(A) = sum_k=0^m frac(2m-k)m(2m)(m-k)fracA^kk\n\nand\n\n q_m(A) = sum_k=0^m frac(2m-k)m(2m)(m-k)frac(-A)^kk\n\nrespectively. Then the Padé approximation (of the matrix exponential exp(A)) reads\n\n r_m(A) = q_m(A)^-1p_m(A)\n\nDefining further\n\n W_pX = operatornameP_pXp^mathrmH - pX^mathrmHoperatornameP_p\n quadtextwhere \n operatornameP_p = I - frac12pp^mathrmH\n\nthe retraction reads\n\n operatornameretr_pX = r_m(W_pX)p\n\n[ZhuDuan2018]: X. Zhu, C. Duan: On matrix exponentials and their approximations related to optimization on the Stiefel manifold, Optimizazion Letters 13(5), pp. 1069–1083, 2018. doi 10.1007/s11590-018-1341-z.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, PolarRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the Stiefel manifold M. With USV = p + X the retraction reads\n\noperatornameretr_p X = UbarV^mathrmH\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, QRRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, ::QRRetraction)\n\nCompute the QR-based retraction QRRetraction on the Stiefel manifold M. With QR = p + X the retraction reads\n\noperatornameretr_p X = QD\n\nwhere D is a n k matrix with\n\nD = operatornamediagbigl(operatornamesgn(R_ii+05)_i=1^k bigr)\n\nwhere operatornamesgn(p) = begincases 1 text for p 0\n0 text for p = 0\n-1 text for p 0 endcases\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_direction-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{CayleyRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_direction","text":"vector_transport_direction(::Stiefel, p, X, d, ::DifferentiatedRetractionVectorTransport{CayleyRetraction})\n\nCompute the vector transport given by the differentiated retraction of the CayleyRetraction, cf. [Zhu2017] Equation (17).\n\nThe formula reads\n\noperatornameT_pd(X) =\nBigl(I - frac12W_pdBigr)^-1W_pXBigl(I - frac12W_pdBigr)^-1p\n\nwith\n\n W_pX = operatornameP_pXp^mathrmH - pX^mathrmHoperatornameP_p\n quadtextwhere \n operatornameP_p = I - frac12pp^mathrmH\n\nSince this is the differentiated retraction as a vector transport, the result will be in the tangent space at q=operatornameretr_p(d) using the CayleyRetraction.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_direction-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{PolarRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_direction","text":"vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{PolarRetraction})\n\nCompute the vector transport by computing the push forward of retract(::Stiefel, ::Any, ::Any, ::PolarRetraction) Section 3.5 of [Zhu2017]:\n\nT_pd^textPol(X) = q*Λ + (I-qq^mathrmT)X(1+d^mathrmTd)^-frac12\n\nwhere q = operatornameretr^mathrmPol_p(d), and Λ is the unique solution of the Sylvester equation\n\n Λ(I+d^mathrmTd)^frac12 + (I + d^mathrmTd)^frac12 = q^mathrmTX - X^mathrmTq\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_direction-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{QRRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_direction","text":"vector_transport_direction(M::Stiefel, p, X, d, DifferentiatedRetractionVectorTransport{QRRetraction})\n\nCompute the vector transport by computing the push forward of the retract(::Stiefel, ::Any, ::Any, ::QRRetraction), See [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].\n\nT_pd^textQR(X) = q*rho_mathrms(q^mathrmTXR^-1) + (I-qq^mathrmT)XR^-1\n\nwhere q = operatornameretr^mathrmQR_p(d), R is the R factor of the QR decomposition of p + d, and\n\nbigl( rho_mathrms(A) bigr)_ij\n= begincases\nA_ijtext if i j\n0 text if i = j\n-A_ji text if i j\nendcases\n\n[AbsilMahonySepulchre2008]: Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_to-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{PolarRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{PolarRetraction})\n\nCompute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::PolarRetraction), see Section 4 of [HuangGallivanAbsil2015] or Section 3.5 of [Zhu2017]:\n\nT_qgets p^textPol(X) = q*Λ + (I-qq^mathrmT)X(1+d^mathrmTd)^-frac12\n\nwhere d = bigl( operatornameretr^mathrmPol_pbigr)^-1(q), and Λ is the unique solution of the Sylvester equation\n\n Λ(I+d^mathrmTd)^frac12 + (I + d^mathrmTd)^frac12 = q^mathrmTX - X^mathrmTq\n\n[HuangGallivanAbsil2015]: Huang, W., Gallivan, K. A., and Absil, P.-A.: A Broyden class of quasi-Newton methods for Riemannian optimization SIAM Journal of Optimization, 2015, Vol. 25, No. 3, pp. 1660–1685 doi: 10.1137/140955483 pdf: tech. report\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_to-Tuple{Stiefel, Any, Any, Any, DifferentiatedRetractionVectorTransport{QRRetraction}}","page":"Stiefel","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Stiefel, p, X, q, DifferentiatedRetractionVectorTransport{QRRetraction})\n\nCompute the vector transport by computing the push forward of the retract(M::Stiefel, ::Any, ::Any, ::QRRetraction), see [AbsilMahonySepulchre2008], p. 173, or Section 3.5 of [Zhu2017].\n\nT_q gets p^textQR(X) = q*rho_mathrms(q^mathrmTXR^-1) + (I-qq^mathrmT)XR^-1\n\nwhere d = bigl(operatornameretr^mathrmQRbigr)^-1_p(q), R is the R factor of the QR decomposition of p+X, and\n\nbigl( rho_mathrms(A) bigr)_ij\n= begincases\nA_ijtext if i j\n0 text if i = j\n-A_ji text if i j\nendcases\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.vector_transport_to-Tuple{Stiefel, Any, Any, Any, ProjectionTransport}","page":"Stiefel","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Stiefel, p, X, q, ::ProjectionTransport)\n\nCompute a vector transport by projection, i.e. project X from the tangent space at p by projection it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Default-metric:-the-Euclidean-metric","page":"Stiefel","title":"Default metric: the Euclidean metric","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"The EuclideanMetric is obtained from the embedding of the Stiefel manifold in ℝ^nk.","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelEuclideanMetric.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/stiefel.html#Base.exp-Tuple{Stiefel, Vararg{Any}}","page":"Stiefel","title":"Base.exp","text":"exp(M::Stiefel, p, X)\n\nCompute the exponential map on the Stiefel{n,k,𝔽}() manifold M emanating from p in tangent direction X.\n\nexp_p X = beginpmatrix\n pX\n endpmatrix\n operatornameExp\n left(\n beginpmatrix p^mathrmHX - X^mathrmHX\n I_n p^mathrmHXendpmatrix\n right)\nbeginpmatrix exp( -p^mathrmHX) 0_nendpmatrix\n\nwhere operatornameExp denotes matrix exponential, cdot^mathrmH denotes the complex conjugate transpose or Hermitian, and I_k and 0_k are the identity matrix and the zero matrix of dimension k k, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.get_basis-Union{Tuple{k}, Tuple{n}, Tuple{Stiefel{n, k, ℝ}, Any, DefaultOrthonormalBasis{ℝ, ManifoldsBase.TangentSpaceType}}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.get_basis","text":"get_basis(M::Stiefel{n,k,ℝ}, p, B::DefaultOrthonormalBasis) where {n,k}\n\nCreate the default basis using the parametrization for any X T_pmathcal M. Set p_bot in ℝ^ntimes(n-k) the matrix such that the ntimes n matrix of the common columns p p_bot is an ONB. For any skew symmetric matrix a ℝ^ktimes k and any b ℝ^(n-k)times k the matrix\n\nX = pa + p_bot b T_pmathcal M\n\nand we can use the frac12k(k-1) + (n-k)k = nk-frac12k(k+1) entries of a and b to specify a basis for the tangent space. using unit vectors for constructing both the upper matrix of a to build a skew symmetric matrix and the matrix b, the default basis is constructed.\n\nSince p p_bot is an automorphism on ℝ^ntimes p the elements of a and b are orthonormal coordinates for the tangent space. To be precise exactly one element in the upper trangular entries of a is set to 1 its symmetric entry to -1 and we normalize with the factor frac1sqrt2 and for b one can just use unit vectors reshaped to a matrix to obtain orthonormal set of parameters.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{Stiefel, Any, Any, ProjectionInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Stiefel, p, q, method::ProjectionInverseRetraction)\n\nCompute a projection-based inverse retraction.\n\nThe inverse retraction is computed by projecting the logarithm map in the embedding to the tangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.project-Tuple{Stiefel, Any, Any}","page":"Stiefel","title":"ManifoldsBase.project","text":"project(M::Stiefel,p)\n\nProjects p from the embedding onto the Stiefel M, i.e. compute q as the polar decomposition of p such that q^mathrmHq is the identity, where cdot^mathrmH denotes the hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.project-Tuple{Stiefel, Vararg{Any}}","page":"Stiefel","title":"ManifoldsBase.project","text":"project(M::Stiefel, p, X)\n\nProject X onto the tangent space of p to the Stiefel manifold M. The formula reads\n\noperatornameproj_mathcal M(p X) = X - p operatornameSym(p^mathrmHX)\n\nwhere operatornameSym(q) is the symmetrization of q, e.g. by operatornameSym(q) = fracq^mathrmH+q2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.retract-Tuple{Stiefel, Any, Any, ProjectionRetraction}","page":"Stiefel","title":"ManifoldsBase.retract","text":"retract(M::Stiefel, p, X, method::ProjectionRetraction)\n\nCompute a projection-based retraction.\n\nThe retraction is computed by projecting the exponential map in the embedding to M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#The-canonical-metric","page":"Stiefel","title":"The canonical metric","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Any XT_pmathcal M, pmathcal M, can be written as","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"X = pA + (I_n-pp^mathrmT)B\nquad\nA ℝ^pp text skew-symmetric\nquad\nB ℝ^np text arbitrary","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"In the EuclideanMetric, the elements from A are counted twice (i.e. weighted with a factor of 2). The canonical metric avoids this.","category":"page"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelCanonicalMetric.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.ApproximateLogarithmicMap","page":"Stiefel","title":"Manifolds.ApproximateLogarithmicMap","text":"ApproximateLogarithmicMap <: ApproximateInverseRetraction\n\nAn approximate implementation of the logarithmic map, which is an inverse_retraction. See inverse_retract(::MetricManifold{ℝ,Stiefel{n,k,ℝ},CanonicalMetric}, ::Any, ::Any, ::ApproximateLogarithmicMap) where {n,k} for a use case.\n\nFields\n\nmax_iterations – maximal number of iterations used in the approximation\ntolerance – a tolerance used as a stopping criterion\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Manifolds.CanonicalMetric","page":"Stiefel","title":"Manifolds.CanonicalMetric","text":"CanonicalMetric <: AbstractMetric\n\nThe Canonical Metric refers to a metric for the Stiefel manifold, see[EdelmanAriasSmith1998].\n\n[EdelmanAriasSmith1998]: Edelman, A., Ariar, T. A., Smith, S. T.: The Geometry of Algorihthms with Orthogonality Constraints, SIAM Journal on Matrix Analysis and Applications (20(2), pp. 303–353, 1998. doi: 10.1137/S0895479895290954 arxiv: 9806030\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelCanonicalMetric.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/stiefel.html#Base.exp-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, CanonicalMetric}, Vararg{Any}}} where {n, k}","page":"Stiefel","title":"Base.exp","text":"q = exp(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, X)\nexp!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, q, CanonicalMetric}, p, X)\n\nCompute the exponential map on the Stiefel(n,k) manifold with respect to the CanonicalMetric.\n\nFirst, decompose The tangent vector X into its horizontal and vertical component with respect to p, i.e.\n\nX = pp^mathrmTX + (I_n-pp^mathrmT)X\n\nwhere I_n is the ntimes n identity matrix. We introduce A=p^mathrmTX and QR = (I_n-pp^mathrmT)X the qr decomposition of the vertical component. Then using the matrix exponential operatornameExp we introduce B and C as\n\nbeginpmatrix\nBC\nendpmatrix\ncoloneqq\noperatornameExpleft(\nbeginpmatrix\nA -R^mathrmT R 0\nendpmatrix\nright)\nbeginpmatrixI_k0endpmatrix\n\nthe exponential map reads\n\nq = exp_p X = pC + QB\n\nFor more details, see [EdelmanAriasSmith1998][Zimmermann2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, CanonicalMetric}, Any, Any, Any}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.inner","text":"inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, X, Y)\n\nCompute the inner product on the Stiefel manifold with respect to the CanonicalMetric. The formula reads\n\ng_p(XY) = operatornametrbigl( X^mathrmT(I_n - frac12pp^mathrmT)Y bigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, CanonicalMetric}, Any, Any, ApproximateLogarithmicMap}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"X = inverse_retract(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)\ninverse_retract!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)\n\nCompute an approximation to the logarithmic map on the Stiefel(n,k) manifold with respect to the CanonicalMetric using a matrix-algebraic based approach to an iterative inversion of the formula of the exp.\n\nThe algorithm is derived in[Zimmermann2017] and it uses the max_iterations and the tolerance field from the ApproximateLogarithmicMap.\n\n[Zimmermann2017]: Zimmermann, R.: _A matrix-algebraic algorithm for the Riemannian logarithm on the Stiefel manifold under the canoncial metric. SIAM Journal on Matrix Analysis and Applications 28(2), pp. 322-342, 2017. doi: 10.1137/16M1074485, arXiv: 1604.05054.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#The-submersion-or-normal-metric","page":"Stiefel","title":"The submersion or normal metric","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelSubmersionMetric.jl\"]\nOrder = [:type, :function]\nPublic = true\nPrivate = false","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.StiefelSubmersionMetric","page":"Stiefel","title":"Manifolds.StiefelSubmersionMetric","text":"StiefelSubmersionMetric{T<:Real} <: RiemannianMetric\n\nThe submersion (or normal) metric family on the Stiefel manifold.\n\nThe family, with a single real parameter α-1, has two special cases:\n\nα = -frac12: EuclideanMetric\nα = 0: CanonicalMetric\n\nThe family was described in [HüperMarkinaLeite2021]. This implementation follows the description in [ZimmermanHüper2022].\n\n[HüperMarkinaLeite2021]: Hüper, M., Markina, A., Leite, R. T. (2021) \"A Lagrangian approach to extremal curves on Stiefel manifolds\" Journal of Geometric Mechanics, 13(1): 55-72. doi: 10.3934/jgm.2020031\n\n[ZimmermanHüper2022]: Ralf Zimmerman and Knut Hüper. (2022). \"Computing the Riemannian logarithm on the Stiefel manifold: metrics, methods and performance.\" arXiv: 2103.12046\n\nConstructor\n\nStiefelSubmersionMetric(α)\n\nConstruct the submersion metric on the Stiefel manifold with the parameter α.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Base.exp-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, <:StiefelSubmersionMetric}, Vararg{Any}}} where {n, k}","page":"Stiefel","title":"Base.exp","text":"q = exp(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, <:StiefelSubmersionMetric}, p, X)\nexp!(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, q, <:StiefelSubmersionMetric}, p, X)\n\nCompute the exponential map on the Stiefel(n,k) manifold with respect to the StiefelSubmersionMetric.\n\nThe exponential map is given by\n\nexp_p X = operatornameExpbigl(\n -frac2α+1α+1 p p^mathrmT X p^mathrmT +\n X p^mathrmT - p X^mathrmT\nbigr) p operatornameExpbigl(fracalphaalpha+1 p^mathrmT Xbigr)\n\nThis implementation is based on [ZimmermanHüper2022].\n\nFor k fracn2 the exponential is computed more efficiently using StiefelFactorization.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Base.log-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, <:StiefelSubmersionMetric}, Any, Any}} where {n, k}","page":"Stiefel","title":"Base.log","text":"log(M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric}, p, q; kwargs...)\n\nCompute the logarithmic map on the Stiefel(n,k) manifold with respect to the StiefelSubmersionMetric.\n\nThe logarithmic map is computed using ShootingInverseRetraction. For k lfloorfracn2rfloor, this is sped up using the k-shooting method of [ZimmermanHüper2022]. Keyword arguments are forwarded to ShootingInverseRetraction; see that documentation for details. Their defaults are:\n\nnum_transport_points=4\ntolerance=sqrt(eps())\nmax_iterations=1_000\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{MetricManifold{ℝ, Stiefel{n, k, ℝ}, <:StiefelSubmersionMetric}, Any, Any, Any}} where {n, k}","page":"Stiefel","title":"ManifoldsBase.inner","text":"inner(M::MetricManifold{ℝ, Stiefel{n,k,ℝ}, X, <:StiefelSubmersionMetric}, p, X, Y)\n\nCompute the inner product on the Stiefel manifold with respect to the StiefelSubmersionMetric. The formula reads\n\ng_p(XY) = operatornametrbigl( X^mathrmT(I_n - frac2α+12(α+1)pp^mathrmT)Y bigr)\n\nwhere α is the parameter of the metric.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#ManifoldsBase.inverse_retract-Tuple{MetricManifold{ℝ, <:Stiefel, <:StiefelSubmersionMetric}, Any, Any, ShootingInverseRetraction}","page":"Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(\n M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric},\n p,\n q,\n method::ShootingInverseRetraction,\n)\n\nCompute the inverse retraction using ShootingInverseRetraction.\n\nIn general the retraction is computed using the generic shooting method.\n\ninverse_retract(\n M::MetricManifold{ℝ,Stiefel{n,k,ℝ},<:StiefelSubmersionMetric},\n p,\n q,\n method::ShootingInverseRetraction{\n ExponentialRetraction,\n ProjectionInverseRetraction,\n <:Union{ProjectionTransport,ScaledVectorTransport{ProjectionTransport}},\n },\n)\n\nCompute the inverse retraction using ShootingInverseRetraction more efficiently.\n\nFor k fracn2 the retraction is computed more efficiently using StiefelFactorization.\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Internal-types-and-functions","page":"Stiefel","title":"Internal types and functions","text":"","category":"section"},{"location":"manifolds/stiefel.html","page":"Stiefel","title":"Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/StiefelSubmersionMetric.jl\"]\nOrder = [:type, :function]\nPublic = false\nPrivate = true","category":"page"},{"location":"manifolds/stiefel.html#Manifolds.StiefelFactorization","page":"Stiefel","title":"Manifolds.StiefelFactorization","text":"StiefelFactorization{UT,XT} <: AbstractManifoldPoint\n\nRepresent points (and vectors) on Stiefel(n, k) with 2k k factors.[ZimmermanHüper2022]\n\nGiven a point p mathrmSt(n k) and another matrix B ℝ^n k for k lfloorfracn2rfloor the factorization is\n\nbeginaligned\nB = UZ\nU = beginbmatrixp Qendbmatrix mathrmSt(n 2k)\nZ = beginbmatrixZ_1 Z_2endbmatrix quad Z_1Z_2 ℝ^k k\nendaligned\n\nIf B mathrmSt(n k), then Z mathrmSt(2k k). Note that not every matrix B can be factorized in this way.\n\nFor a fixed U, if r mathrmSt(n k) has the factor Z_r mathrmSt(2k k), then X_r T_r mathrmSt(n k) has the factor Z_X_r T_Z_r mathrmSt(2k k).\n\nQ is determined by choice of a second matrix A ℝ^n k with the decomposition\n\nbeginaligned\nA = UZ\nZ_1 = p^mathrmT A \nQ Z_2 = (I - p p^mathrmT) A\nendaligned\n\nwhere here Q Z_2 is the any decomposition that produces Q mathrmSt(n k), for which we choose the QR decomposition.\n\nThis factorization is useful because it is closed under addition, subtraction, scaling, projection, and the Riemannian exponential and logarithm under the StiefelSubmersionMetric. That is, if all matrices involved are factorized to have the same U, then all of these operations and any algorithm that depends only on them can be performed in terms of the 2k k matrices Z. For n k, this can be much more efficient than working with the full matrices.\n\nwarning: Warning\nThis type is intended strictly for internal use and should not be directly used.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/stiefel.html#Manifolds.stiefel_factorization-Tuple{Any, Any}","page":"Stiefel","title":"Manifolds.stiefel_factorization","text":"stiefel_factorization(p, x) -> StiefelFactorization\n\nCompute the StiefelFactorization of x relative to the point p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/stiefel.html#Literature","page":"Stiefel","title":"Literature","text":"","category":"section"},{"location":"manifolds/circle.html#Circle","page":"Circle","title":"Circle","text":"","category":"section"},{"location":"manifolds/circle.html","page":"Circle","title":"Circle","text":"Modules = [Manifolds]\nPages = [\"manifolds/Circle.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/circle.html#Manifolds.Circle","page":"Circle","title":"Manifolds.Circle","text":"Circle{𝔽} <: AbstractManifold{𝔽}\n\nThe circle 𝕊^1 is a manifold here represented by real-valued points in -ππ) or complex-valued points z ℂ of absolute value lvert zrvert = 1.\n\nConstructor\n\nCircle(𝔽=ℝ)\n\nGenerate the ℝ-valued Circle represented by angles, which alternatively can be set to use the AbstractNumbers 𝔽=ℂ to obtain the circle represented by ℂ-valued circle of unit numbers.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/circle.html#Base.exp-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"Base.exp","text":"exp(M::Circle, p, X)\n\nCompute the exponential map on the Circle.\n\nexp_p X = (p+X)_2π\n\nwhere (cdot)_2π is the (symmetric) remainder with respect to division by 2π, i.e. in -ππ).\n\nFor the complex-valued case, the same formula as for the Sphere 𝕊^1 is applied to values in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Base.log-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"Base.log","text":"log(M::Circle, p, q)\n\nCompute the logarithmic map on the Circle M.\n\nlog_p q = (q-p)_2π\n\nwhere (cdot)_2π is the (symmetric) remainder with respect to division by 2π, i.e. in -ππ).\n\nFor the complex-valued case, the same formula as for the Sphere 𝕊^1 is applied to values in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Base.rand-Tuple{Circle}","page":"Circle","title":"Base.rand","text":"Random.rand(M::Circle{ℝ}; vector_at = nothing, σ::Real=1.0)\n\nIf vector_at is nothing, return a random point on the Circle mathbb S^1 by picking a random element from -pipi) uniformly.\n\nIf vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the Circle by using a normal distribution with mean 0 and standard deviation σ.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.complex_dot-Tuple{Any, Any}","page":"Circle","title":"Manifolds.complex_dot","text":"complex_dot(a, b)\n\nCompute the inner product of two (complex) numbers with in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.manifold_volume-Tuple{Circle}","page":"Circle","title":"Manifolds.manifold_volume","text":"manifold_volume(M::Circle)\n\nReturn the volume of the Circle M, i.e. 2π.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.sym_rem-Union{Tuple{N}, Tuple{N, Any}} where N<:Number","page":"Circle","title":"Manifolds.sym_rem","text":"sym_rem(x,[T=π])\n\nCompute symmetric remainder of x with respect to the interall 2*T, i.e. (x+T)%2T, where the default for T is π\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Manifolds.volume_density-Tuple{Circle, Any, Any}","page":"Circle","title":"Manifolds.volume_density","text":"volume_density(::Circle, p, X)\n\nReturn volume density of Circle, i.e. 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.check_point-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.check_point","text":"check_point(M::Circle, p)\n\nCheck whether p is a point on the Circle M. For the real-valued case, p is an angle and hence it checks that p -ππ). for the complex-valued case, it is a unit number, p ℂ with lvert p rvert = 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.check_vector-Tuple{Circle{ℝ}, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.check_vector","text":"check_vector(M::Circle, p, X; kwargs...)\n\nCheck whether X is a tangent vector in the tangent space of p on the Circle M. For the real-valued case represented by angles, all X are valid, since the tangent space is the whole real line. For the complex-valued case X has to lie on the line parallel to the tangent line at p in the complex plane, i.e. their inner product has to be zero.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.distance-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.distance","text":"distance(M::Circle, p, q)\n\nCompute the distance on the Circle M, which is the absolute value of the symmetric remainder of p and q for the real-valued case and the angle between both complex numbers in the Gaussian plane for the complex-valued case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.embed-Tuple{Circle, Any, Any}","page":"Circle","title":"ManifoldsBase.embed","text":"embed(M::Circle, p, X)\n\nEmbed a tangent vector X at p on Circle M in the ambient space. It returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.embed-Tuple{Circle, Any}","page":"Circle","title":"ManifoldsBase.embed","text":"embed(M::Circle, p)\n\nEmbed a point p on Circle M in the ambient space. It returns p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.get_coordinates-Tuple{Circle{ℂ}, Any, Any, DefaultOrthonormalBasis{<:Any, ManifoldsBase.TangentSpaceType}}","page":"Circle","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::Circle{ℂ}, p, X, B::DefaultOrthonormalBasis)\n\nReturn tangent vector coordinates in the Lie algebra of the Circle.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.get_vector_orthonormal-Tuple{Circle{ℂ}, Any, Any, ManifoldsBase.RealNumbers}","page":"Circle","title":"ManifoldsBase.get_vector_orthonormal","text":"get_vector(M::Circle{ℂ}, p, X, B::DefaultOrthonormalBasis)\n\nReturn tangent vector from the coordinates in the Lie algebra of the Circle.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.injectivity_radius-Tuple{Circle}","page":"Circle","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Circle[, p])\n\nReturn the injectivity radius on the Circle M, i.e. π.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.inner-Tuple{Circle, Vararg{Any}}","page":"Circle","title":"ManifoldsBase.inner","text":"inner(M::Circle, p, X, Y)\n\nCompute the inner product of the two tangent vectors X,Y from the tangent plane at p on the Circle M using the restriction of the metric from the embedding, i.e.\n\ng_p(XY) = X*Y\n\nfor the real case and\n\ng_p(XY) = Y^mathrmTX\n\nfor the complex case interpreting complex numbers in the Gaussian plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.is_flat-Tuple{Circle}","page":"Circle","title":"ManifoldsBase.is_flat","text":"is_flat(::Circle)\n\nReturn true. Circle is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.manifold_dimension-Tuple{Circle}","page":"Circle","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Circle)\n\nReturn the dimension of the Circle M, i.e. dim(𝕊^1) = 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.parallel_transport_to-Tuple{Circle, Any, Any, Any}","page":"Circle","title":"ManifoldsBase.parallel_transport_to","text":" parallel_transport_to(M::Circle, p, X, q)\n\nCompute the parallel transport of X from the tangent space at p to the tangent space at q on the Circle M. For the real-valued case this results in the identity. For the complex-valud case, the formula is the same as for the Sphere(1) in the complex plane.\n\nmathcal P_qp X = X - fraclog_p qX_pd^2_ℂ(pq)\nbigl(log_p q + log_q p bigr)\n\nwhere log denotes the logarithmic map on M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.project-Tuple{Circle, Any, Any}","page":"Circle","title":"ManifoldsBase.project","text":"project(M::Circle, p, X)\n\nProject a value X onto the tangent space of the point p on the Circle M.\n\nFor the real-valued case this is just the identity. For the complex valued case X is projected onto the line in the complex plane that is parallel to the tangent to p on the unit circle and contains 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#ManifoldsBase.project-Tuple{Circle, Any}","page":"Circle","title":"ManifoldsBase.project","text":"project(M::Circle, p)\n\nProject a point p onto the Circle M. For the real-valued case this is the remainder with respect to modulus 2π. For the complex-valued case the result is the projection of p onto the unit circle in the complex plane.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Statistics.mean-Tuple{Circle{ℂ}, Any}","page":"Circle","title":"Statistics.mean","text":"mean(M::Circle{ℂ}, x::AbstractVector[, w::AbstractWeights])\n\nCompute the Riemannian mean of x of points on the Circle 𝕊^1, reprsented by complex numbers, i.e. embedded in the complex plane. Comuting the sum\n\ns = sum_i=1^n x_i\n\nthe mean is the angle of the complex number s, so represented in the complex plane as fracslvert s rvert, whenever s neq 0.\n\nIf the sum s=0, the mean is not unique. For example for opposite points or equally spaced angles.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/circle.html#Statistics.mean-Tuple{Circle{ℝ}, Any}","page":"Circle","title":"Statistics.mean","text":"mean(M::Circle{ℝ}, x::AbstractVector[, w::AbstractWeights])\n\nCompute the Riemannian mean of x of points on the Circle 𝕊^1, reprsented by real numbers, i.e. the angular mean\n\noperatornameatanBigl( sum_i=1^n w_isin(x_i) sum_i=1^n w_isin(x_i) Bigr)\n\n\n\n\n\n","category":"method"},{"location":"misc/about.html#About-Manifolds.jl","page":"About","title":"About Manifolds.jl","text":"","category":"section"},{"location":"misc/about.html#License","page":"About","title":"License","text":"","category":"section"},{"location":"misc/about.html","page":"About","title":"About","text":"MIT License","category":"page"},{"location":"misc/about.html#Core-Developers","page":"About","title":"Core Developers","text":"","category":"section"},{"location":"misc/about.html","page":"About","title":"About","text":"Seth Axen\nMateusz Baran\nRonny Bergmann","category":"page"},{"location":"misc/about.html#Contributors","page":"About","title":"Contributors","text":"","category":"section"},{"location":"misc/about.html","page":"About","title":"About","text":"See the GitHub contributors page.","category":"page"},{"location":"misc/about.html","page":"About","title":"About","text":"Contributions are welcome!","category":"page"},{"location":"features/testing.html#Testing","page":"Testing","title":"Testing","text":"","category":"section"},{"location":"features/testing.html","page":"Testing","title":"Testing","text":"Documentation for testing utilities for Manifolds.jl. The function test_manifold can be used to verify that your manifold correctly implements the Manifolds.jl interface. Similarly test_group and test_action can be used to verify implementation of groups and group actions.","category":"page"},{"location":"features/testing.html","page":"Testing","title":"Testing","text":"Manifolds.test_action\nManifolds.test_group\nManifolds.test_manifold\nManifolds.find_eps\nManifolds.test_parallel_transport","category":"page"},{"location":"features/testing.html#Manifolds.test_action","page":"Testing","title":"Manifolds.test_action","text":"test_action(\n A::AbstractGroupAction,\n a_pts::AbstractVector,\n m_pts::AbstractVector,\n X_pts = [];\n atol = 1e-10,\n atol_ident_compose = 0,\n test_optimal_alignment = false,\n test_mutating_group=true,\n test_mutating_action=true,\n test_diff = false,\n test_switch_direction = true,\n)\n\nTests general properties of the action A, given at least three different points that lie on it (contained in a_pts) and three different point that lie on the manifold it acts upon (contained in m_pts).\n\nArguments\n\natol_ident_compose = 0: absolute tolerance for the test that composition with identity doesn't change the group element.\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.test_group","page":"Testing","title":"Manifolds.test_group","text":"test_group(\n G,\n g_pts::AbstractVector,\n X_pts::AbstractVector = [],\n Xe_pts::AbstractVector = [];\n atol = 1e-10,\n test_mutating = true,\n test_exp_lie_log = true,\n test_diff = false,\n test_invariance = false,\n test_lie_bracket=false,\n test_adjoint_action=false,\n diff_convs = [(), (LeftForwardAction(),), (RightBackwardAction(),)],\n)\n\nTests general properties of the group G, given at least three different points elements of it (contained in g_pts). Optionally, specify test_diff to test differentials of translation, using X_pts, which must contain at least one tangent vector at g_pts[1], and the direction conventions specified in diff_convs. Xe_pts should contain tangent vectors at identity for testing Lie algebra operations. If the group is equipped with an invariant metric, test_invariance indicates that the invariance should be checked for the provided points.\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.test_manifold","page":"Testing","title":"Manifolds.test_manifold","text":"test_manifold(\n M::AbstractManifold,\n pts::AbstractVector;\n args,\n)\n\nTest general properties of manifold M, given at least three different points that lie on it (contained in pts).\n\nArguments\n\nbasis_has_specialized_diagonalizing_get = false: if true, assumes that DiagonalizingOrthonormalBasis given in basis_types has get_coordinates and get_vector that work without caching.\nbasis_types_to_from = (): basis types that will be tested based on get_coordinates and get_vector.\nbasis_types_vecs = () : basis types that will be tested based on get_vectors\ndefault_inverse_retraction_method = ManifoldsBase.LogarithmicInverseRetraction(): default method for inverse retractions (log.\ndefault_retraction_method = ManifoldsBase.ExponentialRetraction(): default method for retractions (exp).\nexp_log_atol_multiplier = 0: change absolute tolerance of exp/log tests (0 use default, i.e. deactivate atol and use rtol).\nexp_log_rtol_multiplier = 1: change the relative tolerance of exp/log tests (1 use default). This is deactivated if the exp_log_atol_multiplier is nonzero.\nexpected_dimension_type = Integer: expected type of value returned by manifold_dimension.\ninverse_retraction_methods = []: inverse retraction methods that will be tested.\nis_mutating = true: whether mutating variants of functions should be tested.\nis_point_atol_multiplier = 0: determines atol of is_point checks.\nis_tangent_atol_multiplier = 0: determines atol of is_vector checks.\nmid_point12 = test_exp_log ? shortest_geodesic(M, pts[1], pts[2], 0.5) : nothing: if not nothing, then check that mid_point(M, pts[1], pts[2]) is approximately equal to mid_point12. This is by default set to nothing if text_exp_log is set to false.\npoint_distributions = [] : point distributions to test.\nrand_tvector_atol_multiplier = 0 : chage absolute tolerance in testing random vectors (0 use default, i.e. deactivate atol and use rtol) random tangent vectors are tangent vectors.\nretraction_atol_multiplier = 0: change absolute tolerance of (inverse) retraction tests (0 use default, i.e. deactivate atol and use rtol).\nretraction_rtol_multiplier = 1: change the relative tolerance of (inverse) retraction tests (1 use default). This is deactivated if the exp_log_atol_multiplier is nonzero.\nretraction_methods = []: retraction methods that will be tested.\ntest_atlases = []: Vector or tuple of atlases that should be tested.\ntest_exp_log = true: if true, check that exp is the inverse of log.\ntest_injectivity_radius = true: whether implementation of injectivity_radius should be tested.\ntest_inplace = false : if true check if inplace variants work if they are activated, e.g. check that exp!(M, p, p, X) work if test_exp_log = true. This in general requires is_mutating to be true.\ntest_is_tangent: if true check that the default_inverse_retraction_method actually returns valid tangent vectors.\ntest_musical_isomorphisms = false : test musical isomorphisms.\ntest_mutating_rand = false : test the mutating random function for points on manifolds.\ntest_project_point = false: test projections onto the manifold.\ntest_project_tangent = false : test projections on tangent spaces.\ntest_representation_size = true : test repersentation size of points/tvectprs.\ntest_tangent_vector_broadcasting = true : test boradcasting operators on TangentSpace.\ntest_vector_spaces = true : test Vector bundle of this manifold.\ntest_default_vector_transport = false : test the default vector transport (usually parallel transport).\ntest_vee_hat = false: test vee and hat functions.\ntvector_distributions = [] : tangent vector distributions to test.\nvector_transport_methods = []: vector transport methods that should be tested.\nvector_transport_inverse_retractions = [default_inverse_retraction_method for _ in 1:length(vector_transport_methods)]` inverse retractions to use with the vector transport method (especially the differentiated ones)\nvector_transport_to = [ true for _ in 1:length(vector_transport_methods)]: whether to check the to variant of vector transport\nvector_transport_direction = [ true for _ in 1:length(vector_transport_methods)]: whether to check the direction variant of vector transport\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.find_eps","page":"Testing","title":"Manifolds.find_eps","text":"find_eps(x...)\n\nFind an appropriate tolerance for given points or tangent vectors, or their types.\n\n\n\n\n\n","category":"function"},{"location":"features/testing.html#Manifolds.test_parallel_transport","page":"Testing","title":"Manifolds.test_parallel_transport","text":"test_parallel_transport(M,P; along=false, to=true, diretion=true)\n\nGeneric tests for parallel transport on Mgiven at least two pointsin P.\n\nThe single functions to transport along (a curve), to (a point) or (towards a) direction are sub-tests that can be activated by the keywords arguemnts\n\n!!! Note Since the interface to specify curves is not yet provided, the along keyword does not have an effect yet\n\n\n\n\n\n","category":"function"},{"location":"misc/notation.html#Notation-overview","page":"Notation","title":"Notation overview","text":"","category":"section"},{"location":"misc/notation.html","page":"Notation","title":"Notation","text":"Since manifolds include a reasonable amount of elements and functions, the following list tries to keep an overview of used notation throughout Manifolds.jl. The order is alphabetical by name. They might be used in a plain form within the code or when referring to that code. This is for example the case with the calligraphic symbols.","category":"page"},{"location":"misc/notation.html","page":"Notation","title":"Notation","text":"Within the documented functions, the utf8 symbols are used whenever possible, as long as that renders correctly in TeX within this documentation.","category":"page"},{"location":"misc/notation.html","page":"Notation","title":"Notation","text":"Symbol Description Also used Comment\ntau_p action map by group element p mathrmL_p, mathrmR_p either left or right\noperatornameAd_p(X) adjoint action of element p of a Lie group on the element X of the corresponding Lie algebra \ntimes Cartesian product of two manifolds see ProductManifold\n^wedge (n-ary) Cartesian power of a manifold see PowerManifold\ncdot^mathrmH conjugate/Hermitian transpose \na coordinates of a point in a chart see get_parameters\nfracmathrmDmathrmdt covariant derivative of a vector field X(t) \nT^*_p mathcal M the cotangent space at p \nξ a cotangent vector from T^*_p mathcal M ξ_1 ξ_2 ηzeta sometimes written with base point ξ_p.\nmathrmdphi_p(q) Differential of a map phi mathcal M to mathcal N with respect to p at a point q. For functions of multiple variables, for example phi(p p_1) where p in mathcal M and p_1 in mathcal M_1, variable p is explicitly stated to specify with respect to which argument the differential is calculated. mathrmdphi_q, (mathrmdphi)_q, (phi_*)_q, D_pphi(q) pushes tangent vectors X in T_q mathcal M forward to mathrmdphi_p(q)X in T_phi(q) mathcal N\nn dimension (of a manifold) n_1n_2ldotsm dim(mathcal M) for the real dimension sometimes also dim_mathbb R(mathcal M)\nd(cdotcdot) (Riemannian) distance d_mathcal M(cdotcdot) \nexp_p X exponential map at p in mathcal M of a vector X in T_p mathcal M exp_p(X) \nF a fiber see VectorBundleFibers\nmathbb F a field, usually mathbb F in mathbb Rmathbb C mathbb H, i.e. the real, complex, and quaternion numbers, respectively. field a manifold or a basis is based on\ngamma a geodesic gamma_pq, gamma_pX connecting two points pq or starting in p with velocity X.\n f(p) gradient of function f colon mathcalM to mathbbR at p in mathcalM \ncirc a group operation \ncdot^mathrmH Hermitian or conjugate transposed for both complex or quaternion matrices \ne identity element of a group \nI_k identity matrix of size ktimes k \nk indices ij \nlanglecdotcdotrangle inner product (in T_p mathcal M) langlecdotcdotrangle_p g_p(cdotcdot) \noperatornameretr^-1_pq an inverse retraction \nmathfrak g a Lie algebra \nmathcalG a (Lie) group \nlog_p q logarithmic map at p in mathcal M of a point q in mathcal M log_p(q) \nmathcal M a manifold mathcal M_1 mathcal M_2ldotsmathcal N \noperatornameExp the matrix exponential \noperatornameLog the matrix logarithm \nmathcal P_qgets pX parallel transport of the vector X from T_pmathcal M to T_qmathcal M\nmathcal P_pYX parallel transport in direction Y of the vector X from T_pmathcal M to T_qmathcal M, q = exp_pY\nmathcal P_t_1gets t_0^cX parallel transport along the curve c mathcal P^cX=mathcal P_1gets 0^cX of the vector X from p=c(0) to c(1)\np a point on mathcal M p_1 p_2 ldotsq for 3 points one might use xyz\noperatornameretr_pX a retraction \nξ a set of tangent vectors X_1ldotsX_n \nT_p mathcal M the tangent space at p \nX a tangent vector from T_p mathcal M X_1X_2ldotsYZ sometimes written with base point X_p\noperatornametr trace (of a matrix) \ncdot^mathrmT transposed \ne_i in mathbb R^n the ith unit vector e_i^n the space dimension (n) is omited, when clear from context\nB a vector bundle \nmathcal T_qgets pX vector transport of the vector X from T_pmathcal M to T_qmathcal M\nmathcal T_pYX vector transport in direction Y of the vector X from T_pmathcal M to T_qmathcal M, where q is deretmined by Y, for example using the exponential map or some retraction.\noperatornameVol(mathcal M) volume of manifold mathcal M \ntheta_p(X) volume density for vector X tangent at point p \n0_k the ktimes k zero matrix. ","category":"page"},{"location":"manifolds/symmetricpsdfixedrank.html#Symmetric-Positive-Semidefinite-Matrices-of-Fixed-Rank","page":"Symmetric positive semidefinite fixed rank","title":"Symmetric Positive Semidefinite Matrices of Fixed Rank","text":"","category":"section"},{"location":"manifolds/symmetricpsdfixedrank.html","page":"Symmetric positive semidefinite fixed rank","title":"Symmetric positive semidefinite fixed rank","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveSemidefiniteFixedRank.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpsdfixedrank.html#Manifolds.SymmetricPositiveSemidefiniteFixedRank","page":"Symmetric positive semidefinite fixed rank","title":"Manifolds.SymmetricPositiveSemidefiniteFixedRank","text":"SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe AbstractManifold $ \\operatorname{SPS}_k(n)$ consisting of the real- or complex-valued symmetric positive semidefinite matrices of size n n and rank k, i.e. the set\n\noperatornameSPS_k(n) = bigl\np 𝔽^n n big p^mathrmH = p\napa^mathrmH geq 0 text for all a 𝔽\ntext and operatornamerank(p) = kbigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ. We sometimes operatornameSPS_k𝔽(n), when distinguishing the real- and complex-valued manifold is important.\n\nAn element is represented by q 𝔽^n k from the factorization p = qq^mathrmH. Note that since for any unitary (orthogonal) A 𝔽^n n we have (Aq)(Aq)^mathrmH = qq^mathrmH = p, the representation is not unique, or in other words, the manifold is a quotient manifold of 𝔽^n k.\n\nThe tangent space at p, T_poperatornameSPS_k(n), is also represented by matrices Y 𝔽^n k and reads as\n\nT_poperatornameSPS_k(n) = bigl\nX 𝔽^n nX = qY^mathrmH + Yq^mathrmH\ntext ie X = X^mathrmH\nbigr\n\nNote that the metric used yields a non-complete manifold. The metric was used in[JourneeBachAbsilSepulchre2010][MassartAbsil2020].\n\nConstructor\n\nSymmetricPositiveSemidefiniteFixedRank(n::Int, k::Int, field::AbstractNumbers=ℝ)\n\nGenerate the manifold of n n symmetric positive semidefinite matrices of rank k over the field of real numbers ℝ or complex numbers ℂ.\n\n[JourneeBachAbsilSepulchre2010]: Journée, M., Bach, F., Absil, P.-A., and Sepulchre, R.: “Low-Rank Optimization on the Cone of Positive Semidefinite Matrices”, SIAM Journal on Optimization (20)5, pp. 2327–2351, 2010. doi: 10.1137/080731359, arXiv: 0807.4423.\n\n[MassartAbsil2020]: Massart, E., Absil, P.-A.: \"Quotient Geometry with Simple Geodesics for the AbstractManifold of Fixed-Rank Positive-Semidefinite Matrices\", SIAM Journal on Matrix Analysis and Applications (41)1, pp. 171–198, 2020. doi: 10.1137/18m1231389, preprint: sites.uclouvain.be/absil/2018.06.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpsdfixedrank.html#Base.exp-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"Base.exp","text":"exp(M::SymmetricPositiveSemidefiniteFixedRank, q, Y)\n\nCompute the exponential map on the SymmetricPositiveSemidefiniteFixedRank, which just reads\n\n exp_q Y = q+Y\n\nnote: Note\nSince the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing q_2 = exp_p(log_pq)might yield a matrix q_2neq q, but they represent the same point on the quotient manifold, i.e. d_operatornameSPS_k(n)(q_2q) = 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#Base.log-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"Base.log","text":"log(M::SymmetricPositiveSemidefiniteFixedRank, q, p)\n\nCompute the logarithmic map on the SymmetricPositiveSemidefiniteFixedRank manifold by minimizing lVert p - qYrVert with respect to Y.\n\nnote: Note\nSince the manifold is represented in the embedding and is a quotient manifold, the exponential and logarithmic map are a bijection only with respect to the equivalence classes. Computing q_2 = exp_p(log_pq)might yield a matrix q_2neq q, but they represent the same point on the quotient manifold, i.e. d_operatornameSPS_k(n)(q_2q) = 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase._isapprox-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase._isapprox","text":"isapprox(M::SymmetricPositiveSemidefiniteFixedRank, p, q; kwargs...)\n\ntest, whether two points p, q are (approximately) nearly the same. Since this is a quotient manifold in the embedding, the test is performed by checking their distance, if they are not the same, i.e. that d_mathcal M(pq) approx 0, where the comparison is performed with the classical isapprox. The kwargs... are passed on to this accordingly.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{SymmetricPositiveSemidefiniteFixedRank{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.check_point","text":"check_point(M::SymmetricPositiveSemidefiniteFixedRank{n,𝔽}, q; kwargs...)\n\nCheck whether q is a valid manifold point on the SymmetricPositiveSemidefiniteFixedRank M, i.e. whether p=q*q' is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽. The symmetry of p is not explicitly checked since by using q p is symmetric by construction. The tolerance for the symmetry of p can and the rank of q*q' be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.check_vector-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.check_vector","text":"check_vector(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SymmetricPositiveSemidefiniteFixedRank M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.\n\nDue to the reduced representation this is fulfilled as soon as the matrix is of correct size.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.distance-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.distance","text":"distance(M::SymmetricPositiveSemidefiniteFixedRank, p, q)\n\nCompute the distance between two points p, q on the SymmetricPositiveSemidefiniteFixedRank, which is the Frobenius norm of Y which minimizes lVert p - qYrVert with respect to Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.is_flat-Tuple{SymmetricPositiveSemidefiniteFixedRank}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.is_flat","text":"is_flat(::SymmetricPositiveSemidefiniteFixedRank)\n\nReturn false. SymmetricPositiveSemidefiniteFixedRank is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.manifold_dimension-Tuple{SymmetricPositiveSemidefiniteFixedRank}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SymmetricPositiveSemidefiniteFixedRank{n,k,𝔽})\n\nReturn the dimension of the SymmetricPositiveSemidefiniteFixedRank matrix M over the number system 𝔽, i.e.\n\nbeginaligned\ndim operatornameSPS_kℝ(n) = kn - frack(k-1)2\ndim operatornameSPS_kℂ(n) = 2kn - k^2\nendaligned\n\nwhere the last k^2 is due to the zero imaginary part for Hermitian matrices diagonal\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.vector_transport_to-Tuple{SymmetricPositiveSemidefiniteFixedRank, Any, Any, Any, ProjectionTransport}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::SymmetricPositiveSemidefiniteFixedRank, p, X, q)\n\ntransport the tangent vector X at p to q by projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpsdfixedrank.html#ManifoldsBase.zero_vector-Tuple{SymmetricPositiveSemidefiniteFixedRank, Vararg{Any}}","page":"Symmetric positive semidefinite fixed rank","title":"ManifoldsBase.zero_vector","text":" zero_vector(M::SymmetricPositiveSemidefiniteFixedRank, p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the SymmetricPositiveSemidefiniteFixedRank manifold M.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#atlases_and_charts","page":"Atlases and charts","title":"Atlases and charts","text":"","category":"section"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Atlases on an n-dimensional manifold mathcal M are collections of charts mathcal A = (U_i φ_i) colon i in I, where I is a (finite or infinte) index family, such that U_i subseteq mathcal M is an open set and each chart φ_i U_i to mathbbR^n is a homeomorphism. This means, that φ_i is bijective – sometimes also called one-to-one and onto - and continuous, and its inverse φ_i^-1 is continuous as well. The inverse φ_i^-1 is called (local) parametrization. The resulting parameters a=φ(p) of p (with respect to the chart φ) are in the literature also called “(local) coordinates”. To distinguish the parameter a from get_coordinates in a basis, we use the terminology parameter in this package.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"For an atlas mathcal A we further require that","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"displaystylebigcup_iin I U_i = mathcal M","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"We say that φ_i is a chart about p, if pin U_i. An atlas provides a connection between a manifold and the Euclidean space mathbbR^n, since locally, a chart about p can be used to identify its neighborhood (as long as you stay in U_i) with a subset of a Euclidean space. Most manifolds we consider are smooth, i.e. any change of charts φ_i circ φ_j^-1 mathbbR^ntomathbbR^n, where ijin I, is a smooth function. These changes of charts are also called transition maps.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Most operations on manifolds in Manifolds.jl avoid operating in a chart through appropriate embeddings and formulas derived for particular manifolds, though atlases provide the most general way of working with manifolds. Compared to these approaches, using an atlas is often more technical and time-consuming. They are extensively used in metric-related functions on MetricManifolds.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Atlases are represented by objects of subtypes of AbstractAtlas. There are no type restrictions for indices of charts in atlases.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Operations using atlases and charts are available through the following functions:","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"get_chart_index can be used to select an appropriate chart for the neighborhood of a given point p. This function should work deterministically, i.e. for a fixed p always return the same chart.\nget_parameters converts a point to its parameters with respect to the chart in a chart.\nget_point converts parameters (local coordinates) in a chart to the point that corresponds to them.\ninduced_basis returns a basis of a given vector space at a point induced by a chart φ.\ntransition_map converts coordinates of a point between two charts, e.g. computes φ_icirc φ_j^-1 mathbbR^ntomathbbR^n, ijin I.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"While an atlas could store charts as explicit functions, it is favourable, that the [get_parameters] actually implements a chart φ, get_point its inverse, the prametrization φ^-1.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Modules = [Manifolds,ManifoldsBase]\nPages = [\"atlases.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/atlases.html#Manifolds.AbstractAtlas","page":"Atlases and charts","title":"Manifolds.AbstractAtlas","text":"AbstractAtlas{𝔽}\n\nAn abstract class for atlases whith charts that have values in the vector space 𝔽ⁿ for some value of n. 𝔽 is a number system determined by an AbstractNumbers object.\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.InducedBasis","page":"Atlases and charts","title":"Manifolds.InducedBasis","text":"InducedBasis(vs::VectorSpaceType, A::AbstractAtlas, i)\n\nThe basis induced by chart with index i from an AbstractAtlas A of vector space of type vs.\n\nFor the vs a TangentSpace this works as follows:\n\nLet n denote the dimension of the manifold mathcal M.\n\nLet the parameter a=φ_i(p) mathbb R^n and j1n. We can look at the jth parameter curve b_j(t) = a + te_j, where e_j denotes the jth unit vector. Using the parametrisation we obtain a curve c_j(t) = φ_i^-1(b_j(t)) which fulfills c(0) = p.\n\nNow taking the derivative(s) with respect to t (and evaluate at t=0), we obtain a tangent vector for each j corresponding to an equivalence class of curves (having the same derivative) as\n\nX_j = c_j = fracmathrmdmathrmdt c_i(t) Bigl_t=0\n\nand the set X_1ldotsX_n is the chart-induced basis of T_pmathcal M.\n\nSee also\n\nVectorSpaceType, AbstractBasis\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.RetractionAtlas","page":"Atlases and charts","title":"Manifolds.RetractionAtlas","text":"RetractionAtlas{\n 𝔽,\n TRetr<:AbstractRetractionMethod,\n TInvRetr<:AbstractInverseRetractionMethod,\n TBasis<:AbstractBasis,\n} <: AbstractAtlas{𝔽}\n\nAn atlas indexed by points on a manifold, mathcal M = I and parameters (local coordinates) are given in T_pmathcal M. This means that a chart φ_p = mathrmcordcircmathrmretr_p^-1 is only locally defined (around p), where mathrmcord is the decomposition of the tangent vector into coordinates with respect to the given basis of the tangent space, cf. get_coordinates. The parametrization is given by φ_p^-1=mathrmretr_pcircmathrmvec, where mathrmvec turns the basis coordinates into a tangent vector, cf. get_vector.\n\nIn short: The coordinates with respect to a basis are used together with a retraction as a parametrization.\n\nSee also\n\nAbstractAtlas, AbstractInverseRetractionMethod, AbstractRetractionMethod, AbstractBasis\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#LinearAlgebra.norm-Tuple{AbstractManifold, AbstractAtlas, Any, Any, Any}","page":"Atlases and charts","title":"LinearAlgebra.norm","text":"norm(M::AbstractManifold, A::AbstractAtlas, i, a, Xc)\n\nCalculate norm on manifold M at point with parameters a in chart i of an AbstractAtlas A of vector with coefficients Xc in induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.affine_connection!-Tuple{AbstractManifold, Any, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"Manifolds.affine_connection!","text":"affine_connection!(M::AbstractManifold, Zc, A::AbstractAtlas, i, a, Xc, Yc)\n\nCalculate affine connection on manifold M at point with parameters a in chart i of an an AbstractAtlas A of vectors with coefficients Zc and Yc in induced basis and save the result in Zc.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.affine_connection-Tuple{AbstractManifold, Vararg{Any, 5}}","page":"Atlases and charts","title":"Manifolds.affine_connection","text":"affine_connection(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)\n\nCalculate affine connection on manifold M at point with parameters a in chart i of AbstractAtlas A of vectors with coefficients Xc and Yc in induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.check_chart_switch-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.check_chart_switch","text":"check_chart_switch(M::AbstractManifold, A::AbstractAtlas, i, a)\n\nDetermine whether chart should be switched when an operation in chart i from an AbstractAtlas A reaches parameters a in that chart.\n\nBy default false is returned.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_chart_index-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.get_chart_index","text":"get_chart_index(M::AbstractManifold, A::AbstractAtlas, i, a)\n\nSelect a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point with parametrization a in chart i. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.\n\nSee also\n\nget_default_atlas\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_chart_index-Tuple{AbstractManifold, AbstractAtlas, Any}","page":"Atlases and charts","title":"Manifolds.get_chart_index","text":"get_chart_index(M::AbstractManifold, A::AbstractAtlas, p)\n\nSelect a chart from an AbstractAtlas A for manifold M that is suitable for representing the neighborhood of point p. This selection should be deterministic, although different charts may be selected for arbitrarily close but distinct points.\n\nSee also\n\nget_default_atlas\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_default_atlas-Tuple{AbstractManifold}","page":"Atlases and charts","title":"Manifolds.get_default_atlas","text":"get_default_atlas(::AbstractManifold)\n\nDetermine the default real-valued atlas for the given manifold.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_parameters-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.get_parameters","text":"get_parameters(M::AbstractManifold, A::AbstractAtlas, i, p)\n\nCalculate parameters (local coordinates) of point p on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the chart φ_i(p) iin I. The parameters are in the number system determined by A. If the point pnotin U_i is not in the domain of the chart, this method should throw an error.\n\nSee also\n\nget_point, get_chart_index\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.get_point-Tuple{AbstractManifold, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.get_point","text":"get_point(M::AbstractManifold, A::AbstractAtlas, i, a)\n\nCalculate point at parameters (local coordinates) a on manifold M in chart from an AbstractAtlas A at index i. This function is hence an implementation of the inverse φ_i^-1(a) iin I of a chart, also called a parametrization.\n\nSee also\n\nget_parameters, get_chart_index\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.induced_basis-Tuple{AbstractManifold, AbstractAtlas, Any, VectorSpaceType}","page":"Atlases and charts","title":"Manifolds.induced_basis","text":"induced_basis(M::AbstractManifold, A::AbstractAtlas, i, p, VST::VectorSpaceType)\n\nBasis of vector space of type VST at point p from manifold M induced by chart (A, i).\n\nSee also\n\nVectorSpaceType, AbstractAtlas\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.induced_basis-Union{Tuple{𝔽}, Tuple{AbstractManifold{𝔽}, AbstractAtlas, Any}, Tuple{AbstractManifold{𝔽}, AbstractAtlas, Any, VectorSpaceType}} where 𝔽","page":"Atlases and charts","title":"Manifolds.induced_basis","text":"induced_basis(::AbstractManifold, A::AbstractAtlas, i, VST::VectorSpaceType = TangentSpace)\n\nGet the basis induced by chart with index i from an AbstractAtlas A of vector space of type vs. Returns an object of type InducedBasis.\n\nSee also\n\nVectorSpaceType, AbstractBasis\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.inverse_chart_injectivity_radius-Tuple{AbstractManifold, AbstractAtlas, Any}","page":"Atlases and charts","title":"Manifolds.inverse_chart_injectivity_radius","text":"inverse_chart_injectivity_radius(M::AbstractManifold, A::AbstractAtlas, i)\n\nInjectivity radius of get_point for chart i from an AbstractAtlas A of a manifold M.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.local_metric-Tuple{AbstractManifold, Any, InducedBasis}","page":"Atlases and charts","title":"Manifolds.local_metric","text":"local_metric(M::AbstractManifold, p, B::InducedBasis)\n\nCompute the local metric tensor for vectors expressed in terms of coordinates in basis B on manifold M. The point p is not checked.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.transition_map-Tuple{AbstractManifold, AbstractAtlas, Any, AbstractAtlas, Any, Any}","page":"Atlases and charts","title":"Manifolds.transition_map","text":"transition_map(M::AbstractManifold, A_from::AbstractAtlas, i_from, A_to::AbstractAtlas, i_to, a)\ntransition_map(M::AbstractManifold, A::AbstractAtlas, i_from, i_to, a)\n\nGiven coordinates a in chart (A_from, i_from) of a point on manifold M, returns coordinates of that point in chart (A_to, i_to). If A_from and A_to are equal, A_to can be omitted.\n\nMathematically this function is the transition map or change of charts, but it might even be between two atlases A_textfrom = (U_iφ_i)_iin I and A_textto = (V_jpsi_j)_jin J, and hence I J are their index sets. We have i_textfromin I, i_texttoin J.\n\nThis method then computes\n\nbigl(psi_i_texttocirc φ_i_textfrom^-1bigr)(a)\n\nNote that, similarly to get_parameters, this method should fail the same way if V_i_texttocap U_i_textfrom=emptyset.\n\nSee also\n\nAbstractAtlas, get_parameters, get_point\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.transition_map_diff!-Tuple{AbstractManifold, Any, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"Manifolds.transition_map_diff!","text":"transition_map_diff!(M::AbstractManifold, c_out, A::AbstractAtlas, i_from, a, c, i_to)\n\nCompute transition_map_diff on given arguments and save the result in c_out.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.transition_map_diff-Tuple{AbstractManifold, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"Manifolds.transition_map_diff","text":"transition_map_diff(M::AbstractManifold, A::AbstractAtlas, i_from, a, c, i_to)\n\nCompute differential of transition map from chart i_from to chart i_to from an AbstractAtlas A on manifold M at point with parameters a on tangent vector with coordinates c in the induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#ManifoldsBase.inner-Tuple{AbstractManifold, AbstractAtlas, Vararg{Any, 4}}","page":"Atlases and charts","title":"ManifoldsBase.inner","text":"inner(M::AbstractManifold, A::AbstractAtlas, i, a, Xc, Yc)\n\nCalculate inner product on manifold M at point with parameters a in chart i of an atlas A of vectors with coefficients Xc and Yc in induced basis.\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Cotangent-space-and-musical-isomorphisms","page":"Atlases and charts","title":"Cotangent space and musical isomorphisms","text":"","category":"section"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Related to atlases, there is also support for the cotangent space and coefficients of cotangent vectors in bases of the cotangent space.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Functions sharp and flat implement musical isomorphisms for arbitrary vector bundles.","category":"page"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Modules = [Manifolds,ManifoldsBase]\nPages = [\"cotangent_space.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"features/atlases.html#Manifolds.RieszRepresenterCotangentVector","page":"Atlases and charts","title":"Manifolds.RieszRepresenterCotangentVector","text":"RieszRepresenterCotangentVector(M::AbstractManifold, p, X)\n\nCotangent vector in Riesz representer form on manifold M at point p with Riesz representer X.\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.flat-Tuple{AbstractManifold, Any, Any}","page":"Atlases and charts","title":"Manifolds.flat","text":"flat(M::AbstractManifold, p, X)\n\nCompute the flat isomorphism (one of the musical isomorphisms) of tangent vector X from the vector space of type M at point p from the underlying AbstractManifold.\n\nThe function can be used for example to transform vectors from the tangent bundle to vectors from the cotangent bundle Tmathcal M T^*mathcal M\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Manifolds.sharp-Tuple{AbstractManifold, Any, Any}","page":"Atlases and charts","title":"Manifolds.sharp","text":"sharp(M::AbstractManifold, p, ξ)\n\nCompute the sharp isomorphism (one of the musical isomorphisms) of vector ξ from the vector space M at point p from the underlying AbstractManifold.\n\nThe function can be used for example to transform vectors from the cotangent bundle to vectors from the tangent bundle T^*mathcal M Tmathcal M\n\n\n\n\n\n","category":"method"},{"location":"features/atlases.html#Computations-in-charts","page":"Atlases and charts","title":"Computations in charts","text":"","category":"section"},{"location":"features/atlases.html","page":"Atlases and charts","title":"Atlases and charts","text":"Manifolds.IntegratorTerminatorNearChartBoundary\nManifolds.estimate_distance_from_bvp\nManifolds.solve_chart_exp_ode\nManifolds.solve_chart_log_bvp\nManifolds.solve_chart_parallel_transport_ode","category":"page"},{"location":"features/atlases.html#Manifolds.IntegratorTerminatorNearChartBoundary","page":"Atlases and charts","title":"Manifolds.IntegratorTerminatorNearChartBoundary","text":"IntegratorTerminatorNearChartBoundary{TKwargs}\n\nAn object for determining the point at which integration of a differential equation in a chart on a manifold should be terminated for the purpose of switching a chart.\n\nThe value stored in check_chart_switch_kwargs will be passed as keyword arguments to check_chart_switch. By default an empty tuple is stored.\n\n\n\n\n\n","category":"type"},{"location":"features/atlases.html#Manifolds.estimate_distance_from_bvp","page":"Atlases and charts","title":"Manifolds.estimate_distance_from_bvp","text":"estimate_distance_from_bvp(\n M::AbstractManifold,\n a1,\n a2,\n A::AbstractAtlas,\n i;\n solver=GeneralMIRK4(),\n dt=0.05,\n kwargs...,\n)\n\nEstimate distance between points on AbstractManifold M with parameters a1 and a2 in chart i of AbstractAtlas A using solver solver, employing solve_chart_log_bvp to solve the geodesic BVP.\n\n\n\n\n\n","category":"function"},{"location":"features/atlases.html#Manifolds.solve_chart_exp_ode","page":"Atlases and charts","title":"Manifolds.solve_chart_exp_ode","text":"solve_chart_exp_ode(\n M::AbstractManifold,\n a,\n Xc,\n A::AbstractAtlas,\n i0;\n solver=AutoVern9(Rodas5()),\n final_time=1.0,\n check_chart_switch_kwargs=NamedTuple(),\n kwargs...,\n)\n\nSolve geodesic ODE on a manifold M from point of coordinates a in chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.\n\n\n\n\n\n","category":"function"},{"location":"features/atlases.html#Manifolds.solve_chart_log_bvp","page":"Atlases and charts","title":"Manifolds.solve_chart_log_bvp","text":"solve_chart_log_bvp(\n M::AbstractManifold,\n a1,\n a2,\n A::AbstractAtlas,\n i;\n solver=GeneralMIRK4(),\n dt=0.05,\n kwargs...,\n)\n\nSolve the BVP corresponding to geodesic calculation on AbstractManifold M, between points with parameters a1 and a2 in a chart i of an AbstractAtlas A using solver solver. Geodesic γ is sampled at time interval dt, with γ(0) = a1 and γ(1) = a2.\n\n\n\n\n\n","category":"function"},{"location":"features/atlases.html#Manifolds.solve_chart_parallel_transport_ode","page":"Atlases and charts","title":"Manifolds.solve_chart_parallel_transport_ode","text":"solve_chart_parallel_transport_ode(\n M::AbstractManifold,\n a,\n Xc,\n A::AbstractAtlas,\n i0,\n Yc;\n solver=AutoVern9(Rodas5()),\n check_chart_switch_kwargs=NamedTuple(),\n final_time=1.0,\n kwargs...,\n)\n\nParallel transport vector with coordinates Yc along geodesic on a manifold M from point of coordinates a in a chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.\n\n\n\n\n\n","category":"function"},{"location":"features/differentiation.html#Differentiation","page":"Differentiation","title":"Differentiation","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Documentation for Manifolds.jl's methods and types for finite differences and automatic differentiation.","category":"page"},{"location":"features/differentiation.html#Differentiation-backends","page":"Differentiation","title":"Differentiation backends","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/differentiation.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Further differentiation backends and features are available in ManifoldDiff.jl.","category":"page"},{"location":"features/differentiation.html#FiniteDifferenes.jl","page":"Differentiation","title":"FiniteDifferenes.jl","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/finite_differences.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"features/differentiation.html#Riemannian-differentiation-backends","page":"Differentiation","title":"Riemannian differentiation backends","text":"","category":"section"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/riemannian_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"features/differentiation.html","page":"Differentiation","title":"Differentiation","text":"Modules = [Manifolds]\nPages = [\"differentiation/embedded_diff.jl\"]\nOrder = [:type, :function, :constant]","category":"page"},{"location":"manifolds/flag.html#Flag-manifold","page":"Flag","title":"Flag manifold","text":"","category":"section"},{"location":"manifolds/flag.html","page":"Flag","title":"Flag","text":"Modules = [Manifolds]\nPages = [\"manifolds/Flag.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/flag.html#Manifolds.Flag","page":"Flag","title":"Manifolds.Flag","text":"Flag{N,d} <: AbstractDecoratorManifold{ℝ}\n\nFlag manifold of d subspaces of ℝ^N[YeWongLim2022]. By default the manifold uses the Stiefel coordinates representation, embedding it in the Stiefel manifold. The other available representation is an embedding in OrthogonalMatrices. It can be utilized using OrthogonalPoint and OrthogonalTVector wrappers.\n\nTangent space is represented in the block-skew-symmetric form.\n\nConstructor\n\nFlag(N, n1, n2, ..., nd)\n\nGenerate the manifold operatornameFlag(n_1 n_2 n_d N) of subspaces\n\n𝕍_1 𝕍_2 V_d quad operatornamedim(𝕍_i) = n_i\n\nwhere 𝕍_i for i 1 2 d are subspaces of ℝ^N of dimension operatornamedim 𝕍_i = n_i.\n\n[YeWongLim2022]: K. Ye, K. S.-W. Wong, and L.-H. Lim, “Optimization on flag manifolds,” Math. Program., vol. 194, no. 1, pp. 621–660, Jul. 2022, doi: 10.1007/s10107-021-01640-3.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Manifolds.OrthogonalPoint","page":"Flag","title":"Manifolds.OrthogonalPoint","text":"OrthogonalPoint <: AbstractManifoldPoint\n\nA type to represent points on a manifold Flag in the orthogonal coordinates representation, i.e. a rotation matrix.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Manifolds.OrthogonalTVector","page":"Flag","title":"Manifolds.OrthogonalTVector","text":"OrthogonalTVector <: TVector\n\nA type to represent tangent vectors to points on a Flag manifold in the orthogonal coordinates representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Manifolds.ZeroTuple","page":"Flag","title":"Manifolds.ZeroTuple","text":"ZeroTuple\n\nInternal structure for representing shape of a Flag manifold. Behaves like a normal tuple, except at index zero returns value 0.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{AbstractMatrix}, Flag, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector}","page":"Flag","title":"Base.convert","text":"convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)\n\nConvert tangent vector from Flag manifold M from orthogonal representation to Stiefel representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{AbstractMatrix}, Flag, Manifolds.OrthogonalPoint}","page":"Flag","title":"Base.convert","text":"convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint)\n\nConvert point p from Flag manifold M from orthogonal representation to Stiefel representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{Manifolds.OrthogonalPoint}, Flag, AbstractMatrix}","page":"Flag","title":"Base.convert","text":"convert(::Type{OrthogonalPoint}, M::Flag, p::AbstractMatrix)\n\nConvert point p from Flag manifold M from Stiefel representation to orthogonal representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#Base.convert-Tuple{Type{Manifolds.OrthogonalTVector}, Flag, AbstractMatrix, AbstractMatrix}","page":"Flag","title":"Base.convert","text":"convert(::Type{OrthogonalTVector}, M::Flag, p::AbstractMatrix, X::AbstractMatrix)\n\nConvert tangent vector from Flag manifold M from Stiefel representation to orthogonal representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.get_embedding-Union{Tuple{Flag{N, dp1}}, Tuple{dp1}, Tuple{N}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::Flag)\n\nGet the embedding of the Flag manifold M, i.e. the Stiefel manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.injectivity_radius-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Flag)\ninjectivity_radius(M::Flag, p)\n\nReturn the injectivity radius on the Flag M, which is fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.manifold_dimension-Union{Tuple{Flag{N, dp1}}, Tuple{dp1}, Tuple{N}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Flag)\n\nReturn dimension of flag manifold operatornameFlag(n_1 n_2 n_d N). The formula reads sum_i=1^d (n_i-n_i-1)(N-n_i).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#The-flag-manifold-represented-as-points-on-the-[Stiefel](@ref)-manifold","page":"Flag","title":"The flag manifold represented as points on the Stiefel manifold","text":"","category":"section"},{"location":"manifolds/flag.html","page":"Flag","title":"Flag","text":"Modules = [Manifolds]\nPages = [\"manifolds/FlagStiefel.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/flag.html#ManifoldsBase.check_vector-Union{Tuple{dp1}, Tuple{N}, Tuple{Flag{N, dp1}, AbstractMatrix, AbstractMatrix}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.check_vector","text":"check_vector(M::Flag, p::AbstractMatrix, X::AbstractMatrix; kwargs... )\n\nCheck whether X is a tangent vector to point p on the Flag manifold M operatornameFlag(n_1 n_2 n_d N) in the Stiefel representation, i.e. that X is a matrix of the form\n\nX = beginbmatrix\n0 B_12 cdots B_1d \n-B_12^mathrmT 0 cdots B_2d \nvdots vdots ddots vdots \n-B_1d^mathrmT -B_2d^mathrmT cdots 0 \n-B_1d+1^mathrmT -B_2d+1^mathrmT cdots -B_dd+1^mathrmT\nendbmatrix\n\nwhere B_ij ℝ^(n_i - n_i-1) (n_j - n_j-1), for 1 i j d+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.default_inverse_retraction_method-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.default_inverse_retraction_method","text":"default_inverse_retraction_method(M::Flag)\n\nReturn PolarInverseRetraction as the default inverse retraction for the Flag manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.default_retraction_method-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Flag)\n\nReturn PolarRetraction as the default retraction for the Flag manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.default_vector_transport_method-Tuple{Flag}","page":"Flag","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::Flag)\n\nReturn the ProjectionTransport as the default vector transport method for the Flag manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.inverse_retract-Tuple{Flag, Any, Any, PolarInverseRetraction}","page":"Flag","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Flag, p, q, ::PolarInverseRetraction)\n\nCompute the inverse retraction for the PolarRetraction, on the Flag manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.project-Tuple{Flag, Any, Any}","page":"Flag","title":"ManifoldsBase.project","text":"project(::Flag, p, X)\n\nProject vector X in the Euclidean embedding to the tangent space at point p on Flag manifold. The formula reads[YeWongLim2022]:\n\nY_i = X_i - (p_i p_i^mathrmT) X_i + sum_j neq i p_j X_j^mathrmT p_i\n\nfor i from 1 to d where the resulting vector is Y = Y_1 Y_2 Y_d and X = X_1 X_2 X_d, p = p_1 p_2 p_d are decompositions into basis vector matrices for consecutive subspaces of the flag.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.retract-Tuple{Flag, Any, Any, PolarRetraction}","page":"Flag","title":"ManifoldsBase.retract","text":"retract(M::Flag, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the Flag M. With USV = p + X the retraction reads\n\noperatornameretr_p X = UV^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#The-flag-manifold-represented-as-orthogonal-matrices","page":"Flag","title":"The flag manifold represented as orthogonal matrices","text":"","category":"section"},{"location":"manifolds/flag.html","page":"Flag","title":"Flag","text":"Modules = [Manifolds]\nPages = [\"manifolds/FlagOrthogonal.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/flag.html#ManifoldsBase.check_vector-Union{Tuple{dp1}, Tuple{N}, Tuple{Flag{N, dp1}, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.check_vector","text":"check_vector(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector; kwargs... )\n\nCheck whether X is a tangent vector to point p on the Flag manifold M operatornameFlag(n_1 n_2 n_d N) in the orthogonal matrix representation, i.e. that X is block-skew-symmetric with zero diagonal:\n\nX = beginbmatrix\n0 B_12 cdots B_1d+1 \n-B_12^mathrmT 0 cdots B_2d+1 \nvdots vdots ddots vdots \n-B_1d+1^mathrmT -B_2d+1^mathrmT cdots 0 \nendbmatrix\n\nwhere B_ij ℝ^(n_i - n_i-1) (n_j - n_j-1), for 1 i j d+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.get_embedding-Union{Tuple{N}, Tuple{Flag{N}, Manifolds.OrthogonalPoint}} where N","page":"Flag","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::Flag, p::OrthogonalPoint)\n\nGet embedding of Flag manifold M, i.e. the manifold OrthogonalMatrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.project-Union{Tuple{dp1}, Tuple{N}, Tuple{Flag{N, dp1}, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector}} where {N, dp1}","page":"Flag","title":"ManifoldsBase.project","text":"project(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)\n\nProject vector X to tangent space at point p from Flag manifold M operatornameFlag(n_1 n_2 n_d N), in the orthogonal matrix representation. It works by first projecting X to the space of SkewHermitianMatrices and then setting diagonal blocks to 0:\n\nX = beginbmatrix\n0 B_12 cdots B_1d+1 \n-B_12^mathrmT 0 cdots B_2d+1 \nvdots vdots ddots vdots \n-B_1d+1^mathrmT -B_2d+1^mathrmT cdots 0 \nendbmatrix\n\nwhere B_ij ℝ^(n_i - n_i-1) (n_j - n_j-1), for 1 i j d+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/flag.html#ManifoldsBase.retract-Tuple{Flag, Manifolds.OrthogonalPoint, Manifolds.OrthogonalTVector, QRRetraction}","page":"Flag","title":"ManifoldsBase.retract","text":"retract(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector, ::QRRetraction)\n\nCompute the QR retraction on the Flag in the orthogonal matrix representation as the first order approximation to the exponential map. Similar to QR retraction for [GeneralUnitaryMatrices].\n\n\n\n\n\n","category":"method"},{"location":"tutorials/working-in-charts.html#Working-in-charts","page":"work in charts","title":"Working in charts","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"In this tutorial we will learn how to use charts for basic geometric operations like exponential map, logarithmic map and parallel transport.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"There are two conceptually different approaches to working on a manifold: working in charts and chart-free representations.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The first one, widespread in differential geometry textbooks, is based on defining an atlas on the manifold and performing computations in selected charts. This approach, while generic, is not ideally suitable in all circumstances. For example, working in charts that do not cover the entire manifold causes issues with having to switch charts when operating on a manifold.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The second one is beneficital, if there exist a representation of points and tangent vectors for a manifold, which allow for efficient closed-form formulas for standard functions like the exponential map or Riemannian distance in this representation. These computations are then chart-free. Manifolds.jl supports both approaches, although the chart-free approach is the main focus of the library.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"In this tutorial we focus on chart-based computation.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"using Manifolds, RecursiveArrayTools, OrdinaryDiffEq, DiffEqCallbacks, BoundaryValueDiffEq","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The manifold we consider is the M is the torus in form of the EmbeddedTorus, that is the representation defined as a surface of revolution of a circle of radius 2 around a circle of radius 3. The atlas we will perform computations in is its DefaultTorusAtlas A, consistting of a family of charts indexed by two angles, that specify the base point of the chart.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We will draw geodesics time between 0 and t_end, and then sample the solution at multiples of dt and draw a line connecting sampled points.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"M = Manifolds.EmbeddedTorus(3, 2)\nA = Manifolds.DefaultTorusAtlas()","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"Manifolds.DefaultTorusAtlas()","category":"page"},{"location":"tutorials/working-in-charts.html#Setup","page":"work in charts","title":"Setup","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We will first set up our plot with an empty torus. param_points are points on the surface of the torus that will be used for basic surface shape in Makie.jl. The torus will be colored according to its Gaussian curvature stored in gcs. We later want to have a color scale that has negative curvature blue, zero curvature white and positive curvature red so gcs_mm is the largest absolute value of the curvature that will be needed to properly set range of curvature values.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"In the documentation this tutorial represents a static situation (without interactivity). Makie.jl rendering is turned off.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"# using GLMakie, Makie\n# GLMakie.activate!()\n\n\"\"\"\n torus_figure()\n\nThis function generates a simple plot of a torus and returns the new figure containing the plot.\n\"\"\"\nfunction torus_figure()\n fig = Figure(resolution=(1400, 1000), fontsize=16)\n ax = LScene(fig[1, 1], show_axis=true)\n ϴs, φs = LinRange(-π, π, 50), LinRange(-π, π, 50)\n param_points = [Manifolds._torus_param(M, θ, φ) for θ in ϴs, φ in φs]\n X1, Y1, Z1 = [[p[i] for p in param_points] for i in 1:3]\n gcs = [gaussian_curvature(M, p) for p in param_points]\n gcs_mm = max(abs(minimum(gcs)), abs(maximum(gcs)))\n pltobj = surface!(\n ax,\n X1,\n Y1,\n Z1;\n shading=true,\n ambient=Vec3f(0.65, 0.65, 0.65),\n backlight=1.0f0,\n color=gcs,\n colormap=Reverse(:RdBu),\n colorrange=(-gcs_mm, gcs_mm),\n transparency=true,\n )\n wireframe!(ax, X1, Y1, Z1; transparency=true, color=:gray, linewidth=0.5)\n zoom!(ax.scene, cameracontrols(ax.scene), 0.98)\n Colorbar(fig[1, 2], pltobj, height=Relative(0.5), label=\"Gaussian curvature\")\n return ax, fig\nend","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"torus_figure","category":"page"},{"location":"tutorials/working-in-charts.html#Values-for-the-geodesic","page":"work in charts","title":"Values for the geodesic","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"solve_for is a helper function that solves a parallel transport along geodesic problem on the torus M. p0x is the (theta varphi) parametrization of the point from which we will transport the vector. We first calculate the coordinates in the embedding of p0x and store it as p, and then get the initial chart from atlas A appropriate for starting working at point p. The vector we transport has coordinates Y_transp in the induced tangent space basis of chart i_p0x. The function returns the full solution to the parallel transport problem, containing the sequence of charts that was used and solutions of differential equations computed using OrdinaryDiffEq.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"bvp_i is needed later for a different purpose, it is the chart index we will use for solving the logarithmic map boundary value problem in.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"Next we solve the vector transport problem solve_for([θₚ, φₚ], [θₓ, φₓ], [θy, φy]), sample the result at the selected time steps and store the result in geo. The solution includes the geodesic which we extract and convert to a sequence of points digestible by Makie.jl, geo_ps. [θₚ, φₚ] is the parametrization in chart (0, 0) of the starting point of the geodesic. The direction of the geodesic is determined by [θₓ, φₓ], coordinates of the tangent vector at the starting point expressed in the induced basis of chart i_p0x (which depends on the initial point). Finally, [θy, φy] are the coordinates of the tangent vector that will be transported along the geodesic, which are also expressed in same basis as [θₓ, φₓ].","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We won’t draw the transported vector at every point as there would be too many arrows, which is why we select every 100th point only for that purpose with pt_indices. Then, geo_ps_pt contains points at which the transported vector is tangent to and geo_Ys the transported vector at that point, represented in the embedding.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"The logarithmic map will be solved between points with parametrization bvp_a1 and bvp_a2 in chart bvp_i. The result is assigned to variable bvp_sol and then sampled with time step 0.05. The result of this sampling is converted from parameters in chart bvp_i to point in the embedding and stored in geo_r.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"function solve_for(p0x, X_p0x, Y_transp, T)\n p = [Manifolds._torus_param(M, p0x...)...]\n i_p0x = Manifolds.get_chart_index(M, A, p)\n p_exp = Manifolds.solve_chart_parallel_transport_ode(\n M,\n [0.0, 0.0],\n X_p0x,\n A,\n i_p0x,\n Y_transp;\n final_time=T,\n )\n return p_exp\nend;","category":"page"},{"location":"tutorials/working-in-charts.html#Solving-parallel-Transport-ODE","page":"work in charts","title":"Solving parallel Transport ODE","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We set the end time t_end and time step dt.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"t_end = 2.0\ndt = 1e-1","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"0.1","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"We also parametrise the start point and direction.","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"θₚ = π/10\nφₚ = -π/4\nθₓ = π/2\nφₓ = 0.7\nθy = 0.2\nφy = -0.1\n\ngeo = solve_for([θₚ, φₚ], [θₓ, φₓ], [θy, φy], t_end)(0.0:dt:t_end);\n# geo_ps = [Point3f(s[1]) for s in geo]\n# pt_indices = 1:div(length(geo), 10):length(geo)\n# geo_ps_pt = [Point3f(s[1]) for s in geo[pt_indices]]\n# geo_Ys = [Point3f(s[3]) for s in geo[pt_indices]]\n\n# ax1, fig1 = torus_figure()\n# arrows!(ax1, geo_ps_pt, geo_Ys, linewidth=0.05, color=:blue)\n# lines!(geo_ps; linewidth=4.0, color=:green)\n# fig1","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"(Image: fig-pt)","category":"page"},{"location":"tutorials/working-in-charts.html#Solving-the-logairthmic-map-ODE","page":"work in charts","title":"Solving the logairthmic map ODE","text":"","category":"section"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"θ₁=π/2\nφ₁=-1.0\nθ₂=-π/8\nφ₂=π/2\n\nbvp_i = (0, 0)\nbvp_a1 = [θ₁, φ₁]\nbvp_a2 = [θ₂, φ₂]\nbvp_sol = Manifolds.solve_chart_log_bvp(M, bvp_a1, bvp_a2, A, bvp_i);\n# geo_r = [Point3f(get_point(M, A, bvp_i, p[1:2])) for p in bvp_sol(0.0:0.05:1.0)]\n\n# ax2, fig2 = torus_figure()\n# lines!(geo_r; linewidth=4.0, color=:green)\n# fig2","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"(Image: fig-geodesic)","category":"page"},{"location":"tutorials/working-in-charts.html","page":"work in charts","title":"work in charts","text":"An interactive Pluto version of this tutorial is available in file tutorials/working-in-charts.jl.","category":"page"},{"location":"tutorials/getstarted.html#Get-Started-with-Manifolds.jl","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This is a short overview of Manifolds.jl and how to get started working with your first Manifold. we first need to install the package, using for example","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"using Pkg; Pkg.add(\"Manifolds\")","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Then you can load the package with","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"using Manifolds","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[ Info: Precompiling ManifoldsRecipesBaseExt [37da849e-34ab-54fd-a5a4-b22599bd6cb0]","category":"page"},{"location":"tutorials/getstarted.html#Using-the-Library-of-Manifolds","page":"🚀 Get Started with Manifolds.jl","title":"Using the Library of Manifolds","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Manifolds.jl is first of all a library of manifolds, see the list in the menu here under “basic manifolds”.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Let’s look at three examples together with the first few functions on manifolds.","category":"page"},{"location":"tutorials/getstarted.html#.-[The-Euclidean-space](https://juliamanifolds.github.io/Manifolds.jl/latest/manifolds/euclidean.html)","page":"🚀 Get Started with Manifolds.jl","title":"1. The Euclidean space","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The Euclidean Space Euclidean brings us (back) into linear case of vectors, so in terms of manifolds, this is a very simple one. It is often useful to compare to classical algorithms, or implementations.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₁ = Euclidean(3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Euclidean(3; field = ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Since a manifold is a type in Julia, we write it in CamelCase. Its parameters are first a dimension or size parameter of the manifold, sometimes optional is a field the manifold is defined over.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"For example the above definition is the same as the real-valued case","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₁ === Euclidean(3, field=ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But we even introduced a short hand notation, since ℝ is also just a symbol/variable to use”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₁ === ℝ^3","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"And similarly here are two ways to create the manifold of vectors of length two with complex entries – or mathematically the space mathbb C^2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Euclidean(2, field=ℂ) === ℂ^2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The easiest to check is the dimension of a manifold. Here we have three “directions to walk into” at every point pin mathbb R ^3 so 🔗 manifold_dimension) is","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"manifold_dimension(M₁)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3","category":"page"},{"location":"tutorials/getstarted.html#.-[The-hyperpolic-space](@ref-HyperbolicSpace)","page":"🚀 Get Started with Manifolds.jl","title":"2. The hyperpolic space","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The d-dimensional hyperbolic space is usually represented in mathbb R^d+1 as the set of points pinmathbb R^3 fulfilling","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p_1^2+p_2^2+cdots+p_d^2-p_d+1^2 = -1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We define the manifold using","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₂ = Hyperbolic(2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Hyperbolic(2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"And we can again just start with looking at the manifold dimension of M₂","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"manifold_dimension(M₂)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"A next useful function is to check, whether some pmathbb R^3 is a point on the manifold M₂. We can check","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₂, [0, 0, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"or","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₂, [1, 0, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"false","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Keyword arguments are passed on to any numerical checks, for example an absolute tolerance when checking the above equiality.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But in an interactive session an error message might be helpful. A positional (third) argument is present to activate this. Setting this parameter to true, we obtain an error message that gives insight into why the point is not a point on M₂. Note that the LoadError: is due to quarto, on REPL you would just get the DomainError.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₂, [0, 0, 1.001], true)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"LoadError: DomainError with -1.0020009999999997:\nThe point [0.0, 0.0, 1.001] does not lie on Hyperbolic(2) since its Minkowski inner product is not -1.","category":"page"},{"location":"tutorials/getstarted.html#.-[The-sphere](@ref-SphereSection)","page":"🚀 Get Started with Manifolds.jl","title":"3. The sphere","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The sphere mathbb S^d is the d-dimensional sphere represented in its embedded form, that is unit vectors p in mathbb R^d+1 with unit norm lVert p rVert_2 = 1.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₃ = Sphere(2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Sphere(2, ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"If we only have a point that is approximately on the manifold, we can allow for a tolerance. Usually these are the same values of atol and rtol alowed in isapprox, i.e. we get","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₃, [0, 0, 1.001]; atol=1e-3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Here we can show a last nice check: 🔗 is_vector to check whether a tangent vector X is a representation of a tangent vector XT_pmathcal M to a point p on the manifold.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This function has two positional asrguments, the first to again indicate whether to throw an error, the second to disable the check that p is a valid point on the manifold. Usually this validity is essential for the tangent check, but if it was for example performed before, it can be turned off to spare time.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"For example in our first example the point is not of unit norm","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_vector(M₃, [2, 0, 0], [0, 1, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"false","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But the orthogonality of p and X is still valid, we can disable the point check, but even setting the error to true we get here","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_vector(M₃, [2, 0, 0], [0, 1, 1], true, false)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But of course it is better to use a valid point in the first place","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_vector(M₃, [1, 0, 0], [0, 1, 1])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"and for these we again get informative error messages","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"@expect_error is_vector(M₃, [1, 0, 0], [0.1, 1, 1], true) DomainError","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"LoadError: LoadError: UndefVarError: `@expect_error` not defined\nin expression starting at In[19]:1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To learn about how to define a manifold youself check out the 🔗 How to define your own manifold tutorial of 🔗 ManifoldsBase.jl.”","category":"page"},{"location":"tutorials/getstarted.html#Building-more-advanced-manifolds","page":"🚀 Get Started with Manifolds.jl","title":"Building more advanced manifolds","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Based on these basic manifolds we can directly build more advanced manifolds.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The first one concerns vectors or matrices of data on a manifold, the PowerManifold.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₄ = M₂^2","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"PowerManifold(Hyperbolic(2), 2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Then points are represented by arrays, where the power manifold dimension is added in the end. In other words – for the hyperbolic manifold here, we have a matrix with 2 columns, where each column is a valid point on hyperbolic space.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p = [0 0; 0 1; 1 sqrt(2)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3×2 Matrix{Float64}:\n 0.0 0.0\n 0.0 1.0\n 1.0 1.41421","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[is_point(M₂, p[:, 1]), is_point(M₂, p[:, 2])]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Bool}:\n 1\n 1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But of course the method we used previously also works for power manifolds:","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₄, p)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Note that nested power manifolds are combined into one as in","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₄₂ = M₄^4","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"PowerManifold(Hyperbolic(2), 2, 4)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"which represents 2times 4 – matrices of hyperbolic points represented in 3times 2times 4 arrays.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We can – alternatively – use a power manifold with nested arrays","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₅ = PowerManifold(M₃, NestedPowerRepresentation(), 2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"PowerManifold(Sphere(2, ℝ), NestedPowerRepresentation(), 2)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"which emphasizes that we have vectors of length 2 that contain points, so we store them that way.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₂ = [[0.0, 0.0, 1.0], [0.0, 1.0, 0.0]]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Vector{Float64}}:\n [0.0, 0.0, 1.0]\n [0.0, 1.0, 0.0]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To unify both representations, elements of the power manifold can also be accessed in the classical indexing fashion, if we start with the corresponding manifold first. This way one can implement algorithms also independent of which representation is used.”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p[M₄, 1]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3-element Vector{Float64}:\n 0.0\n 0.0\n 1.0","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₂[M₅, 2]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3-element Vector{Float64}:\n 0.0\n 1.0\n 0.0","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Another construtor is the ProductManifold to combine different manifolds. Here of course the order matters. First we construct these using ","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₆ = M₂ × M₃","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"ProductManifold with 2 submanifolds:\n Hyperbolic(2)\n Sphere(2, ℝ)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Since now the representations might differ from element to element, we have to encapsulate these in their own type.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₃ = Manifolds.ArrayPartition([0, 0, 1], [0, 1, 0])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"([0, 0, 1], [0, 1, 0])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Here ArrayPartition taken from 🔗 RecursiveArrayTools.jl to store the point on the product manifold efficiently in one array, still allowing efficient access to the product elements.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"is_point(M₆, p₃, true)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"true","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"But accessing single components still works the same.”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₃[M₆, 1]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"3-element Vector{Int64}:\n 0\n 0\n 1","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Finally, also the TangentBundle, the manifold collecting all tangent spaces on a manifold is available as”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₇ = TangentBundle(M₃)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"TangentBundle(Sphere(2, ℝ))","category":"page"},{"location":"tutorials/getstarted.html#Implementing-generic-Functions","page":"🚀 Get Started with Manifolds.jl","title":"Implementing generic Functions","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"In this section we take a look how to implement generic functions on manifolds.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"For our example here, we want to implement the so-called 📖 Bézier curve using the so-called 📖 de-Casteljau algorithm. The linked algorithm can easily be generalised to manifolds by replacing lines with geodesics. This was for example used in [1] and the following example is an extended version of an example from [2].","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The algorithm works recursively. For the case that we have a Bézier curve with just two points, the algorithm just evaluates the geodesic connecting both at some time point t01. The function to evaluate a shortest geodesic (it might not be unique, but then a deterministic choice is taken) between two points p and q on a manifold M 🔗 shortest_geodesic(M, p, q, t).","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function de_Casteljau(M::AbstractManifold, t, pts::NTuple{2})\n return shortest_geodesic(M, pts[1], pts[2], t)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"de_Casteljau (generic function with 1 method)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function de_Casteljau(M::AbstractManifold, t, pts::NTuple)\n p = de_Casteljau(M, t, pts[1:(end - 1)])\n q = de_Casteljau(M, t, pts[2:end])\n return shortest_geodesic(M, p, q, t)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"de_Casteljau (generic function with 2 methods)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Which can now be used on any manifold where the shortest geodesic is implemented","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Now on several manifolds the 📖 exponential map and its (locally defined) inverse, the logarithmic map might not be available in an implementation. So one way to generalise this, is the use of a retraction (see [3], Def. 4.1.1 for details) and its (local) inverse.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The function itself is quite similar to the expponential map, just that 🔗 retract(M, p, X, m) has one further parameter, the type of retraction to take, so m is a subtype of AbstractRetractionMethod m, the same for the 🔗 inverse_retract(M, p, q, n) with an AbstractInverseRetractionMethod n.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Thinking of a generic implementation, we would like to have a way to specify one, that is available. This can be done by using 🔗 default_retraction_method and 🔗 default_inverse_retraction_method, respectively. We implement","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function generic_de_Casteljau(\n M::AbstractManifold,\n t,\n pts::NTuple{2};\n m::AbstractRetractionMethod=default_retraction_method(M),\n n::AbstractInverseRetractionMethod=default_inverse_retraction_method(M),\n)\n X = inverse_retract(M, pts[1], pts[2], n)\n return retract(M, pts[1], X, t, m)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"generic_de_Casteljau (generic function with 1 method)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"and for the recursion","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"function generic_de_Casteljau(\n M::AbstractManifold,\n t,\n pts::NTuple;\n m::AbstractRetractionMethod=default_retraction_method(M),\n n::AbstractInverseRetractionMethod=default_inverse_retraction_method(M),\n)\n p = generic_de_Casteljau(M, t, pts[1:(end - 1)]; m=m, n=n)\n q = generic_de_Casteljau(M, t, pts[2:end]; m=m, n=n)\n X = inverse_retract(M, p, q, n)\n return retract(M, p, X, t, m)\nend","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"generic_de_Casteljau (generic function with 2 methods)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Note that on a manifold M where the exponential map is implemented, the default_retraction_method(M) returns 🔗 ExponentialRetraction, which yields that the retract function falls back to calling exp.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The same mechanism exists for 🔗 parallel_transport_to(M, p, X, q) and the more general 🔗 vector_transport_to(M, p, X, q, m) whose 🔗 AbstractVectorTransportMethod m has a default defined by 🔗 default_vector_transport_method(M).","category":"page"},{"location":"tutorials/getstarted.html#Allocating-and-in-place-computations","page":"🚀 Get Started with Manifolds.jl","title":"Allocating and in-place computations","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Memory allocation is a 🔗 critical performace issue when programming in Julia. To take this into account, Manifolds.jl provides special functions to reduce the amount of allocations.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We again look at the 📖 exponential map. On a manifold M the exponential map needs a point p (to start from) and a tangent vector X, which can be seen as direction to “walk into” as well as the length to walk into this direction. In Manifolds.jl the function can then be called with q = exp(M, p, X) (see 🔗 exp(M, p, X)). This function returns the resulting point q, which requires to allocate new memory.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To avoid this allocation, the function 🔗 exp!(M, q, p, X) can be called. Here q is allocated beforehand and is passed as the memory, where the result is returned in. It might be used even for interims computations, as long as it does not introduce side effects. Thas means that even with exp!(M, p, p, X) the result is correct.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Let’s look at an example.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"We take another look at the Sphere, but now a high-dimensional one. We can also illustrate how to generate radnom points and tangent vectors.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M = Sphere(10000)\np₄ = rand(M)\nX = rand(M; vector_at=p₄)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Looking at the allocations required we get","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"@allocated exp(M, p₄, X)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"9920959","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"While if we have already allocated memory for the resulting point on the manifold, for example","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"q₂ = zero(p₄);","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"There are no new memory allocations necessary if we use the in-place function.”","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"@allocated exp!(M, q₂, p₄, X)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"0","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This methodology is used for all functions that compute a new point or tangent vector. By default all allocating functions allocate memory and call the in-place function. This also means that if you implement a new manifold, you just have to implement the in-place version.","category":"page"},{"location":"tutorials/getstarted.html#Decorating-a-manifold","page":"🚀 Get Started with Manifolds.jl","title":"Decorating a manifold","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"As you saw until now, an 🔗 AbstractManifold describes a Riemannian manifold. For completeness, this also includes the chosen 📖 Riemannian metric tensor or inner product on the tangent spaces.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"In Manifolds.jl these are assumed to be a “reasonable default”. For example on the Sphere(n) we used above, the default metric is the one inherited from restricting the inner product from the embedding space onto each tangent space.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Consider a manifold like","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₈ = SymmetricPositiveDefinite(3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"SymmetricPositiveDefinite(3)","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"which is the manifold of 33 matrices that are symmetric and positive definite. which has a default as well, the affine invariant AffineInvariantMetric, but also has several different metrics.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"To switch the metric, we use the idea of a 📖 decorator pattern approach. Defining","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"M₈₂ = MetricManifold(M₈, BuresWassersteinMetric())","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"MetricManifold(SymmetricPositiveDefinite(3), BuresWassersteinMetric())","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"changes the manifold to use the BuresWassersteinMetric.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"This changes all functions that depend on the metric, most prominently the Riemannian matric, but also the exponential and logarithmic map and hence also geodesics.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"All functions that are not dependent on a metric – for example the manifold dimension, the tests of points and vectors we already looked at, but also all retractions – stay unchanged. This means that for example","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[manifold_dimension(M₈₂), manifold_dimension(M₈)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Int64}:\n 6\n 6","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"both calls the same underlying function. On the other hand with","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"p₅, X₅ = one(zeros(3, 3)), [1.0 0.0 1.0; 0.0 1.0 0.0; 1.0 0.0 1.0]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"([1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0], [1.0 0.0 1.0; 0.0 1.0 0.0; 1.0 0.0 1.0])","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"but for example the exponential map and the norm yield different results","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[exp(M₈, p₅, X₅), exp(M₈₂, p₅, X₅)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Matrix{Float64}}:\n [4.194528049465325 0.0 3.194528049465325; 0.0 2.718281828459045 0.0; 3.194528049465325 0.0 4.194528049465328]\n [2.5 0.0 1.5; 0.0 2.25 0.0; 1.5 0.0 2.5]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[norm(M₈, p₅, X₅), norm(M₈₂, p₅, X₅)]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"2-element Vector{Float64}:\n 2.23606797749979\n 1.118033988749895","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Technically this done using Traits – the trait here is the IsMetricManifold trait. Our trait system allows to combine traits but also to inherit properties in a hierarchical way, see 🔗 here for the technical details.","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"The same approach is used for","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"specifying a different connection\nspecifying a manifold as a certain quotient manifold\nspecifying a certain 🔗 embeddings\nspecify a certain group action","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Again, for all of these, the concrete types only have to be used if you want to do a second, different from the details, property, for example a second way to embed a manfiold. If a manifold is (in its usual representation) an embedded manifold, this works with the default manifold type already, since then it is again set as the reasonable default.","category":"page"},{"location":"tutorials/getstarted.html#References","page":"🚀 Get Started with Manifolds.jl","title":"References","text":"","category":"section"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[1]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Bergmann, R. and Gousenbourger, P.-Y.: A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics, 2018. doi: 10.3389/fams.2018.00059, arXiv: 1807.10090","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[2]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Axen, S. D., Baran, M., Bergmann, R. and Rzecki, K: Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds, arXiv preprint, 2022, 2106.08777","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"[3]","category":"page"},{"location":"tutorials/getstarted.html","page":"🚀 Get Started with Manifolds.jl","title":"🚀 Get Started with Manifolds.jl","text":"Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access","category":"page"},{"location":"manifolds/hyperbolic.html#HyperbolicSpace","page":"Hyperbolic space","title":"Hyperbolic space","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"The hyperbolic space can be represented in three different models.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Hyperboloid which is the default model, i.e. is used when using arbitrary array types for points and tangent vectors\nPoincaré ball with separate types for points and tangent vectors and a visualization for the two-dimensional case\nPoincaré half space with separate types for points and tangent vectors and a visualization for the two-dimensional cae.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"In the following the common functions are collected.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"A function in this general section uses vectors interpreted as if in the hyperboloid model, and other representations usually just convert to this representation to use these general functions.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPages = [\"manifolds/Hyperbolic.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Manifolds.Hyperbolic","page":"Hyperbolic space","title":"Manifolds.Hyperbolic","text":"Hyperbolic{N} <: AbstractDecoratorManifold{ℝ}\n\nThe hyperbolic space mathcal H^n represented by n+1-Tuples, i.e. embedded in the Lorentzian manifold equipped with the MinkowskiMetric cdotcdot_mathrmM. The space is defined as\n\nmathcal H^n = Biglp ℝ^n+1 Big pp_mathrmM= -p_n+1^2\n + displaystylesum_k=1^n p_k^2 = -1 p_n+1 0Bigr\n\nThe tangent space T_p mathcal H^n is given by\n\nT_p mathcal H^n = bigl\nX ℝ^n+1 pX_mathrmM = 0\nbigr\n\nNote that while the MinkowskiMetric renders the Lorentz manifold (only) pseudo-Riemannian, on the tangent bundle of the Hyperbolic space it induces a Riemannian metric. The corresponding sectional curvature is -1.\n\nIf p and X are Vectors of length n+1 they are assumed to be a HyperboloidPoint and a HyperboloidTVector, respectively\n\nOther models are the Poincaré ball model, see PoincareBallPoint and PoincareBallTVector, respectiely and the Poincaré half space model, see PoincareHalfSpacePoint and PoincareHalfSpaceTVector, respectively.\n\nConstructor\n\nHyperbolic(n)\n\nGenerate the Hyperbolic manifold of dimension n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.HyperboloidPoint","page":"Hyperbolic space","title":"Manifolds.HyperboloidPoint","text":"HyperboloidPoint <: AbstractManifoldPoint\n\nIn the Hyperboloid model of the Hyperbolic mathcal H^n points are represented as vectors in ℝ^n+1 with MinkowskiMetric equal to -1.\n\nThis representation is the default, i.e. AbstractVectors are assumed to have this repesentation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.HyperboloidTVector","page":"Hyperbolic space","title":"Manifolds.HyperboloidTVector","text":"HyperboloidTVector <: TVector\n\nIn the Hyperboloid model of the Hyperbolic mathcal H^n tangent vctors are represented as vectors in ℝ^n+1 with MinkowskiMetric pX_mathrmM=0 to their base point p.\n\nThis representation is the default, i.e. vectors are assumed to have this repesentation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareBallPoint","page":"Hyperbolic space","title":"Manifolds.PoincareBallPoint","text":"PoincareBallPoint <: AbstractManifoldPoint\n\nA point on the Hyperbolic manifold mathcal H^n can be represented as a vector of norm less than one in mathbb R^n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareBallTVector","page":"Hyperbolic space","title":"Manifolds.PoincareBallTVector","text":"PoincareBallTVector <: TVector\n\nIn the Poincaré ball model of the Hyperbolic mathcal H^n tangent vectors are represented as vectors in ℝ^n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareHalfSpacePoint","page":"Hyperbolic space","title":"Manifolds.PoincareHalfSpacePoint","text":"PoincareHalfSpacePoint <: AbstractManifoldPoint\n\nA point on the Hyperbolic manifold mathcal H^n can be represented as a vector in the half plane, i.e. x ℝ^n with x_d 0.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Manifolds.PoincareHalfSpaceTVector","page":"Hyperbolic space","title":"Manifolds.PoincareHalfSpaceTVector","text":"PoincareHalfPlaneTVector <: TVector\n\nIn the Poincaré half plane model of the Hyperbolic mathcal H^n tangent vectors are represented as vectors in ℝ^n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/hyperbolic.html#Base.exp-Tuple{Hyperbolic, Vararg{Any}}","page":"Hyperbolic space","title":"Base.exp","text":"exp(M::Hyperbolic, p, X)\n\nCompute the exponential map on the Hyperbolic space mathcal H^n emanating from p towards X. The formula reads\n\nexp_p X = cosh(sqrtXX_mathrmM)p\n+ sinh(sqrtXX_mathrmM)fracXsqrtXX_mathrmM\n\nwhere cdotcdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.log-Tuple{Hyperbolic, Vararg{Any}}","page":"Hyperbolic space","title":"Base.log","text":"log(M::Hyperbolic, p, q)\n\nCompute the logarithmic map on the Hyperbolic space mathcal H^n, the tangent vector representing the geodesic starting from p reaches q after time 1. The formula reads for p q\n\nlog_p q = d_mathcal H^n(pq)\nfracq-pq_mathrmM plVert q-pq_mathrmM p rVert_2\n\nwhere cdotcdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold. For p=q the logarihmic map is equal to the zero vector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Manifolds.manifold_volume-Tuple{Hyperbolic}","page":"Hyperbolic space","title":"Manifolds.manifold_volume","text":"manifold_dimension(M::Hyperbolic)\n\nReturn the volume of the hyperbolic space manifold mathcal H^n, i.e. infinity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.check_point-Tuple{Hyperbolic, Any}","page":"Hyperbolic space","title":"ManifoldsBase.check_point","text":"check_point(M::Hyperbolic, p; kwargs...)\n\nCheck whether p is a valid point on the Hyperbolic M.\n\nFor the HyperboloidPoint or plain vectors this means that, p is a vector of length n+1 with inner product in the embedding of -1, see MinkowskiMetric. The tolerance for the last test can be set using the kwargs....\n\nFor the PoincareBallPoint a valid point is a vector p ℝ^n with a norm stricly less than 1.\n\nFor the PoincareHalfSpacePoint a valid point is a vector from p ℝ^n with a positive last entry, i.e. p_n0\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.check_vector-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.check_vector","text":"check_vector(M::Hyperbolic{n}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the Hyperbolic M, i.e. after check_point(M,p), X has to be of the same dimension as p. The tolerance for the last test can be set using the kwargs....\n\nFor a the hyperboloid model or vectors, X has to be orthogonal to p with respect to the inner product from the embedding, see MinkowskiMetric.\n\nFor a the Poincaré ball as well as the Poincaré half plane model, X has to be a vector from ℝ^n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.injectivity_radius-Tuple{Hyperbolic}","page":"Hyperbolic space","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Hyperbolic)\ninjectivity_radius(M::Hyperbolic, p)\n\nReturn the injectivity radius on the Hyperbolic, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.is_flat-Tuple{Hyperbolic}","page":"Hyperbolic space","title":"ManifoldsBase.is_flat","text":"is_flat(::Hyperbolic)\n\nReturn false. Hyperbolic is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.manifold_dimension-Union{Tuple{Hyperbolic{N}}, Tuple{N}} where N","page":"Hyperbolic space","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Hyperbolic)\n\nReturn the dimension of the hyperbolic space manifold mathcal H^n, i.e. dim(mathcal H^n) = n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.parallel_transport_to-Tuple{Hyperbolic, Any, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::Hyperbolic, p, X, q)\n\nCompute the paralllel transport of the X from the tangent space at p on the Hyperbolic space mathcal H^n to the tangent at q along the geodesic connecting p and q. The formula reads\n\nmathcal P_qpX = X - fraclog_p qX_pd^2_mathcal H^n(pq)\nbigl(log_p q + log_qp bigr)\n\nwhere cdotcdot_p denotes the inner product in the tangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.project-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.project","text":"project(M::Hyperbolic, p, X)\n\nPerform an orthogonal projection with respect to the Minkowski inner product of X onto the tangent space at p of the Hyperbolic space M.\n\nThe formula reads\n\nY = X + pX_mathrmM p\n\nwhere cdot cdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.\n\nnote: Note\nProjection is only available for the (default) HyperboloidTVector representation, the others don't have such an embedding\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Statistics.mean-Tuple{Hyperbolic, Vararg{Any}}","page":"Hyperbolic space","title":"Statistics.mean","text":"mean(\n M::Hyperbolic,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = CyclicProximalPointEstimation();\n kwargs...,\n)\n\nCompute the Riemannian mean of x on the Hyperbolic space using CyclicProximalPointEstimation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#hyperboloid_model","page":"Hyperbolic space","title":"hyperboloid model","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPrivate = false\nPages = [\"manifolds/HyperbolicHyperboloid.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidPoint}, PoincareBallPoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidPoint}, p::PoincareBallPoint)\nconvert(::Type{AbstractVector}, p::PoincareBallPoint)\n\nconvert a point PoincareBallPoint x (from ℝ^n) from the Poincaré ball model of the Hyperbolic manifold mathcal H^n to a HyperboloidPoint π(p) ℝ^n+1. The isometry is defined by\n\nπ(p) = frac11-lVert p rVert^2\nbeginpmatrix2p_12p_n1+lVert p rVert^2endpmatrix\n\nNote that this is also used, when the type to convert to is a vector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidPoint}, PoincareHalfSpacePoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidPoint}, p::PoincareHalfSpacePoint)\nconvert(::Type{AbstractVector}, p::PoincareHalfSpacePoint)\n\nconvert a point PoincareHalfSpacePoint p (from ℝ^n) from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a HyperboloidPoint π(p) ℝ^n+1.\n\nThis is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidTVector}, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidTVector}, p::PoincareBallPoint, X::PoincareBallTVector)\nconvert(::Type{AbstractVector}, p::PoincareBallPoint, X::PoincareBallTVector)\n\nConvert the PoincareBallTVector X from the tangent space at p to a HyperboloidTVector by computing the push forward of the isometric map, cf. convert(::Type{HyperboloidPoint}, p::PoincareBallPoint).\n\nThe push forward π_*(p) maps from ℝ^n to a subspace of ℝ^n+1, the formula reads\n\nπ_*(p)X = beginpmatrix\n frac2X_11-lVert p rVert^2 + frac4(1-lVert p rVert^2)^2Xpp_1\n \n frac2X_n1-lVert p rVert^2 + frac4(1-lVert p rVert^2)^2Xpp_n\n frac4(1-lVert p rVert^2)^2Xp\nendpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{HyperboloidTVector}, PoincareHalfSpacePoint, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{HyperboloidTVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)\nconvert(::Type{AbstractVector}, p::PoincareHalfSpacePoint, X::PoincareHalfSpaceTVector)\n\nconvert a point PoincareHalfSpaceTVector X (from ℝ^n) at p from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a HyperboloidTVector π(p) ℝ^n+1.\n\nThis is done in two steps, namely transforming it to a Poincare ball point and from there further on to a Hyperboloid point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{HyperboloidPoint, HyperboloidTVector}}, Tuple{PoincareBallPoint, PoincareBallTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{HyperboloidPoint,HyperboloidTVector}}.\n (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}\n)\nconvert(\n ::Type{Tuple{P,T}},\n (p, X)::Tuple{PoincareBallPoint,PoincareBallTVector},\n) where {P<:AbstractVector, T <: AbstractVector}\n\nConvert a PoincareBallPoint p and a PoincareBallTVector X to a HyperboloidPoint and a HyperboloidTVector simultaneously, see convert(::Type{HyperboloidPoint}, ::PoincareBallPoint) and convert(::Type{HyperboloidTVector}, ::PoincareBallPoint, ::PoincareBallTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{HyperboloidPoint, HyperboloidTVector}}, Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{HyperboloidPoint,HyperboloidTVector},\n (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}\n)\nconvert(\n ::Type{Tuple{T,T},\n (p,X)::Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}\n) where {T<:AbstractVector}\n\nconvert a point PoincareHalfSpaceTVector X (from ℝ^n) at p from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a tuple of a HyperboloidPoint and a HyperboloidTVector π(p) ℝ^n+1 simultaneously.\n\nThis is done in two steps, namely transforming it to the Poincare ball model and from there further on to a Hyperboloid.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Manifolds.volume_density-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"Manifolds.volume_density","text":"volume_density(M::Hyperbolic, p, X)\n\nCompute volume density function of the hyperbolic manifold. The formula reads (sinh(lVert XrVert)lVert XrVert)^(n-1) where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.change_representer-Tuple{Hyperbolic, EuclideanMetric, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.change_representer","text":"change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p, X)\n\nChange the Eucliden representer X of a cotangent vector at point p. We only have to correct for the metric, which means that the sign of the last entry changes, since for the result Y we are looking for a tangent vector such that\n\n g_p(YZ) = -y_n+1z_n+1 + sum_i=1^n y_iz_i = sum_i=1^n+1 z_ix_i\n\nholds, which directly yields y_i=x_i for i=1ldotsn and y_n+1=-x_n+1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.distance-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.distance","text":"distance(M::Hyperbolic, p, q)\ndistance(M::Hyperbolic, p::HyperboloidPoint, q::HyperboloidPoint)\n\nCompute the distance on the Hyperbolic M, which reads\n\nd_mathcal H^n(pq) = operatornameacosh( - p q_mathrmM)\n\nwhere cdotcdot_mathrmM denotes the MinkowskiMetric on the embedding, the Lorentzian manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.get_coordinates-Tuple{Hyperbolic, Any, Any, DefaultOrthonormalBasis}","page":"Hyperbolic space","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::Hyperbolic, p, X, ::DefaultOrthonormalBasis)\n\nCompute the coordinates of the vector X with respect to the orthogonalized version of the unit vectors from ℝ^n, where n is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.get_vector-Tuple{Hyperbolic, Any, Any, DefaultOrthonormalBasis}","page":"Hyperbolic space","title":"ManifoldsBase.get_vector","text":"get_vector(M::Hyperbolic, p, c, ::DefaultOrthonormalBasis)\n\nCompute the vector from the coordinates with respect to the orthogonalized version of the unit vectors from ℝ^n, where n is the manifold dimension of the Hyperbolic M, utting them intop the tangent space at p and orthonormalizing them.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.inner-Tuple{Hyperbolic, Any, Any, Any}","page":"Hyperbolic space","title":"ManifoldsBase.inner","text":"inner(M::Hyperbolic{n}, p, X, Y)\ninner(M::Hyperbolic{n}, p::HyperboloidPoint, X::HyperboloidTVector, Y::HyperboloidTVector)\n\nCmpute the inner product in the Hyperboloid model, i.e. the minkowski_metric in the embedding. The formula reads\n\ng_p(XY) = XY_mathrmM = -X_nY_n + displaystylesum_k=1^n-1 X_kY_k\n\nThis employs the metric of the embedding, see Lorentz space.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#hyperboloid_plot","page":"Hyperbolic space","title":"Visualization of the Hyperboloid","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"For the case of Hyperbolic(2) there is plotting available based on a PlottingRecipe. You can easily plot points, connecting geodesics as well as tangent vectors.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"note: Note\nThe recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation for the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of wires and a wireframe_color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_x or surface_resolution_y) and a surface_color.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"using Manifolds, Plots\nM = Hyperbolic(2)\npts = [ [0.85*cos(φ), 0.85*sin(φ), sqrt(0.85^2+1)] for φ ∈ range(0,2π,length=11) ]\nscene = plot(M, pts; geodesic_interpolation=100)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot. Note that we avoid redrawing the wireframe in the following plot! calls.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, pts; wireframe=false)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind that a tangent vector in plotting always requires its base point.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"pts2 = [ [0.45 .*cos(φ + 6π/11), 0.45 .*sin(φ + 6π/11), sqrt(0.45^2+1) ] for φ ∈ range(0,2π,length=11)]\nvecs = log.(Ref(M),pts,pts2)\nplot!(scene, M, pts, vecs; wireframe=false)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Just to illustrate, for the first point the tangent vector is pointing along the following geodesic","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, [pts[1], pts2[1]]; geodesic_interpolation=100, wireframe=false)","category":"page"},{"location":"manifolds/hyperbolic.html#Internal-functions","page":"Hyperbolic space","title":"Internal functions","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"The following functions are available for internal use to construct points in the hyperboloid model","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPublic = false\nPages = [\"manifolds/HyperbolicHyperboloid.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Manifolds._hyperbolize-Tuple{Hyperbolic, Any, Any}","page":"Hyperbolic space","title":"Manifolds._hyperbolize","text":"_hyperbolize(M, p, Y)\n\nGiven the Hyperbolic(n) manifold using the hyperboloid model and a point p thereon, we can put a vector Yin ℝ^n into the tangent space by computing its last component such that for the resulting p we have that its minkowski_metric is pX_mathrmM = 0, i.e. X_n+1 = fractilde p Yp_n+1, where tilde p = (p_1ldotsp_n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Manifolds._hyperbolize-Tuple{Hyperbolic, Any}","page":"Hyperbolic space","title":"Manifolds._hyperbolize","text":"_hyperbolize(M, q)\n\nGiven the Hyperbolic(n) manifold using the hyperboloid model, a point from the qin ℝ^n can be set onto the manifold by computing its last component such that for the resulting p we have that its minkowski_metric is pp_mathrmM = - 1, i.e. p_n+1 = sqrtlVert q rVert^2 - 1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#poincare_ball","page":"Hyperbolic space","title":"Poincaré ball model","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPages = [\"manifolds/HyperbolicPoincareBall.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallPoint}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareBallPoint}, p::HyperboloidPoint)\nconvert(::Type{PoincareBallPoint}, p::T) where {T<:AbstractVector}\n\nconvert a HyperboloidPoint pℝ^n+1 from the hyperboloid model of the Hyperbolic manifold mathcal H^n to a PoincareBallPoint π(p)ℝ^n in the Poincaré ball model. The isometry is defined by\n\nπ(p) = frac11+p_n+1 beginpmatrixp_1p_nendpmatrix\n\nNote that this is also used, when x is a vector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallPoint}, PoincareHalfSpacePoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareBallPoint}, p::PoincareHalfSpacePoint)\n\nconvert a point PoincareHalfSpacePoint p (from ℝ^n) from the Poincaré half plane model of the Hyperbolic manifold mathcal H^n to a PoincareBallPoint π(p) ℝ^n. Denote by tilde p = (p_1ldotsp_d-1)^mathrmT. Then the isometry is defined by\n\nπ(p) = frac1lVert tilde p rVert^2 + (p_n+1)^2\nbeginpmatrix2p_12p_n-1lVert prVert^2 - 1endpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallTVector}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareBallTVector}, p::HyperboloidPoint, X::HyperboloidTVector)\nconvert(::Type{PoincareBallTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}\n\nconvert a HyperboloidTVector X at p to a PoincareBallTVector on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Hyperboloid to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::HyperboloidPoint).\n\nThe formula reads\n\nπ_*(p)X = frac1p_n+1+1Bigl(tilde X - fracX_n+1p_n+1+1tilde p Bigl)\n\nwhere tilde X = beginpmatrixX_1X_nendpmatrix and tilde p = beginpmatrixp_1p_nendpmatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareBallTVector}, PoincareHalfSpacePoint, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{PoincareBallTVector},\n p::PoincareHalfSpacePoint,\n X::PoincareHalfSpaceTVector\n)\n\nconvert a PoincareHalfSpaceTVector X at p to a PoincareBallTVector on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Poincaré half space to the Poincaré ball, cf. convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint).\n\nThe formula reads\n\nπ_*(p)X =\nfrac1lVert tilde prVert^2 + (1+p_n)^2\nbeginpmatrix\n2X_1\n\n2X_n-1\n2Xp\nendpmatrix\n-\nfrac2(lVert tilde prVert^2 + (1+p_n)^2)^2\nbeginpmatrix\n2p_1(Xp+X_n)\n\n2p_n-1(Xp+X_n)\n(lVert p rVert^2-1)(Xp+X_n)\nendpmatrix\n\nwhere tilde p = beginpmatrixp_1p_n-1endpmatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareBallPoint, PoincareBallTVector}}, Tuple{HyperboloidPoint, HyperboloidTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}\n)\nconvert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p, X)::Tuple{P,T},\n) where {P<:AbstractVector, T <: AbstractVector}\n\nConvert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::HyperboloidPoint) and convert(::Type{PoincareBallTVector}, ::HyperboloidPoint, ::HyperboloidTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareBallPoint, PoincareBallTVector}}, Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}\n)\nconvert(\n ::Type{Tuple{PoincareBallPoint,PoincareBallTVector}},\n (p, X)::Tuple{T,T},\n) where {T <: AbstractVector}\n\nConvert a PoincareHalfSpacePoint p and a PoincareHalfSpaceTVector X to a PoincareBallPoint and a PoincareBallTVector simultaneously, see convert(::Type{PoincareBallPoint}, ::PoincareHalfSpacePoint) and convert(::Type{PoincareBallTVector}, ::PoincareHalfSpacePoint, ::PoincareHalfSpaceTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.change_metric-Tuple{Hyperbolic, EuclideanMetric, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.change_metric","text":"change_metric(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)\n\nSince in the metric we always have the term α = frac21-sum_i=1^n p_i^2 per element, the correction for the metric reads Z = frac1αX.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.change_representer-Tuple{Hyperbolic, EuclideanMetric, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.change_representer","text":"change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)\n\nSince in the metric we have the term α = frac21-sum_i=1^n p_i^2 per element, the correction for the gradient reads Y = frac1α^2X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.distance-Tuple{Hyperbolic, PoincareBallPoint, PoincareBallPoint}","page":"Hyperbolic space","title":"ManifoldsBase.distance","text":"distance(::Hyperbolic, p::PoincareBallPoint, q::PoincareBallPoint)\n\nCompute the distance on the Hyperbolic manifold mathcal H^n represented in the Poincaré ball model. The formula reads\n\nd_mathcal H^n(pq) =\noperatornameacoshBigl(\n 1 + frac2lVert p - q rVert^2(1-lVert prVert^2)(1-lVert qrVert^2)\nBigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.inner-Tuple{Hyperbolic, PoincareBallPoint, PoincareBallTVector, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.inner","text":"inner(::Hyperbolic, p::PoincareBallPoint, X::PoincareBallTVector, Y::PoincareBallTVector)\n\nCompute the inner producz in the Poincaré ball model. The formula reads\n\ng_p(XY) = frac4(1-lVert p rVert^2)^2 X Y \n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.project-Tuple{Hyperbolic, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"ManifoldsBase.project","text":"project(::Hyperbolic, ::PoincareBallPoint, ::PoincareBallTVector)\n\nprojction of tangent vectors in the Poincaré ball model is just the identity, since the tangent space consists of all ℝ^n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#poincare_ball_plot","page":"Hyperbolic space","title":"Visualization of the Poincaré ball","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"note: Note\nThe recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"If we consider a set of points, we can first plot these and their connecting geodesics using the geodesic_interpolation For the points. This variable specifies with how many points a geodesic between two successive points is sampled (per default it's -1, which deactivates geodesics) and the line style is set to be a path. Another keyword argument added is the border of the Poincaré disc, namely circle_points = 720 resolution of the drawn boundary (every hlaf angle) as well as its color, hyperbolic_border_color = RGBA(0.0, 0.0, 0.0, 1.0).","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"using Manifolds, Plots\nM = Hyperbolic(2)\npts = PoincareBallPoint.( [0.85 .* [cos(φ), sin(φ)] for φ ∈ range(0,2π,length=11)])\nscene = plot(M, pts, geodesic_interpolation = 100)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, pts)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind, that a tangent vector in plotting always requires its base point","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"pts2 = PoincareBallPoint.( [0.45 .* [cos(φ + 6π/11), sin(φ + 6π/11)] for φ ∈ range(0,2π,length=11)])\nvecs = log.(Ref(M),pts,pts2)\nplot!(scene, M, pts,vecs)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Just to illustrate, for the first point the tangent vector is pointing along the following geodesic","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, [pts[1], pts2[1]], geodesic_interpolation=100)","category":"page"},{"location":"manifolds/hyperbolic.html#poincare_halfspace","page":"Hyperbolic space","title":"Poincaré half space model","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"Modules = [Manifolds]\nPages = [\"manifolds/HyperbolicPoincareHalfspace.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpacePoint}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpacePoint}, p::Hyperboloid)\nconvert(::Type{PoincareHalfSpacePoint}, p)\n\nconvert a HyperboloidPoint or Vectorp (from ℝ^n+1) from the Hyperboloid model of the Hyperbolic manifold mathcal H^n to a PoincareHalfSpacePoint π(x) ℝ^n.\n\nThis is done in two steps, namely transforming it to a Poincare ball point and from there further on to a PoincareHalfSpacePoint point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpacePoint}, PoincareBallPoint}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpacePoint}, p::PoincareBallPoint)\n\nconvert a point PoincareBallPoint p (from ℝ^n) from the Poincaré ball model of the Hyperbolic manifold mathcal H^n to a PoincareHalfSpacePoint π(p) ℝ^n. Denote by tilde p = (p_1ldotsp_n-1). Then the isometry is defined by\n\nπ(p) = frac1lVert tilde p rVert^2 - (p_n-1)^2\nbeginpmatrix2p_12p_n-11-lVert prVert^2endpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpaceTVector}, Any}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpaceTVector}, p::HyperboloidPoint, ::HyperboloidTVector)\nconvert(::Type{PoincareHalfSpaceTVector}, p::P, X::T) where {P<:AbstractVector, T<:AbstractVector}\n\nconvert a HyperboloidTVector X at p to a PoincareHalfSpaceTVector on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Hyperboloid to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint).\n\nThis is done similarly to the approach there, i.e. by using the Poincaré ball model as an intermediate step.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{PoincareHalfSpaceTVector}, PoincareBallPoint, PoincareBallTVector}","page":"Hyperbolic space","title":"Base.convert","text":"convert(::Type{PoincareHalfSpaceTVector}, p::PoincareBallPoint, X::PoincareBallTVector)\n\nconvert a PoincareBallTVector X at p to a PoincareHalfSpacePoint on the Hyperbolic manifold mathcal H^n by computing the push forward π_*(p)X of the isometry π that maps from the Poincaré ball to the Poincaré half space, cf. convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint).\n\nThe formula reads\n\nπ_*(p)X =\nfrac1lVert tilde prVert^2 + (1-p_n)^2\nbeginpmatrix\n2X_1\n\n2X_n-1\n-2Xp\nendpmatrix\n-\nfrac2(lVert tilde prVert^2 + (1-p_n)^2)^2\nbeginpmatrix\n2p_1(Xp-X_n)\n\n2p_n-1(Xp-X_n)\n(lVert p rVert^2-1)(Xp-X_n)\nendpmatrix\n\nwhere tilde p = beginpmatrixp_1p_n-1endpmatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}, Tuple{HyperboloidPoint, HyperboloidTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},\n (p,X)::Tuple{HyperboloidPoint,HyperboloidTVector}\n)\nconvert(\n ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},\n (p, X)::Tuple{P,T},\n) where {P<:AbstractVector, T <: AbstractVector}\n\nConvert a HyperboloidPoint p and a HyperboloidTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::HyperboloidPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::Tuple{HyperboloidPoint,HyperboloidTVector}) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#Base.convert-Tuple{Type{Tuple{PoincareHalfSpacePoint, PoincareHalfSpaceTVector}}, Tuple{PoincareBallPoint, PoincareBallTVector}}","page":"Hyperbolic space","title":"Base.convert","text":"convert(\n ::Type{Tuple{PoincareHalfSpacePoint,PoincareHalfSpaceTVector}},\n (p,X)::Tuple{PoincareBallPoint,PoincareBallTVector}\n)\n\nConvert a PoincareBallPoint p and a PoincareBallTVector X to a PoincareHalfSpacePoint and a PoincareHalfSpaceTVector simultaneously, see convert(::Type{PoincareHalfSpacePoint}, ::PoincareBallPoint) and convert(::Type{PoincareHalfSpaceTVector}, ::PoincareBallPoint,::PoincareBallTVector) for the formulae.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.distance-Tuple{Hyperbolic, PoincareHalfSpacePoint, PoincareHalfSpacePoint}","page":"Hyperbolic space","title":"ManifoldsBase.distance","text":"distance(::Hyperbolic, p::PoincareHalfSpacePoint, q::PoincareHalfSpacePoint)\n\nCompute the distance on the Hyperbolic manifold mathcal H^n represented in the Poincaré half space model. The formula reads\n\nd_mathcal H^n(pq) = operatornameacoshBigl( 1 + fraclVert p - q rVert^22 p_n q_n Bigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.inner-Tuple{Hyperbolic, PoincareHalfSpacePoint, PoincareHalfSpaceTVector, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"ManifoldsBase.inner","text":"inner(\n ::Hyperbolic{n},\n p::PoincareHalfSpacePoint,\n X::PoincareHalfSpaceTVector,\n Y::PoincareHalfSpaceTVector\n)\n\nCompute the inner product in the Poincaré half space model. The formula reads\n\ng_p(XY) = fracXYp_n^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#ManifoldsBase.project-Tuple{Hyperbolic, PoincareHalfSpaceTVector}","page":"Hyperbolic space","title":"ManifoldsBase.project","text":"project(::Hyperbolic, ::PoincareHalfSpacePoint ::PoincareHalfSpaceTVector)\n\nprojction of tangent vectors in the Poincaré half space model is just the identity, since the tangent space consists of all ℝ^n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/hyperbolic.html#poincare_half_plane_plot","page":"Hyperbolic space","title":"Visualization on the Poincaré half plane","text":"","category":"section"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"For the case of Hyperbolic(2) there is a plotting available based on a PlottingRecipe you can easily plot points, connecting geodesics as well as tangent vectors.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"note: Note\nThe recipes are only loaded if Plots.jl or RecipesBase.jl is loaded.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We again have two different recipes, one for points, one for tangent vectors, where the first one again can be equipped with geodesics between the points. In the following example we generate 7 points on an ellipse in the Hyperboloid model.","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"using Manifolds, Plots\nM = Hyperbolic(2)\npre_pts = [2.0 .* [5.0*cos(φ), sin(φ)] for φ ∈ range(0,2π,length=7)]\npts = convert.(\n Ref(PoincareHalfSpacePoint),\n Manifolds._hyperbolize.(Ref(M), pre_pts)\n)\nscene = plot(M, pts, geodesic_interpolation = 100)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, pts)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"We can further generate tangent vectors in these spaces and use a plot for there. Keep in mind, that a tangent vector in plotting always requires its base point. Here we would like to look at the tangent vectors pointing to the origin","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"origin = PoincareHalfSpacePoint([0.0,1.0])\nvecs = [log(M,p,origin) for p ∈ pts]\nscene = plot!(scene, M, pts, vecs)","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"And we can again look at the corresponding geodesics, for example","category":"page"},{"location":"manifolds/hyperbolic.html","page":"Hyperbolic space","title":"Hyperbolic space","text":"plot!(scene, M, [pts[1], origin], geodesic_interpolation=100)\nplot!(scene, M, [pts[2], origin], geodesic_interpolation=100)","category":"page"},{"location":"manifolds/projectivespace.html#Projective-space","page":"Projective space","title":"Projective space","text":"","category":"section"},{"location":"manifolds/projectivespace.html","page":"Projective space","title":"Projective space","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProjectiveSpace.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/projectivespace.html#Manifolds.AbstractProjectiveSpace","page":"Projective space","title":"Manifolds.AbstractProjectiveSpace","text":"AbstractProjectiveSpace{𝔽} <: AbstractDecoratorManifold{𝔽}\n\nAn abstract type to represent a projective space over 𝔽 that is represented isometrically in the embedding.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/projectivespace.html#Manifolds.ArrayProjectiveSpace","page":"Projective space","title":"Manifolds.ArrayProjectiveSpace","text":"ArrayProjectiveSpace{T<:Tuple,𝔽} <: AbstractProjectiveSpace{𝔽}\n\nThe projective space 𝔽ℙ^n₁n₂nᵢ is the manifold of all lines in 𝔽^n₁n₂nᵢ. The default representation is in the embedding, i.e. as unit (Frobenius) norm matrices in 𝔽^n₁n₂nᵢ:\n\n𝔽ℙ^n_1 n_2 n_i = bigl p 𝔽^n_1 n_2 n_i big lVert p rVert_mathrmF = 1 λ 𝔽 λ = 1 p p λ bigr\n\nwhere p is an equivalence class of points p, sim indicates equivalence, and lVert rVert_mathrmF is the Frobenius norm. Note that unlike ProjectiveSpace, the argument for ArrayProjectiveSpace is given by the size of the embedding. This means that ProjectiveSpace(2) and ArrayProjectiveSpace(3) are the same manifold. Additionally, ArrayProjectiveSpace(n,1;field=𝔽) and Grassmann(n,1;field=𝔽) are the same.\n\nThe tangent space at point p is given by\n\nT_p 𝔽ℙ^n_1 n_2 n_i = bigl X 𝔽^n_1 n_2 n_i pX_mathrmF = 0 bigr \n\nwhere _mathrmF denotes the (Frobenius) inner product in the embedding 𝔽^n_1 n_2 n_i.\n\nConstructor\n\nArrayProjectiveSpace(n₁,n₂,...,nᵢ; field=ℝ)\n\nGenerate the projective space 𝔽ℙ^n_1 n_2 n_i, defaulting to the real projective space, where field can also be used to generate the complex- and right-quaternionic projective spaces.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/projectivespace.html#Manifolds.ProjectiveSpace","page":"Projective space","title":"Manifolds.ProjectiveSpace","text":"ProjectiveSpace{n,𝔽} <: AbstractProjectiveSpace{𝔽}\n\nThe projective space 𝔽ℙ^n is the manifold of all lines in 𝔽^n+1. The default representation is in the embedding, i.e. as unit norm vectors in 𝔽^n+1:\n\n𝔽ℙ^n = bigl p 𝔽^n+1 big lVert p rVert = 1 λ 𝔽 λ = 1 p p λ bigr\n\nwhere p is an equivalence class of points p, and indicates equivalence. For example, the real projective space ℝℙ^n is represented as the unit sphere 𝕊^n, where antipodal points are considered equivalent.\n\nThe tangent space at point p is given by\n\nT_p 𝔽ℙ^n = bigl X 𝔽^n+1 big pX = 0 bigr \n\nwhere denotes the inner product in the embedding 𝔽^n+1.\n\nWhen 𝔽 = ℍ, this implementation of ℍℙ^n is the right-quaternionic projective space.\n\nConstructor\n\nProjectiveSpace(n[, field=ℝ])\n\nGenerate the projective space 𝔽ℙ^n 𝔽^n+1, defaulting to the real projective space ℝℙ^n, where field can also be used to generate the complex- and right-quaternionic projective spaces.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/projectivespace.html#Base.log-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"Base.log","text":"log(M::AbstractProjectiveSpace, p, q)\n\nCompute the logarithmic map on AbstractProjectiveSpace M$ = 𝔽ℙ^n$, i.e. the tangent vector whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads\n\nlog_p q = (q λ - cos θ p) fracθsin θ\n\nwhere θ = arccosq p_mathrmF is the distance between p and q, _mathrmF is the Frobenius inner product, and λ = fracq p_mathrmFq p_mathrmF 𝔽 is the unit scalar that minimizes d_𝔽^n+1(p - q λ). That is, q λ is the member of the equivalence class q that is closest to p in the embedding. As a result, exp_p circ log_p colon q q λ.\n\nThe logarithmic maps for the real AbstractSphere 𝕊^n and the real projective space ℝℙ^n are identical when p and q are in the same hemisphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#Manifolds.manifold_volume-Tuple{AbstractProjectiveSpace{ℝ}}","page":"Projective space","title":"Manifolds.manifold_volume","text":"manifold_volume(M::AbstractProjectiveSpace{ℝ})\n\nVolume of the n-dimensional AbstractProjectiveSpace M. The formula reads:\n\nfracpi^(n+1)2Γ((n+1)2)\n\nwhere Γ denotes the Gamma function. For details see [BoyaSudarshanTilma2003].\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#Manifolds.uniform_distribution-Union{Tuple{n}, Tuple{ProjectiveSpace{n, ℝ}, Any}} where n","page":"Projective space","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::ProjectiveSpace{n,ℝ}, p) where {n}\n\nUniform distribution on given ProjectiveSpace M. Generated points will be of similar type as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase._isapprox-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase._isapprox","text":"isapprox(M::AbstractProjectiveSpace, p, q; kwargs...)\n\nCheck that points p and q on the AbstractProjectiveSpace M=𝔽ℙ^n are members of the same equivalence class, i.e. that p = q λ for some element λ 𝔽 with unit absolute value, that is, λ = 1. This is equivalent to the Riemannian distance being 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.check_point-Tuple{AbstractProjectiveSpace, Any}","page":"Projective space","title":"ManifoldsBase.check_point","text":"check_point(M::AbstractProjectiveSpace, p; kwargs...)\n\nCheck whether p is a valid point on the AbstractProjectiveSpace M, i.e. that it has the same size as elements of the embedding and has unit Frobenius norm. The tolerance for the norm check can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.check_vector-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase.check_vector","text":"check_vector(M::AbstractProjectiveSpace, p, X; kwargs... )\n\nCheck whether X is a tangent vector in the tangent space of p on the AbstractProjectiveSpace M, i.e. that X has the same size as elements of the tangent space of the embedding and that the Frobenius inner product p X_mathrmF = 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.distance-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase.distance","text":"distance(M::AbstractProjectiveSpace, p, q)\n\nCompute the Riemannian distance on AbstractProjectiveSpace M=𝔽ℙ^n between points p and q, i.e.\n\nd_𝔽ℙ^n(p q) = arccosbigl p q_mathrmF bigr\n\nNote that this definition is similar to that of the AbstractSphere. However, the absolute value ensures that all equivalent p and q have the same pairwise distance.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.get_coordinates-Tuple{AbstractProjectiveSpace{ℝ}, Any, Any, DefaultOrthonormalBasis}","page":"Projective space","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})\n\nRepresent the tangent vector X at point p from the AbstractProjectiveSpace M = 𝔽ℙ^n in an orthonormal basis by unitarily transforming the hyperplane containing X, whose normal is p, to the hyperplane whose normal is the x-axis.\n\nGiven q = p overlineλ + x, where λ = fracx p_mathrmFx p_mathrmF, _mathrmF denotes the Frobenius inner product, and overline denotes complex or quaternionic conjugation, the formula for Y is\n\nbeginpmatrix0 Yendpmatrix = left(X - qfrac2 q X_mathrmFq q_mathrmFright)overlineλ\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.get_vector-Tuple{AbstractProjectiveSpace, Any, Any, DefaultOrthonormalBasis{ℝ}}","page":"Projective space","title":"ManifoldsBase.get_vector","text":"get_vector(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})\n\nConvert a one-dimensional vector of coefficients X in the basis B of the tangent space at p on the AbstractProjectiveSpace M=𝔽ℙ^n to a tangent vector Y at p by unitarily transforming the hyperplane containing X, whose normal is the x-axis, to the hyperplane whose normal is p.\n\nGiven q = p overlineλ + x, where λ = fracx p_mathrmFx p_mathrmF, _mathrmF denotes the Frobenius inner product, and overline denotes complex or quaternionic conjugation, the formula for Y is\n\nY = left(X - qfrac2 leftlangle q beginpmatrix0 Xendpmatrixrightrangle_mathrmFq q_mathrmFright) λ\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.inverse_retract-Tuple{AbstractProjectiveSpace, Any, Any, Union{PolarInverseRetraction, ProjectionInverseRetraction, QRInverseRetraction}}","page":"Projective space","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::AbstractProjectiveSpace, p, q, method::ProjectionInverseRetraction)\ninverse_retract(M::AbstractProjectiveSpace, p, q, method::PolarInverseRetraction)\ninverse_retract(M::AbstractProjectiveSpace, p, q, method::QRInverseRetraction)\n\nCompute the equivalent inverse retraction ProjectionInverseRetraction, PolarInverseRetraction, and QRInverseRetraction on the AbstractProjectiveSpace manifold M=𝔽ℙ^n, i.e.\n\noperatornameretr_p^-1 q = q frac1p q_mathrmF - p\n\nwhere _mathrmF is the Frobenius inner product.\n\nNote that this inverse retraction is equivalent to the three corresponding inverse retractions on Grassmann(n+1,1,𝔽), where the three inverse retractions in this case coincide. For ℝℙ^n, it is the same as the ProjectionInverseRetraction on the real Sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.is_flat-Tuple{AbstractProjectiveSpace}","page":"Projective space","title":"ManifoldsBase.is_flat","text":"is_flat(M::AbstractProjectiveSpace)\n\nReturn true if AbstractProjectiveSpace is of dimension 1 and false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.manifold_dimension-Union{Tuple{AbstractProjectiveSpace{𝔽}}, Tuple{𝔽}} where 𝔽","page":"Projective space","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::AbstractProjectiveSpace{𝔽}) where {𝔽}\n\nReturn the real dimension of the AbstractProjectiveSpace M, respectively i.e. the real dimension of the embedding minus the real dimension of the field 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.parallel_transport_direction-Tuple{AbstractProjectiveSpace, Any, Any, Any}","page":"Projective space","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::AbstractProjectiveSpace, p, X, d)\n\nParallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M along the geodesic in the direction indicated by the tangent vector d, i.e.\n\nmathcalP_exp_p (d) p(X) = X - left(p fracsin θθ + d frac1 - cos θθ^2right) d X_p\n\nwhere θ = lVert d rVert, and _p is the inner product at the point p. For the real projective space, this is equivalent to the same vector transport on the real AbstractSphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.parallel_transport_to-Tuple{AbstractProjectiveSpace, Any, Any, Any}","page":"Projective space","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::AbstractProjectiveSpace, p, X, q)\n\nParallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M=𝔽ℙ^n to the tangent space at another point q.\n\nThis implementation proceeds by transporting X to T_q λ M using the same approach as parallel_transport_direction, where λ = fracq p_mathrmFq p_mathrmF 𝔽 is the unit scalar that takes q to the member q λ of its equivalence class q closest to p in the embedding. It then maps the transported vector from T_q λ M to T_q M. The resulting transport to T_q M is\n\nmathcalP_q p(X) = left(X - left(p fracsin θθ + d frac1 - cos θθ^2right) d X_pright) overlineλ\n\nwhere d = log_p q is the direction of the transport, θ = lVert d rVert_p is the distance between p and q, and overline denotes complex or quaternionic conjugation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.project-Tuple{AbstractProjectiveSpace, Any, Any}","page":"Projective space","title":"ManifoldsBase.project","text":"project(M::AbstractProjectiveSpace, p, X)\n\nOrthogonally project the point X onto the tangent space at p on the AbstractProjectiveSpace M:\n\noperatornameproj_p (X) = X - pp X_mathrmF\n\nwhere _mathrmF denotes the Frobenius inner product. For the real AbstractSphere and AbstractProjectiveSpace, this projection is the same.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.project-Tuple{AbstractProjectiveSpace, Any}","page":"Projective space","title":"ManifoldsBase.project","text":"project(M::AbstractProjectiveSpace, p)\n\nOrthogonally project the point p from the embedding onto the AbstractProjectiveSpace M:\n\noperatornameproj(p) = fracplVert p rVert_mathrmF\n\nwhere lVert rVert_mathrmF denotes the Frobenius norm. This is identical to projection onto the AbstractSphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.representation_size-Union{Tuple{ArrayProjectiveSpace{N}}, Tuple{N}} where N","page":"Projective space","title":"ManifoldsBase.representation_size","text":"representation_size(M::AbstractProjectiveSpace)\n\nReturn the size points on the AbstractProjectiveSpace M are represented as, i.e., the representation size of the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#ManifoldsBase.retract-Tuple{AbstractProjectiveSpace, Any, Any, Union{PolarRetraction, ProjectionRetraction, QRRetraction}}","page":"Projective space","title":"ManifoldsBase.retract","text":"retract(M::AbstractProjectiveSpace, p, X, method::ProjectionRetraction)\nretract(M::AbstractProjectiveSpace, p, X, method::PolarRetraction)\nretract(M::AbstractProjectiveSpace, p, X, method::QRRetraction)\n\nCompute the equivalent retraction ProjectionRetraction, PolarRetraction, and QRRetraction on the AbstractProjectiveSpace manifold M=𝔽ℙ^n, i.e.\n\noperatornameretr_p X = operatornameproj_p(p + X)\n\nNote that this retraction is equivalent to the three corresponding retractions on Grassmann(n+1,1,𝔽), where in this case they coincide. For ℝℙ^n, it is the same as the ProjectionRetraction on the real Sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/projectivespace.html#Statistics.mean-Tuple{AbstractProjectiveSpace, Vararg{Any}}","page":"Projective space","title":"Statistics.mean","text":"mean(\n M::AbstractProjectiveSpace,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/4);\n kwargs...,\n)\n\nCompute the Riemannian mean of points in vector x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#VectorBundleSection","page":"Vector bundle","title":"Vector bundles","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Vector bundle E is a manifold that is built on top of another manifold mathcal M (base space). It is characterized by a continuous function Π E mathcal M, such that for each point p mathcal M the preimage of p by Π, Π^-1(p), has a structure of a vector space. These vector spaces are called fibers. Bundle projection can be performed using function bundle_projection.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point x. An object representing a tangent bundle can be obtained using the constructor called TangentBundle.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Fibers of a vector bundle are represented by the type VectorBundleFibers. The important difference between functions operating on VectorBundle and VectorBundleFibers is that in the first case both a point on the underlying manifold and the vector are represented together (by a single argument) while in the second case only the vector part is present, while the point is supplied in a different argument where needed.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"VectorBundleFibers refers to the whole set of fibers of a vector bundle. There is also another type, VectorSpaceAtPoint, that represents a specific fiber at a given point. This distinction is made to reduce the need to repeatedly construct objects of type VectorSpaceAtPoint in certain usage scenarios. This is also considered a manifold.","category":"page"},{"location":"manifolds/vector_bundle.html#FVector","page":"Vector bundle","title":"FVector","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"For cases where confusion between different types of vectors is possible, the type FVector can be used to express which type of vector space the vector belongs to. It is used for example in musical isomorphisms (the flat and sharp functions) that are used to go from a tangent space to cotangent space and vice versa.","category":"page"},{"location":"manifolds/vector_bundle.html#Documentation","page":"Vector bundle","title":"Documentation","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/VectorBundle.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.TangentSpace-Tuple{AbstractManifold, Any}","page":"Vector bundle","title":"ManifoldsBase.TangentSpace","text":"TangentSpace(M::AbstractManifold, p)\n\nReturn a TangentSpaceAtPoint representing tangent space at p on the AbstractManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.CotangentSpaceAtPoint-Tuple{AbstractManifold, Any}","page":"Vector bundle","title":"Manifolds.CotangentSpaceAtPoint","text":"CotangentSpaceAtPoint(M::AbstractManifold, p)\n\nReturn an object of type VectorSpaceAtPoint representing cotangent space at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.SasakiRetraction","page":"Vector bundle","title":"Manifolds.SasakiRetraction","text":"struct SasakiRetraction <: AbstractRetractionMethod end\n\nExponential map on TangentBundle computed via Euler integration as described in [Muralidharan2012]. The system of equations for gamma ℝ to Tmathcal M such that gamma(1) = exp_pX(X_M X_F) and gamma(0)=(p X) reads\n\ndotgamma(t) = (dotp(t) dotX(t)) = (R(X(t) dotX(t))dotp(t) 0)\n\nwhere R is the Riemann curvature tensor (see riemann_tensor).\n\nConstructor\n\nSasakiRetraction(L::Int)\n\nIn this constructor L is the number of integration steps.\n\n[Muralidharan2012]: P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012, pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.TangentBundle","page":"Vector bundle","title":"Manifolds.TangentBundle","text":"TangentBundle{𝔽,M} = VectorBundle{𝔽,TangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}\n\nTangent bundle for manifold of type M, as a manifold with the Sasaki metric [Sasaki1958].\n\nExact retraction and inverse retraction can be approximated using VectorBundleProductRetraction, VectorBundleInverseProductRetraction and SasakiRetraction. VectorBundleProductVectorTransport can be used as a vector transport.\n\n[Sasaki1958]: S. Sasaki, “On the differential geometry of tangent bundles of Riemannian manifolds,” Tohoku Math. J. (2), vol. 10, no. 3, pp. 338–354, 1958, doi: 10.2748/tmj/1178244668.\n\nConstructors\n\nTangentBundle(M::AbstractManifold)\nTangentBundle(M::AbstractManifold, vtm::VectorBundleProductVectorTransport)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.TangentSpaceAtPoint","page":"Vector bundle","title":"Manifolds.TangentSpaceAtPoint","text":"TangentSpaceAtPoint{M}\n\nAlias for VectorSpaceAtPoint for the tangent space at a point.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.TangentSpaceAtPoint-Tuple{AbstractManifold, Any}","page":"Vector bundle","title":"Manifolds.TangentSpaceAtPoint","text":"TangentSpaceAtPoint(M::AbstractManifold, p)\n\nReturn an object of type VectorSpaceAtPoint representing tangent space at p on the AbstractManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.TensorProductType","page":"Vector bundle","title":"Manifolds.TensorProductType","text":"TensorProductType(spaces::VectorSpaceType...)\n\nVector space type corresponding to the tensor product of given vector space types.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundle","page":"Vector bundle","title":"Manifolds.VectorBundle","text":"VectorBundle{𝔽,TVS<:VectorSpaceType,TM<:AbstractManifold{𝔽}} <: AbstractManifold{𝔽}\n\nVector bundle on a AbstractManifold M of type VectorSpaceType.\n\nConstructor\n\nVectorBundle(M::AbstractManifold, type::VectorSpaceType)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleFibers","page":"Vector bundle","title":"Manifolds.VectorBundleFibers","text":"VectorBundleFibers(fiber::VectorSpaceType, M::AbstractManifold)\n\nType representing a family of vector spaces (fibers) of a vector bundle over M with vector spaces of type fiber. In contrast with VectorBundle, operations on VectorBundleFibers expect point-like and vector-like parts to be passed separately instead of being bundled together. It can be thought of as a representation of vector spaces from a vector bundle but without storing the point at which a vector space is attached (which is specified separately in various functions).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleInverseProductRetraction","page":"Vector bundle","title":"Manifolds.VectorBundleInverseProductRetraction","text":"struct VectorBundleInverseProductRetraction <: AbstractInverseRetractionMethod end\n\nInverse retraction of the point y at point p from vector bundle B over manifold B.fiber (denoted mathcal M). The inverse retraction is derived as a product manifold-style approximation to the logarithmic map in the Sasaki metric. The considered product manifold is the product between the manifold mathcal M and the topological vector space isometric to the fiber.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B. Similarly, q = (x_q V_q).\n\nThe inverse retraction is calculated as\n\noperatornameretr^-1_p q = (operatornameretr^-1_x_p(x_q) V_operatornameretr^-1 - V_p)\n\nwhere V_operatornameretr^-1 is the result of vector transport of V_q to the point x_p. The difference V_operatornameretr^-1 - V_p corresponds to the logarithmic map in the vector space F.\n\nSee also VectorBundleProductRetraction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleProductRetraction","page":"Vector bundle","title":"Manifolds.VectorBundleProductRetraction","text":"struct VectorBundleProductRetraction <: AbstractRetractionMethod end\n\nProduct retraction map of tangent vector X at point p from vector bundle B over manifold B.fiber (denoted mathcal M). The retraction is derived as a product manifold-style approximation to the exponential map in the Sasaki metric. The considered product manifold is the product between the manifold mathcal M and the topological vector space isometric to the fiber.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\nThe tangent vector X = (V_XM V_XF) T_pB where V_XM is a tangent vector from the tangent space T_x_pmathcal M and V_XF is a tangent vector from the tangent space T_V_pF (isomorphic to F).\n\nThe retraction is calculated as\n\noperatornameretr_p(X) = (exp_x_p(V_XM) V_exp)\n\nwhere V_exp is the result of vector transport of V_p + V_XF to the point exp_x_p(V_XM). The sum V_p + V_XF corresponds to the exponential map in the vector space F.\n\nSee also VectorBundleInverseProductRetraction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleProductVectorTransport","page":"Vector bundle","title":"Manifolds.VectorBundleProductVectorTransport","text":"VectorBundleProductVectorTransport{\n TMP<:AbstractVectorTransportMethod,\n TMV<:AbstractVectorTransportMethod,\n} <: AbstractVectorTransportMethod\n\nVector transport type on VectorBundle. method_point is used for vector transport of the point part and method_vector is used for transport of the vector part.\n\nThe vector transport is derived as a product manifold-style vector transport. The considered product manifold is the product between the manifold mathcal M and the topological vector space isometric to the fiber.\n\nConstructor\n\nVectorBundleProductVectorTransport(\n method_point::AbstractVectorTransportMethod,\n method_vector::AbstractVectorTransportMethod,\n)\nVectorBundleProductVectorTransport()\n\nBy default both methods are set to ParallelTransport.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorBundleVectorTransport","page":"Vector bundle","title":"Manifolds.VectorBundleVectorTransport","text":"const VectorBundleVectorTransport = VectorBundleProductVectorTransport\n\nDeprecated: an alias for VectorBundleProductVectorTransport.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Manifolds.VectorSpaceAtPoint","page":"Vector bundle","title":"Manifolds.VectorSpaceAtPoint","text":"VectorSpaceAtPoint{\n 𝔽,\n TFiber<:VectorBundleFibers{<:VectorSpaceType,<:AbstractManifold{𝔽}},\n TX,\n} <: AbstractManifold{𝔽}\n\nA vector space at a point p on the manifold. This is modelled using VectorBundleFibers with only a vector-like part and fixing the point-like part to be just p.\n\nThis vector space itself is also a manifold. Especially, it's flat and hence isometric to the Euclidean manifold.\n\nConstructor\n\nVectorSpaceAtPoint(fiber::VectorBundleFibers, p)\n\nA vector space (fiber type fiber of a vector bundle) at point p from the manifold fiber.manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/vector_bundle.html#Base.exp-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any}","page":"Vector bundle","title":"Base.exp","text":"exp(M::TangentSpaceAtPoint, p, X)\n\nExponential map of tangent vectors X and p from the tangent space M. It is calculated as their sum.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.getindex-Tuple{ArrayPartition, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.getindex","text":"getindex(p::ArrayPartition, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s]\n\nAccess the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.getindex-Tuple{ProductRepr, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.getindex","text":"getindex(p::ProductRepr, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s]\n\nAccess the element(s) at index s of a point p on a VectorBundle M by using the symbols :point and :vector for the base and vector component, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.log-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Vararg{Any}}","page":"Vector bundle","title":"Base.log","text":"log(M::TangentSpaceAtPoint, p, q)\n\nLogarithmic map on the tangent space manifold M, calculated as the difference of tangent vectors q and p from M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.setindex!-Tuple{ArrayPartition, Any, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.setindex!","text":"setindex!(p::ArrayPartition, val, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s] = val\n\nSet the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.\n\nnote: Note\nThe content of element of p is replaced, not the element itself.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Base.setindex!-Tuple{ProductRepr, Any, VectorBundle, Symbol}","page":"Vector bundle","title":"Base.setindex!","text":"setindex!(p::ProductRepr, val, M::VectorBundle, s::Symbol)\np[M::VectorBundle, s] = val\n\nSet the element(s) at index s of a point p on a VectorBundle M to val by using the symbols :point and :vector for the base and vector component, respectively.\n\nnote: Note\nThe content of element of p is replaced, not the element itself.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#LinearAlgebra.norm-Tuple{VectorBundleFibers, Any, Any}","page":"Vector bundle","title":"LinearAlgebra.norm","text":"norm(B::VectorBundleFibers, p, q)\n\nNorm of the vector X from the vector space of type B.fiber at point p from manifold B.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.bundle_projection-Tuple{VectorBundle, Any}","page":"Vector bundle","title":"Manifolds.bundle_projection","text":"bundle_projection(B::VectorBundle, p::ArrayPartition)\n\nProjection of point p from the bundle M to the base manifold. Returns the point on the base manifold B.manifold at which the vector part of p is attached.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.inverse_retract_product-Tuple{VectorBundle, Any, Any}","page":"Vector bundle","title":"Manifolds.inverse_retract_product","text":"inverse_retract_product(M::VectorBundle, p, q)\n\nCompute the allocating variant of the VectorBundleInverseProductRetraction, which by default allocates and calls inverse_retract_product!.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.retract_product-Tuple{VectorBundle, Any, Any, Number}","page":"Vector bundle","title":"Manifolds.retract_product","text":"retract_product(M::VectorBundle, p, q, t::Number)\n\nCompute the allocating variant of the VectorBundleProductRetraction, which by default allocates and calls retract_product!.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.retract_sasaki-Tuple{AbstractManifold, Any, Any, Number, SasakiRetraction}","page":"Vector bundle","title":"Manifolds.retract_sasaki","text":"retract_sasaki(M::AbstractManifold, p, X, t::Number, m::SasakiRetraction)\n\nCompute the allocating variant of the SasakiRetraction, which by default allocates and calls retract_sasaki!.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Manifolds.vector_bundle_transport-Tuple{VectorSpaceType, AbstractManifold}","page":"Vector bundle","title":"Manifolds.vector_bundle_transport","text":"vector_bundle_transport(fiber::VectorSpaceType, M::AbstractManifold)\n\nDetermine the vector tranport used for exp and log maps on a vector bundle with vector space type fiber and manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.allocate_result-Union{Tuple{TF}, Tuple{VectorBundleFibers, TF, Vararg{Any}}} where TF","page":"Vector bundle","title":"ManifoldsBase.allocate_result","text":"allocate_result(B::VectorBundleFibers, f, x...)\n\nAllocates an array for the result of function f that is an element of the vector space of type B.fiber on manifold B.manifold and arguments x... for implementing the non-modifying operation using the modifying operation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.allocate_result_type-Union{Tuple{N}, Tuple{TF}, Tuple{VectorBundleFibers, TF, Tuple{Vararg{Any, N}}}} where {TF, N}","page":"Vector bundle","title":"ManifoldsBase.allocate_result_type","text":"allocate_result_type(B::VectorBundleFibers, f, args::NTuple{N,Any}) where N\n\nReturn type of element of the array that will represent the result of function f for representing an operation with result in the vector space fiber for manifold M on given arguments (passed at a tuple).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.distance-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.distance","text":"distance(M::TangentSpaceAtPoint, p, q)\n\nDistance between vectors p and q from the vector space M. It is calculated as the norm of their difference.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.distance-Tuple{VectorBundleFibers, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.distance","text":"distance(B::VectorBundleFibers, p, X, Y)\n\nDistance between vectors X and Y from the vector space at point p from the manifold B.manifold, that is the base manifold of M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.injectivity_radius-Tuple{TangentBundle{𝔽} where 𝔽}","page":"Vector bundle","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::TangentBundle)\n\nInjectivity radius of TangentBundle manifold is infinite if the base manifold is flat and 0 otherwise. See https://mathoverflow.net/questions/94322/injectivity-radius-of-the-sasaki-metric.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.injectivity_radius-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽}","page":"Vector bundle","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::TangentSpaceAtPoint)\n\nReturn the injectivity radius on the TangentSpaceAtPoint M, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.inner-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.inner","text":"inner(M::TangentSpaceAtPoint, p, X, Y)\n\nInner product of vectors X and Y from the tangent space at M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.inner-Tuple{VectorBundle, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.inner","text":"inner(B::VectorBundle, p, X, Y)\n\nInner product of tangent vectors X and Y at point p from the vector bundle B over manifold B.fiber (denoted mathcal M).\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\nThe tangent vector v = (V_XM V_XF) T_xB where V_XM is a tangent vector from the tangent space T_x_pmathcal M and V_XF is a tangent vector from the tangent space T_V_pF (isomorphic to F). Similarly for the other tangent vector w = (V_YM V_YF) T_xB.\n\nThe inner product is calculated as\n\nX Y_p = V_XM V_YM_x_p + V_XF V_YF_V_p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.inner-Tuple{VectorBundleFibers, Any, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.inner","text":"inner(B::VectorBundleFibers, p, X, Y)\n\nInner product of vectors X and Y from the vector space of type B.fiber at point p from manifold B.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.is_flat-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽}","page":"Vector bundle","title":"ManifoldsBase.is_flat","text":"is_flat(::TangentSpaceAtPoint)\n\nReturn true. TangentSpaceAtPoint is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.is_flat-Tuple{VectorBundle}","page":"Vector bundle","title":"ManifoldsBase.is_flat","text":"is_flat(::VectorBundle)\n\nReturn true if the underlying manifold of VectorBundle M is flat.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(M::TangentSpaceAtPoint, p, X)\n\nProject the vector X from the tangent space M, that is project the vector X tangent at M.point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(M::TangentSpaceAtPoint, p)\n\nProject the point p from the tangent space M, that is project the vector p tangent at M.point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{VectorBundle, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(B::VectorBundle, p, X)\n\nProject the element X of the ambient space of the tangent space T_p B to the tangent space T_p B.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\nThe vector x = (V_XM V_XF) where x_p belongs to the ambient space of T_x_pmathcal M and V_XF belongs to the ambient space of the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\n\nThe projection is calculated by projecting V_XM to tangent space T_x_pmathcal M and then projecting the vector V_XF to the fiber F.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{VectorBundle, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(B::VectorBundle, p)\n\nProject the point p from the ambient space of the vector bundle B over manifold B.fiber (denoted mathcal M) to the vector bundle.\n\nNotation:\n\nThe point p = (x_p V_p) where x_p belongs to the ambient space of mathcal M and V_p belongs to the ambient space of the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\n\nThe projection is calculated by projecting the point x_p to the manifold mathcal M and then projecting the vector V_p to the tangent space T_x_pmathcal M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.project-Tuple{VectorBundleFibers, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.project","text":"project(B::VectorBundleFibers, p, X)\n\nProject vector X from the vector space of type B.fiber at point p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.vector_transport_to-Tuple{VectorBundle, Any, Any, Any, Manifolds.VectorBundleProductVectorTransport}","page":"Vector bundle","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::VectorBundle, p, X, q, m::VectorBundleProductVectorTransport)\n\nCompute the vector transport the tangent vector Xat p to q on the VectorBundle M using the VectorBundleProductVectorTransport m.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector!-Tuple{VectorBundleFibers, Any, Any}","page":"Vector bundle","title":"ManifoldsBase.zero_vector!","text":"zero_vector!(B::VectorBundleFibers, X, p)\n\nSave the zero vector from the vector space of type B.fiber at point p from manifold B.manifold to X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector-Tuple{TangentSpaceAtPoint{𝔽} where 𝔽, Vararg{Any}}","page":"Vector bundle","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::TangentSpaceAtPoint, p)\n\nZero tangent vector at point p from the tangent space M, that is the zero tangent vector at point M.point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector-Tuple{VectorBundle, Vararg{Any}}","page":"Vector bundle","title":"ManifoldsBase.zero_vector","text":"zero_vector(B::VectorBundle, p)\n\nZero tangent vector at point p from the vector bundle B over manifold B.fiber (denoted mathcal M). The zero vector belongs to the space T_pB\n\nNotation:\n\nThe point p = (x_p V_p) where x_p mathcal M and V_p belongs to the fiber F=π^-1(x_p) of the vector bundle B where π is the canonical projection of that vector bundle B.\n\nThe zero vector is calculated as\n\nmathbf0_p = (mathbf0_x_p mathbf0_F)\n\nwhere mathbf0_x_p is the zero tangent vector from T_x_pmathcal M and mathbf0_F is the zero element of the vector space F.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#ManifoldsBase.zero_vector-Tuple{VectorBundleFibers, Any}","page":"Vector bundle","title":"ManifoldsBase.zero_vector","text":"zero_vector(B::VectorBundleFibers, p)\n\nCompute the zero vector from the vector space of type B.fiber at point p from manifold B.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/vector_bundle.html#Example","page":"Vector bundle","title":"Example","text":"","category":"section"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"The following code defines a point on the tangent bundle of the sphere S^2 and a tangent vector to that point.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"using Manifolds\nM = Sphere(2)\nTB = TangentBundle(M)\np = ProductRepr([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])\nX = ProductRepr([0.0, 1.0, 0.0], [0.0, 0.0, -2.0])","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"An approximation of the exponential in the Sasaki metric using 1000 steps can be calculated as follows.","category":"page"},{"location":"manifolds/vector_bundle.html","page":"Vector bundle","title":"Vector bundle","text":"q = retract(TB, p, X, SasakiRetraction(1000))\nprintln(\"Approximation of the exponential map: \", q)","category":"page"},{"location":"manifolds/spheresymmetricmatrices.html#Unit-norm-symmetric-matrices","page":"Unit-norm symmetric matrices","title":"Unit-norm symmetric matrices","text":"","category":"section"},{"location":"manifolds/spheresymmetricmatrices.html","page":"Unit-norm symmetric matrices","title":"Unit-norm symmetric matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/SphereSymmetricMatrices.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/spheresymmetricmatrices.html#Manifolds.SphereSymmetricMatrices","page":"Unit-norm symmetric matrices","title":"Manifolds.SphereSymmetricMatrices","text":"SphereSymmetricMatrices{n,𝔽} <: AbstractEmbeddedManifold{ℝ,TransparentIsometricEmbedding}\n\nThe AbstractManifold consisting of the n n symmetric matrices of unit Frobenius norm, i.e.\n\nmathcalS_textsym =biglp 𝔽^n n big p^mathrmH = p lVert p rVert = 1 bigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ.\n\nConstructor\n\nSphereSymmetricMatrices(n[, field=ℝ])\n\nGenerate the manifold of n-by-n symmetric matrices of unit Frobenius norm.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{SphereSymmetricMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.check_point","text":"check_point(M::SphereSymmetricMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether the matrix is a valid point on the SphereSymmetricMatrices M, i.e. is an n-by-n symmetric matrix of unit Frobenius norm.\n\nThe tolerance for the symmetry of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{SphereSymmetricMatrices{n, 𝔽}, Any, Any}} where {n, 𝔽}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::SphereSymmetricMatrices{n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SphereSymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) of unit Frobenius norm.\n\nThe tolerance for the symmetry of p and X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.is_flat-Tuple{SphereSymmetricMatrices}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::SphereSymmetricMatrices)\n\nReturn false. SphereSymmetricMatrices is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.manifold_dimension-Union{Tuple{SphereSymmetricMatrices{n, 𝔽}}, Tuple{𝔽}, Tuple{n}} where {n, 𝔽}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SphereSymmetricMatrices{n,𝔽})\n\nReturn the manifold dimension of the SphereSymmetricMatrices n-by-n symmetric matrix M of unit Frobenius norm over the number system 𝔽, i.e.\n\nbeginaligned\ndim(mathcalS_textsym)(nℝ) = fracn(n+1)2 - 1\ndim(mathcalS_textsym)(nℂ) = 2fracn(n+1)2 - n -1\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.project-Tuple{SphereSymmetricMatrices, Any, Any}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SphereSymmetricMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the SphereSymmetricMatrices M, i.e.\n\noperatornameproj_p(X) = fracX + X^mathrmH2 - p fracX + X^mathrmH2p\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/spheresymmetricmatrices.html#ManifoldsBase.project-Tuple{SphereSymmetricMatrices, Any}","page":"Unit-norm symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SphereSymmetricMatrices, p)\n\nProjects p from the embedding onto the SphereSymmetricMatrices M, i.e.\n\noperatornameproj_mathcalS_textsym(p) = frac12 bigl( p + p^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Positive-Numbers","page":"Positive numbers","title":"Positive Numbers","text":"","category":"section"},{"location":"manifolds/positivenumbers.html","page":"Positive numbers","title":"Positive numbers","text":"The manifold PositiveNumbers represents positive numbers with hyperbolic geometry. Additionally, there are also short forms for its corresponding PowerManifolds, i.e. PositiveVectors, PositiveMatrices, and PositiveArrays.","category":"page"},{"location":"manifolds/positivenumbers.html","page":"Positive numbers","title":"Positive numbers","text":"Modules = [Manifolds]\nPages = [\"manifolds/PositiveNumbers.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveNumbers","page":"Positive numbers","title":"Manifolds.PositiveNumbers","text":"PositiveNumbers <: AbstractManifold{ℝ}\n\nThe hyperbolic manifold of positive numbers H^1 is a the hyperbolic manifold represented by just positive numbers.\n\nConstructor\n\nPositiveNumbers()\n\nGenerate the ℝ-valued hyperbolic model represented by positive positive numbers. To use this with arrays (1-element arrays), please use SymmetricPositiveDefinite(1).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/positivenumbers.html#Base.exp-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"Base.exp","text":"exp(M::PositiveNumbers, p, X)\n\nCompute the exponential map on the PositiveNumbers M.\n\nexp_p X = poperatornameexp(Xp)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Base.log-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"Base.log","text":"log(M::PositiveNumbers, p, q)\n\nCompute the logarithmic map on the PositiveNumbers M.\n\nlog_p q = plogfracqp\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveArrays-Union{Tuple{Vararg{Int64, I}}, Tuple{I}} where I","page":"Positive numbers","title":"Manifolds.PositiveArrays","text":"PositiveArrays(n₁,n₂,...,nᵢ)\n\nGenerate the manifold of i-dimensional arrays with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveMatrices-Tuple{Integer, Integer}","page":"Positive numbers","title":"Manifolds.PositiveMatrices","text":"PositiveMatrices(m,n)\n\nGenerate the manifold of matrices with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.PositiveVectors-Tuple{Integer}","page":"Positive numbers","title":"Manifolds.PositiveVectors","text":"PositiveVectors(n)\n\nGenerate the manifold of vectors with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.manifold_volume-Tuple{PositiveNumbers}","page":"Positive numbers","title":"Manifolds.manifold_volume","text":"manifold_volume(M::PositiveNumbers)\n\nReturn volume of PositiveNumbers M, i.e. Inf.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#Manifolds.volume_density-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"Manifolds.volume_density","text":"volume_density(M::PositiveNumbers, p, X)\n\nCompute volume density function of PositiveNumbers. The formula reads\n\ntheta_p(X) = exp(X p)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.change_metric-Tuple{PositiveNumbers, EuclideanMetric, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.change_metric","text":"change_metric(M::PositiveNumbers, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric of PositiveNumbers M.\n\nFor all ZY we are looking for the function c on the tangent space at p such that\n\n ZY = XY = fracc(Z)c(Y)p^2 = g_p(c(Y)c(Z))\n\nand hence C(X) = pX.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.change_representer-Tuple{PositiveNumbers, EuclideanMetric, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.change_representer","text":"change_representer(M::PositiveNumbers, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function with respect to the EuclideanMetric g_E, this function changes the representer into the one with respect to the positivity metric representation of PositiveNumbers M.\n\nFor all tangent vectors Y the result Z has to fulfill\n\n XY = XY = fracZYp^2 = g_p(YZ)\n\nand hence Z = p^2X\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.check_point-Tuple{PositiveNumbers, Any}","page":"Positive numbers","title":"ManifoldsBase.check_point","text":"check_point(M::PositiveNumbers, p)\n\nCheck whether p is a point on the PositiveNumbers M, i.e. p0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.check_vector-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.check_vector","text":"check_vector(M::PositiveNumbers, p, X; kwargs...)\n\nCheck whether X is a tangent vector in the tangent space of p on the PositiveNumbers M. For the real-valued case represented by positive numbers, all X are valid, since the tangent space is the whole real line. For the complex-valued case X [...]\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.distance-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.distance","text":"distance(M::PositiveNumbers, p, q)\n\nCompute the distance on the PositiveNumbers M, which is\n\nd(pq) = Bigllvert log fracpq Bigrrvert = lvert log p - log qrvert\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.get_coordinates-Tuple{PositiveNumbers, Any, Any, DefaultOrthonormalBasis{ℝ}}","page":"Positive numbers","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(::PositiveNumbers, p, X, ::DefaultOrthonormalBasis{ℝ})\n\nCompute the coordinate of vector X which is tangent to p on the PositiveNumbers manifold. The formula is X p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.get_vector-Tuple{PositiveNumbers, Any, Any, DefaultOrthonormalBasis{ℝ}}","page":"Positive numbers","title":"ManifoldsBase.get_vector","text":"get_vector(::PositiveNumbers, p, c, ::DefaultOrthonormalBasis{ℝ})\n\nCompute the vector with coordinate c which is tangent to p on the PositiveNumbers manifold. The formula is p * c.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.injectivity_radius-Tuple{PositiveNumbers}","page":"Positive numbers","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::PositiveNumbers[, p])\n\nReturn the injectivity radius on the PositiveNumbers M, i.e. infty.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.inner-Tuple{PositiveNumbers, Vararg{Any}}","page":"Positive numbers","title":"ManifoldsBase.inner","text":"inner(M::PositiveNumbers, p, X, Y)\n\nCompute the inner product of the two tangent vectors X,Y from the tangent plane at p on the PositiveNumbers M, i.e.\n\ng_p(XY) = fracXYp^2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.is_flat-Tuple{PositiveNumbers}","page":"Positive numbers","title":"ManifoldsBase.is_flat","text":"is_flat(::PositiveNumbers)\n\nReturn false. PositiveNumbers is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.manifold_dimension-Tuple{PositiveNumbers}","page":"Positive numbers","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::PositiveNumbers)\n\nReturn the dimension of the PositiveNumbers M, i.e. of the 1-dimensional hyperbolic space,\n\ndim(H^1) = 1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.parallel_transport_to-Tuple{PositiveNumbers, Any, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::PositiveNumbers, p, X, q)\n\nCompute the parallel transport of X from the tangent space at p to the tangent space at q on the PositiveNumbers M.\n\nmathcal P_qgets p(X) = Xcdotfracqp\n\n\n\n\n\n","category":"method"},{"location":"manifolds/positivenumbers.html#ManifoldsBase.project-Tuple{PositiveNumbers, Any, Any}","page":"Positive numbers","title":"ManifoldsBase.project","text":"project(M::PositiveNumbers, p, X)\n\nProject a value X onto the tangent space of the point p on the PositiveNumbers M, which is just the identity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Torus","page":"Torus","title":"Torus","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"The torus 𝕋^d -ππ)^d is modeled as an AbstractPowerManifold of the (real-valued) Circle and uses ArrayPowerRepresentation. Points on the torus are hence row vectors, x ℝ^d.","category":"page"},{"location":"manifolds/torus.html#Example","page":"Torus","title":"Example","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"The following code can be used to make a three-dimensional torus 𝕋^3 and compute a tangent vector:","category":"page"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"using Manifolds\nM = Torus(3)\np = [0.5, 0.0, 0.0]\nq = [0.0, 0.5, 1.0]\nX = log(M, p, q)","category":"page"},{"location":"manifolds/torus.html#Types-and-functions","page":"Torus","title":"Types and functions","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:","category":"page"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Modules = [Manifolds]\nPages = [\"manifolds/Torus.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/torus.html#Manifolds.Torus","page":"Torus","title":"Manifolds.Torus","text":"Torus{N} <: AbstractPowerManifold\n\nThe n-dimensional torus is the n-dimensional product of the Circle.\n\nThe Circle is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/torus.html#ManifoldsBase.check_point-Tuple{Torus, Any}","page":"Torus","title":"ManifoldsBase.check_point","text":"check_point(M::Torus{n},p)\n\nChecks whether p is a valid point on the Torus M, i.e. each of its entries is a valid point on the Circle and the length of x is n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.check_vector-Union{Tuple{N}, Tuple{Torus{N}, Any, Any}} where N","page":"Torus","title":"ManifoldsBase.check_vector","text":"check_vector(M::Torus{n}, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the Torus M. This means, that p is valid, that X is of correct dimension and elementwise a tangent vector to the elements of p on the Circle.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Embedded-Torus","page":"Torus","title":"Embedded Torus","text":"","category":"section"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Two-dimensional torus embedded in ℝ^3.","category":"page"},{"location":"manifolds/torus.html","page":"Torus","title":"Torus","text":"Modules = [Manifolds]\nPages = [\"manifolds/EmbeddedTorus.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/torus.html#Manifolds.DefaultTorusAtlas","page":"Torus","title":"Manifolds.DefaultTorusAtlas","text":"DefaultTorusAtlas()\n\nAtlas for torus with charts indexed by two angles numbers θ₀ φ₀ -π π). Inverse of a chart (θ₀ φ₀) is given by\n\nx(θ φ) = (R + rcos(θ + θ₀))cos(φ + φ₀) \ny(θ φ) = (R + rcos(θ + θ₀))sin(φ + φ₀) \nz(θ φ) = rsin(θ + θ₀)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/torus.html#Manifolds.EmbeddedTorus","page":"Torus","title":"Manifolds.EmbeddedTorus","text":"EmbeddedTorus{TR<:Real} <: AbstractDecoratorManifold{ℝ}\n\nSurface in ℝ³ described by parametric equations:\n\nx(θ φ) = (R + rcos θ)cos φ \ny(θ φ) = (R + rcos θ)sin φ \nz(θ φ) = rsin θ\n\nfor θ, φ in -π π). It is assumed that R r 0.\n\nAlternative names include anchor ring, donut and doughnut.\n\nConstructor\n\nEmbeddedTorus(R, r)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/torus.html#Manifolds.affine_connection-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Vararg{Any, 4}}","page":"Torus","title":"Manifolds.affine_connection","text":"affine_connection(M::EmbeddedTorus, A::DefaultTorusAtlas, i, a, Xc, Yc)\n\nAffine connection on EmbeddedTorus M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.check_chart_switch-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Any, Any}","page":"Torus","title":"Manifolds.check_chart_switch","text":"check_chart_switch(::EmbeddedTorus, A::DefaultTorusAtlas, i, a; ϵ = pi/3)\n\nReturn true if parameters a lie closer than ϵ to chart boundary.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.gaussian_curvature-Tuple{Manifolds.EmbeddedTorus, Any}","page":"Torus","title":"Manifolds.gaussian_curvature","text":"gaussian_curvature(M::EmbeddedTorus, p)\n\nGaussian curvature at point p from EmbeddedTorus M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.inverse_chart_injectivity_radius-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Any}","page":"Torus","title":"Manifolds.inverse_chart_injectivity_radius","text":"inverse_chart_injectivity_radius(M::AbstractManifold, A::AbstractAtlas, i)\n\nInjectivity radius of get_point for chart i from the DefaultTorusAtlas A of the EmbeddedTorus.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#Manifolds.normal_vector-Tuple{Manifolds.EmbeddedTorus, Any}","page":"Torus","title":"Manifolds.normal_vector","text":"normal_vector(M::EmbeddedTorus, p)\n\nOutward-pointing normal vector on the EmbeddedTorus at the point p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.check_point-Tuple{Manifolds.EmbeddedTorus, Any}","page":"Torus","title":"ManifoldsBase.check_point","text":"check_point(M::EmbeddedTorus, p; kwargs...)\n\nCheck whether p is a valid point on the EmbeddedTorus M. The tolerance for the last test can be set using the kwargs....\n\nThe method checks if (p_1^2 + p_2^2 + p_3^2 + R^2 - r^2)^2 is apprximately equal to 4R^2(p_1^2 + p_2^2).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.check_vector-Tuple{Manifolds.EmbeddedTorus, Any, Any}","page":"Torus","title":"ManifoldsBase.check_vector","text":"check_vector(M::EmbeddedTorus, p, X; atol=eps(eltype(p)), kwargs...)\n\nCheck whether X is a valid vector tangent to p on the EmbeddedTorus M. The method checks if the vector X is orthogonal to the vector normal to the torus, see normal_vector. Absolute tolerance can be set using atol.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.inner-Tuple{Manifolds.EmbeddedTorus, Manifolds.DefaultTorusAtlas, Vararg{Any, 4}}","page":"Torus","title":"ManifoldsBase.inner","text":"inner(M::EmbeddedTorus, ::DefaultTorusAtlas, i, a, Xc, Yc)\n\nInner product on EmbeddedTorus in chart i in the DefaultTorusAtlas. between vectors with coordinates Xc and Yc tangent at point with parameters a. Vector coordinates must be given in the induced basis.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.is_flat-Tuple{Manifolds.EmbeddedTorus}","page":"Torus","title":"ManifoldsBase.is_flat","text":"is_flat(::EmbeddedTorus)\n\nReturn false. EmbeddedTorus is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/torus.html#ManifoldsBase.manifold_dimension-Tuple{Manifolds.EmbeddedTorus}","page":"Torus","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::EmbeddedTorus)\n\nReturn the dimension of the EmbeddedTorus M that is 2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#The-probability-simplex","page":"Probability simplex","title":"The probability simplex","text":"","category":"section"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProbabilitySimplex.jl\"]\nOrder = [:type, :function]\nPrivate=false\nPublic=true","category":"page"},{"location":"manifolds/probabilitysimplex.html#Manifolds.FisherRaoMetric","page":"Probability simplex","title":"Manifolds.FisherRaoMetric","text":"FisherRaoMetric <: AbstractMetric\n\nThe Fisher-Rao metric or Fisher information metric is a particular Riemannian metric which can be defined on a smooth statistical manifold, i.e., a smooth manifold whose points are probability measures defined on a common probability space.\n\nSee for example the ProbabilitySimplex.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/probabilitysimplex.html#Manifolds.ProbabilitySimplex","page":"Probability simplex","title":"Manifolds.ProbabilitySimplex","text":"ProbabilitySimplex{n,boundary} <: AbstractDecoratorManifold{𝔽}\n\nThe (relative interior of) the probability simplex is the set\n\nΔ^n = biggl p ℝ^n+1 big p_i 0 text for all i=1n+1\ntext and mathbb1p = sum_i=1^n+1 p_i = 1biggr\n\nwhere mathbb1=(11)^mathrmT ℝ^n+1 denotes the vector containing only ones.\n\nIf boundary is set to :open, then the object represents an open simplex. Otherwise, that is when boundary is set to :closed, the boundary is also included:\n\nhatΔ^n = biggl p ℝ^n+1 big p_i geq 0 text for all i=1n+1\ntext and mathbb1p = sum_i=1^n+1 p_i = 1biggr\n\nThis set is also called the unit simplex or standard simplex.\n\nThe tangent space is given by\n\nT_pΔ^n = biggl X ℝ^n+1 big mathbb1X = sum_i=1^n+1 X_i = 0 biggr\n\nThe manifold is implemented assuming the Fisher-Rao metric for the multinomial distribution, which is equivalent to the induced metric from isometrically embedding the probability simplex in the n-sphere of radius 2. The corresponding diffeomorphism varphi mathbb Δ^n mathcal N, where mathcal N subset 2𝕊^n is given by varphi(p) = 2sqrtp.\n\nThis implementation follows the notation in [ÅströmPetraSchmitzerSchnörr2017].\n\nConstructor\n\nProbabilitySimplex(n::Int; boundary::Symbol=:open)\n\n[ÅströmPetraSchmitzerSchnörr2017]: F. Åström, S. Petra, B. Schmitzer, C. Schnörr: “Image Labeling by Assignment”, Journal of Mathematical Imaging and Vision, 58(2), pp. 221–238, 2017. doi: 10.1007/s10851-016-0702-4 arxiv: 1603.05285.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/probabilitysimplex.html#Base.exp-Tuple{ProbabilitySimplex, Vararg{Any}}","page":"Probability simplex","title":"Base.exp","text":"exp(M::ProbabilitySimplex, p, X)\n\nCompute the exponential map on the probability simplex.\n\nexp_pX = frac12Bigl(p+fracX_p^2lVert X_p rVert^2Bigr)\n+ frac12Bigl(p - fracX_p^2lVert X_p rVert^2Bigr)cos(lVert X_prVert)\n+ frac1lVert X_p rVertsqrtpsin(lVert X_prVert)\n\nwhere X_p = fracXsqrtp, with its division meant elementwise, as well as for the operations X_p^2 and sqrtp.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Base.log-Tuple{ProbabilitySimplex, Vararg{Any}}","page":"Probability simplex","title":"Base.log","text":"log(M::ProbabilitySimplex, p, q)\n\nCompute the logarithmic map of p and q on the ProbabilitySimplex M.\n\nlog_pq = fracd_Δ^n(pq)sqrt1-sqrtpsqrtq(sqrtpq - sqrtpsqrtqp)\n\nwhere pq and sqrtp is meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Base.rand-Tuple{ProbabilitySimplex}","page":"Probability simplex","title":"Base.rand","text":"rand(::ProbabilitySimplex; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (uniform over the Fisher-Rao metric; that is, uniform with respect to the n-sphere whose positive orthant is mapped to the simplex). point x on the ProbabilitySimplex manifold M according to the isometric embedding into the n-sphere by normalizing the vector length of a sample from a multivariate Gaussian. See [Marsaglia1972].\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_pmathrmDelta^nby shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.\n\n[Marsaglia1972]: Marsaglia, G.: Choosing a Point from the Surface of a Sphere. Annals of Mathematical Statistics, 43 (2): 645–646, 1972. doi: 10.1214/aoms/1177692644\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldDiff.riemannian_gradient-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldDiff.riemannian_gradient","text":"X = riemannian_gradient(M::ProbabilitySimplex{n}, p, Y)\nriemannian_gradient!(M::ProbabilitySimplex{n}, X, p, Y)\n\nGiven a gradient Y = operatornamegrad tilde f(p) in the embedding ℝ^n+1 of the ProbabilitySimplex Δ^n, this function computes the Riemannian gradient X = operatornamegrad f(p) where f is the function tilde f restricted to the manifold.\n\nThe formula reads\n\n X = p Y - p Yp\n\nwhere denotes the emelementwise product.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.manifold_volume-Union{Tuple{ProbabilitySimplex{n}}, Tuple{n}} where n","page":"Probability simplex","title":"Manifolds.manifold_volume","text":"manifold_volume(::ProbabilitySimplex{n}) where {n}\n\nReturn the volume of the ProbabilitySimplex, i.e. volume of the n-dimensional Sphere divided by 2^n+1, corresponding to the volume of its positive orthant.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.volume_density-Union{Tuple{N}, Tuple{ProbabilitySimplex{N}, Any, Any}} where N","page":"Probability simplex","title":"Manifolds.volume_density","text":"volume_density(M::ProbabilitySimplex{N}, p, X) where {N}\n\nCompute the volume density at point p on ProbabilitySimplex M for tangent vector X. It is computed using isometry with positive orthant of a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.change_metric-Tuple{ProbabilitySimplex, EuclideanMetric, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.change_metric","text":"change_metric(M::ProbabilitySimplex, ::EuclideanMetric, p, X)\n\nTo change the metric, we are looking for a function ccolon T_pΔ^n to T_pΔ^n such that for all XY T_pΔ^n This can be achieved by rewriting representer change in matrix form as (Diagonal(p) - p * p') * X and taking square root of the matrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.change_representer-Tuple{ProbabilitySimplex, EuclideanMetric, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.change_representer","text":"change_representer(M::ProbabilitySimplex, ::EuclideanMetric, p, X)\n\nGiven a tangent vector with respect to the metric from the embedding, the EuclideanMetric, the representer of a linear functional on the tangent space is adapted as Z = p * X - p * dot(p X). The first part “compensates” for the divsion by p in the Riemannian metric on the ProbabilitySimplex and the second part performs appropriate projection to keep the vector tangent.\n\nFor details see Proposition 2.3 in [ÅströmPetraSchmitzerSchnörr2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.check_point-Union{Tuple{boundary}, Tuple{n}, Tuple{ProbabilitySimplex{n, boundary}, Any}} where {n, boundary}","page":"Probability simplex","title":"ManifoldsBase.check_point","text":"check_point(M::ProbabilitySimplex, p; kwargs...)\n\nCheck whether p is a valid point on the ProbabilitySimplex M, i.e. is a point in the embedding with positive entries that sum to one The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.check_vector-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.check_vector","text":"check_vector(M::ProbabilitySimplex, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the ProbabilitySimplex M, i.e. after check_point(M,p), X has to be of same dimension as p and its elements have to sum to one. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.distance-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.distance","text":"distance(M, p, q)\n\nCompute the distance between two points on the ProbabilitySimplex M. The formula reads\n\nd_Δ^n(pq) = 2arccos biggl( sum_i=1^n+1 sqrtp_i q_i biggr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.injectivity_radius-Union{Tuple{n}, Tuple{ProbabilitySimplex{n}, Any}} where n","page":"Probability simplex","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M, p)\n\nCompute the injectivity radius on the ProbabilitySimplex M at the point p, i.e. the distanceradius to a point near/on the boundary, that could be reached by following the geodesic.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.inner-Union{Tuple{boundary}, Tuple{n}, Tuple{ProbabilitySimplex{n, boundary}, Any, Any, Any}} where {n, boundary}","page":"Probability simplex","title":"ManifoldsBase.inner","text":"inner(M::ProbabilitySimplex, p, X, Y)\n\nCompute the inner product of two tangent vectors X, Y from the tangent space T_pΔ^n at p. The formula reads\n\ng_p(XY) = sum_i=1^n+1fracX_iY_ip_i\n\nWhen M includes boundary, we can just skip coordinates where p_i is equal to 0, see Proposition 2.1 in [AyJostLeSchwachhöfer2017].\n\n[AyJostLeSchwachhöfer2017]: N. Ay, J. Jost, H. V. Le, and L. Schwachhöfer, Information Geometry. in Ergebnisse der Mathematik und ihrer Grenzgebiete. 3. Folge / A Series of Modern Surveys in Mathematics. Springer International Publishing, 2017. doi: 10.1007/978-3-319-56478-4\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.inverse_retract-Tuple{ProbabilitySimplex, Any, Any, SoftmaxInverseRetraction}","page":"Probability simplex","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::ProbabilitySimplex, p, q, ::SoftmaxInverseRetraction)\n\nCompute a first order approximation by projection. The formula reads\n\noperatornameretr^-1_p q = bigl( I_n+1 - frac1nmathbb1^n+1n+1 bigr)(log(q)-log(p))\n\nwhere mathbb1^mn is the size (m,n) matrix containing ones, and log is applied elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.is_flat-Tuple{ProbabilitySimplex}","page":"Probability simplex","title":"ManifoldsBase.is_flat","text":"is_flat(::ProbabilitySimplex)\n\nReturn false. ProbabilitySimplex is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.manifold_dimension-Union{Tuple{ProbabilitySimplex{n}}, Tuple{n}} where n","page":"Probability simplex","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::ProbabilitySimplex{n})\n\nReturns the manifold dimension of the probability simplex in ℝ^n+1, i.e.\n\n dim_Δ^n = n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.project-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"ManifoldsBase.project","text":"project(M::ProbabilitySimplex, p, Y)\n\nProject Y from the embedding onto the tangent space at p on the ProbabilitySimplex M. The formula reads\n\n`math \\operatorname{proj}_{Δ^n}(p,Y) = Y - \\bar{Y} where barY denotes mean of Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.project-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"ManifoldsBase.project","text":"project(M::ProbabilitySimplex, p)\n\nproject p from the embedding onto the ProbabilitySimplex M. The formula reads\n\noperatornameproj_Δ^n(p) = frac1mathbb 1pp\n\nwhere mathbb 1 ℝ denotes the vector of ones. Not that this projection is only well-defined if p has positive entries.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.representation_size-Union{Tuple{ProbabilitySimplex{n}}, Tuple{n}} where n","page":"Probability simplex","title":"ManifoldsBase.representation_size","text":"representation_size(::ProbabilitySimplex{n})\n\nReturn the representation size of points in the n-dimensional probability simplex, i.e. an array size of (n+1,).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.retract-Tuple{ProbabilitySimplex, Any, Any, SoftmaxRetraction}","page":"Probability simplex","title":"ManifoldsBase.retract","text":"retract(M::ProbabilitySimplex, p, X, ::SoftmaxRetraction)\n\nCompute a first order approximation by applying the softmax function. The formula reads\n\noperatornameretr_p X = fracpmathrme^Xpmathrme^X\n\nwhere multiplication, exponentiation and division are meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.riemann_tensor-Tuple{ProbabilitySimplex, Vararg{Any, 4}}","page":"Probability simplex","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::ProbabilitySimplex, p, X, Y, Z)\n\nCompute the Riemann tensor R(XY)Z at point p on ProbabilitySimplex M. It is computed using isometry with positive orthant of a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#ManifoldsBase.zero_vector-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::ProbabilitySimplex, p)\n\nReturn the zero tangent vector in the tangent space of the point p from the ProbabilitySimplex M, i.e. its representation by the zero vector in the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Statistics.mean-Tuple{ProbabilitySimplex, Vararg{Any}}","page":"Probability simplex","title":"Statistics.mean","text":"mean(\n M::ProbabilitySimplex,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolation();\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProbabilitySimplexEuclideanMetric.jl\"]\nOrder = [:type, :function]\nPrivate=false\nPublic=true","category":"page"},{"location":"manifolds/probabilitysimplex.html#Base.rand-Tuple{MetricManifold{ℝ, <:ProbabilitySimplex, <:EuclideanMetric}}","page":"Probability simplex","title":"Base.rand","text":"rand(::MetricManifold{ℝ,<:ProbabilitySimplex,<:EuclideanMetric}; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (uniform) point x on the ProbabilitySimplex with the Euclidean metric manifold M by normalizing independent exponential draws to unit sum, see [Devroye1986], Theorems 2.1 and 2.2 on p. 207 and 208, respectively.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_pmathrmDelta^nby shifting a multivariate Gaussian with standard deviation σ to have a zero component sum.\n\n[Devroye1986]: Devroye, L.: Non-Uniform Random Variate Generation. Springer New York, NY, 1986. doi: 10.1007/978-1-4613-8643-8\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.manifold_volume-Union{Tuple{MetricManifold{ℝ, <:ProbabilitySimplex{n}, <:EuclideanMetric}}, Tuple{n}} where n","page":"Probability simplex","title":"Manifolds.manifold_volume","text":"manifold_volume(::MetricManifold{ℝ,<:ProbabilitySimplex{n},<:EuclideanMetric})) where {n}\n\nReturn the volume of the ProbabilitySimplex with the Euclidean metric. The formula reads fracsqrtn+1n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.volume_density-Tuple{MetricManifold{ℝ, <:ProbabilitySimplex, <:EuclideanMetric}, Any, Any}","page":"Probability simplex","title":"Manifolds.volume_density","text":"volume_density(::MetricManifold{ℝ,<:ProbabilitySimplex,<:EuclideanMetric}, p, X)\n\nCompute the volume density at point p on ProbabilitySimplex M for tangent vector X. It is equal to 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Real-probability-amplitudes","page":"Probability simplex","title":"Real probability amplitudes","text":"","category":"section"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"An isometric embedding of interior of ProbabilitySimplex in positive orthant of the Sphere is established through functions simplex_to_amplitude and amplitude_to_simplex. Some properties extend to the boundary but not all.","category":"page"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"This embedding isometrically maps the Fisher-Rao metric on the open probability simplex to the sphere of radius 1 with Euclidean metric. More details can be found in Section 2.2 of [AyJostLeSchwachhöfer2017].","category":"page"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"The name derives from the notion of probability amplitudes in quantum mechanics. They are complex-valued and their squared norm corresponds to probability. This construction restricted to real valued amplitudes results in this embedding.","category":"page"},{"location":"manifolds/probabilitysimplex.html","page":"Probability simplex","title":"Probability simplex","text":"Modules = [Manifolds]\nPages = [\"manifolds/ProbabilitySimplex.jl\"]\nOrder = [:type, :function]\nPrivate=true\nPublic=false","category":"page"},{"location":"manifolds/probabilitysimplex.html#Manifolds.amplitude_to_simplex-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"Manifolds.amplitude_to_simplex","text":"amplitude_to_simplex(M::ProbabilitySimplex{N}, p) where {N}\n\nConvert point (real) probability amplitude p on to a point on ProbabilitySimplex. The formula reads (p_1^2 p_2^2 p_N+1^2). This is an isometry from the interior of the positive orthant of a sphere to interior of the probability simplex.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.amplitude_to_simplex_diff-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"Manifolds.amplitude_to_simplex_diff","text":"amplitude_to_simplex_diff(M::ProbabilitySimplex, p, X)\n\nCompute differential of amplitude_to_simplex of a point p on ProbabilitySimplex at tangent vector X from the tangent space at p from a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.simplex_to_amplitude-Tuple{ProbabilitySimplex, Any}","page":"Probability simplex","title":"Manifolds.simplex_to_amplitude","text":"simplex_to_amplitude(M::ProbabilitySimplex, p)\n\nConvert point p on ProbabilitySimplex to (real) probability amplitude. The formula reads (sqrtp_1 sqrtp_2 sqrtp_N+1). This is an isometry from the interior of the probability simplex to the interior of the positive orthant of a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Manifolds.simplex_to_amplitude_diff-Tuple{ProbabilitySimplex, Any, Any}","page":"Probability simplex","title":"Manifolds.simplex_to_amplitude_diff","text":"simplex_to_amplitude_diff(M::ProbabilitySimplex, p, X)\n\nCompute differential of simplex_to_amplitude of a point on p one ProbabilitySimplex at tangent vector X from the tangent space at p from a sphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/probabilitysimplex.html#Literature","page":"Probability simplex","title":"Literature","text":"","category":"section"},{"location":"manifolds/generalizedstiefel.html#Generalized-Stiefel","page":"Generalized Stiefel","title":"Generalized Stiefel","text":"","category":"section"},{"location":"manifolds/generalizedstiefel.html","page":"Generalized Stiefel","title":"Generalized Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/GeneralizedStiefel.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/generalizedstiefel.html#Manifolds.GeneralizedStiefel","page":"Generalized Stiefel","title":"Manifolds.GeneralizedStiefel","text":"GeneralizedStiefel{n,k,𝔽,B} <: AbstractDecoratorManifold{𝔽}\n\nThe Generalized Stiefel manifold consists of all ntimes k, ngeq k orthonormal matrices w.r.t. an arbitrary scalar product with symmetric positive definite matrix Bin R^n n, i.e.\n\noperatornameSt(nkB) = bigl p in mathbb F^n k big p^mathrmH B p = I_k bigr\n\nwhere 𝔽 ℝ ℂ, cdot^mathrmH denotes the complex conjugate transpose or Hermitian, and I_k in mathbb R^k k denotes the k k identity matrix.\n\nIn the case B=I_k one gets the usual Stiefel manifold.\n\nThe tangent space at a point pinmathcal M=operatornameSt(nkB) is given by\n\nT_pmathcal M = X in 𝔽^n k p^mathrmHBX + X^mathrmHBp=0_n\n\nwhere 0_k is the k k zero matrix.\n\nThis manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the zero_vector are inherited from the embedding.\n\nThe manifold is named after Eduard L. Stiefel (1909–1978).\n\nConstructor\n\nGeneralizedStiefel(n, k, B=I_n, F=ℝ)\n\nGenerate the (real-valued) Generalized Stiefel manifold of ntimes k dimensional orthonormal matrices with scalar product B.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalizedstiefel.html#Base.rand-Tuple{GeneralizedStiefel}","page":"Generalized Stiefel","title":"Base.rand","text":"rand(::GeneralizedStiefel; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (Gaussian) point p on the GeneralizedStiefel manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size nk.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_vector_atmathrmSt(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedStiefel{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Generalized Stiefel","title":"ManifoldsBase.check_point","text":"check_point(M::GeneralizedStiefel, p; kwargs...)\n\nCheck whether p is a valid point on the GeneralizedStiefel M=operatornameSt(nkB), i.e. that it has the right AbstractNumbers type and x^mathrmHBx is (approximately) the identity, where cdot^mathrmH is the complex conjugate transpose. The settings for approximately can be set with kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedStiefel{n, k, 𝔽}, Any, Any}} where {n, k, 𝔽}","page":"Generalized Stiefel","title":"ManifoldsBase.check_vector","text":"check_vector(M::GeneralizedStiefel, p, X; kwargs...)\n\nCheck whether X is a valid tangent vector at p on the GeneralizedStiefel M=operatornameSt(nkB), i.e. the AbstractNumbers fits, p is a valid point on M and it (approximately) holds that p^mathrmHBX + overlineX^mathrmHBp = 0, where kwargs... is passed to the isapprox.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.inner-Tuple{GeneralizedStiefel, Any, Any, Any}","page":"Generalized Stiefel","title":"ManifoldsBase.inner","text":"inner(M::GeneralizedStiefel, p, X, Y)\n\nCompute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedStiefel manifold M. The formula reads\n\n(X Y)_p = operatornametrace(v^mathrmHBw)\n\ni.e. the metric induced by the scalar product B from the embedding, restricted to the tangent space.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.is_flat-Tuple{GeneralizedStiefel}","page":"Generalized Stiefel","title":"ManifoldsBase.is_flat","text":"is_flat(M::GeneralizedStiefel)\n\nReturn true if GeneralizedStiefel M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.manifold_dimension-Union{Tuple{GeneralizedStiefel{n, k, ℝ}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Generalized Stiefel","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::GeneralizedStiefel)\n\nReturn the dimension of the GeneralizedStiefel manifold M=operatornameSt(nkB𝔽). The dimension is given by\n\nbeginaligned\ndim mathrmSt(n k B ℝ) = nk - frac12k(k+1) \ndim mathrmSt(n k B ℂ) = 2nk - k^2\ndim mathrmSt(n k B ℍ) = 4nk - k(2k-1)\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.project-Tuple{GeneralizedStiefel, Any, Any}","page":"Generalized Stiefel","title":"ManifoldsBase.project","text":"project(M:GeneralizedStiefel, p, X)\n\nProject X onto the tangent space of p to the GeneralizedStiefel manifold M. The formula reads\n\noperatornameproj_operatornameSt(nk)(pX) = X - poperatornameSym(p^mathrmHBX)\n\nwhere operatornameSym(y) is the symmetrization of y, e.g. by operatornameSym(y) = fracy^mathrmH+y2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.project-Tuple{GeneralizedStiefel, Any}","page":"Generalized Stiefel","title":"ManifoldsBase.project","text":"project(M::GeneralizedStiefel,p)\n\nProject p from the embedding onto the GeneralizedStiefel M, i.e. compute q as the polar decomposition of p such that q^mathrmHBq is the identity, where cdot^mathrmH denotes the hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedstiefel.html#ManifoldsBase.retract-Tuple{GeneralizedStiefel, Vararg{Any}}","page":"Generalized Stiefel","title":"ManifoldsBase.retract","text":"retract(M::GeneralizedStiefel, p, X)\nretract(M::GeneralizedStiefel, p, X, ::PolarRetraction)\nretract(M::GeneralizedStiefel, p, X, ::ProjectionRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the GeneralizedStiefel manifold M, which in this case is the same as the projection based retraction employing the exponential map in the embedding and projecting the result back to the manifold.\n\nThe default retraction for this manifold is the ProjectionRetraction.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Symplectic-Stiefel","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"","category":"section"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"The SymplecticStiefel manifold, denoted operatornameSpSt(2n 2k), represents canonical symplectic bases of 2k dimensonal symplectic subspaces of mathbbR^2n times 2n. This means that the columns of each element p in operatornameSpSt(2n 2k) subset mathbbR^2n times 2k constitute a canonical symplectic basis of operatornamespan(p). The canonical symplectic form is a non-degenerate, bilinear, and skew symmetric map omega_2kcolon mathbbF^2k times mathbbF^2k rightarrow mathbbF, given by omega_2k(x y) = x^T Q_2k y for elements x y in mathbbF^2k, with","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":" Q_2k = \n beginbmatrix\n 0_k I_k \n -I_k 0_k\n endbmatrix","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"Specifically given an element p in operatornameSpSt(2n 2k) we require that","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":" omega_2n (p x p y) = x^T(p^TQ_2np)y = x^TQ_2ky = omega_2k(x y) forall x y in mathbbF^2k","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"leading to the requirement on p that p^TQ_2np = Q_2k. In the case that k = n, this manifold reduces to the Symplectic manifold, which is also known as the symplectic group.","category":"page"},{"location":"manifolds/symplecticstiefel.html","page":"Symplectic Stiefel","title":"Symplectic Stiefel","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymplecticStiefel.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symplecticstiefel.html#Manifolds.SymplecticStiefel","page":"Symplectic Stiefel","title":"Manifolds.SymplecticStiefel","text":"SymplecticStiefel{n, k, 𝔽} <: AbstractEmbeddedManifold{𝔽, DefaultIsometricEmbeddingType}\n\nThe symplectic Stiefel manifold consists of all 2n 2k n geq k matrices satisfying the requirement\n\noperatornameSpSt(2n 2k ℝ)\n = bigl p ℝ^2n 2n big p^mathrmTQ_2np = Q_2k bigr\n\nwhere\n\nQ_2n =\nbeginbmatrix\n 0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe symplectic Stiefel tangent space at p can be parametrized as [BendokatZimmermann2021]\n\n beginalign*\n T_poperatornameSpSt(2n 2k)\n = X in mathbbR^2n times 2k p^TQ_2nX + X^TQ_2np = 0 \n = X = pΩ + p^sB \n Ω ℝ^2k 2k Ω^+ = -Ω \n p^s operatornameSpSt(2n 2(n- k)) B ℝ^2(n-k) 2k \n endalign*\n\nwhere Ω in mathfraksp(2nF) is Hamiltonian and p^s means the symplectic complement of p s.t. p^+p^s = 0.\n\nConstructor\n\nSymplecticStiefel(2n::Int, 2k::Int, field::AbstractNumbers=ℝ)\n -> SymplecticStiefel{div(2n, 2), div(2k, 2), field}()\n\nGenerate the (real-valued) symplectic Stiefel manifold of 2n times 2k matrices which span a 2k dimensional symplectic subspace of ℝ^2n times 2n. The constructor for the SymplecticStiefel manifold accepts the even column dimension 2n and an even number of columns 2k for the real symplectic Stiefel manifold with elements p in ℝ^2n 2k.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplecticstiefel.html#Base.exp-Tuple{SymplecticStiefel, Any, Any}","page":"Symplectic Stiefel","title":"Base.exp","text":"exp(::SymplecticStiefel, p, X)\nexp!(M::SymplecticStiefel, q, p, X)\n\nCompute the exponential mapping\n\n operatornameexpcolon ToperatornameSpSt(2n 2k)\n rightarrow operatornameSpSt(2n 2k)\n\nat a point p in operatornameSpSt(2n 2k) in the direction of X in T_poperatornameSpSt(2n 2k).\n\nThe tangent vector X can be written in the form X = barOmegap [BendokatZimmermann2021], with\n\n barOmega = X (p^mathrmTp)^-1p^mathrmT\n + Q_2np(p^mathrmTp)^-1X^mathrmT(I_2n - Q_2n^mathrmTp(p^mathrmTp)^-1p^mathrmTQ_2n)Q_2n\n in ℝ^2n times 2n\n\nwhere Q_2n is the SymplecticMatrix. Using this expression for X, the exponential mapping can be computed as\n\n operatornameexp_p(X) = operatornameExp(barOmega - barOmega^mathrmT)\n operatornameExp(barOmega^mathrmT)p\n\nwhere operatornameExp(cdot) denotes the matrix exponential.\n\nComputing the above mapping directly however, requires taking matrix exponentials of two 2n times 2n matrices, which is computationally expensive when n increases. Therefore we instead follow [BendokatZimmermann2021] who express the above exponential mapping in a way which only requires taking matrix exponentials of an 8k times 8k matrix and a 4k times 4k matrix.\n\nTo this end, first define\n\nbarA = Q_2kp^mathrmTX(p^mathrmTp)^-1Q_2k +\n (p^mathrmTp)^-1X^mathrmT(p - Q_2n^mathrmTp(p^mathrmTp)^-1Q_2k) in ℝ^2k times 2k\n\nand\n\nbarH = (I_2n - pp^+)Q_2nX(p^mathrmTp)^-1Q_2k in ℝ^2n times 2k\n\nWe then let barDelta = pbarA + barH, and define the matrices\n\n γ = leftleft(I_2n - frac12pp^+right)barDelta quad\n -p right in ℝ^2n times 4k\n\nand\n\n λ = leftQ_2n^mathrmTpQ_2k quad\n left(barDelta^+left(I_2n\n - frac12pp^+right)right)^mathrmTright in ℝ^2n times 4k\n\nWith the above defined matrices it holds that barOmega = λγ^mathrmT. As a last preliminary step, concatenate γ and λ to define the matrices Γ = λ quad -γ in ℝ^2n times 8k and Λ = γ quad λ in ℝ^2n times 8k.\n\nWith these matrix constructions done, we can compute the exponential mapping as\n\n operatornameexp_p(X) =\n Γ operatornameExp(ΛΓ^mathrmT)\n beginbmatrix\n 0_4k \n I_4k\n endbmatrix\n operatornameExp(λγ^mathrmT)\n beginbmatrix\n 0_2k \n I_2k\n endbmatrix\n\nwhich only requires computing the matrix exponentials of ΛΓ^mathrmT in ℝ^8k times 8k and λγ^mathrmT in ℝ^4k times 4k.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Base.inv-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any}} where {n, k}","page":"Symplectic Stiefel","title":"Base.inv","text":"inv(::SymplecticStiefel{n, k}, A)\ninv!(::SymplecticStiefel{n, k}, q, p)\n\nCompute the symplectic inverse A^+ of matrix A ℝ^2n 2k. Given a matrix\n\nA ℝ^2n 2kquad\nA =\nbeginbmatrix\nA_1 1 A_1 2 \nA_2 1 A_2 2\nendbmatrix A_i j in ℝ^2n 2k\n\nthe symplectic inverse is defined as:\n\nA^+ = Q_2k^mathrmT A^mathrmT Q_2n\n\nwhere\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nFor any p in operatornameSpSt(2n 2k) we have that p^+p = I_2k.\n\nThe symplectic inverse of a matrix A can be expressed explicitly as:\n\nA^+ =\nbeginbmatrix\n A_2 2^mathrmT -A_1 2^mathrmT 12mm\n -A_2 1^mathrmT A_1 1^mathrmT\nendbmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Base.rand-Union{Tuple{SymplecticStiefel{n}}, Tuple{n}} where n","page":"Symplectic Stiefel","title":"Base.rand","text":"rand(M::SymplecticStiefel; vector_at=nothing,\n hamiltonian_norm=(vector_at === nothing ? 1/2 : 1.0))\n\nGenerate a random point p in operatornameSpSt(2n 2k) or a random tangent vector X in T_poperatornameSpSt(2n 2k) if vector_at is set to a point p in operatornameSp(2n).\n\nA random point on operatornameSpSt(2n 2k) is found by first generating a random point on the symplectic manifold operatornameSp(2n), and then projecting onto the Symplectic Stiefel manifold using the canonical_project π_operatornameSpSt(2n 2k). That is, p = π_operatornameSpSt(2n 2k)(p_operatornameSp).\n\nTo generate a random tangent vector in T_poperatornameSpSt(2n 2k) this code exploits the second tangent vector space parametrization of SymplecticStiefel, showing that any X in T_poperatornameSpSt(2n 2k) can be written as X = pΩ_X + p^sB_X. To generate random tangent vectors at p then, this function sets B_X = 0 and generates a random Hamiltonian matrix Ω_X in mathfraksp(2nF) with Frobenius norm of hamiltonian_norm before returning X = pΩ_X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldDiff.riemannian_gradient-Tuple{SymplecticStiefel, Any, Any}","page":"Symplectic Stiefel","title":"ManifoldDiff.riemannian_gradient","text":"X = riemannian_gradient(::SymplecticStiefel, f, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())\nriemannian_gradient!(::SymplecticStiefel, f, X, p, Y; embedding_metric::EuclideanMetric=EuclideanMetric())\n\nCompute the riemannian gradient X of f on SymplecticStiefel at a point p, provided that the gradient of the function tilde f, which is f continued into the embedding is given by Y. The metric in the embedding is the Euclidean metric.\n\nThe manifold gradient X is computed from Y as\n\n X = Yp^mathrmTp + Q_2npY^mathrmTQ_2np\n\nwhere Q_2n is the SymplecticMatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Manifolds.canonical_project-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any}} where {n, k}","page":"Symplectic Stiefel","title":"Manifolds.canonical_project","text":"canonical_project(::SymplecticStiefel, p_Sp)\ncanonical_project!(::SymplecticStiefel{n,k}, p, p_Sp)\n\nDefine the canonical projection from operatornameSp(2n 2n) onto operatornameSpSt(2n 2k), by projecting onto the first k columns and the n + 1'th onto the n + k'th columns [BendokatZimmermann2021].\n\nIt is assumed that the point p is on operatornameSp(2n 2n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Manifolds.get_total_space-Union{Tuple{SymplecticStiefel{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Symplectic Stiefel","title":"Manifolds.get_total_space","text":"get_total_space(::SymplecticStiefel)\n\nReturn the total space of the SymplecticStiefel manifold, which is the corresponding Symplectic manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Manifolds.symplectic_inverse_times-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any, Any}} where {n, k}","page":"Symplectic Stiefel","title":"Manifolds.symplectic_inverse_times","text":"symplectic_inverse_times(::SymplecticStiefel, p, q)\nsymplectic_inverse_times!(::SymplecticStiefel, A, p, q)\n\nDirectly compute the symplectic inverse of p in operatornameSpSt(2n 2k), multiplied with q in operatornameSpSt(2n 2k). That is, this function efficiently computes p^+q = (Q_2kp^mathrmTQ_2n)q in ℝ^2k times 2k, where Q_2n Q_2k are the SymplecticMatrix of sizes 2n times 2n and 2k times 2k respectively.\n\nThis function performs this common operation without allocating more than a 2k times 2k matrix to store the result in, or in the case of the in-place function, without allocating memory at all.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.check_point-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any}} where {n, k}","page":"Symplectic Stiefel","title":"ManifoldsBase.check_point","text":"check_point(M::SymplecticStiefel, p; kwargs...)\n\nCheck whether p is a valid point on the SymplecticStiefel, operatornameSpSt(2n 2k) manifold. That is, the point has the right AbstractNumbers type and p^+p is (approximately) the identity, where for A in mathbbR^2n times 2k, A^+ = Q_2k^mathrmTA^mathrmTQ_2n is the symplectic inverse, with\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.check_vector-Tuple{SymplecticStiefel, Vararg{Any}}","page":"Symplectic Stiefel","title":"ManifoldsBase.check_vector","text":"check_vector(M::Symplectic, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector at p on the SymplecticStiefel, operatornameSpSt(2n 2k) manifold. First recall the definition of the symplectic inverse for A in mathbbR^2n times 2k, A^+ = Q_2k^mathrmTA^mathrmTQ_2n is the symplectic inverse, with\n\n Q_2n =\n beginbmatrix\n 0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe we check that H = p^+X in 𝔤_2k, where 𝔤 is the Lie Algebra of the symplectic group operatornameSp(2k), characterized as [BendokatZimmermann2021],\n\n 𝔤_2k = H in ℝ^2k times 2k H^+ = -H \n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{SymplecticStiefel{n, k}, Any, Any, Any}} where {n, k}","page":"Symplectic Stiefel","title":"ManifoldsBase.inner","text":"inner(M::SymplecticStiefel{n, k}, p, X. Y)\n\nCompute the Riemannian inner product g^operatornameSpSt at p in operatornameSpSt between tangent vectors X X in T_poperatornameSpSt. Given by Proposition 3.10 in [BendokatZimmermann2021].\n\ng^operatornameSpSt_p(X Y)\n = operatornametrleft(X^mathrmTleft(I_2n -\n frac12Q_2n^mathrmTp(p^mathrmTp)^-1p^mathrmTQ_2nright)Y(p^mathrmTp)^-1right)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.inverse_retract-Tuple{SymplecticStiefel, Any, Any, CayleyInverseRetraction}","page":"Symplectic Stiefel","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(::SymplecticStiefel, p, q, ::CayleyInverseRetraction)\ninverse_retract!(::SymplecticStiefel, q, p, X, ::CayleyInverseRetraction)\n\nCompute the Cayley Inverse Retraction X = mathcalL_p^operatornameSpSt(q) such that the Cayley Retraction from p along X lands at q, i.e. mathcalR_p(X) = q [BendokatZimmermann2021].\n\nFirst, recall the definition the standard symplectic matrix\n\nQ =\nbeginbmatrix\n 0 I \n-I 0\nendbmatrix\n\nas well as the symplectic inverse of a matrix A, A^+ = Q^mathrmT A^mathrmT Q.\n\nFor p q operatornameSpSt(2n 2k ℝ) then, we can define the inverse cayley retraction as long as the following matrices exist.\n\n U = (I + p^+ q)^-1 in ℝ^2k times 2k\n quad\n V = (I + q^+ p)^-1 in ℝ^2k times 2k\n\nIf that is the case, the inverse cayley retration at p applied to q is\n\nmathcalL_p^operatornameSp(q) = 2pbigl(V - Ubigr) + 2bigl((p + q)U - pbigr)\n T_poperatornameSp(2n)\n\n[BendokatZimmermann2021]: Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.is_flat-Tuple{SymplecticStiefel}","page":"Symplectic Stiefel","title":"ManifoldsBase.is_flat","text":"is_flat(::SymplecticStiefel)\n\nReturn false. SymplecticStiefel is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.manifold_dimension-Union{Tuple{SymplecticStiefel{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Symplectic Stiefel","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(::SymplecticStiefel{n, k})\n\nReturns the dimension of the symplectic Stiefel manifold embedded in ℝ^2n times 2k, i.e. [BendokatZimmermann2021]\n\n operatornamedim(operatornameSpSt(2n 2k)) = (4n - 2k + 1)k\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.project-Tuple{SymplecticStiefel, Any, Any}","page":"Symplectic Stiefel","title":"ManifoldsBase.project","text":"project(::SymplecticStiefel, p, A)\nproject!(::SymplecticStiefel, Y, p, A)\n\nGiven a point p in operatornameSpSt(2n 2k), project an element A in mathbbR^2n times 2k onto the tangent space T_poperatornameSpSt(2n 2k) relative to the euclidean metric of the embedding mathbbR^2n times 2k.\n\nThat is, we find the element X in T_poperatornameSpSt(2n 2k) which solves the constrained optimization problem\n\n operatornamemin_X in mathbbR^2n times 2k frac12X - A^2 quad\n textst\n h(X)colon= X^mathrmT Q p + p^mathrmT Q X = 0\n\nwhere h mathbbR^2n times 2k rightarrow operatornameskew(2k) defines the restriction of X onto the tangent space T_poperatornameSpSt(2n 2k).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#ManifoldsBase.retract-Tuple{SymplecticStiefel, Any, Any, CayleyRetraction}","page":"Symplectic Stiefel","title":"ManifoldsBase.retract","text":"retract(::SymplecticStiefel, p, X, ::CayleyRetraction)\nretract!(::SymplecticStiefel, q, p, X, ::CayleyRetraction)\n\nCompute the Cayley retraction on the Symplectic Stiefel manifold, computed inplace of q from p along X.\n\nGiven a point p in operatornameSpSt(2n 2k), every tangent vector X in T_poperatornameSpSt(2n 2k) is of the form X = tildeOmegap, with\n\n tildeOmega = left(I_2n - frac12pp^+right)Xp^+ -\n pX^+left(I_2n - frac12pp^+right) in ℝ^2n times 2n\n\nas shown in Proposition 3.5 of [BendokatZimmermann2021]. Using this representation of X, the Cayley retraction on operatornameSpSt(2n 2k) is defined pointwise as\n\n mathcalR_p(X) = operatornamecayleft(frac12tildeOmegaright)p\n\nThe operator operatornamecay(A) = (I - A)^-1(I + A) is the Cayley transform.\n\nHowever, the computation of an 2n times 2n matrix inverse in the expression above can be reduced down to inverting a 2k times 2k matrix due to Proposition 5.2 of [BendokatZimmermann2021].\n\nLet A = p^+X and H = X - pA. Then an equivalent expression for the Cayley retraction defined pointwise above is\n\n mathcalR_p(X) = -p + (H + 2p)(H^+H4 - A2 + I_2k)^-1\n\nIt is this expression we compute inplace of q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplecticstiefel.html#Literature","page":"Symplectic Stiefel","title":"Literature","text":"","category":"section"},{"location":"manifolds/connection.html#ConnectionSection","page":"Connection manifold","title":"Connection manifold","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"A connection manifold always consists of a topological manifold together with a connection Gamma.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"However, often there is an implicitly assumed (default) connection, like the LeviCivitaConnection connection on a Riemannian manifold. It is not necessary to use this decorator if you implement just one (or the first) connection. If you later introduce a second, the old (first) connection can be used without an explicitly stated connection.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"This manifold decorator serves two purposes:","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"to implement different connections (e.g. in closed form) for one AbstractManifold\nto provide a way to compute geodesics on manifolds, where this AbstractAffineConnection does not yield a closed formula.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"An example of usage can be found in Cartan-Schouten connections, see AbstractCartanSchoutenConnection.","category":"page"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"Pages = [\"connection.md\"]\nDepth = 2","category":"page"},{"location":"manifolds/connection.html#Types","page":"Connection manifold","title":"Types","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/ConnectionManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/connection.html#Manifolds.AbstractAffineConnection","page":"Connection manifold","title":"Manifolds.AbstractAffineConnection","text":"AbstractAffineConnection\n\nAbstract type for affine connections on a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.ConnectionManifold","page":"Connection manifold","title":"Manifolds.ConnectionManifold","text":"ConnectionManifold{𝔽,,M<:AbstractManifold{𝔽},G<:AbstractAffineConnection} <: AbstractDecoratorManifold{𝔽}\n\nConstructor\n\nConnectionManifold(M, C)\n\nDecorate the AbstractManifold M with AbstractAffineConnection C.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.IsConnectionManifold","page":"Connection manifold","title":"Manifolds.IsConnectionManifold","text":"IsConnectionManifold <: AbstractTrait\n\nSpecify that a certain decorated Manifold is a connection manifold in the sence that it provides explicit connection properties, extending/changing the default connection properties of a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.IsDefaultConnection","page":"Connection manifold","title":"Manifolds.IsDefaultConnection","text":"IsDefaultConnection{G<:AbstractAffineConnection}\n\nSpecify that a certain AbstractAffineConnection is the default connection for a manifold. This way the corresponding ConnectionManifold falls back to the default methods of the manifold it decorates.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Manifolds.LeviCivitaConnection","page":"Connection manifold","title":"Manifolds.LeviCivitaConnection","text":"LeviCivitaConnection\n\nThe Levi-Civita connection of a Riemannian manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/connection.html#Functions","page":"Connection manifold","title":"Functions","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/ConnectionManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/connection.html#Base.exp-Tuple{ManifoldsBase.TraitList{IsConnectionManifold}, AbstractDecoratorManifold, Any, Any}","page":"Connection manifold","title":"Base.exp","text":"exp(::TraitList{IsConnectionManifold}, M::AbstractDecoratorManifold, p, X)\n\nCompute the exponential map on a manifold that IsConnectionManifold M equipped with corresponding affine connection.\n\nIf M is a MetricManifold with a IsDefaultMetric trait, this method falls back to exp(M, p, X).\n\nOtherwise it numerically integrates the underlying ODE, see solve_exp_ode. Currently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.christoffel_symbols_first-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.christoffel_symbols_first","text":"christoffel_symbols_first(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n)\n\nCompute the Christoffel symbols of the first kind in local coordinates of basis B. The Christoffel symbols are (in Einstein summation convention)\n\nΓ_ijk = frac12 Biglg_kji + g_ikj - g_ijkBigr\n\nwhere g_ijk=frac p^k g_ij is the coordinate derivative of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered (ijk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.christoffel_symbols_second-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.christoffel_symbols_second","text":"christoffel_symbols_second(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n)\n\nCompute the Christoffel symbols of the second kind in local coordinates of basis B. For affine connection manifold the Christoffel symbols need to be explicitly implemented while, for a MetricManifold they are computed as (in Einstein summation convention)\n\nΓ^l_ij = g^kl Γ_ijk\n\nwhere Γ_ijk are the Christoffel symbols of the first kind (see christoffel_symbols_first), and g^kl is the inverse of the local representation of the metric tensor. The dimensions of the resulting multi-dimensional array are ordered (lij).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.christoffel_symbols_second_jacobian-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.christoffel_symbols_second_jacobian","text":"christoffel_symbols_second_jacobian(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n)\n\nGet partial derivatives of the Christoffel symbols of the second kind for manifold M at p with respect to the coordinates of B, i.e.\n\nfrac p^l Γ^k_ij = Γ^k_ijl\n\nThe dimensions of the resulting multi-dimensional array are ordered (ijkl).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.connection-Tuple{AbstractManifold}","page":"Connection manifold","title":"Manifolds.connection","text":"connection(M::AbstractManifold)\n\nGet the connection (an object of a subtype of AbstractAffineConnection) of AbstractManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.connection-Tuple{ConnectionManifold}","page":"Connection manifold","title":"Manifolds.connection","text":"connection(M::ConnectionManifold)\n\nReturn the connection associated with ConnectionManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.gaussian_curvature-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.gaussian_curvature","text":"gaussian_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())\n\nCompute the Gaussian curvature of the manifold M at the point p using basis B. This is equal to half of the scalar Ricci curvature, see ricci_curvature.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.is_default_connection-Tuple{AbstractManifold, AbstractAffineConnection}","page":"Connection manifold","title":"Manifolds.is_default_connection","text":"is_default_connection(M::AbstractManifold, G::AbstractAffineConnection)\n\nreturns whether an AbstractAffineConnection is the default metric on the manifold M or not. This can be set by defining this function, or setting the IsDefaultConnection trait for an AbstractDecoratorManifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.ricci_tensor-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"Manifolds.ricci_tensor","text":"ricci_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())\n\nCompute the Ricci tensor, also known as the Ricci curvature tensor, of the manifold M at the point p using basis B, see https://en.wikipedia.org/wiki/Ricci_curvature#Introduction_and_local_definition.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#Manifolds.solve_exp_ode-Tuple{AbstractManifold, Any, Any, Number}","page":"Connection manifold","title":"Manifolds.solve_exp_ode","text":"solve_exp_ode(\n M::AbstractConnectionManifold,\n p,\n X,\n t::Number,\n B::AbstractBasis;\n backend::AbstractDiffBackend = default_differential_backend(),\n solver = AutoVern9(Rodas5()),\n kwargs...,\n)\n\nApproximate the exponential map on the manifold by evaluating the ODE descripting the geodesic at 1, assuming the default connection of the given manifold by solving the ordinary differential equation\n\nfracd^2dt^2 p^k + Γ^k_ij fracddt p_i fracddt p_j = 0\n\nwhere Γ^k_ij are the Christoffel symbols of the second kind, and the Einstein summation convention is assumed. The argument solver follows the OrdinaryDiffEq conventions. kwargs... specify keyword arguments that will be passed to OrdinaryDiffEq.solve.\n\nCurrently, the numerical integration is only accurate when using a single coordinate chart that covers the entire manifold. This excludes coordinates in an embedded space.\n\nnote: Note\nThis function only works when OrdinaryDiffEq.jl is loaded withusing OrdinaryDiffEq\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#ManifoldsBase.riemann_tensor-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Connection manifold","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend=default_differential_backend())\n\nCompute the Riemann tensor R^l_ijk, also known as the Riemann curvature tensor, at the point p in local coordinates defined by B. The dimensions of the resulting multi-dimensional array are ordered (lijk).\n\nThe function uses the coordinate expression involving the second Christoffel symbol, see https://en.wikipedia.org/wiki/Riemann_curvature_tensor#Coordinate_expression for details.\n\nSee also\n\nchristoffel_symbols_second, christoffel_symbols_second_jacobian\n\n\n\n\n\n","category":"method"},{"location":"manifolds/connection.html#connections_charts","page":"Connection manifold","title":"Charts and bases of vector spaces","text":"","category":"section"},{"location":"manifolds/connection.html","page":"Connection manifold","title":"Connection manifold","text":"All connection-related functions take a basis of a vector space as one of the arguments. This is needed because generally there is no way to define these functions without referencing a basis. In some cases there is no need to be explicit about this basis, and then for example a DefaultOrthonormalBasis object can be used. In cases where being explicit about these bases is needed, for example when using multiple charts, a basis can be specified, for example using induced_basis.","category":"page"},{"location":"index.html#Manifolds","page":"Home","title":"Manifolds","text":"","category":"section"},{"location":"index.html","page":"Home","title":"Home","text":"Manifolds.Manifolds","category":"page"},{"location":"index.html#Manifolds.Manifolds","page":"Home","title":"Manifolds.Manifolds","text":"Manifolds.jl provides a library of manifolds aiming for an easy-to-use and fast implementation.\n\n\n\n\n\n","category":"module"},{"location":"index.html","page":"Home","title":"Home","text":"The implemented manifolds are accompanied by their mathematical formulae.","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"The manifolds are implemented using the interface for manifolds given in ManifoldsBase.jl. You can use that interface to implement your own software on manifolds, such that all manifolds based on that interface can be used within your code.","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"For more information, see the About section.","category":"page"},{"location":"index.html#Getting-started","page":"Home","title":"Getting started","text":"","category":"section"},{"location":"index.html","page":"Home","title":"Home","text":"To install the package just type","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"using Pkg; Pkg.add(\"Manifolds\")","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"Then you can directly start, for example to stop half way from the north pole on the Sphere to a point on the the equator, you can generate the shortest_geodesic. It internally employs log and exp.","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"using Manifolds\nM = Sphere(2)\nγ = shortest_geodesic(M, [0., 0., 1.], [0., 1., 0.])\nγ(0.5)","category":"page"},{"location":"index.html#Citation","page":"Home","title":"Citation","text":"","category":"section"},{"location":"index.html","page":"Home","title":"Home","text":"If you use Manifolds.jl in your work, please cite the following","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"@online{2106.08777,\n Author = {Seth D. Axen and Mateusz Baran and Ronny Bergmann and Krzysztof Rzecki},\n Title = {Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds},\n Year = {2021},\n Eprint = {2106.08777},\n Eprinttype = {arXiv},\n}","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"To refer to a certain version we recommend to also cite for example","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"@software{manifoldsjl-zenodo-mostrecent,\n Author = {Seth D. Axen and Mateusz Baran and Ronny Bergmann},\n Title = {Manifolds.jl},\n Doi = {10.5281/ZENODO.4292129},\n Url = {https://zenodo.org/record/4292129},\n Publisher = {Zenodo},\n Year = {2021},\n Copyright = {MIT License}\n}","category":"page"},{"location":"index.html","page":"Home","title":"Home","text":"for the most recent version or a corresponding version specific DOI, see the list of all versions. Note that both citations are in BibLaTeX format.","category":"page"},{"location":"manifolds/lorentz.html#Lorentzian-Manifold","page":"Lorentzian manifold","title":"Lorentzian Manifold","text":"","category":"section"},{"location":"manifolds/lorentz.html","page":"Lorentzian manifold","title":"Lorentzian manifold","text":"The Lorentz manifold is a pseudo-Riemannian manifold. It is named after the Dutch physicist Hendrik Lorentz (1853–1928). The default LorentzMetric is the MinkowskiMetric named after the German mathematician Hermann Minkowski (1864–1909).","category":"page"},{"location":"manifolds/lorentz.html","page":"Lorentzian manifold","title":"Lorentzian manifold","text":"Within Manifolds.jl it is used as the embedding of the Hyperbolic space.","category":"page"},{"location":"manifolds/lorentz.html","page":"Lorentzian manifold","title":"Lorentzian manifold","text":"Modules = [Manifolds]\nPages = [\"Lorentz.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/lorentz.html#Manifolds.Lorentz","page":"Lorentzian manifold","title":"Manifolds.Lorentz","text":"Lorentz{N} = MetricManifold{Euclidean{N,ℝ},LorentzMetric}\n\nThe Lorentz manifold (or Lorentzian) is a pseudo-Riemannian manifold.\n\nConstructor\n\nLorentz(n[, metric=MinkowskiMetric()])\n\nGenerate the Lorentz manifold of dimension n with the LorentzMetric m, which is by default set to the MinkowskiMetric.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/lorentz.html#Manifolds.LorentzMetric","page":"Lorentzian manifold","title":"Manifolds.LorentzMetric","text":"LorentzMetric <: AbstractMetric\n\nAbstract type for Lorentz metrics, which have a single time dimension. These metrics assume the spacelike convention with the time dimension being last, giving the signature (+++-).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/lorentz.html#Manifolds.MinkowskiMetric","page":"Lorentzian manifold","title":"Manifolds.MinkowskiMetric","text":"MinkowskiMetric <: LorentzMetric\n\nAs a special metric of signature (+++-), i.e. a LorentzMetric, see minkowski_metric for the formula.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/lorentz.html#Manifolds.minkowski_metric-Tuple{Any, Any}","page":"Lorentzian manifold","title":"Manifolds.minkowski_metric","text":"minkowski_metric(a,b)\n\nCompute the minkowski metric on mathbb R^n is given by\n\nab_mathrmM = -a_nb_n +\ndisplaystylesum_k=1^n-1 a_kb_k\n\n\n\n\n\n","category":"method"},{"location":"misc/internals.html#Internal-documentation","page":"Internals","title":"Internal documentation","text":"","category":"section"},{"location":"misc/internals.html","page":"Internals","title":"Internals","text":"This page documents the internal types and methods of Manifolds.jl's that might be of use for writing your own manifold.","category":"page"},{"location":"misc/internals.html#Functions","page":"Internals","title":"Functions","text":"","category":"section"},{"location":"misc/internals.html","page":"Internals","title":"Internals","text":"Manifolds.eigen_safe\nManifolds.isnormal\nManifolds.log_safe\nManifolds.log_safe!\nManifolds.mul!_safe\nManifolds.nzsign\nManifolds.realify\nManifolds.realify!\nManifolds.select_from_tuple\nManifolds.unrealify!\nManifolds.usinc\nManifolds.usinc_from_cos\nManifolds.vec2skew!\nManifolds.ziptuples","category":"page"},{"location":"misc/internals.html#Manifolds.eigen_safe","page":"Internals","title":"Manifolds.eigen_safe","text":"eigen_safe(x)\n\nCompute the eigendecomposition of x. If x is a StaticMatrix, it is converted to a Matrix before the decomposition.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.isnormal","page":"Internals","title":"Manifolds.isnormal","text":"isnormal(x; kwargs...) -> Bool\n\nCheck if the matrix or number x is normal, that is, if it commutes with its adjoint:\n\nx x^mathrmH = x^mathrmH x\n\nBy default, this is an equality check. Provide kwargs for isapprox to perform an approximate check.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.log_safe","page":"Internals","title":"Manifolds.log_safe","text":"log_safe(x)\n\nCompute the matrix logarithm of x. If x is a StaticMatrix, it is converted to a Matrix before computing the log.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.log_safe!","page":"Internals","title":"Manifolds.log_safe!","text":"log_safe!(y, x)\n\nCompute the matrix logarithm of x. If the eltype of y is real, then the imaginary part of x is ignored, and a DomainError is raised if real(x) has no real logarithm.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.mul!_safe","page":"Internals","title":"Manifolds.mul!_safe","text":"mul!_safe(Y, A, B) -> Y\n\nCall mul! safely, that is, A and/or B are permitted to alias with Y.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.nzsign","page":"Internals","title":"Manifolds.nzsign","text":"nzsign(z[, absz])\n\nCompute a modified sign(z) that is always nonzero, i.e. where\n\noperatorname(nzsign)(z) = begincases\n 1 textif z = 0\n fraczz textotherwise\nendcases\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.realify","page":"Internals","title":"Manifolds.realify","text":"realify(X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers) -> Y::AbstractMatrix{<:Real}\n\nGiven a matrix X 𝔽^n n, compute Y ℝ^m m, where m = n operatornamedim_𝔽, and operatornamedim_𝔽 is the real_dimension of the number field 𝔽, using the map ϕ colon X Y, that preserves the matrix product, so that for all CD 𝔽^n n,\n\nϕ(C) ϕ(D) = ϕ(CD)\n\nSee realify! for an in-place version, and unrealify! to compute the inverse of ϕ.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.realify!","page":"Internals","title":"Manifolds.realify!","text":"realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers)\n\nIn-place version of realify.\n\n\n\n\n\nrealify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{<:Complex}, ::typeof(ℂ))\n\nGiven a complex matrix X = A + iB ℂ^n n, compute its realified matrix Y ℝ^2n 2n, written where\n\nY = beginpmatrixA -B B A endpmatrix\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.select_from_tuple","page":"Internals","title":"Manifolds.select_from_tuple","text":"select_from_tuple(t::NTuple{N, Any}, positions::Val{P})\n\nSelects elements of tuple t at positions specified by the second argument. For example select_from_tuple((\"a\", \"b\", \"c\"), Val((3, 1, 1))) returns (\"c\", \"a\", \"a\").\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.unrealify!","page":"Internals","title":"Manifolds.unrealify!","text":"unrealify!(X::AbstractMatrix{T𝔽}, Y::AbstractMatrix{<:Real}, 𝔽::AbstractNumbers[, n])\n\nGiven a real matrix Y ℝ^m m, where m = n operatornamedim_𝔽, and operatornamedim_𝔽 is the real_dimension of the number field 𝔽, compute in-place its equivalent matrix X 𝔽^n n. Note that this function does not check that Y has a valid structure to be un-realified.\n\nSee realify! for the inverse of this function.\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.usinc","page":"Internals","title":"Manifolds.usinc","text":"usinc(θ::Real)\n\nUnnormalized version of sinc function, i.e. operatornameusinc(θ) = fracsin(θ)θ. This is equivalent to sinc(θ/π).\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.usinc_from_cos","page":"Internals","title":"Manifolds.usinc_from_cos","text":"usinc_from_cos(x::Real)\n\nUnnormalized version of sinc function, i.e. operatornameusinc(θ) = fracsin(θ)θ, computed from x = cos(θ).\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.vec2skew!","page":"Internals","title":"Manifolds.vec2skew!","text":"vec2skew!(X, v, k)\n\ncreate a skew symmetric matrix inplace in X of size ktimes k from a vector v, for example for v=[1,2,3] and k=3 this yields\n\n[ 0 1 2;\n -1 0 3;\n -2 -3 0\n]\n\n\n\n\n\n","category":"function"},{"location":"misc/internals.html#Manifolds.ziptuples","page":"Internals","title":"Manifolds.ziptuples","text":"ziptuples(a, b[, c[, d[, e]]])\n\nZips tuples a, b, and remaining in a fast, type-stable way. If they have different lengths, the result is trimmed to the length of the shorter tuple.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/sphere.html#SphereSection","page":"Sphere","title":"Sphere and unit norm arrays","text":"","category":"section"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"AbstractSphere","category":"page"},{"location":"manifolds/sphere.html#Manifolds.AbstractSphere","page":"Sphere","title":"Manifolds.AbstractSphere","text":"AbstractSphere{𝔽} <: AbstractDecoratorManifold{𝔽}\n\nAn abstract type to represent a unit sphere that is represented isometrically in the embedding.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"The classical sphere, i.e. unit norm (real- or complex-valued) vectors can be generated as usual: to create the 2-dimensional sphere (in ℝ^3), use Sphere(2) and Sphere(2,ℂ), respectively.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"Sphere","category":"page"},{"location":"manifolds/sphere.html#Manifolds.Sphere","page":"Sphere","title":"Manifolds.Sphere","text":"Sphere{n,𝔽} <: AbstractSphere{𝔽}\n\nThe (unit) sphere manifold 𝕊^n is the set of all unit norm vectors in 𝔽^n+1. The sphere is represented in the embedding, i.e.\n\n𝕊^n = bigl p in 𝔽^n+1 big lVert p rVert = 1 bigr\n\nwhere 𝔽inℝℂℍ. Note that compared to the ArraySphere, here the argument n of the manifold is the dimension of the manifold, i.e. 𝕊^n 𝔽^n+1, nin ℕ.\n\nThe tangent space at point p is given by\n\nT_p𝕊^n = bigl X 𝔽^n+1 Re(pX) = 0 bigr \n\nwhere 𝔽inℝℂℍ and cdotcdot denotes the inner product in the embedding 𝔽^n+1.\n\nFor 𝔽=ℂ, the manifold is the complex sphere, written ℂ𝕊^n, embedded in ℂ^n+1. ℂ𝕊^n is the complexification of the real sphere 𝕊^2n+1. Likewise, the quaternionic sphere ℍ𝕊^n is the quaternionification of the real sphere 𝕊^4n+3. Consequently, ℂ𝕊^0 is equivalent to 𝕊^1 and Circle, while ℂ𝕊^1 and ℍ𝕊^0 are equivalent to 𝕊^3, though with different default representations.\n\nThis manifold is modeled as a special case of the more general case, i.e. as an embedded manifold to the Euclidean, and several functions like the inner product and the zero_vector are inherited from the embedding.\n\nConstructor\n\nSphere(n[, field=ℝ])\n\nGenerate the (real-valued) sphere 𝕊^n ℝ^n+1, where field can also be used to generate the complex- and quaternionic-valued sphere.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"For the higher-dimensional arrays, for example unit (Frobenius) norm matrices, the manifold is generated using the size of the matrix. To create the unit sphere of 32 real-valued matrices, write ArraySphere(3,2) and the complex case is done – as for the Euclidean case – with an keyword argument ArraySphere(3,2; field = ℂ). This case also covers the classical sphere as a special case, but you specify the size of the vectors/embedding instead: The 2-sphere can here be generated ArraySphere(3).","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"ArraySphere","category":"page"},{"location":"manifolds/sphere.html#Manifolds.ArraySphere","page":"Sphere","title":"Manifolds.ArraySphere","text":"ArraySphere{T<:Tuple,𝔽} <: AbstractSphere{𝔽}\n\nThe (unit) sphere manifold 𝕊^n₁n₂nᵢ is the set of all unit (Frobenius) norm elements of 𝔽^n₁n₂nᵢ, where 𝔽\\in{ℝ,ℂ,ℍ}. The generalized sphere is represented in the embedding, and supports arbitrary sized arrays or in other words arbitrary tensors of unit norm. The set formally reads\n\n𝕊^n_1 n_2 n_i = bigl p in 𝔽^n_1 n_2 n_i big lVert p rVert = 1 bigr\n\nwhere 𝔽inℝℂℍ. Setting i=1 and 𝔽=ℝ this simplifies to unit vectors in ℝ^n, see Sphere for this special case. Note that compared to this classical case, the argument for the generalized case here is given by the dimension of the embedding. This means that Sphere(2) and ArraySphere(3) are the same manifold.\n\nThe tangent space at point p is given by\n\nT_p 𝕊^n_1 n_2 n_i = bigl X 𝔽^n_1 n_2 n_i Re(pX) = 0 bigr \n\nwhere 𝔽inℝℂℍ and cdotcdot denotes the (Frobenius) inner product in the embedding 𝔽^n_1 n_2 n_i.\n\nThis manifold is modeled as an embedded manifold to the Euclidean, i.e. several functions like the inner product and the zero_vector are inherited from the embedding.\n\nConstructor\n\nArraySphere(n₁,n₂,...,nᵢ; field=ℝ)\n\nGenerate sphere in 𝔽^n_1 n_2 n_i, where 𝔽 defaults to the real-valued case ℝ.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"There is also one atlas available on the sphere.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"Manifolds.StereographicAtlas","category":"page"},{"location":"manifolds/sphere.html#Manifolds.StereographicAtlas","page":"Sphere","title":"Manifolds.StereographicAtlas","text":"StereographicAtlas()\n\nThe stereographic atlas of S^n with two charts: one with the singular point (-1, 0, ..., 0) (called :north) and one with the singular point (1, 0, ..., 0) (called :south).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/sphere.html#Functions-on-unit-spheres","page":"Sphere","title":"Functions on unit spheres","text":"","category":"section"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"Modules = [Manifolds]\nPages = [\"manifolds/Sphere.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/sphere.html#Base.exp-Tuple{AbstractSphere, Vararg{Any}}","page":"Sphere","title":"Base.exp","text":"exp(M::AbstractSphere, p, X)\n\nCompute the exponential map from p in the tangent direction X on the AbstractSphere M by following the great arc eminating from p in direction X.\n\nexp_p X = cos(lVert X rVert_p)p + sin(lVert X rVert_p)fracXlVert X rVert_p\n\nwhere lVert X rVert_p is the norm on the tangent space at p of the AbstractSphere M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Base.log-Tuple{AbstractSphere, Vararg{Any}}","page":"Sphere","title":"Base.log","text":"log(M::AbstractSphere, p, q)\n\nCompute the logarithmic map on the AbstractSphere M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. The formula reads for x -y\n\nlog_p q = d_𝕊(pq) fracq-Re(pq) plVert q-Re(pq) p rVert_2\n\nand a deterministic choice from the set of tangent vectors is returned if x=-y, i.e. for opposite points.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.local_metric-Union{Tuple{n}, Tuple{Sphere{n, ℝ}, Any, DefaultOrthonormalBasis}} where n","page":"Sphere","title":"Manifolds.local_metric","text":"local_metric(M::Sphere{n}, p, ::DefaultOrthonormalBasis)\n\nreturn the local representation of the metric in a DefaultOrthonormalBasis, namely the diagonal matrix of size nn with ones on the diagonal, since the metric is obtained from the embedding by restriction to the tangent space T_pmathcal M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.manifold_volume-Tuple{AbstractSphere{ℝ}}","page":"Sphere","title":"Manifolds.manifold_volume","text":"manifold_volume(M::AbstractSphere{ℝ})\n\nVolume of the n-dimensional Sphere M. The formula reads\n\noperatornameVol(𝕊^n) = frac2pi^(n+1)2Γ((n+1)2)\n\nwhere Γ denotes the Gamma function.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.uniform_distribution-Union{Tuple{n}, Tuple{Sphere{n, ℝ}, Any}} where n","page":"Sphere","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::Sphere{n,ℝ}, p) where {n}\n\nUniform distribution on given Sphere M. Generated points will be of similar type as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Manifolds.volume_density-Tuple{AbstractSphere{ℝ}, Any, Any}","page":"Sphere","title":"Manifolds.volume_density","text":"volume_density(M::AbstractSphere{ℝ}, p, X)\n\nCompute volume density function of a sphere, i.e. determinant of the differential of exponential map exp(M, p, X). The formula reads (sin(lVert XrVert)lVert XrVert)^(n-1) where n is the dimension of M. It is derived from Eq. (4.1) in [ChevallierLiLuDunson2022].\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.check_point-Tuple{AbstractSphere, Any}","page":"Sphere","title":"ManifoldsBase.check_point","text":"check_point(M::AbstractSphere, p; kwargs...)\n\nCheck whether p is a valid point on the AbstractSphere M, i.e. is a point in the embedding of unit length. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.check_vector-Tuple{AbstractSphere, Any, Any}","page":"Sphere","title":"ManifoldsBase.check_vector","text":"check_vector(M::AbstractSphere, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the AbstractSphere M, i.e. after check_point(M,p), X has to be of same dimension as p and orthogonal to p. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.distance-Tuple{AbstractSphere, Any, Any}","page":"Sphere","title":"ManifoldsBase.distance","text":"distance(M::AbstractSphere, p, q)\n\nCompute the geodesic distance betweeen p and q on the AbstractSphere M. The formula is given by the (shorter) great arc length on the (or a) great circle both p and q lie on.\n\nd_𝕊(pq) = arccos(Re(pq))\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.get_coordinates-Tuple{AbstractSphere{ℝ}, Any, Any, DefaultOrthonormalBasis}","page":"Sphere","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)\n\nRepresent the tangent vector X at point p from the AbstractSphere M in an orthonormal basis by rotating the hyperplane containing X to a hyperplane whose normal is the x-axis.\n\nGiven q = p λ + x, where λ = operatornamesgn(x p), and _mathrmF denotes the Frobenius inner product, the formula for Y is\n\nbeginpmatrix0 Yendpmatrix = X - qfrac2 q X_mathrmFq q_mathrmF\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.get_vector-Tuple{AbstractSphere{ℝ}, Any, Any, DefaultOrthonormalBasis}","page":"Sphere","title":"ManifoldsBase.get_vector","text":"get_vector(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)\n\nConvert a one-dimensional vector of coefficients X in the basis B of the tangent space at p on the AbstractSphere M to a tangent vector Y at p by rotating the hyperplane containing X, whose normal is the x-axis, to the hyperplane whose normal is p.\n\nGiven q = p λ + x, where λ = operatornamesgn(x p), and _mathrmF denotes the Frobenius inner product, the formula for Y is\n\nY = X - qfrac2 leftlangle q beginpmatrix0 Xendpmatrixrightrangle_mathrmFq q_mathrmF\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.injectivity_radius-Tuple{AbstractSphere}","page":"Sphere","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::AbstractSphere[, p])\n\nReturn the injectivity radius for the AbstractSphere M, which is globally π.\n\ninjectivity_radius(M::Sphere, x, ::ProjectionRetraction)\n\nReturn the injectivity radius for the ProjectionRetraction on the AbstractSphere, which is globally fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.inverse_retract-Tuple{AbstractSphere, Any, Any, ProjectionInverseRetraction}","page":"Sphere","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::AbstractSphere, p, q, ::ProjectionInverseRetraction)\n\nCompute the inverse of the projection based retraction on the AbstractSphere M, i.e. rearranging p+X = qlVert p+XrVert_2 yields since Re(pX) = 0 and when d_𝕊^2(pq) fracπ2 that\n\noperatornameretr_p^-1(q) = fracqRe(p q) - p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.is_flat-Tuple{AbstractSphere}","page":"Sphere","title":"ManifoldsBase.is_flat","text":"is_flat(M::AbstractSphere)\n\nReturn true if AbstractSphere is of dimension 1 and false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.manifold_dimension-Tuple{AbstractSphere}","page":"Sphere","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::AbstractSphere)\n\nReturn the dimension of the AbstractSphere M, respectively i.e. the dimension of the embedding -1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.parallel_transport_to-Tuple{AbstractSphere, Vararg{Any, 4}}","page":"Sphere","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::AbstractSphere, p, X, q)\n\nCompute the parallel transport on the Sphere of the tangent vector X at p to q, provided, the geodesic between p and q is unique. The formula reads\n\nP_pq(X) = X - fracRe(log_p qX_p)d^2_𝕊(pq)\nbigl(log_p q + log_q p bigr)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.project-Tuple{AbstractSphere, Any, Any}","page":"Sphere","title":"ManifoldsBase.project","text":"project(M::AbstractSphere, p, X)\n\nProject the point X onto the tangent space at p on the Sphere M.\n\noperatornameproj_p(X) = X - Re(p X)p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.project-Tuple{AbstractSphere, Any}","page":"Sphere","title":"ManifoldsBase.project","text":"project(M::AbstractSphere, p)\n\nProject the point p from the embedding onto the Sphere M.\n\noperatornameproj(p) = fracplVert p rVert\n\nwhere lVertcdotrVert denotes the usual 2-norm for vectors if m=1 and the Frobenius norm for the case m1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.representation_size-Union{Tuple{ArraySphere{N}}, Tuple{N}} where N","page":"Sphere","title":"ManifoldsBase.representation_size","text":"representation_size(M::AbstractSphere)\n\nReturn the size points on the AbstractSphere M are represented as, i.e., the representation size of the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.retract-Tuple{AbstractSphere, Any, Any, ProjectionRetraction}","page":"Sphere","title":"ManifoldsBase.retract","text":"retract(M::AbstractSphere, p, X, ::ProjectionRetraction)\n\nCompute the retraction that is based on projection, i.e.\n\noperatornameretr_p(X) = fracp+XlVert p+X rVert_2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#ManifoldsBase.riemann_tensor-Tuple{AbstractSphere{ℝ}, Vararg{Any, 4}}","page":"Sphere","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::AbstractSphere{ℝ}, p, X, Y, Z)\n\nCompute the Riemann tensor R(XY)Z at point p on AbstractSphere M. The formula reads [MuralidharanFletcher2021] (though note that a different convention is used in that paper than in Manifolds.jl):\n\nR(XY)Z = langle Z Y rangle X - langle Z X rangle Y\n\n[MuralidharanFletcher2021]: P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012, pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Statistics.mean-Tuple{AbstractSphere, Vararg{Any}}","page":"Sphere","title":"Statistics.mean","text":"mean(\n S::AbstractSphere,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/2);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/sphere.html#Visualization-on-Sphere{2,ℝ}","page":"Sphere","title":"Visualization on Sphere{2,ℝ}","text":"","category":"section"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"You can visualize both points and tangent vectors on the sphere.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"note: Note\nThere seems to be no unified way to draw spheres in the backends of Plots.jl. This recipe currently uses the seriestype wireframe and surface, which does not yet work with the default backend GR.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"In general you can plot the surface of the hyperboloid either as wireframe (wireframe=true) additionally specifying wires (or wires_x and wires_y) to change the density of the wires and a wireframe_color for their color. The same holds for the plot as a surface (which is false by default) and its surface_resolution (or surface_resolution_lat or surface_resolution_lon) and a surface_color.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"using Manifolds, Plots\npythonplot()\nM = Sphere(2)\npts = [ [1.0, 0.0, 0.0], [0.0, -1.0, 0.0], [0.0, 0.0, 1.0], [1.0, 0.0, 0.0] ]\nscene = plot(M, pts; wireframe_color=colorant\"#CCCCCC\", markersize=10)","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"which scatters our points. We can also draw connecting geodesics, which here is a geodesic triangle. Here we discretize each geodesic with 100 points along the geodesic. The default value is geodesic_interpolation=-1 which switches to scatter plot of the data.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"plot!(scene, M, pts; wireframe=false, geodesic_interpolation=100, linewidth=2)","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"And we can also add tangent vectors, for example tangents pointing towards the geometric center of given points.","category":"page"},{"location":"manifolds/sphere.html","page":"Sphere","title":"Sphere","text":"pts2 = [ [1.0, 0.0, 0.0], [0.0, -1.0, 0.0], [0.0, 0.0, 1.0] ]\np3 = 1/sqrt(3) .* [1.0, -1.0, 1.0]\nvecs = log.(Ref(M), pts2, Ref(p3))\nplot!(scene, M, pts2, vecs; wireframe = false, linewidth=1.5)","category":"page"},{"location":"manifolds/shapespace.html#Shape-spaces","page":"Shape spaces","title":"Shape spaces","text":"","category":"section"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Shape spaces are spaces of k points in mathbbR^n up to simultaneous action of a group on all points. The most commonly encountered are Kendall's pre-shape and shape spaces. In the case of the Kendall's pre-shape spaces the action is translation and scaling. In the case of the Kendall's shape spaces the action is translation, scaling and rotation.","category":"page"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"using Manifolds, Plots\n\nM = KendallsShapeSpace(2, 3)\n# two random point on the shape space\np = [\n 0.4385117672460505 -0.6877826444042382 0.24927087715818771\n -0.3830259932279294 0.35347460720654283 0.029551386021386548\n]\nq = [\n -0.42693314765896473 -0.3268567431952937 0.7537898908542584\n 0.3054740561061169 -0.18962848284149897 -0.11584557326461796\n]\n# let's plot them as triples of points on a plane\nfig = scatter(p[1,:], p[2,:], label=\"p\", aspect_ratio=:equal)\nscatter!(fig, q[1,:], q[2,:], label=\"q\")\n\n# aligning q to p\nA = get_orbit_action(M)\na = optimal_alignment(A, p, q)\nrot_q = apply(A, a, q)\nscatter!(fig, rot_q[1,:], rot_q[2,:], label=\"q aligned to p\")","category":"page"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"A more extensive usage example is available in the hand_gestures.jl tutorial.","category":"page"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsPreShapeSpace.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/shapespace.html#Manifolds.KendallsPreShapeSpace","page":"Shape spaces","title":"Manifolds.KendallsPreShapeSpace","text":"KendallsPreShapeSpace{n,k} <: AbstractSphere{ℝ}\n\nKendall's pre-shape space of k landmarks in ℝ^n represented by n×k matrices. In each row the sum of elements of a matrix is equal to 0. The Frobenius norm of the matrix is equal to 1 [Kendall1984][Kendall1989].\n\nThe space can be interpreted as tuples of k points in ℝ^n up to simultaneous translation and scaling of all points, so this can be thought of as a quotient manifold.\n\nConstructor\n\nKendallsPreShapeSpace(n::Int, k::Int)\n\nSee also\n\nKendallsShapeSpace, esp. for the references\n\n\n\n\n\n","category":"type"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsShapeSpace.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/shapespace.html#Manifolds.KendallsShapeSpace","page":"Shape spaces","title":"Manifolds.KendallsShapeSpace","text":"KendallsShapeSpace{n,k} <: AbstractDecoratorManifold{ℝ}\n\nKendall's shape space, defined as quotient of a KendallsPreShapeSpace (represented by n×k matrices) by the action ColumnwiseMultiplicationAction.\n\nThe space can be interpreted as tuples of k points in ℝ^n up to simultaneous translation and scaling and rotation of all points [Kendall1984][Kendall1989].\n\nThis manifold possesses the IsQuotientManifold trait.\n\nConstructor\n\nKendallsShapeSpace(n::Int, k::Int)\n\nReferences\n\n[Kendall1989]: D. G. Kendall, “A Survey of the Statistical Theory of Shape,” Statist. Sci., vol. 4, no. 2, pp. 87–99, May 1989 doi: 10.1214/ss/1177012582.\n\n[Kendall1984]: D. G. Kendall, “Shape Manifolds, Procrustean Metrics, and Complex Projective Spaces,” Bull. London Math. Soc., vol. 16, no. 2, pp. 81–121, Mar. 1984 doi: 10.1112/blms/16.2.81.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/shapespace.html#Provided-functions","page":"Shape spaces","title":"Provided functions","text":"","category":"section"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsPreShapeSpace.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/shapespace.html#ManifoldsBase.check_point-Tuple{KendallsPreShapeSpace, Any}","page":"Shape spaces","title":"ManifoldsBase.check_point","text":"check_point(M::KendallsPreShapeSpace, p; atol=sqrt(max_eps(X, Y)), kwargs...)\n\nCheck whether p is a valid point on KendallsPreShapeSpace, i.e. whether each row has zero mean. Other conditions are checked via embedding in ArraySphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.check_vector-Tuple{KendallsPreShapeSpace, Any, Any}","page":"Shape spaces","title":"ManifoldsBase.check_vector","text":"check_vector(M::KendallsPreShapeSpace, p, X; kwargs... )\n\nCheck whether X is a valid tangent vector on KendallsPreShapeSpace, i.e. whether each row has zero mean. Other conditions are checked via embedding in ArraySphere.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.get_embedding-Union{Tuple{KendallsPreShapeSpace{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Shape spaces","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::KendallsPreShapeSpace)\n\nReturn the space KendallsPreShapeSpace M is embedded in, i.e. ArraySphere of matrices of the same shape.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.manifold_dimension-Union{Tuple{KendallsPreShapeSpace{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Shape spaces","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::KendallsPreShapeSpace)\n\nReturn the dimension of the KendallsPreShapeSpace manifold M. The dimension is given by n(k - 1) - 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.project-Tuple{KendallsPreShapeSpace, Any, Any}","page":"Shape spaces","title":"ManifoldsBase.project","text":"project(M::KendallsPreShapeSpace, p, X)\n\nProject tangent vector X at point p from the embedding to KendallsPreShapeSpace by selecting the right element from the tangent space to orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.\n\nReferences\n\n[Srivastava2016]: A. Srivastava and E. P. Klassen, Functional and Shape Data Analysis. Springer New York, 2016. ISBN: 978-1-4939-4018-9. doi: 10.1007/978-1-4939-4020-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.project-Tuple{KendallsPreShapeSpace, Any}","page":"Shape spaces","title":"ManifoldsBase.project","text":"project(M::KendallsPreShapeSpace, p)\n\nProject point p from the embedding to KendallsPreShapeSpace by selecting the right element from the orthogonal section representing the quotient manifold M. See Section 3.7 of [Srivastava2016] for details.\n\nThe method computes the mean of the landmarks and moves them to make their mean zero; afterwards the Frobenius norm of the landmarks (as a matrix) is normalised to fix the scaling.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html","page":"Shape spaces","title":"Shape spaces","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/KendallsShapeSpace.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/shapespace.html#Base.exp-Tuple{KendallsShapeSpace, Any, Any}","page":"Shape spaces","title":"Base.exp","text":"exp(M::KendallsShapeSpace, p, X)\n\nCompute the exponential map on KendallsShapeSpace M. See [Guigui2021] for discussion about its computation.\n\n[Guigui2021]: N. Guigui, E. Maignant, A. Trouvé, and X. Pennec, “Parallel Transport on Kendall Shape Spaces,” in Geometric Science of Information, Cham, 2021, pp. 103–110. doi: 10.1007/978-3-030-80209-7_12.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Base.log-Tuple{KendallsShapeSpace, Any, Any}","page":"Shape spaces","title":"Base.log","text":"log(M::KendallsShapeSpace, p, q)\n\nCompute the logarithmic map on KendallsShapeSpace M. See the [exp](@ref exp(::KendallsShapeSpace, ::Any, ::Any)onential map for more details\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Base.rand-Tuple{KendallsShapeSpace}","page":"Shape spaces","title":"Base.rand","text":"rand(::KendallsShapeSpace; vector_at=nothing)\n\nWhen vector_at is nothing, return a random point x on the KendallsShapeSpace manifold M by generating a random point in the embedding.\n\nWhen vector_at is not nothing, return a random vector from the tangent space with mean zero and standard deviation σ.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Manifolds.get_total_space-Union{Tuple{KendallsShapeSpace{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Shape spaces","title":"Manifolds.get_total_space","text":"get_total_space(::Grassmann{n,k})\n\nReturn the total space of the KendallsShapeSpace manifold, which is the KendallsPreShapeSpace manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#Manifolds.horizontal_component-Tuple{KendallsShapeSpace, Any, Any}","page":"Shape spaces","title":"Manifolds.horizontal_component","text":"horizontal_component(::KendallsShapeSpace, p, X)\n\nCompute the horizontal component of tangent vector X at p on KendallsShapeSpace M. See [Guigui2021], Section 2.3 for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.get_embedding-Union{Tuple{KendallsShapeSpace{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Shape spaces","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::KendallsShapeSpace)\n\nGet the manifold in which KendallsShapeSpace M is embedded, i.e. KendallsPreShapeSpace of matrices of the same shape.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.is_flat-Tuple{KendallsShapeSpace}","page":"Shape spaces","title":"ManifoldsBase.is_flat","text":"is_flat(::KendallsShapeSpace)\n\nReturn false. KendallsShapeSpace is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/shapespace.html#ManifoldsBase.manifold_dimension-Union{Tuple{KendallsShapeSpace{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Shape spaces","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::KendallsShapeSpace)\n\nReturn the dimension of the KendallsShapeSpace manifold M. The dimension is given by n(k - 1) - 1 - n(n - 1)2 in the typical case where k geq n+1, and (k + 1)(k - 2) 2 otherwise, unless k is equal to 1, in which case the dimension is 0. See [Kendall1984] for a discussion of the over-dimensioned case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#Graph-manifold","page":"Graph manifold","title":"Graph manifold","text":"","category":"section"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"For a given graph G(VE) implemented using Graphs.jl, the GraphManifold models a PowerManifold either on the nodes or edges of the graph, depending on the GraphManifoldType. i.e., it's either a mathcal M^lvert V rvert for the case of a vertex manifold or a mathcal M^lvert E rvert for the case of a edge manifold.","category":"page"},{"location":"manifolds/graph.html#Example","page":"Graph manifold","title":"Example","text":"","category":"section"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"To make a graph manifold over ℝ^2 with three vertices and two edges, one can use","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"using Manifolds\nusing Graphs\nM = Euclidean(2)\np = [[1., 4.], [2., 5.], [3., 6.]]\nq = [[4., 5.], [6., 7.], [8., 9.]]\nx = [[6., 5.], [4., 3.], [2., 8.]]\nG = SimpleGraph(3)\nadd_edge!(G, 1, 2)\nadd_edge!(G, 2, 3)\nN = GraphManifold(G, M, VertexManifold())","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"It supports all AbstractPowerManifold operations (it is based on NestedPowerRepresentation) and furthermore it is possible to compute a graph logarithm:","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"using Manifolds\nusing Graphs\nM = Euclidean(2)\np = [[1., 4.], [2., 5.], [3., 6.]]\nq = [[4., 5.], [6., 7.], [8., 9.]]\nx = [[6., 5.], [4., 3.], [2., 8.]]\nG = SimpleGraph(3)\nadd_edge!(G, 1, 2)\nadd_edge!(G, 2, 3)\nN = GraphManifold(G, M, VertexManifold())","category":"page"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"incident_log(N, p)","category":"page"},{"location":"manifolds/graph.html#Types-and-functions","page":"Graph manifold","title":"Types and functions","text":"","category":"section"},{"location":"manifolds/graph.html","page":"Graph manifold","title":"Graph manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/GraphManifold.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/graph.html#Manifolds.EdgeManifold","page":"Graph manifold","title":"Manifolds.EdgeManifold","text":"EdgeManifoldManifold <: GraphManifoldType\n\nA type for a GraphManifold where the data is given on the edges.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.GraphManifold","page":"Graph manifold","title":"Manifolds.GraphManifold","text":"GraphManifold{G,𝔽,M,T} <: AbstractPowerManifold{𝔽,M,NestedPowerRepresentation}\n\nBuild a manifold, that is a PowerManifold of the AbstractManifold M either on the edges or vertices of a graph G depending on the GraphManifoldType T.\n\nFields\n\nG is an AbstractSimpleGraph\nM is a AbstractManifold\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.GraphManifoldType","page":"Graph manifold","title":"Manifolds.GraphManifoldType","text":"GraphManifoldType\n\nThis type represents the type of data on the graph that the GraphManifold represents.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.VertexManifold","page":"Graph manifold","title":"Manifolds.VertexManifold","text":"VectexGraphManifold <: GraphManifoldType\n\nA type for a GraphManifold where the data is given on the vertices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/graph.html#Manifolds.incident_log-Tuple{GraphManifold{<:Graphs.AbstractGraph, 𝔽, <:AbstractManifold{𝔽}, VertexManifold} where 𝔽, Any}","page":"Graph manifold","title":"Manifolds.incident_log","text":"incident_log(M::GraphManifold, x)\n\nReturn the tangent vector on the (vertex) GraphManifold, where at each node the sum of the logs to incident nodes is computed. For a SimpleGraph, an egde is interpreted as double edge in the corresponding SimpleDiGraph\n\nIf the internal graph is a SimpleWeightedGraph the weighted sum of the tangent vectors is computed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.check_point-Tuple{GraphManifold, Vararg{Any}}","page":"Graph manifold","title":"ManifoldsBase.check_point","text":"check_point(M::GraphManifold, p)\n\nCheck whether p is a valid point on the GraphManifold, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of p passes the check_point test for the base manifold M.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.check_vector-Tuple{GraphManifold, Vararg{Any}}","page":"Graph manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::GraphManifold, p, X; kwargs...)\n\nCheck whether p is a valid point on the GraphManifold, and X it from its tangent space, i.e. its length equals the number of vertices (for VertexManifolds) or the number of edges (for EdgeManifolds) and that each element of X together with its corresponding entry of p passes the check_vector test for the base manifold M.manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.manifold_dimension-Tuple{GraphManifold{<:Graphs.AbstractGraph, 𝔽, <:AbstractManifold{𝔽}, EdgeManifold} where 𝔽}","page":"Graph manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(N::GraphManifold{G,𝔽,M,EdgeManifold})\n\nreturns the manifold dimension of the GraphManifold N on the edges of a graph G=(VE), i.e.\n\ndim(mathcal N) = lvert E rvert dim(mathcal M)\n\nwhere mathcal M is the manifold of the data on the edges.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/graph.html#ManifoldsBase.manifold_dimension-Tuple{GraphManifold{<:Graphs.AbstractGraph, 𝔽, <:AbstractManifold{𝔽}, VertexManifold} where 𝔽}","page":"Graph manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(N::GraphManifold{G,𝔽,M,VertexManifold})\n\nreturns the manifold dimension of the GraphManifold N on the vertices of a graph G=(VE), i.e.\n\ndim(mathcal N) = lvert V rvert dim(mathcal M)\n\nwhere mathcal M is the manifold of the data on the nodes.\n\n\n\n\n\n","category":"method"},{"location":"features/integration.html#Integration","page":"Integration","title":"Integration","text":"","category":"section"},{"location":"features/integration.html","page":"Integration","title":"Integration","text":"manifold_volume(::AbstractManifold)\nvolume_density(::AbstractManifold, ::Any, ::Any)","category":"page"},{"location":"features/integration.html#Manifolds.manifold_volume-Tuple{AbstractManifold}","page":"Integration","title":"Manifolds.manifold_volume","text":"manifold_volume(M::AbstractManifold)\n\nVolume of manifold M defined through integration of Riemannian volume element in a chart. Note that for many manifolds there is no universal agreement over the exact ranges over which the integration should happen. For details see [BoyaSudarshanTilma2003].\n\n[BoyaSudarshanTilma2003]: L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1\n\n\n\n\n\n","category":"method"},{"location":"features/integration.html#Manifolds.volume_density-Tuple{AbstractManifold, Any, Any}","page":"Integration","title":"Manifolds.volume_density","text":"volume_density(M::AbstractManifold, p, X)\n\nVolume density function of manifold M, i.e. determinant of the differential of exponential map exp(M, p, X). Determinant can be understood as computed in a basis, from the matrix of the linear operator said differential corresponds to. Details are available in Section 4.1 of [ChevallierLiLuDunson2022].\n\nNote that volume density is well-defined only for X for which exp(M, p, X) is injective.\n\n[ChevallierLiLuDunson2022]: E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#EuclideanSection","page":"Euclidean","title":"Euclidean space","text":"","category":"section"},{"location":"manifolds/euclidean.html","page":"Euclidean","title":"Euclidean","text":"The Euclidean space ℝ^n is a simple model space, since it has curvature constantly zero everywhere; hence, nearly all operations simplify. The easiest way to generate an Euclidean space is to use a field, i.e. AbstractNumbers, e.g. to create the ℝ^n or ℝ^ntimes n you can simply type M = ℝ^n or ℝ^(n,n), respectively.","category":"page"},{"location":"manifolds/euclidean.html","page":"Euclidean","title":"Euclidean","text":"Modules = [Manifolds]\nPages = [\"manifolds/Euclidean.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/euclidean.html#Manifolds.Euclidean","page":"Euclidean","title":"Manifolds.Euclidean","text":"Euclidean{T<:Tuple,𝔽} <: AbstractManifold{𝔽}\n\nEuclidean vector space.\n\nConstructor\n\nEuclidean(n)\n\nGenerate the n-dimensional vector space ℝ^n.\n\nEuclidean(n₁,n₂,...,nᵢ; field=ℝ)\n𝔽^(n₁,n₂,...,nᵢ) = Euclidean(n₁,n₂,...,nᵢ; field=𝔽)\n\nGenerate the vector space of k = n_1 cdot n_2 cdot cdot n_i values, i.e. the manifold 𝔽^n_1 n_2 n_i, 𝔽inℝℂ, whose elements are interpreted as n_1 n_2 n_i arrays. For i=2 we obtain a matrix space. The default field=ℝ can also be set to field=ℂ. The dimension of this space is k dim_ℝ 𝔽, where dim_ℝ 𝔽 is the real_dimension of the field 𝔽.\n\nEuclidean(; field=ℝ)\n\nGenerate the 1D Euclidean manifold for an ℝ-, ℂ-valued real- or complex-valued immutable values (in contrast to 1-element arrays from the constructor above).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/euclidean.html#Base.exp-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"Base.exp","text":"exp(M::Euclidean, p, X)\n\nCompute the exponential map on the Euclidean manifold M from p in direction X, which in this case is just\n\nexp_p X = p + X\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#Base.log-Tuple{Euclidean, Vararg{Any}}","page":"Euclidean","title":"Base.log","text":"log(M::Euclidean, p, q)\n\nCompute the logarithmic map on the Euclidean M from p to q, which in this case is just\n\nlog_p q = q-p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#LinearAlgebra.norm-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"LinearAlgebra.norm","text":"norm(M::Euclidean, p, X)\n\nCompute the norm of a tangent vector X at p on the Euclidean M, i.e. since every tangent space can be identified with M itself in this case, just the (Frobenius) norm of X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#Manifolds.manifold_volume-Tuple{Euclidean}","page":"Euclidean","title":"Manifolds.manifold_volume","text":"manifold_volume(::Euclidean)\n\nReturn volume of the Euclidean manifold, i.e. infinity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#Manifolds.volume_density-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"Manifolds.volume_density","text":"volume_density(M::Euclidean, p, X)\n\nReturn volume density function of Euclidean manifold M, i.e. 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.distance-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"ManifoldsBase.distance","text":"distance(M::Euclidean, p, q)\n\nCompute the Euclidean distance between two points on the Euclidean manifold M, i.e. for vectors it's just the norm of the difference, for matrices and higher order arrays, the matrix and ternsor Frobenius norm, respectively.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.embed-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"ManifoldsBase.embed","text":"embed(M::Euclidean, p, X)\n\nEmbed the tangent vector X at point p in M. Equivalent to an identity map.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.embed-Tuple{Euclidean, Any}","page":"Euclidean","title":"ManifoldsBase.embed","text":"embed(M::Euclidean, p)\n\nEmbed the point p in M. Equivalent to an identity map.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.injectivity_radius-Tuple{Euclidean}","page":"Euclidean","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Euclidean)\n\nReturn the injectivity radius on the Euclidean M, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.inner-Tuple{Euclidean, Vararg{Any}}","page":"Euclidean","title":"ManifoldsBase.inner","text":"inner(M::Euclidean, p, X, Y)\n\nCompute the inner product on the Euclidean M, which is just the inner product on the real-valued or complex valued vector space of arrays (or tensors) of size n_1 n_2 n_i, i.e.\n\ng_p(XY) = sum_k I overlineX_k Y_k\n\nwhere I is the set of vectors k ℕ^i, such that for all\n\ni j i it holds 1 k_j n_j and overlinecdot denotes the complex conjugate.\n\nFor the special case of i 2, i.e. matrices and vectors, this simplifies to\n\ng_p(XY) = X^mathrmHY\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.is_flat-Tuple{Euclidean}","page":"Euclidean","title":"ManifoldsBase.is_flat","text":"is_flat(::Euclidean)\n\nReturn true. Euclidean is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.manifold_dimension-Union{Tuple{Euclidean{N, 𝔽}}, Tuple{𝔽}, Tuple{N}} where {N, 𝔽}","page":"Euclidean","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Euclidean)\n\nReturn the manifold dimension of the Euclidean M, i.e. the product of all array dimensions and the real_dimension of the underlying number system.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.parallel_transport_along-Tuple{Euclidean, Any, Any, AbstractVector}","page":"Euclidean","title":"ManifoldsBase.parallel_transport_along","text":"parallel_transport_along(M::Euclidean, p, X, c)\n\nthe parallel transport on Euclidean is the identiy, i.e. returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.parallel_transport_direction-Tuple{Euclidean, Any, Any, Any}","page":"Euclidean","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::Euclidean, p, X, d)\n\nthe parallel transport on Euclidean is the identiy, i.e. returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.parallel_transport_to-Tuple{Euclidean, Any, Any, Any}","page":"Euclidean","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::Euclidean, p, X, q)\n\nthe parallel transport on Euclidean is the identiy, i.e. returns X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.project-Tuple{Euclidean, Any, Any}","page":"Euclidean","title":"ManifoldsBase.project","text":"project(M::Euclidean, p, X)\n\nProject an arbitrary vector X into the tangent space of a point p on the Euclidean M, which is just the identity, since any tangent space of M can be identified with all of M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.project-Tuple{Euclidean, Any}","page":"Euclidean","title":"ManifoldsBase.project","text":"project(M::Euclidean, p)\n\nProject an arbitrary point p onto the Euclidean manifold M, which is of course just the identity map.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.representation_size-Union{Tuple{Euclidean{N}}, Tuple{N}} where N","page":"Euclidean","title":"ManifoldsBase.representation_size","text":"representation_size(M::Euclidean)\n\nReturn the array dimensions required to represent an element on the Euclidean M, i.e. the vector of all array dimensions.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.riemann_tensor-Tuple{Euclidean, Vararg{Any, 4}}","page":"Euclidean","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(M::Euclidean, p, X, Y, Z)\n\nCompute the Riemann tensor R(XY)Z at point p on Euclidean manifold M. Its value is always the zero tangent vector. ````\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.vector_transport_to-Tuple{Euclidean, Any, Any, Any, AbstractVectorTransportMethod}","page":"Euclidean","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Euclidean, p, X, q, ::AbstractVectorTransportMethod)\n\nTransport the vector X from the tangent space at p to the tangent space at q on the Euclidean M, which simplifies to the identity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/euclidean.html#ManifoldsBase.zero_vector-Tuple{Euclidean, Vararg{Any}}","page":"Euclidean","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Euclidean, x)\n\nReturn the zero vector in the tangent space of x on the Euclidean M, which here is just a zero filled array the same size as x.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#Multinomial-symmetric-matrices","page":"Multinomial symmetric matrices","title":"Multinomial symmetric matrices","text":"","category":"section"},{"location":"manifolds/multinomialsymmetric.html","page":"Multinomial symmetric matrices","title":"Multinomial symmetric matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/MultinomialSymmetric.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/multinomialsymmetric.html#Manifolds.MultinomialSymmetric","page":"Multinomial symmetric matrices","title":"Manifolds.MultinomialSymmetric","text":"MultinomialSymmetric{n} <: AbstractMultinomialDoublyStochastic{N}\n\nThe multinomial symmetric matrices manifold consists of all symmetric nn matrices with positive entries such that each column sums to one, i.e.\n\nbeginaligned\nmathcalSP(n) coloneqq biglp ℝ^nn big p_ij 0 text for all i=1n j=1m\n p^mathrmT = p\n pmathbf1_n = mathbf1_n\nbigr\nendaligned\n\nwhere mathbf1_n is the vector of length n containing ones.\n\nIt is modeled as IsIsometricEmbeddedManifold. via the AbstractMultinomialDoublyStochastic type, since it shares a few functions also with AbstractMultinomialDoublyStochastic, most and foremost projection of a point from the embedding onto the manifold.\n\nThe tangent space can be written as\n\nT_pmathcalSP(n) coloneqq bigl\nX ℝ^nn big X = X^mathrmT text and \nXmathbf1_n = mathbf0_n\nbigr\n\nwhere mathbf0_n is the vector of length n containing zeros.\n\nMore details can be found in Section IV[DouikHassibi2019].\n\nConstructor\n\nMultinomialSymmetric(n)\n\nGenerate the manifold of matrices mathbb R^nn that are doubly stochastic and symmetric.\n\n[DouikHassibi2019]: A. Douik, B. Hassibi: AbstractManifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry, IEEE Transactions on Signal Processing 67(22), pp. 5761–5774, 2019. doi: 10.1109/tsp.2019.2946024, arXiv: 1802.02628.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.check_point-Union{Tuple{n}, Tuple{MultinomialSymmetric{n}, Any}} where n","page":"Multinomial symmetric matrices","title":"ManifoldsBase.check_point","text":"check_point(M::MultinomialSymmetric, p)\n\nChecks whether p is a valid point on the MultinomialSymmetric(m,n) M, i.e. is a symmetric matrix with positive entries whose rows sum to one.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.check_vector-Union{Tuple{n}, Tuple{MultinomialSymmetric{n}, Any, Any}} where n","page":"Multinomial symmetric matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::MultinomialSymmetric p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the MultinomialSymmetric M. This means, that p is valid, that X is of correct dimension, symmetric, and sums to zero along any row.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.is_flat-Tuple{MultinomialSymmetric}","page":"Multinomial symmetric matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::MultinomialSymmetric)\n\nReturn false. MultinomialSymmetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.manifold_dimension-Union{Tuple{MultinomialSymmetric{n}}, Tuple{n}} where n","page":"Multinomial symmetric matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::MultinomialSymmetric{n}) where {n}\n\nreturns the dimension of the MultinomialSymmetric manifold namely\n\noperatornamedim_mathcalSP(n) = fracn(n-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.project-Tuple{MultinomialSymmetric, Any, Any}","page":"Multinomial symmetric matrices","title":"ManifoldsBase.project","text":"project(M::MultinomialSymmetric{n}, p, Y) where {n}\n\nProject Y onto the tangent space at p on the MultinomialSymmetric M, return the result in X. The formula reads\n\n operatornameproj_p(Y) = Y - (αmathbf1_n^mathrmT + mathbf1_n α^mathrmT) p\n\nwhere denotes the Hadamard or elementwise product and mathbb1_n is the vector of length n containing ones. The two vector α ℝ^nn is given by solving\n\n (I_n+p)α = Ymathbf1\n\nwhere I_n is teh nn unit matrix and mathbf1_n is the vector of length n containing ones.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#ManifoldsBase.retract-Tuple{MultinomialSymmetric, Any, Any, ProjectionRetraction}","page":"Multinomial symmetric matrices","title":"ManifoldsBase.retract","text":"retract(M::MultinomialSymmetric, p, X, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting podotexp(Xp) back onto the manifold, where are elementwise multiplication and division, respectively. Similarly, exp refers to the elementwise exponentiation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomialsymmetric.html#Literature","page":"Multinomial symmetric matrices","title":"Literature","text":"","category":"section"},{"location":"manifolds/quotient.html#QuotientManifoldSection","page":"Quotient manifold","title":"Quotient manifold","text":"","category":"section"},{"location":"manifolds/quotient.html","page":"Quotient manifold","title":"Quotient manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/QuotientManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/quotient.html#Manifolds.IsQuotientManifold","page":"Quotient manifold","title":"Manifolds.IsQuotientManifold","text":"IsQuotientManifold <: AbstractTrait\n\nSpecify that a certain decorated manifold is a quotient manifold in the sense that it provides implicitly (or explicitly through QuotientManifold properties of a quotient manifold.\n\nSee QuotientManifold for more details.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/quotient.html#Manifolds.QuotientManifold","page":"Quotient manifold","title":"Manifolds.QuotientManifold","text":"QuotientManifold{M <: AbstractManifold{𝔽}, N} <: AbstractManifold{𝔽}\n\nEquip a manifold mathcal M explicitly with the property of being a quotient manifold.\n\nA manifold mathcal M is then a a quotient manifold of another manifold mathcal N, i.e. for an equivalence relation on mathcal N we have\n\n mathcal M = mathcal N = bigl p p mathcal N bigr\n\nwhere p q mathcal N q p denotes the equivalence class containing p. For more details see Subsection 3.4.1[AbsilMahonySepulchre2008].\n\nThis manifold type models an explicit quotient structure. This should be done if either the default implementation of mathcal M uses another representation different from the quotient structure or if it provides a (default) quotient structure that is different from the one introduced here.\n\nFields\n\nmanifold – the manifold mathcal M in the introduction above.\ntotal_space – the manifold mathcal N in the introduction above.\n\nConstructor\n\nQuotientManifold(M,N)\n\nCreate a manifold where M is the quotient manifold and Nis its total space.\n\n[AbsilMahonySepulchre2008]: Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access\n\n\n\n\n\n","category":"type"},{"location":"manifolds/quotient.html#Provided-functions","page":"Quotient manifold","title":"Provided functions","text":"","category":"section"},{"location":"manifolds/quotient.html","page":"Quotient manifold","title":"Quotient manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/QuotientManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/quotient.html#Manifolds.canonical_project!-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.canonical_project!","text":"canonical_project!(M, q, p)\n\nCompute the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold in place of q.\n\nSee canonical_project for more details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.canonical_project-Tuple{AbstractManifold, Any}","page":"Quotient manifold","title":"Manifolds.canonical_project","text":"canonical_project(M, p)\n\nCompute the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection π from the total space mathcal N onto mathcal M given by\n\n π = π_mathcal N mathcal M mathcal N mathcal M p π_mathcal N mathcal M(p) = p\n\nin other words, this function implicitly assumes, that the total space mathcal N is given, for example explicitly when M is a QuotientManifold and p is a point on N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.differential_canonical_project!-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.differential_canonical_project!","text":"differential_canonical_project!(M, Y, p, X)\n\nCompute the differential of the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold. See differential_canonical_project for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.differential_canonical_project-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.differential_canonical_project","text":"differential_canonical_project(M, p, X)\n\nCompute the differential of the canonical projection π on a manifold mathcal M that IsQuotientManifold, e.g. a QuotientManifold. The canonical (or natural) projection π from the total space mathcal N onto mathcal M, such that its differential\n\n Dπ(p) T_pmathcal N T_π(p)mathcal M\n\nwhere again the total space might be implicitly assumed, or explicitly when using a QuotientManifold M. So here p is a point on N and X is from T_pmathcal N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.get_orbit_action-Tuple{AbstractManifold}","page":"Quotient manifold","title":"Manifolds.get_orbit_action","text":"get_orbit_action(M::AbstractDecoratorManifold)\n\nReturn the group action that generates the orbit of an equivalence class of the quotient manifold M for which equivalence classes are orbits of an action of a Lie group. For the case that\n\nmathcal M = mathcal N mathcal O\n\nwhere mathcal O is a Lie group with its group action generating the orbit.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.get_total_space-Tuple{AbstractManifold}","page":"Quotient manifold","title":"Manifolds.get_total_space","text":"get_total_space(M::AbstractDecoratorManifold)\n\nReturn the total space of a manifold that IsQuotientManifold, e.g. a QuotientManifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.horizontal_component-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.horizontal_component","text":"horizontal_component(N::AbstractManifold, p, X)\n\nCompute the horizontal component of tangent vector X at point p in the total space of quotient manifold N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.horizontal_lift!-Tuple{AbstractManifold, Any, Any, Any}","page":"Quotient manifold","title":"Manifolds.horizontal_lift!","text":"horizontal_lift!(N, Y, q, X)\nhorizontal_lift!(QuotientManifold{M,N}, Y, p, X)\n\nCompute the horizontal_lift of X from T_pmathcal M, p=π(q). to `T_q\\mathcal N in place of Y.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.horizontal_lift-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.horizontal_lift","text":"horizontal_lift(N::AbstractManifold, q, X)\nhorizontal_lift(::QuotientManifold{𝔽,MT<:AbstractManifold{𝔽},NT<:AbstractManifold}, p, X) where {𝔽}\n\nGiven a point q in total space of quotient manifold N such that p=π(q) is a point on a quotient manifold M (implicitly given for the first case) and a tangent vector X this method computes a tangent vector Y on the horizontal space of T_qmathcal N, i.e. the subspace that is orthogonal to the kernel of Dπ(q).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/quotient.html#Manifolds.vertical_component-Tuple{AbstractManifold, Any, Any}","page":"Quotient manifold","title":"Manifolds.vertical_component","text":"vertical_component(N::AbstractManifold, p, X)\n\nCompute the vertical component of tangent vector X at point p in the total space of quotient manifold N.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#Centered-matrices","page":"Centered matrices","title":"Centered matrices","text":"","category":"section"},{"location":"manifolds/centeredmatrices.html","page":"Centered matrices","title":"Centered matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/CenteredMatrices.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/centeredmatrices.html#Manifolds.CenteredMatrices","page":"Centered matrices","title":"Manifolds.CenteredMatrices","text":"CenteredMatrices{m,n,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe manifold of m n real-valued or complex-valued matrices whose columns sum to zero, i.e.\n\nbigl p 𝔽^m n big 1 1 * p = 0 0 bigr\n\nwhere 𝔽 ℝℂ.\n\nConstructor\n\nCenteredMatrices(m, n[, field=ℝ])\n\nGenerate the manifold of m-by-n (field-valued) matrices whose columns sum to zero.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{CenteredMatrices{m, n, 𝔽}, Any}} where {m, n, 𝔽}","page":"Centered matrices","title":"ManifoldsBase.check_point","text":"check_point(M::CenteredMatrices{m,n,𝔽}, p; kwargs...)\n\nCheck whether the matrix is a valid point on the CenteredMatrices M, i.e. is an m-by-n matrix whose columns sum to zero.\n\nThe tolerance for the column sums of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{CenteredMatrices{m, n, 𝔽}, Any, Any}} where {m, n, 𝔽}","page":"Centered matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::CenteredMatrices{m,n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the CenteredMatrices M, i.e. that X is a matrix of size (m, n) whose columns sum to zero and its values are from the correct AbstractNumbers. The tolerance for the column sums of p and X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.is_flat-Tuple{CenteredMatrices}","page":"Centered matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::CenteredMatrices)\n\nReturn true. CenteredMatrices is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.manifold_dimension-Union{Tuple{CenteredMatrices{m, n, 𝔽}}, Tuple{𝔽}, Tuple{n}, Tuple{m}} where {m, n, 𝔽}","page":"Centered matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::CenteredMatrices{m,n,𝔽})\n\nReturn the manifold dimension of the CenteredMatrices m-by-n matrix M over the number system 𝔽, i.e.\n\ndim(mathcal M) = (m*n - n) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.project-Tuple{CenteredMatrices, Any, Any}","page":"Centered matrices","title":"ManifoldsBase.project","text":"project(M::CenteredMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the CenteredMatrices M, i.e.\n\noperatornameproj_p(X) = X - beginbmatrix\n1\n\n1\nendbmatrix * c_1 dots c_n\n\nwhere c_i = frac1msum_j=1^m x_ji for i = 1 dots n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/centeredmatrices.html#ManifoldsBase.project-Tuple{CenteredMatrices, Any}","page":"Centered matrices","title":"ManifoldsBase.project","text":"project(M::CenteredMatrices, p)\n\nProjects p from the embedding onto the CenteredMatrices M, i.e.\n\noperatornameproj_mathcal M(p) = p - beginbmatrix\n1\n\n1\nendbmatrix * c_1 dots c_n\n\nwhere c_i = frac1msum_j=1^m p_ji for i = 1 dots n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#GroupManifoldSection","page":"Group manifold","title":"Group manifolds and actions","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Lie groups, groups that are Riemannian manifolds with a smooth binary group operation AbstractGroupOperation, are implemented as AbstractDecoratorManifold and specifying the group operation using the IsGroupManifold or by decorating an existing manifold with a group operation using GroupManifold.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"The common addition and multiplication group operations of AdditionOperation and MultiplicationOperation are provided, though their behavior may be customized for a specific group.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"There are short introductions at the beginning of each subsection. They briefly mention what is available with links to more detailed descriptions.","category":"page"},{"location":"manifolds/group.html#Contents","page":"Group manifold","title":"Contents","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Pages = [\"group.md\"]\nDepth = 3","category":"page"},{"location":"manifolds/group.html#Groups","page":"Group manifold","title":"Groups","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"The following operations are available for group manifolds:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Identity: an allocation-free representation of the identity element of the group.\ninv: get the inverse of a given element.\ncompose: compose two given elements of a group.\nidentity_element get the identity element of the group, in the representation used by other points from the group.","category":"page"},{"location":"manifolds/group.html#Group-manifold","page":"Group manifold","title":"Group manifold","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"GroupManifold adds a group structure to the wrapped manifold. It does not affect metric (or connection) structure of the wrapped manifold, however it can to be further wrapped in MetricManifold to get invariant metrics, or in a ConnectionManifold to equip it with a Cartan-Schouten connection.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/group.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AbstractGroupOperation","page":"Group manifold","title":"Manifolds.AbstractGroupOperation","text":"AbstractGroupOperation\n\nAbstract type for smooth binary operations on elements of a Lie group mathcalG:\n\n mathcalG mathcalG mathcalG\n\nAn operation can be either defined for a specific group manifold over number system 𝔽 or in general, by defining for an operation Op the following methods:\n\nidentity_element!(::AbstractDecoratorManifold, q, q)\ninv!(::AbstractDecoratorManifold, q, p)\n_compose!(::AbstractDecoratorManifold, x, p, q)\n\nNote that a manifold is connected with an operation by wrapping it with a decorator, AbstractDecoratorManifold using the IsGroupManifold to specify the operation. For a concrete case the concrete wrapper GroupManifold can be used.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.AbstractInvarianceTrait","page":"Group manifold","title":"Manifolds.AbstractInvarianceTrait","text":"AbstractInvarianceTrait <: AbstractTrait\n\nA common supertype for anz AbstractTrait related to metric invariance\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.ActionDirection","page":"Group manifold","title":"Manifolds.ActionDirection","text":"ActionDirection\n\nDirection of action on a manifold, either LeftForwardAction, LeftBackwardAction, RightForwardAction or RightBackwardAction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.ForwardBackwardSwitch","page":"Group manifold","title":"Manifolds.ForwardBackwardSwitch","text":"struct ForwardBackwardSwitch <: AbstractDirectionSwitchType end\n\nSwitch between forward and backward action, maintaining left/right direction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.GroupExponentialRetraction","page":"Group manifold","title":"Manifolds.GroupExponentialRetraction","text":"GroupExponentialRetraction{D<:ActionDirection} <: AbstractRetractionMethod\n\nRetraction using the group exponential exp_lie \"translated\" to any point on the manifold.\n\nFor more details, see retract.\n\nConstructor\n\nGroupExponentialRetraction(conv::ActionDirection = LeftForwardAction())\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.GroupLogarithmicInverseRetraction","page":"Group manifold","title":"Manifolds.GroupLogarithmicInverseRetraction","text":"GroupLogarithmicInverseRetraction{D<:ActionDirection} <: AbstractInverseRetractionMethod\n\nRetraction using the group logarithm log_lie \"translated\" to any point on the manifold.\n\nFor more details, see inverse_retract.\n\nConstructor\n\nGroupLogarithmicInverseRetraction(conv::ActionDirection = LeftForwardAction())\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.HasBiinvariantMetric","page":"Group manifold","title":"Manifolds.HasBiinvariantMetric","text":"HasBiinvariantMetric <: AbstractInvarianceTrait\n\nSpecify that a certain the metric of a GroupManifold is a bi-invariant metric\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.HasLeftInvariantMetric","page":"Group manifold","title":"Manifolds.HasLeftInvariantMetric","text":"HasLeftInvariantMetric <: AbstractInvarianceTrait\n\nSpecify that a certain the metric of a GroupManifold is a left-invariant metric\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.HasRightInvariantMetric","page":"Group manifold","title":"Manifolds.HasRightInvariantMetric","text":"HasRightInvariantMetric <: AbstractInvarianceTrait\n\nSpecify that a certain the metric of a GroupManifold is a right-invariant metric\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.Identity","page":"Group manifold","title":"Manifolds.Identity","text":"Identity{O<:AbstractGroupOperation}\n\nRepresent the group identity element e mathcalG on a Lie group mathcal G with AbstractGroupOperation of type O.\n\nSimilar to the philosophy that points are agnostic of their group at hand, the identity does not store the group g it belongs to. However it depends on the type of the AbstractGroupOperation used.\n\nSee also identity_element on how to obtain the corresponding AbstractManifoldPoint or array representation.\n\nConstructors\n\nIdentity(G::AbstractDecoratorManifold{𝔽})\nIdentity(o::O)\nIdentity(::Type{O})\n\ncreate the identity of the corresponding subtype O<:AbstractGroupOperation\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.IsGroupManifold","page":"Group manifold","title":"Manifolds.IsGroupManifold","text":"IsGroupManifold{O<:AbstractGroupOperation} <: AbstractTrait\n\nA trait to declare an AbstractManifold as a manifold with group structure with operation of type O.\n\nUsing this trait you can turn a manifold that you implement implictly into a Lie group. If you wish to decorate an existing manifold with one (or different) AbstractGroupActions, see GroupManifold.\n\nConstructor\n\nIsGroupManifold(op)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.LeftBackwardAction","page":"Group manifold","title":"Manifolds.LeftBackwardAction","text":"LeftBackwardAction()\n\nLeft action of a group on a manifold. For an action α X G X it is characterized by \n\nα(α(x h) g) = α(x gh)\n\nfor all g h G and x X.\n\nNote that a left action may still act from the right side in an expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.LeftForwardAction","page":"Group manifold","title":"Manifolds.LeftForwardAction","text":"LeftForwardAction()\n\nLeft action of a group on a manifold. For an action α G X X it is characterized by \n\nα(g α(h x)) = α(gh x)\n\nfor all g h G and x X.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.LeftRightSwitch","page":"Group manifold","title":"Manifolds.LeftRightSwitch","text":"struct LeftRightSwitch <: AbstractDirectionSwitchType end\n\nSwitch between left and right action, maintaining forward/backward direction.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RightBackwardAction","page":"Group manifold","title":"Manifolds.RightBackwardAction","text":"RightBackwardAction()\n\nRight action of a group on a manifold. For an action α X G X it is characterized by \n\nα(α(x h) g) = α(x hg)\n\nfor all g h G and x X.\n\nNote that a right action may still act from the left side in an expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RightForwardAction","page":"Group manifold","title":"Manifolds.RightForwardAction","text":"RightForwardAction()\n\nRight action of a group on a manifold. For an action α G X X it is characterized by \n\nα(g α(h x)) = α(hg x)\n\nfor all g h G and x X.\n\nNote that a right action may still act from the left side in an expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.SimultaneousSwitch","page":"Group manifold","title":"Manifolds.SimultaneousSwitch","text":"struct LeftRightSwitch <: AbstractDirectionSwitchType end\n\nSimultaneously switch left/right and forward/backward directions.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.inv-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Base.inv","text":"inv(G::AbstractDecoratorManifold, p)\n\nInverse p^-1 mathcalG of an element p mathcalG, such that p circ p^-1 = p^-1 circ p = e mathcalG, where e is the Identity element of mathcalG.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.adjoint_action-Tuple{AbstractDecoratorManifold, Any, Any}","page":"Group manifold","title":"Manifolds.adjoint_action","text":"adjoint_action(G::AbstractDecoratorManifold, p, X)\n\nAdjoint action of the element p of the Lie group G on the element X of the corresponding Lie algebra.\n\nIt is defined as the differential of the group authomorphism Ψ_p(q) = pqp¹ at the identity of G.\n\nThe formula reads\n\noperatornameAd_p(X) = dΨ_p(e)X\n\nwhere e is the identity element of G.\n\nNote that the adjoint representation of a Lie group isn't generally faithful. Notably the adjoint representation of SO(2) is trivial.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.compose-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.compose","text":"compose(G::AbstractDecoratorManifold, p, q)\n\nCompose elements pq mathcalG using the group operation p circ q.\n\nFor implementing composition on a new group manifold, please overload _compose instead so that methods with Identity arguments are not ambiguous.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{AbstractManifold, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G, X)\nexp_lie!(G, q, X)\n\nCompute the group exponential of the Lie algebra element X. It is equivalent to the exponential map defined by the CartanSchoutenMinus connection.\n\nGiven an element X 𝔤 = T_e mathcalG, where e is the Identity element of the group mathcalG, and 𝔤 is its Lie algebra, the group exponential is the map\n\nexp 𝔤 mathcalG\n\nsuch that for ts ℝ, γ(t) = exp (t X) defines a one-parameter subgroup with the following properties. Note that one-parameter subgroups are commutative (see [Suhubi2013], section 3.5), even if the Lie group itself is not commutative.\n\nbeginaligned\nγ(t) = γ(-t)^-1\nγ(t + s) = γ(t) circ γ(s) = γ(s) circ γ(t)\nγ(0) = e\nlim_t 0 fracddt γ(t) = X\nendaligned\n\nnote: Note\nIn general, the group exponential map is distinct from the Riemannian exponential map exp.\n\nFor example for the MultiplicationOperation and either Number or AbstractMatrix the Lie exponential is the numeric/matrix exponential.\n\nexp X = operatornameExp X = sum_n=0^ frac1n X^n\n\nSince this function also depends on the group operation, make sure to implement the corresponding trait version exp_lie(::TraitList{<:IsGroupManifold}, G, X).\n\n[Suhubi2013]: E. Suhubi, Exterior Analysis: Using Applications of Differential Forms, 1st edition. Amsterdam: Academic Press, 2013.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.get_coordinates_lie-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractManifold, Any, AbstractBasis}","page":"Group manifold","title":"Manifolds.get_coordinates_lie","text":"get_coordinates_lie(G::AbstractManifold, X, B::AbstractBasis)\n\nGet the coordinates of an element X from the Lie algebra og G with respect to a basis B. This is similar to calling get_coordinates at the p=Identity(G).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.get_vector_lie-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractManifold, Any, AbstractBasis}","page":"Group manifold","title":"Manifolds.get_vector_lie","text":"get_vector_lie(G::AbstractDecoratorManifold, a, B::AbstractBasis)\n\nReconstruct a tangent vector from the Lie algebra of G from cooordinates a of a basis B. This is similar to calling get_vector at the p=Identity(G).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.identity_element-Tuple{AbstractDecoratorManifold, Any}","page":"Group manifold","title":"Manifolds.identity_element","text":"identity_element(G::AbstractDecoratorManifold, p)\n\nReturn a point representation of the Identity on the IsGroupManifold G, where p indicates the type to represent the identity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.identity_element-Tuple{AbstractDecoratorManifold}","page":"Group manifold","title":"Manifolds.identity_element","text":"identity_element(G)\n\nReturn a point representation of the Identity on the IsGroupManifold G. By default this representation is the default array or number representation. It should return the corresponding default representation of e as a point on G if points are not represented by arrays.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_translate-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.inverse_translate","text":"inverse_translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction())\n\nInverse translate group element q by p with the inverse translation τ_p^-1 with the specified convention, either left (L_p^-1) or right (R_p^-1), defined as\n\nbeginaligned\nL_p^-1 q p^-1 circ q\nR_p^-1 q q circ p^-1\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_translate_diff-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.inverse_translate_diff","text":"inverse_translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())\n\nFor group elements p q mathcalG and tangent vector X T_q mathcalG, compute the action on X of the differential of the inverse translation τ_p by p, with the specified left or right convention. The differential transports vectors:\n\n(mathrmdτ_p^-1)_q T_q mathcalG T_τ_p^-1 q mathcalG\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.is_group_manifold-Tuple{AbstractManifold, AbstractGroupOperation}","page":"Group manifold","title":"Manifolds.is_group_manifold","text":"is_group_manifold(G::GroupManifold)\nis_group_manifoldd(G::AbstractManifold, o::AbstractGroupOperation)\n\nreturns whether an AbstractDecoratorManifold is a group manifold with AbstractGroupOperation o. For a GroupManifold G this checks whether the right operations is stored within G.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.is_identity-Tuple{AbstractDecoratorManifold, Any}","page":"Group manifold","title":"Manifolds.is_identity","text":"is_identity(G::AbstractDecoratorManifold, q; kwargs)\n\nCheck whether q is the identity on the IsGroupManifold G, i.e. it is either the Identity{O} with the corresponding AbstractGroupOperation O, or (approximately) the correct point representation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.lie_bracket-Tuple{AbstractDecoratorManifold, Any, Any}","page":"Group manifold","title":"Manifolds.lie_bracket","text":"lie_bracket(G::AbstractDecoratorManifold, X, Y)\n\nLie bracket between elements X and Y of the Lie algebra corresponding to the Lie group G, cf. IsGroupManifold.\n\nThis can be used to compute the adjoint representation of a Lie algebra. Note that this representation isn't generally faithful. Notably the adjoint representation of 𝔰𝔬(2) is trivial.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{AbstractDecoratorManifold, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G, q)\nlog_lie!(G, X, q)\n\nCompute the Lie group logarithm of the Lie group element q. It is equivalent to the logarithmic map defined by the CartanSchoutenMinus connection.\n\nGiven an element q mathcalG, compute the right inverse of the group exponential map exp_lie, that is, the element log q = X 𝔤 = T_e mathcalG, such that q = exp X\n\nnote: Note\nIn general, the group logarithm map is distinct from the Riemannian logarithm map log.For matrix Lie groups this is equal to the (matrix) logarithm:\n\nlog q = operatornameLog q = sum_n=1^ frac(-1)^n+1n (q - e)^n\n\nwhere e here is the Identity element, that is, 1 for numeric q or the identity matrix I_m for matrix q ℝ^m m.\n\nSince this function also depends on the group operation, make sure to implement either\n\n_log_lie(G, q) and _log_lie!(G, X, q) for the points not being the Identity\nthe trait version log_lie(::TraitList{<:IsGroupManifold}, G, e), log_lie(::TraitList{<:IsGroupManifold}, G, X, e) for own implementations of the identity case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.switch_direction-Tuple{ActionDirection, Manifolds.AbstractDirectionSwitchType}","page":"Group manifold","title":"Manifolds.switch_direction","text":"switch_direction(::ActionDirection, type::AbstractDirectionSwitchType = SimultaneousSwitch())\n\nReturns type of action between left and right, forward or backward, or both at the same type, depending on type, which is either of LeftRightSwitch, ForwardBackwardSwitch or SimultaneousSwitch.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.translate","text":"translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirection=LeftForwardAction()])\n\nTranslate group element q by p with the translation τ_p with the specified convention, either left forward (L_p), left backward (R_p), right backward (R_p) or right forward (L_p), defined as\n\nbeginaligned\nL_p q p circ q\nL_p q p^-1 circ q\nR_p q q circ p\nR_p q q circ p^-1\nendaligned\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate_diff-Tuple{AbstractDecoratorManifold, Vararg{Any}}","page":"Group manifold","title":"Manifolds.translate_diff","text":"translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirection=LeftForwardAction())\n\nFor group elements p q mathcalG and tangent vector X T_q mathcalG, compute the action of the differential of the translation τ_p by p on X, with the specified left or right convention. The differential transports vectors:\n\n(mathrmdτ_p)_q T_q mathcalG T_τ_p q mathcalG\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.hat-Union{Tuple{O}, Tuple{ManifoldsBase.TraitList{IsGroupManifold{O}}, AbstractDecoratorManifold, Identity{O}, Any}} where O<:AbstractGroupOperation","page":"Group manifold","title":"ManifoldsBase.hat","text":"hat(M::AbstractDecoratorManifold{𝔽,O}, ::Identity{O}, Xⁱ) where {𝔽,O<:AbstractGroupOperation}\n\nGiven a basis e_i on the tangent space at a the Identity and tangent component vector X^i, compute the equivalent vector representation ``X=X^i e_i**, where Einstein summation notation is used:\n\n X^i X^i e_i\n\nFor array manifolds, this converts a vector representation of the tangent vector to an array representation. The vee map is the hat map's inverse.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.inverse_retract-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractDecoratorManifold, Any, Any, Manifolds.GroupLogarithmicInverseRetraction}","page":"Group manifold","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(\n G::AbstractDecoratorManifold,\n p,\n X,\n method::GroupLogarithmicInverseRetraction{<:ActionDirection},\n)\n\nCompute the inverse retraction using the group logarithm log_lie \"translated\" to any point on the manifold. With a group translation (translate) τ_p in a specified direction, the retraction is\n\noperatornameretr_p^-1 = (mathrmdτ_p)_e circ log circ τ_p^-1\n\nwhere log is the group logarithm (log_lie), and (mathrmdτ_p)_e is the action of the differential of translation τ_p evaluated at the identity element e (see translate_diff).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.retract-Tuple{ManifoldsBase.TraitList{<:IsGroupManifold}, AbstractDecoratorManifold, Any, Any, Manifolds.GroupExponentialRetraction}","page":"Group manifold","title":"ManifoldsBase.retract","text":"retract(\n G::AbstractDecoratorManifold,\n p,\n X,\n method::GroupExponentialRetraction{<:ActionDirection},\n)\n\nCompute the retraction using the group exponential exp_lie \"translated\" to any point on the manifold. With a group translation (translate) τ_p in a specified direction, the retraction is\n\noperatornameretr_p = τ_p circ exp circ (mathrmdτ_p^-1)_p\n\nwhere exp is the group exponential (exp_lie), and (mathrmdτ_p^-1)_p is the action of the differential of inverse translation τ_p^-1 evaluated at p (see inverse_translate_diff).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.vee-Union{Tuple{O}, Tuple{ManifoldsBase.TraitList{IsGroupManifold{O}}, AbstractDecoratorManifold, Identity{O}, Any}} where O<:AbstractGroupOperation","page":"Group manifold","title":"ManifoldsBase.vee","text":"vee(M::AbstractManifold, p, X)\n\nGiven a basis e_i on the tangent space at a point p and tangent vector X, compute the vector components X^i, such that X = X^i e_i, where Einstein summation notation is used:\n\nvee X^i e_i X^i\n\nFor array manifolds, this converts an array representation of the tangent vector to a vector representation. The hat map is the vee map's inverse.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#GroupManifold","page":"Group manifold","title":"GroupManifold","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"As a concrete wrapper for manifolds (e.g. when the manifold per se is a group manifold but another group structure should be implemented), there is the GroupManifold","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/GroupManifold.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GroupManifold","page":"Group manifold","title":"Manifolds.GroupManifold","text":"GroupManifold{𝔽,M<:AbstractManifold{𝔽},O<:AbstractGroupOperation} <: AbstractDecoratorManifold{𝔽}\n\nDecorator for a smooth manifold that equips the manifold with a group operation, thus making it a Lie group. See IsGroupManifold for more details.\n\nGroup manifolds by default forward metric-related operations to the wrapped manifold.\n\nConstructor\n\nGroupManifold(manifold, op)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Generic-Operations","page":"Group manifold","title":"Generic Operations","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"For groups based on an addition operation or a group operation, several default implementations are provided.","category":"page"},{"location":"manifolds/group.html#Addition-Operation","page":"Group manifold","title":"Addition Operation","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/addition_operation.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AdditionOperation","page":"Group manifold","title":"Manifolds.AdditionOperation","text":"AdditionOperation <: AbstractGroupOperation\n\nGroup operation that consists of simple addition.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Multiplication-Operation","page":"Group manifold","title":"Multiplication Operation","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/multiplication_operation.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.MultiplicationOperation","page":"Group manifold","title":"Manifolds.MultiplicationOperation","text":"MultiplicationOperation <: AbstractGroupOperation\n\nGroup operation that consists of multiplication.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Circle-group","page":"Group manifold","title":"Circle group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/circle_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.CircleGroup","page":"Group manifold","title":"Manifolds.CircleGroup","text":"CircleGroup <: GroupManifold{Circle{ℂ},MultiplicationOperation}\n\nThe circle group is the complex circle (Circle(ℂ)) equipped with the group operation of complex multiplication (MultiplicationOperation).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RealCircleGroup","page":"Group manifold","title":"Manifolds.RealCircleGroup","text":"RealCircleGroup <: GroupManifold{Circle{ℝ},AdditionOperation}\n\nThe real circle group is the real circle (Circle(ℝ)) equipped with the group operation of addition (AdditionOperation).\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#General-linear-group","page":"Group manifold","title":"General linear group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/general_linear.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GeneralLinear","page":"Group manifold","title":"Manifolds.GeneralLinear","text":"GeneralLinear{n,𝔽} <:\n AbstractDecoratorManifold{𝔽}\n\nThe general linear group, that is, the group of all invertible matrices in 𝔽^nn.\n\nThe default metric is the left-mathrmGL(n)-right-mathrmO(n)-invariant metric whose inner product is\n\nX_pY_p_p = p^-1X_pp^-1Y_p_mathrmF = X_e Y_e_mathrmF\n\nwhere X_p Y_p T_p mathrmGL(n 𝔽), X_e = p^-1X_p 𝔤𝔩(n) = T_e mathrmGL(n 𝔽) = 𝔽^nn is the corresponding vector in the Lie algebra, and _mathrmF denotes the Frobenius inner product.\n\nBy default, tangent vectors X_p are represented with their corresponding Lie algebra vectors X_e = p^-1X_p.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.exp-Tuple{GeneralLinear, Any, Any}","page":"Group manifold","title":"Base.exp","text":"exp(G::GeneralLinear, p, X)\n\nCompute the exponential map on the GeneralLinear group.\n\nThe exponential map is\n\nexp_p colon X p operatornameExp(X^mathrmH) operatornameExp(X - X^mathrmH)\n\nwhere operatornameExp() denotes the matrix exponential, and ^mathrmH is the conjugate transpose. [AndruchowLarotondaRechtVarela2014][MartinNeff2016]\n\n[AndruchowLarotondaRechtVarela2014]: Andruchow E., Larotonda G., Recht L., and Varela A.: “The left invariant metric in the general linear group”, Journal of Geometry and Physics 86, pp. 241-257, 2014. doi: 10.1016/j.geomphys.2014.08.009, arXiv: 1109.0520v1.\n\n[MartinNeff2016]: Martin, R. J. and Neff, P.: “Minimal geodesics on GL(n) for left-invariant, right-O(n)-invariant Riemannian metrics”, Journal of Geometric Mechanics 8(3), pp. 323-357, 2016. doi: 10.3934/jgm.2016010, arXiv: 1409.7849v2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.log-Tuple{GeneralLinear, Any, Any}","page":"Group manifold","title":"Base.log","text":"log(G::GeneralLinear, p, q)\n\nCompute the logarithmic map on the GeneralLinear(n) group.\n\nThe algorithm proceeds in two stages. First, the point r = p^-1 q is projected to the nearest element (under the Frobenius norm) of the direct product subgroup mathrmO(n) S^+, whose logarithmic map is exactly computed using the matrix logarithm. This initial tangent vector is then refined using the NLSolveInverseRetraction.\n\nFor GeneralLinear(n, ℂ), the logarithmic map is instead computed on the realified supergroup GeneralLinear(2n) and the resulting tangent vector is then complexified.\n\nNote that this implementation is experimental.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.rand-Tuple{GeneralLinear}","page":"Group manifold","title":"Base.rand","text":"Random.rand(G::GeneralLinear; vector_at=nothing, kwargs...)\n\nIf vector_at is nothing, return a random point on the GeneralLinear group G by using rand in the embedding.\n\nIf vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the GeneralLinear by using by using rand in the embedding.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Heisenberg-group","page":"Group manifold","title":"Heisenberg group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/heisenberg.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.HeisenbergGroup","page":"Group manifold","title":"Manifolds.HeisenbergGroup","text":"HeisenbergGroup{n} <: AbstractDecoratorManifold{ℝ}\n\nHeisenberg group HeisenbergGroup(n) is the group of (n+2) (n+2) matrices [BinzPods2008]\n\nbeginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\nwhere I_n is the nn unit matrix, mathbfa is a row vector of length n, mathbfb is a column vector of length n and c is a real number. The group operation is matrix multiplication.\n\nThe left-invariant metric on the manifold is used.\n\n[BinzPods2008]: E. Binz and S. Pods, The Geometry of Heisenberg Groups: With Applications in Signal Theory, Optics, Quantization, and Field Quantization. American Mathematical Soc., 2008.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.exp-Tuple{HeisenbergGroup, Any, Any}","page":"Group manifold","title":"Base.exp","text":"exp(M::HeisenbergGroup, p, X)\n\nExponential map on the HeisenbergGroup M with the left-invariant metric. The expression reads\n\nexp_beginbmatrix 1 mathbfa_p c_p \nmathbf0 I_n mathbfb_p \n0 mathbf0 1 endbmatrixleft(beginbmatrix 0 mathbfa_X c_X \nmathbf0 0_n mathbfb_X \n0 mathbf0 0 endbmatrixright) =\nbeginbmatrix 1 mathbfa_p + mathbfa_X c_p + c_X + mathbfa_Xmathbfb_X2 + mathbfa_pmathbfb_X \nmathbf0 I_n mathbfb_p + mathbfb_X \n0 mathbf0 1 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.log-Tuple{HeisenbergGroup, Any, Any}","page":"Group manifold","title":"Base.log","text":"log(G::HeisenbergGroup, p, q)\n\nCompute the logarithmic map on the HeisenbergGroup group. The formula reads\n\nlog_beginbmatrix 1 mathbfa_p c_p \nmathbf0 I_n mathbfb_p \n0 mathbf0 1 endbmatrixleft(beginbmatrix 1 mathbfa_q c_q \nmathbf0 I_n mathbfb_q \n0 mathbf0 1 endbmatrixright) =\nbeginbmatrix 0 mathbfa_q - mathbfa_p c_q - c_p + mathbfa_pmathbfb_p - mathbfa_qmathbfb_q - (mathbfa_q - mathbfa_p)(mathbfb_q - mathbfb_p) 2 \nmathbf0 0_n mathbfb_q - mathbfb_p \n0 mathbf0 0 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.rand-Tuple{HeisenbergGroup}","page":"Group manifold","title":"Base.rand","text":"Random.rand(M::HeisenbergGroup; vector_at = nothing, σ::Real=1.0)\n\nIf vector_at is nothing, return a random point on the HeisenbergGroup M by sampling elements of the first row and the last column from the normal distribution with mean 0 and standard deviation σ.\n\nIf vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the HeisenbergGroup by using a normal distribution with mean 0 and standard deviation σ.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{HeisenbergGroup, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(M::HeisenbergGroup, X)\n\nLie group exponential for the HeisenbergGroup M of the vector X. The formula reads\n\nexpleft(beginbmatrix 0 mathbfa c \nmathbf0 0_n mathbfb \n0 mathbf0 0 endbmatrixright) = beginbmatrix 1 mathbfa c + mathbfamathbfb2 \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{HeisenbergGroup, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(M::HeisenbergGroup, p)\n\nLie group logarithm for the HeisenbergGroup M of the point p. The formula reads\n\nlogleft(beginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrixright) =\nbeginbmatrix 0 mathbfa c - mathbfamathbfb2 \nmathbf0 0_n mathbfb \n0 mathbf0 0 endbmatrix\n\nwhere I_n is the nn identity matrix, 0_n is the nn zero matrix and mathbfamathbfb is dot product of vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.get_coordinates-Tuple{HeisenbergGroup, Any, Any, DefaultOrthonormalBasis{ℝ, ManifoldsBase.TangentSpaceType}}","page":"Group manifold","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(M::HeisenbergGroup, p, X, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})\n\nGet coordinates of tangent vector X at point p from the HeisenbergGroup M. Given a matrix\n\nbeginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\nthe coordinates are concatenated vectors mathbfa, mathbfb, and number c.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.get_vector-Tuple{HeisenbergGroup, Any, Any, DefaultOrthonormalBasis{ℝ, ManifoldsBase.TangentSpaceType}}","page":"Group manifold","title":"ManifoldsBase.get_vector","text":"get_vector(M::HeisenbergGroup, p, Xⁱ, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})\n\nGet tangent vector with coordinates Xⁱ at point p from the HeisenbergGroup M. Given a vector of coordinates beginbmatrixmathbba mathbbb cendbmatrix the tangent vector is equal to\n\nbeginbmatrix 1 mathbfa c \nmathbf0 I_n mathbfb \n0 mathbf0 1 endbmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.injectivity_radius-Tuple{HeisenbergGroup}","page":"Group manifold","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::HeisenbergGroup)\n\nReturn the injectivity radius on the HeisenbergGroup M, which is .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Union{Tuple{n}, Tuple{HeisenbergGroup{n}, Any, Any}} where n","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::HeisenbergGroup{n}, p, X)\n\nProject a matrix X in the Euclidean embedding onto the Lie algebra of HeisenbergGroup M. Sets the diagonal elements to 0 and all non-diagonal elements except the first row and the last column to 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Union{Tuple{n}, Tuple{HeisenbergGroup{n}, Any}} where n","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::HeisenbergGroup{n}, p)\n\nProject a matrix p in the Euclidean embedding onto the HeisenbergGroup M. Sets the diagonal elements to 1 and all non-diagonal elements except the first row and the last column to 0.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#(Special)-Orthogonal-and-(Special)-Unitary-group","page":"Group manifold","title":"(Special) Orthogonal and (Special) Unitary group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Since the orthogonal, unitary and special orthogonal and special unitary groups share many common functions, these are also implemented on a common level.","category":"page"},{"location":"manifolds/group.html#Common-functions","page":"Group manifold","title":"Common functions","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/general_unitary_groups.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GeneralUnitaryMultiplicationGroup","page":"Group manifold","title":"Manifolds.GeneralUnitaryMultiplicationGroup","text":"GeneralUnitaryMultiplicationGroup{n,𝔽,M} = GroupManifold{𝔽,M,MultiplicationOperation}\n\nA generic type for Lie groups based on a unitary property and matrix multiplcation, see e.g. Orthogonal, SpecialOrthogonal, Unitary, and SpecialUnitary\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{Manifolds.GeneralUnitaryMultiplicationGroup{2, ℝ}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":" exp_lie(G::Orthogonal{2}, X)\n exp_lie(G::SpecialOrthogonal{2}, X)\n\nCompute the Lie group exponential map on the Orthogonal(2) or SpecialOrthogonal(2) group. Given X = beginpmatrix 0 -θ θ 0 endpmatrix, the group exponential is\n\nexp_e colon X beginpmatrix cos θ -sin θ sin θ cos θ endpmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{Manifolds.GeneralUnitaryMultiplicationGroup{4, ℝ}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":" exp_lie(G::Orthogonal{4}, X)\n exp_lie(G::SpecialOrthogonal{4}, X)\n\nCompute the group exponential map on the Orthogonal(4) or the SpecialOrthogonal group. The algorithm used is a more numerically stable form of those proposed in [Gallier2002], [Andrica2013].\n\n[Gallier2002]: Gallier J.; Xu D.; Computing exponentials of skew-symmetric matrices and logarithms of orthogonal matrices. International Journal of Robotics and Automation (2002), 17(4), pp. 1-11. pdf.\n\n[Andrica2013]: Andrica D.; Rohan R.-A.; Computing the Rodrigues coefficients of the exponential map of the Lie groups of matrices. Balkan Journal of Geometry and Its Applications (2013), 18(2), pp. 1-2. pdf.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Orthogonal-group","page":"Group manifold","title":"Orthogonal group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/orthogonal.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.Orthogonal","page":"Group manifold","title":"Manifolds.Orthogonal","text":"Orthogonal{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,AbsoluteDeterminantOneMatrices}\n\nOrthogonal group mathrmO(n) represented by OrthogonalMatrices.\n\nConstructor\n\nOrthogonal(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Special-orthogonal-group","page":"Group manifold","title":"Special orthogonal group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_orthogonal.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialOrthogonal","page":"Group manifold","title":"Manifolds.SpecialOrthogonal","text":"SpecialOrthogonal{n} <: GroupManifold{ℝ,Rotations{n},MultiplicationOperation}\n\nSpecial orthogonal group mathrmSO(n) represented by rotation matrices, see Rotations.\n\nConstructor\n\nSpecialOrthogonal(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Special-unitary-group","page":"Group manifold","title":"Special unitary group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_unitary.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialUnitary","page":"Group manifold","title":"Manifolds.SpecialUnitary","text":"SpecialUnitary{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}}\n\nThe special unitary group mathrmSU(n) represented by unitary matrices of determinant +1.\n\nThe tangent spaces are of the form\n\nT_pmathrmSU(x) = bigl X in mathbb C^nn big X = pY text where Y = -Y^mathrmH bigr\n\nand we represent tangent vectors by just storing the SkewHermitianMatrices Y, or in other words we represent the tangent spaces employing the Lie algebra mathfraksu(n).\n\nConstructor\n\nSpecialUnitary(n)\n\nGenerate the Lie group of nn unitary matrices with determinant +1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{SpecialUnitary, Vararg{Any}}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(G::SpecialUnitary, p)\n\nProject p to the nearest point on the SpecialUnitary group G.\n\nGiven the singular value decomposition p = U S V^mathrmH, with the singular values sorted in descending order, the projection is\n\noperatornameproj_mathrmSU(n)(p) =\nUoperatornamediagleft11det(U V^mathrmH)right V^mathrmH\n\nThe diagonal matrix ensures that the determinant of the result is +1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Unitary-group","page":"Group manifold","title":"Unitary group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/unitary.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.Unitary","page":"Group manifold","title":"Manifolds.Unitary","text":" Unitary{n,𝔽} = GeneralUnitaryMultiplicationGroup{n,𝔽,AbsoluteDeterminantOneMatrices}\n\nThe group of unitary matrices mathrmU(n 𝔽), either complex (when 𝔽=ℂ) or quaternionic (when 𝔽=ℍ)\n\nThe group consists of all points p 𝔽^n n where p^mathrmHp = pp^mathrmH = I.\n\nThe tangent spaces are if the form\n\nT_pmathrmU(n) = bigl X in 𝔽^nn big X = pY text where Y = -Y^mathrmH bigr\n\nand we represent tangent vectors by just storing the SkewHermitianMatrices Y, or in other words we represent the tangent spaces employing the Lie algebra mathfraku(n 𝔽).\n\nQuaternionic unitary group is isomorphic to the compact symplectic group of the same dimension.\n\nConstructor\n\nUnitary(n, 𝔽::AbstractNumbers=ℂ)\n\nConstruct mathrmU(n 𝔽). See also Orthogonal(n) for the real-valued case.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{Unitary{2, ℂ}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::Unitary{2,ℂ}, X)\n\nCompute the group exponential map on the Unitary(2) group, which is\n\nexp_e colon X e^operatornametr(X) 2 left(cos θ I + fracsin θθ left(X - fracoperatornametr(X)2 Iright)right)\n\nwhere θ = frac12 sqrt4det(X) - operatornametr(X)^2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Power-group","page":"Group manifold","title":"Power group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/power_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.PowerGroup-Tuple{AbstractPowerManifold}","page":"Group manifold","title":"Manifolds.PowerGroup","text":"PowerGroup{𝔽,T} <: GroupManifold{𝔽,<:AbstractPowerManifold{𝔽,M,RPT},ProductOperation}\n\nDecorate a power manifold with a ProductOperation.\n\nConstituent manifold of the power manifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.\n\nConstructor\n\nPowerGroup(manifold::AbstractPowerManifold)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.PowerGroupNested","page":"Group manifold","title":"Manifolds.PowerGroupNested","text":"PowerGroupNested\n\nAlias to PowerGroup with NestedPowerRepresentation representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.PowerGroupNestedReplacing","page":"Group manifold","title":"Manifolds.PowerGroupNestedReplacing","text":"PowerGroupNestedReplacing\n\nAlias to PowerGroup with NestedReplacingPowerRepresentation representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Product-group","page":"Group manifold","title":"Product group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/product_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.ProductGroup-Union{Tuple{ProductManifold{𝔽}}, Tuple{𝔽}} where 𝔽","page":"Group manifold","title":"Manifolds.ProductGroup","text":"ProductGroup{𝔽,T} <: GroupManifold{𝔽,ProductManifold{T},ProductOperation}\n\nDecorate a product manifold with a ProductOperation.\n\nEach submanifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.\n\nConstructor\n\nProductGroup(manifold::ProductManifold)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.ProductOperation","page":"Group manifold","title":"Manifolds.ProductOperation","text":"ProductOperation <: AbstractGroupOperation\n\nDirect product group operation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Semidirect-product-group","page":"Group manifold","title":"Semidirect product group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/semidirect_product_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SemidirectProductGroup-Union{Tuple{𝔽}, Tuple{AbstractDecoratorManifold{𝔽}, AbstractDecoratorManifold{𝔽}, AbstractGroupAction}} where 𝔽","page":"Group manifold","title":"Manifolds.SemidirectProductGroup","text":"SemidirectProductGroup(N::GroupManifold, H::GroupManifold, A::AbstractGroupAction)\n\nA group that is the semidirect product of a normal group mathcalN and a subgroup mathcalH, written mathcalG = mathcalN _θ mathcalH, where θ mathcalH mathcalN mathcalN is an automorphism action of mathcalH on mathcalN. The group mathcalG has the composition rule\n\ng circ g = (n h) circ (n h) = (n circ θ_h(n) h circ h)\n\nand the inverse\n\ng^-1 = (n h)^-1 = (θ_h^-1(n^-1) h^-1)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.SemidirectProductOperation","page":"Group manifold","title":"Manifolds.SemidirectProductOperation","text":"SemidirectProductOperation(action::AbstractGroupAction)\n\nGroup operation of a semidirect product group. The operation consists of the operation opN on a normal subgroup N, the operation opH on a subgroup H, and an automorphism action of elements of H on N. Only the action is stored.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.identity_element-Tuple{SemidirectProductGroup}","page":"Group manifold","title":"Manifolds.identity_element","text":"identity_element(G::SemidirectProductGroup)\n\nGet the identity element of SemidirectProductGroup G. Uses ArrayPartition from RecursiveArrayTools.jl to represent the point.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate_diff-Tuple{SemidirectProductGroup, Any, Any, Any, LeftForwardAction}","page":"Group manifold","title":"Manifolds.translate_diff","text":"translate_diff(G::SemidirectProductGroup, p, q, X, conX::LeftForwardAction)\n\nPerform differential of the left translation on the semidirect product group G.\n\nSince the left translation is defined as (cf. SemidirectProductGroup):\n\nL_(n h) (n h) = ( L_n θ_h(n) L_h h)\n\nthen its differential can be computed as\n\nmathrmdL_(n h)(X_n X_h) = ( mathrmdL_n (mathrmdθ_h(X_n)) mathrmdL_h X_h)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Special-Euclidean-group","page":"Group manifold","title":"Special Euclidean group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_euclidean.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialEuclidean","page":"Group manifold","title":"Manifolds.SpecialEuclidean","text":"SpecialEuclidean(n)\n\nSpecial Euclidean group mathrmSE(n), the group of rigid motions.\n\nmathrmSE(n) is the semidirect product of the TranslationGroup on ℝ^n and SpecialOrthogonal(n)\n\nmathrmSE(n) mathrmT(n) _θ mathrmSO(n)\n\nwhere θ is the canonical action of mathrmSO(n) on mathrmT(n) by vector rotation.\n\nThis constructor is equivalent to calling\n\nTn = TranslationGroup(n)\nSOn = SpecialOrthogonal(n)\nSemidirectProductGroup(Tn, SOn, RotationAction(Tn, SOn))\n\nPoints on mathrmSE(n) may be represented as points on the underlying product manifold mathrmT(n) mathrmSO(n). For group-specific functions, they may also be represented as affine matrices with size (n + 1, n + 1) (see affine_matrix), for which the group operation is MultiplicationOperation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.SpecialEuclideanInGeneralLinear","page":"Group manifold","title":"Manifolds.SpecialEuclideanInGeneralLinear","text":"SpecialEuclideanInGeneralLinear\n\nAn explicit isometric and homomorphic embedding of mathrmSE(n) in mathrmGL(n+1) and 𝔰𝔢(n) in 𝔤𝔩(n+1). Note that this is not a transparently isometric embedding.\n\nConstructor\n\nSpecialEuclideanInGeneralLinear(n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.adjoint_action-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}, LeftForwardAction}}}, Any, TFVector{<:Any, VeeOrthogonalBasis{ℝ}}}","page":"Group manifold","title":"Manifolds.adjoint_action","text":"adjoint_action(::SpecialEuclidean{3}, p, fX::TFVector{<:Any,VeeOrthogonalBasis{ℝ}})\n\nAdjoint action of the SpecialEuclidean group on the vector with coefficients fX tangent at point p.\n\nThe formula for the coefficients reads t(Rω) + Rr for the translation part and Rω for the rotation part, where t is the translation part of p, R is the rotation matrix part of p, r is the translation part of fX and ω is the rotation part of fX, is the cross product and is the matrix product.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.affine_matrix-Union{Tuple{n}, Tuple{SpecialEuclidean{n}, Any}} where n","page":"Group manifold","title":"Manifolds.affine_matrix","text":"affine_matrix(G::SpecialEuclidean, p) -> AbstractMatrix\n\nRepresent the point p mathrmSE(n) as an affine matrix. For p = (t R) mathrmSE(n), where t mathrmT(n) R mathrmSO(n), the affine representation is the n + 1 n + 1 matrix\n\nbeginpmatrix\nR t \n0^mathrmT 1\nendpmatrix\n\nThis function embeds mathrmSE(n) in the general linear group mathrmGL(n+1). It is an isometric embedding and group homomorphism [RicoMartinez1988].\n\nSee also screw_matrix for matrix representations of the Lie algebra.\n\n[RicoMartinez1988]: Rico Martinez, J. M., “Representations of the Euclidean group and its applications to the kinematics of spatial chains,” PhD Thesis, University of Florida, 1988.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::SpecialEuclidean{2}, X)\n\nCompute the group exponential of X = (b Ω) 𝔰𝔢(2), where b 𝔱(2) and Ω 𝔰𝔬(2):\n\nexp X = (t R) = (U(θ) b exp Ω)\n\nwhere t mathrmT(2), R = exp Ω is the group exponential on mathrmSO(2),\n\nU(θ) = fracsin θθ I_2 + frac1 - cos θθ^2 Ω\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::SpecialEuclidean{3}, X)\n\nCompute the group exponential of X = (b Ω) 𝔰𝔢(3), where b 𝔱(3) and Ω 𝔰𝔬(3):\n\nexp X = (t R) = (U(θ) b exp Ω)\n\nwhere t mathrmT(3), R = exp Ω is the group exponential on mathrmSO(3),\n\nU(θ) = I_3 + frac1 - cos θθ^2 Ω + fracθ - sin θθ^3 Ω^2\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.exp_lie-Tuple{SpecialEuclidean, Any}","page":"Group manifold","title":"Manifolds.exp_lie","text":"exp_lie(G::SpecialEuclidean{n}, X)\n\nCompute the group exponential of X = (b Ω) 𝔰𝔢(n), where b 𝔱(n) and Ω 𝔰𝔬(n):\n\nexp X = (t R)\n\nwhere t mathrmT(n) and R = exp Ω is the group exponential on mathrmSO(n).\n\nIn the screw_matrix representation, the group exponential is the matrix exponential (see exp_lie).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.lie_bracket-Tuple{SpecialEuclidean, ProductRepr, ProductRepr}","page":"Group manifold","title":"Manifolds.lie_bracket","text":"lie_bracket(G::SpecialEuclidean, X::ProductRepr, Y::ProductRepr)\nlie_bracket(G::SpecialEuclidean, X::ArrayPartition, Y::ArrayPartition)\nlie_bracket(G::SpecialEuclidean, X::AbstractMatrix, Y::AbstractMatrix)\n\nCalculate the Lie bracket between elements X and Y of the special Euclidean Lie algebra. For the matrix representation (which can be obtained using screw_matrix) the formula is X Y = XY-YX, while in the ProductRepr representation the formula reads X Y = (t_1 R_1) (t_2 R_2) = (R_1 t_2 - R_2 t_1 R_1 R_2 - R_2 R_1).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{2}, ℝ}, SpecialOrthogonal{2}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G::SpecialEuclidean{2}, p)\n\nCompute the group logarithm of p = (t R) mathrmSE(2), where t mathrmT(2) and R mathrmSO(2):\n\nlog p = (b Ω) = (U(θ)^-1 t log R)\n\nwhere b 𝔱(2), Ω = log R 𝔰𝔬(2) is the group logarithm on mathrmSO(2),\n\nU(θ) = fracsin θθ I_2 + frac1 - cos θθ^2 Ω\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{GroupManifold{ℝ, ProductManifold{ℝ, Tuple{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}}}, Manifolds.SemidirectProductOperation{RotationAction{TranslationGroup{Tuple{3}, ℝ}, SpecialOrthogonal{3}, LeftForwardAction}}}, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G::SpecialEuclidean{3}, p)\n\nCompute the group logarithm of p = (t R) mathrmSE(3), where t mathrmT(3) and R mathrmSO(3):\n\nlog p = (b Ω) = (U(θ)^-1 t log R)\n\nwhere b 𝔱(3), Ω = log R 𝔰𝔬(3) is the group logarithm on mathrmSO(3),\n\nU(θ) = I_3 + frac1 - cos θθ^2 Ω + fracθ - sin θθ^3 Ω^2\n\nand θ = frac1sqrt2 lVert Ω rVert_e (see norm) is the angle of the rotation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.log_lie-Tuple{SpecialEuclidean, Any}","page":"Group manifold","title":"Manifolds.log_lie","text":"log_lie(G::SpecialEuclidean{n}, p) where {n}\n\nCompute the group logarithm of p = (t R) mathrmSE(n), where t mathrmT(n) and R mathrmSO(n):\n\nlog p = (b Ω)\n\nwhere b 𝔱(n) and Ω = log R 𝔰𝔬(n) is the group logarithm on mathrmSO(n).\n\nIn the affine_matrix representation, the group logarithm is the matrix logarithm (see log_lie):\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.screw_matrix-Union{Tuple{n}, Tuple{SpecialEuclidean{n}, Any}} where n","page":"Group manifold","title":"Manifolds.screw_matrix","text":"screw_matrix(G::SpecialEuclidean, X) -> AbstractMatrix\n\nRepresent the Lie algebra element X 𝔰𝔢(n) = T_e mathrmSE(n) as a screw matrix. For X = (b Ω) 𝔰𝔢(n), where Ω 𝔰𝔬(n) = T_e mathrmSO(n), the screw representation is the n + 1 n + 1 matrix\n\nbeginpmatrix\nΩ b \n0^mathrmT 0\nendpmatrix\n\nThis function embeds 𝔰𝔢(n) in the general linear Lie algebra 𝔤𝔩(n+1) but it's not a homomorphic embedding (see SpecialEuclideanInGeneralLinear for a homomorphic one).\n\nSee also affine_matrix for matrix representations of the Lie group.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.translate_diff-Tuple{SpecialEuclidean, Any, Any, Any, RightBackwardAction}","page":"Group manifold","title":"Manifolds.translate_diff","text":"translate_diff(G::SpecialEuclidean, p, q, X, ::RightBackwardAction)\n\nDifferential of the right action of the SpecialEuclidean group on itself. The formula for the rotation part is the differential of the right rotation action, while the formula for the translation part reads\n\nR_qX_Rt_p + X_t\n\nwhere R_q is the rotation part of q, X_R is the rotation part of X, t_p is the translation part of p and X_t is the translation part of X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.embed-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any, Any}","page":"Group manifold","title":"ManifoldsBase.embed","text":"embed(M::SpecialEuclideanInGeneralLinear, p, X)\n\nEmbed the tangent vector X at point p on SpecialEuclidean in the GeneralLinear group. Point p can use any representation valid for SpecialEuclidean. The embedding is similar from the one defined by screw_matrix but the translation part is multiplied by inverse of the rotation part.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.embed-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any}","page":"Group manifold","title":"ManifoldsBase.embed","text":"embed(M::SpecialEuclideanInGeneralLinear, p)\n\nEmbed the point p on SpecialEuclidean in the GeneralLinear group. The embedding is calculated using affine_matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::SpecialEuclideanInGeneralLinear, p, X)\n\nProject tangent vector X at point p in GeneralLinear to the SpecialEuclidean Lie algebra. This reverses the transformation performed by embed\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{EmbeddedManifold{ℝ, <:SpecialEuclidean, <:GeneralLinear}, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(M::SpecialEuclideanInGeneralLinear, p)\n\nProject point p in GeneralLinear to the SpecialEuclidean group. This is performed by extracting the rotation and translation part as in affine_matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Special-linear-group","page":"Group manifold","title":"Special linear group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/special_linear.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.SpecialLinear","page":"Group manifold","title":"Manifolds.SpecialLinear","text":"SpecialLinear{n,𝔽} <: AbstractDecoratorManifold\n\nThe special linear group mathrmSL(n𝔽) that is, the group of all invertible matrices with unit determinant in 𝔽^nn.\n\nThe Lie algebra 𝔰𝔩(n 𝔽) = T_e mathrmSL(n𝔽) is the set of all matrices in 𝔽^nn with trace of zero. By default, tangent vectors X_p T_p mathrmSL(n𝔽) for p mathrmSL(n𝔽) are represented with their corresponding Lie algebra vector X_e = p^-1X_p 𝔰𝔩(n 𝔽).\n\nThe default metric is the same left-mathrmGL(n)-right-mathrmO(n)-invariant metric used for GeneralLinear(n, 𝔽). The resulting geodesic on mathrmGL(n𝔽) emanating from an element of mathrmSL(n𝔽) in the direction of an element of 𝔰𝔩(n 𝔽) is a closed subgroup of mathrmSL(n𝔽). As a result, most metric functions forward to GeneralLinear.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{SpecialLinear, Any, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(G::SpecialLinear, p, X)\n\nOrthogonally project X 𝔽^n n onto the tangent space of p to the SpecialLinear G = mathrmSL(n 𝔽). The formula reads\n\noperatornameproj_p\n = (mathrmdL_p)_e operatornameproj_𝔰𝔩(n 𝔽) (mathrmdL_p^-1)_p\n colon X X - fracoperatornametr(X)n I\n\nwhere the last expression uses the tangent space representation as the Lie algebra.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.project-Tuple{SpecialLinear, Any}","page":"Group manifold","title":"ManifoldsBase.project","text":"project(G::SpecialLinear, p)\n\nProject p mathrmGL(n 𝔽) to the SpecialLinear group G=mathrmSL(n 𝔽).\n\nGiven the singular value decomposition of p, written p = U S V^mathrmH, the formula for the projection is\n\noperatornameproj_mathrmSL(n 𝔽)(p) = U S D V^mathrmH\n\nwhere\n\nD_ij = δ_ij begincases\n 1 text if i n \n det(p)^-1 text if i = n\nendcases\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Translation-group","page":"Group manifold","title":"Translation group","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/translation_group.jl\"]\nOrder = [:constant, :type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.TranslationGroup","page":"Group manifold","title":"Manifolds.TranslationGroup","text":"TranslationGroup{T<:Tuple,𝔽} <: GroupManifold{Euclidean{T,𝔽},AdditionOperation}\n\nTranslation group mathrmT(n) represented by translation arrays.\n\nConstructor\n\nTranslationGroup(n₁,...,nᵢ; field = 𝔽)\n\nGenerate the translation group on 𝔽^n₁nᵢ = Euclidean(n₁,...,nᵢ; field = 𝔽), which is isomorphic to the group itself.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Group-actions","page":"Group manifold","title":"Group actions","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Group actions represent actions of a given group on a specified manifold. The following operations are available:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"apply: performs given action of an element of the group on an object of compatible type.\napply_diff: differential of apply with respect to the object it acts upon.\ndirection: tells whether a given action is LeftForwardAction, RightForwardAction, LeftBackwardAction or RightBackwardAction.\ninverse_apply: performs given action of the inverse of an element of the group on an object of compatible type. By default inverts the element and calls apply but it may be have a faster implementation for some actions.\ninverse_apply_diff: counterpart of apply_diff for inverse_apply.\noptimal_alignment: determine the element of a group that, when it acts upon a point, produces the element closest to another given point in the metric of the G-manifold.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Furthermore, group operation action features the following:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"translate: an operation that performs either left (LeftForwardAction) or right (RightBackwardAction) translation, or actions by inverses of elements (RightForwardAction and LeftBackwardAction). This is by default performed by calling compose with appropriate order of arguments. This function is separated from compose mostly to easily represent its differential, translate_diff.\ntranslate_diff: differential of translate with respect to the point being translated.\nadjoint_action: adjoint action of a given element of a Lie group on an element of its Lie algebra.\nlie_bracket: Lie bracket of two vectors from a Lie algebra corresponding to a given group.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"The following group actions are available:","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Group operation action GroupOperationAction that describes action of a group on itself.\nRotationAction, that is action of SpecialOrthogonal group on different manifolds.\nTranslationAction, which is the action of TranslationGroup group on different manifolds.","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/group_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AbstractGroupAction","page":"Group manifold","title":"Manifolds.AbstractGroupAction","text":"AbstractGroupAction\n\nAn abstract group action on a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.adjoint_apply_diff_group-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.adjoint_apply_diff_group","text":"adjoint_apply_diff_group(A::AbstractGroupAction, a, X, p)\n\nPullback with respect to group element of group action A.\n\n(mathrmdτ^p*) T_τ_a p mathcal M T_a mathcal G\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply!-Tuple{AbstractGroupAction{LeftForwardAction}, Any, Any, Any}","page":"Group manifold","title":"Manifolds.apply!","text":"apply!(A::AbstractGroupAction, q, a, p)\n\nApply action a to the point p with the rule specified by A. The result is saved in q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply-Tuple{AbstractGroupAction, Any, Any}","page":"Group manifold","title":"Manifolds.apply","text":"apply(A::AbstractGroupAction, a, p)\n\nApply action a to the point p using map τ_a, specified by A. Unless otherwise specified, the right action is defined in terms of the left action:\n\nmathrmR_a = mathrmL_a^-1\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply_diff-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.apply_diff","text":"apply_diff(A::AbstractGroupAction, a, p, X)\n\nFor point p mathcal M and tangent vector X T_p mathcal M, compute the action on X of the differential of the action of a mathcalG, specified by rule A. Written as (mathrmdτ_a)_p, with the specified left or right convention, the differential transports vectors\n\n(mathrmdτ_a)_p T_p mathcal M T_τ_a p mathcal M\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.apply_diff_group-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.apply_diff_group","text":"apply_diff_group(A::AbstractGroupAction, a, X, p)\n\nCompute the value of differential of action AbstractGroupAction A on vector X, where element a is acting on p, with respect to the group element.\n\nLet mathcal G be the group acting on manifold mathcal M by the action A. The action is of element g mathcal G on a point p mathcal M. The differential transforms vector X from the tangent space at a ∈ \\mathcal G, X T_a mathcal G into a tangent space of the manifold mathcal M. When action on element p is written as mathrmdτ^p, with the specified left or right convention, the differential transforms vectors\n\n(mathrmdτ^p) T_a mathcal G T_τ_a p mathcal M\n\nSee also\n\napply, apply_diff\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.base_group-Tuple{AbstractGroupAction}","page":"Group manifold","title":"Manifolds.base_group","text":"base_group(A::AbstractGroupAction)\n\nThe group that acts in action A.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.center_of_orbit","page":"Group manifold","title":"Manifolds.center_of_orbit","text":"center_of_orbit(\n A::AbstractGroupAction,\n pts,\n p,\n mean_method::AbstractEstimationMethod = GradientDescentEstimation(),\n)\n\nCalculate an action element a of action A that is the mean element of the orbit of p with respect to given set of points pts. The mean is calculated using the method mean_method.\n\nThe orbit of p with respect to the action of a group mathcalG is the set\n\nO = τ_a p a mathcalG \n\nThis function is useful for computing means on quotients of manifolds by a Lie group action.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/group.html#Manifolds.direction-Union{Tuple{AbstractGroupAction{AD}}, Tuple{AD}} where AD","page":"Group manifold","title":"Manifolds.direction","text":"direction(::AbstractGroupAction{AD}) -> AD\n\nGet the direction of the action\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.group_manifold-Tuple{AbstractGroupAction}","page":"Group manifold","title":"Manifolds.group_manifold","text":"group_manifold(A::AbstractGroupAction)\n\nThe manifold the action A acts upon.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_apply!-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.inverse_apply!","text":"inverse_apply!(A::AbstractGroupAction, q, a, p)\n\nApply inverse of action a to the point p with the rule specified by A. The result is saved in q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_apply-Tuple{AbstractGroupAction, Any, Any}","page":"Group manifold","title":"Manifolds.inverse_apply","text":"inverse_apply(A::AbstractGroupAction, a, p)\n\nApply inverse of action a to the point p. The action is specified by A.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.inverse_apply_diff-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.inverse_apply_diff","text":"inverse_apply_diff(A::AbstractGroupAction, a, p, X)\n\nFor group point p mathcal M and tangent vector X T_p mathcal M, compute the action on X of the differential of the inverse action of a mathcalG, specified by rule A. Written as (mathrmdτ_a^-1)_p, with the specified left or right convention, the differential transports vectors\n\n(mathrmdτ_a^-1)_p T_p mathcal M T_τ_a^-1 p mathcal M\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.optimal_alignment!-Tuple{AbstractGroupAction, Any, Any, Any}","page":"Group manifold","title":"Manifolds.optimal_alignment!","text":"optimal_alignment!(A::AbstractGroupAction, x, p, q)\n\nCalculate an action element of action A that acts upon p to produce the element closest to q. The result is written to x.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.optimal_alignment-Tuple{AbstractGroupAction, Any, Any}","page":"Group manifold","title":"Manifolds.optimal_alignment","text":"optimal_alignment(A::AbstractGroupAction, p, q)\n\nCalculate an action element a of action A that acts upon p to produce the element closest to q in the metric of the G-manifold:\n\nargmin_a mathcalG d_mathcal M(τ_a p q)\n\nwhere mathcalG is the group that acts on the G-manifold mathcal M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Group-operation-action","page":"Group manifold","title":"Group operation action","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/group_operation_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.GroupOperationAction","page":"Group manifold","title":"Manifolds.GroupOperationAction","text":"GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirection = LeftForwardAction())\n\nAction of a group upon itself via left or right translation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Rotation-action","page":"Group manifold","title":"Rotation action","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/rotation_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.ColumnwiseMultiplicationAction","page":"Group manifold","title":"Manifolds.ColumnwiseMultiplicationAction","text":"ColumnwiseMultiplicationAction{\n TM<:AbstractManifold,\n TO<:GeneralUnitaryMultiplicationGroup,\n TAD<:ActionDirection,\n} <: AbstractGroupAction{TAD}\n\nAction of the (special) unitary or orthogonal group GeneralUnitaryMultiplicationGroup of type On columns of points on a matrix manifold M.\n\nConstructor\n\nColumnwiseMultiplicationAction(\n M::AbstractManifold,\n On::GeneralUnitaryMultiplicationGroup,\n AD::ActionDirection = LeftForwardAction(),\n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RotationAction","page":"Group manifold","title":"Manifolds.RotationAction","text":"RotationAction(\n M::AbstractManifold,\n SOn::SpecialOrthogonal,\n AD::ActionDirection = LeftForwardAction(),\n)\n\nSpace of actions of the SpecialOrthogonal group mathrmSO(n) on a Euclidean-like manifold M of dimension n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RotationAroundAxisAction","page":"Group manifold","title":"Manifolds.RotationAroundAxisAction","text":"RotationAroundAxisAction(axis::AbstractVector)\n\nSpace of actions of the circle group RealCircleGroup on ℝ^3 around given axis.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RowwiseMultiplicationAction","page":"Group manifold","title":"Manifolds.RowwiseMultiplicationAction","text":"RowwiseMultiplicationAction{\n TM<:AbstractManifold,\n TO<:GeneralUnitaryMultiplicationGroup,\n TAD<:ActionDirection,\n} <: AbstractGroupAction{TAD}\n\nAction of the (special) unitary or orthogonal group GeneralUnitaryMultiplicationGroup of type On columns of points on a matrix manifold M.\n\nConstructor\n\nRowwiseMultiplicationAction(\n M::AbstractManifold,\n On::GeneralUnitaryMultiplicationGroup,\n AD::ActionDirection = LeftForwardAction(),\n)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.apply-Tuple{Manifolds.RotationAroundAxisAction, Any, Any}","page":"Group manifold","title":"Manifolds.apply","text":"apply(A::RotationAroundAxisAction, θ, p)\n\nRotate point p from Euclidean(3) manifold around axis A.axis by angle θ. The formula reads\n\np_rot = (cos(θ))p + (kp) sin(θ) + k (kp) (1-cos(θ))\n\nwhere k is the vector A.axis and ⋅ is the dot product.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.optimal_alignment-Tuple{Manifolds.ColumnwiseMultiplicationAction{TM, TO, LeftForwardAction} where {TM<:AbstractManifold, TO<:Manifolds.GeneralUnitaryMultiplicationGroup}, Any, Any}","page":"Group manifold","title":"Manifolds.optimal_alignment","text":"optimal_alignment(A::LeftColumnwiseMultiplicationAction, p, q)\n\nCompute optimal alignment for the left ColumnwiseMultiplicationAction, i.e. the group element O^* that, when it acts on p, returns the point closest to q. Details of computation are described in Section 2.2.1 of [Srivastava2016].\n\nThe formula reads\n\nO^* = begincases\nUV^T textif operatornamedet(p q^mathrmT)\nU K V^mathrmT textotherwise\nendcases\n\nwhere U Sigma V^mathrmT is the SVD decomposition of p q^mathrmT and K is the unit diagonal matrix with the last element on the diagonal replaced with -1.\n\nReferences\n\n[Srivastava2016]: A. Srivastava and E. P. Klassen, Functional and Shape Data Analysis. Springer New York, 2016. ISBN: 978-1-4939-4018-9. doi: 10.1007/978-1-4939-4020-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Translation-action","page":"Group manifold","title":"Translation action","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/translation_action.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.TranslationAction","page":"Group manifold","title":"Manifolds.TranslationAction","text":"TranslationAction(\n M::AbstractManifold,\n Rn::TranslationGroup,\n AD::ActionDirection = LeftForwardAction(),\n)\n\nSpace of actions of the TranslationGroup mathrmT(n) on a Euclidean-like manifold M.\n\nThe left and right actions are equivalent.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Metrics-on-groups","page":"Group manifold","title":"Metrics on groups","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Lie groups by default typically forward all metric-related operations like exponential or logarithmic map to the underlying manifold, for example SpecialOrthogonal uses methods for Rotations (which is, incidentally, bi-invariant), or SpecialEuclidean uses product metric of the translation and rotation parts (which is not invariant under group operation).","category":"page"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"It is, however, possible to change the metric used by a group by wrapping it in a MetricManifold decorator.","category":"page"},{"location":"manifolds/group.html#Invariant-metrics","page":"Group manifold","title":"Invariant metrics","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/metric.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.LeftInvariantMetric","page":"Group manifold","title":"Manifolds.LeftInvariantMetric","text":"LeftInvariantMetric <: AbstractMetric\n\nAn AbstractMetric that changes the metric of a Lie group to the left-invariant metric obtained by left-translations to the identity. Adds the HasLeftInvariantMetric trait.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.RightInvariantMetric","page":"Group manifold","title":"Manifolds.RightInvariantMetric","text":"RightInvariantMetric <: AbstractMetric\n\nAn AbstractMetric that changes the metric of a Lie group to the right-invariant metric obtained by right-translations to the identity. Adds the HasRightInvariantMetric trait.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.direction-Tuple{AbstractDecoratorManifold}","page":"Group manifold","title":"Manifolds.direction","text":"direction(::AbstractDecoratorManifold) -> AD\n\nGet the direction of the action a certain Lie group with its implicit metric has\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Manifolds.has_approx_invariant_metric-Tuple{AbstractDecoratorManifold, Any, Any, Any, Any, ActionDirection}","page":"Group manifold","title":"Manifolds.has_approx_invariant_metric","text":"has_approx_invariant_metric(\n G::AbstractDecoratorManifold,\n p,\n X,\n Y,\n qs::AbstractVector,\n conv::ActionDirection = LeftForwardAction();\n kwargs...,\n) -> Bool\n\nCheck whether the metric on the group mathcalG is (approximately) invariant using a set of predefined points. Namely, for p mathcalG, XY T_p mathcalG, a metric g, and a translation map τ_q in the specified direction, check for each q mathcalG that the following condition holds:\n\ng_p(X Y) g_τ_q p((mathrmdτ_q)_p X (mathrmdτ_q)_p Y)\n\nThis is necessary but not sufficient for invariance.\n\nOptionally, kwargs passed to isapprox may be provided.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Cartan-Schouten-connections","page":"Group manifold","title":"Cartan-Schouten connections","text":"","category":"section"},{"location":"manifolds/group.html","page":"Group manifold","title":"Group manifold","text":"Modules = [Manifolds]\nPages = [\"groups/connections.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/group.html#Manifolds.AbstractCartanSchoutenConnection","page":"Group manifold","title":"Manifolds.AbstractCartanSchoutenConnection","text":"AbstractCartanSchoutenConnection\n\nAbstract type for Cartan-Schouten connections, that is connections whose geodesics going through group identity are one-parameter subgroups. See[Pennec2020] for details.\n\n[Pennec2020]: X. Pennec and M. Lorenzi, “5 - Beyond Riemannian geometry: The affine connection setting for transformation groups,” in Riemannian Geometric Statistics in Medical Image Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 169–229. doi: 10.1016/B978-0-12-814725-2.00012-1.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.CartanSchoutenMinus","page":"Group manifold","title":"Manifolds.CartanSchoutenMinus","text":"CartanSchoutenMinus\n\nThe unique Cartan-Schouten connection such that all left-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.CartanSchoutenPlus","page":"Group manifold","title":"Manifolds.CartanSchoutenPlus","text":"CartanSchoutenPlus\n\nThe unique Cartan-Schouten connection such that all right-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Manifolds.CartanSchoutenZero","page":"Group manifold","title":"Manifolds.CartanSchoutenZero","text":"CartanSchoutenZero\n\nThe unique torsion-free Cartan-Schouten connection. It is biinvariant with respect to the group operation.\n\nIf the metric on the underlying manifold is bi-invariant then it is equivalent to the Levi-Civita connection of that metric.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/group.html#Base.exp-Union{Tuple{𝔽}, Tuple{ConnectionManifold{𝔽, <:AbstractDecoratorManifold{𝔽}, <:AbstractCartanSchoutenConnection}, Any, Any}} where 𝔽","page":"Group manifold","title":"Base.exp","text":"exp(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, X) where {𝔽}\n\nCompute the exponential map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#Base.log-Union{Tuple{𝔽}, Tuple{ConnectionManifold{𝔽, <:AbstractDecoratorManifold{𝔽}, <:AbstractCartanSchoutenConnection}, Any, Any}} where 𝔽","page":"Group manifold","title":"Base.log","text":"log(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, q) where {𝔽}\n\nCompute the logarithmic map on the ConnectionManifold M with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_direction-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenZero} where {𝔽, M}, Identity, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::CartanSchoutenZeroGroup, ::Identity, X, d)\n\nTransport tangent vector X at identity on the group manifold with the CartanSchoutenZero connection in the direction d. See [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_to-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenMinus} where {𝔽, M}, Any, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::CartanSchoutenMinusGroup, p, X, q)\n\nTransport tangent vector X at point p on the group manifold M with the CartanSchoutenMinus connection to point q. See [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_to-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenPlus} where {𝔽, M}, Any, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_to","text":"vector_transport_to(M::CartanSchoutenPlusGroup, p, X, q)\n\nTransport tangent vector X at point p on the group manifold M with the CartanSchoutenPlus connection to point q. See [Pennec2020] for details.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/group.html#ManifoldsBase.parallel_transport_to-Tuple{ConnectionManifold{𝔽, M, CartanSchoutenZero} where {𝔽, M}, Identity, Any, Any}","page":"Group manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::CartanSchoutenZeroGroup, p::Identity, X, q)\n\nTransport vector X at identity of group M equipped with the CartanSchoutenZero connection to point q using parallel transport.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Metric-manifold","page":"Metric manifold","title":"Metric manifold","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"A Riemannian manifold always consists of a topological manifold together with a smoothly varying metric g.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"However, often there is an implicitly assumed (default) metric, like the usual inner product on Euclidean space. This decorator takes this into account. It is not necessary to use this decorator if you implement just one (or the first) metric. If you later introduce a second, the old (first) metric can be used with the (non MetricManifold) AbstractManifold, i.e. without an explicitly stated metric.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"This manifold decorator serves two purposes:","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"to implement different metrics (e.g. in closed form) for one AbstractManifold\nto provide a way to compute geodesics on manifolds, where this AbstractMetric does not yield closed formula.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Pages = [\"metric.md\"]\nDepth = 2","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Note that a metric manifold is has a IsConnectionManifold trait referring to the LeviCivitaConnection of the metric g, and thus a large part of metric manifold's functionality relies on this.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Let's first look at the provided types.","category":"page"},{"location":"manifolds/metric.html#Types","page":"Metric manifold","title":"Types","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/MetricManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/metric.html#Manifolds.IsDefaultMetric","page":"Metric manifold","title":"Manifolds.IsDefaultMetric","text":"IsDefaultMetric{G<:AbstractMetric}\n\nSpecify that a certain AbstractMetric is the default metric for a manifold. This way the corresponding MetricManifold falls back to the default methods of the manifold it decorates.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/metric.html#Manifolds.IsMetricManifold","page":"Metric manifold","title":"Manifolds.IsMetricManifold","text":"IsMetricManifold <: AbstractTrait\n\nSpecify that a certain decorated Manifold is a metric manifold in the sence that it provides explicit metric properties, extending/changing the default metric properties of a manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/metric.html#Manifolds.MetricManifold","page":"Metric manifold","title":"Manifolds.MetricManifold","text":"MetricManifold{𝔽,M<:AbstractManifold{𝔽},G<:AbstractMetric} <: AbstractDecoratorManifold{𝔽}\n\nEquip a AbstractManifold explicitly with an AbstractMetric G.\n\nFor a Metric AbstractManifold, by default, assumes, that you implement the linear form from local_metric in order to evaluate the exponential map.\n\nIf the corresponding AbstractMetric G yields closed form formulae for e.g. the exponential map and this is implemented directly (without solving the ode), you can of course still implement that directly.\n\nConstructor\n\nMetricManifold(M, G)\n\nGenerate the AbstractManifold M as a manifold with the AbstractMetric G.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/metric.html#Implement-Different-Metrics-on-the-same-Manifold","page":"Metric manifold","title":"Implement Different Metrics on the same Manifold","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"In order to distinguish different metrics on one manifold, one can introduce two AbstractMetrics and use this type to dispatch on the metric, see SymmetricPositiveDefinite. To avoid overhead, one AbstractMetric can then be marked as being the default, i.e. the one that is used, when no MetricManifold decorator is present. This avoids reimplementation of the first existing metric, access to the metric-dependent functions that were implemented using the undecorated manifold, as well as the transparent fallback of the corresponding MetricManifold with default metric to the undecorated implementations. This does not cause any runtime overhead. Introducing a default AbstractMetric serves a better readability of the code when working with different metrics.","category":"page"},{"location":"manifolds/metric.html#Implementation-of-Metrics","page":"Metric manifold","title":"Implementation of Metrics","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"For the case that a local_metric is implemented as a bilinear form that is positive definite, the following further functions are provided, unless the corresponding AbstractMetric is marked as default – then the fallbacks mentioned in the last section are used for e.g. the exponential map.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Modules = [Manifolds, ManifoldsBase]\nPages = [\"manifolds/MetricManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/metric.html#Base.log-Tuple{MetricManifold, Vararg{Any}}","page":"Metric manifold","title":"Base.log","text":"log(N::MetricManifold{M,G}, p, q)\n\nCopute the logarithmic map on the AbstractManifold M equipped with the AbstractMetric G.\n\nIf the metric was declared the default metric using the IsDefaultMetric trait or is_default_metric, this method falls back to log(M,p,q). Otherwise, you have to provide an implementation for the non-default AbstractMetric G metric within its MetricManifold{M,G}.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.connection-Tuple{MetricManifold}","page":"Metric manifold","title":"Manifolds.connection","text":"connection(::MetricManifold)\n\nReturn the LeviCivitaConnection for a metric manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.det_local_metric-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.det_local_metric","text":"det_local_metric(M::AbstractManifold, p, B::AbstractBasis)\n\nReturn the determinant of local matrix representation of the metric tensor g, i.e. of the matrix G(p) representing the metric in the tangent space at p with as a matrix.\n\nSee also local_metric\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.einstein_tensor-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.einstein_tensor","text":"einstein_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = diff_badefault_differential_backendckend())\n\nCompute the Einstein tensor of the manifold M at the point p, see https://en.wikipedia.org/wiki/Einstein_tensor\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.flat-Tuple{MetricManifold, Any, TFVector}","page":"Metric manifold","title":"Manifolds.flat","text":"flat(N::MetricManifold{M,G}, p, X::TFVector)\n\nCompute the musical isomorphism to transform the tangent vector X from the AbstractManifold M equipped with AbstractMetric G to a cotangent by computing\n\nX^= G_p X\n\nwhere G_p is the local matrix representation of G, see local_metric\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.inverse_local_metric-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.inverse_local_metric","text":"inverse_local_metric(M::AbstractcManifold{𝔽}, p, B::AbstractBasis)\n\nReturn the local matrix representation of the inverse metric (cometric) tensor of the tangent space at p on the AbstractManifold M with respect to the AbstractBasis basis B.\n\nThe metric tensor (see local_metric) is usually denoted by G = (g_ij) 𝔽^dd, where d is the dimension of the manifold.\n\nThen the inverse local metric is denoted by G^-1 = g^ij.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.is_default_metric-Tuple{AbstractManifold, AbstractMetric}","page":"Metric manifold","title":"Manifolds.is_default_metric","text":"is_default_metric(M::AbstractManifold, G::AbstractMetric)\n\nreturns whether an AbstractMetric is the default metric on the manifold M or not. This can be set by defining this function, or setting the IsDefaultMetric trait for an AbstractDecoratorManifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.local_metric-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.local_metric","text":"local_metric(M::AbstractManifold{𝔽}, p, B::AbstractBasis)\n\nReturn the local matrix representation at the point p of the metric tensor g with respect to the AbstractBasis B on the AbstractManifold M. Let ddenote the dimension of the manifold and b_1ldotsb_d the basis vectors. Then the local matrix representation is a matrix Gin 𝔽^ntimes n whose entries are given by g_ij = g_p(b_ib_j) ijin1d.\n\nThis yields the property for two tangent vectors (using Einstein summation convention) X = X^ib_i Y=Y^ib_i in T_pmathcal M we get g_p(X Y) = g_ij X^i Y^j.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.local_metric_jacobian-Tuple{AbstractManifold, Any, AbstractBasis, ManifoldDiff.AbstractDiffBackend}","page":"Metric manifold","title":"Manifolds.local_metric_jacobian","text":"local_metric_jacobian(\n M::AbstractManifold,\n p,\n B::AbstractBasis;\n backend::AbstractDiffBackend,\n)\n\nGet partial derivatives of the local metric of M at p in basis B with respect to the coordinates of p, frac p^k g_ij = g_ijk. The dimensions of the resulting multi-dimensional array are ordered (ijk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.log_local_metric_density-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.log_local_metric_density","text":"log_local_metric_density(M::AbstractManifold, p, B::AbstractBasis)\n\nReturn the natural logarithm of the metric density ρ of M at p, which is given by ρ = log sqrtdet g_ij for the metric tensor expressed in basis B.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.metric-Tuple{MetricManifold}","page":"Metric manifold","title":"Manifolds.metric","text":"metric(M::MetricManifold)\n\nGet the metric g of the manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.ricci_curvature-Tuple{AbstractManifold, Any, AbstractBasis}","page":"Metric manifold","title":"Manifolds.ricci_curvature","text":"ricci_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = default_differential_backend())\n\nCompute the Ricci scalar curvature of the manifold M at the point p using basis B. The curvature is computed as the trace of the Ricci curvature tensor with respect to the metric, that is R=g^ijR_ij where R is the scalar Ricci curvature at p, g^ij is the inverse local metric (see inverse_local_metric) at p and R_ij is the Riccie curvature tensor, see ricci_tensor. Both the tensor and inverse local metric are expressed in local coordinates defined by B, and the formula uses the Einstein summation convention.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Manifolds.sharp-Tuple{MetricManifold, Any, CoTFVector}","page":"Metric manifold","title":"Manifolds.sharp","text":"sharp(N::MetricManifold{M,G}, p, ξ::CoTFVector)\n\nCompute the musical isomorphism to transform the cotangent vector ξ from the AbstractManifold M equipped with AbstractMetric G to a tangent by computing\n\nξ^ = G_p^-1 ξ\n\nwhere G_p is the local matrix representation of G, i.e. one employs inverse_local_metric here to obtain G_p^-1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#ManifoldsBase.inner-Tuple{MetricManifold, Any, Any, Any}","page":"Metric manifold","title":"ManifoldsBase.inner","text":"inner(N::MetricManifold{M,G}, p, X, Y)\n\nCompute the inner product of X and Y from the tangent space at p on the AbstractManifold M using the AbstractMetric G. If M has G as its IsDefaultMetric trait, this is done using inner(M, p, X, Y), otherwise the local_metric(M, p) is employed as\n\ng_p(X Y) = X G_p Y\n\nwhere G_p is the loal matrix representation of the AbstractMetric G.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/metric.html#Metrics,-charts-and-bases-of-vector-spaces","page":"Metric manifold","title":"Metrics, charts and bases of vector spaces","text":"","category":"section"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Metric-related functions, similarly to connection-related functions, need to operate in a basis of a vector space, see here.","category":"page"},{"location":"manifolds/metric.html","page":"Metric manifold","title":"Metric manifold","text":"Metric-related functions can take bases of associated tangent spaces as arguments. For example local_metric can take the basis of the tangent space it is supposed to operate on instead of a custom basis of the space of symmetric bilinear operators.","category":"page"},{"location":"manifolds/symmetric.html#Symmetric-matrices","page":"Symmetric matrices","title":"Symmetric matrices","text":"","category":"section"},{"location":"manifolds/symmetric.html","page":"Symmetric matrices","title":"Symmetric matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Symmetric.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetric.html#Manifolds.SymmetricMatrices","page":"Symmetric matrices","title":"Manifolds.SymmetricMatrices","text":"SymmetricMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe AbstractManifold $ \\operatorname{Sym}(n)$ consisting of the real- or complex-valued symmetric matrices of size n n, i.e. the set\n\noperatornameSym(n) = biglp 𝔽^n n big p^mathrmH = p bigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ.\n\nThough it is slightly redundant, usually the matrices are stored as n n arrays.\n\nNote that in this representation, the complex valued case has to have a real-valued diagonal, which is also reflected in the manifold_dimension.\n\nConstructor\n\nSymmetricMatrices(n::Int, field::AbstractNumbers=ℝ)\n\nGenerate the manifold of n n symmetric matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetric.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{SymmetricMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Symmetric matrices","title":"ManifoldsBase.check_point","text":"check_point(M::SymmetricMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether p is a valid manifold point on the SymmetricMatrices M, i.e. whether p is a symmetric matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.\n\nThe tolerance for the symmetry of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{n}, Tuple{SymmetricMatrices{n, 𝔽}, Any, Any}} where {n, 𝔽}","page":"Symmetric matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::SymmetricMatrices{n,𝔽}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SymmetricMatrices M, i.e. X has to be a symmetric matrix of size (n,n) and its values have to be from the correct AbstractNumbers.\n\nThe tolerance for the symmetry of X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.is_flat-Tuple{SymmetricMatrices}","page":"Symmetric matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::SymmetricMatrices)\n\nReturn true. SymmetricMatrices is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.manifold_dimension-Union{Tuple{SymmetricMatrices{N, 𝔽}}, Tuple{𝔽}, Tuple{N}} where {N, 𝔽}","page":"Symmetric matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SymmetricMatrices{n,𝔽})\n\nReturn the dimension of the SymmetricMatrices matrix M over the number system 𝔽, i.e.\n\nbeginaligned\ndim mathrmSym(nℝ) = fracn(n+1)2\ndim mathrmSym(nℂ) = 2fracn(n+1)2 - n = n^2\nendaligned\n\nwhere the last -n is due to the zero imaginary part for Hermitian matrices\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.project-Tuple{SymmetricMatrices, Any, Any}","page":"Symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SymmetricMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the SymmetricMatrices M,\n\noperatornameproj_p(X) = frac12 bigl( X + X^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetric.html#ManifoldsBase.project-Tuple{SymmetricMatrices, Any}","page":"Symmetric matrices","title":"ManifoldsBase.project","text":"project(M::SymmetricMatrices, p)\n\nProjects p from the embedding onto the SymmetricMatrices M, i.e.\n\noperatornameproj_operatornameSym(n)(p) = frac12 bigl( p + p^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Grassmannian-manifold","page":"Grassmann","title":"Grassmannian manifold","text":"","category":"section"},{"location":"manifolds/grassmann.html","page":"Grassmann","title":"Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/Grassmann.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/grassmann.html#Manifolds.Grassmann","page":"Grassmann","title":"Manifolds.Grassmann","text":"Grassmann{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe Grassmann manifold operatornameGr(nk) consists of all subspaces spanned by k linear independent vectors 𝔽^n, where 𝔽 ℝ ℂ is either the real- (or complex-) valued vectors. This yields all k-dimensional subspaces of ℝ^n for the real-valued case and all 2k-dimensional subspaces of ℂ^n for the second.\n\nThe manifold can be represented as\n\noperatornameGr(nk) = bigl operatornamespan(p) p 𝔽^n k p^mathrmHp = I_k\n\nwhere cdot^mathrmH denotes the complex conjugate transpose or Hermitian and I_k is the k k identity matrix. This means, that the columns of p form an unitary basis of the subspace, that is a point on operatornameGr(nk), and hence the subspace can actually be represented by a whole equivalence class of representers. Another interpretation is, that\n\noperatornameGr(nk) = operatornameSt(nk) operatornameO(k)\n\ni.e the Grassmann manifold is the quotient of the Stiefel manifold and the orthogonal group operatornameO(k) of orthogonal k k matrices. Note that it doesn't matter whether we start from the Euclidean or canonical metric on the Stiefel manifold, the resulting quotient metric on Grassmann is the same.\n\nThe tangent space at a point (subspace) p is given by\n\nT_pmathrmGr(nk) = bigl\nX 𝔽^n k \nX^mathrmHp + p^mathrmHX = 0_k bigr\n\nwhere 0_k is the k k zero matrix.\n\nNote that a point p operatornameGr(nk) might be represented by different matrices (i.e. matrices with unitary column vectors that span the same subspace). Different representations of p also lead to different representation matrices for the tangent space T_pmathrmGr(nk)\n\nFor a representation of points as orthogonal projectors. Here\n\noperatornameGr(nk) = bigl p in mathbb R^nn p = p^mathrmT p^2 = p operatornamerank(p) = k\n\nwith tangent space\n\nT_pmathrmGr(nk) = bigl\nX mathbb R^n n X=X^mathrmT text and X = pX+Xp bigr\n\nsee also ProjectorPoint and ProjectorTVector.\n\nThe manifold is named after Hermann G. Graßmann (1809-1877).\n\nA good overview can be found in[BendokatZimmermannAbsil2020].\n\nConstructor\n\nGrassmann(n,k,field=ℝ)\n\nGenerate the Grassmann manifold operatornameGr(nk), where the real-valued case field = ℝ is the default.\n\n[BendokatZimmermannAbsil2020]: T. Bendokat, R. Zimmermann, and P. -A. Absil: A Grassmann Manifold Handbook: Basic Geometry and Computational Aspects, arXiv preprint 2011.13699, 2020.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Base.convert-Tuple{Type{ProjectorPoint}, AbstractMatrix}","page":"Grassmann","title":"Base.convert","text":"convert(::Type{ProjectorPoint}, p::AbstractMatrix)\n\nConvert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for\n\n π^mathrmSG(p) = pp^mathrmT)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Base.convert-Tuple{Type{ProjectorPoint}, StiefelPoint}","page":"Grassmann","title":"Base.convert","text":"convert(::Type{ProjectorPoint}, ::Stiefelpoint)\n\nConvert a point p on Stiefel that also represents a point (i.e. subspace) on Grassmann to a projector representation of said subspace, i.e. compute the canonical_project! for\n\n π^mathrmSG(p) = pp^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.get_total_space-Union{Tuple{Grassmann{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Grassmann","title":"Manifolds.get_total_space","text":"get_total_space(::Grassmann{n,k})\n\nReturn the total space of the Grassmann manifold, which is the corresponding Stiefel manifold, independent of whether the points are represented already in the total space or as ProjectorPoints.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.change_metric-Tuple{Grassmann, EuclideanMetric, Any, Any}","page":"Grassmann","title":"ManifoldsBase.change_metric","text":"change_metric(M::Grassmann, ::EuclideanMetric, p X)\n\nChange X to the corresponding vector with respect to the metric of the Grassmann M, which is just the identity, since the manifold is isometrically embedded.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.change_representer-Tuple{Grassmann, EuclideanMetric, Any, Any}","page":"Grassmann","title":"ManifoldsBase.change_representer","text":"change_representer(M::Grassmann, ::EuclideanMetric, p, X)\n\nChange X to the corresponding representer of a cotangent vector at p. Since the Grassmann manifold M, is isometrically embedded, this is the identity\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.default_retraction_method-Tuple{Grassmann, Type{ProjectorPoint}}","page":"Grassmann","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Grassmann, ::Type{ProjectorPoint})\n\nReturn ExponentialRetraction as the default on the Grassmann manifold with projection matrices\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.default_retraction_method-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.default_retraction_method","text":"default_retraction_method(M::Grassmann)\ndefault_retraction_method(M::Grassmann, ::Type{StiefelPoint})\n\nReturn PolarRetracion as the default on the Grassmann manifold with projection matrices\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.default_vector_transport_method-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.default_vector_transport_method","text":"default_vector_transport_method(M::Grassmann)\n\nReturn the ProjectionTransport as the default vector transport method for the Grassmann manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.injectivity_radius-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Grassmann)\ninjectivity_radius(M::Grassmann, p)\n\nReturn the injectivity radius on the Grassmann M, which is fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.is_flat-Tuple{Grassmann}","page":"Grassmann","title":"ManifoldsBase.is_flat","text":"is_flat(M::Grassmann)\n\nReturn true if Grassmann M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.manifold_dimension-Union{Tuple{Grassmann{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Grassmann)\n\nReturn the dimension of the Grassmann(n,k,𝔽) manifold M, i.e.\n\ndim operatornameGr(nk) = k(n-k) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Statistics.mean-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"Statistics.mean","text":"mean(\n M::Grassmann,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/4);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#The-Grassmanian-represented-as-points-on-the-[Stiefel](@ref)-manifold","page":"Grassmann","title":"The Grassmanian represented as points on the Stiefel manifold","text":"","category":"section"},{"location":"manifolds/grassmann.html","page":"Grassmann","title":"Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/GrassmannStiefel.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/grassmann.html#Manifolds.StiefelPoint","page":"Grassmann","title":"Manifolds.StiefelPoint","text":"StiefelPoint <: AbstractManifoldPoint\n\nA point on a Stiefel manifold. This point is mainly used for representing points on the Grassmann where this is also the default representation and hence equivalent to using AbstractMatrices thereon. they can also used be used as points on Stiefel.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Manifolds.StiefelTVector","page":"Grassmann","title":"Manifolds.StiefelTVector","text":"StiefelTVector <: TVector\n\nA tangent vector on the Grassmann manifold represented by a tangent vector from the tangent space of a corresponding point from the Stiefel manifold, see StiefelPoint. This is the default representation so is can be used interchangeably with just abstract matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Base.exp-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"Base.exp","text":"exp(M::Grassmann, p, X)\n\nCompute the exponential map on the Grassmann M= mathrmGr(nk) starting in p with tangent vector (direction) X. Let X = USV denote the SVD decomposition of X. Then the exponential map is written using\n\nz = p Vcos(S)V^mathrmH + Usin(S)V^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of S. A final QR decomposition z=QR is performed for numerical stability reasons, yielding the result as\n\nexp_p X = Q\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Base.log-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"Base.log","text":"log(M::Grassmann, p, q)\n\nCompute the logarithmic map on the Grassmann M$ = \\mathcal M=\\mathrm{Gr}(n,k)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads\n\nlog_p q = Vcdot operatornameatan(S) cdot U^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian. The matrices U and V are the unitary matrices, and S is the diagonal matrix containing the singular values of the SVD-decomposition\n\nUSV = (q^mathrmHp)^-1 ( q^mathrmH - q^mathrmHpp^mathrmH)\n\nIn this formula the operatornameatan is meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Base.rand-Tuple{Grassmann}","page":"Grassmann","title":"Base.rand","text":"rand(M::Grassmann; σ::Real=1.0, vector_at=nothing)\n\nWhen vector_at is nothing, return a random point p on Grassmann manifold M by generating a random (Gaussian) matrix with standard deviation σ in matching size, which is orthonormal.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_pmathrmGr(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent space at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.uniform_distribution-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, ℝ}, Any}} where {n, k}","page":"Grassmann","title":"Manifolds.uniform_distribution","text":"uniform_distribution(M::Grassmann{n,k,ℝ}, p)\n\nUniform distribution on given (real-valued) Grassmann M. Specifically, this is the normalized Haar measure on M. Generated points will be of similar type as p.\n\nThe implementation is based on Section 2.5.1 in [Chikuse2003]; see also Theorem 2.2.2(iii) in [Chikuse2003].\n\n[Chikuse2003]: Y. Chikuse: \"Statistics on Special Manifolds\", Springer New York, 2003, doi: 10.1007/978-0-387-21540-2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.distance-Tuple{Grassmann, Any, Any}","page":"Grassmann","title":"ManifoldsBase.distance","text":"distance(M::Grassmann, p, q)\n\nCompute the Riemannian distance on Grassmann manifold M= mathrmGr(nk).\n\nThe distance is given by\n\nd_mathrmGr(nk)(pq) = operatornamenorm(log_p(q))\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.inner-Tuple{Grassmann, Any, Any, Any}","page":"Grassmann","title":"ManifoldsBase.inner","text":"inner(M::Grassmann, p, X, Y)\n\nCompute the inner product for two tangent vectors X, Y from the tangent space of p on the Grassmann manifold M. The formula reads\n\ng_p(XY) = operatornametr(X^mathrmHY)\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.inverse_retract-Tuple{Grassmann, Any, Any, PolarInverseRetraction}","page":"Grassmann","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Grassmann, p, q, ::PolarInverseRetraction)\n\nCompute the inverse retraction for the PolarRetraction, on the Grassmann manifold M, i.e.,\n\noperatornameretr_p^-1q = q*(p^mathrmHq)^-1 - p\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.inverse_retract-Tuple{Grassmann, Any, Any, QRInverseRetraction}","page":"Grassmann","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M, p, q, ::QRInverseRetraction)\n\nCompute the inverse retraction for the QRRetraction, on the Grassmann manifold M, i.e.,\n\noperatornameretr_p^-1q = q(p^mathrmHq)^-1 - p\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.project-Tuple{Grassmann, Any}","page":"Grassmann","title":"ManifoldsBase.project","text":"project(M::Grassmann, p)\n\nProject p from the embedding onto the Grassmann M, i.e. compute q as the polar decomposition of p such that q^mathrmHq is the identity, where cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.project-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"ManifoldsBase.project","text":"project(M::Grassmann, p, X)\n\nProject the n-by-k X onto the tangent space of p on the Grassmann M, which is computed by\n\noperatornameproj_p(X) = X - pp^mathrmHX\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.representation_size-Union{Tuple{Grassmann{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Grassmann","title":"ManifoldsBase.representation_size","text":"representation_size(M::Grassmann{n,k})\n\nReturn the represenation size or matrix dimension of a point on the Grassmann M, i.e. (nk) for both the real-valued and the complex value case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.retract-Tuple{Grassmann, Any, Any, PolarRetraction}","page":"Grassmann","title":"ManifoldsBase.retract","text":"retract(M::Grassmann, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the Grassmann M. With USV = p + X the retraction reads\n\noperatornameretr_p X = UV^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.retract-Tuple{Grassmann, Any, Any, QRRetraction}","page":"Grassmann","title":"ManifoldsBase.retract","text":"retract(M::Grassmann, p, X, ::QRRetraction )\n\nCompute the QR-based retraction QRRetraction on the Grassmann M. With QR = p + X the retraction reads\n\noperatornameretr_p X = QD\n\nwhere D is a m n matrix with\n\nD = operatornamediagleft( operatornamesgnleft(R_ii+frac12right)_i=1^n right)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.riemann_tensor-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, ℝ}, Vararg{Any, 4}}} where {n, k}","page":"Grassmann","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::Grassmann{n,k,ℝ}, p, X, Y, Z) where {n,k}\n\nCompute the value of Riemann tensor on the real Grassmann manifold. The formula reads[Rentmeesters2011] R(XY)Z = (XY^mathrmT - YX^mathrmT)Z + Z(Y^mathrmTX - X^mathrmTY).\n\n[Rentmeesters2011]: Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.vector_transport_to-Tuple{Grassmann, Any, Any, Any, ProjectionTransport}","page":"Grassmann","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Grassmann,p,X,q,::ProjectionTransport)\n\ncompute the projection based transport on the Grassmann M by interpreting X from the tangent space at p as a point in the embedding and projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.zero_vector-Tuple{Grassmann, Vararg{Any}}","page":"Grassmann","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Grassmann, p)\n\nReturn the zero tangent vector from the tangent space at p on the Grassmann M, which is given by a zero matrix the same size as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#The-Grassmannian-represented-as-projectors","page":"Grassmann","title":"The Grassmannian represented as projectors","text":"","category":"section"},{"location":"manifolds/grassmann.html","page":"Grassmann","title":"Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/GrassmannProjector.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/grassmann.html#Manifolds.ProjectorPoint","page":"Grassmann","title":"Manifolds.ProjectorPoint","text":"ProjectorPoint <: AbstractManifoldPoint\n\nA type to represent points on a manifold Grassmann that are orthogonal projectors, i.e. a matrix p mathbb F^nn projecting onto a k-dimensional subspace.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Manifolds.ProjectorTVector","page":"Grassmann","title":"Manifolds.ProjectorTVector","text":"ProjectorTVector <: TVector\n\nA type to represent tangent vectors to points on a Grassmann manifold that are orthogonal projectors.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/grassmann.html#Base.exp-Tuple{Grassmann, ProjectorPoint, ProjectorTVector}","page":"Grassmann","title":"Base.exp","text":"exp(M::Grassmann, p::ProjectorPoint, X::ProjectorTVector)\n\nCompute the exponential map on the Grassmann as\n\n exp_pX = operatornameExp(Xp)poperatornameExp(-Xp)\n\nwhere operatornameExp denotes the matrix exponential and AB = AB-BA denotes the matrix commutator.\n\nFor details, see Proposition 3.2 in [BendokatZimmermannAbsil2020].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.canonical_project!-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k}, ProjectorPoint, Any}} where {n, k}","page":"Grassmann","title":"Manifolds.canonical_project!","text":"canonical_project!(M::Grassmann{n,k}, q::ProjectorPoint, p)\n\nCompute the canonical projection π(p) from the Stiefel manifold onto the Grassmann manifold when represented as ProjectorPoint, i.e.\n\n π^mathrmSG(p) = pp^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.differential_canonical_project!-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k}, ProjectorTVector, Any, Any}} where {n, k}","page":"Grassmann","title":"Manifolds.differential_canonical_project!","text":"canonical_project!(M::Grassmann{n,k}, q::ProjectorPoint, p)\n\nCompute the canonical projection π(p) from the Stiefel manifold onto the Grassmann manifold when represented as ProjectorPoint, i.e.\n\n Dπ^mathrmSG(p)X = Xp^mathrmT + pX^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#Manifolds.horizontal_lift-Tuple{Stiefel, Any, ProjectorTVector}","page":"Grassmann","title":"Manifolds.horizontal_lift","text":"horizontal_lift(N::Stiefel{n,k}, q, X::ProjectorTVector)\n\nCompute the horizontal lift of X from the tangent space at p=π(q) on the Grassmann manifold, i.e.\n\nY = Xq T_qmathrmSt(nk)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.check_point","text":"check_point(::Grassmann{n,k}, p::ProjectorPoint; kwargs...)\n\nCheck whether an orthogonal projector is a point from the Grassmann(n,k) manifold, i.e. the ProjectorPoint p mathbb F^nn, mathbb F mathbb R mathbb C has to fulfill p^mathrmT = p, p^2=p, and `\\operatorname{rank} p = k.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.check_size-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.check_size","text":"check_size(M::Grassmann{n,k,𝔽}, p::ProjectorPoint; kwargs...) where {n,k}\n\nCheck that the ProjectorPoint is of correct size, i.e. from mathbb F^nn\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint, ProjectorTVector}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.check_vector","text":"check_vector(::Grassmann{n,k,𝔽}, p::ProjectorPoint, X::ProjectorTVector; kwargs...) where {n,k,𝔽}\n\nCheck whether the ProjectorTVector X is from the tangent space T_poperatornameGr(nk) at the ProjectorPoint p on the Grassmann manifold operatornameGr(nk). This means that X has to be symmetric and that\n\nXp + pX = X\n\nmust hold, where the kwargs can be used to check both for symmetrix of X` and this equality up to a certain tolerance.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.get_embedding-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k, 𝔽}, ProjectorPoint}} where {n, k, 𝔽}","page":"Grassmann","title":"ManifoldsBase.get_embedding","text":"get_embedding(M::Grassmann{n,k,𝔽}, p::ProjectorPoint) where {n,k,𝔽}\n\nReturn the embedding of the ProjectorPoint representation of the Grassmann manifold, i.e. the Euclidean space mathbb F^nn.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.parallel_transport_direction-Tuple{Grassmann, ProjectorPoint, ProjectorTVector, ProjectorTVector}","page":"Grassmann","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(\n M::Grassmann,\n p::ProjectorPoint,\n X::ProjectorTVector,\n d::ProjectorTVector\n)\n\nCompute the parallel transport of X from the tangent space at p into direction d, i.e. to q=exp_pd. The formula is given in Proposition 3.5 of [BendokatZimmermannAbsil2020] as\n\nmathcalP_q p(X) = operatornameExp(dp)XoperatornameExp(-dp)\n\nwhere operatornameExp denotes the matrix exponential and AB = AB-BA denotes the matrix commutator.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/grassmann.html#ManifoldsBase.representation_size-Union{Tuple{k}, Tuple{n}, Tuple{Grassmann{n, k}, ProjectorPoint}} where {n, k}","page":"Grassmann","title":"ManifoldsBase.representation_size","text":"representation_size(M::Grassmann{n,k}, p::ProjectorPoint)\n\nReturn the represenation size or matrix dimension of a point on the Grassmann M when using ProjectorPoints, i.e. (nn).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Essential-Manifold","page":"Essential manifold","title":"Essential Manifold","text":"","category":"section"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"The essential manifold is modeled as an AbstractPowerManifold of the 3times3 Rotations and uses NestedPowerRepresentation.","category":"page"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/EssentialManifold.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/essentialmanifold.html#Manifolds.EssentialManifold","page":"Essential manifold","title":"Manifolds.EssentialManifold","text":"EssentialManifold <: AbstractPowerManifold{ℝ}\n\nThe essential manifold is the space of the essential matrices which is represented as a quotient space of the Rotations manifold product mathrmSO(3)^2.\n\nLet R_x(θ) R_y(θ) R_x(θ) in ℝ^xtimes 3 denote the rotation around the z, y, and x axis in ℝ^3, respectively, and further the groups\n\nH_z = bigl(R_z(θ)R_z(θ)) big θ -ππ) bigr\n\nand\n\nH_π = bigl (II) (R_x(π) R_x(π)) (IR_z(π)) (R_x(π) R_y(π)) bigr\n\nacting elementwise on the left from mathrmSO(3)^2 (component wise).\n\nThen the unsigned Essential manifold mathcalM_textE can be identified with the quotient space\n\nmathcalM_textE = (textSO(3)textSO(3))(H_z H_π)\n\nand for the signed Essential manifold mathcalM_textƎ, the quotient reads\n\nmathcalM_textƎ = (textSO(3)textSO(3))(H_z)\n\nAn essential matrix is defined as\n\nE = (R_1)^T T_2 - T_1_ R_2\n\nwhere the poses of two cameras (R_i T_i) i=12, are contained in the space of rigid body transformations SE(3) and the operator _colon ℝ^3 to operatornameSkewSym(3) denotes the matrix representation of the cross product operator. For more details see [TronDaniilidis2017].\n\nConstructor\n\nEssentialManifold(is_signed=true)\n\nGenerate the manifold of essential matrices, either the signed (is_signed=true) or unsigned (is_signed=false) variant.\n\n[TronDaniilidis2017]: Tron R.; Daniilidis K.; The Space of Essential Matrices as a Riemannian Quotient AbstractManifold. SIAM Journal on Imaging Sciences (2017), DOI: 10.1137/16M1091332, PDF: https://www.cis.upenn.edu/~kostas/mypub.dir/tron17siam.pdf.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/essentialmanifold.html#Functions","page":"Essential manifold","title":"Functions","text":"","category":"section"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"Modules = [Manifolds]\nPrivate = false\nPages = [\"manifolds/EssentialManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/essentialmanifold.html#Base.exp-Tuple{EssentialManifold, Vararg{Any}}","page":"Essential manifold","title":"Base.exp","text":"exp(M::EssentialManifold, p, X)\n\nCompute the exponential map on the EssentialManifold from p into direction X, i.e.\n\ntextexp_p(X) =textexp_g( tilde X) quad g in text(SO)(3)^2\n\nwhere tilde X is the horizontal lift of X[TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Base.log-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"Base.log","text":"log(M::EssentialManifold, p, q)\n\nCompute the logarithmic map on the EssentialManifold M, i.e. the tangent vector, whose geodesic starting from p reaches q after time 1. Here, p=(R_p_1R_p_2) and q=(R_q_1R_q_2) are elements of SO(3)^2. We use that any essential matrix can, up to scale, be decomposed to\n\nE = R_1^T e_z_R_2\n\nwhere (R_1R_2)SO(3)^2. Two points in SO(3)^2 are equivalent iff their corresponding essential matrices are equal (up to a sign flip). To compute the logarithm, we first move q to another representative of its equivalence class. For this, we find t= t_textopt for which the function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nwhere d() is the distance function in SO(3), is minimized. Further, the group H_z acting on the left on SO(3)^2 is defined as\n\nH_z = (R_z(θ)R_z(θ))colon θ in -ππ) \n\nwhere R_z(θ) is the rotation around the z axis with angle θ. Points in H_z are denoted by S_z. Then, the logarithm is defined as\n\nlog_p (S_z(t_textopt)q) = textLog(R_p_i^T R_z(t_textopt)R_b_i)_i=12\n\nwhere textLog is the logarithm on SO(3). For more details see [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.check_point-Tuple{EssentialManifold, Any}","page":"Essential manifold","title":"ManifoldsBase.check_point","text":"check_point(M::EssentialManifold, p; kwargs...)\n\nCheck whether the matrix is a valid point on the EssentialManifold M, i.e. a 2-element array containing SO(3) matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.check_vector-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.check_vector","text":"check_vector(M::EssentialManifold, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the EssentialManifold M, i.e. X has to be a 2-element array of 3-by-3 skew-symmetric matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.distance-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.distance","text":"distance(M::EssentialManifold, p, q)\n\nCompute the Riemannian distance between the two points p and q on the EssentialManifold. This is done by computing the distance of the equivalence classes p and q of the points p=(R_p_1R_p_2) q=(R_q_1R_q_2) SO(3)^2, respectively. Two points in SO(3)^2 are equivalent iff their corresponding essential matrices, given by\n\nE = R_1^T e_z_R_2\n\nare equal (up to a sign flip). Using the logarithmic map, the distance is given by\n\ntextdist(pq) = textlog_p q = log_p (S_z(t_textopt)q) \n\nwhere S_z H_z = (R_z(θ)R_z(θ))colon θ in -ππ) in which R_z(θ) is the rotation around the z axis with angle θ and t_textopt is the minimizer of the cost function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nwhere d() is the distance function in SO(3)[TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.is_flat-Tuple{EssentialManifold}","page":"Essential manifold","title":"ManifoldsBase.is_flat","text":"is_flat(::EssentialManifold)\n\nReturn false. EssentialManifold is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.manifold_dimension-Tuple{EssentialManifold}","page":"Essential manifold","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::EssentialManifold{is_signed, ℝ})\n\nReturn the manifold dimension of the EssentialManifold, which is 5[TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.parallel_transport_to-Tuple{EssentialManifold, Any, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::EssentialManifold, p, X, q)\n\nCompute the vector transport of the tangent vector X at p to q on the EssentialManifold M using left translation of the ambient group.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#ManifoldsBase.project-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"ManifoldsBase.project","text":"project(M::EssentialManifold, p, X)\n\nProject the matrix X onto the tangent space\n\nT_p textSO(3)^2 = T_textvptextSO(3)^2 T_texthptextSO(3)^2\n\nby first computing its projection onto the vertical space T_textvptextSO(3)^2 using vert_proj. Then the orthogonal projection of X onto the horizontal space T_texthptextSO(3)^2 is defined as\n\nPi_h(X) = X - fractextvert_proj_p(X)2 beginbmatrix R_1^T e_z R_2^T e_z endbmatrix\n\nwith R_i = R_0 R_i i=12 where R_i is part of the pose of camera i g_i = (R_iT_i) textSE(3) and R_0 textSO(3) such that R_0(T_2-T_1) = e_z.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Internal-Functions","page":"Essential manifold","title":"Internal Functions","text":"","category":"section"},{"location":"manifolds/essentialmanifold.html","page":"Essential manifold","title":"Essential manifold","text":"Modules = [Manifolds]\nPublic = false\nPages = [\"manifolds/EssentialManifold.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair-Tuple{Any, Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair","text":"dist_min_angle_pair(p, q)\n\nThis function computes the global minimizer of the function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nfor the given values. This is done by finding the discontinuity points t_d_i i=12 of its derivative and using Newton's method to minimize the function over the intervals t_d_1t_d_2 and t_d_2t_d_1+2π separately. Then, the minimizer for which f is minimal is chosen and given back together with the minimal value. For more details see Algorithm 1 in [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair_compute_df_break-Tuple{Any, Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair_compute_df_break","text":"dist_min_angle_pair_compute_df_break(t_break, q)\n\nThis function computes the derivatives of each term f_i i=12 at discontinuity point t_break. For more details see [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair_df_newton-NTuple{9, Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair_df_newton","text":"dist_min_angle_pair_df_newton(m1, Φ1, c1, m2, Φ2, c2, t_min, t_low, t_high)\n\nThis function computes the minimizer of the function\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\nin the interval t_low, t_high using Newton's method. For more details see [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.dist_min_angle_pair_discontinuity_distance-Tuple{Any}","page":"Essential manifold","title":"Manifolds.dist_min_angle_pair_discontinuity_distance","text":"dist_min_angle_pair_discontinuity_distance(q)\n\nThis function computes the point t_textdi for which the first derivative of\n\nf(t) = f_1 + f_2 quad f_i = frac12 θ^2_i(t) quad θ_i(t)=d(R_p_iR_z(t)R_b_i) text for i=12\n\ndoes not exist. This is the case for sin(θ_i(t_textdi)) = 0. For more details see Proposition 9 and its proof, as well as Lemma 1 in [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Manifolds.vert_proj-Tuple{EssentialManifold, Any, Any}","page":"Essential manifold","title":"Manifolds.vert_proj","text":"vert_proj(M::EssentialManifold, p, X)\n\nProject X onto the vertical space T_textvptextSO(3)^2 with\n\ntextvert_proj_p(X) = e_z^T(R_1 X_1 + R_2 X_2)\n\nwhere e_z is the third unit vector, X_i T_ptextSO(3) for i=12 and it holds R_i = R_0 R_i i=12 where R_i is part of the pose of camera i g_i = (R_iT_i) textSE(3) and R_0 textSO(3) such that R_0(T_2-T_1) = e_z [TronDaniilidis2017].\n\n\n\n\n\n","category":"method"},{"location":"manifolds/essentialmanifold.html#Literature","page":"Essential manifold","title":"Literature","text":"","category":"section"},{"location":"manifolds/power.html#PowerManifoldSection","page":"Power manifold","title":"Power manifold","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"A power manifold is based on a AbstractManifold mathcal M to build a mathcal M^n_1 times n_2 times cdots times n_m. In the case where m=1 we can represent a manifold-valued vector of data of length n_1, for example a time series. The case where m=2 is useful for representing manifold-valued matrices of data of size n_1 times n_2, for example certain types of images.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"There are three available representations for points and vectors on a power manifold:","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"ArrayPowerRepresentation (the default one), very efficient but only applicable when points on the underlying manifold are represented using plain AbstractArrays.\nNestedPowerRepresentation, applicable to any manifold. It assumes that points on the underlying manifold are represented using mutable data types.\nNestedReplacingPowerRepresentation, applicable to any manifold. It does not mutate points on the underlying manifold, replacing them instead when appropriate.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"Below are some examples of usage of these representations.","category":"page"},{"location":"manifolds/power.html#Example","page":"Power manifold","title":"Example","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"There are two ways to store the data: in a multidimensional array or in a nested array.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"Let's look at an example for both. Let mathcal M be Sphere(2) the 2-sphere and we want to look at vectors of length 4.","category":"page"},{"location":"manifolds/power.html#ArrayPowerRepresentation","page":"Power manifold","title":"ArrayPowerRepresentation","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"For the default, the ArrayPowerRepresentation, we store the data in a multidimensional array,","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds\nM = PowerManifold(Sphere(2), 4)\np = cat([1.0, 0.0, 0.0],\n [1/sqrt(2.0), 1/sqrt(2.0), 0.0],\n [1/sqrt(2.0), 0.0, 1/sqrt(2.0)],\n [0.0, 1.0, 0.0]\n ,dims=2)","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"which is a valid point i.e.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"is_point(M, p)","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"This can also be used in combination with HybridArrays.jl and StaticArrays.jl, by setting","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using HybridArrays, StaticArrays\nq = HybridArray{Tuple{3,StaticArrays.Dynamic()},Float64,2}(p)","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"which is still a valid point on M and PowerManifold works with these, too.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"An advantage of this representation is that it is quite efficient, especially when a HybridArray (from the HybridArrays.jl package) is used to represent a point on the power manifold. A disadvantage is not being able to easily identify parts of the multidimensional array that correspond to a single point on the base manifold. Another problem is, that accessing a single point is p[:, 1] which might be unintuitive.","category":"page"},{"location":"manifolds/power.html#NestedPowerRepresentation","page":"Power manifold","title":"NestedPowerRepresentation","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"For the NestedPowerRepresentation we can now do","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds\nM = PowerManifold(Sphere(2), NestedPowerRepresentation(), 4)\np = [ [1.0, 0.0, 0.0],\n [1/sqrt(2.0), 1/sqrt(2.0), 0.0],\n [1/sqrt(2.0), 0.0, 1/sqrt(2.0)],\n [0.0, 1.0, 0.0],\n ]","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"which is again a valid point so is_point(M, p) here also yields true. A disadvantage might be that with nested arrays one loses a little bit of performance. The data however is nicely encapsulated. Accessing the first data item is just p[1].","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"For accessing points on power manifolds in both representations you can use get_component and set_component! functions. They work work both point representations.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds\nM = PowerManifold(Sphere(2), NestedPowerRepresentation(), 4)\np = [ [1.0, 0.0, 0.0],\n [1/sqrt(2.0), 1/sqrt(2.0), 0.0],\n [1/sqrt(2.0), 0.0, 1/sqrt(2.0)],\n [0.0, 1.0, 0.0],\n ]\nset_component!(M, p, [0.0, 0.0, 1.0], 4)\nget_component(M, p, 4)","category":"page"},{"location":"manifolds/power.html#NestedReplacingPowerRepresentation","page":"Power manifold","title":"NestedReplacingPowerRepresentation","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"The final representation is the NestedReplacingPowerRepresentation. It is similar to the NestedPowerRepresentation but it does not perform in-place operations on the points on the underlying manifold. The example below uses this representation to store points on a power manifold of the SpecialEuclidean group in-line in an Vector for improved efficiency. When having a mixture of both, i.e. an array structure that is nested (like ´NestedPowerRepresentation) in the sense that the elements of the main vector are immutable, then changing the elements can not be done in an in-place way and hence NestedReplacingPowerRepresentation has to be used.","category":"page"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"using Manifolds, StaticArrays\nR2 = Rotations(2)\n\nG = SpecialEuclidean(2)\nN = 5\nGN = PowerManifold(G, NestedReplacingPowerRepresentation(), N)\n\nq = [1.0 0.0; 0.0 1.0]\np1 = [ProductRepr(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, i)))) for i in 1:N]\np2 = [ProductRepr(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, -i)))) for i in 1:N]\n\nX = similar(p1);\n\nlog!(GN, X, p1, p2)","category":"page"},{"location":"manifolds/power.html#Types-and-Functions","page":"Power manifold","title":"Types and Functions","text":"","category":"section"},{"location":"manifolds/power.html","page":"Power manifold","title":"Power manifold","text":"Modules = [Manifolds]\nPages = [\"manifolds/PowerManifold.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/power.html#Manifolds.ArrayPowerRepresentation","page":"Power manifold","title":"Manifolds.ArrayPowerRepresentation","text":"ArrayPowerRepresentation\n\nRepresentation of points and tangent vectors on a power manifold using multidimensional arrays where first dimensions are equal to representation_size of the wrapped manifold and the following ones are equal to the number of elements in each direction.\n\nTorus uses this representation.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.PowerFVectorDistribution","page":"Power manifold","title":"Manifolds.PowerFVectorDistribution","text":"PowerFVectorDistribution([type::VectorBundleFibers], [x], distr)\n\nGenerates a random vector at a point from vector space (a fiber of a tangent bundle) of type type using the power distribution of distr.\n\nVector space type and point can be automatically inferred from distribution distr.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.PowerMetric","page":"Power manifold","title":"Manifolds.PowerMetric","text":"PowerMetric <: AbstractMetric\n\nRepresent the AbstractMetric on an AbstractPowerManifold, i.e. the inner product on the tangent space is the sum of the inner product of each elements tangent space of the power manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.PowerPointDistribution","page":"Power manifold","title":"Manifolds.PowerPointDistribution","text":"PowerPointDistribution(M::AbstractPowerManifold, distribution)\n\nPower distribution on manifold M, based on distribution.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/power.html#Manifolds.flat-Tuple{AbstractPowerManifold, Vararg{Any}}","page":"Power manifold","title":"Manifolds.flat","text":"flat(M::AbstractPowerManifold, p, X)\n\nuse the musical isomorphism to transform the tangent vector X from the tangent space at p on an AbstractPowerManifold M to a cotangent vector. This can be done elementwise for each entry of X (and p).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#Manifolds.manifold_volume-Union{Tuple{PowerManifold{𝔽, <:AbstractManifold, TSize}}, Tuple{TSize}, Tuple{𝔽}} where {𝔽, TSize}","page":"Power manifold","title":"Manifolds.manifold_volume","text":"manifold_volume(M::PowerManifold)\n\nReturn the manifold volume of an PowerManifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#Manifolds.sharp-Tuple{AbstractPowerManifold, Vararg{Any}}","page":"Power manifold","title":"Manifolds.sharp","text":"sharp(M::AbstractPowerManifold, p, ξ::RieszRepresenterCotangentVector)\n\nUse the musical isomorphism to transform the cotangent vector ξ from the tangent space at p on an AbstractPowerManifold M to a tangent vector. This can be done elementwise for every entry of ξ (and p).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#Manifolds.volume_density-Tuple{PowerManifold, Any, Any}","page":"Power manifold","title":"Manifolds.volume_density","text":"volume_density(M::PowerManifold, p, X)\n\nReturn volume density on the PowerManifold M, i.e. product of constituent volume densities.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#ManifoldsBase.change_metric-Tuple{AbstractPowerManifold, AbstractMetric, Any, Any}","page":"Power manifold","title":"ManifoldsBase.change_metric","text":"change_metric(M::AbstractPowerManifold, ::AbstractMetric, p, X)\n\nSince the metric on a power manifold decouples, the change of metric can be done elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/power.html#ManifoldsBase.change_representer-Tuple{AbstractPowerManifold, AbstractMetric, Any, Any}","page":"Power manifold","title":"ManifoldsBase.change_representer","text":"change_representer(M::AbstractPowerManifold, ::AbstractMetric, p, X)\n\nSince the metric on a power manifold decouples, the change of a representer can be done elementwise\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#Rotations","page":"Rotations","title":"Rotations","text":"","category":"section"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"The manifold mathrmSO(n) of orthogonal matrices with determinant +1 in ℝ^n n, i.e.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"mathrmSO(n) = biglR ℝ^n n big R R^mathrmT =\nR^mathrmTR = I_n det(R) = 1 bigr","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"The Lie group mathrmSO(n) is a subgroup of the orthogonal group mathrmO(n) and also known as the special orthogonal group or the set of rotations group. See also SpecialOrthogonal, which is this manifold equipped with the group operation.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"The tangent space to a point p mathrmSO(n) is given by","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"T_pmathrmSO(n) = X X=pYqquad Y=-Y^mathrmT","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"i.e. all vectors that are a product of a skew symmetric matrix multiplied with p.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Since the orthogonal matrices mathrmSO(n) are a Lie group, tangent vectors can also be represented by elements of the corresponding Lie algebra, which is the tangent space at the identity element. In the notation above, this means we just store the component Y of X.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"This convention allows for more efficient operations on tangent vectors. Tangent spaces at different points are different vector spaces.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Let L_R mathrmSO(n) mathrmSO(n) where R mathrmSO(n) be the left-multiplication by R, that is L_R(S) = RS. The tangent space at rotation R, T_R mathrmSO(n), is related to the tangent space at the identity rotation I_n by the differential of L_R at identity, (mathrmdL_R)_I_n T_I_n mathrmSO(n) T_R mathrmSO(n). To convert the tangent vector representation at the identity rotation X T_I_n mathrmSO(n) (i.e., the default) to the matrix representation of the corresponding tangent vector Y at a rotation R use the embed which implements the following multiplication: Y = RX T_R mathrmSO(n). You can compare the functions log and exp to see how it works in practice.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Several common functions are also implemented together with orthogonal and unitary matrices.","category":"page"},{"location":"manifolds/rotations.html","page":"Rotations","title":"Rotations","text":"Modules = [Manifolds]\nPages = [\"manifolds/Rotations.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/rotations.html#Manifolds.NormalRotationDistribution","page":"Rotations","title":"Manifolds.NormalRotationDistribution","text":"NormalRotationDistribution(M::Rotations, d::Distribution, x::TResult)\n\nDistribution that returns a random point on the manifold Rotations M. Random point is generated using base distribution d and the type of the result is adjusted to TResult.\n\nSee normal_rotation_distribution for details.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/rotations.html#Manifolds.Rotations","page":"Rotations","title":"Manifolds.Rotations","text":"Rotations{N} <: AbstractManifold{ℝ}\n\nThe manifold of rotation matrices of sice n n, i.e. real-valued orthogonal matrices with determinant +1.\n\nConstructor\n\nRotations(n)\n\nGenerate the manifold of n n rotation matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/rotations.html#Manifolds.angles_4d_skew_sym_matrix-Tuple{Any}","page":"Rotations","title":"Manifolds.angles_4d_skew_sym_matrix","text":"angles_4d_skew_sym_matrix(A)\n\nThe Lie algebra of Rotations(4) in ℝ^4 4, 𝔰𝔬(4), consists of 4 4 skew-symmetric matrices. The unique imaginary components of their eigenvalues are the angles of the two plane rotations. This function computes these more efficiently than eigvals.\n\nBy convention, the returned values are sorted in decreasing order (corresponding to the same ordering of angles as cos_angles_4d_rotation_matrix).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#Manifolds.normal_rotation_distribution-Union{Tuple{N}, Tuple{Rotations{N}, Any, Real}} where N","page":"Rotations","title":"Manifolds.normal_rotation_distribution","text":"normal_rotation_distribution(M::Rotations, p, σ::Real)\n\nReturn a random point on the manifold Rotations M by generating a (Gaussian) random orthogonal matrix with determinant +1. Let\n\nQR = A\n\nbe the QR decomposition of a random matrix A, then the formula reads\n\np = QD\n\nwhere D is a diagonal matrix with the signs of the diagonal entries of R, i.e.\n\nD_ij=begincases operatornamesgn(R_ij) textif i=j 0 textotherwise endcases\n\nIt can happen that the matrix gets -1 as a determinant. In this case, the first and second columns are swapped.\n\nThe argument p is used to determine the type of returned points.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.injectivity_radius-Tuple{Rotations, PolarRetraction}","page":"Rotations","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::Rotations, ::PolarRetraction)\n\nReturn the radius of injectivity for the PolarRetraction on the Rotations M which is fracπsqrt2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.inverse_retract-Tuple{Rotations, Any, Any, PolarInverseRetraction}","page":"Rotations","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M, p, q, ::PolarInverseRetraction)\n\nCompute a vector from the tangent space T_pmathrmSO(n) of the point p on the Rotations manifold M with which the point q can be reached by the PolarRetraction from the point p after time 1.\n\nThe formula reads\n\noperatornameretr^-1_p(q)\n= -frac12(p^mathrmTqs - (p^mathrmTqs)^mathrmT)\n\nwhere s is the solution to the Sylvester equation\n\np^mathrmTqs + s(p^mathrmTq)^mathrmT + 2I_n = 0\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.inverse_retract-Tuple{Rotations, Any, Any, QRInverseRetraction}","page":"Rotations","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Rotations, p, q, ::QRInverseRetraction)\n\nCompute a vector from the tangent space T_pmathrmSO(n) of the point p on the Rotations manifold M with which the point q can be reached by the QRRetraction from the point q after time 1.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.parallel_transport_direction-Tuple{Rotations, Any, Any, Any}","page":"Rotations","title":"ManifoldsBase.parallel_transport_direction","text":"parallel_transport_direction(M::Rotations, p, X, d)\n\nCompute parallel transport of vector X tangent at p on the Rotations manifold in the direction d. The formula, provided in [Rentmeesters2011], reads:\n\nmathcal P_qgets pX = q^mathrmTp operatornameExp(d2) X operatornameExp(d2)\n\nwhere q=exp_p d.\n\nThe formula simplifies to identity for 2-D rotations.\n\n[Rentmeesters2011]: Rentmeesters Q., “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.project-Tuple{Rotations, Any}","page":"Rotations","title":"ManifoldsBase.project","text":"project(M::Rotations, p; check_det = true)\n\nProject p to the nearest point on manifold M.\n\nGiven the singular value decomposition p = U Σ V^mathrmT, with the singular values sorted in descending order, the projection is\n\noperatornameproj_mathrmSO(n)(p) =\nUoperatornamediagleft11det(U V^mathrmT)right V^mathrmT\n\nThe diagonal matrix ensures that the determinant of the result is +1. If p is expected to be almost special orthogonal, then you may avoid this check with check_det = false.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#ManifoldsBase.zero_vector-Tuple{Rotations, Any}","page":"Rotations","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Rotations, p)\n\nReturn the zero tangent vector from the tangent space art p on the Rotations as an element of the Lie group, i.e. the zero matrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/rotations.html#Literature","page":"Rotations","title":"Literature","text":"","category":"section"},{"location":"manifolds/generalizedgrassmann.html#Generalized-Grassmann","page":"Generalized Grassmann","title":"Generalized Grassmann","text":"","category":"section"},{"location":"manifolds/generalizedgrassmann.html","page":"Generalized Grassmann","title":"Generalized Grassmann","text":"Modules = [Manifolds]\nPages = [\"manifolds/GeneralizedGrassmann.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/generalizedgrassmann.html#Manifolds.GeneralizedGrassmann","page":"Generalized Grassmann","title":"Manifolds.GeneralizedGrassmann","text":"GeneralizedGrassmann{n,k,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe generalized Grassmann manifold operatornameGr(nkB) consists of all subspaces spanned by k linear independent vectors 𝔽^n, where 𝔽 ℝ ℂ is either the real- (or complex-) valued vectors. This yields all k-dimensional subspaces of ℝ^n for the real-valued case and all 2k-dimensional subspaces of ℂ^n for the second.\n\nThe manifold can be represented as\n\noperatornameGr(n k B) = bigl operatornamespan(p) big p 𝔽^n k p^mathrmHBp = I_k\n\nwhere cdot^mathrmH denotes the complex conjugate (or Hermitian) transpose and I_k is the k k identity matrix. This means, that the columns of p form an unitary basis of the subspace with respect to the scaled inner product, that is a point on operatornameGr(nkB), and hence the subspace can actually be represented by a whole equivalence class of representers. For B=I_n this simplifies to the Grassmann manifold.\n\nThe tangent space at a point (subspace) p is given by\n\nT_xmathrmGr(nkB) = bigl\nX 𝔽^n k \nX^mathrmHBp + p^mathrmHBX = 0_k bigr\n\nwhere 0_k denotes the k k zero matrix.\n\nNote that a point p operatornameGr(nkB) might be represented by different matrices (i.e. matrices with B-unitary column vectors that span the same subspace). Different representations of p also lead to different representation matrices for the tangent space T_pmathrmGr(nkB)\n\nThe manifold is named after Hermann G. Graßmann (1809-1877).\n\nConstructor\n\nGeneralizedGrassmann(n, k, B=I_n, field=ℝ)\n\nGenerate the (real-valued) Generalized Grassmann manifold of ntimes k dimensional orthonormal matrices with scalar product B.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/generalizedgrassmann.html#Base.exp-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"Base.exp","text":"exp(M::GeneralizedGrassmann, p, X)\n\nCompute the exponential map on the GeneralizedGrassmann M= mathrmGr(nkB) starting in p with tangent vector (direction) X. Let X^mathrmHBX = USV denote the SVD decomposition of X^mathrmHBX. Then the exponential map is written using\n\nexp_p X = p Vcos(S)V^mathrmH + Usin(S)V^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian and the cosine and sine are applied element wise to the diagonal entries of S.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#Base.log-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"Base.log","text":"log(M::GeneralizedGrassmann, p, q)\n\nCompute the logarithmic map on the GeneralizedGrassmann M$ = \\mathcal M=\\mathrm{Gr}(n,k,B)$, i.e. the tangent vector X whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads\n\nlog_p q = Vcdot operatornameatan(S) cdot U^mathrmH\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian. The matrices U and V are the unitary matrices, and S is the diagonal matrix containing the singular values of the SVD-decomposition\n\nUSV = (q^mathrmHBp)^-1 ( q^mathrmH - q^mathrmHBpp^mathrmH)\n\nIn this formula the operatornameatan is meant elementwise.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#Base.rand-Tuple{GeneralizedGrassmann}","page":"Generalized Grassmann","title":"Base.rand","text":"rand(::GeneralizedGrassmann; vector_at=nothing, σ::Real=1.0)\n\nWhen vector_at is nothing, return a random (Gaussian) point p on the GeneralizedGrassmann manifold M by generating a (Gaussian) matrix with standard deviation σ and return the (generalized) orthogonalized version, i.e. return the projection onto the manifold of the Q component of the QR decomposition of the random matrix of size nk.\n\nWhen vector_at is not nothing, return a (Gaussian) random vector from the tangent space T_vector_atmathrmSt(nk) with mean zero and standard deviation σ by projecting a random Matrix onto the tangent vector at vector_at.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.change_metric-Tuple{GeneralizedGrassmann, EuclideanMetric, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.change_metric","text":"change_metric(M::GeneralizedGrassmann, ::EuclideanMetric, p X)\n\nChange X to the corresponding vector with respect to the metric of the GeneralizedGrassmann M, i.e. let B=LL be the Cholesky decomposition of the matrix M.B, then the corresponding vector is LX.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.change_representer-Tuple{GeneralizedGrassmann, EuclideanMetric, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.change_representer","text":"change_representer(M::GeneralizedGrassmann, ::EuclideanMetric, p, X)\n\nChange X to the corresponding representer of a cotangent vector at p with respect to the scaled metric of the GeneralizedGrassmann M, i.e, since\n\ng_p(XY) = operatornametr(Y^mathrmHBZ) = operatornametr(X^mathrmHZ) = XZ\n\nhas to hold for all Z, where the repreenter X is given, the resulting representer with respect to the metric on the GeneralizedGrassmann is given by Y = B^-1X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedGrassmann{n, k, 𝔽}, Any}} where {n, k, 𝔽}","page":"Generalized Grassmann","title":"ManifoldsBase.check_point","text":"check_point(M::GeneralizedGrassmann{n,k,𝔽}, p)\n\nCheck whether p is representing a point on the GeneralizedGrassmann M, i.e. its a n-by-k matrix of unitary column vectors with respect to the B inner prudct and of correct eltype with respect to 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.check_vector-Union{Tuple{𝔽}, Tuple{k}, Tuple{n}, Tuple{GeneralizedGrassmann{n, k, 𝔽}, Any, Any}} where {n, k, 𝔽}","page":"Generalized Grassmann","title":"ManifoldsBase.check_vector","text":"check_vector(M::GeneralizedGrassmann{n,k,𝔽}, p, X; kwargs...)\n\nCheck whether X is a tangent vector in the tangent space of p on the GeneralizedGrassmann M, i.e. that X is of size and type as well as that\n\n p^mathrmHBX + overlineX^mathrmHBp = 0_k\n\nwhere cdot^mathrmH denotes the complex conjugate transpose or Hermitian, overlinecdot the (elementwise) complex conjugate, and 0_k denotes the k k zero natrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.distance-Tuple{GeneralizedGrassmann, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.distance","text":"distance(M::GeneralizedGrassmann, p, q)\n\nCompute the Riemannian distance on GeneralizedGrassmann manifold M= mathrmGr(nkB).\n\nThe distance is given by\n\nd_mathrmGr(nkB)(pq) = operatornamenorm(log_p(q))\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.injectivity_radius-Tuple{GeneralizedGrassmann}","page":"Generalized Grassmann","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::GeneralizedGrassmann)\ninjectivity_radius(M::GeneralizedGrassmann, p)\n\nReturn the injectivity radius on the GeneralizedGrassmann M, which is fracπ2.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.inner-Union{Tuple{k}, Tuple{n}, Tuple{GeneralizedGrassmann{n, k}, Any, Any, Any}} where {n, k}","page":"Generalized Grassmann","title":"ManifoldsBase.inner","text":"inner(M::GeneralizedGrassmann, p, X, Y)\n\nCompute the inner product for two tangent vectors X, Y from the tangent space of p on the GeneralizedGrassmann manifold M. The formula reads\n\ng_p(XY) = operatornametr(X^mathrmHBY)\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.is_flat-Tuple{GeneralizedGrassmann}","page":"Generalized Grassmann","title":"ManifoldsBase.is_flat","text":"is_flat(M::GeneralizedGrassmann)\n\nReturn true if GeneralizedGrassmann M is one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.manifold_dimension-Union{Tuple{GeneralizedGrassmann{n, k, 𝔽}}, Tuple{𝔽}, Tuple{k}, Tuple{n}} where {n, k, 𝔽}","page":"Generalized Grassmann","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::GeneralizedGrassmann)\n\nReturn the dimension of the GeneralizedGrassmann(n,k,𝔽) manifold M, i.e.\n\ndim operatornameGr(nkB) = k(n-k) dim_ℝ 𝔽\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.project-Tuple{GeneralizedGrassmann, Any, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.project","text":"project(M::GeneralizedGrassmann, p, X)\n\nProject the n-by-k X onto the tangent space of p on the GeneralizedGrassmann M, which is computed by\n\noperatornameproj_p(X) = X - pp^mathrmHB^mathrmTX\n\nwhere cdot^mathrmH denotes the complex conjugate transposed or Hermitian and cdot^mathrmT the transpose.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.project-Tuple{GeneralizedGrassmann, Any}","page":"Generalized Grassmann","title":"ManifoldsBase.project","text":"project(M::GeneralizedGrassmann, p)\n\nProject p from the embedding onto the GeneralizedGrassmann M, i.e. compute q as the polar decomposition of p such that q^mathrmHBq is the identity, where cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.representation_size-Union{Tuple{GeneralizedGrassmann{n, k}}, Tuple{k}, Tuple{n}} where {n, k}","page":"Generalized Grassmann","title":"ManifoldsBase.representation_size","text":"representation_size(M::GeneralizedGrassmann{n,k})\n\nReturn the represenation size or matrix dimension of a point on the GeneralizedGrassmann M, i.e. (nk) for both the real-valued and the complex value case.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.retract-Tuple{GeneralizedGrassmann, Any, Any, PolarRetraction}","page":"Generalized Grassmann","title":"ManifoldsBase.retract","text":"retract(M::GeneralizedGrassmann, p, X, ::PolarRetraction)\n\nCompute the SVD-based retraction PolarRetraction on the GeneralizedGrassmann M, by projecting p + X onto M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#ManifoldsBase.zero_vector-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::GeneralizedGrassmann, p)\n\nReturn the zero tangent vector from the tangent space at p on the GeneralizedGrassmann M, which is given by a zero matrix the same size as p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/generalizedgrassmann.html#Statistics.mean-Tuple{GeneralizedGrassmann, Vararg{Any}}","page":"Generalized Grassmann","title":"Statistics.mean","text":"mean(\n M::GeneralizedGrassmann,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolationWithinRadius(π/4);\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolationWithinRadius.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#Skew-hermitian-matrices","page":"Skew-Hermitian matrices","title":"Skew-hermitian matrices","text":"","category":"section"},{"location":"manifolds/skewhermitian.html","page":"Skew-Hermitian matrices","title":"Skew-Hermitian matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/SkewHermitian.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/skewhermitian.html#Manifolds.SkewHermitianMatrices","page":"Skew-Hermitian matrices","title":"Manifolds.SkewHermitianMatrices","text":"SkewHermitianMatrices{n,𝔽} <: AbstractDecoratorManifold{𝔽}\n\nThe AbstractManifold $ \\operatorname{SkewHerm}(n)$ consisting of the real- or complex-valued skew-hermitian matrices of size n n, i.e. the set\n\noperatornameSkewHerm(n) = biglp 𝔽^n n big p^mathrmH = -p bigr\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transpose, and the field 𝔽 ℝ ℂ ℍ.\n\nThough it is slightly redundant, usually the matrices are stored as n n arrays.\n\nNote that in this representation, the real-valued part of the diagonal must be zero, which is also reflected in the manifold_dimension.\n\nConstructor\n\nSkewHermitianMatrices(n::Int, field::AbstractNumbers=ℝ)\n\nGenerate the manifold of n n skew-hermitian matrices.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/skewhermitian.html#Manifolds.SkewSymmetricMatrices","page":"Skew-Hermitian matrices","title":"Manifolds.SkewSymmetricMatrices","text":"SkewSymmetricMatrices{n}\n\nGenerate the manifold of n n real skew-symmetric matrices. This is equivalent to SkewHermitianMatrices(n, ℝ).\n\nConstructor\n\nSkewSymmetricMatrices(n::Int)\n\n\n\n\n\n","category":"type"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.check_point-Union{Tuple{𝔽}, Tuple{n}, Tuple{SkewHermitianMatrices{n, 𝔽}, Any}} where {n, 𝔽}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.check_point","text":"check_point(M::SkewHermitianMatrices{n,𝔽}, p; kwargs...)\n\nCheck whether p is a valid manifold point on the SkewHermitianMatrices M, i.e. whether p is a skew-hermitian matrix of size (n,n) with values from the corresponding AbstractNumbers 𝔽.\n\nThe tolerance for the skew-symmetry of p can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.check_vector-Tuple{SkewHermitianMatrices, Any, Any}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::SkewHermitianMatrices{n}, p, X; kwargs... )\n\nCheck whether X is a tangent vector to manifold point p on the SkewHermitianMatrices M, i.e. X must be a skew-hermitian matrix of size (n,n) and its values have to be from the correct AbstractNumbers. The tolerance for the skew-symmetry of p and X can be set using kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.is_flat-Tuple{SkewHermitianMatrices}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.is_flat","text":"is_flat(::SkewHermitianMatrices)\n\nReturn true. SkewHermitianMatrices is a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.manifold_dimension-Union{Tuple{SkewHermitianMatrices{N, 𝔽}}, Tuple{𝔽}, Tuple{N}} where {N, 𝔽}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SkewHermitianMatrices{n,𝔽})\n\nReturn the dimension of the SkewHermitianMatrices matrix M over the number system 𝔽, i.e.\n\ndim mathrmSkewHerm(nℝ) = fracn(n+1)2 dim_ℝ 𝔽 - n\n\nwhere dim_ℝ 𝔽 is the real_dimension of 𝔽. The first term corresponds to only the upper triangular elements of the matrix being unique, and the second term corresponds to the constraint that the real part of the diagonal be zero.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.project-Tuple{SkewHermitianMatrices, Any, Any}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.project","text":"project(M::SkewHermitianMatrices, p, X)\n\nProject the matrix X onto the tangent space at p on the SkewHermitianMatrices M,\n\noperatornameproj_p(X) = frac12 bigl( X - X^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/skewhermitian.html#ManifoldsBase.project-Tuple{SkewHermitianMatrices, Any}","page":"Skew-Hermitian matrices","title":"ManifoldsBase.project","text":"project(M::SkewHermitianMatrices, p)\n\nProjects p from the embedding onto the SkewHermitianMatrices M, i.e.\n\noperatornameproj_operatornameSkewHerm(n)(p) = frac12 bigl( p - p^mathrmH bigr)\n\nwhere cdot^mathrmH denotes the Hermitian, i.e. complex conjugate transposed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Tucker","page":"Tucker","title":"Tucker manifold","text":"","category":"section"},{"location":"manifolds/tucker.html","page":"Tucker","title":"Tucker","text":"Modules = [Manifolds]\nPages = [\"Tucker.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/tucker.html#Manifolds.Tucker","page":"Tucker","title":"Manifolds.Tucker","text":"Tucker{N, R, D, 𝔽} <: AbstractManifold{𝔽}\n\nThe manifold of N_1 times dots times N_D real-valued or complex-valued tensors of fixed multilinear rank (R_1 dots R_D) . If R_1 = dots = R_D = 1, this is the Segre manifold, i.e., the set of rank-1 tensors.\n\nRepresentation in HOSVD format\n\nLet mathbbF be the real or complex numbers. Any tensor p on the Tucker manifold can be represented as a multilinear product in HOSVD [DeLathauwer2000] form\n\np = (U_1dotsU_D) cdot mathcalC\n\nwhere mathcal C in mathbbF^R_1 times dots times R_D and, for d=1dotsD, the matrix U_d in mathbbF^N_d times R_d contains the singular vectors of the dth unfolding of mathcalA\n\nTangent space\n\nThe tangent space to the Tucker manifold at p = (U_1dotsU_D) cdot mathcalC is [Koch2010]\n\nT_p mathcalM =\nbigl\n(U_1dotsU_D) cdot mathcalC^prime\n+ sum_d=1^D bigl(\n (U_1 dots U_d-1 U_d^prime U_d+1 dots U_D)\n cdot mathcalC\nbigr)\nbigr\n\nwhere mathcalC^prime is arbitrary, U_d^mathrmH is the Hermitian adjoint of U_d, and U_d^mathrmH U_d^prime = 0 for all d.\n\nConstructor\n\nTucker(N::NTuple{D, Int}, R::NTuple{D, Int}[, field = ℝ])\n\nGenerate the manifold of field-valued tensors of dimensions N[1] × … × N[D] and multilinear rank R = (R[1], …, R[D]).\n\n[DeLathauwer2000]: Lieven De Lathauwer, Bart De Moor, Joos Vandewalle: \"A multilinear singular value decomposition\" SIAM Journal on Matrix Analysis and Applications, 21(4), pp. 1253-1278, 2000 doi: 10.1137/S0895479896305696\n\n[Koch2010]: Othmar Koch, Christian Lubic, \"Dynamical Tensor approximation\" SIAM Journal on Matrix Analysis and Applications, 31(5), pp. 2360-2375, 2010 doi: 10.1137/09076578X\n\n\n\n\n\n","category":"type"},{"location":"manifolds/tucker.html#Manifolds.TuckerPoint","page":"Tucker","title":"Manifolds.TuckerPoint","text":"TuckerPoint{T,D}\n\nAn order D tensor of fixed multilinear rank and entries of type T, which makes it a point on the Tucker manifold. The tensor is represented in HOSVD form.\n\nConstructors:\n\nTuckerPoint(core::AbstractArray{T,D}, factors::Vararg{<:AbstractMatrix{T},D}) where {T,D}\n\nConstruct an order D tensor of element type T that can be represented as the multilinear product (factors[1], …, factors[D]) ⋅ core. It is assumed that the dimensions of the core are the multilinear rank of the tensor and that the matrices factors each have full rank. No further assumptions are made.\n\nTuckerPoint(p::AbstractArray{T,D}, mlrank::NTuple{D,Int}) where {T,D}\n\nThe low-multilinear rank tensor arising from the sequentially truncated the higher-order singular value decomposition of the D-dimensional array p of type T. The singular values are truncated to get a multilinear rank mlrank [Vannieuwenhoven2012].\n\n[Vannieuwenhoven2012]: Nick Vannieuwenhoven, Raf Vandebril, Karl Meerbergen: \"A new truncation strategy for the higher-order singular value decomposition\" SIAM Journal on Scientific Computing, 34(2), pp. 1027-1052, 2012 doi: 10.1137/110836067\n\n\n\n\n\n","category":"type"},{"location":"manifolds/tucker.html#Manifolds.TuckerTVector","page":"Tucker","title":"Manifolds.TuckerTVector","text":"TuckerTVector{T, D} <: TVector\n\nTangent vector to the D-th order Tucker manifold at p = (U_1dotsU_D) mathcalC. The numbers are of type T and the vector is represented as\n\nX =\n(U_1dotsU_D) cdot mathcalC^prime +\nsum_d=1^D (U_1dotsU_d-1U_d^primeU_d+1dotsU_D) cdot mathcalC\n\nwhere U_d^mathrmH U_d^prime = 0.\n\nConstructor\n\nTuckerTVector(C′::Array{T,D}, U′::NTuple{D,Matrix{T}}) where {T,D}\n\nConstructs a Dth order TuckerTVector of number type T with C^prime and U^prime, so that, together with a TuckerPoint p as above, the tangent vector can be represented as X in the above expression.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/tucker.html#Base.convert-Union{Tuple{D}, Tuple{T}, Tuple{𝔽}, Tuple{Type{Matrix{T}}, CachedBasis{𝔽, DefaultOrthonormalBasis{𝔽, ManifoldsBase.TangentSpaceType}, Manifolds.HOSVDBasis{T, D}}}} where {𝔽, T, D}","page":"Tucker","title":"Base.convert","text":"Base.convert(::Type{Matrix{T}}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}\nBase.convert(::Type{Matrix}, basis::CachedBasis{𝔽,DefaultOrthonormalBasis{𝔽, TangentSpaceType},HOSVDBasis{T, D}}) where {𝔽, T, D}\n\nConvert a HOSVD-derived cached basis from [Dewaele2021] of the Dth order Tucker manifold with number type T to a matrix. The columns of this matrix are the vectorisations of the embeddings of the basis vectors.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Base.foreach","page":"Tucker","title":"Base.foreach","text":"Base.foreach(f, M::Tucker, p::TuckerPoint, basis::AbstractBasis, indices=1:manifold_dimension(M))\n\nLet basis be and AbstractBasis at a point p on M. Suppose f is a function that takes an index and a vector as an argument. This function applies f to i and the ith basis vector sequentially for each i in indices. Using a CachedBasis may speed up the computation.\n\nNOTE: The i'th basis vector is overwritten in each iteration. If any information about the vector is to be stored, f must make a copy.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/tucker.html#Base.ndims-Union{Tuple{TuckerPoint{T, D}}, Tuple{D}, Tuple{T}} where {T, D}","page":"Tucker","title":"Base.ndims","text":"Base.ndims(p::TuckerPoint{T,D}) where {T,D}\n\nThe order of the tensor corresponding to the TuckerPoint p, i.e., D.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Base.size-Tuple{TuckerPoint}","page":"Tucker","title":"Base.size","text":"Base.size(p::TuckerPoint)\n\nThe dimensions of a TuckerPoint p, when regarded as a full tensor (see embed).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.check_point-Union{Tuple{D}, Tuple{R}, Tuple{N}, Tuple{Tucker{N, R, D}, Any}} where {N, R, D}","page":"Tucker","title":"ManifoldsBase.check_point","text":"check_point(M::Tucker{N,R,D}, p; kwargs...) where {N,R,D}\n\nCheck whether the multidimensional array or TuckerPoint p is a point on the Tucker manifold, i.e. it is a Dth order N[1] × … × N[D] tensor of multilinear rank (R[1], …, R[D]). The keyword arguments are passed to the matrix rank function applied to the unfoldings. For a TuckerPoint it is checked that the point is in correct HOSVD form.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.check_vector-Union{Tuple{D}, Tuple{T}, Tuple{R}, Tuple{N}, Tuple{Tucker{N, R, D}, TuckerPoint{T, D}, TuckerTVector}} where {N, R, T, D}","page":"Tucker","title":"ManifoldsBase.check_vector","text":"check_vector(M::Tucker{N,R,D}, p::TuckerPoint{T,D}, X::TuckerTVector) where {N,R,T,D}\n\nCheck whether a TuckerTVector X is is in the tangent space to the Dth order Tucker manifold M at the Dth order TuckerPoint p. This is the case when the dimensions of the factors in X agree with those of p and the factor matrices of X are in the orthogonal complement of the HOSVD factors of p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.embed-Tuple{Tucker, Any, TuckerPoint}","page":"Tucker","title":"ManifoldsBase.embed","text":"embed(::Tucker{N,R,D}, p::TuckerPoint) where {N,R,D}\n\nConvert a TuckerPoint p on the rank R Tucker manifold to a full N[1] × … × N[D]-array by evaluating the Tucker decomposition.\n\nembed(::Tucker{N,R,D}, p::TuckerPoint, X::TuckerTVector) where {N,R,D}\n\nConvert a tangent vector X with base point p on the rank R Tucker manifold to a full tensor, represented as an N[1] × … × N[D]-array.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.get_basis-Union{Tuple{𝔽}, Tuple{Tucker, TuckerPoint}, Tuple{Tucker, TuckerPoint, DefaultOrthonormalBasis{𝔽, ManifoldsBase.TangentSpaceType}}} where 𝔽","page":"Tucker","title":"ManifoldsBase.get_basis","text":"get_basis(:: Tucker, p::TuckerPoint, basisType::DefaultOrthonormalBasis{𝔽, TangentSpaceType}) where 𝔽\n\nAn implicitly stored basis of the tangent space to the Tucker manifold. Assume p = (U_1dotsU_D) cdot mathcalC is in HOSVD format and that, for d=1dotsD, the singular values of the d'th unfolding are sigma_dj, with j = 1dotsR_d. The basis of the tangent space is as follows: [Dewaele2021]\n\nbigl\n(U_1dotsU_D) e_i\nbigr cup bigl\n(U_1dots sigma_dj^-1 U_d^perp e_i e_j^TdotsU_D) cdot mathcalC\nbigr\n\nfor all d = 1dotsD and all canonical basis vectors e_i and e_j. Every U_d^perp is such that U_d quad U_d^perp forms an orthonormal basis of mathbbR^N_d.\n\n[Dewaele2021]: Nick Dewaele, Paul Breiding, Nick Vannieuwenhoven, \"The condition number of many tensor decompositions is invariant under Tucker compression\" arxiv: 2106.13034\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.inner-Tuple{Tucker, TuckerPoint, TuckerTVector, TuckerTVector}","page":"Tucker","title":"ManifoldsBase.inner","text":"inner(M::Tucker, p::TuckerPoint, X::TuckerTVector, Y::TuckerTVector)\n\nThe Euclidean inner product between tangent vectors X and X at the point p on the Tucker manifold. This is equal to embed(M, p, X) ⋅ embed(M, p, Y).\n\ninner(::Tucker, A::TuckerPoint, X::TuckerTVector, Y)\ninner(::Tucker, A::TuckerPoint, X, Y::TuckerTVector)\n\nThe Euclidean inner product between X and Y where X is a vector tangent to the Tucker manifold at p and Y is a vector in the ambient space or vice versa. The vector in the ambient space is represented as a full tensor, i.e., a multidimensional array.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.inverse_retract-Tuple{Tucker, Any, TuckerPoint, TuckerPoint, ProjectionInverseRetraction}","page":"Tucker","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Tucker, p::TuckerPoint, q::TuckerPoint, ::ProjectionInverseRetraction)\n\nThe projection inverse retraction on the Tucker manifold interprets q as a point in the ambient Euclidean space (see embed) and projects it onto the tangent space at to M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.is_flat-Tuple{Tucker}","page":"Tucker","title":"ManifoldsBase.is_flat","text":"is_flat(::Tucker)\n\nReturn false. Tucker is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.manifold_dimension-Union{Tuple{Tucker{n⃗, r⃗}}, Tuple{r⃗}, Tuple{n⃗}} where {n⃗, r⃗}","page":"Tucker","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(::Tucker{N,R,D}) where {N,R,D}\n\nThe dimension of the manifold of N_1 times dots times N_D tensors of multilinear rank (R_1 dots R_D), i.e.\n\nmathrmdim(mathcalM) = prod_d=1^D R_d + sum_d=1^D R_d (N_d - R_d)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.project-Tuple{Tucker, Any, TuckerPoint, Any}","page":"Tucker","title":"ManifoldsBase.project","text":"project(M::Tucker, p::TuckerPoint, X)\n\nThe least-squares projection of a dense tensor X onto the tangent space to M at p.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.retract-Tuple{Tucker, Any, Any, PolarRetraction}","page":"Tucker","title":"ManifoldsBase.retract","text":"retract(::Tucker, p::TuckerPoint, X::TuckerTVector, ::PolarRetraction)\n\nThe truncated HOSVD-based retraction [Kressner2014] to the Tucker manifold, i.e. the result is the sequentially tuncated HOSVD approximation of p + X.\n\nIn the exceptional case that the multilinear rank of p + X is lower than that of p, this retraction produces a boundary point, which is outside the manifold.\n\n[Kressner2014]: Daniel Kressner, Michael Steinlechner, Bart Vandereycken: \"Low-rank tensor completion by Riemannian optimization\" BIT Numerical Mathematics, 54(2), pp. 447-468, 2014 doi: 10.1007/s10543-013-0455-z\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#ManifoldsBase.zero_vector-Tuple{Tucker, TuckerPoint}","page":"Tucker","title":"ManifoldsBase.zero_vector","text":"zero_vector(::Tucker, p::TuckerPoint)\n\nThe zero element in the tangent space to p on the Tucker manifold, represented as a TuckerTVector.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/tucker.html#Literature","page":"Tucker","title":"Literature","text":"","category":"section"},{"location":"manifolds/elliptope.html#Elliptope","page":"Elliptope","title":"Elliptope","text":"","category":"section"},{"location":"manifolds/elliptope.html","page":"Elliptope","title":"Elliptope","text":"Modules = [Manifolds]\nPages = [\"manifolds/Elliptope.jl\"]\nOrder = [:type,:function]","category":"page"},{"location":"manifolds/elliptope.html#Manifolds.Elliptope","page":"Elliptope","title":"Manifolds.Elliptope","text":"Elliptope{N,K} <: AbstractDecoratorManifold{ℝ}\n\nThe Elliptope manifold, also known as the set of correlation matrices, consists of all symmetric positive semidefinite matrices of rank k with unit diagonal, i.e.,\n\nbeginaligned\nmathcal E(nk) =\nbiglp ℝ^n n big a^mathrmTpa geq 0 text for all a ℝ^n\np_ii = 1 text for all i=1ldotsn\ntextand p = qq^mathrmT text for q in ℝ^n k text with operatornamerank(p) = operatornamerank(q) = k\nbigr\nendaligned\n\nAnd this manifold is working solely on the matrices q. Note that this q is not unique, indeed for any orthogonal matrix A we have (qA)(qA)^mathrmT = qq^mathrmT = p, so the manifold implemented here is the quotient manifold. The unit diagonal translates to unit norm columns of q.\n\nThe tangent space at p, denoted T_pmathcal E(nk), is also represented by matrices Yin ℝ^n k and reads as\n\nT_pmathcal E(nk) = bigl\nX ℝ^n nX = qY^mathrmT + Yq^mathrmT text with X_ii = 0 text for i=1ldotsn\nbigr\n\nendowed with the Euclidean metric from the embedding, i.e. from the ℝ^n k\n\nThis manifold was for example investigated in[JourneeBachAbsilSepulchre2010].\n\nConstructor\n\nElliptope(n,k)\n\ngenerates the manifold mathcal E(nk) subset ℝ^n n.\n\n[JourneeBachAbsilSepulchre2010]: Journée, M., Bach, F., Absil, P.-A., and Sepulchre, R.: “Low-Rank Optimization on the Cone of Positive Semidefinite Matrices”, SIAM Journal on Optimization (20)5, pp. 2327–2351, 2010. doi: 10.1137/080731359, arXiv: 0807.4423.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/elliptope.html#ManifoldsBase.check_point-Union{Tuple{K}, Tuple{N}, Tuple{Elliptope{N, K}, Any}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.check_point","text":"check_point(M::Elliptope, q; kwargs...)\n\nchecks, whether q is a valid reprsentation of a point p=qq^mathrmT on the Elliptope M, i.e. is a matrix of size (N,K), such that p is symmetric positive semidefinite and has unit trace. Since by construction p is symmetric, this is not explicitly checked. Since p is by construction positive semidefinite, this is not checked. The tolerances for positive semidefiniteness and unit trace can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.check_vector-Union{Tuple{K}, Tuple{N}, Tuple{Elliptope{N, K}, Any, Any}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.check_vector","text":"check_vector(M::Elliptope, q, Y; kwargs... )\n\nCheck whether X = qY^mathrmT + Yq^mathrmT is a tangent vector to p=qq^mathrmT on the Elliptope M, i.e. Y has to be of same dimension as q and a X has to be a symmetric matrix with zero diagonal.\n\nThe tolerance for the base point check and zero diagonal can be set using the kwargs.... Note that symmetric of X holds by construction an is not explicitly checked.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.is_flat-Tuple{Elliptope}","page":"Elliptope","title":"ManifoldsBase.is_flat","text":"is_flat(::Elliptope)\n\nReturn false. Elliptope is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.manifold_dimension-Union{Tuple{Elliptope{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::Elliptope)\n\nreturns the dimension of Elliptope M=mathcal E(nk) nk ℕ, i.e.\n\ndim mathcal E(nk) = n(k-1) - frack(k-1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.project-Tuple{Elliptope, Any}","page":"Elliptope","title":"ManifoldsBase.project","text":"project(M::Elliptope, q)\n\nproject q onto the manifold Elliptope M, by normalizing the rows of q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.project-Tuple{Elliptope, Vararg{Any}}","page":"Elliptope","title":"ManifoldsBase.project","text":"project(M::Elliptope, q, Y)\n\nProject Y onto the tangent space at q, i.e. row-wise onto the oblique manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.representation_size-Union{Tuple{Elliptope{N, K}}, Tuple{K}, Tuple{N}} where {N, K}","page":"Elliptope","title":"ManifoldsBase.representation_size","text":"representation_size(M::Elliptope)\n\nReturn the size of an array representing an element on the Elliptope manifold M, i.e. n k, the size of such factor of p=qq^mathrmT on mathcal M = mathcal E(nk).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.retract-Tuple{Elliptope, Any, Any, ProjectionRetraction}","page":"Elliptope","title":"ManifoldsBase.retract","text":"retract(M::Elliptope, q, Y, ::ProjectionRetraction)\n\ncompute a projection based retraction by projecting q+Y back onto the manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.vector_transport_to-Tuple{Elliptope, Any, Any, Any, ProjectionTransport}","page":"Elliptope","title":"ManifoldsBase.vector_transport_to","text":"vector_transport_to(M::Elliptope, p, X, q)\n\ntransport the tangent vector X at p to q by projecting it onto the tangent space at q.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#ManifoldsBase.zero_vector-Tuple{Elliptope, Vararg{Any}}","page":"Elliptope","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::Elliptope,p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the Elliptope manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/elliptope.html#Literature","page":"Elliptope","title":"Literature","text":"","category":"section"},{"location":"manifolds/multinomial.html#Multinomial-matrices","page":"Multinomial matrices","title":"Multinomial matrices","text":"","category":"section"},{"location":"manifolds/multinomial.html","page":"Multinomial matrices","title":"Multinomial matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Multinomial.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/multinomial.html#Manifolds.MultinomialMatrices","page":"Multinomial matrices","title":"Manifolds.MultinomialMatrices","text":"MultinomialMatrices{n,m} <: AbstractPowerManifold{ℝ}\n\nThe multinomial manifold consists of m column vectors, where each column is of length n and unit norm, i.e.\n\nmathcalMN(nm) coloneqq bigl p ℝ^nm big p_ij 0 text for all i=1n j=1m text and p^mathrmTmathbb1_m = mathbb1_nbigr\n\nwhere mathbb1_k is the vector of length k containing ones.\n\nThis yields exactly the same metric as considering the product metric of the probablity vectors, i.e. PowerManifold of the (n-1)-dimensional ProbabilitySimplex.\n\nThe ProbabilitySimplex is stored internally within M.manifold, such that all functions of AbstractPowerManifold can be used directly.\n\nConstructor\n\nMultinomialMatrices(n, m)\n\nGenerate the manifold of matrices mathbb R^nm such that the m columns are discrete probability distributions, i.e. sum up to one.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/multinomial.html#Functions","page":"Multinomial matrices","title":"Functions","text":"","category":"section"},{"location":"manifolds/multinomial.html","page":"Multinomial matrices","title":"Multinomial matrices","text":"Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:","category":"page"},{"location":"manifolds/multinomial.html","page":"Multinomial matrices","title":"Multinomial matrices","text":"Modules = [Manifolds]\nPages = [\"manifolds/Multinomial.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/multinomial.html#ManifoldsBase.check_point-Tuple{MultinomialMatrices, Any}","page":"Multinomial matrices","title":"ManifoldsBase.check_point","text":"check_point(M::MultinomialMatrices, p)\n\nChecks whether p is a valid point on the MultinomialMatrices(m,n) M, i.e. is a matrix of m discrete probability distributions as columns from mathbb R^n, i.e. each column is a point from ProbabilitySimplex(n-1).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/multinomial.html#ManifoldsBase.check_vector-Union{Tuple{m}, Tuple{n}, Tuple{MultinomialMatrices{n, m}, Any, Any}} where {n, m}","page":"Multinomial matrices","title":"ManifoldsBase.check_vector","text":"check_vector(M::MultinomialMatrices p, X; kwargs...)\n\nChecks whether X is a valid tangent vector to p on the MultinomialMatrices M. This means, that p is valid, that X is of correct dimension and columnswise a tangent vector to the columns of p on the ProbabilitySimplex.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Symplectic","page":"Symplectic","title":"Symplectic","text":"","category":"section"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"The Symplectic manifold, denoted operatornameSp(2n mathbbF), is a closed, embedded, submanifold of mathbbF^2n times 2n that represents transformations into symplectic subspaces which keep the canonical symplectic form over mathbbF^2n times 2n invariant under the standard embedding inner product. The canonical symplectic form is a non-degenerate bilinear and skew symmetric map omegacolon mathbbF^2n times mathbbF^2n rightarrow mathbbF, given by omega(x y) = x^T Q_2n y for elements x y in mathbbF^2n, with","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":" Q_2n = \n beginbmatrix\n 0_n I_n \n -I_n 0_n\n endbmatrix","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"That means that an element p in operatornameSp(2n) must fulfill the requirement that ","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":" omega (p x p y) = x^T(p^TQp)y = x^TQy = omega(x y)","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"leading to the requirement on p that p^TQp = Q.","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"The symplectic manifold also forms a group under matrix multiplication, called the textitsymplectic group. Since all the symplectic matrices necessarily have determinant one, the symplectic group operatornameSp(2n mathbbF) is a subgroup of the special linear group, operatornameSL(2n mathbbF). When the underlying field is either mathbbR or mathbbC the symplectic group with a manifold structure constitutes a Lie group, with the Lie Algebra ","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":" mathfraksp(2nF) = H in mathbbF^2n times 2n Q H + H^T Q = 0","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"This set is also known as the Hamiltonian matrices, which have the property that (QH)^T = QH and are commonly used in physics.","category":"page"},{"location":"manifolds/symplectic.html","page":"Symplectic","title":"Symplectic","text":"Modules = [Manifolds]\nPages = [\"manifolds/Symplectic.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symplectic.html#Manifolds.ExtendedSymplecticMetric","page":"Symplectic","title":"Manifolds.ExtendedSymplecticMetric","text":"ExtendedSymplecticMetric <: AbstractMetric\n\nThe extension of the RealSymplecticMetric at a point p \\in \\operatorname{Sp}(2n) as an inner product over the embedding space ℝ^2n times 2n, i.e.\n\n langle x y rangle_p = langle p^-1x p^-1rangle_operatornameFr\n = operatornametr(x^mathrmT(pp^mathrmT)^-1y) forall x y in ℝ^2n times 2n\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Manifolds.RealSymplecticMetric","page":"Symplectic","title":"Manifolds.RealSymplecticMetric","text":"RealSymplecticMetric <: RiemannianMetric\n\nThe canonical Riemannian metric on the symplectic manifold, defined pointwise for p in operatornameSp(2n) by [Fiori2011]\n\nbeginalign*\n g_p colon T_poperatornameSp(2n) times T_poperatornameSp(2n) rightarrow ℝ \n g_p(Z_1 Z_2) = operatornametr((p^-1Z_1)^mathrmT (p^-1Z_2))\nendalign*\n\nThis metric is also the default metric for the Symplectic manifold.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Manifolds.Symplectic","page":"Symplectic","title":"Manifolds.Symplectic","text":"Symplectic{n, 𝔽} <: AbstractEmbeddedManifold{𝔽, DefaultIsometricEmbeddingType}\n\nThe symplectic manifold consists of all 2n times 2n matrices which preserve the canonical symplectic form over 𝔽^2n 2n times 𝔽^2n 2n,\n\n omegacolon 𝔽^2n 2n times 𝔽^2n 2n rightarrow 𝔽\n quad omega(x y) = p^mathrmT Q_2n q x y in 𝔽^2n 2n\n\nwhere\n\nQ_2n =\nbeginbmatrix\n 0_n I_n \n -I_n 0_n\nendbmatrix\n\nThat is, the symplectic manifold consists of\n\noperatornameSp(2n ℝ) = bigl p ℝ^2n 2n big p^mathrmTQ_2np = Q_2n bigr\n\nwith 0_n and I_n denoting the n n zero-matrix and indentity matrix in ℝ^n times n respectively.\n\nThe tangent space at a point p is given by [BendokatZimmermann2021]\n\nbeginalign*\n T_poperatornameSp(2n)\n = X in mathbbR^2n times 2n p^TQ_2nX + X^TQ_2np = 0 \n = X = pQS S R^2n 2n S^mathrmT = S \nendalign*\n\nConstructor\n\nSymplectic(2n, field=ℝ) -> Symplectic{div(2n, 2), field}()\n\nGenerate the (real-valued) symplectic manifold of 2n times 2n symplectic matrices. The constructor for the Symplectic manifold accepts the even column/row embedding dimension 2n for the real symplectic manifold, ℝ^2n 2n.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Manifolds.SymplecticMatrix","page":"Symplectic","title":"Manifolds.SymplecticMatrix","text":"SymplecticMatrix{T}\n\nA lightweight structure to represent the action of the matrix representation of the canonical symplectic form,\n\nQ_2n(λ) = λ\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix quad in ℝ^2n times 2n\n\nsuch that the canonical symplectic form is represented by\n\nomega_2n(x y) = x^mathrmTQ_2n(1)y quad x y in ℝ^2n\n\nThe entire matrix is however not instantiated in memory, instead a scalar λ of type T is stored, which is used to keep track of scaling and transpose operations applied to each SymplecticMatrix. For example, given Q = SymplecticMatrix(1.0) represented as 1.0*[0 I; -I 0], the adjoint Q' returns SymplecticMatrix(-1.0) = (-1.0)*[0 I; -I 0].\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symplectic.html#Base.exp-Tuple{Symplectic, Vararg{Any}}","page":"Symplectic","title":"Base.exp","text":"exp(M::Symplectic, p, X)\nexp!(M::Symplectic, q, p, X)\n\nThe Exponential mapping on the Symplectic manifold with the RealSymplecticMetric Riemannian metric.\n\nFor the point p in operatornameSp(2n) the exponential mapping along the tangent vector X in T_poperatornameSp(2n) is computed as [WangSunFiori2018]\n\n operatornameexp_p(X) = p operatornameExp((p^-1X)^mathrmT)\n operatornameExp(p^-1X - (p^-1X)^mathrmT)\n\nwhere operatornameExp(cdot) denotes the matrix exponential.\n\n[WangSunFiori2018]: Wang, Jing and Sun, Huafei and Fiori, Simone: A Riemannian-steepest-descent approach for optimization on the real symplectic group, Mathematical Methods in the Applied Sciences, 41(11) pp. 4273-4286, 2018 doi 10.1002/mma.4890\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Base.inv-Union{Tuple{n}, Tuple{Symplectic{n, ℝ}, Any}} where n","page":"Symplectic","title":"Base.inv","text":"inv(::Symplectic, A)\ninv!(::Symplectic, A)\n\nCompute the symplectic inverse A^+ of matrix A ℝ^2n 2n. Given a matrix\n\nA ℝ^2n 2nquad\nA =\nbeginbmatrix\nA_11 A_12 \nA_21 A_2 2\nendbmatrix\n\nthe symplectic inverse is defined as:\n\nA^+ = Q_2n^mathrmT A^mathrmT Q_2n\n\nwhere\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe symplectic inverse of A can be expressed explicitly as:\n\nA^+ =\nbeginbmatrix\n A_2 2^mathrmT -A_1 2^mathrmT 12mm\n -A_2 1^mathrmT A_1 1^mathrmT\nendbmatrix\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Base.rand-Tuple{Symplectic}","page":"Symplectic","title":"Base.rand","text":"rand(::SymplecticStiefel; vector_at=nothing,\n hamiltonian_norm = (vector_at === nothing ? 1/2 : 1.0))\n\nGenerate a random point on operatornameSp(2n) or a random tangent vector X in T_poperatornameSp(2n) if vector_at is set to a point p in operatornameSp(2n).\n\nA random point on operatornameSp(2n) is constructed by generating a random Hamiltonian matrix Ω in mathfraksp(2nF) with norm hamiltonian_norm, and then transforming it to a symplectic matrix by applying the Cayley transform\n\n operatornamecaycolon mathfraksp(2nF) rightarrow operatornameSp(2n)\n Omega mapsto (I - Omega)^-1(I + Omega)\n\nTo generate a random tangent vector in T_poperatornameSp(2n), this code employs the second tangent vector space parametrization of Symplectic. It first generates a random symmetric matrix S by S = randn(2n, 2n) and then symmetrizes it as S = S + S'. Then S is normalized to have Frobenius norm of hamiltonian_norm and X = pQS is returned, where Q is the SymplecticMatrix.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldDiff.gradient-Tuple{Symplectic, Any, Any, ManifoldDiff.RiemannianProjectionBackend}","page":"Symplectic","title":"ManifoldDiff.gradient","text":"gradient(M::Symplectic, f, p, backend::RiemannianProjectionBackend;\n extended_metric=true)\ngradient!(M::Symplectic, f, p, backend::RiemannianProjectionBackend;\n extended_metric=true)\n\nCompute the manifold gradient textgradf(p) of a scalar function f colon operatornameSp(2n) rightarrow ℝ at p in operatornameSp(2n).\n\nThe element textgradf(p) is found as the Riesz representer of the differential textDf(p) colon T_poperatornameSp(2n) rightarrow ℝ w.r.t. the Riemannian metric inner product at p [Fiori2011]. That is, textgradf(p) in T_poperatornameSp(2n) solves the relation\n\n g_p(textgradf(p) X) = textDf(p) quadforall X in T_poperatornameSp(2n)\n\nThe default behaviour is to first change the representation of the Euclidean gradient from the Euclidean metric to the RealSymplecticMetric at p, and then we projecting the result onto the correct tangent tangent space T_poperatornameSp(2n ℝ) w.r.t the Riemannian metric g_p extended to the entire embedding space.\n\nArguments:\n\nextended_metric = true: If true, compute the gradient textgradf(p) by first changing the representer of the Euclidean gradient of a smooth extension of f, f(p), w.r.t. the RealSymplecticMetric at p extended to the entire embedding space, before projecting onto the correct tangent vector space w.r.t. the same extended metric g_p. If false, compute the gradient by first projecting f(p) onto the tangent vector space, before changing the representer in the tangent vector space to comply with the RealSymplecticMetric.\n\n[Fiori2011]: Simone Fiori: Solving minimal-distance problems over the manifold of real-symplectic matrices, SIAM Journal on Matrix Analysis and Applications 32(3), pp. 938-968, 2011. doi 10.1137/100817115.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Manifolds.project_normal!-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric}, Any, Any, Any}} where {m, n, 𝔽}","page":"Symplectic","title":"Manifolds.project_normal!","text":"project_normal!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X)\n\nProject onto the normal of the tangent space (T_poperatornameSp(2n))^perp_g at a point p operatornameSp(2n), relative to the riemannian metric g RealSymplecticMetric. That is,\n\n(T_poperatornameSp(2n))^perp_g = Y in mathbbR^2n times 2n \n g_p(Y X) = 0 forall X in T_poperatornameSp(2n)\n\nThe closed form projection operator onto the normal space is given by [GaoSonAbsilStykel2021]\n\noperatornameP^(T_poperatornameSp(2n))perp_g_p(X) = pQoperatornameskew(p^mathrmTQ^mathrmTX)\n\nwhere operatornameskew(A) = frac12(A - A^mathrmT). This function is not exported.\n\n[GaoSonAbsilStykel2021]: Gao, Bin and Son, Nguyen Thanh and Absil, P-A and Stykel, Tatjana: Riemannian optimization on the symplectic Stiefel manifold, SIAM Journal on Optimization 31(2), pp. 1546-1575, 2021. doi 10.1137/20M1348522\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Manifolds.symplectic_inverse_times-Union{Tuple{n}, Tuple{Symplectic{n}, Any, Any}} where n","page":"Symplectic","title":"Manifolds.symplectic_inverse_times","text":"symplectic_inverse_times(::Symplectic, p, q)\nsymplectic_inverse_times!(::Symplectic, A, p, q)\n\nDirectly compute the symplectic inverse of p in operatornameSp(2n), multiplied with q in operatornameSp(2n). That is, this function efficiently computes p^+q = (Q_2np^mathrmTQ_2n)q in ℝ^2n times 2n, where Q_2n is the SymplecticMatrix of size 2n times 2n.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.change_representer-Tuple{Symplectic, EuclideanMetric, Any, Any}","page":"Symplectic","title":"ManifoldsBase.change_representer","text":"change_representer(::Symplectic, ::EuclideanMetric, p, X)\nchange_representer!(::Symplectic, Y, ::EuclideanMetric, p, X)\n\nCompute the representation of a tangent vector ξ T_poperatornameSp(2n ℝ) s.t.\n\n g_p(c_p(ξ) η) = ξ η^textEuc η T_poperatornameSp(2n ℝ)\n\nwith the conversion function\n\n c_p T_poperatornameSp(2n ℝ) rightarrow T_poperatornameSp(2n ℝ) quad\n c_p(ξ) = frac12 pp^mathrmT ξ + frac12 pQ ξ^mathrmT pQ\n\nEach of the terms c_p^1(ξ) = p p^mathrmT ξ and c_p^2(ξ) = pQ ξ^mathrmT pQ from the above definition of c_p(η) are themselves metric compatible in the sense that\n\n c_p^i T_poperatornameSp(2n ℝ) rightarrow mathbbR^2n times 2nquad\n g_p^i(c_p(ξ) η) = ξ η^textEuc η T_poperatornameSp(2n ℝ)\n\nfor i in 1 2. However the range of each function alone is not confined to T_poperatornameSp(2n ℝ), but the convex combination\n\n c_p(ξ) = frac12c_p^1(ξ) + frac12c_p^2(ξ)\n\ndoes have the correct range T_poperatornameSp(2n ℝ).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.change_representer-Union{Tuple{n}, Tuple{m}, Tuple{𝔽}, Tuple{MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric}, EuclideanMetric, Any, Any}} where {𝔽, m, n}","page":"Symplectic","title":"ManifoldsBase.change_representer","text":"change_representer(MetMan::MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric},\n EucMet::EuclideanMetric, p, X)\nchange_representer!(MetMan::MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric},\n Y, EucMet::EuclideanMetric, p, X)\n\nChange the representation of a matrix ξ mathbbR^2n times 2n into the inner product space (ℝ^2n times 2n g_p) where the inner product is given by g_p(ξ η) = langle p^-1ξ p^-1η rangle = operatornametr(ξ^mathrmT(pp^mathrmT)^-1η), as the extension of the RealSymplecticMetric onto the entire embedding space.\n\nBy changing the representation we mean to apply a mapping\n\n c_p mathbbR^2n times 2n rightarrow mathbbR^2n times 2n\n\ndefined by requiring that it satisfy the metric compatibility condition\n\n g_p(c_p(ξ) η) = p^-1c_p(ξ) p^-1η = ξ η^textEuc\n η T_poperatornameSp(2n ℝ)\n\nIn this case, we compute the mapping\n\n c_p(ξ) = pp^mathrmT ξ\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.check_point-Union{Tuple{ℝ}, Tuple{n}, Tuple{Symplectic{n, ℝ}, Any}} where {n, ℝ}","page":"Symplectic","title":"ManifoldsBase.check_point","text":"check_point(M::Symplectic, p; kwargs...)\n\nCheck whether p is a valid point on the Symplectic M=operatornameSp(2n), i.e. that it has the right AbstractNumbers type and p^+p is (approximately) the identity, where A^+ = Q_2n^mathrmTA^mathrmTQ_2n is the symplectic inverse, with\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.check_vector-Tuple{Symplectic, Vararg{Any}}","page":"Symplectic","title":"ManifoldsBase.check_vector","text":"check_vector(M::Symplectic, p, X; kwargs...)\n\nChecks whether X is a valid tangent vector at p on the Symplectic M=operatornameSp(2n), i.e. the AbstractNumbers fits and it (approximately) holds that p^TQ_2nX + X^TQ_2np = 0, where\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nThe tolerance can be set with kwargs... (e.g. atol = 1.0e-14).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.distance-Union{Tuple{n}, Tuple{Symplectic{n}, Any, Any}} where n","page":"Symplectic","title":"ManifoldsBase.distance","text":"distance(M::Symplectic, p, q)\n\nCompute an approximate geodesic distance between two Symplectic matrices p q in operatornameSp(2n), as done in [WangSunFiori2018].\n\n operatornamedist(p q)\n operatornameLog(p^+q)_operatornameFr\n\nwhere the operatornameLog(cdot) operator is the matrix logarithm.\n\nThis approximation is justified by first recalling the Baker-Campbell-Hausdorf formula,\n\noperatornameLog(operatornameExp(A)operatornameExp(B))\n = A + B + frac12A B + frac112A A B + frac112B B A\n + ldots \n\nThen we write the expression for the exponential map from p to q as\n\n q =\n operatornameexp_p(X)\n =\n p operatornameExp((p^+X)^mathrmT)\n operatornameExp(p^+X - (p^+X)^mathrmT)\n X in T_poperatornameSp\n\nand with the geodesic distance between p and q given by operatornamedist(p q) = X_p = p^+X_operatornameFr we see that\n\n beginalign*\n operatornameLog(p^+q)_operatornameFr\n = operatornameLogleft(\n operatornameExp((p^+X)^mathrmT)\n operatornameExp(p^+X - (p^+X)^mathrmT)\n right)_operatornameFr \n = p^+X + frac12(p^+X)^mathrmT p^+X - (p^+X)^mathrmT\n + ldots _operatornameFr \n p^+X_operatornameFr = operatornamedist(p q)\n endalign*\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.inner-Union{Tuple{n}, Tuple{Symplectic{n, ℝ}, Any, Any, Any}} where n","page":"Symplectic","title":"ManifoldsBase.inner","text":"inner(::Symplectic{n, ℝ}, p, X, Y)\n\nCompute the canonical Riemannian inner product RealSymplecticMetric\n\n g_p(X Y) = operatornametr((p^-1X)^mathrmT (p^-1Y))\n\nbetween the two tangent vectors X Y in T_poperatornameSp(2n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.inverse_retract-Tuple{Symplectic, Any, Any, CayleyInverseRetraction}","page":"Symplectic","title":"ManifoldsBase.inverse_retract","text":"inverse_retract(M::Symplectic, p, q, ::CayleyInverseRetraction)\n\nCompute the Cayley Inverse Retraction X = mathcalL_p^operatornameSp(q) such that the Cayley Retraction from p along X lands at q, i.e. mathcalR_p(X) = q [BendokatZimmermann2021].\n\nFirst, recall the definition the standard symplectic matrix\n\nQ =\nbeginbmatrix\n 0 I \n-I 0\nendbmatrix\n\nas well as the symplectic inverse of a matrix A, A^+ = Q^mathrmT A^mathrmT Q.\n\nFor p q operatornameSp(2n ℝ) then, we can then define the inverse cayley retraction as long as the following matrices exist.\n\n U = (I + p^+ q)^-1 quad V = (I + q^+ p)^-1\n\nIf that is the case, the inverse cayley retration at p applied to q is\n\nmathcalL_p^operatornameSp(q) = 2pbigl(V - Ubigr) + 2bigl((p + q)U - pbigr)\n T_poperatornameSp(2n)\n\n[BendokatZimmermann2021]: Bendokat, Thomas and Zimmermann, Ralf: The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications arXiv preprint arXiv:2108.12447, 2021.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.is_flat-Tuple{Symplectic}","page":"Symplectic","title":"ManifoldsBase.is_flat","text":"is_flat(::Symplectic)\n\nReturn false. Symplectic is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.manifold_dimension-Union{Tuple{Symplectic{n}}, Tuple{n}} where n","page":"Symplectic","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(::Symplectic{n})\n\nReturns the dimension of the symplectic manifold embedded in ℝ^2n times 2n, i.e.\n\n operatornamedim(operatornameSp(2n)) = (2n + 1)n\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.project!-Union{Tuple{𝔽}, Tuple{n}, Tuple{m}, Tuple{MetricManifold{𝔽, Euclidean{Tuple{m, n}, 𝔽}, ExtendedSymplecticMetric}, Any, Any, Any}} where {m, n, 𝔽}","page":"Symplectic","title":"ManifoldsBase.project!","text":"project!(::MetricManifold{𝔽,Euclidean,ExtendedSymplecticMetric}, Y, p, X) where {𝔽}\n\nCompute the projection of X R^2n 2n onto T_poperatornameSp(2n ℝ) w.r.t. the Riemannian metric g RealSymplecticMetric. The closed form projection mapping is given by [GaoSonAbsilStykel2021]\n\n operatornameP^T_poperatornameSp(2n)_g_p(X) = pQoperatornamesym(p^mathrmTQ^mathrmTX)\n\nwhere operatornamesym(A) = frac12(A + A^mathrmT). This function is not exported.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.project-Tuple{Symplectic, Any, Any}","page":"Symplectic","title":"ManifoldsBase.project","text":"project(::Symplectic, p, A)\nproject!(::Symplectic, Y, p, A)\n\nGiven a point p in operatornameSp(2n), project an element A in mathbbR^2n times 2n onto the tangent space T_poperatornameSp(2n) relative to the euclidean metric of the embedding mathbbR^2n times 2n.\n\nThat is, we find the element X in T_poperatornameSpSt(2n 2k) which solves the constrained optimization problem\n\n operatornamemin_X in mathbbR^2n times 2n frac12X - A^2 quad\n textst\n h(X) colon= X^mathrmT Q p + p^mathrmT Q X = 0\n\nwhere hcolonmathbbR^2n times 2n rightarrow operatornameskew(2n) defines the restriction of X onto the tangent space T_poperatornameSpSt(2n 2k).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#ManifoldsBase.retract-Tuple{Symplectic, Any, Any}","page":"Symplectic","title":"ManifoldsBase.retract","text":"retract(::Symplectic, p, X, ::CayleyRetraction)\nretract!(::Symplectic, q, p, X, ::CayleyRetraction)\n\nCompute the Cayley retraction on p operatornameSp(2n ℝ) in the direction of tangent vector X T_poperatornameSp(2n ℝ), as defined in by Birtea et al in proposition 2 [BirteaCaşuComănescu2020].\n\nUsing the symplectic inverse of a matrix A in ℝ^2n times 2n, A^+ = Q_2n^mathrmT A^mathrmT Q_2n where\n\nQ_2n =\nbeginbmatrix\n0_n I_n \n -I_n 0_n\nendbmatrix\n\nthe retraction mathcalRcolon ToperatornameSp(2n) rightarrow operatornameSp(2n) is defined pointwise as\n\nbeginalign*\nmathcalR_p(X) = p operatornamecayleft(frac12p^+Xright) \n = p operatornameexp_11(p^+X) \n = p (2I - p^+X)^-1(2I + p^+X)\nendalign*\n\nHere operatornameexp_11(z) = (2 - z)^-1(2 + z) denotes the Padé (1, 1) approximation to operatornameexp(z).\n\n[BirteaCaşuComănescu2020]: Birtea, Petre and Caşu, Ioan and Comănescu, Dan: Optimization on the real symplectic group, Monatshefte f{\"u}r Mathematik, Springer, 2020. doi 10.1007/s00605-020-01369-9\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symplectic.html#Literature","page":"Symplectic","title":"Literature","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html#SymmetricPositiveDefiniteSection","page":"Symmetric positive definite","title":"Symmetric positive definite matrices","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"SymmetricPositiveDefinite","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.SymmetricPositiveDefinite","page":"Symmetric positive definite","title":"Manifolds.SymmetricPositiveDefinite","text":"SymmetricPositiveDefinite{N} <: AbstractDecoratorManifold{ℝ}\n\nThe manifold of symmetric positive definite matrices, i.e.\n\nmathcal P(n) =\nbigl\np ℝ^n n big a^mathrmTpa 0 text for all a ℝ^nbackslash0\nbigr\n\nThe tangent space at T_pmathcal P(n) reads\n\n T_pmathcal P(n) =\n bigl\n X in mathbb R^nn big X=X^mathrmT\n bigr\n\ni.e. the set of symmetric matrices,\n\nConstructor\n\nSymmetricPositiveDefinite(n)\n\ngenerates the manifold mathcal P(n) subset ℝ^n n\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"This manifold can – for example – be illustrated as ellipsoids: since the eigenvalues are all positive they can be taken as lengths of the axes of an ellipsoids while the directions are given by the eigenvectors.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"(Image: An example set of data)","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"The manifold can be equipped with different metrics","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Common-and-metric-independent-functions","page":"Symmetric positive definite","title":"Common and metric independent functions","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefinite.jl\"]\nOrder = [:function]\nPublic=true\nPrivate=false\nFilter = t -> t !== mean","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Base.convert-Tuple{Type{AbstractMatrix}, SPDPoint}","page":"Symmetric positive definite","title":"Base.convert","text":"convert(::Type{AbstractMatrix}, p::SPDPoint)\n\nreturn the point p as a matrix. The matrix is either stored within the SPDPoint or reconstructed from p.eigen.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.rand-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"Base.rand","text":"rand(M::SymmetricPositiveDefinite; σ::Real=1)\n\nGenerate a random symmetric positive definite matrix on the SymmetricPositiveDefinite manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.check_point-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.check_point","text":"check_point(M::SymmetricPositiveDefinite, p; kwargs...)\n\nchecks, whether p is a valid point on the SymmetricPositiveDefinite M, i.e. is a matrix of size (N,N), symmetric and positive definite. The tolerance for the second to last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.check_vector-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.check_vector","text":"check_vector(M::SymmetricPositiveDefinite, p, X; kwargs... )\n\nCheck whether X is a tangent vector to p on the SymmetricPositiveDefinite M, i.e. atfer check_point(M,p), X has to be of same dimension as p and a symmetric matrix, i.e. this stores tangent vetors as elements of the corresponding Lie group. The tolerance for the last test can be set using the kwargs....\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.injectivity_radius-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"ManifoldsBase.injectivity_radius","text":"injectivity_radius(M::SymmetricPositiveDefinite[, p])\ninjectivity_radius(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}[, p])\ninjectivity_radius(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}[, p])\n\nReturn the injectivity radius of the SymmetricPositiveDefinite. Since M is a Hadamard manifold with respect to the AffineInvariantMetric and the LogCholeskyMetric, the injectivity radius is globally .\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::SymmetricPositiveDefinite)\n\nReturn false. SymmetricPositiveDefinite is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.manifold_dimension-Union{Tuple{SymmetricPositiveDefinite{N}}, Tuple{N}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.manifold_dimension","text":"manifold_dimension(M::SymmetricPositiveDefinite)\n\nreturns the dimension of SymmetricPositiveDefinite M=mathcal P(n) n ℕ, i.e.\n\ndim mathcal P(n) = fracn(n+1)2\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.project-Tuple{SymmetricPositiveDefinite, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.project","text":"project(M::SymmetricPositiveDefinite, p, X)\n\nproject a matrix from the embedding onto the tangent space T_pmathcal P(n) of the SymmetricPositiveDefinite matrices, i.e. the set of symmetric matrices.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.representation_size-Union{Tuple{SymmetricPositiveDefinite{N}}, Tuple{N}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.representation_size","text":"representation_size(M::SymmetricPositiveDefinite)\n\nReturn the size of an array representing an element on the SymmetricPositiveDefinite manifold M, i.e. n n, the size of such a symmetric positive definite matrix on mathcal M = mathcal P(n).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.zero_vector-Tuple{SymmetricPositiveDefinite, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.zero_vector","text":"zero_vector(M::SymmetricPositiveDefinite, p)\n\nreturns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the SymmetricPositiveDefinite manifold M.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Default-metric:-the-affine-invariant-metric","page":"Symmetric positive definite","title":"Default metric: the affine invariant metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteAffineInvariant.jl\"]\nOrder = [:type]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.AffineInvariantMetric","page":"Symmetric positive definite","title":"Manifolds.AffineInvariantMetric","text":"AffineInvariantMetric <: AbstractMetric\n\nThe linear affine metric is the metric for symmetric positive definite matrices, that employs matrix logarithms and exponentials, which yields a linear and affine metric.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"This metric is also the default metric, i.e. any call of the following functions with P=SymmetricPositiveDefinite(3) will result in MetricManifold(P,AffineInvariantMetric())and hence yield the formulae described in this seciton.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteAffineInvariant.jl\"]\nOrder = [:function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{SymmetricPositiveDefinite, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(M::SymmetricPositiveDefinite, p, X)\nexp(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, X)\n\nCompute the exponential map from p with tangent vector X on the SymmetricPositiveDefinite M with its default MetricManifold having the AffineInvariantMetric. The formula reads\n\nexp_p X = p^frac12operatornameExp(p^-frac12 X p^-frac12)p^frac12\n\nwhere operatornameExp denotes to the matrix exponential.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{SymmetricPositiveDefinite, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.log","text":"log(M::SymmetricPositiveDefinite, p, q)\nlog(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)\n\nCompute the logarithmic map from p to q on the SymmetricPositiveDefinite as a MetricManifold with AffineInvariantMetric. The formula reads\n\nlog_p q =\np^frac12operatornameLog(p^-frac12qp^-frac12)p^frac12\n\nwhere operatornameLog denotes to the matrix logarithm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.manifold_volume-Tuple{SymmetricPositiveDefinite}","page":"Symmetric positive definite","title":"Manifolds.manifold_volume","text":"manifold_volume(::SymmetricPositiveDefinite)\n\nReturn volume of the SymmetricPositiveDefinite manifold, i.e. infinity.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.volume_density-Union{Tuple{n}, Tuple{SymmetricPositiveDefinite{n}, Any, Any}} where n","page":"Symmetric positive definite","title":"Manifolds.volume_density","text":"volume_density(::SymmetricPositiveDefinite{n}, p, X) where {n}\n\nCompute the volume density of the SymmetricPositiveDefinite manifold at p in direction X. See [ChevallierKalungaAngulo2017], Section 6.2 for details. Note that metric in Manifolds.jl has a different scaling factor than the reference.\n\n[ChevallierKalungaAngulo2017]: E. Chevallier, E. Kalunga, and J. Angulo, “Kernel Density Estimation on Spaces of Gaussian Distributions and Symmetric Positive Definite Matrices,” SIAM J. Imaging Sci., vol. 10, no. 1, pp. 191–215, Jan. 2017, doi: 10.1137/15M1053566.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_metric-Tuple{SymmetricPositiveDefinite, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_metric","text":"change_metric(M::SymmetricPositiveDefinite{n}, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal P(n) with respect to the EuclideanMetric g_E, this function changes into the AffineInvariantMetric (default) metric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ccolon T_pmathcal P(n) to T_pmathcal P(n) such that for all YZ T_pmathcal P(n)` it holds\n\nYZ = operatornametr(YZ) = operatornametr(p^-1c(Y)p^-1c(Z)) = g_p(c(Z)c(Y))\n\nand hence c(X) = pX is computed.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_representer-Tuple{SymmetricPositiveDefinite, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_representer","text":"change_representer(M::SymmetricPositiveDefinite, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the AffineInvariantMetric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ZT_pmathcal P(n) such that for all YT_pmathcal P(n)` it holds\n\nXY = operatornametr(XY) = operatornametr(p^-1Zp^-1Y) = g_p(ZY)\n\nand hence Z = pXp.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(M::SymmetricPositiveDefinite, p, q)\ndistance(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)\n\nCompute the distance on the SymmetricPositiveDefinite manifold between p and q, as a MetricManifold with AffineInvariantMetric. The formula reads\n\nd_mathcal P(n)(pq)\n= lVert operatornameLog(p^-frac12qp^-frac12)rVert_mathrmF\n\nwhere operatornameLog denotes the matrix logarithm and lVertcdotrVert_mathrmF denotes the matrix Frobenius norm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_basis-Tuple{SymmetricPositiveDefinite, Any, DefaultOrthonormalBasis}","page":"Symmetric positive definite","title":"ManifoldsBase.get_basis","text":"[Ξ,κ] = get_basis(M::SymmetricPositiveDefinite, p, B::DefaultOrthonormalBasis)\n[Ξ,κ] = get_basis(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, B::DefaultOrthonormalBasis)\n\nReturn a default ONB for the tangent space T_pmathcal P(n) of the SymmetricPositiveDefinite with respect to the AffineInvariantMetric.\n\n g_p(XY) = operatornametr(p^-1 X p^-1 Y)\n\nThe basis constructed here is based on the ONB for symmetric matrices constructed as follows. Let\n\nDelta_ij = (a_kl)_kl=1^n quad text with \na_kl =\nbegincases\n 1 mbox for k=l text if i=j\n frac1sqrt2 mbox for k=i l=j text or k=j l=i\n 0 text else\nendcases\n\nwhich forms an ONB for the space of symmetric matrices.\n\nWe then form the ONB by\n\n Xi_ij = p^frac12Delta_ijp^frac12qquad i=1ldotsn j=ildotsn\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_basis_diagonalizing-Union{Tuple{N}, Tuple{SymmetricPositiveDefinite{N}, Any, DiagonalizingOrthonormalBasis}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.get_basis_diagonalizing","text":"[Ξ,κ] = get_basis_diagonalizing(M::SymmetricPositiveDefinite, p, B::DiagonalizingOrthonormalBasis)\n[Ξ,κ] = get_basis_diagonalizing(M::MetricManifold{SymmetricPositiveDefinite{N},AffineInvariantMetric}, p, B::DiagonalizingOrthonormalBasis)\n\nReturn a orthonormal basis Ξ as a vector of tangent vectors (of length manifold_dimension of M) in the tangent space of p on the MetricManifold of SymmetricPositiveDefinite manifold M with AffineInvariantMetric that diagonalizes the curvature tensor R(uv)w with eigenvalues κ and where the direction B.frame_direction V has curvature 0.\n\nThe construction is based on an ONB for the symmetric matrices similar to get_basis(::SymmetricPositiveDefinite, p, ::DefaultOrthonormalBasis just that the ONB here is build from the eigen vectors of p^frac12Vp^frac12.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_coordinates-Tuple{SymmetricPositiveDefinite, Any, Any, Any, DefaultOrthonormalBasis}","page":"Symmetric positive definite","title":"ManifoldsBase.get_coordinates","text":"get_coordinates(::SymmetricPositiveDefinite, p, X, ::DefaultOrthonormalBasis)\n\nUsing the basis from get_basis the coordinates with respect to this ONB can be simplified to\n\n c_k = mathrmtr(p^-frac12Delta_ij X)\n\nwhere k is trhe linearized index of the i=1ldotsn j=ildotsn.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.get_vector-Tuple{SymmetricPositiveDefinite, Any, Any, Any, DefaultOrthonormalBasis}","page":"Symmetric positive definite","title":"ManifoldsBase.get_vector","text":"get_vector(::SymmetricPositiveDefinite, p, c, ::DefaultOrthonormalBasis)\n\nUsing the basis from get_basis the vector reconstruction with respect to this ONB can be simplified to\n\n X = p^frac12 Biggl( sum_i=1j=i^n c_k Delta_ij Biggr) p^frac12\n\nwhere k is the linearized index of the i=1ldotsn j=ildotsn.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Tuple{SymmetricPositiveDefinite, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(M::SymmetricPositiveDefinite, p, X, Y)\ninner(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, X, Y)\n\nCompute the inner product of X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with AffineInvariantMetric. The formula reads\n\ng_p(XY) = operatornametr(p^-1 X p^-1 Y)\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, AffineInvariantMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,AffineInvariantMetric})\n\nReturn false. SymmetricPositiveDefinite with AffineInvariantMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.parallel_transport_to-Tuple{SymmetricPositiveDefinite, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.parallel_transport_to","text":"parallel_transport_to(M::SymmetricPositiveDefinite, p, X, q)\nparallel_transport_to(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, X, y)\n\nCompute the parallel transport of X from the tangent space at p to the tangent space at q on the SymmetricPositiveDefinite as a MetricManifold with the AffineInvariantMetric. The formula reads\n\nmathcal P_qpX = p^frac12\noperatornameExpbigl(\nfrac12p^-frac12log_p(q)p^-frac12\nbigr)\np^-frac12X p^-frac12\noperatornameExpbigl(\nfrac12p^-frac12log_p(q)p^-frac12\nbigr)\np^frac12\n\nwhere operatornameExp denotes the matrix exponential and log the logarithmic map on SymmetricPositiveDefinite (again with respect to the AffineInvariantMetric).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.riemann_tensor-Tuple{SymmetricPositiveDefinite, Vararg{Any, 4}}","page":"Symmetric positive definite","title":"ManifoldsBase.riemann_tensor","text":"riemann_tensor(::SymmetricPositiveDefinite, p, X, Y, Z)\n\nCompute the value of Riemann tensor on the SymmetricPositiveDefinite manifold. The formula reads[Rentmeesters2011] R(XY)Z=p^12R(X_I Y_I)Z_Ip^12, where R_I(X_I Y_I)Z_I=frac14Z_I X_I Y_I, X_I=p^-12Xp^-12, Y_I=p^-12Yp^-12 and Z_I=p^-12Zp^-12.\n\n[Rentmeesters2011]: Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#BuresWassersteinMetricSection","page":"Symmetric positive definite","title":"Bures-Wasserstein metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteBuresWasserstein.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.BuresWassersteinMetric","page":"Symmetric positive definite","title":"Manifolds.BuresWassersteinMetric","text":"BurresWassertseinMetric <: AbstractMetric\n\nThe Bures Wasserstein metric for symmetric positive definite matrices[MalagoMontruccioPistone2018].\n\n[MalagoMontruccioPistone2018]: Malagò, L., Montrucchio, L., Pistone, G.: Wasserstein Riemannian geometry of Gaussian densities. Information Geometry, 1, pp. 137–179, 2018. doi: 10.1007/s41884-018-0014-4\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X)\n\nCompute the exponential map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n exp_p(X) = p+X+L_p(X)pL_p(X)\n\nwhere q=L_p(X) denotes the Lyapunov operator, i.e. it solves pq + qp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.log","text":"log(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)\n\nCompute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n log_p(q) = (pq)^frac12 + (qp)^frac12 - 2 p\n\nwhere q=L_p(X) denotes the Lyapunov operator, i.e. it solves pq + qp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_representer-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, BuresWassersteinMetric}, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_representer","text":"change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the BuresWassersteinMetric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ZT_pmathcal P(n) such that for all YT_pmathcal P(n)` it holds\n\nXY = operatornametr(XY) = ZY_mathrmBW\n\nfor all Y and hence we get Z= 2(A+A^{\\mathrm{T}})withA=Xp``.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(::MatricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)\n\nCompute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.\n\nd(pq) =\n operatornametr(p) + operatornametr(q) - 2operatornametrBigl( (p^frac12qp^frac12 bigr)^frac12 Bigr)\n\nwhere the last trace can be simplified (by rotating the matrix products in the trace) to operatornametr(pq).\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, BuresWassersteinMetric}, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(::MetricManifold{ℝ,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X, Y)\n\nCompute the inner product SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n XY = frac12operatornametr(L_p(X)Y)\n\nwhere q=L_p(X) denotes the Lyapunov operator, i.e. it solves pq + qp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, BuresWassersteinMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,BuresWassersteinMetric})\n\nReturn false. SymmetricPositiveDefinite with BuresWassersteinMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Generalized-Bures-Wasserstein-metric","page":"Symmetric positive definite","title":"Generalized Bures-Wasserstein metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteGeneralizedBuresWasserstein.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.GeneralizedBuresWassersteinMetric","page":"Symmetric positive definite","title":"Manifolds.GeneralizedBuresWassersteinMetric","text":"GeneralizedBurresWassertseinMetric{T<:AbstractMatrix} <: AbstractMetric\n\nThe generalized Bures Wasserstein metric for symmetric positive definite matrices, see[HanMishraJawanpuriaGao2021].\n\nThis metric internally stores the symmetric positive definite matrix M to generalise the metric, where the name also follows the mentioned preprint.\n\n[HanMishraJawanpuriaGao2021]: Han, A., Mishra, B., Jawanpuria, P., Gao, J.: Generalized Bures-Wasserstein geometry for positive definite matrices. arXiv: 2110.10464.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, GeneralizedBuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(::MatricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, X)\n\nCompute the exponential map on SymmetricPositiveDefinite with respect to the GeneralizedBuresWassersteinMetric given by\n\n exp_p(X) = p+X+mathcal ML_pM(X)pML_pM(X)\n\nwhere q=L_Mp(X) denotes the generalized Lyapunov operator, i.e. it solves pqM + Mqp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, GeneralizedBuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"Base.log","text":"log(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)\n\nCompute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by\n\n log_p(q) = M(M^-1pM^-1q)^frac12 + (qM^-1pM^-1)^frac12M - 2 p\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.change_representer-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, GeneralizedBuresWassersteinMetric}, EuclideanMetric, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.change_representer","text":"change_representer(M::MetricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, E::EuclideanMetric, p, X)\n\nGiven a tangent vector X T_pmathcal M representing a linear function on the tangent space at p with respect to the EuclideanMetric g_E, this is turned into the representer with respect to the (default) metric, the GeneralizedBuresWassersteinMetric on the SymmetricPositiveDefinite M.\n\nTo be precise we are looking for ZT_pmathcal P(n) such that for all YT_pmathcal P(n) it holds\n\nXY = operatornametr(XY) = ZY_mathrmBW\n\nfor all Y and hence we get Z = 2pXM + 2MXp.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, <:GeneralizedBuresWassersteinMetric}, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(::MatricManifold{SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, q)\n\nCompute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.\n\nd(pq) = operatornametr(M^-1p) + operatornametr(M^-1q)\n - 2operatornametrbigl( (p^frac12M^-1qM^-1p^frac12 bigr)^frac12\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, <:GeneralizedBuresWassersteinMetric}, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(::MetricManifold{ℝ,SymmetricPositiveDefinite,GeneralizedBuresWassersteinMetric}, p, X, Y)\n\nCompute the inner product SymmetricPositiveDefinite with respect to the GeneralizedBuresWassersteinMetric given by\n\n XY = frac12operatornametr(L_pM(X)Y)\n\nwhere q=L_Mp(X) denotes the generalized Lyapunov operator, i.e. it solves pqM + Mqp = X.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, <:GeneralizedBuresWassersteinMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric})\n\nReturn false. SymmetricPositiveDefinite with GeneralizedBuresWassersteinMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Log-Euclidean-metric","page":"Symmetric positive definite","title":"Log-Euclidean metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteLogEuclidean.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.LogEuclideanMetric","page":"Symmetric positive definite","title":"Manifolds.LogEuclideanMetric","text":"LogEuclideanMetric <: RiemannianMetric\n\nThe LogEuclidean Metric consists of the Euclidean metric applied to all elements after mapping them into the Lie Algebra, i.e. performing a matrix logarithm beforehand.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Union{Tuple{N}, Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite{N}, LogEuclideanMetric}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(M::MetricManifold{SymmetricPositiveDefinite{N},LogEuclideanMetric}, p, q)\n\nCompute the distance on the SymmetricPositiveDefinite manifold between p and q as a MetricManifold with LogEuclideanMetric. The formula reads\n\n d_mathcal P(n)(pq) = lVert operatornameLog p - operatornameLog q rVert_mathrmF\n\nwhere operatornameLog denotes the matrix logarithm and lVertcdotrVert_mathrmF denotes the matrix Frobenius norm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, LogEuclideanMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,LogEuclideanMetric})\n\nReturn false. SymmetricPositiveDefinite with LogEuclideanMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Log-Cholesky-metric","page":"Symmetric positive definite","title":"Log-Cholesky metric","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"manifolds/SymmetricPositiveDefiniteLogCholesky.jl\"]\nOrder = [:type, :function]","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.LogCholeskyMetric","page":"Symmetric positive definite","title":"Manifolds.LogCholeskyMetric","text":"LogCholeskyMetric <: RiemannianMetric\n\nThe Log-Cholesky metric imposes a metric based on the Cholesky decomposition as introduced by [Lin2019].\n\n[Lin2019]: Lin, Zenhua: \"Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition\", arXiv: 1908.09326.\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html#Base.exp-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, LogCholeskyMetric}, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.exp","text":"exp(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, X)\n\nCompute the exponential map on the SymmetricPositiveDefinite M with LogCholeskyMetric from p into direction X. The formula reads\n\nexp_p X = (exp_y W)(exp_y W)^mathrmT\n\nwhere exp_xW is the exponential map on CholeskySpace, y is the cholesky decomposition of p, W = y(y^-1Xy^-mathrmT)_frac12, and (cdot)_frac12 denotes the lower triangular matrix with the diagonal multiplied by frac12.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Base.log-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, LogCholeskyMetric}, Vararg{Any}}","page":"Symmetric positive definite","title":"Base.log","text":"log(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)\n\nCompute the logarithmic map on SymmetricPositiveDefinite M with respect to the LogCholeskyMetric emanating from p to q. The formula can be adapted from the CholeskySpace as\n\nlog_p q = xW^mathrmT + Wx^mathrmT\n\nwhere x is the cholesky factor of p and W=log_x y for y the cholesky factor of q and the just mentioned logarithmic map is the one on CholeskySpace.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.distance-Union{Tuple{N}, Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite{N}, LogCholeskyMetric}, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.distance","text":"distance(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)\n\nCompute the distance on the manifold of SymmetricPositiveDefinite nmatrices, i.e. between two symmetric positive definite matrices p and q with respect to the LogCholeskyMetric. The formula reads\n\nd_mathcal P(n)(pq) = sqrt\n lVert x - y rVert_mathrmF^2\n + lVert log(operatornamediag(x)) - log(operatornamediag(y))rVert_mathrmF^2 \n\nwhere x and y are the cholesky factors of p and q, respectively, cdot denbotes the strictly lower triangular matrix of its argument, and lVertcdotrVert_mathrmF the Frobenius norm.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.inner-Union{Tuple{N}, Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite{N}, LogCholeskyMetric}, Any, Any, Any}} where N","page":"Symmetric positive definite","title":"ManifoldsBase.inner","text":"inner(M::MetricManifold{LogCholeskyMetric,ℝ,SymmetricPositiveDefinite}, p, X, Y)\n\nCompute the inner product of two matrices X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with LogCholeskyMetric. The formula reads\n\n g_p(XY) = a_z(X)a_z(Y)_z\n\nwhere cdotcdot_x denotes inner product on the CholeskySpace, z is the cholesky factor of p, a_z(W) = z (z^-1Wz^-mathrmT)_frac12, and (cdot)_frac12 denotes the lower triangular matrix with the diagonal multiplied by frac12\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.is_flat-Tuple{MetricManifold{ℝ, <:SymmetricPositiveDefinite, LogCholeskyMetric}}","page":"Symmetric positive definite","title":"ManifoldsBase.is_flat","text":"is_flat(::MetricManifold{ℝ,<:SymmetricPositiveDefinite,LogCholeskyMetric})\n\nReturn false. SymmetricPositiveDefinite with LogCholeskyMetric is not a flat manifold.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#ManifoldsBase.parallel_transport_to-Tuple{MetricManifold{ℝ, SymmetricPositiveDefinite, LogCholeskyMetric}, Any, Any, Any}","page":"Symmetric positive definite","title":"ManifoldsBase.parallel_transport_to","text":"vector_transport_to(\n M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric},\n p,\n X,\n q,\n ::ParallelTransport,\n)\n\nParallel transport the tangent vector X at p along the geodesic to q with respect to the SymmetricPositiveDefinite manifold M and LogCholeskyMetric. The parallel transport is based on the parallel transport on CholeskySpace: Let x and y denote the cholesky factors of p and q, respectively and W = x(x^-1Xx^-mathrmT)_frac12, where (cdot)_frac12 denotes the lower triangular matrix with the diagonal multiplied by frac12. With V the parallel transport on CholeskySpace from x to y. The formula hear reads\n\nmathcal P_qpX = yV^mathrmT + Vy^mathrmT\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Statistics","page":"Symmetric positive definite","title":"Statistics","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Modules = [Manifolds]\nPages = [\"SymmetricPositiveDefinite.jl\"]\nOrder = [:function]\nFilter = t -> t === mean","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Statistics.mean-Tuple{SymmetricPositiveDefinite, Any}","page":"Symmetric positive definite","title":"Statistics.mean","text":"mean(\n M::SymmetricPositiveDefinite,\n x::AbstractVector,\n [w::AbstractWeights,]\n method = GeodesicInterpolation();\n kwargs...,\n)\n\nCompute the Riemannian mean of x using GeodesicInterpolation.\n\n\n\n\n\n","category":"method"},{"location":"manifolds/symmetricpositivedefinite.html#Efficient-representation","page":"Symmetric positive definite","title":"Efficient representation","text":"","category":"section"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"When a point p is used in several occasions, it might be beneficial to store the eigenvalues and vectors of p and optionally its square root and the inverse of the square root. The SPDPoint can be used for exactly that.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"SPDPoint","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.SPDPoint","page":"Symmetric positive definite","title":"Manifolds.SPDPoint","text":"SPDPoint <: AbstractManifoldsPoint\n\nStore the result of eigen(p) of an SPD matrix and (optionally) p^12 and p^-12 to avoid their repeated computations.\n\nThis result only has the result of eigen as a mandatory storage, the other three can be stored. If they are not stored they are computed and returned (but then still not stored) when required.\n\nConstructor\n\nSPDPoint(p::AbstractMatrix; store_p=true, store_sqrt=true, store_sqrt_inv=true)\n\nCreate an SPD point using an symmetric positive defincite matrix p, where you can optionally store p, sqrt and sqrt_inv\n\n\n\n\n\n","category":"type"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"and there are three internal functions to be able to use SPDPoint interchangeably with the default representation as a matrix.","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html","page":"Symmetric positive definite","title":"Symmetric positive definite","text":"Manifolds.spd_sqrt\nManifolds.spd_sqrt_inv\nManifolds.spd_sqrt_and_sqrt_inv","category":"page"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.spd_sqrt","page":"Symmetric positive definite","title":"Manifolds.spd_sqrt","text":"spd_sqrt(p::AbstractMatrix)\nspd_sqrt(p::SPDPoint)\n\nreturn p^frac12 by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.\n\nThis method assumes that p represents an spd matrix.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.spd_sqrt_inv","page":"Symmetric positive definite","title":"Manifolds.spd_sqrt_inv","text":"spd_sqrt_inv(p::SPDPoint)\n\nreturn p^-frac12 by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.\n\nThis method assumes that p represents an spd matrix.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/symmetricpositivedefinite.html#Manifolds.spd_sqrt_and_sqrt_inv","page":"Symmetric positive definite","title":"Manifolds.spd_sqrt_and_sqrt_inv","text":"spd_sqrt_and_sqrt_inv(p::AbstractMatrix)\nspd_sqrt_and_sqrt_inv(p::SPDPoint)\n\nreturn p^frac12 and p^-frac12 by either computing them (if they are missing or for the AbstractMatrix) or returning their stored value from within the SPDPoint.\n\nCompared to calling single methods spd_sqrt and spd_sqrt_inv this method only computes the eigenvectors once for the case of the AbstractMatrix or if both are missing.\n\nThis method assumes that p represents an spd matrix.\n\n\n\n\n\n","category":"function"},{"location":"manifolds/symmetricpositivedefinite.html#Literature","page":"Symmetric positive definite","title":"Literature","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"EditURL = \"https://github.com/JuliaManifolds/Manifolds.jl/blob/master/CONTRIBUTING.md\"","category":"page"},{"location":"misc/contributing.html#Contributing-to-Manifolds.jl","page":"Contributing","title":"Contributing to Manifolds.jl","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"First, thanks for taking the time to contribute. Any contribution is appreciated and welcome.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"The following is a set of guidelines to Manifolds.jl.","category":"page"},{"location":"misc/contributing.html#Table-of-Contents","page":"Contributing","title":"Table of Contents","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"Contributing to Manifolds.jl - Table of Contents\nI just have a question\nHow can I file an issue?\nHow can I contribute?\nAdd a missing method\nProvide a new manifold\nCode style","category":"page"},{"location":"misc/contributing.html#I-just-have-a-question","page":"Contributing","title":"I just have a question","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"The developers can most easily be reached in the Julia Slack channel #manifolds. You can apply for the Julia Slack workspace here if you haven't joined yet. You can also ask your question on discourse.julialang.org.","category":"page"},{"location":"misc/contributing.html#How-can-I-file-an-issue?","page":"Contributing","title":"How can I file an issue?","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"If you found a bug or want to propose a feature, we track our issues within the GitHub repository.","category":"page"},{"location":"misc/contributing.html#How-can-I-contribute?","page":"Contributing","title":"How can I contribute?","text":"","category":"section"},{"location":"misc/contributing.html#Add-a-missing-method","page":"Contributing","title":"Add a missing method","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"Not all methods from our interface ManifoldsBase.jl have been implemented for every manifold. If you notice a method missing and can contribute an implementation, please do so! Even providing a single new method is a good contribution.","category":"page"},{"location":"misc/contributing.html#Provide-a-new-manifold","page":"Contributing","title":"Provide a new manifold","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"A main contribution you can provide is another manifold that is not yet included in the package. A manifold is a concrete type of AbstractManifold from ManifoldsBase.jl. This package also provides the main set of functions a manifold can/should implement. Don't worry if you can only implement some of the functions. If the application you have in mind only requires a subset of these functions, implement those. The ManifoldsBase.jl interface provides concrete error messages for the remaining unimplemented functions.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"One important detail is that the interface usually provides an in-place as well as a non-mutating variant See for example exp! and exp. The non-mutating one (e.g. exp) always falls back to use the in-place one, so in most cases it should suffice to implement the in-place one (e.g. exp!).","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"Note that since the first argument is always the AbstractManifold, the mutated argument is always the second one in the signature. In the example we have exp(M, p, X, t) for the exponential map and exp!(M, q, p, X, t) for the in-place one, which stores the result in q.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"On the other hand, the user will most likely look for the documentation of the non-mutating version, so we recommend adding the docstring for the non-mutating one, where all different signatures should be collected in one string when reasonable. This can best be achieved by adding a docstring to the method with a general signature with the first argument being your manifold:","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"struct MyManifold <: AbstractManifold end\n\n@doc raw\"\"\"\n exp(M::MyManifold, p, X)\n\nDescribe the function.\n\"\"\"\nexp(::MyManifold, ::Any...)","category":"page"},{"location":"misc/contributing.html#Code-style","page":"Contributing","title":"Code style","text":"","category":"section"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"We try to follow the documentation guidelines from the Julia documentation as well as Blue Style. We run JuliaFormatter.jl on the repo in the way set in the .JuliaFormatter.toml file, which enforces a number of conventions consistent with the Blue Style.","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"We also follow a few internal conventions:","category":"page"},{"location":"misc/contributing.html","page":"Contributing","title":"Contributing","text":"It is preferred that the AbstractManifold's struct contain a reference to the general theory.\nAny implemented function should be accompanied by its mathematical formulae if a closed form exists.\nWithin the source code of one manifold, the type of the manifold should be the first element of the file, and an alphabetical order of the functions is preferable.\nThe above implies that the in-place variant of a function follows the non-mutating variant.\nThere should be no dangling = signs.\nAlways add a newline between things of different types (struct/method/const).\nAlways add a newline between methods for different functions (including in-place/nonmutating variants).\nPrefer to have no newline between methods for the same function; when reasonable, merge the docstrings.\nAll import/using/include should be in the main module file.","category":"page"}] } diff --git a/previews/PR628/tutorials/getstarted.html b/previews/PR628/tutorials/getstarted.html index 3c2ef8d659..ff3d68f093 100644 --- a/previews/PR628/tutorials/getstarted.html +++ b/previews/PR628/tutorials/getstarted.html @@ -1,5 +1,5 @@ -🚀 Get Started with Manifolds.jl · Manifolds.jl
Edit on GitHub

🚀 Get Started with Manifolds.jl

This is a short overview of Manifolds.jl and how to get started working with your first Manifold. we first need to install the package, using for example

using Pkg; Pkg.add("Manifolds")

Then you can load the package with

using Manifolds

Using the Library of Manifolds

Manifolds.jl is first of all a library of manifolds, see the list in the menu here under “basic manifolds”.

Let’s look at three examples together with the first few functions on manifolds.

1. The Euclidean space

The Euclidean Space Euclidean brings us (back) into linear case of vectors, so in terms of manifolds, this is a very simple one. It is often useful to compare to classical algorithms, or implementations.

M₁ = Euclidean(3)
Euclidean(3; field = ℝ)

Since a manifold is a type in Julia, we write it in CamelCase. Its parameters are first a dimension or size parameter of the manifold, sometimes optional is a field the manifold is defined over.

For example the above definition is the same as the real-valued case

M₁ === Euclidean(3, field=ℝ)
true

But we even introduced a short hand notation, since ℝ is also just a symbol/variable to use”

M₁ === ℝ^3
true

And similarly here are two ways to create the manifold of vectors of length two with complex entries – or mathematically the space $\mathbb C^2$

Euclidean(2, field=ℂ) === ℂ^2
true

The easiest to check is the dimension of a manifold. Here we have three “directions to walk into” at every point $p\in \mathbb R ^3$ so 🔗 manifold_dimension) is

manifold_dimension(M₁)
3

2. The hyperpolic space

The $d$-dimensional hyperbolic space is usually represented in $\mathbb R^{d+1}$ as the set of points $p\in\mathbb R^3$ fulfilling

\[p_1^2+p_2^2+\cdots+p_d^2-p_{d+1}^2 = -1.\]

We define the manifold using

M₂ = Hyperbolic(2)
Hyperbolic(2)

And we can again just start with looking at the manifold dimension of M₂

manifold_dimension(M₂)
2

A next useful function is to check, whether some $p∈\mathbb R^3$ is a point on the manifold M₂. We can check

is_point(M₂, [0, 0, 1])
true

or

is_point(M₂, [1, 0, 1])
false

Keyword arguments are passed on to any numerical checks, for example an absolute tolerance when checking the above equiality.

But in an interactive session an error message might be helpful. A positional (third) argument is present to activate this. Setting this parameter to true, we obtain an error message that gives insight into why the point is not a point on M₂. Note that the LoadError: is due to quarto, on REPL you would just get the DomainError.

is_point(M₂, [0, 0, 1.001], true)
LoadError: DomainError with -1.0020009999999997:
+🚀 Get Started with Manifolds.jl · Manifolds.jl
Edit on GitHub
🚀 Get Started with Manifolds.jl
This is a short overview of Manifolds.jl and how to get started working with your first Manifold. we first need to install the package, using for example
using Pkg; Pkg.add("Manifolds")
Then you can load the package with
using Manifolds
[ Info: Precompiling ManifoldsRecipesBaseExt [37da849e-34ab-54fd-a5a4-b22599bd6cb0]
Using the Library of Manifolds
Manifolds.jl is first of all a library of manifolds, see the list in the menu here under “basic manifolds”.
Let’s look at three examples together with the first few functions on manifolds.
1. The Euclidean space
The Euclidean Space Euclidean brings us (back) into linear case of vectors, so in terms of manifolds, this is a very simple one. It is often useful to compare to classical algorithms, or implementations.
M₁ = Euclidean(3)
Euclidean(3; field = ℝ)
Since a manifold is a type in Julia, we write it in CamelCase. Its parameters are first a dimension or size parameter of the manifold, sometimes optional is a field the manifold is defined over.
For example the above definition is the same as the real-valued case
M₁ === Euclidean(3, field=ℝ)
true
But we even introduced a short hand notation, since ℝ is also just a symbol/variable to use”
M₁ === ℝ^3
true
And similarly here are two ways to create the manifold of vectors of length two with complex entries – or mathematically the space $\mathbb C^2$
Euclidean(2, field=ℂ) === ℂ^2
true
The easiest to check is the dimension of a manifold. Here we have three “directions to walk into” at every point $p\in \mathbb R ^3$ so 🔗 manifold_dimension) is
manifold_dimension(M₁)
3
2. The hyperpolic space
The $d$-dimensional hyperbolic space is usually represented in $\mathbb R^{d+1}$ as the set of points $p\in\mathbb R^3$ fulfilling
\[p_1^2+p_2^2+\cdots+p_d^2-p_{d+1}^2 = -1.\]
We define the manifold using
M₂ = Hyperbolic(2)
Hyperbolic(2)
And we can again just start with looking at the manifold dimension of M₂
manifold_dimension(M₂)
2
A next useful function is to check, whether some $p∈\mathbb R^3$ is a point on the manifold M₂. We can check
is_point(M₂, [0, 0, 1])
true
or
is_point(M₂, [1, 0, 1])
false
Keyword arguments are passed on to any numerical checks, for example an absolute tolerance when checking the above equiality.
But in an interactive session an error message might be helpful. A positional (third) argument is present to activate this. Setting this parameter to true, we obtain an error message that gives insight into why the point is not a point on M₂. Note that the LoadError: is due to quarto, on REPL you would just get the DomainError.
is_point(M₂, [0, 0, 1.001], true)
LoadError: DomainError with -1.0020009999999997:
 The point [0.0, 0.0, 1.001] does not lie on Hyperbolic(2) since its Minkowski inner product is not -1.
3. The sphere
The sphere $\mathbb S^d$ is the $d$-dimensional sphere represented in its embedded form, that is unit vectors $p \in \mathbb R^{d+1}$ with unit norm $\lVert p \rVert_2 = 1$.
M₃ = Sphere(2)
Sphere(2, ℝ)
If we only have a point that is approximately on the manifold, we can allow for a tolerance. Usually these are the same values of atol and rtol alowed in isapprox, i.e. we get
is_point(M₃, [0, 0, 1.001]; atol=1e-3)
true
Here we can show a last nice check: 🔗 is_vector to check whether a tangent vector X is a representation of a tangent vector $X∈T_p\mathcal M$ to a point p on the manifold.
This function has two positional asrguments, the first to again indicate whether to throw an error, the second to disable the check that p is a valid point on the manifold. Usually this validity is essential for the tangent check, but if it was for example performed before, it can be turned off to spare time.
For example in our first example the point is not of unit norm
is_vector(M₃, [2, 0, 0], [0, 1, 1])
false
But the orthogonality of p and X is still valid, we can disable the point check, but even setting the error to true we get here
is_vector(M₃, [2, 0, 0], [0, 1, 1], true, false)
true
But of course it is better to use a valid point in the first place
is_vector(M₃, [1, 0, 0], [0, 1, 1])
true
and for these we again get informative error messages
@expect_error is_vector(M₃, [1, 0, 0], [0.1, 1, 1], true) DomainError
LoadError: LoadError: UndefVarError: `@expect_error` not defined
 in expression starting at In[19]:1
To learn about how to define a manifold youself check out the 🔗 How to define your own manifold tutorial of 🔗 ManifoldsBase.jl.”
Building more advanced manifolds
Based on these basic manifolds we can directly build more advanced manifolds.
The first one concerns vectors or matrices of data on a manifold, the PowerManifold.
M₄ = M₂^2
PowerManifold(Hyperbolic(2), 2)
Then points are represented by arrays, where the power manifold dimension is added in the end. In other words – for the hyperbolic manifold here, we have a matrix with 2 columns, where each column is a valid point on hyperbolic space.
p = [0 0; 0 1; 1 sqrt(2)]
3×2 Matrix{Float64}:
  0.0  0.0
@@ -47,10 +47,10 @@
     return retract(M, p, X, t, m)
 end
generic_de_Casteljau (generic function with 2 methods)
Note that on a manifold M where the exponential map is implemented, the default_retraction_method(M) returns 🔗 ExponentialRetraction, which yields that the retract function falls back to calling exp.
The same mechanism exists for 🔗 parallel_transport_to(M, p, X, q) and the more general 🔗 vector_transport_to(M, p, X, q, m) whose 🔗 AbstractVectorTransportMethod m has a default defined by 🔗 default_vector_transport_method(M).
Allocating and in-place computations
Memory allocation is a 🔗 critical performace issue when programming in Julia. To take this into account, Manifolds.jl provides special functions to reduce the amount of allocations.
We again look at the 📖 exponential map. On a manifold M the exponential map needs a point p (to start from) and a tangent vector X, which can be seen as direction to “walk into” as well as the length to walk into this direction. In Manifolds.jl the function can then be called with q = exp(M, p, X) (see 🔗 exp(M, p, X)). This function returns the resulting point q, which requires to allocate new memory.
To avoid this allocation, the function 🔗 exp!(M, q, p, X) can be called. Here q is allocated beforehand and is passed as the memory, where the result is returned in. It might be used even for interims computations, as long as it does not introduce side effects. Thas means that even with exp!(M, p, p, X) the result is correct.
Let’s look at an example.
We take another look at the Sphere, but now a high-dimensional one. We can also illustrate how to generate radnom points and tangent vectors.
M = Sphere(10000)
 p₄ = rand(M)
-X = rand(M; vector_at=p₄)
Looking at the allocations required we get
@allocated exp(M, p₄, X)
17791918
While if we have already allocated memory for the resulting point on the manifold, for example
q₂ = zero(p₄);
There are no new memory allocations necessary if we use the in-place function.”
@allocated exp!(M, q₂, p₄, X)
0
This methodology is used for all functions that compute a new point or tangent vector. By default all allocating functions allocate memory and call the in-place function. This also means that if you implement a new manifold, you just have to implement the in-place version.
Decorating a manifold
As you saw until now, an 🔗 AbstractManifold describes a Riemannian manifold. For completeness, this also includes the chosen 📖 Riemannian metric tensor or inner product on the tangent spaces.
In Manifolds.jl these are assumed to be a “reasonable default”. For example on the Sphere(n) we used above, the default metric is the one inherited from restricting the inner product from the embedding space onto each tangent space.
Consider a manifold like
M₈ = SymmetricPositiveDefinite(3)
SymmetricPositiveDefinite(3)
which is the manifold of $3×3$ matrices that are symmetric and positive definite. which has a default as well, the affine invariant AffineInvariantMetric, but also has several different metrics.
To switch the metric, we use the idea of a 📖 decorator pattern approach. Defining
M₈₂ = MetricManifold(M₈, BuresWassersteinMetric())
MetricManifold(SymmetricPositiveDefinite(3), BuresWassersteinMetric())
changes the manifold to use the BuresWassersteinMetric.
This changes all functions that depend on the metric, most prominently the Riemannian matric, but also the exponential and logarithmic map and hence also geodesics.
All functions that are not dependent on a metric – for example the manifold dimension, the tests of points and vectors we already looked at, but also all retractions – stay unchanged. This means that for example
[manifold_dimension(M₈₂), manifold_dimension(M₈)]
2-element Vector{Int64}:
+X = rand(M; vector_at=p₄)
Looking at the allocations required we get
@allocated exp(M, p₄, X)
9920959
While if we have already allocated memory for the resulting point on the manifold, for example
q₂ = zero(p₄);
There are no new memory allocations necessary if we use the in-place function.”
@allocated exp!(M, q₂, p₄, X)
0
This methodology is used for all functions that compute a new point or tangent vector. By default all allocating functions allocate memory and call the in-place function. This also means that if you implement a new manifold, you just have to implement the in-place version.
Decorating a manifold
As you saw until now, an 🔗 AbstractManifold describes a Riemannian manifold. For completeness, this also includes the chosen 📖 Riemannian metric tensor or inner product on the tangent spaces.
In Manifolds.jl these are assumed to be a “reasonable default”. For example on the Sphere(n) we used above, the default metric is the one inherited from restricting the inner product from the embedding space onto each tangent space.
Consider a manifold like
M₈ = SymmetricPositiveDefinite(3)
SymmetricPositiveDefinite(3)
which is the manifold of $3×3$ matrices that are symmetric and positive definite. which has a default as well, the affine invariant AffineInvariantMetric, but also has several different metrics.
To switch the metric, we use the idea of a 📖 decorator pattern approach. Defining
M₈₂ = MetricManifold(M₈, BuresWassersteinMetric())
MetricManifold(SymmetricPositiveDefinite(3), BuresWassersteinMetric())
changes the manifold to use the BuresWassersteinMetric.
This changes all functions that depend on the metric, most prominently the Riemannian matric, but also the exponential and logarithmic map and hence also geodesics.
All functions that are not dependent on a metric – for example the manifold dimension, the tests of points and vectors we already looked at, but also all retractions – stay unchanged. This means that for example
[manifold_dimension(M₈₂), manifold_dimension(M₈)]
2-element Vector{Int64}:
  6
  6
both calls the same underlying function. On the other hand with
p₅, X₅ = one(zeros(3, 3)), [1.0 0.0 1.0; 0.0 1.0 0.0; 1.0 0.0 1.0]
([1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0], [1.0 0.0 1.0; 0.0 1.0 0.0; 1.0 0.0 1.0])
but for example the exponential map and the norm yield different results
[exp(M₈, p₅, X₅), exp(M₈₂, p₅, X₅)]
2-element Vector{Matrix{Float64}}:
  [4.194528049465325 0.0 3.194528049465325; 0.0 2.718281828459045 0.0; 3.194528049465325 0.0 4.194528049465328]
  [2.5 0.0 1.5; 0.0 2.25 0.0; 1.5 0.0 2.5]
[norm(M₈, p₅, X₅), norm(M₈₂, p₅, X₅)]
2-element Vector{Float64}:
  2.23606797749979
- 1.118033988749895
Technically this done using Traits – the trait here is the IsMetricManifold trait. Our trait system allows to combine traits but also to inherit properties in a hierarchical way, see 🔗 here for the technical details.
The same approach is used for
Again, for all of these, the concrete types only have to be used if you want to do a second, different from the details, property, for example a second way to embed a manfiold. If a manifold is (in its usual representation) an embedded manifold, this works with the default manifold type already, since then it is again set as the reasonable default.
References
[1]
Bergmann, R. and Gousenbourger, P.-Y.: A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics, 2018. doi: 10.3389/fams.2018.00059, arXiv: 1807.10090
[2]
Axen, S. D., Baran, M., Bergmann, R. and Rzecki, K: Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds, arXiv preprint, 2022, 2106.08777
[3]
Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access

+ 1.118033988749895

Technically this done using Traits – the trait here is the IsMetricManifold trait. Our trait system allows to combine traits but also to inherit properties in a hierarchical way, see 🔗 here for the technical details.

The same approach is used for

Again, for all of these, the concrete types only have to be used if you want to do a second, different from the details, property, for example a second way to embed a manfiold. If a manifold is (in its usual representation) an embedded manifold, this works with the default manifold type already, since then it is again set as the reasonable default.

References

[1]

Bergmann, R. and Gousenbourger, P.-Y.: A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics, 2018. doi: 10.3389/fams.2018.00059, arXiv: 1807.10090

[2]

Axen, S. D., Baran, M., Bergmann, R. and Rzecki, K: Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds, arXiv preprint, 2022, 2106.08777

[3]

Absil, P.-A., Mahony, R. and Sepulchre R., Optimization Algorithms on Matrix Manifolds Princeton University Press, 2008, doi: 10.1515/9781400830244 open access

diff --git a/previews/PR628/tutorials/hand-gestures.html b/previews/PR628/tutorials/hand-gestures.html index 65a4331dbe..56ba2348ba 100644 --- a/previews/PR628/tutorials/hand-gestures.html +++ b/previews/PR628/tutorials/hand-gestures.html @@ -1,5 +1,5 @@ -perform Hand gesture analysis · Manifolds.jl
Edit on GitHub

Hand gesture analysis

In this tutorial we will learn how to use Kendall’s shape space to analyze hand gesture data.

Let’s start by loading libraries required for our work.

using Manifolds, CSV, DataFrames, Plots, MultivariateStats
[ Info: Precompiling ManifoldsRecipesBaseExt [37da849e-34ab-54fd-a5a4-b22599bd6cb0]

Our first function loads dataset of hand gestures, described here.

function load_hands()
+perform Hand gesture analysis · Manifolds.jl
Edit on GitHub
Hand gesture analysis
In this tutorial we will learn how to use Kendall’s shape space to analyze hand gesture data.
Let’s start by loading libraries required for our work.
using Manifolds, CSV, DataFrames, Plots, MultivariateStats
Our first function loads dataset of hand gestures, described here.
function load_hands()
     hands_url = "https://raw.githubusercontent.com/geomstats/geomstats/master/geomstats/datasets/data/hands/hands.txt"
     hand_labels_url = "https://raw.githubusercontent.com/geomstats/geomstats/master/geomstats/datasets/data/hands/labels.txt"
 
@@ -11,83 +11,83 @@
 scatter3d(hands[1, 1, :], hands[1, 2, :], hands[1, 3, :])
Each gesture is represented by 22 landmarks in $ℝ³$, so we use the appropriate Kendall’s shape space
Mshape = KendallsShapeSpace(3, 22)
KendallsShapeSpace{3, 22}()
Hands read from the dataset are projected to the shape space to remove translation and scaling variability. Rotational variability is then handled using the quotient structure of KendallsShapeSpace
hands_projected = [project(Mshape, hands[i, :, :]) for i in axes(hands, 1)]
In the next part let’s do tangent space PCA. This starts with computing a mean point and computing logithmic maps at mean to each point in the dataset.
mean_hand = mean(Mshape, hands_projected)
 hand_logs = [log(Mshape, mean_hand, p) for p in hands_projected]
For a tangent PCA, we need coordinates in a basis. Some libraries skip this step because the representation of tangent vectors forms a linear subspace of an Euclidean space so PCA automatically detects which directions have no variance but this is a more generic way to solve this issue.
B = get_basis(Mshape, mean_hand, ProjectedOrthonormalBasis(:svd))
 hand_log_coordinates = [get_coordinates(Mshape, mean_hand, X, B) for X in hand_logs]
This code prepares data for MultivariateStats – mean=0 is set because we’ve centered the data geometrically to mean_hand in the code above.
red_coords = reduce(hcat, hand_log_coordinates)
-fp = fit(PCA, red_coords; mean=0)
PCA(indim = 59, outdim = 19, principalratio = 0.9912988285103255)
+fp = fit(PCA, red_coords; mean=0)
PCA(indim = 59, outdim = 18, principalratio = 0.9900213563800988)
 
 Pattern matrix (unstandardized loadings):
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-             PC1           PC2           PC3           PC4           PC5           PC6           PC7           PC8           PC9          PC10          PC11          PC12          PC13          PC14          PC15          PC16          PC17          PC18          PC19
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-1    0.0173855     0.000636845  -0.0161893    -0.0245499    -0.00981021    0.0108967     0.00480455   -0.00160225    0.00965055    0.00308236   -0.00718659   -0.000243068  -0.00278085    0.000614788  -9.15296e-5   -0.000505545   0.00195782    0.00250739    0.000594843
-2    0.00414129    0.000334051  -0.00621444    0.00790698    0.0175519    -0.0097201    -0.00241452    0.00218353    0.00804002   -0.0049976    -0.00514098    0.00217929   -0.000189061   0.00306193    0.0045976    -0.00290717    0.0027132     0.000826467   0.000683271
-3   -0.00278452    0.0327623    -0.00106001   -0.00522848   -0.00599399    0.00897585    0.0109365     0.00154308   -0.00510698   -0.0118133    -0.000394887  -0.00861796   -0.000921745  -0.00186573    0.00624982   -0.00378874    0.00282378   -0.00101771   -0.00286378
-4    0.00227632   -0.0205855    -0.00370886   -0.00918484   -0.00281422   -0.00511051   -0.015321      0.00120702   -0.006792     -0.00168908    8.68548e-6    0.00402992   -0.00324521    0.00280144    0.00255311   -0.00160794    0.000180003  -0.000551923   0.00130734
-5   -0.0049244     0.0121741    -0.0119137     0.0118437     0.00064937    0.0129349    -0.00160643    0.00385634   -0.00686451    0.00113489   -0.000602382   0.000139858   0.00439824    0.000576411   0.00406128    0.000175348  -0.00222317   -0.00454532    0.00239012
-6    0.0022564     0.00405703   -0.0147493     0.00479343    0.00099672   -0.0037997     0.00427197   -0.00492114   -0.00751233    0.00635193   -0.0046186    -0.00386301   -0.000190645  -0.000564171  -0.000725947   0.00416211    0.000130641   0.00255604   -0.00126336
-7   -0.00849223    0.0185022     0.010854      0.0155381     0.00220708    0.000408101  -0.00732174   -0.00679773    0.0012842     0.00746195   -0.00570278   -0.00230826    0.00379148    0.00122698    0.00123253   -0.00166504    0.00307727    0.000367742   0.00210109
-8    0.0364754     0.00356004    0.00864952   -0.00313843    0.0128588     0.000392635   0.000367246   0.00971228   -0.00555784    0.00454216    0.000805735   0.000455146  -0.00178109   -0.0059085    -0.000704806   0.00202109   -0.00231604   -0.00145624   -0.00135686
-9   -0.00642437    0.0193549    -0.011419      0.000886165   0.0166549     0.00515056   -0.000280578   0.00361531    0.00435576    0.00122792   -0.00134617   -0.000851905  -0.0104828    -0.00184189    0.000607793   0.00344577    0.0057421     0.000522023   0.000591562
-10   0.0375757    -0.00015996    0.0407193     0.018211     -0.0211973     0.0109156     0.00528872   -0.00438362   -0.00573709   -0.00167852    0.000278635  -0.0022946     0.00153229   -0.000445404   0.00259449    0.00224609   -0.000574173   0.00274393    0.000188819
-11   0.0277787     0.00780307   -0.0166318    -0.00376651   -0.0083135    -0.00195865   -0.000493546  -0.00024609   -0.00567971   -0.00532441   -0.00212507    0.00602551    0.00386       0.00193343    4.23417e-5   -0.00476551    0.000403882   0.00184378    0.000899672
-12   0.10427       0.0111309    -0.015799     -0.000302332   0.00516824   -0.00532884   -0.0014996    -7.30056e-5   -0.00240161    0.00172376    0.00687669   -0.00625024   -0.00639534    0.00295592    0.00113749   -0.000466109  -0.000286855   0.00130816   -0.00023168
-13   0.0349156    -0.0259781     9.64139e-5    0.00413941    0.00930036    0.0120427    -0.00544059   -0.0130528     0.0092189     0.00781286    0.00541738    0.00122035    0.00472085   -0.00313777    0.00420017   -0.00330501    0.00263946    0.00114665   -0.00191432
-14   0.0406743    -0.0145554     0.00847745   -0.008102     -0.0146731     0.0122504     0.00151511    0.0119469     0.00645629   -0.00484009    0.00357907    0.0022329     0.00315935   -0.00342815    0.00112121    0.000716972  -0.000267723   0.00102893    0.00226669
-15  -0.00930256   -0.0167858     0.00611584    0.024959     -0.00635687    0.00927873    0.00612683    0.0137937     0.00355393    0.00435918   -0.00352841    0.00155106   -0.000587037   0.0032852    -0.00115968   -0.00459812    0.000365738   0.00152501   -0.00220028
-16  -0.00443594   -0.00281474    0.00505291   -0.00342471    0.0178561    -0.00334566    0.00749361   -0.00705821    0.00378162   -0.00416412   -0.00867159    0.0033906     0.00257508    0.00611411    0.00313804   -0.00166894   -0.000486449  -0.000684733  -0.000431136
-17   0.0116867     0.0190841     0.00768291    0.00226264   -0.0023963    -0.0120551    -0.0108479     0.00923083    0.00173054    0.00319921    0.000263058   0.00831246    0.00149357   -0.00341414    0.00165869   -0.000452325   0.00122167    0.000489292  -0.000724031
-18   0.0267767    -0.0159784     0.0133608    -0.0147061     0.0162533     0.00217607   -0.00086192    0.00502474   -0.00327539    0.00389318    0.00760878    0.000559328   0.00246694    0.00188893    0.00119427   -0.00116627   -0.000328369   0.00330999    0.000683408
-19   0.0178674     0.00678508    0.00622795    0.00252456    0.0101081    -0.00520374   -0.00394873   -0.00857975    0.00459688    0.00264695    0.00338812   -0.00368184   -0.00100438   -0.0019011     0.000770851   0.00044916   -0.00450338    0.000428239  -0.00173068
-20   0.0142149    -0.0102457    -0.00720102   -0.00827252   -0.000194544  -0.00904612    0.00656784   -0.00288506   -0.00337141   -0.000904713   0.00562513    0.00267589    0.00346339   -0.00100621   -0.00310453    0.00179422    0.000962525  -0.000278243   0.00176121
-21  -0.0236419    -0.0249401    -0.00224796   -0.00102043   -0.00730152    0.00452086    0.00427695    0.00706512   -0.00260505    0.00724108    0.00013085   -0.000635022  -0.0044843     0.0065385     0.0038201     0.0021496    -0.00239896   -0.00176404   -0.000719906
-22  -0.0321825    -0.00425879    0.0225478     0.0109337     0.0145482     0.0158751    -0.00235927    0.00364776    0.000820952   0.00241549    0.0041401    -0.000768498  -0.00151804   -0.00103051   -0.000977858   0.00102485    0.00302874   -0.00154859    0.000908919
-23  -0.0547437     0.00957327   -0.0296533    -0.00785133    0.0046406     0.0125083    -0.003309     -0.00971159   -0.00520429    0.000105352   0.0123953     0.00298409   -0.00098002   -0.00107685    0.00212605   -0.00222586   -2.45066e-5    0.00179058   -0.00341318
-24  -0.0459331     0.0277414     0.0177563    -0.00757283   -0.00154994    0.00419174    0.000228397   0.0047202    -0.00719053    0.00425062    0.00842774    0.00407616    0.00221613   -0.00192485    0.000413624  -0.00184245   -0.000469158   0.00126403    0.000520384
-25   0.0137253     0.0330938    -0.00259305   -0.0173027     5.76481e-5    0.0133787    -0.00258063    0.00199686    0.00372244    0.00811022    0.000803248  -0.00177067    0.00209383   -0.000529693   0.00128358   -0.0037069    -0.00514658   -0.00184888   -0.000194885
-26  -0.0603615    -0.0119161     0.00882267    0.00514721    0.00529219   -0.0122092     0.00736956   -0.00682808    0.000558328   0.00834601    0.0116706    -0.00351252   -0.00185182   -0.000584981   0.000266096  -0.0040918     0.000738611  -0.000967152   0.00238475
-27   0.0336629     0.0104236     0.0261054    -0.0152452    -0.00252001   -0.00504679   -0.0123813    -0.00272042    0.00297605   -0.00692167    0.00454449    0.00353461   -0.00250126    0.00216841   -0.00364534    0.000924378  -0.00102377    0.000628113   0.000155479
-28   0.0422619    -0.00242415    0.00194491   -0.00269802   -0.00745415   -0.0151133     0.00447106    0.00282524   -0.00353172    0.00314076    0.00584346   -0.0046243    -0.00235677    0.00768856    0.000553617   0.00217504    0.000911649  -0.00247882   -0.000685967
-29   0.00883288   -0.00162966    0.018317     -0.00091465   -0.0117905    -0.0143036    -0.00415359   -0.0102138    -0.00610175    0.00279988   -0.00565156    0.0046463     0.00197636   -0.00129791    0.00400266   -0.00288579   -0.0019277     0.000179645  -0.00116481
-30  -0.0167029     0.00911663   -0.00133306    0.00854662   -0.0196894    -0.00125151    0.00519147   -0.00662994    0.0116743    -0.00286996    0.00369844   -0.00142735    0.00241535    0.00170889   -0.00332472   -0.000731511   6.42406e-5   -0.00392972   -0.00221066
-31   0.0185643    -0.00511788    0.00897978   -0.0059246     0.0069449     0.00488395   -0.0036883     0.000884436  -0.00130671    0.00485091   -0.00602461   -0.00157791    0.000661809   0.00128482   -0.0022535     0.000643781  -0.00137816    0.00138855    0.00177414
-32   0.0318392    -0.0241056    -0.00183089    0.00331854   -0.00112742    0.00427225    0.00690474   -0.0114143     0.0135192     0.00089417    0.00105723   -0.00176937    0.00226368   -0.00349391   -0.000954307   0.00145221   -0.00236592    0.000190196   0.00329855
-33  -0.0323147     0.053425      0.0372678    -0.0105732     0.0132107    -0.00339071   -0.000764724  -0.00172247    0.010934     -0.00426652    0.00350433   -0.00285683    0.00615795    0.00285417   -0.0014361     0.00537323    0.00181549    0.0011817     0.000144893
-34   0.0102755    -0.0254688     0.000576695  -0.0157286    -0.00370359    0.00639325   -0.0100209    -0.00130888   -0.00169533   -0.00640355   -0.00161379   -0.00620737    0.00465267   -0.00542501    0.00221331    0.00467989   -0.000154791  -0.00357667   -0.00174044
-35  -0.0187921    -0.0278792     0.00762221    0.0203661    -0.00522219   -0.00496367    0.0026507     0.00309316   -0.00263494   -0.0023065     0.00230521   -0.0021306     0.00317717   -0.0011341     0.00171337    0.00253469    0.00173667    0.00472356   -0.00325254
-36  -0.0281434     0.00692303    0.0135576     0.0150621    -3.45035e-5    0.00692872   -0.00213414    0.00749015    0.00013037   -0.00161564    0.0014149     0.00355391   -0.00353628    0.00186856   -0.0040984    -0.000762863  -0.00374575   -0.00286227    0.00239549
-37   0.0444518     0.0140451    -0.0177105     0.00747961    0.000690187   0.0143313    -0.00211967   -0.00148993    0.00697546   -0.00192432    0.00286409    0.00458382   -0.000210551   0.00431424    0.000836407   0.00198358    0.000554871  -0.00185297   -0.000933994
-38   0.0427542     0.0198576    -0.00795449    0.0115803    -0.00629815    0.000958173  -0.000670645   0.00184352   -0.0014269    -0.00182662    0.00286294   -0.00191824    0.00346162   -0.00172646   -0.0048974    -0.00372581    0.00120087    0.0019076     0.00402424
-39   0.0229225    -0.00426749    0.0223177    -0.00606517   -0.000464169  -0.00294724    0.0133813    -0.0024651     0.00602226    0.00279229    0.000209127   0.00209029   -0.00436785   -0.00112376    0.00524927   -0.00139411    0.00203064   -0.00387777    0.00210721
-40   0.00340627   -0.002551      0.00468302    0.016922     -0.00087532    0.00381858   -0.00115579   -0.00982067   -0.000953865  -0.0107195    -0.00149229    0.00567459   -0.00950229   -0.00649935   -0.00401252   -0.00142877    6.51574e-5   -0.001418     -0.0007485
-41  -0.00252943   -0.0154656    -0.0185877    -0.00503709    0.0196475     0.000757621   0.0083016    -0.00139321   -0.0122729    -0.00334757    0.000134299   0.0025698     0.00693995    0.000106431  -0.00570021    0.001442      0.00234008   -0.00351234    0.00105664
-42  -0.0197534    -0.0420968     0.00903828   -0.0126781    -0.00700759    0.00315487    0.00215178   -0.00277645   -0.00241088    0.00403162   -0.00370267   -0.00432386    0.00329252    0.00108784   -0.00355877    0.000312319   0.00117976   -0.00111906   -0.00100037
-43  -0.0165414     0.00141539   -0.0137025     0.00235394    0.0100988    -0.00772571    0.0161823     0.0080184     0.0109971    -0.0068699     0.00472434   -0.000858139   0.00166438    0.000621182   0.00347287   -0.00042774   -0.00578248    0.00116141   -0.000969362
-44   0.00327356    0.00732386   -0.0172391     0.00208018   -0.00439327   -0.0129229    -0.00222108    0.0138643     0.00446419    0.000994211   0.0015694     0.00304331    0.00744581   -0.00213839    0.00202703    0.00250179    0.00141239   -0.000133561  -0.00230411
-45  -0.000888326   0.0259359    -0.0130999     0.00421491    0.00342141    0.0144244     0.00336686   -0.00102413   -0.00817201    0.00386964   -0.00406899    0.00163275    0.00427038   -0.000788569   0.00357643    0.00316951    0.000309124   0.00150524    0.00161125
-46  -0.0042722     0.00307551    0.00358086    0.00270541   -0.0161164    -0.00118439   -0.00450004    0.00302117    0.00390437    0.00333273    0.003588      0.00229504    6.91777e-5    0.000371144   0.000325992   0.00111262    0.00341049   -0.00107284   -0.000469154
-47  -0.0272713     0.0117052     0.0030402     0.00528473   -0.000105286  -0.00283541   -0.00784446    0.00565022    0.00170229    0.00394462   -0.00513521   -0.00819901    0.000136608   0.00181311   -0.00200453   -0.00178317    0.00129039   -0.00147405   -0.000814289
-48  -0.0134193    -0.0186634     0.000326505  -0.00455047   -0.00159784    0.00490561   -0.00164247   -0.00449218    0.00307453    0.000120946   0.00248512    0.00924946    0.00107424    0.00620751    0.00352128    0.0032275     0.00195177   -0.00125506    0.00112995
-49  -0.00241856   -0.0212005     0.0255376    -0.0142958     0.0108332     0.00804346    0.00190185    0.00388918   -0.00871033   -0.00484363    0.000815342  -0.000501167  -0.00667201    0.000774967  -6.7004e-5    -0.00134048    2.77396e-5    0.00200935   -0.00124611
-50   0.0186602    -0.0137507    -0.00215632    0.0148877     0.0130769     0.00787733   -0.00673317    0.00375946    0.0104502     0.00157273   -0.0016547     0.00151579    0.000143324   0.00199503   -0.00527869    0.00035693   -0.00175686    0.000878632  -0.00360001
-51  -0.0466559    -0.0141001    -0.00849404    0.00284194    0.00635534   -0.002886     -0.00521712    0.00171564    0.00357409   -0.0056073    -0.00483095   -0.00512542   -0.00101796   -0.00138773    0.00397766    0.000947478  -0.00312091    0.00327453    0.00558783
-52   0.016956      0.0109322    -0.00785692    0.0191416    -0.00204687    0.00622328   -0.00116895   -0.0092148    -0.00570974   -0.00132407    0.00384308    0.00255672   -0.0011175     0.00740385   -0.000415327   0.00502273   -0.00236483    0.00208774    0.000171655
-53   0.0290288    -0.0180278     0.00561411    0.000300885  -0.00347658    0.00636645    0.000726997   0.00533765   -0.000322152  -0.00590684    0.00667851   -0.00364209    0.00171821    0.00474059    0.00310052   -0.00152966    0.00284979    0.000256984   0.00251753
-54  -0.0177287    -0.000415008  -0.0179228    -0.00752319   -0.0143941    -0.00299678    0.0134179     0.00368634    0.00596021    0.00644779    0.00176823    0.00466333   -0.00528731   -0.00497389   -0.00206298    0.00309406    0.00107216    0.00205944    0.00182448
-55   0.0568136     0.00919571    0.0250636     0.00058887    0.0142726    -0.000612628   0.0206662     2.20095e-5   -0.00422504    0.00328228   -0.00575157    0.00741408    0.00125492   -0.00202048    0.00106353    0.000523687  -0.000235755  -0.000703685  -0.00181743
-56  -0.0710828     0.01179       0.0078574    -0.0235474    -0.0129393     0.00685923    0.00325491   -0.003256      0.00267407   -0.000496581  -0.00414493    0.00346954   -0.00180817    0.00410908   -0.000452841   0.000890347  -0.00112818    0.0023644    -0.0011635
-57  -0.00737688    0.0227088    -0.00145208    0.00822139   -0.00305843   -0.00168834    0.0109569    -0.00435245   -0.006992     -0.000592417   0.00111379   -0.00090976    0.0011256     0.00241324   -0.00434676   -0.000758851   0.00038675    0.00101628    0.000880843
-58   0.00230222    0.0190556    -6.60482e-5    0.0108511    -0.00704239   -0.00533839   -0.00472773   -0.00333405   -0.00175351    0.00266828   -0.000361014   0.000837679  -0.00489893   -0.00248396    0.00804991    0.00362131   -0.000867214  -0.00137022    0.00092548
-59  -0.0478689    -0.0216948     0.0024752     0.0145396     0.00704264   -0.00198715    9.93362e-5    0.000922192  -0.00090266   -0.00454114    0.00377277    0.00257683    0.00161294   -0.00247874    0.00418941    0.00181706   -0.000826388   1.92124e-5    0.000363471
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+            PC1           PC2           PC3           PC4           PC5           PC6           PC7           PC8           PC9          PC10          PC11          PC12          PC13          PC14          PC15          PC16          PC17          PC18
+─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+1   -0.0290105    0.0208927    -0.01643       0.00190549    0.00901145    0.000643771  -0.00363047   -0.00217327    0.00312554   -0.00356053    0.00478045    0.00165704    0.00218866    0.0037857     0.000320345  -0.00145212    0.000948335  -0.00184176
+2    0.0172527    0.0165863    -0.0168821    -0.0183233     0.0121555     0.00833736    0.00187667   -0.000648234   0.00706323    0.00583622   -0.0044018     0.0012355     0.00118376   -0.00246016    0.00446684   -0.00498993   -0.0028049    -0.00259758
+3    0.0447499   -0.00487667   -0.00247071   -0.00148697   -0.00200127   -0.00795338    0.00905314    0.00687454    0.0114088    -0.000998774   0.00459101    0.00645948    0.00073043    0.00591995   -0.00520394    0.00129428   -0.000463386  -0.00207384
+4   -0.00881422  -0.0341713     0.00749624    0.00795209   -0.00260601    0.00356386    0.00204456   -0.00905276    0.00826807    0.00012095    0.000768538  -0.000460691   0.00411022   -0.00216294   -0.000650028   0.00251224    0.00149784   -0.00181133
+5    0.0325794   -0.023796      0.000642765   0.00509869    0.00759807    0.00483368   -0.00252952    0.00656179    0.00322274   -0.000313146   0.00143493   -0.000676479   0.000146354  -0.00266203    0.00353957    0.0021415    -0.00457168    0.00282965
+6   -0.00617763   6.91201e-5    0.00765638    0.00183758    0.00157382    0.00184956   -0.00797935    0.000700457   0.0087012     0.00992564    0.00263642    0.00294279   -0.0092        0.00133877    0.00145735   -0.0014816     0.00235123   -0.00039541
+7   -0.0183122    0.0131045     0.0125222    -0.00638021   -0.006709     -0.00013628    0.00858169   -0.00159031   -0.00585433   -0.0032447     0.00880912   -0.00149308    0.000724205   0.00469925    0.00432005    0.0012382    -0.00251638    6.89878e-5
+8    0.0392874   -0.0152552    -0.00404674   -0.0183856    -0.0054739     0.000203488   0.00687526    0.00989129   -0.00570517    0.00234255   -0.00221344   -0.00514796    0.000658069   0.00220789    7.02581e-5    0.000380265   0.0007751     0.00234631
+9   -0.00525049  -0.0181427    -0.00473895   -0.0128126     0.000405834  -0.00936332   -0.000781745   0.011196     -0.00498502    0.00199077    0.00355555   -0.00334398    0.00763648    0.000311697  -0.000844841  -0.00526438   -0.00201977    0.00188678
+10   0.0771681    0.0248294    -0.00375548   -0.0138712    -0.0126479    -0.00543573   -0.0136609    -0.00408721   -0.00445726   -0.00407287    0.00696664   -0.00158737   -0.00201909   -0.00211184    0.000907502   0.00235338   -0.00259266    0.00114594
+11  -0.0013693    0.0125762    -0.00145726    0.0119688    -0.00362363    0.00954477    0.000894749   0.00311196    0.000186917   0.00923739    0.0036434     0.00484736    0.000288834  -0.00269382   -0.00194147   -0.000702207  -0.00245996   -0.000458531
+12   0.00497523   0.0154863     0.0409999    -0.00832204   -0.00216091    0.0149159     0.011796      0.0121391    -0.00292353   -0.00532504   -0.00427894    0.000550893  -0.00408841    0.000520159  -0.00344571    0.000625647   0.000271049  -0.00165807
+13  -0.0541357   -0.0291498     0.0140122     0.00292223    0.00128359    0.00301256   -0.00581861   -0.00397323    0.000588485   0.0025976    -0.00442985   -0.00603182    0.00326815    0.00326603    0.000384467  -0.00134404   -0.00160027   -0.00261985
+14  -0.0493144    0.0120223    -0.0163111     0.0103746    -0.0126512    -0.011453      0.00488614   -0.00586095    0.0027455    -0.00434342    0.00203457   -0.000941868  -0.00426973   -0.00447805   -0.00239537   -0.00320013    0.000877498   0.000673572
+15  -0.00654048   0.00225524   -0.028207      0.00306531    0.00321072   -0.000599231   0.00320363   -0.0059508    -0.00586048    0.0031903    -0.00613799    0.00471076   -0.00101853    0.00294667   -0.000548534   0.00402922    0.000405583   2.6607e-5
+16   0.0300802    0.0075843     0.00364836   -0.00205771   -0.0148831     0.0211394    -0.000508637   0.0036868     0.0109845    -0.00574404   -0.00920237    0.0007153     0.000544823  -0.00209521    0.000474541  -0.00052208    0.00180017    0.00202094
+17  -0.0110775    0.0373997    -0.00242133    0.00827109   -0.000567586  -0.0141686    -0.000939656   0.00843637   -0.00590348    0.00649057    0.00259619   -0.000897277   0.00443368   -0.0047585    -0.00160148    0.000335684   0.00152076   -0.00300398
+18   0.0391783    0.0248007     0.0308429     0.00118303    0.00981074    0.00261316   -0.00100239   -0.0062546    -0.00491006   -0.00506867    0.00441608   -0.00367774   -0.00481009   -0.000493728  -0.00329753    0.000419403   0.000711267   0.000406243
+19   0.0138738   -0.0443171    -0.00598066    0.00585226    0.00596223    0.00680714   -0.0079294    -0.00269779   -0.00426069   -0.00718608    0.00761514    0.00336824   -0.00295577   -0.00264683    0.00316699   -0.000418376  -0.00240164   -0.00413196
+20   0.0173164   -0.0215417     0.000863689  -0.0205664     0.00121695    0.00307745    0.00191828   -0.00849558   -0.00147893    0.00180504    0.00814434    0.00372913    0.00188294   -0.00170647   -0.00451407   -0.00100769   -0.000238128  -0.000257117
+21   0.00338984   0.00237562    0.0237069    -0.0129184     0.00148197   -0.000855367   0.00148785    0.00142366    0.00320966    0.00781237    0.000800995  -0.000516126   0.00440079   -0.0079143     0.00215576    0.00201592   -0.000335618   0.00337192
+22  -0.00746071  -0.0116344     0.0021644     0.0152239     0.00723169    0.0120803    -0.000485058   0.00653526    0.0026666     0.00152026    0.0135607    -0.00247612    0.00348543    3.45051e-6    0.0017885     0.000179426  -0.000524643  -0.000805656
+23   0.0478442   -0.0227649    -0.0113793    -0.00367693    0.0106966     0.00169994    0.0135303    -0.00344929    0.000128235   0.00063693   -0.00225447    0.000880574  -0.00665083   -0.0050547    -0.00295617   -0.00422433    0.00166798   -0.00189465
+24  -0.0142467    0.0166931     0.00516018    0.00593988   -0.0210703     0.00438546    0.00643305    0.00174866    0.00505729    0.000463517   0.00763753   -0.00417294   -0.00156206    0.00540319   -0.00301265   -0.00408336   -0.00144362   -0.000137294
+25   0.00108012   0.0195339     0.011519      0.0110158     0.00193433    0.0107534    -0.00146174    0.000236797   0.00226925   -0.00744152    0.00199678   -0.00445237    0.00273993   -0.000207735  -0.00191042    0.00121896    0.00195283   -0.00274164
+26   0.0123466    0.0083253     0.00519553   -0.00196478    0.0137825    -0.00233978   -0.00771765   -0.00232805   -0.00279333    0.00340724    0.0012353    -0.00362154   -0.0013554     0.000632953  -2.37112e-5    0.00141247   -0.000568908  -0.000973567
+27  -0.00893091   0.00641791    0.0087648     0.00424429   -0.000824081  -0.00761539   -0.0152518     0.00995065    0.00317758    8.84094e-5   -0.00419563   -0.00124495   -0.00589762   -0.000929293   0.00477719    0.00377025    0.00267074    0.000761405
+28   0.0378644   -0.0125169     0.012799      0.0178141     0.00260966   -0.00752201    0.00299546   -0.00777486    0.00426756    0.00566038    0.00107451   -0.000215202  -0.00470252    0.00209217   -0.000578698   0.00150591   -0.00148331    0.00229085
+29   0.00205475   0.0304241    -0.0354979     0.00394855   -0.00350914    0.00725592   -0.00678139    0.000307436  -0.00315394   -0.00689183    0.000456785   0.00368637    0.00277269   -0.00277076   -0.00422942    0.00223455    0.0015448    -0.00234455
+30   0.0749975   -0.00999942    0.00367276    0.0100629    -0.00671752   -0.011357      0.00301586    0.000408736   0.00259563    0.000303288  -0.000111357  -0.00159763    0.00161827   -0.000545339   0.00377406    0.00268094    0.00406555   -0.00203144
+31   0.0209729    0.00213421    0.00669869    0.016557      0.00403684   -0.0178951     0.0107244     0.0111298     0.00610797   -0.00390215   -0.00353771   -0.00178467    0.00235713    0.000973802   0.000274041   0.00218045   -0.00215689   -0.00158819
+32  -0.0244084   -0.0371206     0.0192767    -0.000685794   0.0158289    -0.001451     -0.00509477    0.00577056   -0.00513049   -0.00950968   -0.00158958    0.000989458  -0.000699212   0.00122133   -0.000191417   0.000911926   0.00209233   -6.04374e-5
+33   0.00565764  -0.0172793     0.00401092   -0.00793658    0.00504771   -0.00220381    0.00224319    0.0071918    -0.0124133     0.00175162    0.00348751    0.00633021   -0.00260535    0.00565187   -0.00186287   -0.000238933   0.000666333   0.00250607
+34   0.00185581  -0.0166196    -0.0197269     0.00699341    0.00647246   -0.00303065   -0.000117067   0.00490106    0.00667588   -0.00855122    0.00302462    0.00173228    0.00553969   -0.00468124    0.00121978    0.0005079     0.000420239   0.00253235
+35   0.0199811    0.0267965     0.0129649     0.00264194    0.000195136  -0.00349662    0.00294599   -0.00187851    0.00177767   -0.0053757    -0.00330811   -0.00295473    0.00208629   -6.97773e-5   -0.00153972   -0.000773065  -0.00157575   -0.000197057
+36   0.0175704    0.0191343    -0.0116551     0.00882917   -0.0104714     0.0103777     0.00118041   -0.000696881   0.00192364    0.00744034    0.00497109   -0.00164206    0.00162482   -0.00139405    0.00167977    0.000693101  -0.00132024    0.00297973
+37  -0.00462744  -0.013417      0.00735863    0.0138801    -0.0058212    -0.00238145   -0.00576575    0.00188503    0.00101854    0.0035232     0.0016009     0.00106877   -0.00593854   -0.0015165    -0.00563642   -0.000339869   0.00216456    0.002153
+38  -0.0218719    0.00531191    0.00305154    0.0241393     0.0234907     0.00316473    0.0020773    -0.00469298   -0.00845531    0.00456344   -0.000534739   0.00131404   -0.00166945   -0.000113877  -0.00168502    0.00333815   -0.00307554    0.00114466
+39  -0.00848638   0.0208304     0.00949937    0.0226454     0.0052942    -0.000851704   0.00632965    2.91971e-5    0.00329463    6.28469e-5    0.00660731    0.00235582   -0.00130279   -0.00141865    0.00530658   -0.00248136    0.000456183   0.00125713
+40  -0.0887529   -0.0108083    -0.00348235   -0.0197061    -0.00851786   -0.00490488    0.00159713    0.00351037    0.0148414    -0.00401737    0.00779929    0.00245023   -0.00253298   -0.000226246  -0.000206421   0.00510786    0.00148421    0.00186788
+41   0.00130006   0.00193007   -0.00297337    0.0070658     0.00888416    0.00665004   -0.013746      0.000961125   0.00363303    0.00316905    0.000576911  -0.00659932    0.00136165    0.0013939    -0.00380487   -0.00444913    0.00366095    0.00144111
+42  -0.0207553    0.0174796    -0.00445662   -0.0117613     0.0273261    -0.00065484    0.00296882    0.00593266    0.00162045   -0.00318673    0.0066341    -0.0053347     0.000440878  -0.000644585  -0.00244859    0.00184264    0.00345959   -0.000426283
+43   0.0413948    0.00307635   -0.00665062   -0.00226029    0.017443     -0.00424136    0.00950125   -0.00429922    0.00148225   -0.000166312   0.00294757   -0.00069645    0.000696539   0.000366659   0.00282844   -0.00230084    0.0053369     0.00238474
+44   0.00449575   0.0201137     0.03094      -0.0058886    -0.00146264    0.0101428    -0.00516029    0.00543426   -0.00941967    0.000969442  -0.000431407   0.0064443     0.00115545   -0.00181689    0.00364823   -0.000426309   0.000849352  -0.00167685
+45  -0.0205292   -0.00157548    0.013357     -0.00792343    0.00744915    0.00216668   -0.00243796    0.00180573    0.01512       0.00713893   -0.00283512    0.00430074    0.000788886   0.0049491     0.0029426    -0.00139686    0.00105337   -0.00239361
+46  -0.0215505   -0.0112917     0.013841      0.0111599    -0.0105729     0.00953035    0.0113897    -0.00673481   -0.0100248     0.00344613    0.00262901    0.0047878     0.00566946   -6.60172e-5    0.00414744    0.00111141    0.00450865   -0.00145945
+47  -0.0171993    0.0180146     0.00810394   -0.00791244    0.0061704     0.00923438    0.000727892  -0.0152243     0.00748635   -0.00599911   -0.00175649    0.00265434   -8.49398e-5    0.00305952   -0.00198115    0.00274446   -0.0028668     0.00323797
+48   0.0587549    0.0116068    -0.00915491    0.00448539    0.0104133     0.00457871    0.00126112    0.00499596    0.00964989   -0.00404286    0.000207311   0.003728     -0.000433589  -0.000303131   0.00412588    0.000467283  -0.000916261  -0.00103631
+49  -0.00166257   0.0250389     0.00797097    0.000683472  -0.000895449  -0.0133557    -0.00573426    0.000680622   0.00069621    0.00638431   -0.00245348    0.00498899    0.00507946    0.0057863    -0.00069408    0.0014596     0.000877213  -0.000692365
+50  -0.0355097    0.0143079    -0.00981991    0.00946907   -0.00422843   -0.00254884    0.00491884    0.00651818   -0.00548423   -0.0071809     9.81603e-5    0.00390103   -0.00712449    0.0013088     0.00694234   -0.00320143    0.000147409   0.00234526
+51   0.0456319   -0.0188437     0.00614929    0.01619      -0.0156405     0.00353768   -0.00911906    0.000874972  -0.00121217   -0.00403428   -0.000414905   0.00681573    0.00859836    0.00350106   -0.00263157   -0.00122084    0.00183226    0.00257702
+52   0.00746721   0.0133773    -0.0340613    -0.0139034     0.00655522    0.00929538    0.000770716  -0.000483502  -0.00600155    0.00201797    0.0011251     0.00179484   -2.38878e-5    0.00486216    0.00282832    0.00255029    0.00367921    0.00129338
+53   0.00823236  -0.00600734   -0.0200329     0.00202998   -0.0011313     0.0105144     0.00321895    0.00687414    0.000987698   0.00431901    0.000760463  -0.00635147   -0.00119575    0.00474285    4.40898e-5    0.00580837   -0.00332298   -0.00201341
+54  -0.043754    -0.00171994   -0.00111157    0.00123094   -0.00428039    0.0027972     0.00934907   -0.00596239   -0.00226019    0.001642     -0.00513074   -0.00589632    0.00344517   -0.0042949     0.0025378     0.00306413    0.00186166    0.00125999
+55   0.0430398   -0.000525733   0.0081576    -0.00839141   -0.00347855   -0.00933299    0.00251806   -0.0126012     0.002086      0.00272973    0.00204035   -0.000224255  -0.000607192  -0.000454776  -0.000157181   0.00250081    0.00145433   -0.00163108
+56   0.0305092   -0.00319322   -0.010629      0.0139009     0.00442941    0.00855659    0.00087527   -0.00330425    0.000399393  -0.000737765  -0.00150343   -0.00754475    0.000704529   0.00851631    0.00185909   -0.00126123    0.00232031    0.00223781
+57   0.00321453  -0.0190408    -0.0279848     0.00741802   -0.0157076     0.00592558    0.0020086     0.00843992   -0.00442316    0.00325392   -0.002545     -0.00268433   -0.00623548   -0.00142257   -0.00199612    0.0016597     0.000405685  -0.00229266
+58   0.0156328   -0.0074322     0.0066988    -0.0114629    -0.0168092     0.00328227   -0.00226964   -0.00110748    0.000440872   0.00227572    0.00827165   -0.00488151   -0.00316671   -2.58046e-5    0.00360288    0.00115025    0.00316887   -0.00204823
+59  -0.00151264   0.00426245    0.00115303    0.00338067    0.00957651    0.0116283     0.00361068    0.0102905     0.00246382    0.00700902    0.00252521    0.00257786    0.000578243  -0.00384276   -0.00597088    0.00283491    0.00171675    0.00226962
+─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 Importance of components:
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-                                 PC1        PC2        PC3         PC4         PC5         PC6        PC7         PC8         PC9        PC10        PC11         PC12         PC13         PC14         PC15         PC16         PC17         PC18        PC19
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-SS Loadings (Eigenvalues)  0.0572506  0.0191037  0.0120201  0.00706941  0.00554948  0.00374734  0.002738   0.00220153  0.00208836  0.00128335  0.00123065  0.000879446  0.000798525  0.000599247  0.000553266  0.000362632  0.000274384  0.000230071  0.00020263
-Variance explained         0.480209   0.160239   0.100823   0.0592971   0.0465482   0.0314321   0.0229659  0.0184661   0.0175169   0.0107646   0.0103225   0.00737666   0.00669791   0.00502639   0.00464071   0.0030417    0.00230149   0.0019298    0.00169963
-Cumulative variance        0.480209   0.640448   0.741271   0.800568    0.847116    0.878549    0.901515   0.919981    0.937497    0.948262    0.958585    0.965961     0.972659     0.977686     0.982326     0.985368     0.987669     0.989599     0.991299
-Proportion explained       0.484424   0.161645   0.101708   0.0598176   0.0469567   0.031708    0.0231675  0.0186282   0.0176706   0.0108591   0.0104131   0.00744141   0.0067567    0.00507051   0.00468145   0.0030684    0.00232169   0.00194674   0.00171455
-Cumulative proportion      0.484424   0.64607    0.747778   0.807595    0.854552    0.88626     0.909428   0.928056    0.945726    0.956585    0.966999    0.97444      0.981197     0.986267     0.990949     0.994017     0.996339     0.998285     1.0
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Now let’s show explained variance of each principal component.
plot(principalvars(fp), title="explained variance", label="Tangent PCA")
The next plot shows how projections on the first two pricipal components look like.
fig = plot(; title="coordinates per gesture of the first two principal components")
+──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+                                 PC1        PC2        PC3         PC4        PC5         PC6         PC7         PC8         PC9        PC10       PC11         PC12         PC13         PC14        PC15         PC16         PC17         PC18
+──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+SS Loadings (Eigenvalues)  0.0559745  0.0192925  0.0128414  0.00672244  0.0055061  0.00364815  0.00229962  0.00223028  0.00206984  0.00135745  0.00119    0.000805397  0.000775895  0.000619591  0.00052072  0.000351929  0.000282879  0.000224033
+Variance explained         0.474806   0.16365    0.108928   0.0570235   0.0467058  0.0309456   0.0195066   0.0189185   0.0175575   0.0115146   0.0100942  0.00683182   0.00658157   0.00525572   0.00441704  0.00298526   0.00239954   0.00190038
+Cumulative variance        0.474806   0.638456   0.747384   0.804407    0.851113   0.882059    0.901565    0.920484    0.938041    0.949556    0.95965    0.966482     0.973063     0.978319     0.982736    0.985721     0.988121     0.990021
+Proportion explained       0.479592   0.165299   0.110026   0.0575982   0.0471765  0.0312575   0.0197032   0.0191092   0.0177345   0.0116307   0.010196   0.00690068   0.00664791   0.00530869   0.00446156  0.00301535   0.00242373   0.00191953
+Cumulative proportion      0.479592   0.644891   0.754917   0.812515    0.859692   0.890949    0.910652    0.929761    0.947496    0.959127    0.969323   0.976223     0.982871     0.98818      0.992641    0.995657     0.99808      1.0
+──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Now let’s show explained variance of each principal component.
plot(principalvars(fp), title="explained variance", label="Tangent PCA")
The next plot shows how projections on the first two pricipal components look like.
fig = plot(; title="coordinates per gesture of the first two principal components")
 for label_num in [0, 1]
     mask = hand_labels .== label_num
     cur_hand_logs = red_coords[:, mask]
@@ -100,4 +100,4 @@
     distance(Mshape, hands_projected[i], hands_projected[j]) for
     i in eachindex(hands_projected), j in eachindex(hands_projected)
 ]
-heatmap(hand_distances, aspect_ratio=:equal)

+heatmap(hand_distances, aspect_ratio=:equal)

diff --git a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-11-output-1.svg b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-11-output-1.svg index 1f0d22b41d..da1891b943 100644 --- a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-11-output-1.svg +++ b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-11-output-1.svg @@ -1,52 +1,52 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-12-output-1.svg b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-12-output-1.svg index 42e60e98f6..d87084905e 100644 --- a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-12-output-1.svg +++ b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-12-output-1.svg @@ -1,95 +1,95 @@ - + - + - + - + - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-13-output-1.svg b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-13-output-1.svg index bbe6e3de77..7548d45db4 100644 --- a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-13-output-1.svg +++ b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-13-output-1.svg @@ -1,43 +1,43 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + - + - + - + diff --git a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-5-output-1.svg b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-5-output-1.svg index be99b1781a..c8653e144f 100644 --- a/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-5-output-1.svg +++ b/previews/PR628/tutorials/hand-gestures_files/figure-commonmark/cell-5-output-1.svg @@ -1,76 +1,76 @@ - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR628/tutorials/integration.html b/previews/PR628/tutorials/integration.html index 6f4368ac5d..6ae29ec836 100644 --- a/previews/PR628/tutorials/integration.html +++ b/previews/PR628/tutorials/integration.html @@ -10,7 +10,7 @@ rand!(M, q) end return V * sum/N -end
simple_mc_integrate (generic function with 1 method)

We used the function manifold_volume to get the volume of the set over which integration is performed, as described in the linked Wikipedia article.

Distributions

We will now try to verify that volume density correction correctly changes probability density of an exponential-wrapped normal distribution. pdf_tangent_space represents probability density of a normally distributed random variable $X_T$ in the tangent space $T_p \mathcal{M}$. Its probability density (with respect to the Lebesgue measure of the tangent space) is $f_{X_T}\colon T_p \mathcal{M} \to \mathbb{R}$.

pdf_manifold refers to the probability density of the distribution $X_M$ from the tangent space $T_p \mathcal{M}$ wrapped using exponential map on the manifold. The formula for probability density with respect to pushforward measure of the Lebesgue measure in the tangent space reads

\[f_{X_M}(q) = \sum_{X \in T_p\mathcal{M}, \exp_p(X)=q} \frac{f_{X_T}(X)}{\theta_p(X)}\]

volume_density function calculates the correction $\theta_p(X)$.

function pdf_tangent_space(M::AbstractManifold, p)
+end
simple_mc_integrate (generic function with 1 method)

We used the function manifold_volume to get the volume of the set over which the integration is performed, as described in the linked Wikipedia article.

Distributions

We will now try to verify that volume density correction correctly changes probability density of an exponential-wrapped normal distribution. pdf_tangent_space represents probability density of a normally distributed random variable $X_T$ in the tangent space $T_p \mathcal{M}$. Its probability density (with respect to the Lebesgue measure of the tangent space) is $f_{X_T}\colon T_p \mathcal{M} \to \mathbb{R}$.

pdf_manifold refers to the probability density of the distribution $X_M$ from the tangent space $T_p \mathcal{M}$ wrapped using exponential map on the manifold. The formula for probability density with respect to pushforward measure of the Lebesgue measure in the tangent space reads

\[f_{X_M}(q) = \sum_{X \in T_p\mathcal{M}, \exp_p(X)=q} \frac{f_{X_T}(X)}{\theta_p(X)}\]

volume_density function calculates the correction $\theta_p(X)$.

function pdf_tangent_space(M::AbstractManifold, p)
     return pdf(MvNormal(zeros(manifold_dimension(M)), 0.2*I), p)
 end
 
@@ -26,7 +26,7 @@
     end
 end
 
-println(simple_mc_integrate(Sphere(2), pdf_manifold; N=1000000))
1.0007420406021186

The function simple_mc_integrate, defined in the previous section, is used to verify that the density integrates to 1 over the manifold.

Note that our pdf_manifold implements a simplified version of $f_{X_M}$ which assumes that the probability mass of pdf_tangent_space outside of (local) injectivity radius at $p$ is negligible. In such case there is only one non-zero summand in the formula for $f_{X_M}(q)$, namely $X=\log_p(q)$. Otherwise we would have to consider other vectors $Y\in T_p \mathcal{M}$ such that $\exp_p(Y) = q$ in that sum.

Remarkably, exponential-wrapped distributions possess three important qualities [2]:

  • Densities of $X_M$ are explicit. There is no normalization constant that needs to be computed like in truncated distributions.
  • Sampling from $X_M$ is easy. It suffices to get a sample from $X_T$ and pass it to the exponential map.
  • If mean of $X_T$ is 0, then there is a simple correspondence between moments of $X_M$ and $X_T$, for example $p$ is the mean of $X_M$.

Kernel density estimation

We can also make a Pelletier’s isotropic kernel density estimator. Given points $p_1, p_2, \dots, p_n$ on $d$-dimensional manifold $\mathcal M$ the density at point $q$ is defined as

\[f(q) = \frac{1}{n h^d} \sum_{i=1}^n \frac{1}{\theta_q(\log_q(p_i))}K\left( \frac{d(q, p_i)}{h} \right),\]

where $h$ is the bandwidth, a small positive number less than the injectivity radius of $\mathcal M$ and $K\colon\mathbb{R}\to\mathbb{R}$ is a kernel function. Note that Pelletier’s estimator can only use radially-symmetric kernels. The radially symmetric multivariate Epanechnikov kernel used in the example below is described in [3].

struct PelletierKDE{TM<:AbstractManifold,TPts<:AbstractVector}
+println(simple_mc_integrate(Sphere(2), pdf_manifold; N=1000000))
0.9988842504754084

The function simple_mc_integrate, defined in the previous section, is used to verify that the density integrates to 1 over the manifold.

Note that our pdf_manifold implements a simplified version of $f_{X_M}$ which assumes that the probability mass of pdf_tangent_space outside of (local) injectivity radius at $p$ is negligible. In such case there is only one non-zero summand in the formula for $f_{X_M}(q)$, namely $X=\log_p(q)$. Otherwise we would have to consider other vectors $Y\in T_p \mathcal{M}$ such that $\exp_p(Y) = q$ in that sum.

Remarkably, exponential-wrapped distributions possess three important qualities [2]:

  • Densities of $X_M$ are explicit. There is no normalization constant that needs to be computed like in truncated distributions.
  • Sampling from $X_M$ is easy. It suffices to get a sample from $X_T$ and pass it to the exponential map.
  • If mean of $X_T$ is 0, then there is a simple correspondence between moments of $X_M$ and $X_T$, for example $p$ is the mean of $X_M$.

Kernel density estimation

We can also make a Pelletier’s isotropic kernel density estimator. Given points $p_1, p_2, \dots, p_n$ on $d$-dimensional manifold $\mathcal M$ the density at point $q$ is defined as

\[f(q) = \frac{1}{n h^d} \sum_{i=1}^n \frac{1}{\theta_q(\log_q(p_i))}K\left( \frac{d(q, p_i)}{h} \right),\]

where $h$ is the bandwidth, a small positive number less than the injectivity radius of $\mathcal M$ and $K\colon\mathbb{R}\to\mathbb{R}$ is a kernel function. Note that Pelletier’s estimator can only use radially-symmetric kernels. The radially symmetric multivariate Epanechnikov kernel used in the example below is described in [3].

struct PelletierKDE{TM<:AbstractManifold,TPts<:AbstractVector}
     M::TM
     bandwidth::Float64
     pts::TPts
@@ -57,5 +57,5 @@
 pts = rand(M, 8)
 kde = PelletierKDE(M, 0.7, pts)
 println(simple_mc_integrate(Sphere(2), kde; N=1000000))
-println(kde(rand(M)))
0.9994072759685285
-0.0

Technical notes

This section contains a few technical notes that are relevant to the problem of integration on manifolds but can be freely skipped on the first read of the tutorial.

Conflicting statements about volume of a manifold

manifold_volume and volume_density are closely related to each other, though very few sources explore this connection, and some even claiming a certain level of arbitrariness in defining manifold_volume. Volume is sometimes considered arbitrary because Riemannian metrics on some spaces like the manifold of rotations are defined with arbitrary constants. However, once a constant is picked (and it must be picked before any useful computation can be performed), all geometric operations must follow in a consistent way: inner products, exponential and logarithmic maps, volume densities, etc. Manifolds.jl consistently picks such constants and provides a unified framework, though it sometimes results in picking a different constant than what is the most popular in some sub-communities.

Haar measures

On Lie groups the situation regarding integration is more complicated. Invariance under left or right group action is a desired property that leads one to consider Haar measures [4]. It is, however, unclear what are the practical benefits of considering Haar measures over the Lebesgue measure of the underlying manifold, which often turns out to be invariant anyway.

Integration in charts

Integration through charts is an approach currently not supported by Manifolds.jl. One has to define a suitable set of disjoint charts covering the entire manifold and use a method for multivariate Euclidean integration. Note that ranges of parameters have to be adjusted for each manifold and scaling based on the metric needs to be applied. See [5] for some considerations on symmetric spaces.

References

[1]

A. le Brigant and S. Puechmorel, “Approximation of Densities on Riemannian Manifolds,” Entropy, vol. 21, no. 1, Art. no. 1, Jan. 2019, doi: 10.3390/e21010043.

[2]

E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.

[3]

N. Langrené and X. Warin, “Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating,” Journal of Computational and Graphical Statistics, vol. 28, no. 3, pp. 596–608, Jul. 2019, doi: 10.1080/10618600.2018.1549052.

[4]

S. Tornier, “Haar Measures.” arXiv, Jun. 19, 2020. doi: 10.48550/arXiv.2006.10956.

[5]

L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1

+println(kde(rand(M)))
0.9988319869387484
+0.0

Technical notes

This section contains a few technical notes that are relevant to the problem of integration on manifolds but can be freely skipped on the first read of the tutorial.

Conflicting statements about volume of a manifold

manifold_volume and volume_density are closely related to each other, though very few sources explore this connection, and some even claiming a certain level of arbitrariness in defining manifold_volume. Volume is sometimes considered arbitrary because Riemannian metrics on some spaces like the manifold of rotations are defined with arbitrary constants. However, once a constant is picked (and it must be picked before any useful computation can be performed), all geometric operations must follow in a consistent way: inner products, exponential and logarithmic maps, volume densities, etc. Manifolds.jl consistently picks such constants and provides a unified framework, though it sometimes results in picking a different constant than what is the most popular in some sub-communities.

Haar measures

On Lie groups the situation regarding integration is more complicated. Invariance under left or right group action is a desired property that leads one to consider Haar measures [4]. It is, however, unclear what are the practical benefits of considering Haar measures over the Lebesgue measure of the underlying manifold, which often turns out to be invariant anyway.

Integration in charts

Integration through charts is an approach currently not supported by Manifolds.jl. One has to define a suitable set of disjoint charts covering the entire manifold and use a method for multivariate Euclidean integration. Note that ranges of parameters have to be adjusted for each manifold and scaling based on the metric needs to be applied. See [5] for some considerations on symmetric spaces.

References

[1]

A. le Brigant and S. Puechmorel, “Approximation of Densities on Riemannian Manifolds,” Entropy, vol. 21, no. 1, Art. no. 1, Jan. 2019, doi: 10.3390/e21010043.

[2]

E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on symmetric spaces.” arXiv, Oct. 09, 2022. doi: 10.48550/arXiv.2009.01983.

[3]

N. Langrené and X. Warin, “Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating,” Journal of Computational and Graphical Statistics, vol. 28, no. 3, pp. 596–608, Jul. 2019, doi: 10.1080/10618600.2018.1549052.

[4]

S. Tornier, “Haar Measures.” arXiv, Jun. 19, 2020. doi: 10.48550/arXiv.2006.10956.

[5]

L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003, doi: 10.1016/S0034-4877(03)80038-1

diff --git a/previews/PR628/tutorials/working-in-charts.html b/previews/PR628/tutorials/working-in-charts.html index de734114b3..0efc1b130c 100644 --- a/previews/PR628/tutorials/working-in-charts.html +++ b/previews/PR628/tutorials/working-in-charts.html @@ -76,4 +76,4 @@ # ax2, fig2 = torus_figure() # lines!(geo_r; linewidth=4.0, color=:green) -# fig2

fig-geodesic

An interactive Pluto version of this tutorial is available in file tutorials/working-in-charts.jl.

+# fig2

fig-geodesic

An interactive Pluto version of this tutorial is available in file tutorials/working-in-charts.jl.