Symmetric positive definite matrices
Manifolds.SymmetricPositiveDefinite β Type
SymmetricPositiveDefinite{T} <: AbstractDecoratorManifold{β}The manifold of symmetric positive definite matrices, i.e.
\[\mathcal P(n) = \bigl\{ p β β^{nΓn}\ \big|\ a^\mathrm{T}pa > 0 \text{ for all } a β β^{n}\backslash\{0\} \bigr\}\]
The tangent space at $T_p\mathcal P(n)$ reads
\[ T_p\mathcal P(n) = \bigl\{ X \in \mathbb R^{nΓn} \big|\ X=X^\mathrm{T} \bigr\},\]
i.e. the set of symmetric matrices,
Constructor
SymmetricPositiveDefinite(n; parameter::Symbol=:type)generates the manifold $\mathcal P(n) \subset β^{nΓn}$
This manifold can β for example β be illustrated as ellipsoids: since the eigenvalues are all positive they can be taken as lengths of the axes of an ellipsoids while the directions are given by the eigenvectors.
The manifold can be equipped with different metrics
Common and metric independent functions
Base.convert β Method
convert(::Type{AbstractMatrix}, p::SPDPoint)return the point p as a matrix. The matrix is either stored within the SPDPoint or reconstructed from p.eigen.
Base.rand β Method
rand(M::SymmetricPositiveDefinite; vector_at=nothing, tangent_distr=:Gaussian, Ο::Real=1/sqrt(n))Generate a random symmetric positive definite matrix on the SymmetricPositiveDefinite manifold M, or, if vector_at is a point $p$, a random tangent vector at $p$. The parameter Ο has no effect on a point.
For tangent_distr = :Gaussian the coordinates of the tangent vector in an orthonormal basis of $T_p\mathcal P(n)$ are independent and normally distributed with standard deviation Ο. For tangent_distr = :Rician the tangent vector is $RR^{\mathrm{T}}$ with $R = L + \sqrt{Ο}U$, where $L$ is the lower triangular Cholesky factor of $p$ and $U$ is upper triangular with independent standard normal entries; here Ο defaults to $1/\lVert p\rVert_{\mathrm{F}}$ instead.
ManifoldsBase.check_point β Method
check_point(M::SymmetricPositiveDefinite, p; kwargs...)checks, whether p is a valid point on the SymmetricPositiveDefinite M, i.e. is a matrix of size (N,N), symmetric and positive definite. The tolerance for the second to last test can be set using the kwargs....
ManifoldsBase.check_vector β Method
check_vector(M::SymmetricPositiveDefinite, p, X; kwargs... )Check whether X is a tangent vector to p on the SymmetricPositiveDefinite M. After check_point(M,p), X has to be of the same dimension as p and a symmetric matrix, i.e. this stores tangent vectors as elements of the corresponding Lie group. The tolerance for the last test can be set using the kwargs....
ManifoldsBase.injectivity_radius β Method
injectivity_radius(M::SymmetricPositiveDefinite[, p])
injectivity_radius(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}[, p])
injectivity_radius(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}[, p])Return the injectivity radius of the SymmetricPositiveDefinite. Since M is a Hadamard manifold with respect to the AffineInvariantMetric and the LogCholeskyMetric, the injectivity radius is globally $β$.
ManifoldsBase.is_flat β Method
is_flat(::SymmetricPositiveDefinite)Return false. SymmetricPositiveDefinite is not a flat manifold.
ManifoldsBase.manifold_dimension β Method
manifold_dimension(M::SymmetricPositiveDefinite)returns the dimension of SymmetricPositiveDefinite M $=\mathcal P(n), n β β$, i.e.
\[\dim \mathcal P(n) = \frac{n(n+1)}{2}.\]
ManifoldsBase.project β Method
project(M::SymmetricPositiveDefinite, p, X)project a matrix from the embedding onto the tangent space $T_p\mathcal P(n)$ of the SymmetricPositiveDefinite matrices, i.e. the set of symmetric matrices.
ManifoldsBase.representation_size β Method
representation_size(M::SymmetricPositiveDefinite)Return the size of an array representing an element on the SymmetricPositiveDefinite manifold M, i.e. $nΓn$, the size of such a symmetric positive definite matrix on $\mathcal M = \mathcal P(n)$.
ManifoldsBase.zero_vector β Method
zero_vector(M::SymmetricPositiveDefinite, p)returns the zero tangent vector in the tangent space of the symmetric positive definite matrix p on the SymmetricPositiveDefinite manifold M.
Default metric: the affine invariant metric
Manifolds.AffineInvariantMetric β Type
AffineInvariantMetric <: AbstractMetricThe linear affine metric is the metric for symmetric positive definite matrices, that employs matrix logarithms and exponentials, which yields a linear and affine metric.
This metric is also the default metric, i.e. any call of the following functions with P=SymmetricPositiveDefinite(3) will result in MetricManifold(P,AffineInvariantMetric())and hence yield the formulae described in this section.
Base.exp β Method
exp(M::SymmetricPositiveDefinite, p, X)
exp(M::MetricManifold{<:SymmetricPositiveDefinite,AffineInvariantMetric}, p, X)Compute the exponential map from p with tangent vector X on the SymmetricPositiveDefinite M with its default MetricManifold having the AffineInvariantMetric. The formula reads
\[\exp_p X = p^{\frac{1}{2}}\operatorname{Exp}(p^{-\frac{1}{2}} X p^{-\frac{1}{2}})p^{\frac{1}{2}},\]
where $\operatorname{Exp}$ denotes to the matrix exponential.
Base.log β Method
log(M::SymmetricPositiveDefinite, p, q)
log(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)Compute the logarithmic map from p to q on the SymmetricPositiveDefinite as a MetricManifold with AffineInvariantMetric. The formula reads
\[\log_p q = p^{\frac{1}{2}}\operatorname{Log}(p^{-\frac{1}{2}}qp^{-\frac{1}{2}})p^{\frac{1}{2}},\]
where $\operatorname{Log}$ denotes to the matrix logarithm.
ManifoldDiff.riemannian_Hessian β Method
riemannian_Hessian(M::SymmetricPositiveDefinite, p, G, H, X)The Riemannian Hessian can be computed as stated in Eq. (7.3) [Ngu23]. Let $\nabla f(p)$ denote the Euclidean gradient G, $\nabla^2 f(p)[X]$ the Euclidean Hessian H, and $\operatorname{sym}(X) = \frac{1}{2}\bigl(X^{\mathrm{T}}+X\bigr)$ the symmetrization operator. Then the formula reads
\[ \operatorname{Hess}f(p)[X] = p\operatorname{sym}(β^2 f(p)[X])p + \operatorname{sym}\bigl( X\operatorname{sym}\bigl(β f(p)\bigr)p)\]
Manifolds.manifold_volume β Method
manifold_volume(::SymmetricPositiveDefinite)Return volume of the SymmetricPositiveDefinite manifold, i.e. infinity.
Manifolds.volume_density β Method
volume_density(::SymmetricPositiveDefinite, p, X)Compute the volume density of the SymmetricPositiveDefinite manifold at p in direction X. See [CKA17], Section 6.2 for details. Note that metric in Manifolds.jl has a different scaling factor than the reference. It is the determinant of the differential of $\exp_p$ at X in orthonormal bases. With the eigenvalues $Ξ»_1,β¦,Ξ»_n$ of $p^{-1/2}Xp^{-1/2}$ it reads
\[ΞΈ_p(X) = \prod_{1 β€ i < j β€ n} \frac{\sinh\bigl(\lvert Ξ»_i-Ξ»_j\rvert/2\bigr)}{\lvert Ξ»_i-Ξ»_j\rvert/2},\]
where a factor with $Ξ»_i = Ξ»_j$ is $1$, see [dSLCY25], Proposition 4.3.
ManifoldsBase.change_metric β Method
change_metric(M::SymmetricPositiveDefinite, E::EuclideanMetric, p, X)Given a tangent vector $X β T_p\mathcal P(n)$ with respect to the EuclideanMetric g_E, this function changes into the AffineInvariantMetric (default) metric on the SymmetricPositiveDefinite M.
To be precise we are looking for $c\colon T_p\mathcal P(n) β T_p\mathcal P(n)$ such that for all $Y,Z β T_p\mathcal P(n)$ it holds
\[β¨Y,Zβ© = \operatorname{tr}(YZ) = \operatorname{tr}(p^{-1}c(Y)p^{-1}c(Z)) = g_p(c(Z),c(Y))\]
and hence $c(X) = pX$ is computed.
ManifoldsBase.change_representer β Method
change_representer(M::SymmetricPositiveDefinite, E::EuclideanMetric, p, X)Compute the representer of the linear function given by $X β T_p\mathcal M$ with respect to the (default) AffineInvariantMetric on the SymmetricPositiveDefinite M. Here X represents the linear function on the tangent space at p with respect to the EuclideanMetric g_E.
To be precise we are looking for $ZβT_p\mathcal P(n)$ such that for all $YβT_p\mathcal P(n)$ it holds
\[β¨X,Yβ© = \operatorname{tr}(XY) = \operatorname{tr}(p^{-1}Zp^{-1}Y) = g_p(Z,Y)\]
and hence $Z = pXp$.
ManifoldsBase.distance β Method
distance(M::SymmetricPositiveDefinite, p, q)
distance(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, q)Compute the distance on the SymmetricPositiveDefinite manifold between p and q, as a MetricManifold with AffineInvariantMetric. The formula reads
\[d_{\mathcal P(n)}(p,q) = \lVert \operatorname{Log}(p^{-\frac{1}{2}}qp^{-\frac{1}{2}})\rVert_{\mathrm{F}}.,\]
where $\operatorname{Log}$ denotes the matrix logarithm and $\lVertβ \rVert_{\mathrm{F}}$ denotes the matrix Frobenius norm.
ManifoldsBase.get_basis β Method
[Ξ,ΞΊ] = get_basis(M::SymmetricPositiveDefinite, p, B::DefaultOrthonormalBasis)
[Ξ,ΞΊ] = get_basis(M::MetricManifold{<:SymmetricPositiveDefinite,AffineInvariantMetric}, p, B::DefaultOrthonormalBasis)Return a default ONB for the tangent space $T_p\mathcal P(n)$ of the SymmetricPositiveDefinite with respect to the AffineInvariantMetric.
\[ g_p(X,Y) = \operatorname{tr}(p^{-1} X p^{-1} Y),\]
The basis constructed here is based on the ONB for symmetric matrices constructed as follows. Let
\[\Delta_{i,j} = (a_{k,l})_{k,l=1}^n \quad \text{ with } a_{k,l} = \begin{cases} 1 & \mbox{ for } k=l \text{ if } i=j\\ \frac{1}{\sqrt{2}} & \mbox{ for } k=i, l=j \text{ or } k=j, l=i\\ 0 & \text{ else.} \end{cases}\]
which forms an ONB for the space of symmetric matrices.
We then form the ONB by
\[ \Xi_{i,j} = p^{\frac{1}{2}}\Delta_{i,j}p^{\frac{1}{2}},\qquad i=1,\ldots,n, j=i,\ldots,n.\]
ManifoldsBase.get_basis_diagonalizing β Method
[Ξ,ΞΊ] = get_basis_diagonalizing(M::SymmetricPositiveDefinite, p, B::DiagonalizingOrthonormalBasis)
[Ξ,ΞΊ] = get_basis_diagonalizing(M::MetricManifold{<:SymmetricPositiveDefinite,AffineInvariantMetric}, p, B::DiagonalizingOrthonormalBasis)Return an orthonormal basis Ξ of the tangent space at p that diagonalizes the curvature tensor $R(u,v)w$, together with its eigenvalues ΞΊ. The basis is a vector of tangent vectors (of length manifold_dimension of M) on the MetricManifold of the SymmetricPositiveDefinite manifold M with AffineInvariantMetric, and the direction B.frame_direction $V$ has curvature 0.
The construction is based on an ONB for the symmetric matrices similar to get_basis(::SymmetricPositiveDefinite, p, ::DefaultOrthonormalBasis just that the ONB here is build from the eigen vectors of $p^{\frac{1}{2}}Vp^{\frac{1}{2}}$.
ManifoldsBase.get_coordinates β Method
get_coordinates(::SymmetricPositiveDefinite, p, X, ::DefaultOrthonormalBasis)Using the basis from get_basis the coordinates with respect to this ONB are the inner products with its basis vectors $\Xi_{i,j}$,
\[ c_k = g_p(X, \Xi_{i,j}) = \operatorname{tr}(p^{-1} X p^{-1} \Xi_{i,j}),\]
where $k$ is the linearized index of the $i=1,\ldots,n, j=i,\ldots,n$.
ManifoldsBase.get_vector β Method
get_vector(::SymmetricPositiveDefinite, p, c, ::DefaultOrthonormalBasis)Using the basis from get_basis the vector reconstruction with respect to this ONB can be simplified to
\[ X = p^{\frac{1}{2}} \Biggl( \sum_{i=1,j=i}^n c_k \Delta_{i,j} \Biggr) p^{\frac{1}{2}}\]
where $k$ is the linearized index of the $i=1,\ldots,n, j=i,\ldots,n$.
ManifoldsBase.inner β Method
inner(M::SymmetricPositiveDefinite, p, X, Y)
inner(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, X, Y)Compute the inner product of X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with AffineInvariantMetric. The formula reads
\[g_p(X,Y) = \operatorname{tr}(p^{-1} X p^{-1} Y),\]
ManifoldsBase.is_flat β Method
is_flat(::MetricManifold{β,<:SymmetricPositiveDefinite,AffineInvariantMetric})Return false. SymmetricPositiveDefinite with AffineInvariantMetric is not a flat manifold.
ManifoldsBase.parallel_transport_to β Method
parallel_transport_to(M::SymmetricPositiveDefinite, p, X, q)
parallel_transport_to(M::MetricManifold{SymmetricPositiveDefinite,AffineInvariantMetric}, p, X, y)Compute the parallel transport of X from the tangent space at p to the tangent space at q on the SymmetricPositiveDefinite as a MetricManifold with the AffineInvariantMetric. The formula reads
\[\mathcal P_{qβp}X = p^{\frac{1}{2}} \operatorname{Exp}\bigl( \frac{1}{2}p^{-\frac{1}{2}}\log_p(q)p^{-\frac{1}{2}} \bigr) p^{-\frac{1}{2}}X p^{-\frac{1}{2}} \operatorname{Exp}\bigl( \frac{1}{2}p^{-\frac{1}{2}}\log_p(q)p^{-\frac{1}{2}} \bigr) p^{\frac{1}{2}},\]
where $\operatorname{Exp}$ denotes the matrix exponential and log the logarithmic map on SymmetricPositiveDefinite (again with respect to the AffineInvariantMetric).
ManifoldsBase.riemann_tensor β Method
riemann_tensor(::SymmetricPositiveDefinite, p, X, Y, Z)Compute the value of Riemann tensor on the SymmetricPositiveDefinite manifold. The formula reads [Ren11] $R(X,Y)Z=p^{1/2}R(X_I, Y_I)Z_Ip^{1/2}$, where $R_I(X_I, Y_I)Z_I=\frac{1}{4}[Z_I, [X_I, Y_I]]$, $X_I=p^{-1/2}Xp^{-1/2}$, $Y_I=p^{-1/2}Yp^{-1/2}$ and $Z_I=p^{-1/2}Zp^{-1/2}$.
ManifoldsBase.sectional_curvature_max β Method
sectional_curvature_max(M::SymmetricPositiveDefinite)Return maximum sectional curvature of SymmetricPositiveDefinite manifold, that is 0.
ManifoldsBase.sectional_curvature_min β Method
sectional_curvature_min(M::SymmetricPositiveDefinite)Return the minimum sectional curvature of the SymmetricPositiveDefinite manifold with the AffineInvariantMetric.
This is 0 for $1Γ1$ matrices, where the manifold has dimension one, and $-1/2$ otherwise: the sectional curvatures of this metric are at most 0, see sectional_curvature_max, and their absolute values are bounded by $1/2$ and by no smaller constant, see [CB23], Section 2, comment 4 after Theorem 2.7, p. 1445.
Bures-Wasserstein metric
Manifolds.BuresWassersteinMetric β Type
BuresWassersteinMetric <: RiemannianMetricThe Bures Wasserstein metric for symmetric positive definite matrices [MMP18]
Base.exp β Method
exp(::MetricManifold{β,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X)Compute the exponential map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by
\[ \exp_p(X) = p+X+L_p(X)pL_p(X)\]
where $q=L_p(X)$ denotes the Lyapunov operator, i.e. it solves $pq + qp = X$.
Base.log β Method
log(::MetricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)Compute the logarithmic map on SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by
\[ \log_p(q) = (pq)^{\frac{1}{2}} + (qp)^{\frac{1}{2}} - 2 p\]
where $q=L_p(X)$ denotes the Lyapunov operator, i.e. it solves $pq + qp = X$.
ManifoldsBase.change_representer β Method
change_representer(M::MetricManifold{β,<:SymmetricPositiveDefinite,BuresWassersteinMetric}, E::EuclideanMetric, p, X)Compute the representer of the linear function given by $X β T_p\mathcal M$ with respect to the BuresWassersteinMetric on the SymmetricPositiveDefinite M. Here X represents the linear function on the tangent space at p with respect to the EuclideanMetric g_E.
To be precise we are looking for $ZβT_p\mathcal P(n)$ such that for all $YβT_p\mathcal P(n)$ it holds
\[β¨X,Yβ© = \operatorname{tr}(XY) = β¨Z,Yβ©_{\mathrm{BW}}\]
for all $Y$ and hence we get $Z$= 2(A+A^{\mathrm{T}})$with$A=Xp``.
ManifoldsBase.distance β Method
distance(::MetricManifold{SymmetricPositiveDefinite,BuresWassersteinMetric}, p, q)Compute the distance with respect to the BuresWassersteinMetric on SymmetricPositiveDefinite matrices, i.e.
\[d(p,q) = \sqrt{\operatorname{tr}(p) + \operatorname{tr}(q) - 2\operatorname{tr}\bigl((pq)^{\frac{1}{2}}\bigr)},\]
where $(pq)^{\frac{1}{2}}$ is the matrix square root of $pq$, see [HMJG23], Section 2, eq. (1).
ManifoldsBase.inner β Method
inner(::MetricManifold{β,SymmetricPositiveDefinite,BuresWassersteinMetric}, p, X, Y)Compute the inner product SymmetricPositiveDefinite with respect to the BuresWassersteinMetric given by
\[ β¨X,Yβ© = \frac{1}{2}\operatorname{tr}(L_p(X)Y)\]
where $q=L_p(X)$ denotes the Lyapunov operator, i.e. it solves $pq + qp = X$.
ManifoldsBase.is_flat β Method
is_flat(::MetricManifold{β,<:SymmetricPositiveDefinite,BuresWassersteinMetric})Return false. SymmetricPositiveDefinite with BuresWassersteinMetric is not a flat manifold.
Generalized Bures-Wasserstein metric
Manifolds.GeneralizedBuresWassersteinMetric β Type
GeneralizedBuresWassersteinMetric{T<:AbstractMatrix} <: RiemannianMetricThe generalized Bures Wasserstein metric for symmetric positive definite matrices, see [HMJG21].
This metric internally stores the symmetric positive definite matrix $B$ to generalise the metric, which is called $M$ in the cited paper.
Base.exp β Method
exp(M::MetricManifold{β,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric}, p, X)Compute the exponential map on the SymmetricPositiveDefinite manifold M with respect to the GeneralizedBuresWassersteinMetric with matrix $B$, given in Table 1 of [HMJG23] by
\[ \exp_p(X) = p+X+BL_{p,B}(X)pL_{p,B}(X)B\]
where $q=L_{p,B}(X)$ denotes the generalized Lyapunov operator, i.e. it solves $pqB + Bqp = X$, as defined below Eq. (3) there.
Base.log β Method
log(M::MetricManifold{β,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric}, p, q)Compute the logarithmic map on the SymmetricPositiveDefinite manifold M with respect to the GeneralizedBuresWassersteinMetric with matrix $B$ given by
\[ \log_p(q) = B(B^{-1}pB^{-1}q)^{\frac{1}{2}} + (qB^{-1}pB^{-1})^{\frac{1}{2}}B - 2 p.\]
ManifoldsBase.change_representer β Method
change_representer(M::MetricManifold{β,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric}, E::EuclideanMetric, p, X)Compute the representer of the linear function given by $X β T_p\mathcal M$ with respect to the GeneralizedBuresWassersteinMetric with matrix $B$ on the SymmetricPositiveDefinite M. Here X represents the linear function on the tangent space at p with respect to the EuclideanMetric g_E.
To be precise we are looking for $ZβT_p\mathcal P(n)$ such that for all $YβT_p\mathcal P(n)$ it holds
\[β¨X,Yβ© = \operatorname{tr}(XY) = β¨Z,Yβ©_{\mathrm{BW}}\]
for all $Y$ and hence we get $Z = 2pXB + 2BXp$.
ManifoldsBase.distance β Method
distance(M::MetricManifold{β,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric}, p, q)Compute the distance on the SymmetricPositiveDefinite manifold M with respect to the GeneralizedBuresWassersteinMetric with matrix $B$, i.e.
\[d(p,q) = \sqrt{\operatorname{tr}(B^{-1}p) + \operatorname{tr}(B^{-1}q) - 2\operatorname{tr}\bigl((B^{-1}qB^{-1}p)^{\frac{1}{2}}\bigr)},\]
see [HZ23], Section 3.2, eqs. (24) and (25).
ManifoldsBase.inner β Method
inner(M::MetricManifold{β,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric}, p, X, Y)Compute the inner product on the SymmetricPositiveDefinite manifold M with respect to the GeneralizedBuresWassersteinMetric with matrix $B$, given in Eq. (3) of [HMJG23] by
\[ β¨X,Yβ© = \frac{1}{2}\operatorname{tr}(L_{p,B}(X)Y)\]
where $q=L_{p,B}(X)$ denotes the generalized Lyapunov operator, i.e. it solves $pqB + Bqp = X$, as defined below Eq. (3) there.
ManifoldsBase.is_flat β Method
is_flat(::MetricManifold{β,<:SymmetricPositiveDefinite,<:GeneralizedBuresWassersteinMetric})Return false. SymmetricPositiveDefinite with GeneralizedBuresWassersteinMetric is not a flat manifold.
Log-Euclidean metric
Manifolds.LogEuclideanMetric β Type
LogEuclideanMetric <: RiemannianMetricThe LogEuclidean Metric consists of the Euclidean metric applied to all elements after mapping them into the Lie Algebra, i.e. performing a matrix logarithm beforehand.
ManifoldsBase.distance β Method
distance(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogEuclideanMetric}, p, q)Compute the distance on the SymmetricPositiveDefinite manifold between p and q as a MetricManifold with LogEuclideanMetric. The formula reads
\[ d_{\mathcal P(n)}(p,q) = \lVert \operatorname{Log} p - \operatorname{Log} q \rVert_{\mathrm{F}}\]
where $\operatorname{Log}$ denotes the matrix logarithm and $\lVertβ \rVert_{\mathrm{F}}$ denotes the matrix Frobenius norm.
ManifoldsBase.is_flat β Method
is_flat(::MetricManifold{β,<:SymmetricPositiveDefinite,LogEuclideanMetric})Return true. SymmetricPositiveDefinite with LogEuclideanMetric is a flat manifold: its metric is the pullback of an inner product on the symmetric matrices by the matrix logarithm, so it is isometric to a Euclidean space and its curvature is zero, see Section 3.2 and Table 4 of [TP23].
ManifoldsBase.riemann_tensor β Method
riemann_tensor(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogEuclideanMetric}, p, X, Y, Z)Compute the Riemann tensor $R(X,Y)Z$ at p on the SymmetricPositiveDefinite matrices M with the LogEuclideanMetric. Its value is always the zero tangent vector, since $R = 0$ for this metric, see Table 4 of [TP23].
ManifoldsBase.sectional_curvature β Method
sectional_curvature(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogEuclideanMetric}, p, X, Y)Return the sectional curvature $ΞΊ_p(X,Y) = 0$ of the SymmetricPositiveDefinite matrices M with the LogEuclideanMetric. The Riemann tensor of this metric is $R = 0$, see Table 4 of [TP23], so $β¨R(X,Y)Y,Xβ©_p = 0$ for all linearly independent $X, Y β T_p\mathcal M$.
ManifoldsBase.sectional_curvature_max β Method
sectional_curvature_max(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogEuclideanMetric})Return the upper bound 0 of the sectional curvature of the SymmetricPositiveDefinite matrices M with the LogEuclideanMetric. The Riemann tensor of this metric is $R = 0$, see Table 4 of [TP23], so every sectional curvature is 0.
ManifoldsBase.sectional_curvature_min β Method
sectional_curvature_min(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogEuclideanMetric})Return the lower bound 0 of the sectional curvature of the SymmetricPositiveDefinite matrices M with the LogEuclideanMetric. The Riemann tensor of this metric is $R = 0$, see Table 4 of [TP23], so every sectional curvature is 0.
Log-Cholesky metric
Manifolds.LogCholeskyMetric β Type
LogCholeskyMetric <: RiemannianMetricThe Log-Cholesky metric imposes a metric based on the Cholesky decomposition as introduced by [Lin19].
Base.exp β Method
exp(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, X)Compute the exponential map on the SymmetricPositiveDefinite M with LogCholeskyMetric from p into direction X. The formula reads
\[\exp_p X = (\exp_y W)(\exp_y W)^\mathrm{T}\]
where $\exp_xW$ is the exponential map on CholeskySpace, $y$ is the Cholesky decomposition of $p$, $W = y(y^{-1}Xy^{-\mathrm{T}})_\frac{1}{2}$, and $(β
)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$.
Base.log β Method
log(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)Compute the logarithmic map on SymmetricPositiveDefinite M with respect to the LogCholeskyMetric emanating from p to q. The formula can be adapted from the CholeskySpace as
\[\log_p q = xW^{\mathrm{T}} + Wx^{\mathrm{T}},\]
where $x$ is the Cholesky factor of $p$ and $W=\log_x y$ for $y$ the Cholesky factor of $q$ and the just mentioned logarithmic map is the one on CholeskySpace.
ManifoldsBase.distance β Method
distance(M::MetricManifold{SymmetricPositiveDefinite,LogCholeskyMetric}, p, q)Compute the distance on the manifold of SymmetricPositiveDefinite matrices, i.e. between two symmetric positive definite matrices p and q with respect to the LogCholeskyMetric. The formula reads
\[d_{\mathcal P(n)}(p,q) = \sqrt{ \lVert β x β - β y β \rVert_{\mathrm{F}}^2 + \lVert \log(\operatorname{diag}(x)) - \log(\operatorname{diag}(y))\rVert_{\mathrm{F}}^2 }\ \ ,\]
where $x$ and $y$ are the Cholesky factors of $p$ and $q$, respectively, $ββ β$ denotes the strictly lower triangular matrix of its argument, and $\lVertβ \rVert_{\mathrm{F}}$ the Frobenius norm.
ManifoldsBase.inner β Method
inner(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric}, p, X, Y)Compute the inner product of two matrices X, Y in the tangent space of p on the SymmetricPositiveDefinite manifold M, as a MetricManifold with LogCholeskyMetric. The formula reads
\[ g_p(X,Y) = β¨a_z(X),a_z(Y)β©_z,\]
where $β¨β
,β
β©_x$ denotes inner product on the CholeskySpace, $z$ is the Cholesky factor of $p$, $a_z(W) = z (z^{-1}Wz^{-\mathrm{T}})_{\frac{1}{2}}$, and $(β
)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$
ManifoldsBase.is_flat β Method
is_flat(::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric})Return true. SymmetricPositiveDefinite with LogCholeskyMetric is a flat manifold. See Proposition 8 of [Lin19].
ManifoldsBase.parallel_transport_to β Method
vector_transport_to(
M::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric},
p,
X,
q,
::ParallelTransport,
)Parallel transport the tangent vector X at p along the geodesic to q with respect to the SymmetricPositiveDefinite manifold M and LogCholeskyMetric. The parallel transport is based on the parallel transport on CholeskySpace: Let $x$ and $y$ denote the Cholesky factors of p and q, respectively and $W = x(x^{-1}Xx^{-\mathrm{T}})_\frac{1}{2}$, where $(β
)_\frac{1}{2}$ denotes the lower triangular matrix with the diagonal multiplied by $\frac{1}{2}$. With $V$ the parallel transport of $W$ on CholeskySpace from $x$ to $y$, the formula here reads
\[\mathcal P_{qβp}X = yV^{\mathrm{T}} + Vy^{\mathrm{T}}.\]
ManifoldsBase.riemann_tensor β Method
riemann_tensor(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric}, p, X, Y, Z)Compute the Riemann tensor $R(X,Y)Z$ at p on the SymmetricPositiveDefinite matrices M with the LogCholeskyMetric. Its value is always the zero tangent vector, since M is flat.
ManifoldsBase.sectional_curvature β Method
sectional_curvature(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric}, p, X, Y)Return the sectional curvature 0 of the SymmetricPositiveDefinite matrices M with the LogCholeskyMetric, which is flat.
ManifoldsBase.sectional_curvature_max β Method
sectional_curvature_max(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric})Return the upper bound 0 of the sectional curvature of the SymmetricPositiveDefinite matrices M with the LogCholeskyMetric, which is flat.
ManifoldsBase.sectional_curvature_min β Method
sectional_curvature_min(M::MetricManifold{β,<:SymmetricPositiveDefinite,LogCholeskyMetric})Return the lower bound 0 of the sectional curvature of the SymmetricPositiveDefinite matrices M with the LogCholeskyMetric, which is flat.
Statistics
Statistics.mean β Method
mean(
M::SymmetricPositiveDefinite,
x::AbstractVector,
[w::AbstractWeights,]
method = GeodesicInterpolation();
kwargs...,
)Compute the Riemannian mean of x using GeodesicInterpolation.
Efficient representation
When a point p is used in several occasions, it might be beneficial to store the eigenvalues and vectors of p and optionally its square root and the inverse of the square root. The SPDPoint can be used for exactly that.
Manifolds.SPDPoint β Type
SPDPoint <: AbstractManifoldsPointStore the result of eigen(p) of an SPD matrix and (optionally) $p^{1/2}$ and $p^{-1/2}$ to avoid their repeated computations.
This result only has the result of eigen as a mandatory storage, the other three can be stored. If they are not stored they are computed and returned (but then still not stored) when required.
Constructor
SPDPoint(p::AbstractMatrix; store_p=true, store_sqrt=true, store_sqrt_inv=true)Create an SPD point using a symmetric positive definite matrix p, where you can optionally store p, sqrt and sqrt_inv.
and there are three internal functions to be able to use SPDPoint interchangeably with the default representation as a matrix.
Manifolds.spd_sqrt β Function
spd_sqrt(p::AbstractMatrix)
spd_sqrt(p::SPDPoint)return $p^{\frac{1}{2}}$ by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.
This method assumes that p represents an spd matrix.
Manifolds.spd_sqrt_inv β Function
spd_sqrt_inv(p::SPDPoint)return $p^{-\frac{1}{2}}$ by either computing it (if it is missing or for the AbstractMatrix) or returning the stored value from within the SPDPoint.
This method assumes that p represents an spd matrix.
Manifolds.spd_sqrt_and_sqrt_inv β Function
spd_sqrt_and_sqrt_inv(p::AbstractMatrix)
spd_sqrt_and_sqrt_inv(p::SPDPoint)return $p^{\frac{1}{2}}$ and $p^{-\frac{1}{2}}$ by either computing them (if they are missing or for the AbstractMatrix) or returning their stored value from within the SPDPoint.
Compared to calling single methods spd_sqrt and spd_sqrt_inv this method only computes the eigenvectors once for the case of the AbstractMatrix or if both are missing.
This method assumes that p represents an spd matrix.
Literature
- [CKA17]
- E.Β Chevallier, E.Β Kalunga and J.Β Angulo. Kernel Density Estimation on Spaces of Gaussian Distributions and Symmetric Positive Definite Matrices. SIAMΒ JournalΒ onΒ ImagingΒ Sciences 10, 191β215 (2017).
- [CB23]
- C.Β Criscitiello and N.Β Boumal. An Accelerated First-Order Method for Non-convex Optimization on Manifolds. FoundationsΒ ofΒ ComputationalΒ Mathematics 23, 1433β1509 (2023).
- [HMJG21]
- A.Β Han, B.Β Mishra, P.Β Jawanpuria and J.Β Gao. Learning with symmetric positive definite matrices via generalized Bures-Wasserstein geometry, arXivΒ Preprint (2021), arXiv:2110.10464.
- [HMJG23]
- A.Β Han, B.Β Mishra, P.Β Jawanpuria and J.Β Gao. Learning with Symmetric Positive Definite Matrices via Generalized Bures-Wasserstein Geometry. In: Geometric Science of Information, Vol.Β 14071 of Lecture Notes in Computer Science, edited by F.Β Nielsen and F.Β Barbaresco (Springer Nature Switzerland, 2023); pp.Β 405β415.
- [HZ23]
- Z.Β Huang and L.Β Zheng. Target detection based on generalized BuresβWasserstein distance. EURASIPΒ JournalΒ onΒ AdvancesΒ inΒ SignalΒ Processing 2023 (2023).
- [Lin19]
- Z.Β Lin. Riemannian Geometry of Symmetric Positive Definite Matrices via Cholesky Decomposition. SIAMΒ JournalΒ onΒ MatrixΒ AnalysisΒ andΒ Applications 40, 1353β1370 (2019), arXiv:1908.09326.
- [MMP18]
- L.Β MalagΓ³, L.Β Montrucchio and G.Β Pistone. Wasserstein Riemannian geometry of Gaussian densities. InformationΒ Geometry 1, 137β179 (2018).
- [Ngu23]
- D.Β Nguyen. Operator-Valued Formulas for Riemannian Gradient and Hessian and Families of Tractable Metrics in Riemannian Optimization. JournalΒ ofΒ OptimizationΒ TheoryΒ andΒ Applications 198, 135β164 (2023), arXiv:2009.10159.
- [Ren11]
- Q.Β Rentmeesters. A gradient method for geodesic data fitting on some symmetric Riemannian manifolds. In: IEEE Conference on Decision and Control and European Control Conference (2011); pp.Β 7141β7146.
- [dSLCY25]
- T.Β deΒ Surrel, F.Β Lotte, S.Β Chevallier and F.Β Yger. Wrapped Gaussian on the manifold of Symmetric Positive Definite Matrices. In: Proceedings of the 42nd International Conference on Machine Learning, Vol.Β 267 of Proceedings of Machine Learning Research (PMLR, 2025); pp.Β 12816β12839.
- [TP23]
- Y.Β Thanwerdas and X.Β Pennec. O(n)-invariant Riemannian metrics on SPD matrices. LinearΒ AlgebraΒ andΒ itsΒ Applications 661, 163β201 (2023).