geomstats.geometry package#

Subpackages#

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.

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

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

Bases: Diffeo

Diffeomorphism through autodiff.

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

inverse(image_point)[source]#

Inverse diffeomorphism at image point.

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

Inverse tangent diffeomorphism at image point.

tangent(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 inverse(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(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(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(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(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.)

inverse(image_point)[source]#

Inverse diffeomorphism at image point.

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

Tangent diffeomorphism at image point.

tangent(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(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(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.DiscreteCurves(ambient_dim=2, k_sampling_points=10, starting_at_origin=True, equip=True)[source]#

Bases: object

Space of discrete curves.

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]

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.

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

Bases: FiberBundle

Principal bundle of curves modulo reparametrizations with an elastic metric.

The space of parameterized curves is the total space of a principal bundle where the group action is given by reparametrization 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.RotationBundle(total_space, aligner=None)[source]#

Bases: FiberBundle

Principal bundle of curves modulo rotations with an elastic metric.

This is the fiber bundle where the total space is the space of parameterized curves equipped with an elastic 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.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.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.

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

new(equip=True)[source]#

Create manifold with same parameters.

Parameters:

equip (bool) – If True, equip space with default metric.

Returns:

manifold (DiscreteSurfaces)

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]

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.

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.

class geomstats.geometry.discrete_surfaces.L2SurfacesMetric(space)[source]#

Bases: NFoldMetric

L2 metric on the space of discrete surfaces.

Notes

Adds base_manifold (manifold that is repeated n_copies times) and n_copies to space as attribute if it does not have them as their expected by NFoldMetric.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[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=[…, 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.

class geomstats.geometry.discrete_surfaces.RelaxedPathStraightening(total_space, n_nodes=3, lambda_=1.0, discrepancy_loss=None, path_energy=None, optimizer=None, initialization=None)[source]#

Bases: PathBasedLogSolver, AlignerAlgorithm

Class to solve the geodesic boundary value problem with path-straightening.

Parameters:
  • space (Manifold) – Equipped manifold.

  • n_nodes (int) – Number of path discretization points.

  • lambda_ (float) – Discrepancy loss weight.

  • discrepancy_loss (callable) – A generic discrepancy term. Receives point and outputs a callable which receives another point and outputs a scalar measuring discrepancy between point and another point. Scalar sums to energy of a path.

  • path_energy (callable) – Method to compute Riemannian path energy.

  • optimizer (ScipyMinimize) – An optimizer to solve path energy minimization problem.

  • initialization (callable or array-like, shape=[n_nodes - 2, n_vertices, 3]) – A method to get initial guess for optimization or an initial path.

References

[HSKCB2022]

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

align(point, base_point)[source]#

Align point to base point.

Parameters:
  • point (Surface or list[Surface] or array-like, shape=[…, n_vertices, 3])

  • base_point (array-like, shape=[…, n_vertices, 3])

Returns:

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

discrete_geodesic_bvp(point, base_point)[source]#

Solve boundary value problem (BVP).

Given an initial point and an end point, solve the geodesic equation via minimizing the Riemannian path energy and a relaxation term.

Parameters:
  • point (Surface or list[Surface] or array-like, shape=[…, n_vertices, 3])

  • base_point (Surface or list[Surface] or array-like, shape=[…, n_vertices, 3])

Returns:

discr_geod_path (array-like, shape=[…, n_times, n_nodes, n_vertices, 3]) – Discrete geodesic.

class geomstats.geometry.discrete_surfaces.ReparametrizationBundle(total_space, aligner=None)[source]#

Bases: FiberBundle

Principal bundle of surfaces module reparametrizations.

Parameters:
  • total_space (DiscreteSurfaces) – Surfaces equipped with a reparametrization-invariant metric.

  • aligner (AlignerAlgorithm) – If None, instantiates default RelaxedPathStraightening.

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:

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.

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 (see e.g. [SK2016] for more details).

This alignment results in an approximate quotient of the product group action.

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

[SK2016]

Anuj Srivastava, and Eric P. Klassen. Functional and Shape Data Analysis. Springer, 2016.

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:

  1. the vertical projection

  2. the horizontal lift of the tangent submersion

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.EuclideanCholeskyDiffeo[source]#

Bases: Diffeo

Euclidean-Cholesky diffeomorphism from Cor+ to LT^1.

A diffeomorphism between full-rank correlation matrices \(\mathrm{Cor}(n)\) and lower triangular matrices with unit diagonal \(\mathrm{LT}^1(n)\).

Check out chapter 7 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.

inverse(image_point)[source]#

Inverse diffeomorphism at image point.

\[\begin{split}\begin{aligned} \Phi(\Gamma) &= \operatorname{Diag}\left(\phi(\Gamma)\right)^{-1 / 2} \phi(\Gamma) \operatorname{Diag}\left(\phi(\Gamma)\right)^{-1 / 2} \\ &= \operatorname{Cor} \circ \phi(\Gamma) \end{aligned}\end{split}\]
Parameters:

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

Returns:

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

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

Inverse tangent diffeomorphism at image point.

\[d_{\Gamma} \Phi (Y)= d_{\phi(\Gamma)} \operatorname{Cor} \circ d_{\Gamma} \phi(Y)\]
Parameters:
  • image_tangent_vec (array-like, shape=[…, n, n]) – Image tangent vector at image point.

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

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

Returns:

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

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

Tangent diffeomorphism at base point.

\[d_C \Theta (X)=\Theta(C) \operatorname{Low}_s\left(L^{-1} X L^{-\top}\right) -\frac{1}{2} \operatorname{Diag}\left(L^{-1} X L^{-\top}\right) \Theta(C)\]
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.EuclideanCholeskyMetric(space)[source]#

Bases: PullbackDiffeoMetric

Pullback metric via a diffeomorphism.

Diffeormorphism is between full-rank correlation matrices and lower triangular matrices with unit diagonal endowed with a Euclidean metric.

For more details, check section 7.4.2 of [T2022].

Parameters:

space (FullRankCorrelationMatrices) – Manifold.

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.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.LogEuclideanCholeskyDiffeo[source]#

Bases: ComposedDiffeo

log-Euclidean-Cholesky diffeomorphism from Cor+ to LT^0.

A diffeomorphism between full-rank correlation matrices \(\mathrm{Cor}(n)\) and strictly lower triangular matrices \(\mathrm{LT}^0(n)\).

Check out chapter 7 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.

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

Bases: PullbackDiffeoMetric

Pullback metric via a diffeomorphism.

Diffeormorphism is between full-rank correlation matrices and strictly lower triangular matrices endowed with a Euclidean metric.

For more details, check section 7.4.3 of [T2022].

Parameters:

space (FullRankCorrelationMatrices) – Manifold.

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

[T2024]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices.” SIAM Journal on Matrix Analysis and Applications, 2024, 930–53. https://doi.org/10.1137/22M1538144.

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 [T2024] for more details.

References

[T2024]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices.” SIAM Journal on Matrix Analysis and Applications, 2024, 930–53. https://doi.org/10.1137/22M1538144.

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

inverse(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(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(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.SPDScalingFinder(root_finder=None)[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 ([T2024], [MO1968], [JR2009]).

It finds the roots of the gradient of the strictly convex map

\[F(D) = \frac{1}{2} \mathbb{1}^{\top} D^{\top} \Sigma D \mathbb{1}-\operatorname{tr}(\log (D))\]

For details, check out [T2024]’s section 3.5.

To ensure convergence, it is better to use a damped Newton method, which leverages function being standard self-concordant and strictly convex (check out section 5.1.5 of [N2018]).

Parameters:

root_finder (RootFinder)

References

[T2024]

Thanwerdas, Yann. “Permutation-Invariant Log-Euclidean Geometries on Full-Rank Correlation Matrices.” SIAM Journal on Matrix Analysis and Applications, 2024, 930–53. https://doi.org/10.1137/22M1538144.

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

[N2018]

Yurii Nesterov. Lectures on Convex Optimization. Springer, 2018.

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.

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.

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

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

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

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]

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.

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]

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

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.

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

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.

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

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

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.

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.

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.

class geomstats.geometry.lower_triangular_matrices.StrictlyLowerTriangularMatrices(n, equip=True)[source]#

Bases: LevelSet, MatrixVectorSpace

Strictly lower triangular matrices.

Set of lower triangular matrices with null diagonal:

\[\operatorname{LT}^0(n)=\{L \in \operatorname{LT}(n) \mid \operatorname{Diag}(L)=0\}\]
Parameters:
  • n (int) – Integer representing the shapes of the matrices: n x n.

  • equip (bool) – If True, equip space with default metric.

static basis_representation(matrix_representation)[source]#

Compute the coefficients of matrices in the given basis.

Parameters:

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

Returns:

vec (array-like, shape=[…, dim]) – Vector.

static default_metric()[source]#

Metric to equip the space with if equip is True.

projection(point)[source]#

Project a point to the manifold.

Parameters:

point (array-like, shape[…, n, n]) – Point to project.

Returns:

proj_point (array-like, shape[…, n, n]) – 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])

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

Register quotient structure.

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)

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

inverse(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.matrices.matrix_matrix_transpose(point)[source]#

Matrix multiplication with transpose.

\[f(A) = A A^{\top}\]
Parameters:

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

Returns:

mat (array-like, shape=[n, n]) – Matrix resulting from operation.

geomstats.geometry.matrices.tangent_matrix_matrix_transpose(tangent_vec, base_point)[source]#

Tangent matrix multiplication with transpose.

\[d_A f (X) = X A^\top + A X^\top\]
Parameters:
  • tangent_vec (array-like, shape=[…, n, n]) – Tangent vector.

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

Returns:

image_tangent_vec (array-like, shape=[n, n]) – Matrix resulting from operation.

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

A diffeomorphism between the open hemisphere and the hyperboloid.

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

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

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]) – 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.LowerMatrixLog[source]#

Bases: Diffeo

Matrix logarithm diffeomorphism.

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

static inverse(image_point)[source]#

Compute the matrix exponential.

\[\exp(L) = \sum_{k=0}^{n-1} \frac{1}{k!} L^k\]
Parameters:

image_point (array_like, shape=[…, n, n]) – Symmetric matrix.

Returns:

exponential (array_like, shape=[…, n, n]) – Exponential of image_point.

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

Inverse tangent diffeomorphism at image point.

\[d_L \exp(X) = \sum_{k=1}^{n-1}\left(\frac{1}{k!} \sum_{j=1}^k\left(L^{j-1} X L^{k-j}\right)\right)\]
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.

classmethod tangent(tangent_vec, base_point=None, image_point=