Developer Guide

Base Manifold

The common base class for all manifolds is geoopt.manifolds.base.Manifold.

class geoopt.manifolds.base.Manifold(**kwargs)[source]
_assert_check_shape(shape, name)[source]

Util to check shape and raise an error if needed.

Exhaustive implementation for checking if a given point has valid dimension size, shape, etc. It will raise a ValueError if check is not passed

Parameters:
  • shape (tuple) – shape of point on the manifold
  • name (str) – name to be present in errors
Raises:

ValueError

_check_point_on_manifold(x, *, atol=1e-05, rtol=1e-05)[source]

Util to check point lies on the manifold.

Exhaustive implementation for checking if a given point lies on the manifold. It should return boolean and a reason of failure if check is not passed. You can assume assert_check_point is already passed beforehand

Parameters:
Returns:

check result and the reason of fail if any

Return type:

bool, str or None

_check_shape(shape, name)[source]

Util to check shape.

Exhaustive implementation for checking if a given point has valid dimension size, shape, etc. It should return boolean and a reason of failure if check is not passed

Parameters:
  • shape (tuple) – shape of point on the manifold
  • name (str) – name to be present in errors
Returns:

check result and the reason of fail if any

Return type:

bool, str or None

_check_vector_on_tangent(x, u, *, atol=1e-05, rtol=1e-05)[source]

Util to check a vector belongs to the tangent space of a point.

Exhaustive implementation for checking if a given point lies in the tangent space at x of the manifold. It should return a boolean indicating whether the test was passed and a reason of failure if check is not passed. You can assume assert_check_point is already passed beforehand

Parameters:
  • x (tensor) –
  • u (tensor) –
  • atol (float) – absolute tolerance
  • rtol – relative tolerance
Returns:

check result and the reason of fail if any

Return type:

bool, str or None

assert_check_point(x)[source]

Check if point is valid to be used with the manifold and raise an error with informative message on failure.

Parameters:x (tensor) – point on the manifold

Notes

This check is compatible to what optimizer expects, last dimensions are treated as manifold dimensions

assert_check_point_on_manifold(x, *, atol=1e-05, rtol=1e-05)[source]

Check if point :math`x` is lying on the manifold and raise an error with informative message on failure.

Parameters:
assert_check_vector(u)[source]

Check if vector is valid to be used with the manifold and raise an error with informative message on failure.

Parameters:u (tensor) – vector on the tangent plane

Notes

This check is compatible to what optimizer expects, last dimensions are treated as manifold dimensions

assert_check_vector_on_tangent(x, u, *, ok_point=False, atol=1e-05, rtol=1e-05)[source]

Check if u \(u\) is lying on the tangent space to x and raise an error on fail.

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector on the tangent space to \(x\)
  • atol (float) – absolute tolerance as in numpy.allclose()
  • rtol (float) – relative tolerance as in numpy.allclose()
  • ok_point (bool) – is a check for point required?
check_point(x, *, explain=False)[source]

Check if point is valid to be used with the manifold.

Parameters:
  • x (tensor) – point on the manifold
  • explain (bool) – return an additional information on check
Returns:

boolean indicating if tensor is valid and reason of failure if False

Return type:

bool

Notes

This check is compatible to what optimizer expects, last dimensions are treated as manifold dimensions

check_point_on_manifold(x, *, explain=False, atol=1e-05, rtol=1e-05)[source]

Check if point \(x\) is lying on the manifold.

Parameters:
Returns:

boolean indicating if tensor is valid and reason of failure if False

Return type:

bool

Notes

This check is compatible to what optimizer expects, last dimensions are treated as manifold dimensions

check_vector(u, *, explain=False)[source]

Check if vector is valid to be used with the manifold.

Parameters:
  • u (tensor) – vector on the tangent plane
  • explain (bool) – return an additional information on check
Returns:

boolean indicating if tensor is valid and reason of failure if False

Return type:

bool

Notes

This check is compatible to what optimizer expects, last dimensions are treated as manifold dimensions

check_vector_on_tangent(x, u, *, ok_point=False, explain=False, atol=1e-05, rtol=1e-05)[source]

Check if \(u\) is lying on the tangent space to x.

Parameters:
  • x (tensor) – point on the manifold
  • u (tensor) – vector on the tangent space to \(x\)
  • atol (float) – absolute tolerance as in numpy.allclose()
  • rtol (float) – relative tolerance as in numpy.allclose()
  • explain (bool) – return an additional information on check
  • ok_point (bool) – is a check for point required?
Returns:

boolean indicating if tensor is valid and reason of failure if False

Return type:

bool

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