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.ComplexMatrixVectorSpace(shape, dim=None, **kwargs)[source]#

Bases: ComplexVectorSpace

A matrix vector space.

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.

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.

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.

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.

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.

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.

random_point(n_samples=1, **kwargs)[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.
Returns:: samples (array-like, shape=[…, *point_shape]) – Points sampled on the manifold.

random_tangent_vec(base_point=None, 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=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.DiffeomorphicMatrixVectorSpace(shape, dim=None, **kwargs)[source]#

Bases: MatrixVectorSpace, DiffeomorphicVectorSpace

A matrix vector space defined by a diffeomorphism.

basis_representation(matrix_representation)[source]#

Convert a symmetric matrix into a vector.

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

matrix_representation(basis_representation)[source]#

Convert a vector into a symmetric matrix.

Parameters:: basis_representation (array-like, shape=[…, n(n+1)/2]) – Vector.
Returns:: matrix_representation (array-like, shape=[…, n, n]) – Symmetric matrix.

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

Bases: VectorSpace, DiffeomorphicManifold

A vector space defined by a diffeomorphism.

projection(point)[source]#

Make a matrix null-row-sum symmetric.

It considers only the first \(n-1 \times n-1\) components.

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

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(intrinsic=False, shape=None, **kwargs)[source]#

Bases: Manifold, ABC

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

Parameters:: intrinsic (bool) – Coordinates type.

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 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)

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

Bases: VectorSpace, ABC

A matrix vector space.

abstract basis_representation(matrix_representation)[source]#

Compute the coefficients of matrices in the given basis.

This takes a matrix (the matrix representation of a point) and transforms it into its corresponding vector representation (the coefficients wrt a given basis).

Previously, this method was called to_vector. basis_representation makes it more clear that the vector representation depends on the chosen basis.

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

matrix_representation(basis_representation)[source]#

Compute the matrix representation for the given basis coefficients.

This takes a vector representation of a point (the coefficients wrt a given basis) and creates the corresponding matrix representation.

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

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.

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=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.

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=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.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.

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=[…, dim]) – Sample.

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

Generate random tangent vec.

This method is not recommended for statistical purposes, as the tangent vectors generated are not drawn from a distribution related to the Riemannian metric.

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.

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.

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, intrinsic=True, 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.
intrinsic (bool) – Coordinates type.
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 or instance or ScalarProductMetric instance) – 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.

projection(point)[source]#

Project a point to the manifold.

Parameters:: point (array-like, shape[…, *point_shape]) – Point.
Returns:: point (array-like, shape[…, *point_shape]) – 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: ComplexMatrixVectorSpace

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=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.

random_unit_tangent_vec(base_point=None, 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.

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=None)[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=None)[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.

For four tangent vectors at base_point \(P\):

\(H|_P = tangent\_vec\_a\),
\(X|_P = tangent\_vec\_b\),
\(Y|_P = tangent\_vec\_c\),
\(Z|_P = tangent\_vec\_d\),

the covariant derivative of the curvature is defined as: \((\nabla_H R)(X, Y) Z |_P\).

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=None)[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)[source]#

Compute the geodesic ODE associated with the connection.

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

injectivity_radius(base_point=None)[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=None)[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=None)[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}^l\) as a sum of four terms:

\[\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 image 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 image 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 image 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.InvolutionDiffeomorphism[source]#

Bases: Diffeo

A diffeomorphism that is also an involution.

inverse_diffeomorphism(image_point)[source]#

Inverse diffeomorphism at image 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.

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.

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 image point.

inverse_tangent_diffeomorphism(image_tangent_vec, image_point=None, base_point=None)[source]#: 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.VectorSpaceDiffeo(space_ndim, image_space_ndim=None)[source]#

Bases: Diffeo

A diffeo between vector spaces.

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.

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.

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'(s)\|\neq 0 \forall s \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.

property discrete_curves_with_l2#: Copy of discrete curves with the L^2 metric.

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

interpolate(point)[source]#

Interpolate between the sampling points of a discrete curve.

Parameters:: point (array-like, shape=[…, k_sampling_points, ambient_dim]) – Discrete curve starting at the origin.
Returns:: spline (function) – Cubic spline that interpolates between the sampling points of the discrete curve.

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

length(point)[source]#

Compute the length of a discrete curve.

This is the integral of the absolute value of the velocity.

Parameters:: point (array-like, shape=[…, k_sampling_points, ambient_dim]) – Discrete curve starting at the origin.
Returns:: length (array-like, shape=[…, ]) – Length of the discrete curve.

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

normalize(point)[source]#: Rescale discrete curve to have unit length.

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(total_space, n_space_grid=100, max_slope=6)[source]#

Bases: AlignerAlgorithm

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

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

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

Parameters:

total_space (Manifold) – Total space with reparametrizations fiber bundle structure.
n_space_grid (int) – Number of sampling points of the unit interval.
max_slope (int) – Maximum slope allowed for a reparametrization.

References

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

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

Align point to base point.

Parameters:

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

Returns:

aligned (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Curve reparametrized in an optimal way with respect to reference curve.
squared_dist (array, shape=[…,]) – Quotient distance between point and base point. If return_sdist is True.

class geomstats.geometry.discrete_curves.ElasticMetric(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.

For curves in \(\mathbb{R}^2\), it pullbacks the L2 metric by the F-transform (see [NK2018]).

For curves in \(\mathbb{R}^d\), it pullbacks a scaled L2 metric by the SRV transform (see [BCKKNP2022). It only works for ratio \(a / 2b = 1\).

When a=1, and b=1/2, it is equivalent to the SRV metric.

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.

[BCKKNP2022]

Martin Bauer, Nicolas Charon, Eric Klassen, Sebastian Kurtek, Tom Needham, and Thomas Pierron. “Elastic Metrics on Spaces of Euclidean Curves: Theory and Algorithms.” arXiv, September 20, 2022. https://doi.org/10.48550/arXiv.2209.09862.

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 transform 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(total_space, n_time_grid=100, threshold=0.001, max_iter=20, tol=0.001, verbose=0, save_history=False)[source]#

Bases: AlignerAlgorithm

Align two curves through iterative horizontal geodesic algorithm.

This algorithm computes the horizontal geodesic between two curves in the shape bundle of curves modulo reparametrizations, and at the same time, aligns the end curve with respect to the initial curve. This is done through an iterative 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 procedure is based on the decomposition of any path of curves into a horizontal path of curves composed with a path of reparametrizations: \(c(t, s) = c_h(t, phi(t, s))\) where \(d/dt c_h(t, .)\) is horizontal. Here t is the time parameter of the path and s the space parameter of the curves.

The 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 such that the path of its inverses 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:

total_space (Manifold) – Total space with reparametrizations fiber bundle structure.
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. Optional, default: 20.
tol (float) – Minimal spacing between time samples in the unit segment when reparametrizing the end curve. Optional, default: 1e-3.
verbose (boolean) – Optional, default: False.
save_history (bool) – If True, history is saved in a self.history.

References

[LAB2017]

A. Le Brigant, “Optimal matching between curves in a manifold”, in Geometric Science of Information. Springer Lecture Notes in Computer Science 10589 (2017), 57 - 64. https://hal.science/hal-04374199.

align(point, base_point)[source]#

Align point to base point.

Parameters:

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

Returns:

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

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

Compute 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.
end_spline (callable or list[callable]) – Spline interpolation of end point.

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

\[\begin{split}t_i = i / k, \\ i = 0, ..., k - 1\end{split}\]

where \(k\) is the number of landmarks (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.SRVMetric(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.SRVReparametrizationBundle(total_space, aligner=None)[source]#

Bases: FiberBundle

Principal bundle of curves modulo reparameterizations with 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). The geodesic between the shapes of two curves is computed by aligning (i.e. reparametrizing) one of the two curves with respect to the other, and computing the geodesic between the aligned curves. This geodesic will be horizontal, and will project to a geodesic on the shape space.

Two different aligners are available: - IterativeHorizontalGeodesicAligner (default) - DynamicProgrammingAligner.

Parameters:: total_space (DiscreteCurvesStartingAtOrigin) – Space of discrete curves starting at the origin

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.SRVRotationBundle(total_space, aligner=None)[source]#

Bases: FiberBundle

Principal bundle of curves modulo rotations with the SRV metric.

This is the fiber bundle where the total space is the space of parameterized curves equipped with the SRV metric, the action is given by rotations, and the base space is the shape space of curves modulo rotations.

Parameters:: total_space (DiscreteCurvesStartingAtOrigin) – Space of discrete curves starting at the origin

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

Align point to base point.

Find optimal rotation of curve with respect to base curve.

Parameters:

point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Discrete curve to align.
base_point (array-like, shape=[…, k_sampling_points - 1, ambient_dim]) – Reference discrete curve.
return_rotation (boolean) – If true, returns the optimal rotation used for the alignment. Optional, default : False.

Returns:

aligned (array-like, shape=[…, k_sampling_points - 1, ambient_dim) – Curve optimally rotated with respect to reference curve.

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(s) = c(0) + \int_0^s q(u) |q(u)|du\]

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, \text{ where } dQ_c(h)=k \text{ 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.

\[(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, ambient_dim]) – Discrete curve.
image_point (array-like, shape=[…, k_sampling_points - 1, ambient_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.

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_surfaces module#

Discrete Surfaces with Elastic metrics.

Lead authors: Emmanuel Hartman, Adele Myers.

References

[HSKCB2022]

Emmanuel Hartman, Yashil Sukurdeep, Eric Klassen, Nicolas Charon, and Martin Bauer. “Elastic shape analysis of surfaces with second-order Sobolev metrics: a comprehensive numerical framework”. arXiv:2204.04238 [cs.CV], 25 Sep 2022

[HPBDC2023]

Emmanuel Hartman, Emery Pierson, Martin Bauer, Mohamed Daoudi, and Nicolas Charon. “Basis Restricted Elastic Shape Analysis on the Space of Unregistered Surfaces.” arXiv, November 7, 2023. https://doi.org/10.48550/arXiv.2311.04382.

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.

\[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: \(\Delta_q = - Tr(g_q^{-1} \nabla^2)\) where \(g_q\) is the surface metric matrix of \(q\).

The area of the triangles is computed using Heron’s formula.

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.

static surface_metric_matrices_from_one_forms(one_forms)[source]#

Compute the surface metric matrices directly from the one_forms.

This function is useful for efficiency purposes.

Parameters:: one_forms (array-like, shape=[…, n_faces, 2, 3]) – One form evaluated at each face of the triangulated surface.
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]) – Vertex area for each vertex.

class geomstats.geometry.discrete_surfaces.DiscreteSurfacesExpSolver(space, n_steps=10, optimizer=None)[source]#

Bases: ExpSolver

Class to solve the initial value problem (IVP) for exp.

Implements methods from discrete geodesic calculus method.

discrete_geodesic_ivp(tangent_vec, base_point)[source]#

Solve initial value problem (IVP).

Given an initial tangent vector and an initial point, solve the geodesic equation.

Parameters:

tangent_vec (array-like, shape=[n_vertices, 3]) – Initial tangent vector.
base_point (array-like, shape=[n_vertices, 3]) – Initial point, i.e. initial discrete surface.

Returns:

geod (array-like, shape=[n_steps, n_vertices, 3]) – Discretized geodesic uniformly sampled.

exp(tangent_vec, base_point)[source]#

Compute exponential map associated to the Riemmannian metric.

Parameters:

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

Returns:

point (array-like, shape=[…, n_vertices, 3]) – Point on the manifold.

geodesic_ivp(tangent_vec, base_point)[source]#

Geodesic curve for initial value problem.

Parameters:

tangent_vec (array-like, shape=[…, n_vertices, 3]) – Initial tangent vector.
base_point (array-like, shape=[…, n_vertices, 3]) – Initial point, i.e. initial discrete surface.

Returns:

path (callable) – Time parametrized geodesic curve. f(t).

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] and [HPBDC2023] (appendix) 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]

[HPBDC2023]

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>\)

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.

geomstats.geometry.euclidean module#

Euclidean space.

class geomstats.geometry.euclidean.CanonicalEuclideanMetric(space)[source]#

Bases: EuclideanMetric

Class for the canonical Euclidean metric.

Notes

Metric matrix is identity (NB: EuclideanMetric allows to use a different metric matrix).

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.

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.

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.

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, metric_matrix=None, signature=None)[source]#

Bases: RiemannianMetric

Class for a Euclidean metric.

This metric is: - flat: the inner-product is independent of the base point; - positive definite

christoffels(base_point=None)[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.

exp(tangent_vec, base_point)[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.

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:

injectivity_radius(base_point=None)[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.

inner_product_derivative_matrix(base_point=None)[source]#

Compute derivative of the inner prod matrix at base point.

Writing \(g_{ij}\) the inner-product matrix at base point, this computes \(mat_{ijk} = \partial_k g_{ij}\), where the index k of the derivation is put last.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: metric_derivative (array-like, shape=[…, dim, dim, dim]) – Derivative of the inner-product matrix, where the index k of the derivation is last: \(mat_{ijk} = \partial_k g_{ij}\).

log(point, base_point)[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.

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.AlignerAlgorithm(total_space)[source]#

Bases: ABC

Base class for point to point aligner.

Parameters:: total_space (Manifold) – Space equipped with a group action and a group-invariant metric.

abstract align(point, base_point)[source]#

Align point to base point.

Parameters:

point (array-like, shape=[…, *total_space.shape]) – Point to align.
base_point (array-like, shape=[…, *total_space.shape]) – Base point.

Returns:

aligned_point (array-like, shape=[…, *total_space.shape]) – Aligned point.

class geomstats.geometry.fiber_bundle.AlternatingAligner(total_space, threshold=0.001, max_iter=20, verbose=0)[source]#

Bases: AlignerAlgorithm

Alternate alignment algorithm.

Assumes total space is equipped with several group actions. Aligns points wrt these group actions by alternate minimization wrt each of them (similar approach used in e.g. [JKKS2012]).

Parameters:

total_space (Manifold) – Manifold equipped with a quotient structure.
threshold (float) – Distance between consecutive aligned points for which convergence is considered reached.
max_iter (int) – Maximum number of iterations.
verbose (boolean) – If log number of iterations need for convergence.

References

[JKKS2012]

Ian H. Jermyn, Sebastian Kurtek, Eric Klassen, and Anuj Srivastava. “Elastic Shape Matching of Parameterized Surfaces Using Square Root Normal Fields.” In Computer Vision – ECCV 2012, edited by Andrew Fitzgibbon, Svetlana Lazebnik, Pietro Perona, Yoichi Sato, and Cordelia Schmid, 804–17. Lecture Notes in Computer Science. Berlin, Heidelberg: Springer, 2012. https://doi.org/10.1007/978-3-642-33715-4_58.

align(point, base_point)[source]#

Align point to base point.

Parameters:

point (array-like, shape=[…, *point_shape]) – Discrete curve to align.
base_point (array-like, shape=[…, *point_shape]) – Reference discrete curve.

Returns:

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

class geomstats.geometry.fiber_bundle.DistanceMinimizingAligner(total_space, optimizer=None, group_elem_shape=None)[source]#

Bases: AlignerAlgorithm

Aligment based on minimization of squared distance.

Parameters:

total_space (Manifold) – Space equipped with a group action and a group-invariant metric.
optimizer (ScipyMinimize) – Optimizer to solve minimization problem.
group_elem_shape (tuple) – Shape of the group element representation.

align(point, base_point)[source]#

Align point to base point.

Parameters:

point (array-like, shape=[…, *total_space.shape]) – Point to align.
base_point (array-like, shape=[…, *total_space.shape]) – Base point.

Returns:

aligned_point (array-like, shape=[…, *total_space.shape]) – Aligned point.

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

Bases: object

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:

total_space (Manifold) – Space equipped with a group action and a group-invariant metric.
aligner (AlignerAlgorithm) – If True and autodiff works, instantiates default DistanceMinimizationBasedAligner.

align(point, base_point)[source]#

Align point to base point.

Parameters:

point (array-like, shape=[…, *total_space.shape]) – Point to align.
base_point (array-like, shape=[…, *total_space.shape]) – Base point.

Returns:

aligned_point (array-like, shape=[…, *total_space.shape]) – Aligned 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 from:

the vertical projection

the horizontal lift of the tangent submersion

the align method

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 [ONeill] 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

[ONeill]

O’Neill, Barrett. The Fundamental Equations of a Submersion, Michigan Mathematical Journal 13, no. 4 (December 1966): 459–69. https://doi.org/10.1307/mmj/1028999604.

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 \(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.LogScaledMetric(space, alpha=None, delta=None, zeta=1.0)[source]#

Bases: PullbackDiffeoMetric

Pullback metric via a diffeomorphism.

Diffeormorphism between full-rank correlation matrices and the space of symmetric matrices with null row sums.

Check out [T2023] for more details.

Parameters:

space (FullRankCorrelationMatrices)
alpha (float) – Scalar multiplying first term of quadratic form.
delta (float) – Scalar multiplying second term of quadratic form.
zeta (float) – Scalar multiplying third term of quadratic form.

References

[T2023]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices,” November 2023. https://hal.science/hal-03878729.

class geomstats.geometry.full_rank_correlation_matrices.LogScalingDiffeo[source]#

Bases: Diffeo

Off-log diffeomorphism from Cor+ to Row_1^+.

A diffeomorphism between full-rank correlation matrices \(Cor+(n)\) and the space of symmetric matrices with null row sums \(Row_0(n)\).

\[\operatorname{Log} ^{\star} = \log \left(\mathcal{D}^{\star}(\Sigma) \star \Sigma\right): \operatorname{Cor}^{+}(n) \longrightarrow \operatorname{Row}_0(n)\]

Check out [T2023] for more details.

References

[T2023]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices,” November 2023. https://hal.science/hal-03878729.

diffeomorphism(base_point)[source]#

Diffeomorphism at base point.

NB: congruence action is implictly performed.

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

inverse_diffeomorphism(image_point)[source]#

Inverse diffeomorphism at image point.

\(f^{-1}: N \rightarrow M\)

Parameters:: image_point (array-like, shape=[…, n, n]) – 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=[…, n, n]) – Image tangent vector at image point.
image_point (array-like, shape=[…, n, n]) – Image point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

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

tangent_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=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.
image_point (array-like, shape=[…, n, n]) – Image point.

Returns:

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

class geomstats.geometry.full_rank_correlation_matrices.OffLogDiffeo[source]#

Bases: Diffeo

Off-log diffeomorphism from Cor+ to Hol.

A diffeomorphism between full-rank correlation matrices Cor+ and symmetric hollow matrices Hol:

\[\operatorname{Log} = \operatorname{Off} \circ \log : \operatorname{Cor}^{+}(n) \longrightarrow \operatorname{Hol}(n)\]

Check out chapter 8 of [T2022] for more details.

References

[T2022]

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

diffeomorphism(base_point)[source]#

Diffeomorphism at base point.

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

inverse_diffeomorphism(image_point)[source]#

Inverse diffeomorphism at image point.

\(f^{-1}: N \rightarrow M\)

Parameters:: image_point (array-like, shape=[…, n, n]) – 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=[…, n, n]) – Image tangent vector at image point.
image_point (array-like, shape=[…, n, n]) – Image point.
base_point (array-like, shape=[…, n, n]) – Base point.

Returns:

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

tangent_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=[…, n, n]) – Tangent vector at base point.
base_point (array-like, shape=[…, n, n]) – Base point.
image_point (array-like, shape=[…, n, n]) – Image point.

Returns:

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

class geomstats.geometry.full_rank_correlation_matrices.OffLogMetric(space, alpha=None, beta=None, gamma=1.0)[source]#

Bases: PullbackDiffeoMetric

Pullback metric via a diffeomorphism.

Diffeormorphism between full-rank correlation matrices and hollow matrices endowed with a permutation-invariant metric.

For more details, check section 8.2.2 [T2022].

Parameters:

space (FullRankCorrelationMatrices)
alpha (float) – Scalar multiplying first term of quadratic form.
beta (float) – Scalar multiplying second term of quadratic form.
gamma (float) – Scalar multiplying third term of quadratic form.

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.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].

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.UniqueDiagonalMatrixAlgorithm(atol=1e-12, max_iter=100)[source]#

Bases: object

Find unique diagonal matrix corresponding to a full-rank correlation matrix.

That is, for all symmetric matrix \(S\), there exists a unique diagonal matrix \(D\) such that \(expm(D+S)\) is a full-rank correlation matrix.

Converges in logarithmic time to the solution of the equation, no closed form.

Check out Theorem 8.10 of [T2022] for more details.

Parameters:

atol (float) – Tolerance to check algorithm convergence.
max_iter (int) – Maximum iterations.

References

[T2022]

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

[AH2020]

Ilya Archakov, and Peter Reinhard Hansen. “A New Parametrization of Correlation Matrices.” arXiv, December 3, 2020. https://doi.org/10.48550/arXiv.2012.02395.

apply(sym_mat)[source]#

Find unique diagonal matrix corresponding to a full-rank correlation matrix.

Parameters:: sym_mat (array-like, shape=[…, n, n])
Returns:: diag_mat (array-like, shape=[…, n, n])

class geomstats.geometry.full_rank_correlation_matrices.UniquePositiveDiagonalMatrixAlgorithm(atol=1e-12, max_iter=100)[source]#

Bases: object

Find unique positive diagonal matrix corresponding to an SPD matrix.

That is, for every symmetric positive-definite matrix \(\Sigma\), there exists a unique positive diagonal matrix \(\Delta\) such that \(\Delta \Sigma \Delta\) is a symmetric positive-definite matrix with unit row sums.

This result is known as the existence and uniqueness of the scaling of SPD matrices ([T2023], [MO1968], [JR2009]).

Parameters:

atol (float) – Tolerance to check algorithm convergence.
max_iter (int) – Maximum iterations.

References

[T2023]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices,” November 2023. https://hal.science/hal-03878729.

[MO1968]

Marshall, Albert W., and Ingram Olkin. “Scaling of Matrices to Achieve Specified Row and Column Sums.” Numerische Mathematik 12, no. 1 (August 1, 1968): 83–90. https://doi.org/10.1007/BF02170999.

[JR2009]

Johnson, Charles R., and Robert Reams. “Scaling of Symmetric Matrices by Positive Diagonal Congruence.” Linear and Multilinear Algebra 57, no. 2 (March 1, 2009): 123–40. https://doi.org/10.1080/03081080600872327.

apply(sym_mat)[source]#

Apply Newton method to find scaling.

Parameters:: sym_mat (array-like, shape=[…, n, n]) – Symmetric positive-definite matrix.
Returns:: diag_vec (array-like, shape=[…, n]) – Scaling of spd_matrix.

geomstats.geometry.full_rank_correlation_matrices.corr_map(point)[source]#

Compute the correlation matrix associated to an SPD matrix.

\[\text { Cor }: \Sigma \in \operatorname{Sym}^{+}(n) \longmapsto \operatorname{Diag}(\Sigma)^{-1 / 2} \Sigma \operatorname{Diag}(\Sigma)^{-1 / 2} \in \operatorname{Cor}^{+}(n)\]

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

geomstats.geometry.full_rank_correlation_matrices.off_map(matrix)[source]#: Subtract diagonal to a matrix.

geomstats.geometry.full_rank_correlation_matrices.tangent_corr_map(tangent_vec, base_point)[source]#

Compute the differential of the differential of the corr map.

\[d_{\Sigma} \operatorname{Cor}(X)=\Delta_{\Sigma}\left[X-\frac{1}{2} \left(\Delta_{\Sigma}^2 \operatorname{Diag}(X) \Sigma+\Sigma \operatorname{Diag}(X) \Delta_{\Sigma}^2\right)\right] \Delta_{\Sigma}\]

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])

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.

References

[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: RiemannianMetric

Canonical metric of the Grassmann manifold.

exp(tangent_vec, base_point)[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=None)[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.

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

Compute Frobenius inner-product of two tangent vectors.

Coincides with the Frobenius metric.

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.

log(point, base_point)[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.

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.

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)[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 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.group_action module#

Group actions.

class geomstats.geometry.group_action.ComposeAction(group, lie_algebra_repr=True)[source]#

Bases: GroupAction

Action of a group on itself by composition.

Parameters:

group (LieGroup)
lie_algebra_repr (bool) – If True, group elements are represented by the vector representation of Lie algebra elements. This is amenable to perform gradient-based optimizations on the Lie algebra.

property group_elem_shape#: Shape of the group element representation.

class geomstats.geometry.group_action.CongruenceAction[source]#

Bases: GroupAction

Congruence action.

class geomstats.geometry.group_action.GroupAction[source]#

Bases: ABC

Base class for group action.

class geomstats.geometry.group_action.PermutationAction[source]#

Bases: CongruenceAction

Congruence action of the permutation group on matrices.

class geomstats.geometry.group_action.RowPermutationAction[source]#

Bases: GroupAction

Action of the permutation group on matrices by multiplication.

class geomstats.geometry.group_action.SpecialOrthogonalComposeAction(n)[source]#

Bases: ComposeAction

Action of the special orthogonal group.

Parameters:

n (int) – Integer representing the shapes of the matrices : n x n.
lie_algebra_repr (bool) – If True, group elements are represented by the vector representation of Lie algebra elements. This is amenable to perform gradient-based optimizations on the Lie algebra.

geomstats.geometry.group_action.permutation_matrix_from_vector(group_elem, dtype=<class 'numpy.int64'>)[source]#

Transform a permutation vector into a matrix.

Parameters:

group_elem (array-like, shape=[…, n]) – The element of a group.
dtype (gs.dtype) – Array dtype

Returns:

mat_group_element (array-like, shape=[…, n, n]) – Matrix representation of group element.

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

References

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)[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)[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: ComplexMatrixVectorSpace

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

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

static basis_representation(matrix_representation)[source]#

Convert a Hermitian matrix into a vector.

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

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.

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.

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=None)[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).

See also

Integration

squared_dist(point_a, point_b)[source]#

Compute the Bures-Wasserstein 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:

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

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

Bases: ComplexMatricesMetric

Class for the Euclidean metric on the HPD manifold.

static exp_domain(tangent_vec, base_point)[source]#

Compute the domain of the Euclidean exponential map.

Compute the real interval of time where the Euclidean geodesic starting at point base_point in direction tangent_vec is defined.

Parameters:

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

Returns:

exp_domain (array-like, shape=[…, 2]) – Interval of time where the geodesic is defined.

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.

class geomstats.geometry.hpd_matrices.HPDLogEuclideanMetric(space, image_space=None)[source]#

Bases: PullbackDiffeoMetric

Class for the Log-Euclidean metric on the HPD manifold.

class geomstats.geometry.hpd_matrices.HPDMatrices(n, equip=True)[source]#

Bases: ComplexVectorSpaceOpenSet

Class for the manifold of Hermitian positive definite (HPD) matrices.

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

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

Check if a matrix is Hermitian with positive eigenvalues.

Parameters:

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

Returns:

belongs (array-like, shape=[…,]) – Boolean denoting if mat is an HPD matrix.

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

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

Project a matrix to the space of HPD matrices.

First the Hermitian part of point is computed, then the eigenvalues are floored to gs.atol.

Parameters:

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

Returns:

projected (array-like, shape=[…, n, n]) – HPD matrix.

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

Sample in HPD(n) from the log-uniform distribution.

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.

Returns:

samples (array-like, shape=[…, n, n]) – Points sampled in HPD(n).

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

Sample on the tangent space of HPD(n) from the uniform distribution.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
base_point (array-like, shape=[…, n, n]) – Base point of the tangent space.

Returns:

samples (array-like, shape=[…, n, n]) – Points sampled in the tangent space at base_point.

geomstats.geometry.hyperbolic module#

Common interface to hyperbolic spaces.

Lead author: Thomas Gerald.

class geomstats.geometry.hyperbolic.Hyperbolic(dim, 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.
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, i.e.

\[- x_0^2 + x_1^2 + ... + x_n^2 = - 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.

project_on_geodesic(point, base_point, tangent_vec)[source]#

Project on geodesic in extrinsic coordinates.

Project point onto geodesic going through base point in direction of tangent vector. See reference below.

Parameters:

point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space.
base_point (array-like, shape=[…, dim + 1]) – Point through which the geodesic passes.
tangent_vec (array-like, shape=[…, dim + 1]) – Tangent vector in Minkowski space, direction of the geodesic.

Returns:

proj (array-like, shape=[…, dim + 1]) – Projected point on the geodesic.

References

[CSV2016]

R. Chakraborty, D. Seo, and B. C. Vemuri, “An efficient exact-pga algorithm for constant curvature manifolds.” Proceedings of the IEEE conference on computer vision and pattern recognition. 2016.

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: RiemannianMetric

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=None)[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 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, intrinsic=False, 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 intrinsic 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.
intrinsic (bool) – 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)[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=None)[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)[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)[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)[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=None)[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)[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.

class geomstats.geometry.invariant_metric.InvariantMetricMatrixExpODESolver(space, integrator=None)[source]#

Bases: ExpODESolver

An exp solver adapted to _InvariantMetricMatrix.

exp(tangent_vec, base_point)[source]#

Compute Riemannian exponential of tan. vector wrt to base point.

If \(\gamma\) is a geodesic, then it satisfies the Euler-Poincare equation [Kolev]:

\[\dot{\gamma}(t) = (dL_{\gamma(t)}) X(t) \dot{X}(t) = ad^*_{X(t)}X(t)\]

where \(ad^*\) is the dual adjoint map with respect to the metric. For a right-invariant metric, \(dR\) is used instead of \(dL\) and \(ad^*\) is replaced by \(-ad^*\). The exponential map is approximated by numerical integration of this equation, with initial conditions \(\dot{\gamma}(0)\) given by the argument tangent_vec and \(\gamma(0)\) by base_point.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at a base point.
base_point (array-like, shape=[…, n, n]) – Point in the group. Optional, defaults to identity if None.

Returns:

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

References

https://en.wikipedia.org/wiki/Runge–Kutta_methods

[Kolev]

Kolev, Boris. “Lie Groups and Mechanics: An Introduction.” Journal of Nonlinear Mathematical Physics 11, no. 4, 2004: 480–98. https://doi.org/10.2991/jnmp.2004.11.4.5.

geodesic_ivp(tangent_vec, base_point)[source]#: Geodesic curve for initial value problem.

class geomstats.geometry.invariant_metric.InvariantMetricMatrixLogODESolver(space, n_nodes=10, integrator=None, initialization=None, use_jac=True)[source]#

Bases: LogODESolver

A log solver adapted to _InvariantMetricMatrix.

log(point, base_point)[source]#: Logarithm map.

geomstats.geometry.klein_bottle module#

The Klein Bottle manifold.

Lead author: Juliane Braunsmann

class geomstats.geometry.klein_bottle.KleinBottle(equip=True)[source]#

Bases: Manifold

Class for the Klein Bottle, a two dimensional manifold which is not orientable.

Points are understood to be on the Klein Bottle if they are in the interval \([0,1]^2\). Each point in \(\mathbb R^2\) can be understood as a point on the Klein Bottle by considering the equivalence relation

\begin{align} & (x_1,y_1) \sim (x_2, y_2) \\ \Leftrightarrow \quad & y_1-y_2 \in \mathbb Z \text{ and } x_1-x_2 \in 2\mathbb Z \\ \text{ or } \quad & y_1 + y_2 \in \mathbb Z \text{ and } x_1-x_2 \in \mathbb Z\setminus 2\mathbb Z. \end{align}

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

Evaluate if the point belongs to the set [0,1]^2.

Parameters:

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

Returns:

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

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

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

Evaluate whether two points represent equivalent points on the Klein Bottle.

This method uses the equivalence stated in the class description.

This means points are equivalent if one walks an even number of squares in x-direction and any number of squares in y-direction or an uneven number of squares in x-direction and any number of squares in y-direction while “mirroring” the y coordinate.

Parameters:

point_a (array-like, shape=[…, 2]) – Representation of point on Klein Bottle
point_b (array-like, shape=[…, 2]) – Representation of point on Klein Bottle
atol (Absolute tolerance to test for belonging to mathbb Z.)

Returns:

is_equivalent (array-like, shape=[…, 2]) – Boolean evaluating if points are equivalent

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

Evaluate if the point belongs to \(\mathbb R^2\).

This method checks the shape of the input point.

Parameters:

vector (array-like, shape=[…, dim]) – Point to test.
base_point (unused here)
atol (float) – Unused here.

Returns:

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

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

Uniformly sample points on the manifold.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (unused)

Returns:

samples (array-like, shape=[n_samples, 2]) – Points sampled on the manifold.

regularize(point)[source]#

Regularize arbitrary point to canonical equivalent in unit square.

Regularize any point in \(\mathbb R^2\) to its canonical equivalent representation in the square \([0,1]^2\).

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

static to_bagel_coords(point, radius=5.0)[source]#

Convert point to coordinates in R^3 parametrizing the Klein bagel.

Convert from the intrinsic coordinates in the Klein bottle (2 parameters), to the coordinates of the Klein bagel parametrization in 3d Euclidean space (3 parameters). For intrinsic parameters (theta,v) the Klein bagel parametrization is [https://en.wikipedia.org/wiki/Klein_bottle#The_figure_8_immersion]:

x = left(r + cos(theta/2)sin(v) - sin(theta/2)sin(2v)right)cos(theta) y = left(r + cos(theta/2)sin(v) - sin(theta/2)sin(2v)right)sin(theta) z = sin(theta/2)sin(v) + cos(theta/2)sin(2v)

for 0leqtheta<2pi and 0leq v<2pi. r is a constant to determine the aspect ratio.

Parameters:

point (array-like, shape=[…, 2]) – Point on the Klein bottle, in intrinsic coordinates.
radius (float) – Radius of the circle.

Returns:

point_extrinsic (array-like, shape=[…, 4]) – Point on the Klein bottle, in the Klein bagel parametrization.

static to_bottle_coords(point)[source]#

Convert point to coordinates in R^3 parametrizing the Klein bottle.

Convert from the intrinsic coordinates in the Klein bottle (2 parameters), to the coordinates of the Klein bottle parametrization in 3d Euclidean space (3 parameters). For intrinsic parameters (theta,v) the Klein bottle parametrization is [https://en.wikipedia.org/wiki/Klein_bottle#Bottle_shape]

Parameters:: point (array-like, shape=[…, 2]) – Point on the Klein bottle, in intrinsic coordinates.
Returns:: point_extrinsic (array-like, shape=[…, 4]) – Point on the Klein bottle, in the Klein bagel parametrization.

to_coords(point, coords_type, **kwargs)[source]#

Convert point from intrinsic to coordinates type.

Parameters:

point (array-like, shape=[…, 2]) – Point on the Klein bottle, in intrinsic coordinates.
coords_type (str) – One of the following: “extrinsic”, “bottle”, “bagel”

Returns:

transformed_point (array-like, shape=[…, repr_dim]) – Point in new representation.

static to_extrinsic_coords(point)[source]#

Convert point to extrinsic coordinates.

Convert from the intrinsic coordinates in the Klein bottle (2 parameters), to the extrinsic coordinates in Euclidean space (4 parameters). For intrinsic parameters (theta,v) the extrinsic Euclidean parametrization is [https://en.wikipedia.org/wiki/Klein_bottle#4-D_non-intersecting]:

x = R left(cos(theta/2)cos(v) - sin(theta/2)sin(2v)right) y = R left(sin(theta/2)cos(v) + cos(theta/2)sin(2v)right) z = P cos(theta)(1+epsilon sin(v)) w = P sin(theta)(1+epsilon sin(v))

for 0leqtheta<2pi and 0leq v<2pi. P and R are constants to determine the aspect ratio. ε is any small constant .

Parameters:: point (array-like, shape=[…, 2]) – Point on the Klein bottle, in intrinsic coordinates.
Returns:: point_extrinsic (array-like, shape=[…, 4]) – Point on the Klein bottle, in extrinsic coordinates in Euclidean space.

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

Project a vector to a tangent space of the manifold.

In this case returns the vector itself.

Parameters:

vector (array-like, shape=[…, dim]) – Vector.
base_point (unused)

Returns:

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

class geomstats.geometry.klein_bottle.KleinBottleMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Class for the Klein Bottle Metric.

Implements exp and log using explicit formulas.

Parameters:: space (KleinBottle) – Underlying manifold.

exp(tangent_vec, base_point)[source]#

Exponential map.

Computed by adding tangent_vec to base_point and finding canonical representation in the unit square.

Parameters:

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

Returns:

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

injectivity_radius(base_point=None)[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=[…, 2]) – Point on the manifold. Unused.
Returns:: radius (float) – 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=[…, 2]) – Tangent vector at base point.
tangent_vec_b (array-like, shape=[…, 2]) – Tangent vector at base point.
base_point (array-like, shape=[…, 2]) – Base point. Optional, default: None, unused.

Returns:

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

log(point, base_point)[source]#

Logarithm map.

Computed by finding the representative of point closest to base_point and returning their difference.

Parameters:

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

Returns:

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

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: MatrixVectorSpace, 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

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.

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: MatrixVectorSpace

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.

static basis_representation(matrix_representation)[source]#

Convert a lower triangular matrix into a vector.

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

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.

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.

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, intrinsic=True, 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.
intrinsic (bool) – Coordinate type.
equip (bool) – If True, equip space with default metric.

point_ndim#

Dimension of point array.

Type:: int

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 or instance or ScalarProductMetric instance) – If None, default metric will be used.

equip_with_quotient_structure()[source]#

Equip manifold with quotient structure.

Creates attributes quotient and fiber_bundle or aligner ( aligner is used in quotient contexts where the notion of fiber bundle is not defined.).

Returns:: quotient (Manifold or None) – Quotient space equipped with a quotient metric.

abstract 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.

projection(point)[source]#

Project a point to the manifold.

Parameters:: point (array-like, shape[…, *point_shape]) – Point.
Returns:: point (array-like, shape[…, *point_shape]) – 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=None, n_samples=1)[source]#

Generate random tangent vec.

This method is not recommended for statistical purposes, as the tangent vectors generated are not drawn from a distribution related to the Riemannian metric.

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=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.manifold.register_quotient_structure(Space, Metric, GroupAction, FiberBundle, QuotientMetric=None)[source]#

Parameters:

Space (type or str)
Metric (type or str)
GroupAction (type or str)
FiberBundle (type or str)
QuotientMetric (type or str)

geomstats.geometry.matrices module#

Module exposing the Matrices and MatricesMetric class.

class geomstats.geometry.matrices.BasisRepresentationDiffeo(space)[source]#

Bases: VectorSpaceDiffeo

A diffeo from matrices to Euclidean through basis representation.

Parameters:: space (MatrixVectorSpace)

diffeomorphism(base_point=None)[source]#

Diffeomorphism at base point.

Parameters:: base_point (array-like, shape=[…, m, n]) – Base point.
Returns:: image_point (array-like, shape=[…, dim]) – Image point.

inverse_diffeomorphism(image_point=None)[source]#

Inverse diffeomorphism at image point.

\(f^{-1}: N \rightarrow M\)

Parameters:: image_point (array-like, shape=[…, dim]) – Image point.
Returns:: base_point (array-like, shape=[…, m, n]) – Base point.

class geomstats.geometry.matrices.FlattenDiffeo(m, n=None)[source]#

Bases: VectorSpaceDiffeo

A diffeo from matrices to Euclidean by flattening.

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

diffeomorphism(base_point=None)[source]#

Diffeomorphism at base point.

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

inverse_diffeomorphism(image_point=None)[source]#

Inverse diffeomorphism at image point.

\(f^{-1}: N \rightarrow M\)

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

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

Bases: MatrixVectorSpace

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.

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.

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.MatricesDiagMetric(space, metric_coeffs=None)[source]#

Bases: EuclideanMetric

Flat metric on matrices given by a diagonal metric matrix.

Parameters:

space (MatrixVectorSpace)
metric_coeffs (array-like, shape=[m,n])

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.

Notes

Implementation relies on fact that the metric_matrix is diagonal, i.e.

we just need to multiply each element of the tangent vector by the corresponding diagonal coefficient. (Avoids unnecessary reshapings.)

class geomstats.geometry.matrices.MatricesMetric(space, metric_matrix=None, 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.

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.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), i.e. .. math:

ds^2 = - dx_1^2 + dx_2^2 + ... + dx_n^2

Parameters:: dim (int) – Dimension of Minkowski space.

class geomstats.geometry.minkowski.MinkowskiMetric(space)[source]#

Bases: EuclideanMetric

Class for the pseudo-Euclidean Minkowski metric.

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.

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.

\[\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.

\[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)[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=None)[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)[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: PullbackDiffeoMetric

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.

injectivity_radius(base_point=None)[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.

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)[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)[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)[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, total_space, 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 \(\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.

See also

Integration

class geomstats.geometry.pre_shape.PreShapeMetric(space)[source]#

Bases: PullbackDiffeoMetric

Procrustes metric on the pre-shape space.

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.

For four vectors fields \(H|_P =\) tangent_vec_a, \(X|_P =\) tangent_vec_b, \(Y|_P =\) tangent_vec_c, \(Z|_P =\) tangent_vec_d with tangent vector value specified in argument at the base_point \(P\), the covariant derivative of the curvature \((\nabla_H R)(X, Y) Z |_P\) is computed at the base_point \(P\). Since the sphere is a constant curvature space this vanishes identically.

Parameters:

tangent_vec_a (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point along which the curvature is derived.
tangent_vec_b (array-like, shape=[…, k_landmarks, m_ambient]) – Unused tangent vector at base_point (since curvature derivative vanishes).
tangent_vec_c (array-like, shape=[…, k_landmarks, m_ambient]) – Unused tangent vector at base_point (since curvature derivative vanishes).
tangent_vec_d (array-like, shape=[…, k_landmarks, m_ambient]) – Unused tangent vector at base_point (since curvature derivative vanishes).
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Unused point on the group.

Returns:

curvature_derivative (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.

injectivity_radius(base_point=None)[source]#

Compute the radius of the injectivity domain.

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

class geomstats.geometry.pre_shape.PreShapeSpace(k_landmarks, m_ambient, equip=True)[source]#

Bases: LevelSet

Class for the Kendall pre-shape space.

The pre-shape space is the sphere of the space of centered k-ad of landmarks in \(R^m\) (for the Frobenius norm). It is endowed with the spherical Procrustes metric d(x, y):= arccos(tr(xy^t)).

Points are represented by \(k \times m\) centred matrices as in [Nava]. Beware that this is not the usual convention from the literature.

Parameters:

k_landmarks (int) – Number of landmarks
m_ambient (int) – Number of coordinates of each landmark.

References

[Nava]

Nava-Yazdani, E., H.-C. Hege, T. J.Sullivan, and C. von Tycowicz. “Geodesic Analysis in Kendall’s Shape Space with Epidemiological Applications.” Journal of Mathematical Imaging and Vision 62, no. 4 549–59. https://doi.org/10.1007/s10851-020-00945-w.

static center(point)[source]#

Center landmarks around 0.

Parameters:: point (array-like, shape=[…, k_landmarks, m_ambient]) – Point in Matrices space.
Returns:: centered (array-like, shape=[…, k_landmarks, m_ambient]) – Point with centered landmarks.

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

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

Check that landmarks are centered around 0.

Parameters:

point (array-like, shape=[…, k_landmarks, m_ambient]) – Point in Matrices space.
atol (float) – Tolerance at which to evaluate mean == 0. Optional, default: backend atol.

Returns:

is_centered (array-like, shape=[…,]) – Boolean evaluating if point is centered.

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

projection(point)[source]#

Project a point on the pre-shape space.

Parameters:: point (array-like, shape=[…, k_landmarks, m_ambient]) – Point in Matrices space.
Returns:: projected_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point projected on the pre-shape space.

Notes

Requires space to be equipped.

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

Sample in the pre-shape space from the uniform distribution.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Not used.

Returns:

samples (array-like, shape=[…, dim + 1]) – Points sampled on the pre-shape space.

random_uniform(n_samples=1)[source]#

Sample in the pre-shape space from the uniform distribution.

Parameters:: n_samples (int) – Number of samples. Optional, default: 1.
Returns:: samples (array-like, shape=[…, k_landmarks, m_ambient]) – Points sampled on the pre-shape space.

Notes

Requires space to be equipped.

submersion(point)[source]#

Submersion that defines the manifold.

Parameters:: point (array-like, shape=[…, k_landmarks, m_ambient])
Returns:: submersion (array-like, shape=[…])

tangent_submersion(vector, point)[source]#

Tangent submersion.

Parameters:

vector (array-like, shape=[…, dim+1])
point (array-like, shape=[…, dim+1])

Returns:

tangent_submersion (array-like, shape=[…])

to_tangent(vector, base_point)[source]#

Project a vector to the tangent space.

Project a vector in the embedding matrix space to the tangent space of the pre-shape space at a base point.

Parameters:

vector (array-like, shape=[…, k_landmarks, m_ambient]) – Vector in Matrix space.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point on the pre-shape space defining the tangent space, where the vector will be projected.

Returns:

tangent_vec (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector in the tangent space of the pre-shape space at the base point.

Notes

Requires space to be equipped.

class geomstats.geometry.pre_shape.PreShapeSpaceBundle(total_space, aligner=None)[source]#

Bases: FiberBundle

Class for the Kendall pre-shape space bundle.

align(point, base_point)[source]#

Align point to base_point.

Find the optimal rotation R in SO(m) such that the base point and R.point are well positioned.

Parameters:

point (array-like, shape=[…, k_landmarks, m_ambient]) – Point on the manifold.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point on the manifold.

Returns:

aligned (array-like, shape=[…, k_landmarks, m_ambient]) – R.point.

integrability_tensor(tangent_vec_x, tangent_vec_e, base_point)[source]#

Compute the fundamental tensor A of the submersion.

The fundamental tensor A is defined for tangent vectors of the total space by [ONeill] \(A_X Y = ver\nabla^M_{hor X}(hor Y) + hor \nabla^M_{hor X}(ver Y)\) where \(hor, ver\) are the horizontal and vertical projections.

For the Kendall shape space, we have the closed-form expression at base-point P [Pennec]: \(A_X E = P Sylv_P(E^\top hor(X)) + F + <F,P> P\) where \(F = hor(X) Sylv_P(P^\top E)\) and \(Sylv_P(B)\) is the unique skew-symmetric matrix \(\Omega\) solution of \(P^\top P \Omega + \Omega P^\top P = B - B^\top\).

Parameters:

tangent_vec_x (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
tangent_vec_e (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point of the total space.

Returns:

vector (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of the A tensor applied to tangent_vec_x and tangent_vec_e.

References

[ONeill]

O’Neill, Barrett. The Fundamental Equations of a Submersion, Michigan Mathematical Journal 13, no. 4 (December 1966): 459–69. https://doi.org/10.1307/mmj/1028999604.

[Pennec]

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

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 horizontal covariant derivative \(\nabla_X (A_Y E)\) is necessary to compute the covariant derivative of the curvature in a submersion. The components \(\nabla_X (A_Y E)\) and \(A_Y E\) are computed here for the Kendall shape space at base-point \(P = base\_point\) for horizontal vector fields fields :math: X, Y extending the values \(X|_P = horizontal\_vec\_x\), \(Y|_P = horizontal\_vec\_y\) and a general vector field \(E\) extending \(E|_P = tangent\_vec\_e\) in a neighborhood of the base-point P 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=[…, k_landmarks, m_ambient]) – Horizontal tangent vector at base_point.
horizontal_vec_y (array-like, shape=[…, k_landmarks, m_ambient]) – Horizontal tangent vector at base_point.
nabla_x_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
tangent_vec_e (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
nabla_x_e (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point of the total space.

Returns:

nabla_x_a_y_e (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(\nabla_X^S (A_Y E)\).
a_y_e (array-like, shape=[…, k_landmarks, m_ambient]) – 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.

integrability_tensor_derivative_parallel(horizontal_vec_x, horizontal_vec_y, horizontal_vec_z, base_point)[source]#

Compute derivative of the integrability tensor A (special case).

The horizontal covariant derivative \(\nabla_X (A_Y Z)\) of the integrability tensor A may be computed more efficiently in the case of parallel vector fields in the quotient space. \(\nabla_X (A_Y Z)\) and \(A_Y Z\) are computed here for the Kendall shape space with quotient-parallel vector fields \(X, Y, Z\) extending the values horizontal_vec_x, horizontal_vec_y and horizontal_vec_z by parallel transport in a neighborhood of the base-space. Such vector fields verify \(\nabla_X^X = A_X X = 0\), \(\nabla_X^Y = A_X Y\) and similarly for Z.

Parameters:

horizontal_vec_x (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
horizontal_vec_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
horizontal_vec_z (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point of the total space.

Returns:

nabla_x_a_y_z (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(\nabla_X (A_Y Z)\) with X = horizontal_vec_x, Y = horizontal_vec_y and Z = horizontal_vec_z.
a_y_z (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(A_Y Z\) with Y = horizontal_vec_y and Z = horizontal_vec_z.

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]#

Check whether the tangent vector is horizontal at base_point.

Parameters:

tangent_vec (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point on the manifold. Optional, default: none.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

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

iterated_integrability_tensor_derivative_parallel(horizontal_vec_x, horizontal_vec_y, base_point)[source]#

Compute iterated derivatives of the integrability tensor A.

The iterated horizontal covariant derivative \(\nabla_X (A_Y A_X Y)\) (where \(X\) and \(Y\) are horizontal vector fields) is a key ingredient in the computation of the covariant derivative of the directional curvature in a submersion.

The components \(\nabla_X (A_Y A_X Y)\), \(A_X A_Y A_X Y\), \(\nabla_X (A_X Y)\), and intermediate computations \(A_Y A_X Y\) and \(A_X Y\) are computed here for the Kendall shape space in the special case of quotient-parallel vector fields \(X, Y\) extending the values horizontal_vec_x and horizontal_vec_y by parallel transport in a neighborhood. Such vector fields verify \(\nabla_X^X = A_X X\) and \(\nabla_X^Y = A_X Y\).

Parameters:

horizontal_vec_x (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
horizontal_vec_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point of the total space.

Returns:

nabla_x_a_y_a_x_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(\nabla_X^S (A_Y A_X Y)\) with X = horizontal_vec_x and Y = horizontal_vec_y.
a_x_a_y_a_x_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(A_X A_Y A_X Y\) with X = horizontal_vec_x and Y = horizontal_vec_y.
nabla_x_a_x_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(\nabla_X^S (A_X Y)\) with X = horizontal_vec_x and Y = horizontal_vec_y.
a_y_a_x_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(A_Y A_X Y\) with X = horizontal_vec_x and Y = horizontal_vec_y.
a_x_y (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector at base_point, result of \(A_X Y\) with X = horizontal_vec_x and Y = horizontal_vec_y.

References

[Pennec]

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

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

Project to vertical subspace.

Compute the vertical component of a tangent vector \(w\) at a base point \(x\) by solving the sylvester equation:

\[Axx^T + xx^TA = wx^T - xw^T\]

where A is skew-symmetric. Then Ax is the vertical projection of w.

Parameters:

tangent_vec (array-like, shape=[…, k_landmarks, m_ambient]) – Tangent vector to the pre-shape space at base_point.
base_point (array-like, shape=[…, k_landmarks, m_ambient]) – Point on the pre-shape space.
return_skew (bool) – Whether to return the skew-symmetric matrix A. Optional, default: False

Returns:

vertical (array-like, shape=[…, k_landmarks, m_ambient]) – Vertical component of tangent_vec.
skew (array-like, shape=[…, m_ambient, m_ambient]) – Vertical component of tangent_vec.

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, point_ndim=None, 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 (tuple) – Collection of manifolds in the product.
point_ndim (int or None) – If None, defaults to 1, unless all factors have the same shape.

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.

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 point_ndim#: Point type of space.

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=None)[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=None)[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.

Returns:

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

log(point, base_point)[source]#

Compute the logarithm map via diffeomorphic pullback.

Parameters:

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

Returns:

log (array-like, shape=[…, *shape]) – Logarithm of point from base_point.

metric_matrix(base_point=None)[source]#

Metric matrix at the tangent space at a base point.

Parameters:: base_point (array-like, shape=[…, *shape]) – Base point.
Returns:: 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.

Returns:

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

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

Compute the parallel transport via diffeomorphic pullback.

Parameters:

tangent_vec (array-like, shape=[…, *shape]) – Tangent vector.
base_point (array-like, shape=[…, *shape]) – Base point.
direction (array-like, shape=[…, *shape]) – Direction.
end_point (array-like, shape=[…, *shape]) – End point.

Returns:

parallel_transport (array-like, shape=[…, *shape]) – Parallel transport.

squared_dist(point_a, point_b)[source]#

Squared geodesic distance between two points via pullback.

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 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.

Returns:

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

class geomstats.geometry.pullback_metric.PullbackMetric(space, signature=None)[source]#

Bases: RiemannianMetric

Pullback metric.

Let \(f\) be an immersion \(f: M \rightarrow N\) of one manifold \(M\) into the Riemannian manifold \(N\) with metric \(g\). The pull-back metric \(f^*g\) is defined on \(M\) for a base point \(p\) as: \((f^*g)_p(u, v) = g_{f(p)}(df_p u , df_p v) \quad \forall u, v \in T_pM\)

Note

The pull-back metric is currently only implemented for an immersion into the Euclidean space, i.e. for

\(N=\mathbb{R}^n\).

inner_product_derivative_matrix(base_point)[source]#

Compute the inner-product derivative matrix.

The derivative of the metrix matrix is given by \(\partial_k g_{ij}(p)\) where \(p\) is the base_point.

The index k of the derivation is last.

Parameters:: base_point (array-like, shape=[…, *shape]) – Base point. Optional, default: None.
Returns:: inner_prod_deriv_mat (array-like, shape=[…, dim, dim, dim]) – Inner-product derivative matrix, where the index of the derivation is last: \(mat_{ijk} = \partial_k g_{ij}\).

mean_curvature_vector(base_point)[source]#

Compute the mean curvature vector.

The mean curvature vector is defined at base point \(p\) by \(H_p^\alpha= \frac{1}{d} (f^{*}g)_{p}^{ij} (\partial_{i j}^2 f^\alpha(p)\) \(-\Gamma_{i j}^k(p) \partial_k f^\alpha(p))\) where \(f^{*}g\) is the pullback of the metric \(g\) by the immersion \(f\).

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: mean_curvature_vector (array-like, shape=[…, embedding_dim]) – Mean curvature vector.

metric_matrix(base_point)[source]#

Metric matrix at the tangent space at a base point.

Let \(f\) be the immersion \(f: M \rightarrow \mathbb{R}^n\) of the manifold \(M\) into the Euclidean space \(\mathbb{R}^n\). The elements of the metric matrix at a base point \(p\) are defined as: \((f*g)_{ij}(p) = <df_p e_i , df_p e_j>\), for \(e_i, e_j\) basis elements of \(M\).

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

second_fundamental_form(base_point)[source]#

Compute the second fundamental form.

In the case of an immersion f, the second fundamental form is given by the formula: \(\RN{2}(p)_{ij}^\alpha = \partial_{i j}^2 f^\alpha(p)\) \(-\Gamma_{i j}^k(p) \partial_k f^\alpha(p)\) at base_point \(p\).

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: second_fundamental_form (array-like, shape=[…, embedding_dim, dim, dim]) – Second fundamental form \(\RN{2}(p)_{ij}^\alpha\) where the \(\alpha\) index is first.

geomstats.geometry.quotient_metric module#

Classes for fiber bundles and quotient metrics.

Lead author: Nicolas Guigui.

class geomstats.geometry.quotient_metric.QuotientMetric(space, total_space, signature=None)[source]#

Bases: RiemannianMetric

Quotient metric.

Given a (principal) fiber bundle, or more generally a manifold with a Lie group acting on it by the right, the quotient space is the space of orbits under this action. The quotient metric is defined such that the canonical projection is a Riemannian submersion, i.e. it is isometric to the restriction of the metric of the total space to horizontal subspaces.

Parameters:

space (Manifold) – Base.
total_space (Manifold) – Total space equipped with a fiber bundle structure.

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

Compute the curvature.

For three vectors fields \(X|_P = tangent\_vec\_a, Y|_P = tangent\_vec\_b, Z|_P = tangent\_vec\_c\) with tangent vector specified in argument at the base point \(P\), the curvature is defined by \(R(X,Y)Z = \nabla_{[X,Y]}Z - \nabla_X\nabla_Y Z + \nabla_Y\nabla_X Z\).

In the case of quotient metrics, the fundamental equations of a Riemannian submersion allow to compute the curvature of the base manifold from the one of the total space and a correction term that uses the integrability tensor A [ONeill].

In more details, let \(X, Y, Z\) be the horizontal lift of vector fields extending the tangent vectors given in argument in a neighborhood of the base-point P in the base-space. Then the curvature of the base-space at the base-points is \(R(X,Y) Z = hor( R^T(X,Y) Z) - 2 A_Z A_X Y + A_X A_Y Z - A_Y A_X Z\), where \(R^T(X,Y)Z\) is the curvature tensor of the total space.

Parameters:

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

Returns:

curvature (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector at base_point.

References

[ONeill]

O’Neill, Barrett. The Fundamental Equations of a Submersion, Michigan Mathematical Journal 13, no. 4 (December 1966): 459–69. https://doi.org/10.1307/mmj/1028999604.

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

Compute the covariant derivative of the curvature.

In the case of quotient metrics, the fundamental equations of a Riemannian submersion allow to compute this tensor on the base manifold from the one of the total space T and its covariant derivative with additional correction terms involving the integrability tensor A and its covariant derivatives [Pennec].

In more details, let \(H, X, Y, Z\) 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_H H=0\), \(\nabla^T_H X = A_H X\) (and similarly for Y and Z) using the connection \(\nabla^T\) of the total space. Then the covariant derivative of the curvature tensor is given by

\[\nabla_H (R(X, Y) Z) = hor\nabla_H^T(R^T(X,Y)Z) - A_H(ver R^T(X,Y)Z ) + (2 A_H A_Z A_X Y - A_H A_X A_Y Z + A_H A_Y A_X Z) - (2 \nabla_H^T A_Z A_X Y - \nabla_H^T A_X A_Y Z + \nabla_H^T A_Y A_X Z)\]

where \(R^T(X,Y)Z\) is the curvature tensor of the total space.

Parameters:

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

Returns:

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

References

[Pennec]

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

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

Compute the covariant derivative of the directional curvature.

This tensor can be computed from the covariant derivative of the curvature tensor as in done generically the Connection class. However, in the case of quotient metrics, a simplified expression can be implemented based on the directional curvature of the total space T and its covariant derivative with additional correction terms involving the integrability tensor A and its covariant derivatives [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

\[\nabla_X (R_Y(X)) = hor \nabla^T_X (R^T_Y(X)) - A_X( ver R^T_Y(X)) + 3 A_X A_Y A_X Y - 3 \nabla_X^T 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=[…, 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]) – Point on the base manifold.

Returns:

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

References

[Pennec]

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

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector to the quotient manifold.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Point on the quotient manifold. Optional, default: None.

Returns:

exp (array-like, shape=[…, {dim, [n, n]}]) – Point on the quotient 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:

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

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

Parameters:

tangent_vec_a (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector to the quotient manifold.
tangent_vec_b (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector to the quotient manifold.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Point on the quotient manifold. Optional, default: None.
fiber_point (array-like, shape=[…, {dim, [n, n]}]) – Point on the total space, lift of base_point, i.e. such that submersion applied to point results in base_point. Optional, default: None. In this case, it is computed using the method lift.

Returns:

inner_product (float, shape=[…]) – Inner products

log(point, base_point)[source]#

Compute the Riemannian logarithm of a point.

Parameters:

point (array-like, shape=[…, {dim, [n, n]}]) – Point on the quotient manifold.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Point on the quotient manifold.

Returns:

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

squared_dist(point_a, point_b)[source]#

Squared geodesic distance between two points.

Parameters:

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

Returns:

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

geomstats.geometry.rank_k_psd_matrices module#

The manifold of Positive Semi Definite matrices of rank k PSD(n,k).

Lead author: Anna Calissano.

class geomstats.geometry.rank_k_psd_matrices.BuresWassersteinBundle(total_space)[source]#

Bases: FiberBundle

Class for the quotient structure on PSD matrices.

align(point, base_point)[source]#

Align point to base_point.

Find the optimal rotation R in SO(m) such that the base point and R.point are well positioned.

Parameters:

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

Returns:

aligned (array-like, shape=[…, n, k]) – R.point.

horizontal_lift(tangent_vec, base_point=None, fiber_point=None)[source]#: Horizontal lift of a tangent vector.

lift(point)[source]#: Find a representer in top space.

static riemannian_submersion(point)[source]#: Project.

tangent_riemannian_submersion(tangent_vec, base_point)[source]#: Differential.

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

Project to vertical subspace.

Compute the vertical component of a tangent vector \(w\) at a base point \(x\) by solving the sylvester equation:

\[Axx^T + xx^TA = wx^T - xw^T\]

where A is skew-symmetric. Then Ax is the vertical projection of w.

Parameters:

tangent_vec (array-like, shape=[…, n, k]) – Tangent vector to the pre-shape space at base_point.
base_point (array-like, shape=[…, n, k]) – Point on the pre-shape space.
return_skew (bool) – Whether to return the skew-symmetric matrix A. Optional, default: False

Returns:

vertical (array-like, shape=[…, n, k]) – Vertical component of tangent_vec.
skew (array-like, shape=[…, m_ambient, m_ambient]) – Vertical component of tangent_vec.

class geomstats.geometry.rank_k_psd_matrices.PSDBuresWassersteinMetric(space, total_space=None)[source]#

Bases: QuotientMetric

Bures-Wasserstein metric for fixed rank PSD matrices.

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

Bases: object

Class for the psd matrices.

The class is redirecting to the correct embedding manifold. The stratum PSD rank k if the matrix is not full rank. The top stratum SPD if the matrix is full rank. The whole stratified space of PSD if no rank is specified.

Parameters:

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

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

Bases: Manifold

Class for PSD(n,k).

The manifold of Positive Semi Definite matrices of rank k: PSD(n,k).

Parameters:

n (int) – Integer representing the shape of the matrices: n x n.
k (int) – Integer representing the rank of the matrix (k<n).

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

Check if the matrix belongs to the space.

Parameters:

mat (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 is an SPD matrix.

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

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

Check if the vector belongs to the tangent space.

Parameters:

vector (array-like, shape=[…, n, n]) – Matrix to check if it belongs to the tangent space.
base_point (array-like, shape=[…, n, n]) – Base point of the tangent space. Optional, default: None.
atol (float) – Absolute tolerance. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean denoting if vector belongs to tangent space at base_point.

projection(point)[source]#

Project a matrix to the space of PSD matrices of rank k.

The nearest symmetric positive semidefinite matrix in the Frobenius norm to an arbitrary real matrix A is shown to be (B + H)/2, where H is the symmetric polar factor of B=(A + A’)/2. As [Higham1988] is turning the matrix into a PSD, the rank is then forced to be k.

Parameters:: point (array-like, shape=[…, n, n]) – Matrix to project.
Returns:: projected (array-like, shape=[…, n, n]) – PSD matrix rank k.

References

[Higham1988]

Highamm, N. J. “Computing a nearest symmetric positive semidefinite matrix.” Linear Algebra and Its Applications 103 (May 1, 1988): 103-118. https://doi.org/10.1016/0024-3795(88)90223-6

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

Sample in PSD(n,k) from the log-uniform distribution.

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.

Returns:

samples (array-like, shape=[…, n, n]) – Points sampled in PSD(n,k).

to_tangent(vector, base_point)[source]#

Project to the tangent space of PSD(n,k) at base_point.

Parameters:

vector (array-like, shape=[…, n, n]) – Matrix to check if it belongs to the tangent space.
base_point (array-like, shape=[…, n, n]) – Base point of the tangent space. Optional, default: None.

Returns:

tangent (array-like, shape=[…, n, n]) – Projection of the tangent vector at base_point.

geomstats.geometry.riemannian_metric module#

Riemannian and pseudo-Riemannian metrics.

Lead author: Nina Miolane.

class geomstats.geometry.riemannian_metric.RiemannianMetric(space, signature=None)[source]#

Bases: Connection, ABC

Class for Riemannian and pseudo-Riemannian metrics.

The associated Levi-Civita connection on the tangent bundle.

christoffels(base_point=None)[source]#

Compute Christoffel symbols of the Levi-Civita connection.

The Koszul formula defining the Levi-Civita connection gives the expression of the Christoffel symbols with respect to the metric: \(\Gamma^k_{ij}(p) = \frac{1}{2} g^{lk}( \partial_i g_{jl} + \partial_j g_{li} - \partial_l g_{ij})\), where:

\(p\) represents the base point, and
\(g\) represents the Riemannian metric tensor.

Note that the function computing the derivative of the metric matrix puts the index of the derivation last.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: christoffels (array-like, shape=[…, dim, dim, dim]) – Christoffel symbols, where the contravariant index is first.

closest_neighbor_index(point, neighbors)[source]#

Closest neighbor of point among neighbors.

Parameters:

point (array-like, shape=[…, dim]) – Point.
neighbors (array-like, shape=[n_neighbors, dim]) – Neighbors.

Returns:

closest_neighbor_index (int) – Index of closest neighbor.

cometric_matrix(base_point=None)[source]#

Inner co-product matrix at the cotangent space at a base point.

This represents the cometric matrix, i.e. the inverse of the metric matrix.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: cometric_matrix (array-like, shape=[…, dim, dim]) – Inverse of inner-product matrix.

covariant_riemann_tensor(base_point=None)[source]#

Compute purely covariant version of Riemannian tensor at base_point.

In the literature the covariant riemannian tensor is noted \(R_{ijkl}\).

Convention used in the literature (tensor index notation, ref. Wikipedia) is: \(R_{ijkl} = <R(x_k, x_l)x_j, x_i>\) where \(x_i\) is the i-th basis vector of the tangent space at base point.

In other words: [cov_riemann_tensor]_{ijkl} = [metric_matrix]_{im} [riemann_tensor]_{jkl}^m

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: covariant_tensor (array-like, shape=[…, dim, dim, dim, dim]) – covariant_riemann_tensor[…, i, j, k, l] = R_{ijkl} Covariant version of Riemannian curvature tensor.

diameter(points)[source]#

Give the distance between two farthest points.

Distance between the two points that are farthest away from each other in points.

Parameters:: points (array-like, shape=[…, dim]) – Points.
Returns:: diameter (float) – Distance between two farthest points.

dist(point_a, point_b)[source]#

Geodesic distance between two points.

Note: It only works for positive definite Riemannian metrics.

Parameters:

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

Returns:

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

dist_broadcast(point_a, point_b)[source]#

Compute the geodesic distance between points.

If n_samples_a == n_samples_b then dist is the element-wise distance result of a point in points_a with the point from points_b of the same index. If n_samples_a not equal to n_samples_b then dist is the result of applying geodesic distance for each point from points_a to all points from points_b.

Parameters:

point_a (array-like, shape=[n_samples_a, dim]) – Set of points in the Poincare ball.
point_b (array-like, shape=[n_samples_b, dim]) – Second set of points in the Poincare ball.

Returns:

dist (array-like, shape=[n_samples_a, dim] or [n_samples_a, n_samples_b, dim]) – Geodesic distance between the two points.

dist_pairwise(points, n_jobs=1, **joblib_kwargs)[source]#

Compute the pairwise distance between points.

Parameters:

points (array-like, shape=[n_samples, dim]) – Set of points in the manifold.
n_jobs (int) – Number of jobs to run in parallel, using joblib. Note that a higher number of jobs may not be beneficial when one computation of a geodesic distance is cheap. Optional. Default: 1.
**joblib_kwargs (dict) – Keyword arguments to joblib.Parallel

Returns:

dist (array-like, shape=[n_samples, n_samples]) – Pairwise distance matrix between all the points.

See also

joblib documentations

hamiltonian(state)[source]#

Compute the hamiltonian energy associated to the cometric.

The Hamiltonian at state \((q, p)\) is defined by

\[H(q, p) = \frac{1}{2} <p, p>_q\]

where \(<\cdot, \cdot>_q\) is the cometric at \(q\).

Parameters:: state (tuple of arrays) – Position and momentum variables. The position is a point on the manifold, while the momentum is cotangent vector.
Returns:: energy (float) – Hamiltonian energy at state.

inner_coproduct(cotangent_vec_a, cotangent_vec_b, base_point=None)[source]#

Compute inner coproduct between two cotangent vectors at base point.

This is the inner product associated to the cometric matrix.

Parameters:

cotangent_vec_a (array-like, shape=[…, dim]) – Cotangent vector at base_point.
cotangent_vet_b (array-like, shape=[…, dim]) – Cotangent vector at base_point.
base_point (array-like, shape=[…, dim]) – Point on the manifold.

Returns:

inner_coproduct (float) – Inner coproduct between the two cotangent vectors.

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.

Returns:

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

inner_product_derivative_matrix(base_point=None)[source]#

Compute derivative of the inner prod matrix at base point.

Writing \(g_{ij}\) the inner-product matrix at base point, this computes \(mat_{ijk} = \partial_k g_{ij}\), where the index k of the derivation is put last.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: metric_derivative (array-like, shape=[…, dim, dim, dim]) – Derivative of the inner-product matrix, where the index k of the derivation is last: \(mat_{ijk} = \partial_k g_{ij}\).

metric_matrix(base_point=None)[source]#

Metric matrix at the tangent space at a base point.

Parameters:: base_point (array-like, shape=[…, dim]) – Base point.
Returns:: 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.

Returns:

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

normal_basis(basis, base_point=None)[source]#

Normalize the basis with respect to the metric.

This corresponds to a renormalization of each basis vector.

Parameters:

basis (array-like, shape=[dim, dim]) – Matrix of a metric.
base_point (array-like, shape=[dim]) – Base point.

Returns:

basis (array-like, shape=[dim, n, n]) – Normal basis.

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

Normalize tangent vector at a given point.

Parameters:

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

Returns:

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

random_unit_tangent_vec(base_point=None, 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.

scalar_curvature(base_point=None)[source]#

Compute scalar curvature at base_point.

In the literature scalar_curvature is noted S and writes: \(S = g^{ij} Ric_{ij}\), with Einstein notation, where we recognize the trace of the Ricci tensor according to the Riemannian metric \(g\).

Parameters:: base_point (array-like, shape=[…, dim]) – Point on the manifold.
Returns:: curvature (array-like, shape=[…,]) – Scalar curvature.

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

Compute the sectional curvature.

In the literature sectional curvature is noted K.

For two orthonormal tangent vectors \(x,y\) at a base point, the sectional curvature is defined by \(K(x,y) = <R(x, y)x, y>\).

For non-orthonormal vectors, it is \(K(x,y) = <R(x, y)y, x> / (<x, x><y, y> - <x, y>^2)\).

sectional_curvature(X, Y, P) = K(X,Y) where X, Y are tangent vectors at base point P.

The information manifold of multinomial distributions has constant sectional curvature given by \(K = 2 \sqrt{n}\).

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]) – Point in the manifold.

Returns:

sectional_curvature (array-like, shape=[…,]) – Sectional curvature at base_point.

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 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.

Returns:

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

geomstats.geometry.sasaki_metric module#

Class for the Sasaki metric.

A class implementing the Sasaki metric: The natural metric on the tangent bundle TM of a Riemannian manifold M.

Lead authors: E. Nava-Yazdani, F. Ambellan, M. Hanik and C. von Tycowicz.

class geomstats.geometry.sasaki_metric.GradientDescent(lrate=0.1, max_iter=100, tol=1e-06)[source]#

Bases: object

Gradient descent algorithm.

minimize(x_ini, i_pt, e_pt, grad, exp)[source]#: Apply a gradient descent until max_iter or a given tolerance is reached.

class geomstats.geometry.sasaki_metric.SasakiMetric(space, n_jobs=1, n_steps=3)[source]#

Bases: RiemannianMetric

Implements of the Sasaki metric on the tangent bundle TM of a Riem. manifold M.

The Sasaki metric is characterized by the following three properties:

the canonical projection of TM becomes a Riemannian submersion,
parallel vector fields along curves are orthogonal to their fibres, and
its restriction to any tangent space is Euclidean.

Geodesic computations are realized via a discrete formulation of the geodesic equation on TM that involve geodesics, parallel translation, and the curvature tensor on the base manifold M (see [1]_ for details). However, as the implemented energy in the discrete-geodesics-optimization as well as the approximations of its gradient slightly differ from those proposed in [1]_, we also refer to [2] for additional details.

Parameters:

space (Manifold) – Tangent bundle.
n_jobs (int) – Number of jobs for parallel computing. Optional, default: 1.
n_steps (int) – Number of discrete time steps. Optional, default: 3.

References

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a point.

Exponential map at base_point of tangent_vec computed by shooting a Sasaki geodesic using an Euler integration on TM.

Parameters:

tangent_vec (array-like, shape=[…, 2, M.dim]) – Tangent vector in TTM at the base point in TM.
base_point (array-like, shape=[…, 2, M.dim]) – Point in the tangent bundle TM of manifold M.

Returns:

exp (array-like, shape=[…, 2, M.dim]) – Point on the tangent bundle TM.

geodesic_discrete(initial_point, end_point)[source]#

Compute Sakai geodesic employing a variational time discretization.

Parameters:

end_points (array-like, shape=[…, 2, M.shape]) – Points in the tangent bundle TM of manifold M.
initial_points (array-like, shape=[…, 2, M.shape]) – Points in the tangent bundle TM of manifold M.

Returns:

geodesic (array-like, shape=[…, n_steps + 1, 2, M.shape]) – Discrete geodesics of form x(s)=(p(s), u(s)) in Sasaki metric connecting initial_point = x(0) and end_point = x(1).

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=[…, 2, M.dim]) – Tangent vector in TTM of the tangent bundle TM.
tangent_vec_b (array-like, shape=[…, 2, M.dim]) – Tangent vector in TTM of the tangent bundle TM.
base_point (array-like, shape=[…, 2, M.dim]) – Point in the tangent bundle TM of manifold M.

Returns:

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

log(point, base_point)[source]#

Compute the Riemannian logarithm of a point.

Logarithmic map at base_point of point computed by iteratively relaxing a discretized geodesic between base_point and point.

Parameters:

point (array-like, shape=[…, 2, M.dim]) – Point in the tangent bundle TM of manifold M.
base_point (array-like, shape=[…, 2, M.dim]) – Point in the tangent bundle TM of manifold M.

Returns:

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

class geomstats.geometry.sasaki_metric.TangentBundle(space, equip=True)[source]#

Bases: Manifold

Tangent bundle of a space.

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.

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.

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 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.

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

Project a vector to a tangent 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.

geomstats.geometry.scalar_product_metric module#

Scalar product of a Riemannian metric.

Define the product of a Riemannian metric with a scalar number.

Public Methods:: register_scaled_method(func_name, scaling_type)
Public classes: ScalarProductMetric

Lead author: John Harvey.

class geomstats.geometry.scalar_product_metric.ScalarProductMetric(space, scale)[source]#

Bases: object

Class for scalar products of Riemannian and pseudo-Riemannian metrics.

This class multiplies the (0,2) metric tensor ‘space.metric’ by a scalar ‘scaling_factor’. Note that this does not scale distances by ‘scaling_factor’. That would require multiplication by the square of the scalar.

The space is not automatically equipped with the ScalarProductMetric.

An object of this type can also be instantiated by the expression scaling_factor * space.metric.

This class acts as a wrapper for the underlying Riemannian metric. All public attributes apart from ‘underlying_metric’ and ‘scaling_factor’ are loaded from the underlying metric at initialization and rescaled by the appropriate factor. Changes to the underlying metric at runtime will not affect the attributes of this object.

One exception to this is when the ‘underlying_metric’ is itself of type ScalarProductMetric. In this case, rather than wrapping the wrapper, the ‘underlying_metric’ of the first ScalarProductMetric object is wrapped a second time with a new ‘scaling_factor’.

Parameters:

space (Manifold or ComplexManifold) – A manifold equipped with a metric which is being scaled.
scale (float) – The value by which to scale the metric. Note that this rescales the (0,2) metric tensor, so distances are rescaled by the square root of this.

geomstats.geometry.scalar_product_metric.register_scaled_method(func_name, scaling_type)[source]#

The ScalarProductMetric class rescales various methods of a RiemannianMetric by the correct factor. The default behaviour is to rescale linearly. This method allows the user to add a new method to be rescaled according to a different rule.

Note that this method must be called before the ScalarProductMetric is instantiated. It does not affect objects which already exist.

Parameters:

func_name (str) – The name of a method from a RiemannianMetric object which must be rescaled.
scaling_type (str, {‘sqrt’,) – ‘linear’,
‘quadratic’, ‘inverse’, ‘inverse_sqrt’}

How the method should be rescaled as a function of ScalarProductMetric.scale.

geomstats.geometry.siegel module#

The Siegel manifold.

The Siegel manifold is a generalization of the Poincare disk to complex matrices of singular values strictly lower than one. It is defined as the set of complex matrices M such that: I - M @ M.conj().T is a positive definite matrix. Warning: another more restrictive definition of the Siegel disk also exists which add a symmetry condition on the matrices. It has been proven in [Cabanes2022] that the sub-manifold of symmetric Siegel matrices is a totally geodesic sub-manifold of the Siegel space. The sub-manifold of real Siegel matrices is also a totally geodesic sub-manifold of the Siegel space.

Lead author: Yann Cabanes.

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

class geomstats.geometry.siegel.Siegel(n, symmetric=False, equip=True)[source]#

Bases: ComplexVectorSpaceOpenSet

Class for the Siegel space.

Parameters:

n (int) – Integer representing the shape of the matrices: n x n.
symmetric (bool) – If symmetric is True, add a symmetry condition on the matrices to belong to the Siegel space. Optional, default: False.

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

Check if a matrix belongs to the Siegel space.

Parameters:

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

Returns:

belongs (array-like, shape=[…,]) – Boolean denoting if mat belongs to the Siegel space.

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

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

Project a matrix to the Siegel space.

Parameters:

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

Returns:

projected (array-like, shape=[…, n, n]) – Matrix in the Siegel space.

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

Generate random points in the Siegel space.

The Siegel space is the set of complex matrices of singular values strictly lower than one. The Frobenius norm of a matrix is greater than or equal to the spectral norm which corresponds to the largest singular value of a matrix. Then, simulating a matrix with Frobenius norm strictly lower than one, its singular values are also strictly lower than one, therefore this matrix belongs to the Siegel 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: 1.

Returns:

samples (array-like, shape=[…, n, n]) – Points sampled in the Siegel space.

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

Sample on the tangent space of Siegel space from the uniform distribution.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
base_point (array-like, shape=[…, n, n]) – Base point of the tangent space. Optional, default: None.

Returns:

samples (array-like, shape=[…, n, n]) – Points sampled in the tangent space at base_point.

class geomstats.geometry.siegel.SiegelMetric(space, signature=None)[source]#

Bases: ComplexRiemannianMetric

Class for the Siegel metric.

exp(tangent_vec, base_point)[source]#

Compute the Siegel exponential map.

Compute the exponential map at base_point of tangent_vec.

Parameters:

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

Returns:

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

static exp_at_zero(tangent_vec)[source]#

Compute the Siegel exponential map at zero.

Compute the exponential map at zero (null matrix) of tangent_vec.

Parameters:: tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base point.
Returns:: exp (array-like, shape=[…, n, n]) – Point on the manifold.

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

Compute the Siegel inner-product.

Compute the inner-product of tangent_vec_a and tangent_vec_b at point base_point using the Siegel Riemannian metric. The expression of the inner product between the vectors v and w at point O is \(<v, w>_{O} = 1/2 * trace((I - O O^{H})^{-1} v (I - O^{H} O)^{-1} w^{H}) + 1/2 * trace((I - O O^{H})^{-1} w (I - O^{H} O)^{-1} v^{H}) = Re(trace((I - O O^{H})^{-1} v (I - O^{H} O)^{-1} w^{H}))\) where H denotes the conjugate transpose operator.

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.

static isometry(point, point_to_zero)[source]#

Define an isometry for the Siegel metric.

Isometry for the Siegel metric sending point_to_zero (parameter of the isometry) on zero.

Parameters:

point (array-like, shape=[…, n, n]) – Point on the Siegel space.
point_to_zero (array-like, shape=[…, n, n]) – Point send on zero (null matrix) by the isometry.

Returns:

point_image (array-like, shape=[…, n, n]) – Image of point by the isometry.

log(point, base_point)[source]#

Compute the Siegel logarithm map.

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

Parameters:

point (array-like, shape=[…, n, n]) – Point on the Siegel space.
base_point (array-like, shape=[…, n, n]) – Point on the Siegel space.

Returns:

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

static log_at_zero(point)[source]#

Compute the Siegel logarithm map at zero.

Compute the logarithm map at zero (null matrix) of point.

Parameters:: point (array-like, shape=[…, n, n]) – Point on the Siegel space.
Returns:: log_at_zero (array-like, shape=[…, n, n]) – Riemannian logarithm at zero (null matrix).

sectional_curvature(tangent_vec_a, tangent_vec_b, base_point=None, atol=1e-12)[source]#

Compute the sectional curvature.

For two orthonormal tangent vectors at a base point \(x,y\), the sectional curvature is defined by \(<R(x, y)x, y>\). Non-orthonormal vectors can be given.

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. Optional, default is zero
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

sectional_curvature (array-like, shape=[…,]) – Sectional curvature at base_point.

sectional_curvature_at_zero(tangent_vec_a, tangent_vec_b, atol=1e-12)[source]#

Compute the sectional curvature at zero.

Non-orthonormal vectors can be given.

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at zero.
tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector at zero.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

sectional_curvature (array-like, shape=[…,]) – Sectional curvature at zero.

squared_dist(point_a, point_b)[source]#

Compute the Siegel 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:

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

static tangent_vec_from_base_point_to_zero(tangent_vec, base_point)[source]#

Transport a tangent vector from a base point to zero.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at zero.
base_point (array-like, shape=[…, n, n]) – Point on the Siegel space.

Returns:

tangent_vec_at_zero (array-like, shape=[…, n, n]) – Tangent vector at zero (null matrix).

static tangent_vec_from_zero_to_base_point(tangent_vec, base_point)[source]#

Transport a tangent vector from zero to a base point.

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at zero.
base_point (array-like, shape=[…, n, n]) – Point on the Siegel space.

Returns:

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

geomstats.geometry.skew_symmetric_matrices module#

Module providing the SkewSymmetricMatrices class.

This is the Lie algebra of the Special Orthogonal Group. As basis we choose the matrices with a single 1 on the upper triangular part of the matrices (and a -1 in its lower triangular part), except in dim 2 and 3 to match usual conventions.

Lead author: Nicolas Guigui.

class geomstats.geometry.skew_symmetric_matrices.SkewSymmetricMatrices(n, equip=True)[source]#

Bases: MatrixLieAlgebra

Class for skew-symmetric matrices.

Parameters:: n (int) – Number of rows and columns.

basis_representation(matrix_representation)[source]#

Calculate the coefficients of given matrix in the basis.

Compute a 1d-array that corresponds to the input matrix in the basis representation.

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

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

Evaluate if point is a skew-symmetric matrix.

Parameters:

point (array-like, shape=[…, n, n]) – Square matrix to check.
atol (float) – Tolerance for the equality evaluation. Optional, default: backend atol.

Returns:

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

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

classmethod projection(mat)[source]#

Compute the skew-symmetric component of a matrix.

The skew-symmetric part of a matrix \(X\) is defined by

\[(X - X^T) / 2\]

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

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

Sample from a uniform distribution in a cube and project to skew-symmetric.

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=[…, n, n]) – Sample.

geomstats.geometry.spd_matrices module#

The manifold of symmetric positive definite (SPD) matrices.

Lead authors: Yann Thanwerdas and Olivier Bisson.

class geomstats.geometry.spd_matrices.CholeskyMap[source]#

Bases: Diffeo

Cholesky map.

A diffeomorphism from the space of symmetric positive-definite matrices to the space of positive lower triangular matrices.

classmethod diffeomorphism(base_point)[source]#

Compute cholesky factor.

Compute cholesky factor for a symmetric positive definite matrix.

Parameters:: base_point (array_like, shape=[…, n, n]) – spd matrix.
Returns:: cf (array_like, shape=[…, n, n]) – lower triangular matrix with positive diagonal elements.

static inverse_diffeomorphism(image_point)[source]#

Compute gram matrix of rows.

Gram_matrix is mapping from point to point.point^{T}. This is diffeomorphism between cholesky space and spd manifold.

Parameters:: image_point (array-like, shape=[…, n, n]) – element in cholesky space.
Returns:: projected (array-like, shape=[…, n, n]) – SPD matrix.

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

Compute differential of gram.

Parameters:

image_tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.
image_point (array_like, shape=[…, n, n]) – Base point.
base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

differential_gram (array-like, shape=[…, n, n]) – Differential of the gram.

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

Compute the differential of the cholesky factor map.

Parameters:

tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array_like, shape=[…, n, n]) – Base point.
image_point (array_like, shape=[…, n, n]) – Image base point.

Returns:

differential_cf (array-like, shape=[…, n, n]) – Differential of cholesky factor map lower triangular matrix.

class geomstats.geometry.spd_matrices.LieCholeskyMetric(space)[source]#

Bases: PullbackDiffeoMetric

Pullback metric via a diffeomorphism.

Diffeormorphism between SPD matrices and PLT matrices equipped with left invariant metric (see chapter 7 [TP2022]).

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.spd_matrices.MatrixPower(power)[source]#

Bases: Diffeo

Matrix power diffeomorphism.

A diffeomorphism from the space of symmetric positive-definite matrices to itself.

diffeomorphism(base_point)[source]#

Compute the matrix power.

Parameters:: base_point (array_like, shape=[…, n, n]) – Symmetric matrix with non-negative eigenvalues.
Returns:: powerm (array_like or list of arrays, shape=[…, n, n]) – Matrix power of mat.

inverse_diffeomorphism(image_point)[source]#

Compute the inverse matrix power.

Parameters:: image_point (array_like, shape=[…, n, n]) – Symmetric matrix with non-negative eigenvalues.
Returns:: powerm (array_like or list of arrays, shape=[…, n, n]) – Matrix power of mat.

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

Compute the inverse of the differential of the matrix power.

Compute the inverse of the differential of the power function on SPD matrices, \(A^p=\exp(p \log(A))\), at base_point applied to tangent_vec.

Parameters:

image_tangent_vec (array_like, shape=[…, n, n]) – Image tangent vector at image point.
image_base_point (array_like, shape=[…, n, n]) – Image point.
base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

inverse_differential_power (array-like, shape=[…, n, n]) – Inverse of the differential of the power function.

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

Compute the differential of the matrix power function.

Compute the differential of the power function on SPD(n), \(A^p=\exp(p \log(A))\), at base_point applied to tangent_vec.

Parameters:

tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array_like, shape=[…, n, n]) – Base point.
image_point (array_like, shape=[…, n, n]) – Image base point.

Returns:

differential_power (array-like, shape=[…, n, n]) – Differential of the power function.

class geomstats.geometry.spd_matrices.SPDAffineMetric(space, signature=None)[source]#

Bases: RiemannianMetric

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

Parameters:: power_affine (int) – Power transformation of the classical SPD metric. Optional, default: 1.

References

[TP2019]

Thanwerdas, Pennec. “Is affine-invariance well defined on SPD matrices? A principled continuum of metrics” Proc. of GSI, 2019. https://arxiv.org/abs/1906.01349

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 symmetric 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=None)[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.

\[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 SPD 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 SPD 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.spd_matrices.SPDBuresWassersteinMetric(space, signature=None)[source]#

Bases: RiemannianMetric

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

References

[BJL2017]

Bhatia, Jain, Lim. “On the Bures-Wasserstein distance between positive definite matrices” Elsevier, Expositiones Mathematicae, vol. 37(2), 165-191, 2017. https://arxiv.org/pdf/1712.01504.pdf

[MMP2018]

Malago, Montrucchio, Pistone. “Wasserstein-Riemannian geometry of Gaussian densities” Information Geometry, vol. 1, 137-179, 2018. https://arxiv.org/pdf/1801.09269.pdf

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.

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).

References

[TP2021] (1,2)

Yann Thanwerdas, Xavier Pennec. O(n)-invariant Riemannian metrics on SPD matrices. 2021. ⟨hal-03338601v2⟩

See also

Integration

squared_dist(point_a, point_b)[source]#

Compute the Bures-Wasserstein 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:

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

Notes

Use of abs in the output prevents nan when calling sqrt in very small negative outputs (e.g. -1e-16).

class geomstats.geometry.spd_matrices.SPDEuclideanMetric(space, metric_matrix=None, signature=None)[source]#

Bases: MatricesMetric

Class for the Euclidean metric on the SPD manifold.

static exp_domain(tangent_vec, base_point)[source]#

Compute the domain of the Euclidean exponential map.

Compute the real interval of time where the Euclidean geodesic starting at point base_point in direction tangent_vec is defined.

Parameters:

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

Returns:

exp_domain (array-like, shape=[…, 2]) – Interval of time where the geodesic is defined.

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.

class geomstats.geometry.spd_matrices.SPDLogEuclideanMetric(space, image_space=None)[source]#

Bases: PullbackDiffeoMetric

Class for the Log-Euclidean metric on the SPD manifold.

class geomstats.geometry.spd_matrices.SPDMatrices(n, equip=True)[source]#

Bases: VectorSpaceOpenSet

Class for the manifold of symmetric positive definite (SPD) matrices.

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

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

Check if a matrix is symmetric with positive eigenvalues.

Parameters:

mat (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 is an SPD matrix.

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

projection(point)[source]#

Project a matrix to the space of SPD matrices.

First the symmetric part of point is computed, then the eigenvalues are floored to gs.atol.

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

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

Sample in SPD(n) from the log-uniform distribution.

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.

Returns:

samples (array-like, shape=[…, n, n]) – Points sampled in SPD(n).

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

Sample on the tangent space of SPD(n) from the uniform distribution.

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
base_point (array-like, shape=[…, n, n]) – Base point of the tangent space.

Returns:

samples (array-like, shape=[…, n, n]) – Points sampled in the tangent space at base_point.

class geomstats.geometry.spd_matrices.SPDPowerMetric(space, image_space)[source]#

Bases: PullbackDiffeoMetric

Pullback metric induced by the power diffeomorphism.

Given an equipped image space, the pullback metric is given by

\[g_{\Sigma}^{(p)}(X, X)= \frac{1}{p^2} g_{\Sigma^p}\left(d_{\Sigma} \operatorname{pow}_p(X), d_{\Sigma} \operatorname{pow}_p(X)\right)\]

The image space must be equipped with a ScalarProductMetric. The scale \(s\) relates with power \(p\) by

\[s = 1 / power^2\]

Check section 5.3 of [T2022] for more details.

References

[T2022]

Thanwerdas, Y. (2022) Riemannian and stratified geometries of covariance and correlation matrices. Theses. Université Côte d’Azur. Available at: https://hal.archives-ouvertes.fr/tel-03698752 (Accessed: 29 September 2022).

class geomstats.geometry.spd_matrices.SymMatrixLog[source]#

Bases: Diffeo

Matrix logarithm diffeomorphism.

A diffeomorphism from the space of symmetric positive-definite matrices to the space of symmetric matrices.

classmethod diffeomorphism(base_point)[source]#

Compute the matrix log for a symmetric matrix.

Parameters:: base_point (array_like, shape=[…, n, n]) – Symmetric matrix.
Returns:: log (array_like, shape=[…, n, n]) – Matrix logarithm of base_point.

classmethod inverse_diffeomorphism(image_point)[source]#

Compute the matrix exponential for a symmetric matrix.

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

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

Compute the differential of the matrix exponential.

Computes the differential of the matrix exponential on SPD matrices at base_point applied to tangent_vec.

Parameters:

image_tangent_vec (array_like, shape=[…, n, n]) – Image tangent vector at image point.
image_point (array_like, shape=[…, n, n]) – Image point.
base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

differential_exp (array-like, shape=[…, n, n]) – Differential of the matrix exponential.

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

Compute the differential of the matrix logarithm.

Compute the differential of the matrix logarithm on SPD matrices at base_point applied to tangent_vec.

Parameters:

tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.
base_point (array_like, shape=[…, n, n]) – Base point.
image_point (array_like, shape=[…, n, n]) – Image base point.

Returns:

differential_log (array-like, shape=[…, n, n]) – Differential of the matrix logarithm.

geomstats.geometry.spd_matrices.logmh(mat)[source]#: Compute the matrix log for a Hermitian matrix.

geomstats.geometry.special_euclidean module#

The special Euclidean group SE(n).

i.e. the Lie group of rigid transformations in n dimensions.

Lead authors: Nicolas Guigui and Nina Miolane.

class geomstats.geometry.special_euclidean.SpecialEuclidean(n, point_type='matrix', epsilon=0.0, equip=True)[source]#

Bases: object

Class for the special Euclidean groups.

Parameters:

n (int) – Integer representing the shapes of the matrices : n x n.
point_type (str, {'vector', 'matrix'}) – Representation of the elements of the group. Optional, default: ‘matrix’,
epsilon (float) – Precision used for calculations involving potential divison by 0 in rotations. Optional, default: 0.

class geomstats.geometry.special_euclidean.SpecialEuclideanMatricesCanonicalLeftMetric(space)[source]#

Bases: _InvariantMetricMatrix

Class for the canonical left-invariant metric on SE(n).

The canonical left-invariant metric is defined by endowing the tangent space at the identity with the Frobenius inned-product, and to define the metric at any point by left-translation. This results in a direct product metric between rotations and translations, whose geodesics are therefore easily computable with the matrix exponential and straight lines.

Parameters:: space (SpecialEuclidean) – Instance of the class SpecialEuclidean with point_type=’matrix’.

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

Exponential map associated to the cannonical metric.

Exponential map at base_point of tangent_vec. The geodesics of this metric correspond to a direct product metric between rotation and translation: the translation part is a straight line, while the rotation part has constant angular velocity (which corresponds to one- parameter subgroups of the rotation group).

Parameters:

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

Returns:

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

See also

examples.plot_geodesics_se2

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:

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 does not depend on the base point. If the rotation part is null, then the radius is infinite, otherwise it is the same as the special orthonormal group.

Parameters:: base_point (array-like, shape=[…, n + 1, n + 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 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.

log(point, base_point=None)[source]#

Compute logarithm map associated to the canonical metric.

Log map at base_point of point. The geodesics of this metric correspond to a direct product metric between rotation and translation: the translation part is a straight line, while the rotation part has constant angular velocity (which corresponds to one- parameter subgroups of the rotation group).

Parameters:

point (array-like, shape=[…, n + 1, n + 1]) – Point on the manifold.
base_point (array-like, shape=[…, n + 1, n + 1]) – Point on the manifold.

Returns:

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

References

[Zefran98]

Zefran, M., V. Kumar, and C.B. Croke. “On the Generation of Smooth Three-Dimensional Rigid Body Motions.” IEEE Transactions on Robotics and Automation 14, no. 4 (August 1998): 576–89. https://doi.org/10.1109/70.704225.

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

Compute the parallel transport of a tangent vector.

Closed-form solution for 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)\). As the special Euclidean group endowed with its canonical left-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 + 1, n + 1]) – Tangent vector at base point to be transported.
base_point (array-like, shape=[…, n + 1, n + 1]) – Point on the hypersphere.
direction (array-like, shape=[…, n + 1, n + 1]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None
end_point (array-like, shape=[…, n + 1, n + 1]) – Point on the Grassmann manifold to transport to. Unused if tangent_vec_b is given. Optional, default: None

Returns:

transported_tangent_vec (array-like, shape=[…, n + 1, n + 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.

class geomstats.geometry.special_euclidean.SpecialEuclideanMatricesLieAlgebra(n, equip=True)[source]#

Bases: MatrixLieAlgebra

Lie Algebra of the special Euclidean group.

This is the tangent space at the identity. It is identified with the \(n + 1 \times n + 1\) block matrices of the form:

\[((A, t), (0, 0))\]

where A is an \(n \times n\) skew-symmetric matrix, \(t\) is an n-dimensional vector.

Parameters:: n (int) – Integer dimension of the underlying Euclidean space. Matrices will be of size: (n+1) x (n+1).

basis_representation(matrix_representation)[source]#

Calculate the coefficients of given matrix in the basis.

Compute a 1d-array that corresponds to the input matrix in the basis representation.

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

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

Evaluate if the rotation part of point is a skew-symmetric matrix.

Parameters:

point (array-like, shape=[…, n + 1, n + 1]) – Square matrix to check.
atol (float) – Tolerance for the equality evaluation. Optional, default: backend atol.

Returns:

belongs (array-like, shape=[…,]) – Boolean evaluating if rotation part of matrix is skew symmetric.

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

projection(mat)[source]#

Project a matrix to the Lie Algebra.

Compute the skew-symmetric projection of the rotation part of matrix.

Parameters:: mat (array-like, shape=[…, n + 1, n + 1]) – Matrix.
Returns:: projected (array-like, shape=[…, n + 1, n + 1]) – Matrix belonging to Lie Algebra.

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

Sample in the lie algebra 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 + 1, n + 1]) – Sample.

geomstats.geometry.special_euclidean.homogeneous_representation(rotation, translation, constant=1.0)[source]#

Embed rotation, translation couples into n+1 square matrices.

Construct a block matrix of size \(n + 1 \times n + 1\) of the form

\[\begin{split}\begin{pmatrix} R & t \\ 0 & c \end{pmatrix}\end{split}\]

where \(R\) is a square matrix, \(t\) a vector of size \(n\), and \(c\) a constant (either 0 or 1 should be used).

Parameters:

rotation (array-like, shape=[…, n, n]) – Square Matrix.
translation (array-like, shape=[…, n]) – Vector.
constant (float or array-like of shape […]) – Constant to use at the last line and column of the square matrix. Optional, default: 1.

Returns:

mat (array-like, shape=[…, n + 1, n + 1]) – Square Matrix of size n + 1. It can represent an element of the special euclidean group or its Lie algebra.

geomstats.geometry.special_orthogonal module#

Exposes the SpecialOrthogonal group class.

Lead authors: Nicolas Guigui and Nina Miolane.

class geomstats.geometry.special_orthogonal.SpecialOrthogonal(n, point_type='matrix', epsilon=0.0, equip=True)[source]#

Bases: object

Class for the special orthogonal groups.

Parameters:

n (int) – Integer representing the shapes of the matrices : n x n.
point_type (str, {'vector', 'matrix'}) – Representation of the elements of the group.
epsilon (float, optional) – precision to use for calculations involving potential divison by 0 in rotations default: 0

geomstats.geometry.stiefel module#

Stiefel manifold St(n,p).

A set of all orthonormal p-frames in n-dimensional space, where p <= n.

Lead author: Oleg Kachan.

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

Bases: LevelSet

Class for Stiefel manifolds St(n,p).

A set of all orthonormal p-frames in n-dimensional space, where p <= n.

Parameters:

n (int) – Dimension of the ambient vector space.
p (int) – Number of basis vectors in the orthonormal frame.

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

projection(point)[source]#

Project a close enough matrix to the Stiefel manifold.

A singular value decomposition is used, and all singular values are set to 1 [Absil]

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

References

[Absil]

Absil, Pierre-Antoine, and Jérôme Malick. “Projection-like Retractions on Matrix Manifolds.” SIAM Journal on Optimization 22, no. 1 (January 2012): 135–58. https://doi.org/10.1137/100802529.

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

Sample on St(n,p) from the uniform distribution.

If \(Z(p,n) \sim N(0,1)\), then \(St(n,p) \sim U\), according to Haar measure: \(St(n,p) := Z(Z^TZ)^{-1/2}\).

Parameters:

n_samples (int) – Number of samples. Optional, default: 1.
bound (float) – Unused here.

Returns:

samples (array-like, shape=[…, n, p]) – Samples on the Stiefel manifold.

random_uniform(n_samples=1)[source]#

Sample on St(n,p) from the uniform distribution.

If \(Z(p,n) \sim N(0,1)\), then \(St(n,p) \sim U\), according to Haar measure: \(St(n,p) := Z(Z^TZ)^{-1/2}\).

Parameters:: n_samples (int) – Number of samples. Optional, default: 1.
Returns:: samples (array-like, shape=[…, n, p]) – Samples on the Stiefel manifold.

submersion(point)[source]#

Submersion that defines the manifold.

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

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])

static to_grassmannian(point)[source]#

Project a point of St(n, p) to Gr(n, p).

If \(U \in St(n, p)\) is an orthonormal frame, return the orthogonal projector \(P = U U^T\) onto the subspace of \(\mathbb{R}^n\) spanned by \(U\).

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

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Inspired by the method of Pymanopt.

Parameters:

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

Returns:

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

class geomstats.geometry.stiefel.StiefelCanonicalMetric(space)[source]#

Bases: RiemannianMetric

Class that defines the canonical metric for Stiefel manifolds.

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, n, p]) – Tangent vector at a base point.
base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

Returns:

exp (array-like, shape=[…, n, p]) – Point in the Stiefel manifold equal to the Riemannian exponential of tangent_vec at the base point.

injectivity_radius(base_point=None)[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 the exact injectivity radius is not known, and we use here a lower bound given by [Rentmeesters2015].

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

References

[Rentmeesters2015]

Rentmeesters, Quentin. “Algorithms for Data Fitting on Some Common Homogeneous Spaces.” UCL - Université Catholique de Louvain, 2013. https://dial.uclouvain.be/pr/boreal/object/boreal:132587.

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

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

Canonical inner-product on the tangent space at base_point, which is different from the inner-product induced by the embedding (see [RLSMRZ2017]).

\[\langle\Delta, \tilde{\Delta}\rangle_{U}=\operatorname{tr} \left(\Delta^{T}\left(I-\frac{1}{2} U U^{T}\right) \tilde{\Delta}\right)\]

Parameters:

tangent_vec_a (array-like, shape=[…, n, p]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, n, p]) – Second tangent vector at base point.
base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

Returns:

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

References

[RLSMRZ2017]

R Zimmermann. A matrix-algebraic algorithm for the Riemannian logarithm on the Stiefel manifold under the canonical metric. SIAM Journal on Matrix Analysis and Applications 38 (2), 322-342, 2017. https://epubs.siam.org/doi/pdf/10.1137/16M1074485

lifting(point, base_point)[source]#

Compute the lifting of a point.

This computation is based on the QR-decomposion.

e.g. \(P_x^{-1}(Q) = QR - X\).

Parameters:

point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.
base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

Returns:

log (array-like, shape=[…, dim + 1]) – Tangent vector at the base point equal to the lifting of point at the base point.

static retraction(tangent_vec, base_point)[source]#

Compute the retraction of a tangent vector.

This computation is based on the QR-decomposition.

e.g. \(P_x(V) = qf(X + V)\).

Parameters:

tangent_vec (array-like, shape=[…, n, p]) – Tangent vector at a base point.
base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

Returns:

exp (array-like, shape=[…, n, p]) – Point in the Stiefel manifold equal to the retraction of tangent_vec at the base point.

geomstats.geometry.sub_riemannian_metric module#

Implementation of sub-Riemannian geometry.

Lead author: Morten Pedersen.

class geomstats.geometry.sub_riemannian_metric.SubRiemannianMetric(space, cometric_matrix=None, frame=None)[source]#

Bases: object

Class for Sub-Riemannian metrics.

This implementation assumes a bracket-generating distribution of constant dimension.

Only one of the arguments ‘cometric_matrix’ and ‘frame’ can be different from None. If the frame is supplied, it is assumed orthonormal.

Parameters:

space (Manifold object)
cometric_matrix (callable) – Optional, default: ‘None’

The cometric matrix as a function of a point.

You should pass :
base_point : array-like, shape=[…, dim]

It returns:
_ : array-like, shape=[…, dim, dim]
frame (callable) – Optional, default: ‘None’

Matrix representing the frame spanning the distribution, as a function of a point.

You should pass:
point : array-like, shape=[…, dim]

It returns

_array-like, shape=[…, dim, dist_dim]
Frame field matrix. Each column is a vector field of the frame spanning the distribution.

exp(cotangent_vec, base_point, n_steps=20)[source]#

Exponential map associated to the cometric.

Exponential map at base_point of cotangent_vec computed by integration of the Hamiltonian equation (initial value problem), using the cometric. In the Riemannian case this yields the exponential associated to the Levi-Civita connection of the metric (the inverse of the cometric).

Parameters:

cotangent_vec (array-like, shape=[…, dim]) – Tangent vector at the base point.
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.

Returns:

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

geodesic(initial_point, initial_cotangent_vec, n_steps=20)[source]#

Generate parameterized function for the normal geodesic curve.

Normal geodesic curve defined by an initial point and an initial cotangent vector.

Parameters:

initial_point (array-like, shape=[…, dim]) – Point on the manifold, initial point of the geodesic.
initial_cotangent_vec (array-like, shape=[…, dim]) – Cotangent vector at base point, the initial speed of the geodesics.

Returns:

path (callable) – Time parameterized normal 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.

hamiltonian(state)[source]#

Compute the hamiltonian energy associated to the cometric.

The Hamiltonian at state \((q, p)\) is defined by

\[H(q, p) = \frac{1}{2} <p, p>_q\]

where \(<\cdot, \cdot>_q\) is the cometric at \(q\).

Parameters:: state (array-like, shape=[[…, dim], […, dim]]) – The first array in ‘state’ contains positions, the second contains covectors (momentums).
Returns:: energy (float) – Hamiltonian energy at state.

inner_coproduct(cotangent_vec_a, cotangent_vec_b, base_point)[source]#

Compute inner coproduct between two cotangent vectors at base point.

This is the inner product associated to the cometric matrix.

Parameters:

cotangent_vec_a (array-like, shape=[…, dim]) – Cotangent vector at base_point.
cotangent_vec_b (array-like, shape=[…, dim]) – Cotangent vector at base_point.
base_point (array-like, shape=[…, dim]) – Point on the manifold.

Returns:

inner_coproduct (float) – Inner coproduct between the two cotangent vectors.

static iterate(func, n_steps)[source]#

Construct a function which iterates another function n_steps times.

Parameters:

func (callable) – A function which calculates the next step of a sequence to be calculated.
n_steps (int) – The number of times to iterate func.

Returns:

flow (callable) – Given a state, ‘flow’ returns a sequence with n_steps iterations of func.

sr_sharp(base_point, cotangent_vec)[source]#

Compute sub-Riemannian sharp map.

This is the sub-Riemannian sharp map, mapping a covector at base_point to a tangent vector in the distribution subspace at base_point. For an orthonormal frame (F_i)_{i=1..dist_dim}, the sharp map is given by

\[\sharp(q, p) = \sum_i^{dist_dim} p(F_i(q)) * F_i(q)\]

Parameters:

base_point (array-like, shape=[…, dim]) – Point on the manifold.
cotangent_vec (array-like, shape=[…, dim]) – Cotangent vector at base_point.

Returns:

sr_sharp (array-like, shape=[…, dim]) – sub-Riemannian sharp of ‘cotangent_vec’ at ‘base_point’

symp_euler(hamiltonian, step_size)[source]#

Compute a function which calculates a step of symplectic euler integration.

Parameters:

hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.
step_size (float) – Step size of the symplectic euler step

Returns:

step (callable) – Given a state, ‘step’ returns the next symplectic euler step

symp_flow(hamiltonian, end_time=1.0, n_steps=20)[source]#

Compute the symplectic flow of the hamiltonian.

Parameters:

hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.
end_time (float) – The last time point until which to calculate the flow.
n_steps (int) – Number of integration steps.

Returns:

_ (array-like, shape[,n_steps]) – Given a state, ‘symp_flow’ returns a sequence with n_steps iterations of func.

static symp_grad(hamiltonian)[source]#

Compute the symplectic gradient of the Hamiltonian.

Parameters:: hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.
Returns:: vector (array-like, shape=[, 2*dim]) – The symplectic gradient of the Hamiltonian.

geomstats.geometry.symmetric_matrices module#

The vector space of symmetric matrices.

Lead author: Yann Thanwerdas.

class geomstats.geometry.symmetric_matrices.ConstantValueRowSumsDiffeo(value=0.0)[source]#

Bases: Diffeo

A diffeomorphism from the constant-value-row-sum matrices to symmetric matrices.

A particular case is the diffeomorphism between the space of null-row-sum symmetric n-matrices and the space of symmetric (n-1)-matrices.

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

diffeomorphism(base_point)[source]#

Diffeomorphism at base point.

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

inverse_diffeomorphism(image_point)[source]#

Inverse diffeomorphism at image point.

\(f^{-1}: N \rightarrow M\)

Parameters:: image_point (array-like, shape=[…, n-1, n-1]) – 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=[…, *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.

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.

class geomstats.geometry.symmetric_matrices.HollowMatricesPermutationInvariantMetric(space, alpha=None, beta=None, gamma=1.0)[source]#

Bases: EuclideanMetric

A permutation-invariant metric on the space of hollow matrices.

It is flat Riemannian metric invariant by the congruence action of permutation matrices defined over a matrix vector space.

Its associated quadratic form is:

\[q(X)=\alpha \operatorname{tr}\left(X^2\right) +\beta \operatorname{Sum}\left(X^2\right) +\gamma \operatorname{Sum}(X)^2\]

Parameters:

space (Manifold)
alpha (float) – Scalar multiplying first term of quadratic form.
beta (float) – Scalar multiplying second term of quadratic form.
gamma (float) – Scalar multiplying third term of quadratic form.
Check out chapter 8 of [T2022]_ for more details.

References

[T2022]

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

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=[…, 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. Optional, default: None.

Returns:

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

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=[…, n, n]) – Vector.
base_point (array-like, shape=[…, n, n]) – Base point. Optional, default: None.

Returns:

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

class geomstats.geometry.symmetric_matrices.NullRowSumsPermutationInvariantMetric(space, alpha=None, delta=None, zeta=1.0)[source]#

Bases: EuclideanMetric

A permutation-invariant metric on the space of null-row-sums symmetric matrices.

It is flat Riemannian metric invariant by the congruence action of permutation matrices defined over a matrix vector space.

Its associated quadratic form is:

\[q(Y)=\alpha \operatorname{tr}\left(Y^2\right) +\delta \operatorname{tr}\left(\operatorname{Diag}(Y)^2\right) +\zeta \operatorname{tr}(Y)^2\]

Check out chapter 8 of [T2022] and [T2023] for more details.

Parameters:

space (Manifold)
alpha (float) – Scalar multiplying first term of quadratic form.
delta (float) – Scalar multiplying second term of quadratic form.
zeta (float) – Scalar multiplying third term of quadratic form.

References

[T2022]

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

[T2023]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices,” November 2023. https://hal.science/hal-03878729.

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=[…, 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. Optional, default: None.

Returns:

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

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=[…, n, n]) – Vector.
base_point (array-like, shape=[…, n, n]) – Base point. Optional, default: None.

Returns:

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

class geomstats.geometry.symmetric_matrices.NullRowSumsSymmetricMatrices(n, equip=True)[source]#

Bases: LevelSet, DiffeomorphicMatrixVectorSpace

Space of null-row-sums symmetric matrices.

Set of symmetric matrices with null row sums:

\[\operatorname{Row_0}(n) = \{S \in \operatorname{Sym}(n) \mid S \mathbb{1}=0 \}\]

Check out chapter 8 of [T2022] and [T2023] for more details.

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

References

[T2022]

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

[T2023]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices,” November 2023. https://hal.science/hal-03878729.

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

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])

class geomstats.geometry.symmetric_matrices.SymmetricHollowMatrices(n, equip=True)[source]#

Bases: LevelSet, MatrixVectorSpace

Space of symmetric hollow matrices.

Set of symmetric matrices with null diagonal:

\[\operatorname{Hol}(n) = \{X \in \operatorname{Sym}(n) \mid \operatorname{Diag}(X)=0\}\]

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

References

[T2022]

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

static basis_representation(matrix_representation)[source]#

Convert a hollow symmetric matrix into a vector.

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

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

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.

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])

class geomstats.geometry.symmetric_matrices.SymmetricMatrices(n, equip=True)[source]#

Bases: MatrixVectorSpace

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

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

static basis_representation(matrix_representation)[source]#

Convert a symmetric matrix into a vector.

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

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

Evaluate if a matrix is symmetric.

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.

static matrix_representation(basis_representation)[source]#

Convert a vector into a symmetric matrix.

Parameters:: basis_representation (array-like, shape=[…, n(n+1)/2]) – Vector.
Returns:: matrix_representation (array-like, shape=[…, n, n]) – Symmetric matrix.

projection(point)[source]#

Make a matrix symmetric, by averaging with its transpose.

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

Module contents#

The Geometry Package.