Manifolds

The rigorous mathematical definition of a manifold is beyond the scope of this documentation. However, if you are unfamiliar with the idea, it is fine just to visualize it as a smooth subset of Euclidean space. Simple examples include the surface of a sphere or a torus, or the Möbius strip. For an exact definition and a general background on Riemannian optimization we refer readers to the monographs [AMS2008] and [Bou2020] (both of which are freely available online). If you need to solve an optimization problem with a search space that is constrained in some smooth way, then performing optimization on manifolds may well be the natural approach to take.

The manifolds that we currently support are listed below. We plan to implement more depending on the needs of users, so if there is a particular manifold you would like to optimize over, please let us know. If you wish to implement your own manifold for Pymanopt, you will need to inherit from the abstract pymanopt.manifolds.manifold.Manifold or pymanopt.manifolds.manifold.RiemannianSubmanifold base class.

Manifold

pymanopt.manifolds.manifold.raise_not_implemented_error(method)

class pymanopt.manifolds.manifold.Manifold(name, dimension, point_layout=1)

Bases: object

Riemannian manifold base class.

Abstract base class setting out a template for manifold classes.

Parameters

• name (str) – String representation of the manifold.

• dimension (int) – The dimension of the manifold, i.e., the vector space dimension of the tangent spaces.

• point_layout (Union[int, Sequence[int]]) – Abstract description of the representation of points on the manifold. For manifolds representing points as simple numpy arrays, point_layout is 1. For more complicated manifolds which might represent points as a tuple or list of n arrays, point_layout would be n. Finally, in the special case of the pymanopt.manifolds.product.Product manifold point_layout will be a compound sequence of point layouts of manifolds involved in the product.

Note

Not all methods are required by all optimizers. In particular, first order gradient based optimizers such as pymanopt.optimizers.steepest_descent.SteepestDescent and pymanopt.optimizers.conjugate_gradient.ConjugateGradient require euclidean_to_riemannian_gradient() to be implemented but not euclidean_to_riemannian_hessian(). Second-order optimizers such as pymanopt.optimizers.trust_regions.TrustRegions will require euclidean_to_riemannian_hessian().

property dim: int

The dimension of the manifold.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

property num_values: int

Total number of values representing a point on the manifold.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

abstract inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point (numpy.ndarray) – The base point.

• tangent_vector_a (numpy.ndarray) – The first tangent vector.

• tangent_vector_b (numpy.ndarray) – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

Return type

float

abstract projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

abstract norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

abstract random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

abstract random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

abstract zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

class pymanopt.manifolds.manifold.RiemannianSubmanifold(name, dimension, point_layout=1)

Bases: pymanopt.manifolds.manifold.Manifold

Base class for Riemannian submanifolds of Euclidean space.

This class provides a generic method to project Euclidean gradients to their Riemannian counterparts via the euclidean_to_riemannian_gradient() method. Similarly, if the Weingarten map (also known as shape operator) is provided via implementing the weingarten() method, the class provides a generic implementation of the euclidean_to_riemannian_hessian() method required by second-order optimizers to translate Euclidean Hessian-vector products to their Riemannian counterparts.

Note

This class follows definition 3.47 in [Bou2020] of “Riemannian submanifolds”. As such, manifolds derived from this class are assumed to be embedded submanifolds of Euclidean space with the Riemannian metric inherited from the embedding space obtained by restricting it to the tangent space at a given point.

For the exact definition of the Weingarten map refer to [AMT2013] and the notes in section 5.11 of [Bou2020].

Parameters

• name (str) –

• dimension (int) –

• point_layout (Union[int, Sequence[int]]) –

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

abstract inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point (numpy.ndarray) – The base point.

• tangent_vector_a (numpy.ndarray) – The first tangent vector.

• tangent_vector_b (numpy.ndarray) – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

Return type

float

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

abstract norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

abstract projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

abstract random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

abstract random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

abstract zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.manifold.RetrAsExpMixin

Bases: object

Mixin which defers calls to the exponential map to the retraction.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

Euclidean Space

class pymanopt.manifolds.euclidean.Euclidean(*shape)

Bases: pymanopt.manifolds.euclidean._Euclidean

Euclidean manifold.

Parameters

shape (int) – Shape of points on the manifold.

Note

If shape == (n,), this is the manifold of vectors with the standard Euclidean inner product, i.e., \(\R^n\). For shape == (m, n), it corresponds to the manifold of m x n matrices equipped with the standard trace inner product. For shape == (n1, n2, ..., nk), the class represents the manifold of tensors of shape n1 x n2 x ... x nk with the inner product corresponding to the usual tensor dot product.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.euclidean.ComplexEuclidean(*shape)

Bases: pymanopt.manifolds.euclidean._Euclidean

Complex Euclidean manifold.

Parameters

shape – Shape of points on the manifold.

Note

If shape == (n,), this is the manifold of vectors with the standard Euclidean inner product, i.e., \(\C^n\). For shape == (m, n), it corresponds to the manifold of m x n matrices equipped with the standard trace inner product. For shape == (n1, n2, ..., nk), the class represents the manifold of tensors of shape n1 x n2 x ... x nk with the inner product corresponding to the usual tensor dot product.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

class pymanopt.manifolds.euclidean.Symmetric(n, k=1)

Bases: pymanopt.manifolds.euclidean._Euclidean

(Product) manifold of symmetric matrices.

Parameters

• n (int) – Number of rows and columns of matrices.

• k (int) – Number of elements in the product manifold.

Note

Manifold of n x n symmetric matrices as a Riemannian submanifold of Euclidean space. If k > 1 then this is the product manifold of k symmetric n x n matrices represented as arrays of shape (k, n, n).

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.euclidean.SkewSymmetric(n, k=1)

Bases: pymanopt.manifolds.euclidean._Euclidean

(Product) manifold of skew-symmetric matrices.

Parameters

• n – Number of rows and columns of matrices.

• k – Number of elements in the product manifold.

Note

Manifold of n x n skew-symmetric matrices as a Riemannian submanifold of Euclidean space. If k > 1 then this is the product manifold of k skew-symmetric n x n matrices represented as arrays of shape (k, n, n).

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

Sphere Manifold

class pymanopt.manifolds.sphere.Sphere(*shape)

Bases: pymanopt.manifolds.sphere._SphereBase

The sphere manifold.

Manifold of shape \(n_1 \times \ldots \times n_k\) tensors with unit Euclidean norm. The norm is understood as the \(\ell_2\)-norm of \(\E = \R^{\sum_{i=1}^k n_i}\) after identifying \(\R^{n_1 \times \ldots \times n_k}\) with \(\E\). The metric is the one inherited from the usual Euclidean inner product that induces \(\norm{\cdot}_2\) on \(\E\) such that the manifold forms a Riemannian submanifold of Euclidean space.

Parameters

shape (int) – The shape of tensors.

Note

The Weingarten map is taken from [AMT2013].

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.sphere.SphereSubspaceIntersection(matrix)

Bases: pymanopt.manifolds.sphere._SphereSubspaceIntersectionManifold

Sphere-subspace intersection manifold.

Manifold of \(n\)-dimensional vectors with unit \(\ell_2\)-norm intersecting an \(r\)-dimensional subspace of \(\R^n\). The subspace is represented by a matrix of size n x r whose columns span the subspace.

Parameters

matrix – Matrix whose columns span the intersecting subspace.

Note

The Weingarten map is taken from [AMT2013].

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.sphere.SphereSubspaceComplementIntersection(matrix)

Bases: pymanopt.manifolds.sphere._SphereSubspaceIntersectionManifold

Sphere-subspace complement intersection manifold.

Manifold of \(n\)-dimensional vectors with unit \(\ell_2\)-norm that are orthogonal to an \(r\)-dimensional subspace of \(\R^n\). The subspace is represented by a matrix of size n x r whose columns span the subspace.

Parameters

matrix – Matrix whose columns span the subspace.

Note

The Weingarten map is taken from [AMT2013].

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

Stiefel Manifold

class pymanopt.manifolds.stiefel.Stiefel(n, p, *, k=1, retraction='qr')

Bases: pymanopt.manifolds.manifold.RiemannianSubmanifold

The (product) Stiefel manifold.

The Stiefel manifold \(\St(n, p)\) is the manifold of orthonormal n x p matrices. A point \(\vmX \in \St(n, p)\) therefore satisfies the condition \(\transp{\vmX}\vmX = \Id_p\). Points on the manifold are represented as arrays of shape (n, p) if k == 1. For k > 1, the class represents the product manifold of k Stiefel manifolds, in which case points on the manifold are represented as arrays of shape (k, n, p).

The metric is the usual Euclidean metric on \(\R^{n \times p}\) which turns \(\St(n, p)^k\) into a Riemannian submanifold.

Parameters

• n (int) – The number of rows.

• p (int) – The number of columns.

• k (int) – The number of elements in the product.

• retraction (str) – The type of retraction to use. Possible choices are qr and polar.

Note

The formula for the exponential map can be found in [ZH2021].

The Weingarten map is taken from [AMT2013].

The default retraction used here is a first-order one based on the QR decomposition. To switch to a second-order polar retraction, use Stiefel(n, p, k=k, retraction="polar").

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

Grassmann Manifold

class pymanopt.manifolds.grassmann.Grassmann(n, p, *, k=1)

Bases: pymanopt.manifolds.grassmann._GrassmannBase

The Grassmann manifold.

This is the manifold of subspaces of dimension p of a real vector space of dimension n. The optional argument k allows to optimize over the product of k Grassmann manifolds. Elements are represented as n x p matrices if k == 1, and as k x n x p arrays if k > 1.

Parameters

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

• p (int) – Dimension of the subspaces.

• k (int) – The number of elements in the product.

Note

The geometry assumed here is the one obtained by treating the Grassmannian as a Riemannian quotient manifold of the Stiefel manifold (see also pymanopt.manifolds.stiefel.Stiefel) with the orthogonal group \(\O(p) = \set{\vmQ \in \R^{p \times p} : \transp{\vmQ}\vmQ = \vmQ\transp{\vmQ} = \Id_p}\).

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

property dim: int

The dimension of the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.grassmann.ComplexGrassmann(n, p, *, k=1)

Bases: pymanopt.manifolds.grassmann._GrassmannBase

The complex Grassmann manifold.

This is the manifold of subspaces of dimension p of complex vector space of dimension n. The optional argument k allows to optimize over the product of k complex Grassmannians. Elements are represented as n x p matrices if k == 1, and as k x n x p arrays if k > 1.

Parameters

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

• p (int) – Dimension of the subspaces.

• k (int) – The number of elements in the product.

Note

Similar to Grassmann, the complex Grassmannian is treated as a Riemannian quotient manifold of the complex Stiefel manifold with the unitary group \(\U(p) = \set{\vmU \in \R^{p \times p} : \transp{\vmU}\vmU = \vmU\transp{\vmU} = \Id_p}\).

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

property dim: int

The dimension of the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

Complex Circle

class pymanopt.manifolds.complex_circle.ComplexCircle(n=1)

Bases: pymanopt.manifolds.manifold.RiemannianSubmanifold

Manifold of unit-modulus complex numbers.

Manifold of complex vectors \(\vmz\) in \(\C^n\) such that each component \(z_i\) has unit modulus \(\abs{z_i} = 1\).

Parameters

n – The dimension of the underlying complex space.

Note

The manifold structure is the Riemannian submanifold structure from the embedding space \(\R^2 \times \ldots \times \R^2\), i.e., the complex circle identified with the unit circle in the real plane.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

property dim: int

The dimension of the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

property num_values: int

Total number of values representing a point on the manifold.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

Group Manifolds

class pymanopt.manifolds.group.SpecialOrthogonalGroup(n, *, k=1, retraction='qr')

Bases: pymanopt.manifolds.group._UnitaryBase

The (product) manifold of rotation matrices.

The special orthgonal group \(\SO(n)\). Points on the manifold are matrices \(\vmQ \in \R^{n \times n}\) such that each matrix is orthogonal with determinant 1, i.e., \(\transp{\vmQ}\vmQ = \vmQ\transp{\vmQ} = \Id_n\) and \(\det(\vmQ) = 1\). For k > 1, the class can be used to optimize over the product manifold of rotation matrices \(\SO(n)^k\). In that case points on the manifold are represented as arrays of shape (k, n, n).

The metric is the usual Euclidean one inherited from the embedding space \((\R^{n \times n})^k\). As such \(\SO(n)^k\) forms a Riemannian submanifold.

The tangent space \(\tangent{\vmQ}\SO(n)\) at a point \(\vmQ\) is given by \(\tangent{\vmQ}\SO(n) = \set{\vmQ \vmOmega \in \R^{n \times n} \mid \vmOmega = -\transp{\vmOmega}} = \vmQ \Skew(n)\), where \(\Skew(n)\) denotes the set of skew-symmetric matrices. This corresponds to the Lie algebra of \(\SO(n)\), a fact which is used here to conveniently represent tangent vectors numerically by their skew-symmetric factor. The method embedding() can be used to transform a tangent vector from its Lie algebra representation to the embedding space representation.

Parameters

• n (int) – The dimension of the space that elements of the group act on.

• k (int) – The number of elements in the product of groups.

• retraction (str) – The type of retraction to use. Possible choices are qr and polar.

Note

The default QR-based retraction is only a first-order approximation of the exponential map. Use of an SVD-based second-order retraction can be enabled by setting the retraction argument to “polar”.

The procedure to generate random points on the manifold sampled uniformly from the Haar measure is detailed in [Mez2006].

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.group.UnitaryGroup(n, *, k=1, retraction='qr')

Bases: pymanopt.manifolds.group._UnitaryBase

The (product) manifold of unitary matrices (i.e., the unitary group).

The unitary group \(\U(n)\). Points on the manifold are matrices \(\vmX \in \C^{n \times n}\) such that each matrix is unitary, i.e., \(\transp{\conj{\vmX}}\vmX = \adj{\vmX}\vmX = \Id_n\). For k > 1, the class represents the product manifold of unitary matrices \(\U(n)^k\). In that case points on the manifold are represented as arrays of shape (k, n, n).

The metric is the usual Euclidean one inherited from the embedding space \((\C^{n \times n})^k\), i.e., \(\inner{\vmA}{\vmB} = \Re\tr(\adj{\vmA}\vmB)\). As such \(\U(n)^k\) forms a Riemannian submanifold.

The tangent space \(\tangent{\vmX}\U(n)\) at a point \(\vmX\) is given by \(\tangent{\vmX}\U(n) = \set{\vmX \vmOmega \in \C^{n \times n} \mid \vmOmega = -\adj{\vmOmega}} = \vmX \adj{\Skew}(n)\), where \(\adj{\Skew}(n)\) denotes the set of skew-Hermitian matrices. This corresponds to the Lie algebra of \(\U(n)\), a fact which is used here to conveniently represent tangent vectors numerically by their skew-Hermitian factor. The method embedding() can be used to convert a tangent vector from its Lie algebra representation to the embedding space representation.

Parameters

• n (int) – The dimension of the space that elements of the group act on.

• k (int) – The number of elements in the product of groups.

• retraction (str) – The type of retraction to use. Possible choices are qr and polar.

Note

The default QR-based retraction is only a first-order approximation of the exponential map. Use of an SVD-based second-order retraction can be enabled by setting the retraction argument to “polar”.

The procedure to generate random points on the manifold sampled uniformly from the Haar measure is detailed in [Mez2006].

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

Oblique Manifold

class pymanopt.manifolds.oblique.Oblique(m, n)

Bases: pymanopt.manifolds.manifold.RiemannianSubmanifold

Manifold of matrices with unit-norm columns.

The oblique manifold deals with matrices of size m x n such that each column has unit Euclidean norm, i.e., is a point on the unit sphere in \(\R^m\). The metric is such that the oblique manifold is a Riemannian submanifold of the space of m x n matrices with the usual trace inner product.

Parameters

• m (int) – The number of rows of each matrix.

• n (int) – The number of columns of each matrix.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

property dim: int

The dimension of the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

property num_values: int

Total number of values representing a point on the manifold.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

Symmetric Positive Definite Matrices

class pymanopt.manifolds.positive_definite.SymmetricPositiveDefinite(n, *, k=1)

Bases: pymanopt.manifolds.positive_definite._PositiveDefiniteBase

Manifold of symmetric positive definite matrices.

Points on the manifold and tangent vectors are represented as arrays of shape k x n x n if k > 1, and n x n if k == 1.

Parameters

• n (int) – The size of matrices in the manifold, i.e., the number of rows and columns of each element.

• k (int) – The number of elements in the product geometry.

Note

The geometry is based on the discussion in chapter 6 of [Bha2007]. Also see [SH2015] for more details.

The second-order retraction is taken from [JVV2012].

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.positive_definite.HermitianPositiveDefinite(n, *, k=1)

Bases: pymanopt.manifolds.positive_definite._PositiveDefiniteBase

Manifold of Hermitian positive definite matrices.

Points on the manifold and tangent vectors are represented as arrays of shape k x n x n if k > 1, and n x n if k == 1.

Parameters

• n (int) – The size of matrices in the manifold, i.e., the number of rows and columns of each element.

• k (int) – The number of elements in the product geometry.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.positive_definite.SpecialHermitianPositiveDefinite(n, *, k=1)

Bases: pymanopt.manifolds.positive_definite._PositiveDefiniteBase

Manifold of hermitian positive definite matrices with unit determinant.

Points on the manifold and tangent vectors are represented as arrays of shape k x n x n if k > 1, and n x n if k == 1.

Parameters

• n (int) – The size of matrices in the manifold, i.e., the number of rows and columns of each element.

• k (int) – The number of elements in the product geometry.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

Positive Semidefinite Matrices

class pymanopt.manifolds.psd.PSDFixedRank(n, k)

Bases: pymanopt.manifolds.psd._PSDFixedRank

Manifold of fixed-rank positive semidefinite (PSD) matrices.

Parameters

• n (int) – Number of rows and columns of a point in the ambient space.

• k (int) – Rank of matrices in the ambient space.

Note

A point \(\vmX\) on the manifold is parameterized as \(\vmX = \vmY\transp{\vmY}\) where \(\vmY\) is a real matrix of size n x k and rank k. As such, \(\vmX\) is symmetric, positive semidefinite with rank k.

Tangent vectors \(\dot{\vmY}\) are represented as matrices of the same size as points on the manifold so that tangent vectors in the ambient space \(\R^{n \times n}\) correspond to \(\dot{\vmX} = \vmY\transp{\dot{\vmY}} + \dot{\vmY}\transp{\vmY}\). The metric is the canonical Euclidean metric on \(\R^{n \times k}\).

Since for any orthogonal matrix \(\vmQ\) of size \(k \times k\) it holds that \(\vmY\vmQ\transp{(\vmY\vmQ)} = \vmY\transp{\vmY}\), we identify all matrices of the form \(\vmY\vmQ\) with an equivalence class. This set of equivalence classes then forms a Riemannian quotient manifold which is implemented here.

Notice that this manifold is not complete: if optimization leads points to be rank-deficient, the geometry will break down. Hence, this geometry should only be used if it is expected that the points of interest will have rank exactly k. Reduce k if that is not the case.

The quotient geometry implemented here is the simplest case presented in [JBA+2010].

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.psd.PSDFixedRankComplex(n, k)

Bases: pymanopt.manifolds.psd._PSDFixedRank

Manifold of fixed-rank Hermitian positive semidefinite (PSD) matrices.

Parameters

• n – Number of rows and columns of a point in the ambient space.

• k – Rank of matrices in the ambient space.

Note

A point \(\vmX\) on the manifold is parameterized as \(\vmX = \vmY\conj{\vmY}\), where \(\vmY\) is a complex matrix of size n x k and rank k.

Tangent vectors are represented as matrices of the same shape as points on the manifold.

For any point \(\vmY\) on the manifold, given any complex unitary matrix \(\vmU \in \C^{k \times k}\), we say \(\vmY\vmU\) is equivalent to \(\vmY\) since \(\vmY\) and \(\vmY\vmU\) are indistinguishable in the ambient space \(\C^{n \times n}\), i.e., \(\vmX = \vmY\vmU\conj{(\vmY\vmU)} = \vmY\conj{\vmY}\). Therefore, the set of equivalence classes forms a Riemannian quotient manifold \(\C^{n \times k} / \U(k)\) where \(\U(k)\) denotes the unitary group. The metric is the usual real trace inner product.

Notice that this manifold is not complete: if optimization leads points to be rank-deficient, the geometry will break down. Hence, this geometry should only be used if it is expected that the points of interest will have rank exactly k. Reduce k if that is not the case.

The implementation follows the quotient geometry originally described in [Yat2013].

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

class pymanopt.manifolds.psd.Elliptope(n, k)

Bases: pymanopt.manifolds.manifold.Manifold, pymanopt.manifolds.manifold.RetrAsExpMixin

Manifold of fixed-rank PSD matrices with unit diagonal elements.

Parameters

• n – Number of rows and columns of a point in the ambient space.

• k – Rank of matrices in the ambient space.

Note

A point \(\vmX\) on the manifold is parameterized as \(\vmX = \vmY\transp{\vmY}\) where \(\vmY\) is a matrix of size n x k and rank k. As such, \(\vmX\) is symmetric, positive semidefinite with rank k.

Tangent vectors are represented as matrices of the same size as points on the manifold so that tangent vectors in the ambient space are of the form \(\dot{\vmX} = \vmY \transp{\dot{\vmY}} + \dot{\vmY}\transp{\vmY}\) and \(\dot{X}_{ii} = 0\). The metric is the canonical Euclidean metric on \(\R^{n \times k}\).

The diagonal constraints on \(X_{ii} = 1\) translate to unit-norm constraints on the rows of \(\vmY\): \(\norm{\vmy_i} = 1\) where \(\vmy_i\) denotes the i-th column of \(\transp{\vmY}\). Without any further restrictions, this coincides with the oblique manifold (see pymanopt.manifolds.oblique.Oblique). However, since for any orthogonal matrix \(\vmQ\) of size k, it holds that \(\vmY\vmQ\transp{(\vmY\vmQ)} = \vmY\transp{\vmY}\), we “group” all matrices of the form \(\vmY\vmQ\) in an equivalence class. This set of equivalence classes is a Riemannian quotient manifold that is implemented here.

Note that this geometry formally breaks down at rank-deficient points. This does not appear to be a major issue in practice when optimization algorithms converge to rank-deficient points, but convergence theorems no longer hold. As an alternative, you may try using the oblique manifold since it does not break down at rank drop.

The geometry is taken from [JBA+2010].

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

Fixed-Rank Matrices

class pymanopt.manifolds.fixed_rank.FixedRankEmbedded(m, n, k)

Bases: pymanopt.manifolds.manifold.RiemannianSubmanifold

Manifold of fixed rank matrices.

Parameters

• m (int) – The number of rows of matrices in the ambient space.

• n (int) – The number of columns of matrices in the ambient space.

• k (int) – The rank of matrices.

The manifold of m x n real matrices of fixed rank k. For efficiency purposes, points on the manifold are represented with a truncated singular value decomposition instead of full matrices of size m x n. Specifically, a point is represented as a tuple (u, s, vt) of three arrays. The arrays u, s and vt have shapes (m, k), (k,) and (k, n), respectively, and the rank k matrix which they represent can be recovered by the product u @ np.diag(s) @ vt.

Vectors Z in the ambient space are best represented as arrays of shape (m, n). If these are low-rank, they may also be represented as tuples of arrays (U, S, V) such that Z = U @ S @ V.T. There are no restrictions on what U, S and V are, as long as their product as indicated yields a real m x n matrix.

Tangent vectors are represented as tuples of the form (Up, M, Vp). The matrices Up (of size m x k) and Vp (of size n x k) obey the conditions np.allclose(Up.T @ U, 0) and np.allclose(Vp.T @ V, 0). The matrix M (of size k x k) is arbitrary. Such a structure corresponds to the tangent vector Z = u @ M @ vt + Up @ vt + u * Vp.T in the ambient space of m x n matrices at a point (u, s, vt).

The chosen geometry yields a Riemannian submanifold of the embedding space \(\R^{m \times n}\) equipped with the usual trace inner product.

Note

• The implementation follows the embedded geometry described in [Van2013].

• The class is currently not compatible with the pymanopt.optimizers.trust_regions.TrustRegions optimizer.

• Details on the implementation of euclidean_to_riemannian_gradient() can be found at https://j-towns.github.io/papers/svd-derivative.pdf.

• The second-order retraction follows results presented in [AM2012].

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

projection(point, vector)

Project vector in the ambient space to the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space.

Returns

A tangent vector parameterized as a (Up, M, Vp).

Note

The argument vector must either be an array of shape (m, n) in the ambient space, or else a tuple (U, S, V) where U @ S @ V is in the ambient space (of low-rank matrices).

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

property dim: int

The dimension of the manifold.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

weingarten(point, tangent_vector, normal_vector)

Compute the Weingarten map of the manifold.

This map takes a vector tangent_vector in the tangent space at point and a vector normal_vector in the normal space at point to produce another tangent vector.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

• normal_vector – A vector orthogonal to the tangent space at point.

Returns

A tangent vector.

Positive Matrices

class pymanopt.manifolds.positive.Positive(m, n, *, k=1, use_parallel_transport=False)

Bases: pymanopt.manifolds.manifold.Manifold

The (product) manifold of positive matrices.

Parameters

• m (int) – The number of rows.

• n (int) – The number of columns.

• k (int) – The number of matrices in the product.

• use_parallel_transport (bool) – Flag whether to use a parallel transport for transport() or a transporter (the default).

Note

Points on the manifold are represented as arrays of size m x n (when k is 1), and k x m x n otherwise.

The tangent spaces of the manifold correspond to copies of \(\R^{m \times n}\). As such, tangent vectors are represented as arrays of the same shape as points on the manifold without any positivity constraints on the individual elements.

The Riemannian metric is the bi-invariant metric for positive definite matrices from chapter 6 of [Bha2007] on individual scalar coordinates of matrices. See also section 11.4 of [Bou2020] for further details.

The second-order retraction is taken from [JVV2012].

The parallel transport that is used when use_parallel_transport is True is taken from [SH2015].

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

property dim: int

The dimension of the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

property num_values: int

Total number of values representing a point on the manifold.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

Hyperbolic Space

class pymanopt.manifolds.hyperbolic.PoincareBall(n, *, k=1)

Bases: pymanopt.manifolds.manifold.Manifold

The Poincare ball.

The Poincare ball of dimension n. Elements are represented as arrays of shape (n,) if k = 1. For k > 1, the class represents the product manifold of k Poincare balls of dimension n, in which case points are represented as arrays of shape (k, n).

Since the manifold is open, the tangent space at every point is a copy of \(\R^n\).

The Poincare ball is embedded in \(\R^n\) and is a Riemannian manifold, but it is not an embedded Riemannian submanifold since the metric is not inherited from the Euclidean inner product of its ambient space. Instead, the Riemannian metric is conformal to the Euclidean one (angles are preserved), and it is given at every point \(\vmx\) by \(\inner{\vmu}{\vmv}_\vmx = \lambda_\vmx^2 \inner{\vmu}{\vmv}\) where \(\lambda_\vmx = 2 / (1 - \norm{\vmx}^2)\) is the conformal factor. This induces the following distance between two points \(\vmx\) and \(\vmy\) on the manifold:

\(\dist_\manM(\vmx, \vmy) = \arccosh\parens{1 + 2 \frac{\norm{\vmx - \vmy}^2}{(1 - \norm{\vmx}^2) (1 - \norm{\vmy}^2)}}.\)

The norm here is understood as the Euclidean norm in the ambient space.

Parameters

• n (int) – The dimension of the Poincare ball.

• k (int) – The number of elements in the product of Poincare balls.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

mobius_addition(point_a, point_b)

Möbius addition.

Special non-associative and non-commutative operation which is closed in the Poincare ball.

Parameters

• point_a – The first point.

• point_b – The second point.

Returns

The Möbius sum of point_a and point_b.

conformal_factor(point)

The conformal factor for a point.

Parameters

point – The point for which to compute the conformal factor.

Returns

The conformal factor. If point is a point on the product manifold of k Poincare balls, the return value will be an array of shape (k,1). The singleton dimension is explicitly kept to simplify multiplication of point by the conformal factor on product manifolds.

property dim: int

The dimension of the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

property num_values: int

Total number of values representing a point on the manifold.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

Product Manifold

class pymanopt.manifolds.product.Product(manifolds)

Bases: pymanopt.manifolds.manifold.Manifold

Cartesian product manifold.

Points on the manifold and tangent vectors are represented as lists of points and tangent vectors of the individual manifolds. The metric is obtained by element-wise extension of the individual manifolds.

Parameters

manifolds (Sequence[pymanopt.manifolds.manifold.Manifold]) – The collection of manifolds in the product.

property typical_dist

Returns the scale of the manifold.

This is used by the trust-regions optimizer to determine default initial and maximal trust-region radii.

Raises

NotImplementedError – If no typical_dist is defined.

norm(point, tangent_vector)

Computes the norm of a tangent vector at a point on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the tangent space at point.

Returns

The norm of tangent_vector.

inner_product(point, tangent_vector_a, tangent_vector_b)

Inner product between tangent vectors at a point on the manifold.

This method implements a Riemannian inner product between two tangent vectors tangent_vector_a and tangent_vector_b in the tangent space at point.

Parameters

• point – The base point.

• tangent_vector_a – The first tangent vector.

• tangent_vector_b – The second tangent vector.

Returns

The inner product between tangent_vector_a and tangent_vector_b in the tangent space at point.

dist(point_a, point_b)

The geodesic distance between two points on the manifold.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The distance between point_a and point_b on the manifold.

projection(point, vector)

Projects vector in the ambient space on the tangent space.

Parameters

• point – A point on the manifold.

• vector – A vector in the ambient space of the tangent space at point.

Returns

An element of the tangent space at point closest to vector in the ambient space.

to_tangent_space(point, vector)

Re-tangentialize a vector.

This method guarantees that vector is indeed a tangent vector at point on the manifold. Typically this simply corresponds to a call to meth:projection but may differ for certain manifolds.

Parameters

• point – A point on the manifold.

• vector – A vector close to the tangent space at point.

Returns

The tangent vector at point closest to vector.

euclidean_to_riemannian_gradient(point, euclidean_gradient)

Converts the Euclidean to the Riemannian gradient.

Parameters

• point – The point on the manifold at which the Euclidean gradient was evaluated.

• euclidean_gradient – The Euclidean gradient as a vector in the ambient space of the tangent space at point.

Returns

The Riemannian gradient at point. This must be a tangent vector at point.

euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)

Converts the Euclidean to the Riemannian Hessian.

This converts the Euclidean Hessian euclidean_hessian of a function at a point point along a tangent vector tangent_vector to the Riemannian Hessian of point along tangent_vector on the manifold.

Parameters

• point – The point on the manifold at which the Euclidean gradient and Hessian was evaluated.

• euclidean_gradient – The Euclidean gradient at point.

• euclidean_hessian – The Euclidean Hessian at point along the direction tangent_vector.

• tangent_vector – The tangent vector in the direction of which the Riemannian Hessian is to be calculated.

Returns

The Riemannian Hessian as a tangent vector at point.

exp(point, tangent_vector)

Computes the exponential map on the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

The point on the manifold reached by moving away from point along a geodesic in the direction of tangent_vector.

retraction(point, tangent_vector)

Retracts a tangent vector back to the manifold.

This generalizes the exponential map, and is often more efficient to compute numerically. It maps a vector tangent_vector in the tangent space at point back to the manifold.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector at point.

Returns

A point on the manifold reached by moving away from point in the direction of tangent_vector.

log(point_a, point_b)

Computes the logarithmic map on the manifold.

The logarithmic map log(point_a, point_b) produces a tangent vector in the tangent space at point_a that points in the direction of point_b. In other words, exp(point_a, log(point_a, point_b)) == point_b. As such it is the inverse of exp().

Parameters

• point_a – First point on the manifold.

• point_b – Second point on the manifold.

Returns

A tangent vector in the tangent space at point_a.

random_point()

Returns a random point on the manifold.

Returns

A randomly chosen point on the manifold.

random_tangent_vector(point)

Returns a random vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

A randomly chosen tangent vector in the tangent space at point.

transport(point_a, point_b, tangent_vector_a)

Compute transport of tangent vectors between tangent spaces.

This may either be a vector transport (a generalization of parallel transport) as defined in section 8.1 of [AMS2008], or a transporter (see e.g. section 10.5 of [Bou2020]). It transports a vector tangent_vector_a in the tangent space at point_a to the tangent space at point_b.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

• tangent_vector_a – The tangent vector at point_a to transport to the tangent space at point_b.

Returns

A tangent vector at point_b.

pair_mean(point_a, point_b)

Computes the intrinsic mean of two points on the manifold.

Returns the intrinsic mean of two points point_a and point_b on the manifold, i.e., a point that lies mid-way between point_a and point_b on the geodesic arc joining them.

Parameters

• point_a – The first point on the manifold.

• point_b – The second point on the manifold.

Returns

The mid-way point between point_a and point_b.

zero_vector(point)

Returns the zero vector in the tangent space at point.

Parameters

point – A point on the manifold.

Returns

The origin of the tangent space at point.

property dim: int

The dimension of the manifold.

embedding(point, tangent_vector)

Convert tangent vector to ambient space representation.

Certain manifolds represent tangent vectors in a format that is more convenient for numerical calculations than their representation in the ambient space. Euclidean Hessian operators generally expect tangent vectors in their ambient space representation though. This method allows switching between the two possible representations, For most manifolds, embedding is simply the identity map.

Parameters

• point – A point on the manifold.

• tangent_vector – A tangent vector in the internal representation of the manifold.

Returns

The same tangent vector in the ambient space representation.

Note

This method is mainly needed internally by the pymanopt.core.problem.Problem class in order to convert tangent vectors to the representation expected by user-given or autodiff-generated Euclidean Hessian operators.

property num_values: int

Total number of values representing a point on the manifold.

property point_layout

The number of elements a point on a manifold consists of.

For most manifolds, which represent points as (potentially multi-dimensional) arrays, this will be 1, but other manifolds might represent points as tuples or lists of arrays. In this case, point_layout describes how many elements such tuples/lists contain.