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
.-
component_inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\) according to components of the manifold.
The result of the function is same as
inner
withkeepdim=True
for all the manifolds except ProductManifold. For this manifold it acts different way computing inner product for each component and then building an output correctly tiling and reshaping the result.Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
Returns: inner product component wise (broadcasted)
Return type: Notes
The purpose of this method is better adaptive properties in optimization since ProductManifold will “hide” the structure in public API.
-
dist
(x: torch.Tensor, y: torch.Tensor, *, keepdim=False) → torch.Tensor[source]¶ Compute distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: distance between two points
Return type:
-
dist2
(x: torch.Tensor, y: torch.Tensor, *, keepdim=False) → torch.Tensor[source]¶ Compute squared distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: squared distance between two points
Return type:
-
egrad2rgrad
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).
Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – gradient to be projected
Returns: grad vector in the Riemannian manifold
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
extra_repr
()[source]¶ Set the extra representation of the module
To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.
-
inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None, *, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
logmap
(x: torch.Tensor, y: torch.Tensor) → torch.Tensor[source]¶ Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
Returns: tangent vector
Return type:
-
norm
(x: torch.Tensor, u: torch.Tensor, *, keepdim=False)[source]¶ Norm of a tangent vector at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
origin
(*size, dtype=None, device=None, seed=42) → geoopt.tensor.ManifoldTensor[source]¶ Zero point origin.
Parameters: - size (shape) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (int) – ignored
Returns: Return type:
-
proju
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
projx
(x: torch.Tensor) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
random
(*size, mean=0.0, std=1.0, device=None, dtype=None) → geoopt.tensor.ManifoldTensor¶ 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:
-
random_normal
(*size, mean=0.0, std=1.0, device=None, dtype=None) → geoopt.tensor.ManifoldTensor[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:
-
retr
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
-
-
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) -
origin
(*size, dtype=None, device=None, seed=42) → torch.Tensor[source]¶ Identity matrix point origin.
Parameters: - size (shape) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (int) – ignored
Returns: Return type:
-
projx
(x: torch.Tensor) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
random
(*size, dtype=None, device=None) → torch.Tensor¶ 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:
-
random_naive
(*size, dtype=None, device=None) → torch.Tensor[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:
-
-
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: torch.Tensor, u: torch.Tensor) → torch.Tensor¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
expmap_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor]¶ Perform a retraction + vector transport at once.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point and vectors
Return type: Tuple[torch.Tensor, torch.Tensor]
Notes
Sometimes this is a far more optimal way to preform retraction + vector transport
-
inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None, *, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
proju
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
retr
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
retr_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor][source]¶ Perform a retraction + vector transport at once.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point and vectors
Return type: Tuple[torch.Tensor, torch.Tensor]
Notes
Sometimes this is a far more optimal way to preform retraction + vector transport
-
transp_follow_expmap
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → torch.Tensor¶ Perform vector transport following \(u\): \(\mathfrak{T}_{x\to\operatorname{retr}(x, u)}(v)\).
This operation is sometimes is much more simpler and can be optimized.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
transp_follow_retr
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport following \(u\): \(\mathfrak{T}_{x\to\operatorname{retr}(x, u)}(v)\).
This operation is sometimes is much more simpler and can be optimized.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
-
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: torch.Tensor, u: torch.Tensor) → torch.Tensor¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None, *, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
proju
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
retr
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
-
-
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 re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.
-
retr
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
retr_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor]¶ Perform an exponential map and vector transport from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point
Return type:
-
transp_follow_retr
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → torch.Tensor¶ Perform vector transport following \(u\): \(\mathfrak{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 (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
-
class
geoopt.manifolds.
Sphere
(intersection: torch.Tensor = None, complement: torch.Tensor = 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
-
dist
(x: torch.Tensor, y: torch.Tensor, *, keepdim=False) → torch.Tensor[source]¶ Compute distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: distance between two points
Return type:
-
egrad2rgrad
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None, *, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
logmap
(x: torch.Tensor, y: torch.Tensor) → torch.Tensor[source]¶ Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
Returns: tangent vector
Return type:
-
proju
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
projx
(x: torch.Tensor) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
random
(*size, dtype=None, device=None) → torch.Tensor¶ 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: 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
-
random_uniform
(*size, dtype=None, device=None) → torch.Tensor[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: 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: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
- intersection (tensor) – shape
-
class
geoopt.manifolds.
SphereExact
(intersection: torch.Tensor = None, complement: torch.Tensor = 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
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 re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.
-
retr
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
retr_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor]¶ Perform an exponential map and vector transport from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point
Return type:
-
transp_follow_retr
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → torch.Tensor¶ Perform vector transport following \(u\): \(\mathfrak{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 (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
- intersection (tensor) – shape
-
class
geoopt.manifolds.
Stereographic
(k=0.0, learnable=False)[source]¶ \(\kappa\)-Stereographic model.
Parameters: k (float|tensor) – sectional curvature \(\kappa\) of the manifold - k<0: Poincaré ball (stereographic projection of hyperboloid) - k>0: Stereographic projection of sphere - k=0: Euclidean geometry Notes
It is extremely recommended to work with this manifold in double precision.
http://andbloch.github.io/K-Stereographic-Model/ or \kappa-Stereographic Projection model
References
The functions for the mathematics in gyrovector spaces are taken from the following resources:
- [1] Ganea, Octavian, Gary Bécigneul, and Thomas Hofmann. “Hyperbolic
- neural networks.” Advances in neural information processing systems. 2018.
- [2] Bachmann, Gregor, Gary Bécigneul, and Octavian-Eugen Ganea. “Constant
- Curvature Graph Convolutional Networks.” arXiv preprint arXiv:1911.05076 (2019).
- [3] Skopek, Ondrej, Octavian-Eugen Ganea, and Gary Bécigneul.
- “Mixed-curvature Variational Autoencoders.” arXiv preprint arXiv:1911.08411 (2019).
- [4] Ungar, Abraham A. Analytic hyperbolic geometry: Mathematical
- foundations and applications. World Scientific, 2005.
- [5] Albert, Ungar Abraham. Barycentric calculus in Euclidean and
- hyperbolic geometry: A comparative introduction. World Scientific, 2010.
See also
StereographicExact
,PoincareBall
,PoincareBallExact
,SphereProjection
,SphereProjectionExact
-
dist
(x: torch.Tensor, y: torch.Tensor, *, keepdim=False, dim=-1) → torch.Tensor[source]¶ Compute distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: distance between two points
Return type:
-
dist2
(x: torch.Tensor, y: torch.Tensor, *, keepdim=False, dim=-1) → torch.Tensor[source]¶ Compute squared distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: squared distance between two points
Return type:
-
egrad2rgrad
(x: torch.Tensor, u: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).
Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – gradient to be projected
Returns: grad vector in the Riemannian manifold
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor, *, project=True, dim=-1) → torch.Tensor[source]¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
expmap_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor, *, dim=-1, project=True) → Tuple[torch.Tensor, torch.Tensor][source]¶ Perform an exponential map and vector transport from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point
Return type:
-
inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None, *, keepdim=False, dim=-1) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
logmap
(x: torch.Tensor, y: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
Returns: tangent vector
Return type:
-
norm
(x: torch.Tensor, u: torch.Tensor, *, keepdim=False, dim=-1) → torch.Tensor[source]¶ Norm of a tangent vector at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
origin
(*size, dtype=None, device=None, seed=42) → geoopt.tensor.ManifoldTensor[source]¶ Zero point origin.
Parameters: - size (shape) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (int) – ignored
Returns: random point on the manifold
Return type:
-
proju
(x: torch.Tensor, u: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
projx
(x: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
random
(*size, mean=0, std=1, dtype=None, device=None) → geoopt.tensor.ManifoldTensor¶ 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
- dtype (torch.dtype) – target dtype for sample, if not None, should match Manifold dtype
- device (torch.device) – target device for sample, if not None, should match Manifold device
Returns: random point on the PoincareBall manifold
Return type: Notes
The device and dtype will match the device and dtype of the Manifold
-
random_normal
(*size, mean=0, std=1, dtype=None, device=None) → geoopt.tensor.ManifoldTensor[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
- dtype (torch.dtype) – target dtype for sample, if not None, should match Manifold dtype
- device (torch.device) – target device for sample, if not None, should match Manifold device
Returns: random point on the PoincareBall manifold
Return type: Notes
The device and dtype will match the device and dtype of the Manifold
-
retr
(x: torch.Tensor, u: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
retr_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor, *, dim=-1) → Tuple[torch.Tensor, torch.Tensor][source]¶ Perform a retraction + vector transport at once.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point and vectors
Return type: Tuple[torch.Tensor, torch.Tensor]
Notes
Sometimes this is a far more optimal way to preform retraction + vector transport
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor, *, dim=-1)[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
-
transp_follow_expmap
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor, *, dim=-1, project=True) → torch.Tensor[source]¶ Perform vector transport following \(u\): \(\mathfrak{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 (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
transp_follow_retr
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Perform vector transport following \(u\): \(\mathfrak{T}_{x\to\operatorname{retr}(x, u)}(v)\).
This operation is sometimes is much more simpler and can be optimized.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
wrapped_normal
(*size, mean: torch.Tensor, std=1, dtype=None, device=None) → geoopt.tensor.ManifoldTensor[source]¶ Create a point on the manifold, measure is induced by Normal distribution on the tangent space of mean.
Definition is taken from [1] Mathieu, Emile et. al. “Continuous Hierarchical Representations with Poincaré Variational Auto-Encoders.” arXiv preprint arxiv:1901.06033 (2019).
Parameters: - size (shape) – the desired shape
- mean (float|tensor) – mean value for the Normal distribution
- std (float|tensor) – std value for the Normal distribution
- dtype (torch.dtype) – target dtype for sample, if not None, should match Manifold dtype
- device (torch.device) – target device for sample, if not None, should match Manifold device
Returns: random point on the PoincareBall manifold
Return type: Notes
The device and dtype will match the device and dtype of the Manifold
-
class
geoopt.manifolds.
StereographicExact
(k=0.0, learnable=False)[source]¶ \(\kappa\)-Stereographic model.
Parameters: k (float|tensor) – sectional curvature \(\kappa\) of the manifold - k<0: Poincaré ball (stereographic projection of hyperboloid) - k>0: Stereographic projection of sphere - k=0: Euclidean geometry Notes
It is extremely recommended to work with this manifold in double precision.
http://andbloch.github.io/K-Stereographic-Model/ or \kappa-Stereographic Projection model
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 re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.
-
retr
(x: torch.Tensor, u: torch.Tensor, *, project=True, dim=-1) → torch.Tensor¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
retr_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor, *, dim=-1, project=True) → Tuple[torch.Tensor, torch.Tensor]¶ Perform an exponential map and vector transport from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point
Return type:
-
transp_follow_retr
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor, *, dim=-1, project=True) → torch.Tensor¶ Perform vector transport following \(u\): \(\mathfrak{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 (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
-
class
geoopt.manifolds.
PoincareBall
(c=1.0, learnable=False)[source]¶ Poincare ball model.
See more in \kappa-Stereographic Projection model
Parameters: c (float|tensor) – ball’s negative curvature. The parametrization is constrained to have positive c Notes
It is extremely recommended to work with this manifold in double precision
-
class
geoopt.manifolds.
PoincareBallExact
(c=1.0, learnable=False)[source]¶ Poincare ball model.
See more in \kappa-Stereographic Projection model
Parameters: c (float|tensor) – ball’s negative curvature. The parametrization is constrained to have positive c 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.
-
class
geoopt.manifolds.
SphereProjection
(k=1.0, learnable=False)[source]¶ Stereographic Projection Spherical model.
See more in \kappa-Stereographic Projection model
Parameters: k (float|tensor) – sphere’s positive curvature. The parametrization is constrained to have positive k Notes
It is extremely recommended to work with this manifold in double precision
-
class
geoopt.manifolds.
SphereProjectionExact
(k=1.0, learnable=False)[source]¶ Stereographic Projection Spherical model.
See more in \kappa-Stereographic Projection model
Parameters: k (float|tensor) – sphere’s positive curvature. The parametrization is constrained to have positive k 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.
-
class
geoopt.manifolds.
Scaled
(manifold: geoopt.manifolds.base.Manifold, scale=1.0, learnable=False)[source]¶ Scaled manifold.
Scales all the distances on tha manifold by a constant factor. Scaling may be learnable since the underlying representation is canonical.
Examples
Here is a simple example of radius 2 Sphere
>>> import geoopt, torch, numpy as np >>> sphere = geoopt.Sphere() >>> radius_2_sphere = Scaled(sphere, 2) >>> p1 = torch.tensor([-1., 0.]) >>> p2 = torch.tensor([0., 1.]) >>> np.testing.assert_allclose(sphere.dist(p1, p2), np.pi / 2) >>> np.testing.assert_allclose(radius_2_sphere.dist(p1, p2), np.pi)
-
egrad2rgrad
(x: torch.Tensor, u: torch.Tensor, **kwargs) → torch.Tensor[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).
Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – gradient to be projected
Returns: grad vector in the Riemannian manifold
Return type:
-
inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None, *, keepdim=False, **kwargs) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
norm
(x: torch.Tensor, u: torch.Tensor, *, keepdim=False, **kwargs) → torch.Tensor[source]¶ Norm of a tangent vector at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
proju
(x: torch.Tensor, u: torch.Tensor, **kwargs) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
projx
(x: torch.Tensor, **kwargs) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
random
(*size, dtype=None, device=None, **kwargs) → torch.Tensor[source]¶ Random sampling on the manifold.
The exact implementation depends on manifold and usually does not follow all assumptions about uniform measure, etc.
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor, **kwargs) → torch.Tensor[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
-
-
class
geoopt.manifolds.
ProductManifold
(*manifolds_with_shape)[source]¶ Product Manifold.
Examples
A Torus
>>> import geoopt >>> sphere = geoopt.Sphere() >>> torus = ProductManifold((sphere, 2), (sphere, 2))
-
component_inner
(x: torch.Tensor, u: torch.Tensor, v=None) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\) according to components of the manifold.
The result of the function is same as
inner
withkeepdim=True
for all the manifolds except ProductManifold. For this manifold it acts different way computing inner product for each component and then building an output correctly tiling and reshaping the result.Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
Returns: inner product component wise (broadcasted)
Return type: Notes
The purpose of this method is better adaptive properties in optimization since ProductManifold will “hide” the structure in public API.
-
dist
(x, y, *, keepdim=False)[source]¶ Compute distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: distance between two points
Return type:
-
dist2
(x: torch.Tensor, y: torch.Tensor, *, keepdim=False)[source]¶ Compute squared distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: squared distance between two points
Return type:
-
egrad2rgrad
(x: torch.Tensor, u: torch.Tensor)[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).
Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – gradient to be projected
Returns: grad vector in the Riemannian manifold
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
expmap_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor][source]¶ Perform an exponential map and vector transport from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point
Return type:
-
classmethod
from_point
(*parts, batch_dims=0)[source]¶ Construct Product manifold from given points.
Parameters: Returns: Return type:
-
inner
(x: torch.Tensor, u: torch.Tensor, v=None, *, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
logmap
(x: torch.Tensor, y: torch.Tensor) → torch.Tensor[source]¶ Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
Returns: tangent vector
Return type:
-
origin
(*size, dtype=None, device=None, seed=42) → geoopt.tensor.ManifoldTensor[source]¶ Create some reasonable point on the manifold in a deterministic way.
For some manifolds there may exist e.g. zero vector or some analogy. In case it is possible to define this special point, this point is returned with the desired size. In other case, the returned point is sampled on the manifold in a deterministic way.
Parameters: - size (Union[int, Tuple[int]]) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (Optional[int]) – A parameter controlling deterministic randomness for manifolds that do not provide
.origin
, but provide.random
. (default: 42)
Returns: Return type:
-
pack_point
(*tensors) → torch.Tensor[source]¶ Construct a tensor representation of a manifold point.
In case of regular manifolds this will return the same tensor. However, for e.g. Product manifold this function will pack all non-batch dimensions.
Parameters: tensors (Tuple[torch.Tensor]) – Returns: Return type: torch.Tensor
-
proju
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
projx
(x: torch.Tensor) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
retr
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
retr_transp
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor)[source]¶ Perform a retraction + vector transport at once.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported point and vectors
Return type: Tuple[torch.Tensor, torch.Tensor]
Notes
Sometimes this is a far more optimal way to preform retraction + vector transport
-
take_submanifold_value
(x: torch.Tensor, i: int, reshape=True) → torch.Tensor[source]¶ Take i’th slice of the ambient tensor and possibly reshape.
Parameters: Returns: Return type:
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
-
transp_follow_expmap
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport following \(u\): \(\mathfrak{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 (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
transp_follow_retr
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport following \(u\): \(\mathfrak{T}_{x\to\operatorname{retr}(x, u)}(v)\).
This operation is sometimes is much more simpler and can be optimized.
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
unpack_tensor
(tensor: torch.Tensor) → Tuple[torch.Tensor][source]¶ Construct a point on the manifold.
This method should help to work with product and compound manifolds. Internally all points on the manifold are stored in an intuitive format. However, there might be cases, when this representation is simpler or more efficient to store in a different way that is hard to use in practice.
Parameters: tensor (torch.Tensor) – Returns: Return type: torch.Tensor
-
-
class
geoopt.manifolds.
Lorentz
(k=1.0, learnable=False)[source]¶ Lorentz model
Parameters: k (float|tensor) – manifold negative curvature Notes
It is extremely recommended to work with this manifold in double precision
-
dist
(x: torch.Tensor, y: torch.Tensor, *, keepdim=False, dim=-1) → torch.Tensor[source]¶ Compute distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool) – keep the last dim?
Returns: distance between two points
Return type:
-
egrad2rgrad
(x: torch.Tensor, u: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).
Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – gradient to be projected
Returns: grad vector in the Riemannian manifold
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor, *, norm_tan=True, project=True, dim=-1) → torch.Tensor[source]¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
inner
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor = None, *, keepdim=False, dim=-1) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
logmap
(x: torch.Tensor, y: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
Returns: tangent vector
Return type:
-
norm
(u: torch.Tensor, *, keepdim=False, dim=-1) → torch.Tensor[source]¶ Norm of a tangent vector at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
origin
(*size, dtype=None, device=None, seed=42) → geoopt.tensor.ManifoldTensor[source]¶ Zero point origin.
Parameters: - size (shape) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (int) – ignored
Returns: zero point on the manifold
Return type:
-
proju
(x: torch.Tensor, v: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
projx
(x: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
random_normal
(*size, mean=0, std=1, dtype=None, device=None) → geoopt.tensor.ManifoldTensor[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
- dtype (torch.dtype) – target dtype for sample, if not None, should match Manifold dtype
- device (torch.device) – target device for sample, if not None, should match Manifold device
Returns: random points on Hyperboloid
Return type: Notes
The device and dtype will match the device and dtype of the Manifold
-
retr
(x: torch.Tensor, u: torch.Tensor, *, norm_tan=True, project=True, dim=-1) → torch.Tensor¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor, *, dim=-1) → torch.Tensor[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
-
transp_follow_expmap
(x: torch.Tensor, u: torch.Tensor, v: torch.Tensor, *, dim=-1, project=True) → torch.Tensor[source]¶ Perform vector transport following \(u\): \(\mathfrak{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 (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (torch.Tensor) – tangent vector at point \(x\) to be transported
Returns: transported tensor
Return type:
-
-
class
geoopt.manifolds.
SymmetricPositiveDefinite
(default_metric: Union[str, geoopt.manifolds.symmetric_positive_definite.SPDMetric] = 'AIM')[source]¶ Manifold of symmetric positive definite matrices.
\[\begin{split}A = A^T\\ \langle x, A x \rangle > 0 \quad , \forall x \in \mathrm{R}^{n}, x \neq 0 \\ A \in \mathrm{R}^{n\times m}\end{split}\]The tangent space of the manifold contains all symmetric matrices.
References
- https://github.com/pymanopt/pymanopt/blob/master/pymanopt/manifolds/psd.py
- https://github.com/dalab/matrix-manifolds/blob/master/graphembed/graphembed/manifolds/spd.py
Parameters: default_metric (Union[str, SPDMetric]) – one of AIM, SM, LEM. So far only AIM is fully implemented. -
dist
(x: torch.Tensor, y: torch.Tensor, keepdim=False) → torch.Tensor[source]¶ Compute distance between 2 points on the manifold that is the shortest path along geodesics.
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
- keepdim (bool, optional) – keep the last dim?, by default False
Returns: distance between two points
Return type: Raises: ValueError
– if mode isn’t in _dist_metric
-
egrad2rgrad
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(x\).
Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – gradient to be projected
Returns: grad vector in the Riemannian manifold
Return type:
-
expmap
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform an exponential map \(\operatorname{Exp}_x(u)\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
extra_repr
() → str[source]¶ Set the extra representation of the module
To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.
-
inner
(x: torch.Tensor, u: torch.Tensor, v: Optional[torch.Tensor] = None, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(x\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
- v (Optional[torch.Tensor]) – tangent vector at point \(x\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type: Raises: ValueError
– if keepdim sine torch.trace doesn’t support keepdim
-
logmap
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform an logarithmic map \(\operatorname{Log}_{x}(y)\).
Parameters: - x (torch.Tensor) – point on the manifold
- y (torch.Tensor) – point on the manifold
Returns: tangent vector
Return type:
-
origin
(*size, dtype=None, device=None, seed: Optional[int] = 42) → torch.Tensor[source]¶ Create some reasonable point on the manifold in a deterministic way.
For some manifolds there may exist e.g. zero vector or some analogy. In case it is possible to define this special point, this point is returned with the desired size. In other case, the returned point is sampled on the manifold in a deterministic way.
Parameters: - size (Union[int, Tuple[int]]) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (Optional[int]) – A parameter controlling deterministic randomness for manifolds that do not provide
.origin
, but provide.random
. (default: 42)
Returns: Return type:
-
proju
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Project vector \(u\) on a tangent space for \(x\), usually is the same as
egrad2rgrad()
.Parameters: - torch.Tensor (u) – point on the manifold
- torch.Tensor – vector to be projected
Returns: projected vector
Return type:
-
projx
(x: torch.Tensor) → torch.Tensor[source]¶ Project point \(x\) on the manifold.
Parameters: torch.Tensor (x) – point to be projected Returns: projected point Return type: torch.Tensor
-
random
(*size, dtype=None, device=None, **kwargs) → torch.Tensor[source]¶ Random sampling on the manifold.
The exact implementation depends on manifold and usually does not follow all assumptions about uniform measure, etc.
-
retr
(x: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Perform a retraction from point \(x\) with given direction \(u\).
Parameters: - x (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(x\)
Returns: transported point
Return type:
-
transp
(x: torch.Tensor, y: torch.Tensor, v: torch.Tensor) → torch.Tensor[source]¶ Perform vector transport \(\mathfrak{T}_{x\to y}(v)\).
Parameters: - x (torch.Tensor) – start point on the manifold
- y (torch.Tensor) – target point on the manifold
- v (torch.Tensor) – tangent vector at point \(x\)
Returns: transported tensor
Return type:
-
class
geoopt.manifolds.
UpperHalf
(metric: geoopt.manifolds.siegel.vvd_metrics.SiegelMetricType = <SiegelMetricType.RIEMANNIAN: 'riem'>, rank: int = None)[source]¶ Upper Half Space Manifold.
This model generalizes the upper half plane model of the hyperbolic plane. Points in the space are complex symmetric matrices.
\[\mathcal{S}_n = \{Z = X + iY \in \operatorname{Sym}(n, \mathbb{C}) | Y >> 0 \}.\]Parameters: - metric (SiegelMetricType) – one of Riemannian, Finsler One, Finsler Infinity, Finsler metric of minimum entropy, or learnable weighted sum.
- rank (int) – Rank of the space. Only mandatory for “fmin” and “wsum” metrics.
-
egrad2rgrad
(z: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(Z\).
For a function \(f(Z)\) on \(\mathcal{S}_n\), the gradient is:
\[\operatorname{grad}_{R}(f(Z)) = Y \cdot \operatorname{grad}_E(f(Z)) \cdot Y\]where \(Y\) is the imaginary part of \(Z\).
Parameters: - z (torch.Tensor) – point on the manifold
- u (torch.Tensor) – gradient to be projected
Returns: Riemannian gradient
Return type:
-
inner
(z: torch.Tensor, u: torch.Tensor, v=None, *, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(Z\).
The inner product at point \(Z = X + iY\) of the vectors \(U, V\) is:
\[g_{Z}(U, V) = \operatorname{Tr}[ Y^{-1} U Y^{-1} \overline{V} ]\]Parameters: - z (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(z\)
- v (torch.Tensor) – tangent vector at point \(z\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
origin
(*size, dtype=None, device=None, seed: Optional[int] = 42) → torch.Tensor[source]¶ Create points at the origin of the manifold in a deterministic way.
For the Upper half model, the origin is the imaginary identity. This is, a matrix whose real part is all zeros, and the identity as the imaginary part.
Parameters: - size (Union[int, Tuple[int]]) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (Optional[int]) – A parameter controlling deterministic randomness for manifolds that do not provide
.origin
, but provide.random
. (default: 42)
Returns: Return type:
-
projx
(z: torch.Tensor) → torch.Tensor[source]¶ Project point \(Z\) on the manifold.
In this space, we need to ensure that \(Y = Im(Z)\) is positive definite. Since the matrix Y is symmetric, it is possible to diagonalize it. For a diagonal matrix the condition is just that all diagonal entries are positive, so we clamp the values that are <= 0 in the diagonal to an epsilon, and then restore the matrix back into non-diagonal form using the base change matrix that was obtained from the diagonalization.
Parameters: z (torch.Tensor) – point on the manifold Returns: Projected points Return type: torch.Tensor
-
class
geoopt.manifolds.
BoundedDomain
(metric: geoopt.manifolds.siegel.vvd_metrics.SiegelMetricType = <SiegelMetricType.RIEMANNIAN: 'riem'>, rank: int = None)[source]¶ Bounded domain Manifold.
This model generalizes the Poincare ball model. Points in the space are complex symmetric matrices.
\[\mathcal{B}_n := \{ Z \in \operatorname{Sym}(n, \mathbb{C}) | Id - Z^*Z >> 0 \}\]Parameters: - metric (SiegelMetricType) – one of Riemannian, Finsler One, Finsler Infinity, Finsler metric of minimum entropy, or learnable weighted sum.
- rank (int) – Rank of the space. Only mandatory for “fmin” and “wsum” metrics.
-
dist
(z1: torch.Tensor, z2: torch.Tensor, *, keepdim=False) → torch.Tensor[source]¶ Compute distance in the Bounded domain model.
To compute distances in the Bounded Domain Model we need to map the elements to the Upper Half Space Model by means of the Cayley Transform, and then compute distances in that domain.
Parameters: - z1 (torch.Tensor) – point on the manifold
- z2 (torch.Tensor) – point on the manifold
- keepdim (bool, optional) – keep the last dim?, by default False
Returns: distance between two points
Return type:
-
egrad2rgrad
(z: torch.Tensor, u: torch.Tensor) → torch.Tensor[source]¶ Transform gradient computed using autodiff to the correct Riemannian gradient for the point \(Z\).
For a function \(f(Z)\) on \(\mathcal{B}_n\), the gradient is:
\[\operatorname{grad}_{R}(f(Z)) = A \cdot \operatorname{grad}_E(f(Z)) \cdot A\]where \(A = Id - \overline{Z}Z\)
Parameters: - z (torch.Tensor) – point on the manifold
- u (torch.Tensor) – gradient to be projected
Returns: Riemannian gradient
Return type:
-
inner
(z: torch.Tensor, u: torch.Tensor, v=None, *, keepdim=False) → torch.Tensor[source]¶ Inner product for tangent vectors at point \(Z\).
The inner product at point \(Z = X + iY\) of the vectors \(U, V\) is:
\[g_{Z}(U, V) = \operatorname{Tr}[(Id - \overline{Z}Z)^{-1} U (Id - Z\overline{Z})^{-1} \overline{V}]\]Parameters: - z (torch.Tensor) – point on the manifold
- u (torch.Tensor) – tangent vector at point \(z\)
- v (torch.Tensor) – tangent vector at point \(z\)
- keepdim (bool) – keep the last dim?
Returns: inner product (broadcasted)
Return type:
-
origin
(*size, dtype=None, device=None, seed: Optional[int] = 42) → torch.Tensor[source]¶ Create points at the origin of the manifold in a deterministic way.
For the Bounded domain model, the origin is the zero matrix. This is, a matrix whose real and imaginary parts are all zeros.
Parameters: - size (Union[int, Tuple[int]]) – the desired shape
- device (torch.device) – the desired device
- dtype (torch.dtype) – the desired dtype
- seed (Optional[int]) – A parameter controlling deterministic randomness for manifolds that do not provide
.origin
, but provide.random
. (default: 42)
Returns: Return type:
-
projx
(z: torch.Tensor) → torch.Tensor[source]¶ Project point \(Z\) on the manifold.
In the Bounded domain model, we need to ensure that \(Id - \overline(Z)Z\) is positive definite.
Steps to project: Z complex symmetric matrix 1) Diagonalize Z: \(Z = \overline{S} D S^*\) 2) Clamp eigenvalues: \(D' = clamp(D, max=1 - epsilon)\) 3) Rebuild Z: \(Z' = \overline{S} D' S^*\)
Parameters: z (torch.Tensor) – point on the manifold Returns: Projected points Return type: torch.Tensor