geomstats.variants.geometry package#

Submodules#

geomstats.variants.geometry.discrete_curves module#

Non-vectorized dynamic programming aligner for discrete curves.

class geomstats.variants.geometry.discrete_curves.DynamicProgrammingAligner(total_space, n_space_grid=100, max_slope=6)[source]#

Bases: AlignerAlgorithm

Align two curves through dynamic programming.

Variant of geomstats.geometry.discrete_curves.DynamicProgrammingAligner with a non-vectorized implementation.

Find the reparametrization gamma of end_curve that minimizes the distance between initial_curve and end_curve reparametrized by gamma, and output the corresponding distance, using a dynamic programming algorithm.

The objective can be expressed in terms of square root velocity (SRV) representations: it is equivalent to finding the gamma that maximizes the L2 scalar product between \(initial_{srv}\) and \(end_{srv}@\gamma\), where \(initial_{srv}\) is the SRV representation of the initial curve and \(end_{srv}@\gamma\) is the SRV representation of the end curve reparametrized by \(\gamma\), i.e

\[end_{srv}@\gamma(t) = end_{srv}(\gamma(t))\cdot|\gamma(t)|^\frac{1}{2}\]

The dynamic programming algorithm assumes that for every subinterval \(\left[\frac{i}{n},\frac{i+1}{n}\right]\) of \(\left[0,1\right]\), gamma is linear.

Parameters:

  • total_space (Manifold) – Total space with reparametrizations fiber bundle structure.

  • n_space_grid (int) – Number of sampling points of the unit interval.

  • max_slope (int) – Maximum slope allowed for a reparametrization.

References

[WAJ2007]

M. Washington, S. Anuj & H. Joshi, “On Shape of Plane Elastic Curves”, in International Journal of Computer Vision. 73(3):307-324, 2007.

align(point, base_point, return_sdist=False)[source]#

Align point to base point.

Parameters:

  • point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Discrete curve to align.

  • base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Reference discrete curve.

  • return_sdist (bool) – If True, also returns squared distance.

Returns:

  • aligned (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Curve reparametrized in an optimal way with respect to reference curve.

  • squared_dist (array, shape=[…,]) – Quotient distance between point and base point. If return_sdist is True.

geomstats.variants.geometry.positive_lower_triangular_matrices module#

Matrix logarithm on unit-diagonal lower triangular matrices with logm and expm.

class geomstats.variants.geometry.positive_lower_triangular_matrices.LowerMatrixLog[source]#

Bases: Diffeo

Matrix logarithm diffeomorphism.

Variant of geomstats.geometry.positive_lower_triangular_matrices.LowerMatrixLog computed with the general matrix logarithm and exponential.

A diffeomorphism between the lower triangular matrices with unit diagonal and strictly lower triangular matrices.

Notes

The differentials use that, for a matrix function \(f\),

\[\begin{split}f\left(\begin{bmatrix} X & E \\ 0 & X \end{bmatrix}\right) = \begin{bmatrix} f(X) & d_X f(E) \\ 0 & f(X) \end{bmatrix}\end{split}\]
static inverse(image_point)[source]#

Compute the matrix exponential.

Parameters:

image_point (array_like, shape=[…, n, n]) – Strictly lower triangular matrix.

Returns:

exponential (array_like, shape=[…, n, n]) – Lower triangular matrix with unit diagonal.

inverse_tangent(image_tangent_vec, image_point=None, base_point=None)[source]#

Inverse tangent diffeomorphism at image point.

Parameters:

  • image_tangent_vec (array-like, shape=[…, n, n]) – Image tangent vector at image point.

  • image_point (array-like, shape=[…, n, n]) – Image point.

  • base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point.

tangent(tangent_vec, base_point=None, image_point=None)[source]#

Tangent diffeomorphism at base point.

Parameters:

  • tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point.

  • base_point (array-like, shape=[…, n, n]) – Base point.

  • image_point (array-like, shape=[…, n, n]) – Image point.

Returns:

image_tangent_vec (array-like, shape=[…, n, n]) – Image tangent vector at image of the base point.

geomstats.variants.geometry.positive_reals module#

Logarithmic metric on the positive reals as a pullback diffeo metric.

class geomstats.variants.geometry.positive_reals.LogDiffeo[source]#

Bases: Diffeo

Logarithm diffeomorphism from the positive reals to the reals.

\[\log: \mathbb{R}_{>0} \rightarrow \mathbb{R}, \quad x \mapsto \log x\]

with inverse the exponential function and differentials

\[d\log_x(u) = \frac{u}{x}, \quad d\exp_z(w) = e^z w\]
inverse(image_point)[source]#

Inverse diffeomorphism at image point.

Parameters:

image_point (array-like, shape=[…, 1]) – Image point.

Returns:

base_point (array-like, shape=[…, 1]) – Base point.

inverse_tangent(image_tangent_vec, image_point=None, base_point=None)[source]#

Inverse tangent diffeomorphism at image point.

Parameters:

  • image_tangent_vec (array-like, shape=[…, 1]) – Image tangent vector at image point.

  • image_point (array-like, shape=[…, 1]) – Image point.

  • base_point (array-like, shape=[…, 1]) – Base point.

Returns:

tangent_vec (array-like, shape=[…, 1]) – Tangent vector at base point.

tangent(tangent_vec, base_point=None, image_point=None)[source]#

Tangent diffeomorphism at base point.

Parameters:

  • tangent_vec (array-like, shape=[…, 1]) – Tangent vector at base point.

  • base_point (array-like, shape=[…, 1]) – Base point.

  • image_point (array-like, shape=[…, 1]) – Image point.

Returns:

image_tangent_vec (array-like, shape=[…, 1]) – Image tangent vector at image of the base point.

class geomstats.variants.geometry.positive_reals.PullbackPositiveRealsMetric(space)[source]#

Bases: PullbackDiffeoMetric

Logarithmic metric on the positive reals.

Variant of geomstats.geometry.positive_reals.PositiveRealsMetric obtained by pulling back the Euclidean metric through the logarithm:

\[g_x(u, v) = \frac{uv}{x^2}\]
Parameters:

space (PositiveReals) – Manifold.

geomstats.variants.geometry.spd_matrices module#

Bures-Wasserstein metric on SPD matrices as a quotient metric.

Importing this module registers the quotient structure of the positive general linear group under the special orthogonal compose action, so that PositiveGeneralLinear.equip_with_quotient induces the Bures-Wasserstein metric on SPD matrices.

class geomstats.variants.geometry.spd_matrices.PositiveGeneralLinearGramBundle(total_space)[source]#

Bases: FiberBundle

Gram map bundle from the positive general linear group to SPD matrices.

The Gram map \(X \mapsto XX^T\) is invariant under the right action of the special orthogonal group, and induces a diffeomorphism from the quotient \(GL^+(n) / SO(n)\) to SPD matrices.

Variant of geomstats.geometry.spd_matrices.SPDBuresWassersteinMetric obtained as the quotient of the Frobenius metric on the positive general linear group.

Parameters:

total_space (PositiveGeneralLinear) – Total space.

align(point, base_point)[source]#

Align point to base point.

Denoting point by \(X\) and base_point by \(Y\), find the rotation \(R \in SO(n)\) minimizing \(\|XR - Y\|_F\). This is the orthogonal Procrustes problem: with the singular value decomposition \(X^T Y = U \Sigma V^T\), the minimizer is \(R = UV^T\).

Since \(\det(X^T Y) > 0\) on the positive general linear group, \(\det(UV^T) = 1\), so no determinant correction is needed.

Parameters:

  • point (array-like, shape=[…, n, n]) – Point of the total space to align.

  • base_point (array-like, shape=[…, n, n]) – Point of the total space.

Returns:

aligned_point (array-like, shape=[…, n, n]) – Point of the fiber of point closest to base_point.

horizontal_lift(tangent_vec, base_point=None, fiber_point=None)[source]#

Lift a tangent vector to a horizontal vector in the total space.

Denoting tangent_vec by \(W\), base_point by \(P\) and fiber_point by \(X\), the horizontal lift is

\[V = SX\]

where \(S\) is the symmetric solution of the Sylvester equation \(PS + SP = W\).

Parameters:

  • tangent_vec (array-like, shape=[…, n, n]) – Tangent vector to SPD matrices at base_point.

  • base_point (array-like, shape=[…, n, n]) – SPD matrix. Optional, default: None. In this case, fiber_point must be given, and riemannian_submersion is used to compute base_point.

  • fiber_point (array-like, shape=[…, n, n]) – Point of the total space in the fiber above base_point. Optional, default: None. In this case, lift is used to compute fiber_point.

Returns:

horizontal_lift (array-like, shape=[…, n, n]) – Horizontal tangent vector to the total space at fiber_point.

static lift(point)[source]#

Lift an SPD matrix to the total space with the Cholesky factor.

The Cholesky factor is lower triangular with positive diagonal, so it has a positive determinant.

Parameters:

point (array-like, shape=[…, n, n]) – SPD matrix.

Returns:

lift (array-like, shape=[…, n, n]) – Point of the total space.

static riemannian_submersion(point)[source]#

Project a point to SPD matrices with the Gram map.

\[\pi(X) = XX^T\]
Parameters:

point (array-like, shape=[…, n, n]) – Point of the total space.

Returns:

projection (array-like, shape=[…, n, n]) – SPD matrix.

tangent_riemannian_submersion(tangent_vec, base_point)[source]#

Project a tangent vector to SPD matrices.

Differential of the Gram map:

\[d\pi_X(V) = XV^T + VX^T\]
Parameters:

  • tangent_vec (array-like, shape=[…, n, n]) – Tangent vector to the total space at base_point.

  • base_point (array-like, shape=[…, n, n]) – Point of the total space.

Returns:

projection (array-like, shape=[…, n, n]) – Symmetric matrix, tangent to SPD matrices at the projection of base_point.

class geomstats.variants.geometry.spd_matrices.QuotientSPDBuresWassersteinMetric(space, total_space=None)[source]#

Bases: QuotientMetric

Bures-Wasserstein metric on SPD matrices as a quotient metric.

Variant of geomstats.geometry.spd_matrices.SPDBuresWassersteinMetric obtained as the quotient of the Frobenius metric on the positive general linear group by the right action of the special orthogonal group.

Parameters:

  • space (SPDMatrices) – Base manifold.

  • total_space (PositiveGeneralLinear) – Total space. Optional, default: None. In this case, it is equipped with the Frobenius metric and the special orthogonal compose action.

Module contents#

Alternative implementations of geometries in geomstats.geometry.