Geometry#

Manifolds#

Manifold#

Manifold module.

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

Lead author: Nina Miolane.

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

Class for manifolds.

Parameters:

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

point_ndim#

Dimension of point array.

Type:: int

default_point_type#

Point type: “vector” or “matrix”.

Type:: str

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

Evaluate if a point belongs to the manifold.

Parameters:

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

Returns:

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

equip_with_group_action(group_action)[source]#

Equip manifold with group action.

Parameters:: group_action (str) – Group action.

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

Equip manifold with a Riemannian metric.

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

equip_with_quotient_structure()[source]#

Equip manifold with quotient structure.

Creates attributes quotient and fiber_bundle.

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

Check whether the vector is tangent at base_point.

Parameters:

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

Returns:

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

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

Sample random points on the manifold according to some distribution.

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

Parameters:

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

Returns:

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

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

Generate random tangent vec.

Parameters:

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

Returns:

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

regularize(point)[source]#

Regularize a point to the canonical representation for the manifold.

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

abstract to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

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

Returns:

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

Embedded Manifold#

Product Manifold#

Product of manifolds.

Lead author: Nicolas Guigui, John Harvey.

class geomstats.geometry.product_manifold.ProductManifold(factors, default_point_type='auto', equip=True)[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.

Parameters:

factors (list) – List of manifolds in the product.
default_point_type ({‘auto’, ‘vector’, ‘matrix’, ‘other’}) – Optional. Default value is ‘auto’, which will implement as ‘vector’ unless all factors have the same shape. Vector representation gives the point as a 1-d array. Matrix representation allows for a point to be represented by an array of shape (n, dim), if each manifold has default_point_type ‘vector’ with shape (dim,). ‘other’ will behave as matrix but for higher dimensions.

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

Test if a point belongs to the manifold.

Parameters:

point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point.
atol (float,) – Tolerance.

Returns:

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

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

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

Check whether the vector is tangent at base_point.

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

Parameters:

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

Returns:

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

projection(point)[source]#

Project a point onto product manifold.

Parameters:: point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point in product manifold.
Returns:: projected (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Projected point.

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

Sample in the product space from the product distribution.

The distribution used is the product of the distributions used by the random_point methods of each individual factor manifold.

Parameters:

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

Returns:

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

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

Sample on the tangent space from the product distribution.

The distribution used is the product of the distributions used by the random_tangent_vec methods of each individual factor manifold.

Parameters:

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

Returns:

samples (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Points sampled in the tangent space of the product manifold at base_point.

regularize(point)[source]#

Regularize the point into the manifold’s canonical representation.

Parameters:: point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point to be regularized.
Returns:: regularized_point (array-like, shape=[…, {dim, embedding_space.dim,) – [n_manifolds, dim_each]}] Point in the manifold’s canonical representation.

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Parameters:

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

Returns:

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

Notes

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

class geomstats.geometry.product_manifold.ProductRiemannianMetric(space)[source]#

Class for product of Riemannian metrics.

property default_point_type#: Point type of space.

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

Compute the Riemannian exponential of a tangent vector.

Parameters:

tangent_vec (array-like, shape=[…, self.shape]) – Tangent vector at a base point.
base_point (array-like, shape=[…, self.shape]) – Point on the manifold. Optional, default: None.

Returns:

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

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=[…, self.shape]) – First tangent vector at base point.
tangent_vec_b (array-like, shape=[…, self.shape]) – Second tangent vector at base point.
base_point (array-like, shape=[…, self.shape]) – Point on the manifold. Optional, default: None.

Returns:

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

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

Compute the Riemannian logarithm of a point.

Parameters:

point (array-like, shape=[…, self.shape]) – Point on the manifold.
base_point (array-like, shape=[…, self.shape]) – Point on the manifold. Optional, default: None.

Returns:

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

metric_matrix(base_point=None)[source]#

Compute the matrix of the inner-product.

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

Parameters:: base_point (array-like, shape=[…, self.shape]) – Point on the manifold at which to compute the inner-product matrix. Optional, default: None.
Returns:: matrix (array-like, shape as described below) – Matrix of the inner-product at the base point. The matrix is in block diagonal form with a block for each factor. Each block is the same size as the metric_matrix for that factor.

property shape#: Shape of space.

Euclidean Space#

Euclidean space.

class geomstats.geometry.euclidean.Euclidean(dim, equip=True)[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.

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

exp(tangent_vec, base_point)[source]#

Compute the group exponential, which is simply the addition.

Parameters:

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

Returns:

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

property identity#

Identity of the group.

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

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

Class for Euclidean metrics.

As a Riemannian metric, the Euclidean metric is:

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

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

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

The Riemannian exponential is vector addition in the Euclidean space.

Parameters:

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

Returns:

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

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

Inner product between two tangent vectors at a base point.

Parameters:

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

Returns:

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

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

Compute log map using a base point and other point.

The Riemannian logarithm is the subtraction in the Euclidean space.

Parameters:

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

Returns:

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

metric_matrix(base_point=None)[source]#

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

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

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

Compute norm of a vector.

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

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

Parameters:

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

Returns:

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

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

Compute the parallel transport of a tangent vector.

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

Parameters:

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

Returns:

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

Minkowski Space#

Minkowski space.

Lead author: Nina Miolane.

class geomstats.geometry.minkowski.Minkowski(dim, equip=True)[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(space)[source]#

Class for the pseudo-Riemannian Minkowski metric.

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

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

Compute the Riemannian exponential of tangent_vec at base_point.

The Riemannian exponential is the addition in the Minkowski space.

Parameters:

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

Returns:

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

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

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

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

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

Inner product between two tangent vectors at a base point.

Parameters:

tangent_vec_a (array-like, shape=[…, 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.

Lead author: Nina Miolane.

class geomstats.geometry.hypersphere.Hypersphere(dim, default_coords_type='extrinsic', equip=True)[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(space, signature=None)[source]#

Class for the Hypersphere Metric.

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.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

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

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

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

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

Parameters:

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

Returns:

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

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

Compute the Riemannian logarithm of a point.

Parameters:

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

Returns:

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

metric_matrix(base_point=None)[source]#

Metric matrix at the tangent space at a base point.

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

norm_factor_gradient(variances)[source]#

Compute the gradient of the normalization factor.

Parameters:: variances (array-like, shape=[n,]) – Variance of the distribution.
Returns:: norm_func (array-like, shape=[n,]) – Normalisation factor for all given variances.

normalization_factor(variances)[source]#

Return normalization factor of the Gaussian distribution.

Parameters:: variances (array-like, shape=[n,]) – Variance of the distribution.
Returns:: norm_func (array-like, shape=[n,]) – Normalisation factor for all given variances.

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

Compute the parallel transport of a tangent vector.

Parameters:

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

Returns:

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

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

Squared geodesic distance between two points.

Parameters:

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

Returns:

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

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

Compute the squared norm of a vector.

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

Parameters:

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

Returns:

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

Hyperbolic Space#

Common interface to hyperbolic spaces.

Lead author: Thomas Gerald.

class geomstats.geometry.hyperbolic.Hyperbolic(dim, default_coords_type='extrinsic', equip=True)[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 as the set of points whose squared norm is equal to -1. This representation is called extrinsic here.
the Poincare ball, the open ball of the Euclidean space of dimension dim.
the Poincare half-space, the open space of points of the Euclidean space of dimension dim, whose last coordinate is positive.

Parameters:

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

Discretized Curves Space#

Symmetric-Positive-Definite (SPD) Matrices Space#

The manifold of symmetric positive definite (SPD) matrices.

Lead author: Yann Thanwerdas.

class geomstats.geometry.spd_matrices.SPDAffineMetric(space, power_affine=1)[source]#

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

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

References

[TP2019]

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

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

injectivity_radius(base_point)[source]#

Radius of the largest ball where the exponential is injective.

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

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

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

Compute the affine-invariant inner-product.

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

Parameters:

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

Returns:

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

log(point, base_point, **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.SPDBuresWassersteinMetric(space, signature=None)[source]#

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

References

[BJL2017]

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

[MMP2018]

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

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

injectivity_radius(base_point)[source]#

Compute the upper bound of the injectivity domain.

This is the smallest eigen value of the base point.

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

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

Compute the Bures-Wasserstein inner-product.

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

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

Parameters:

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

Returns:

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

log(point, base_point, **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, base_point, direction=None, end_point=None, n_steps=10, step='rk4')[source]#

Compute the parallel transport of a tangent vec along a geodesic.

Approximation of the solution of the parallel transport of a tangent vector a along the geodesic defined by \(t \mapsto exp_{( base\_point)}(t* tangent\_vec\_b)\). The parallel transport equation is formulated in this case in [TP2021].

Parameters:

tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at base_point to transport.
base_point (array-like, shape=[…, n, n]) – Initial point of the geodesic.
direction (array-like, shape=[…, n, n]) – Tangent vector at base_point, initial velocity of the geodesic to transport along.
end_point (array-like, shape=[…, n, n]) – Point to transport to. Optional, default: None.
n_steps (int) – Number of steps to use to approximate the solution of the ordinary differential equation. Optional, default: 100
step (str, {‘euler’, ‘rk2’, ‘rk4’}) – Scheme to use in the integration scheme. Optional, default: ‘rk4’.

Returns:

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

References

[TP2021]

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

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.

Lead author: Nicolas Guigui.

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

Evaluate if point is a skew-symmetric matrix.

Parameters:

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

Returns:

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

classmethod projection(mat)[source]#

Compute the skew-symmetric component of a matrix.

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

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

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

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

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

Parameters:

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

Returns:

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

Stiefel Manifold#

Stiefel manifold St(n,p).

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

Lead author: Oleg Kachan.

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

Class for Stiefel manifolds St(n,p).

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

Parameters:

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

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

projection(point)[source]#

Project a close enough matrix to the Stiefel manifold.

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

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

References

[Absil]

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

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

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

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

Parameters:

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

Returns:

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

random_uniform(n_samples=1)[source]#

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

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

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

submersion(point)[source]#

Submersion that defines the manifold.

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

tangent_submersion(vector, point)[source]#

Tangent submersion.

Parameters:

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

Returns:

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

static to_grassmannian(point)[source]#

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

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

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

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

Inspired by the method of Pymanopt.

Parameters:

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

Returns:

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

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

Class that defines the canonical metric for Stiefel manifolds.

exp(tangent_vec, base_point)[source]#

Compute the Riemannian exponential of a tangent vector.

Parameters:

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

Returns:

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

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

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

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

References

[Rentmeesters2015]

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

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

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

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

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

References

[RLSMRZ2017]

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

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.

lifting(point, base_point)[source]#

Compute the lifting of a point.

This computation is based on the QR-decomposion.

e.g. \(P_x^{-1}(Q) = QR - X\).

Parameters:

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

Returns:

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

log(point, base_point)[source]#

Compute the Riemannian logarithm of a point.

Parameters:

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

Returns:

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

Lead author: Nina Miolane.

class geomstats.geometry.lie_group.LieGroup(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

compose(point_a, point_b)[source]#

Perform function composition corresponding to the Lie group.

Multiply the elements point_a and point_b.

Parameters:

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

Returns:

composed (array-like, shape=[…, {dim, [n, n]}]) – Product of point_a and point_b along the first dimension.

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

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

Compute the group exponential at base_point of tangent_vec.

Parameters:

tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector at base point.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Base point. Optional, default: self.identity

Returns:

result (array-like, shape=[…, {dim, [n, n]}]) – Group exponential.

exp_from_identity(tangent_vec)[source]#

Compute the group exponential of tangent vector from the identity.

Parameters:: tangent_vec (array-like, shape=[…, {dim, [n, n]}]) – Tangent vector at base point.
Returns:: point (array-like, shape=[…, {dim, [n, n]}]) – Group exponential.

exp_not_from_identity(tangent_vec, base_point)[source]#

Calculate the group exponential at base_point.

Parameters:

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

Returns:

exp (array-like, shape=[…, {dim, [n, n]}]) – Group exponential.

property identity#

Identity of the group.

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

classmethod inverse(point)[source]#

Compute the inverse law of the Lie group.

Parameters:: point (array-like, shape=[…, {dim, [n, n]}]) – Point to be inverted.
Returns:: inverse (array-like, shape=[…, {dim, [n, n]}]) – Inverted point.

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

Check whether the vector is tangent at base_point.

Parameters:

vector (array-like, shape=[…, dim_embedding]) – Vector.
base_point (array-like, shape=[…, dim_embedding]) – Point in the Lie group. Optional. default: identity.
atol (float) – Precision at which to evaluate if the rotation part is skew-symmetric. Optional. default: 1e-6

Returns:

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

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

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

Compute the Jacobian matrix of the left translation by the point.

Parameters:

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

Returns:

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

lie_bracket(tangent_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=True, inverse=False)[source]#

Compute the push-forward map by the left/right translation.

Compute the push-forward map, of the left/right translation by the point. It corresponds to the tangent map, or differential of the group multiplication by the point or its inverse. For groups with a vector representation, it is only implemented at identity, but it can be used at other points by passing inverse=True. This method wraps the jacobian translation which actually computes the matrix representation of the map.

Parameters:

point (array-like, shape=[…, {dim, [n, n]]) – Point.
left (bool) – Whether to calculate the differential of left or right translations. Optional, default: True.
inverse (bool,) – Whether to inverse the jacobian matrix. If True, the push forward by the translation by the inverse of point is returned. Optional, default: False.

Returns:

tangent_map (callable) – Tangent map of the left/right translation by point. It can be applied to tangent vectors.

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

Project a vector onto the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, {dim, [n, n]}]) – Vector to project. Its shape must match the shape of base_point.
base_point (array-like, shape=[…, {dim, [n, n]}], optional) – Point of the group. Optional, default: identity.

Returns:

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

class geomstats.geometry.lie_group.MatrixLieGroup(representation_dim, lie_algebra=None, **kwargs)[source]#

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=True, inverse=False)[source]#

Compute the push-forward map by the left/right translation.

Parameters:

point (array-like, shape=[…, {dim, [n, n]]) – Point.
left (bool) – Whether to calculate the differential of left or right translations. Optional, default: True
inverse (bool,) – Whether to inverse the jacobian matrix. If True, the push forward by the translation by the inverse of point is returned. Optional, default: False.

Returns:

tangent_map (callable) – Tangent map of the left/right translation by point. It can be applied to tangent vectors.

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

Project a vector onto the tangent space at a base point.

Parameters:

vector (array-like, shape=[…, {dim, [n, n]}]) – Vector to project. Its shape must match the shape of base_point.
base_point (array-like, shape=[…, {dim, [n, n]}], optional) – Point of the group. Optional, default: identity.

Returns:

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

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

Lead author: Stefan Heyder.

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

Class implementing matrix Lie algebra related functions.

Parameters:: representation_dim (int) – Amount of rows and columns in the matrix representation of the Lie algebra.

baker_campbell_hausdorff(matrix_a, matrix_b, order=2)[source]#

Calculate the Baker-Campbell-Hausdorff approximation of given order.

The implementation is based on [CM2009a] with the pre-computed constants taken from [CM2009b]. Our coefficients are truncated to enable us to calculate BCH up to order 15.

This represents Z = log(exp(X)exp(Y)) as an infinite linear combination of the form Z = sum z_i e_i where z_i are rational numbers and e_i are iterated Lie brackets starting with e_1 = X, e_2 = Y, each e_i is given by some i’,i’’: e_i = [e_i’, e_i’’].

Parameters:

matrix_a (array-like, shape=[…, *point_shape])
matrix_b (array-like, shape=[…, *point_shape]) – Matrices.
order (int) – The order to which the approximation is calculated. Note that this is NOT the same as using only e_i with i < order. Optional, default 2.

References

[CM2009a]

F. Casas and A. Murua. An efficient algorithm for computing the Baker–Campbell–Hausdorff series and some of its applications. Journal of Mathematical Physics 50, 2009

[CM2009b]

http://www.ehu.eus/ccwmuura/research/bchHall20.dat

abstract basis_representation(matrix_representation)[source]#

Compute the coefficients of matrices in the given basis.

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

classmethod bracket(mat_a, mat_b)#

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

Parameters:

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

Returns:

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

matrix_representation(basis_representation)[source]#

Compute the matrix representation for the given basis coefficients.

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

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

Matrices Space#

Module exposing the Matrices and MatricesMetric class.

class geomstats.geometry.matrices.Matrices(m, n, equip=True)[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.

classmethod bracket(mat_a, mat_b)[source]#

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

Parameters:

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

Returns:

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

classmethod congruent(mat_1, mat_2)[source]#

Compute the congruent action of mat_2 on mat_1.

This is \(mat\_2 \ mat\_1 \ mat\_2^T\).

Parameters:

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

Returns:

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

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

static diagonal(mat)[source]#

Return the diagonal of a matrix as a vector.

Parameters:: mat (array-like, shape=[…, m, n]) – Matrix.
Returns:: diagonal (array-like, shape=[…, min(m, n)]) – Vector of diagonal coefficients.

static equal(mat_a, mat_b, atol=1e-12)[source]#

Test if matrices a and b are close.

Parameters:

mat_a (array-like, shape=[…, dim1, dim2]) – Matrix.
mat_b (array-like, shape=[…, dim2, dim3]) – Matrix.
atol (float) – Tolerance. Optional, default: backend atol.

Returns:

eq (array-like, shape=[…,]) – Boolean evaluating if the matrices are close.

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

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

classmethod to_upper_triangular(mat)[source]#

Make a matrix upper triangular.

Make a matrix upper triangular by zeroing out lower elements.

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

static trace_product(mat_1, mat_2)[source]#

Compute trace of the product of two matrices.

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

Parameters:

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

Returns:

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

static transpose(mat)[source]#

Return the transpose of matrices.

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

class geomstats.geometry.matrices.MatricesMetric(space, signature=None)[source]#

Euclidean metric on matrices given by Frobenius inner-product.

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

Compute Frobenius inner-product of two tangent vectors.

Parameters:

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

Returns:

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

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

Compute norm of a matrix.

Norm of a matrix associated to the Frobenius inner product.

Parameters:

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

Returns:

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

General Linear Group#

Module exposing the GeneralLinear group class.

class geomstats.geometry.general_linear.GeneralLinear(n, positive_det=False, equip=True)[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).

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

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

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

Parameters:

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

Returns:

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

Notes

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

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

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

Vectorization#

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

projection(point)[source]#

Project a matrix to the general linear group.

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

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

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

Sample in GL(n) from the normal distribution.

Parameters:

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

Returns:

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

class geomstats.geometry.general_linear.SquareMatrices(n)[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, equip=True)[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.SpecialEuclideanMatrixCanonicalLeftMetric(space)[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:: space (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.

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, equip=True)[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.

Lead author: Anna Calissano.

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(space, base_graph, graph_to_permute)[source]#

Align graphs.

Parameters:

space (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(space, base_graph, graph_to_permute)[source]#

Align graphs.

Parameters:

space (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.GraphPoint(adj)[source]#

Class for the GraphPoint.

Points are represented by \(nodes \times nodes\) adjacency matrices.

Parameters:: adj (array-like, shape=[n_nodes, n_nodes]) – Adjacency matrix.

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, equip=True)[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]

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

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

pad_with_zeros(points)[source]#

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]

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]

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]

[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(space, base_graph, graph_to_permute)[source]#

Align graphs.

Parameters:

space (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:

space (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]

[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(space, 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(space, geodesic, graph_to_permute)[source]#

Compute the distance between the geodesic and the point.

Parameters:

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

Lead author: Olivier Peltre.

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

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

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

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

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

References

[Batzies15]

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

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

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

Parameters:

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

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

projection(point)[source]#

Project a matrix to the Grassmann manifold.

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

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

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

Sample random points from a uniform distribution.

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

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

References

[Chikuse03]

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

random_uniform(n_samples=1)[source]#

Sample random points from a uniform distribution.

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

References

[Chikuse03]

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

submersion(point)[source]#

Submersion that defines the Grassmann manifold.

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

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

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

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

References

[Pau07]

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

tangent_submersion(vector, point)[source]#

Tangent submersion.

Parameters:

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

Returns:

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

to_tangent(vector, base_point)[source]#

Project a vector to a tangent space of the manifold.

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

Parameters:

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

Returns:

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

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

Canonical metric of the Grassmann manifold.

Coincides with the Frobenius metric.

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

Exponentiate the invariant vector field v from base point p.

Parameters:

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

Returns:

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

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

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

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

References

[BZA20]

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

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

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

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

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

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

Parameters:

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

Returns:

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

References

[Batzies2015]

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

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

Compute the parallel transport of a tangent vector.

Parameters:

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

Returns:

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

References

[BZA20]

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

Squared geodesic distance between two points.

Parameters:

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

Returns:

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

Landmarks Space#

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

Lead author: Nicolas Guigui.

class geomstats.geometry.landmarks.L2LandmarksMetric(space, scales=None)[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.

class geomstats.geometry.landmarks.Landmarks(ambient_manifold, k_landmarks, equip=True)[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.

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

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.

Lead author: Yann Cabanes.

References

[JV2016]

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

class geomstats.geometry.poincare_polydisk.PoincarePolydisk(n_disks, equip=True)[source]#

Class for the Poincare polydisk.

The Poincare polydisk is a direct product of n Poincare disks, i.e. hyperbolic spaces of dimension 2.

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

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

static intrinsic_to_extrinsic_coords(point_intrinsic)[source]#

Convert point from intrinsic to extrensic coordinates.

Convert the parameterization of a point in the hyperbolic space from its intrinsic coordinates, to its extrinsic coordinates in Minkowski space.

Parameters:: point_intrinsic (array-like, shape=[…, n_disk, dim]) – Point in intrinsic coordinates.
Returns:: point_extrinsic (array-like, shape=[…, n_disks, dim + 1]) – Point in extrinsic coordinates.

class geomstats.geometry.poincare_polydisk.PoincarePolydiskMetric(space)[source]#

Class defining the Poincare polydisk metric.

The Poincare polydisk metric is a product of n Poincare metrics, each of them being multiplied by a specific constant factor (see [JV2016]).

This metric comes from a model used to represent stationary complex autoregressive Gaussian signals.

References

[JV2016]

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

Lower Triangular Matrices#

The vector space of lower triangular matrices.

Lead author: Saiteja Utpala.

class geomstats.geometry.lower_triangular_matrices.LowerTriangularMatrices(n, equip=True)[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.

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

from_vector(vec)[source]#

Convert a vector into a lower triangular matrix.

Parameters:: vec (array-like, shape=[…, n(n+1)/2]) – Vector.
Returns:: mat (array-like, shape=[…, n, n]) – Lower triangular matrix.

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.

Lead author: Saiteja Utpala.

class geomstats.geometry.positive_lower_triangular_matrices.CholeskyMetric(space, signature=None)[source]#

Class for Cholesky metric on Cholesky space.

References

[TP2019]

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

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

Compute the inner product using only diagonal elements.

Parameters:

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

Returns:

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

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

Compute the Cholesky exponential map.

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

Parameters:

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

Returns:

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

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

Compute the inner product.

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

Parameters:

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

Returns:

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

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

Compute the Cholesky logarithm map.

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

Parameters:

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

Returns:

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

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

Compute the Cholesky Metric squared distance.

Compute the Riemannian squared distance between point_a and point_b.

Parameters:

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

Returns:

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

static strictly_lower_inner_product(tangent_vec_a, tangent_vec_b)[source]#

Compute the inner product using only strictly lower triangular elements.

Parameters:

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

Returns:

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

class geomstats.geometry.positive_lower_triangular_matrices.PositiveLowerTriangularMatrices(n, equip=True)[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 default_metric()[source]#: Metric to equip the space with if equip is True.

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.
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]) – Tangent vector at gram(base_point).
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. Optional, default: 1.0

Returns:

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

Metrics#

Riemannian Metric#

Riemannian and pseudo-Riemannian metrics.

Lead author: Nina Miolane.

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

Class for Riemannian and pseudo-Riemannian metrics.

The associated Levi-Civita connection on the tangent bundle.

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.

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

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

closest_neighbor_index(point, neighbors)[source]#

Closest neighbor of point among neighbors.

Parameters:

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

Returns:

closest_neighbor_index (int) – Index of closest neighbor.

cometric_matrix(base_point=None)[source]#

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

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

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

covariant_riemann_tensor(base_point)[source]#

Compute purely covariant version of Riemannian tensor at base_point.

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

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

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

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

diameter(points)[source]#

Give the distance between two farthest points.

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

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

dist(point_a, point_b, **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.

dist_broadcast(point_a, point_b)[source]#

Compute the geodesic distance between points.

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

Parameters:

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

Returns:

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

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

Compute the pairwise distance between points.

Parameters:

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

Returns:

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

Product Riemannian Metric#

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(space)[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:: space (LieGroup) – The group to equip with the bi-invariant metric

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

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

Compute Riemannian exponential of tangent vector from the identity.

For a bi-invariant metric, this corresponds to the group exponential.

Parameters:

tangent_vec – Tangent vector at identity.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group. Optional, default : identity.

Returns:

exp (array-like, shape=[…, {dim, [n, n]}]) – Point in the group.

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image. In the case of a bi-invariant metric, it does not depend on the base point.

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

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

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

Parameters:

tangent_vec_a (array-like, shape=[…, n, n]) – First tangent vector at base_point.
tangent_vec_b (array-like, shape=[…, n, n]) – Second tangent vector at base_point.
base_point (array-like, shape=[…, n, n]) – Point in the group. Optional, defaults to identity if None.

Returns:

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

inner_product_at_identity(tangent_vec_a, tangent_vec_b)[source]#

Compute inner product at tangent space at identity.

Parameters:

tangent_vec_a (array-like, shape=[…, {dim, [n, n]}]) – First tangent vector at identity.
tangent_vec_b (array-like, shape=[…, {dim, [n, n]}]) – Second tangent vector at identity.

Returns:

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

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

Compute Riemannian logarithm of a point wrt the identity.

For a bi-invariant metric this corresponds to the group logarithm.

Parameters:

point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group.
base_point (array-like, shape=[…, {dim, [n, n]}]) – Point in the group. Optional, default : identity.

Returns:

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

References

[Gallier]

Gallier, Jean, and Jocelyn Quaintance. Differential Geometry and Lie Groups: A Computational Perspective. Geonger International Publishing, 2020. https://doi.org/10.1007/978-3-030-46040-2.

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

Compute the parallel transport of a tangent vec along a geodesic.

Closed-form solution for the parallel transport of a tangent vector a along the geodesic between the base point and an end point, or alternatively defined by \(t \mapsto exp_{(base\_point)}(t*direction)\). As a compact Lie group endowed with its canonical bi-invariant metric is a symmetric space, parallel transport is achieved by a geodesic symmetry, or equivalently, one step of the pole ladder scheme.

Parameters:

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

Returns:

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

class geomstats.geometry.invariant_metric.InvariantMetric(space, metric_mat_at_identity=None, left=True)[source]#

Class for invariant metrics on Lie groups.

This class supports both left and right invariant metrics which exist on Lie groups.

If point_type == ‘vector’, points are parameterized by the Riemannian logarithm for the canonical left-invariant metric.

Parameters:

space (LieGroup) – Group to equip with the invariant metric
metric_mat_at_identity (array-like, shape=[dim, dim]) – Matrix that defines the metric at identity. Optional, defaults to identity matrix if None.
left (bool) – Whether to use a left or right invariant metric. Optional, default: True.

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(space, n_jobs=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:

space (Manifold) – 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#

Implementation of sub-Riemannian geometry.

Lead author: Morten Pedersen.

class geomstats.geometry.sub_riemannian_metric.SubRiemannianMetric(space, cometric_matrix=None, frame=None)[source]#

Class for Sub-Riemannian metrics.

This implementation assumes a bracket-generating distribution of constant dimension.

Only one of the arguments ‘cometric_matrix’ and ‘frame’ can be different from None. If the frame is supplied, it is assumed orthonormal.

Parameters:

space (Manifold object)
cometric_matrix (callable) – Optional, default: ‘None’

The cometric matrix as a function of a point.

You should pass :
base_point : array-like, shape=[…, dim]

It returns:
_ : array-like, shape=[…, dim, dim]
frame (callable) – Optional, default: ‘None’

Matrix representing the frame spanning the distribution, as a function of a point.

You should pass:
point : array-like, shape=[…, dim]

It returns

_array-like, shape=[…, dim, dist_dim]
Frame field matrix. Each column is a vector field of the frame spanning the distribution.

exp(cotangent_vec, base_point, n_steps=20, **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.
point_type (str, {‘vector’, ‘matrix’}) – Type of representation used for points. Optional, default: None.

Returns:

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

geodesic(initial_point, initial_cotangent_vec, n_steps=20)[source]#

Generate parameterized function for the normal geodesic curve.

Normal geodesic curve defined by an initial point and an initial cotangent vector.

Parameters:

initial_point (array-like, shape=[…, dim]) – Point on the manifold, initial point of the geodesic.
initial_cotangent_vec (array-like, shape=[…, dim],) – Cotangent vector at base point, the initial speed of the geodesics.

Returns:

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

hamiltonian(state)[source]#

Compute the hamiltonian energy associated to the cometric.

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

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

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

Parameters:: state (array-like, shape=[[…, dim], […, dim]]) – The first array in ‘state’ contains positions, the second contains covectors (momentums).
Returns:: energy (float) – Hamiltonian energy at state.

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

Compute inner coproduct between two cotangent vectors at base point.

This is the inner product associated to the cometric matrix.

Parameters:

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

Returns:

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

static iterate(func, n_steps)[source]#

Construct a function which iterates another function n_steps times.

Parameters:

func (callable) – A function which calculates the next step of a sequence to be calculated.
n_steps (int) – The number of times to iterate func.

Returns:

flow (callable) – Given a state, ‘flow’ returns a sequence with n_steps iterations of func.

sr_sharp(base_point, cotangent_vec)[source]#

Compute sub-Riemannian sharp map.

This is the sub-Riemannian sharp map, mapping a covector at base_point to a tangent vector in the distribution subspace at base_point. For an orthonormal frame (F_i)_{i=1..dist_dim}, the sharp map is given by

\[\sharp(q, p) = \sum_i^{dist_dim} p(F_i(q)) * F_i(q)\]

Parameters:

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

Returns:

sr_sharp (array-like, shape=[…, dim]) – sub-Riemannian sharp of ‘cotangent_vec’ at ‘base_point’

symp_euler(hamiltonian, step_size)[source]#

Compute a function which calculates a step of symplectic euler integration.

Parameters:

hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.
step_size (float) – Step size of the symplectic euler step

Returns:

step (callable) – Given a state, ‘step’ returns the next symplectic euler step

symp_flow(hamiltonian, end_time=1.0, n_steps=20)[source]#

Compute the symplectic flow of the hamiltonian.

Parameters:

hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.
end_time (float) – The last time point until which to calculate the flow.
n_steps (int) – Number of integration steps.

Returns:

_ (array-like, shape[,n_steps]) – Given a state, ‘symp_flow’ returns a sequence with n_steps iterations of func.

static symp_grad(hamiltonian)[source]#

Compute the symplectic gradient of the Hamiltonian.

Parameters:: hamiltonian (callable) – The hamiltonian function from the tangent bundle to the reals.
Returns:: vector (array-like, shape=[, 2*dim]) – The symplectic gradient of the Hamiltonian.

Connections#

Affine connections.

Lead author: Nicolas Guigui.

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

Class for affine connections.

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

christoffels(base_point)[source]#

Christoffel symbols associated with the connection.

The contravariant index is on the first dimension.

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

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

Compute the Riemann curvature map R.

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

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

Parameters:

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

Returns:

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

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

Compute the covariant derivative of the curvature.

For four tangent vectors at base_point \(P\): - \(H|_P = tangent\_vec\_a\), - \(X|_P = tangent\_vec\_b\), - \(Y|_P = tangent\_vec\_c\), - \(Z|_P = tangent\_vec\_d\), the covariant derivative of the curvature is defined as: \((\nabla_H R)(X, Y) Z |_P\).

Parameters:

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

Returns:

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

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

Compute the directional curvature (tidal force operator).

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

Parameters:

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

Returns:

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

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

Compute the covariant derivative of the directional curvature.

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

References

[Pennec]

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

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

injectivity_radius(base_point)[source]#

Compute the radius of the injectivity domain.

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

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

ladder_parallel_transport(tangent_vec, base_point, direction, n_rungs=1, scheme='pole', alpha=1, **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.

Parameters:

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

Returns:

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

ricci_tensor(base_point)[source]#

Compute Ricci curvature tensor at base_point.

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

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

riemann_tensor(base_point)[source]#

Compute Riemannian tensor at base_point.

In the literature the riemannian curvature tensor is noted \(R_{ijk}^l\).

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

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

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

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