# Geometry#

## Manifolds#

### Manifold#

Manifold module.

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

class geomstats.geometry.manifold.Manifold(dim, shape, metric=None, default_coords_type='intrinsic', **kwargs)[source]#

Class for manifolds.

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

• shape (tuple of int) – Shape of one element of the manifold. Optional, default : None.

• metric (RiemannianMetric) – Metric object to use on the manifold.

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

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

property default_point_type#

Point type.

vector or matrix.

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

property metric#

Riemannian Metric associated to the Manifold.

abstract 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=[…, {dim, [n, n]}]) – 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=[…, dim]) – Point.

Returns:

tangent_vec (array-like, shape=[…, dim]) – 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=[…, dim]) – Regularized point.

abstract to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:
• vector (array-like, shape=[…, dim]) – Vector.

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

Returns:

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

### Product Manifold#

Product of manifolds.

class geomstats.geometry.product_manifold.NFoldManifold(base_manifold, n_copies, metric=None, default_coords_type='intrinsic', **kwargs)[source]#

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.

• metric (RiemannianMetric) – Metric object to use on the manifold.

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

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

Test if a point belongs to the manifold.

Parameters:
• point (array-like, shape=[…, n_copies, *base_shape]) – Point.

• atol (float,) – Tolerance.

Returns:

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

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

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.product_manifold.ProductManifold(manifolds, metrics=None, default_point_type='vector', n_jobs=1, **kwargs)[source]#

Class for a product of manifolds M_1 x … x M_n.

In contrast to the classes NFoldManifold, Landmarks, or DiscretizedCurves, the manifolds M_1, …, M_n need not be the same, nor of same dimension, but the list of manifolds needs to be provided.

By default, a point is represented by an array of shape: […, dim_1 + … + dim_n_manifolds] where n_manifolds is the number of manifolds in the product. This type of representation is called ‘vector’.

Alternatively, a point can be represented by an array of shape: […, n_manifolds, dim] if the n_manifolds have same dimension dim. This type of representation is called matrix.

Parameters:
• manifolds (list) – List of manifolds in the product.

• n_jobs (int) – Number of jobs for parallel computing. Optional, default: 1.

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

Test if a point belongs to the manifold.

Parameters:
• point (array-like, shape=[…, {dim, [n_manifolds, dim_each]}]) – Point.

• atol (float,) – Tolerance.

Returns:

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

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=[…, 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.

projection(point)[source]#

Project a point in product embedding manifold on each manifold.

Parameters:

point (array-like, shape=[…, {dim, [n_manifolds, dim_each]}]) – Point in embedding manifold.

Returns:

projected (array-like, shape=[…, {dim, [n_manifolds, dim_each]}]) – Projected point.

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

Sample in the product space from the uniform distribution.

Parameters:
• n_samples (int, optional) – Number of samples.

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

Returns:

samples (array-like, shape=[…, {dim, [n_manifolds, dim_each]}]) – Points sampled on the hypersphere.

regularize(point)[source]#

Regularize the point into the manifold’s canonical representation.

Parameters:

point (array-like, shape=[…, {dim, [n_manifolds, dim_each]}]) – Point to be regularized.

Returns:

regularized_point (array-like,) – shape=[…, {dim, [n_manifolds, dim_each]}] Point in the manifold’s canonical representation.

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

The tangent space of the product manifold is the direct sum of tangent spaces.

Parameters:
• vector (array-like, shape=[…, dim]) – Vector.

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

Returns:

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

### Euclidean Space#

Euclidean space.

class geomstats.geometry.euclidean.Euclidean(dim)[source]#

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.

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.

get_identity()[source]#

Get the identity of the group.

Returns:

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

property identity#

Get the identity of the group.

Returns:

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

class geomstats.geometry.euclidean.EuclideanMetric(dim, shape=None)[source]#

Class for Euclidean metrics.

As a Riemannian metric, the Euclidean metric is:

• flat: the inner-product is independent of the base point;

• positive definite: it has signature (dimension, 0, 0), where dimension is the dimension of the Euclidean space.

Parameters:

dim (int) – Dimension of the Euclidean space.

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

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

The Riemannian exponential is vector addition in the Euclidean space.

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

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

Returns:

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

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

Inner product between two tangent vectors at a base point.

Parameters:
• tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base point.

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

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

Returns:

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

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

Compute log map using a base point and other point.

The Riemannian logarithm is the subtraction in the Euclidean space.

Parameters:
• point (array-like, shape=[…, dim]) – Point.

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

Returns:

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

metric_matrix(base_point=None)[source]#

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

Parameters:

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

Returns:

inner_prod_mat (array-like, shape=[…, dim, dim]) – Inner-product matrix.

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

Compute norm of a vector.

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

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

Parameters:
• vector (array-like, shape=[…, dim]) – Vector.

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

Returns:

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

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

Compute the parallel transport of a tangent vector.

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

Parameters:
• tangent_vec (array-like, shape=[…, dim]) – Tangent vector at base point to be transported.

• base_point (array-like, shape=[…, dim]) – Point on the manifold. Point to transport from. Optional, default: None

• direction (array-like, shape=[…, dim]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None.

• end_point (array-like, shape=[…, dim]) – Point on the manifold. Point to transport to. Optional, default: None.

Returns:

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

### Minkowski Space#

Minkowski space.

class geomstats.geometry.minkowski.Minkowski(dim, **kwargs)[source]#

Class for Minkowski space.

This is the Euclidean space endowed with the inner-product of signature ( dim-1, 1).

Parameters:

dim (int) – Dimension of Minkowski space.

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

Class for the pseudo-Riemannian Minkowski metric.

The metric is flat: the inner product is independent of the base point.

Parameters:

dim (int) – Dimension of the Minkowski space.

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

Compute the Riemannian exponential of tangent_vec at base_point.

The Riemannian exponential is the addition in the Minkowski space.

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

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

Returns:

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

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In the case of the Minkowski space, it does not depend on the base point and is infinite everywhere, because of the flat curvature.

Parameters:

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

Returns:

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

Inner product between two tangent vectors at a base point.

Parameters:
• tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base point.

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

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

Returns:

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

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

Compute the Riemannian logarithm of point at base_point.

The Riemannian logarithm is the subtraction in the Minkowski space.

Parameters:
• point (array-like, shape=[…, dim]) – Point.

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

Returns:

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

metric_matrix(base_point=None)[source]#

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

Parameters:

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

Returns:

inner_prod_mat (array-like, shape=[…, dim, dim]) – Inner-product matrix.

### Hypersphere#

The n-dimensional hypersphere.

The n-dimensional hypersphere embedded in (n+1)-dimensional Euclidean space.

class geomstats.geometry.hypersphere.Hypersphere(dim, default_coords_type='extrinsic')[source]#

Class for the n-dimensional hypersphere.

Class for the n-dimensional hypersphere embedded in the (n+1)-dimensional Euclidean space.

By default, points are parameterized by their extrinsic (n+1)-coordinates. For dimensions 1 and 2, this can be changed with the default_coords_type parameter. For dimensions 1 (the circle), the intrinsic coordinates correspond angles in radians, with 0. mapping to point [1., 0.]. For dimension 2, the intrinsic coordinates are the spherical coordinates from the north pole, i.e. where angles [0., 0.] correspond to point [0., 0., 1.].

Parameters:
• dim (int) – Dimension of the hypersphere.

• default_coords_type (str, {‘extrinsic’, ‘intrinsic’}) – Type of representation for dimensions 1 and 2.

class geomstats.geometry.hypersphere.HypersphereMetric(dim)[source]#

Class for the Hypersphere Metric.

Parameters:

dim (int) – Dimension of the hypersphere.

christoffels(point, coords_type='spherical')[source]#

Compute the Christoffel symbols at a point.

Only implemented in dimension 2 and for spherical coordinates.

Parameters:
• point (array-like, shape=[…, dim]) – Point on hypersphere where the Christoffel symbols are computed.

• coords_type (str, {‘spherical’, ‘intrinsic’, ‘extrinsic’}) – Coordinates in which to express the Christoffel symbols. Optional, default: ‘spherical’.

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 x, z \rangle y - \langle y,z \rangle x$$.

Parameters:
• tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base_point.

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

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

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

Returns:

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

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

Compute the covariant derivative of the curvature.

The derivative of the curvature vanishes since the hypersphere is a constant curvature space.

Parameters:
• tangent_vec_a (array-like, shape=[…, dim]) – Tangent vector at base_point along which the curvature is derived.

• tangent_vec_b (array-like, shape=[…, dim]) – Unused tangent vector at base_point (since curvature derivative vanishes).

• tangent_vec_c (array-like, shape=[…, dim]) – Unused tangent vector at base_point (since curvature derivative vanishes).

• tangent_vec_d (array-like, shape=[…, dim]) – Unused tangent vector at base_point (since curvature derivative vanishes).

• base_point (array-like, shape=[…, dim]) – Unused point on the hypersphere.

Returns:

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

dist(point_a, point_b)[source]#

Compute the geodesic distance between two points.

Parameters:
• point_a (array-like, shape=[…, dim + 1]) – First point on the hypersphere.

• point_b (array-like, shape=[…, dim + 1]) – Second point on the hypersphere.

Returns:

dist (array-like, shape=[…, 1]) – Geodesic distance between the two points.

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

Compute the Riemannian exponential of a tangent vector.

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

• base_point (array-like, shape=[…, dim + 1]) – Point on the hypersphere.

Returns:

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

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:

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

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

Parameters:
• tangent_vec_a (array-like, shape=[…, dim + 1]) – First tangent vector at base point.

• tangent_vec_b (array-like, shape=[…, dim + 1]) – Second tangent vector at base point.

• base_point (array-like, shape=[…, dim + 1], optional) – Point on the hypersphere.

Returns:

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

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

Compute the Riemannian logarithm of a point.

Parameters:
• point (array-like, shape=[…, dim + 1]) – Point on the hypersphere.

• base_point (array-like, shape=[…, dim + 1]) – Point on the hypersphere.

Returns:

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

metric_matrix(base_point=None)[source]#

Metric matrix at the tangent space at a base point.

Parameters:

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

Returns:

mat (array-like, shape=[…, dim + 1, dim + 1]) – Inner-product matrix.

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, **kwargs)[source]#

Squared geodesic distance between two points.

Parameters:
• point_a (array-like, shape=[…, dim]) – Point on the hypersphere.

• point_b (array-like, shape=[…, dim]) – Point on the hypersphere.

Returns:

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

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

Compute the squared norm of a vector.

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

Parameters:
• vector (array-like, shape=[…, dim + 1]) – Vector on the tangent space of the hypersphere at base point.

• base_point (array-like, shape=[…, dim + 1], optional) – Point on the hypersphere.

Returns:

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

### Hyperbolic Space#

Common interface to hyperbolic spaces.

class geomstats.geometry.hyperbolic.Hyperbolic(*args, default_coords_type='extrinsic', **kwargs)[source]#

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. This representation is called extrinsic here.

• the Poincare ball, the open ball of the Euclidean space of dimension dim.

• the Poincare half-space, the open space of points of the Euclidean space of dimension dim, whose last coordinate is positive.

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

• default_coords_type (str, {‘extrinsic’, ‘ball’, ‘half-space’}) – Default coordinates to represent points in hyperbolic space. Optional, default: ‘extrinsic’.

• scale (int) – Scale of the hyperbolic space, defined as the set of points in Minkowski space whose squared norm is equal to -scale. Optional, default: 1.

### Symmetric-Positive-Definite (SPD) Matrices Space#

The manifold of symmetric positive definite (SPD) matrices.

class geomstats.geometry.spd_matrices.SPDMatrices(n, **kwargs)[source]#

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

Parameters:

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

static aux_differential_power(power, tangent_vec, base_point)[source]#

Compute the differential of the matrix power.

Auxiliary function to the functions differential_power and inverse_differential_power.

Parameters:
• power (float) – Power function to differentiate.

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

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

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

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

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

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

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

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

Check if a matrix is symmetric with positive eigenvalues.

Parameters:
• mat (array-like, shape=[…, n, n]) – Matrix to be checked.

• atol (float) – Tolerance. Optional, default: backend atol.

Returns:

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

classmethod cholesky_factor(mat)[source]#

Compute cholesky factor.

Compute cholesky factor for a symmetric positive definite matrix.

Parameters:

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

Returns:

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

classmethod differential_cholesky_factor(tangent_vec, base_point)[source]#

Compute the differential of the cholesky factor map.

Parameters:
• tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point. symmetric matrix.

• base_point (array_like, shape=[…, n, n]) – Base point. spd matrix.

Returns:

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

classmethod differential_exp(tangent_vec, base_point)[source]#

Compute the differential of the matrix exponential.

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

Parameters:
• tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

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

classmethod differential_log(tangent_vec, base_point)[source]#

Compute the differential of the matrix logarithm.

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

Parameters:
• tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

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

classmethod differential_power(power, tangent_vec, base_point)[source]#

Compute the differential of the matrix power function.

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

Parameters:
• power (int) – Power.

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

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

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

classmethod expm(mat)#

Compute the matrix exponential for a symmetric matrix.

Parameters:

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

Returns:

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

classmethod inverse_differential_exp(tangent_vec, base_point)[source]#

Compute the inverse of the differential of the matrix exponential.

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

Parameters:
• tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

inverse_differential_exp (array-like, shape=[…, n, n]) – Inverse of the differential of the matrix exponential.

classmethod inverse_differential_log(tangent_vec, base_point)[source]#

Compute the inverse of the differential of the matrix logarithm.

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

Parameters:
• tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point.

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

inverse_differential_log (array-like, shape=[…, n, n]) – Inverse of the differential of the matrix logarithm.

classmethod inverse_differential_power(power, tangent_vec, base_point)[source]#

Compute the inverse of the differential of the matrix power.

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

Parameters:
• power (int) – Power.

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

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

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

classmethod logm(mat)[source]#

Compute the matrix log for a symmetric matrix.

Parameters:

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

Returns:

log (array_like, shape=[…, n, n]) – Matrix logarithm of mat.

classmethod powerm(mat, power)#

Compute the matrix power.

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.

projection(point)[source]#

Project a matrix to the space of SPD matrices.

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

Parameters:

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

Returns:

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

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

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

Parameters:
• n_samples (int) – Number of samples. Optional, default: 1.

• bound (float) – Bound of the interval in which to sample in the tangent space. Optional, default: 1.

Returns:

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

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

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

Parameters:
• n_samples (int) – Number of samples. Optional, default: 1.

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

Returns:

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

static to_vector(mat)#

Convert a symmetric matrix into a vector.

Parameters:

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

Returns:

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

class geomstats.geometry.spd_matrices.SPDMetricAffine(n, power_affine=1)[source]#

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

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

Compute the affine-invariant exponential map.

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

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

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

Returns:

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

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:

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, **kwargs)[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 SPD matrices. Point to transport from

• direction (array-like, shape=[…, n, n]) – Tangent vector at base point, initial speed of the geodesic along which the parallel transport is computed. Unused if end_point is given. Optional, default: None.

• end_point (array-like, shape=[…, n, n]) – Point on the manifold of SPD matrices. Point to transport to. Optional, default: None.

Returns:

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

class geomstats.geometry.spd_matrices.SPDMetricBuresWasserstein(n)[source]#

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

Parameters:

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

References

[BJL2017]

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

[MMP2018]

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

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

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:

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, **kwargs)[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_a, base_point, tangent_vec_b=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_a (array-like, shape=[…, n, n]) – Tangent vector at base_point to transport.

• tangent_vec_b (array-like, shape=[…, n, n]) – Tangent vector ar base_point, initial velocity of the geodesic to transport along.

• base_point (array-like, shape=[…, n, n]) – Initial point of the geodesic.

• end_point (array-like, shape=[…, n, n]) – Point to transport to. Optional, default: None.

• n_steps (int) – Number of steps to use to approximate the solution of the ordinary differential equation. Optional, default: 100

• step (str, {‘euler’, ‘rk2’, ‘rk4’}) – Scheme to use in the integration scheme. Optional, default: ‘rk4’.

Returns:

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

References

[TP2021]

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

Integration

squared_dist(point_a, point_b, **kwargs)[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.spd_matrices.SPDMetricEuclidean(n, power_euclidean=1)[source]#

Class for the Euclidean metric on the SPD manifold.

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

Compute the Euclidean exponential map.

Compute the Euclidean exponential at point base_point of tangent vector tangent_vec. This gives a symmetric positive definite matrix.

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

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

Returns:

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

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:

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

Compute the Euclidean inner-product.

Compute the inner-product of tangent_vec_a and tangent_vec_b at point base_point using the power-Euclidean metric.

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

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

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

Returns:

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

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

Compute the Euclidean logarithm map.

Compute the Euclidean logarithm at point base_point, of point. 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]) – Euclidean logarithm.

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 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 manifold. Point to transport to. Optional, default: None.

Returns:

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

class geomstats.geometry.spd_matrices.SPDMetricLogEuclidean(n)[source]#

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

Parameters:

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

dist(point_a, point_b)[source]#

Compute log euclidean distance.

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

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

Returns:

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

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

Compute the Log-Euclidean exponential map.

Compute the Riemannian exponential at point base_point of tangent vector tangent_vec wrt the Log-Euclidean metric. This gives a symmetric positive definite matrix.

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

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

Returns:

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

Radius of the largest ball where the exponential is injective.

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

Parameters:

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

Returns:

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

Compute the Log-Euclidean inner-product.

Compute the inner-product of tangent_vec_a and tangent_vec_b at point base_point using the log-Euclidean metric.

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

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

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

Returns:

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

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

Compute the Log-Euclidean logarithm map.

Compute the Riemannian logarithm at point base_point, of point wrt the Log-Euclidean 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.

### Skew-Symmetric Matrices Space#

Module providing the SkewSymmetricMatrices class.

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

class geomstats.geometry.skew_symmetric_matrices.SkewSymmetricMatrices(n)[source]#

Class for skew-symmetric matrices.

Parameters:

n (int) – Number of rows and columns.

basis_representation(matrix_representation)[source]#

Calculate the coefficients of given matrix in the basis.

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

Parameters:

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

Returns:

basis_representation (array-like, shape=[…, dim]) – Representation in the basis.

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

Evaluate if mat is a skew-symmetric matrix.

Parameters:
• mat (array-like, shape=[…, n, n]) – Square matrix to check.

• atol (float) – Tolerance for the equality evaluation. Optional, default: backend atol.

Returns:

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

classmethod projection(mat)[source]#

Compute the skew-symmetric component of a matrix.

The skew-symmetric part of a matrix $$X$$ is defined by

$(X - X^T) / 2$
Parameters:

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

Returns:

skew_sym (array-like, shape=[…, n, n]) – Skew-symmetric matrix.

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

Sample from a uniform distribution in a cube.

Parameters:
• n_samples (int) – Number of samples. Optional, default: 1.

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

Returns:

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

### Stiefel Manifold#

Stiefel manifold St(n,p).

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

class geomstats.geometry.stiefel.Stiefel(n, p, **kwargs)[source]#

Class for Stiefel manifolds St(n,p).

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

Parameters:
• n (int) – Dimension of the ambient vector space.

• p (int) – Number of basis vectors in the orthonormal frame.

projection(point)[source]#

Project a close enough matrix to the Stiefel manifold.

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

Parameters:

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

Returns:

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

References

[Absil]

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

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

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

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

Parameters:
• n_samples (int) – Number of samples. Optional, default: 1.

• bound (float) – Unused here.

Returns:

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

random_uniform(n_samples=1)[source]#

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

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

Parameters:

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

Returns:

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

static to_grassmannian(point)[source]#

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

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

Parameters:

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

Returns:

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

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Inspired by the method of Pymanopt.

Parameters:
• vector (array-like, shape=[…, n, p]) – Vector.

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

Returns:

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

class geomstats.geometry.stiefel.StiefelCanonicalMetric(n, p)[source]#

Class that defines the canonical metric for Stiefel manifolds.

Parameters:
• n (int) – Dimension of the ambient vector space.

• p (int) – Number of basis vectors in the orthonormal frames.

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

Compute the Riemannian exponential of a tangent vector.

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

• base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

Returns:

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

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In this case the exact injectivity radius is not known, and we use here a lower bound given by [Rentmeesters2015].

Parameters:

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

Returns:

References

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

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

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

Canonical inner-product on the tangent space at base_point, which is different from the inner-product induced by the embedding (see [RLSMRZ2017]).

$\langle\Delta, \tilde{\Delta}\rangle_{U}=\operatorname{tr} \left(\Delta^{T}\left(I-\frac{1}{2} U U^{T}\right) \tilde{\Delta}\right)$

References

R Zimmermann. A matrix-algebraic algorithm for the Riemannian logarithm on the Stiefel manifold under the canonical metric. SIAM Journal on Matrix Analysis and Applications 38 (2), 322-342, 2017. https://epubs.siam.org/doi/pdf/10.1137/16M1074485

Parameters:
• tangent_vec_a (array-like, shape=[…, n, p]) – First tangent vector at base point.

• tangent_vec_b (array-like, shape=[…, n, p]) – Second tangent vector at base point.

• base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

Returns:

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

log(point, base_point, max_iter=30, tol=1e-12, **kwargs)[source]#

Compute the Riemannian logarithm of a point.

When p=n, the space St(n,n)~O(n) has two non connected sheets: the log is only defined for data from the same sheet. For p<n, the space St(n,p)~O(n)/O(n-p)~SO(n)/SO(n-p) is connected. Based on [ZR2017].

References

[ZR2017]

Zimmermann, Ralf. “A Matrix-Algebraic Algorithm for the Riemannian Logarithm on the Stiefel Manifold under the Canonical Metric” SIAM J. Matrix Anal. & Appl., 38(2), 322–342, 2017. https://arxiv.org/pdf/1604.05054.pdf

Parameters:
• point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

• base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

• max_iter (int) – Maximum number of iterations to perform during the algorithm. Optional, default: 30.

• tol (float) – Tolerance to reach convergence. The matrix 2-norm is used as criterion. Optional, default: 1e-6.

Returns:

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

static retraction(tangent_vec, base_point)[source]#

Compute the retraction of a tangent vector.

This computation is based on the QR-decomposition.

e.g. $$P_x(V) = qf(X + V)$$.

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

• base_point (array-like, shape=[…, n, p]) – Point in the Stiefel manifold.

Returns:

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

### Lie Groups#

Lie groups.

class geomstats.geometry.lie_group.LieGroup(dim, shape, lie_algebra=None, **kwargs)[source]#

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

left_canonical_metric#

The left invariant metric that corresponds to the Euclidean inner product at the identity.

Type:

InvariantMetric

right_canonical_metric#

The right invariant metric that corresponds to the Euclidean inner product at the identity.

Type:

InvariantMetric

Add a metric to the instance’s list of metrics.

Parameters:

metric (RiemannianMetric) – Metric to add.

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.

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.

get_identity()[source]#

Get the identity of the group.

Returns:

identity (array-like, shape={[dim], [n, n]}) – Identity of the Lie group.

property identity#

Get the 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_or_right='left')[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_or_right (str, {‘left’, ‘right’}) – Indicate whether to calculate the differential of left or right translations. Optional, default: ‘left’.

Returns:

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

lie_bracket(tangent_vector_a, tangent_vector_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_vector_a (array-like, shape=[…, n, n]) – Tangent vector at base point.

• tangent_vector_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_or_right='left', 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_or_right (str, {‘left’, ‘right’}) – Whether to calculate the differential of left or right translations. Optional, default: ‘left’

• 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(dim, n, lie_algebra=None, **kwargs)[source]#

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_vector_a, tangent_vector_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_vector_a (array-like, shape=[…, n, n]) – Tangent vector at base point.

• tangent_vector_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_or_right='left', 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_or_right (str, {‘left’, ‘right’}) – Whether to calculate the differential of left or right translations. Optional, default: ‘left’

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

### Lie Algebra#

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

class geomstats.geometry.lie_algebra.MatrixLieAlgebra(dim, n, **kwargs)[source]#

Class implementing matrix Lie algebra related functions.

Parameters:
• dim (int) – Dimension of the Lie algebra as a real vector space.

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

abstract basis_representation(matrix_representation)[source]#

Compute the coefficients of matrices in the given basis.

Parameters:

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

Returns:

basis_representation (array-like, shape=[…, dim]) – Coefficients in the basis.

classmethod bracket(mat_a, mat_b)#

Compute the commutator of a and b, i.e. [a, b] = ab - ba.

Parameters:
• mat_a (array-like, shape=[…, n, n]) – Matrix.

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

Returns:

mat_c (array-like, shape=[…, n, n]) – Commutator.

matrix_representation(basis_representation)[source]#

Compute the matrix representation for the given basis coefficients.

Sums the basis elements according to the coefficients given in basis_representation.

Parameters:

basis_representation (array-like, shape=[…, dim]) – Coefficients in the basis.

Returns:

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

### Matrices Space#

Module exposing the Matrices and MatricesMetric class.

class geomstats.geometry.matrices.Matrices(m, n, **kwargs)[source]#

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.

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

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 matrix is square and 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 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.

• atol (float) – Absolute tolerance. Optional, default: backend atol.

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 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 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 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 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 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 suymmetric by averaging it with its transpose.

Parameters:

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

Returns:

sym (array-like, shape=[…, n, n]) – Symmetric matrix.

classmethod to_upper_triangular(mat)[source]#

Make a matrix upper triangular.

Make a matrix upper triangular by zeroing out lower elements.

Parameters:

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

Returns:

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

static trace_product(mat_1, mat_2)[source]#

Compute trace of the product of two matrices.

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

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

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

Returns:

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

static transpose(mat)[source]#

Return the transpose of matrices.

Parameters:

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

Returns:

transpose (array-like, shape=[…, n, n]) – Transposed matrix.

class geomstats.geometry.matrices.MatricesMetric(m, n, **kwargs)[source]#

Euclidean metric on matrices given by Frobenius inner-product.

Parameters:

m, n (int) – Integers representing the shapes of the matrices: m x 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.

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

### General Linear Group#

Module exposing the GeneralLinear group class.

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

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

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

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

Parameters:
• n_samples (int) – Number of samples. Optional, default: 1.

• bound (float) – Bound of the interval in which to sample each matrix entry. Optional, default: 1.

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

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.

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.

### Special Euclidean Group#

The special Euclidean group SE(n).

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

Lead authors: Nicolas Guigui and Nina Miolane.

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

Class for the special Euclidean groups.

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

• point_type (str, {'vector', 'matrix'}) – Representation of the elements of the group. Optional, default: ‘matrix’,

• epsilon (float) – Precision used for calculations involving potential divison by 0 in rotations. Optional, default: 0.

class geomstats.geometry.special_euclidean.SpecialEuclideanMatrixCannonicalLeftMetric(group)[source]#

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

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

Parameters:

group (SpecialEuclidean) – Instance of the class SpecialEuclidean with point_type=’matrix’.

exp(tangent_vec, base_point=None, n_steps=10, step='rk4', **kwargs)[source]#

Exponential map associated to the cannonical metric.

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

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

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

Returns:

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

examples.plot_geodesics_se2

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In this case, it does not depend on the base point. If the rotation part is null, then the radius is infinite, otherwise it is the same as the special orthonormal group.

Parameters:

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

Returns:

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

Compute inner product of two vectors in tangent space at base point.

Parameters:
• tangent_vec_a (array-like, shape=[…, n, n]) – First tangent vector at base_point.

• tangent_vec_b (array-like, shape=[…, n, n]) – Second tangent vector at base_point.

• base_point (array-like, shape=[…, n, n]) – Point in the group. Optional, defaults to identity if None.

Returns:

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

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

Compute logarithm map associated to the canonical metric.

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

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

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

Returns:

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

References

[Zefran98]

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

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

Compute the parallel transport of a tangent vector.

Closed-form solution for the parallel transport of a tangent vector a along the geodesic between two points base_point and end_point or alternatively defined by $$t \mapsto exp_{(base\_point)}( t*direction)$$. As the special Euclidean group endowed with its canonical left-invariant metric is a symmetric space, parallel transport is achieved by a geodesic symmetry, or equivalently, one step of the pole ladder scheme.

Parameters:
• tangent_vec (array-like, shape=[…, n + 1, n + 1]) – Tangent vector at base point to be transported.

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

• direction (array-like, shape=[…, n + 1, n + 1]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None

• end_point (array-like, shape=[…, n + 1, n + 1]) – Point on the Grassmann manifold to transport to. Unused if tangent_vec_b is given. Optional, default: None

Returns:

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

private_squared_dist(point_a, point_b)[source]#

Compute geodesic distance between two points.

Compute the squared geodesic distance between point_a and point_b, as defined by the metric.

This is an auxiliary private function that:

• is called by the method squared_dist of the class SpecialEuclideanMatrixCannonicalLeftMetric,

• has been created to support the implementation of custom_gradient in tensorflow backend.

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

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

Returns:

_ (array-like, shape=[…,]) – Geodesic distance between point_a and point_b.

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

Squared geodesic distance between two points.

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

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

Returns:

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

class geomstats.geometry.special_euclidean.SpecialEuclideanMatrixLieAlgebra(n)[source]#

Lie Algebra of the special Euclidean group.

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

$((A, t), (0, 0))$

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

Parameters:

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

basis_representation(matrix_representation)[source]#

Calculate the coefficients of given matrix in the basis.

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

Parameters:

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

Returns:

basis_representation (array-like, shape=[…, dim]) – Representation in the basis.

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

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

Parameters:
• mat (array-like, shape=[…, n + 1, n + 1]) – Square matrix to check.

• atol (float) – Tolerance for the equality evaluation. Optional, default: backend atol.

Returns:

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

projection(mat)[source]#

Project a matrix to the Lie Algebra.

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

Parameters:

mat (array-like, shape=[…, n + 1, n + 1]) – Matrix.

Returns:

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

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

Sample in the lie algebra with a uniform distribution in a box.

Parameters:
• n_samples (int) – Number of samples. Optional, default: 1.

• bound (float) – Side of hypercube support of the uniform distribution. Optional, default: 1.0

Returns:

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

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

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

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

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

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

Parameters:
• rotation (array-like, shape=[…, n, n]) – Square Matrix.

• translation (array-like, shape=[…, n]) – Vector.

• output_shape (tuple of int) – Desired output shape. This is need for vectorization.

• constant (float or array-like of shape […]) – Constant to use at the last line and column of the square matrix. Optional, default: 1.

Returns:

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

geomstats.geometry.special_euclidean.submersion(point)[source]#

Define SE(n) as the pre-image of identity.

Parameters:

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

Returns:

submersed_point (array-like, shape=[…, n + 1, n + 1]) – Submersed Point.

geomstats.geometry.special_euclidean.tangent_submersion(vector, point)[source]#

Define the tangent space of SE(n) as the kernel of this method.

Parameters:
• vector (array-like, shape=[…, n + 1, n + 1]) – Point.

• point (array-like, shape=[…, n + 1, n + 1]) – Point.

Returns:

submersed_vector (array-like, shape=[…, n + 1, n + 1]) – Submersed Vector.

### Special Orthogonal Group#

Exposes the SpecialOrthogonal group class.

Lead authors: Nicolas Guigui and Nina Miolane.

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

Class for the special orthogonal groups.

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

• point_type (str, {'vector', 'matrix'}) – Representation of the elements of the group.

• epsilon (float, optional) – precision to use for calculations involving potential divison by 0 in rotations default: 0

### Graph Space#

Graph Space.

class geomstats.geometry.stratified.graph_space.ExhaustiveAligner[source]#

Brute force exact alignment.

Exact Alignment obtained by exploring the whole permutation group.

Notes

Not recommended for large n_nodes.

align(metric, base_graph, graph_to_permute)[source]#

Align graphs.

Parameters:
• metric (GraphSpaceMetric) – Metric between elements of GraphSpace.

• base_graph (array-like, shape=[…, n_nodes, n_nodes]) – Base graph.

• graph_to_permute (array-like, shape=[…, n_nodes, n_nodes]) – Graph to align.

Returns:

permuted_graph (array-like, shape=[…, n_nodes, n_nodes]) – Permuted graph as to be aligned with respect to the geodesic.

class geomstats.geometry.stratified.graph_space.FAQAligner[source]#

Fast Quadratic Assignment for graph matching (or network alignment).

References

[Vogelstein2015]

Vogelstein JT, Conroy JM, Lyzinski V, Podrazik LJ, Kratzer SG, Harley ET, Fishkind DE, Vogelstein RJ, Priebe CE. “Fast approximate quadratic programming for graph matching.“ PLoS One. 2015 Apr 17; doi: 10.1371/journal.pone.0121002.

align(metric, base_graph, graph_to_permute)[source]#

Align graphs.

Parameters:
• metric (GraphSpaceMetric) – Metric between elements of GraphSpace.

• base_graph (array-like, shape=[…, n_nodes, n_nodes]) – Base graph.

• graph_to_permute (array-like, shape=[…, n_nodes, n_nodes]) – Graph to align.

Returns:

permuted_graph (array-like, shape=[…, n_nodes, n_nodes]) – Permuted graph as to be aligned with respect to the geodesic.

Class for the GraphPoint.

Points are represented by $$nodes \times nodes$$ adjacency matrices.

Parameters:

References

[Calissano2020]

Calissano, A., Feragen, A., Vantini, S. “Graph Space: Geodesic Principal Components for a Population of Network-valued Data.” Mox report 14, 2020. https://mox.polimi.it/reports-and-theses/publication-results/?id=855.

property n_nodes#

Retrieve the number of nodes.

to_array()[source]#

Return a copy of the adjacency matrix.

to_networkx()[source]#

Turn the graph into a networkx format.

class geomstats.geometry.stratified.graph_space.GraphSpace(n_nodes, total_space=None)[source]#

Class for the Graph Space.

Graph Space to analyse populations of labelled and unlabelled graphs. The space focuses on graphs with scalar euclidean attributes on nodes and edges, with a finite number of nodes and both directed and undirected edges. For undirected graphs, use symmetric adjacency matrices. The space is a quotient space obtained by applying the permutation action of nodes to the space of adjacency matrices. Notice that for computation reasons the module works with both the gs.array representation of graph and the GraphPoint representation.

Points are represented by $$nodes \times nodes$$ adjacency matrices. Both the array input and the Graph Point type input work.

Parameters:
• n_nodes (int) – Number of graph nodes

• total_space (space) – Total Space before applying the permutation action. Default: Euclidean Space.

References

[Calissano2020]

Calissano, A., Feragen, A., Vantini, S. “Graph Space: Geodesic Principal Components for a Population of Network-valued Data.” Mox report 14, 2020. https://mox.polimi.it/reports-and-theses/publication-results/?id=855.

[Jain2009]

Jain, B., Obermayer, K. “Structure Spaces.” Journal of Machine Learning Research, 10(11), 2009. https://www.jmlr.org/papers/volume10/jain09a/jain09a.pdf

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

Check if the point belongs to the space.

Parameters:
• graphs (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes]) – Points to be checked.

• atol (float) – Tolerance. Optional, default: backend atol.

Returns:

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

Pad points with zeros to match space dimension.

Parameters:

points (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes])

permute(graph_to_permute, permutation)[source]#

Permutation action applied to graph observation.

Parameters:
• graph_to_permute (list of GraphPoint or array-like,) – shape=[…, n_nodes, n_nodes] Input graphs to be permuted.

• permutation (array-like, shape=[…, n_nodes]) – Node permutations where in position i we have the value j meaning the node i should be permuted with node j.

Returns:

graphs_permuted (array-like, shape=[…, n_nodes, n_nodes]) – Graphs permuted.

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

Sample in Graph Space.

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:

graph_samples (array-like, shape=[…, n_nodes, n_nodes]) – Points sampled in GraphSpace(n_nodes).

set_to_array(points)[source]#

Return a copy of the adjacency matrices.

Parameters:

points (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes]) – Points to be turned into an array

Returns:

graph_array (array-like, shape=[…, n_nodes, n_nodes]) – An array containing all the Graphs.

set_to_networkx(points)[source]#

Turn points into a networkx object.

Parameters:

points (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes])

Returns:

nx_list (list of networkx object) – An array containing all the Graphs.

class geomstats.geometry.stratified.graph_space.GraphSpaceMetric(space)[source]#

Class for the Graph Space Metric.

Every metric $$d: X \times X \rightarrow \mathbb{R}$$ on the total space of adjacency matrices can descend onto the quotient space as a pseudo-metric: $$d([x_1],[x_2]) = min_{t\in T} d_X(x_1, t^Tx_2t)$$. The metric relies on the total space metric and an alignment procedure, i.e., Graph Matching or Networks alignment procedure. Metric, alignment, geodesics, and alignment with respect to a geodesic are defined. By default, the alignment is the identity and the total space metric is the Frobenious norm.

Parameters:

space (GraphSpace) – GraphSpace object.

References

[Calissano2020]

Calissano, A., Feragen, A., Vantini, S. “Graph Space: Geodesic Principal Components for a Population of Network-valued Data.” Mox report 14, 2020. https://mox.polimi.it/reports-and-theses/publication-results/?id=855.

align_point_to_geodesic(geodesic, graph_to_permute)[source]#

Align graph to a geodesic.

Using the selected alignment technique, it returns the permuted graph_to_permute as optimally aligned to the geodesic using [Huckemann2010].

Parameters:
• geodesic (function) – Geodesic in Graph Space function.

• graph_to_permute (list of Graph or array-like, shape=[…, n_nodes, n_nodes]) – Graph to align.

Returns:

permuted_graph (list, shape = […, n_nodes, n_nodes])

References

[Huckemann2010]

Huckemann, S., Hotz, T., Munk, A. “Intrinsic shape analysis: Geodesic PCA for Riemannian manifolds modulo isometric Lie group actions.” Statistica Sinica, 1-58, 2010.

align_point_to_point(base_graph, graph_to_permute)[source]#

Align graphs.

Using the selected alignment technique, it returns the permuted graph_to_permute as optimally aligned to the base_graph.

Parameters:
• base_graph (list of Graph or array-like, shape=[…, n_nodes, n_nodes]) – Base graph.

• graph_to_permute (list of Graph or array-like, shape=[…, n_nodes, n_nodes]) – Graph to align.

Returns:

permuted_graph (list, shape = […, n_nodes, n_nodes])

dist(graph_a, graph_b)[source]#

Compute distance between two equivalence classes.

Compute the distance between two equivalence classes of adjacency matrices [Jain2009].

Parameters:
• graph_a (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes])

• graph_b (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes])

Returns:

distance (array-like, shape=[…]) – distance between equivalence classes.

References

[Jain2009]

Jain, B., Obermayer, K. “Structure Spaces.” Journal of Machine Learning Research 10.11 (2009). https://www.jmlr.org/papers/v10/jain09a.html.

geodesic(base_point, end_point)[source]#

Compute geodesic between two equivalence classes.

Compute the geodesic between two equivalence classes of adjacency matrices [Calissano2020].

Parameters:
• base_point (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes]) – Start .

• end_point (list of GraphPoint or array-like, shape=[…, n_nodes, n_nodes]) – Second graph to align to the first graph.

Returns:

geodesic (callable) – Geodesic function.

References

[Calissano2020]

Calissano, A., Feragen, A., Vantini, S.

“Graph Space: Geodesic Principal Components for a Population of Network-valued Data.” Mox report 14, 2020. https://mox.polimi.it/reports-and-theses/publication-results/?id=855.

property n_nodes#

Retrieve the number of nodes.

property perm_#

Permutation of nodes after alignment.

Node permutations where in position i we have the value j meaning the node i should be permuted with node j.

set_aligner(aligner, **kwargs)[source]#

Set the aligning strategy.

Graph Space metric relies on alignment. In this module we propose the identity matching, the FAQ graph matching by [Vogelstein2015], and exhaustive aligner which explores the whole permutation group.

Parameters:

aligner (str) – ‘ID’ Identity ‘FAQ’ Fast Quadratic Assignment - only compatible with Frobenious norm ‘exhaustive’ all group exhaustive search

References

[Vogelstein2015]

Vogelstein JT, Conroy JM, Lyzinski V, Podrazik LJ, Kratzer SG, Harley ET, Fishkind DE, Vogelstein RJ, Priebe CE. “Fast approximate quadratic programming for graph matching.“ PLoS One. 2015 Apr 17; doi: 10.1371/journal.pone.0121002.

set_point_to_geodesic_aligner(aligner, **kwargs)[source]#

Set the alignment between a point and a geodesic.

Following the geodesic to point alignment in [Calissano2020] and [Huckemann2010], this function defines the parameters [s_min, s_max] and the number of points to sample in the domain.

Parameters:
• s_min (float) – Minimum value of the domain to sample along the geodesics.

• s_max (float) – Minimum value of the domain to sample along the geodesics.

• n_points (int) – Number of points to sample between s_min and s_max.

References

[Calissano2020]

Calissano, A., Feragen, A., Vantini, S. “Graph Space: Geodesic Principal Components for a Population of Network-valued Data.” Mox report 14, 2020. https://mox.polimi.it/reports-and-theses/publication-results/?id=855.

[Huckemann2010]

Huckemann, S., Hotz, T., Munk, A. “Intrinsic shape analysis: Geodesic PCA for Riemannian manifolds modulo isometric Lie group actions.” Statistica Sinica, 1-58, 2010.

property total_space_metric#

Retrieve the total space metric.

class geomstats.geometry.stratified.graph_space.IDAligner[source]#

Identity alignment.

The identity alignment is not performing any matching but returning the nodes in their original position. This alignment can be selected when working with labelled graphs.

align(metric, base_graph, graph_to_permute)[source]#

Align graphs.

Parameters:
• metric (GraphSpaceMetric) – Metric between elements of GraphSpace.

• base_graph (array-like, shape=[…, n_nodes, n_nodes]) – Base graph.

• graph_to_permute (array-like, shape=[…, n_nodes, n_nodes]) – Graph to align.

Returns:

permuted_graph (array-like, shape=[…, n_nodes, n_nodes]) – Permuted graph as to be aligned with respect to the geodesic.

class geomstats.geometry.stratified.graph_space.PointToGeodesicAligner(s_min, s_max, n_points=10)[source]#

Class for the Alignment of the points with respect to a geodesic.

Implementing the algorithm in [Huckemann2010] to select an optimal alignment to a point with respect to a geodesic. The algorithm sample discrete set of n_points along the geodesic between [s_min, s_max] and find the permutation that gets closer to the datapoints along the geodesic.

Parameters:
• metric (GraphSpaceMetric) – Metric between elements of GraphSpace.

• s_min (float) – Minimum value of the domain to sample along the geodesics.

• s_max (float) – Minimum value of the domain to sample along the geodesics.

• n_points (int) – Number of points to sample between s_min and s_max.

References

[Calissano2020]

Calissano, A., Feragen, A., Vantini, S. “Graph Space: Geodesic Principal Components for a Population of Network-valued Data.” Mox report 14, 2020. https://mox.polimi.it/reports-and-theses/publication-results/?id=855.

[Huckemann2010]

Huckemann, S., Hotz, T., Munk, A. “Intrinsic shape analysis: Geodesic PCA for Riemannian manifolds modulo isometric Lie group actions.” Statistica Sinica, 1-58, 2010.

align(metric, geodesic, graph_to_permute)[source]#

Align the graph to the geodesic.

Parameters:
• geodesic (function) – Geodesic function in GraphSpace.

• graph_to_permute (array-like, shape=[…, n_nodes, n_nodes]) – Graph to align.

Returns:

permuted_graph (array-like, shape=[…, n_nodes]) – Permuted graph as to be aligned with respect to the geodesic.

dist(metric, geodesic, graph_to_permute)[source]#

Compute the distance between the geodesic and the point.

Parameters:
• geodesic (function) – Geodesic function in GraphSpace.

• graph_to_permute (array-like, shape=[…, n_nodes, n_nodes]) – Graph to align.

Returns:

dist (array-like, shape=[…, n_nodes]) – Distance between the graph_to_permute and the geodesic.

property s#

Save the domain discretization.

### Grassmannian Manifold#

Manifold of linear subspaces.

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

$$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, **kwargs)[source]#

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

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

• p (int) – Dimension of the subspaces.

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

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(n, p)[source]#

Canonical metric of the Grassmann manifold.

Coincides with the Frobenius metric.

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

• p (int) – Dimension of the subspaces.

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

Exponentiate the invariant vector field v from base point p.

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

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

Returns:

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

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:

References

[BZA20]

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

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

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

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

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

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

Parameters:
• point (array-like, shape=[…, n, n]) – Point.

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

Returns:

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

References

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

parallel_transport(tangent_vec, base_point, tangent_vec_b=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.

• tangent_vec_b (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 tangent_vec_b is given. Optional, default: None

Returns:

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

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.

private_squared_dist(point_a, point_b)[source]#

Compute geodesic distance between two points.

Compute the squared geodesic distance between point_a and point_b, as defined by the metric.

This is an auxiliary private function that:

• is called by the method squared_dist of the class GrassmannianCanonicalMetric,

• has been created to support the implementation of custom_gradient in tensorflow backend.

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

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

Returns:

_ (array-like, shape=[…,]) – Geodesic distance between point_a and point_b.

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

Squared geodesic distance between two points.

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

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

Returns:

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

geomstats.geometry.grassmannian.submersion(point, p)[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.

References

[Pau07]

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

### Landmarks Space#

Manifold for sets of landmarks that belong to any given manifold.

class geomstats.geometry.landmarks.L2LandmarksMetric(ambient_metric, k_landmarks, **kwargs)[source]#

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.

Parameters:
• ambient_metric (RiemannianMetric) – Riemannian metric of the manifold to which the landmarks belong.

• k_landmarks (int) – Number of landmarks.

class geomstats.geometry.landmarks.Landmarks(ambient_manifold, k_landmarks, **kwargs)[source]#

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.

### Poincare Polydisk Space#

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.

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, default_coords_type='extrinsic')[source]#

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.

• default_coords_type (str, {'intrinsic', 'extrinsic', etc}) – Coordinate type. Optional, default: 'extrinsic'.

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.

to_tangent(vector, base_point)[source]#

Project a vector in the tangent space.

Project a vector in Minkowski space on the tangent space of the hyperbolic space at a base point.

Parameters:
• vector (array-like, shape=[…, n_disks, dim + 1]) – Vector.

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

Returns:

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

class geomstats.geometry.poincare_polydisk.PoincarePolydiskMetric(n_disks, default_coords_type='extrinsic')[source]#

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.

Parameters:
• n_disks (int) – Number of disks.

• default_coords_type (str, {'intrinsic', 'extrinsic', etc}) – Coordinate type. Optional, default: 'extrinsic'.

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

### Lower Triangular Matrices#

The vector space of lower triangular matrices.

class geomstats.geometry.lower_triangular_matrices.LowerTriangularMatrices(n, **kwargs)[source]#

Class for the vector space of lower triangular matrices of size n.

Parameters:

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

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

Evaluate if a matrix is lower triangular.

Parameters:
• point (array-like, shape=[.., n, n]) – Point to test.

• atol (float) – Tolerance to evaluate equality with the transpose.

Returns:

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

projection(point)[source]#

Make a square matrix lower triangular by zeroing out other elements.

Parameters:

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

Returns:

sym (array-like, shape=[…, n, n]) – Symmetric matrix.

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

Sample a lower triangular matrix with a uniform distribution in a box.

Parameters:
• n_samples (int) – Number of samples. Optional, default: 1.

• bound (float) – Side of hypercube support of the uniform distribution. Optional, default: 1.0.

Returns:

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

static to_vector(mat)[source]#

Convert a lower triangular matrix into a vector.

Parameters:

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

Returns:

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

### Positive Lower Triangular Matrices#

The manifold of lower triangular matrices with positive diagonal elements.

class geomstats.geometry.positive_lower_triangular_matrices.CholeskyMetric(n)[source]#

Class for cholesky metric on cholesky space.

Parameters:

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

References

[TP2019]

. “Riemannian Geometry of Symmetric Positive Definite Matrices Via Cholesky Decomposition” SIAM journal on Matrix Analysis and Applications , 2019. https://arxiv.org/abs/1908.09326

static diag_inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]#

Compute the inner product using only diagonal elements.

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

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

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

Returns:

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

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

Compute the Cholesky exponential map.

Compute the Riemannian exponential at point base_point of tangent vector tangent_vec wrt the Cholesky metric. This gives a lower triangular matrix with positive elements.

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

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

Returns:

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

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

Compute the inner product.

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

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

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

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

Returns:

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

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

Compute the Cholesky logarithm map.

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

Parameters:
• point (array-like, shape=[…, n, n]) – Point.

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

Returns:

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

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

Compute the Cholesky Metric squared distance.

Compute the Riemannian squared distance between point_a and point_b.

Parameters:
• point_a (array-like, shape=[…, n, n]) – Point.

• point_b (array-like, shape=[…, n, n]) – Point.

Returns:

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

static strictly_lower_inner_product(tangent_vec_a, tangent_vec_b)[source]#

Compute the inner product using only strictly lower triangular elements.

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

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

Returns:

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

class geomstats.geometry.positive_lower_triangular_matrices.PositiveLowerTriangularMatrices(n, **kwargs)[source]#

Manifold of lower triangular matrices with >0 diagonal.

This manifold is also called the cholesky space.

Parameters:

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

References

[TP2019]

Z Lin. “Riemannian Geometry of Symmetric Positive Definite Matrices Via Cholesky Decomposition” SIAM journal on Matrix Analysis and Applications , 2019. https://arxiv.org/abs/1908.09326

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

Check if mat is lower triangular with >0 diagonal.

Parameters:
• mat (array-like, shape=[…, n, n]) – Matrix to be checked.

• atol (float) – Tolerance. Optional, default: backend atol.

Returns:

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

static differential_gram(tangent_vec, base_point)[source]#

Compute differential of gram.

Parameters:
• tangent_vec (array_like, shape=[…, n, n]) – Tangent vector at base point. Symmetric Matrix.

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

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

static gram(point)[source]#

Compute gram matrix of rows.

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

Parameters:

point (array-like, shape=[…, n, n]) – element in cholesky space.

Returns:

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

static inverse_differential_gram(tangent_vec, base_point)[source]#

Compute inverse differential of gram map.

Parameters:
• tangent_vec (array_like, shape=[…, n, n]) – tanget vector at gram(base_point) Symmetric Matrix.

• base_point (array_like, shape=[…, n, n]) – Base point.

Returns:

inverse_differential_gram (array-like, shape=[…, n, n]) – Inverse differential of gram. Lower triangular matrix.

projection(point)[source]#

Project a matrix to the Cholesksy space.

First it is projected to space lower triangular matrices and then diagonal elements are exponentiated to make it positive.

Parameters:

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

Returns:

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

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

Sample from the manifold.

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.

## Metrics#

### Riemannian Metric#

Riemannian and pseudo-Riemannian metrics.

class geomstats.geometry.riemannian_metric.RiemannianMetric(dim, shape=None, signature=None, default_coords_type='intrinsic')[source]#

Class for Riemannian and pseudo-Riemannian metrics.

The associated Levi-Civita connection on the tangent bundle.

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

• shape (tuple of int) – Shape of one element of the manifold. Optional, default : (dim, ).

• signature (tuple) – Signature of the metric. Optional, default: None.

christoffels(base_point)[source]#

Compute Christoffel symbols of the Levi-Civita connection.

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

• $$p$$ represents the base point, and

• $$g$$ represents the Riemannian metric tensor.

Parameters:

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

Returns:

christoffels (array-like, shape=[…, dim, dim, dim]) – Christoffel symbols.

closest_neighbor_index(point, neighbors)[source]#

Closest neighbor of point among neighbors.

Parameters:
• point (array-like, shape=[…, dim]) – Point.

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

Returns:

closest_neighbor_index (int) – Index of closest neighbor.

cometric_matrix(base_point=None)[source]#

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

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

Parameters:

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

Returns:

mat (array-like, shape=[…, dim, dim]) – Inverse of inner-product matrix.

diameter(points)[source]#

Give the distance between two farthest points.

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

Parameters:

points (array-like, shape=[…, dim]) – Points.

Returns:

diameter (float) – Distance between two farthest points.

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

Geodesic distance between two points.

Note: It only works for positive definite Riemannian metrics.

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

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

Returns:

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

Compute the geodesic distance between points.

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

Parameters:
• point_a (array-like, shape=[n_samples_a, dim]) – Set of points in the Poincare ball.

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

Returns:

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

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

Compute the pairwise distance between points.

Parameters:
• points (array-like, shape=[n_samples, dim]) – Set of points in the manifold.

• n_jobs (int) – Number of jobs to run in parallel, using joblib. Note that a higher number of jobs may not be beneficial when one computation of a geodesic distance is cheap. Optional. Default: 1.

• **joblib_kwargs (dict) – Keyword arguments to joblib.Parallel

Returns:

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

hamiltonian(state)[source]#

Compute the hamiltonian energy associated to the cometric.

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

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

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

Parameters:

state (tuple of arrays) – Position and momentum variables. The position is a point on the manifold, while the momentum is cotangent vector.

Returns:

energy (float) – Hamiltonian energy at state.

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

Compute inner coproduct between two cotangent vectors at base point.

This is the inner product associated to the cometric matrix.

Parameters:
• cotangent_vec_a (array-like, shape=[…, dim]) – Cotangent vector at base_point.

• cotangent_vet_b (array-like, shape=[…, dim]) – Cotangent vector at base_point.

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

Returns:

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

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

inner_product_derivative_matrix(base_point=None)[source]#

Compute derivative of the inner prod matrix at base point.

Parameters:

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

Returns:

mat (array-like, shape=[…, dim, dim]) – Derivative of inverse of inner-product matrix.

metric_matrix(base_point=None)[source]#

Metric matrix at the tangent space at a base point.

Parameters:

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

Returns:

mat (array-like, shape=[…, dim, dim]) – Inner-product matrix.

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

Compute norm of a vector.

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

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

Parameters:
• vector (array-like, shape=[…, dim]) – Vector.

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

Returns:

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

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

Normalize the basis with respect to the metric.

This corresponds to a renormalization of each basis vector.

Parameters:
• basis (array-like, shape=[dim, dim]) – Matrix of a metric.

• base_point

Returns:

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

normalize(vector, base_point)[source]#

Normalize tangent vector at a given point.

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

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

Returns:

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

random_unit_tangent_vec(base_point, 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 constitues of a single point.

Returns:

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

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

Compute the sectional curvature.

For two orthonormal tangent vectors $$x,y$$ at a base point, the sectional curvature is defined by $$<R(x, y)x, y> = <R_x(y), y>$$. For non-orthonormal vectors vectors, it is $$<R(x, y)x, y> / \\|x \wedge y\\|^2$$.

Parameters:
• tangent_vec_a (array-like, shape=[…, n, n]) – Tangent vector at base_point.

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

• base_point (array-like, shape=[…, n, n]) – Point in the group. Optional, default is the identity

Returns:

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

https

//en.wikipedia.org/wiki/Sectional_curvature

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

Squared geodesic distance between two points.

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

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

Returns:

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

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.

### Product Riemannian Metric#

Product of Riemannian metrics.

Define the metric of a product manifold endowed with a product metric.

class geomstats.geometry.product_riemannian_metric.NFoldMetric(base_metric, n_copies)[source]#

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_metric (RiemannianMetric) – Base metric.

• n_copies (int) – Number of replication of the base metric.

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

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 landmark set and an initial tangent vector,

• an initial landmark set and an end landmark set.

Parameters:
• initial_point (array-like, shape=[…, dim]) – Landmark set, initial point of the geodesic.

• end_point (array-like, shape=[…, dim]) – Landmark set, end point of the geodesic. If None, an initial tangent vector must be given. Optional, default : None

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

Returns:

path (callable) – Time parameterized geodesic curve.

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

Compute the matrix of the inner-product.

Matrix of the inner-product defined by the Riemmanian metric at point base_point of the manifold.

Parameters:

base_point (array-like, shape=[…, n_copies, *base_shape]) – Point on the manifold at which to compute the inner-product matrix. Optional, default: None.

Returns:

matrix (array-like, shape=[…, n_copies, dim, dim]) – Matrix of the inner-product at the base point.

class geomstats.geometry.product_riemannian_metric.ProductRiemannianMetric(metrics, default_point_type='vector', n_jobs=1)[source]#

Class for product of Riemannian metrics.

Parameters:
• metrics (list) – List of metrics in the product.

• default_point_type (str, {‘vector’, ‘matrix’}) – Point type. Optional, default: ‘vector’.

• n_jobs (int) – Number of jobs for parallel computing. Optional, default: 1.

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

Compute the Riemannian exponential of a tangent vector.

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

• base_point (array-like, shape=[…, dim]) – Point on the manifold. Optional, default: None.

Returns:

exp (array-like, shape=[…, dim]) – 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=None)[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=[…, 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 on the manifold. Optional, default: None.

Returns:

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

is_intrinsic(point)[source]#

Test in a point is represented in intrinsic coordinates.

This method is only useful for point_type == vector.

Parameters:

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

Returns:

intrinsic (array-like, shape=[…,]) – Whether intrinsic coordinates are used for all manifolds.

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

Compute the Riemannian logarithm of a point.

Parameters:
• point (array-like, shape=[…, dim]) – Point on the manifold.

• base_point (array-like, shape=[…, dim]) – Point on the manifold. Optional, default: None.

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 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_metrics, dim] or) – […, dim] Point on the manifold at which to compute the inner-product matrix. Optional, default: None.

Returns:

• matrix (array-like, shape=[…, dim, dim] or)

• […, dim + n_metrics, dim + n_metrics] – Matrix of the inner-product at the base point.

### Invariant Metric#

Left- and right- invariant metrics that exist on Lie groups.

Lead authors: Nicolas Guigui and Nina Miolane.

class geomstats.geometry.invariant_metric.BiInvariantMetric(group)[source]#

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:

group (LieGroup) – The group to equip with the bi-invariant metric

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

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

Compute Riemannian exponential of tangent vector from the identity.

For a bi-invariant metric, this corresponds to the group exponential.

Parameters:
• tangent_vec – Tangent vector at identity.

• base_point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group. Optional, default : identity.

Returns:

exp (array-like, shape=[…, {dim, [n, n]}]) – Point in the group.

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

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:

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

Compute inner product of two vectors in tangent space at base point.

Parameters:
• tangent_vec_a (array-like, shape=[…, n, n]) – First tangent vector at base_point.

• tangent_vec_b (array-like, shape=[…, n, n]) – Second tangent vector at base_point.

• base_point (array-like, shape=[…, n, n]) – Point in the group. Optional, defaults to identity if None.

Returns:

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

inner_product_at_identity(tangent_vec_a, tangent_vec_b)[source]#

Compute inner product at tangent space at identity.

Parameters:
• tangent_vec_a (array-like, shape=[…, {dim, [n, n]}]) – First tangent vector at identity.

• tangent_vec_b (array-like, shape=[…, {dim, [n, n]}]) – Second tangent vector at identity.

Returns:

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

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

Compute Riemannian logarithm of a point wrt the identity.

For a bi-invariant metric this corresponds to the group logarithm.

Parameters:
• point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group.

• base_point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group. Optional, default : identity.

Returns:

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

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

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

Compute the parallel transport of a tangent vec along a geodesic.

Closed-form solution for the parallel transport of a tangent vector a along the geodesic between the base point and an end point, or alternatively defined by $$t \mapsto exp_{(base\_point)}(t*direction)$$. As a compact Lie group endowed with its canonical bi-invariant metric is a symmetric space, parallel transport is achieved by a geodesic symmetry, or equivalently, one step of the pole ladder scheme.

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

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

• direction (array-like, shape=[…, n, n]) – Tangent vector at base point, along which the parallel transport is computed. Optional, default: None.

• end_point (array-like, shape=[…, n, n]) – Point on the manifold. Point to transport to. Optional, default: None.

Returns:

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

class geomstats.geometry.invariant_metric.InvariantMetric(group, metric_mat_at_identity=None, left_or_right='left', point_type=None)[source]#

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:
• group (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_or_right (str, {‘left’, ‘right’}) – Whether to use a left or right invariant metric. Optional, default: ‘left’.

• point_type (str, {‘vector’, ‘matrix’}) – Point representation. Optional, default: group.default_point_type.

### Sasaki Metric#

Class for the Sasaki metric.

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

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

class geomstats.geometry.sasaki_metric.SasakiMetric(metric: RiemannianMetric, n_jobs: int = 1)[source]#

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

The Sasaki metric is characterized by the following three properties:

• the canonical projection of TM becomes a Riemannian submersion,

• parallel vector fields along curves are orthogonal to their fibres, and

• its restriction to any tangent space is Euclidean.

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

Parameters:
• metric (RiemannianMetric) – Metric of the base manifold of the tangent bundle.

• n_jobs (int) – Number of jobs for parallel computing. Optional, default: 1.

References

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

Compute the Riemannian exponential of a point.

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

Parameters:
• tangent_vec (array-like, shape=[…, 2, M.dim]) – Tangent vector in TTM at the base point in TM.

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

• n_steps (int) – Number of discrete time steps. Optional, default: N_STEPS.

Returns:

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

geodesic_discrete(initial_points, end_points, n_steps=3, **kwargs)[source]#

Compute Sakai geodesic employing a variational time discretization.

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

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

• n_steps (int) – n_steps - 1 is the number of intermediate points in the discretization of the geodesic from initial_point to end_point Optional, default: N_STEPS.

Returns:

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

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

Inner product between two tangent vectors at a base point.

Parameters:
• tangent_vec_a (array-like, shape=[…, 2, M.dim]) – Tangent vector in TTM of the tangent bundle TM.

• tangent_vec_b (array-like, shape=[…, 2, M.dim]) – Tangent vector in TTM of the tangent bundle TM.

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

Returns:

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

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

Compute the Riemannian logarithm of a point.

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

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

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

• n_steps (int) – Number of discrete time steps. Optional, default: N_STEPS.

Returns:

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

### Sub Riemannian Metric#

Sub-Riemannian metrics.

class geomstats.geometry.sub_riemannian_metric.SubRiemannianMetric(dim, dist_dim, default_point_type='vector')[source]#

Class for Sub-Riemannian metrics.

This implementation assumes a distribution of constant dimension.

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

• dist_dim (int) – Dimension of the distribution

• default_point_type (str, {‘vector’, ‘matrix’}) – Point type. Optional, default: ‘vector’.

abstract cometric_matrix(base_point=None)[source]#

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

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

Parameters:

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

Returns:

mat (array-like, shape=[…, dim, dim]) – Inverse of inner-product matrix.

cometric_sub_matrix(base_point)[source]#

Cometric sub matrix of dimension dist_dim x dist_dim.

Let {X_i}, i = 1, .., dist_dim, be an arbitrary frame for the distribution and let g be the sub-Riemannian metric. Then cometric_sub_matrix is the matrix given by the inverse of the matrix g_ij = g(X_i, X_j), where i,j = 1, .., dist_dim.

Parameters:

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

Returns:

_ (array-like, shape=[…, dist_dim, dist_dim]) – Cometric submatrix.

exp(cotangent_vec, base_point, n_steps=20, **kwargs)[source]#

Exponential map associated to the cometric.

Exponential map at base_point of cotangent_vec computed by integration of the Hamiltonian equation (initial value problem), using the cometric. In the Riemannian case this yields the exponential associated to the Levi-Civita connection of the metric (the inverse of the cometric).

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

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

• n_steps (int) – Number of discrete time steps to take in the integration. Optional, default: N_STEPS.

Returns:

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

frame(point)[source]#

Frame field for the distribution.

The frame field spans the distribution at point. The frame field is represented as a matrix, whose columns are the frame field vectors.

Parameters:

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

Returns:

_ (array-like, shape=[…, dim, dist_dim]) – Frame field matrix.

hamiltonian(state)[source]#

Compute the hamiltonian energy associated to the cometric.

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

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

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

Parameters:

state (tuple of arrays) – Position and momentum variables. Position is a point on the manifold, while the momentum is cotangent vector.

Returns:

energy (float) – Hamiltonian energy at state.

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

Compute inner coproduct between two cotangent vectors at base point.

This is the inner product associated to the cometric matrix.

Parameters:
• cotangent_vec_a (array-like, shape=[…, dim]) – Cotangent vector at base_point.

• cotangent_vec_b (array-like, shape=[…, dim]) – Cotangent vector at base_point.

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

Returns:

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

static iterate(func, n_steps)[source]#

Construct a function which iterates another function n_steps times.

Parameters:
• func (callable) – A function which calculates the next step of a sequence to be calculated.

• n_steps (int) – The number of times to iterate func.

Returns:

flow (callable) – Given a state, ‘flow’ returns a sequence with n_steps iterations of func.

metric_matrix(base_point)[source]#

Metric matrix at the tangent space at a base point.

This is a sub-Riemannian metric, so it is assumed to satisfy the conditions of an inner product only on each distribution subspace.

Parameters:

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

Returns:

_ (array-like, shape=[…, dim, dim]) – Inner-product matrix.

symp_euler(step_size)[source]#

Compute a function which calculates a step of symplectic euler integration.

The output function computes a symplectic euler step of the Hamiltonian system of equations associated with the cometric and obtained by the method symp_grad().

Parameters:

step_size (float) – Step size of the symplectic euler step.

Returns:

step (callable) – Given a state, ‘step’ returns the next symplectic euler step.

symp_flow(end_time=1.0, n_steps=20)[source]#

Compute the symplectic flow of the hamiltonian.

Parameters:
• hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.

• end_time (float) – The last time point until which to calculate the flow.

• n_steps (int) – Number of integration steps.

Returns:

_ (array-like, shape[,n_steps]) – Given a state, ‘symp_flow’ returns a sequence with n_steps iterations of func.

Compute the symplectic gradient of the Hamiltonian.

Parameters:

hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.

Returns:

vector (array-like, shape=[, 2*dim]) – The symplectic gradient of the Hamiltonian.

## Connections#

Affine connections.

class geomstats.geometry.connection.Connection(dim, shape=None, default_coords_type='intrinsic')[source]#

Class for affine connections.

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

• shape (tuple of int) – Shape of one element of the manifold. Optional, default : (dim, ).

• default_coords_type (str, {'intrinsic', 'extrinsic', etc}) – Coordinate type. Optional, default: 'intrinsic'.

christoffels(base_point)[source]#

Christoffel symbols associated with the connection.

Parameters:

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

Returns:

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

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

Compute the curvature.

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

Parameters:
• tangent_vec_a (array-like, shape=[…, {dim, [n, m]}]) – Tangent vector at base_point.

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

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

• base_point (array-like, shape=[…, {dim, [n, m]}]) – Point on the group. Optional, default is the identity.

Returns:

curvature (array-like, shape=[…, {dim, [n, m]}]) – 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 vectors fields $$H|_P = tangent\_vec\_a, X|_P = tangent\_vec\_b, Y|_P = tangent\_vec\_c, Z|_P = tangent\_vec\_d$$ with tangent vector value specified in argument at the base point P, the covariant derivative of the curvature $$(\nabla_H R)(X, Y) Z |_P$$ is computed at the base point P.

Parameters:
• tangent_vec_a (array-like, shape=[…, {dim, [n, m]}]) – Tangent vector at base_point.

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

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

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

• base_point (array-like, shape=[…, {dim, [n, m]}]) – Point on the group. Optional, default is the identity.

Returns:

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

property default_point_type#

Point type.

vector or matrix.

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

Compute the directional curvature (tidal force operator).

For two vectors fields $$X|_P = tangent\_vec\_a$$, and $$Y|_P = tangent\_vec\_b$$ with tangent vector specified in argument at the base point $$P$$, 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 two vectors fields $$X|_P = tangent\_vec\_a, Y|_P = tangent\_vec\_b$$ with tangent vector value specified in argument at the base point P, the covariant derivative (in the direction X) $$(\nabla_X R_Y)(X) |_P = (\nabla_X R)(Y, X) Y |_P$$ of the directional curvature (in the direction Y) $$R_Y(X) = R(Y, X) Y$$ is a quadratic tensor in X and Y that plays an important role in the computation of the moments of the empirical Fréchet mean.

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, n_steps=100, step='euler', **kwargs)[source]#

Exponential map associated to the affine connection.

Exponential map at base_point of tangent_vec computed by integration of the geodesic equation (initial value problem), using the christoffel symbols.

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

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

• n_steps (int) – Number of discrete time steps to take in the integration. Optional, default: N_STEPS.

• step (str, {‘euler’, ‘rk4’}) – The numerical scheme to use for integration. Optional, default: ‘euler’.

Returns:

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

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

Generate parameterized function for the geodesic curve.

Geodesic curve defined by either:

• an initial point and an initial tangent vector,

• an initial point and an end point.

Parameters:
• initial_point (array-like, shape=[…, dim]) – Point on the manifold, initial point of the geodesic.

• end_point (array-like, shape=[…, dim], optional) – Point on the manifold, end point of the geodesic. If None, an initial tangent vector must be given.

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

Returns:

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

geodesic_equation(state, _time)[source]#

Compute the geodesic ODE associated with the connection.

Parameters:
• state (array-like, shape=[…, dim]) – Tangent vector at the position.

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

Returns:

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

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:

ladder_parallel_transport(tangent_vec, base_point, direction, n_rungs=1, scheme='pole', alpha=1, **single_step_kwargs)[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

• **single_step_kwargs (keyword arguments for the step functions)

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, n_steps=100, step='euler', max_iter=25, verbose=False, tol=1e-12)[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).