# 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 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: x (tensor) – point on the manifold atol (float) – absolute tolerance as in numpy.allclose() rtol (float) – relative tolerance as in numpy.allclose() check result and the reason of fail if any 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 check result and the reason of fail if any 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 check result and the reason of fail if any 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 :mathx 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=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 boolean indicating if tensor is valid and reason of failure if False 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: 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 boolean indicating if tensor is valid and reason of failure if False 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 boolean indicating if tensor is valid and reason of failure if False 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? boolean indicating if tensor is valid and reason of failure if False 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? distance between two points 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 grad vector in the Riemannian manifold 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$$ transported point 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 transported point 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 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? inner product (broadcasted) 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 tangent vector 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? inner product (broadcasted) 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 projected vector tensor
projx(x)[source]

Project point $$x$$ on the manifold.

Parameters: x (tensor) – point to be projected projected point 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$$ transported point 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 transported point and vectors 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$$ transported tensor(s) 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, non-exact, 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 transported tensor 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 transported tensor tensor