Projective space

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

An abstract type to represent a projective space over 𝔽 that is represented isometrically in the embedding.

ArrayProjectiveSpace{T<:Tuple,𝔽} <: AbstractProjectiveSpace{𝔽}

The projective space $𝔽ℙ^{n₁,n₂,…,nᵢ}$ is the manifold of all lines in $𝔽^{n₁,n₂,…,nᵢ}$. The default representation is in the embedding, i.e. as unit (Frobenius) norm matrices in $𝔽^{n₁,n₂,…,nᵢ}$:

where $[p]$ is an equivalence class of points $p$, $\sim$ indicates equivalence, and $\lVert ⋅ \rVert_{\mathrm{F}}$ is the Frobenius norm. Note that unlike ProjectiveSpace, the argument for ArrayProjectiveSpace is given by the size of the embedding. This means that ProjectiveSpace(2) and ArrayProjectiveSpace(3) are the same manifold. Additionally, ArrayProjectiveSpace(n,1;field=𝔽) and Grassmann(n,1;field=𝔽) are the same.

The tangent space at point $p$ is given by

where $⟨⋅,⋅⟩_{\mathrm{F}}$ denotes the (Frobenius) inner product in the embedding $𝔽^{n_1, n_2, …, n_i}$.

Constructor

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

Generate the projective space $𝔽ℙ^{n_1, n_2, …, n_i}$, defaulting to the real projective space, where field can also be used to generate the complex- and right-quaternionic projective spaces.

ProjectiveSpace{n,𝔽} <: AbstractProjectiveSpace{𝔽}

The projective space $𝔽ℙ^n$ is the manifold of all lines in $𝔽^{n+1}$. The default representation is in the embedding, i.e. as unit norm vectors in $𝔽^{n+1}$:

where $[p]$ is an equivalence class of points $p$, and $∼$ indicates equivalence. For example, the real projective space $ℝℙ^n$ is represented as the unit sphere $𝕊^n$, where antipodal points are considered equivalent.

The tangent space at point $p$ is given by

where $⟨⋅,⋅⟩$ denotes the inner product in the embedding $𝔽^{n+1}$.

When $𝔽 = ℍ$, this implementation of $ℍℙ^n$ is the right-quaternionic projective space.

Constructor

ProjectiveSpace(n[, field=ℝ])

Generate the projective space $𝔽ℙ^{n} ⊂ 𝔽^{n+1}$, defaulting to the real projective space $ℝℙ^n$, where field can also be used to generate the complex- and right-quaternionic projective spaces.

isapprox(M::AbstractProjectiveSpace, p, q; kwargs...)

Check that points p and q on the AbstractProjectiveSpace M$=𝔽ℙ^n$ are members of the same equivalence class, i.e. that $p = q λ$ for some element $λ ∈ 𝔽$ with unit absolute value, that is, $|λ| = 1$. This is equivalent to the Riemannian distance being 0.

log(M::AbstractProjectiveSpace, p, q)

Compute the logarithmic map on AbstractProjectiveSpace M$ = 𝔽ℙ^n$, i.e. the tangent vector whose corresponding geodesic starting from p reaches q after time 1 on M. The formula reads

where $θ = \arccos|⟨q, p⟩_{\mathrm{F}}|$ is the distance between $p$ and $q$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ is the Frobenius inner product, and $λ = \frac{⟨q, p⟩_{\mathrm{F}}}{|⟨q, p⟩_{\mathrm{F}}|} ∈ 𝔽$ is the unit scalar that minimizes $d_{𝔽^{n+1}}(p - q λ)$. That is, $q λ$ is the member of the equivalence class $[q]$ that is closest to $p$ in the embedding. As a result, $\exp_p \circ \log_p \colon q ↦ q λ$.

The logarithmic maps for the real AbstractSphere $𝕊^n$ and the real projective space $ℝℙ^n$ are identical when $p$ and $q$ are in the same hemisphere.

normal_tvector_distribution(M::ProjectiveSpace{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::ProjectiveSpace{n,ℝ}, p) where {n}

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

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

Check whether p is a valid point on the AbstractProjectiveSpace M, i.e. that it has the same size as elements of the embedding and has unit Frobenius norm. The tolerance for the norm check can be set using the kwargs....

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

Check whether X is a tangent vector in the tangent space of p on the AbstractProjectiveSpace M, i.e. that X has the same size as elements of the tangent space of the embedding and that the Frobenius inner product $⟨p, X⟩_{\mathrm{F}} = 0$. The optional parameter check_base_point indicates whether to call check_manifold_point for p.

distance(M::AbstractProjectiveSpace, p, q)

Compute the Riemannian distance on AbstractProjectiveSpace M$=𝔽ℙ^n$ between points p and q, i.e.

Note that this definition is similar to that of the AbstractSphere. However, the absolute value ensures that all equivalent p and q have the same pairwise distance.

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

Represent the tangent vector $X$ at point $p$ from the AbstractProjectiveSpace $M = 𝔽ℙ^n$ in an orthonormal basis by unitarily transforming the hyperplane containing $X$, whose normal is $p$, to the hyperplane whose normal is the $x$-axis.

Given $q = p \overline{λ} + x$, where $λ = \frac{⟨x, p⟩_{\mathrm{F}}}{|⟨x, p⟩_{\mathrm{F}}|}$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, and $\overline{⋅}$ denotes complex or quaternionic conjugation, the formula for $Y$ is

get_vector(M::AbstractProjectiveSpace, p, X, B::DefaultOrthonormalBasis{ℝ})

Convert a one-dimensional vector of coefficients $X$ in the basis B of the tangent space at $p$ on the AbstractProjectiveSpace $M=𝔽ℙ^n$ to a tangent vector $Y$ at $p$ by unitarily transforming the hyperplane containing $X$, whose normal is the $x$-axis, to the hyperplane whose normal is $p$.

Given $q = p \overline{λ} + x$, where $λ = \frac{⟨x, p⟩_{\mathrm{F}}}{|⟨x, p⟩_{\mathrm{F}}|}$, $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product, and $\overline{⋅}$ denotes complex or quaternionic conjugation, the formula for $Y$ is

inverse_retract(M::AbstractProjectiveSpace, p, q, method::ProjectionInverseRetraction)
inverse_retract(M::AbstractProjectiveSpace, p, q, method::PolarInverseRetraction)
inverse_retract(M::AbstractProjectiveSpace, p, q, method::QRInverseRetraction)

Compute the equivalent inverse retraction ProjectionInverseRetraction, PolarInverseRetraction, and QRInverseRetraction on the AbstractProjectiveSpace manifold M$=𝔽ℙ^n$, i.e.

where $⟨⋅, ⋅⟩_{\mathrm{F}}$ is the Frobenius inner product.

Note that this inverse retraction is equivalent to the three corresponding inverse retractions on Grassmann(n+1,1,𝔽), where the three inverse retractions in this case coincide. For $ℝℙ^n$, it is the same as the ProjectionInverseRetraction on the real Sphere.

manifold_dimension(M::AbstractProjectiveSpace{𝔽}) where {𝔽}

Return the real dimension of the AbstractProjectiveSpace M, respectively i.e. the real dimension of the embedding minus the real dimension of the field 𝔽.

project(M::AbstractProjectiveSpace, p, X)

Orthogonally project the point X onto the tangent space at p on the AbstractProjectiveSpace M:

where $⟨⋅, ⋅⟩_{\mathrm{F}}$ denotes the Frobenius inner product. For the real AbstractSphere and AbstractProjectiveSpace, this projection is the same.

project(M::AbstractProjectiveSpace, p)

Orthogonally project the point p from the embedding onto the AbstractProjectiveSpace M:

where $\lVert ⋅ \rVert_{\mathrm{F}}$ denotes the Frobenius norm. This is identical to projection onto the AbstractSphere.

representation_size(M::AbstractProjectiveSpace)

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

retract(M::AbstractProjectiveSpace, p, X, method::ProjectionRetraction)
retract(M::AbstractProjectiveSpace, p, X, method::PolarRetraction)
retract(M::AbstractProjectiveSpace, p, X, method::QRRetraction)

Compute the equivalent retraction ProjectionRetraction, PolarRetraction, and QRRetraction on the AbstractProjectiveSpace manifold M$=𝔽ℙ^n$, i.e.

Note that this retraction is equivalent to the three corresponding retractions on Grassmann(n+1,1,𝔽), where in this case they coincide. For $ℝℙ^n$, it is the same as the ProjectionRetraction on the real Sphere.

vector_transport_direction(M::AbstractProjectiveSpace, p, X, d, method::ParallelTransport)

Parallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M along the geodesic in the direction indicated by the tangent vector d, i.e.

where $θ = \lVert d \rVert$, and $⟨⋅, ⋅⟩_p$ is the inner product at the point $p$. For the real projective space, this is equivalent to the same vector transport on the real AbstractSphere.

vector_transport_to(M::AbstractProjectiveSpace, p, X, q, method::ParallelTransport)

Parallel transport a vector X from the tangent space at a point p on the AbstractProjectiveSpace M$=𝔽ℙ^n$ to the tangent space at another point q.

This implementation proceeds by transporting $X$ to $T_{q λ} M$ using the same approach as vector_transport_direction, where $λ = \frac{⟨q, p⟩_{\mathrm{F}}}{|⟨q, p⟩_{\mathrm{F}}|} ∈ 𝔽$ is the unit scalar that takes $q$ to the member $q λ$ of its equivalence class $[q]$ closest to $p$ in the embedding. It then maps the transported vector from $T_{q λ} M$ to $T_{q} M$. The resulting transport to $T_{q} M$ is

where $d = \log_p q$ is the direction of the transport, $θ = \lVert d \rVert_p$ is the distance between $p$ and $q$, and $\overline{⋅}$ denotes complex or quaternionic conjugation.

mean(
    M::AbstractProjectiveSpace,
    x::AbstractVector,
    [w::AbstractWeights,]
    method = GeodesicInterpolationWithinRadius(π/4);
    kwargs...,
)

Compute the Riemannian mean of points in vector x using GeodesicInterpolationWithinRadius.