homeotopy 0.1.0__tar.gz

homeotopy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Erik Brinkman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

homeotopy-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.1
+Name: homeotopy
+Version: 0.1.0
+Summary: A library for computing homeomorphisms between some common stnandard topologies
+License: MIT
+Author: Erik Brinkman
+Author-email: erik.brinkman@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: numba (>=0.61.0,<0.62.0)
+Description-Content-Type: text/markdown
+
+# Homotopy
+
+A python library for computing homeomorphisms between some common continuous
+spaces.
+
+## Installation
+
+```sh
+pip install homeotopy
+```
+
+## Usage
+
+```py
+import homeotopy
+
+points = ...
+# create a mapping from the simplex to the surface of the sphere
+mapping = homeotopy.homeomorphism(homeotopy.simplex(), homeotopy.sphere())
+sphere_points = mapping(points)
+
+rev_mapping = reversed(mapping)
+duplicate_points = rev_mapping(sphere_points)
+```
+

homeotopy-0.1.0/README.md

@@ -0,0 +1,24 @@
+# Homotopy
+
+A python library for computing homeomorphisms between some common continuous
+spaces.
+
+## Installation
+
+```sh
+pip install homeotopy
+```
+
+## Usage
+
+```py
+import homeotopy
+
+points = ...
+# create a mapping from the simplex to the surface of the sphere
+mapping = homeotopy.homeomorphism(homeotopy.simplex(), homeotopy.sphere())
+sphere_points = mapping(points)
+
+rev_mapping = reversed(mapping)
+duplicate_points = rev_mapping(sphere_points)
+```

homeotopy-0.1.0/homeotopy/__init__.py

@@ -0,0 +1,39 @@
+"""A library for creating some standard homeomorphisms.
+
+This library is based around a set of `Topologies`. Calling `homeomorphism` with
+two Topologies creates a homeomorphism from one topology to the other.
+Topoligies should specify their domains, but where unspecified, the topoligies
+try to conform to a reasonable standard domain. The homeomorphism should work
+for closed set elements too, but thos elements may not be bijective.
+
+Remarks
+-------
+It's probably important to note that floating point numbers are not real
+numbers, and so none of these are really bijective at all.
+
+Also note that this library does not define homeotopies. It's just named this
+have to "py" in the name.
+"""
+
+from ._ball import Ball, ball
+from ._cube import Cube, cube
+from ._homeomorphism import Homeomorphism, Topology, homeomorphism
+from ._plane import Plane, plane
+from ._simplex import Simplex, simplex
+from ._sphere import Sphere, sphere
+
+__all__ = (
+    "Homeomorphism",
+    "Topology",
+    "homeomorphism",
+    "Ball",
+    "ball",
+    "Cube",
+    "cube",
+    "Plane",
+    "plane",
+    "Sphere",
+    "sphere",
+    "Simplex",
+    "simplex",
+)

homeotopy-0.1.0/homeotopy/_ball.py

@@ -0,0 +1,45 @@
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._homeomorphism import Topology
+
+
+@dataclass(frozen=True, slots=True)
+class Ball(Topology):
+    """The topology of the p-norm ball.
+
+    This represents all points in R^n s.t. ||x||_p < 1, although it should also
+    work fo the boundary.
+    """
+
+    p: float
+
+    def __post_init__(self):
+        if self.p <= 0:
+            raise ValueError(f"p must be greater than or equal to 0: {self.p:g}")
+
+    def to_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        if self.p == math.inf:
+            return points
+        else:
+            tiny = np.finfo(points.dtype).smallest_normal
+            source = np.linalg.norm(points, self.p, -1)
+            target = np.abs(points).max(-1) + tiny
+            return np.clip(points * (source / target)[..., None], -1, 1)
+
+    def from_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        if self.p == math.inf:
+            return points
+        else:
+            tiny = np.finfo(points.dtype).smallest_normal
+            source = np.abs(points).max(-1)
+            target = np.linalg.norm(points, self.p, -1) + tiny
+            return points * (source / target)[..., None]
+
+
+def ball(p: float = 2.0) -> Ball:
+    """Create a topology of the interior of the p-norm unit ball."""
+    return Ball(p)

homeotopy-0.1.0/homeotopy/_cube.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+from functools import cache
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._homeomorphism import Topology
+
+
+@dataclass(frozen=True, slots=True)
+class Cube(Topology):
+    """The topology of the unit hyper cube.
+
+    This represents all points in R^n s.t 0 < x_i < 1, although the boundary
+    should also work.
+    """
+
+    def to_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        return np.clip(points * 2 - 1, -1, 1)
+
+    def from_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        return np.clip((points + 1) / 2, 0, 1)
+
+
+@cache
+def cube() -> Cube:
+    """Create a topology of the unit cube."""
+    return Cube()

homeotopy-0.1.0/homeotopy/_homeomorphism.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class Topology(ABC):
+    """An abstract topological space.
+
+    For this library to work, each Topologiy should define a homeomorphism from
+    it to the inf-norm ball.
+
+    Remarks
+    -------
+    `to_inf_ball` and `from_inf_ball` are not meant to be called in isolation,
+    but rather used in combination with `homeomorphism`.
+    """
+
+    @abstractmethod
+    def to_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        """Map a set of points in this topology to the inf-ball.
+
+        Parameters
+        ----------
+        points : (..., d_in)
+            A set of points in the input topological space
+
+        Returns
+        -------
+        points : (..., d_out)
+            A set of points in the inf-norm ball, e.g. -1 < x_i < 1 for points
+            in the open topology, but points can be mapped to the border for
+            border points in the source topology.
+        """
+        pass
+
+    @abstractmethod
+    def from_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        """Map a set of points from the inf-ball to this topology.
+
+        Parameters
+        ----------
+        points : (..., d_in)
+            A set of points in the inf-norm ball, e.g. -1 < x_i < 1 for points
+            in the open topology, but points on the boarder should be handled as
+            well.
+
+        Returns
+        -------
+        points : (..., d_out)
+            A set of points in the topological space.
+        """
+        pass
+
+
+@dataclass(frozen=True, slots=True)
+class Homeomorphism:
+    """A homeomorphism from source to target.
+
+    Homeomorphisms can be called on points in the source domain to map them to
+    points in the target domain. They can also be `reversed` to create the
+    inverse mapping.
+
+
+    Example
+    -------
+
+        from homeotopy import homeomorphism, ball, simplex
+        import numpy as np
+
+        forward = homeomorphism(ball(1), simplex())
+        backward = reversed(forward)
+
+        ball_points = ...
+        simplex_points = forwad(ball_points)
+        backward(simplex_points)
+
+    """
+
+    source: Topology
+    target: Topology
+
+    def __reversed__(self) -> Homeomorphism:
+        return Homeomorphism(self.target, self.source)
+
+    def __call__(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        return self.target.from_inf_ball(self.source.to_inf_ball(points))
+
+
+def homeomorphism(source: Topology, target: Topology) -> Homeomorphism:
+    """Create a Homeomorphism from a source and a target topology."""
+    return Homeomorphism(source, target)

homeotopy-0.1.0/homeotopy/_plane.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from functools import cache
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._homeomorphism import Topology
+
+
+@dataclass(frozen=True, slots=True)
+class Plane(Topology):
+    """The topology of the euclidian plane.
+
+    This represents all points in R^n, but boundary points map to inf.
+
+    Remarks
+    -------
+    While translations will keep all points valid, this will try to keep points
+    at the "center" of the space mapped to (0, 0, ..., 0).
+    """
+
+    def to_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        return np.tanh(points)
+
+    def from_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        # -1 and 1 raise this warning but produce the correct result, we clip in case things are a little outside
+        with np.errstate(divide="ignore"):
+            return np.arctanh(np.clip(points, -1, 1))
+
+
+@cache
+def plane() -> Plane:
+    """Create a topology of the euclidian plane."""
+    return Plane()

homeotopy-0.1.0/homeotopy/_simplex.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass
+from functools import cache
+
+import numba as nb
+import numpy as np
+from numpy.typing import NDArray
+
+from ._homeomorphism import Topology
+
+# NOTE we use this to avoid divide by zero errors
+
+
+@nb.jit(nb.float64[:, ::1](nb.int64), parallel=True, cache=True, nogil=True)
+def basis(dim: int) -> NDArray[np.float64]:
+    """Create a basis for rotating the simplex onto the origin of dim - 1"""
+    res = np.empty((dim, dim))
+    for i in nb.prange(0, dim - 1):
+        num = i + 1
+        frac = 1 / (num + 1)
+        res[i, :num] = -((frac / num) ** 0.5)
+        res[i, num] = (1 - frac) ** 0.5
+        res[i, num + 1 :] = 0
+    res[-1] = (1 / dim) ** 0.5
+    return res
+
+
+@dataclass(frozen=True, slots=True)
+class Simplex(Topology):
+    """The topology of the simplex
+
+    This represents all points in R^n s.t. 0 < x_i and Σx_i = 1.
+    """
+
+    def to_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        tiny = np.finfo(points.dtype).smallest_normal
+        d = points.shape[-1]
+
+        simp_direc = points - np.full(d, 1 / d)
+        isimp_a = d * np.maximum(-simp_direc, simp_direc / (d - 1)).max(-1)
+
+        cube_direc = simp_direc @ basis(d)[: d - 1].T
+        icube_a = np.max(np.abs(cube_direc), -1) + tiny
+
+        return np.clip(cube_direc * (isimp_a / icube_a)[..., None], -1, 1)
+
+    def from_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        tiny = np.finfo(points.dtype).smallest_normal
+        d = points.shape[-1]
+
+        icube_a = np.max(np.abs(points), -1)
+
+        simp_direc = np.insert(points, d, 0, -1) @ basis(d + 1)
+        isimp_a = (d + 1) * np.maximum(-simp_direc, simp_direc / d).max(-1) + tiny
+
+        raw = simp_direc * (icube_a / isimp_a)[..., None] + np.full(d + 1, 1 / (d + 1))
+        return np.clip(raw, 0, 1)
+
+
+@cache
+def simplex() -> Simplex:
+    """Create the topology of the simplex."""
+    return Simplex()

homeotopy-0.1.0/homeotopy/_sphere.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from functools import cache
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._homeomorphism import Topology
+
+
+@dataclass(frozen=True, slots=True)
+class Sphere(Topology):
+    """The topology of the unit sphere.
+
+    This represents all points in R^n s.t. ||x||_2 = 1, except for the point
+    (1, 0, ..., 0). That point is considered the boundary of the space, and will
+    be mapped the largest closed point in some other topologies.
+
+    Remarks
+    -------
+    If you had points on the surface of another p-ball, you could use the ball
+    homeomorphism to first map them onto the surface of the 2-ball, and then
+    apply this homeomorphism.
+    """
+
+    # NOTE for both of these we need to special case (1, 0, ..., 0) to (1, 1, ..., 1) and vice versa
+    def to_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        tiny = np.finfo(points.dtype).smallest_normal
+        scale = 1 - points[..., :1]
+
+        normal = np.clip(np.tanh(points[..., 1:] / np.maximum(scale, tiny)), -1, 1)
+        return np.where(scale <= 0, 1, normal)
+
+    def from_inf_ball(self, points: NDArray[np.float64]) -> NDArray[np.float64]:
+        big = np.finfo(points.dtype).max
+        with np.errstate(divide="ignore"):
+            plane = np.arctanh(points)
+
+        s2 = (plane[..., None, :] @ plane[..., None])[..., 0]
+        s2p = np.minimum(s2 + 1, big)
+
+        x0 = np.where(s2 == np.inf, 1, (s2 - 1) / s2p)
+        xns = np.where(s2 == np.inf, 0, 2 * plane / s2p)
+        return np.concatenate([x0, xns], -1)
+
+
+@cache
+def sphere() -> Sphere:
+    """Create a topology fot the unit sphere."""
+    return Sphere()

homeotopy-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "homeotopy"
+version = "0.1.0"
+description = "A library for computing homeomorphisms between some common stnandard topologies"
+authors = ["Erik Brinkman <erik.brinkman@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+numba = "^0.61.0"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+ruff = "^0.9.2"
+ipykernel = "^6.29.5"
+sphinx = "^8.1.3"
+myst-parser = "^4.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"