# Geometry¶

## Manifolds¶

### Manifold¶

Manifold module.

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

class geomstats.geometry.manifold.Manifold(dim, default_point_type='vector', default_coords_type='intrinsic')[source]

Class for manifolds.

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

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

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

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

Evaluate if a point belongs to the manifold.

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

• atol (float) – Absolute tolerance. Optional, default: 1e-6.

Returns

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

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

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

• atol (float) – Absolute tolerance. Optional, default: 1e-6.

Returns

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

regularize(point)[source]

Regularize a point to the canonical representation for the manifold.

Parameters

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

Returns

regularized_point (array-like, shape=[…, dim]) – Regularized point.

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

### Embedded Manifold¶

Manifold embedded in another manifold.

class geomstats.geometry.embedded_manifold.EmbeddedManifold(dim, embedding_manifold, default_point_type='vector', default_coords_type='intrinsic')[source]

Class for manifolds embedded in an embedding manifold.

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

• embedding_manifold (Manifold) – Embedding manifold.

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

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

extrinsic_to_intrinsic_coords(point_extrinsic)[source]

Convert from extrinsic to intrinsic coordinates.

Parameters

point_extrinsic (array-like, shape=[…, dim_embedding]) – Point in the embedded manifold in extrinsic coordinates, i. e. in the coordinates of the embedding manifold.

Returns

point_intrinsic (array-lie, shape=[…, dim]) – Point in the embedded manifold in intrinsic coordinates.

intrinsic_to_extrinsic_coords(point_intrinsic)[source]

Convert from intrinsic to extrinsic coordinates.

Parameters

point_intrinsic (array-like, shape=[…, dim]) – Point in the embedded manifold in intrinsic coordinates.

Returns

point_extrinsic (array-like, shape=[…, dim_embedding]) – Point in the embedded manifold in extrinsic coordinates.

projection(point)[source]

Project a point in embedding manifold on embedded manifold.

Parameters

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

Returns

Projected point.

### Product Manifold¶

Product of manifolds.

class geomstats.geometry.product_manifold.ProductManifold(manifolds, default_point_type='vector', n_jobs=1)[source]

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

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

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

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

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

• default_point_type (str, {‘vector’, ‘matrix’}) – Default representation of points. Optional, default: ‘vector’.

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

random_uniform(n_samples, point_type=None)[source]

Sample in the product space from the uniform distribution.

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

• point_type (str, {‘vector’, ‘matrix’}) – Representation of point. Optional, default: None.

Returns

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

### Euclidean Space¶

Euclidean space.

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

Class for Euclidean spaces.

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

Parameters

dim (int) – Dimension of the Euclidean space.

belongs(point)[source]

Evaluate if a point belongs to the Euclidean space.

Parameters

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

Returns

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

exp(tangent_vec, base_point=None)[source]

Compute the group exponential, which is simply the addition.

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

• base_point (array-like, shape=[…, n]) – Point from which the exponential is computed.

Returns

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

get_identity(point_type=None)[source]

Get the identity of the group.

Parameters

point_type (str, {‘vector’, ‘matrix’}) – The point_type of the returned value. Optional, default: self.default_point_type

Returns

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

property identity

Get the identity of the group.

Parameters

point_type (str, {‘vector’, ‘matrix’}) – The point_type of the returned value. Optional, default: self.default_point_type

Returns

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

random_uniform(n_samples=1, bound=1.0)[source]

Sample in the Euclidean space with the uniform distribution.

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

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

Returns

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

class geomstats.geometry.euclidean.EuclideanMetric(dim, default_point_type='vector')[source]

Class for Euclidean metrics.

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

Parameters

dim (int) – Dimension of the Euclidean space.

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

log(point, base_point)[source]

Compute log map using a base point and other point.

The Riemannian logarithm is the subtraction in the Euclidean space.

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

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

Returns

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

### Minkowski Space¶

Minkowski space.

class geomstats.geometry.minkowski.Minkowski(dim)[source]

Class for Minkowski space.

Parameters

dim (int) – Dimension of Minkowski space.

belongs(point)[source]

Evaluate if a point belongs to the Minkowski space.

Parameters

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

Returns

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

random_uniform(n_samples=1, bound=1.0)[source]

Sample in the Minkowski space from the uniform distribution.

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

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

Returns

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

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

Class for the pseudo-Riemannian Minkowski metric.

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

Parameters

dim (int) – Dimension of the Minkowski space.

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

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

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

### Hypersphere¶

The n-dimensional hypersphere.

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

class geomstats.geometry.hypersphere.Hypersphere(dim)[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.

Parameters

dim (int) – Dimension of the hypersphere.

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

Class for the Hypersphere Metric.

Parameters

dim (int) – Dimension of the hypersphere.

christoffels(point, point_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.

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

dist(point_a, point_b)[source]

Compute the geodesic distance between two points.

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

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

Returns

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

exp(tangent_vec, base_point)[source]

Compute the Riemannian exponential of a tangent vector.

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

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

Returns

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

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.

static parallel_transport(tangent_vec_a, tangent_vec_b, base_point)[source]

Compute the parallel transport of a tangent vector.

Closed-form solution for the parallel transport of a tangent vector a along the geodesic defined by exp_(base_point)(tangent_vec_b).

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

• tangent_vec_b (array-like, shape=[…, dim + 1]) – Tangent vector at base point, along which the parallel transport is computed.

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

Returns

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

squared_dist(point_a, point_b)[source]

Squared geodesic distance between two points.

Parameters
• point_a (array-like, shape=[…, dim]) – Point 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¶

The n-dimensional hyperbolic space.

The n-dimensional hyperbolic space embedded and its different representations.

class geomstats.geometry.hyperbolic.Hyperbolic(dim, scale=1, **kwargs)[source]

Class for the n-dimensional hyperbolic space.

Class for the n-dimensional hyperbolic space as embedded in (n+1)-dimensional Minkowski space.

The point_type variable allows to choose the representation of the points as input.

If point_type is set to ‘ball’ then points are parametrized by their coordinates inside the Poincare Ball n-coordinates.

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

• point_type (str, {‘extrinsic’, ‘intrinsic’, etc}) – Default coordinates to represent points in hyperbolic space. Optional, default: ‘extrinsic’.

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

static ball_to_half_space_coordinates(point)[source]

Convert ball to half space coordinates.

Convert the parameterization of a point in the hyperbolic space from its Poincare ball coordinates, to the Poincare half-space coordinates.

Parameters

point (array-like, shape=[…, dim]) – Point in the hyperbolic space in Poincare ball coordinates.

Returns

point_ball (array-like, shape=[…, dim]) – Point in the hyperbolic space in half-space coordinates.

static ball_to_half_space_tangent(tangent_vec, base_point)[source]

Convert ball to half-space tangent coordinates.

Convert the parameterization of a tangent vector to the hyperbolic space from its Poincare ball coordinates, to the Poinare half-space coordinates.

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

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

Returns

tangent_vec_half_spacel (array-like, shape=[…, dim]) – Tangent vector in the Poincare half-space.

belongs(point, tolerance=1e-06)[source]

Test if a point belongs to the hyperbolic space.

Test if a point belongs to the hyperbolic space in its hyperboloid representation.

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

• tolerance (float) – Tolerance at which to evaluate how close the squared norm is to the reference value. Optional, default: TOLERANCE.

Returns

belongs (array-like, shape=[…, 1]) – Array of booleans indicating whether the corresponding points belong to the hyperbolic space.

static change_coordinates_system(point, from_coordinates_system, to_coordinates_system)[source]

Convert coordinates of a point.

Convert the parameterization of a point in the hyperbolic space from current given coordinate system to an other also given in parameters. The possible coordinates system are ‘extrinsic’, ‘intrinsic’, ‘ball’ and ‘half-plane’ that correspond respectivelly to extrinsic coordinates in the hyperboloid , intrinsic coordinates in the hyperboloid, ball coordinates in the Poincare ball model and coordinates in the Poincare upper half-plane model.

Parameters
• point (array-like, shape=[…, {dim, dim + 1}]) – Point in hyperbolic space.

• from_coordinates_system (str, {‘extrinsic’, ‘intrinsic’, etc}) – Coordinates type.

• to_coordinates_system (str, {‘extrinsic’, ‘intrinsic’, etc}) – Coordinates type.

Returns

point_to (array-like, shape=[…, dim]) – or shape=[n_sample, dim + 1] Point in hyperbolic space in coordinates given by to_point_type.

from_coordinates(point, from_coords_type)[source]

Convert to a type of coordinates given some type.

Convert the parameterization of a point in hyperbolic space from given coordinate system to the current coordinate system.

Parameters
• point (array-like, shape=[…, {dim, dim + 1}]) – Point in hyperbolic space in coordinates from_point_type.

• from_coords_type (str, {‘ball’, ‘extrinsic’, ‘intrinsic’, …}) – Coordinates type.

Returns

point_current (array-like, shape=[…, {dim, dim + 1}]) – Point in hyperbolic space.

static half_space_to_ball_coordinates(point)[source]

Convert half-space to ball coordinates.

Convert the parameterization of a point in the hyperbolic space from its Poincare half-space coordinates, to the Poincare ball coordinates.

Parameters

point (array-like, shape=[…, dim]) – Point in the hyperbolic space in half-space coordinates.

Returns

point_ball (array-like, shape=[…, dim]) – Point in the hyperbolic space in Poincare ball coordinates.

static half_space_to_ball_tangent(tangent_vec, base_point)[source]

Convert half-space to ball tangent coordinates.

Convert the parameterization of a tangent vector to the hyperbolic space from its Poincare half-space coordinates, to the Poinare ball coordinates.

Parameters
• tangent_vec (array-like, shape=[…, dim]) – Tangent vector at the base point in the Poincare half-space.

• base_point (array-like, shape=[…, dim]) – Point in the Poincare half-space.

Returns

tangent_vec_ball (array-like, shape=[…, dim]) – Tangent vector in the Poincare ball.

random_uniform(n_samples=1, bound=1.0)[source]

Sample over the hyperbolic space using uniform distribution.

Sample over the hyperbolic space. The sampling is performed by sampling over uniform distribution, the sampled examples are considered in the intrinsic coordinates system. The function then transforms intrinsic samples into system coordinate selected.

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

• bound (float) – Bound defining the hypersquare in which to sample uniformly. Optional, default: 1.

Returns

samples (array-like, shape=[…, dim + 1]) – Samples in hyperbolic space.

to_coordinates(point, to_coords_type='ball')[source]

Convert coordinates of a point.

Convert the parameterization of a point in the hyperbolic space from current coordinate system to the coordinate system given.

Parameters
• point (array-like, shape=[…, {dim, dim + 1}]) – Point in hyperbolic space.

• to_coords_type (str, {‘extrinsic’, ‘intrinsic’, etc}) – Coordinates type. Optional, default: ‘ball’.

Returns

point_to (array-like, shape=[…, {dim, dim + 1}]) – Point in hyperbolic space in coordinates given by to_point_type.

class geomstats.geometry.hyperbolic.HyperbolicMetric(dim, scale=1)[source]

Class that defines operations using a hyperbolic metric.

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

• point_type (str, {‘extrinsic’, ‘intrinsic’, etc}, optional) – Default coordinates to represent points in hyperbolic space.

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

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]) – Point in hyperbolic space. Optional, default: None.

Returns

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

squared_norm(vector, base_point=None)[source]

Compute the squared norm of a vector.

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

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

• base_point (array-like, shape=[…, dim + 1]) – Point in hyperbolic space in extrinsic coordinates. Optional, default: None.

Returns

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

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

The manifold of symmetric positive definite (SPD) matrices.

class geomstats.geometry.spd_matrices.SPDMatrices(n)[source]

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

Parameters

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

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

Check if a matrix is symmetric and invertible.

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

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

Returns

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

classmethod logm(mat)[source]

Compute the matrix log for a symmetric matrix.

Parameters

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

Returns

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

random_tangent_vec_uniform(n_samples=1, base_point=None)[source]

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

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

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

Returns

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

random_uniform(n_samples=1)[source]

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

Parameters

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

Returns

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

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

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

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

Compute the affine-invariant exponential map.

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

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

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

Returns

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

geodesic(initial_point, initial_tangent_vec)[source]

Compute the affine-invariant geodesic.

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

• initial_tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at the initial point, the initial speed of the geodesic.

Returns

geodesic (callable) – Time-parameterized geodesic curve.

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_a, tangent_vec_b, base_point)[source]

Parallel transport of a tangent vector.

Closed-form solution for the parallel transport of a tangent vector a along the geodesic defined by exp_(base_point)(tangent_vec_b). Denoting tangent_vec_a by S, base_point by A, let B = Exp_A(tangent_vec_b) and :math: E = (BA^{- 1})^({ 1 / 2}). Then the parallel transport to Bis:

..math::

S’ = ESE^T

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

• tangent_vec_b (array-like, shape=[…, dim + 1]) – Tangent vector at base point, initial speed of the geodesic along which the parallel transport is computed.

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

Returns

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

class geomstats.geometry.spd_matrices.SPDMetricEuclidean(n, power_euclidean=1)[source]

Class for the Euclidean metric on the SPD manifold.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]

Compute the Euclidean inner-product.

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

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

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

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

Returns

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

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

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

Parameters

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

exp(tangent_vec, base_point)[source]

Compute the Log-Euclidean exponential map.

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

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

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

Returns

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

geodesic(initial_point, initial_tangent_vec)[source]

Compute the Log-Euclidean geodesic.

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

• initial_tangent_vec (array-like, shape=[…, n, n]) – Tangent vector at the initial point, the initial speed of the geodesic.

Returns

geodesic (callable) – Time-parameterized geodesic curve.

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]

Compute the Log-Euclidean inner-product.

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

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

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

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

Returns

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

log(point, base_point)[source]

Compute the Log-Euclidean logarithm map.

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

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

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

Returns

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

class geomstats.geometry.spd_matrices.SPDMetricProcrustes(n)[source]

Class for the Procrustes metric on the SPD manifold.

Parameters

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

References

inner_product(tangent_vec_a, tangent_vec_b, base_point)[source]

Compute the Procrustes inner-product.

Compute the inner-product of tangent_vec_a and tangent_vec_b at point base_point using the Procrustes 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.

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

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

Class for skew-symmetric matrices.

Parameters

n (int) – Number of rows and columns.

basis_representation(matrix_representation)[source]

Calculate the coefficients of given matrix in the basis.

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

Parameters

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

Returns

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

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

Evaluate if mat is a skew-symmetric matrix.

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

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

Returns

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

### Stiefel Manifold¶

Stiefel manifold St(n,p).

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

class geomstats.geometry.stiefel.Stiefel(n, p)[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.

random_uniform(n_samples=1)[source]

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

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

Parameters

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

Returns

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

static to_grassmannian(point)[source]

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

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

Parameters

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

Returns

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

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

Class that defines the canonical metric for Stiefel manifolds.

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

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

### Lie Groups¶

Lie groups.

class geomstats.geometry.lie_group.LieGroup(dim, default_point_type='vector', **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.

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

add_metric(metric)[source]

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

Parameters

metric (RiemannianMetric) – Metric to add.

compose(point_a, point_b)[source]

Perform function composition corresponding to the Lie group.

Multiply the elements point_a and point_b.

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

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

Returns

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

exp(tangent_vec, base_point=None)[source]

Compute the group exponential at base_point of tangent_vec.

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

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

Returns

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

exp_from_identity(tangent_vec)[source]

Compute the group exponential of tangent vector from the identity.

Parameters

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

Returns

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

exp_not_from_identity(tangent_vec, base_point)[source]

Calculate the group exponential at base_point.

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

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

Returns

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

get_identity(point_type=None)[source]

Get the identity of the group.

Parameters

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

Returns

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

property identity

Get the identity of the group.

Parameters

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

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

Returns

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

jacobian_translation(point, left_or_right='left')[source]

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

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

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

• left_or_right (str, {‘left’, ‘right’}) – Indicate whether to calculate the differential of left or right translations. Optional, default: ‘left’.

Returns

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

lie_bracket(tangent_vector_a, tangent_vector_b, base_point=None)[source]

Compute the lie bracket of two tangent vectors.

For matrix Lie groups with tangent vectors A,B at the same base point P this is given by (translate to identity, compute commutator, go back) $$[A,B] = A_P^{-1}B - B_P^{-1}A$$

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

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

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

Returns

bracket (array-like, shape=[…, n, n]) – Lie bracket.

log(point, base_point=None)[source]

Compute the group logarithm of point relative to base_point.

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

• base_point (array-like, shape=[…, {dim, [n, n]}]) – Base point. Optional, defaults to identity if None.

Returns

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

log_from_identity(point)[source]

Compute the group logarithm of point from the identity.

Parameters

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

Returns

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

log_not_from_identity(point, base_point)[source]

Compute the group logarithm of point from base_point.

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

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

Returns

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

tangent_translation_map(point, left_or_right='left', inverse=False)[source]

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

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

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

• left_or_right (str, {‘left’, ‘right’}) – Whether to calculate the differential of left or right translations. Optional, default: ‘left’

• inverse (bool,) – Whether to inverse the jacobian matrix. If True, the push forward by the translation by the inverse of point is returned. Optional, default: False.

Returns

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

to_tangent(vector, base_point=None)[source]

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

Parameters
• vector (array-like, shape=[…, {dim, [n, n]}]) – Vector to project. Its shape must match the shape of base_point.

• base_point (array-like, shape=[…, {dim, [n, n]}], optional) – Point of the group.

Returns

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

geomstats.geometry.lie_group.grad(y_pred, y_true, group, metric=None)[source]

Compute the gradient of the loss function from closed-form expression.

Parameters
• y_pred (array-like, shape=[…, {dim, [n, n]}]) – Prediction.

• y_true (array-like, shape=[…, {dim, [n, n]}]) – Ground-truth. Shape has to match y_pred.

• group (LieGroup)

• metric (RiemannianMetric) – Riemannian metric. optional, defaults to the left invariant metric if None.

Returns

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

geomstats.geometry.lie_group.loss(y_pred, y_true, group, metric=None)[source]

Compute loss given by Riemannian metric.

Parameters
• y_pred (array-like, shape=[…, {dim, [n, n]}]) – Prediction.

• y_true (array-like, shape=[…, {dim, [n, n]}]) – Ground-truth. Shape has to match y_pred.

• group (LieGroup)

• metric (RiemannianMetric) – Riemannian metric. Optional, defaults to the left invariant metric if None.

Returns

loss (array-like, shape=[…, {dim, [n, n]}]) – Squared (geodesic) distance between y_pred and y_true

### Lie Algebra¶

Module providing an implementation of MatrixLieAlgebras.

There are two main forms of representation for elements of a MatrixLieAlgebra implemented here. The first one is as a matrix, as elements of R^(n x n). The second is by choosing a base and remembering the coefficients of an element in that base. This base will be provided in child classes (e.g. SkewSymmetricMatrices).

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

Class implementing matrix Lie algebra related functions.

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

• n (int) – Amount of rows and columns in the matrix representation of the Lie algebra.

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

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

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

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

Parameters
• matrix_a, matrix_b (array-like, shape=[…, n, n]) – Matrices.

• order (int) – The order to which the approximation is calculated. Note that this is NOT the same as using only e_i with i < order. Optional, default 2.

References

CM2009a

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

CM2009b

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

basis_representation(matrix_representation)[source]

Compute the coefficients of matrices in the given basis.

Parameters

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

Returns

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

static lie_bracket(matrix_a, matrix_b)[source]

Compute the Lie_bracket (commutator) of two matrices.

Notice that inputs have to be given in matrix form, no conversion between basis and matrix representation is attempted.

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

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

Returns

bracket (shape=[…, n, n]) – Lie bracket.

matrix_representation(basis_representation)[source]

Compute the matrix representation for the given basis coefficients.

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

Parameters

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

Returns

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

### Matrices Space¶

Module exposing the Matrices and MatricesMetric class.

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

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

Parameters

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

belongs(point)[source]

Check if point belongs to the Matrices space.

Parameters

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

Returns

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

classmethod bracket(mat_a, mat_b)[source]

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

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

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

Returns

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

classmethod congruent(mat_1, mat_2)[source]

Compute the congruent action of mat_2 on mat_1.

This is :math: 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 equal(mat_a, mat_b, atol=1e-05)[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: 1e-5.

Returns

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

classmethod is_skew_symmetric(mat, atol=1e-05)[source]

Check if a matrix is skew symmetric.

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

• atol (float) – Absolute tolerance. Optional, default: 1e-5.

Returns

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

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_symmetric(mat, atol=1e-05)[source]

Check if a matrix is symmetric.

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

• atol (float) – Absolute tolerance. Optional, default: 1e-5.

Returns

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

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_uniform(n_samples=1, bound=1.0)[source]

Sample from a uniform distribution.

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

• bound (float) – Bound. Optional, default: 1.

Returns

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

classmethod to_skew_symmetric(mat)[source]

Make a matrix skew-symmetric, by averaging 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_symmetric(mat)[source]

Make a matrix symmetric, by averaging with its transpose.

Parameters

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

Returns

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

static transpose(mat)[source]

Return the transpose of matrices.

Parameters

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

Returns

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

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

Euclidean metric on matrices given by Frobenius inner-product.

Parameters

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

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

Compute Frobenius inner-product of two tan vecs at base_point.

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.

### General Linear Group¶

Module exposing the GeneralLinear group class.

class geomstats.geometry.general_linear.GeneralLinear(n, **kwargs)[source]

Class for the general linear group GL(n).

Parameters

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

belongs(point)[source]

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

Parameters

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

Returns

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

classmethod compose(*args)[source]

Return the product of a collection of matrices.

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 :math:’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.

get_identity()[source]

Return the identity matrix.

property identity

Return the identity matrix.

static inverse(point)[source]

Return the inverse of a matrix.

Parameters

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

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)$
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 {\mathrm with} \quad\\ {\mathrm e}^{X} = g h^{-1}\end{split}$

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

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

random_uniform(n_samples=1, tol=1e-06)[source]

Sample in GL(n) from the uniform distribution.

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

• tol (float) – Threshold for the absolute value of the determinant of the returned matrix. Optional, default: 1e-6.

Returns

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

### Special Euclidean Group¶

The special euclidean group SE(n).

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

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

Class for the special euclidean groups.

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

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

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

### Special Orthogonal Group¶

Exposes the SpecialOrthogonal group class.

class geomstats.geometry.special_orthogonal.SpecialOrthogonal(n, point_type='matrix', epsilon=0.0)[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

### Grassmannian Manifold¶

Module exposing Grassmannian and GrassmannianMetric classes.

class geomstats.geometry.grassmannian.Grassmannian(n, k)[source]

Class for Grassmann manifolds Gr(n, k).

Class for Grassmann manifolds Gr(n, k) of k-dimensional subspaces in the n-dimensional Euclidean space.

The subspaces are represented by their (unique) orthogonal projection matrix onto themselves.

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

• k (int) – Dimension of the subspaces.

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

Check if the point belongs to the manifold.

Check if an (n,n)-matrix is an orthogonal projector onto a subspace of rank k.

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

• atol (int) – Optional, default: 1e-5.

Returns

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

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

Check if a vector is tangent to the manifold at the base point.

Check if the (n,n)-matrix :math: Y is symmetric and verifies the relation :math: PY + YP = Y where :math: P represents the base point and :math: Y the vector.

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

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

• atol (int) – Optional, default: 1e-5.

Returns

belongs (array-like, shape=[…,]) – Boolean evaluating if vector is tangent to the Grassmannian at base_point.

random_uniform(n_samples=1)[source]

Sample random points from a uniform distribution.

Following [Chikuse03], :math: n_samples * n * kscalars are sampled from a standard normal distribution and reshaped to matrices, the projectors on their first k columns follow a uniform distribution.

Parameters

n_samples (int) – The number of points to sample Optional. default: 1.

Returns

projectors (array-like, shape=[…, n, n]) – Points following a uniform distribution.

References

Chikuse03

Yasuko Chikuse, Statistics on special manifolds,

New York: Springer-Verlag. 2003, 10.1007/978-0-387-21540-2

to_tangent(vector, base_point=None)[source]

Project a vector to a tangent space of the manifold.

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

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

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

Returns

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

class geomstats.geometry.grassmannian.GrassmannianCanonicalMetric(n, p)[source]

Canonical metric of the Grassmann manifold.

Coincides with the Frobenius metric.

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

• k (int) – Dimension of the subspaces.

exp(tangent_vec, base_point)[source]

Exponentiate the invariant vector field v from base point p.

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

• base_point (array-like, shape=[…, n, n]) – Base point. base_point is a rank p projector of Gr(n, k).

Returns

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

log(point, base_point)[source]

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

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

$\omega = \frac 1 2 \log \big((2 P' - 1)(2 P - 1)\big)$
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.

### Landmarks Space¶

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

class geomstats.geometry.landmarks.L2Metric(ambient_manifold, n_landmarks)[source]

L2 Riemannian metric on the space of landmarks.

Parameters
• ambient_manifold (Manifold) – Manifold in which landmarks lie

• n_landmarks (int) – Number of landmarks.

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

Generate parameterized function for the geodesic curve.

Geodesic curve defined by either: - an initial landmark set and an initial tangent vector, - an initial landmark set and an end landmark set.

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

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

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

Returns

path (callable) – Time parameterized geodesic curve.

class geomstats.geometry.landmarks.Landmarks(ambient_manifold, n_landmarks)[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.

• n_landmarks (int) – Number of landmarks.

### Poincare Polydisk Space¶

The Poincare polydisk.

The Poincare polydisk is defined as a product manifold of the Hyperbolic space of dimension 2. The Poincare polydisk has a product metric. The metric on each space is the natural Poincare metric multiplied by a constant.

References

JV2016

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

class geomstats.geometry.poincare_polydisk.PoincarePolydisk(n_disks, coords_type='extrinsic')[source]

Class for the Poincare polydisk.

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

Parameters
• n_disks (int) – Number of disks.

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

static intrinsic_to_extrinsic_coords(point_intrinsic)[source]

Convert point from intrinsic to extrensic coordinates.

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

Parameters

point_intrinsic (array-like, shape=[…, n_disk, dim]) – Point in intrinsic coordinates.

Returns

point_extrinsic (array-like, shape=[…, n_disks, dim + 1]) – Point in extrinsic coordinates.

projection_to_tangent_space(vector, base_point)[source]

Project a vector in the tangent space.

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

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

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

Returns

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

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

Class defining the Poincare polydisk metric.

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

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

Parameters
• n_disks (int) – Number of disks.

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

References

JV2016

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

## Metrics¶

### Riemannian Metric¶

Riemannian and pseudo-Riemannian metrics.

class geomstats.geometry.riemannian_metric.RiemannianMetric(dim, signature=None, default_point_type='vector')[source]

Class for Riemannian and pseudo-Riemannian metrics.

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

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

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

christoffels(base_point)[source]

Compute Christoffel symbols associated with the connection.

Parameters

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

Returns

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

closest_neighbor_index(point, neighbors)[source]

Closest neighbor of point among neighbors.

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

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

Returns

closest_neighbor_index (int) – Index of closest neighbor.

diameter(points)[source]

Give the distance between two farthest points.

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

Parameters

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

Returns

diameter (float) – Distance between two farthest points.

dist(point_a, point_b)[source]

Geodesic distance between two points.

Note: It only works for positive definite Riemannian metrics.

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

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

Returns

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

dist_pairwise(point)[source]

Compute the pairwise distance between points.

Parameters

point (array-like, shape=[n_samples, dim]) – Set of points in hyperbolic space.

Returns

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

inner_product_derivative_matrix(base_point=None)[source]

Compute derivative of the inner prod matrix at base point.

Parameters

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

Returns

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

inner_product_inverse_matrix(base_point=None)[source]

Inner product matrix at the tangent space at a base point.

Parameters

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

Returns

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

inner_product_matrix(base_point=None)[source]

Inner product matrix at the tangent space at a base point.

Parameters

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

Returns

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

norm(vector, base_point=None)[source]

Compute norm of a vector.

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

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

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

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

Returns

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

squared_dist(point_a, point_b)[source]

Squared geodesic distance between two points.

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

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

Returns

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

squared_norm(vector, base_point=None)[source]

Compute the square of the norm of a vector.

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

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

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

Returns

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

geomstats.geometry.riemannian_metric.grad(y_pred, y_true, metric)[source]

Closed-form for the gradient of the loss function.

Parameters
• y_pred (array-like, shape=[…, dim]) – Prediction.

• y_true (array-like, shape=[…, dim]) – Ground-truth.

• metric (RiemannianMetric) – Metric.

Returns

geomstats.geometry.riemannian_metric.loss(y_pred, y_true, metric)[source]

Compute loss function between prediction and ground truth.

Loss function given by a Riemannian metric, expressed as the squared geodesic distance between the prediction and the ground truth.

Parameters
• y_pred (array-like, shape=[…, dim]) – Prediction.

• y_true (array-like, shape=[…, dim]) – Ground-truth.

• metric (RiemannianMetric) – Metric.

Returns

sq_dist (array-like, shape=[…,]) – Loss, i.e. the squared distance.

### Product Riemannian Metric¶

Product of Riemannian metrics.

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

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

Class for product of Riemannian metrics.

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

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

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

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

Compute the Riemannian exponential of a tangent vector.

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

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

• point_type (str, {‘vector’, ‘matrix’}) – Type of representation used for points. Optional, default: None.

Returns

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

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

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

Inner product defined by the Riemannian metric at point base_point between tangent vectors tangent_vec_a and tangent_vec_b.

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

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

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

• point_type (str, {‘vector’, ‘matrix’}) – Type of representation used for points. Optional, default: None.

Returns

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

inner_product_matrix(base_point=None, point_type=None)[source]

Compute the matrix of the inner-product.

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

Parameters
• base_point (array-like, shape=[…, n_metrics, dim] or) – […, dim] Point on the manifold at which to compute the inner-product matrix. Optional, default: None.

• point_type (str, {‘vector’, ‘matrix’}) – Type of representation used for points. Optional, default: None.

Returns

• matrix (array-like, shape=[…, dim, dim] or)

• […, dim + n_metrics, dim + n_metrics] – Matrix of the inner-product at the base point.

is_intrinsic(point)[source]

Test in a point is represented in intrinsic coordinates.

This method is only useful for point_type=vector.

Parameters

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

Returns

intrinsic (array-like, shape=[…,]) – Whether intrinsic coordinates are used for all manifolds.

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

Compute the Riemannian logarithm of a point.

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

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

• point_type (str, {‘vector’, ‘matrix’}) – Type of representation used for points. Optional, default: None.

Returns

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

### Invariant Metric¶

Left- and right- invariant metrics that exist on Lie groups.

class geomstats.geometry.invariant_metric.BiInvariantMetric(group)[source]

Class for bi-invariant metrics which exist on Lie groups.

Compact Lie groups and direct products of compact Lie groups with vector spaces admit bi-invariant metrics. Products Lie groups are not implemented. Other groups such as SE(3) admit bi-invariant pseudo-metrics.

Parameters

group (LieGroup) – The group to equip with the bi-invariant metric

exp_from_identity(tangent_vec)[source]

Compute Riemannian exponential of tangent vector from the identity.

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

Parameters

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

Returns

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

log_from_identity(point)[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.

Returns

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

class geomstats.geometry.invariant_metric.InvariantMetric(group, inner_product_mat_at_identity=None, left_or_right='left', **kwargs)[source]

Class for invariant metrics which exist on Lie groups.

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

Points are parameterized by the Riemannian logarithm for the canonical left-invariant metric.

Parameters
• group (LieGroup) – Group to equip with the invariant metric

• inner_product_mat_at_identity (array-like, shape=[dim, dim]) – Matrix that defines the metric at identity. Optional, defaults to identity matrix if None.

• left_or_right (str, {‘left’, ‘right’}) – Wether to use a left or right invariant metric. Optional, default: ‘left’.

exp(tangent_vec, base_point=None)[source]

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

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

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

Returns

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

exp_from_identity(tangent_vec)[source]

Compute Riemannian exponential of tangent vector from the identity.

Parameters

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

Returns

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

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=[…, dim]) – First tangent vector at base_point.

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

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

Returns

inner_prod (array-like, shape=[…, dim]) – 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]) – First tangent vector at identity.

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

Returns

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

inner_product_matrix(base_point=None)[source]

Compute inner product matrix at the tangent space at a base point.

Parameters

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

Returns

metric_mat (array-like, shape=[…, dim, dim]) – Metric matrix at base_point.

left_exp_from_identity(tangent_vec)[source]

Compute the exponential from identity with the left-invariant metric.

Compute Riemannian exponential of a tangent vector at the identity associated to the left-invariant metric.

If the method is called by a right-invariant metric, it uses the left-invariant metric associated to the same inner-product matrix at the identity.

Parameters

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

Returns

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

left_log_from_identity(point)[source]

Compute Riemannian log of a point wrt. id of left-invar. metric.

Compute Riemannian logarithm of a point wrt the identity associated to the left-invariant metric.

If the method is called by a right-invariant metric, it uses the left-invariant metric associated to the same inner-product matrix at the identity.

Parameters

point (array-like, shape=[…, dim]) – Point in the group.

Returns

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

log(point, base_point=None)[source]

Compute Riemannian logarithm of a point from a base point.

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

• base_point (array-like, shape=[…, dim], optional) – Point in the group, from which to compute the log, (the default is identity).

Returns

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

log_from_identity(point)[source]

Compute Riemannian logarithm of a point wrt the identity.

Parameters

point (array-like, shape=[…, dim]) – Point in the group.

Returns

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

## Connections¶

Affine connections.

class geomstats.geometry.connection.Connection(dim, default_point_type='vector', default_coords_type='intrinsic')[source]

Class for affine connections.

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

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

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

christoffels(base_point)[source]

Christoffel symbols associated with the connection.

Parameters

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

Returns

gamma (array-like, shape=[…, dim, dim, dim]) – Christoffel symbols, with the covariant index on the first dimension.

connection(tangent_vec_a, tangent_vec_b, base_point)[source]

Covariant derivative.

Connection applied to tangent_vector_b in the direction of tangent_vector_a, both tangent at 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]) – Point on the manifold.

exp(tangent_vec, base_point, n_steps=10, step='euler', point_type=None, **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’.

• 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, end_point=None, initial_tangent_vec=None, point_type=None)[source]

Generate parameterized function for the geodesic curve.

Geodesic curve defined by either: - an initial point and an initial tangent vector, - an initial point and an end point.

Parameters
• initial_point (array-like, shape=[…, dim]) – Point on the manifold, initial point of the geodesic.

• end_point (array-like, shape=[…, dim], optional) – Point on the manifold, end point of the geodesic. If None, an initial tangent vector must be given.

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

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

Returns

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

geodesic_equation(position, velocity)[source]

Compute the geodesic ODE associated with the connection.

Parameters
• velocity (array-like, shape=[…, dim]) – Tangent vector at the position.

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

ladder_parallel_transport(tangent_vec_a, tangent_vec_b, base_point, n_rungs=1, scheme='pole', alpha=2, **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 [GJSP2019] while Schild’s ladder is a first order approximation. Both schemes are available any affine connection manifolds whose exponential and logarithm maps are implemented. tangent_vec_a is transported along the geodesic starting at the base_point with initial tangent vector tangent_vec_b.

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

• tangent_vec_b (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

Marco Lorenzi, Xavier Pennec. Efficient Parallel Transpor of Deformations in Time Series of Images: from Schild’s to Pole Ladder.Journal of Mathematical Imaging and Vision, Springer Verlag, 2013, 50 (1-2), pp.5-17. ⟨10.1007/s10851-013-0470-3⟩

GP2020

Nicolas Guigui, Xavier Pennec. Numerical Accuracy of

Ladder Schemes for Parallel Transport on Manifolds. 2020. ⟨hal-02894783⟩

log(point, base_point, n_steps=10, step='euler', max_iter=25, verbose=False, tol=1e-06)[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’.

Returns

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

riemannian_curvature(base_point)[source]

Compute Riemannian curvature tensor associated with the connection.

Parameters

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

torsion(base_point)[source]

Compute torsion tensor associated with the connection.

Parameters

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