manifolds ========= .. py:module:: topmost.models.hierarchical.HyperMiner.manifolds .. toctree:: :titlesonly: :maxdepth: 1 base/index.rst euclidean/index.rst math_util/index.rst poincare/index.rst Package Contents ---------------- .. autoapisummary:: topmost.models.hierarchical.HyperMiner.manifolds.Euclidean topmost.models.hierarchical.HyperMiner.manifolds.PoincareBall .. py:class:: Euclidean(**kwargs) Bases: :py:obj:`topmost.models.hierarchical.HyperMiner.manifolds.base.Manifold` Euclidean Manifold class. Usually we refer it as R^n. .. attribute:: name The manifold name, and its value is "Euclidean". :type: str Initialize an Euclidean manifold. :param \*\*kwargs: Description .. py:attribute:: name :value: 'Euclidean' .. py:method:: proj(x, c) A projection function that prevents x from leaving the manifold. :param x: A point should be on the manifold, but it may not meet the manifold constraints. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: A projected point, meeting the manifold constraints. :rtype: tensor .. py:method:: proj_tan(v, x, c) A projection function that prevents v from leaving the tangent space of point x. :param v: A point should be on the tangent space, but it may not meet the manifold constraints. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: A projected point, meeting the tangent space constraints. :rtype: tensor .. py:method:: proj_tan0(v, c) A projection function that prevents v from leaving the tangent space of origin point. :param v: A point should be on the tangent space, but it may not meet the manifold constraints. :type v: tensor :param c: The manifold curvature. :type c: tensor :returns: A projected point, meeting the tangent space constraints. :rtype: tensor .. py:method:: expmap(v, x, c) Map a point v in the tangent space of point x to the manifold. :param v: A point in the tangent space of point x. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping tangent point v to the manifold. :rtype: tensor .. py:method:: expmap0(v, c) Map a point v in the tangent space of origin point to the manifold. :param v: A point in the tangent space of origin point. :type v: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping tangent point v to the manifold. :rtype: tensor .. py:method:: logmap(y, x, c) Map a point y on the manifold to the tangent space of x. :param y: A point on the manifold. :type y: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping y to the tangent space of x. :rtype: tensor .. py:method:: logmap0(y, c) Map a point y on the manifold to the tangent space of origin point. :param y: A point on the manifold. :type y: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping y to the tangent space of origin point. :rtype: tensor .. py:method:: ptransp(v, x, y, c) Parallel transport function, used to move point v in the tangent space of x to the tangent space of y. :param v: A point in the tangent space of x. :type v: tensor :param x: A point on the manifold. :type x: tensor :param y: A point on the manifold. :type y: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of transporting v from the tangent space at x to the tangent space at y. :rtype: tensor .. py:method:: ptransp0(v, x, c) Parallel transport function, used to move point v in the tangent space of origin point to the tangent space of y. :param v: A point in the tangent space of origin point. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of transporting v from the tangent space at origin point to the tangent space at y. :rtype: tensor .. py:method:: dist(x, y, c) Calculate the squared geodesic/distance between x and y. :param x: A point on the manifold. :type x: tensor :param y: A point on the manifold. :type y: tensor :param c: The manifold curvature. :type c: tensor :returns: the geodesic/distance between x and y. :rtype: tensor .. py:method:: egrad2rgrad(grad, x, c) Computes Riemannian gradient from the Euclidean gradient, typically used in Riemannian optimizers. :param grad: Euclidean gradient at x. :type grad: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: Riemannian gradient at x. :rtype: tensor .. py:method:: inner(v1, v2, x, c, keep_shape=False) Computes the inner product of a pair of tangent vectors v1 and v2 at x. :param v1: A tangent point at x. :type v1: tensor :param v2: A tangent point at x. :type v2: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :param keep_shape: Whether the output tensor keeps shape or not. :type keep_shape: bool, optional :returns: The inner product of v1 and v2 at x. :rtype: tensor .. py:class:: PoincareBall Bases: :py:obj:`topmost.models.hierarchical.HyperMiner.manifolds.base.Manifold` PoicareBall Manifold class. We use the following convention: x0^2 + x1^2 + ... + xd^2 < 1 / c. (c < 0) So that the Poincare ball radius will be 1 / sqrt(-c). Notice that the more close c is to 0, the more flat space will be. Initialize a manifold. .. py:attribute:: name :value: 'PoincareBall' .. py:attribute:: truncate_c .. py:method:: proj(x, c) A projection function that prevents x from leaving the manifold. :param x: A point should be on the manifold, but it may not meet the manifold constraints. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: A projected point, meeting the manifold constraints. :rtype: tensor .. py:method:: proj_tan(v, x, c) A projection function that prevents v from leaving the tangent space of point x. :param v: A point should be on the tangent space, but it may not meet the manifold constraints. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: A projected point, meeting the tangent space constraints. :rtype: tensor .. py:method:: proj_tan0(v, c) A projection function that prevents v from leaving the tangent space of origin point. :param v: A point should be on the tangent space, but it may not meet the manifold constraints. :type v: tensor :param c: The manifold curvature. :type c: tensor :returns: A projected point, meeting the tangent space constraints. :rtype: tensor .. py:method:: expmap(v, x, c) Map a point v in the tangent space of point x to the manifold. :param v: A point in the tangent space of point x. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping tangent point v to the manifold. :rtype: tensor .. py:method:: expmap0(v, c) Map a point v in the tangent space of origin point to the manifold. :param v: A point in the tangent space of origin point. :type v: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping tangent point v to the manifold. :rtype: tensor .. py:method:: logmap(y, x, c) Map a point y on the manifold to the tangent space of x. :param y: A point on the manifold. :type y: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping y to the tangent space of x. :rtype: tensor .. py:method:: logmap0(y, c) Map a point y on the manifold to the tangent space of origin point. :param y: A point on the manifold. :type y: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping y to the tangent space of origin point. :rtype: tensor .. py:method:: ptransp(v, x, y, c) Parallel transport function, used to move point v in the tangent space of x to the tangent space of y. :param v: A point in the tangent space of x. :type v: tensor :param x: A point on the manifold. :type x: tensor :param y: A point on the manifold. :type y: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of transporting v from the tangent space at x to the tangent space at y. :rtype: tensor .. py:method:: ptransp0(v, x, c) Parallel transport function, used to move point v in the tangent space of origin point to the tangent space of y. :param v: A point in the tangent space of origin point. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of transporting v from the tangent space at origin point to the tangent space at y. :rtype: tensor .. py:method:: dist(x, y, c) Calculate the squared geodesic/distance between x and y. :param x: A point on the manifold. :type x: tensor :param y: A point on the manifold. :type y: tensor :param c: The manifold curvature. :type c: tensor :returns: the geodesic/distance between x and y. :rtype: tensor .. py:method:: egrad2rgrad(grad, x, c) Computes Riemannian gradient from the Euclidean gradient, typically used in Riemannian optimizers. :param grad: Euclidean gradient at x. :type grad: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: Riemannian gradient at x. :rtype: tensor .. py:method:: inner(v1, v2, x, c, keep_shape=False) Computes the inner product of a pair of tangent vectors v1 and v2 at x. :param v1: A tangent point at x. :type v1: tensor :param v2: A tangent point at x. :type v2: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :param keep_shape: Whether the output tensor keeps shape or not. :type keep_shape: bool, optional :returns: The inner product of v1 and v2 at x. :rtype: tensor .. py:method:: retraction(v, x, c) Retraction is a continuous map function from tangent space to the manifold, typically used in Riemannian optimizers. The exp map is one of retraction functions. :param v: A tangent point at x. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor :returns: The result of mapping tangent point v at x to the manifold. :rtype: tensor .. py:method:: _mobius_add(x, y, c) .. py:method:: _mobius_mul(x, a, c) .. py:method:: _mobius_matvec(x, a, c) .. py:method:: _lambda_x(x, c) .. py:method:: _gyration(x, y, v, c)