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

Evaluate if a point belongs to the manifold.

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

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

Returns

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

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

Check whether the vector is tangent at base_point.

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

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

Sample random points on the manifold.

If the manifold is compact, a uniform distribution is used.

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

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

Returns

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

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', **kwargs)[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_point(n_samples=1, bound=1.0)[source]

Sample in the product space from the uniform distribution.

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

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

Returns

samples (array-like, shape=[…, dim + 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_point(n_samples=1, bound=1.0)[source]

Sample in the Euclidean space with a uniform distribution in a box.

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

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

Returns

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

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.

log(point, base_point)[source]

Compute log map using a base point and other point.

The Riemannian logarithm is the subtraction in the Euclidean space.

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

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

Returns

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

metric_matrix(base_point=None)[source]

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

Parameters

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

Returns

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

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

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.

metric_matrix(base_point=None)[source]

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

Parameters

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

Returns

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

Hypersphere

The n-dimensional hypersphere.

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

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

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

Compute the curvature.

For three tangent vectors at a base point :math: x,y,z, the curvature is defined by :math: R(X, Y)Z = nabla_{[X,Y]}Z - nabla_Xnabla_Y Z + - nabla_Ynabla_X Z, where :math: nabla is the Levi-Civita connection. In the case of the hypersphere, we have the closed formula :math: 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 group. Optional, default is the identity.

Returns

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

dist(point_a, point_b)[source]

Compute the geodesic distance between two points.

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

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

Returns

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

exp(tangent_vec, base_point)[source]

Compute the Riemannian exponential of a tangent vector.

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

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

Returns

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

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 :math: t mapsto exp_(base_point)(t* 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, atol=1e-12)[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.

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

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

Discretized Curves Space

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.

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

Compute the differential of the matrix power.

Auxiliary function to the functions differential_power and inverse_differential_power.

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

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

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

Returns

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

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

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

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

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

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

Check if a matrix is symmetric and invertible.

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

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

Returns

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

classmethod differential_exp(tangent_vec, base_point)[source]

Compute the differential of the matrix exponential.

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

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

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

Returns

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

classmethod differential_log(tangent_vec, base_point)[source]

Compute the differential of the matrix logarithm.

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

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

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

Returns

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

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

Compute the differential of the matrix power function.

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

Parameters
  • power (int) – Power.

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

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

Returns

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

classmethod inverse_differential_exp(tangent_vec, base_point)[source]

Compute the inverse of the differential of the matrix exponential.

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

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

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

Returns

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

classmethod inverse_differential_log(tangent_vec, base_point)[source]

Compute the inverse of the differential of the matrix logarithm.

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

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

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

Returns

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

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

Compute the inverse of the differential of the matrix power.

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

Parameters
  • power (int) – Power.

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

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

Returns

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

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

Check whether the vector is tangent at base_point.

A “vector” is tangent to the manifold of SPD matrices if it is a symmetric matrix.

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

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

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

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

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

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

Returns

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

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

to_tangent(vector, base_point=None)[source]

Project a vector to a tangent space of the manifold.

A “vector” is tangent to the manifold of SPD matrices if it is a symmetric matrix, so the symmetric component of the input matrix is returned.

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

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

Returns

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

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.

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 `B`is:

..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.SPDMetricBuresWasserstein(n)[source]

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

Parameters

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

References

exp(tangent_vec, base_point)[source]

Compute the Bures-Wasserstein exponential map.

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

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

Returns

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

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 :math: A and tangent_vec_b :math: B at point base_point :math: S=PDP^top using the Bures-Wasserstein Riemannian metric: ..math:: frac{1}{2}sum_{i,j}frac{[P^top AP]_{ij}[P^top BP]_{ij}}{d_i+d_j} .

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

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

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

Returns

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

log(point, base_point)[source]

Compute the Bures-Wasserstein logarithm map.

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

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

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

Returns

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

squared_dist(point_a, point_b)[source]

Compute the Bures-Wasserstein squared distance.

Compute the Riemannian squared distance between point_a and point_b.

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

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

Returns

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

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

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.

Skew-Symmetric Matrices Space

Module providing the SkewSymmetricMatrices class.

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

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

Class for skew-symmetric matrices.

Parameters

n (int) – Number of rows and columns.

basis_representation(matrix_representation)[source]

Calculate the coefficients of given matrix in the basis.

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

Parameters

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

Returns

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

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

Evaluate if mat is a skew-symmetric matrix.

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

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

Returns

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

classmethod projection(mat)[source]

Compute the skew-symmetric component of a matrix.

The skew-symmetric part of a matrix :math: X is defined by .. math:

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

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] or [n_samples, m, n]) – Sample.

Stiefel Manifold

Stiefel manifold St(n,p).

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

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

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

Test if a point belongs to St(n,p).

Test whether the point is a p-frame in n-dimensional space, and it is orthonormal.

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

  • atol (float, optional) – Tolerance at which to evaluate. Optional, default: 1e-5.

Returns

belongs (array-like, shape=[…,]) – Array of booleans evaluating if the corresponding points belong to the Stiefel manifold.

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

Check whether the vector is tangent at base_point.

A matrix :math: X is tangent to the Stiefel manifold at a point :math: U if :math: U^TX is skew-symmetric.

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

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

random_uniform(n_samples=1)[source]

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

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

Parameters

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

Returns

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

static to_grassmannian(point)[source]

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

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

Parameters

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

Returns

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

to_tangent(vector, base_point=None)[source]

Project a vector to a tangent space of the manifold.

Inspired by the method of Pymanopt.

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

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

Returns

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

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

Class that defines the canonical metric for Stiefel manifolds.

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

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

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

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.

log(point, base_point, max_iter=30, tol=1e-06)[source]

Compute the Riemannian logarithm of a point.

Based on [ZR2017].

References

ZR2017

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

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

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

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

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

Returns

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

static retraction(tangent_vec, base_point)[source]

Compute the retraction of a tangent vector.

This computation is based on the QR-decomposition.

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

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

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

Returns

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

Lie Groups

Lie groups.

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

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

  • lie_algebra (MatrixLieAlgebra) – Lie algebra for matrix groups. Optional, default: None.

lie_algebra

Tangent space at the identity.

Type

MatrixLieAlgebra or None

left_canonical_metric

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

Type

InvariantMetric

right_canonical_metric

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

Type

InvariantMetric

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

  • atol (float) – Precision at which to evaluate if the rotation part is skew-symmetric. Optional. default: 1e-6

Returns

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

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

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

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

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

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

Returns

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

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

Compute the lie bracket of two tangent vectors.

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

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

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

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

Returns

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

log(point, base_point=None)[source]

Compute the group logarithm of point relative to base_point.

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

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

Returns

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

log_from_identity(point)[source]

Compute the group logarithm of point from the identity.

Parameters

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

Returns

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

log_not_from_identity(point, base_point)[source]

Compute the group logarithm of point from base_point.

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

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

Returns

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

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

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

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

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

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

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

Returns

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

to_tangent(vector, base_point=None)[source]

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

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

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

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

Class implementing matrix Lie algebra related functions.

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

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

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

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

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

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

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

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

References

CM2009a

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

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.

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.

projection(mat)[source]

Project a matrix to the Lie Algebra.

Parameters

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

Returns

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

Matrices Space

Module exposing the Matrices and MatricesMetric class.

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

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

Parameters

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

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-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: 1e-5.

Returns

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

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: 1e-5.

Returns

is_diagonal (array-like, shape=[…,]) – Boolean evaluating if the matrix is square and diagonal.

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: 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-12)[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_point(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 of the interval in which to sample each entry. 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 trace_product(mat_1, mat_2)[source]

Compute trace of the product of two matrices.

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

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

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

Returns

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

static transpose(mat)[source]

Return the transpose of matrices.

Parameters

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

Returns

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

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

Euclidean metric on matrices given by Frobenius inner-product.

Parameters

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

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

Compute Frobenius inner-product of two tangent vectors.

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

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

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

Returns

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

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

Sample in GL(n) from the uniform distribution.

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

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

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.

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

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

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

Parameters

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

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

See also

examples.plot_geodesics_se2

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

Compute logarithm map associated to the canonical metric.

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

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

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

Returns

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

References

[Zefran98] Zefran, M., V. Kumar, and C.B. Croke.

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

parallel_transport(tangent_vec_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 :math: t mapsto exp_(base_point)(t* tangent_vec_b). As the special Euclidean group endowed with its canonical left-invariant metric is a symmetric space, parallel transport is achieved by a geodesic symmetry, or equivalently, one step

of the pole ladder scheme.

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

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

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

Returns

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

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

Lie Algebra of the special Euclidean group.

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

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

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

Parameters

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

basis_representation(matrix_representation)[source]

Calculate the coefficients of given matrix in the basis.

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

Parameters

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

Returns

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

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

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

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

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

Returns

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

projection(mat)[source]

Project a matrix to the Lie Algebra.

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

Parameters

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

Returns

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

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

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

Construct a block matrix of size :math: n + 1 times n + 1 of the form .. math:

\matvec{cc}{R & t\\
            0&c}

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

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

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

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

  • constant (float) – Constant to use at the last line and column of the square matrix. Optional, default: 1.

Returns

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

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

Manifold of linear subspaces.

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

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

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

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

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

\[Gr(n, k) \simeq St(n, k) / SO(k)\]
class geomstats.geometry.grassmannian.Grassmannian(n, k)[source]

Class for Grassmann manifolds Gr(n, k).

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

  • k (int) – Dimension of the subspaces.

belongs(point, atol=1e-12)[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-12)[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 * k scalars 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.

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

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

  • k_landmarks (int) – Number of landmarks.

Poincare Polydisk Space

The Poincare polydisk.

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

References

JV2016

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

class geomstats.geometry.poincare_polydisk.PoincarePolydisk(n_disks, 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(points, n_jobs=1, **joblib_kwargs)[source]

Compute the pairwise distance between points.

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

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

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

Returns

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

See also

https

//joblib.readthedocs.io/en/latest/

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.

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.

metric_matrix(base_point=None)[source]

Metric matrix at the tangent space at a base point.

Parameters

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

Returns

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

norm(vector, base_point=None)[source]

Compute norm of a vector.

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

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

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

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

Returns

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

orthonormal_basis(basis, base_point=None)[source]

Orthonormalize the basis with respect to the metric.

This corresponds to a renormalization.

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

  • base_point

Returns

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

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

Compute the sectional curvature.

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

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

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

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

Returns

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

See also

https

//en.wikipedia.org/wiki/Sectional_curvature

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

loss_grad (array-like, shape=[…,]) – Gradient of the loss.

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.

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.

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

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 on compact Lie groups.

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

Parameters

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

References

Gallier

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

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

Compute Riemannian exponential of tangent vector from the identity.

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

Parameters
  • tangent_vec – Tangent vector at identity.

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

Returns

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

References

Gallier

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

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.

class geomstats.geometry.invariant_metric.InvariantMetric(group, metric_mat_at_identity=None, left_or_right='left', point_type=None)[source]

Class for invariant metrics on Lie groups.

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

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

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

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

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

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

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

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

Compute the curvature.

For three tangent vectors at a base point :math: X,Y,Z, the curvature is defined by :math: R(X, Y)Z = nabla_{[X,Y]}Z - nabla_Xnabla_Y Z + - nabla_Ynabla_X Z.

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

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

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

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

Returns

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

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

  • max_iter

  • verbose

  • tol

Returns

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

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