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

_check_point_on_manifold
(x, *, atol=1e05, rtol=1e05)[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:  x (tensor) – point on the manifold
 atol (float) – absolute tolerance as in
numpy.allclose()
 rtol (float) – relative tolerance as in
numpy.allclose()
Returns: check result and the reason of fail if any
Return type:

_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: Returns: check result and the reason of fail if any
Return type:

_check_vector_on_tangent
(x, u, *, atol=1e05, rtol=1e05)[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:

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=1e05, rtol=1e05)[source] Check if point :math`x` is lying on the manifold and raise an error with informative message on failure.
Parameters:  x (tensor) – point on the manifold
 atol (float) – absolute tolerance as in
numpy.allclose()
 rtol (float) – relative tolerance as in
numpy.allclose()

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=1e05, rtol=1e05)[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: Notes
This check is compatible to what optimizer expects, last dimensions are treated as manifold dimensions

check_point_on_manifold
(x, *, explain=False, atol=1e05, rtol=1e05)[source] Check if point \(x\) is lying on the manifold.
Parameters:  x (tensor) – point on the manifold
 atol (float) – absolute tolerance as in
numpy.allclose()
 rtol (float) – relative tolerance as in
numpy.allclose()
 explain (bool) – return an additional information on check
Returns: boolean indicating if tensor is valid and reason of failure if False
Return type: 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: 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=1e05, rtol=1e05)[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:

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

expmap_transp
(x, u, v)[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
Returns: transported point
Return type: tensor

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 singleline and multiline 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)[source] Perform a retraction + vector transport at once.
Parameters:  x (tensor) – point on the manifold
 v (tensor) – tangent vector at point \(x\) to be transported
 u (tensor) – tangent vector at point \(x\) (required keyword only argument)
 order (int) – order of retraction approximation, by default uses the simplest. Possible choices depend on a concrete manifold and 1 stays for exponential map
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)[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\)
Returns: transported tensor(s)
Return type: tensor or tuple of tensors

transp_follow_expmap
(x, u, v)[source] Perform vector transport following \(u\): \(\mathfrac{T}_{x\to\operatorname{Exp}(x, u)}(v)\).
Here, \(\operatorname{Exp}\) is the best possible approximation of the true exponential map. There are cases when the exact variant is hard or impossible implement, therefore a fallback, nonexact, implementation is used.
Parameters:  x (tensor) – point on the manifold
 u (tensor) – tangent vector at point \(x\)
 v (tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type: tensor

transp_follow_retr
(x, u, v)[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
Returns: transported tensor
Return type: tensor
