geomstats.geometry package#

Subpackages#

geomstats.geometry.stratified package

Submodules#

geomstats.geometry.base module#

Abstract classes for manifolds.

Lead authors: Nicolas Guigui and Nina Miolane.

class geomstats.geometry.base.ComplexVectorSpace(shape, dim=None, **kwargs)[source]#

Bases: ComplexManifold, ABC

Abstract class for complex vector spaces.

Parameters:

shape (tuple) – Shape of the elements of the vector space. The dimension is the product of these values by default.
default_point_type (str, {‘vector’, ‘matrix’}) – Point type. Optional, default: ‘vector’.

property basis#: Basis of the vector space.

belongs(point, atol=1e-12)[source]#

Evaluate if the point belongs to the vector space.

This method checks the shape of the input point.

Parameters:

point (array-like, shape=[.., *point_shape]) – Point to test.
atol (float) – Unused here.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the space.

is_tangent(vector, base_point=None, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Tangent vectors are identified with points of the vector space so this checks the shape of the input vector.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point in the vector space.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

static projection(point)[source]#

Project a point to the vector space.

This method is for compatibility and returns point. point should have the right shape,

Parameters:: point (array-like, shape[…, *point_shape]) – Point.
Returns:: point (array-like, shape[…, *point_shape]) – Point.

random_point(n_samples=1, bound=1.0)[source]#

Sample in the complex vector space with a uniform distribution in a box.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Side of hypercube support of the uniform distribution. Optional, default: 1.0

Returns:

point (array-like, shape=[…, *point_shape]) – Sample.

to_tangent(vector, base_point=None)[source]#

Project a vector to a tangent space of the vector space.

This method is for compatibility and returns vector.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point in the vector space

Returns:

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

class geomstats.geometry.base.ComplexVectorSpaceOpenSet(embedding_space, shape=None, **kwargs)[source]#

Bases: ComplexManifold, ABC

Class for manifolds that are open sets of a complex vector space.

In this case, tangent vectors are identified with vectors of the embedding space.

Parameters:

dim (int) – Dimension of the manifold. It is often the same as the embedding space dimension but may differ in some cases.
embedding_space (VectorSpace) – Embedding space that contains the manifold.

is_tangent(vector, base_point=None, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

abstract projection(point)[source]#

Project a point in embedding manifold on manifold.

Parameters:: point (array-like, shape=[…, *point_shape]) – Point in embedding manifold.
Returns:: projected (array-like, shape=[…, *point_shape]) – Projected point.

random_point(n_samples=1, bound=1.0)[source]#

Sample random points on the manifold.

If the manifold is compact, a uniform distribution is used.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample for non compact manifolds. Optional, default: 1.

Returns:

samples (array-like, shape=[…, *point_shape]) – Points sampled on the hypersphere.

to_tangent(vector, base_point=None)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.

Returns:

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

class geomstats.geometry.base.DiffeomorphicManifold(diffeo, image_space, **kwargs)[source]#

Bases: Manifold

A manifold defined by a diffeomorphism.

random_point(n_samples=1, bound=1.0)[source]#

Sample random points on the manifold according to some distribution.

If the manifold is compact, preferably a uniform distribution will be used.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample for non compact manifolds. Optional, default: 1.

Returns:

samples (array-like, shape=[…, *point_shape]) – Points sampled on the manifold.

random_tangent_vec(base_point, n_samples=1)[source]#

Generate random tangent vec.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
base_point (array-like, shape={[n_samples, *point_shape], [*point_shape,]}) – Point.

Returns:

tangent_vec (array-like, shape=[…, *point_shape]) – Tangent vec at base point.

regularize(point)[source]#

Regularize a point to the canonical representation for the manifold.

Parameters:: point (array-like, shape=[…, dim]) – Point.
Returns:: regularized_point (array-like, shape=[…, *point_shape]) – Regularized point.

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.

Returns:

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

class geomstats.geometry.base.ImmersedSet(dim, equip=True)[source]#

Bases: Manifold, ABC

Class for manifolds embedded in a vector space by an immersion.

The manifold is represented with intrinsic coordinates, such that the immersion gives a parameterization of the manifold in these coordinates.

Parameters:: dim (int) – Dimension of the embedded manifold.

belongs(point, atol=1e-12)[source]#

Evaluate if a point belongs to the manifold.

Parameters:

point (array-like, shape=[…, dim]) – Point to evaluate.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the manifold.

static default_metric()[source]#: Metric to equip the space with if equip is True.

hessian_immersion(base_point)[source]#

Compute the Hessian of the immersion.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: hessian_immersion (array-like, shape=[…, embedding_dim, dim, dim]) – Hessian at the base point

abstract immersion(point)[source]#

Evaluate the immersion function at a point.

Parameters:: point (array-like, shape=[…, dim]) – Point in the immersed manifold.
Returns:: immersion (array-like, shape=[…, dim_embedding]) – Immersion of the point.

is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

jacobian_immersion(base_point)[source]#

Evaluate the Jacobian of the immersion at a point.

Parameters:: base_point (array-like, shape=[…, dim]) – Point in the immersed manifold.
Returns:: jacobian_immersion (array-like, shape=[…, dim_embedding, dim])

projection(point)[source]#

Project a point to the embedded manifold.

This is simply point, since we are in intrinsic coordinates.

Parameters:: point (array-like, shape=[…, dim_embedding]) – Point in the embedding manifold.
Returns:: projected_point (array-like, shape=[…, dim]) – Point in the embedded manifold.

random_point(n_samples=1, bound=1.0)[source]#

Sample random points on the manifold according to some distribution.

If the manifold is compact, preferably a uniform distribution will be used.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample for non compact manifolds. Optional, default: 1.

Returns:

samples (array-like, shape=[…, *point_shape]) – Points sampled on the manifold.

tangent_immersion(tangent_vec, base_point)[source]#

Evaluate the tangent immersion at a tangent vec and point.

Parameters:

tangent_vec (array-like, shape=[…, dim])
base_point (array-like, shape=[…, dim]) – Point in the immersed manifold.

Returns:

tangent_vec_emb (array-like, shape=[…, dim_embedding])

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

This is simply the vector since we are in intrinsic coordinates.

Parameters:

vector (array-like, shape=[…, dim_embedding]) – Vector.
base_point (array-like, shape=[…, dim]) – Point in the embedded manifold.

Returns:

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

class geomstats.geometry.base.LevelSet(default_coords_type='extrinsic', shape=None, **kwargs)[source]#

Bases: Manifold, ABC

Class for manifolds embedded in a vector space by a submersion.

Parameters:: default_coords_type (str, {‘intrinsic’, ‘extrinsic’, etc}) – Coordinate type. Optional, default: ‘extrinsic’.

belongs(point, atol=1e-12)[source]#

Evaluate if a point belongs to the manifold.

Parameters:

point (array-like, shape=[…, *point_shape]) – Point to evaluate.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the manifold.

extrinsic_to_intrinsic_coords(point_extrinsic)[source]#

Convert from extrinsic to intrinsic coordinates.

Parameters:: point_extrinsic (array-like, shape=[…, *embedding_space.point_shape]) – Point in the embedded manifold in extrinsic coordinates, i. e. in the coordinates of the embedding manifold.
Returns:: point_intrinsic (array-lie, shape=[…, *point_shape]) – Point in the embedded manifold in intrinsic coordinates.

intrinsic_to_extrinsic_coords(point_intrinsic)[source]#

Convert from intrinsic to extrinsic coordinates.

Parameters:: point_intrinsic (array-like, shape=[…, *point_shape]) – Point in the embedded manifold in intrinsic coordinates.
Returns:: point_extrinsic (array-like, shape=[…, *embedding_space.point_shape]) – Point in the embedded manifold in extrinsic coordinates.

is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

abstract projection(point)[source]#

Project a point in embedding manifold on embedded manifold.

Parameters:: point (array-like, shape=[…, *embedding_space.point_shape]) – Point in embedding manifold.
Returns:: projected (array-like, shape=[…, *point_shape]) – Projected point.

abstract submersion(point)[source]#

Submersion that defines the manifold.

$\mathrm{submersion}(x)=0$ defines the manifold.

Parameters:: point (array-like, shape=[…, *point_shape])
Returns:: submersed_point (array-like)

abstract tangent_submersion(vector, point)[source]#

Tangent submersion.

Parameters:

vector (array-like, shape=[…, *point_shape])
point (array-like, shape=[…, *point_shape])

Returns:

submersed_vector (array-like)

abstract to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.

Returns:

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

class geomstats.geometry.base.OpenSet(embedding_space, shape=None, **kwargs)[source]#

Bases: Manifold, ABC

Class for manifolds that are open sets.

NB: if the embedding space is a vector space, use VectorSpaceOpenSet.

Parameters:: embedding_space (Manifold) – Embedding space that contains the manifold.

is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

random_point(n_samples=1, bound=1.0)[source]#

Sample random points on the manifold.

Points are sampled from the embedding space using the distribution set for that manifold and then projected to the manifold. As a result, this is not a uniform distribution on the manifold itself.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample for the embedding space. Optional, default: 1.

Returns:

samples (array-like, shape=[…, *point_shape]) – Points sampled on the hypersphere.

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.

Returns:

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

class geomstats.geometry.base.VectorSpace(shape, dim=None, **kwargs)[source]#

Bases: Manifold, ABC

Abstract class for vector spaces.

Parameters:: shape (tuple) – Shape of the elements of the vector space. The dimension is the product of these values by default.

property basis#: Basis of the vector space.

belongs(point, atol=1e-12)[source]#

Evaluate if the point belongs to the vector space.

This method checks the shape of the input point.

Parameters:

point (array-like, shape=[.., *point_shape]) – Point to test.
atol (float) – Unused here.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the space.

is_tangent(vector, base_point=None, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Tangent vectors are identified with points of the vector space so this checks the shape of the input vector.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point in the vector space.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (array-like, shape=[…,]) – Boolean denoting if vector is a tangent vector at the base point.

static projection(point)[source]#

Project a point to the vector space.

This method is for compatibility and returns point. point should have the right shape,

Parameters:: point (array-like, shape[…, *point_shape]) – Point.
Returns:: point (array-like, shape[…, *point_shape]) – Point.

random_point(n_samples=1, bound=1.0)[source]#

Sample in the vector space with a uniform distribution in a box.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Side of hypercube support of the uniform distribution. Optional, default: 1.0

Returns:

point (array-like, shape=[…, *point_shape]) – Sample.

to_tangent(vector, base_point=None)[source]#

Project a vector to a tangent space of the vector space.

This method is for compatibility and returns vector.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point in the vector space

Returns:

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

class geomstats.geometry.base.VectorSpaceOpenSet(embedding_space, shape=None, **kwargs)[source]#

Bases: OpenSet, ABC

Class for manifolds that are open sets of a vector space.

In this case, tangent vectors are identified with vectors of the embedding space.

Parameters:: embedding_space (VectorSpace) – Embedding space that contains the manifold.

is_tangent(vector, base_point=None, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

abstract projection(point)[source]#

Project a point in embedding manifold on manifold.

Parameters:: point (array-like, shape=[…, *point_shape]) – Point in embedding manifold.
Returns:: projected (array-like, shape=[…, *point_shape]) – Projected point.

to_tangent(vector, base_point=None)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.

Returns:

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

geomstats.geometry.complex_manifold module#

Complex manifold module.

In other words, a topological space that locally resembles Hermitian space near each point.

Lead author: Yann Cabanes.

class geomstats.geometry.complex_manifold.ComplexManifold(dim, shape, default_coords_type='intrinsic', equip=True)[source]#

Bases: ABC

Class for complex manifolds.

Parameters:

dim (int) – Dimension of the manifold.
shape (tuple of int) – Shape of one element of the manifold. Optional, default : None.
default_coords_type (str, {‘intrinsic’, ‘extrinsic’, etc}) – Coordinate type. Optional, default: ‘intrinsic’.
equip (bool) – If True, equip space with default metric.

abstract belongs(point, atol=1e-12)[source]#

Evaluate if a point belongs to the manifold.

Parameters:

point (array-like, shape=[…, *point_shape]) – Point to evaluate.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the manifold.

equip_with_metric(Metric=None, **metric_kwargs)[source]#

Equip manifold with Metric.

Parameters:: Metric (Connection object) – If None, default metric will be used.

abstract is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

abstract random_point(n_samples=1, bound=1.0)[source]#

Sample random points on the manifold according to some distribution.

If the manifold is compact, preferably a uniform distribution will be used.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample for non compact manifolds. Optional, default: 1.

Returns:

samples (array-like, shape=[…, *point_shape]) – Points sampled on the manifold.

random_tangent_vec(base_point, n_samples=1)[source]#

Generate random tangent vec.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
base_point (array-like, shape=[…, *point_shape]) – Point.

Returns:

tangent_vec (array-like, shape=[…, *point_shape]) – Tangent vec at base point.

regularize(point)[source]#

Regularize a point to the canonical representation for the manifold.

Parameters:: point (array-like, shape=[…, dim]) – Point.
Returns:: regularized_point (array-like, shape=[…, *point_shape]) – Regularized point.

abstract to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.

Returns:

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

geomstats.geometry.complex_matrices module#

Module exposing the ComplexMatrices class.

Lead author: Yann Cabanes.

class geomstats.geometry.complex_matrices.ComplexMatrices(m, n, equip=True)[source]#

Bases: ComplexVectorSpace

Class for the space of complex matrices (m, n).

Parameters:: m, n (int) – Integers representing the shapes of the matrices: m x n.

belongs(point, atol=1e-12)[source]#

Check if point belongs to the Matrices space.

Parameters:

point (array-like, shape=[…, m, n]) – Point to be checked.
atol (float) – Unused here.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the Matrices space.

classmethod congruent(mat_1, mat_2)[source]#

Compute the congruent action of mat_2 on mat_1.

This is $mat\_2 \ mat\_1 \ mat\_2^T$.

Parameters:

mat_1 (array-like, shape=[…, n, n]) – Matrix.
mat_2 (array-like, shape=[…, n, n]) – Matrix.

Returns:

cong (array-like, shape=[…, n, n]) – Result of the congruent action.

static default_metric()[source]#: Metric to equip the space with if equip is True.

static frobenius_product(mat_1, mat_2)[source]#

Compute Frobenius inner-product of two matrices.

The einsum function is used to avoid computing a matrix product. It is also faster than using a sum an element-wise product.

Parameters:

mat_1 (array-like, shape=[…, m, n]) – Matrix.
mat_2 (array-like, shape=[…, m, n]) – Matrix.

Returns:

product (array-like, shape=[…,]) – Frobenius inner-product of mat_1 and mat_2

classmethod is_hermitian(mat, atol=1e-12)[source]#

Check if a square matrix is Hermitian.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_herm (array-like, shape=[…,]) – Boolean evaluating if the matrix is symmetric.

classmethod is_hpd(mat, atol=1e-12)[source]#

Check if a square matrix is Hermitian positive definite.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_hpd (array-like, shape=[…,]) – Boolean evaluating if the matrix is Hermitian positive definite.

classmethod is_skew_hermitian(mat, atol=1e-12)[source]#

Check if a matrix is skew-Hermitian.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_skew_herm (array-like, shape=[…,]) – Boolean evaluating if the matrix is skew-Hermitian.

random_point(n_samples=1, bound=1.0)[source]#

Sample from a uniform distribution in a complex cube.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample each entry. Optional, default: 1.

Returns:

point (array-like, shape=[…, m, n]) – Sample.

classmethod to_hermitian(mat)[source]#

Make a matrix Hermitian.

Make a matrix Hermitian by averaging it with its transconjugate.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: herm (array-like, shape=[…, n, n]) – Hermitian matrix.

classmethod to_skew_hermitian(mat)[source]#

Make a matrix skew-Hermitian.

Make matrix skew-Hermitian by averaging it with minus its transconjugate.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: skew_sym (array-like, shape=[…, n, n]) – Skew-Hermitian matrix.

static transconjugate(mat)[source]#

Return the transconjugate of matrices.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: transconjugate (array-like, shape=[…, n, n]) – Transconjugated matrix.

class geomstats.geometry.complex_matrices.ComplexMatricesMetric(space, signature=None)[source]#

Bases: HermitianMetric

Hermitian metric on complex matrices given by Frobenius inner-product.

static inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute Frobenius inner-product of two tangent vectors.

Parameters:

tangent_vec_a (array-like, shape=[…, m, n]) – Tangent vector.
tangent_vec_b (array-like, shape=[…, m, n]) – Tangent vector.
base_point (array-like, shape=[…, m, n]) – Base point. Optional, default: None.

Returns:

inner_prod (array-like, shape=[…,]) – Frobenius inner-product of tangent_vec_a and tangent_vec_b.

norm(vector, base_point=None)[source]#

Compute norm of a complex matrix.

Norm of a matrix associated to the Frobenius inner product.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

norm (array-like, shape=[…,]) – Norm.

squared_norm(vector, base_point=None)[source]#

Compute the square of the norm of a vector.

Squared norm of a vector associated to the inner product at the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

sq_norm (array-like, shape=[…,]) – Squared norm.

geomstats.geometry.complex_poincare_disk module#

The complex Poincaré disk manifold.

The Poincaré complex disk is a representation of the Hyperbolic space of dimension 2.

Lead author: Yann Cabanes.

References

[Cabanes2022]

Yann Cabanes. Multidimensional complex stationary centered Gaussian autoregressive time series machine learning in Poincaré and Siegel disks: application for audio and radar clutter classification, PhD thesis, 2022

[JV2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

[Yang2013]

Marc Arnaudon, Frédéric Barbaresco and Le Yang. Riemannian medians and means with applications to radar signal processing, IEEE Journal of Selected Topics in Signal Processing, vol. 7, no. 4, pp. 595-604, Aug. 2013, doi: 10.1109/JSTSP.2013.2261798. https://ieeexplore.ieee.org/document/6514112

class geomstats.geometry.complex_poincare_disk.ComplexPoincareDisk(equip=True)[source]#

Bases: ComplexVectorSpaceOpenSet

Class for the complex Poincaré disk.

The Poincaré disk is a representation of the Hyperbolic space of dimension 2. Its complex dimension is 1.

static belongs(point, atol=1e-12)[source]#

Check if a point belongs to the complex unit disk.

Check if a point belongs to the Poincaré complex disk, i.e. Check if its norm is lower than one.

Parameters:

point (array-like, shape=[…, 1]) – Point to be checked.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…]) – Boolean denoting if point belongs to the complex Poincaré disk.

static default_metric()[source]#: Metric to equip the space with if equip is True.

static projection(point)[source]#

Project a point on the complex unit disk.

Parameters:

point (array-like, shape=[…, 1]) – Point to project.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

projected (array-like, shape=[…, 1]) – Projected point.

static random_point(n_samples=1, bound=0.8)[source]#

Generate random points in the complex unit disk.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample in the tangent space. Optional, default: 0.8.

Returns:

samples (array-like, shape=[…, 1]) – Points sampled in the unit disk.

class geomstats.geometry.complex_poincare_disk.ComplexPoincareDiskMetric(space, signature=None)[source]#

Bases: ComplexRiemannianMetric

Class for the complex Poincaré metric.

dist(point_a, point_b, atol=1e-12)[source]#

Compute the complex Poincaré disk distance.

Compute the Riemannian distance between point_a and point_b.

Parameters:

point_a (array-like, shape=[…, 1]) – Point.
point_b (array-like, shape=[…, 1]) – Point.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

dist (array-like, shape=[…]) – Riemannian distance.

static exp(tangent_vec, base_point)[source]#

Compute the complex Poincaré disk exponential map.

Parameters:

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

Returns:

exp (array-like, shape=[…, 1]) – Riemannian exponential.

log(point, base_point)[source]#

Compute the complex Poincaré disk logarithm map.

Compute the Riemannian logarithm at point base_point, of point wrt the positive reals metric. This gives a tangent vector at point base_point.

Parameters:

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

Returns:

log (array-like, shape=[…, 1]) – Riemannian logarithm.

metric_matrix(base_point)[source]#

Compute the metric matrix at base point.

Parameters:: base_point (array-like, shape=[…, 1]) – Base point.
Returns:: inner_prod_mat (array-like, shape=[…]) – Inner product matrix.

squared_dist(point_a, point_b, atol=1e-12)[source]#

Compute the complex Poincaré disk squared distance.

Compute the Riemannian squared distance between point_a and point_b.

Parameters:

point_a (array-like, shape=[…, 1]) – Point.
point_b (array-like, shape=[…, 1]) – Point.

Returns:

squared_dist (array-like, shape=[…]) – Riemannian squared distance.

geomstats.geometry.complex_riemannian_metric module#

Riemannian and pseudo-Riemannian metrics for complex manifolds.

Lead author: Yann Cabanes.

class geomstats.geometry.complex_riemannian_metric.ComplexRiemannianMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Class for Riemannian and pseudo-Riemannian metrics for Complex manifolds.

The associated Levi-Civita connection on the tangent bundle.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Inner product between two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base point.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

inner_product (array-like, shape=[…,]) – Inner-product.

random_unit_tangent_vec(base_point, n_vectors=1)[source]#

Generate a random unit tangent vector at a given point.

Parameters:

base_point (array-like, shape=[…, dim]) – Point.
n_vectors (float) – Number of vectors to be generated at base_point. For vectorization purposes n_vectors can be greater than 1 iff base_point consists of a single point.

Returns:

normalized_vector (array-like, shape=[…, n_vectors, dim]) – Random unit tangent vector at base_point.

squared_norm(vector, base_point=None)[source]#

Compute the square of the norm of a vector.

Squared norm of a vector associated to the inner product at the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

sq_norm (array-like, shape=[…,]) – Squared norm.

geomstats.geometry.connection module#

Affine connections.

Lead author: Nicolas Guigui.

class geomstats.geometry.connection.Connection(space)[source]#

Bases: ABC

Class for affine connections.

Parameters:: space (Manifold object) – M in the tuple (M, g).

christoffels(base_point)[source]#

Christoffel symbols associated with the connection.

The contravariant index is on the first dimension.

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: gamma (array-like, shape=[…, dim, dim, dim]) – Christoffel symbols, with the contravariant index on the first dimension.

curvature(tangent_vec_a, tangent_vec_b, tangent_vec_c, base_point)[source]#

Compute the Riemann curvature map R.

For three tangent vectors at base point $P$: - $X|_P = tangent\_vec\_a$, - $Y|_P = tangent\_vec\_b$, - $Z|_P = tangent\_vec\_c$, the curvature(X, Y, Z, P) is defined by $R(X,Y)Z = \nabla_X \nabla_Y Z - \nabla_Y \nabla_X Z - \nabla_[X, Y]Z$.

The output is the tangent vector: $dx^l(R(X, Y)Z) = R_{ijk}^l X_j Y_k Z_i$ written with Einstein notation.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_c (array-like, shape=[…, dim]) – Tangent vector at base_point.
base_point (array-like, shape=[…, dim]) – Point on the manifold.

Returns:

curvature (array-like, shape=[…, dim]) – curvature(X, Y, Z, P)[…, l] = dx^l(R(X, Y)Z) Tangent vector at base_point.

curvature_derivative(tangent_vec_a, tangent_vec_b, tangent_vec_c, tangent_vec_d, base_point=None)[source]#

Compute the covariant derivative of the curvature.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_c (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_d (array-like, shape=[…, dim]) – Tangent vector at base_point.
base_point (array-like, shape=[…, dim]) – Point on the manifold.

Returns:

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

directional_curvature(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the directional curvature (tidal force operator).

For two tangent vectors at base_point $P$: - $X|_P = tangent\_vec\_a$, - $Y|_P = tangent\_vec\_b$, the directional curvature, better known in relativity as the tidal force operator, is defined by $R_Y(X) = R(Y,X)Y$.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base_point.
base_point (array-like, shape=[…, dim]) – Base-point on the manifold.

Returns:

directional_curvature (array-like, shape=[…, dim]) – Tangent vector at base_point.

directional_curvature_derivative(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute the covariant derivative of the directional curvature.

For tangent vector fields at base_point $P$: - $X|_P = tangent\_vec\_a$, - $Y|_P = tangent\_vec\_b$, the covariant derivative (in the direction X) $(\nabla_X R_Y)(X) |_P = (\nabla_X R)(Y, X) Y |_P$ of the directional curvature (in the direction Y) $R_Y(X) = R(Y, X) Y$ is a quadratic tensor in X and Y that plays an important role in the computation of the moments of the empirical Fréchet mean.

References

[Pennec]

Pennec, Xavier. Curvature effects on the empirical mean in Riemannian and affine Manifolds: a non-asymptotic high concentration expansion in the small-sample regime. Preprint. 2019. https://arxiv.org/abs/1906.07418

exp(tangent_vec, base_point)[source]#

Exponential map associated to the affine connection.

Parameters:

tangent_vec (array-like, shape=[…, dim]) – Tangent vector at the base point.
base_point (array-like, shape=[…, dim]) – Point on the manifold.

Returns:

exp (array-like, shape=[…, dim]) – Point on the manifold.

geodesic(initial_point, end_point=None, initial_tangent_vec=None)[source]#

Generate parameterized function for the geodesic curve.

Geodesic curve defined by either:

an initial point and an initial tangent vector,
an initial point and an end point.

Parameters:

initial_point (array-like, shape=[…, dim]) – Point on the manifold, initial point of the geodesic.
end_point (array-like, shape=[…, dim], optional) – Point on the manifold, end point of the geodesic. If None, an initial tangent vector must be given.
initial_tangent_vec (array-like, shape=[…, dim],) – Tangent vector at base point, the initial speed of the geodesics. Optional, default: None. If None, an end point must be given and a logarithm is computed.

Returns:

path (callable) – Time parameterized geodesic curve. If a batch of initial conditions is passed, the output array’s first dimension represents the different initial conditions, and the second corresponds to time.

geodesic_equation(state, _time)[source]#

Compute the geodesic ODE associated with the connection.

Parameters:

state (array-like, shape=[…, dim]) – Tangent vector at the position.
_time (array-like, shape=[…, dim]) – Point on the manifold, the position at which to compute the geodesic ODE.

Returns:

geodesic_ode (array-like, shape=[…, dim]) – Value of the vector field to be integrated at position.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image.

Parameters:: base_point (array-like, shape=[…, {dim, [n, m]}]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

ladder_parallel_transport(tangent_vec, base_point, direction, n_rungs=1, scheme='pole', alpha=1, return_geodesics=False)[source]#

Approximate parallel transport using the pole ladder scheme.

Approximate Parallel transport using either the pole ladder or the Schild’s ladder scheme [LP2013b]. Pole ladder is exact in symmetric spaces and of order two in general while Schild’s ladder is a first order approximation [GP2020]. Both schemes are available on any affine connection manifolds whose exponential and logarithm maps are implemented. tangent_vec is transported along the geodesic starting at the base_point with initial tangent vector direction.

Parameters:

tangent_vec (array-like, shape=[…, dim]) – Tangent vector at base point to transport.
direction (array-like, shape=[…, dim]) – Tangent vector at base point, initial speed of the geodesic along which to transport.
base_point (array-like, shape=[…, dim]) – Point on the manifold, initial position of the geodesic along which to transport.
n_rungs (int) – Number of steps of the ladder. Optional, default: 1.
scheme (str, {‘pole’, ‘schild’}) – The scheme to use for the construction of the ladder at each step. Optional, default: ‘pole’.
alpha (float) – Exponent for the scaling of the vector to transport. Must be greater or equal to 1, 2 is optimal. See [GP2020]. Optional, default: 2

Returns:

ladder (dict of array-like and callable with following keys) –

transported_tangent_vectorarray-like, shape=[…, dim]: Approximation of the parallel transport of tangent vector a.
trajectorylist of list of callable, len=n_steps: List of lists containing the geodesics of the construction, only if return_geodesics=True in the step function. The geodesics are methods of the class connection.

References

[LP2013b]

Lorenzi, Marco, and Xavier Pennec. “Efficient Parallel Transport of Deformations in Time Series of Images: From Schild to Pole Ladder.” Journal of Mathematical Imaging and Vision 50, no. 1 (September 1, 2014): 5–17. https://doi.org/10.1007/s10851-013-0470-3.

[GP2020] (1,2)

Guigui, Nicolas, and Xavier Pennec. “Numerical Accuracy of Ladder Schemes for Parallel Transport on Manifolds.” Foundations of Computational Mathematics, June 18, 2021. https://doi.org/10.1007/s10208-021-09515-x.

log(point, base_point)[source]#

Compute logarithm map associated to the affine connection.

Solve the boundary value problem associated to the geodesic equation using the Christoffel symbols and conjugate gradient descent.

Parameters:

point (array-like, shape=[…, dim]) – Point on the manifold.
base_point (array-like, shape=[…, dim]) – Point on the manifold.
n_steps (int) – Number of discrete time steps to take in the integration. Optional, default: N_STEPS.
step (str, {‘euler’, ‘rk4’}) – Numerical scheme to use for integration. Optional, default: ‘euler’.
max_iter
verbose
tol

Returns:

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

parallel_transport(tangent_vec, base_point, direction=None, end_point=None)[source]#

Compute the parallel transport of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, {dim, [n, m]}]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, {dim, [n, m]}]) – Point on the manifold. Point to transport from.
direction (array-like, shape=[…, {dim, [n, m]}]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None.
end_point (array-like, shape=[…, {dim, [n, m]}]) – Point on the manifold. Point to transport to. Optional, default: None.

Returns:

transported_tangent_vec (array-like, shape=[…, {dim, [n, m]}]) – Transported tangent vector at exp_(base_point)(tangent_vec_b).

ricci_tensor(base_point)[source]#

Compute Ricci curvature tensor at base_point.

The Ricci curvature tensor $\mathrm{Ric}_{ij}$ is defined as: $\mathrm{Ric}_{ij} = R_{ikj}^k$ with Einstein notation.

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: ricci_tensor (array-like, shape=[…, dim, dim]) – ricci_tensor[…,i,j] = Ric_{ij} Ricci tensor curvature.

riemann_tensor(base_point)[source]#

Compute Riemannian tensor at base_point.

In the literature the riemannian curvature tensor is noted $R_{ijk}^l$.

Following tensor index convention (ref. Wikipedia), we have: $R_{ijk}^l = dx^l(R(X_j, X_k)X_i)$

which gives $R_{ijk}^lk$ as a sum of four terms: $R_{ijk}^l = :math:$partial_j Gamma^l_{ki}` $- \partial_k \Gamma^l_{ji}$ $+ \Gamma^l_{jm} \Gamma^m_{ki}$ $- \Gamma^l_{km} \Gamma^m_{ji}$

Note that geomstats puts the contravariant index on the first dimension of the Christoffel symbols.

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: riemann_curvature (array-like, shape=[…, dim, dim,) – dim, dim] riemann_tensor[…,i,j,k,l] = R_{ijk}^l Riemannian tensor curvature, with the contravariant index on the last dimension.

geomstats.geometry.diffeo module#

Diffeomorpism implementation.

class geomstats.geometry.diffeo.AutodiffDiffeo(space_shape, image_space_shape)[source]#

Bases: Diffeo

Diffeomorphism through autodiff.

inverse_jacobian_diffeomorphism(image_point)[source]#

Jacobian of the inverse diffeomorphism at image point.

Parameters:: image_point (array-like, shape=[…, *image_shape]) – Base point.
Returns:: mat (array-like, shape=[…, *shape, *image_shape]) – Jacobian of the inverse diffeomorphism.

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

Tangent diffeomorphism at base point.

Parameters:

image_tangent_vec (array-like, shape=[…, *image_shape]) – Tangent vector at base point.
image_point (array-like, shape=[…, *image_shape]) – Base point.
base_point (array-like, shape=[…, *space_shape]) – Base point.

Returns:

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

jacobian_diffeomorphism(base_point)[source]#

Jacobian of the diffeomorphism at base point.

Parameters:: base_point (array-like, shape=[…, *space_shape]) – Base point.
Returns:: mat (array-like, shape=[…, *image_shape, *space_shape]) – Jacobian of the diffeomorphism.

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

Tangent diffeomorphism at base point.

Parameters:

tangent_vec (array-like, shape=[…, *space_shape]) – Tangent vector at base point.
base_point (array-like, shape=[…, *space_shape]) – Base point.
image_point (array-like, shape=[…, *image_shape]) – Image point.

Returns:

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

class geomstats.geometry.diffeo.ComposedDiffeo(diffeos)[source]#

Bases: Diffeo

A composed diffeomorphism.

Parameters:: diffeos (list[Diffeo]) – An (ordered) list of diffeomorphisms.

diffeomorphism(base_point)[source]#: Diffeomorphism at base point.

inverse_diffeomorphism(image_point)[source]#: Inverse diffeomorphism at base point.

inverse_tangent_diffeomorphism(image_tangent_vec, image_point=None, base_point=None)[source]#: Inverse tangent diffeomorphism at image point.

tangent_diffeomorphism(tangent_vec, base_point=None, image_point=None)[source]#: Tangent diffeomorphism at base point.

class geomstats.geometry.diffeo.Diffeo[source]#

Bases: object

Diffeormorphism.

Let $f$ be the diffeomorphism $f: M \rightarrow N$ of the manifold $M$ into the manifold N.

abstract diffeomorphism(base_point)[source]#

Diffeomorphism at base point.

Parameters:: base_point (array-like, shape=[…, *space_shape]) – Base point.
Returns:: image_point (array-like, shape=[…, *image_shape]) – Image point.

abstract inverse_diffeomorphism(image_point)[source]#

Inverse diffeomorphism at base point.

$f^-1: N \rightarrow M$

Parameters:: image_point (array-like, shape=[…, *image_shape]) – Image point.
Returns:: base_point (array-like, shape=[…, *space_shape]) – Base point.

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

Inverse tangent diffeomorphism at image point.

df^-1_p is a linear map from T_f(p)N to T_pM

Parameters:

image_tangent_vec (array-like, shape=[…, *image_shape]) – Image tangent vector at image point.
image_point (array-like, shape=[…, *image_shape]) – Image point.
base_point (array-like, shape=[…, *space_shape]) – Base point.

Returns:

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

Notes

See tangent_diffeomorphism docstrings for signature considerations.

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

Tangent diffeomorphism at base point.

df_p is a linear map from T_pM to T_f(p)N.

Parameters:

tangent_vec (array-like, shape=[…, *space_shape]) – Tangent vector at base point.
base_point (array-like, shape=[…, *space_shape]) – Base point.
image_point (array-like, shape=[…, *image_shape]) – Image point.

Returns:

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

Notes

Signature choice (i.e. having the possibility to pass both base and image points) comes from performance considerations. In several methods (e.g. PullbackDiffeoMetric.inner_product) the need to call tangent_diffeomorphism comes after having called diffeomorphism, which means we have both base_point and image_point available. In some cases, tangent_diffeomorphism needs access to base_point (e.g. SRVTransform), while in others, it needs access to image_point (e.g. CholeskyMap). By passing both, we give the corresponding implementation the possibility to choose the one that is more convenient (performancewise). If we pass only one of the two, it has the mechanims to perform the necessary transformations (e.g. calling diffeomorphism or inverse_diffeomorphism on it).

class geomstats.geometry.diffeo.ReversedDiffeo(diffeo)[source]#

Bases: Diffeo

Reverses the direction of a diffeomorphism.

Parameters:: diffeo (Diffeo.)

diffeomorphism(base_point)[source]#: Diffeomorphism at base point.

inverse_diffeomorphism(image_point)[source]#: Inverse diffeomorphism at base point.

inverse_tangent_diffeomorphism(image_tangent_vec, image_point=None, base_point=None)[source]#: Tangent diffeomorphism at base point.

tangent_diffeomorphism(tangent_vec, base_point=None, image_point=None)[source]#: Tangent diffeomorphism at base point.

geomstats.geometry.discrete_curves module#

Parameterized curves on any given manifold.

Lead author: Alice Le Brigant.

class geomstats.geometry.discrete_curves.DiscreteCurvesStartingAtOrigin(ambient_dim=2, k_sampling_points=10, equip=True)[source]#

Bases: NFoldManifold

Space of discrete curves modulo translations.

Each individual curve is represented by a 2d-array of shape [ k_sampling_points - 1, ambient_dim].

This space corresponds to the space of immersions defined below, i.e. the space of smooth functions from an interval I into the ambient Euclidean space M, with non-vanishing derivative.

\[Imm(I, M)=\{c \in C^{\infty}(I, M) \|c'(t)\|\neq 0 \forall t \in I \},\]

where the interval of parameters I is taken to be I = [0, 1] without loss of generality.

Parameters:

ambient_dim (int) – Dimension of the ambient Euclidean space in which curves take values.
k_sampling_points (int) – Number of sampling points.
equip (bool) – If True, equip space with default metric.

property ambient_manifold#: Manifold in which curves take values.

static default_metric()[source]#: Metric to equip the space with if equip is True.

insert_origin(point)[source]#: Insert origin as first element of point.

property k_sampling_points#: Number of sampling points for the discrete curves.

new(equip=True)[source]#: Create manifold with same parameters.

projection(point)[source]#

Project a point from discrete curves.

Removes translation and origin.

Parameters:: point (array-like, shape=[…, k_sampling_points, ambient_dim])
Returns:: proj_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim])

random_point(n_samples=1, bound=1.0)[source]#

Sample random curves.

Sampling on the sphere to avoid chaotic curves.

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

Bases: object

Align two curves through dynamic programming.

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 .. math:: end_srv@gamma(t) = end_srv(gamma(t))cdot|gamma(t)|^frac{1}{2}

The dynamic programming algorithm assumes that for every subinterval :math: ‘left[frac{i}{n},frac{i+1}{n}right]’ of :math: ‘left[0,1right]’, gamma is linear.

Parameters:

n_space_grid (int) – Number of subintervals in which the reparametrization is linear. Optinal, default: 100.
max_slope (int) – Maximum slope allowed for a reparametrization. Optional, default: 6.

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(bundle, point, base_point, return_sdist=False)[source]#

Vectorize the dynamic programming algorithm.

Parameters:

point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Initial discrete curve.
base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – End discrete curve.
return_sdist (bool) – If True, also returns squared distance.

Returns:

aligned (array-like, shape=[…, k_sampling_points - 1, ambient_dim) – Action of the optimal g on point.
squared_dist (array, shape=[…,]) – Quotient distance between point and base point. If return_sdist is True.

class geomstats.geometry.discrete_curves.ElasticTranslationMetric(space, a, b=None)[source]#

Bases: PullbackDiffeoMetric

Elastic metric on the space of discrete curves.

Family of elastic metric parametrized by bending and stretching parameters a and b. These can be obtained as pullbacks of the L2 metric by the F-transforms.

See [NK2018] for details.

Parameters:

a (float) – Bending parameter.
b (float) – Stretching parameter.

References

[KN2018] (1,2)

S. Kurtek and T. Needham, “Simplifying transforms for general elastic metrics on the space of plane curves”, arXiv:1803.10894 [math.DG], 29 Mar 2018.

class geomstats.geometry.discrete_curves.FTransform(ambient_manifold, k_sampling_points, a=1.0, b=None)[source]#

Bases: AutodiffDiffeo

FTransform.

The f_transform is defined on the space of curves quotiented by translations, which is identified with the space of curves with their first sampling point located at 0:

\[curve(0) = (0, 0)\]

The f_transform is given by the formula:

\[Imm(I, R^2) / R^2 \mapsto C^\infty(I, R^2\backslash\{0\}) c \mapsto 2b |c'|^{1/2} (\frac{c'}{|c'|})^{a/(2b)}\]

where the identification $C = R^2$ is used and the exponentiation is a complex exponentiation, which can make the f_transform not well-defined:

\[f(c) = 2b r^{1/2}\exp(i\theta * a/(2b)) * \exp(ik\pi * a/b)\]

where (r, theta) is the polar representation of c’, and for any $k \in Z$.

Parameters:

ambient_manifold (Manifold) – Manifold in which curves take values.
k_sampling_points (int) – Number of sampling points.
a (float) – Bending parameter.
b (float) – Stretching parameter.

Notes

It is currently only implemented for the Euclidean ambient manifold with dimension 2.

f_transform is a bijection if and only if a/2b=1.

If a/2b is an integer not equal to 1: - then f_transform is well-defined but many-to-one.

If a/2b is not an integer: - then f_transform is multivalued, - and f_transform takes finitely many values if and only if a 2b is rational.

diffeomorphism(base_point)[source]#

Compute the f_transform of a curve.

The implementation uses formula (3) from [KN2018] , i.e. choses the representative corresponding to k = 0.

Parameters:: base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Discrete curve.
Returns:: image_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – F_transform of the curve.

inverse_diffeomorphism(image_point)[source]#

Compute the inverse F_transform of a transformed curve.

This only works if a / (2b) <= 1. See [KN2018] for details.

When the f_transform is many-to-one, one antecedent is chosen.

Parameters:: image_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – F tranform representation of a discrete curve.
Returns:: point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Curve starting at the origin retrieved from its square-root velocity.

class geomstats.geometry.discrete_curves.IterativeHorizontalGeodesicAligner(n_time_grid=100, threshold=0.001, max_iter=20, save_history=False)[source]#

Bases: object

Iterative horizontal geodesic algorithm.

The horizontal geodesic is computed by an interative procedure where the initial curve stays fixed and the sampling points are moved on the end curve to obtain its optimal parametrization with respect to the initial curve. This optimal matching algorithm sets current_end_curve to be the end curve and iterates three steps: 1) compute the geodesic between the initial curve and current_end_curve 2) compute the path of reparametrizations that transforms this geodesic into a horizontal path of curves 3) invert this path of reparametrizations to find the horizontal path and update current_end_curve to be its end point. The algorithm stops when the new current_end_curve is sufficiently close to the former current_end_curve.

Parameters:

n_time_grid (int) – Number of times in which compute the geodesic.
threshold (float) – When the difference between the new end curve and the current end curve becomes lower than this threshold, the algorithm stops. Optional, default: 1e-3.
max_iter (int) – Maximum number of iterations.
save_history (bool) – If True, history is saved in a self.history.

align(bundle, point, base_point)[source]#

Align point to base point.

Parameters:

point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Initial discrete curve.
base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – End discrete curve.

Returns:

aligned (array-like, shape=[…, k_sampling_points - 1, ambient_dim) – Action of the optimal g on point.

discrete_horizontal_geodesic(bundle, initial_point, end_point)[source]#

Discrete horizontal geodesic.

Parameters:

initial_point (array-like, shape=[…, k_sampling_points, ambient_dim]) – Initial discrete curve.
end_point (array-like, shape=[…, k_sampling_points, ambient_dim]) – End discrete curve.

Returns:

geod_points (array, shape=[…, n_time_grid, k - 1, ambient_dim])

class geomstats.geometry.discrete_curves.L2CurvesMetric(space)[source]#

Bases: NFoldMetric

L2 metric on the space of discrete curves.

L2 metric on the space of regularly sampled discrete curves defined on the unit interval. The inner product between two tangent vectors is given by the integral of the ambient space inner product, approximated by a left Riemann sum.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute L2 inner product between two tangent vectors.

The inner product is the integral of the ambient space inner product, approximated by a left Riemann sum.

Parameters:

tangent_vec_a (array-like, shape=[…, k_landmarks, ambient_dim]) – Tangent vector to a curve, i.e. infinitesimal vector field along a curve.
tangent_vec_b (array-like, shape=[…, k_landmarks, ambient_dim]) – Tangent vector to a curve, i.e. infinitesimal vector field along a curve.
base_point (array-like, shape=[…, k_landmarks, ambient_dim]) – Discrete curve defined on the unit interval [0, 1].

Returns:

inner_prod (array_like, shape=[…]) – L2 inner product between tangent_vec_a and tangent_vec_b.

static riemann_sum(func)[source]#

Compute the left Riemann sum approximation of the integral.

Compute the left Riemann sum approximation of the integral of a function func defined on the unit interval, given by sample points at regularly spaced times ..math:

t_i = i / (k_landmarks),
i = 0, ..., k_landmarks - 1

(last time is missing).

Parameters:: func (array-like, shape=[…, k_landmarks]) – Sample points of a function at regularly spaced times.
Returns:: riemann_sum (array-like, shape=[…, ]) – Left Riemann sum.

class geomstats.geometry.discrete_curves.SRVTransform(ambient_manifold, k_sampling_points)[source]#

Bases: Diffeo

SRV transform.

Diffeomorphism between discrete curves starting at origin with k_sampling_points and landmarks with k_sampling_points - 1.

Parameters:

ambient_manifold (Manifold) – Manifold in which curves take values.
k_sampling_points (int) – Number of sampling points.

Notes

It is currently only implemented for the Euclidean ambient manifold.

diffeomorphism(base_point)[source]#

Square Root Velocity Transform (SRVT).

Compute the square root velocity representation of a curve. The velocity is computed using the log map.

In the case of several curves, an index selection procedure allows to get rid of the log between the end point of curve[k, :, :] and the starting point of curve[k + 1, :, :].

\[Q(c) = c'/ |c'|^{1/2}\]

Parameters:: base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Discrete curve.
Returns:: image_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – SRV representation.

inverse_diffeomorphism(image_point)[source]#

Inverse of the Square Root Velocity Transform (SRVT).

Retrieve a curve from its square root velocity representation.

\[c(t) = c(0) + \int_0^t q(s) |q(s)|ds\]

with: - c the curve that can be retrieved only up to a translation, - q the srv representation of the curve, - c(0) the starting point of the curve.

See [Sea2011] Section 2.1 for details.

It performs numerical integration on a manifold.

Parameters:: image_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – SRV representation.
Returns:: curve (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Discrete curve.

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

Inverse of differential of the square root velocity transform.

\[(c, k) -> h, where dQ_c(h)=k and h' = |c'| * (k + <k,v> v)\]

Parameters:

image_tangent_vec (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Tangent vector to SRV representation.
image_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – SRV representation.
base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Discrete curve.

Returns:

tangent_vec (array-like, shape=[…, ambient_dim]) – Inverse of the differential of the square root velocity transform at curve evaluated at tangent_vec.

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

Differential of the square root velocity transform.

..math::: (h, c) -> dQ_c(h) = |c'|^(-1/2} * (h' - 1/2 * <h',v>v) v = c'/|c'|

Parameters:

tangent_vec (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Tangent vector to curve.
base_point (array-like, shape=[…, k_sampling_points - 1, ambiend_dim]) – Discrete curve.
image_point (array-like, shape=[…, k_sampling_points - 1, ambiend_dim]) – SRV representation.

Returns:

d_srv_vec (array-like, shape=[…, k_sampling_points - 1, ambient_dim,]) – Differential of the square root velocity transform at curve evaluated at tangent_vec.

class geomstats.geometry.discrete_curves.SRVTranslationMetric(space)[source]#

Bases: PullbackDiffeoMetric

Square Root Velocity metric on the space of discrete curves.

The SRV metric is equivalent to the elastic metric chosen with - bending parameter a = 1, - stretching parameter b = 1/2. It can be obtained as the pullback of the L2 metric by the Square Root Velocity Function.

See [Sea2011] for details.

References

[Sea2011] (1,2)

A. Srivastava, E. Klassen, S. H. Joshi and I. H. Jermyn, “Shape Analysis of Elastic Curves in Euclidean Spaces,” in IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 33, no. 7, pp. 1415-1428, July 2011.

class geomstats.geometry.discrete_curves.SRVTranslationReparametrizationBundle(total_space)[source]#

Bases: FiberBundle

Principal bundle of shapes of curves induced by the SRV metric.

The space of parameterized curves is the total space of a principal bundle where the group action is given by reparameterization and the base space is the shape space of curves modulo reparametrization, i.e. unparametrized curves. In the discrete case, reparametrization corresponds to resampling.

Each tangent vector to the space of parameterized curves can be split into a vertical part (tangent to the fibers of the principal bundle) and a horizontal part (orthogonal to the vertical part with respect to the SRV metric). Horizontal geodesics in the total space can be computed using an algorithm that iteratively finds the best correspondence between two fibers of the principal bundle, see Reference below.

Parameters:

ambient_manifold (Manifold) – Manifold in which curves take values.
k_sampling_points (int) – Number of sampling points for the discrete curves.

References

[LAB2017]

A. Le Brigant, “A discrete framework to find the optimal matching between manifold- valued curves,” in Journal of Mathematical Imaging and Vision, 61, pp. 40-70, 2019.

align(point, base_point)[source]#

Find optimal reparametrization of curve with respect to base curve.

The new parametrization of curve is optimal in the sense that it is the member of its fiber closest to the base curve with respect to the SRVMetric. It is found as the end point of the horizontal geodesic starting at the base curve and ending at the fiber of curve.

Parameters:

point (array-like, shape=[…, k_sampling_points, ambient_dim]) – Point to align.
base_point (array-like, shape=[…, k_sampling_points, ambient_dim]) – Reference point.

Returns:

aligned (array-like, shape=[…, k_sampling_points -1 , ambient_dim]) – Optimal reparametrization of the curve represented by point.

horizontal_projection(tangent_vec, base_point)[source]#

Compute horizontal part of tangent vector at base point.

Parameters:

tangent_vec (array-like, shape=[…, k_sampling_points, ambient_dim]) – Tangent vector to decompose into horizontal and vertical parts.
base_point (array-like, shape=[…, k_sampling_points, ambient_dim]) – Discrete curve, base point of tangent_vec in the manifold of curves.

Returns:

tangent_vec_hor (array-like, shape=[…, k_sampling_points, ambient_dim]) – Horizontal part of tangent_vec.

vertical_projection(tangent_vec, base_point, return_norm=False)[source]#

Compute vertical part of tangent vector at base point.

Parameters:

tangent_vec (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Tangent vector to decompose into horizontal and vertical parts.
base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Discrete curve, base point of tangent_vec in the manifold of curves.
return_norm (boolean,) – If True, the method returns the pointwise norm of the vertical part of tangent_vec.

Returns:

tangent_vec_ver (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Vertical part of tangent_vec.
vertical_norm (array-like, shape=[…, n_points]) – Pointwise norm of the vertical part of tangent_vec. Only returned when return_norm is True.

class geomstats.geometry.discrete_curves.SRVTranslationReparametrizationQuotientMetric(space, fiber_bundle, signature=None)[source]#

Bases: QuotientMetric

SRV quotient metric on the space of unparametrized curves.

This is the class for the quotient metric induced by the SRV Metric on the shape space of unparametrized curves, i.e. the space of parametrized curves quotiented by the group of reparametrizations. In the discrete case, reparametrization corresponds to resampling.

geomstats.geometry.discrete_curves.centered_difference(array, delta=None, axis=-1, endpoints=False)[source]#

Centered difference in a Euclidean space.

Points live in R^n, but are a 1d embedding (e.g. a curve).

Parameters:

array (array-like) – Values of a function.
delta (float) – Spacing between points.
axis (int) – Axis in which perform the difference. Must be given backwards.
endpoints (bool) – If True, endpoints are computed by backward and forward differences, respectively.

Returns:

centered_diff (array-like) – Same shape as array.

geomstats.geometry.discrete_curves.forward_difference(array, delta=None, axis=-1)[source]#

Forward difference in a Euclidean space.

Points live in R^n, but are a 1d embedding (e.g. a curve).

Parameters:

array (array-like) – Values of a function.
delta (float) – Spacing between points.
axis (int) – Axis in which perform the difference. Must be given backwards.

Returns:

forward_diff (array-like) – Shape in the specified axis reduces by one.

geomstats.geometry.discrete_curves.insert_zeros(array, axis=-1, end=False)[source]#

Insert zeros in a given array.

Insert zeros while taking care of

Parameters:

array (array-like)
axis (int) – Axis in which insert the zeros. Must be given backwards.
end (bool) – If True, zeros are introduced at the end.

Returns:

array_with_zeros (array-like) – Shape in the specified axis increases by one.

geomstats.geometry.discrete_curves.second_centered_difference(array, delta=None, axis=-1)[source]#

Second centered difference in a Euclidean space.

Points live in R^n, but are a 1d embedding (e.g. a curve).

Parameters:

array (array-like) – Values of a function.
delta (float) – Spacing between points.
axis (int) – Axis in which perform the difference. Must be given backwards.

Returns:

second_centered_diff (array-like) – Shape in the specified axis reduces by two (endpoints).

geomstats.geometry.discrete_surfaces module#

Discrete Surfaces with Elastic metrics.

Lead authors: Emmanuel Hartman, Adele Myers.

class geomstats.geometry.discrete_surfaces.DiscreteSurfaces(faces, equip=True)[source]#

Bases: Manifold

Space of parameterized discrete surfaces.

Each surface is sampled with fixed n_vertices vertices and n_faces faces in $mathbb{R}^3$.

Each individual surface is represented by a 2d-array of shape [ n_vertices, 3]. This space corresponds to the space of immersions defined below, i.e. the space of smooth functions from a template to manifold $M$ into $mathbb{R}^3$, with non-vanishing Jacobian. .. math:

Imm(M,\mathbb{R}^3)=\{ f \in C^{\infty}(M, \mathbb{R}^3)
\|Df(x)\|\neq 0 \forall x \in M \}.

Parameters:: faces (integer array-like, shape=[n_faces, 3]) – Triangulation of the surface. Each face is given by 3 indices that indicate its vertices.

belongs(point, atol=1e-12)[source]#

Evaluate whether a point belongs to the manifold.

Checks that vertices are inputed in proper form and are consistent with the mesh structure.

Parameters:

point (array-like, shape=[…, n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the space of discrete surfaces.

static default_metric()[source]#: Metric to equip the space with if equip is True.

face_areas(point)[source]#

Compute the areas for each face of a triangulated surface.

The corresponds to the volume area for the surface metric, that is the volume area of the pullback metric of the immersion defining the surface metric.

Parameters:: point (array-like, shape=[n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
Returns:: _ (array-like, shape=[n_faces,]) – Area computed at each face of the triangulated surface.

is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Tangent vectors are identified with points of the vector space so this checks the shape of the input vector.

Parameters:

vector (array-like, shape=[…, n_vertices, 3]) – Vector, i.e. a 3D vector field on the surface.
base_point (array-like, shape=[…, n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (array-like, shape=[…,]) – Boolean denoting if vector is a tangent vector at the base point.

laplacian(point)[source]#

Compute the mesh Laplacian operator of a triangulated surface.

Denoting q the surface, i.e. the point in the DiscreteSurfaces manifold, the laplacian at q is defined as the operator: :math: Delta_q = - Tr(g_q^{-1} nabla^2) where $g_q$ is the surface metric matrix of $q$.

Parameters:: point (array-like, shape=[n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
Returns:: _laplacian (callable) – Function that evaluates the mesh Laplacian operator at a tangent vector field to the surface.

normals(point)[source]#

Compute normals at each face of a triangulated surface.

Normals are the cross products between edges of each face that are incident to its x-coordinate.

Parameters:: point (array-like, shape=[n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
Returns:: normals_at_point (array-like, shape=[n_faces, 3]) – Normals of each face of the mesh.

projection(point)[source]#

Project a point to the manifold.

Parameters:: point (array-like, shape=[…, n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation..
Returns:: _ (array-like, shape=[…, n_vertices, 3]) – Point.

random_point(n_samples=1)[source]#

Sample discrete surfaces.

This sample random discrete surfaces with the correct number of vertices.

Parameters:: n_samples (int) – Number of surfaces to sample. Optional, Default=1
Returns:: vertices (array-like, shape=[n_samples, n_vertices, 3]) – Vertices for a batch of points in the space of discrete surfaces.

surface_metric_matrices(point)[source]#

Compute the surface metric matrices.

The matrices are evaluated at the faces of a triangulated surface.

The surface metric is the pullback metric of the immersion q defining the surface, i.e. of the map q: M -> R3, where M is the parameterization manifold.

Parameters:: point (array like, shape=[n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
Returns:: metric_mats (array-like, shape=[n_faces, 2, 2]) – Surface metric matrices evaluated at each face of the triangulated surface.

surface_one_forms(point)[source]#

Compute the vector valued one-forms.

The one forms are evaluated at the faces of a triangulated surface.

A one-form is represented by the two vectors (01) and (02) at each face of vertices 0, 1, 2.

Parameters:: point (array-like, shape=[…, n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
Returns:: one_forms_bp (array-like, shape=[…, n_faces, 2, 3]) – One form evaluated at each face of the triangulated surface.

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, n_vertices, 3]) – Vector, i.e. a 3D vector field on the surface.
base_point (array-like, shape=[…, n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.

Returns:

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

vertex_areas(point)[source]#

Compute vertex areas for a triangulated surface.

Vertex area is the area of all of the triangles who are in contact (incident) with a specific vertex, according to the formula: vertex_areas = 2 * sum_incident_areas / 3.0

Parameters:: point (array-like, shape=[…, n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.
Returns:: vertex_areas (array-like, shape=[…, n_vertices, 1]) – Vertex area for each vertex.

class geomstats.geometry.discrete_surfaces.ElasticMetric(space, a0=1.0, a1=1.0, b1=1.0, c1=1.0, d1=1.0, a2=1.0)[source]#

Bases: RiemannianMetric

Elastic metric defined by a family of second order Sobolev metrics.

Each individual discrete surface is represented by a 2D-array of shape [ n_vertices, 3]. See [HSKCB2022] for details.

The parameters a0, a1, b1, c1, d1, a2 (detailed below) are non-negative weighting coefficients for the different terms in the metric.

Parameters:

space (DiscreteSurfaces) – Instantiated DiscreteSurfaces manifold.
a0 (float) – First order parameter. Default: 1.
a1 (float) – Stretching parameter. Default: 1.
b1 (float) – Shearing parameter. Default: 1.
c1 (float) – Bending parameter. Default: 1.
d1 (float) – Additonal first order parameter. Default: 1.
a2 (float) – Second order parameter. Default: 1.

References

[HSKCB2022]

“Elastic shape analysis of surfaces with second-order Sobolev metrics: a comprehensive numerical framework”. arXiv:2204.04238 [cs.CV], 25 Sep 2022

exp(tangent_vec, base_point)[source]#

Compute the exponential map.

Parameters:

tangent_vec (array-like, shape=[…, n_vertices, 3]) – Tangent vector at base point.
base_point (array-like, shape=[…, n_vertices, 3]) – Base point.

Returns:

exp (array-like, shape=[…, n_vertices, 3]) – End point of the geodesic starting at base_point with initial velocity tangent_vec and stopping at time 1.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute inner product between two tangent vectors at a base point.

The inner-product has 6 terms, where each term corresponds to one of the 6 hyperparameters a0, a1, b1, c1, d1, a2.

We denote h and k the tangent vectors a and b respectively. We denote q the base point, i.e. the surface.

The six terms of the inner-product are given by: $\int_M (G_{a_0} + G_{a_1} + G_{b_1} + G_{c_1} + G_{d_1} + G_{a_2})vol_q$

where: - $G_{a_0} = a_0 <h, k>$ - $G_{a_1} = a_1.g_q^{-1} <dh_m, dk_m>$ - $G_{b_1} = b_1.g_q^{-1} <dh_+, dk_+>$ - $G_{c_1} = c_1.g_q^{-1} <dh_\perp, dk_\perp>$ - $G_{d_1} = d_1.g_q^{-1} <dh_0, dk_0>$ - $G_{a_2} = a_2 <\Delta_q h, \Delta_q k>$

with notations taken from .. [HSKCB2022].

Parameters:

tangent_vec_a (array-like, shape=[…, n_vertices, 3]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n_vertices, 3]) – Tangent vector at base point.
base_point (array-like, shape=[n_vertices, 3]) – Surface, as the 3D coordinates of the vertices of its triangulation.

Returns:

inner_prod (array-like, shape=[…]) – Inner-product.

References

[HSKCB2022]

“Elastic shape analysis of surfaces with second-order Sobolev metrics: a comprehensive numerical framework”. arXiv:2204.04238 [cs.CV], 25 Sep 2022.

log(point, base_point)[source]#

Compute the logarithm map.

Parameters:

point (array-like, shape=[…, n_vertices, 3]) – Point.
base_point (array-like, shape=[…, n_vertices, 3]) – Base po int.

Returns:

tangent_vec (array-like, shape=[…, n_vertices, 3]) – Initial velocity of the geodesic starting at base_point and reaching point at time 1.

path_energy(path)[source]#

Compute path energy of a path in the space of discrete surfaces.

Parameters:: path (array-like, shape=[…, n_times, n_vertices, 3]) – Piecewise linear path of discrete surfaces.
Returns:: energy (array-like, shape=[…,]) – Path energy.

path_energy_per_time(path)[source]#

Compute stepwise path energy of a path in the space of discrete surfaces.

Parameters:: path (array-like, shape=[…, n_times, n_vertices, 3]) – Piecewise linear path of discrete surfaces.
Returns:: energy (array-like, shape=[…, n_times - 1,]) – Stepwise path energy.

geomstats.geometry.euclidean module#

Euclidean space.

class geomstats.geometry.euclidean.Euclidean(dim, equip=True)[source]#

Bases: VectorSpace

Class for Euclidean spaces.

By definition, a Euclidean space is a vector space of a given dimension, equipped with a Euclidean metric.

Parameters:: dim (int) – Dimension of the Euclidean space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

exp(tangent_vec, base_point)[source]#

Compute the group exponential, which is simply the addition.

Parameters:

tangent_vec (array-like, shape=[…, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n]) – Point from which the exponential is computed.

Returns:

point (array-like, shape=[…, n]) – Group exponential.

property identity#

Identity of the group.

Returns:: identity (array-like, shape=[n])

class geomstats.geometry.euclidean.EuclideanMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Class for Euclidean metrics.

As a Riemannian metric, the Euclidean metric is:

flat: the inner-product is independent of the base point;
positive definite: it has signature (dimension, 0, 0), where dimension is the dimension of the Euclidean space.

exp(tangent_vec, base_point, **kwargs)[source]#

Compute exp map of a base point in tangent vector direction.

The Riemannian exponential is vector addition in the Euclidean space.

Parameters:

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

Returns:

exp (array-like, shape=[…, dim]) – Riemannian exponential.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Inner product between two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base point.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

inner_product (array-like, shape=[…,]) – Inner-product.

log(point, base_point, **kwargs)[source]#

Compute log map using a base point and other point.

The Riemannian logarithm is the subtraction in the Euclidean space.

Parameters:

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

Returns:

log (array-like, shape=[…, dim]) – Riemannian logarithm.

metric_matrix(base_point=None)[source]#

Compute the inner-product matrix, independent of the base point.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.
Returns:: inner_prod_mat (array-like, shape=[…, dim, dim]) – Inner-product matrix.

norm(vector, base_point=None)[source]#

Compute norm of a vector.

Norm of a vector associated to the inner product at the tangent space at a base point.

Note: This only works for positive-definite Riemannian metrics and inner products.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

norm (array-like, shape=[…,]) – Norm.

parallel_transport(tangent_vec, base_point=None, direction=None, end_point=None)[source]#

Compute the parallel transport of a tangent vector.

On a Euclidean space, the parallel transport of a (tangent) vector returns the vector itself.

Parameters:

tangent_vec (array-like, shape=[…, dim]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, dim]) – Point on the manifold. Point to transport from. Optional, default: None
direction (array-like, shape=[…, dim]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None.
end_point (array-like, shape=[…, dim]) – Point on the manifold. Point to transport to. Optional, default: None.

Returns:

transported_tangent_vec (array-like, shape=[…, dim]) – Transported tangent vector at exp_(base_point)(tangent_vec_b).

geomstats.geometry.fiber_bundle module#

Class for (principal) fiber bundles.

Lead author: Nicolas Guigui.

class geomstats.geometry.fiber_bundle.FiberBundle(total_space, group=None, group_action=None, group_dim=None)[source]#

Bases: ABC

Class for (principal) fiber bundles.

This class implements abstract methods for fiber bundles, or more generally manifolds, with a submersion map, or a right Lie group action.

Parameters:

group (LieGroup) – Group that acts on the total space by the right. Optional. Default : None. Either the group or the group action must be given.
group_action (callable) – Right group action. It must take as input a point of the total space and an element of the group, and return a point of the total space.

align(point, base_point, max_iter=25, verbose=False, tol=1e-12)[source]#

Align point to base_point.

Find the optimal group element g such that the base point and point.g are well positioned, meaning that the total space distance is minimized. This also means that the geodesic joining the base point and the aligned point is horizontal. By default, this is solved by a gradient descent in the Lie algebra.

Parameters:

point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point on the manifold.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point on the manifold.
max_iter (int) – Maximum number of gradient steps. Optional, default : 25.
verbose (bool) – Verbosity level. Optional, default : False.
tol (float) – Tolerance for the stopping criterion. Optional, default : backend atol

Returns:

aligned (array-like, shape=[…, {total_space.dim, [n, m]}]) – Action of the optimal g on point.

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

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

It means that horizontal lift is the inverse of the restriction of the tangent submersion to the horizontal space at point, where point must be in the fiber above the base point. By default, the base manifold is not explicit but is identified with a horizontal section of the fiber bundle, so the horizontal lift is the horizontal projection.

Parameters:

tangent_vec (array-like, shape=[…, {base_dim, [n, m]}])
fiber_point (array-like, shape=[…, {ambient_dim, [n, m]}]) – Point of the total space. Optional, default : None. The lift method is used to compute a point at which to compute a tangent vector.
base_point (array-like, shape=[…, {base_dim, [n, m]}]) – Point of the base space. Optional, default : None. In this case, point must be given, and submersion is used to compute the base_point if needed.

Returns:

horizontal_lift (array-like, shape=[…, {total_space.dim, [n, m]}]) – Horizontal tangent vector to the total space at point.

horizontal_projection(tangent_vec, base_point)[source]#

Project to horizontal subspace.

Compute the horizontal component of a tangent vector at a base point by removing the vertical component, or by computing a horizontal lift of the tangent projection.

Parameters:

tangent_vec (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector to the total space at base_point.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point on the total space.

Returns:

horizontal (array-like, shape=[…, {total_space.dim, [n, m]}]) – Horizontal component of tangent_vec.

integrability_tensor(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the fundamental tensor A of the submersion.

The fundamental integrability tensor A is defined for tangent vectors $X = tangent\_vec\_a$ and $Y = tangent\_vec\_b$ of the total space by [O’Neill]_ as $A_X Y = ver\nabla_{hor X} (hor Y) + hor \nabla_{hor X}( ver Y)$ where $hor, ver$ are the horizontal and vertical projections and $\nabla$ is the connection of the total space.

Parameters:

tangent_vec_a (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector at base_point.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point of the total space.

Returns:

vector (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector at base_point, result of the A tensor applied to tangent_vec_a and tangent_vec_b.

References

integrability_tensor_derivative(horizontal_vec_x, horizontal_vec_y, nabla_x_y, tangent_vec_e, nabla_x_e, base_point)[source]#

Compute the covariant derivative of the integrability tensor A.

The covariant derivative $\nabla_X (A_Y E)$ in total space is necessary to compute the covariant derivative of the directional curvature in a submersion. The components $\nabla_X (A_Y E)$ and $A_Y E$ are computed at base-point $P = base\_point$ for horizontal vector fields $X, Y$ extending the values given in argument $X|_P = horizontal_vec_x$, $Y|_P = horizontal\_vec\_y$ and a general vector field $E$ extending $E|_x = tangent\_vec\_e$ in a neighborhood of x with covariant derivatives $\nabla_X Y |_P = nabla_x_y$ and $\nabla_X E |_P = nabla_x_e$.

Parameters:

horizontal_vec_x (array-like, shape=[…, {total_space.dim, [n, m]}]) – Horizontal tangent vector at base_point.
horizontal_vec_y (array-like, shape=[…, {total_space.dim, [n, m]}]) – Horizontal tangent vector at base_point.
nabla_x_y (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector at base_point.
tangent_vec_e (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector at base_point.
nabla_x_e (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector at base_point.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point of the total space.

Returns:

nabla_x_a_y_e (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector at base_point, result of $\nabla_X (A_Y E)$.
a_y_e (array-like, shape=[…, {ambient_dim, [n, n]}]) – Tangent vector at base_point, result of $A_Y E$.

References

[Pennec]

Pennec, Xavier. Computing the curvature and its gradient in Kendall shape spaces. Unpublished.

is_horizontal(tangent_vec, base_point, atol=1e-12)[source]#

Evaluate if the tangent vector is horizontal at base_point.

Parameters:

tangent_vec (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point on the manifold. Optional, default: None.
atol (float) – Absolute tolerance. Optional, default: backend atol

Returns:

is_horizontal (bool) – Boolean denoting if tangent vector is horizontal.

is_vertical(tangent_vec, base_point, atol=1e-12)[source]#

Evaluate if the tangent vector is vertical at base_point.

Parameters:

tangent_vec (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point on the manifold. Optional, default: None.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_vertical (bool) – Boolean denoting if tangent vector is vertical.

static lift(point)[source]#

Lift a point to total space.

This is a section of the fiber bundle, defined on the base manifold, with values in the total space. It means that submersion applied after lift results in the identity map. By default, the base manifold is not explicit but is identified with a section of the fiber bundle, so the lift is the identity map.

Parameters:: point (array-like, shape=[…, {base_dim, [n, m]}]) – Point of the base manifold.
Returns:: lift (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point of the total space.

static riemannian_submersion(point)[source]#

Project a point to base manifold.

This is the projection of the fiber bundle, defined on the total space, with values in the base manifold. This map is surjective. By default, the base manifold is not explicit but is identified with a local section of the fiber bundle, so the submersion is the identity map.

Parameters:: point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point of the total space.
Returns:: projection (array-like, shape=[…, {base_dim, [n, m]}]) – Point of the base manifold.

tangent_riemannian_submersion(tangent_vec, base_point)[source]#

Project a tangent vector to base manifold.

This is the differential of the projection of the fiber bundle, defined on the tangent space of a point of the total space, with values in the tangent space of the projection of this point in the base manifold. This map is surjective. By default, the base manifold is not explicit but is identified with a horizontal section of the fiber bundle, so the tangent submersion is the horizontal projection.

Parameters:

tangent_vec (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector to the total space at base_point.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point of the total space.

Returns:

projection (array-like, shape=[…, {base_dim, [n, m]}]) – Tangent vector to the base manifold.

vertical_projection(tangent_vec, base_point)[source]#

Project to vertical subspace.

Compute the vertical component of a tangent vector $w$ at a base point $P$ by removing the horizontal component.

Parameters:

tangent_vec (array-like, shape=[…, {total_space.dim, [n, m]}]) – Tangent vector to the total space at base_point.
base_point (array-like, shape=[…, {total_space.dim, [n, m]}]) – Point on the total space.

Returns:

vertical (array-like, shape=[…, {total_space.dim, [n, m]}]) – Vertical component of tangent_vec.

geomstats.geometry.full_rank_correlation_matrices module#

The manifold of full-rank correlation matrices.

Lead authors: Yann Thanwerdas and Olivier Bisson.

References

[T2022]

Yann Thanwerdas. Riemannian and stratified

geometries on covariance and correlation matrices. Differential Geometry [math.DG]. Université Côte d’Azur, 2022.

class geomstats.geometry.full_rank_correlation_matrices.CorrelationMatricesBundle(total_space)[source]#

Bases: FiberBundle

Fiber bundle to construct the quotient metric on correlation matrices.

Correlation matrices are obtained as the quotient of the space of SPD matrices by the action by congruence of diagonal matrices.

References

[TP21]

Thanwerdas, Yann, and Xavier Pennec. “Geodesics and Curvature of the Quotient-Affine Metrics on Full-Rank CorrelationMatrices.” In Proceedings of Geometric Science of Information. Paris, France, 2021. https://hal.archives-ouvertes.fr/hal-03157992.

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

Compute the horizontal lift wrt the affine-invariant metric.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector of the manifold of full-rank correlation matrices.
fiber_point (array-like, shape=[…, n, n]) – SPD matrix in the fiber above point.
base_point (array-like, shape=[…, n, n]) – Full-rank correlation matrix.

Returns:

hor_lift (array-like, shape=[…, n, n]) – Horizontal lift of tangent_vec from point to base_point.

static riemannian_submersion(point)[source]#

Compute the correlation matrix associated to an SPD matrix.

Parameters:: point (array-like, shape=[…, n, n]) – SPD matrix.
Returns:: cor (array_like, shape=[…, n, n]) – Full rank correlation matrix.

tangent_riemannian_submersion(tangent_vec, base_point)[source]#

Compute the differential of the submersion.

Parameters:

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

Returns:

result (array-like, shape=[…, n, n])

vertical_projection(tangent_vec, base_point)[source]#

Compute the vertical projection wrt the affine-invariant metric.

Parameters:

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

Returns:

ver (array-like, shape=[…, n, n]) – Vertical projection.

class geomstats.geometry.full_rank_correlation_matrices.FullRankCorrelationAffineQuotientMetric(space, total_space=None)[source]#

Bases: QuotientMetric

Class for the quotient of the affine-invariant metric.

The affine-invariant metric on SPD matrices is invariant under the action of diagonal matrices, thus it induces a quotient metric on the manifold of full-rank correlation matrices.

class geomstats.geometry.full_rank_correlation_matrices.FullRankCorrelationMatrices(n, equip=True)[source]#

Bases: LevelSet

Class for the manifold of full-rank correlation matrices.

Parameters:: n (int) – Integer representing the shape of the matrices: n x n.

static default_metric()[source]#: Metric to equip the space with if equip is True.

static diag_action(diagonal_vec, point)[source]#

Apply a diagonal matrix on an SPD matrices by congruence.

The action of $D$ on $\Sigma$ is given by :math:`D Sigma D. The diagonal matrix must be passed as a vector representing its diagonal.

Parameters:

diagonal_vec (array-like, shape=[…, n]) – Vector coefficient of the diagonal matrix.
point (array-like, shape=[…, n, n]) – Symmetric Positive definite matrix.

Returns:

mat (array-like, shape=[…, n, n]) – Symmetric matrix obtained by the action of diagonal_vec on point.

classmethod from_covariance(point)[source]#

Compute the correlation matrix associated to an SPD matrix.

The correlation matrix associated to an SPD matrix (the covariance) $\Sigma$ is given by $D \Sigma D$ where $D$ is the inverse square-root of the diagonal of $\Sigma$.

Parameters:: point (array-like, shape=[…, n, n]) – Symmetric Positive definite matrix.
Returns:: corr (array-like, shape=[…, n, n]) – Correlation matrix obtained by dividing all elements by the diagonal entries.

projection(point)[source]#

Project a matrix to the space of correlation matrices.

Parameters:: point (array-like, shape=[…, n, n]) – Matrix to project.

random_point(n_samples=1, bound=1.0)[source]#

Sample full-rank correlation matrices by projecting random SPD mats.

Parameters:

n_samples (int) – Number of samples.
bound (float) – Bound of the interval in which to sample. Optional, default: 1.

Returns:

cor (array-like, shape=[n_samples, n, n]) – Sample of full-rank correlation matrices.

submersion(point)[source]#

Submersion that defines the manifold.

Parameters:: point (array-like, shape=[…, n, n])
Returns:: submersed_point (array-like, shape=[…, n])

tangent_submersion(vector, point)[source]#

Tangent submersion.

Parameters:

vector (array-like, shape=[…, n, n])
point (Ignored.)

Returns:

submersed_vector (array-like, shape=[…, n])

to_tangent(vector, base_point)[source]#

Project a matrix to the tangent space at a base point.

The tangent space to the space of correlation matrices is the space of symmetric matrices with null diagonal.

Parameters:

vector (array-like, shape=[…, n, n]) – Matrix to project
base_point (array-like, shape=[…, n, n]) – Correlation matrix.

Returns:

tangent_vec (array-like, shape=[…, n, n]) – Symmetric matrix with 0 diagonal.

class geomstats.geometry.full_rank_correlation_matrices.PolyHyperbolicCholeskyMetric(space)[source]#

Bases: PullbackDiffeoMetric

Pullback metric via a diffeomorphism.

Diffeormorphism between full-rank correlation matrices and the space of lower triangular matrices with positive diagonal and unit normed rows.

Since this image space is also diffeomorphic to another space, the product space of successively increasing factor-dimension open hemispheres, we take advantage of ComposedDiffeo to avoid explicitly representing the intermediate space.

For more details, check section 7.4.1 [T2022].

geomstats.geometry.full_rank_matrices module#

Full rank Euclidean matrices $R_*^{m\times n}$.

Lead author: Anna Calissano.

class geomstats.geometry.full_rank_matrices.FullRankMatrices(n, k, equip=True)[source]#

Bases: VectorSpaceOpenSet

Class for $R_*^{n\times k}$ matrices of dimension n x k and full rank.

Parameters:

n (int) – Integer representing the shape of the matrices: n x k
k (int) – Integer representing the shape of the matrices: n x k

belongs(point, atol=1e-12)[source]#

Check if the matrix belongs to $R_*^{n \times k}$.

Parameters:

point (array-like, shape=[…, n, k]) – Matrix to be checked.
atol (float) – Unused.

Returns:

belongs (Boolean) – Denoting if point is in $R_*^{m\times n}$.

static default_metric()[source]#: Metric to equip the space with if equip is True.

projection(point)[source]#

Project a matrix to the set of full rank matrices.

As the space of full rank matrices is dense in the space of matrices, this is not a projection per se, but a regularization if the matrix input X is not already full rank: $X + \epsilon [I_{rank}, 0]$ is returned where $\epsilon=gs.atol$

Parameters:: point (array-like, shape=[…, n, k]) – Point in embedding manifold.
Returns:: projected (array-like, shape=[…, n, k]) – Projected point.

random_point(n_samples=1, bound=1.0, n_iter=100)[source]#

Sample in $R_*^{n\times k}$ from a normal distribution.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – This parameter is ignored.
n_iter (int) – Maximum number of trials to sample a matrix with full rank. Optional, default: 100.

Returns:

samples (array-like, shape=[…, n, k]) – Point sampled on $R_*^{n\times k}$.

geomstats.geometry.functions module#

Module for function spaces as geometric objects.

class geomstats.geometry.functions.HilbertSphere(domain, equip=True)[source]#

Bases: Manifold

Class for space of one dimensional functions with norm 1.

The tangent space is given by functions that have zero inner-product with the base point

Parameters:

domain (array-like, shape=[n_samples,]) – Grid points on the domain.
Ref
—–
.. [Sea2016] Srivastava, Anuj, and Eric P. Klassen.
Functional and shape data analysis.
Vol. 1. New York (Springer, 2016.)

belongs(point, atol=1e-12)[source]#

Evaluate if the point belongs to the vector space.

This method checks the shape of the input point.

Parameters:

point (array-like, shape=[…, n_samples]) – Point to test.
atol (float)

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, n_samples]) – Vector.
base_point (array-like, shape=[…, n_samples]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

projection(point)[source]#

Project a point to the infinite dimensional hypersphere.

Parameters:: point (array-like, shape=[…, n_samples]) – Discrete evaluation of a function.
Returns:: projected_point (array-like, shape=[…, n_samples]) – Point projected to the hypersphere.

random_point(n_samples=1, bound=1.0)[source]#

Sample random points on the manifold.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – This parameter is ignored

Returns:

samples (array-like, shape=[…, dim])

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, n_samples]) – Vector.
base_point (array-like, shape=[…, n_samples]) – Point on the manifold.

Returns:

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

class geomstats.geometry.functions.HilbertSphereMetric(space, signature=None)[source]#

Bases: RiemannianMetric

A Riemannian metric on the Hilbert sphere (functions of norm 1).

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, n_samples]) – Tangent vector at a base point.
base_point (array-like, shape=[…, n_samples]) – Point on the hypersphere.

Returns:

exp (array-like, shape=[…, n_samples]) – Point on the hypersphere equal to the Riemannian exponential of tangent_vec at the base point.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute the inner-product of two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, n_samples]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n_samples]) – Second tangent vector at base point.
base_point (array-like, shape=[…, n_samples], optional) – Point on the hypersphere.

Returns:

inner_prod (array-like, shape=[…,]) – Inner-product of the two tangent vectors.

log(point, base_point)[source]#

Compute the Riemannian logarithm of a point.

Parameters:

point (array-like, shape=[…, n_samples]) – Point on the hypersphere.
base_point (array-like, shape=[…, n_samples]) – Point on the hypersphere.

Returns:

log (array-like, shape=[…, n_samples]) – Tangent vector at the base point equal to the Riemannian logarithm of point at the base point.

geomstats.geometry.general_linear module#

Module exposing the GeneralLinear group class.

class geomstats.geometry.general_linear.GeneralLinear(n, positive_det=False, equip=True)[source]#

Bases: MatrixLieGroup, VectorSpaceOpenSet

Class for the general linear group GL(n) and its identity component.

If positive_det=True, this is the connected component of the identity, i.e. the space of matrices with positive determinant.

Parameters:

n (int) – Integer representing the shape of the matrices: n x n.
positive_det (bool) – Whether to restrict to the identity connected component of the general linear group, i.e. matrices with positive determinant. Optional, default: False.

belongs(point, atol=1e-12)[source]#

Check if a matrix is invertible and of the right shape.

Parameters:

point (array-like, shape=[…, n, n]) – Matrix to be checked.
atol (float) – Tolerance threshold for the determinant.

Returns:

belongs (array-like, shape=[…,]) – Boolean denoting if point is in GL(n).

static default_metric()[source]#: Metric to equip the space with if equip is True.

classmethod orbit(point, base_point=None)[source]#

Compute the one-parameter orbit of base_point passing through point.

Parameters:

point (array-like, shape=[…, n, n]) – Target point.
base_point (array-like, shape=[…, n, n], optional) – Base point. Optional, defaults to identity if None.

Returns:

path (callable) – One-parameter orbit. Satisfies path(0) = base_point and path(1) = point.

Notes

Denoting point by $g$ and base_point by $h$, the orbit $\gamma$ satisfies:

\[\begin{split}\gamma(t) = {\mathrm e}^{t X} \cdot h \\ \quad \text{with} \quad\\ {\mathrm e}^{X} = g h^{-1}\end{split}\]

The path is not uniquely defined and depends on the choice of $V$ returned by log().

Vectorization#

Return a collection of trajectories (4-D array) from a collection of input matrices (3-D array).

projection(point)[source]#

Project a matrix to the general linear group.

As GL(n) is dense in the space of matrices, this is not a projection per se, but a regularization if the matrix is not already invertible: $X + \epsilon I_n$ is returned where $\epsilon=gs.atol$ is returned for an input X.

Parameters:: point (array-like, shape=[…, dim_embedding]) – Point in embedding manifold.
Returns:: projected (array-like, shape=[…, dim_embedding]) – Projected point.

random_point(n_samples=1, bound=1.0, n_iter=100)[source]#

Sample in GL(n) from the normal distribution.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – This parameter is ignored
n_iter (int) – Maximum number of trials to sample a matrix with positive det. Optional, default: 100.

Returns:

samples (array-like, shape=[…, n, n]) – Point sampled on GL(n).

class geomstats.geometry.general_linear.SquareMatrices(n, equip=True)[source]#

Bases: MatrixLieAlgebra

Lie algebra of the general linear group.

This is the space of matrices.

Parameters:: n (int) – Integer representing the shape of the matrices: n x n.

basis_representation(matrix_representation)[source]#

Compute the coefficient in the usual matrix basis.

This simply flattens the input.

Parameters:: matrix_representation (array-like, shape=[…, n, n]) – Matrix.
Returns:: basis_representation (array-like, shape=[…, dim]) – Representation in the basis.

static default_metric()[source]#: Metric to equip the space with if equip is True.

matrix_representation(basis_representation)[source]#

Compute the matrix representation for the given basis coefficients.

This simply reshapes the input into a square matrix.

Parameters:: basis_representation (array-like, shape=[…, dim]) – Coefficients in the basis.
Returns:: matrix_representation (array-like, shape=[…, n, n]) – Matrix.

geomstats.geometry.grassmannian module#

Manifold of linear subspaces.

The Grassmannian $Gr(n, k)$ is the manifold of k-dimensional subspaces in n-dimensional Euclidean space.

Lead author: Olivier Peltre.

$Gr(n, p)$ is represented by $n \times n$ matrices of rank $p$ satisfying $P^2 = P$ and $P^T = P$. Each $P \in Gr(n, p)$ is identified with the unique orthogonal projector onto ${\rm Im}(P)$.

$Gr(n, p)$ is a homogoneous space, quotient of the special orthogonal group by the subgroup of rotations stabilising a $p$-dimensional subspace:

\[Gr(n, p) \simeq \frac {SO(n)} {SO(p) \times SO(n-p)}\]

It is therefore customary to represent the Grassmannian by equivalence classes of orthogonal $p$-frames in ${\mathbb R}^n$. For such a representation, work in the Stiefel manifold instead.

\[Gr(n, p) \simeq St(n, p) / SO(p)\]

References

[Batzies15]

Batzies, E., K. Hüper, L. Machado, and F. Silva Leite. “Geometric Mean and Geodesic Regression on Grassmannians.” Linear Algebra and Its Applications 466 (February 1, 2015): 83–101. https://doi.org/10.1016/j.laa.2014.10.003.

class geomstats.geometry.grassmannian.Grassmannian(n, p, equip=True)[source]#

Bases: LevelSet

Class for Grassmann manifolds $Gr(n, p)$.

Parameters:

n (int) – Dimension of the Euclidean space.
p (int) – Dimension of the subspaces.

static default_metric()[source]#: Metric to equip the space with if equip is True.

projection(point)[source]#

Project a matrix to the Grassmann manifold.

An eigenvalue decomposition of (the symmetric part of) point is used.

Parameters:: point (array-like, shape=[…, n, n]) – Point in embedding manifold.
Returns:: projected (array-like, shape=[…, n, n]) – Projected point.

random_point(n_samples=1, bound=1.0)[source]#

Sample random points from a uniform distribution.

Following [Chikuse03], $n\_samples * n * p$ scalars are sampled from a standard normal distribution and reshaped to matrices, the projectors on their first $p$ columns follow a uniform distribution.

Parameters:: n_samples (int) – The number of points to sample Optional. default: 1.
Returns:: projectors (array-like, shape=[…, n, n]) – Points following a uniform distribution.

References

[Chikuse03]

Yasuko Chikuse, Statistics on special manifolds, New York: Springer-Verlag. 2003, 10.1007/978-0-387-21540-2

random_uniform(n_samples=1)[source]#

Sample random points from a uniform distribution.

Parameters:: n_samples (int) – The number of points to sample Optional. default: 1.
Returns:: projectors (array-like, shape=[…, n, n]) – Points following a uniform distribution.

References

[Chikuse03]

Yasuko Chikuse, Statistics on special manifolds, New York: Springer-Verlag. 2003, 10.1007/978-0-387-21540-2

submersion(point)[source]#

Submersion that defines the Grassmann manifold.

The Grassmann manifold is defined here as embedded in the set of symmetric matrices, as the pre-image of the function defined around the projector on the space spanned by the first $p$ columns of the identity matrix by (see Exercise E.25 in [Pau07]).

\[\begin{split}\begin{pmatrix} I_p + A & B^T \\ B & D \end{pmatrix} \mapsto (D - B(I_p + A)^{-1}B^T, A + A^2 + B^TB)\end{split}\]

This map is a submersion and its zero space is the set of orthogonal rank-$p$ projectors.

Parameters:: point (array-like, shape=[…, n, n])
Returns:: submersed_point (array-like, shape=[…, n, n])

References

[Pau07]

Paulin, Frédéric. “Géométrie diﬀérentielle élémentaire,” 2007. https://www.imo.universite-paris-saclay.fr/~paulin/notescours/ cours_geodiff.pdf.

tangent_submersion(vector, point)[source]#

Tangent submersion.

Parameters:

vector (array-like, shape=[…, n, n])
point (array-like, shape=[…, n, n])

Returns:

submersed_vector (array-like, shape=[…, n, n])

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Compute the bracket (commutator) of the base_point with the skew-symmetric part of vector.

Parameters:

vector (array-like, shape=[…, n, n]) – Vector.
base_point (array-like, shape=[…, n, n]) – Point on the manifold.

Returns:

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

class geomstats.geometry.grassmannian.GrassmannianCanonicalMetric(space)[source]#

Bases: MatricesMetric

Canonical metric of the Grassmann manifold.

Coincides with the Frobenius metric.

exp(tangent_vec, base_point, **kwargs)[source]#

Exponentiate the invariant vector field v from base point p.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point. tangent_vec is the bracket of a skew-symmetric matrix with the base_point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

exp (array-like, shape=[…, n, n]) – Riemannian exponential.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In this case it is Pi / 2 everywhere.

Parameters:: base_point (array-like, shape=[…, n, n]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

References

[BZA20]

Bendokat, Thomas, Ralf Zimmermann, and P.-A. Absil. “A Grassmann Manifold Handbook: Basic Geometry and Computational Aspects.” ArXiv:2011.13699 [Cs, Math], November 27, 2020. https://arxiv.org/abs/2011.13699.

log(point, base_point, **kwargs)[source]#

Compute the Riemannian logarithm of point w.r.t. base_point.

Given $P, P'$ in $Gr(n, p)$ the logarithm from $P$ to $P$ is induced by the infinitesimal rotation [Batzies2015]:

\[Y = \frac 1 2 \log \big((2 P' - 1)(2 P - 1)\big)\]

The tangent vector $X$ at $P$ is then recovered by $X = [Y, P]$.

Parameters:

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

Returns:

tangent_vec (array-like, shape=[…, n, n]) – Riemannian logarithm, a tangent vector at base_point.

References

[Batzies2015]

Batzies, Hüper, Machado, Leite. “Geometric Mean and Geodesic Regression on Grassmannians” Linear Algebra and its Applications, 466, 83-101, 2015.

parallel_transport(tangent_vec, base_point, direction=None, end_point=None)[source]#

Compute the parallel transport of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, n, n]) – Point on the Grassmann manifold. Point to transport from.
direction (array-like, shape=[…, n, n]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None
end_point (array-like, shape=[…, n, n]) – Point on the Grassmann manifold to transport to. Unused if direction is given. Optional, default: None

Returns:

transported_tangent_vec (array-like, shape=[…, n, n]) – Transported tangent vector at exp_(base_point)(direction).

References

[BZA20]

squared_dist(point_a, point_b, **kwargs)[source]#

Squared geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, dim]) – Point.
point_b (array-like, shape=[…, dim]) – Point.

Returns:

sq_dist (array-like, shape=[…,]) – Squared distance.

geomstats.geometry.heisenberg module#

The 3D Heisenberg group.

Lead author: Morten Pedersen.

class geomstats.geometry.heisenberg.HeisenbergVectors(equip=True)[source]#

Bases: LieGroup, VectorSpace

Class for the 3D Heisenberg group in the vector representation.

The 3D Heisenberg group represented as R^3. It is a step-2 Carnot Lie group. It can be equipped with a natural sub-Riemannian structure, and it is a fundamental example in sub-Riemannian geometry.

Parameters:

No parameters
Reference
———
https (//en.wikipedia.org/wiki/Heisenberg_group)

compose(point_a, point_b)[source]#

Compute the group product of elements point_a and point_b.

Parameters:

point_a (array-like, shape=[…, 3]) – Left factor in the product.
point_b (array-like, shape=[…, 3]) – Right factor in the product.

Returns:

point_ab (array-like, shape=[…, 3]) – Product of point_a and point_b along the first dimension.

exp_from_identity(tangent_vec)[source]#

Compute the group exponential of the tangent vector at the identity.

Parameters:: tangent_vec (array-like, shape=[…, 3]) – Tangent vector at base point.
Returns:: _ (array-like, shape=[…, 3]) – Point.

property identity#

Identity of the 3D Heisenberg group.

Returns:: _ (array-like, shape=[3,])

inverse(point)[source]#

Compute the group inverse of point.

Parameters:: point (array-like, shape=[…, 3]) – Point.
Returns:: _ (array-like, shape=[…, 3]) – Inverse.

jacobian_translation(point, left=True)[source]#

Compute the Jacobian matrix of left/right translation by a point.

This calculates the differential of the left translation L_(point) evaluated at ‘point’. Note that it only depends on the point we are left-translating by, not on the point where the differential is evaluated.

Parameters:

point (array-like, shape=[…, 3]) – Point.
left (bool) – Indicate whether to calculate the differential of left or right translations. Optional, default: True.

Returns:

_ (array-like, shape=[…, 3, 3]) – Jacobian of the left/right translation by point.

lie_bracket(tangent_vec_a, tangent_vec_b, base_point=None)[source]#: Compute the lie bracket of two tangent vectors.

log_from_identity(point)[source]#

Compute the group logarithm of the point at the identity.

Parameters:: point (array-like, shape=[…, 3]) – Point.
Returns:: _ (array-like, shape=[…, 3]) – Group logarithm.

static upper_triangular_matrix_from_vector(point)[source]#

Compute the upper triangular matrix representation of the vector.

The 3D Heisenberg group can also be represented as 3x3 upper triangular matrices. This function computes this representation of the vector ‘point’.

Parameters:: point (array-like, shape=[…, 3]) – Point in the vector-represention.
Returns:: upper_triangular_mat (array-like, shape=[…, 3, 3]) – Upper triangular matrix.

static vector_from_upper_triangular_matrix(matrix)[source]#

Compute the vector representation of the upper triangular matrix.

Parameters:: matrix (array-like, shape=[…, 3, 3]) – Upper triangular matrix.
Returns:: vector (array-like, shape=[…, 3])

geomstats.geometry.hermitian module#

Complex Hermitian space.

Lead author: Yann Cabanes.

class geomstats.geometry.hermitian.Hermitian(dim, equip=True)[source]#

Bases: ComplexVectorSpace

Class for Hermitian spaces.

By definition, a Hermitian space is a complex vector space of a given dimension, equipped with a Hermitian metric.

Parameters:: dim (int) – Dimension of the Hermitian space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

exp(tangent_vec, base_point=None)[source]#

Compute the group exponential, which is simply the addition.

Parameters:

tangent_vec (array-like, shape=[…, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n]) – Point from which the exponential is computed.

Returns:

point (array-like, shape=[…, n]) – Group exponential.

property identity#

Identity of the group.

Returns:: identity (array-like, shape=[n])

class geomstats.geometry.hermitian.HermitianMetric(space, signature=None)[source]#

Bases: ComplexRiemannianMetric

Class for Hermitian metrics.

As a Riemannian metric, the Hermitian metric is:

flat: the inner-product is independent of the base point.
positive definite: it has signature (dimension, 0, 0), where dimension is the dimension of the Hermitian space.

static exp(tangent_vec, base_point, **kwargs)[source]#

Compute exp map of a base point in tangent vector direction.

The Riemannian exponential is vector addition in the Hermitian space.

Parameters:

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

Returns:

exp (array-like, shape=[…, dim]) – Riemannian exponential.

static inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Inner product between two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base point.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

inner_product (array-like, shape=[…,]) – Inner-product.

static log(point, base_point, **kwargs)[source]#

Compute log map using a base point and other point.

The Riemannian logarithm is the subtraction in the Hermitian space.

Parameters:

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

Returns:

log (array-like, shape=[…, dim]) – Riemannian logarithm.

metric_matrix(base_point=None)[source]#

Compute the inner-product matrix, independent of the base point.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.
Returns:: inner_prod_mat (array-like, shape=[…, dim, dim]) – Inner-product matrix.

static norm(vector, base_point=None)[source]#

Compute norm of a vector.

Norm of a vector associated to the inner product at the tangent space at a base point.

Note: This only works for positive-definite Riemannian metrics and inner products.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

norm (array-like, shape=[…,]) – Norm.

geomstats.geometry.hermitian_matrices module#

The vector space of Hermitian matrices.

Lead author: Yann Cabanes.

class geomstats.geometry.hermitian_matrices.HermitianMatrices(n, equip=True)[source]#

Bases: ComplexVectorSpace

Class for the vector space of Hermitian matrices of size n.

Parameters:: n (int) – Integer representing the shapes of the matrices: n x n.

belongs(point, atol=1e-12)[source]#

Evaluate if a matrix is Hermitian.

Parameters:

point (array-like, shape=[.., n, n]) – Point to test.
atol (float) – Tolerance to evaluate equality with the transpose.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

from_vector(vec)[source]#

Convert a vector into a Hermitian matrix.

Parameters:: vec (array-like, shape=[…, dim]) – Vector.
Returns:: mat (array-like, shape=[…, n, n]) – Hermitian matrix.

static projection(point)[source]#

Make a matrix Hermitian, by averaging with its transconjugate.

Parameters:: point (array-like, shape=[…, n, n]) – Matrix.
Returns:: herm (array-like, shape=[…, n, n]) – Symmetric matrix.

random_point(n_samples=1, bound=1.0)[source]#

Sample a Hermitian matrix.

Points are generated by sampling complex matrices from a uniform distribution in a box and averaging with the transconjugate.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Side of hypercube support of the uniform distribution. Optional, default: 1.0

Returns:

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

static to_vector(point)[source]#

Convert a Hermitian matrix into a vector.

Parameters:: point (array-like, shape=[…, n, n]) – Matrix.
Returns:: vec (array-like, shape=[…, n(n+1)/2]) – Vector.

geomstats.geometry.hermitian_matrices.apply_func_to_eigvalsh(mat, function, check_positive=False)[source]#

Apply function to eigenvalues and reconstruct the matrix.

Parameters:

mat (array_like, shape=[…, n, n]) – Hermitian matrix.
function (callable, list of callables) – Function to apply to eigenvalues. If a list of functions is passed, a list of results will be returned.
check_positive (bool) – Whether to check positivity of the eigenvalues. Optional. Default: False.

Returns:

mat (array_like, shape=[…, n, n]) – Hermitian matrix.

geomstats.geometry.hermitian_matrices.expmh(mat)[source]#

Compute the matrix exponential for a Hermitian matrix.

Parameters:: mat (array_like, shape=[…, n, n]) – Symmetric matrix.
Returns:: exponential (array_like, shape=[…, n, n]) – Exponential of mat.

geomstats.geometry.hermitian_matrices.powermh(mat, power)[source]#

Compute the matrix power for a Hermitian matrix.

Parameters:

mat (array_like, shape=[…, n, n]) – Symmetric matrix with non-negative eigenvalues.
power (float, list) – Power at which mat will be raised. If a list of powers is passed, a list of results will be returned.

Returns:

powerm (array_like or list of arrays, shape=[…, n, n]) – Matrix power of mat.

geomstats.geometry.hpd_matrices module#

The manifold of Hermitian positive definite (HPD) matrices.

Lead author: Yann Cabanes.

References

[Cabanes2022]

[JV2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

class geomstats.geometry.hpd_matrices.HPDAffineMetric(space, signature=None)[source]#

Bases: ComplexRiemannianMetric

Class for the affine-invariant metric on the HPD manifold.

exp(tangent_vec, base_point)[source]#

Compute the affine-invariant exponential map.

Compute the Riemannian exponential at point base_point of tangent vector tangent_vec wrt the metric defined in inner_product. This gives a Hermitian positive definite matrix.

Parameters:

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

Returns:

exp (array-like, shape=[…, n, n]) – Riemannian exponential.

injectivity_radius(base_point)[source]#

Radius of the largest ball where the exponential is injective.

Because of the negative curvature of this space, the injectivity radius is infinite everywhere.

Parameters:: base_point (array-like, shape=[…, n, n]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the affine-invariant inner-product.

Compute the inner-product of tangent_vec_a and tangent_vec_b at point base_point using the affine invariant Riemannian metric.

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

inner_product (array-like, shape=[…, n, n]) – Inner-product.

log(point, base_point)[source]#

Compute the affine-invariant logarithm map.

Compute the Riemannian logarithm at point base_point, of point wrt the metric defined in inner_product. This gives a tangent vector at point base_point.

Parameters:

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

Returns:

log (array-like, shape=[…, n, n]) – Riemannian logarithm of point at base_point.

parallel_transport(tangent_vec, base_point, direction=None, end_point=None)[source]#

Parallel transport of a tangent vector.

Closed-form solution for the parallel transport of a tangent vector along the geodesic between two points base_point and end_point or alternatively defined by $t \mapsto exp_{(base\_point)}( t*direction)$. Denoting tangent_vec_a by S, base_point by A, and end_point by B or B = Exp_A(tangent_vec_b) and $E = (BA^{- 1})^{( 1 / 2)}$. Then the parallel transport to B is:

\[S' = ESE^T\]

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, n, n]) – Point on the manifold of HPD matrices. Point to transport from
direction (array-like, shape=[…, n, n]) – Tangent vector at base point, initial speed of the geodesic along which the parallel transport is computed. Unused if end_point is given. Optional, default: None.
end_point (array-like, shape=[…, n, n]) – Point on the manifold of HPD matrices. Point to transport to. Optional, default: None.

Returns:

transported_tangent_vec (array-like, shape=[…, n, n]) – Transported tangent vector at exp_(base_point)(tangent_vec_b).

class geomstats.geometry.hpd_matrices.HPDBuresWassersteinMetric(space, signature=None)[source]#

Bases: ComplexRiemannianMetric

Class for the Bures-Wasserstein metric on the HPD manifold.

exp(tangent_vec, base_point)[source]#

Compute the Bures-Wasserstein exponential map.

Parameters:

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

Returns:

exp (array-like, shape=[…,]) – Riemannian exponential.

injectivity_radius(base_point)[source]#

Compute the upper bound of the injectivity domain.

This is the smallest eigen value of the base point.

Parameters:: base_point (array-like, shape=[…, n, n]) – Point on the manifold.
Returns:: radius (float) – Injectivity radius.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the Bures-Wasserstein inner-product.

Compute the inner-product of tangent_vec_a $A$ and tangent_vec_b $B$ at point base_point $S=PDP^\top$ using the Bures-Wasserstein Riemannian metric:

\[\frac{1}{2}\sum_{i,j}\frac{[P^\top AP]_{ij}[P^\top BP]_{ij}}{d_i+d_j}\]

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

inner_product (array-like, shape=[…,]) – Inner-product.

log(point, base_point)[source]#

Compute the Bures-Wasserstein logarithm map.

Compute the Riemannian logarithm at point base_point, of point wrt the Bures-Wasserstein metric. This gives a tangent vector at point base_point.

Parameters:

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

Returns:

log (array-like, shape=[…, n, n]) – Riemannian logarithm.

parallel_transport(tangent_vec, base_point, direction=None, end_point=None, n_steps=10, step='rk4')[source]#

Compute the parallel transport of a tangent vec along a geodesic.

Approximation of the solution of the parallel transport of a tangent vector a along the geodesic defined by $t \mapsto exp_{( base\_point)}(t* tangent\_vec\_b)$. The parallel transport equation is formulated in this case in [TP2021].

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base_point to transport.
base_point (array-like, shape=[…, n, n]) – Initial point of the geodesic.
direction (array-like, shape=[…, n, n]) – Tangent vector at base_point, initial velocity of the geodesic to transport along.
end_point (array-like, shape=[…, n, n]) – Point to transport to. Optional, default: None.
n_steps (int) – Number of steps to use to approximate the solution of the ordinary differential equation. Optional, default: 100
step (str, {‘euler’, ‘rk2’, ‘rk4’}) – Scheme to use in the integration scheme. Optional, default: ‘rk4’.

Returns:

transported (array-like, shape=[…, n, n]) – Transported tangent vector at exp_(base_point)(tangent_vec_b).

geomstats.geometry.hyperbolic module#

Common interface to hyperbolic spaces.

Lead author: Thomas Gerald.

class geomstats.geometry.hyperbolic.Hyperbolic(dim, default_coords_type='extrinsic', equip=True)[source]#

Bases: object

Class for the n-dimensional Hyperbolic space.

This class is a common interface to the different models of hyperbolic geometry:

the hyperboloid, embedded in Minkowski space of dimension dim + 1 as the set of points whose squared norm is equal to -1. This representation is called extrinsic here.
the Poincare ball, the open ball of the Euclidean space of dimension dim.
the Poincare half-space, the open space of points of the Euclidean space of dimension dim, whose last coordinate is positive.

Parameters:

dim (int) – Dimension of the hyperbolic space.
default_coords_type (str, {‘extrinsic’, ‘ball’, ‘half-space’}) – Default coordinates to represent points in hyperbolic space. Optional, default: ‘extrinsic’.

geomstats.geometry.hyperboloid module#

The n-dimensional hyperbolic space.

The n-dimensional hyperbolic space embedded with the hyperboloid representation (embedded in minkowsky space).

Lead author: Nina Miolane.

class geomstats.geometry.hyperboloid.Hyperboloid(dim, equip=True)[source]#

Bases: _Hyperbolic, LevelSet

Class for the n-dimensional hyperboloid space.

Class for the n-dimensional hyperboloid space as embedded in (n+1)-dimensional Minkowski space as the set of points with squared norm equal to -1. For other representations of hyperbolic spaces see the Hyperbolic class.

Parameters:: dim (int) – Dimension of the hyperbolic space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

extrinsic_to_intrinsic_coords(point_extrinsic)[source]#

Convert from extrinsic to intrinsic coordinates.

Parameters:: point_extrinsic (array-like, shape=[…, dim + 1]) – Point in the embedded manifold in extrinsic coordinates, i. e. in the coordinates of the embedding manifold.
Returns:: point_intrinsic (array-like, shape=[…, dim]) – Point in intrinsic coordinates.

intrinsic_to_extrinsic_coords(point_intrinsic)[source]#

Convert from intrinsic to extrinsic coordinates.

Parameters:: point_intrinsic (array-like, shape=[…, dim]) – Point in the embedded manifold in intrinsic coordinates.
Returns:: point_extrinsic (array-like, shape=[…, dim + 1]) – Point in the embedded manifold in extrinsic coordinates.

projection(point)[source]#

Project a point in space on the hyperboloid.

Parameters:: point (array-like, shape=[…, dim + 1]) – Point in embedding Euclidean space.
Returns:: projected_point (array-like, shape=[…, dim + 1]) – Point projected on the hyperboloid.

regularize(point)[source]#

Regularize a point to the canonical representation.

Regularize a point to the canonical representation chosen for the hyperbolic space, to avoid numerical issues.

Parameters:: point (array-like, shape=[…, dim + 1]) – Point.
Returns:: projected_point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space in canonical representation in extrinsic coordinates.

submersion(point)[source]#

Submersion that defines the manifold.

Parameters:: point (array-like, shape=[…, dim + 1])
Returns:: submersed_point (array-like, shape=[…])

tangent_submersion(vector, point)[source]#

Tangent submersion.

Parameters:

vector (array-like, shape=[…, dim + 1])
point (array-like, shape=[…, dim + 1])

Returns:

submersed_vector (array-like, shape=[…])

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the hyperbolic space.

Project a vector in Minkowski space on the tangent space of the hyperbolic space at a base point.

Parameters:

vector (array-like, shape=[…, dim + 1]) – Vector in Minkowski space to be projected.
base_point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space.

Returns:

tangent_vec (array-like, shape=[…, dim + 1]) – Tangent vector at the base point, equal to the projection of the vector in Minkowski space.

class geomstats.geometry.hyperboloid.HyperboloidMetric(space, signature=None)[source]#

Bases: HyperbolicMetric

Class that defines operations using a hyperbolic metric.

dist(point_a, point_b)[source]#

Compute the geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, dim + 1]) – First point in hyperbolic space.
point_b (array-like, shape=[…, dim + 1]) – Second point in hyperbolic space.

Returns:

dist (array-like, shape=[…,]) – Geodesic distance between the two points.

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, dim + 1]) – Tangent vector at a base point.
base_point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space.

Returns:

exp (array-like, shape=[…, dim + 1]) – Point in hyperbolic space equal to the Riemannian exponential of tangent_vec at the base point.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In the case of the hyperbolic space, it does not depend on the base point and is infinite everywhere, because of the negative curvature.

Parameters:: base_point (array-like, shape=[…, dim+1]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute the inner-product of two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, dim + 1]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, dim + 1]) – Second tangent vector at base point.
base_point (array-like, shape=[…, dim + 1], optional) – Point in hyperbolic space.

Returns:

inner_prod (array-like, shape=[…,]) – Inner-product of the two tangent vectors.

log(point, base_point)[source]#

Compute Riemannian logarithm of a point wrt a base point.

If default_coords_type is ‘poincare’ then base_point belongs to the Poincare ball and point is a vector in the Euclidean space of the same dimension as the ball.

Parameters:

point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space.
base_point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space.

Returns:

log (array-like, shape=[…, dim + 1]) – Tangent vector at the base point equal to the Riemannian logarithm of point at the base point.

metric_matrix(base_point=None)[source]#

Compute the inner product matrix.

Parameters:: base_point (array-like, shape=[…, dim + 1]) – Base point. Optional, default: None.
Returns:: inner_prod_mat (array-like, shape=[…, dim+1, dim + 1]) – Inner-product matrix.

parallel_transport(tangent_vec, base_point, direction=None, end_point=None)[source]#

Compute the parallel transport of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, dim + 1]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, dim + 1]) – Point on the hyperboloid.
direction (array-like, shape=[…, dim + 1]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default : None.
end_point (array-like, shape=[…, dim + 1]) – Point on the hyperboloid. Point to transport to. Unused if tangent_vec_b is given. Optional, default : None.

Returns:

transported_tangent_vec (array-like, shape=[…, dim + 1]) – Transported tangent vector at exp_(base_point)(tangent_vec_b).

squared_dist(point_a, point_b)[source]#

Squared geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, dim]) – Point.
point_b (array-like, shape=[…, dim]) – Point.

Returns:

sq_dist (array-like, shape=[…,]) – Squared distance.

squared_norm(vector, base_point=None)[source]#

Compute the squared norm of a vector.

Squared norm of a vector associated with the inner-product at the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, dim + 1]) – Vector on the tangent space of the hyperbolic space at base point.
base_point (array-like, shape=[…, dim + 1], optional) – Point in hyperbolic space in extrinsic coordinates.

Returns:

sq_norm (array-like, shape=[…,]) – Squared norm of the vector.

geomstats.geometry.hypersphere module#

The n-dimensional hypersphere.

The n-dimensional hypersphere embedded in (n+1)-dimensional Euclidean space.

Lead author: Nina Miolane.

class geomstats.geometry.hypersphere.Hypersphere(dim, default_coords_type='extrinsic', equip=True)[source]#

Bases: _Hypersphere

Class for the n-dimensional hypersphere.

Class for the n-dimensional hypersphere embedded in the (n+1)-dimensional Euclidean space.

By default, points are parameterized by their extrinsic (n+1)-coordinates. For dimensions 1 and 2, this can be changed with the default_coords_type parameter. For dimensions 1 (the circle), the intrinsic coordinates correspond angles in radians, with 0. mapping to point [1., 0.]. For dimension 2, the intrinsic coordinates are the spherical coordinates from the north pole, i.e. where angles [0., 0.] correspond to point [0., 0., 1.].

Parameters:

dim (int) – Dimension of the hypersphere.
default_coords_type (str, {‘extrinsic’, ‘intrinsic’}) – Type of representation for dimensions 1 and 2.

class geomstats.geometry.hypersphere.HypersphereMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Class for the Hypersphere Metric.

christoffels(base_point)[source]#

Compute the Christoffel symbols at a point.

Only implemented in dimension 2 and for spherical coordinates.

Parameters:: base_point (array-like, shape=[…, dim]) – Point on hypersphere where the Christoffel symbols are computed.
Returns:: christoffel (array-like, shape=[…, contravariant index, 1st) – covariant index, 2nd covariant index] Christoffel symbols at point.

curvature(tangent_vec_a, tangent_vec_b, tangent_vec_c, base_point)[source]#

Compute the curvature.

For three tangent vectors at a base point $x,y,z$, the curvature is defined by $R(x, y)z = \nabla_{[x,y]}z - \nabla_z\nabla_y z + \nabla_y\nabla_x z$, where $\nabla$ is the Levi-Civita connection. In the case of the hypersphere, we have the closed formula $R(x,y)z = \langle y,z \rangle x - \langle x, z \rangle y$.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base_point.
tangent_vec_c (array-like, shape=[…, dim]) – Tangent vector at base_point.
base_point (array-like, shape=[…, dim]) – Point on the hypersphere.

Returns:

curvature (array-like, shape=[…, dim]) – Tangent vector at base_point.

curvature_derivative(tangent_vec_a, tangent_vec_b=None, tangent_vec_c=None, tangent_vec_d=None, base_point=None)[source]#

Compute the covariant derivative of the curvature.

The derivative of the curvature vanishes since the hypersphere is a constant curvature space.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base_point along which the curvature is derived.
tangent_vec_b (array-like, shape=[…, dim]) – Unused tangent vector at base_point (since curvature derivative vanishes).
tangent_vec_c (array-like, shape=[…, dim]) – Unused tangent vector at base_point (since curvature derivative vanishes).
tangent_vec_d (array-like, shape=[…, dim]) – Unused tangent vector at base_point (since curvature derivative vanishes).
base_point (array-like, shape=[…, dim]) – Unused point on the hypersphere.

Returns:

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

dist(point_a, point_b)[source]#

Compute the geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, dim + 1]) – First point on the hypersphere.
point_b (array-like, shape=[…, dim + 1]) – Second point on the hypersphere.

Returns:

dist (array-like, shape=[…, 1]) – Geodesic distance between the two points.

exp(tangent_vec, base_point, **kwargs)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, dim + 1]) – Tangent vector at a base point.
base_point (array-like, shape=[…, dim + 1]) – Point on the hypersphere.

Returns:

exp (array-like, shape=[…, dim + 1]) – Point on the hypersphere equal to the Riemannian exponential of tangent_vec at the base point.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In the case of the sphere, it does not depend on the base point and is Pi everywhere.

Parameters:: base_point (array-like, shape=[…, dim+1]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute the inner-product of two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, dim + 1]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, dim + 1]) – Second tangent vector at base point.
base_point (array-like, shape=[…, dim + 1], optional) – Point on the hypersphere.

Returns:

inner_prod (array-like, shape=[…,]) – Inner-product of the two tangent vectors.

log(point, base_point, **kwargs)[source]#

Compute the Riemannian logarithm of a point.

Parameters:

point (array-like, shape=[…, dim + 1]) – Point on the hypersphere.
base_point (array-like, shape=[…, dim + 1]) – Point on the hypersphere.

Returns:

log (array-like, shape=[…, dim + 1]) – Tangent vector at the base point equal to the Riemannian logarithm of point at the base point.

metric_matrix(base_point=None)[source]#

Metric matrix at the tangent space at a base point.

Parameters:: base_point (array-like, shape=[…, dim + 1]) – Base point. Optional, default: None.
Returns:: mat (array-like, shape=[…, dim + 1, dim + 1]) – Inner-product matrix.

norm_factor_gradient(variances)[source]#

Compute the gradient of the normalization factor.

Parameters:: variances (array-like, shape=[n,]) – Variance of the distribution.
Returns:: norm_func (array-like, shape=[n,]) – Normalisation factor for all given variances.

normalization_factor(variances)[source]#

Return normalization factor of the Gaussian distribution.

Parameters:: variances (array-like, shape=[n,]) – Variance of the distribution.
Returns:: norm_func (array-like, shape=[n,]) – Normalisation factor for all given variances.

parallel_transport(tangent_vec, base_point, direction=None, end_point=None)[source]#

Compute the parallel transport of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, dim + 1]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, dim + 1]) – Point on the hypersphere.
direction (array-like, shape=[…, dim + 1]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default : None.
end_point (array-like, shape=[…, dim + 1]) – Point on the hypersphere. Point to transport to. Unused if tangent_vec_b is given. Optional, default : None.

Returns:

transported_tangent_vec (array-like, shape=[…, dim + 1]) – Transported tangent vector at end_point=exp_(base_point)(tangent_vec_b).

squared_dist(point_a, point_b, **kwargs)[source]#

Squared geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, dim]) – Point on the hypersphere.
point_b (array-like, shape=[…, dim]) – Point on the hypersphere.

Returns:

sq_dist (array-like, shape=[…,])

squared_norm(vector, base_point=None)[source]#

Compute the squared norm of a vector.

Squared norm of a vector associated with the inner-product at the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, dim + 1]) – Vector on the tangent space of the hypersphere at base point.
base_point (array-like, shape=[…, dim + 1], optional) – Point on the hypersphere.

Returns:

sq_norm (array-like, shape=[…, 1]) – Squared norm of the vector.

geomstats.geometry.invariant_metric module#

Left- and right- invariant metrics that exist on Lie groups.

Lead authors: Nicolas Guigui and Nina Miolane.

class geomstats.geometry.invariant_metric.BiInvariantMetric(space)[source]#

Bases: RiemannianMetric

Class for bi-invariant metrics on compact Lie groups.

Compact Lie groups and direct products of compact Lie groups with vector spaces admit bi-invariant metrics [Gallier]. Products Lie groups are not implemented. Other groups such as SE(3) admit bi-invariant pseudo-metrics.

Parameters:: space (LieGroup) – The group to equip with the bi-invariant metric

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

exp(tangent_vec, base_point=None, **kwargs)[source]#

Compute Riemannian exponential of tangent vector from the identity.

For a bi-invariant metric, this corresponds to the group exponential.

Parameters:

tangent_vec – Tangent vector at identity.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group. Optional, default : identity.

Returns:

exp (array-like, shape=[…, {dim, [n, n]}]) – Point in the group.

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In the case of a bi-invariant metric, it does not depend on the base point.

Parameters:: base_point (array-like, shape=[…, n, n]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute inner product of two vectors in tangent space at base point.

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – First tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, n, n]) – Second tangent vector at base_point.
base_point (array-like, shape=[…, n, n]) – Point in the group. Optional, defaults to identity if None.

Returns:

inner_prod (array-like, shape=[…,]) – Inner-product of the two tangent vectors.

inner_product_at_identity(tangent_vec_a, tangent_vec_b)[source]#

Compute inner product at tangent space at identity.

Parameters:

tangent_vec_a (array-like, shape=[…, {dim, [n, n]}]) – First tangent vector at identity.
tangent_vec_b (array-like, shape=[…, {dim, [n, n]}]) – Second tangent vector at identity.

Returns:

inner_prod (array-like, shape=[…]) – Inner-product of the two tangent vectors.

log(point, base_point=None, **kwargs)[source]#

Compute Riemannian logarithm of a point wrt the identity.

For a bi-invariant metric this corresponds to the group logarithm.

Parameters:

point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group. Optional, default : identity.

Returns:

log (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector at the identity equal to the Riemannian logarithm of point at the identity.

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

parallel_transport(tangent_vec, base_point, direction=None, end_point=None)[source]#

Compute the parallel transport of a tangent vec along a geodesic.

Closed-form solution for the parallel transport of a tangent vector a along the geodesic between the base point and an end point, or alternatively defined by $t \mapsto exp_{(base\_point)}(t*direction)$. As a compact Lie group endowed with its canonical bi-invariant metric is a symmetric space, parallel transport is achieved by a geodesic symmetry, or equivalently, one step of the pole ladder scheme.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, n, n]) – Point on the manifold.
direction (array-like, shape=[…, n, n]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None.
end_point (array-like, shape=[…, n, n]) – Point on the manifold. Point to transport to. Optional, default: None.

Returns:

transported_tangent_vec (array-like, shape=[…, n, n]) – Transported tangent vector at end_point=exp_(base_point)(tangent_vec_b).

class geomstats.geometry.invariant_metric.InvariantMetric(space, metric_mat_at_identity=None, left=True)[source]#

Bases: object

Class for invariant metrics on Lie groups.

This class supports both left and right invariant metrics which exist on Lie groups.

If point_type == ‘vector’, points are parameterized by the Riemannian logarithm for the canonical left-invariant metric.

Parameters:

space (LieGroup) – Group to equip with the invariant metric
metric_mat_at_identity (array-like, shape=[dim, dim]) – Matrix that defines the metric at identity. Optional, defaults to identity matrix if None.
left (bool) – Whether to use a left or right invariant metric. Optional, default: True.

geomstats.geometry.landmarks module#

Manifold for sets of landmarks that belong to any given manifold.

Lead author: Nicolas Guigui.

class geomstats.geometry.landmarks.L2LandmarksMetric(space, scales=None, signature=None)[source]#

Bases: NFoldMetric

L2 Riemannian metric on the space of landmarks.

This is the NFoldMetric of the n-fold manifold made out of k_landmarks copies of the ambient manifold of each landmark.

class geomstats.geometry.landmarks.Landmarks(ambient_manifold, k_landmarks, equip=True)[source]#

Bases: NFoldManifold

Class for space of landmarks.

The landmark space is a product manifold where all manifolds in the product are the same. The default metric is the product metric and is often referred to as the L2 metric.

Parameters:

ambient_manifold (Manifold) – Manifold to which landmarks belong.
k_landmarks (int) – Number of landmarks.

static default_metric()[source]#: Metric to equip the space with if equip is True.

property k_landmarks#: Number of landmarks.

geomstats.geometry.lie_algebra module#

Module providing an implementation of MatrixLieAlgebras.

There are two main forms of representation for elements of a MatrixLieAlgebra implemented here. The first one is as a matrix, as elements of R^(n x n). The second is by choosing a base and remembering the coefficients of an element in that base. This base will be provided in child classes (e.g. SkewSymmetricMatrices).

Lead author: Stefan Heyder.

class geomstats.geometry.lie_algebra.MatrixLieAlgebra(representation_dim, **kwargs)[source]#

Bases: VectorSpace, ABC

Class implementing matrix Lie algebra related functions.

Parameters:: representation_dim (int) – Amount of rows and columns in the matrix representation of the Lie algebra.

baker_campbell_hausdorff(matrix_a, matrix_b, order=2)[source]#

Calculate the Baker-Campbell-Hausdorff approximation of given order.

The implementation is based on [CM2009a] with the pre-computed constants taken from [CM2009b]. Our coefficients are truncated to enable us to calculate BCH up to order 15.

This represents Z = log(exp(X)exp(Y)) as an infinite linear combination of the form Z = sum z_i e_i where z_i are rational numbers and e_i are iterated Lie brackets starting with e_1 = X, e_2 = Y, each e_i is given by some i’,i’’: e_i = [e_i’, e_i’’].

Parameters:

matrix_a (array-like, shape=[…, *point_shape])
matrix_b (array-like, shape=[…, *point_shape]) – Matrices.
order (int) – The order to which the approximation is calculated. Note that this is NOT the same as using only e_i with i < order. Optional, default 2.

References

[CM2009a]

F. Casas and A. Murua. An efficient algorithm for computing the Baker–Campbell–Hausdorff series and some of its applications. Journal of Mathematical Physics 50, 2009

[CM2009b]

http://www.ehu.eus/ccwmuura/research/bchHall20.dat

abstract basis_representation(matrix_representation)[source]#

Compute the coefficients of matrices in the given basis.

Parameters:: matrix_representation (array-like, shape=[…, *point_shape]) – Matrix.
Returns:: basis_representation (array-like, shape=[…, dim]) – Coefficients in the basis.

classmethod bracket(mat_a, mat_b)#

Compute the commutator of a and b, i.e. [a, b] = ab - ba.

Parameters:

mat_a (array-like, shape=[…, n, n]) – Matrix.
mat_b (array-like, shape=[…, n, n]) – Matrix.

Returns:

mat_c (array-like, shape=[…, n, n]) – Commutator.

matrix_representation(basis_representation)[source]#

Compute the matrix representation for the given basis coefficients.

Sums the basis elements according to the coefficients given in basis_representation.

Parameters:: basis_representation (array-like, shape=[…, dim]) – Coefficients in the basis.
Returns:: matrix_representation (array-like, shape=[…, *point_shape]) – Matrix.

geomstats.geometry.lie_group module#

Lie groups.

Lead author: Nina Miolane.

class geomstats.geometry.lie_group.LieGroup(lie_algebra=None, **kwargs)[source]#

Bases: Manifold, ABC

Class for Lie groups.

In this class, point_type (‘vector’ or ‘matrix’) will be used to describe the format of the points on the Lie group. If point_type is ‘vector’, the format of the inputs is […, dimension], where dimension is the dimension of the Lie group. If point_type is ‘matrix’ the format of the inputs is […, n, n] where n is the parameter of GL(n) e.g. the amount of rows and columns of the matrix.

Parameters:

dim (int) – Dimension of the Lie group.
lie_algebra (MatrixLieAlgebra) – Lie algebra for matrix groups. Optional, default: None.

lie_algebra#

Tangent space at the identity.

Type:: MatrixLieAlgebra or None

compose(point_a, point_b)[source]#

Perform function composition corresponding to the Lie group.

Multiply the elements point_a and point_b.

Parameters:

point_a (array-like, shape=[…, {dim, [n, n]}]) – Left factor in the product.
point_b (array-like, shape=[…, {dim, [n, n]}]) – Right factor in the product.

Returns:

composed (array-like, shape=[…, {dim, [n, n]}]) – Product of point_a and point_b along the first dimension.

default_metric()[source]#: Metric to equip the space with if equip is True.

exp(tangent_vec, base_point=None)[source]#

Compute the group exponential at base_point of tangent_vec.

Parameters:

tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector at base point.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Base point. Optional, default: self.identity

Returns:

result (array-like, shape=[…, {dim, [n, n]}]) – Group exponential.

exp_from_identity(tangent_vec)[source]#

Compute the group exponential of tangent vector from the identity.

Parameters:: tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector at base point.
Returns:: point (array-like, shape=[…, {dim, [n, n]}]) – Group exponential.

exp_not_from_identity(tangent_vec, base_point)[source]#

Calculate the group exponential at base_point.

Parameters:

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

Returns:

exp (array-like, shape=[…, {dim, [n, n]}]) – Group exponential.

property identity#

Identity of the group.

Returns:: identity (array-like, shape={[dim], [n, n]}) – Identity of the Lie group.

classmethod inverse(point)[source]#

Compute the inverse law of the Lie group.

Parameters:: point (array-like, shape=[…, {dim, [n, n]}]) – Point to be inverted.
Returns:: inverse (array-like, shape=[…, {dim, [n, n]}]) – Inverted point.

is_tangent(vector, base_point=None, atol=1e-06)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, dim_embedding]) – Vector.
base_point (array-like, shape=[…, dim_embedding]) – Point in the Lie group. Optional. default: identity.
atol (float) – Precision at which to evaluate if the rotation part is skew-symmetric. Optional. default: 1e-6

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

jacobian_translation(point, left=True)[source]#

Compute the Jacobian of left/right translation by a point.

Compute the Jacobian matrix of the left translation by the point.

Parameters:

point (array-like, shape=[…, {dim, [n, n]]) – Point.
left (bool) – Indicate whether to calculate the differential of left or right translations. Optional, default: True.

Returns:

jacobian (array-like, shape=[…, dim, dim]) – Jacobian of the left/right translation by point.

lie_bracket(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute the lie bracket of two tangent vectors.

For matrix Lie groups with tangent vectors A,B at the same base point P this is given by (translate to identity, compute commutator, go back) $[A,B] = A_P^{-1}B - B_P^{-1}A$

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

bracket (array-like, shape=[…, n, n]) – Lie bracket.

log(point, base_point=None)[source]#

Compute the group logarithm of point relative to base_point.

Parameters:

point (array-like, shape=[…, {dim, [n, n]}]) – Point.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Base point. Optional, defaults to identity if None.

Returns:

tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Group logarithm.

log_from_identity(point)[source]#

Compute the group logarithm of point from the identity.

Parameters:: point (array-like, shape=[…, {dim, [n, n]}]) – Point.
Returns:: tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Group logarithm.

log_not_from_identity(point, base_point)[source]#

Compute the group logarithm of point from base_point.

Parameters:

point (array-like, shape=[…, {dim, [n, n]}]) – Point.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Base point.

Returns:

tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Group logarithm.

tangent_translation_map(point, left=True, inverse=False)[source]#

Compute the push-forward map by the left/right translation.

Compute the push-forward map, of the left/right translation by the point. It corresponds to the tangent map, or differential of the group multiplication by the point or its inverse. For groups with a vector representation, it is only implemented at identity, but it can be used at other points by passing inverse=True. This method wraps the jacobian translation which actually computes the matrix representation of the map.

Parameters:

point (array-like, shape=[…, {dim, [n, n]]) – Point.
left (bool) – Whether to calculate the differential of left or right translations. Optional, default: True.
inverse (bool,) – Whether to inverse the jacobian matrix. If True, the push forward by the translation by the inverse of point is returned. Optional, default: False.

Returns:

tangent_map (callable) – Tangent map of the left/right translation by point. It can be applied to tangent vectors.

to_tangent(vector, base_point=None)[source]#

Project a vector onto the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, {dim, [n, n]}]) – Vector to project. Its shape must match the shape of base_point.
base_point (array-like, shape=[…, {dim, [n, n]}], optional) – Point of the group. Optional, default: identity.

Returns:

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

class geomstats.geometry.lie_group.MatrixLieGroup(representation_dim, lie_algebra=None, **kwargs)[source]#

Bases: Manifold, ABC

Class for matrix Lie groups.

static compose(point_a, point_b)[source]#

Perform function composition corresponding to the Lie group.

Multiply the elements point_a and point_b.

Parameters:

point_a (array-like, shape=[…, {dim, [n, n]}]) – Left factor in the product.
point_b (array-like, shape=[…, {dim, [n, n]}]) – Right factor in the product.

Returns:

composed (array-like, shape=[…, {dim, [n, n]}]) – Product of point_a and point_b along the first dimension.

classmethod exp(tangent_vec, base_point=None)[source]#

Exponentiate a left-invariant vector field from a base point.

The vector input is not an element of the Lie algebra, but of the tangent space at base_point: if $g$ denotes base_point, $v$ the tangent vector, and $V = g^{-1} v$ the associated Lie algebra vector, then

\[\exp(v, g) = mul(g, \exp(V))\]

Therefore, the Lie exponential is obtained when base_point is None, or the identity.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point. Optional, defaults to identity if None.

Returns:

point (array-like, shape=[…, n, n]) – Left multiplication of exp(algebra_mat) with base_point.

property identity#: Matrix identity.

classmethod inverse(point)[source]#

Compute the inverse law of the Lie group.

Parameters:: point (array-like, shape=[…, {dim, [n, n]}]) – Point to be inverted.
Returns:: inverse (array-like, shape=[…, {dim, [n, n]}]) – Inverted point.

is_tangent(vector, base_point=None, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, dim_embedding]) – Vector.
base_point (array-like, shape=[…, dim_embedding]) – Point in the Lie group. Optional. default: identity.
atol (float) – Precision at which to evaluate if the rotation part is skew-symmetric. Optional. default: 1e-6

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

lie_bracket(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute the lie bracket of two tangent vectors.

For matrix Lie groups with tangent vectors A,B at the same base point P this is given by (translate to identity, compute commutator, go back) $[A,B] = A_P^{-1}B - B_P^{-1}A$

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

bracket (array-like, shape=[…, n, n]) – Lie bracket.

classmethod log(point, base_point=None)[source]#

Compute a left-invariant vector field bringing base_point to point.

The output is a vector of the tangent space at base_point, so not a Lie algebra element if it is not the identity.

Parameters:

point (array-like, shape=[…, n, n]) – Point.
base_point (array-like, shape=[…, n, n]) – Base point. Optional, defaults to identity if None.

Returns:

tangent_vec (array-like, shape=[…, n, n]) – Matrix such that exp(tangent_vec, base_point) = point.

Notes

Denoting point by $g$ and base_point by $h$, the output satisfies:

\[g = \exp(\log(g, h), h)\]

tangent_translation_map(point, left=True, inverse=False)[source]#

Compute the push-forward map by the left/right translation.

Parameters:

point (array-like, shape=[…, {dim, [n, n]]) – Point.
left (bool) – Whether to calculate the differential of left or right translations. Optional, default: True
inverse (bool,) – Whether to inverse the jacobian matrix. If True, the push forward by the translation by the inverse of point is returned. Optional, default: False.

Returns:

tangent_map (callable) – Tangent map of the left/right translation by point. It can be applied to tangent vectors.

to_tangent(vector, base_point=None)[source]#

Project a vector onto the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, {dim, [n, n]}]) – Vector to project. Its shape must match the shape of base_point.
base_point (array-like, shape=[…, {dim, [n, n]}], optional) – Point of the group. Optional, default: identity.

Returns:

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

geomstats.geometry.lower_triangular_matrices module#

The vector space of lower triangular matrices.

Lead author: Saiteja Utpala.

class geomstats.geometry.lower_triangular_matrices.LowerTriangularMatrices(n, equip=True)[source]#

Bases: VectorSpace

Class for the vector space of lower triangular matrices of size n.

Parameters:: n (int) – Integer representing the shapes of the matrices: n x n.

belongs(point, atol=1e-12)[source]#

Evaluate if a matrix is lower triangular.

Parameters:

point (array-like, shape=[.., n, n]) – Point to test.
atol (float) – Tolerance to evaluate equality with the transpose.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

from_vector(vec)[source]#

Convert a vector into a lower triangular matrix.

Parameters:: vec (array-like, shape=[…, n(n+1)/2]) – Vector.
Returns:: mat (array-like, shape=[…, n, n]) – Lower triangular matrix.

matrix_representation(vec)[source]#

Compute the matrix representation for the given basis coefficients.

Parameters:: matrix_representation (array-like, shape=[…, n, n]) – Matrix.
Returns:: basis_representation (array-like, shape=[…, dim]) – Representation in the basis.

projection(point)[source]#

Make a square matrix lower triangular by zeroing out other elements.

Parameters:: point (array-like, shape=[…, n, n]) – Matrix.
Returns:: sym (array-like, shape=[…, n, n]) – Symmetric matrix.

random_point(n_samples=1, bound=1.0)[source]#

Sample a lower triangular matrix with a uniform distribution in a box.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Side of hypercube support of the uniform distribution. Optional, default: 1.0.

Returns:

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

static to_vector(point)[source]#

Convert a lower triangular matrix into a vector.

Parameters:: point (array-like, shape=[…, n, n]) – Matrix.
Returns:: vec (array-like, shape=[…, n(n+1)/2]) – Vector.

geomstats.geometry.manifold module#

Manifold module.

In other words, a topological space that locally resembles Euclidean space near each point.

Lead author: Nina Miolane.

class geomstats.geometry.manifold.Manifold(dim, shape, default_coords_type='intrinsic', equip=True)[source]#

Bases: ABC

Class for manifolds.

Parameters:

dim (int) – Dimension of the manifold.
shape (tuple of int) – Shape of one element of the manifold. Optional, default : None.
default_coords_type (str, {‘intrinsic’, ‘extrinsic’, etc}) – Coordinate type. Optional, default: ‘intrinsic’.
equip (bool) – If True, equip space with default metric.

point_ndim#

Dimension of point array.

Type:: int

default_point_type#

Point type: “vector” or “matrix”.

Type:: str

abstract belongs(point, atol=1e-12)[source]#

Evaluate if a point belongs to the manifold.

Parameters:

point (array-like, shape=[…, *point_shape]) – Point to evaluate.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if point belongs to the manifold.

equip_with_group_action(group_action)[source]#

Equip manifold with group action.

Parameters:: group_action (str) – Group action.

equip_with_metric(Metric=None, **metric_kwargs)[source]#

Equip manifold with a Riemannian metric.

Parameters:: Metric (RiemannianMetric object) – If None, default metric will be used.

equip_with_quotient_structure()[source]#

Equip manifold with quotient structure.

Creates attributes quotient and fiber_bundle.

abstract is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

abstract random_point(n_samples=1, bound=1.0)[source]#

Sample random points on the manifold according to some distribution.

If the manifold is compact, preferably a uniform distribution will be used.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample for non compact manifolds. Optional, default: 1.

Returns:

samples (array-like, shape=[…, *point_shape]) – Points sampled on the manifold.

random_tangent_vec(base_point, n_samples=1)[source]#

Generate random tangent vec.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
base_point (array-like, shape={[n_samples, *point_shape], [*point_shape,]}) – Point.

Returns:

tangent_vec (array-like, shape=[…, *point_shape]) – Tangent vec at base point.

regularize(point)[source]#

Regularize a point to the canonical representation for the manifold.

Parameters:: point (array-like, shape=[…, dim]) – Point.
Returns:: regularized_point (array-like, shape=[…, *point_shape]) – Regularized point.

abstract to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, *point_shape]) – Vector.
base_point (array-like, shape=[…, *point_shape]) – Point on the manifold.

Returns:

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

geomstats.geometry.matrices module#

Module exposing the Matrices and MatricesMetric class.

class geomstats.geometry.matrices.Matrices(m, n, equip=True)[source]#

Bases: VectorSpace

Class for the space of matrices (m, n).

Parameters:: m, n (int) – Integers representing the shapes of the matrices: m x n.

classmethod align_matrices(point, base_point)[source]#

Align matrices.

Find the optimal rotation R in SO(m) such that the base point and R.point are well positioned.

Parameters:

point (array-like, shape=[…, m, n]) – Point on the manifold.
base_point (array-like, shape=[…, m, n]) – Point on the manifold.

Returns:

aligned (array-like, shape=[…, m, n]) – R.point.

classmethod bracket(mat_a, mat_b)[source]#

Compute the commutator of a and b, i.e. [a, b] = ab - ba.

Parameters:

mat_a (array-like, shape=[…, n, n]) – Matrix.
mat_b (array-like, shape=[…, n, n]) – Matrix.

Returns:

mat_c (array-like, shape=[…, n, n]) – Commutator.

classmethod congruent(mat_1, mat_2)[source]#

Compute the congruent action of mat_2 on mat_1.

This is $mat\_2 \ mat\_1 \ mat\_2^T$.

Parameters:

mat_1 (array-like, shape=[…, n, n]) – Matrix.
mat_2 (array-like, shape=[…, n, n]) – Matrix.

Returns:

cong (array-like, shape=[…, n, n]) – Result of the congruent action.

static default_metric()[source]#: Metric to equip the space with if equip is True.

static diagonal(mat)[source]#

Return the diagonal of a matrix as a vector.

Parameters:: mat (array-like, shape=[…, m, n]) – Matrix.
Returns:: diagonal (array-like, shape=[…, min(m, n)]) – Vector of diagonal coefficients.

static equal(mat_a, mat_b, atol=1e-12)[source]#

Test if matrices a and b are close.

Parameters:

mat_a (array-like, shape=[…, dim1, dim2]) – Matrix.
mat_b (array-like, shape=[…, dim2, dim3]) – Matrix.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

eq (array-like, shape=[…,]) – Boolean evaluating if the matrices are close.

static flatten(mat)[source]#

Return a flattened form of the matrix.

Flatten a matrix (compatible with vectorization on data axis 0). The reverse operation is reshape. These operations are often called matrix vectorization / matricization in mathematics (https://en.wikipedia.org/wiki/Tensor_reshaping). The names flatten / reshape were chosen to avoid confusion with vectorization on data axis 0.

Parameters:: mat (array-like, shape=[…, m, n]) – Matrix.
Returns:: vec (array-like, shape=[…, m * n]) – Flatten copy of mat.

static frobenius_product(mat_1, mat_2)[source]#

Compute Frobenius inner-product of two matrices.

The einsum function is used to avoid computing a matrix product. It is also faster than using a sum an element-wise product.

Parameters:

mat_1 (array-like, shape=[…, m, n]) – Matrix.
mat_2 (array-like, shape=[…, m, n]) – Matrix.

Returns:

product (array-like, shape=[…,]) – Frobenius inner-product of mat_1 and mat_2

classmethod is_diagonal(mat, atol=1e-12)[source]#

Check if a square matrix is diagonal.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_diagonal (array-like, shape=[…,]) – Boolean evaluating if the matrix is square and diagonal.

classmethod is_lower_triangular(mat, atol=1e-12)[source]#

Check if a square matrix is lower triangular.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default : backend atol.

Returns:

is_tril (array-like, shape=[…,]) – Boolean evaluating if the matrix is lower triangular

classmethod is_pd(mat)[source]#

Check if a matrix is positive definite.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: is_pd (array-like, shape=[…,]) – Boolean evaluating if the matrix is positive definite.

classmethod is_skew_symmetric(mat, atol=1e-12)[source]#

Check if a square matrix is skew symmetric.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_skew_sym (array-like, shape=[…,]) – Boolean evaluating if the matrix is skew-symmetric.

classmethod is_spd(mat, atol=1e-12)[source]#

Check if a matrix is symmetric positive definite.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_spd (array-like, shape=[…,]) – Boolean evaluating if the matrix is symmetric positive definite.

static is_square(mat)[source]#

Check if a matrix is square.

Parameters:: mat (array-like, shape=[…, m, n]) – Matrix.
Returns:: is_square (array-like, shape=[…,]) – Boolean evaluating if the matrix is square.

classmethod is_strictly_lower_triangular(mat, atol=1e-12)[source]#

Check if a square matrix is strictly lower triangular.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default : backend atol.

Returns:

is_strictly_tril (array-like, shape=[…,]) – Boolean evaluating if the matrix is strictly lower triangular

classmethod is_strictly_upper_triangular(mat, atol=1e-12)[source]#

Check if a square matrix is strictly upper triangular.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default : backend atol.

Returns:

is_strictly_triu (array-like, shape=[…,]) – Boolean evaluating if the matrix is strictly upper triangular

classmethod is_symmetric(mat, atol=1e-12)[source]#

Check if a square matrix is symmetric.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_sym (array-like, shape=[…,]) – Boolean evaluating if the matrix is symmetric.

classmethod is_upper_triangular(mat, atol=1e-12)[source]#

Check if a square matrix is upper triangular.

Parameters:

mat (array-like, shape=[…, n, n]) – Matrix.
atol (float) – Absolute tolerance. Optional, default : backend atol.

Returns:

is_triu (array-like, shape=[…,]) – Boolean evaluating if the matrix is upper triangular.

static mul(*args)[source]#

Compute the product of matrices a1, …, an.

Parameters:

a1 (array-like, shape=[…, dim_1, dim_2]) – Matrix.
a2 (array-like, shape=[…, dim_2, dim_3]) – Matrix.
…
an (array-like, shape=[…, dim_n-1, dim_n]) – Matrix.

Returns:

mul (array-like, shape=[…, dim_1, dim_n]) – Result of the product of matrices.

random_point(n_samples=1, bound=1.0)[source]#

Sample from a uniform distribution in a cube.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample each entry. Optional, default: 1.

Returns:

point (array-like, shape=[…, m, n]) – Sample.

reshape(vec)[source]#

Return a matricized form of the vector.

Matricize a vector (compatible with vectorization on data axis 0). The reverse operation is matrices.flatten. These operations are often called matrix vectorization / matricization in mathematics (https://en.wikipedia.org/wiki/Tensor_reshaping). The names flatten / reshape were chosen to avoid confusion with vectorization on data axis 0.

Parameters:: vec (array-like, shape=[…, m * n]) – Vector.
Returns:: mat (array-like, shape=[…, m, n]) – Matricized copy of vec.

classmethod to_diagonal(mat)[source]#

Make a matrix diagonal.

Make a matrix diagonal by zeroing out non diagonal elements.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: diag (array-like, shape=[…, n, n])

classmethod to_lower_triangular(mat)[source]#

Make a matrix lower triangular.

Make a matrix lower triangular by zeroing out upper elements.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: tril (array-like, shape=[…, n, n]) – Lower triangular matrix.

classmethod to_lower_triangular_diagonal_scaled(mat, K=2.0)[source]#

Make a matrix lower triangular.

Make matrix lower triangular by zeroing out upper elements and divide diagonal by factor K.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: tril (array-like, shape=[…, n, n]) – Lower triangular matrix.

classmethod to_skew_symmetric(mat)[source]#

Make a matrix skew-symmetric.

Make matrix skew-symmetric by averaging it with minus its transpose.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: skew_sym (array-like, shape=[…, n, n]) – Skew-symmetric matrix.

classmethod to_strictly_lower_triangular(mat)[source]#

Make a matrix strictly lower triangular.

Make a matrix stricly lower triangular by zeroing out upper and diagonal elements.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: tril (array-like, shape=[…, n, n]) – Lower triangular matrix.

classmethod to_strictly_upper_triangular(mat)[source]#

Make a matrix stritcly upper triangular.

Make a matrix strictly upper triangular by zeroing out lower and diagonal elements.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: triu (array-like, shape=[…, n, n])

classmethod to_symmetric(mat)[source]#

Make a matrix symmetric.

Make a matrix symmetric by averaging it with its transpose.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: sym (array-like, shape=[…, n, n]) – Symmetric matrix.

classmethod to_upper_triangular(mat)[source]#

Make a matrix upper triangular.

Make a matrix upper triangular by zeroing out lower elements.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: triu (array-like, shape=[…, n, n])

static trace_product(mat_1, mat_2)[source]#

Compute trace of the product of two matrices.

The einsum function is used to avoid computing a matrix product. It is also faster than using a sum an element-wise product.

Parameters:

mat_1 (array-like, shape=[…, m, n]) – Matrix.
mat_2 (array-like, shape=[…, m, n]) – Matrix.

Returns:

product (array-like, shape=[…,]) – Frobenius inner-product of mat_1 and mat_2

static transpose(mat)[source]#

Return the transpose of matrices.

Parameters:: mat (array-like, shape=[…, n, n]) – Matrix.
Returns:: transpose (array-like, shape=[…, n, n]) – Transposed matrix.

class geomstats.geometry.matrices.MatricesMetric(space, signature=None)[source]#

Bases: EuclideanMetric

Euclidean metric on matrices given by Frobenius inner-product.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute Frobenius inner-product of two tangent vectors.

Parameters:

tangent_vec_a (array-like, shape=[…, m, n]) – Tangent vector.
tangent_vec_b (array-like, shape=[…, m, n]) – Tangent vector.
base_point (array-like, shape=[…, m, n]) – Base point. Optional, default: None.

Returns:

inner_prod (array-like, shape=[…,]) – Frobenius inner-product of tangent_vec_a and tangent_vec_b.

norm(vector, base_point=None)[source]#

Compute norm of a matrix.

Norm of a matrix associated to the Frobenius inner product.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

norm (array-like, shape=[…,]) – Norm.

geomstats.geometry.minkowski module#

Minkowski space.

Lead author: Nina Miolane.

class geomstats.geometry.minkowski.Minkowski(dim, equip=True)[source]#

Bases: Euclidean

Class for Minkowski space.

This is the Euclidean space endowed with the inner-product of signature ( dim-1, 1).

Parameters:: dim (int) – Dimension of Minkowski space.

class geomstats.geometry.minkowski.MinkowskiMetric(space)[source]#

Bases: RiemannianMetric

Class for the pseudo-Riemannian Minkowski metric.

The metric is flat: the inner product is independent of the base point.

exp(tangent_vec, base_point, **kwargs)[source]#

Compute the Riemannian exponential of tangent_vec at base_point.

The Riemannian exponential is the addition in the Minkowski space.

Parameters:

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

Returns:

exp (array-like, shape=[…, dim]) – Riemannian exponential.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In the case of the Minkowski space, it does not depend on the base point and is infinite everywhere, because of the flat curvature.

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

inner_product(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Inner product between two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, dim]) – Tangent vector at base point.
base_point (array-like, shape=[…, dim]) – Base point. Optional, default: None.

Returns:

inner_product (array-like, shape=[…,]) – Inner-product.

log(point, base_point, **kwargs)[source]#

Compute the Riemannian logarithm of point at base_point.

The Riemannian logarithm is the subtraction in the Minkowski space.

Parameters:

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

Returns:

log (array-like, shape=[…, dim]) – Riemannian logarithm.

metric_matrix(base_point=None)[source]#

Compute the inner product matrix, independent of the base point.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: inner_prod_mat (array-like, shape=[…, dim, dim]) – Inner-product matrix.

geomstats.geometry.nfold_manifold module#

N-fold product manifold.

Lead author: Nicolas Guigui, John Harvey.

class geomstats.geometry.nfold_manifold.NFoldManifold(base_manifold, n_copies, equip=True)[source]#

Bases: Manifold

Class for an n-fold product manifold $M^n$.

Define a manifold as the product manifold of n copies of a given base manifold M.

Parameters:

base_manifold (Manifold) – Base manifold.
n_copies (int) – Number of replication of the base manifold.
default_coords_type (str, {'intrinsic', 'extrinsic', etc}) – Coordinate type. Optional, default: ‘intrinsic’.

belongs(point, atol=1e-12)[source]#

Test if a point belongs to the manifold.

Parameters:

point (array-like, shape=[…, n_copies, *base_shape]) – Point.
atol (float,) – Tolerance.

Returns:

belongs (array-like, shape=[…, n_copies, *base_shape]) – Boolean evaluating if the point belongs to the manifold.

static default_metric()[source]#: Metric to equip the space with if equip is True.

is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

The tangent space of the product manifold is the direct sum of tangent spaces.

Parameters:

vector (array-like, shape=[…, n_copies, *base_shape]) – Vector.
base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

projection(point)[source]#

Project a point from product embedding manifold to the product manifold.

Parameters:: point (array-like, shape=[…, n_copies, *base_shape]) – Point in embedding manifold.
Returns:: projected (array-like, shape=[…, n_copies, *base_shape]) – Projected point.

random_point(n_samples=1, bound=1.0)[source]#

Sample in the product space from the product distribution.

The distribution used is the product of the distributions that each copy of the manifold uses in its own random_point method.

Parameters:

n_samples (int, optional) – Number of samples.
bound (float) – Bound of the interval in which to sample for non compact manifolds. Optional, default: 1.

Returns:

samples (array-like, shape=[…, n_copies, *base_shape]) – Points sampled on the product manifold.

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

The tangent space of the product manifold is the direct sum of tangent spaces.

Parameters:

vector (array-like, shape=[…, n_copies, *base_shape]) – Vector.
base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold.

Returns:

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

class geomstats.geometry.nfold_manifold.NFoldMetric(space, scales=None, signature=None)[source]#

Bases: RiemannianMetric

Class for an n-fold product manifold $M^n$.

Define a manifold as the product manifold of n copies of a given base manifold M.

Parameters:

space (NFoldManifold) – Base space.
scales (array-like) – Scale of each metric in the product.

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, n_copies, *base_shape]) – Tangent vector at a base point.
base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold. Optional, default: None.

Returns:

exp (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold equal to the Riemannian exponential of tangent_vec at the base point.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the inner-product of two tangent vectors at a base point.

Inner product defined by the Riemannian metric at point base_point between tangent vectors tangent_vec_a and tangent_vec_b.

Parameters:

tangent_vec_a (array-like, shape=[…, n_copies, *base_shape]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n_copies, *base_shape]) – Second tangent vector at base point.
base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold. Optional, default: None.

Returns:

inner_prod (array-like, shape=[…,]) – Inner-product of the two tangent vectors.

log(point, base_point)[source]#

Compute the Riemannian logarithm of a point.

Parameters:

point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold.
base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold. Optional, default: None.

Returns:

log (array-like, shape=[…, n_copies, *base_shape]) – Tangent vector at the base point equal to the Riemannian logarithm of point at the base point.

metric_matrix(base_point)[source]#

Compute the matrix of the inner-product.

Matrix of the inner-product defined by the Riemmanian metric at point base_point of the manifold.

Parameters:: base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold at which to compute the inner-product matrix.
Returns:: matrix (array-like, shape=[…, n_copies, dim, dim]) – Matrix of the inner-product at the base point.

pointwise_inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Pointwise inner product.

Parameters:

tangent_vec_a (array-like, shape=[…, n_copies, *base_shape]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n_copies, *base_shape]) – Second tangent vector at base point.
base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold. Optional, default: None.

Returns:

pointwise_inner_prod (array-like, shape=[…, n_copies]) – Inner-product of the two tangent vectors.

pointwise_norm(tangent_vec, base_point)[source]#

Compute the pointwise norms of a tangent vector.

Compute the norms of the components of a tangent vector at the different sampling points of a base curve.

Parameters:

tangent_vec (array-like, shape=[…, n_copies, *base_shape]) – Tangent vector to discrete curve.
base_point (array-like, shape=[…, n_copies, *base_shape]) – Point representing a discrete curve.

Returns:

norm (array-like, shape=[…, *base_shape]) – Point-wise norms.

geomstats.geometry.open_hemisphere module#

Open hemisphere.

For more details, check section 7.4.1 of [T2022].

Lead author: Olivier Bisson.

References

[T2022]

Yann Thanwerdas. Riemannian and stratified

geometries on covariance and correlation matrices. Differential Geometry [math.DG]. Université Côte d’Azur, 2022.

class geomstats.geometry.open_hemisphere.OpenHemisphere(dim, equip=True)[source]#

Bases: OpenSet

Open hemisphere.

An open set of the hypersphere where the first coordinate is always positive.

..math:

\mathrm{HS}^{k-1}=\left\{x \in \mathbb{R}^k: \|x\|=1
\text { and } x_0>0\right\}

belongs(point, atol=1e-12)[source]#: Check if a point belongs to the open hemisphere.

static default_metric()[source]#: Metric to equip the space with if equip is True.

projection(point)[source]#

Project a point on the open hemisphere.

Parameters:: point (array-like, shape=[…, dim]) – Point in embedding hypersphere space.
Returns:: projected_point (array-like, shape=[…, dim]) – Point projected on the open hemisphere.

class geomstats.geometry.open_hemisphere.OpenHemispherePullbackMetric(space)[source]#

Bases: PullbackDiffeoMetric

Pullback diffeo metric for Open Hemisphere.

Pulls back metric from hyperboloid.

class geomstats.geometry.open_hemisphere.OpenHemisphereToHyperboloidDiffeo[source]#

Bases: Diffeo

A diffeomorphism between the open hemisphere and the hyperboloid.

diffeomorphism(base_point)[source]#: Diffeomorphism at base point.

inverse_diffeomorphism(image_point)[source]#: Inverse diffeomorphism at base point.

inverse_tangent_diffeomorphism(image_tangent_vec, image_point=None, base_point=None)[source]#: Inverse tangent diffeomorphism at image point.

tangent_diffeomorphism(tangent_vec, base_point=None, image_point=None)[source]#: Tangent diffeomorphism at base point.

class geomstats.geometry.open_hemisphere.OpenHemispheresProduct(n, equip=True)[source]#

Bases: ProductManifold

A consecutively factor-dim increasing product manifold of open hemispheres.

..math:

HS^1\times \dots \times HS(n)

static default_metric()[source]#: Metric to equip the space with if equip is True.

class geomstats.geometry.open_hemisphere.OpenHemispheresProductMetric(space)[source]#

Bases: ProductRiemannianMetric

Define the product metric on these manifolds.

geomstats.geometry.poincare_ball module#

The n-dimensional hyperbolic space.

The n-dimensional hyperbolic space with Poincare ball model.

Lead author: Hadi Zaatiti.

class geomstats.geometry.poincare_ball.PoincareBall(dim, equip=True)[source]#

Bases: _Hyperbolic, VectorSpaceOpenSet

Class for the n-dimensional Poincare ball.

Class for the n-dimensional Poincaré ball model. For other representations of hyperbolic spaces see the Hyperbolic class.

Parameters:: dim (int) – Dimension of the hyperbolic space.

belongs(point, atol=1e-12)[source]#

Test if a point belongs to the hyperbolic space.

Test if a point belongs to the hyperbolic space based on the poincare ball representation.

Parameters:

point (array-like, shape=[…, dim]) – Point to be tested.
atol (float, optional) – Tolerance at which to evaluate how close the squared norm is to the reference value. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Array of booleans indicating whether the corresponding points belong to the hyperbolic space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

projection(point)[source]#

Project a point on the ball.

Project a point by clipping such that l2 norm being lower than 1

Parameters:: point (array-like, shape=[…, dim]) – Point in embedding Euclidean space.
Returns:: projected_point (array-like, shape=[…, dim]) – Point projected on the ball.

class geomstats.geometry.poincare_ball.PoincareBallMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Class that defines operations using a Poincare ball.

dist(point_a, point_b)[source]#

Compute the geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, dim]) – First point in the Poincare ball.
point_b (array-like, shape=[…, dim]) – Second point in the Poincare ball.

Returns:

dist (array-like, shape=[…,]) – Geodesic distance between the two points.

exp(tangent_vec, base_point, **kwargs)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, dim]) – Tangent vector at a base point.
base_point (array-like, shape=[…, dim]) – Point in the Poincare ball.

Returns:

exp (array-like, shape=[…, dim]) – Point in the Poincare ball equal to the Riemannian exponential of tangent_vec at the base point.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

log(point, base_point, **kwargs)[source]#

Compute Riemannian logarithm of a point wrt a base point.

Parameters:

point (array-like, shape=[…, dim]) – Point in the Poincare ball.
base_point (array-like, shape=[…, dim]) – Point in the Poincare ball.

Returns:

log (array-like, shape=[…, dim]) – Tangent vector at the base point equal to the Riemannian logarithm of point at the base point.

metric_matrix(base_point=None)[source]#

Compute the inner product matrix.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point. Optional, defaults to zeros if None.
Returns:: inner_prod_mat (array-like, shape=[…, dim, dim]) – Inner-product matrix.

mobius_add(point_a, point_b, project_first=True)[source]#

Compute the Mobius addition of two points.

The Mobius addition is useful to compute the log and exp in the ‘ball’ representation.

\[a\oplus b=\frac{(1+2\langle a,b\rangle + ||b||^2)a+ (1-||a||^2)b}{1+2\langle a,b\rangle + ||a||^2||b||^2}\]

Parameters:

point_a (array-like, shape=[…, dim]) – Point in Poincare ball.
point_b (array-like, shape=[…, dim]) – Point in Poincare ball.
project_first (boolean) – Project points on the ball or not (according to tolerance).

Returns:

mobius_add (array-like, shape=[…, dim]) – Result of the Mobius addition.

norm_factor_gradient(variances)[source]#

Compute normalization factor and its gradient.

Compute normalization factor given current variance and dimensionality.

Parameters:

variances (array-like, shape=[n]) – Value of variance.

Returns:

norm_factor (array-like, shape=[n]) – Normalisation factor.
norm_factor_gradient (array-like, shape=[n]) – Gradient of the normalization factor.

normalization_factor(variances)[source]#

Return normalization factor of the Gaussian distribution.

Parameters:: variances (array-like, shape=[n,]) – Array of equally distant values of the variance precision time.
Returns:: norm_func (array-like, shape=[n,]) – Normalisation factor for all given variances.

retraction(tangent_vec, base_point)[source]#

Poincaré ball model retraction.

Approximate the exponential map of the Poincare ball

Parameters:

tangent_vec (array-like, shape=[…, dim]) – vector in tangent space.
base_point (array-like, shape=[…, dim]) – Second point in the Poincare ball.

Returns:

point (array-like, shape=[…, dim]) – Retraction point.

References

squared_dist(point_a, point_b)[source]#

Squared geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, dim]) – Point.
point_b (array-like, shape=[…, dim]) – Point.

Returns:

sq_dist (array-like, shape=[…,]) – Squared distance.

geomstats.geometry.poincare_half_space module#

The n-dimensional hyperbolic space.

Poincare half-space representation.

Lead author: Alice Le Brigant.

class geomstats.geometry.poincare_half_space.PoincareHalfSpace(dim, equip=True)[source]#

Bases: _Hyperbolic, VectorSpaceOpenSet

Class for the n-dimensional Poincare half-space.

Class for the n-dimensional Poincaré half space model. For other representations of hyperbolic spaces see the Hyperbolic class.

Parameters:: dim (int) – Dimension of the hyperbolic space.

belongs(point, atol=1e-12)[source]#

Evaluate if a point belongs to the upper half space.

Parameters:

point (array-like, shape=[…, dim]) – Point to be checked.
atol (float) – Absolute tolerance to evaluate positivity of the last coordinate.

Returns:

belongs (array-like, shape=[…,]) – Array of booleans indicating whether the corresponding points belong to the upper half space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

projection(point, atol=1e-12)[source]#

Project a point in ambient space to the open set.

The last coordinate is floored to atol if it is negative.

Parameters:

point (array-like, shape=[…, dim_embedding]) – Point in ambient space.
atol (float) – Tolerance to evaluate positivity.

Returns:

projected (array-like, shape=[…, dim_embedding]) – Projected point.

class geomstats.geometry.poincare_half_space.PoincareHalfSpaceMetric(space)[source]#

Bases: RiemannianMetric

Class for the metric of the n-dimensional hyperbolic space.

Class for the metric of the n-dimensional hyperbolic space as embedded in the Poincaré half space model.

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential.

Parameters:

tangent_vec (array-like, shape=[…,n]) – Tangent vector at the base point in the Poincare half space.
base_point (array-like, shape=[…,n]) – Point in the Poincare half space.

Returns:

end_point (array-like, shape=[…,n]) – Point in the Poincare half space, reached by the geodesic starting from base_point with initial velocity tangent_vec

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: radius (array-like, shape=[…,]) – Injectivity radius.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the inner-product of two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, dim + 1]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, dim + 1]) – Second tangent vector at base point.
base_point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space.

Returns:

inner_prod (array-like, shape=[…, 1]) – Inner-product of the two tangent vectors.

log(point, base_point)[source]#

Compute Riemannian logarithm of a point wrt a base point.

Parameters:

point (array-like, shape=[…, dim]) – Point in hyperbolic space.
base_point (array-like, shape=[…, dim]) – Point in hyperbolic space.

Returns:

log (array-like, shape=[…, dim]) – Tangent vector at the base point equal to the Riemannian logarithm of point at the base point.

geomstats.geometry.poincare_polydisk module#

The Poincare polydisk.

The Poincare polydisk is defined as a product manifold of the Hyperbolic space of dimension 2. The Poincare polydisk has a product metric. The metric on each space is the natural Poincare metric multiplied by a constant.

Lead author: Yann Cabanes.

References

[JV2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

class geomstats.geometry.poincare_polydisk.PoincarePolydisk(n_disks, equip=True)[source]#

Bases: NFoldManifold

Class for the Poincare polydisk.

The Poincare polydisk is a direct product of n Poincare disks, i.e. hyperbolic spaces of dimension 2.

Parameters:: n_disks (int) – Number of disks.

static default_metric()[source]#: Metric to equip the space with if equip is True.

static intrinsic_to_extrinsic_coords(point_intrinsic)[source]#

Convert point from intrinsic to extrensic coordinates.

Convert the parameterization of a point in the hyperbolic space from its intrinsic coordinates, to its extrinsic coordinates in Minkowski space.

Parameters:: point_intrinsic (array-like, shape=[…, n_disk, dim]) – Point in intrinsic coordinates.
Returns:: point_extrinsic (array-like, shape=[…, n_disks, dim + 1]) – Point in extrinsic coordinates.

class geomstats.geometry.poincare_polydisk.PoincarePolydiskMetric(space)[source]#

Bases: NFoldMetric

Class defining the Poincare polydisk metric.

The Poincare polydisk metric is a product of n Poincare metrics, each of them being multiplied by a specific constant factor (see [JV2016]).

This metric comes from a model used to represent stationary complex autoregressive Gaussian signals.

References

[JV2016]

B. Jeuris and R. Vandebril. The Kähler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

geomstats.geometry.positive_lower_triangular_matrices module#

The manifold of lower triangular matrices with positive diagonal elements.

Lead authors: Olivier Bisson and Saiteja Utpala.

References

[T2022]

Yann Thanwerdas. Riemannian and stratified

geometries on covariance and correlation matrices. Differential Geometry [math.DG]. Université Côte d’Azur, 2022.

class geomstats.geometry.positive_lower_triangular_matrices.CholeskyMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Class for Cholesky metric on Cholesky space.

References

[TP2019]

. “Riemannian Geometry of Symmetric Positive Definite Matrices Via Cholesky Decomposition” SIAM journal on Matrix Analysis and Applications , 2019. https://arxiv.org/abs/1908.09326

static diag_inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the inner product using only diagonal elements.

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

ip_diagonal (array-like, shape=[…]) – Inner-product.

exp(tangent_vec, base_point, **kwargs)[source]#

Compute the Cholesky exponential map.

Compute the Riemannian exponential at point base_point of tangent vector tangent_vec wrt the Cholesky metric. This gives a lower triangular matrix with positive elements.

Parameters:

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

Returns:

exp (array-like, shape=[…, n, n]) – Riemannian exponential.

classmethod inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the inner product.

Compute the inner-product of tangent_vec_a and tangent_vec_b at point base_point using the cholesky Riemannian metric.

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

inner_product (array-like, shape=[…]) – Inner-product.

log(point, base_point, **kwargs)[source]#

Compute the Cholesky logarithm map.

Compute the Riemannian logarithm at point base_point, of point wrt the Cholesky metric. This gives a tangent vector at point base_point.

Parameters:

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

Returns:

log (array-like, shape=[…, n, n]) – Riemannian logarithm.

squared_dist(point_a, point_b, **kwargs)[source]#

Compute the Cholesky Metric squared distance.

Compute the Riemannian squared distance between point_a and point_b.

Parameters:

point_a (array-like, shape=[…, n, n]) – Point.
point_b (array-like, shape=[…, n, n]) – Point.

Returns:

_ (array-like, shape=[…]) – Riemannian squared distance.

static strictly_lower_inner_product(tangent_vec_a, tangent_vec_b)[source]#

Compute the inner product using only strictly lower triangular elements.

Parameters:

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

Returns:

ip_sl (array-like, shape=[…]) – Inner-product.

class geomstats.geometry.positive_lower_triangular_matrices.InvariantPositiveLowerTriangularMatricesMetric(space, metric_mat_at_identity=None, left=True)[source]#

Bases: _InvariantMetricMatrix

Invariant metric on the positive lower triangular matrices.

inner_product_at_identity(tangent_vec_a, tangent_vec_b)[source]#

Compute inner product at tangent space at identity.

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – First tangent vector at identity.
tangent_vec_b (array-like, shape=[…, n, n]) – Second tangent vector at identity.

Returns:

inner_prod (array-like, shape=[…]) – Inner-product of the two tangent vectors.

class geomstats.geometry.positive_lower_triangular_matrices.PositiveLowerTriangularMatrices(n, equip=True)[source]#

Bases: MatrixLieGroup, VectorSpaceOpenSet

Manifold of lower triangular matrices with >0 diagonal.

This manifold is also called the cholesky space.

Parameters:: n (int) – Integer representing the shape of the matrices: n x n.

References

[TP2019]

Z Lin. “Riemannian Geometry of Symmetric Positive Definite Matrices Via Cholesky Decomposition” SIAM journal on Matrix Analysis and Applications , 2019. https://arxiv.org/abs/1908.09326

belongs(point, atol=1e-12)[source]#

Check if mat is lower triangular with >0 diagonal.

Parameters:

point (array-like, shape=[…, n, n]) – Matrix to be checked.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean denoting if mat belongs to cholesky space.

static default_metric()[source]#: Metric to equip the space with if equip is True.

projection(point)[source]#

Project a matrix to the PLT space.

Parameters:: point (array-like, shape=[…, n, n])
Returns:: projected (array-like, shape=[…, n, n])

random_point(n_samples=1, bound=1.0)[source]#

Sample in PLT.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Side of hypercube support of the uniform distribution. Optional, default: 1.0

Returns:

point (array-like, shape=[…, *point_shape]) – Sample.

class geomstats.geometry.positive_lower_triangular_matrices.UnitNormedRowsPLTDiffeo(n)[source]#

Bases: Diffeo

A diffeomorphism from UnitNormedRowsPLTDMatrices to OpenHemispheresProduct.

A diffeomorphism between the space of lower triangular matrices with positive diagonal and unit normed rows and the product space of successively increasing factor-dimension open hemispheres.

Given the way OpenHemisphere is implemented, i.e. the first component is positive, rows need to be flipped.

diffeomorphism(base_point)[source]#

Diffeomorphism at base point.

Parameters:: base_point (array-like, shape=[…, n, n]) – Base point.
Returns:: image_point (array-like, shape=[…, space_dim]) – Image point.

inverse_diffeomorphism(image_point)[source]#

Inverse diffeomorphism at base point.

$f^-1: N \rightarrow M$

Parameters:: image_point (array-like, shape=[…, space_dim]) – Image point.
Returns:: base_point (array-like, shape=[…, n, n]) – Base point.

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

Inverse tangent diffeomorphism at image point.

df^-1_p is a linear map from T_f(p)N to T_pM

Parameters:

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

Returns:

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

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

Tangent diffeomorphism at base point.

df_p is a linear map from T_pM to T_f(p)N. The diffeomorphism is linear, so its pushforward is itself

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=[…, space_dim]) – Image point.

Returns:

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

class geomstats.geometry.positive_lower_triangular_matrices.UnitNormedRowsPLTMatrices(n, equip=True)[source]#

Bases: DiffeomorphicManifold

Space of positive lower triangular matrices with unit-normed rows.

Rows are unit normed wrt Euclidean norm.

For more details, check section 7.4.1 of [T2022].

belongs(point, atol=1e-12)[source]#: Check if a point belongs to the unit normed plt matrices.

static default_metric()[source]#: Metric to equip the space with if equip is True.

is_tangent(vector, base_point, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape = […, *point_shape]) – Vector.
base_point (array-like, shape = […, *point_shape]) – Point on the manifold.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

class geomstats.geometry.positive_lower_triangular_matrices.UnitNormedRowsPLTMatricesPullbackMetric(space)[source]#

Bases: PullbackDiffeoMetric

Pullback diffeo metric on UnitNormedRowsPLTMatrices.

Results from the pullback of a metric on the OpenHemispheresProduct.

geomstats.geometry.positive_reals module#

The manifold of positive reals.

This manifold is a particular case in dimension 1 of the SPD matrices endowed with the SPD affine-invariant metric with a power affine coefficient equal to one. This manifold is used as part of a product manifold involving complex Poincare disks to classify complex stationary centered Gaussian autoregressive time series in [Cabanes2022], [Cabanes_CESAR_2019], [Cabanes_GSI_2019] and [Cabanes_RADAR_2019]. This product manifold is called ProductPositiveRealsAndComplexPoincareDisks in geomstats. It is a product manifold of complex type, therefore the manifold PositiveReals is compatible with complex input points and vectors even if the input values should be reals.

Lead author: Yann Cabanes.

References

[Cabanes2022]

[Cabanes_CESAR_2019]

Yann Cabanes, Frédéric Barbaresco, Marc Arnaudon, Jérémie Bigot. Unsupervised Machine Learning for Pathological Radar Clutter Clustering: the P-Mean-Shift Algorithm, C&ESAR 2019, Nov 2019, Rennes, France. hal-02875430 https://hal.archives-ouvertes.fr/hal-02875430/document

[Cabanes_GSI_2019]

Yann Cabanes, Frédéric Barbaresco, Marc Arnaudon, Jérémie Bigot. Toeplitz Hermitian Positive Definite Matrix Machine Learning based on Fisher Metric. Geometric Science of Information, 2019, 10.1007/978-3-030-26980-7_27. hal-02875403 https://hal.archives-ouvertes.fr/hal-02875403/document

[Cabanes_RADAR_2019]

Yann Cabanes, Frédéric Barbaresco, Marc Arnaudon, Jérémie Bigot. Non-Supervised High Resolution Doppler Machine Learning for Pathological Radar Clutter. RADAR 2019, Sep 2020, Toulon, France. 10.1109/RADAR41533.2019.171295. hal-02875415 https://hal.archives-ouvertes.fr/hal-02875415/document

[JV2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

class geomstats.geometry.positive_reals.PositiveReals(equip=True)[source]#

Bases: VectorSpaceOpenSet

Class for the manifold of positive reals.

The real positive axis endowed with the Information geometry metric.

static belongs(point, atol=1e-12)[source]#

Check if a point is a positive real.

Evaluate if a point belongs to the positive real axis, i.e. evaluate if its norm is lower than one.

Parameters:

point (array-like, shape=[…, 1]) – Points to be checked.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…]) – Boolean denoting if point is a positive real.

static default_metric()[source]#: Metric to equip the space with if equip is True.

static projection(point, atol=1e-12)[source]#

Project a point on the positive reals.

Parameters:

point (array-like, shape=[…, 1]) – Point in ambient manifold.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

projected (array-like, shape=[…, 1]) – Projected point.

static random_point(n_samples=1, bound=1.0, atol=1e-12)[source]#

Sample in the positive reals.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Bound of the interval in which to sample in the tangent space. Optional, default: 1.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

samples (array-like, shape=[…, 1]) – Points sampled in the positive reals.

class geomstats.geometry.positive_reals.PositiveRealsMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Class for the positive reals metric.

It is a particular case in dimension 1 of the SPD affine-invariant metric with a power affine coefficient equal to one.

dist(point_a, point_b)[source]#

Compute the positive reals distance.

Compute the Riemannian distance between point_a and point_b.

Parameters:

point_a (array-like, shape=[…, 1]) – Point.
point_b (array-like, shape=[…, 1]) – Point.

Returns:

dist (array-like, shape=[…]) – Riemannian distance.

static exp(tangent_vec, base_point)[source]#

Compute the positive reals exponential map.

Parameters:

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

Returns:

exp (array-like, shape=[…, 1]) – Riemannian exponential.

static log(point, base_point)[source]#

Compute the positive reals logarithm map.

Compute the Riemannian logarithm at point base_point, of point wrt the positive reals metric. This gives a tangent vector at point base_point.

Parameters:

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

Returns:

log (array-like, shape=[…, 1]) – Riemannian logarithm.

metric_matrix(base_point)[source]#

Compute the inner product matrix at base point.

Parameters:: base_point (array-like, shape=[…, 1]) – Base point.
Returns:: inner_prod_mat (array-like, shape=[…, 1, 1]) – Inner product matrix.

squared_dist(point_a, point_b)[source]#

Compute the positive reals squared distance.

Compute the Riemannian squared distance between point_a and point_b.

Parameters:

point_a (array-like, shape=[…, 1]) – Point.
point_b (array-like, shape=[…, 1]) – Point.

Returns:

squared_dist (array-like, shape=[…]) – Riemannian squared distance.

geomstats.geometry.pre_shape module#

Kendall Pre-Shape space.

Lead authors: Elodie Maignant and Nicolas Guigui.

class geomstats.geometry.pre_shape.KendallShapeMetric(space, fiber_bundle, signature=None)[source]#

Bases: QuotientMetric

Quotient metric on the shape space.

The Kendall shape space is obtained by taking the quotient of the pre-shape space by the space of rotations of the ambient space.

directional_curvature_derivative(tangent_vec_a, tangent_vec_b, base_point=None)[source]#

Compute the covariant derivative of the directional curvature.

For two vectors fields $X|_P = tangent\_vec\_a, Y|_P = tangent\_vec\_b$ with tangent vector value specified in argument at the base point P, the covariant derivative (in the direction ‘X’) $(\nabla_X R_Y)(X) |_P = (\nabla_X R)(Y, X) Y |_P$ of the directional curvature (in the direction Y) $R_Y(X) = R(Y, X) Y$ is a quadratic tensor in ‘X’ and ‘Y’ that plays an important role in the computation of the moments of the empirical Fréchet mean [Pennec].

In more details, let $X, Y$ be the horizontal lift of parallel vector fields extending the tangent vectors given in argument by parallel transport in a neighborhood of the base-point P in the base-space. Such vector fields verify $\nabla^T_X X=0$ and $\nabla^T_X^Y = A_X Y$ using the connection $\nabla^T$ of the total space. Then the covariant derivative of the directional curvature tensor is given by :math: nabla_X (R_Y(X)) = hor nabla^T_X (R^T_Y(X)) - A_X( ver R^T_Y(X)) - 3 (nabla_X^T A_Y A_X Y - A_X A_Y A_X Y ), where $R^T_Y(X)$ is the directional curvature tensor of the total space.

Parameters:

tangent_vec_a (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point on the group.

Returns:

curvature_derivative (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base point.

parallel_transport(tangent_vec, base_point, direction=None, end_point=None, n_steps=100, step='rk4')[source]#

Compute the parallel transport of a tangent vec along a geodesic.

Approximation of the solution of the parallel transport of a tangent vector a along the geodesic between two points base_point and end_point or alternatively defined by $t\mapsto exp_{(base\_point)}(t*direction)$

Parameters:

tangent_vec (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point to transport.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Initial point of the geodesic to transport along.
direction (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector ar base_point, initial velocity of the geodesic to transport along. Optional, default: None.
end_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point to transport to. Unused if tangent_vec_b is given. Optional, default: None.
n_steps (int) – Number of steps to use to approximate the solution of the ordinary differential equation. Optional, default: 100.
step (str, {‘euler’, ‘rk2’, ‘rk4’}) – Scheme to use in the integration scheme. Optional, default: ‘rk4’.

Returns:

transported (array-like, shape=[…, k_landmarks, m_ambient]) – Transported tangent vector at exp_(base_point)(tangent_vec_b).

References

[GMTP21]

Guigui, Nicolas, Elodie Maignant, Alain Trouvé, and Xavier Pennec. “Parallel Transport on Kendall Shape Spaces.” 5th conference on Geometric Science of Information, Paris 2021. Lecture Notes in Computer Science. Springer, 2021. https://hal.inria.fr/hal-03160677.

geomstats.geometry.product_hpd_and_siegel_disks module#

The ProductHPDMatricesAndSiegelDisks manifold.

The ProductHPDMatricesAndSiegelDisks manifold is defined as a product manifold of the HPD manifold and (n-1) Siegel disks. The HPD Siegel disks product has a product metric. The product metric on the HPD Siegel disks product space is the usual HPD matrices affine-invariant metric (with power affine parameter equal 1) and Siegel metrics multiplied by constants. This product manifold can be used to represent Block-Toeplitz HPD matrices.

Lead author: Yann Cabanes.

References

[Cabanes2022]

[Cabanes2021]

Yann Cabanes and Frank Nielsen. New theoreticla tools in the Siegel space for vectorial autoregressive data classification, Geometric Science of Information, 2021. https://franknielsen.github.io/IG/GSI2021-SiegelLogExpClassification.pdf

[JV2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

class geomstats.geometry.product_hpd_and_siegel_disks.ProductHPDMatricesAndSiegelDisks(n_manifolds, n, equip=True)[source]#

Bases: ProductManifold

Class for the ProductHPDMatricesAndSiegelDisks manifold.

The HPD and Siegel product manifold is a direct product of the HPD manifold and (n-1) Siegel disks. Each manifold of the product is a square matrix manifold of the same dimension.

Parameters:

n_manifolds (int) – Number of manifolds of the product.
n (int) – Size of the matrices.

static default_metric()[source]#: Metric to equip the space with if equip is True.

class geomstats.geometry.product_hpd_and_siegel_disks.ProductHPDMatricesAndSiegelDisksMetric(space)[source]#

Bases: ProductRiemannianMetric

Class defining the ProductHPDMatricesAndSiegelDisks metric.

The HPD Siegel disks product metric is a product of the HPD metric and (n-1) Siegel metrics, each of them being multiplied by a specific constant factor (see [Cabanes2022], [Cabanes2021] and [JV2016]). This metric comes from a model used to represent multidimensional complex stationary centered Gaussian autoregressive times series. A multidimensional times series can be seen as a realization of a multidimensional complex Gaussian distributions with zero mean, a block-Toeplitz HPD covariance matrix and a zero relation matrix. The ProductHPDMatricesAndSiegelDisks metric is inspired by information geometry on this specific set of Gaussian distributions.

References

[Cabanes2022]

[Cabanes2021]

[JV2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

geomstats.geometry.product_manifold module#

Product of manifolds.

Lead author: Nicolas Guigui, John Harvey.

class geomstats.geometry.product_manifold.ProductManifold(factors, default_point_type='auto', equip=True)[source]#

Bases: _IterateOverFactorsMixins, Manifold

Class for a product of manifolds M_1 x … x M_n.

In contrast to the classes NFoldManifold, Landmarks, or DiscretizedCurves, the manifolds M_1, …, M_n need not be the same, nor of same dimension, but the list of manifolds needs to be provided.

Parameters:

factors (list) – List of manifolds in the product.
default_point_type ({‘auto’, ‘vector’, ‘matrix’, ‘other’}) – Optional. Default value is ‘auto’, which will implement as ‘vector’ unless all factors have the same shape. Vector representation gives the point as a 1-d array. Matrix representation allows for a point to be represented by an array of shape (n, dim), if each manifold has default_point_type ‘vector’ with shape (dim,). ‘other’ will behave as matrix but for higher dimensions.

belongs(point, atol=1e-12)[source]#

Test if a point belongs to the manifold.

Parameters:

point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point.
atol (float,) – Tolerance.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if the point belongs to the manifold.

static default_metric()[source]#: Metric to equip the space with if equip is True.

is_tangent(vector, base_point=None, atol=1e-12)[source]#

Check whether the vector is tangent at base_point.

The tangent space of the product manifold is the direct sum of tangent spaces.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Point on the manifold. Optional, default: None
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

is_tangent (bool) – Boolean denoting if vector is a tangent vector at the base point.

projection(point)[source]#

Project a point onto product manifold.

Parameters:: point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point in product manifold.
Returns:: projected (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Projected point.

random_point(n_samples=1, bound=1.0)[source]#

Sample in the product space from the product distribution.

The distribution used is the product of the distributions used by the random_point methods of each individual factor manifold.

Parameters:

n_samples (int, optional) – Number of samples.
bound (float) – Bound of the interval in which to sample for non compact manifolds. Optional, default: 1.

Returns:

samples (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Points sampled from the manifold.

random_tangent_vec(base_point, n_samples=1)[source]#

Sample on the tangent space from the product distribution.

The distribution used is the product of the distributions used by the random_tangent_vec methods of each individual factor manifold.

Parameters:

base_point (array-like, shape=[…, n, n]) – Base point of the tangent space. Optional, default: None.
n_samples (int) – Number of samples. Optional, default: 1.

Returns:

samples (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Points sampled in the tangent space of the product manifold at base_point.

regularize(point)[source]#

Regularize the point into the manifold’s canonical representation.

Parameters:: point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point to be regularized.
Returns:: regularized_point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point in the manifold’s canonical representation.

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (array-like, shape=[…, dim]) – Point on the manifold.

Returns:

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

Notes

The tangent space of the product manifold is the direct sum of tangent spaces.

class geomstats.geometry.product_manifold.ProductRiemannianMetric(space)[source]#

Bases: _IterateOverFactorsMixins, RiemannianMetric

Class for product of Riemannian metrics.

property default_point_type#: Point type of space.

dist(point_a, point_b)[source]#

Geodesic distance between two points.

Parameters:

point_a (array-like, shape=[…, self.shape]) – Point.
point_b (array-like, shape=[…, self.shape]) – Point.

Returns:

dist (array-like, shape=[…,]) – Distance.

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, self.shape]) – Tangent vector at a base point.
base_point (array-like, shape=[…, self.shape]) – Point on the manifold. Optional, default: None.

Returns:

exp (array-like, shape=[…, self.shape]) – Point on the manifold equal to the Riemannian exponential of tangent_vec at the base point.

geodesic(initial_point, end_point=None, initial_tangent_vec=None)[source]#

Generate parameterized function for the geodesic curve.

Geodesic curve defined by either:

an initial point and an initial tangent vector,
an initial point and an end point.

Parameters:

initial_point (array-like, shape=[…, dim]) – Point on the manifold, initial point of the geodesic.
end_point (array-like, shape=[…, dim], optional) – Point on the manifold, end point of the geodesic. If None, an initial tangent vector must be given.
initial_tangent_vec (array-like, shape=[…, dim],) – Tangent vector at base point, the initial speed of the geodesics. Optional, default: None. If None, an end point must be given and a logarithm is computed.

Returns:

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the inner-product of two tangent vectors at a base point.

Inner product defined by the Riemannian metric at point base_point between tangent vectors tangent_vec_a and tangent_vec_b.

Parameters:

tangent_vec_a (array-like, shape=[…, self.shape]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, self.shape]) – Second tangent vector at base point.
base_point (array-like, shape=[…, self.shape]) – Point on the manifold. Optional, default: None.

Returns:

inner_prod (array-like, shape=[…,]) – Inner-product of the two tangent vectors.

log(point, base_point)[source]#

Compute the Riemannian logarithm of a point.

Parameters:

point (array-like, shape=[…, self.shape]) – Point on the manifold.
base_point (array-like, shape=[…, self.shape]) – Point on the manifold. Optional, default: None.

Returns:

log (array-like, shape=[…, self.shape]) – Tangent vector at the base point equal to the Riemannian logarithm of point at the base point.

metric_matrix(base_point=None)[source]#

Compute the matrix of the inner-product.

Matrix of the inner-product defined by the Riemmanian metric at point base_point of the manifold.

Parameters:: base_point (array-like, shape=[…, self.shape]) – Point on the manifold at which to compute the inner-product matrix. Optional, default: None.
Returns:: matrix (array-like, shape as described below) – Matrix of the inner-product at the base point. The matrix is in block diagonal form with a block for each factor. Each block is the same size as the metric_matrix for that factor.

property shape#: Shape of space.

squared_norm(vector, base_point=None)[source]#

Compute the square of the norm of a vector.

Squared norm of a vector associated to the inner product at the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, self.shape]) – Vector.
base_point (array-like, shape=[…, self.shape]) – Base point. Optional, default: None.

Returns:

sq_norm (array-like, shape=[…,]) – Squared norm.

geomstats.geometry.product_positive_reals_and_poincare_disks module#

The ProductPositiveRealsAndComplexPoincareDisks manifold.

The ProductPositiveRealsAndComplexPoincareDisks manifold is defined as a product manifold of the positive reals manifold and (n-1) complex Poincaré disks. The positive reals and complex Poincaré disks product has a product metric. The product metric on the positive reals and complex Poincaré disks product space is the positive reals metric and (n - 1) complex Poincaré metrics multiplied by constants. This product manifold can be used to represent Toeplitz HPD matrices. The ProductPositiveRealsAndComplexPoincareDisks corresponds to the one-dimensional case of ProductHPDMatricesAndSiegelDisks. Indeed, PositiveReals is the one-dimensional case of HPDMatrices and ComplexPoincareDisk is the one-dimensional case of Siegel. In these one-dimensional manifolds, many simplifications occur compared with the multidimensional manifolds since matrices commute in dimension 1.

Lead author: Yann Cabanes.

References

[Cabanes_2022]

[Cabanes_CESAR_2019]

Yann Cabanes, Frédéric Barbaresco, Marc Arnaudon et Jérémie Bigot. Unsupervised Machine Learning for Pathological Radar Clutter Clustering: the P-Mean-Shift Algorithm, IEEE, C&ESAR 2019, Rennes, France, 2019. https://hal.archives-ouvertes.fr/hal-02875430

[Cabanes_RADAR_2019]

Yann Cabanes, Frédéric Barbaresco, Marc Arnaudon et Jérémie Bigot. Non-Supervised High Resolution Doppler Machine Learning for Pathological Radar Clutter, IEEE, RADAR 2019, Toulon, France, 2019. https://hal.archives-ouvertes.fr/hal-02875415

[Cabanes_GSI_2019]

Yann Cabanes, Frédéric Barbaresco, Marc Arnaudon et Jérémie Bigot. Toeplitz Hermitian Positive Definite Matrix Machine Learning based on Fisher Metric, IEEE, GSI 2019, Toulouse, France, 2019. https://hal.archives-ouvertes.fr/hal-02875403

[Le_Brigant_2017]

Alice Le Brigant. Probability on the spaces of curves and the associated metric spaces using information geometry; radar applications, PhD thesis, tel-01635258, 2017. https://theses.hal.science/tel-01635258

[Jeuris_2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

[Yang_2013]

Marc Arnaudon, Frédéric Barbaresco and Le Yang. Riemannian Medians and Means With Applications to Radar Signal Processing, IEEE, 2013.

class geomstats.geometry.product_positive_reals_and_poincare_disks.ProductPositiveRealsAndComplexPoincareDisks(n_manifolds, equip=True)[source]#

Bases: ProductManifold

Class for the ProductPositiveRealsAndComplexPoincareDisks manifold.

The positive reals and complex Poincaré disks product manifold is a direct product of the positive reals manifold and (n-1) complex Poincaré disks. Each manifold of the product is a one-dimensional manifold.

Parameters:: n_manifolds (int) – Number of manifolds of the product.

static default_metric()[source]#: Metric to equip the space with if equip is True.

class geomstats.geometry.product_positive_reals_and_poincare_disks.ProductPositiveRealsAndComplexPoincareDisksMetric(space)[source]#

Bases: ProductRiemannianMetric

Class defining the ProductPositiveRealsAndComplexPoincareDisks metric.

The positive reals and complex Poincaré disks product metric is a product of the positive reals metric and (n-1) complex Poincaré metrics, each of them being multiplied by a specific constant factor (see [Cabanes_2022], [Cabanes_CESAR_2019], [Cabanes_RADAR_2019], [Cabanes_GSI_2019], [Le_Brigant_2017], [Jeuris_2016] and [Yang_2013]). This metric comes from a model used to represent one-dimensional complex stationary centered Gaussian autoregressive times series. Such a times series can be seen as a realization of a multidimensional complex Gaussian distributions with zero mean, a Toeplitz HPD covariance matrix and a zero relation matrix. The ProductPositiveRealsAndComplexPoincareDisks metric is inspired by information geometry on this specific set of Gaussian distributions.

References

[Cabanes_2022]

[Cabanes_CESAR_2019]

[Cabanes_RADAR_2019]

[Cabanes_GSI_2019]

[Le_Brigant_2017]

[Jeuris_2016]

B. Jeuris and R. Vandebril. The Kahler mean of Block-Toeplitz matrices with Toeplitz structured blocks, 2016. https://epubs.siam.org/doi/pdf/10.1137/15M102112X

[Yang_2013]

Marc Arnaudon, Frédéric Barbaresco and Le Yang. Riemannian Medians and Means With Applications to Radar Signal Processing, IEEE, 2013.

geomstats.geometry.pullback_metric module#

Classes for the pullback metric.

Lead author: Nina Miolane.

class geomstats.geometry.pullback_metric.PullbackDiffeoMetric(space, diffeo, image_space, signature=None)[source]#

Bases: RiemannianMetric

Pullback metric induced by a diffeomorphism.

curvature(tangent_vec_a, tangent_vec_b, tangent_vec_c, base_point)[source]#

Compute the curvature via diffeomorphic pullback.

Parameters:

tangent_vec_a (array-like, shape=[…, *shape]) – Tangent vector a.
tangent_vec_b (array-like, shape=[…, *shape]) – Tangent vector b.
tangent_vec_c (array-like, shape=[…, *shape]) – Tangent vector c.
base_point (array-like, shape=[…, *shape]) – Base point.

Returns:

curvature (array-like, shape=[…, *shape]) – Curvature in directions tangent_vec a, b, c at base_point.

dist(point_a, point_b)[source]#

Compute the distance via diffeomorphic pullback.

Parameters:

point_a (array-like, shape=[…, *shape]) – Point a.
point_b (array-like, shape=[…, *shape]) – Point b.

Returns:

dist (array-like) – Distance between point_a and point_b.

exp(tangent_vec, base_point)[source]#

Compute the exponential map via diffeomorphic pullback.

Parameters:

tangent_vec (array-like, shape=[…, *shape]) – Tangent vector.
base_point (array-like, shape=[…, *shape]) – Base point.

Returns:

exp (array-like, shape=[…, *shape]) – Riemannian exponential of tangent_vec at base_point.

geodesic(initial_point, end_point=None, initial_tangent_vec=None)[source]#

Compute the geodesic via diffeomorphic pullback.

Parameters:

initial_point (array-like, shape=[…, *shape]) – Initial Point.
end_point (array-like, shape=[…, *shape]) – End Point.

Returns:

geodesic (callable) – Geodesic between initial_point and end_point.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Inner product between two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, *shape]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, *shape]) – Tangent vector at base point.
base_point (array-like, shape=[…, *shape]) – Base point. Optional, default: None.

Returns: