diff --git a/doc/source/bit_generators/lcg128mix.rst b/doc/source/bit_generators/lcg128mix.rst index 2d64a34264..34a847577a 100644 --- a/doc/source/bit_generators/lcg128mix.rst +++ b/doc/source/bit_generators/lcg128mix.rst @@ -20,6 +20,7 @@ Parallel generation :toctree: generated/ ~LCG128Mix.advance + ~LCG128Mix.advance_step ~LCG128Mix.jumped Extending diff --git a/doc/source/bit_generators/pcg32.rst b/doc/source/bit_generators/pcg32.rst index eb41918f8a..125c35e392 100644 --- a/doc/source/bit_generators/pcg32.rst +++ b/doc/source/bit_generators/pcg32.rst @@ -22,6 +22,7 @@ Parallel generation :toctree: generated/ ~PCG32.advance + ~PCG32.advance_step ~PCG32.jumped Extending diff --git a/doc/source/bit_generators/pcg64.rst b/doc/source/bit_generators/pcg64.rst index a131f7ed86..1ae07747c0 100644 --- a/doc/source/bit_generators/pcg64.rst +++ b/doc/source/bit_generators/pcg64.rst @@ -22,6 +22,7 @@ Parallel generation :toctree: generated/ ~PCG64.advance + ~PCG64.advance_step ~PCG64.jumped Extending diff --git a/doc/source/bit_generators/pcg64dxsm.rst b/doc/source/bit_generators/pcg64dxsm.rst index 8091b7e770..4fdd5b1bc6 100644 --- a/doc/source/bit_generators/pcg64dxsm.rst +++ b/doc/source/bit_generators/pcg64dxsm.rst @@ -20,6 +20,7 @@ Parallel generation :toctree: generated/ ~PCG64DXSM.advance + ~PCG64DXSM.advance_step ~PCG64DXSM.jumped Extending diff --git a/doc/source/change-log.rst b/doc/source/change-log.rst index a1929e3967..58df7bde47 100644 --- a/doc/source/change-log.rst +++ b/doc/source/change-log.rst @@ -39,6 +39,18 @@ New features They used to set a flag shared by the whole process, and creating or reseeding any instance turned SIMD back on. The output is the same with and without SIMD. +- Added ``advance_step(max_draws)`` to :class:`~randomgen.pcg64.PCG64`, + :class:`~randomgen.pcg64.PCG64DXSM`, :class:`~randomgen.pcg64.LCG128Mix` + and :class:`~randomgen.pcg32.PCG32` + (:meth:`~randomgen.pcg64.PCG64.advance_step`). It returns a step for + splitting one stream into several, where stream ``i`` is advanced by + ``i * step`` and makes at most ``max_draws`` draws. The step is the odd + integer closest to :math:`2^{XX}/\phi`, where :math:`\phi` is the golden + ratio, for the smallest :math:`XX` with :math:`2^{XX}/\phi` larger than + ``max_draws``, and is computed with integer arithmetic only. Because it is + odd, the states of the streams differ as if at random, apart from their + lowest few bits. Because it is at least ``max_draws``, ``n`` streams do not + overlap as long as ``n * step`` is no larger than the period. .. _stream-changes-2-6-0: @@ -160,7 +172,8 @@ Other fixes - A failed aligned allocation raises ``MemoryError`` instead of crashing, and HC-128 no longer relies on unaligned pointer casts. - The ``advance`` methods of the PCG generators warn against splitting one - stream with a large power of two, and suggest an odd step + stream with a large power of two, and explain how to choose an odd step, + which ``advance_step`` computes (`#450 `_). - The documentation of ``random(dtype=np.longdouble)`` explains why it gives different values across platforms. diff --git a/doc/source/parallel.rst b/doc/source/parallel.rst index 4f245d910b..fdb32de720 100644 --- a/doc/source/parallel.rst +++ b/doc/source/parallel.rst @@ -109,10 +109,54 @@ required to ensure exact reproducibility. In addition to the cryptographic PRNGs, the PCG-based generators also support ``advance``: :class:`~randomgen.pcg64.PCG64`, -:class:`~randomgen.pcg64.LCG128Mix`, and :class:`~randomgen.pcg32.PCG32`. +:class:`~randomgen.pcg64.PCG64DXSM`, :class:`~randomgen.pcg64.LCG128Mix`, and +:class:`~randomgen.pcg32.PCG32`. Note that :class:`~randomgen.hc128.HC128` is based on a stream cipher and so does not support advancing a counter. +.. warning:: + + Do not split a single stream of a PCG-based generator by advancing it by a + large power of two, such as :math:`2^{127}` (:math:`2^{63}` for + :class:`~randomgen.pcg32.PCG32`). These generators are built on an LCG + modulo a power of two, whose lowest :math:`e` bits repeat every + :math:`2^e` steps, so the streams share the lowest bits of their states and + their outputs are strongly related. For example, after advancing + :class:`~randomgen.pcg64.PCG64` by :math:`2^{127}`, each output is the + other with its 32-bit halves swapped and one bit flipped. The ``advance`` + method of each generator describes the effect on its output functions. + + Instead, advance stream ``i`` by ``i * step`` with an odd ``step``. With + any odd step the states of two streams differ as if at random, apart from + their lowest few bits. The size of the step matters for overlap: it must be + at least the number of draws that each stream makes, and ``n`` streams are + only guaranteed not to overlap when ``n * step`` is no larger than the + period. A convenient step is the odd integer closest to + :math:`2^{XX}/\phi`, where :math:`\phi` is the golden ratio, for example + ``0x9e3779b97f4a7c15`` (:math:`XX = 64`, about :math:`1.1 \times 10^{19}` + draws per stream) or, for :class:`~randomgen.pcg32.PCG32`, + ``0x9e3779b9`` (:math:`XX = 32`, about :math:`2.7 \times 10^{9}` draws per + stream). Each generator's ``advance_step`` method, such as + :meth:`PCG64.advance_step `, takes the + largest number of draws that any stream makes and returns this step for the + smallest :math:`XX` that works. ``jumped`` uses a golden-ratio step and is + also a good choice. + + The period of :class:`~randomgen.pcg32.PCG32` is only :math:`2^{64}`, which + limits it to, for example, about :math:`1.4 \times 10^{7}` streams of + :math:`10^{12}` draws. Use :class:`~randomgen.pcg64.PCG64`, or the related + :class:`~randomgen.pcg64.PCG64DXSM` or :class:`~randomgen.pcg64.LCG128Mix`, + whose period is :math:`2^{128}`, when many streams or many draws per stream + are needed. + + .. code-block:: python + + from randomgen import PCG64 + + # Each stream makes at most 10**12 draws + STEP = PCG64.advance_step(10**12) + streams = [PCG64(1234).advance(i * STEP) for i in range(16)] + .. _jumping: Jumping the PRNG state diff --git a/randomgen/common.pxd b/randomgen/common.pxd index f6ace0c5ed..9be4ef8095 100644 --- a/randomgen/common.pxd +++ b/randomgen/common.pxd @@ -24,6 +24,7 @@ cdef object random_raw(bitgen_t *bitgen, object lock, object size, object output cdef object prepare_cffi(bitgen_t *bitgen) cdef object prepare_ctypes(bitgen_t *bitgen) cdef object wrap_int(object val, object bits) +cdef object golden_advance_step(object max_draws, object bits) cdef object check_state_array(object arr, np.npy_intp required_len, int required_bits, object name) cdef object check_state_int(object value, str name, object lower, object upper) diff --git a/randomgen/common.pyx b/randomgen/common.pyx index 068f205969..22d552badc 100644 --- a/randomgen/common.pyx +++ b/randomgen/common.pyx @@ -1,4 +1,5 @@ from collections import namedtuple +import math import operator import sys from threading import RLock @@ -420,6 +421,35 @@ cdef object wrap_int(object val, object bits): val = val - upper * divisor return val +cdef object golden_advance_step(object max_draws, object bits): + """ + Odd integer closest to 2**xx / phi for the smallest xx with 2**xx / phi > max_draws + + Only integer arithmetic is used. 2**xx / phi = (sqrt(5) - 1) * 2**xx / 2 and + sqrt(5) * 2**xx is irrational, so with r = isqrt(5 * 4**xx), the integer part + of 2**xx / phi is (r - 2**xx) // 2. As 2**xx / phi is irrational, it is larger + than an integer n exactly when its integer part is at least n. + """ + n = operator.index(max_draws) + # 2**xx / phi > n needs 2**xx > n, so xx >= n.bit_length(). Since 1 / phi > 1 / 2, + # 2**xx >= 2 * n is enough, so xx is either n.bit_length() or one more. + if n >= 1: + for xx in (n.bit_length(), n.bit_length() + 1): + if xx > bits: + break + p = 1 << xx + floor = (math.isqrt(5 * p * p) - p) // 2 + if floor >= n: + # 2**xx / phi lies strictly between floor and floor + 1, so the + # closest odd integer is floor if it is odd and floor + 1 otherwise + return floor if floor & 1 else floor + 1 + p = 1 << bits + upper = (math.isqrt(5 * p * p) - p) // 2 + raise ValueError( + f"max_draws must be between 1 and {upper}, the integer part of " + f"2**{bits} / phi, where phi is the golden ratio." + ) + cdef int check_state_config(object bit_generator, str name, object current, object new) except -1: """ diff --git a/randomgen/pcg32.pxd b/randomgen/pcg32.pxd index 1706cc6649..bbfbb22a5a 100644 --- a/randomgen/pcg32.pxd +++ b/randomgen/pcg32.pxd @@ -1,7 +1,12 @@ cimport numpy as np from libc.stdint cimport uint32_t, uint64_t -from randomgen.common cimport BitGenerator, fully_qualified_name, wrap_int +from randomgen.common cimport ( + BitGenerator, + fully_qualified_name, + golden_advance_step, + wrap_int, +) cdef extern from "src/pcg32/pcg32.h": diff --git a/randomgen/pcg32.pyi b/randomgen/pcg32.pyi index e46bcc4783..42ecd0c332 100644 --- a/randomgen/pcg32.pyi +++ b/randomgen/pcg32.pyi @@ -17,4 +17,6 @@ class PCG32(BitGenerator): @state.setter def state(self, value: dict[str, str | dict[str, int]]) -> None: ... def advance(self, delta: int) -> PCG32: ... + @staticmethod + def advance_step(max_draws: int) -> int: ... def jumped(self, iter: int = ...) -> PCG32: ... diff --git a/randomgen/pcg32.pyx b/randomgen/pcg32.pyx index 388a84c7ff..d73c7e9b29 100644 --- a/randomgen/pcg32.pyx +++ b/randomgen/pcg32.pyx @@ -78,6 +78,18 @@ cdef class PCG32(BitGenerator): >>> for i in range(10): ... rg[i].bit_generator.advance(i * 2**32) + Each instance above uses a different increment ``inc``. To split a single + stream, advance stream ``i`` by ``i * step``, where ``step`` is + ``advance_step(max_draws)`` and ``max_draws`` is the most draws that any + stream makes, or use ``jumped``. Do not advance by a large power of two + such as ``2**63``, which gives strongly related streams (see + ``advance``). The period of ``PCG32`` is only ``2**64``, which limits how + many streams fit without overlapping, for example to about + ``1.4 * 10**7`` streams of ``10**12`` draws. Use + :class:`~randomgen.pcg64.PCG64`, or the related + :class:`~randomgen.pcg64.PCG64DXSM` or :class:`~randomgen.pcg64.LCG128Mix`, + when many streams or many draws per stream are needed. + **Compatibility Guarantee** ``PCG32`` makes a guarantee that a fixed seed and will always produce @@ -184,6 +196,36 @@ cdef class PCG32(BitGenerator): self : PCG32 RNG advanced delta steps + Warnings + -------- + Do not use ``advance`` with a large power of two, such as ``2**63`` + (half of the period), to split a single stream (the same seed and + ``inc``) into several. The state is an LCG modulo ``2**64``, whose + lowest ``e`` bits repeat every ``2**e`` steps, so advancing by + ``2**e`` leaves them unchanged. After ``advance(2**63)``, the two + states differ only in their top bit at every step, and each output + is the other with its 16-bit halves swapped and one bit flipped. + + After ``advance(2**32)``, the states differ in about 16 of their 64 + bits and never in the lowest 32. + + The size of the step also matters. Stream ``i``, advanced by + ``i * step``, can make at most ``step`` draws before it reaches the + start of stream ``i + 1``, and ``n`` streams are only guaranteed not + to overlap when ``n * step <= 2**64``. The period of ``PCG32`` is + short enough for this to limit real applications, for example to + about ``1.4 * 10**7`` streams of ``10**12`` draws. Use + :class:`~randomgen.pcg64.PCG64`, or the related + :class:`~randomgen.pcg64.PCG64DXSM` or + :class:`~randomgen.pcg64.LCG128Mix`, when many streams or many draws + per stream are needed. ``advance_step`` returns an odd step for a + given number of draws per stream, and the Notes explain how to choose + one. + + See Also + -------- + advance_step : Step for splitting one stream into several. + Notes ----- Advancing a RNG updates the underlying RNG state as-if a given @@ -199,12 +241,148 @@ cdef class PCG32(BitGenerator): differs from the number of bits generated by the underlying RNG. For example, two 16-bit integer values can be simulated from a single draw of a 32-bit RNG. + + To split one stream into several, advance stream ``i`` by ``i * step`` + with an odd ``step``. With an odd step, the states of two streams + differ in their lowest bit at every step and their other bits differ as + if at random: about 32 of the 64 bits differ, with the spread of a + binomial distribution. Only the lowest few bits follow a fixed pattern, + since in any LCG they repeat every few steps. This holds for an odd + step of any size. The size sets how far apart the streams are: stream + ``i`` reaches the start of stream ``i + 1`` after ``step`` draws, so + ``step`` must be at least the number of draws that any stream makes. + The starts ``i * step`` are taken modulo the period, ``2**64``, so + ``n`` streams are only guaranteed not to overlap when + ``n * step <= 2**64``. + + A convenient step is the odd integer closest to ``2**XX / phi``, where + phi is the golden ratio and ``XX`` is chosen so that the step is at + least the number of draws per stream. ``advance_step(max_draws)`` + returns this step for the smallest ``XX`` that works, using only + integer arithmetic. For example, ``XX = 32`` gives ``0x9e3779b9``, + about ``2.7 * 10**9`` draws per stream, and ``XX = 64`` gives + ``0x9e3779b97f4a7c15``, the step of ``jumped``. With ``XX = 64`` the + multiples of the step wrap around the period, and the golden ratio + spreads the streams evenly around it. + + >>> step = PCG32.advance_step(10**10) + >>> hex(step) + '0x278dde6e5' + >>> streams = [PCG32(1234).advance(i * step) for i in range(8)] + + The period of ``PCG32``, ``2**64``, is short enough for + ``n * step <= 2**64`` to limit the number of streams in practice. With + the step from ``advance_step``, the largest number of streams that are + guaranteed not to overlap is + + ================= ================== + Draws per stream Streams + ================= ================== + ``10**6`` ``1.4 * 10**13`` + ``10**9`` ``1.4 * 10**10`` + ``10**12`` ``1.4 * 10**7`` + ``10**15`` 13,254 + ``10**18`` 12 + ================= ================== + + The step from ``advance_step`` is less than twice the number of draws + per stream, so ``n`` streams of ``m`` draws always fit when + ``n * m <= 2**63``. When many streams or many draws per stream are + needed, use :class:`~randomgen.pcg64.PCG64`, or the related + :class:`~randomgen.pcg64.PCG64DXSM` or + :class:`~randomgen.pcg64.LCG128Mix`. Their period of ``2**128`` allows + about ``2.5 * 10**26`` streams of ``10**12`` draws. + + Streams ``i`` and ``j`` are ``(j - i) * step`` draws apart, so they + share the lowest ``v`` bits of their states, where ``2**v`` is the + largest power of two that divides ``j - i``. ``jumped(iter)`` advances + by ``iter`` times a golden-ratio step, so it is also a good choice when + ``iter`` is not a large power of two. """ delta = wrap_int(delta, 64) with self.lock: pcg32_advance_state(&self.rng_state, delta) return self + @staticmethod + def advance_step(max_draws): + """ + advance_step(max_draws) + + Step for splitting one stream into streams of up to max_draws draws + + .. versionadded:: 2.6.0 + + Parameters + ---------- + max_draws : int + The largest number of draws that any stream makes. Must be at + least 1 and at most the integer part of ``2**64 / phi``, about + ``1.1 * 10**19``, where phi is the golden ratio. + + Returns + ------- + step : int + The odd integer closest to ``2**XX / phi``, where ``XX`` is the + smallest integer for which ``2**XX / phi`` is larger than + ``max_draws``. The step is never smaller than ``max_draws``. + + Raises + ------ + ValueError + If ``max_draws`` is outside the range above. + TypeError + If ``max_draws`` is not an integer. + + See Also + -------- + advance : Advance the state as-if delta draws have occurred. + + Notes + ----- + Advance stream ``i`` by ``i * step`` to split one stream into several. + The step is odd, so the states of two streams differ as if at random, + apart from their lowest few bits. The step is at least ``max_draws``, + so a stream that makes at most ``max_draws`` draws does not reach the + start of the next stream. The Notes of ``advance`` explain this choice + of step. + + The starts ``i * step`` are taken modulo the period, ``2**64``, so + streams ``0`` to ``n - 1`` are only guaranteed not to overlap when + ``n * step <= 2**64``. ``advance_step`` does not check this, since it + does not know ``n``, and the period of ``PCG32`` is short enough for + the limit to matter. The largest ``n`` is ``2**64 // step``: + + ================= ================== + ``max_draws`` Largest ``n`` + ================= ================== + ``10**6`` ``1.4 * 10**13`` + ``10**9`` ``1.4 * 10**10`` + ``10**12`` ``1.4 * 10**7`` + ``10**15`` 13,254 + ``10**18`` 12 + ================= ================== + + The step is less than ``2 * max_draws``, so ``n`` streams always fit + when ``n * max_draws <= 2**63``. When many streams or many draws per + stream are needed, use :class:`~randomgen.pcg64.PCG64`, or the related + :class:`~randomgen.pcg64.PCG64DXSM` or + :class:`~randomgen.pcg64.LCG128Mix`. Their period of ``2**128`` allows + about ``2.5 * 10**26`` streams of ``10**12`` draws. + + The step is computed with integer arithmetic only, so it is exact for + any ``max_draws``. + + Examples + -------- + >>> from randomgen import PCG32 + >>> step = PCG32.advance_step(10**10) + >>> hex(step) + '0x278dde6e5' + >>> streams = [PCG32(1234).advance(i * step) for i in range(8)] + """ + return golden_advance_step(max_draws, 64) + cdef jump_inplace(self, object iter): """ Jump state in-place diff --git a/randomgen/pcg64.pxd b/randomgen/pcg64.pxd index 5234810bc9..beb15cf45b 100644 --- a/randomgen/pcg64.pxd +++ b/randomgen/pcg64.pxd @@ -7,6 +7,7 @@ from randomgen.common cimport ( PyArray_malloc_aligned, check_state_config, fully_qualified_name, + golden_advance_step, uint64_to_double, wrap_int, ) diff --git a/randomgen/pcg64.pyi b/randomgen/pcg64.pyi index 1cdce26256..c5b49e9cc7 100644 --- a/randomgen/pcg64.pyi +++ b/randomgen/pcg64.pyi @@ -36,6 +36,8 @@ class PCG64(BitGenerator): @state.setter def state(self, value: dict[str, str | int | dict[str, int]]) -> None: ... def advance(self, delta: int) -> PCG64: ... + @staticmethod + def advance_step(max_draws: int) -> int: ... def jumped(self, iter: int = ...) -> PCG64: ... class LCG128Mix(BitGenerator): @@ -62,6 +64,8 @@ class LCG128Mix(BitGenerator): value: dict[str, str | int | dict[str, bool | int | str]], ) -> None: ... def advance(self, delta: int) -> LCG128Mix: ... + @staticmethod + def advance_step(max_draws: int) -> int: ... def jumped(self, iter: int = ...) -> LCG128Mix: ... class PCG64DXSM(PCG64): diff --git a/randomgen/pcg64.pyx b/randomgen/pcg64.pyx index 38cc4dd97b..fa4ef738df 100644 --- a/randomgen/pcg64.pyx +++ b/randomgen/pcg64.pyx @@ -143,6 +143,13 @@ cdef class PCG64(BitGenerator): >>> for i in range(10): ... rg[i].bit_generator.advance(i * 2**64) + Each instance above uses a different increment ``inc``. To split a single + stream, advance stream ``i`` by ``i * step``, where ``step`` is + ``advance_step(max_draws)`` and ``max_draws`` is the most draws that any + stream makes, or use ``jumped``. Do not advance by a large power of two + such as ``2**127``, which gives strongly related streams (see + ``advance``). + References ---------- .. [1] "PCG, A Family of Better Random Number Generators", @@ -359,6 +366,38 @@ cdef class PCG64(BitGenerator): self : PCG64 RNG advanced delta steps + Warnings + -------- + Do not use ``advance`` with a large power of two, such as ``2**127`` + (half of the period), to split a single stream (the same seed and + ``inc``) into several. The state is an LCG modulo ``2**128``, whose + lowest ``e`` bits repeat every ``2**e`` steps, so advancing by + ``2**e`` leaves them unchanged. After ``advance(2**127)``, the two + states differ only in their top bit at every step, and the outputs + are strongly related: + + * ``"xsl-rr"``: each output is the other with its 32-bit halves + swapped and one bit flipped. More generally, advancing by + ``2**(128 - t)`` gives outputs that are rotations of each other + with at most ``t`` bits flipped. + * ``"dxsm"``, ``"dxsm-128"`` and ``PCG64DXSM``: the two outputs are + never congruent modulo 4, so their last hexadecimal digits never + coincide, and PractRand fails the interleaved streams at 1 MB. + + After ``advance(2**64)``, the states differ in about 32 of their 128 + bits and never in the lowest 64. + + The size of the step also matters. Stream ``i``, advanced by + ``i * step``, can make at most ``step`` draws before it reaches the + start of stream ``i + 1``, and ``n`` streams are only guaranteed not + to overlap when ``n * step <= 2**128``. ``advance_step`` returns an + odd step for a given number of draws per stream, and the Notes + explain how to choose one. + + See Also + -------- + advance_step : Step for splitting one stream into several. + Notes ----- Advancing a RNG updates the underlying RNG state as-if a given @@ -377,6 +416,46 @@ cdef class PCG64(BitGenerator): Advancing the RNG state resets any pre-computed random numbers. This is required to ensure exact reproducibility. + + To split one stream into several, advance stream ``i`` by ``i * step`` + with an odd ``step``. With an odd step, the states of two streams + differ in their lowest bit at every step and their other bits differ as + if at random: about 64 of the 128 bits differ, with the spread of a + binomial distribution. Only the lowest few bits follow a fixed pattern, + since in any LCG they repeat every few steps. This holds for an odd + step of any size. The size sets how far apart the streams are: stream + ``i`` reaches the start of stream ``i + 1`` after ``step`` draws, so + ``step`` must be at least the number of draws that any stream makes. + The starts ``i * step`` are taken modulo the period, ``2**128``, so + ``n`` streams are only guaranteed not to overlap when + ``n * step <= 2**128``. This is not a practical limit: streams of + ``10**12`` draws allow about ``2.5 * 10**26`` streams. + + A convenient step is the odd integer closest to ``2**XX / phi``, where + phi is the golden ratio and ``XX`` is chosen so that the step is at + least the number of draws per stream. ``advance_step(max_draws)`` + returns this step for the smallest ``XX`` that works, using only + integer arithmetic. For example, ``XX = 48`` gives ``0x9e3779b97f4b``, + about ``1.7 * 10**14`` draws per stream, ``XX = 64`` gives + ``0x9e3779b97f4a7c15``, about ``1.1 * 10**19``, and ``XX = 128`` gives + ``0x9e3779b97f4a7c15f39cc0605cedc835``, the step of ``jumped`` and of + NumPy's ``PCG64.jumped``. With ``XX = 128`` the multiples of the step + wrap around the period, and the golden ratio spreads the streams evenly + around it. + + >>> step = PCG64.advance_step(10**10) + >>> hex(step) + '0x278dde6e5' + >>> streams = [PCG64(1234).advance(i * step) for i in range(8)] + + Streams ``i`` and ``j`` are ``(j - i) * step`` draws apart, so they + share the lowest ``v`` bits of their states, where ``2**v`` is the + largest power of two that divides ``j - i``. With fewer than ``2**20`` + streams that is at most 19 bits. NumPy reports that two XSL-RR streams + that share their lowest 58 bits and their increment fail PractRand when + interleaved. ``jumped(iter)`` advances by ``iter`` times a golden-ratio + step, so it is also a good choice when ``iter`` is not a large power of + two. """ delta = wrap_int(delta, 128) @@ -390,6 +469,68 @@ cdef class PCG64(BitGenerator): self._reset_state_variables() return self + @staticmethod + def advance_step(max_draws): + """ + advance_step(max_draws) + + Step for splitting one stream into streams of up to max_draws draws + + .. versionadded:: 2.6.0 + + Parameters + ---------- + max_draws : int + The largest number of draws that any stream makes. Must be at + least 1 and at most the integer part of ``2**128 / phi``, about + ``2.1 * 10**38``, where phi is the golden ratio. + + Returns + ------- + step : int + The odd integer closest to ``2**XX / phi``, where ``XX`` is the + smallest integer for which ``2**XX / phi`` is larger than + ``max_draws``. The step is never smaller than ``max_draws``. + + Raises + ------ + ValueError + If ``max_draws`` is outside the range above. + TypeError + If ``max_draws`` is not an integer. + + See Also + -------- + advance : Advance the state as-if delta draws have occurred. + + Notes + ----- + Advance stream ``i`` by ``i * step`` to split one stream into several. + The step is odd, so the states of two streams differ as if at random, + apart from their lowest few bits. The step is at least ``max_draws``, + so a stream that makes at most ``max_draws`` draws does not reach the + start of the next stream. The Notes of ``advance`` explain this choice + of step. + + The starts ``i * step`` are taken modulo the period, ``2**128``, so + streams ``0`` to ``n - 1`` are only guaranteed not to overlap when + ``n * step <= 2**128``. ``advance_step`` does not check this, since it + does not know ``n``, but it is not a practical limit: streams of + ``10**12`` draws allow about ``2.5 * 10**26`` streams. + + The step is computed with integer arithmetic only, so it is exact for + any ``max_draws``. + + Examples + -------- + >>> from randomgen import PCG64 + >>> step = PCG64.advance_step(10**10) + >>> hex(step) + '0x278dde6e5' + >>> streams = [PCG64(1234).advance(i * step) for i in range(8)] + """ + return golden_advance_step(max_draws, 128) + cdef jump_inplace(self, object iter): """ Jump state in-place @@ -855,9 +996,46 @@ cdef class LCG128Mix(BitGenerator): Returns ------- - self : PCG64 + self : LCG128Mix RNG advanced delta steps + Warnings + -------- + Do not use ``advance`` with a large power of two, such as ``2**127`` + (half of the period), to split a single stream (the same seed, + ``inc`` and ``multiplier``) into several. The state is an LCG modulo + ``2**128``, whose lowest ``e`` bits repeat every ``2**e`` steps, so + advancing by ``2**e`` leaves them unchanged. After + ``advance(2**127)``, the two states differ only in their top bit at + every step, and with most output functions the outputs are strongly + related: + + * ``"xsl-rr"``: each output is the other with its 32-bit halves + swapped and one bit flipped. + * ``"dxsm"``: the two outputs are never congruent modulo 4, and + PractRand fails the interleaved streams at 1 MB. + * ``"upper"``: the outputs are identical except for the highest bit. + More generally, advancing by ``2**(128 - t)`` leaves the lowest + ``64 - t`` bits of every output unchanged. + * ``"lower"``: the outputs are identical, as they are after advancing + by any multiple of ``2**64``. + * ``"murmur3"``: no pattern is visible in the outputs, although the + states are related in the same way. + + After ``advance(2**64)``, the states differ in about 32 of their 128 + bits and never in the lowest 64. + + The size of the step also matters. Stream ``i``, advanced by + ``i * step``, can make at most ``step`` draws before it reaches the + start of stream ``i + 1``, and ``n`` streams are only guaranteed not + to overlap when ``n * step <= 2**128``. ``advance_step`` returns an + odd step for a given number of draws per stream, and the Notes + explain how to choose one. + + See Also + -------- + advance_step : Step for splitting one stream into several. + Notes ----- Advancing a RNG updates the underlying RNG state as-if a given @@ -876,6 +1054,47 @@ cdef class LCG128Mix(BitGenerator): Advancing the RNG state resets any pre-computed random numbers. This is required to ensure exact reproducibility. + + To split one stream into several, advance stream ``i`` by ``i * step`` + with an odd ``step``. With an odd step, the states of two streams + differ in their lowest bit at every step and their other bits differ as + if at random: about 64 of the 128 bits differ, with the spread of a + binomial distribution, for the default ``multiplier``. Only the lowest + few bits follow a fixed pattern, since in any LCG they repeat every few + steps. This holds for an odd step of any size. The size sets how far + apart the streams are: stream ``i`` reaches the start of stream + ``i + 1`` after ``step`` draws, so ``step`` must be at least the number + of draws that any stream makes. The starts ``i * step`` are taken + modulo the period, ``2**128``, so ``n`` streams are only guaranteed not + to overlap when ``n * step <= 2**128``. This is not a practical limit + for ``LCG128Mix``: streams of ``10**12`` draws allow about + ``2.5 * 10**26`` streams. + + A convenient step is the odd integer closest to ``2**XX / phi``, where + phi is the golden ratio and ``XX`` is chosen so that the step is at + least the number of draws per stream. ``advance_step(max_draws)`` + returns this step for the smallest ``XX`` that works, using only + integer arithmetic. For example, ``XX = 48`` gives ``0x9e3779b97f4b``, + about ``1.7 * 10**14`` draws per stream, ``XX = 64`` gives + ``0x9e3779b97f4a7c15``, about ``1.1 * 10**19``, and ``XX = 128`` gives + ``0x9e3779b97f4a7c15f39cc0605cedc835``, the step of ``jumped`` and of + NumPy's ``PCG64.jumped``. With ``XX = 128`` the multiples of the step + wrap around the period, and the golden ratio spreads the streams evenly + around it. + + >>> step = LCG128Mix.advance_step(10**10) + >>> hex(step) + '0x278dde6e5' + >>> streams = [LCG128Mix(1234).advance(i * step) for i in range(8)] + + Streams ``i`` and ``j`` are ``(j - i) * step`` draws apart, so they + share the lowest ``v`` bits of their states, where ``2**v`` is the + largest power of two that divides ``j - i``. With fewer than ``2**20`` + streams that is at most 19 bits. NumPy reports that two XSL-RR streams + that share their lowest 58 bits and their increment fail PractRand when + interleaved. ``jumped(iter)`` advances by ``iter`` times a golden-ratio + step, so it is also a good choice when ``iter`` is not a large power of + two. """ delta = wrap_int(delta, 128) @@ -887,6 +1106,68 @@ cdef class LCG128Mix(BitGenerator): self._reset_state_variables() return self + @staticmethod + def advance_step(max_draws): + """ + advance_step(max_draws) + + Step for splitting one stream into streams of up to max_draws draws + + .. versionadded:: 2.6.0 + + Parameters + ---------- + max_draws : int + The largest number of draws that any stream makes. Must be at + least 1 and at most the integer part of ``2**128 / phi``, about + ``2.1 * 10**38``, where phi is the golden ratio. + + Returns + ------- + step : int + The odd integer closest to ``2**XX / phi``, where ``XX`` is the + smallest integer for which ``2**XX / phi`` is larger than + ``max_draws``. The step is never smaller than ``max_draws``. + + Raises + ------ + ValueError + If ``max_draws`` is outside the range above. + TypeError + If ``max_draws`` is not an integer. + + See Also + -------- + advance : Advance the state as-if delta draws have occurred. + + Notes + ----- + Advance stream ``i`` by ``i * step`` to split one stream into several. + The step is odd, so, for the default ``multiplier``, the states of two + streams differ as if at random, apart from their lowest few bits. The + step is at least ``max_draws``, so a stream that makes at most + ``max_draws`` draws does not reach the start of the next stream. The + Notes of ``advance`` explain this choice of step. + + The starts ``i * step`` are taken modulo the period, ``2**128``, so + streams ``0`` to ``n - 1`` are only guaranteed not to overlap when + ``n * step <= 2**128``. ``advance_step`` does not check this, since it + does not know ``n``, but it is not a practical limit: streams of + ``10**12`` draws allow about ``2.5 * 10**26`` streams. + + The step is computed with integer arithmetic only, so it is exact for + any ``max_draws``. + + Examples + -------- + >>> from randomgen import LCG128Mix + >>> step = LCG128Mix.advance_step(10**10) + >>> hex(step) + '0x278dde6e5' + >>> streams = [LCG128Mix(1234).advance(i * step) for i in range(8)] + """ + return golden_advance_step(max_draws, 128) + cdef jump_inplace(self, object iter): """ Jump state in-place @@ -1038,6 +1319,13 @@ cdef class PCG64DXSM(PCG64): >>> for i in range(10): ... rg[i].bit_generator.advance(i * 2**64) + Each instance above uses a different increment ``inc``. To split a single + stream, advance stream ``i`` by ``i * step``, where ``step`` is + ``advance_step(max_draws)`` and ``max_draws`` is the most draws that any + stream makes, or use ``jumped``. Do not advance by a large power of two + such as ``2**127``, which gives strongly related streams (see + ``advance``). + References ---------- .. [1] "PCG, A Family of Better Random Number Generators", diff --git a/randomgen/tests/test_direct.py b/randomgen/tests/test_direct.py index d4ed51195a..0e0966e4a7 100644 --- a/randomgen/tests/test_direct.py +++ b/randomgen/tests/test_direct.py @@ -1,6 +1,7 @@ from __future__ import annotations import copy +from decimal import Decimal, localcontext import os from os.path import join import pickle @@ -2421,6 +2422,110 @@ def test_inc_with_seed_none_numpy_seed(): PCG64(None, inc=5, numpy_seed=True) +ADVANCE_STEP_BITS = [(PCG32, 64), (PCG64, 128), (PCG64DXSM, 128), (LCG128Mix, 128)] + + +def _golden_floors(bits): + # Integer parts of 2**xx / phi for xx = 1, ..., bits, from 100-digit decimals + # rather than the integer arithmetic that advance_step uses + with localcontext() as ctx: + ctx.prec = 100 + inv_phi = (Decimal(5).sqrt() - 1) / 2 + return [int(Decimal(2) ** xx * inv_phi) for xx in range(1, bits + 1)] + + +@pytest.mark.parametrize(("bg_cls", "bits"), ADVANCE_STEP_BITS) +def test_advance_step(bg_cls, bits): + floors = _golden_floors(bits) + cases = {1, 2, 3, 1000, 10**10, 2**bits // 3} + for floor in floors: + cases.update({floor - 1, floor, floor + 1}) + cases = sorted(n for n in cases if 1 <= n <= floors[-1]) + for max_draws in cases: + # The smallest xx with 2**xx / phi > max_draws, and the closest odd integer + floor = next(f for f in floors if f >= max_draws) + expected = floor if floor % 2 else floor + 1 + step = bg_cls.advance_step(max_draws) + assert step == expected + assert step % 2 == 1 + assert step >= max_draws + # The docstrings use this bound for the number of streams that fit + assert step < 2 * max_draws + + +def test_advance_step_documented_stream_limits(): + # The largest number of streams that do not overlap, as given in the docstrings + # 1.4 * 10**13, 1.4 * 10**10 and 1.4 * 10**7, to two significant digits + for max_draws, power in ((10**6, 13), (10**9, 10), (10**12, 7)): + n = 2**64 // PCG32.advance_step(max_draws) + assert round(n, 1 - power) == 14 * 10 ** (power - 1) + assert 2**64 // PCG32.advance_step(10**15) == 13254 + assert 2**64 // PCG32.advance_step(10**18) == 12 + # 2.5 * 10**26 streams of 10**12 draws + for bg_cls in (PCG64, PCG64DXSM, LCG128Mix): + assert round(2**128 // bg_cls.advance_step(10**12), -25) == 25 * 10**25 + + +@pytest.mark.parametrize( + ("max_draws", "step"), + [ + (1, 1), + (1000, 0x4F1), + (10**10, 0x278DDE6E5), + (10**14, 0x9E3779B97F4B), + (10**19, 0x9E3779B97F4A7C15), + (2**63, 0x9E3779B97F4A7C15), + ], +) +@pytest.mark.parametrize("bg_cls", [PCG32, PCG64, PCG64DXSM, LCG128Mix]) +def test_advance_step_values(bg_cls, max_draws, step): + assert bg_cls.advance_step(max_draws) == step + assert bg_cls(0).advance_step(max_draws) == step + assert bg_cls.advance_step(np.uint64(max_draws)) == step + + +@pytest.mark.parametrize("bg_cls", [PCG64, PCG64DXSM, LCG128Mix]) +def test_advance_step_numpy_jumped(bg_cls): + # The step for XX = 128 is the step of NumPy's PCG64.jumped + assert bg_cls.advance_step(2**127) == 0x9E3779B97F4A7C15F39CC0605CEDC835 + + +@pytest.mark.parametrize( + ("bg_cls", "max_draws"), + [(PCG32, 2**63), (PCG64, 2**127), (PCG64DXSM, 2**127), (LCG128Mix, 2**127)], +) +def test_advance_step_jumped(bg_cls, max_draws): + # The step for XX = bits is the step of jumped + step = bg_cls.advance_step(max_draws) + for i in (1, 2, 5): + jumped = bg_cls(1234).jumped(i) + advanced = bg_cls(1234).advance(i * step) + assert jumped.state == advanced.state + + +@pytest.mark.parametrize(("bg_cls", "bits"), ADVANCE_STEP_BITS) +def test_advance_step_errors(bg_cls, bits): + largest = _golden_floors(bits)[-1] + assert bg_cls.advance_step(largest) < 2**bits + for max_draws in (0, -1, largest + 1, 2**bits): + with pytest.raises(ValueError, match=f"between 1 and {largest}"): + bg_cls.advance_step(max_draws) + for max_draws in (10.0**10, "10", None): + with pytest.raises(TypeError): + bg_cls.advance_step(max_draws) + + +@pytest.mark.parametrize("bg_cls", [PCG32, PCG64, PCG64DXSM, LCG128Mix]) +def test_advance_step_streams_do_not_overlap(bg_cls): + max_draws = 1000 + step = bg_cls.advance_step(max_draws) + streams = [bg_cls(1234).advance(i * step) for i in range(4)] + single = bg_cls(1234).random_raw(4 * step) + for i, stream in enumerate(streams): + draws = stream.random_raw(max_draws) + assert_array_equal(draws, single[i * step : i * step + max_draws]) + + class TestBlaBla(Base): @classmethod def setup_class(cls):