Geometries¶

yetanotherspdnet.functions.spd_geometries — one module per Riemannian geometry of the SPD manifold, each with its geodesic, mean, scalar dispersion and, where the batch normalization needs them, exponential and logarithmic maps. The Geometries on the SPD manifold guide compares them and gives their formulas.

Module	Geometry	Mean used by the batch normalization
`affine_invariant`	affine-invariant (Fisher–Rao)	Karcher mean (iterative)
`log_euclidean`	log-Euclidean	\(\exp(\overline{\log X})\)
`kullback_leibler`	left / right Kullback–Leibler	arithmetic / harmonic mean
`kullback_leibler_symmetrized`	symmetrized Kullback–Leibler	GAH: AI midpoint of harmonic and arithmetic (adaptive: learned point \(t\))
`bures_wasserstein`	Bures–Wasserstein	fixed-point barycenter

Affine-invariant¶

autograd path	manual backward
`affine_invariant_geodesic()`	`AffineInvariantGeodesic`	Affine-invariant geodesic between two SPD matrices.
`affine_invariant_mean_2points()`	`AffineInvariantMean2Points`	Affine-invariant (geometric) mean of two SPD matrices.
`AffineInvariantMean()`	–	Affine-invariant (geometric) mean computed with fixed-point algorithm
–	`AffineInvariantMeanIteration`	One iteration of the fixed-point algorithm computing the affine-invariant (geometric) mean
`affine_invariant_std_scalar()`	`AffineInvariantStdScalar`	Scalar standard deviation with respect to the affine-invariant distance.
`affine_invariant_exp()`	`AffineInvariantExp`	Affine-invariant exponential map on the SPD manifold.
`affine_invariant_log()`	–	Affine-invariant logarithmic map on the SPD manifold.
`affine_invariant_projx()`	–	Project matrices onto the SPD manifold by symmetrizing and clamping eigenvalues to [1e-8, 1e8] (as in the reference RResNet implementation, which also bounds the conditioning).

Affine-invariant Riemannian geometry: geodesic, exp/log maps, mean, and standard deviation.

affine_invariant_geodesic(point1, point2, t)[source]¶

Affine-invariant geodesic between two SPD matrices.

\[\gamma(t) = P_1^{1/2} \big(P_1^{-1/2} P_2 P_1^{-1/2}\big)^{t} P_1^{1/2}\]

with \(t \in [0, 1]\) (\(\gamma(0) = P_1\), \(\gamma(1) = P_2\)). This is the geodesic for the affine-invariant Riemannian metric on the SPD manifold, invariant under congruence transformations \(P \mapsto A P A^\top\) for any invertible \(A\).

Parameters:

point1 (torch.Tensor of shape (..., n_features, n_features)) – SPD matrices
point2 (torch.Tensor of shape (..., n_features, n_features)) – SPD matrices
t (float | torch.Tensor) – parameter on the path, should be in [0,1]

Returns:

point (torch.Tensor of shape (..., n_features, n_features)) – SPD matrices

Return type:

autograd path	manual backward
`LogEuclideanGeodesic()`	–	Log-Euclidean geodesic between two batches of SPD matrices
`LogEuclideanMean()`	–	Log-Euclidean mean
`log_euclidean_std_scalar()`	`LogEuclideanStdScalar`	Scalar standard deviation with respect to the Log-Euclidean distance.

autograd path	manual backward
`euclidean_geodesic()`	`EuclideanGeodesic`	Euclidean geodesic between two symmetric matrices.
`arithmetic_mean()`	`ArithmeticMean`	Arithmetic (Euclidean) mean of a batch of symmetric matrices.
`left_kullback_leibler_std_scalar()`	`LeftKullbackLeiblerStdScalar`	Scalar standard deviation with respect to the left Kullback-Leibler divergence.
`harmonic_curve()`	`HarmonicCurve`	Curve for adaptive harmonic mean computation.
`harmonic_mean()`	`HarmonicMean`	Harmonic mean of a batch of SPD matrices.
`right_kullback_leibler_std_scalar()`	`RightKullbackLeiblerStdScalar`	Scalar standard deviation with respect to the right Kullback-Leibler divergence (docstring previously said “left” — copy-paste bug, fixed).

autograd path	manual backward
`GeometricEuclideanHarmonicCurve()`	–	Curve corresponding to the geometric mean of the Euclidean geodesic and the harmonic curve
`GeometricArithmeticHarmonicMean()`	–	Geometric mean of the arithmetic and harmonic means
`symmetrized_kullback_leibler_std_scalar()`	`SymmetrizedKullbackLeiblerStdScalar`	Scalar standard deviation with respect to the symmetrized Kullback-Leibler (Jeffreys) divergence.
`adaptive_geometric_arithmetic_harmonic_geodesic()`	`AdaptiveGeometricArithmeticHarmonicGeodesic`	Adaptive (AdaptiveGAH) geodesic between harmonic (point1) and arithmetic (point2) means, with a learnable position :math:`t` on the path.
`AdaptiveGeometricArithmeticHarmonicMean()`	–	Adaptive geometric mean of the arithmetic and harmonic means with learnable t (using custom autograd Function for efficient gradients)

autograd path	manual backward
`bures_wasserstein_distance_squared()`	–	Squared Bures-Wasserstein distance between SPD matrices.
`bures_wasserstein_log_identity()`	–	Logarithmic map at the identity under Bures-Wasserstein geometry.
`bures_wasserstein_exp_identity()`	–	Exponential map at the identity under Bures-Wasserstein geometry.
`bures_wasserstein_log()`	–	Logarithmic map at a general base point under BW geometry.
–	`LyapunovSolveSPD`	Solution :math:`Z` of :math:`BZ + ZB = V` for SPD :math:`B`, with an implicit backward.
`bures_wasserstein_parallel_transport_to_identity()`	–	Parallel transport from source to the identity under BW geometry.
`bures_wasserstein_parallel_transport_from_identity()`	–	Parallel transport from the identity to target under BW geometry.
–	`ParallelTransportFromIdentityBW`	BW transport from the identity, :math:`\Gamma_{I\to G} = \mathcal{A}_G^{1/2}`, with a backward that stays finite for repeated eigenvalues of :math:`G`.
`bures_wasserstein_geodesic()`	–	Bures-Wasserstein geodesic (closed-form 2-sample weighted mean).
`BuresWassersteinMean()`	–	Bures-Wasserstein barycenter (Frechet mean) – CamelCase wrapper.
`bures_wasserstein_std_scalar()`	`BuresWassersteinStdScalar`	Scalar standard deviation under the Bures-Wasserstein distance.
`bures_wasserstein_center()`	–	Center SPD data by parallel-transporting from the barycenter to the identity.
`bures_wasserstein_scale()`	–	Scale centered SPD data at the identity.
`bures_wasserstein_bias()`	–	Bias SPD data by parallel-transporting from the identity to bias_point.

Geometries¶

Affine-invariant¶

Log-Euclidean¶

Kullback–Leibler (arithmetic and harmonic)¶

Symmetrized Kullback–Leibler (GAH)¶

Bures–Wasserstein¶