sphere-n 0.2__py3-none-any.whl

sphere_n/__init__.py

@@ -0,0 +1,16 @@
+import sys
+
+if sys.version_info[:2] >= (3, 8):
+    # TODO: Import directly (no need for conditional) when `python_requires = >= 3.9`
+    from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+else:
+    from importlib_metadata import PackageNotFoundError, version  # pragma: no cover
+
+try:
+    # Change here if project is renamed and does not equal the package name
+    dist_name = "sphere-n"
+    __version__ = version(dist_name)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError

sphere_n/cylind_n.py

@@ -0,0 +1,88 @@
+"""
+This code defines a system for generating points on an n-dimensional sphere using a technique called cylindrical mapping. The main purpose is for the sake of comparison with the sphere_n.py code.
+
+The code takes a list of integers as input, which are used as bases for the low-discrepancy sequence generators. These generators help create a more uniform distribution of points compared to random sampling.
+
+The output of this code is a list of floating-point numbers representing coordinates on the n-dimensional sphere. Each time you call the pop() method of a CylindN object, it produces a new set of coordinates.
+
+The code achieves its purpose through a recursive algorithm. It uses two main components: a van der Corput sequence generator (VdCorput) for one dimension, and either a Circle generator or another CylindN generator for the remaining dimensions. This recursive structure allows it to handle spheres of any dimension.
+
+The main logic flow happens in the pop() method. It first generates a cosine value (cosphi) using the van der Corput sequence, mapping it to the range [-1, 1]. Then it calculates the sine value (sinphi) using the Pythagorean identity. The method then recursively generates coordinates for lower dimensions and scales them by sinphi, finally adding cosphi as the last coordinate.
+
+An important data transformation occurs in the pop() method, where the uniform distribution from the van der Corput sequence is transformed into a cosine distribution, which is necessary for proper spherical mapping.
+
+The code also includes a reseed() method, which allows you to reset the internal state of the generators. This is useful for reproducibility in scientific simulations or when you need to generate the same sequence of points multiple times.
+"""
+
+from abc import abstractmethod, ABC
+from typing import List
+
+# import numexpr as ne
+from lds_gen.lds import Circle, VdCorput  # low-discrepancy sequence generators
+import numpy as np
+import math
+
+PI: float = np.pi
+
+
+class CylindGen(ABC):
+    """Base interface for n-sphere generators using cylindrical mapping."""
+
+    @abstractmethod
+    def pop(self) -> List[float]:
+        """Generates and returns a vector of values."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def reseed(self, seed: int) -> None:
+        """Reseeds the generator with a new seed."""
+        raise NotImplementedError
+
+
+class CylindN(CylindGen):
+    """Low-discrepency sequence generator using cylindrical mapping.
+
+    Examples:
+        >>> cgen = CylindN([2, 3, 5, 7])
+        >>> cgen.reseed(0)
+        >>> for _ in range(1):
+        ...     print(cgen.pop())
+        ...
+        [0.4702654580212986, 0.5896942325314937, -0.565685424949238, -0.33333333333333337, 0.0]
+    """
+
+    def __init__(self, base: List[int]) -> None:
+        """_summary_
+
+        Args:
+            base (List[int]): _description_
+        """
+        n = len(base) - 1
+        assert n >= 1
+        self.vdc = VdCorput(base[0])
+        self.c_gen = Circle(base[1]) if n == 1 else CylindN(base[1:])
+
+    def pop(self) -> List[float]:
+        """_summary_
+
+        Returns:
+            List[float]: _description_
+        """
+        cosphi = 2.0 * self.vdc.pop() - 1.0  # map to [-1, 1]
+        sinphi = math.sqrt(1.0 - cosphi * cosphi)
+        return [xi * sinphi for xi in self.c_gen.pop()] + [cosphi]
+
+    def reseed(self, seed: int) -> None:
+        """_summary_
+
+        Args:
+            seed (int): _description_
+        """
+        self.vdc.reseed(seed)
+        self.c_gen.reseed(seed)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

sphere_n/discrep_2.py

@@ -0,0 +1,26 @@
+import numpy as np
+
+
+def discrep_2(K, X):
+    """dispersion measure
+
+    Arguments:
+        K ([type]): [description]
+        X ([type]): [description]
+
+    Returns:
+        float: dispersion
+    """
+    nsimplex, n = K.shape
+    maxq = 0
+    minq = 1000
+    for k in range(nsimplex):
+        p = X[K[k, :], :]
+        for i in range(n - 1):
+            for j in range(i + 1, n):
+                dot = np.dot(p[i, :], p[j, :])
+                q = 1.0 - dot * dot
+                maxq = max(maxq, q)
+                minq = min(minq, q)
+    dis = np.arcsin(np.sqrt(maxq)) - np.arcsin(np.sqrt(minq))
+    return dis

sphere_n/sphere_n.py

@@ -0,0 +1,195 @@
+"""
+Sphere N Generator
+
+This code is a Sphere N Generator, which is designed to create points on the surface of spheres in different dimensions. It's a tool that mathematicians, scientists, or computer graphics programmers might use when they need to work with spherical shapes in multiple dimensions.
+
+The main input for this code is a list of integers, which are used as bases for generating sequences of numbers. These bases are used to initialize different types of generators that create points on spheres.
+
+The output of this code is a series of lists containing floating-point numbers. Each list represents a point on the surface of a sphere, with the number of elements in the list corresponding to the dimension of the sphere.
+
+To achieve its purpose, the code uses several mathematical concepts and algorithms. It starts by defining some constants and helper functions that are used in the calculations. These functions (get_tp_odd, get_tp_even, and get_tp) create lookup tables for mapping values in different dimensions.
+
+The code then defines several classes that generate points on spheres:
+
+1. SphereGen: This is an abstract base class that defines the common interface for all sphere generators.
+
+2. Sphere3: This class generates points on a 3-dimensional sphere. It uses a combination of van der Corput sequences and 2-dimensional sphere points to create 3D points.
+
+3. SphereN: This class can generate points on spheres of any dimension (3 or higher). It uses a recursive approach, building higher-dimensional spheres from lower-dimensional ones.
+
+Each of these classes has methods to generate new points (pop) and to reset the generator with a new starting point (reseed).
+
+The code achieves its purpose through a combination of mathematical transformations and recursive algorithms. It uses trigonometric functions (sine, cosine) and interpolation to map values from one range to another. The core idea is to generate sequences of numbers that, when interpreted as coordinates, create an even distribution across the surface of a sphere.
+
+An important aspect of the code is its use of caching (@cache decorator) for some functions. This improves performance by storing the results of expensive calculations so they don't need to be repeated.
+
+Overall, this code provides a flexible way to generate evenly distributed points on spheres of various dimensions, which can be useful in many scientific and graphical applications.
+"""
+
+from abc import abstractmethod, ABC
+from typing import List
+
+# import numexpr as ne
+from lds_gen.lds import Sphere, VdCorput  # low-discrepancy sequence generators
+from functools import cache
+import numpy as np
+import math
+
+PI: float = np.pi
+X: np.ndarray = np.linspace(0.0, PI, 300)
+NEG_COSINE: np.ndarray = -np.cos(X)
+SINE: np.ndarray = np.sin(X)
+F2: np.ndarray = (X + NEG_COSINE * SINE) / 2.0
+HALF_PI = PI / 2.0
+
+
+@cache
+def get_tp_odd(n: int) -> np.ndarray:
+    """table-lookup of mapping function for odd n
+
+    Returns:
+        np.ndarray: _description_
+    """
+    if n == 1:
+        return NEG_COSINE
+    tp_minus2 = get_tp_odd(n - 2)  # NOQA
+    # return ne.evaluate("((n - 1) * tp_minus2 + NEG_COSINE * SINE**(n - 1)) / n")
+    return ((n - 1) * tp_minus2 + NEG_COSINE * SINE ** (n - 1)) / n
+
+
+@cache
+def get_tp_even(n: int) -> np.ndarray:
+    """table-lookup of mapping function for even n
+
+    Returns:
+        np.ndarray: _description_
+    """
+    if n == 0:
+        return X
+    tp_minus2 = get_tp_even(n - 2)  # NOQA
+    # return ne.evaluate("((n - 1) * tp_minus2 + NEG_COSINE * SINE**(n - 1)) / n")
+    return ((n - 1) * tp_minus2 + NEG_COSINE * SINE ** (n - 1)) / n
+
+
+def get_tp(n: int) -> np.ndarray:
+    """table-lookup of mapping function for n
+
+    Returns:
+        np.ndarray: _description_
+    """
+    return get_tp_even(n) if n % 2 == 0 else get_tp_odd(n)
+
+
+class SphereGen(ABC):
+    """Base class for sphere generators."""
+
+    @abstractmethod
+    def pop(self) -> List[float]:
+        """Generates and returns a vector of values."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def reseed(self, seed: int) -> None:
+        """Reseeds the generator with a new seed."""
+        raise NotImplementedError
+
+
+class Sphere3(SphereGen):
+    """3-Sphere sequence generator
+
+    Examples:
+        >>> sgen = Sphere3([2, 3, 5])
+        >>> sgen.reseed(0)
+        >>> for _ in range(1):
+        ...     print(sgen.pop())
+        ...
+        [0.2913440162992141, 0.8966646826186098, -0.33333333333333337, 6.123233995736766e-17]
+    """
+
+    vdc: VdCorput  # van der Corput sequence generator
+    sphere2: Sphere  # 2-Sphere generator
+
+    def __init__(self, base: List[int]) -> None:
+        """_summary_
+
+        Args:
+            base (List[int]): _description_
+        """
+        self.vdc = VdCorput(base[0])
+        self.sphere2 = Sphere(base[1:3])
+
+    def reseed(self, seed: int) -> None:
+        """_summary_
+
+        Args:
+            seed (int): _description_
+        """
+        self.vdc.reseed(seed)
+        self.sphere2.reseed(seed)
+
+    def pop(self) -> List[float]:
+        """_summary_
+
+        Returns:
+            List[float]: _description_
+        """
+        ti = HALF_PI * self.vdc.pop()  # map to [t0, tm-1]
+        xi = np.interp(ti, F2, X)
+        cosxi = math.cos(xi)
+        sinxi = math.sin(xi)
+        return [sinxi * s for s in self.sphere2.pop()] + [cosxi]
+
+
+class SphereN(SphereGen):
+    """Sphere-N sequence generator
+
+    Examples:
+        >>> sgen = SphereN([2, 3, 5, 7])
+        >>> sgen.reseed(0)
+        >>> for _ in range(1):
+        ...     print(sgen.pop())
+        ...
+        [0.4809684718990214, 0.6031153874276115, -0.5785601510223212, 0.2649326520763179, 6.123233995736766e-17]
+    """
+
+    def __init__(self, base: List[int]) -> None:
+        """_summary_
+
+        Args:
+            base (List[int]): _description_
+        """
+        n = len(base) - 1
+        assert n >= 2
+        self.vdc = VdCorput(base[0])
+        self.s_gen = Sphere(base[1:3]) if n == 2 else SphereN(base[1:])
+        self.n = n
+        tp = get_tp(n)
+        self.range = tp[-1] - tp[0]
+
+    def pop(self) -> List[float]:
+        """_summary_
+
+        Returns:
+            List[float]: _description_
+        """
+        vd = self.vdc.pop()
+        tp = get_tp(self.n)
+        ti = tp[0] + self.range * vd  # map to [t0, tm-1]
+        xi = np.interp(ti, tp, X)
+        sinphi = math.sin(xi)
+        return [xi * sinphi for xi in self.s_gen.pop()] + [math.cos(xi)]
+
+    def reseed(self, seed: int) -> None:
+        """_summary_
+
+        Args:
+            seed (int): _description_
+        """
+        self.vdc.reseed(seed)
+        self.s_gen.reseed(seed)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

sphere_n-0.2.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: sphere-n
+Version: 0.2
+Summary: A library for low-discrepancy sequences
+Home-page: https://github.com/pyscaffold/pyscaffold/
+Author: Wai-Shing Luk
+Author-email: luk036@gmail.com
+License: MIT
+Project-URL: Documentation, https://pyscaffold.org/
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst; charset=UTF-8
+License-File: LICENSE.txt
+Requires-Dist: importlib-metadata
+Requires-Dist: numpy
+Provides-Extra: testing
+Requires-Dist: setuptools; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: numpy; extra == "testing"
+Requires-Dist: scipy; extra == "testing"
+Dynamic: license-file
+
+[![codecov](https://codecov.io/gh/luk036/sphere-n/branch/main/graph/badge.svg?token=EIv4D8NlYj)](https://codecov.io/gh/luk036/sphere-n)
+[![Documentation Status](https://readthedocs.org/projects/sphere-n/badge/?version=latest)](https://sphere-n.readthedocs.io/en/latest/?badge=latest)
+
+# ⚽ sphere-n
+
+> Generator of Low discrepancy Sequence on S_n
+
+This library implements a generator for the generation of low-discrepancy sequences on n-dimensional spheres. Low-discrepancy sequences are utilized for the generation of points that are distributed uniformly across a given space. This technique is of significant value in a number of fields, including computer graphics, numerical integration, and Monte Carlo simulations.
+
+The principal objective of this library is to facilitate the generation of points on the surface of spheres of varying dimensions, including three-dimensional and higher-dimensional spheres. The input required is the dimension of the sphere (n) and a set of base numbers to be used for the underlying sequence generation. The output is a series of vectors, with each vector representing a point on the surface of the n-dimensional sphere.
+
+The library achieves this through a combination of mathematical calculations and recursive structures. The library utilizes a number of fundamental components, including:
+
+1. The VdCorput sequence generator produces a sequence of numbers that are evenly distributed between 0 and 1.
+2. Subsequently, the aforementioned numerical data is mapped onto the surface of a sphere through the use of interpolation functions.
+3. The SphereGen module represents an abstract base class that defines the common interface for all sphere generators.
+4. The recursive structures, namely Sphere3 and NSphere, facilitate the construction of higher-dimensional spheres from their lower-dimensional counterparts.
+
+The primary logic flow begins with the construction of a SphereN object, which utilizes either a Sphere3 (for 3D) or a recursive process to generate lower-dimensional spheres for higher dimensions. In the generation of points, the VdCorput sequence is employed to obtain a base number, which is then subjected to a series of transformations involving sine, cosine, and interpolation in order to map it onto the surface of the sphere.
+
+A noteworthy aspect of the library is its incorporation of caching (through the @cache decorator) to optimize performance by storing and reusing calculated values. Moreover, the library provides traits and structures that facilitate the adaptable deployment of the sphere generators. The SphereGen abstract base class serves to define a common interface for a variety of sphere generators, whereas the NSphere and SphereN structures are responsible for implementing the actual generation logic.
+
+In conclusion, this library provides a sophisticated yet flexible method for generating evenly distributed points on high-dimensional spheres, which can be advantageous in numerous scientific and computational applications.
+
+## Dependencies
+
+- [luk036/lds-gen](https://github.com/luk036/lds-gen)
+- numpy 
+- scipy (for testing only)
+
+## 👀 See also
+
+- [sphere-n-cpp](https://github.com/luk036/sphere-n-cpp)
+- [sphere-n-rs](https://github.com/luk036/sphere-n-rs)
+- [slides](https://luk036.github.io/n_sphere/slides.html)
+
+## 👉 Note
+
+This project has been set up using PyScaffold 3.2.1. For details and usage
+information on PyScaffold see <https://pyscaffold.org/>.

sphere_n-0.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+sphere_n/__init__.py,sha256=maG-vIFXReSK10FS8_urv6C-TfJrlIYSGKw9p9h3hmY,579
+sphere_n/cylind_n.py,sha256=5zRpnSGPdzhM9SSsQBGF7Cr6_HSUWtzrubIL9537p1E,3612
+sphere_n/discrep_2.py,sha256=Ts-D8Rov95aOc0etDc0mE_L7_dDqkamyC-Sm3B4vnCA,612
+sphere_n/sphere_n.py,sha256=ouO9I1MpIDAEhA3S7KEVY9HRG0vEnXqNOA0gj_fmWqE,6723
+sphere_n-0.2.dist-info/licenses/LICENSE.txt,sha256=MyvlyWiWdJ3ZpAOA4wziXlNa9Hbx8XnEL1Aztt9F7W8,1080
+sphere_n-0.2.dist-info/METADATA,sha256=cCpMVrh1qR5T_s2M8oowSzrVghJVW4dZHauBV4N9g6g,4248
+sphere_n-0.2.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+sphere_n-0.2.dist-info/top_level.txt,sha256=iHzEhUMhA0LQaS3boyXp_F3-Nz1VBrfWAufktLNGrdo,9
+sphere_n-0.2.dist-info/RECORD,,

sphere_n-0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sphere_n-0.2.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Wai-Shing Luk
+
+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.

sphere_n-0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+sphere_n