Manifolds

All manifolds share same API. Some manifols may have several implementations of retraction operation, every implementation has a corresponding class.

class geoopt.manifolds.Euclidean(ndim=0)[source]

Simple Euclidean manifold, every coordinate is treated as an independent element.

Parameters:ndim (int) – number of trailing dimensions treated as manifold dimensions. All the operations acting on cuch as inner products, etc will respect the ndim.
dist(x, y, *, keepdim=False)[source]

Compute distance between 2 points on the manifold that is the shortest path along geodesics.

Parameters:
  • x (tensor) – point on the manifold
  • y (tensor) – point on the manifold
  • keepdim (bool) – keep the last dim?
Returns:

distance between two points

Return type:

scalar

egrad2rgrad(x, u)[source]

Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – gradient to be projected
Returns:

grad vector in the Riemannian manifold

Return type:

tensor

expmap(x, u)[source]

Perform an exponential map \(\operatorname{Exp}_x(u)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

expmap_transp(x, u, v, *more)[source]

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

extra_repr()[source]

Set the extra representation of the module

To print customized extra information, you should reimplement this method in your own modules. Both single-line and multi-line strings are acceptable.

inner(x, u, v=None, *, keepdim=False)[source]

Inner product for tangent vectors at point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor (optional)) – tangent vector at point \(x\)
  • keepdim (bool) – keep the last dim?
Returns:

inner product (broadcasted)

Return type:

scalar

logmap(x, y)[source]

Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).

Parameters:
  • x (tensor) – point on the manifold
  • y (tensor) – point on the manifold
Returns:

tangent vector

Return type:

tensor

norm(x, u, *, keepdim=False)[source]

Norm of a tangent vector at point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • keepdim (bool) – keep the last dim?
Returns:

inner product (broadcasted)

Return type:

scalar

proju(x, u)[source]

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

projx(x)[source]

Project point \(x\) on the manifold.

Parameters:x (tensor) – point to be projected
Returns:projected point
Return type:tensor
random_normal(*size, mean=0.0, std=1.0, device=None, dtype=None)[source]

Create a point on the manifold, measure is induced by Normal distribution.

Parameters:
  • size (shape) – the desired shape
  • mean (float|tensor) – mean value for the Normal distribution
  • std (float|tensor) – std value for the Normal distribution
  • device (torch.device) – the desired device
  • dtype (torch.dtype) – the desired dtype
Returns:

random point on the manifold

Return type:

ManifoldTensor

retr(x, u)[source]

Perform a retraction from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

retr_transp(x, u, v, *more)

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

transp(x, y, v, *more)[source]

Perform vector transport \(\mathfrac{T}_{x\to y}(v)\).

Parameters:
  • x (tensor) – start point on the manifold
  • y (tensor) – target point on the manifold
  • v (tensor) – tangent vector at point \(x\)
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_expmap(x, u, v, *more)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_retr(x, u, v, *more)

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

class geoopt.manifolds.Stiefel(**kwargs)[source]

Manifold induced by the following matrix constraint:

\[\begin{split}X^\top X = I\\ X \in \mathrm{R}^{n\times m}\\ n \ge m\end{split}\]
Parameters:canonical (bool) – Use canonical inner product instead of euclidean one (defaults to canonical)
projx(x)[source]

Project point \(x\) on the manifold.

Parameters:x (tensor) – point to be projected
Returns:projected point
Return type:tensor
random_naive(*size, dtype=None, device=None)[source]

Naive approach to get random matrix on Stiefel manifold.

A helper function to sample a random point on the Stiefel manifold. The measure is non-uniform for this method, but fast to compute.

Parameters:
  • size (shape) – the desired output shape
  • dtype (torch.dtype) – desired dtype
  • device (torch.device) – desired device
Returns:

random point on Stiefel manifold

Return type:

ManifoldTensor

class geoopt.manifolds.CanonicalStiefel(**kwargs)[source]

Stiefel Manifold with Canonical inner product

Manifold induced by the following matrix constraint:

\[\begin{split}X^\top X = I\\ X \in \mathrm{R}^{n\times m}\\ n \ge m\end{split}\]
egrad2rgrad(x, u)

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

expmap(x, u)

Perform a retraction from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

expmap_transp(x, u, v, *more)

Perform an retraction and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vector at point \(x\) to be transported
Returns:

transported point and vectors

Return type:

tuple of tensors

Notes

Sometimes this is a far more optimal way to preform retraction + vector transport

inner(x, u, v=None, *, keepdim=False)[source]

Inner product for tangent vectors at point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor (optional)) – tangent vector at point \(x\)
  • keepdim (bool) – keep the last dim?
Returns:

inner product (broadcasted)

Return type:

scalar

proju(x, u)[source]

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

retr(x, u)[source]

Perform a retraction from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

retr_transp(x, u, v, *more)[source]

Perform an retraction and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vector at point \(x\) to be transported
Returns:

transported point and vectors

Return type:

tuple of tensors

Notes

Sometimes this is a far more optimal way to preform retraction + vector transport

transp_follow_expmap(x, u, v, *more)

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{retr}(x, u)}(v)\).

This operation is sometimes is much more simpler and can be optimized.

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_retr(x, u, v, *more)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{retr}(x, u)}(v)\).

This operation is sometimes is much more simpler and can be optimized.

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

class geoopt.manifolds.EuclideanStiefel(**kwargs)[source]

Stiefel Manifold with Euclidean inner product

Manifold induced by the following matrix constraint:

\[\begin{split}X^\top X = I\\ X \in \mathrm{R}^{n\times m}\\ n \ge m\end{split}\]
egrad2rgrad(x, u)

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

expmap(x, u)[source]

Perform an exponential map \(\operatorname{Exp}_x(u)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

expmap_transp(x, u, v, *more)[source]

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

inner(x, u, v=None, *, keepdim=False)[source]

Inner product for tangent vectors at point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor (optional)) – tangent vector at point \(x\)
  • keepdim (bool) – keep the last dim?
Returns:

inner product (broadcasted)

Return type:

scalar

proju(x, u)[source]

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

retr(x, u)[source]

Perform a retraction from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

retr_transp(x, u, v, *more)[source]

Perform an retraction and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vector at point \(x\) to be transported
Returns:

transported point and vectors

Return type:

tuple of tensors

Notes

Sometimes this is a far more optimal way to preform retraction + vector transport

transp(x, y, v, *more)[source]

Perform vector transport \(\mathfrac{T}_{x\to y}(v)\).

Parameters:
  • x (tensor) – start point on the manifold
  • y (tensor) – target point on the manifold
  • v (tensor) – tangent vector at point \(x\)
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_expmap(x, u, v, *more)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_retr(x, u, v, *more)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{retr}(x, u)}(v)\).

This operation is sometimes is much more simpler and can be optimized.

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

class geoopt.manifolds.EuclideanStiefelExact(**kwargs)[source]

Stiefel Manifold with Euclidean inner product

Manifold induced by the following matrix constraint:

\[\begin{split}X^\top X = I\\ X \in \mathrm{R}^{n\times m}\\ n \ge m\end{split}\]

Notes

The implementation of retraction is an exact exponential map, this retraction will be used in optimization

extra_repr()[source]

Set the extra representation of the module

To print customized extra information, you should reimplement this method in your own modules. Both single-line and multi-line strings are acceptable.

retr(x, u)

Perform an exponential map \(\operatorname{Exp}_x(u)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

retr_transp(x, u, v, *more)

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

transp_follow_retr(x, u, v, *more)

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

class geoopt.manifolds.Sphere(intersection=None, complement=None)[source]

Sphere manifold induced by the following constraint

\[\begin{split}\|x\|=1\\ x \in \mathbb{span}(U)\end{split}\]

where \(U\) can be parametrized with compliment space or intersection.

Parameters:
  • intersection (tensor) – shape (..., dim, K), subspace to intersect with
  • complement (tensor) – shape (..., dim, K), subspace to compliment

See also

SphereExact

dist(x, y, *, keepdim=False)[source]

Compute distance between 2 points on the manifold that is the shortest path along geodesics.

Parameters:
  • x (tensor) – point on the manifold
  • y (tensor) – point on the manifold
  • keepdim (bool) – keep the last dim?
Returns:

distance between two points

Return type:

scalar

egrad2rgrad(x, u)

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

expmap(x, u)[source]

Perform an exponential map \(\operatorname{Exp}_x(u)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

expmap_transp(x, u, v, *more)[source]

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

inner(x, u, v=None, *, keepdim=False)[source]

Inner product for tangent vectors at point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor (optional)) – tangent vector at point \(x\)
  • keepdim (bool) – keep the last dim?
Returns:

inner product (broadcasted)

Return type:

scalar

logmap(x, y)[source]

Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).

Parameters:
  • x (tensor) – point on the manifold
  • y (tensor) – point on the manifold
Returns:

tangent vector

Return type:

tensor

proju(x, u)[source]

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

projx(x)[source]

Project point \(x\) on the manifold.

Parameters:x (tensor) – point to be projected
Returns:projected point
Return type:tensor
random_uniform(*size, dtype=None, device=None)[source]

Uniform random measure on Sphere manifold.

Parameters:
  • size (shape) – the desired output shape
  • dtype (torch.dtype) – desired dtype
  • device (torch.device) – desired device
Returns:

random point on Sphere manifold

Return type:

ManifoldTensor

Notes

In case of projector on the manifold, dtype and device are set automatically and shouldn’t be provided. If you provide them, they are checked to match the projector device and dtype

retr(x, u)[source]

Perform a retraction from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

retr_transp(x, u, v, *more)[source]

Perform an retraction and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vector at point \(x\) to be transported
Returns:

transported point and vectors

Return type:

tuple of tensors

Notes

Sometimes this is a far more optimal way to preform retraction + vector transport

transp(x, y, v, *more)[source]

Perform vector transport \(\mathfrac{T}_{x\to y}(v)\).

Parameters:
  • x (tensor) – start point on the manifold
  • y (tensor) – target point on the manifold
  • v (tensor) – tangent vector at point \(x\)
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_expmap(x, u, v, *more)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_retr(x, u, v, *more)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{retr}(x, u)}(v)\).

This operation is sometimes is much more simpler and can be optimized.

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

class geoopt.manifolds.SphereExact(intersection=None, complement=None)[source]

Sphere manifold induced by the following constraint

\[\begin{split}\|x\|=1\\ x \in \mathbb{span}(U)\end{split}\]

where \(U\) can be parametrized with compliment space or intersection.

Parameters:
  • intersection (tensor) – shape (..., dim, K), subspace to intersect with
  • complement (tensor) – shape (..., dim, K), subspace to compliment

See also

Sphere

Notes

The implementation of retraction is an exact exponential map, this retraction will be used in optimization

extra_repr()[source]

Set the extra representation of the module

To print customized extra information, you should reimplement this method in your own modules. Both single-line and multi-line strings are acceptable.

retr(x, u)

Perform an exponential map \(\operatorname{Exp}_x(u)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

retr_transp(x, u, v, *more)

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

transp_follow_retr(x, u, v, *more)

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

class geoopt.manifolds.PoincareBall(c=1.0)[source]

Poincare ball model, see more in Poincare Ball model.

Parameters:c (float|tensor) – ball negative curvature

Notes

It is extremely recommended to work with this manifold in double precision

dist(x, y, *, keepdim=False, dim=-1)[source]

Compute distance between 2 points on the manifold that is the shortest path along geodesics.

Parameters:
  • x (tensor) – point on the manifold
  • y (tensor) – point on the manifold
  • keepdim (bool) – keep the last dim?
Returns:

distance between two points

Return type:

scalar

egrad2rgrad(x, u, *, dim=-1)[source]

Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – gradient to be projected
Returns:

grad vector in the Riemannian manifold

Return type:

tensor

expmap(x, u, *, project=True, dim=-1)[source]

Perform an exponential map \(\operatorname{Exp}_x(u)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

expmap_transp(x, u, v, *more, dim=-1, project=True)[source]

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

inner(x, u, v=None, *, keepdim=False, dim=-1)[source]

Inner product for tangent vectors at point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor (optional)) – tangent vector at point \(x\)
  • keepdim (bool) – keep the last dim?
Returns:

inner product (broadcasted)

Return type:

scalar

logmap(x, y, *, dim=-1)[source]

Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).

Parameters:
  • x (tensor) – point on the manifold
  • y (tensor) – point on the manifold
Returns:

tangent vector

Return type:

tensor

norm(x, u, *, keepdim=False, dim=-1)[source]

Norm of a tangent vector at point \(x\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • keepdim (bool) – keep the last dim?
Returns:

inner product (broadcasted)

Return type:

scalar

proju(x, u)[source]

Project vector \(u\) on a tangent space for \(x\), usually is the same as egrad2rgrad().

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector to be projected
Returns:

projected vector

Return type:

tensor

projx(x, dim=-1)[source]

Project point \(x\) on the manifold.

Parameters:x (tensor) – point to be projected
Returns:projected point
Return type:tensor
random_normal(*size, mean=0, std=1)[source]

Create a point on the manifold, measure is induced by Normal distribution on the tangent space of zero.

Parameters:
  • size (shape) – the desired shape
  • mean (float|tensor) – mean value for the Normal distribution
  • std (float|tensor) – std value for the Normal distribution
Returns:

random point on the PoincareBall manifold

Return type:

ManifoldTensor

Notes

The device and dtype will match the device and dtype of the Manifold

retr(x, u, *, dim=-1)[source]

Perform a retraction from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

retr_transp(x, u, v, *more, dim=-1)[source]

Perform an retraction and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vector at point \(x\) to be transported
Returns:

transported point and vectors

Return type:

tuple of tensors

Notes

Sometimes this is a far more optimal way to preform retraction + vector transport

transp(x, y, v, *more, dim=-1)[source]

Perform vector transport \(\mathfrac{T}_{x\to y}(v)\).

Parameters:
  • x (tensor) – start point on the manifold
  • y (tensor) – target point on the manifold
  • v (tensor) – tangent vector at point \(x\)
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_expmap(x, u, v, *more, dim=-1, project=True)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

transp_follow_retr(x, u, v, *more, dim=-1)[source]

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{retr}(x, u)}(v)\).

This operation is sometimes is much more simpler and can be optimized.

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors

class geoopt.manifolds.PoincareBallExact(c=1.0)[source]

Poincare ball model, see more in Poincare Ball model.

Parameters:c (float|tensor) – ball negative curvature

Notes

It is extremely recommended to work with this manifold in double precision

The implementation of retraction is an exact exponential map, this retraction will be used in optimization.

See also

PoincareBall

extra_repr()[source]

Set the extra representation of the module

To print customized extra information, you should reimplement this method in your own modules. Both single-line and multi-line strings are acceptable.

retr(x, u, *, project=True, dim=-1)

Perform an exponential map \(\operatorname{Exp}_x(u)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

retr_transp(x, u, v, *more, dim=-1, project=True)

Perform an exponential map and vector transport from point \(x\) with given direction \(u\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported point

Return type:

tensor

Notes

By default, no error is raised if exponential map is not implemented. If so, the best approximation to exponential map is applied instead.

transp_follow_retr(x, u, v, *more, dim=-1, project=True)

Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – tangent vector at point \(x\)
  • v (tensor) – tangent vector at point \(x\) to be transported
  • more (tensors) – other tangent vectors at point \(x\) to be transported
Returns:

transported tensor(s)

Return type:

tensor or tuple of tensors