# Sphere and unit norm arrays

Manifolds.AbstractSphereType
AbstractSphere{𝔽} <: AbstractEmbeddedManifold{𝔽,DefaultIsometricEmbeddingType}

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.SphereType
Sphere{n,𝔽} <: AbstractSphere{𝔽}

The (unit) sphere manifold $𝕊^{n}$ is the set of all unit norm vectors in $𝔽^{N}$, 𝔽 elements. 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}\ |\ ⟨p,X⟩ = 0 \bigr \},$

where $𝔽\in\{ℝ,ℂ\}$ and $⟨\cdot,\cdot⟩$ denotes the inner product in the embedding $\mathbb 𝔽^{n+1}$.

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_tangent_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-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.ArraySphereType
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}\ |\ ⟨p,X⟩ = 0 \bigr \},$

where $𝔽\in\{ℝ,ℂ\}$ and $⟨\cdot,\cdot⟩$ denotes the inner product in the embedding $\mathbb 𝔽^{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_tangent_vector are inherited from the embedding.

Constructor

ArraySphere(n₁,n₂,...,nᵢ; field=ℝ))

Generate sphere in $𝔽^{n_1, n_2, …, n_i}$, where 𝔽 defaults to the real-valued case ℝ.

source

# Functions on unit spheres

Base.expMethod
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}X,$

where $\lVert X \rVert_p$ is the norm on the tangent space at p of the AbstractSphere M.

source
Base.logMethod
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-⟨p,q⟩ p}{\lVert q-⟨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.normal_tvector_distributionMethod
normal_tvector_distribution(S::Sphere{n,ℝ}, p, σ)

Generate a distribution in the tangent space at p by generating a normal distribution in ambient space with standard deviation σ projected to the tangent space at p.

source
ManifoldsBase.check_tangent_vectorMethod
check_tangent_vector(M::AbstractSphere, p, X; check_base_point = true, kwargs... )

Check whether X is a tangent vector to p on the AbstractSphere M, i.e. after check_manifold_point(M,p), X has to be of same dimension as p and orthogonal to p. The optional parameter check_base_point indicates, whether to call check_manifold_point for p or not. The tolerance for the last test can be set using the kwargs....

source
ManifoldsBase.distanceMethod
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(⟨p,q⟩).$
source
ManifoldsBase.get_coordinatesMethod
get_coordinates(M::Sphere, p, X, B::DefaultOrthonormalBasis)

Represent the tangent vector X at point p from the Sphere M in an orthonormal basis by rotating the vector X using the rotation matrix $2\frac{q q^\mathrm{T}}{q^\mathrm{T} q} - I$ where $q = p + (1, 0, …, 0)$.

source
ManifoldsBase.inverse_retractMethod
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 $⟨p,X⟩ = 0$ and when $d_{𝕊^2}(p,q) ≤ \frac{π}{2}$ that

$\operatorname{retr}_p^{-1}(q) = \frac{q}{⟨p, q⟩} - p.$
source
ManifoldsBase.projectMethod
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.retractMethod
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.vector_transport_toMethod
vector_transport_to(M::AbstractSphere, p, X, q, ::ParallelTransport)

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{\langle \log_p q,X\rangle_p}{d^2_𝕊(p,q)} \bigl(\log_xy + \log_yx \bigr).$
source