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
- class pymanopt.manifolds.manifold.Manifold(name, dimension, point_layout=1)[source]
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
is1
. For more complicated manifolds which might represent points as a tuple or list ofn
arrays, point_layout would ben
. Finally, in the special case of thepymanopt.manifolds.product.Product
manifoldpoint_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
andpymanopt.optimizers.conjugate_gradient.ConjugateGradient
requireeuclidean_to_riemannian_gradient()
to be implemented but noteuclidean_to_riemannian_hessian()
. Second-order optimizers such aspymanopt.optimizers.trust_regions.TrustRegions
will requireeuclidean_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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.- Return type
float
- abstract projection(point, vector)[source]
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 tovector
in the ambient space.
- abstract norm(point, tangent_vector)[source]
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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- abstract random_tangent_vector(point)[source]
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)[source]
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)[source]
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
andpoint_b
on the manifold.
- euclidean_to_riemannian_gradient(point, euclidean_gradient)[source]
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 atpoint
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 atpoint
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 oftangent_vector
.
- exp(point, tangent_vector)[source]
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- pair_mean(point_a, point_b)[source]
Computes the intrinsic mean of two points on the manifold.
Returns the intrinsic mean of two points
point_a
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_b
.
- to_tangent_space(point, vector)[source]
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- embedding(point, tangent_vector)[source]
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)[source]
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 theweingarten()
method, the class provides a generic implementation of theeuclidean_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)[source]
Compute the Weingarten map of the manifold.
This map takes a vector
tangent_vector
in the tangent space atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
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 atpoint
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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
andpoint_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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 tovector
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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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
.
Euclidean Space
- class pymanopt.manifolds.euclidean.Euclidean(*shape)[source]
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\). Forshape == (m, n)
, it corresponds to the manifold ofm x n
matrices equipped with the standard trace inner product. Forshape == (n1, n2, ..., nk)
, the class represents the manifold of tensors of shapen1 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
andpoint_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 atpoint
.
- 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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 tovector
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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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.Symmetric(n, k=1)[source]
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. Ifk > 1
then this is the product manifold ofk
symmetricn x n
matrices represented as arrays of shape(k, n, n)
.- projection(point, vector)[source]
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 tovector
in the ambient space.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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
andpoint_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 atpoint
.
- 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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
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. Ifk > 1
then this is the product manifold ofk
skew-symmetricn x n
matrices represented as arrays of shape(k, n, n)
.- projection(point, vector)[source]
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 tovector
in the ambient space.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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
andpoint_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 atpoint
.
- 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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
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
andpoint_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 atpoint
.
- 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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 tovector
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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
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
andpoint_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 atpoint
.
- 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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 tovector
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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
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
andpoint_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 atpoint
.
- 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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 tovector
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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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')[source]
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)
ifk == 1
. Fork > 1
, the class represents the product manifold ofk
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
andpolar
.
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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- weingarten(point, tangent_vector, normal_vector)[source]
Compute the Weingarten map of the manifold.
This map takes a vector
tangent_vector
in the tangent space atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
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 atpoint
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 oftangent_vector
.
- norm(point, tangent_vector)[source]
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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- exp(point, tangent_vector)[source]
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 oftangent_vector
.
- zero_vector(point)[source]
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
andpoint_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 atpoint
.
- 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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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)[source]
Bases:
pymanopt.manifolds.grassmann._GrassmannBase
The Grassmann manifold.
This is the manifold of subspaces of dimension
p
of a real vector space of dimensionn
. The optional argumentk
allows to optimize over the product ofk
Grassmann manifolds. Elements are represented asn x p
matrices ifk == 1
, and ask x n x p
arrays ifk > 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)[source]
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
andpoint_b
on the manifold.
- inner_product(point, tangent_vector_a, tangent_vector_b)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 atpoint
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 oftangent_vector
.
- random_point()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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 atpoint
.
- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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)[source]
Bases:
pymanopt.manifolds.grassmann._GrassmannBase
The complex Grassmann manifold.
This is the manifold of subspaces of dimension
p
of complex vector space of dimensionn
. The optional argumentk
allows to optimize over the product ofk
complex Grassmannians. Elements are represented asn x p
matrices ifk == 1
, and ask x n x p
arrays ifk > 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)[source]
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
andpoint_b
on the manifold.
- inner_product(point, tangent_vector_a, tangent_vector_b)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 atpoint
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 oftangent_vector
.
- random_point()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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 atpoint
.
- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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)[source]
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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- norm(point, tangent_vector)[source]
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)[source]
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
andpoint_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)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 oftangent_vector
.
- retraction(point, tangent_vector)[source]
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 atpoint
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- pair_mean(point_a, point_b)[source]
Computes the intrinsic mean of two points on the manifold.
Returns the intrinsic mean of two points
point_a
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_b
.
- zero_vector(point)[source]
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 atpoint
.
- 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 atpoint
and a vectornormal_vector
in the normal space atpoint
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.
Special Orthogonal Group
- class pymanopt.manifolds.special_orthogonal_group.SpecialOrthogonalGroup(n, *, k=1, retraction='qr')[source]
Bases:
pymanopt.manifolds.manifold.RiemannianSubmanifold
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
andpolar
.
Note
The default SVD-based retraction is only a first-order approximation of the exponential map. Use of a second-order retraction can be enabled by instantiating the class with
SpecialOrthogonalGroup(n, k=k, retraction="polar")
.The procedure to generate random rotation matrices sampled uniformly from the Haar measure is detailed in [Mez2006].
- inner_product(point, tangent_vector_a, tangent_vector_b)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- norm(point, tangent_vector)[source]
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 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.
- dist(point_a, point_b)[source]
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
andpoint_b
on the manifold.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)[source]
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- embedding(point, tangent_vector)[source]
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_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 atpoint
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 oftangent_vector
.
- exp(point, tangent_vector)[source]
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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
.
- transport(point_a, point_b, tangent_vector_a)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- pair_mean(point_a, point_b)[source]
Computes the intrinsic mean of two points on the manifold.
Returns the intrinsic mean of two points
point_a
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_b
.
- property dim: int
The dimension of 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 atpoint
.
- 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 atpoint
and a vectornormal_vector
in the normal space atpoint
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.
Oblique Manifold
- class pymanopt.manifolds.oblique.Oblique(m, n)[source]
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 ofm 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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- norm(point, tangent_vector)[source]
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)[source]
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
andpoint_b
on the manifold.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 oftangent_vector
.
- retraction(point, tangent_vector)[source]
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 atpoint
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- pair_mean(point_a, point_b)[source]
Computes the intrinsic mean of two points on the manifold.
Returns the intrinsic mean of two points
point_a
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_b
.
- zero_vector(point)[source]
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 atpoint
.
- 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 atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
Bases:
pymanopt.manifolds.manifold.RiemannianSubmanifold
Manifold of symmetric positive definite matrices.
Points on the manifold and tangent vectors are represented as arrays of shape
k x n x n
ifk > 1
, andn x n
ifk == 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].
- 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.
- dist(point_a, point_b)[source]
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
andpoint_b
on the manifold.
- inner_product(point, tangent_vector_a, tangent_vector_b)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- euclidean_to_riemannian_gradient(point, euclidean_gradient)[source]
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 atpoint
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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
.
- norm(point, tangent_vector)[source]
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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- exp(point, tangent_vector)[source]
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 oftangent_vector
.
- retraction(point, tangent_vector)[source]
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 atpoint
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
.
- zero_vector(point)[source]
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.
- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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 Semidefinite Matrices
- class pymanopt.manifolds.psd.PSDFixedRank(n, k)[source]
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 rankk
. As such, \(\vmX\) is symmetric, positive semidefinite with rankk
.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
. Reducek
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
andpoint_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 atpoint
.
- 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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 tovector
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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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)[source]
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 rankk
.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
. Reducek
if that is not the case.The implementation follows the quotient geometry originally described in [Yat2013].
- random_point()[source]
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
andpoint_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 atpoint
.
- 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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 oftangent_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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- 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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 tovector
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 atpoint
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 oftangent_vector
.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- 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 atpoint_a
to the tangent space atpoint_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 atpoint_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)[source]
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 rankk
. As such, \(\vmX\) is symmetric, positive semidefinite with rankk
.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 sizek
, 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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- norm(point, tangent_vector)[source]
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)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- retraction(point, tangent_vector)[source]
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 atpoint
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 oftangent_vector
.
- euclidean_to_riemannian_gradient(point, euclidean_gradient)[source]
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 atpoint
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- zero_vector(point)[source]
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
andpoint_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 oftangent_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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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)[source]
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 rankk
. For efficiency purposes, points on the manifold are represented with a truncated singular value decomposition instead of full matrices of sizem x n
. Specifically, a point is represented as a tuple(u, s, vt)
of three arrays. The arraysu
,s
andvt
have shapes(m, k)
,(k,)
and(k, n)
, respectively, and the rankk
matrix which they represent can be recovered by the productu @ 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 thatZ = U @ S @ V.T
. There are no restrictions on whatU
,S
andV
are, as long as their product as indicated yields a realm x n
matrix.Tangent vectors are represented as tuples of the form
(Up, M, Vp)
. The matricesUp
(of sizem x k
) andVp
(of sizen x k
) obey the conditionsnp.allclose(Up.T @ U, 0)
andnp.allclose(Vp.T @ V, 0)
. The matrixM
(of sizek x k
) is arbitrary. Such a structure corresponds to the tangent vectorZ = u @ M @ vt + Up @ vt + u * Vp.T
in the ambient space ofm 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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- projection(point, vector)[source]
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)
whereU @ S @ V
is in the ambient space (of low-rank matrices).
- euclidean_to_riemannian_gradient(point, euclidean_gradient)[source]
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 atpoint
.
- retraction(point, tangent_vector)[source]
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 atpoint
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 oftangent_vector
.
- norm(point, tangent_vector)[source]
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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- to_tangent_space(point, vector)[source]
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- random_tangent_vector(point)[source]
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)[source]
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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- zero_vector(point)[source]
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
andpoint_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 pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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 oftangent_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 atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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 atpoint
and a vectornormal_vector
in the normal space atpoint
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)[source]
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
(whenk
is 1), andk 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
isTrue
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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- norm(point, tangent_vector)[source]
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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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)[source]
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
andpoint_b
on the manifold.
- euclidean_to_riemannian_gradient(point, euclidean_gradient)[source]
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 atpoint
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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)[source]
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 atpoint
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 oftangent_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
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
Hyperbolic Space
- class pymanopt.manifolds.hyperbolic.PoincareBall(n, *, k=1)[source]
Bases:
pymanopt.manifolds.manifold.Manifold
The Poincare ball.
The Poincare ball of dimension
n
. Elements are represented as arrays of shape(n,)
ifk = 1
. Fork > 1
, the class represents the product manifold ofk
Poincare balls of dimensionn
, 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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- norm(point, tangent_vector)[source]
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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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)[source]
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
andpoint_b
on the manifold.
- euclidean_to_riemannian_gradient(point, euclidean_gradient)[source]
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 atpoint
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 oftangent_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 atpoint
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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)[source]
Computes the intrinsic mean of two points on the manifold.
Returns the intrinsic mean of two points
point_a
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_b
.
- mobius_addition(point_a, point_b)[source]
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
andpoint_b
.
- conformal_factor(point)[source]
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 ofk
Poincare balls, the return value will be an array of shape(k,1)
. The singleton dimension is explicitly kept to simplify multiplication ofpoint
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
Product Manifold
- class pymanopt.manifolds.product.Product(manifolds)[source]
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)[source]
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)[source]
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
andtangent_vector_b
in the tangent space atpoint
.- 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
andtangent_vector_b
in the tangent space atpoint
.
- dist(point_a, point_b)[source]
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
andpoint_b
on the manifold.
- projection(point, vector)[source]
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 tovector
in the ambient space.
- to_tangent_space(point, vector)[source]
Re-tangentialize a vector.
This method guarantees that
vector
is indeed a tangent vector atpoint
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 tovector
.
- euclidean_to_riemannian_gradient(point, euclidean_gradient)[source]
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 atpoint
.
- euclidean_to_riemannian_hessian(point, euclidean_gradient, euclidean_hessian, tangent_vector)[source]
Converts the Euclidean to the Riemannian Hessian.
This converts the Euclidean Hessian
euclidean_hessian
of a function at a pointpoint
along a tangent vectortangent_vector
to the Riemannian Hessian ofpoint
alongtangent_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 directiontangent_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)[source]
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 oftangent_vector
.
- retraction(point, tangent_vector)[source]
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 atpoint
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 oftangent_vector
.
- log(point_a, point_b)[source]
Computes the logarithmic map on the manifold.
The logarithmic map
log(point_a, point_b)
produces a tangent vector in the tangent space atpoint_a
that points in the direction ofpoint_b
. In other words,exp(point_a, log(point_a, point_b)) == point_b
. As such it is the inverse ofexp()
.- 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()[source]
Returns a random point on the manifold.
- Returns
A randomly chosen point on the manifold.
- random_tangent_vector(point)[source]
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)[source]
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 atpoint_a
to the tangent space atpoint_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 atpoint_b
.
- Returns
A tangent vector at
point_b
.
- pair_mean(point_a, point_b)[source]
Computes the intrinsic mean of two points on the manifold.
Returns the intrinsic mean of two points
point_a
andpoint_b
on the manifold, i.e., a point that lies mid-way betweenpoint_a
andpoint_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
andpoint_b
.
- zero_vector(point)[source]
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.