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

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.

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

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`

).

## 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`

.

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

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

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

`Manifolds.uniform_distribution`

β Method`uniform_distribution(M::Sphere{n,β}, p) where {n}`

Uniform distribution on given `Sphere`

`M`

. Generated points will be of similar type as `p`

.

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

`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\]

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

.

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

.

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

`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}}}.\]

`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}}}.\]

`ManifoldsBase.injectivity_radius`

β Method`injectivity_radius(M::AbstractSphere[, p])`

Return the injectivity radius for the `AbstractSphere`

`M`

, which is globally $Ο$.

`injectivity_radius(M::Sphere, x, ::ProjectionRetraction)`

Return the injectivity radius for the `ProjectionRetraction`

on the `AbstractSphere`

, which is globally $\frac{Ο}{2}$.

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

`ManifoldsBase.is_flat`

β Method`is_flat(M::AbstractSphere)`

Return true if `AbstractSphere`

is of dimension 1 and false otherwise.

`ManifoldsBase.manifold_dimension`

β Method`manifold_dimension(M::AbstractSphere)`

Return the dimension of the `AbstractSphere`

`M`

, respectively i.e. the dimension of the embedding -1.

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

`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\]

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

`ManifoldsBase.representation_size`

β Method`representation_size(M::AbstractSphere)`

Return the size points on the `AbstractSphere`

`M`

are represented as, i.e., the representation size of the embedding.

`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}\]

`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\]

`ManifoldsBase.sectional_curvature`

β Method`sectional_curvature(::AbstractSphere, p, X, Y)`

Sectional curvature of `AbstractSphere`

`M`

is 1 if dimension is greater than 1 and 0 otherwise.

`ManifoldsBase.sectional_curvature_max`

β Method`sectional_curvature_max(::AbstractSphere)`

Sectional curvature of `AbstractSphere`

`M`

is 1 if dimension is greater than 1 and 0 otherwise.

`ManifoldsBase.sectional_curvature_min`

β Method`sectional_curvature_min(M::AbstractSphere)`

Sectional curvature of `AbstractSphere`

`M`

is 1 if dimension is greater than 1 and 0 otherwise.

`Statistics.mean`

β Method```
mean(
S::AbstractSphere,
x::AbstractVector,
[w::AbstractWeights,]
method = GeodesicInterpolationWithinRadius(Ο/2);
kwargs...,
)
```

Compute the Riemannian `mean`

of `x`

using `GeodesicInterpolationWithinRadius`

.

## Visualization on `Sphere{2,β}`

You can visualize both points and tangent vectors on the sphere.

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

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

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

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