Flag manifold

Flag{T,d} <: AbstractDecoratorManifold{ℝ}

Flag manifold of $d$ subspaces of $ℝ^N$ [YWL21]. By default the manifold uses the Stiefel coordinates representation, embedding it in the Stiefel manifold. The other available representation is an embedding in OrthogonalMatrices. It can be utilized using OrthogonalPoint and OrthogonalTVector wrappers.

Tangent space is represented in the block-skew-symmetric form.

Constructor

Flag(N, n1, n2, ..., nd; parameter::Symbol=:type)

Generate the manifold $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ of subspaces

\[𝕍_1 ⊆ 𝕍_2 ⊆ ⋯ ⊆ V_d, \quad \operatorname{dim}(𝕍_i) = n_i\]

where $𝕍_i$ for $i ∈ 1, 2, …, d$ are subspaces of $ℝ^N$ of dimension $\operatorname{dim} 𝕍_i = n_i$.

parameter: whether a type parameter should be used to store n. By default size is stored in type. Value can either be :field or :type.

OrthogonalPoint <: AbstractManifoldPoint

A type to represent points on a manifold Flag in the orthogonal coordinates representation, i.e. a rotation matrix.

OrthogonalTVector <: TVector

A type to represent tangent vectors to points on a Flag manifold in the orthogonal coordinates representation.

ZeroTuple

Internal structure for representing shape of a Flag manifold. Behaves like a normal tuple, except at index zero returns value 0.

convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)

Convert tangent vector from Flag manifold M from orthogonal representation to Stiefel representation.

convert(::Type{AbstractMatrix}, M::Flag, p::OrthogonalPoint)

Convert point p from Flag manifold M from orthogonal representation to Stiefel representation.

convert(::Type{OrthogonalPoint}, M::Flag, p::AbstractMatrix)

Convert point p from Flag manifold M from Stiefel representation to orthogonal representation.

convert(::Type{OrthogonalTVector}, M::Flag, p::AbstractMatrix, X::AbstractMatrix)

Convert tangent vector from Flag manifold M from Stiefel representation to orthogonal representation.

get_embedding(M::Flag)

Get the embedding of the Flag manifold M, i.e. the Stiefel manifold.

injectivity_radius(M::Flag)
injectivity_radius(M::Flag, p)

Return the injectivity radius on the Flag M, which is $\frac{π}{2}$.

manifold_dimension(M::Flag)

Return dimension of flag manifold $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$. The formula reads $\sum_{i=1}^d (n_i-n_{i-1})(N-n_i)$.

check_vector(M::Flag, p::AbstractMatrix, X::AbstractMatrix; kwargs... )

Check whether X is a tangent vector to point p on the Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ in the Stiefel representation, i.e. that X is a matrix of the form

\[X = \begin{bmatrix} 0 & B_{1,2} & ⋯ & B_{1,d} \\ -B_{1,2}^\mathrm{T} & 0 & ⋯ & B_{2,d} \\ \vdots & \vdots & ⋱ & \vdots \\ -B_{1,d}^\mathrm{T} & -B_{2,d}^\mathrm{T} & ⋯ & 0 \\ -B_{1,d+1}^\mathrm{T} & -B_{2,d+1}^\mathrm{T} & ⋯ & -B_{d,d+1}^\mathrm{T} \end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

default_inverse_retraction_method(M::Flag)

Return PolarInverseRetraction as the default inverse retraction for the Flag manifold.

default_retraction_method(M::Flag)

Return PolarRetraction as the default retraction for the Flag manifold.

default_vector_transport_method(M::Flag)

Return the ProjectionTransport as the default vector transport method for the Flag manifold.

inverse_retract(M::Flag, p, q, ::PolarInverseRetraction)

Compute the inverse retraction for the PolarRetraction, on the Flag manifold M.

project(::Flag, p, X)

Project vector X in the Euclidean embedding to the tangent space at point p on Flag manifold. The formula reads [YWL21]:

\[Y_i = X_i - (p_i p_i^{\mathrm{T}}) X_i + \sum_{j \neq i} p_j X_j^{\mathrm{T}} p_i\]

for $i$ from 1 to $d$ where the resulting vector is $Y = [Y_1, Y_2, …, Y_d]$ and $X = [X_1, X_2, …, X_d]$, $p = [p_1, p_2, …, p_d]$ are decompositions into basis vector matrices for consecutive subspaces of the flag.

retract(M::Flag, p, X, ::PolarRetraction)

Compute the SVD-based retraction PolarRetraction on the Flag M. With $USV = p + X$ the retraction reads

\[\operatorname{retr}_p X = UV^\mathrm{H},\]

where $\cdot^{\mathrm{H}}$ denotes the complex conjugate transposed or Hermitian.

check_vector(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector; kwargs... )

Check whether X is a tangent vector to point p on the Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$ in the orthogonal matrix representation, i.e. that X is block-skew-symmetric with zero diagonal:

\[X = \begin{bmatrix} 0 & B_{1,2} & ⋯ & B_{1,d+1} \\ -B_{1,2}^\mathrm{T} & 0 & ⋯ & B_{2,d+1} \\ \vdots & \vdots & ⋱ & \vdots \\ -B_{1,d+1}^\mathrm{T} & -B_{2,d+1}^\mathrm{T} & ⋯ & 0 \end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

get_embedding(M::Flag, p::OrthogonalPoint)

Get embedding of Flag manifold M, i.e. the manifold OrthogonalMatrices.

project(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector)

Project vector X to tangent space at point p from Flag manifold M $\operatorname{Flag}(n_1, n_2, ..., n_d; N)$, in the orthogonal matrix representation. It works by first projecting X to the space of SkewHermitianMatrices and then setting diagonal blocks to 0:

\[X = \begin{bmatrix} 0 & B_{1,2} & ⋯ & B_{1,d+1} \\ -B_{1,2}^\mathrm{T} & 0 & ⋯ & B_{2,d+1} \\ \vdots & \vdots & ⋱ & \vdots \\ -B_{1,d+1}^\mathrm{T} & -B_{2,d+1}^\mathrm{T} & ⋯ & 0 \end{bmatrix}\]

where $B_{i,j} ∈ ℝ^{(n_i - n_{i-1}) × (n_j - n_{j-1})}$, for $1 ≤ i < j ≤ d+1$.

retract(M::Flag, p::OrthogonalPoint, X::OrthogonalTVector, ::QRRetraction)

Compute the QR retraction on the Flag in the orthogonal matrix representation as the first order approximation to the exponential map. Similar to QR retraction for [GeneralUnitaryMatrices].