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 $βŸ¨β‹…,β‹…βŸ©$ 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 $βŸ¨β‹…,β‹…βŸ©$ 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 emanating 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.manifold_volume β€” Method
manifold_volume(M::AbstractSphere{ℝ})

Volume of the $n$-dimensional Sphere M. The formula reads

\[\operatorname{Vol}(π•Š^{n}) = \frac{2\pi^{(n+1)/2}}{Ξ“((n+1)/2)},\]

where $Ξ“$ denotes the Gamma function.

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 between 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β‹…\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
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] ]
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).