Symplectic Grassmann

NEWS.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.x] – 2024-01-18
+
+### Added
+
+* added the real symplectic Grassmann manifold `SymplecticGrassmann`
+* Introduce the manifold of `HamiltonianMatrices` and a wrapper for `Hamiltonian` matrices
+* introduce `rand(:HamiltonianMatrices)`
+* extend `rand` to also `rand!` for `HamiltonianMatrices`, `SymplecticMatrices` and `SymplecticStiefel`
+* implement `riemannian_gradient` conversion for `SymplecticMatrices` and `SymplecticGrassmann`
+* Rename (deprecate) `Symplectic` to `SimplecticMatrices` in order to have a `Symplectic` wrapper for such matrices as well
+* Rename (deprecate) `SymplecticMatrix` to `SymplecticElement` to clarify that it is the special matrix ``J_{2n}`` and not an arbitrary symplectic matrix.
+
 ## [0.9.11] – 2023-12-27
 
 ### Fixed
@@ -37,7 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Improved distribution of random vector generation for rotation matrices and complex circle.
 
-## [0.9.7] - 2023-11-14
+## [0.9.7] – 2023-11-14
 
 ### Fixed
 

docs/make.jl

@@ -113,6 +113,7 @@ makedocs(;
                 "Generalized Stiefel" => "manifolds/generalizedstiefel.md",
                 "Generalized Grassmann" => "manifolds/generalizedgrassmann.md",
                 "Grassmann" => "manifolds/grassmann.md",
+                "Hamiltonian" => "manifolds/hamiltonian.md",
                 "Hyperbolic space" => "manifolds/hyperbolic.md",
                 "Lorentzian manifold" => "manifolds/lorentz.md",
                 "Multinomial doubly stochastic matrices" => "manifolds/multinomialdoublystochastic.md",
@@ -133,7 +134,8 @@ makedocs(;
                 "Symmetric positive definite" => "manifolds/symmetricpositivedefinite.md",
                 "SPD, fixed determinant" => "manifolds/spdfixeddeterminant.md",
                 "Symmetric positive semidefinite fixed rank" => "manifolds/symmetricpsdfixedrank.md",
-                "Symplectic" => "manifolds/symplectic.md",
+                "Symplectic Grassmann" => "manifolds/symplecticgrassmann.md",
+                "Symplectic matrices" => "manifolds/symplectic.md",
                 "Symplectic Stiefel" => "manifolds/symplecticstiefel.md",
                 "Torus" => "manifolds/torus.md",
                 "Tucker" => "manifolds/tucker.md",

docs/src/features/atlases.md

@@ -1,6 +1,6 @@
 # [Atlases and charts](@id 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.
+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 ℝ^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`](@ref) in a basis, we use the terminology parameter in this package.
 
@@ -11,9 +11,9 @@ For an atlas ``\mathcal A`` we further require that
 ```
 
 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
+An atlas provides a connection between a manifold and the Euclidean space ``ℝ^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 manifolds we consider are smooth, i.e. any change of charts ``φ_i \circ φ_j^{-1}: ℝ^n\toℝ^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.
@@ -28,7 +28,7 @@ Operations using atlases and charts are available through the following function
 * [`get_parameters`](@ref Main.Manifolds.get_parameters) converts a point to its parameters with respect to the chart in a chart.
 * [`get_point`](@ref Main.Manifolds.get_point) converts parameters (local coordinates) in a chart to the point that corresponds to them.
 * [`induced_basis`](@ref Main.Manifolds.induced_basis) returns a basis of a given vector space at a point induced by a chart ``φ``.
-* [`transition_map`](@ref Main.Manifolds.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``.
+* [`transition_map`](@ref Main.Manifolds.transition_map) converts coordinates of a point between two charts, e.g. computes ``φ_i\circ φ_j^{-1}: ℝ^n\toℝ^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`](@ref) its inverse, the prametrization ``φ^{-1}``.
 

docs/src/manifolds/essentialmanifold.md

@@ -1,5 +1,5 @@
 # Essential Manifold
-The essential manifold is modeled as an [`AbstractPowerManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/manifolds.html#ManifoldsBase.AbstractPowerManifold)  of the $3\times3$ [`Rotations`](@ref) and uses [`NestedPowerRepresentation`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/manifolds.html#ManifoldsBase.NestedPowerRepresentation).
+The essential manifold is modeled as an [`AbstractPowerManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/manifolds.html#ManifoldsBase.AbstractPowerManifold)  of the $3×3$ [`Rotations`](@ref) and uses [`NestedPowerRepresentation`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/manifolds.html#ManifoldsBase.NestedPowerRepresentation).
 
 ```@autodocs
 Modules = [Manifolds]

docs/src/manifolds/euclidean.md

@@ -1,7 +1,7 @@
 # [Euclidean space](@id EuclideanSection)
 
 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`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#number-system), e.g. to create the $ℝ^n$ or $ℝ^{n\times n}$ you can simply type `M = ℝ^n` or `ℝ^(n,n)`, respectively.
+The easiest way to generate an Euclidean space is to use a field, i.e. [`AbstractNumbers`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#number-system), e.g. to create the $ℝ^n$ or $ℝ^{n×n}$ you can simply type `M = ℝ^n` or `ℝ^(n,n)`, respectively.
 
 ```@autodocs
 Modules = [Manifolds]

docs/src/manifolds/fiber_bundle.md

@@ -4,7 +4,7 @@ Fiber bundle $E$ is a manifold that is built on top of another manifold $\mathca
 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`](@ref).
 
-`Manifolds.jl` primarily deals with the case of trivial bundles, where $E$ can be identified with a product $M \times F$.
+`Manifolds.jl` primarily deals with the case of trivial bundles, where $E$ can be identified with a product $M ×F$.
 
 [Vector bundles](@ref VectorBundleSection) 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](https://en.wikipedia.org/wiki/Ehresmann_connection), providing notions of parallel transport and curvature.
 

docs/src/manifolds/grassmann.md

@@ -10,7 +10,7 @@ Order = [:type,:function]
 
 ```@autodocs
 Modules = [Manifolds]
-Pages = ["GrassmannStiefel.jl"]
+Pages = ["manifolds/GrassmannStiefel.jl"]
 Order = [:type,:function]
 ```
 

docs/src/manifolds/hamiltonian.md

@@ -0,0 +1,7 @@
+# Hamiltonian matrices
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["manifolds/Hamiltonian.jl"]
+Order = [:type, :function]
+```

docs/src/manifolds/power.md

@@ -1,8 +1,8 @@
 # [Power manifold](@id PowerManifoldSection)
 
-A power manifold is based on a [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold)  $\mathcal M$ to build a $\mathcal M^{n_1 \times n_2 \times \cdots \times n_m}$.
+A power manifold is based on a [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold)  $\mathcal M$ to build a $\mathcal M^{n_1×n_2 ×⋯×n_m}$.
 In the case where $m=1$ we can represent a manifold-valued vector of data of length $n_1$, for example a time series.
-The case where $m=2$ is useful for representing manifold-valued matrices of data of size $n_1 \times n_2$, for example certain types of images.
+The case where $m=2$ is useful for representing manifold-valued matrices of data of size $n_1×n_2$, for example certain types of images.
 
 There are three available representations for points and vectors on a power manifold:
 

docs/src/manifolds/rotations.md

@@ -1,8 +1,8 @@
 # Rotations
 
-The manifold $\mathrm{SO}(n)$ of orthogonal matrices with determinant $+1$ in $ℝ^{n × n}$, i.e.
+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}} =
+$\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.

docs/src/manifolds/shapespace.md

@@ -1,6 +1,6 @@
 # Shape spaces
 
-Shape spaces are spaces of ``k`` points in ``\mathbb{R}^n`` up to simultaneous action of a group on all points.
+Shape spaces are spaces of ``k`` points in ``ℝ^n`` up to simultaneous action of a group on all points.
 The most commonly encountered are Kendall's pre-shape and shape spaces.
 In the case of the Kendall's pre-shape spaces the action is translation and scaling.
 In the case of the Kendall's shape spaces the action is translation, scaling and rotation.

docs/src/manifolds/symplectic.md

@@ -1,12 +1,12 @@
-# Symplectic
+# Symplectic matrices
 
-The [`Symplectic`](@ref) manifold, denoted $\operatorname{Sp}(2n, \mathbb{F})$, is a closed, embedded, submanifold of
-$\mathbb{F}^{2n \times 2n}$ that represents transformations into symplectic subspaces which keep the
-canonical symplectic form over $\mathbb{F}^{2n \times 2n }$ invariant under the standard embedding inner product.
+The [`SymplecticMatrices`](@ref) manifold, denoted $\operatorname{Sp}(2n, 𝔽)$, is a closed, embedded, submanifold of
+$𝔽^{2n×2n}$ that represents transformations into symplectic subspaces which keep the
+canonical symplectic form over $𝔽^{2n×2n}$ invariant under the standard embedding inner product.
 The canonical symplectic form is a non-degenerate bilinear and skew symmetric map
-$\omega\colon \mathbb{F}^{2n} \times \mathbb{F}^{2n}
-\rightarrow \mathbb{F}$, given by
-$\omega(x, y) = x^T Q_{2n} y$ for elements $x, y \in \mathbb{F}^{2n}$, with
+$\omega\colon 𝔽 𝔽^{2n}×𝔽^{2n}
+→ 𝔽$, given by
+$\omega(x, y) = x^T Q_{2n} y$ for elements $x, y \in 𝔽^{2n}$, with
 ````math
     Q_{2n} =
     \begin{bmatrix}
@@ -22,11 +22,11 @@ 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](https://en.wikipedia.org/wiki/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
+$\operatorname{Sp}(2n, 𝔽)$ is a subgroup of the special linear group, $\operatorname{SL}(2n, 𝔽)$. When the underlying
+field is either $ℝ$ or $ℂ$ the symplectic group with a manifold structure constitutes a Lie group, with the Lie
 Algebra
 ````math
-    \mathfrak{sp}(2n,F) = \{H \in \mathbb{F}^{2n \times 2n} \;|\; Q H + H^{T} Q = 0\}.
+    \mathfrak{sp}(2n,F) = \{H \in 𝔽^{2n×2n} \;|\; Q H + H^{T} Q = 0\}.
 ````
 This set is also known as the [Hamiltonian matrices](https://en.wikipedia.org/wiki/Hamiltonian_matrix), which have the
 property that $(QH)^T = QH$ and are commonly used in physics.

docs/src/manifolds/symplecticgrassmann.md

@@ -0,0 +1,30 @@
+# (Real) Symplectic Grassmann
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["manifolds/SymplecticGrassmann.jl"]
+Order = [:type, :function]
+```
+
+## The (default) symplectic Stiefel representation
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["manifolds/SymplecticGrassmannStiefel.jl"]
+Order = [:type, :function]
+```
+
+## The symplectic projector representation
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["manifolds/SymplecticGrassmannProjector.jl"]
+Order = [:type, :function]
+```
+
+## Literature
+
+```@bibliography
+Pages = ["symplecticgrassmann.md"]
+Canonical=false
+```

docs/src/manifolds/symplecticstiefel.md

@@ -1,13 +1,13 @@
-# Symplectic Stiefel
+# (Real) Symplectic Stiefel
 
 The [`SymplecticStiefel`](@ref) manifold, denoted $\operatorname{SpSt}(2n, 2k)$,
-represents canonical symplectic bases of $2k$ dimensonal symplectic subspaces of $\mathbb{R}^{2n \times 2n}$.
-This means that the columns of each element $p \in \operatorname{SpSt}(2n, 2k) \subset \mathbb{R}^{2n \times 2k}$
+represents canonical symplectic bases of $2k$ dimensonal symplectic subspaces of $ℝ^{2n×2n}$.
+This means that the columns of each element $p \in \operatorname{SpSt}(2n, 2k) \subset ℝ^{2n×2k}$
 constitute a canonical symplectic basis of $\operatorname{span}(p)$.
 The canonical symplectic form is a non-degenerate, bilinear, and skew symmetric map
-$\omega_{2k}\colon \mathbb{F}^{2k} \times \mathbb{F}^{2k}
-\rightarrow \mathbb{F}$, given by
-$\omega_{2k}(x, y) = x^T Q_{2k} y$ for elements $x, y \in \mathbb{F}^{2k}$, with
+$\omega_{2k}\colon 𝔽^{2k}×𝔽^{2k}
+→ 𝔽$, given by
+$\omega_{2k}(x, y) = x^T Q_{2k} y$ for elements $x, y \in 𝔽^{2k}$, with
 ````math
     Q_{2k} =
     \begin{bmatrix}
@@ -17,10 +17,10 @@ $\omega_{2k}(x, y) = x^T Q_{2k} y$ for elements $x, y \in \mathbb{F}^{2k}$, with
 ````
 Specifically given an element $p \in \operatorname{SpSt}(2n, 2k)$ we require that
 ````math
-    \omega_{2n} (p x, p y) = x^T(p^TQ_{2n}p)y = x^TQ_{2k}y = \omega_{2k}(x, y) \;\forall\; x, y \in \mathbb{F}^{2k},
+    \omega_{2n} (p x, p y) = x^T(p^TQ_{2n}p)y = x^TQ_{2k}y = \omega_{2k}(x, y) \;\forall\; x, y \in 𝔽^{2k},
 ````
 leading to the requirement on $p$ that $p^TQ_{2n}p = Q_{2k}$.
-In the case that $k = n$, this manifold reduces to the [`Symplectic`](@ref) manifold, which is also known as the symplectic group.
+In the case that $k = n$, this manifold reduces to the [`SymplecticMatrices`](@ref) manifold, which is also known as the symplectic group.
 
 ```@autodocs
 Modules = [Manifolds]