diff --git a/previews/PR673/.documenter-siteinfo.json b/previews/PR673/.documenter-siteinfo.json index 5bf1ffe99c..aba0b96cfc 100644 --- a/previews/PR673/.documenter-siteinfo.json +++ b/previews/PR673/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-04T15:37:20","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-04T16:26:35","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/previews/PR673/features/atlases.html b/previews/PR673/features/atlases.html index c8e4c172f8..1b7e6ece32 100644 --- a/previews/PR673/features/atlases.html +++ b/previews/PR673/features/atlases.html @@ -1,11 +1,11 @@ -Atlases and charts · Manifolds.jl
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
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=MIRK4(),
     dt::Real=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/PR673/features/differentiation.html b/previews/PR673/features/differentiation.html index 1b667b1018..72a232dbc7 100644 --- a/previews/PR673/features/differentiation.html +++ b/previews/PR673/features/differentiation.html @@ -1,2 +1,2 @@ -Differentiation · Manifolds.jl
GitHub
+Differentiation · Manifolds.jl
GitHub
diff --git a/previews/PR673/features/distributions.html b/previews/PR673/features/distributions.html index 6b83cd3137..603c8e6aee 100644 --- a/previews/PR673/features/distributions.html +++ b/previews/PR673/features/distributions.html @@ -1,2 +1,2 @@ -Distributions · Manifolds.jl
GitHub

Distributions

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

Manifolds.FVectorDistribution — Type
FVectorDistribution{TSpace<:VectorSpaceFiber, 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, VectorSpaceFiber)

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::VectorSpaceFiber, 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
GitHub

Distributions

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

Manifolds.FVectorDistribution — Type
FVectorDistribution{TSpace<:VectorSpaceFiber, 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, VectorSpaceFiber)

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::VectorSpaceFiber, 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/PR673/features/group_actions.html b/previews/PR673/features/group_actions.html index 90799af530..0a0e84d1d1 100644 --- a/previews/PR673/features/group_actions.html +++ b/previews/PR673/features/group_actions.html @@ -1,10 +1,10 @@ -Group actions · Manifolds.jl
GitHub

Group actions

Group actions represent actions of a given group on a specified manifold. The following operations are available:

  • action_side: whether action acts from the LeftSide or RightSide (not to be confused with action direction).
  • apply: performs given action of an element of the group on an object of compatible type.
  • apply_diff: differential of apply with respect to the object it acts upon.
  • direction: tells whether a given action is LeftAction, RightAction.
  • inverse_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.
  • inverse_apply_diff: counterpart of apply_diff for inverse_apply.
  • optimal_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.

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(
+Group actions · Manifolds.jl
GitHub
Group actions
Group actions represent actions of a given group on a specified manifold. The following operations are available:
  • action_side: whether action acts from the LeftSide or RightSide (not to be confused with action direction).
  • apply: performs given action of an element of the group on an object of compatible type.
  • apply_diff: differential of apply with respect to the object it acts upon.
  • direction: tells whether a given action is LeftAction, RightAction.
  • inverse_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.
  • inverse_apply_diff: counterpart of apply_diff for inverse_apply.
  • optimal_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.
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{AD<:ActionDirection,AS<:GroupActionSide,G<:AbstractDecoratorManifold} <: AbstractGroupAction{AD}
Action of a group upon itself via left or right translation, either from left or right side. An element p of the group can act upon another another element by either:
  • left action from the left side: $L_p: q ↦ p \circ q$,
  • right action from the left side: $L'_p: q ↦ p^{-1} \circ q$,
  • right action from the right side: $R_p: q ↦ q \circ p$,
  • left action from the right side: $R'_p: q ↦ q \circ p^{-1}$.
Constructor
GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirectionAndSide = LeftForwardAction())
source
Manifolds.apply_diff_group — Method
apply_diff_group(A::GroupOperationAction, a, X, p)
Compute differential of GroupOperationAction A with respect to group element at tangent vector X:
\[(\mathrm{d}τ^p) : T_{a} \mathcal G → T_{τ_a p} \mathcal G\]
There are four cases:
  • left action from the left side: $L_a: p ↦ a \circ p$, where
\[(\mathrm{d}L_a) : T_{a} \mathcal G → T_{a \circ p} \mathcal G.\]
  • right action from the left side: $L'_a: p ↦ a^{-1} \circ p$, where
\[(\mathrm{d}L'_a) : T_{a} \mathcal G → T_{a^{-1} \circ p} \mathcal G.\]
  • right action from the right side: $R_a: p ↦ p \circ a$, where
\[(\mathrm{d}R_a) : T_{a} \mathcal G → T_{p \circ a} \mathcal G.\]
  • left action from the right side: $R'_a: p ↦ p \circ a^{-1}$, where
\[(\mathrm{d}R'_a) : T_{a} \mathcal G → T_{p \circ a^{-1}} \mathcal G.\]
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{AD<:ActionDirection,AS<:GroupActionSide,G<:AbstractDecoratorManifold} <: AbstractGroupAction{AD}
Action of a group upon itself via left or right translation, either from left or right side. An element p of the group can act upon another another element by either:
  • left action from the left side: $L_p: q ↦ p \circ q$,
  • right action from the left side: $L'_p: q ↦ p^{-1} \circ q$,
  • right action from the right side: $R_p: q ↦ q \circ p$,
  • left action from the right side: $R'_p: q ↦ q \circ p^{-1}$.
Constructor
GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirectionAndSide = LeftForwardAction())
source
Manifolds.apply_diff_group — Method
apply_diff_group(A::GroupOperationAction, a, X, p)
Compute differential of GroupOperationAction A with respect to group element at tangent vector X:
\[(\mathrm{d}τ^p) : T_{a} \mathcal G → T_{τ_a p} \mathcal G\]
There are four cases:
  • left action from the left side: $L_a: p ↦ a \circ p$, where
\[(\mathrm{d}L_a) : T_{a} \mathcal G → T_{a \circ p} \mathcal G.\]
  • right action from the left side: $L'_a: p ↦ a^{-1} \circ p$, where
\[(\mathrm{d}L'_a) : T_{a} \mathcal G → T_{a^{-1} \circ p} \mathcal G.\]
  • right action from the right side: $R_a: p ↦ p \circ a$, where
\[(\mathrm{d}R_a) : T_{a} \mathcal G → T_{p \circ a} \mathcal G.\]
  • left action from the right side: $R'_a: p ↦ p \circ a^{-1}$, where
\[(\mathrm{d}R'_a) : T_{a} \mathcal G → T_{p \circ a^{-1}} \mathcal G.\]
source
Rotation action
Manifolds.ColumnwiseMultiplicationAction — Type
ColumnwiseMultiplicationAction{
     TAD<:ActionDirection,
     TM<:AbstractManifold,
     TO<:GeneralUnitaryMultiplicationGroup,
@@ -12,11 +12,11 @@
     M::AbstractManifold,
     On::GeneralUnitaryMultiplicationGroup,
     AD::ActionDirection = LeftAction(),
-)
source
Manifolds.RotationAction — Type
RotationAction(
     M::AbstractManifold,
     SOn::SpecialOrthogonal,
     AD::ActionDirection = LeftAction(),
-)
Space of actions of the SpecialOrthogonal group $\mathrm{SO}(n)$ on a Euclidean-like manifold M of dimension n.
source
Manifolds.RowwiseMultiplicationAction — Type
RowwiseMultiplicationAction{
     TAD<:ActionDirection,
     TM<:AbstractManifold,
     TO<:GeneralUnitaryMultiplicationGroup,
@@ -24,14 +24,14 @@
     M::AbstractManifold,
     On::GeneralUnitaryMultiplicationGroup,
     AD::ActionDirection = LeftAction(),
-)
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 [SK16].
The formula reads
\[O^{*} = \begin{cases}
+)
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 [SK16].

The formula reads

\[O^{*} = \begin{cases} UV^T & \text{if } \operatorname{det}(p q^{\mathrm{T}}) \geq 0\\ 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.

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

Translation action

Manifolds.TranslationAction — Type
TranslationAction(
     M::AbstractManifold,
     Rn::TranslationGroup,
     AD::ActionDirection = LeftAction(),
-)

Space of actions of the TranslationGroup $\mathrm{T}(n)$ on a Euclidean-like manifold M.

The left and right actions are equivalent.

source

Rotation-translation action (special Euclidean)

Rotation-translation action (special Euclidean)

Manifolds.ColumnwiseSpecialEuclideanAction — Type
ColumnwiseSpecialEuclideanAction{
     TM<:AbstractManifold,
     TSE<:SpecialEuclidean,
     TAD<:ActionDirection,
@@ -39,23 +39,23 @@
     M::AbstractManifold,
     SE::SpecialEuclidean,
     AD::ActionDirection = LeftAction(),
-)
source
Manifolds.RotationTranslationAction — Type
RotationTranslationAction(
     M::AbstractManifold,
     SOn::SpecialEuclidean,
     AD::ActionDirection = LeftAction(),
-)

Space of actions of the SpecialEuclidean group $\mathrm{SE}(n)$ on a Euclidean-like manifold M of dimension n.

Left actions corresponds to active transformations while right actions can be identified with passive transformations for a particular choice of a basis.

source
Manifolds.apply — Method
apply(::RotationTranslationActionOnVector{LeftAction}, a::ArrayPartition, p)

Rotate point p by a.x[2] and translate it by a.x[1].

source
Manifolds.apply — Method
apply(::RotationTranslationActionOnVector{RightAction}, a::ArrayPartition, p)

Translate point p by -a.x[1] and rotate it by inverse of a.x[2].

source
Manifolds.apply_diff — Method
apply_diff(
+)

Space of actions of the SpecialEuclidean group $\mathrm{SE}(n)$ on a Euclidean-like manifold M of dimension n.

Left actions corresponds to active transformations while right actions can be identified with passive transformations for a particular choice of a basis.

source
Manifolds.apply — Method
apply(::RotationTranslationActionOnVector{LeftAction}, a::ArrayPartition, p)

Rotate point p by a.x[2] and translate it by a.x[1].

source
Manifolds.apply — Method
apply(::RotationTranslationActionOnVector{RightAction}, a::ArrayPartition, p)

Translate point p by -a.x[1] and rotate it by inverse of a.x[2].

source
Manifolds.inverse_apply — Method
inverse_apply(::RotationTranslationActionOnVector{LeftAction}, a::ArrayPartition, p)

Translate point p by -a.x[1] and rotate it by inverse of a.x[2].

source
Manifolds.inverse_apply — Method
inverse_apply(::RotationTranslationActionOnVector{RightAction}, a::ArrayPartition, p)

Rotate point p by a.x[2] and translate it by a.x[1].

source
+)

Compute differential of apply on left RotationTranslationActionOnVector, with respect to a at identity, i.e. left-multiply point p by X.x[2].

source
Manifolds.inverse_apply — Method
inverse_apply(::RotationTranslationActionOnVector{LeftAction}, a::ArrayPartition, p)

Translate point p by -a.x[1] and rotate it by inverse of a.x[2].

source
Manifolds.inverse_apply — Method
inverse_apply(::RotationTranslationActionOnVector{RightAction}, a::ArrayPartition, p)

Rotate point p by a.x[2] and translate it by a.x[1].

source
Manifolds.optimal_alignment — Method
optimal_alignment(A::LeftColumnwiseSpecialEuclideanAction, p, q)

Compute optimal alignment of p to q under the forward left ColumnwiseSpecialEuclideanAction. The algorithm, in sequence, computes optimal translation and optimal rotation.

source
diff --git a/previews/PR673/features/integration.html b/previews/PR673/features/integration.html index 67aecf5985..6998a271ea 100644 --- a/previews/PR673/features/integration.html +++ b/previews/PR673/features/integration.html @@ -1,2 +1,2 @@ -Integration · Manifolds.jl
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 [BST03].

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 [CLLD22].

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

source
+Integration · Manifolds.jl
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 [BST03].

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 [CLLD22].

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

source
diff --git a/previews/PR673/features/statistics.html b/previews/PR673/features/statistics.html index 87ae18a01a..1c7d443c3e 100644 --- a/previews/PR673/features/statistics.html +++ b/previews/PR673/features/statistics.html @@ -1,9 +1,9 @@ -Statistics · Manifolds.jl
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

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 [Wes79].

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 [Wes79].
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 [Pen06] 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 [Pen06] 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 [Kar77] and is also described in [PA12] as the exponential barycenter. The algorithm is further described in[ATV13].

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 [Kar77] and is also described in [PA12] as the exponential barycenter. The algorithm is further described in[ATV13].

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 [Bac14].

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 [Bac14].

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

[ATV13]
B. Afsari, R. Tron and R. Vidal. On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass. SIAM Journal on Control and Optimization 51, 2230–2260 (2013), arXiv:1201.0925.
[Bac14]
M. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014), arXiv:1210.2145, arXiv: 1210.2145.
[CV15]
R. Chakraborty and B. C. Vemuri. Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. In: 2015 IEEE International Conference on Computer Vision (ICCV) (2015).
[CV19]
R. Chakraborty and B. C. Vemuri. Statistics on the Stiefel manifold: Theory and applications. The Annals of Statistics 47 (2019), arXiv:1708.00045.
[CHSV16]
G. Cheng, J. Ho, H. Salehian and B. C. Vemuri. Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. In: Riemannian Computing in Computer Vision (Springer, Cham, 2016); pp. 21–43.
[FVJ08]
P. T. Fletcher, S. Venkatasubramanian and S. Joshi. Robust statistics on Riemannian manifolds via the geometric median. In: 2008 IEEE Conference on Computer Vision and Pattern Recognition (2008).
[HCSV13]
J. Ho, G. Cheng, H. Salehian and B. C. Vemuri. Recursive Karcher expectation estimators and geometric law of large numbers. In: 16th International Conference on Artificial Intelligence and Statistics (2013).
[Kar77]
H. Karcher. Riemannian center of mass and mollifier smoothing. Communications on Pure and Applied Mathematics 30, 509–541 (1977).
[Pen06]
X. Pennec. Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements. Journal of Mathematical Imaging and Vision 25, 127–154 (2006).
[PA12]
X. Pennec and V. Arsigny. Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Matrix Information Geometry (Springer, Berlin, Heidelberg, 2012); pp. 123–166, arXiv:00699361.
[SCaO+15]
H. Salehian, R. Chakraborty, E. and Ofori, D. Vaillancourt and B. C. Vemuri. An efficient recursive estimator of the Fréchet mean on hypersphere with applications to Medical Image Analysis. In: 5th MICCAI workshop on Mathematical Foundations of Computational Anatomy (Oct 2015).
[Wes79]
D. H. West. Updating mean and variance estimates. Communications of the ACM 22, 532–535 (1979).
+) -> (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

[ATV13]
B. Afsari, R. Tron and R. Vidal. On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass. SIAM Journal on Control and Optimization 51, 2230–2260 (2013), arXiv:1201.0925.
[Bac14]
M. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014), arXiv:1210.2145, arXiv: 1210.2145.
[CV15]
R. Chakraborty and B. C. Vemuri. Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. In: 2015 IEEE International Conference on Computer Vision (ICCV) (2015).
[CV19]
R. Chakraborty and B. C. Vemuri. Statistics on the Stiefel manifold: Theory and applications. The Annals of Statistics 47 (2019), arXiv:1708.00045.
[CHSV16]
G. Cheng, J. Ho, H. Salehian and B. C. Vemuri. Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. In: Riemannian Computing in Computer Vision (Springer, Cham, 2016); pp. 21–43.
[FVJ08]
P. T. Fletcher, S. Venkatasubramanian and S. Joshi. Robust statistics on Riemannian manifolds via the geometric median. In: 2008 IEEE Conference on Computer Vision and Pattern Recognition (2008).
[HCSV13]
J. Ho, G. Cheng, H. Salehian and B. C. Vemuri. Recursive Karcher expectation estimators and geometric law of large numbers. In: 16th International Conference on Artificial Intelligence and Statistics (2013).
[Kar77]
H. Karcher. Riemannian center of mass and mollifier smoothing. Communications on Pure and Applied Mathematics 30, 509–541 (1977).
[Pen06]
X. Pennec. Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements. Journal of Mathematical Imaging and Vision 25, 127–154 (2006).
[PA12]
X. Pennec and V. Arsigny. Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Matrix Information Geometry (Springer, Berlin, Heidelberg, 2012); pp. 123–166, arXiv:00699361.
[SCaO+15]
H. Salehian, R. Chakraborty, E. and Ofori, D. Vaillancourt and B. C. Vemuri. An efficient recursive estimator of the Fréchet mean on hypersphere with applications to Medical Image Analysis. In: 5th MICCAI workshop on Mathematical Foundations of Computational Anatomy (Oct 2015).
[Wes79]
D. H. West. Updating mean and variance estimates. Communications of the ACM 22, 532–535 (1979).
diff --git a/previews/PR673/features/testing.html b/previews/PR673/features/testing.html index b39291e758..3e1300525b 100644 --- a/previews/PR673/features/testing.html +++ b/previews/PR673/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 = [],
@@ -25,8 +25,8 @@
     test_adjoint_action=false,
     test_inv_diff=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/PR673/features/utilities.html b/previews/PR673/features/utilities.html index 3665896b88..ded8eec2be 100644 --- a/previews/PR673/features/utilities.html +++ b/previews/PR673/features/utilities.html @@ -1,4 +1,4 @@ Utilities · Manifolds.jl
GitHub

Utilities

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::TangentSpace; kwargs...)
-X ∈ TangentSpace(M, p)

Check whether X is a tangent vector from (in) the tangent space $T_p\mathcal M$, i.e. the TangentSpace 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

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.

+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::TangentSpace; kwargs...)
+X ∈ TangentSpace(M, p)

Check whether X is a tangent vector from (in) the tangent space $T_p\mathcal M$, i.e. the TangentSpace 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

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/PR673/index.html b/previews/PR673/index.html index 628a21a251..ad952a7aee 100644 --- a/previews/PR673/index.html +++ b/previews/PR673/index.html @@ -1,5 +1,5 @@ -Home · Manifolds.jl
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
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/PR673/manifolds/centeredmatrices.html b/previews/PR673/manifolds/centeredmatrices.html index 77fbe9793f..7906415629 100644 --- a/previews/PR673/manifolds/centeredmatrices.html +++ b/previews/PR673/manifolds/centeredmatrices.html @@ -1,11 +1,11 @@ -Centered matrices · Manifolds.jl
GitHub

Centered matrices

Manifolds.CenteredMatrices — Type
CenteredMatrices{T,𝔽} <: 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=ℝ]; parameter::Symbol=:type)

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

parameter: whether a type parameter should be used to store m and n. By default size is stored in type. Value can either be :field or :type.

source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::CenteredMatrices, p, X, V)
-Weingarten!(M::CenteredMatrices, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the CenteredMatrices M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

source
ManifoldsBase.check_point — Method
check_point(M::CenteredMatrices, 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, 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

GitHub

Centered matrices

Manifolds.CenteredMatrices — Type
CenteredMatrices{T,𝔽} <: 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=ℝ]; parameter::Symbol=:type)

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

parameter: whether a type parameter should be used to store m and n. By default size is stored in type. Value can either be :field or :type.

source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::CenteredMatrices, p, X, V)
+Weingarten!(M::CenteredMatrices, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the CenteredMatrices M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

source
ManifoldsBase.check_point — Method
check_point(M::CenteredMatrices, 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, 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/PR673/manifolds/choleskyspace.html b/previews/PR673/manifolds/choleskyspace.html index 428d9c8630..22398d0cca 100644 --- a/previews/PR673/manifolds/choleskyspace.html +++ b/previews/PR673/manifolds/choleskyspace.html @@ -1,6 +1,6 @@ -Cholesky space · Manifolds.jl
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{T} <: 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 [Lin19].

Constructor

CholeskySpace(n; parameter::Symbol=:type)

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

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{T} <: 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 [Lin19].

Constructor

CholeskySpace(n; parameter::Symbol=:type)

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

+}\]

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

diff --git a/previews/PR673/manifolds/circle.html b/previews/PR673/manifolds/circle.html index 472ef078fa..5c0154b1ee 100644 --- a/previews/PR673/manifolds/circle.html +++ b/previews/PR673/manifolds/circle.html @@ -1,3 +1,3 @@ -Circle · Manifolds.jl
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
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/PR673/manifolds/connection.html b/previews/PR673/manifolds/connection.html index e8b5fa896b..e524db3724 100644 --- a/previews/PR673/manifolds/connection.html +++ b/previews/PR673/manifolds/connection.html @@ -1,20 +1,20 @@ -Connection manifold · Manifolds.jl
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
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::ConnectionManifold,
     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/PR673/manifolds/elliptope.html b/previews/PR673/manifolds/elliptope.html index 16e7879719..95d09757bc 100644 --- a/previews/PR673/manifolds/elliptope.html +++ b/previews/PR673/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[JBAS10].

Constructor

Elliptope(n::Int, k::Int; parameter::Symbol=:type)

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

parameter: whether a type parameter should be used to store n and k. By default size is stored in type. Value can either be :field or :type.

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[JBAS10].

Constructor

Elliptope(n::Int, k::Int; parameter::Symbol=:type)

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

parameter: whether a type parameter should be used to store n and k. By default size is stored in type. Value can either be :field or :type.

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/PR673/manifolds/essentialmanifold.html b/previews/PR673/manifolds/essentialmanifold.html index 610098a934..bd464baf11 100644 --- a/previews/PR673/manifolds/essentialmanifold.html +++ b/previews/PR673/manifolds/essentialmanifold.html @@ -1,2 +1,2 @@ -Essential manifold · Manifolds.jl
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 [TD17].

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$[TD17].

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 [TD17].

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)$ [TD17].

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 [TD17].

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 [TD17].

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 [TD17].

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$ [TD17].

source

Literature

+Essential manifold · Manifolds.jl
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 [TD17].

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$[TD17].

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 [TD17].

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)$ [TD17].

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 [TD17].

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 [TD17].

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 [TD17].

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$ [TD17].

source

Literature

diff --git a/previews/PR673/manifolds/euclidean.html b/previews/PR673/manifolds/euclidean.html index d26401cb40..4fd045362f 100644 --- a/previews/PR673/manifolds/euclidean.html +++ b/previews/PR673/manifolds/euclidean.html @@ -1,4 +1,4 @@ Euclidean · Manifolds.jl
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,𝔽} <: AbstractManifold{𝔽}

Euclidean vector space.

Constructor

Euclidean(n)

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

Euclidean(n₁,n₂,...,nᵢ; field=ℝ, parameter::Symbol = :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 $𝔽$.

parameter: whether a type parameter should be used to store n. By default size is stored in type. Value can either be :field or :type.

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.Weingarten — Method
Y = Weingarten(M::Euclidean, p, X, V)
-Weingarten!(M::Euclidean, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Euclidean M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

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 tensor 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 $𝔽$.

parameter: whether a type parameter should be used to store n. By default size is stored in type. Value can either be :field or :type.

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.Weingarten — Method
Y = Weingarten(M::Euclidean, p, X, V)
+Weingarten!(M::Euclidean, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Euclidean M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

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 tensor 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/PR673/manifolds/fiber_bundle.html b/previews/PR673/manifolds/fiber_bundle.html index 08ea5454d0..8130354201 100644 --- a/previews/PR673/manifolds/fiber_bundle.html +++ b/previews/PR673/manifolds/fiber_bundle.html @@ -1,11 +1,11 @@ -Fiber bundle · Manifolds.jl
GitHub

Fiber bundles

Fiber 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$. For each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$ is called a fiber $F$. Bundle projection can be performed using function bundle_projection.

Manifolds.jl primarily deals with the case of trivial bundles, where $E$ can be identified with a product $M \times F$.

Vector bundles is a special case of a fiber bundle. Other examples include unit tangent bundle. Note that in general fiber bundles don't have a canonical Riemannian structure but can at least be equipped with an Ehresmann connection, providing notions of parallel transport and curvature.

Documentation

Manifolds.FiberBundle — Type
FiberBundle{𝔽,TVS<:FiberType,TM<:AbstractManifold{𝔽},TVT<:FiberBundleProductVectorTransport} <: AbstractManifold{𝔽}

Fiber bundle on a AbstractManifold M of type FiberType. Examples include vector bundles, principal bundles or unit tangent bundles, see also 📖 Fiber Bundle.

Fields

  • manifold – the AbstractManifold manifold the Fiber bundle is defined on,
  • type – representing the type of fiber we use.

Constructor

FiberBundle(M::AbstractManifold, type::FiberType)
source
Manifolds.FiberBundleInverseProductRetraction — Type
struct FiberBundleInverseProductRetraction <: 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 FiberBundleProductRetraction.

source
Manifolds.FiberBundleProductRetraction — Type
struct FiberBundleProductRetraction <: 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

math \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 FiberBundleInverseProductRetraction.

source
Manifolds.FiberBundleProductVectorTransport — Type
FiberBundleProductVectorTransport{
+Fiber bundle · Manifolds.jl
GitHub
Fiber bundles
Fiber 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$. For each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$ is called a fiber $F$. Bundle projection can be performed using function bundle_projection.
Manifolds.jl primarily deals with the case of trivial bundles, where $E$ can be identified with a product $M \times F$.
Vector bundles is a special case of a fiber bundle. Other examples include unit tangent bundle. Note that in general fiber bundles don't have a canonical Riemannian structure but can at least be equipped with an Ehresmann connection, providing notions of parallel transport and curvature.
Documentation
Manifolds.FiberBundle — Type
FiberBundle{𝔽,TVS<:FiberType,TM<:AbstractManifold{𝔽},TVT<:FiberBundleProductVectorTransport} <: AbstractManifold{𝔽}
Fiber bundle on a AbstractManifold M of type FiberType. Examples include vector bundles, principal bundles or unit tangent bundles, see also 📖 Fiber Bundle.
Fields
  • manifold – the AbstractManifold              manifold the Fiber bundle is defined on,
  • type     – representing the type of fiber we use.
Constructor
FiberBundle(M::AbstractManifold, type::FiberType)
source
Manifolds.FiberBundleInverseProductRetraction — Type
struct FiberBundleInverseProductRetraction <: 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 FiberBundleProductRetraction.
source
Manifolds.FiberBundleProductRetraction — Type
struct FiberBundleProductRetraction <: 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
math \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 FiberBundleInverseProductRetraction.
source
Manifolds.FiberBundleProductVectorTransport — Type
FiberBundleProductVectorTransport{
     TMP<:AbstractVectorTransportMethod,
     TMV<:AbstractVectorTransportMethod,
 } <: AbstractVectorTransportMethod
Vector transport type on FiberBundle.
Fields
  • method_horizonal – vector transport method of the horizontal part (related to manifold M)
  • method_vertical – vector transport method of the vertical part (related to fibers).
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
FiberBundleProductVectorTransport(
     M::AbstractManifold=DefaultManifold();
     vector_transport_method_horizontal::AbstractVectorTransportMethod = default_vector_transport_method(M),
     vector_transport_method_vertical::AbstractVectorTransportMethod = default_vector_transport_method(M),
-)
Construct the FiberBundleProductVectorTransport using the default_vector_transport_method, which uses ParallelTransport if no manifold is provided.
source
Base.getindex — Method
getindex(p::ArrayPartition, M::FiberBundle, s::Symbol)
-p[M::FiberBundle, s]
Access the element(s) at index s of a point p on a FiberBundle M by using the symbols :point and :vector or :fiber for the base and vector or fiber component, respectively.
source
Base.setindex! — Method
setindex!(p::ArrayPartition, val, M::FiberBundle, s::Symbol)
-p[M::VectorBundle, s] = val
Set the element(s) at index s of a point p on a FiberBundle M to val by using the symbols :point and :fiber or :vector for the base and fiber or vector component, respectively.
Note
The content of element of p is replaced, not the element itself.
source
Manifolds.bundle_projection — Method
bundle_projection(B::FiberBundle, p)
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.bundle_transport_tangent_direction — Function
bundle_transport_tangent_direction(B::FiberBundle, p, pf, X, d)
Compute parallel transport of vertical vector X according to Ehresmann connection on FiberBundle B, in direction $d\in T_p \mathcal M$. $X$ is an element of the vertical bundle $VF\mathcal M$ at pf from tangent to fiber $\pi^{-1}({p})$, $p\in \mathcal M$.
source
Manifolds.bundle_transport_tangent_to — Function
bundle_transport_tangent_to(B::FiberBundle, p, pf, X, q)
Compute parallel transport of vertical vector X according to Ehresmann connection on FiberBundle B, to point $q\in \mathcal M$. $X$ is an element of the vertical bundle $VF\mathcal M$ at pf from tangent to fiber $\pi^{-1}({p})$, $p\in \mathcal M$.
source
Manifolds.bundle_transport_to — Method
bundle_transport_to(B::FiberBundle, p, X, q)
Given a fiber bundle $B=F \mathcal M$, points $p, q\in\mathcal M$, an element $X$ of the fiber over $p$, transport $X$ to fiber over $q$.
Exact meaning of the operation depends on the fiber bundle, or may even be undefined. Some fiber bundles may declare a default local section around each point crossing X, represented by this function.
source
ManifoldsBase.zero_vector — Method
zero_vector(B::FiberBundle, p)
Zero tangent vector at point p from the fiber 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

+)

Construct the FiberBundleProductVectorTransport using the default_vector_transport_method, which uses ParallelTransport if no manifold is provided.

source
Base.getindex — Method
getindex(p::ArrayPartition, M::FiberBundle, s::Symbol)
+p[M::FiberBundle, s]

Access the element(s) at index s of a point p on a FiberBundle M by using the symbols :point and :vector or :fiber for the base and vector or fiber component, respectively.

source
Base.setindex! — Method
setindex!(p::ArrayPartition, val, M::FiberBundle, s::Symbol)
+p[M::VectorBundle, s] = val

Set the element(s) at index s of a point p on a FiberBundle M to val by using the symbols :point and :fiber or :vector for the base and fiber or vector component, respectively.

Note

The content of element of p is replaced, not the element itself.

source
Manifolds.bundle_projection — Method
bundle_projection(B::FiberBundle, p)

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.bundle_transport_tangent_direction — Function
bundle_transport_tangent_direction(B::FiberBundle, p, pf, X, d)

Compute parallel transport of vertical vector X according to Ehresmann connection on FiberBundle B, in direction $d\in T_p \mathcal M$. $X$ is an element of the vertical bundle $VF\mathcal M$ at pf from tangent to fiber $\pi^{-1}({p})$, $p\in \mathcal M$.

source
Manifolds.bundle_transport_tangent_to — Function
bundle_transport_tangent_to(B::FiberBundle, p, pf, X, q)

Compute parallel transport of vertical vector X according to Ehresmann connection on FiberBundle B, to point $q\in \mathcal M$. $X$ is an element of the vertical bundle $VF\mathcal M$ at pf from tangent to fiber $\pi^{-1}({p})$, $p\in \mathcal M$.

source
Manifolds.bundle_transport_to — Method
bundle_transport_to(B::FiberBundle, p, X, q)

Given a fiber bundle $B=F \mathcal M$, points $p, q\in\mathcal M$, an element $X$ of the fiber over $p$, transport $X$ to fiber over $q$.

Exact meaning of the operation depends on the fiber bundle, or may even be undefined. Some fiber bundles may declare a default local section around each point crossing X, represented by this function.

source
ManifoldsBase.zero_vector — Method
zero_vector(B::FiberBundle, p)

Zero tangent vector at point p from the fiber 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
diff --git a/previews/PR673/manifolds/fixedrankmatrices.html b/previews/PR673/manifolds/fixedrankmatrices.html index 55f793cc1a..2a9cdc2328 100644 --- a/previews/PR673/manifolds/fixedrankmatrices.html +++ b/previews/PR673/manifolds/fixedrankmatrices.html @@ -6,5 +6,5 @@ \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 [Van13].

Constructor

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

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

source
Manifolds.OrthographicInverseRetraction — Type
OrthographicInverseRetraction <: AbstractInverseRetractionMethod

Retractions that are related to orthographic projections, which was first used in [AM12].

source
Manifolds.OrthographicRetraction — Type
OrthographicRetraction <: AbstractRetractionMethod

Retractions that are related to orthographic projections, which was first used in [AM12].

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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::FixedRankMatrices, p, G, H, X)
-riemannian_Hessian!(M::FixedRankMatrices, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

The Riemannian Hessian can be computed as stated in Remark 4.1 [Ngu23] or Section 2.3 [Van13], that B. Vandereycken adopted for Manopt (Matlab).

source
Manifolds.inverse_retract_orthographic! — Method
inverse_retract_orthographic!(M::AbstractManifold, X, p, q)

Compute the in-place variant of the OrthographicInverseRetraction.

source
Manifolds.retract_orthographic! — Method
retract_orthographic!(M::AbstractManifold, q, p, X, t::Number)

Compute the in-place variant of the OrthographicRetraction.

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

Check whether the matrix or SVDMPoint x ids a valid point on the FixedRankMatrices 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, 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 [HU17].

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.inverse_retract — Method
inverse_retract(M, p, q, ::OrthographicInverseRetraction)

Compute the orthographic inverse retraction FixedRankMatrices M by computing

\[ X = P_{T_{p}M}(q - p) = qVV^\mathrm{T} + UU^{\mathrm{T}}q - UU^{\mathrm{T}}qVV^{\mathrm{T}} - p,\]

where $p$ is a SVDMPoint(U,S,Vt) and $P_{T_{p}M}$ is the projection onto the tangent space at $p$.

For more details, see [AO14].

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)

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)

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::FixedRankMatrices, p, X, ::OrthographicRetraction)

Compute the OrthographicRetraction on the FixedRankMatrices M by finding the nearest point to $p + X$ in

\[ p + X + N_{p}\mathcal M \cap \mathcal M\]

where $N_{p}\mathcal M$ is the Normal Space of $T_{p}\mathcal M$.

If $X$ is sufficiently small, then the nearest such point is unique and can be expressed by

\[ q = (U(S + M) + U_{p})(S + M)^{-1}((S + M)V^{\mathrm{T}} + V^{\mathrm{T}}_{p}),\]

where $p$ is a SVDMPoint(U,S,Vt) and $X$ is an UMVTVector(Up,M,Vtp).

For more details, see [AO14].

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

[AM12]
P.-A. Absil and J. Malick. Projection-like Retractions on Matrix Manifolds. SIAM Journal on Optimization 22, 135–158 (2012).
[AO14]
P.-A. Absil and I. V. Oseledets. Low-rank retractions: a survey and new results. Computational Optimization and Applications 62, 5–29 (2014).
[HU17]
S. Hosseini and A. Uschmajew. A Riemannian Gradient Sampling Algorithm for Nonsmooth Optimization on Manifolds. SIAM J. Optim. 27, 173–189 (2017).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Van13]
B. Vandereycken. Low-rank matrix completion by Riemannian optimization. SIAM Journal on Optimization 23, 1214–1236 (2013).
+\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 [Van13].

Constructor

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

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

source
Manifolds.OrthographicInverseRetraction — Type
OrthographicInverseRetraction <: AbstractInverseRetractionMethod

Retractions that are related to orthographic projections, which was first used in [AM12].

source
Manifolds.OrthographicRetraction — Type
OrthographicRetraction <: AbstractRetractionMethod

Retractions that are related to orthographic projections, which was first used in [AM12].

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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::FixedRankMatrices, p, G, H, X)
+riemannian_Hessian!(M::FixedRankMatrices, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

The Riemannian Hessian can be computed as stated in Remark 4.1 [Ngu23] or Section 2.3 [Van13], that B. Vandereycken adopted for Manopt (Matlab).

source
Manifolds.inverse_retract_orthographic! — Method
inverse_retract_orthographic!(M::AbstractManifold, X, p, q)

Compute the in-place variant of the OrthographicInverseRetraction.

source
Manifolds.retract_orthographic! — Method
retract_orthographic!(M::AbstractManifold, q, p, X, t::Number)

Compute the in-place variant of the OrthographicRetraction.

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

Check whether the matrix or SVDMPoint x ids a valid point on the FixedRankMatrices 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, 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 [HU17].

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.inverse_retract — Method
inverse_retract(M, p, q, ::OrthographicInverseRetraction)

Compute the orthographic inverse retraction FixedRankMatrices M by computing

\[ X = P_{T_{p}M}(q - p) = qVV^\mathrm{T} + UU^{\mathrm{T}}q - UU^{\mathrm{T}}qVV^{\mathrm{T}} - p,\]

where $p$ is a SVDMPoint(U,S,Vt) and $P_{T_{p}M}$ is the projection onto the tangent space at $p$.

For more details, see [AO14].

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)

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)

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::FixedRankMatrices, p, X, ::OrthographicRetraction)

Compute the OrthographicRetraction on the FixedRankMatrices M by finding the nearest point to $p + X$ in

\[ p + X + N_{p}\mathcal M \cap \mathcal M\]

where $N_{p}\mathcal M$ is the Normal Space of $T_{p}\mathcal M$.

If $X$ is sufficiently small, then the nearest such point is unique and can be expressed by

\[ q = (U(S + M) + U_{p})(S + M)^{-1}((S + M)V^{\mathrm{T}} + V^{\mathrm{T}}_{p}),\]

where $p$ is a SVDMPoint(U,S,Vt) and $X$ is an UMVTVector(Up,M,Vtp).

For more details, see [AO14].

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

[AM12]
P.-A. Absil and J. Malick. Projection-like Retractions on Matrix Manifolds. SIAM Journal on Optimization 22, 135–158 (2012).
[AO14]
P.-A. Absil and I. V. Oseledets. Low-rank retractions: a survey and new results. Computational Optimization and Applications 62, 5–29 (2014).
[HU17]
S. Hosseini and A. Uschmajew. A Riemannian Gradient Sampling Algorithm for Nonsmooth Optimization on Manifolds. SIAM J. Optim. 27, 173–189 (2017).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Van13]
B. Vandereycken. Low-rank matrix completion by Riemannian optimization. SIAM Journal on Optimization 23, 1214–1236 (2013).
diff --git a/previews/PR673/manifolds/flag.html b/previews/PR673/manifolds/flag.html index b9218cbf68..f7816d669f 100644 --- a/previews/PR673/manifolds/flag.html +++ b/previews/PR673/manifolds/flag.html @@ -1,19 +1,19 @@ -Flag · Manifolds.jl
GitHub

Flag manifold

Manifolds.Flag — Type
Flag{T,d} <: AbstractDecoratorManifold{ℝ}

Flag manifold of $d$ subspaces of $ℝ^N$ [YWL21]. 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; parameter::Symbol=:type)

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

parameter: whether a type parameter should be used to store n. By default size is stored in type. Value can either be :field or :type.

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

GitHub

Flag manifold

Manifolds.Flag — Type
Flag{T,d} <: AbstractDecoratorManifold{ℝ}

Flag manifold of $d$ subspaces of $ℝ^N$ [YWL21]. 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; parameter::Symbol=:type)

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

parameter: whether a type parameter should be used to store n. By default size is stored in type. Value can either be :field or :type.

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 [YWL21]:

\[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 [YWL21]:

\[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/PR673/manifolds/generalizedgrassmann.html b/previews/PR673/manifolds/generalizedgrassmann.html index feeeb48161..0672445661 100644 --- a/previews/PR673/manifolds/generalizedgrassmann.html +++ b/previews/PR673/manifolds/generalizedgrassmann.html @@ -1,11 +1,11 @@ Generalized Grassmann · Manifolds.jl
GitHub

Generalized Grassmann

Manifolds.GeneralizedGrassmann — Type
GeneralizedGrassmann{T,𝔽,TB<:AbstractMatrix} <: 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, 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, 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, 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, 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/PR673/manifolds/generalizedstiefel.html b/previews/PR673/manifolds/generalizedstiefel.html index 1894bbbe39..193e252d2d 100644 --- a/previews/PR673/manifolds/generalizedstiefel.html +++ b/previews/PR673/manifolds/generalizedstiefel.html @@ -1,8 +1,8 @@ -Generalized Stiefel · Manifolds.jl
GitHub

Generalized Stiefel

Manifolds.GeneralizedStiefel — Type
GeneralizedStiefel{T,𝔽,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

GitHub

Generalized Stiefel

Manifolds.GeneralizedStiefel — Type
GeneralizedStiefel{T,𝔽,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/PR673/manifolds/generalunitary.html b/previews/PR673/manifolds/generalunitary.html index 8226084863..de635d9791 100644 --- a/previews/PR673/manifolds/generalunitary.html +++ b/previews/PR673/manifolds/generalunitary.html @@ -1,44 +1,44 @@ -Orthogonal and Unitary Matrices · Manifolds.jl
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

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
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::UnitaryMatrices, p, G, H, X)

The Riemannian Hessian can be computed by adopting Eq. (5.6) [Ngu23], so very similar to the complex Stiefel manifold. The only difference is, that here the tangent vectors are stored in the Lie algebra, i.e. the update direction is actually $pX$ instead of just $X$ (in Stiefel). and that means the inverse has to be appliead to the (Euclidean) Hessian to map it into the Lie algebra.

source
ManifoldsBase.Weingarten — Method
Weingarten(M::UnitaryMatrices, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Stiefel M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

The formula is due to [AMT13] given by

\[\mathcal W_p(X,V) = -\frac{1}{2}p\bigl(V^{\mathrm{H}}X - X^\mathrm{H}V\bigr)\]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::UnitaryMatrices{<:Any,ℍ})

Return the dimension of the manifold unitary matrices.

\[\dim_{\mathrm{U}(n, ℍ)} = n(2n+1).\]

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{T,𝔽,S<:AbstractMatrixType} <: AbstractDecoratorManifold

A common parametric type for matrices with a unitary property of size $n×n$ over the field $𝔽$ 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
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::UnitaryMatrices, p, G, H, X)

The Riemannian Hessian can be computed by adopting Eq. (5.6) [Ngu23], so very similar to the complex Stiefel manifold. The only difference is, that here the tangent vectors are stored in the Lie algebra, i.e. the update direction is actually $pX$ instead of just $X$ (in Stiefel). and that means the inverse has to be appliead to the (Euclidean) Hessian to map it into the Lie algebra.

source
ManifoldsBase.Weingarten — Method
Weingarten(M::UnitaryMatrices, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Stiefel M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

The formula is due to [AMT13] given by

\[\mathcal W_p(X,V) = -\frac{1}{2}p\bigl(V^{\mathrm{H}}X - X^\mathrm{H}V\bigr)\]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(M::UnitaryMatrices{<:Any,ℍ})

Return the dimension of the manifold unitary matrices.

\[\dim_{\mathrm{U}(n, ℍ)} = n(2n+1).\]

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{T,𝔽,S<:AbstractMatrixType} <: AbstractDecoratorManifold

A common parametric type for matrices with a unitary property of size $n×n$ over the field $𝔽$ 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 are specialized implementations.

The algorithm used is a more numerically stable form of those proposed in [GX02] and [AR13].

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 are specialized implementations.

The algorithm used is a more numerically stable form of those proposed in [GX02] and [AR13].

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{<:Any,ℂ,DeterminantOneMatrices})

Volume of the manifold of complex general unitary matrices of determinant one. The formula reads [BST03]

\[\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{<:Any,ℝ,AbsoluteDeterminantOneMatrices})

Volume of the manifold of real orthogonal matrices of absolute determinant one. The formula reads [BST03]:

\[\begin{cases} +\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{<:Any,ℂ,DeterminantOneMatrices})

Volume of the manifold of complex general unitary matrices of determinant one. The formula reads [BST03]

\[\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{<:Any,ℝ,AbsoluteDeterminantOneMatrices})

Volume of the manifold of real orthogonal matrices of absolute determinant one. The formula reads [BST03]:

\[\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{<:Any,ℝ,DeterminantOneMatrices})

Volume of the manifold of real orthogonal matrices of determinant one. The formula reads [BST03]:

\[\begin{cases} +\end{cases}\]

source
Manifolds.manifold_volume — Method
manifold_volume(::GeneralUnitaryMatrices{<:Any,ℝ,DeterminantOneMatrices})

Volume of the manifold of real orthogonal matrices of determinant one. The formula reads [BST03]:

\[\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{<:Any,ℂ,AbsoluteDeterminantOneMatrices})

Volume of the manifold of complex general unitary matrices of absolute determinant one. The formula reads [BST03]

\[\sqrt{n 2^{n+1}} π^{n(n+1)/2} \prod_{k=1}^{n-1}\frac{1}{k!}\]

source
Manifolds.volume_density — Method
volume_density(M::GeneralUnitaryMatrices{<:Any,ℝ}, p, X)

Compute 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 [CLLD22]. See also Theorem 4.1 in [FdHDF19], (note that it uses a different convention).

source
Manifolds.volume_density — Method
volume_density(M::GeneralUnitaryMatrices{TypeParameter{Tuple{2}},ℝ}, p, X)

Volume density on O(2)/SO(2) is equal to 1.

source
Manifolds.volume_density — Method
volume_density(M::GeneralUnitaryMatrices{TypeParameter{Tuple{3}},ℝ}, p, X)

Compute the volume density on O(3)/SO(3). The formula reads [FdHDF19]

\[\frac{1-1\cos(\sqrt{2}\lVert X \rVert)}{\lVert X \rVert^2}.\]

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{<:Any,ℂ,AbsoluteDeterminantOneMatrices})

Volume of the manifold of complex general unitary matrices of absolute determinant one. The formula reads [BST03]

\[\sqrt{n 2^{n+1}} π^{n(n+1)/2} \prod_{k=1}^{n-1}\frac{1}{k!}\]

source
Manifolds.volume_density — Method
volume_density(M::GeneralUnitaryMatrices{<:Any,ℝ}, p, X)

Compute 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 [CLLD22]. See also Theorem 4.1 in [FdHDF19], (note that it uses a different convention).

source
Manifolds.volume_density — Method
volume_density(M::GeneralUnitaryMatrices{TypeParameter{Tuple{2}},ℝ}, p, X)

Volume density on O(2)/SO(2) is equal to 1.

source
Manifolds.volume_density — Method
volume_density(M::GeneralUnitaryMatrices{TypeParameter{Tuple{3}},ℝ}, p, X)

Compute the volume density on O(3)/SO(3). The formula reads [FdHDF19]

\[\frac{1-1\cos(\sqrt{2}\lVert X \rVert)}{\lVert X \rVert^2}.\]

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, 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, p, X; kwargs... )
+check_point(M::GeneralUnitaryMatrices, 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, p, X; kwargs... )
 check_vector(M::OrthogonalMatrices, p, X; kwargs... )
 check_vector(M::Rotations, p, X; kwargs... )
-check_vector(M::GeneralUnitaryMatrices, 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, 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, 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, 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)
+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)
 get_embedding(M::Rotations)
-get_embedding(M::UnitaryMatrices)

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::GeneralUnitaryMatrices{<:Any,ℂ,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::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::SpecialOrthogonal)
+get_embedding(M::UnitaryMatrices)

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::GeneralUnitaryMatrices{<:Any,ℂ,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::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::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{<:Any,ℂ,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, 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{<:Any,ℂ,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, p, X)
 project(M::Rotations, p, X)
-project(M::UnitaryMatrices, 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, p)
- project(G::OrthogonalMatrices, 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, 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, p)
+ project(G::OrthogonalMatrices, 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/PR673/manifolds/graph.html b/previews/PR673/manifolds/graph.html index 935c7b4d46..852e9f26a5 100644 --- a/previews/PR673/manifolds/graph.html +++ b/previews/PR673/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/PR673/manifolds/grassmann.html b/previews/PR673/manifolds/grassmann.html index 0e90bd5163..5976c1cfb3 100644 --- a/previews/PR673/manifolds/grassmann.html +++ b/previews/PR673/manifolds/grassmann.html @@ -2,21 +2,21 @@ Grassmann · Manifolds.jl
GitHub

Grassmannian manifold

Manifolds.Grassmann — Type
Grassmann{T,𝔽} <: 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[BZA20].

Constructor

Grassmann(n, k, field=ℝ, parameter::Symbol=:type)

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
Statistics.mean — Method
mean(
+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[BZA20].
Constructor
Grassmann(n, k, field=ℝ, parameter::Symbol=:type)
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

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

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
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::Grassmann, p, G, H, X)

The Riemannian Hessian can be computed by adopting Eq. (6.6) [Ngu23], where we use for the EuclideanMetric $α_0=α_1=1$ in their formula. Let $\nabla f(p)$ denote the Euclidean gradient G, $\nabla^2 f(p)[X]$ the Euclidean Hessian H. Then the formula reads

\[ \operatorname{Hess}f(p)[X] = \operatorname{proj}_{T_p\mathcal M}\Bigl( ∇^2f(p)[X] - X p^{\mathrm{H}}∇f(p) - \Bigr).\]

Compared to Eq. (5.6) also the metric conversion simplifies to the identity.

source
Manifolds.uniform_distribution — Method
uniform_distribution(M::Grassmann{<:Any,ℝ}, 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 [Chi03]; see also Theorem 2.2.2(iii) in [Chi03].

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.riemann_tensor — Method
riemann_tensor(::Grassmann{<:Any,ℝ}, p, X, Y, Z)

Compute the value of Riemann tensor on the real Grassmann manifold. The formula reads [Ren11] $R(X,Y)Z = (XY^\mathrm{T} - YX^\mathrm{T})Z + Z(Y^\mathrm{T}X - X^\mathrm{T}Y)$.

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 [BZA20].

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, 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, p::ProjectorPoint, X::ProjectorTVector; kwargs...)

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
Manifolds.uniform_distribution — Method
uniform_distribution(M::Grassmann{<:Any,ℝ}, 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 [Chi03]; see also Theorem 2.2.2(iii) in [Chi03].

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.riemann_tensor — Method
riemann_tensor(::Grassmann{<:Any,ℝ}, p, X, Y, Z)

Compute the value of Riemann tensor on the real Grassmann manifold. The formula reads [Ren11] $R(X,Y)Z = (XY^\mathrm{T} - YX^\mathrm{T})Z + Z(Y^\mathrm{T}X - X^\mathrm{T}Y)$.

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 [BZA20].

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, 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, p::ProjectorPoint, X::ProjectorTVector; kwargs...)

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 [BZA20] 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

Literature

[BZA20]
T. Bendokat, R. Zimmermann and P.-A. Absil. A Grassmann Manifold Handbook: Basic Geometry and Computational Aspects, arXiv Preprint (2020), arXiv:2011.13699.
[Chi03]
Y. Chikuse. Statistics on Special Manifolds (Springer New York, 2003).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Ren11]
Q. Rentmeesters. A gradient method for geodesic data fitting on some symmetric Riemannian manifolds. In: IEEE Conference on Decision and Control and European Control Conference (2011); pp. 7141–7146.
+)

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 [BZA20] 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, p::ProjectorPoint)

Return the represenation size or matrix dimension of a point on the Grassmann M when using ProjectorPoints, i.e. $(n,n)$.

source

Literature

[BZA20]
T. Bendokat, R. Zimmermann and P.-A. Absil. A Grassmann Manifold Handbook: Basic Geometry and Computational Aspects, arXiv Preprint (2020), arXiv:2011.13699.
[Chi03]
Y. Chikuse. Statistics on Special Manifolds (Springer New York, 2003).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Ren11]
Q. Rentmeesters. A gradient method for geodesic data fitting on some symmetric Riemannian manifolds. In: IEEE Conference on Decision and Control and European Control Conference (2011); pp. 7141–7146.
diff --git a/previews/PR673/manifolds/group.html b/previews/PR673/manifolds/group.html index 338ef30872..c4cd36e90c 100644 --- a/previews/PR673/manifolds/group.html +++ b/previews/PR673/manifolds/group.html @@ -1,81 +1,81 @@ Group manifold · Manifolds.jl
GitHub

Group manifolds

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.GroupExponentialRetraction — Type
GroupExponentialRetraction{D<:ActionDirectionAndSide} <: AbstractRetractionMethod

Retraction using the group exponential exp_lie "translated" to any point on the manifold.

For more details, see retract.

Constructor

GroupExponentialRetraction(conv::ActionDirectionAndSide = LeftAction())
source
Manifolds.GroupLogarithmicInverseRetraction — Type
GroupLogarithmicInverseRetraction{D<:ActionDirectionAndSide} <: AbstractInverseRetractionMethod

Retraction using the group logarithm log_lie "translated" to any point on the manifold.

For more details, see inverse_retract.

Constructor

GroupLogarithmicInverseRetraction(conv::ActionDirectionAndSide = 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.GroupExponentialRetraction — Type
GroupExponentialRetraction{D<:ActionDirectionAndSide} <: AbstractRetractionMethod

Retraction using the group exponential exp_lie "translated" to any point on the manifold.

For more details, see retract.

Constructor

GroupExponentialRetraction(conv::ActionDirectionAndSide = LeftAction())
source
Manifolds.GroupLogarithmicInverseRetraction — Type
GroupLogarithmicInverseRetraction{D<:ActionDirectionAndSide} <: AbstractInverseRetractionMethod

Retraction using the group logarithm log_lie "translated" to any point on the manifold.

For more details, see inverse_retract.

Constructor

GroupLogarithmicInverseRetraction(conv::ActionDirectionAndSide = 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::AbstractGroupOperation)
source
Manifolds.LeftAction — Type
LeftAction()

Left action of a group on a manifold. For a forward action $α: G × X → X$ it is characterized by

\[α(g, α(h, x)) = α(gh, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

source
Manifolds.LeftSide — Type
LeftSide()

An action of a group on a manifold that acts from the left side, i.e. $α: G × X → X$.

source
Manifolds.RightAction — Type
RightAction()

Right action of a group on a manifold. For a forward 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 act from either left or right side in an expression.

source
Manifolds.RightSide — Type
RightSide()

An action of a group on a manifold that acts from the right side, i.e. $α: X × G → X$.

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::AbstractGroupOperation)
source
Manifolds.LeftAction — Type
LeftAction()

Left action of a group on a manifold. For a forward action $α: G × X → X$ it is characterized by

\[α(g, α(h, x)) = α(gh, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

source
Manifolds.LeftSide — Type
LeftSide()

An action of a group on a manifold that acts from the left side, i.e. $α: G × X → X$.

source
Manifolds.RightAction — Type
RightAction()

Right action of a group on a manifold. For a forward 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 act from either left or right side in an expression.

source
Manifolds.RightSide — Type
RightSide()

An action of a group on a manifold that acts from the right side, i.e. $α: X × G → X$.

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 [Suh13], 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::AbstractDecoratorManifold)

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.inv_diff — Method
inv_diff(G::AbstractDecoratorManifold, p, X)

Compute the value of differential of inverse $p^{-1} ∈ \mathcal{G}$ of an element $p ∈ \mathcal{G}$ at tangent vector X at p. The result is a tangent vector at $p^{-1}$.

source
Manifolds.inverse_translate — Method
inverse_translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirectionAndSide=LeftForwardAction())

Inverse translate group element $q$ by $p$ with the translation $τ_p^{-1}$ with the specified convention, either left forward ($L_p^{-1}$), left backward ($R'_p^{-1}$), right backward ($R_p^{-1}$) or right forward ($L'_p^{-1}$), defined as ```math \begin{aligned} Lp^{-1} &: q ↦ p^{-1} \circ q\ +\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::AbstractDecoratorManifold)

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.inv_diff — Method
inv_diff(G::AbstractDecoratorManifold, p, X)

Compute the value of differential of inverse $p^{-1} ∈ \mathcal{G}$ of an element $p ∈ \mathcal{G}$ at tangent vector X at p. The result is a tangent vector at $p^{-1}$.

source
Manifolds.inverse_translate — Method
inverse_translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirectionAndSide=LeftForwardAction())

Inverse translate group element $q$ by $p$ with the translation $τ_p^{-1}$ with the specified convention, either left forward ($L_p^{-1}$), left backward ($R'_p^{-1}$), right backward ($R_p^{-1}$) or right forward ($L'_p^{-1}$), defined as ```math \begin{aligned} Lp^{-1} &: q ↦ p^{-1} \circ q\ L'p^{-1} &: q ↦ p \circ q\ Rp^{-1} &: q ↦ q \circ p^{-1}\ -R'p^{-1} &: q ↦ q \circ p. \end{aligned}

source
Manifolds.inverse_translate_diff — Method
inverse_translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirectionAndSide=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.translate — Method
translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirectionAndSide=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} +R'p^{-1} &: q ↦ q \circ p. \end{aligned}

source
Manifolds.inverse_translate_diff — Method
inverse_translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirectionAndSide=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.translate — Method
translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirectionAndSide=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::ActionDirectionAndSide=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::ActionDirectionAndSide=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,
-)

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,
-)

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

Manifolds.inv_diff — Method
inv_diff(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of differential of additive matrix inversion $p ↦ -p$ at $X$, i.e. $-X$.

source

Multiplication Operation

Manifolds.inv_diff — Method
inv_diff(::MultiplicationGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of differential of matrix inversion $p ↦ p^{-1}$ at $X$. When tangent vectors are represented in Lie algebra in a left-invariant way, the formula reads $-pXp^{-1}$. For matrix groups with ambient space tangent vectors, the formula would read $-p^{-1}Xp^{-1}$. See the section about matrix inverse in [Gil08].

source

Circle group

General linear group

Manifolds.GeneralLinear — Type
GeneralLinear{T,𝔽} <: 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.exp — Method
exp(G::GeneralLinear, p, X)

Compute the exponential map on the GeneralLinear group.

The exponential map is

\[\exp_p \colon X ↦ p \operatorname{Exp}(X^\mathrm{H}) \operatorname{Exp}(X - X^\mathrm{H}),\]

where $\operatorname{Exp}(⋅)$ denotes the matrix exponential, and $⋅^\mathrm{H}$ is the conjugate transpose [ALRV14] [NM16].

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{T} <: AbstractDecoratorManifold{ℝ}

Heisenberg group HeisenbergGroup(n) is the group of $(n+2) × (n+2)$ matrices [BP08]

\[\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

Manifolds.inv_diff — Method
inv_diff(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of differential of additive matrix inversion $p ↦ -p$ at $X$, i.e. $-X$.

source

Multiplication Operation

Manifolds.inv_diff — Method
inv_diff(::MultiplicationGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of differential of matrix inversion $p ↦ p^{-1}$ at $X$. When tangent vectors are represented in Lie algebra in a left-invariant way, the formula reads $-pXp^{-1}$. For matrix groups with ambient space tangent vectors, the formula would read $-p^{-1}Xp^{-1}$. See the section about matrix inverse in [Gil08].

source

Circle group

General linear group

Manifolds.GeneralLinear — Type
GeneralLinear{T,𝔽} <: 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.exp — Method
exp(G::GeneralLinear, p, X)

Compute the exponential map on the GeneralLinear group.

The exponential map is

\[\exp_p \colon X ↦ p \operatorname{Exp}(X^\mathrm{H}) \operatorname{Exp}(X - X^\mathrm{H}),\]

where $\operatorname{Exp}(⋅)$ denotes the matrix exponential, and $⋅^\mathrm{H}$ is the conjugate transpose [ALRV14] [NM16].

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{T} <: AbstractDecoratorManifold{ℝ}

Heisenberg group HeisenbergGroup(n) is the group of $(n+2) × (n+2)$ matrices [BP08]

\[\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, 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, 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{TypeParameter{Tuple{2}}}, X)
- exp_lie(G::SpecialOrthogonal{TypeParameter{Tuple{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
Manifolds.exp_lie — Method
 exp_lie(G::Orthogonal{TypeParameter{Tuple{4}}}, X)
- exp_lie(G::SpecialOrthogonal{TypeParameter{Tuple{4}}}, X)

Compute 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 [GX02], [AR13].

source

Orthogonal group

Manifolds.Orthogonal — Type
Orthogonal{T} = GeneralUnitaryMultiplicationGroup{T,ℝ,AbsoluteDeterminantOneMatrices}

Orthogonal group $\mathrm{O}(n)$ represented by OrthogonalMatrices.

Constructor

Orthogonal(n::Int; parameter::Symbol=:type)
source

Special orthogonal group

Manifolds.SpecialOrthogonal — Type
SpecialOrthogonal{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,DeterminantOneMatrices}

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, 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, 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{TypeParameter{Tuple{2}}}, X)
+ exp_lie(G::SpecialOrthogonal{TypeParameter{Tuple{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
Manifolds.exp_lie — Method
 exp_lie(G::Orthogonal{TypeParameter{Tuple{4}}}, X)
+ exp_lie(G::SpecialOrthogonal{TypeParameter{Tuple{4}}}, X)

Compute 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 [GX02], [AR13].

source

Orthogonal group

Manifolds.Orthogonal — Type
Orthogonal{T} = GeneralUnitaryMultiplicationGroup{T,ℝ,AbsoluteDeterminantOneMatrices}

Orthogonal group $\mathrm{O}(n)$ represented by OrthogonalMatrices.

Constructor

Orthogonal(n::Int; parameter::Symbol=:type)
source

Special orthogonal group

Manifolds.SpecialOrthogonal — Type
SpecialOrthogonal{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,DeterminantOneMatrices}

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._get_parameter — Method
_get_parameter(M::AbstractManifold)

Similar to get_parameter but it can be specialized for manifolds without breaking manifolds being parametrized by other manifolds.

source
Manifolds.adjoint_action — Method
adjoint_action(::SpecialEuclidean{TypeParameter{Tuple{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._get_parameter — Method
_get_parameter(M::AbstractManifold)

Similar to get_parameter but it can be specialized for manifolds without breaking manifolds being parametrized by other manifolds.

source
Manifolds.adjoint_action — Method
adjoint_action(::SpecialEuclidean{TypeParameter{Tuple{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 [Ric88].

See also screw_matrix for matrix representations of the Lie algebra.

source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{TypeParameter{Tuple{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{TypeParameter{Tuple{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::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 ArrayPartition 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{TypeParameter{Tuple{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{TypeParameter{Tuple{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, p)

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} +\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 [Ric88].

See also screw_matrix for matrix representations of the Lie algebra.

source
Manifolds.exp_lie — Method
exp_lie(G::SpecialEuclidean{TypeParameter{Tuple{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{TypeParameter{Tuple{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::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 ArrayPartition 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{TypeParameter{Tuple{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{TypeParameter{Tuple{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, p)

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{T,𝔽} <: 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{T,𝔽} <: 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,𝔽} <: GroupManifold{Euclidean{T,𝔽},AdditionOperation}

Translation group $\mathrm{T}(n)$ represented by translation arrays.

Constructor

TranslationGroup(n₁,...,nᵢ; field=𝔽, parameter::Symbol=:type)

Generate the translation group on $𝔽^{n₁,…,nᵢ}$ = Euclidean(n₁,...,nᵢ; field=𝔽), which is isomorphic to the group itself.

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

Translation group

Manifolds.TranslationGroup — Type
TranslationGroup{T,𝔽} <: GroupManifold{Euclidean{T,𝔽},AdditionOperation}

Translation group $\mathrm{T}(n)$ represented by translation arrays.

Constructor

TranslationGroup(n₁,...,nᵢ; field=𝔽, parameter::Symbol=:type)

Generate the translation group on $𝔽^{n₁,…,nᵢ}$ = Euclidean(n₁,...,nᵢ; field=𝔽), which is isomorphic to the group itself.

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,
@@ -83,4 +83,4 @@
     qs::AbstractVector,
     conv::ActionDirectionAndSide = 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 [PL20] 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 [PL20] for details.

source
+) -> 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 [PL20] 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 [PL20] 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 [PL20] 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 [PL20] 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 [PL20] 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 [PL20] 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/PR673/manifolds/hyperbolic-e8e44318.svg b/previews/PR673/manifolds/hyperbolic-43dabf20.svg similarity index 93% rename from previews/PR673/manifolds/hyperbolic-e8e44318.svg rename to previews/PR673/manifolds/hyperbolic-43dabf20.svg index 5796d91922..89b589a63e 100644 --- a/previews/PR673/manifolds/hyperbolic-e8e44318.svg +++ b/previews/PR673/manifolds/hyperbolic-43dabf20.svg @@ -1,72 +1,72 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-79342447.svg b/previews/PR673/manifolds/hyperbolic-4c4cdac2.svg similarity index 96% rename from previews/PR673/manifolds/hyperbolic-79342447.svg rename to previews/PR673/manifolds/hyperbolic-4c4cdac2.svg index 9b857194c7..09f7cdc994 100644 --- a/previews/PR673/manifolds/hyperbolic-79342447.svg +++ b/previews/PR673/manifolds/hyperbolic-4c4cdac2.svg @@ -1,38 +1,38 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-010abb96.svg b/previews/PR673/manifolds/hyperbolic-4eede24e.svg similarity index 87% rename from previews/PR673/manifolds/hyperbolic-010abb96.svg rename to previews/PR673/manifolds/hyperbolic-4eede24e.svg index af1070df9c..af3c94af1d 100644 --- a/previews/PR673/manifolds/hyperbolic-010abb96.svg +++ b/previews/PR673/manifolds/hyperbolic-4eede24e.svg @@ -1,40 +1,40 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-cfad8624.svg b/previews/PR673/manifolds/hyperbolic-72f480f2.svg similarity index 86% rename from previews/PR673/manifolds/hyperbolic-cfad8624.svg rename to previews/PR673/manifolds/hyperbolic-72f480f2.svg index 51725cd3e0..5005938ea8 100644 --- a/previews/PR673/manifolds/hyperbolic-cfad8624.svg +++ b/previews/PR673/manifolds/hyperbolic-72f480f2.svg @@ -1,48 +1,48 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-8a540b79.svg b/previews/PR673/manifolds/hyperbolic-777c950b.svg similarity index 94% rename from previews/PR673/manifolds/hyperbolic-8a540b79.svg rename to previews/PR673/manifolds/hyperbolic-777c950b.svg index ce65b7a288..f1e40b6c3a 100644 --- a/previews/PR673/manifolds/hyperbolic-8a540b79.svg +++ b/previews/PR673/manifolds/hyperbolic-777c950b.svg @@ -1,75 +1,75 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-2016cf1f.svg b/previews/PR673/manifolds/hyperbolic-8266f31a.svg similarity index 83% rename from previews/PR673/manifolds/hyperbolic-2016cf1f.svg rename to previews/PR673/manifolds/hyperbolic-8266f31a.svg index b1fa18fa2c..c919feb7d1 100644 --- a/previews/PR673/manifolds/hyperbolic-2016cf1f.svg +++ b/previews/PR673/manifolds/hyperbolic-8266f31a.svg @@ -1,69 +1,69 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-97580ee4.svg b/previews/PR673/manifolds/hyperbolic-87129286.svg similarity index 69% rename from previews/PR673/manifolds/hyperbolic-97580ee4.svg rename to previews/PR673/manifolds/hyperbolic-87129286.svg index 10a5b5dbf7..d3b1ec0fd6 100644 --- a/previews/PR673/manifolds/hyperbolic-97580ee4.svg +++ b/previews/PR673/manifolds/hyperbolic-87129286.svg @@ -1,1969 +1,1969 @@ - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-938e1d70.svg b/previews/PR673/manifolds/hyperbolic-a484bb1f.svg similarity index 69% rename from previews/PR673/manifolds/hyperbolic-938e1d70.svg rename to previews/PR673/manifolds/hyperbolic-a484bb1f.svg index d54ac6a53c..64bdce3f00 100644 --- a/previews/PR673/manifolds/hyperbolic-938e1d70.svg +++ b/previews/PR673/manifolds/hyperbolic-a484bb1f.svg @@ -1,1946 +1,1946 @@ - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-4adb56ba.svg b/previews/PR673/manifolds/hyperbolic-bb862b30.svg similarity index 70% rename from previews/PR673/manifolds/hyperbolic-4adb56ba.svg rename to previews/PR673/manifolds/hyperbolic-bb862b30.svg index 0aef91f356..f6ed4d11b3 100644 --- a/previews/PR673/manifolds/hyperbolic-4adb56ba.svg +++ b/previews/PR673/manifolds/hyperbolic-bb862b30.svg @@ -1,375 +1,375 @@ - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-62738466.svg b/previews/PR673/manifolds/hyperbolic-c1adb49c.svg similarity index 69% rename from previews/PR673/manifolds/hyperbolic-62738466.svg rename to previews/PR673/manifolds/hyperbolic-c1adb49c.svg index bdac0ea446..8190b67475 100644 --- a/previews/PR673/manifolds/hyperbolic-62738466.svg +++ b/previews/PR673/manifolds/hyperbolic-c1adb49c.svg @@ -1,1958 +1,1958 @@ - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-ed1d6fd6.svg b/previews/PR673/manifolds/hyperbolic-f345fce6.svg similarity index 97% rename from previews/PR673/manifolds/hyperbolic-ed1d6fd6.svg rename to previews/PR673/manifolds/hyperbolic-f345fce6.svg index 806a7a619c..d7ea5b1f37 100644 --- a/previews/PR673/manifolds/hyperbolic-ed1d6fd6.svg +++ b/previews/PR673/manifolds/hyperbolic-f345fce6.svg @@ -1,25 +1,25 @@ - + - + - + - + - + - - - - - - + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic-90f527ec.svg b/previews/PR673/manifolds/hyperbolic-f9e6bd1f.svg similarity index 84% rename from previews/PR673/manifolds/hyperbolic-90f527ec.svg rename to previews/PR673/manifolds/hyperbolic-f9e6bd1f.svg index 600710d339..1e1fef96a3 100644 --- a/previews/PR673/manifolds/hyperbolic-90f527ec.svg +++ b/previews/PR673/manifolds/hyperbolic-f9e6bd1f.svg @@ -1,73 +1,73 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/hyperbolic.html b/previews/PR673/manifolds/hyperbolic.html index b72de0f9dc..a253e9c90a 100644 --- a/previews/PR673/manifolds/hyperbolic.html +++ b/previews/PR673/manifolds/hyperbolic.html @@ -2,56 +2,56 @@ Hyperbolic space · Manifolds.jl
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{T} <: 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::Int; parameter::Symbol=:type)

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, 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
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::Hyperbolic{n}, p, X, Y, Z)

Compute the Riemann tensor $R(X,Y)Z$ at point p on Hyperbolic M. The formula reads (see e.g., [Lee19] Proposition 8.36)

\[R(X,Y)Z = - (\langle Z, Y \rangle X - \langle Z, X \rangle Y)\]

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::Int; parameter::Symbol=:type)
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, 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
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::Hyperbolic{n}, p, X, Y, Z)

Compute the Riemann tensor $R(X,Y)Z$ at point p on Hyperbolic M. The formula reads (see e.g., [Lee19] Proposition 8.36)

\[R(X,Y)Z = - (\langle Z, Y \rangle X - \langle Z, X \rangle Y)\]

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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::Hyperbolic, p, G, H, X)
 riemannian_Hessian!(M::Hyperbolic, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

Let $\mathbf{g} = \mathbf{g}^{-1} = \operatorname{diag}(1,...,1,-1)$. Then using Remark 4.1 [Ngu23] the formula reads

\[\operatorname{Hess}f(p)[X] = \operatorname{proj}_{T_p\mathcal M}\bigl( \mathbf{g}^{-1}\nabla^2f(p)[X] + X⟨p,\mathbf{g}^{-1}∇f(p)⟩_p -\bigr).\]

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[CLLD22].

source
ManifoldsBase.change_representer — Method
change_representer(M::Hyperbolic, ::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, p, X, Y)
-inner(M::Hyperbolic, 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
+\bigr).\]
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[CLLD22].

source
ManifoldsBase.change_representer — Method
change_representer(M::Hyperbolic, ::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, p, X, Y)
+inner(M::Hyperbolic, 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)
Example block output

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)
Example block output

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)]
+scene = plot(M, pts; geodesic_interpolation=100)
Example block output

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)
Example block output

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)
Example block output

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)
Example block output

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(
+plot!(scene, M, pts, vecs; wireframe=false)
Example block output

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)
Example block output

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
@@ -70,32 +70,32 @@
 ⋮\\
 2p_{n-1}(⟨X,p⟩+X_n)\\
 (\lVert p \rVert^2-1)(⟨X,p⟩+X_n)
-\end{pmatrix}\]
where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.
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, ::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, ::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, ::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, ::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 product 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 product 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)
Example block output

To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot

plot!(scene, M, pts)
Example block output

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)])
+scene = plot(M, pts, geodesic_interpolation = 100)
Example block output

To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot

plot!(scene, M, pts)
Example block output

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)
Example block output

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)
Example block output

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] = +plot!(scene, M, pts,vecs)Example block output

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)
Example block output

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] = \frac{1}{\lVert \tilde p\rVert^2 + (1-p_n)^2} \begin{pmatrix} 2X_1\\ @@ -110,29 +110,29 @@ ⋮\\ 2p_{n-1}(⟨X,p⟩-X_n)\\ (\lVert p \rVert^2-1)(⟨X,p⟩-X_n) -\end{pmatrix}\]

where $\tilde p = \begin{pmatrix}p_1\\⋮\\p_{n-1}\end{pmatrix}$.

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
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.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,
     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.(
     Ref(PoincareHalfSpacePoint),
     Manifolds._hyperbolize.(Ref(M), pre_pts)
 )
-scene = plot(M, pts, geodesic_interpolation = 100)
Example block output

To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot

plot!(scene, M, pts)
Example block output

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])
+scene = plot(M, pts, geodesic_interpolation = 100)
Example block output

To just plot the points atop, we can just omit the geodesic_interpolation parameter to obtain a scatter plot

plot!(scene, M, pts)
Example block output

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)
Example block output

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)
Example block output

Literature

[CLLD22]
E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
[Lee19]
J. M. Lee. Introduction to Riemannian Manifolds (Springer Cham, 2019).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
+scene = plot!(scene, M, pts, vecs)Example block output

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)
Example block output

Literature

[CLLD22]
E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
[Lee19]
J. M. Lee. Introduction to Riemannian Manifolds (Springer Cham, 2019).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
diff --git a/previews/PR673/manifolds/lorentz.html b/previews/PR673/manifolds/lorentz.html index 6eeff70d48..1f036c79d9 100644 --- a/previews/PR673/manifolds/lorentz.html +++ b/previews/PR673/manifolds/lorentz.html @@ -1,3 +1,3 @@ -Lorentzian manifold · Manifolds.jl
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{T} = MetricManifold{Euclidean{T,ℝ},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
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{T} = MetricManifold{Euclidean{T,ℝ},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/PR673/manifolds/metric.html b/previews/PR673/manifolds/metric.html index 4ccf036380..4de9ad9eda 100644 --- a/previews/PR673/manifolds/metric.html +++ b/previews/PR673/manifolds/metric.html @@ -1,7 +1,7 @@ -Metric manifold · Manifolds.jl
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
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/PR673/manifolds/multinomial.html b/previews/PR673/manifolds/multinomial.html index 54c8985c73..a994cc1a29 100644 --- a/previews/PR673/manifolds/multinomial.html +++ b/previews/PR673/manifolds/multinomial.html @@ -1,2 +1,2 @@ -Multinomial matrices · Manifolds.jl
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::Int, m::Int; parameter::Symbol=:type)

Generate the manifold of matrices $\mathbb R^{n×m}$ such that the $m$ columns are discrete probability distributions, i.e. sum up to one.

parameter: whether a type parameter should be used to store n and m. By default size is stored in type. Value can either be :field or :type.

source

Functions

Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:

+Multinomial matrices · Manifolds.jl
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::Int, m::Int; parameter::Symbol=:type)

Generate the manifold of matrices $\mathbb R^{n×m}$ such that the $m$ columns are discrete probability distributions, i.e. sum up to one.

parameter: whether a type parameter should be used to store n and m. By default size is stored in type. Value can either be :field or :type.

source

Functions

Most functions are directly implemented for an AbstractPowerManifold with ArrayPowerRepresentation except the following special cases:

diff --git a/previews/PR673/manifolds/multinomialdoublystochastic.html b/previews/PR673/manifolds/multinomialdoublystochastic.html index 46c48e83c6..9ce7dd481b 100644 --- a/previews/PR673/manifolds/multinomialdoublystochastic.html +++ b/previews/PR673/manifolds/multinomialdoublystochastic.html @@ -1,17 +1,17 @@ -Multinomial doubly stochastic matrices · Manifolds.jl
GitHub

Multinomial doubly stochastic matrices

Manifolds.MultinomialDoubleStochastic — Type
MultinomialDoublyStochastic{T} <: AbstractMultinomialDoublyStochastic

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

GitHub

Multinomial doubly stochastic matrices

Manifolds.MultinomialDoubleStochastic — Type
MultinomialDoublyStochastic{T} <: AbstractMultinomialDoublyStochastic

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 [DH19].

Constructor

MultinomialDoubleStochastic(n::Int; parameter::Symbol=:type)

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 [DH19].
Constructor
MultinomialDoubleStochastic(n::Int; parameter::Symbol=:type)
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, p, Y)

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, p, Y)

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

+ \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

diff --git a/previews/PR673/manifolds/multinomialsymmetric.html b/previews/PR673/manifolds/multinomialsymmetric.html index 4850ba37fc..6ffac2d675 100644 --- a/previews/PR673/manifolds/multinomialsymmetric.html +++ b/previews/PR673/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 [DH19].

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, p, Y)

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

+\bigr\},\]

where $\mathbf{0}_n$ is the vector of length $n$ containing zeros.

More details can be found in Section IV [DH19].

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, p, Y)

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

diff --git a/previews/PR673/manifolds/oblique.html b/previews/PR673/manifolds/oblique.html index 2bf4ddbb2a..091e9facf3 100644 --- a/previews/PR673/manifolds/oblique.html +++ b/previews/PR673/manifolds/oblique.html @@ -1,2 +1,2 @@ -Oblique manifold · Manifolds.jl
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{T,𝔽,S} <: 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::Int, m::Int, field::AbstractNumbers=ℝ; parameter::Symbol=:type)

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, 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
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{T,𝔽,S} <: 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::Int, m::Int, field::AbstractNumbers=ℝ; parameter::Symbol=:type)

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, 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/PR673/manifolds/positivenumbers.html b/previews/PR673/manifolds/positivenumbers.html index 1192add60b..38dd1fd59d 100644 --- a/previews/PR673/manifolds/positivenumbers.html +++ b/previews/PR673/manifolds/positivenumbers.html @@ -1,2 +1,2 @@ -Positive numbers · Manifolds.jl
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
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::SymmetricPositiveDefinite, p, G, H, X)

The Riemannian Hessian can be computed as stated in Eq. (7.3) [Ngu23]. Let $\nabla f(p)$ denote the Euclidean gradient G, $\nabla^2 f(p)[X]$ the Euclidean Hessian H. Then the formula reads

\[ \operatorname{Hess}f(p)[X] = p\bigl(∇^2 f(p)[X]\bigr)p + X\bigl(∇f(p)\bigr)p\]

source
Manifolds.PositiveArrays — Method
PositiveArrays(n₁, n₂, ..., nᵢ; parameter::Symbol=:type)

Generate the manifold of i-dimensional arrays with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.

parameter: whether a type parameter should be used to store n. By default size is stored in a type parameter. Value can either be :field or :type.

source
Manifolds.PositiveMatrices — Method
PositiveMatrices(m::Integer, n::Integer; parameter::Symbol=:type)

Generate the manifold of matrices with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.

parameter: whether a type parameter should be used to store n. By default size is stored in a type parameter. Value can either be :field or :type.

source
Manifolds.PositiveVectors — Method
PositiveVectors(n::Integer; parameter::Symbol=:type)

Generate the manifold of vectors with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.

parameter: whether a type parameter should be used to store n. By default size is stored in a type parameter. Value can either be :field or :type.

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
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
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::SymmetricPositiveDefinite, p, G, H, X)

The Riemannian Hessian can be computed as stated in Eq. (7.3) [Ngu23]. Let $\nabla f(p)$ denote the Euclidean gradient G, $\nabla^2 f(p)[X]$ the Euclidean Hessian H. Then the formula reads

\[ \operatorname{Hess}f(p)[X] = p\bigl(∇^2 f(p)[X]\bigr)p + X\bigl(∇f(p)\bigr)p\]

source
Manifolds.PositiveArrays — Method
PositiveArrays(n₁, n₂, ..., nᵢ; parameter::Symbol=:type)

Generate the manifold of i-dimensional arrays with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.

parameter: whether a type parameter should be used to store n. By default size is stored in a type parameter. Value can either be :field or :type.

source
Manifolds.PositiveMatrices — Method
PositiveMatrices(m::Integer, n::Integer; parameter::Symbol=:type)

Generate the manifold of matrices with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.

parameter: whether a type parameter should be used to store n. By default size is stored in a type parameter. Value can either be :field or :type.

source
Manifolds.PositiveVectors — Method
PositiveVectors(n::Integer; parameter::Symbol=:type)

Generate the manifold of vectors with positive entries. This manifold is modeled as a PowerManifold of PositiveNumbers.

parameter: whether a type parameter should be used to store n. By default size is stored in a type parameter. Value can either be :field or :type.

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/PR673/manifolds/power.html b/previews/PR673/manifolds/power.html index 2730de22a3..8b0fb93bbf 100644 --- a/previews/PR673/manifolds/power.html +++ b/previews/PR673/manifolds/power.html @@ -51,5 +51,5 @@ ([0.0, 0.0], [0.0 -2.2831853071795862; 2.2831853071795862 0.0]) ([0.0, 0.0], [0.0 -0.28318530717958645; 0.28318530717958645 0.0]) ([0.0, 0.0], [0.0 1.7168146928204135; -1.7168146928204135 0.0]) - ([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::VectorSpaceFiber], [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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::AbstractPowerManifold, p, G, H, X)
-riemannian_Hessian!(M::AbstractPowerManifold, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

On an abstract power manifold, this decouples and can be computed elementwise.

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
+ ([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::VectorSpaceFiber], [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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::AbstractPowerManifold, p, G, H, X)
+riemannian_Hessian!(M::AbstractPowerManifold, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

On an abstract power manifold, this decouples and can be computed elementwise.

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
diff --git a/previews/PR673/manifolds/probabilitysimplex.html b/previews/PR673/manifolds/probabilitysimplex.html index 5c9960aff0..68a84269cd 100644 --- a/previews/PR673/manifolds/probabilitysimplex.html +++ b/previews/PR673/manifolds/probabilitysimplex.html @@ -1,13 +1,13 @@ -Probability simplex · Manifolds.jl
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{T,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

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{T,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 [APSS17].

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 [APSS17].

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 [Mar72].

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, p, Y)
-riemannian_gradient!(M::ProbabilitySimplex, 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
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 [APSS17].

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 [AJLS17].

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

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 [Mar72].

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, p, Y)
+riemannian_gradient!(M::ProbabilitySimplex, 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
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 [APSS17].

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 [AJLS17].

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

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

Euclidean metric

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 [Dev86], 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 [AJLS17].

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, p)

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

[AJLS17]
N. Ay, J. Jost, H. V. Lê and L. Schwachhöfer. Information Geometry (Springer Cham, 2017).
[Dev86]
L. Devroye. Non-Uniform Random Variate Generation (Springer New York, NY, 1986).
[Mar72]
G. Marsaglia. Choosing a Point from the Surface of a Sphere. Annals of Mathematical Statistics 43, 645–646 (1972).
[APSS17]
F. Åström, S. Petra, B. Schmitzer and C. Schnörr. Image Labeling by Assignment. Journal of Mathematical Imaging and Vision 58, 211–238 (2017), arXiv:1603.05285.
+)

Compute the Riemannian mean of x using GeodesicInterpolation.

source

Euclidean metric

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 [Dev86], 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 [AJLS17].

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, p)

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

[AJLS17]
N. Ay, J. Jost, H. V. Lê and L. Schwachhöfer. Information Geometry (Springer Cham, 2017).
[Dev86]
L. Devroye. Non-Uniform Random Variate Generation (Springer New York, NY, 1986).
[Mar72]
G. Marsaglia. Choosing a Point from the Surface of a Sphere. Annals of Mathematical Statistics 43, 645–646 (1972).
[APSS17]
F. Åström, S. Petra, B. Schmitzer and C. Schnörr. Image Labeling by Assignment. Journal of Mathematical Imaging and Vision 58, 211–238 (2017), arXiv:1603.05285.
diff --git a/previews/PR673/manifolds/product.html b/previews/PR673/manifolds/product.html index 944f46ccb8..91132cce30 100644 --- a/previews/PR673/manifolds/product.html +++ b/previews/PR673/manifolds/product.html @@ -1,3 +1,3 @@ -Product manifold · Manifolds.jl
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 ArrayPartition (from RecursiveArrayTools.jl) with canonical projections $Π_i : \mathcal{M} → \mathcal{M}_i$ for $i ∈ 1, 2, …, n$ provided by submanifold_component.

Manifolds.ProductFVectorDistribution — Type
ProductFVectorDistribution([type::VectorSpaceFiber], [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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::ProductManifold, p, G, H, X)
-riemannian_Hessian!(M::ProductManifold, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

On a product manifold, this decouples and can be computed elementwise.

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
+Product manifold · Manifolds.jl
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 ArrayPartition (from RecursiveArrayTools.jl) with canonical projections $Π_i : \mathcal{M} → \mathcal{M}_i$ for $i ∈ 1, 2, …, n$ provided by submanifold_component.

Manifolds.ProductFVectorDistribution — Type
ProductFVectorDistribution([type::VectorSpaceFiber], [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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::ProductManifold, p, G, H, X)
+riemannian_Hessian!(M::ProductManifold, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

On a product manifold, this decouples and can be computed elementwise.

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
diff --git a/previews/PR673/manifolds/projectivespace.html b/previews/PR673/manifolds/projectivespace.html index 8cbdb9cfd4..2c8221b5f5 100644 --- a/previews/PR673/manifolds/projectivespace.html +++ b/previews/PR673/manifolds/projectivespace.html @@ -1,12 +1,12 @@ -Projective space · Manifolds.jl
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
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/PR673/manifolds/quotient.html b/previews/PR673/manifolds/quotient.html index fcbb8ccce4..cb36af3c2f 100644 --- a/previews/PR673/manifolds/quotient.html +++ b/previews/PR673/manifolds/quotient.html @@ -1,4 +1,4 @@ -Quotient manifold · Manifolds.jl
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 [AMS08].

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
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 [AMS08].

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/PR673/manifolds/rotations.html b/previews/PR673/manifolds/rotations.html index 8ac33bf180..da1e835820 100644 --- a/previews/PR673/manifolds/rotations.html +++ b/previews/PR673/manifolds/rotations.html @@ -1,8 +1,8 @@ Rotations · Manifolds.jl
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{T} <: AbstractManifold{ℝ}

The manifold of rotation matrices of size $n × n$, i.e. real-valued orthogonal matrices with determinant $+1$.

Constructor

Rotations(n::Int; parameter::Symbol=:type)

Generate the manifold of $n × n$ rotation matrices.

source
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::Rotations, p, G, H, X)

The Riemannian Hessian can be computed by adopting Eq. (5.6) [Ngu23], so very similar to the Stiefel manifold. The only difference is, that here the tangent vectors are stored in the Lie algebra, i.e. the update direction is actually $pX$ instead of just $X$ (in Stiefel). and that means the inverse has to be appliead to the (Euclidean) Hessian to map it into the Lie algebra.

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} +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{T} <: AbstractManifold{ℝ}

The manifold of rotation matrices of size $n × n$, i.e. real-valued orthogonal matrices with determinant $+1$.

Constructor

Rotations(n::Int; parameter::Symbol=:type)

Generate the manifold of $n × n$ rotation matrices.

source
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::Rotations, p, G, H, X)

The Riemannian Hessian can be computed by adopting Eq. (5.6) [Ngu23], so very similar to the Stiefel manifold. The only difference is, that here the tangent vectors are stored in the Lie algebra, i.e. the update direction is actually $pX$ instead of just $X$ (in Stiefel). and that means the inverse has to be appliead to the (Euclidean) Hessian to map it into the Lie algebra.

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.Weingarten — Method
Weingarten(M::Rotations, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Stiefel M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

The formula is due to [AMT13] given by

\[\mathcal W_p(X,V) = -\frac{1}{2}p\bigl(V^{\mathrm{T}}X - X^\mathrm{T}V\bigr)\]

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 [Ren11], 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

[AMT13]
P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Ren11]
Q. Rentmeesters. A gradient method for geodesic data fitting on some symmetric Riemannian manifolds. In: IEEE Conference on Decision and Control and European Control Conference (2011); pp. 7141–7146.
+\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.Weingarten — Method
Weingarten(M::Rotations, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Stiefel M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

The formula is due to [AMT13] given by

\[\mathcal W_p(X,V) = -\frac{1}{2}p\bigl(V^{\mathrm{T}}X - X^\mathrm{T}V\bigr)\]

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 [Ren11], 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

[AMT13]
P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Ren11]
Q. Rentmeesters. A gradient method for geodesic data fitting on some symmetric Riemannian manifolds. In: IEEE Conference on Decision and Control and European Control Conference (2011); pp. 7141–7146.
diff --git a/previews/PR673/manifolds/shapespace-95a8110c.svg b/previews/PR673/manifolds/shapespace-d3551047.svg similarity index 81% rename from previews/PR673/manifolds/shapespace-95a8110c.svg rename to previews/PR673/manifolds/shapespace-d3551047.svg index d7b3f0d33d..e1ebfc0c40 100644 --- a/previews/PR673/manifolds/shapespace-95a8110c.svg +++ b/previews/PR673/manifolds/shapespace-d3551047.svg @@ -1,56 +1,56 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR673/manifolds/shapespace.html b/previews/PR673/manifolds/shapespace.html index 3efeaa1581..04b238f4dd 100644 --- a/previews/PR673/manifolds/shapespace.html +++ b/previews/PR673/manifolds/shapespace.html @@ -19,4 +19,4 @@ A = get_orbit_action(M) a = optimal_alignment(A, p, q) rot_q = apply(A, a, q) -scatter!(fig, rot_q[1,:], rot_q[2,:], label="q aligned to p")Example block output

A more extensive usage example is available in the hand_gestures.jl tutorial.

Manifolds.KendallsPreShapeSpace — Type
KendallsPreShapeSpace{T} <: 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 [Ken84][Ken89].

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; parameter::Symbol=:type)

See also

KendallsShapeSpace, esp. for the references

source
Manifolds.KendallsShapeSpace — Type
KendallsShapeSpace{T} <: 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 [Ken84][Ken89].

This manifold possesses the IsQuotientManifold trait.

Constructor

KendallsShapeSpace(n::Int, k::Int; parameter::Symbol=:type)

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 [SK16] for details.

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 [SK16] 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 [Ken84] for a discussion of the over-dimensioned case.

source
+scatter!(fig, rot_q[1,:], rot_q[2,:], label="q aligned to p")Example block output

A more extensive usage example is available in the hand_gestures.jl tutorial.

Manifolds.KendallsPreShapeSpace — Type
KendallsPreShapeSpace{T} <: 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 [Ken84][Ken89].

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; parameter::Symbol=:type)

See also

KendallsShapeSpace, esp. for the references

source
Manifolds.KendallsShapeSpace — Type
KendallsShapeSpace{T} <: 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 [Ken84][Ken89].

This manifold possesses the IsQuotientManifold trait.

Constructor

KendallsShapeSpace(n::Int, k::Int; parameter::Symbol=:type)

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 [SK16] for details.

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 [SK16] 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 [Ken84] for a discussion of the over-dimensioned case.

source
diff --git a/previews/PR673/manifolds/skewhermitian.html b/previews/PR673/manifolds/skewhermitian.html index 517e3b3390..3bd520da94 100644 --- a/previews/PR673/manifolds/skewhermitian.html +++ b/previews/PR673/manifolds/skewhermitian.html @@ -1,3 +1,3 @@ -Skew-Hermitian matrices · Manifolds.jl
GitHub

Skew-hermitian matrices

Manifolds.SkewHermitianMatrices — Type
SkewHermitianMatrices{T,𝔽} <: 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=ℝ; parameter::Symbol=:type)

Generate the manifold of $n × n$ skew-hermitian matrices.

source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::SkewSymmetricMatrices, p, X, V)
-Weingarten!(M::SkewSymmetricMatrices, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the SkewSymmetricMatrices M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

source
ManifoldsBase.check_point — Method
check_point(M::SkewHermitianMatrices, 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, 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)

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
GitHub

Skew-hermitian matrices

Manifolds.SkewHermitianMatrices — Type
SkewHermitianMatrices{T,𝔽} <: 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=ℝ; parameter::Symbol=:type)

Generate the manifold of $n × n$ skew-hermitian matrices.

source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::SkewSymmetricMatrices, p, X, V)
+Weingarten!(M::SkewSymmetricMatrices, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the SkewSymmetricMatrices M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

source
ManifoldsBase.check_point — Method
check_point(M::SkewHermitianMatrices, 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, 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)

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/PR673/manifolds/spdfixeddeterminant.html b/previews/PR673/manifolds/spdfixeddeterminant.html index a215a9d5c7..22a6a85915 100644 --- a/previews/PR673/manifolds/spdfixeddeterminant.html +++ b/previews/PR673/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; parameter::Symbol=:type)

Generate the manifold $\mathcal P_d(n) \subset \mathcal P(n)$ of determinant $d$, which defaults to 1.

parameter: whether a type parameter should be used to store n. By default size is stored in type. Value can either be :field or :type.

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, p, X)
-project!(M::SPDFixedDeterminant, 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, p)
-project!(M::SPDFixedDeterminant, 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; parameter::Symbol=:type)

Generate the manifold $\mathcal P_d(n) \subset \mathcal P(n)$ of determinant $d$, which defaults to 1.

parameter: whether a type parameter should be used to store n. By default size is stored in type. Value can either be :field or :type.

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, p, X)
+project!(M::SPDFixedDeterminant, 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, p)
+project!(M::SPDFixedDeterminant, 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/PR673/manifolds/spectrahedron.html b/previews/PR673/manifolds/spectrahedron.html index ca79b98585..1156fc3fb5 100644 --- a/previews/PR673/manifolds/spectrahedron.html +++ b/previews/PR673/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 [JBAS10].

Constructor

Spectrahedron(n::Int, k::Int; parameter::Symbol=:type)

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 [JBAS10].

Constructor

Spectrahedron(n::Int, k::Int; parameter::Symbol=:type)

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/PR673/manifolds/sphere-8cbfc3e4.svg b/previews/PR673/manifolds/sphere-3e0ce015.svg similarity index 93% rename from previews/PR673/manifolds/sphere-8cbfc3e4.svg rename to previews/PR673/manifolds/sphere-3e0ce015.svg index 66feae0a23..56147032ab 100644 --- a/previews/PR673/manifolds/sphere-8cbfc3e4.svg +++ b/previews/PR673/manifolds/sphere-3e0ce015.svg @@ -6,7 +6,7 @@ - 2023-11-04T15:36:39.558762 + 2023-11-04T16:26:01.149875 image/svg+xml @@ -384,7 +384,7 @@ L 346.422455 70.341599 - - - + + - - + + - - + + - - + + @@ -481,7 +481,7 @@ L 291.524544 156.694749 L 291.733205 160.106695 L 291.741904 160.948148 L 291.741904 160.948148 -" clip-path="url(#pb904d92211)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #c371d2; stroke-width: 1.5"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #c371d2; stroke-width: 1.5"/> +" clip-path="url(#pa2f17ff01d)" style="fill: none; stroke: #c371d2; stroke-width: 1.5"/> @@ -2755,7 +2755,7 @@ z - - + @@ -2825,7 +2825,7 @@ z - + diff --git a/previews/PR673/manifolds/sphere-b8a65f0d.svg b/previews/PR673/manifolds/sphere-5cd24113.svg similarity index 93% rename from previews/PR673/manifolds/sphere-b8a65f0d.svg rename to previews/PR673/manifolds/sphere-5cd24113.svg index 1bb3361157..ba8d2c184d 100644 --- a/previews/PR673/manifolds/sphere-b8a65f0d.svg +++ b/previews/PR673/manifolds/sphere-5cd24113.svg @@ -6,7 +6,7 @@ - 2023-11-04T15:36:36.646414 + 2023-11-04T16:25:58.699954 image/svg+xml @@ -384,7 +384,7 @@ L 346.422455 70.341599 - - - + + - - + + - - + + - - + + @@ -443,7 +443,7 @@ L 240.694477 197.834141 L 233.847468 197.143894 L 226.865322 195.9051 L 219.81528 194.129688 -" clip-path="url(#pb8da18083c)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p38e864a94b)" style="fill: none; stroke: #cccccc"/> @@ -2666,7 +2666,7 @@ z - - + @@ -2736,7 +2736,7 @@ z - + diff --git a/previews/PR673/manifolds/sphere-9a499769.svg b/previews/PR673/manifolds/sphere-7b10dfde.svg similarity index 93% rename from previews/PR673/manifolds/sphere-9a499769.svg rename to previews/PR673/manifolds/sphere-7b10dfde.svg index 5df44b37f7..34d9c7347a 100644 --- a/previews/PR673/manifolds/sphere-9a499769.svg +++ b/previews/PR673/manifolds/sphere-7b10dfde.svg @@ -6,7 +6,7 @@ - 2023-11-04T15:36:38.291584 + 2023-11-04T16:26:00.091109 image/svg+xml @@ -384,7 +384,7 @@ L 346.422455 70.341599 - - - + + - - + + - - + + - - + + @@ -481,7 +481,7 @@ L 291.524544 156.694749 L 291.733205 160.106695 L 291.741904 160.948148 L 291.741904 160.948148 -" clip-path="url(#p9e929f2540)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #3ea44e; stroke-width: 2"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> +" clip-path="url(#p734fffc8b4)" style="fill: none; stroke: #cccccc"/> @@ -2740,7 +2740,7 @@ z - - + @@ -2810,7 +2810,7 @@ z - + diff --git a/previews/PR673/manifolds/sphere.html b/previews/PR673/manifolds/sphere.html index 3e42ef9d78..bfa147d40c 100644 --- a/previews/PR673/manifolds/sphere.html +++ b/previews/PR673/manifolds/sphere.html @@ -1,17 +1,17 @@ -Sphere · Manifolds.jl
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{T,𝔽} <: 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=ℝ, parameter::Symbol=:type)

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 [CLLD22].

source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::Sphere, p, X, V)
-Weingarten!(M::Sphere, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Sphere M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

The formula is due to [AMT13] given by

\[\mathcal W_p(X,V) = -Xp^{\mathrm{T}}V\]

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
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::AbstractSphere{ℝ}, p, X, Y, Z)

Compute the Riemann tensor $R(X,Y)Z$ at point p on AbstractSphere M. The formula reads [MF12] (though note that a different convention is used in that paper than in Manifolds.jl):

\[R(X,Y)Z = \langle Z, Y \rangle X - \langle Z, X \rangle Y\]

source
Statistics.mean — Method
mean(
+Sphere · Manifolds.jl
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{T,𝔽} <: 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=ℝ, parameter::Symbol=:type)
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 [CLLD22].
source
ManifoldsBase.Weingarten — Method
Y = Weingarten(M::Sphere, p, X, V)
+Weingarten!(M::Sphere, Y, p, X, V)
Compute the Weingarten map $\mathcal W_p$ at p on the Sphere M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.
The formula is due to [AMT13] given by
\[\mathcal W_p(X,V) = -Xp^{\mathrm{T}}V\]
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
ManifoldsBase.riemann_tensor — Method
riemann_tensor(M::AbstractSphere{ℝ}, p, X, Y, Z)
Compute the Riemann tensor $R(X,Y)Z$ at point p on AbstractSphere M. The formula reads [MF12] (though note that a different convention is used in that paper than in Manifolds.jl):
\[R(X,Y)Z = \langle Z, Y \rangle X - \langle Z, X \rangle Y\]
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] ]
-scene = plot(M, pts; wireframe_color=colorant"#CCCCCC", markersize=10)
Example block output

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.

plot!(scene, M, pts; wireframe=false, geodesic_interpolation=100, linewidth=2)
Example block output

And we can also add tangent vectors, for example tangents pointing towards the geometric center of given points.

pts2 =  [ [1.0, 0.0, 0.0], [0.0, -1.0, 0.0], [0.0, 0.0, 1.0] ]
+scene = plot(M, pts; wireframe_color=colorant"#CCCCCC", markersize=10)
Example block output

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.

plot!(scene, M, pts; wireframe=false, geodesic_interpolation=100, linewidth=2)
Example block output

And we can also add tangent vectors, for example tangents pointing towards the geometric center of given points.

pts2 =  [ [1.0, 0.0, 0.0], [0.0, -1.0, 0.0], [0.0, 0.0, 1.0] ]
 p3 = 1/sqrt(3) .* [1.0, -1.0, 1.0]
 vecs = log.(Ref(M), pts2, Ref(p3))
-plot!(scene, M, pts2, vecs; wireframe = false, linewidth=1.5)
Example block output

Literature

[AMT13]
P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
[CLLD22]
E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
[MF12]
P. Muralidharan and P. T. Fletcher. Sasaki metrics for analysis of longitudinal data on manifolds. In: 2012 IEEE Conference on Computer Vision and Pattern Recognition (2012).
+plot!(scene, M, pts2, vecs; wireframe = false, linewidth=1.5)Example block output

Literature

[AMT13]
P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
[CLLD22]
E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
[MF12]
P. Muralidharan and P. T. Fletcher. Sasaki metrics for analysis of longitudinal data on manifolds. In: 2012 IEEE Conference on Computer Vision and Pattern Recognition (2012).
diff --git a/previews/PR673/manifolds/spheresymmetricmatrices.html b/previews/PR673/manifolds/spheresymmetricmatrices.html index 6aad39916a..f0f962b7f1 100644 --- a/previews/PR673/manifolds/spheresymmetricmatrices.html +++ b/previews/PR673/manifolds/spheresymmetricmatrices.html @@ -1,5 +1,5 @@ -Unit-norm symmetric matrices · Manifolds.jl
GitHub

Unit-norm symmetric matrices

Manifolds.SphereSymmetricMatrices — Type
SphereSymmetricMatrices{T,𝔽} <: 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, 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, 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{<:Any,𝔽})

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

GitHub

Unit-norm symmetric matrices

Manifolds.SphereSymmetricMatrices — Type
SphereSymmetricMatrices{T,𝔽} <: 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, 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, 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{<:Any,𝔽})

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/PR673/manifolds/stiefel.html b/previews/PR673/manifolds/stiefel.html index ed873761e2..d964a49293 100644 --- a/previews/PR673/manifolds/stiefel.html +++ b/previews/PR673/manifolds/stiefel.html @@ -1,28 +1,28 @@ -Stiefel · Manifolds.jl
GitHub

Stiefel

Common and metric independent functions

Manifolds.Stiefel — Type
Stiefel{T,𝔽} <: 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=ℝ; parameter::Symbol=:type)

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{<:Any,ℝ}, 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 [Chi03]; see also Theorem 2.2.1(iii) in [Chi03].

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.inverse_retract — Method
inverse_retract(M::Stiefel, p, q, ::QRInverseRetraction)

Compute 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 [KFT13].

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

GitHub

Stiefel

Common and metric independent functions

Manifolds.Stiefel — Type
Stiefel{T,𝔽} <: 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=ℝ; parameter::Symbol=:type)

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{<:Any,ℝ}, 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 [Chi03]; see also Theorem 2.2.1(iii) in [Chi03].

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.inverse_retract — Method
inverse_retract(M::Stiefel, p, q, ::QRInverseRetraction)

Compute 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 [KFT13].

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[Zhu16]. 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[Zhu16]. 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$ [ZD18]. 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$ [ZD18]. 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. [Zhu16] 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. [Zhu16] 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 [Zhu16]:

\[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 [AMS08], p. 173, or Section 3.5 of [Zhu16].

\[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 [Zhu16]:

\[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 [AMS08], p. 173, or Section 3.5 of [Zhu16].

\[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 [HGA15] or Section 3.5 of [Zhu16]:

\[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 [AMS08], p. 173, or Section 3.5 of [Zhu16].

\[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 [HGA15] or Section 3.5 of [Zhu16]:

\[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 [AMS08], p. 173, or Section 3.5 of [Zhu16].

\[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,16 +30,16 @@ \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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::Stiefel, p, G, H, X)
+\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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::Stiefel, p, G, H, X)
 riemannian_Hessian!(M::Stiefel, Y, p, G, H, X)

Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.

Here, we adopt Eq. (5.6) [Ngu23], where we use for the EuclideanMetric $α_0=α_1=1$ in their formula. Then the formula reads

\[ \operatorname{Hess}f(p)[X] = \operatorname{proj}_{T_p\mathcal M}\Bigl( ∇^2f(p)[X] - \frac{1}{2} X \bigl((∇f(p))^{\mathrm{H}}p + p^{\mathrm{H}}∇f(p)\bigr) - \Bigr).\]

Compared to Eq. (5.6) also the metric conversion simplifies to the identity.

source
ManifoldsBase.Weingarten — Method
Weingarten(M::Stiefel, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Stiefel M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

The formula is due to [AMT13] given by

\[\mathcal W_p(X,V) = -Xp^{\mathrm{H}}V - \frac{1}{2}p\bigl(X^\mathrm{H}V + V^{\mathrm{H}}X\bigr)\]

source
ManifoldsBase.get_basis — Method
get_basis(M::Stiefel{<:Any,ℝ}, p, B::DefaultOrthonormalBasis)

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}_{T_p\mathcal M}(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, + \Bigr).\]

Compared to Eq. (5.6) also the metric conversion simplifies to the identity.

source
ManifoldsBase.Weingarten — Method
Weingarten(M::Stiefel, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the Stiefel M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

The formula is due to [AMT13] given by

\[\mathcal W_p(X,V) = -Xp^{\mathrm{H}}V - \frac{1}{2}p\bigl(X^\mathrm{H}V + V^{\mathrm{H}}X\bigr)\]

source
ManifoldsBase.get_basis — Method
get_basis(M::Stiefel{<:Any,ℝ}, p, B::DefaultOrthonormalBasis)

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}_{T_p\mathcal M}(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{<:Any,ℝ},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{<:Any,ℝ},CanonicalMetric}, p, X)
 exp!(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},CanonicalMetric}, q, 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}
@@ -49,24 +49,24 @@
 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 [EAS98][Zim17].
source
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::MetricManifold{ℝ, Stiefel, CanonicalMetric}, p, G, H, X)
+\begin{pmatrix}I_k\\0\end{pmatrix}\]
the exponential map reads
\[q = \exp_p X = pC + QB.\]
For more details, see [EAS98][Zim17].
source
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::MetricManifold{ℝ, Stiefel, CanonicalMetric}, p, G, H, X)
 riemannian_Hessian!(M::MetricManifold{ℝ, Stiefel, CanonicalMetric}, Y, p, G, H, X)
Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.
Here, we adopt Eq. (5.6) [Ngu23], for the CanonicalMetric $α_0=1, α_1=\frac{1}{2}$ in their formula. The formula reads
\[    \operatorname{Hess}f(p)[X]
     =
     \operatorname{proj}_{T_p\mathcal M}\Bigl(
         ∇^2f(p)[X] - \frac{1}{2} X \bigl( (∇f(p))^{\mathrm{H}}p + p^{\mathrm{H}}∇f(p)\bigr)
         - \frac{1}{2} \bigl( P ∇f(p) p^{\mathrm{H}} + p ∇f(p))^{\mathrm{H}} P)X
-    \Bigr),\]
where $P = I-pp^{\mathrm{H}}$.
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ, Stiefel{<:Any,ℝ}, 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{<:Any,ℝ}, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)
-inverse_retract!(M::MetricManifold{ℝ, Stiefel{<:Any,ℝ}, 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 [Zim17] 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 [HML21]. This implementation follows the description in [ZH22].
Constructor
StiefelSubmersionMetric(α)
Construct the submersion metric on the Stiefel manifold with the parameter $α$.
source
Base.exp — Method
q = exp(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},<:StiefelSubmersionMetric}, p, X)
+    \Bigr),\]
where $P = I-pp^{\mathrm{H}}$.
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ, Stiefel{<:Any,ℝ}, 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{<:Any,ℝ}, CanonicalMetric}, p, q, a::ApproximateLogarithmicMap)
+inverse_retract!(M::MetricManifold{ℝ, Stiefel{<:Any,ℝ}, 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 [Zim17] 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 [HML21]. This implementation follows the description in [ZH22].
Constructor
StiefelSubmersionMetric(α)
Construct the submersion metric on the Stiefel manifold with the parameter $α$.
source
Base.exp — Method
q = exp(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},<:StiefelSubmersionMetric}, p, X)
 exp!(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},<:StiefelSubmersionMetric}, q, 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 [ZH22].
For $k < \frac{n}{2}$ the exponential is computed more efficiently using StiefelFactorization.
source
Base.log — Method
log(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},<: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 [ZH22]. 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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},StiefelSubmersionMetric}, p, G, H, X)
+\bigr) p \operatorname{Exp}\bigl(\frac{\alpha}{\alpha+1} p^\mathrm{T} X\bigr)\]
This implementation is based on [ZH22].
For $k < \frac{n}{2}$ the exponential is computed more efficiently using StiefelFactorization.
source
Base.log — Method
log(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},<: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 [ZH22]. 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
ManifoldDiff.riemannian_Hessian — Method
Y = riemannian_Hessian(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},StiefelSubmersionMetric}, p, G, H, X)
 riemannian_Hessian!(MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},StiefelSubmersionMetric}, Y, p, G, H, X)
Compute the Riemannian Hessian $\operatorname{Hess} f(p)[X]$ given the Euclidean gradient $∇ f(\tilde p)$ in G and the Euclidean Hessian $∇^2 f(\tilde p)[\tilde X]$ in H, where $\tilde p, \tilde X$ are the representations of $p,X$ in the embedding,.
Here, we adopt Eq. (5.6) [Ngu23], for the CanonicalMetric $α_0=1, α_1=\frac{1}{2}$ in their formula. The formula reads
\[    \operatorname{Hess}f(p)[X]
     =
     \operatorname{proj}_{T_p\mathcal M}\Bigl(
         ∇^2f(p)[X] - \frac{1}{2} X \bigl( (∇f(p))^{\mathrm{H}}p + p^{\mathrm{H}}∇f(p)\bigr)
         - \frac{2α+1}{2(α+1)} \bigl( P ∇f(p) p^{\mathrm{H}} + p ∇f(p))^{\mathrm{H}} P)X
-    \Bigr),\]
where $P = I-pp^{\mathrm{H}}$.
Compared to Eq. (5.6) we have that their $α_0 = 1$and $\alpha_1 =  \frac{2α+1}{2(α+1)} + 1$.
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},<: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(
+    \Bigr),\]
where $P = I-pp^{\mathrm{H}}$.
Compared to Eq. (5.6) we have that their $α_0 = 1$and $\alpha_1 =  \frac{2α+1}{2(α+1)} + 1$.
source
ManifoldsBase.inner — Method
inner(M::MetricManifold{ℝ,<:Stiefel{<:Any,ℝ},<: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{<:Any,ℝ},<:StiefelSubmersionMetric},
     p,
     q,
@@ -80,7 +80,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 [ZH22].
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 [ZH22].

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}. @@ -88,4 +88,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

[AMT13]
P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
[AMS08]
P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
[Chi03]
Y. Chikuse. Statistics on Special Manifolds (Springer New York, 2003).
[EAS98]
A. Edelman, T. A. Arias and S. T. Smith. The Geometry of Algorithms with Orthogonality Constraints. SIAM Journal on Matrix Analysis and Applications 20, 303–353 (1998), arXiv:806030.
[HGA15]
W. Huang, K. A. Gallivan and P.-A. Absil. A Broyden Class of Quasi-Newton Methods for Riemannian Optimization. SIAM Journal on Optimization 25, 1660–1685 (2015).
[HML21]
K. Hüper, I. Markina and F. S. Leite. A Lagrangian approach to extremal curves on Stiefel manifolds. Journal of Geometric Mechanics 13, 55 (2021).
[KFT13]
T. Kaneko, S. Fiori and T. Tanaka. Empirical Arithmetic Averaging Over the Compact Stiefel Manifold. IEEE Transactions on Signal Processing 61, 883–894 (2013).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Zhu16]
X. Zhu. A Riemannian conjugate gradient method for optimization on the Stiefel manifold. Computational Optimization and Applications 67, 73–110 (2016).
[ZD18]
X. Zhu and C. Duan. On matrix exponentials and their approximations related to optimization on the Stiefel manifold. Optimization Letters 13, 1069–1083 (2018).
[Zim17]
R. Zimmermann. A Matrix-Algebraic Algorithm for the Riemannian Logarithm on the Stiefel Manifold under the Canonical Metric. SIAM J. Matrix Anal. Appl. 38, 322–342 (2017), arXiv:1604.05054.
[ZH22]
R. Zimmermann and K. Hüper. Computing the Riemannian Logarithm on the Stiefel Manifold: Metrics, Methods, and Performance. SIAM Journal on Matrix Analysis and Applications 43, 953–980 (2022), arXiv:2103.12046.
+\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

[AMT13]
P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
[AMS08]
P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
[Chi03]
Y. Chikuse. Statistics on Special Manifolds (Springer New York, 2003).
[EAS98]
A. Edelman, T. A. Arias and S. T. Smith. The Geometry of Algorithms with Orthogonality Constraints. SIAM Journal on Matrix Analysis and Applications 20, 303–353 (1998), arXiv:806030.
[HGA15]
W. Huang, K. A. Gallivan and P.-A. Absil. A Broyden Class of Quasi-Newton Methods for Riemannian Optimization. SIAM Journal on Optimization 25, 1660–1685 (2015).
[HML21]
K. Hüper, I. Markina and F. S. Leite. A Lagrangian approach to extremal curves on Stiefel manifolds. Journal of Geometric Mechanics 13, 55 (2021).
[KFT13]
T. Kaneko, S. Fiori and T. Tanaka. Empirical Arithmetic Averaging Over the Compact Stiefel Manifold. IEEE Transactions on Signal Processing 61, 883–894 (2013).
[Ngu23]
D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
[Zhu16]
X. Zhu. A Riemannian conjugate gradient method for optimization on the Stiefel manifold. Computational Optimization and Applications 67, 73–110 (2016).
[ZD18]
X. Zhu and C. Duan. On matrix exponentials and their approximations related to optimization on the Stiefel manifold. Optimization Letters 13, 1069–1083 (2018).
[Zim17]
R. Zimmermann. A Matrix-Algebraic Algorithm for the Riemannian Logarithm on the Stiefel Manifold under the Canonical Metric. SIAM J. Matrix Anal. Appl. 38, 322–342 (2017), arXiv:1604.05054.
[ZH22]
R. Zimmermann and K. Hüper. Computing the Riemannian Logarithm on the Stiefel Manifold: Metrics, Methods, and Performance. SIAM Journal on Matrix Analysis and Applications 43, 953–980 (2022), arXiv:2103.12046.
diff --git a/previews/PR673/manifolds/symmetric.html b/previews/PR673/manifolds/symmetric.html index cd071e2cbe..34ffd34a10 100644 --- a/previews/PR673/manifolds/symmetric.html +++ b/previews/PR673/manifolds/symmetric.html @@ -1,6 +1,6 @@ -Symmetric matrices · Manifolds.jl
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.Weingarten — Method
Y = Weingarten(M::SymmetricMatrices, p, X, V)
-Weingarten!(M::SymmetricMatrices, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the SymmetricMatrices M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

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

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.Weingarten — Method
Y = Weingarten(M::SymmetricMatrices, p, X, V)
+Weingarten!(M::SymmetricMatrices, Y, p, X, V)

Compute the Weingarten map $\mathcal W_p$ at p on the SymmetricMatrices M with respect to the tangent vector $X \in T_p\mathcal M$ and the normal vector $V \in N_p\mathcal M$.

Since this a flat space by itself, the result is always the zero tangent vector.

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/PR673/manifolds/symmetricpositivedefinite.html b/previews/PR673/manifolds/symmetricpositivedefinite.html index 8d13ce4de2..459d0d6530 100644 --- a/previews/PR673/manifolds/symmetricpositivedefinite.html +++ b/previews/PR673/manifolds/symmetricpositivedefinite.html @@ -5,26 +5,26 @@ \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; parameter::Symbol=:type)

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; parameter::Symbol=:type)
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,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,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
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::SymmetricPositiveDefinite, p, G, H, X)

The Riemannian Hessian can be computed as stated in Eq. (7.3) [Ngu23]. Let $\nabla f(p)$ denote the Euclidean gradient G, $\nabla^2 f(p)[X]$ the Euclidean Hessian H, and $\operatorname{sym}(X) = \frac{1}{2}\bigl(X^{\mathrm{T}}+X\bigr)$ the symmetrization operator. Then the formula reads

\[ \operatorname{Hess}f(p)[X] +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
ManifoldDiff.riemannian_Hessian — Method
riemannian_Hessian(M::SymmetricPositiveDefinite, p, G, H, X)

The Riemannian Hessian can be computed as stated in Eq. (7.3) [Ngu23]. Let $\nabla f(p)$ denote the Euclidean gradient G, $\nabla^2 f(p)[X]$ the Euclidean Hessian H, and $\operatorname{sym}(X) = \frac{1}{2}\bigl(X^{\mathrm{T}}+X\bigr)$ the symmetrization operator. Then the formula reads

\[ \operatorname{Hess}f(p)[X] = p\operatorname{sym}(∇^2 f(p)[X])p - + \operatorname{sym}\bigl( X\operatorname{sym}\bigl(∇ f(p)\bigr)p)\]

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

Compute the volume density of the SymmetricPositiveDefinite manifold at p in direction X. See [CKA17], Section 6.2 for details. Note that metric in Manifolds.jl has a different scaling factor than the reference.

source
ManifoldsBase.change_metric — Method
change_metric(M::SymmetricPositiveDefinite, 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)
+    + \operatorname{sym}\bigl( X\operatorname{sym}\bigl(∇ f(p)\bigr)p)\]
source
Manifolds.volume_density — Method
volume_density(::SymmetricPositiveDefinite, p, X)

Compute the volume density of the SymmetricPositiveDefinite manifold at p in direction X. See [CKA17], Section 6.2 for details. Note that metric in Manifolds.jl has a different scaling factor than the reference.

source
ManifoldsBase.change_metric — Method
change_metric(M::SymmetricPositiveDefinite, 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,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,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,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}} @@ -33,22 +33,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 [Ren11] $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 [HMJG21].

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,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 [Ren11] $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 [HMJG21].

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,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{ℝ,<:SymmetricPositiveDefinite,LogCholeskyMetric}, 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{ℝ,<:SymmetricPositiveDefinite,LogCholeskyMetric}, 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

+)

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

diff --git a/previews/PR673/manifolds/symmetricpsdfixedrank.html b/previews/PR673/manifolds/symmetricpsdfixedrank.html index b8f421e69f..5969e947a3 100644 --- a/previews/PR673/manifolds/symmetricpsdfixedrank.html +++ b/previews/PR673/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 [JBAS10][MA20].

Constructor

SymmetricPositiveSemidefiniteFixedRank(n::Int, k::Int, field::AbstractNumbers=ℝ; parameter::Symbol=:type)

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, 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.manifold_dimension — Method
manifold_dimension(M::SymmetricPositiveSemidefiniteFixedRank)

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 [JBAS10][MA20].

Constructor

SymmetricPositiveSemidefiniteFixedRank(n::Int, k::Int, field::AbstractNumbers=ℝ; parameter::Symbol=:type)

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, 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.manifold_dimension — Method
manifold_dimension(M::SymmetricPositiveSemidefiniteFixedRank)

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/PR673/manifolds/symplectic.html b/previews/PR673/manifolds/symplectic.html index 484cdbe0a5..579b1ca7fa 100644 --- a/previews/PR673/manifolds/symplectic.html +++ b/previews/PR673/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 [Fio11]]

\[\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 [Fio11]]

\[\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{T, 𝔽} <: 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{T, 𝔽} <: 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=ℝ; parameter::Symbol=:type)

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=ℝ; parameter::Symbol=:type)

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 [WSF18]

\[ \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$ [Fio11]]. 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 [GSAS21]

\[\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(MetMan::MetricManifold{<:Any, <:Euclidean, ExtendedSymplecticMetric},
+         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$ [Fio11]]. 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 [GSAS21]

\[\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(MetMan::MetricManifold{<:Any, <:Euclidean, ExtendedSymplecticMetric},
                    EucMet::EuclideanMetric, p, X)
 change_representer!(MetMan::MetricManifold{<:Any, <:Euclidean, 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.change_representer — Method
change_representer(::Symplectic, ::EuclideanMetric, p, X)
+        \;∀\; η ∈ T_p\operatorname{Sp}(2n, ℝ).\]
In this case, we compute the mapping
\[    c_p(ξ) = pp^{\mathrm{T}} ξ.\]
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.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} = + 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.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 [WSF18].

\[ \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 [WSF18].

\[ \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{<:Any,ℝ}, 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$ [BZ21].

First, recall the definition the standard symplectic matrix

\[Q = + \end{align*}\]

source
ManifoldsBase.inner — Method
inner(::Symplectic{<:Any,ℝ}, 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$ [BZ21].

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).\]

[BZ21]: > Bendokat, Thomas and Zimmermann, Ralf: > The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications > arXiv preprint arXiv:2108.12447, 2021.

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(::Symplectic)

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 [GSAS21]

\[ \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)
+                                        ∈ T_p\operatorname{Sp}(2n).\]
[BZ21]:     > Bendokat, Thomas and Zimmermann, Ralf: 	> The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications 	> arXiv preprint arXiv:2108.12447, 2021.
source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(::Symplectic)

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 [GSAS21]

\[ \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 [BCC20].

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

[BZ21]
T. Bendokat and R. Zimmermann. The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications, arXiv Preprint, 2108.12447 (2021).
[BCC20]
P. Birtea, I. Caçu and D. Comănescu. Optimization on the real symplectic group. Monatshefte für Mathematik 191, 465–485 (2020).
[Fio11]
S. Fiori. Solving Minimal-Distance Problems over the Manifold of Real-Symplectic Matrices. SIAM Journal on Matrix Analysis and Applications 32, 938–968 (2011).
[GSAS21]
B. Gao, N. T. Son, P.-A. Absil and T. Stykel. Riemannian Optimization on the Symplectic Stiefel Manifold. SIAM Journal on Optimization 31, 1546–1575 (2021).
[WSF18]
J. Wang, H. Sun and S. Fiori. A Riemannian-steepest-descent approach for optimization on the real symplectic group. Mathematical Methods in the Applied Science 41, 4273–4286 (2018).
+\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

[BZ21]
T. Bendokat and R. Zimmermann. The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications, arXiv Preprint, 2108.12447 (2021).
[BCC20]
P. Birtea, I. Caçu and D. Comănescu. Optimization on the real symplectic group. Monatshefte für Mathematik 191, 465–485 (2020).
[Fio11]
S. Fiori. Solving Minimal-Distance Problems over the Manifold of Real-Symplectic Matrices. SIAM Journal on Matrix Analysis and Applications 32, 938–968 (2011).
[GSAS21]
B. Gao, N. T. Son, P.-A. Absil and T. Stykel. Riemannian Optimization on the Symplectic Stiefel Manifold. SIAM Journal on Optimization 31, 1546–1575 (2021).
[WSF18]
J. Wang, H. Sun and S. Fiori. A Riemannian-steepest-descent approach for optimization on the real symplectic group. Mathematical Methods in the Applied Science 41, 4273–4286 (2018).
diff --git a/previews/PR673/manifolds/symplecticstiefel.html b/previews/PR673/manifolds/symplecticstiefel.html index d2255573cd..d7808034b0 100644 --- a/previews/PR673/manifolds/symplecticstiefel.html +++ b/previews/PR673/manifolds/symplecticstiefel.html @@ -14,7 +14,7 @@ = \{&X = pΩ + p^sB \;|\; Ω ∈ ℝ^{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=ℝ; parameter::Symbol=:type)

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)
+    \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=ℝ; parameter::Symbol=:type)
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$ [BZ21], 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} @@ -33,7 +33,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, 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, A)
 inv!(::SymplecticStiefel, q, p)

Compute the symplectic inverse $A^+$ of matrix $A ∈ ℝ^{2n × 2k}$. Given a matrix

\[A ∈ ℝ^{2n × 2k},\quad A = \begin{bmatrix} @@ -47,21 +47,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, 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 [BZ21].

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, 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 [BZ21].

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 [BZ21],

\[ 𝔤_{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, 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 [BZ21].

\[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 [BZ21],

\[ 𝔤_{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, 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 [BZ21].

\[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$ [BZ21].

First, recall the definition the standard symplectic matrix

\[Q = \begin{bmatrix} 0 & I \\ @@ -69,9 +69,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.manifold_dimension — Method
manifold_dimension(::SymplecticStiefel)

Returns the dimension of the symplectic Stiefel manifold embedded in $ℝ^{2n \times 2k}$, i.e. [BZ21]

\[ \operatorname{dim}(\operatorname{SpSt}(2n, 2k)) = (4n - 2k + 1)k.\]

source
ManifoldsBase.manifold_dimension — Method
manifold_dimension(::SymplecticStiefel)

Returns the dimension of the symplectic Stiefel manifold embedded in $ℝ^{2n \times 2k}$, i.e. [BZ21]

\[ \operatorname{dim}(\operatorname{SpSt}(2n, 2k)) = (4n - 2k + 1)k.\]

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 [BZ21]. 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 [BZ21].

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

[BZ21]
T. Bendokat and R. Zimmermann. The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications, arXiv Preprint, 2108.12447 (2021).
+ pX^+\left(I_{2n} - \frac{1}{2}pp^+\right) \in ℝ^{2n \times 2n},\]

as shown in Proposition 3.5 of [BZ21]. 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 [BZ21].

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

[BZ21]
T. Bendokat and R. Zimmermann. The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications, arXiv Preprint, 2108.12447 (2021).
diff --git a/previews/PR673/manifolds/torus.html b/previews/PR673/manifolds/torus.html index 73923b439b..5c84bbc96a 100644 --- a/previews/PR673/manifolds/torus.html +++ b/previews/PR673/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/PR673/manifolds/tucker.html b/previews/PR673/manifolds/tucker.html index e0d8909082..e244856b19 100644 --- a/previews/PR673/manifolds/tucker.html +++ b/previews/PR673/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=ℝ]; parameter::Symbol=:type)

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 [VVM12].

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=ℝ]; parameter::Symbol=:type)

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 [VVM12].

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 [DBV21] 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, p; kwargs...)

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{<:Any,D}, p::TuckerPoint{T,D}, X::TuckerTVector) where {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, p::TuckerPoint, X::TuckerTVector)

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: [DBV21]

\[\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 [DBV21] 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, p; kwargs...)

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{<:Any,D}, p::TuckerPoint{T,D}, X::TuckerTVector) where {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, p::TuckerPoint, X::TuckerTVector)

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: [DBV21]

\[\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)

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 [KSV13] 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

+\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)

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 [KSV13] 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

diff --git a/previews/PR673/manifolds/vector_bundle.html b/previews/PR673/manifolds/vector_bundle.html index a267627172..808547ad7d 100644 --- a/previews/PR673/manifolds/vector_bundle.html +++ b/previews/PR673/manifolds/vector_bundle.html @@ -1,8 +1,8 @@ -Vector bundle · Manifolds.jl
GitHub

Vector bundles

Vector bundle $E$ is a special case of a fiber bundle where each fiber is a vector space.

Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point $p$. An object representing a tangent bundle can be obtained using the constructor called TangentBundle.

There is also another type, VectorSpaceFiber, that represents a specific fiber at a given point. 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.TensorProductType — Type
TensorProductType(spaces::VectorSpaceType...)

Vector space type corresponding to the tensor product of given vector space types.

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 [Sas58].

Exact retraction and inverse retraction can be approximated using FiberBundleProductRetraction, FiberBundleInverseProductRetraction and SasakiRetraction. FiberBundleProductVectorTransport can be used as a vector transport.

Constructors

TangentBundle(M::AbstractManifold)
-TangentBundle(M::AbstractManifold, vtm::FiberBundleProductVectorTransport)
source
Manifolds.VectorBundle — Type
VectorBundle{𝔽,TVS,TM,VTV} = FiberBundle{𝔽,TVS,TM,TVT} where {TVS<:VectorSpaceType}

Alias for FiberBundle when fiber type is a TVS of type [VectorSpaceType]https://juliamanifolds.github.io/ManifoldsBase.jl/stable/bases/#ManifoldsBase.VectorSpaceType).

VectorSpaceFiberType is used to encode vector spaces as fiber types.

source
Manifolds.fiber_bundle_transport — Method
fiber_bundle_transport(M::AbstractManifold, fiber::FiberType)

Determine the vector transport used for exp and log maps on a vector bundle with fiber type fiber and manifold 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.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

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
+Vector bundle · Manifolds.jl
GitHub
Vector bundles
Vector bundle $E$ is a special case of a fiber bundle where each fiber is a vector space.
Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point $p$. An object representing a tangent bundle can be obtained using the constructor called TangentBundle.
There is also another type, VectorSpaceFiber, that represents a specific fiber at a given point. 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.TensorProductType — Type
TensorProductType(spaces::VectorSpaceType...)
Vector space type corresponding to the tensor product of given vector space types.
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 [Sas58].
Exact retraction and inverse retraction can be approximated using FiberBundleProductRetraction, FiberBundleInverseProductRetraction and SasakiRetraction. FiberBundleProductVectorTransport can be used as a vector transport.
Constructors
TangentBundle(M::AbstractManifold)
+TangentBundle(M::AbstractManifold, vtm::FiberBundleProductVectorTransport)
source
Manifolds.VectorBundle — Type
VectorBundle{𝔽,TVS,TM,VTV} = FiberBundle{𝔽,TVS,TM,TVT} where {TVS<:VectorSpaceType}
Alias for FiberBundle when fiber type is a TVS of type [VectorSpaceType]https://juliamanifolds.github.io/ManifoldsBase.jl/stable/bases/#ManifoldsBase.VectorSpaceType).
VectorSpaceFiberType is used to encode vector spaces as fiber types.
source
Manifolds.fiber_bundle_transport — Method
fiber_bundle_transport(M::AbstractManifold, fiber::FiberType)
Determine the vector transport used for exp and log maps on a vector bundle with fiber type fiber and manifold 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.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
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 = ArrayPartition([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])
 X = ArrayPartition([0.0, 1.0, 0.0], [0.0, 0.0, -2.0])
([0.0, 1.0, 0.0], [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: ArrayPartition{Float64, Tuple{Vector{Float64}, Vector{Float64}}}(([0.6759570857309881, 0.352414864043865, 0.6472138609849256], [-1.031826958326108, 0.6273324630574114, 0.7360618920075952]))

+println("Approximation of the exponential map: ", q)
Approximation of the exponential map: ArrayPartition{Float64, Tuple{Vector{Float64}, Vector{Float64}}}(([0.6759570857309881, 0.352414864043865, 0.6472138609849256], [-1.031826958326108, 0.6273324630574114, 0.7360618920075952]))
diff --git a/previews/PR673/misc/CONTRIBUTING.html b/previews/PR673/misc/CONTRIBUTING.html index 1bb8d861f3..c576b29654 100644 --- a/previews/PR673/misc/CONTRIBUTING.html +++ b/previews/PR673/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/PR673/misc/NEWS.html b/previews/PR673/misc/NEWS.html index f75915ad1b..6777cd7914 100644 --- a/previews/PR673/misc/NEWS.html +++ b/previews/PR673/misc/NEWS.html @@ -13,4 +13,4 @@ else return print(io, "CenteredMatrices($m, $n; parameter=:field)") end -end

  • Argument order for type aliases RotationActionOnVector and RotationTranslationActionOnVector: most often dispatched on argument is now first.

  • A more consistent handling of action direction was introduced. 4-valued ActionDirection was split into 2-valued ActionDirection (either left or right action) and GroupActionSide (action acting from the left or right side). See https://github.com/JuliaManifolds/Manifolds.jl/issues/637 for a design discussion.

    • Removed

    • ProductRepr is removed; please use ArrayPartition instead.
    • Default methods throwing "not implemented" ErrorException for some group-related operations. Standard MethodError is now thrown instead.
    • LinearAffineMetric was deprecated in a previous release and the symbol is now removed. Please use AffineInvariantMetric instead.
    +end

  • Argument order for type aliases RotationActionOnVector and RotationTranslationActionOnVector: most often dispatched on argument is now first.

  • A more consistent handling of action direction was introduced. 4-valued ActionDirection was split into 2-valued ActionDirection (either left or right action) and GroupActionSide (action acting from the left or right side). See https://github.com/JuliaManifolds/Manifolds.jl/issues/637 for a design discussion.

    • Removed

    • ProductRepr is removed; please use ArrayPartition instead.
    • Default methods throwing "not implemented" ErrorException for some group-related operations. Standard MethodError is now thrown instead.
    • LinearAffineMetric was deprecated in a previous release and the symbol is now removed. Please use AffineInvariantMetric instead.
    diff --git a/previews/PR673/misc/about.html b/previews/PR673/misc/about.html index 3db3662169..3ba1b13588 100644 --- a/previews/PR673/misc/about.html +++ b/previews/PR673/misc/about.html @@ -1,2 +1,2 @@ -About · Manifolds.jl
    GitHub
    +About · Manifolds.jl
    GitHub
    diff --git a/previews/PR673/misc/internals.html b/previews/PR673/misc/internals.html index 185ce08970..b80b972c2c 100644 --- a/previews/PR673/misc/internals.html +++ b/previews/PR673/misc/internals.html @@ -1,8 +1,8 @@ -Internals · Manifolds.jl
    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

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

    Types in Extensions

    +]
    source

    Types in Extensions

    diff --git a/previews/PR673/misc/notation.html b/previews/PR673/misc/notation.html index 217fec59c4..8176634c39 100644 --- a/previews/PR673/misc/notation.html +++ b/previews/PR673/misc/notation.html @@ -1,2 +1,2 @@ -Notation · Manifolds.jl
    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 Fiber
    $\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$.
    $\operatorname{grad} f(p)$(Riemannian) gradient of function $f \colon \mathcal{M} \to \mathbb{R}$ at $p \in \mathcal{M}$
    $\nabla f(p)$(Euclidean) gradient of function $f \colon \mathcal{M} \to \mathbb{R}$ at $p \in \mathcal{M}$ but thought of as evaluated in the embeddingG
    $\circ$a group operation
    $\cdot^\mathrm{H}$Hermitian or conjugate transposed for both complex or quaternion matrices
    $\operatorname{Hess} f(p)$(Riemannian) Hessian of function $f \colon T_p\mathcal{M} \to T_p\mathcal M$ (i.e. the 1-1-tensor form) at $p \in \mathcal{M}$
    $\nabla^2 f(p)$(Euclidean) Hessian of function $f$ in the embeddingH
    $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$
    $N_p \mathcal M$the normal space of the tangent space $T_p \mathcal M$ in some embedding $\mathcal E$ that should be clear from context
    $V$a normal vector from $N_p \mathcal M$$W$
    $\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$
    $\mathcal W$the Weingarten map $\mathcal W: T_p\mathcal M × N_p\mathcal M → T_p\mathcal M$$\mathcal W_p$the second notation to emphasize the dependency of the point $p\in\mathcal M$
    $0_k$the $k\times k$ zero matrix.
    +Notation · Manifolds.jl
    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 Fiber
    $\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$.
    $\operatorname{grad} f(p)$(Riemannian) gradient of function $f \colon \mathcal{M} \to \mathbb{R}$ at $p \in \mathcal{M}$
    $\nabla f(p)$(Euclidean) gradient of function $f \colon \mathcal{M} \to \mathbb{R}$ at $p \in \mathcal{M}$ but thought of as evaluated in the embeddingG
    $\circ$a group operation
    $\cdot^\mathrm{H}$Hermitian or conjugate transposed for both complex or quaternion matrices
    $\operatorname{Hess} f(p)$(Riemannian) Hessian of function $f \colon T_p\mathcal{M} \to T_p\mathcal M$ (i.e. the 1-1-tensor form) at $p \in \mathcal{M}$
    $\nabla^2 f(p)$(Euclidean) Hessian of function $f$ in the embeddingH
    $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$
    $N_p \mathcal M$the normal space of the tangent space $T_p \mathcal M$ in some embedding $\mathcal E$ that should be clear from context
    $V$a normal vector from $N_p \mathcal M$$W$
    $\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$
    $\mathcal W$the Weingarten map $\mathcal W: T_p\mathcal M × N_p\mathcal M → T_p\mathcal M$$\mathcal W_p$the second notation to emphasize the dependency of the point $p\in\mathcal M$
    $0_k$the $k\times k$ zero matrix.
    diff --git a/previews/PR673/misc/references.html b/previews/PR673/misc/references.html index a13d9f9105..48d79e5e28 100644 --- a/previews/PR673/misc/references.html +++ b/previews/PR673/misc/references.html @@ -1,2 +1,2 @@ -References · Manifolds.jl
    GitHub

    Literature

    We are slowly moving to using DocumenterCitations.jl. The goal is to have all references used / mentioned in the documentation of Manifolds.jl also listed here. If you notice a reference still defined in a footnote, please change it into a BibTeX reference and open a PR

    Usually you will find a small reference section at the end of every documentation page that contains references for just that page.

    [AMT13]
    P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
    [AMS08]
    P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
    [AM12]
    P.-A. Absil and J. Malick. Projection-like Retractions on Matrix Manifolds. SIAM Journal on Optimization 22, 135–158 (2012).
    [AO14]
    P.-A. Absil and I. V. Oseledets. Low-rank retractions: a survey and new results. Computational Optimization and Applications 62, 5–29 (2014).
    [ATV13]
    B. Afsari, R. Tron and R. Vidal. On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass. SIAM Journal on Control and Optimization 51, 2230–2260 (2013), arXiv:1201.0925.
    [AR13]
    D. Andrica and R.-A. Rohan. Computing the Rodrigues coefficients of the exponential map of the Lie groups of matrices. Balkan Journal of Geometry and Its Applications 18, 1–10 (2013).
    [ALRV14]
    E. Andruchow, G. Larotonda, L. Recht and A. Varela. The left invariant metric in the general linear group. Journal of Geometry and Physics 86, 241–257 (2014), arXiv:1109.0520.
    [ABBR23]
    S. D. Axen, M. Baran, R. Bergmann and K. Rzecki. Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds. AMS Transactions on Mathematical Software (2023), arXiv:2021.08777, accepted for publication.
    [AJLS17]
    N. Ay, J. Jost, H. V. Lê and L. Schwachhöfer. Information Geometry (Springer Cham, 2017).
    [Bac14]
    M. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014), arXiv:1210.2145, arXiv: 1210.2145.
    [BZ21]
    T. Bendokat and R. Zimmermann. The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications, arXiv Preprint, 2108.12447 (2021).
    [BZA20]
    T. Bendokat, R. Zimmermann and P.-A. Absil. A Grassmann Manifold Handbook: Basic Geometry and Computational Aspects, arXiv Preprint (2020), arXiv:2011.13699.
    [BG18]
    R. Bergmann and P.-Y. Gousenbourger. A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics 4 (2018), arXiv:1807.10090.
    [BP08]
    E. Biny and S. Pods. The Geometry of Heisenberg Groups: With Applications in Signal Theory, Optics, Quantization, and Field Quantization (American Mathematical Socienty, 2008).
    [BCC20]
    P. Birtea, I. Caçu and D. Comănescu. Optimization on the real symplectic group. Monatshefte für Mathematik 191, 465–485 (2020).
    [BST03]
    L. J. Boya, E. Sudarshan and T. Tilma. Volumes of compact manifolds. Reports on Mathematical Physics 52, 401–422 (2003).
    [BP19]
    A. L. Brigant and S. Puechmorel. Approximation of Densities on Riemannian Manifolds. Entropy 21, 43 (2019).
    [CV15]
    R. Chakraborty and B. C. Vemuri. Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. In: 2015 IEEE International Conference on Computer Vision (ICCV) (2015).
    [CV19]
    R. Chakraborty and B. C. Vemuri. Statistics on the Stiefel manifold: Theory and applications. The Annals of Statistics 47 (2019), arXiv:1708.00045.
    [CHSV16]
    G. Cheng, J. Ho, H. Salehian and B. C. Vemuri. Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. In: Riemannian Computing in Computer Vision (Springer, Cham, 2016); pp. 21–43.
    [CLLD22]
    E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
    [CKA17]
    E. Chevallier, E. Kalunga and J. Angulo. Kernel Density Estimation on Spaces of Gaussian Distributions and Symmetric Positive Definite Matrices. SIAM Journal on Imaging Sciences 10, 191–215 (2017).
    [Chi03]
    Y. Chikuse. Statistics on Special Manifolds (Springer New York, 2003).
    [Dev86]
    L. Devroye. Non-Uniform Random Variate Generation (Springer New York, NY, 1986).
    [DBV21]
    N. Dewaele, P. Breiding and N. Vannieuwenhoven. The condition number of many tensor decompositions is invariant under Tucker compression, arXiv Preprint (2021), arXiv:2106.13034.
    [DH19]
    A. Douik and B. Hassibi. Manifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry. IEEE Transactions on Signal Processing 67, 5761–5774 (2019), arXiv:1802.02628.
    [EAS98]
    A. Edelman, T. A. Arias and S. T. Smith. The Geometry of Algorithms with Orthogonality Constraints. SIAM Journal on Matrix Analysis and Applications 20, 303–353 (1998), arXiv:806030.
    [FdHDF19]
    L. Falorsi, P. de Haan, T. R. Davidson and P. Forré. Reparameterizing Distributions on Lie Groups, arXiv Preprint (2019).
    [Fio11]
    S. Fiori. Solving Minimal-Distance Problems over the Manifold of Real-Symplectic Matrices. SIAM Journal on Matrix Analysis and Applications 32, 938–968 (2011).
    [FVJ08]
    P. T. Fletcher, S. Venkatasubramanian and S. Joshi. Robust statistics on Riemannian manifolds via the geometric median. In: 2008 IEEE Conference on Computer Vision and Pattern Recognition (2008).
    [GX02]
    J. Gallier and D. Xu. Computing exponentials of skew-symmetric matrices and logarithms of orthogonal matrices. International Journal of Robotics and Automation 17, 1–11 (2002).
    [GSAS21]
    B. Gao, N. T. Son, P.-A. Absil and T. Stykel. Riemannian Optimization on the Symplectic Stiefel Manifold. SIAM Journal on Optimization 31, 1546–1575 (2021).
    [Gil08]
    M. B. Giles. Collected Matrix Derivative Results for Forward and Reverse Mode Algorithmic Differentiation. In: Advances in Automatic Differentiation, Lecture Notes in Computational Science and Engineering, edited by C. H. Bischof, H. M. Bücker, P. Hovland, U. Naumann and J. Utke (Springer, Berlin, Heidelberg, 2008); pp. 35–44.
    [GMTP21]
    N. Guigui, E. Maignant, A. Trouvé and X. Pennec. Parallel Transport on Kendall Shape Spaces. In: Geometric Science of Information (SPringer Cham, 2021); pp. 103–110.
    [HMJG21]
    A. Han, B. Mushra, P. Jawapanpuria and J. Gao. Learning with symmetric positive definite matrices via generalized Bures-Wasserstein geometry, arXive preprint (2021), arXiv:2110.10464.
    [HCSV13]
    J. Ho, G. Cheng, H. Salehian and B. C. Vemuri. Recursive Karcher expectation estimators and geometric law of large numbers. In: 16th International Conference on Artificial Intelligence and Statistics (2013).
    [HU17]
    S. Hosseini and A. Uschmajew. A Riemannian Gradient Sampling Algorithm for Nonsmooth Optimization on Manifolds. SIAM J. Optim. 27, 173–189 (2017).
    [HGA15]
    W. Huang, K. A. Gallivan and P.-A. Absil. A Broyden Class of Quasi-Newton Methods for Riemannian Optimization. SIAM Journal on Optimization 25, 1660–1685 (2015).
    [HML21]
    K. Hüper, I. Markina and F. S. Leite. A Lagrangian approach to extremal curves on Stiefel manifolds. Journal of Geometric Mechanics 13, 55 (2021).
    [JBAS10]
    M. Journée, F. Bach, P.-A. Absil and R. Sepulchre. Low-Rank Optimization on the Cone of Positive Semidefinite Matrices. SIAM Journal on Optimization 20, 2327–2351 (2010), arXiv:0807.4423.
    [KFT13]
    T. Kaneko, S. Fiori and T. Tanaka. Empirical Arithmetic Averaging Over the Compact Stiefel Manifold. IEEE Transactions on Signal Processing 61, 883–894 (2013).
    [Kar77]
    H. Karcher. Riemannian center of mass and mollifier smoothing. Communications on Pure and Applied Mathematics 30, 509–541 (1977).
    [Ken84]
    D. G. Kendall. Shape Manifolds, Procrustean Metrics, and Complex Projective Spaces. Bulletin of the London Mathematical Society 16, 81–121 (1984).
    [Ken89]
    D. G. Kendall. A Survey of the Statistical Theory of Shape. Statistical Sciences 4, 87–99 (1989).
    [KL10]
    O. Koch and C. Lubich. Dynamical Tensor Approximation. SIAM Journal on Matrix Analysis and Applications 31, 2360–2375 (2010).
    [KSV13]
    D. Kressner, M. Steinlechner and B. Vandereycken. Low-rank tensor completion by Riemannian optimization. BIT Numerical Mathematics 54, 447–468 (2013).
    [LW19]
    N. Langrené and X. Warin. Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating. Journal of Computational and Graphical Statistics 28, 596–608 (2019).
    [LMV00]
    L. D. Lathauwer, B. D. Moor and J. Vandewalle. A Multilinear Singular Value Decomposition. SIAM Journal on Matrix Analysis and Applications 21, 1253–1278 (2000).
    [Lee19]
    J. M. Lee. Introduction to Riemannian Manifolds (Springer Cham, 2019).
    [Lin19]
    Z. Lin. Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition. SIAM Journal on Matrix Analysis and Applications 40, 1353–1370 (2019), arXiv:1908.09326.
    [MMP18]
    L. Malagó, L. Montrucchio and G. Pistone. Wasserstein Riemannian geometry of Gaussian densities. Information Geometry 1, 137–179 (2018).
    [Mar72]
    G. Marsaglia. Choosing a Point from the Surface of a Sphere. Annals of Mathematical Statistics 43, 645–646 (1972).
    [MA20]
    E. Massart and P.-A. Absil. Quotient Geometry with Simple Geodesics for the Manifold of Fixed-Rank Positive-Semidefinite Matrices. SIAM Journal on Matrix Analysis and Applications 41, 171–198 (2020). Preprint: sites.uclouvain.be/absil/2018.06.
    [MF12]
    P. Muralidharan and P. T. Fletcher. Sasaki metrics for analysis of longitudinal data on manifolds. In: 2012 IEEE Conference on Computer Vision and Pattern Recognition (2012).
    [NM16]
    P. Neff and R. J. Martin. Minimal geodesics on GL(n) for left-invariant, right-O(n)-invariant Riemannian metrics. J. Geom. Mech. 8, 323–357 (2016), arXiv:1409.7849.
    [Ngu23]
    D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
    [Pen06]
    X. Pennec. Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements. Journal of Mathematical Imaging and Vision 25, 127–154 (2006).
    [PA12]
    X. Pennec and V. Arsigny. Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Matrix Information Geometry (Springer, Berlin, Heidelberg, 2012); pp. 123–166, arXiv:00699361.
    [PL20]
    X. Pennec and M. Lorenzi. Beyond Riemannian geometry: The affine connection setting for transformation groups. In: Riemannian Geometric Statistics in Medical Image Analysis (Elsevier, 2020); pp. 169–229.
    [Ren11]
    Q. Rentmeesters. A gradient method for geodesic data fitting on some symmetric Riemannian manifolds. In: IEEE Conference on Decision and Control and European Control Conference (2011); pp. 7141–7146.
    [Ric88]
    J. M. Rico Martinez. Representations of the Euclidean group and its applications to the kinematics of spatial chains. Ph.D. Thesis, University of FLorida (1988).
    [SCaO+15]
    H. Salehian, R. Chakraborty, E. and Ofori, D. Vaillancourt and B. C. Vemuri. An efficient recursive estimator of the Fréchet mean on hypersphere with applications to Medical Image Analysis. In: 5th MICCAI workshop on Mathematical Foundations of Computational Anatomy (Oct 2015).
    [Sas58]
    S. Sasaki. On the differential geometry of tangent bundles of Riemannian manifolds. Tohoku Math. J. 10 (1958).
    [SK16]
    A. Srivastava and E. P. Klassen. Functional and Shape Data Analysis (Springer New York, 2016).
    [Suh13]
    E. Suhubi. Exterior Analysis: Using Applications of Differential Forms (Academic Press, 2013).
    [Tor20]
    S. Tornier. Haar Measures (2020).
    [TD17]
    R. Tron and K. Daniilidis. The Space of Essential Matrices as a Riemannian Quotient Manifold. SIAM J. Imaging Sci. 10, 1416–1445 (2017).
    [Van13]
    B. Vandereycken. Low-rank matrix completion by Riemannian optimization. SIAM Journal on Optimization 23, 1214–1236 (2013).
    [VVM12]
    N. Vannieuwenhoven, R. Vandebril and K. Meerbergen. A New Truncation Strategy for the Higher-Order Singular Value Decomposition. SIAM Journal on Scientific Computing 34, A1027–A1052 (2012).
    [WSF18]
    J. Wang, H. Sun and S. Fiori. A Riemannian-steepest-descent approach for optimization on the real symplectic group. Mathematical Methods in the Applied Science 41, 4273–4286 (2018).
    [Wes79]
    D. H. West. Updating mean and variance estimates. Communications of the ACM 22, 532–535 (1979).
    [YWL21]
    K. Ye, K. S.-W. Wong and L.-H. Lim. Optimization on flag manifolds. Mathematical Programming 194, 621–660 (2021).
    [Zhu16]
    X. Zhu. A Riemannian conjugate gradient method for optimization on the Stiefel manifold. Computational Optimization and Applications 67, 73–110 (2016).
    [ZD18]
    X. Zhu and C. Duan. On matrix exponentials and their approximations related to optimization on the Stiefel manifold. Optimization Letters 13, 1069–1083 (2018).
    [Zim17]
    R. Zimmermann. A Matrix-Algebraic Algorithm for the Riemannian Logarithm on the Stiefel Manifold under the Canonical Metric. SIAM J. Matrix Anal. Appl. 38, 322–342 (2017), arXiv:1604.05054.
    [ZH22]
    R. Zimmermann and K. Hüper. Computing the Riemannian Logarithm on the Stiefel Manifold: Metrics, Methods, and Performance. SIAM Journal on Matrix Analysis and Applications 43, 953–980 (2022), arXiv:2103.12046.
    [APSS17]
    F. Åström, S. Petra, B. Schmitzer and C. Schnörr. Image Labeling by Assignment. Journal of Mathematical Imaging and Vision 58, 211–238 (2017), arXiv:1603.05285.
    +References · Manifolds.jl
    GitHub

    Literature

    We are slowly moving to using DocumenterCitations.jl. The goal is to have all references used / mentioned in the documentation of Manifolds.jl also listed here. If you notice a reference still defined in a footnote, please change it into a BibTeX reference and open a PR

    Usually you will find a small reference section at the end of every documentation page that contains references for just that page.

    [AMT13]
    P. -.-A. Absil, R. Mahony and J. Trumpf. An Extrinsic Look at the Riemannian Hessian. In: Geometric Science of Information, edited by F. Nielsen and F. Barbaresco (Springer Berlin Heidelberg, 2013); pp. 361–368.
    [AMS08]
    P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
    [AM12]
    P.-A. Absil and J. Malick. Projection-like Retractions on Matrix Manifolds. SIAM Journal on Optimization 22, 135–158 (2012).
    [AO14]
    P.-A. Absil and I. V. Oseledets. Low-rank retractions: a survey and new results. Computational Optimization and Applications 62, 5–29 (2014).
    [ATV13]
    B. Afsari, R. Tron and R. Vidal. On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass. SIAM Journal on Control and Optimization 51, 2230–2260 (2013), arXiv:1201.0925.
    [AR13]
    D. Andrica and R.-A. Rohan. Computing the Rodrigues coefficients of the exponential map of the Lie groups of matrices. Balkan Journal of Geometry and Its Applications 18, 1–10 (2013).
    [ALRV14]
    E. Andruchow, G. Larotonda, L. Recht and A. Varela. The left invariant metric in the general linear group. Journal of Geometry and Physics 86, 241–257 (2014), arXiv:1109.0520.
    [ABBR23]
    S. D. Axen, M. Baran, R. Bergmann and K. Rzecki. Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds. AMS Transactions on Mathematical Software (2023), arXiv:2021.08777, accepted for publication.
    [AJLS17]
    N. Ay, J. Jost, H. V. Lê and L. Schwachhöfer. Information Geometry (Springer Cham, 2017).
    [Bac14]
    M. Bačák. Computing medians and means in Hadamard spaces. SIAM Journal on Optimization 24, 1542–1566 (2014), arXiv:1210.2145, arXiv: 1210.2145.
    [BZ21]
    T. Bendokat and R. Zimmermann. The real symplectic Stiefel and Grassmann manifolds: metrics, geodesics and applications, arXiv Preprint, 2108.12447 (2021).
    [BZA20]
    T. Bendokat, R. Zimmermann and P.-A. Absil. A Grassmann Manifold Handbook: Basic Geometry and Computational Aspects, arXiv Preprint (2020), arXiv:2011.13699.
    [BG18]
    R. Bergmann and P.-Y. Gousenbourger. A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics 4 (2018), arXiv:1807.10090.
    [BP08]
    E. Biny and S. Pods. The Geometry of Heisenberg Groups: With Applications in Signal Theory, Optics, Quantization, and Field Quantization (American Mathematical Socienty, 2008).
    [BCC20]
    P. Birtea, I. Caçu and D. Comănescu. Optimization on the real symplectic group. Monatshefte für Mathematik 191, 465–485 (2020).
    [BST03]
    L. J. Boya, E. Sudarshan and T. Tilma. Volumes of compact manifolds. Reports on Mathematical Physics 52, 401–422 (2003).
    [BP19]
    A. L. Brigant and S. Puechmorel. Approximation of Densities on Riemannian Manifolds. Entropy 21, 43 (2019).
    [CV15]
    R. Chakraborty and B. C. Vemuri. Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. In: 2015 IEEE International Conference on Computer Vision (ICCV) (2015).
    [CV19]
    R. Chakraborty and B. C. Vemuri. Statistics on the Stiefel manifold: Theory and applications. The Annals of Statistics 47 (2019), arXiv:1708.00045.
    [CHSV16]
    G. Cheng, J. Ho, H. Salehian and B. C. Vemuri. Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. In: Riemannian Computing in Computer Vision (Springer, Cham, 2016); pp. 21–43.
    [CLLD22]
    E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
    [CKA17]
    E. Chevallier, E. Kalunga and J. Angulo. Kernel Density Estimation on Spaces of Gaussian Distributions and Symmetric Positive Definite Matrices. SIAM Journal on Imaging Sciences 10, 191–215 (2017).
    [Chi03]
    Y. Chikuse. Statistics on Special Manifolds (Springer New York, 2003).
    [Dev86]
    L. Devroye. Non-Uniform Random Variate Generation (Springer New York, NY, 1986).
    [DBV21]
    N. Dewaele, P. Breiding and N. Vannieuwenhoven. The condition number of many tensor decompositions is invariant under Tucker compression, arXiv Preprint (2021), arXiv:2106.13034.
    [DH19]
    A. Douik and B. Hassibi. Manifold Optimization Over the Set of Doubly Stochastic Matrices: A Second-Order Geometry. IEEE Transactions on Signal Processing 67, 5761–5774 (2019), arXiv:1802.02628.
    [EAS98]
    A. Edelman, T. A. Arias and S. T. Smith. The Geometry of Algorithms with Orthogonality Constraints. SIAM Journal on Matrix Analysis and Applications 20, 303–353 (1998), arXiv:806030.
    [FdHDF19]
    L. Falorsi, P. de Haan, T. R. Davidson and P. Forré. Reparameterizing Distributions on Lie Groups, arXiv Preprint (2019).
    [Fio11]
    S. Fiori. Solving Minimal-Distance Problems over the Manifold of Real-Symplectic Matrices. SIAM Journal on Matrix Analysis and Applications 32, 938–968 (2011).
    [FVJ08]
    P. T. Fletcher, S. Venkatasubramanian and S. Joshi. Robust statistics on Riemannian manifolds via the geometric median. In: 2008 IEEE Conference on Computer Vision and Pattern Recognition (2008).
    [GX02]
    J. Gallier and D. Xu. Computing exponentials of skew-symmetric matrices and logarithms of orthogonal matrices. International Journal of Robotics and Automation 17, 1–11 (2002).
    [GSAS21]
    B. Gao, N. T. Son, P.-A. Absil and T. Stykel. Riemannian Optimization on the Symplectic Stiefel Manifold. SIAM Journal on Optimization 31, 1546–1575 (2021).
    [Gil08]
    M. B. Giles. Collected Matrix Derivative Results for Forward and Reverse Mode Algorithmic Differentiation. In: Advances in Automatic Differentiation, Lecture Notes in Computational Science and Engineering, edited by C. H. Bischof, H. M. Bücker, P. Hovland, U. Naumann and J. Utke (Springer, Berlin, Heidelberg, 2008); pp. 35–44.
    [GMTP21]
    N. Guigui, E. Maignant, A. Trouvé and X. Pennec. Parallel Transport on Kendall Shape Spaces. In: Geometric Science of Information (SPringer Cham, 2021); pp. 103–110.
    [HMJG21]
    A. Han, B. Mushra, P. Jawapanpuria and J. Gao. Learning with symmetric positive definite matrices via generalized Bures-Wasserstein geometry, arXive preprint (2021), arXiv:2110.10464.
    [HCSV13]
    J. Ho, G. Cheng, H. Salehian and B. C. Vemuri. Recursive Karcher expectation estimators and geometric law of large numbers. In: 16th International Conference on Artificial Intelligence and Statistics (2013).
    [HU17]
    S. Hosseini and A. Uschmajew. A Riemannian Gradient Sampling Algorithm for Nonsmooth Optimization on Manifolds. SIAM J. Optim. 27, 173–189 (2017).
    [HGA15]
    W. Huang, K. A. Gallivan and P.-A. Absil. A Broyden Class of Quasi-Newton Methods for Riemannian Optimization. SIAM Journal on Optimization 25, 1660–1685 (2015).
    [HML21]
    K. Hüper, I. Markina and F. S. Leite. A Lagrangian approach to extremal curves on Stiefel manifolds. Journal of Geometric Mechanics 13, 55 (2021).
    [JBAS10]
    M. Journée, F. Bach, P.-A. Absil and R. Sepulchre. Low-Rank Optimization on the Cone of Positive Semidefinite Matrices. SIAM Journal on Optimization 20, 2327–2351 (2010), arXiv:0807.4423.
    [KFT13]
    T. Kaneko, S. Fiori and T. Tanaka. Empirical Arithmetic Averaging Over the Compact Stiefel Manifold. IEEE Transactions on Signal Processing 61, 883–894 (2013).
    [Kar77]
    H. Karcher. Riemannian center of mass and mollifier smoothing. Communications on Pure and Applied Mathematics 30, 509–541 (1977).
    [Ken84]
    D. G. Kendall. Shape Manifolds, Procrustean Metrics, and Complex Projective Spaces. Bulletin of the London Mathematical Society 16, 81–121 (1984).
    [Ken89]
    D. G. Kendall. A Survey of the Statistical Theory of Shape. Statistical Sciences 4, 87–99 (1989).
    [KL10]
    O. Koch and C. Lubich. Dynamical Tensor Approximation. SIAM Journal on Matrix Analysis and Applications 31, 2360–2375 (2010).
    [KSV13]
    D. Kressner, M. Steinlechner and B. Vandereycken. Low-rank tensor completion by Riemannian optimization. BIT Numerical Mathematics 54, 447–468 (2013).
    [LW19]
    N. Langrené and X. Warin. Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating. Journal of Computational and Graphical Statistics 28, 596–608 (2019).
    [LMV00]
    L. D. Lathauwer, B. D. Moor and J. Vandewalle. A Multilinear Singular Value Decomposition. SIAM Journal on Matrix Analysis and Applications 21, 1253–1278 (2000).
    [Lee19]
    J. M. Lee. Introduction to Riemannian Manifolds (Springer Cham, 2019).
    [Lin19]
    Z. Lin. Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition. SIAM Journal on Matrix Analysis and Applications 40, 1353–1370 (2019), arXiv:1908.09326.
    [MMP18]
    L. Malagó, L. Montrucchio and G. Pistone. Wasserstein Riemannian geometry of Gaussian densities. Information Geometry 1, 137–179 (2018).
    [Mar72]
    G. Marsaglia. Choosing a Point from the Surface of a Sphere. Annals of Mathematical Statistics 43, 645–646 (1972).
    [MA20]
    E. Massart and P.-A. Absil. Quotient Geometry with Simple Geodesics for the Manifold of Fixed-Rank Positive-Semidefinite Matrices. SIAM Journal on Matrix Analysis and Applications 41, 171–198 (2020). Preprint: sites.uclouvain.be/absil/2018.06.
    [MF12]
    P. Muralidharan and P. T. Fletcher. Sasaki metrics for analysis of longitudinal data on manifolds. In: 2012 IEEE Conference on Computer Vision and Pattern Recognition (2012).
    [NM16]
    P. Neff and R. J. Martin. Minimal geodesics on GL(n) for left-invariant, right-O(n)-invariant Riemannian metrics. J. Geom. Mech. 8, 323–357 (2016), arXiv:1409.7849.
    [Ngu23]
    D. Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. Journal of Optimization Theory and Applications 198, 135–164 (2023), arXiv:2009.10159.
    [Pen06]
    X. Pennec. Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements. Journal of Mathematical Imaging and Vision 25, 127–154 (2006).
    [PA12]
    X. Pennec and V. Arsigny. Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Matrix Information Geometry (Springer, Berlin, Heidelberg, 2012); pp. 123–166, arXiv:00699361.
    [PL20]
    X. Pennec and M. Lorenzi. Beyond Riemannian geometry: The affine connection setting for transformation groups. In: Riemannian Geometric Statistics in Medical Image Analysis (Elsevier, 2020); pp. 169–229.
    [Ren11]
    Q. Rentmeesters. A gradient method for geodesic data fitting on some symmetric Riemannian manifolds. In: IEEE Conference on Decision and Control and European Control Conference (2011); pp. 7141–7146.
    [Ric88]
    J. M. Rico Martinez. Representations of the Euclidean group and its applications to the kinematics of spatial chains. Ph.D. Thesis, University of FLorida (1988).
    [SCaO+15]
    H. Salehian, R. Chakraborty, E. and Ofori, D. Vaillancourt and B. C. Vemuri. An efficient recursive estimator of the Fréchet mean on hypersphere with applications to Medical Image Analysis. In: 5th MICCAI workshop on Mathematical Foundations of Computational Anatomy (Oct 2015).
    [Sas58]
    S. Sasaki. On the differential geometry of tangent bundles of Riemannian manifolds. Tohoku Math. J. 10 (1958).
    [SK16]
    A. Srivastava and E. P. Klassen. Functional and Shape Data Analysis (Springer New York, 2016).
    [Suh13]
    E. Suhubi. Exterior Analysis: Using Applications of Differential Forms (Academic Press, 2013).
    [Tor20]
    S. Tornier. Haar Measures (2020).
    [TD17]
    R. Tron and K. Daniilidis. The Space of Essential Matrices as a Riemannian Quotient Manifold. SIAM J. Imaging Sci. 10, 1416–1445 (2017).
    [Van13]
    B. Vandereycken. Low-rank matrix completion by Riemannian optimization. SIAM Journal on Optimization 23, 1214–1236 (2013).
    [VVM12]
    N. Vannieuwenhoven, R. Vandebril and K. Meerbergen. A New Truncation Strategy for the Higher-Order Singular Value Decomposition. SIAM Journal on Scientific Computing 34, A1027–A1052 (2012).
    [WSF18]
    J. Wang, H. Sun and S. Fiori. A Riemannian-steepest-descent approach for optimization on the real symplectic group. Mathematical Methods in the Applied Science 41, 4273–4286 (2018).
    [Wes79]
    D. H. West. Updating mean and variance estimates. Communications of the ACM 22, 532–535 (1979).
    [YWL21]
    K. Ye, K. S.-W. Wong and L.-H. Lim. Optimization on flag manifolds. Mathematical Programming 194, 621–660 (2021).
    [Zhu16]
    X. Zhu. A Riemannian conjugate gradient method for optimization on the Stiefel manifold. Computational Optimization and Applications 67, 73–110 (2016).
    [ZD18]
    X. Zhu and C. Duan. On matrix exponentials and their approximations related to optimization on the Stiefel manifold. Optimization Letters 13, 1069–1083 (2018).
    [Zim17]
    R. Zimmermann. A Matrix-Algebraic Algorithm for the Riemannian Logarithm on the Stiefel Manifold under the Canonical Metric. SIAM J. Matrix Anal. Appl. 38, 322–342 (2017), arXiv:1604.05054.
    [ZH22]
    R. Zimmermann and K. Hüper. Computing the Riemannian Logarithm on the Stiefel Manifold: Metrics, Methods, and Performance. SIAM Journal on Matrix Analysis and Applications 43, 953–980 (2022), arXiv:2103.12046.
    [APSS17]
    F. Åström, S. Petra, B. Schmitzer and C. Schnörr. Image Labeling by Assignment. Journal of Mathematical Imaging and Vision 58, 211–238 (2017), arXiv:1603.05285.
    diff --git a/previews/PR673/tutorials/getstarted.html b/previews/PR673/tutorials/getstarted.html index a059159cd9..57be0f45ff 100644 --- a/previews/PR673/tutorials/getstarted.html +++ b/previews/PR673/tutorials/getstarted.html @@ -53,4 +53,4 @@ [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.

    Literature

    [AMS08]
    P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
    [ABBR23]
    S. D. Axen, M. Baran, R. Bergmann and K. Rzecki. Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds. AMS Transactions on Mathematical Software (2023), arXiv:2021.08777, accepted for publication.
    [BG18]
    R. Bergmann and P.-Y. Gousenbourger. A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics 4 (2018), arXiv:1807.10090.
    + 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.

    Literature

    [AMS08]
    P.-A. Absil, R. Mahony and R. Sepulchre. Optimization Algorithms on Matrix Manifolds (Princeton University Press, 2008), available online at press.princeton.edu/chapters/absil/.
    [ABBR23]
    S. D. Axen, M. Baran, R. Bergmann and K. Rzecki. Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds. AMS Transactions on Mathematical Software (2023), arXiv:2021.08777, accepted for publication.
    [BG18]
    R. Bergmann and P.-Y. Gousenbourger. A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve. Frontiers in Applied Mathematics and Statistics 4 (2018), arXiv:1807.10090.
    diff --git a/previews/PR673/tutorials/hand-gestures.html b/previews/PR673/tutorials/hand-gestures.html index c54e264b7d..ef1f6515f7 100644 --- a/previews/PR673/tutorials/hand-gestures.html +++ b/previews/PR673/tutorials/hand-gestures.html @@ -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/PR673/tutorials/integration.html b/previews/PR673/tutorials/integration.html index 667ba4296e..976021c434 100644 --- a/previews/PR673/tutorials/integration.html +++ b/previews/PR673/tutorials/integration.html @@ -58,4 +58,4 @@ kde = PelletierKDE(M, 0.7, pts) println(simple_mc_integrate(Sphere(2), kde; N=1000000)) println(kde(rand(M)))
    1.001187910595545
-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 [Tor20]. 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 [BST03] for some considerations on symmetric spaces.

    References

    Literature

    [BST03]
    L. J. Boya, E. Sudarshan and T. Tilma. Volumes of compact manifolds. Reports on Mathematical Physics 52, 401–422 (2003).
    [BP19]
    A. L. Brigant and S. Puechmorel. Approximation of Densities on Riemannian Manifolds. Entropy 21, 43 (2019).
    [CLLD22]
    E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
    [LW19]
    N. Langrené and X. Warin. Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating. Journal of Computational and Graphical Statistics 28, 596–608 (2019).
    [Tor20]
    S. Tornier. Haar Measures (2020).
    +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 [Tor20]. 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 [BST03] for some considerations on symmetric spaces.

    References

    Literature

    [BST03]
    L. J. Boya, E. Sudarshan and T. Tilma. Volumes of compact manifolds. Reports on Mathematical Physics 52, 401–422 (2003).
    [BP19]
    A. L. Brigant and S. Puechmorel. Approximation of Densities on Riemannian Manifolds. Entropy 21, 43 (2019).
    [CLLD22]
    E. Chevallier, D. Li, Y. Lu and D. B. Dunson. Exponential-wrapped distributions on symmetric spaces. ArXiv Preprint (2022).
    [LW19]
    N. Langrené and X. Warin. Fast and Stable Multivariate Kernel Density Estimation by Fast Sum Updating. Journal of Computational and Graphical Statistics 28, 596–608 (2019).
    [Tor20]
    S. Tornier. Haar Measures (2020).
    diff --git a/previews/PR673/tutorials/working-in-charts.html b/previews/PR673/tutorials/working-in-charts.html index 4806795a7c..78e6a9c527 100644 --- a/previews/PR673/tutorials/working-in-charts.html +++ b/previews/PR673/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.