Update: random number generators

Author: heptaflar

kaleidoscope/generators.py

@@ -0,0 +1,116 @@
+#  Copyright (c) Brockmann Consult GmbH, 2025
+#  License: MIT
+
+"""
+This module provides random number generators.
+"""
+
+import numpy as np
+from numpy.random import BitGenerator
+from numpy.random import Generator
+from overrides import overrides
+
+from .interface.generating import Generating
+from .interface.generating import Normal
+from .interface.generating import Uniform
+from .interface.generating import Univariate
+
+
+def default_bit_generator(
+    seed: int | np.ndarray | None = None,
+) -> BitGenerator:
+    """
+    Returns the default bit generator.
+
+    :param seed: The seed.
+    :return: The default bit generator.
+    """
+    from numpy.random import PCG64DXSM
+
+    return PCG64DXSM(seed)
+
+
+def default_generator(seed) -> Generator:
+    """
+    Returns the default generator.
+
+    :param seed: The seed.
+    :return: The default generator.
+    """
+    return Generator(
+        seed
+        if isinstance(seed, BitGenerator)
+        else default_bit_generator(seed)
+    )
+
+
+class DefaultGenerator(Generating):
+    """The default random number generator."""
+
+    _g: Generator
+
+    def __init__(self, seed: int | np.ndarray | BitGenerator | None = None):
+        """
+        Creates a new random number generator.
+
+        :param seed: The seed.
+        """
+        self._g = default_generator(seed)
+
+    @overrides
+    def random(self) -> int:
+        return self._g.integers(0x8000000000000000)
+
+
+class DefaultUniform(Uniform):
+    """The default uniform random deviate."""
+
+    _g: Generator
+
+    def __init__(self, seed: int | np.ndarray | BitGenerator | None = None):
+        """
+        Creates a new random variate.
+
+        :param seed: The seed.
+        """
+        self._g = default_generator(seed)
+
+    @overrides
+    def get(self, i: int) -> Univariate:
+        return self
+
+    @overrides
+    def random(self) -> float:
+        return self._g.random()
+
+    @overrides
+    def randoms(self, randoms: np.ndarray) -> np.ndarray:
+        self._g.random(out=randoms)
+        return randoms
+
+
+class DefaultNormal(Normal):
+    """The default normal random variate."""
+
+    _g: Generator
+
+    def __init__(self, seed: int | np.ndarray | BitGenerator | None = None):
+        """
+        Creates a new random variate.
+
+        :param seed: The seed.
+        """
+        self._g = default_generator(seed)
+
+    @overrides
+    def get(self, i: int) -> Univariate:
+        return self
+
+    @overrides
+    def random(self) -> float:
+        return self._g.standard_normal()
+
+    @overrides
+    def randoms(self, randoms: np.ndarray) -> np.ndarray:
+        self._g.standard_normal(out=randoms)
+        return randoms

test/kaleidoscope/test_generators.py

@@ -0,0 +1,28 @@
+#  Copyright (c) Brockmann Consult GmbH, 2025
+#  License: MIT
+
+"""
+This module provides unit-level tests for random number generators.
+"""
+
+import unittest
+
+from numpy.random import PCG64
+
+from kaleidoscope.generators import DefaultGenerator
+
+
+class DefaultGeneratorTest(unittest.TestCase):
+
+    def test_random(self):
+        rng = DefaultGenerator(seed=PCG64(42))
+        self.assertEqual(6164909031098000398, rng.random())
+        self.assertEqual(62765134502071353, rng.random())
+        self.assertEqual(6068961337446000720, rng.random())
+        self.assertEqual(3424215743300924766, rng.random())
+        self.assertEqual(1906168894638979906, rng.random())
+        self.assertEqual(1787925334117997081, rng.random())
+
+
+if __name__ == "__main__":
+    unittest.main()