AbstractSphere{𝔽} <: AbstractEmbeddedManifold{𝔽,DefaultIsometricEmbeddingType}

An abstract type to represent a unit sphere that is represented isometrically in the embedding.

Sphere{n,𝔽} <: 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_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- and quaternionic-valued sphere.

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

exp(M::AbstractSphere, p, X)

Compute the exponential map from p in the tangent direction X on the AbstractSphereM 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 AbstractSphereM.

log(M::AbstractSphere, p, q)

Compute the logarithmic map on the AbstractSphereM, 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.

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.

uniform_distribution(M::Sphere{n,ℝ}, p) where {n}

Uniform distribution on given SphereM. Generated points will be of similar type as p.

check_manifold_point(M::AbstractSphere, p; kwargs...)

Check whether p is a valid point on the AbstractSphereM, i.e. is a point in the embedding of unit length. The tolerance for the last test can be set using the kwargs....

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

Check whether X is a tangent vector to p on the AbstractSphereM, 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....

distance(M::AbstractSphere, p, q)

Compute the geodesic distance betweeen p and q on the AbstractSphereM. 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⟩)).\]

get_coordinates(M::AbstractSphere{ℝ}, p, X, B::DefaultOrthonormalBasis)

Represent the tangent vector X at point p from the AbstractSphereM 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}}}.\]

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

injectivity_radius(M::AbstractSphere[, p])

Return the injectivity radius for the AbstractSphereM, which is globally $π$.

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

Return the injectivity radius for the ProjectionRetraction on the AbstractSphere, which is globally $\frac{π}{2}$.

inverse_retract(M::AbstractSphere, p, q, ::ProjectionInverseRetraction)

Compute the inverse of the projection based retraction on the AbstractSphereM, 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.\]

manifold_dimension(M::AbstractSphere)

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

project(M::AbstractSphere, p, X)

Project the point X onto the tangent space at p on the SphereM.

\[\operatorname{proj}_{p}(X) = X - \Re(⟨p, X⟩)p\]

project(M::AbstractSphere, p)

Project the point p from the embedding onto the SphereM.

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

representation_size(M::AbstractSphere)

Return the size points on the AbstractSphereM are represented as, i.e., the representation size of the embedding.

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

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{\Re(⟨\log_p q,X⟩_p)}{d^2_𝕊(p,q)} \bigl(\log_p q + \log_q p \bigr).\]

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

Compute the Riemannian mean of x using GeodesicInterpolationWithinRadius.