From d886762d5f50c9135eff31fb255d0bd0d6a39b8b Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Wed, 4 Nov 2026 08:39:06 +0000 Subject: [PATCH 1/6] DOC: Warn against advancing PCG generators by large powers of two Advancing an LCG modulo 2**128 (2**64 for PCG32) by 2**e leaves the lowest e bits of the state unchanged, so splitting one stream with advance(2**127) gives two streams whose states differ only in the top bit, and whose outputs are strongly related (issue #450). Add a Warnings section to PCG64.advance (also used by PCG64DXSM), LCG128Mix.advance and PCG32.advance that describes the effect on each output function, point the Parallel Features examples to it, and add a warning to the advancing section of parallel.rst. Also list PCG64DXSM there and fix the return type in the LCG128Mix.advance docstring. Co-Authored-By: Claude Opus 5.5 --- doc/source/parallel.rst | 16 ++++++++++- randomgen/pcg32.pyx | 18 +++++++++++++ randomgen/pcg64.pyx | 59 ++++++++++++++++++++++++++++++++++++++++- 3 files changed, 91 insertions(+), 2 deletions(-) diff --git a/doc/source/parallel.rst b/doc/source/parallel.rst index 4f245d910b..0751b36223 100644 --- a/doc/source/parallel.rst +++ b/doc/source/parallel.rst @@ -109,10 +109,24 @@ 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. Use ``jumped``, + whose step is not a power of two, instead. The ``advance`` method of each + generator describes the effect on its output functions. + .. _jumping: Jumping the PRNG state diff --git a/randomgen/pcg32.pyx b/randomgen/pcg32.pyx index 806056282a..3faf60b746 100644 --- a/randomgen/pcg32.pyx +++ b/randomgen/pcg32.pyx @@ -78,6 +78,10 @@ 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, use ``jumped`` rather than advancing by a large power of two such + as ``2**63``, which gives strongly related streams (see ``advance``). + **Compatibility Guarantee** ``PCG32`` makes a guarantee that a fixed seed and will always produce @@ -184,6 +188,20 @@ 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. + + ``jumped`` uses a step that is not a power of two. Since + ``jumped(iter)`` advances by ``iter`` times this step, ``iter`` + should not be a large power of two either. + Notes ----- Advancing a RNG updates the underlying RNG state as-if a given diff --git a/randomgen/pcg64.pyx b/randomgen/pcg64.pyx index 709bd560c3..35c0fcfba0 100644 --- a/randomgen/pcg64.pyx +++ b/randomgen/pcg64.pyx @@ -143,6 +143,10 @@ 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, use ``jumped`` rather than advancing 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 +363,28 @@ 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. + + ``jumped`` uses a step that is not a power of two. Since + ``jumped(iter)`` advances by ``iter`` times this step, ``iter`` + should not be a large power of two either. + Notes ----- Advancing a RNG updates the underlying RNG state as-if a given @@ -844,9 +870,36 @@ 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. + + ``jumped`` uses a step that is not a power of two. Since + ``jumped(iter)`` advances by ``iter`` times this step, ``iter`` + should not be a large power of two either. + Notes ----- Advancing a RNG updates the underlying RNG state as-if a given @@ -1017,6 +1070,10 @@ 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, use ``jumped`` rather than advancing 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", From 7748243181b78800d93f35fe72a1c215bdc0e1ca Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Wed, 4 Nov 2026 08:52:31 +0000 Subject: [PATCH 2/6] DOC: Recommend an odd golden-ratio step for splitting PCG streams Suggest advancing by multiples of the odd integer closest to 2**128 / phi (2**64 / phi for PCG32). With an odd step the states of two streams always differ in the lowest bit and, on average, in about half of their bits, while 2**127 changes one bit and 2**64 never changes the lowest 64 bits. Add an example to parallel.rst. Co-Authored-By: Claude Opus 5.5 --- doc/source/parallel.rst | 22 +++++++++++++++++++--- randomgen/pcg32.pyx | 19 ++++++++++++++----- randomgen/pcg64.pyx | 40 ++++++++++++++++++++++++++++++---------- 3 files changed, 63 insertions(+), 18 deletions(-) diff --git a/doc/source/parallel.rst b/doc/source/parallel.rst index 0751b36223..77a4fe99b3 100644 --- a/doc/source/parallel.rst +++ b/doc/source/parallel.rst @@ -123,9 +123,25 @@ does not support advancing a counter. :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. Use ``jumped``, - whose step is not a power of two, instead. The ``advance`` method of each - generator describes the effect on its output functions. + 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 by multiples of an odd step whose bits look random, so + that the states of the streams always differ in their lowest bit and, on + average, in about half of their bits. A good step is the odd integer + closest to :math:`2^{128}/\phi`, where :math:`\phi` is the golden ratio, + ``0x9e3779b97f4a7c15f39cc0605cedc835`` (``0x9e3779b97f4a7c15``, the odd + integer closest to :math:`2^{64}/\phi`, for + :class:`~randomgen.pcg32.PCG32`), and stream ``i`` uses + ``advance(i * step)``. ``jumped`` uses a similar golden-ratio step and is + also a good choice. + + .. code-block:: python + + from randomgen import PCG64 + + STEP = 0x9e3779b97f4a7c15f39cc0605cedc835 + streams = [PCG64(1234).advance(i * STEP) for i in range(16)] .. _jumping: diff --git a/randomgen/pcg32.pyx b/randomgen/pcg32.pyx index 3faf60b746..5748a5a598 100644 --- a/randomgen/pcg32.pyx +++ b/randomgen/pcg32.pyx @@ -79,8 +79,10 @@ cdef class PCG32(BitGenerator): ... rg[i].bit_generator.advance(i * 2**32) Each instance above uses a different increment ``inc``. To split a single - stream, use ``jumped`` rather than advancing by a large power of two such - as ``2**63``, which gives strongly related streams (see ``advance``). + stream, advance by multiples of an odd step such as + ``0x9e3779b97f4a7c15``, or use ``jumped``, rather than by a large power of + two such as ``2**63``, which gives strongly related streams (see + ``advance``). **Compatibility Guarantee** @@ -198,9 +200,16 @@ cdef class PCG32(BitGenerator): 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. - ``jumped`` uses a step that is not a power of two. Since - ``jumped(iter)`` advances by ``iter`` times this step, ``iter`` - should not be a large power of two either. + To split a stream, advance by multiples of an odd step whose bits + look random. The states of the two streams then always differ in + their lowest bit and, on average, in about 32 of their 64 bits. + After ``advance(2**63)`` they differ in a single bit, and after + ``advance(2**32)`` in about 16 bits, never in the lowest 32. A good + step is ``0x9e3779b97f4a7c15``, the odd integer closest to + ``2**64 / phi``, where phi is the golden ratio. Stream ``i`` then + uses ``advance(i * 0x9e3779b97f4a7c15)``. ``jumped(iter)`` advances + by ``iter`` times a similar golden-ratio step, so it is also a good + choice as long as ``iter`` is not a large power of two. Notes ----- diff --git a/randomgen/pcg64.pyx b/randomgen/pcg64.pyx index 35c0fcfba0..2d12c5fcf1 100644 --- a/randomgen/pcg64.pyx +++ b/randomgen/pcg64.pyx @@ -144,8 +144,10 @@ cdef class PCG64(BitGenerator): ... rg[i].bit_generator.advance(i * 2**64) Each instance above uses a different increment ``inc``. To split a single - stream, use ``jumped`` rather than advancing by a large power of two such - as ``2**127``, which gives strongly related streams (see ``advance``). + stream, advance by multiples of an odd step such as + ``0x9e3779b97f4a7c15f39cc0605cedc835``, or use ``jumped``, rather than by a + large power of two such as ``2**127``, which gives strongly related streams + (see ``advance``). References ---------- @@ -381,9 +383,17 @@ cdef class PCG64(BitGenerator): never congruent modulo 4, so their last hexadecimal digits never coincide, and PractRand fails the interleaved streams at 1 MB. - ``jumped`` uses a step that is not a power of two. Since - ``jumped(iter)`` advances by ``iter`` times this step, ``iter`` - should not be a large power of two either. + To split a stream, advance by multiples of an odd step whose bits + look random. The states of the two streams then always differ in + their lowest bit and, on average, in about 64 of their 128 bits. + After ``advance(2**127)`` they differ in a single bit, and after + ``advance(2**64)`` in about 32 bits, never in the lowest 64. A good + step is ``0x9e3779b97f4a7c15f39cc0605cedc835``, the odd integer + closest to ``2**128 / phi``, where phi is the golden ratio, which is + also the step of NumPy's ``PCG64.jumped``. Stream ``i`` then uses + ``advance(i * 0x9e3779b97f4a7c15f39cc0605cedc835)``. ``jumped(iter)`` + advances by ``iter`` times a similar golden-ratio step, so it is also + a good choice as long as ``iter`` is not a large power of two. Notes ----- @@ -896,9 +906,17 @@ cdef class LCG128Mix(BitGenerator): * ``"murmur3"``: no pattern is visible in the outputs, although the states are related in the same way. - ``jumped`` uses a step that is not a power of two. Since - ``jumped(iter)`` advances by ``iter`` times this step, ``iter`` - should not be a large power of two either. + To split a stream, advance by multiples of an odd step whose bits + look random. The states of the two streams then always differ in + their lowest bit and, on average, in about 64 of their 128 bits. + After ``advance(2**127)`` they differ in a single bit, and after + ``advance(2**64)`` in about 32 bits, never in the lowest 64. A good + step is ``0x9e3779b97f4a7c15f39cc0605cedc835``, the odd integer + closest to ``2**128 / phi``, where phi is the golden ratio, which is + also the step of NumPy's ``PCG64.jumped``. Stream ``i`` then uses + ``advance(i * 0x9e3779b97f4a7c15f39cc0605cedc835)``. ``jumped(iter)`` + advances by ``iter`` times a similar golden-ratio step, so it is also + a good choice as long as ``iter`` is not a large power of two. Notes ----- @@ -1071,8 +1089,10 @@ cdef class PCG64DXSM(PCG64): ... rg[i].bit_generator.advance(i * 2**64) Each instance above uses a different increment ``inc``. To split a single - stream, use ``jumped`` rather than advancing by a large power of two such - as ``2**127``, which gives strongly related streams (see ``advance``). + stream, advance by multiples of an odd step such as + ``0x9e3779b97f4a7c15f39cc0605cedc835``, or use ``jumped``, rather than by a + large power of two such as ``2**127``, which gives strongly related streams + (see ``advance``). References ---------- From e59cd6f763c279759996ee3bb565fddffdc639b1 Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Wed, 4 Nov 2026 10:44:48 +0000 Subject: [PATCH 3/6] DOC: Explain how to choose a step for splitting PCG streams Any odd step makes the states of two streams differ as if at random, apart from their lowest few bits, whatever its size: about half of the bits differ, with a binomial spread. The size only has to exceed the number of draws per stream, so that the streams do not overlap. Say so in the Notes of the PCG advance methods, give odd golden-ratio steps 2**XX / phi for smaller XX (48 and 64 for the 128-bit generators, 32 for PCG32), say how many low bits streams i and j share, and cite NumPy's 58-bit result for XSL-RR. Keep the Warnings to the problem itself, and use the 2**64 / phi step in the parallel.rst example. Co-Authored-By: Claude Opus 5.5 --- doc/source/parallel.rst | 21 +++++----- randomgen/pcg32.pyx | 40 +++++++++++++----- randomgen/pcg64.pyx | 93 +++++++++++++++++++++++++++++++---------- 3 files changed, 112 insertions(+), 42 deletions(-) diff --git a/doc/source/parallel.rst b/doc/source/parallel.rst index 77a4fe99b3..f332acaf94 100644 --- a/doc/source/parallel.rst +++ b/doc/source/parallel.rst @@ -126,21 +126,22 @@ does not support advancing a counter. 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 by multiples of an odd step whose bits look random, so - that the states of the streams always differ in their lowest bit and, on - average, in about half of their bits. A good step is the odd integer - closest to :math:`2^{128}/\phi`, where :math:`\phi` is the golden ratio, - ``0x9e3779b97f4a7c15f39cc0605cedc835`` (``0x9e3779b97f4a7c15``, the odd - integer closest to :math:`2^{64}/\phi`, for - :class:`~randomgen.pcg32.PCG32`), and stream ``i`` uses - ``advance(i * step)``. ``jumped`` uses a similar golden-ratio step and is - also a good choice. + 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, and the size of the step only has to be larger than + the number of draws that each stream makes, so that the streams do not + overlap. 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). ``jumped`` uses a golden-ratio step and is also a good choice. .. code-block:: python from randomgen import PCG64 - STEP = 0x9e3779b97f4a7c15f39cc0605cedc835 + STEP = 0x9e3779b97f4a7c15 streams = [PCG64(1234).advance(i * STEP) for i in range(16)] .. _jumping: diff --git a/randomgen/pcg32.pyx b/randomgen/pcg32.pyx index 5748a5a598..946497fc0e 100644 --- a/randomgen/pcg32.pyx +++ b/randomgen/pcg32.pyx @@ -200,16 +200,9 @@ cdef class PCG32(BitGenerator): 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. - To split a stream, advance by multiples of an odd step whose bits - look random. The states of the two streams then always differ in - their lowest bit and, on average, in about 32 of their 64 bits. - After ``advance(2**63)`` they differ in a single bit, and after - ``advance(2**32)`` in about 16 bits, never in the lowest 32. A good - step is ``0x9e3779b97f4a7c15``, the odd integer closest to - ``2**64 / phi``, where phi is the golden ratio. Stream ``i`` then - uses ``advance(i * 0x9e3779b97f4a7c15)``. ``jumped(iter)`` advances - by ``iter`` times a similar golden-ratio step, so it is also a good - choice as long as ``iter`` is not a large power of two. + After ``advance(2**32)``, the states differ in about 16 of their 64 + bits and never in the lowest 32. The Notes describe how to choose a + step that splits a stream safely. Notes ----- @@ -226,6 +219,33 @@ 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 larger than the number of draws that any stream makes. + + 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 larger + than the number of draws per stream. For example, ``XX = 32`` gives + ``0x9e3779b9``, about ``2.7 * 10**9`` draws per stream, and ``XX = 64`` + gives ``0x9e3779b97f4a7c15``. With ``XX = 64`` the multiples of the + step wrap around the period, and the golden ratio spreads the streams + evenly around it. + + >>> step = 0x9e3779b9 + >>> streams = [PCG32(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``. ``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: diff --git a/randomgen/pcg64.pyx b/randomgen/pcg64.pyx index 2d12c5fcf1..5a34160720 100644 --- a/randomgen/pcg64.pyx +++ b/randomgen/pcg64.pyx @@ -383,17 +383,9 @@ cdef class PCG64(BitGenerator): never congruent modulo 4, so their last hexadecimal digits never coincide, and PractRand fails the interleaved streams at 1 MB. - To split a stream, advance by multiples of an odd step whose bits - look random. The states of the two streams then always differ in - their lowest bit and, on average, in about 64 of their 128 bits. - After ``advance(2**127)`` they differ in a single bit, and after - ``advance(2**64)`` in about 32 bits, never in the lowest 64. A good - step is ``0x9e3779b97f4a7c15f39cc0605cedc835``, the odd integer - closest to ``2**128 / phi``, where phi is the golden ratio, which is - also the step of NumPy's ``PCG64.jumped``. Stream ``i`` then uses - ``advance(i * 0x9e3779b97f4a7c15f39cc0605cedc835)``. ``jumped(iter)`` - advances by ``iter`` times a similar golden-ratio step, so it is also - a good choice as long as ``iter`` is not a large power of two. + After ``advance(2**64)``, the states differ in about 32 of their 128 + bits and never in the lowest 64. The Notes describe how to choose a + step that splits a stream safely. Notes ----- @@ -413,6 +405,38 @@ 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 larger than the number of draws that any stream makes. + + 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 larger + than the number of draws per stream. 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 + 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 = 0x9e3779b97f4a7c15 + >>> 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) @@ -906,17 +930,9 @@ cdef class LCG128Mix(BitGenerator): * ``"murmur3"``: no pattern is visible in the outputs, although the states are related in the same way. - To split a stream, advance by multiples of an odd step whose bits - look random. The states of the two streams then always differ in - their lowest bit and, on average, in about 64 of their 128 bits. - After ``advance(2**127)`` they differ in a single bit, and after - ``advance(2**64)`` in about 32 bits, never in the lowest 64. A good - step is ``0x9e3779b97f4a7c15f39cc0605cedc835``, the odd integer - closest to ``2**128 / phi``, where phi is the golden ratio, which is - also the step of NumPy's ``PCG64.jumped``. Stream ``i`` then uses - ``advance(i * 0x9e3779b97f4a7c15f39cc0605cedc835)``. ``jumped(iter)`` - advances by ``iter`` times a similar golden-ratio step, so it is also - a good choice as long as ``iter`` is not a large power of two. + After ``advance(2**64)``, the states differ in about 32 of their 128 + bits and never in the lowest 64. The Notes describe how to choose a + step that splits a stream safely. Notes ----- @@ -936,6 +952,39 @@ 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 larger than the + number of draws that any stream makes. + + 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 larger + than the number of draws per stream. 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 + 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 = 0x9e3779b97f4a7c15 + >>> 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) From 056747f382b902b0c0486be6b00b11c0b260eacc Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Wed, 4 Nov 2026 13:23:40 +0000 Subject: [PATCH 4/6] ENH: Add advance_step to choose a step for splitting PCG streams PCG64, PCG64DXSM, LCG128Mix and PCG32 gain a static method advance_step(max_draws). It returns the odd integer closest to 2**XX / phi for the smallest XX with 2**XX / phi > max_draws, using only integer arithmetic: the integer part of 2**XX / phi is (isqrt(5 * 4**XX) - 2**XX) // 2. The step is never smaller than max_draws, so streams advanced by i * step do not overlap. The advance docstrings point to it from the Warnings, a See Also section and the Notes, whose examples now use it, and parallel.rst does the same. The method is listed on each generator's API page. Co-Authored-By: Claude Opus 5.5 --- doc/source/bit_generators/lcg128mix.rst | 1 + doc/source/bit_generators/pcg32.rst | 1 + doc/source/bit_generators/pcg64.rst | 1 + doc/source/bit_generators/pcg64dxsm.rst | 1 + doc/source/parallel.rst | 9 +- randomgen/common.pxd | 1 + randomgen/common.pyx | 30 +++++ randomgen/pcg32.pxd | 7 +- randomgen/pcg32.pyi | 2 + randomgen/pcg32.pyx | 83 ++++++++++-- randomgen/pcg64.pxd | 1 + randomgen/pcg64.pyi | 4 + randomgen/pcg64.pyx | 167 +++++++++++++++++++++--- randomgen/tests/test_direct.py | 77 +++++++++++ 14 files changed, 355 insertions(+), 30 deletions(-) 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/parallel.rst b/doc/source/parallel.rst index f332acaf94..6c08558e56 100644 --- a/doc/source/parallel.rst +++ b/doc/source/parallel.rst @@ -135,13 +135,18 @@ does not support advancing a counter. ``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). ``jumped`` uses a golden-ratio step and is also a good choice. + 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. .. code-block:: python from randomgen import PCG64 - STEP = 0x9e3779b97f4a7c15 + # 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: 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 946497fc0e..343f1ee900 100644 --- a/randomgen/pcg32.pyx +++ b/randomgen/pcg32.pyx @@ -201,8 +201,12 @@ cdef class PCG32(BitGenerator): 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 Notes describe how to choose a - step that splits a stream safely. + bits and never in the lowest 32. ``advance_step`` returns a step that + splits a stream safely, and the Notes explain how to choose one. + + See Also + -------- + advance_step : Step for splitting one stream into several. Notes ----- @@ -232,13 +236,17 @@ cdef class PCG32(BitGenerator): 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 larger - than the number of draws per stream. For example, ``XX = 32`` gives - ``0x9e3779b9``, about ``2.7 * 10**9`` draws per stream, and ``XX = 64`` - gives ``0x9e3779b97f4a7c15``. With ``XX = 64`` the multiples of the - step wrap around the period, and the golden ratio spreads the streams - evenly around it. - - >>> step = 0x9e3779b9 + than 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``. 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)] Streams ``i`` and ``j`` are ``(j - i) * step`` draws apart, so they @@ -252,6 +260,63 @@ cdef class PCG32(BitGenerator): 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. Streams ``0`` to ``n - 1`` do not overlap + when ``n * step <= 2**64``. The Notes of ``advance`` explain this + choice of step. + + 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 5a34160720..76329daa27 100644 --- a/randomgen/pcg64.pyx +++ b/randomgen/pcg64.pyx @@ -384,8 +384,12 @@ cdef class PCG64(BitGenerator): 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 Notes describe how to choose a - step that splits a stream safely. + bits and never in the lowest 64. ``advance_step`` returns a step that + splits a stream safely, and the Notes explain how to choose one. + + See Also + -------- + advance_step : Step for splitting one stream into several. Notes ----- @@ -418,15 +422,19 @@ cdef class PCG64(BitGenerator): 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 larger - than the number of draws per stream. 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 - NumPy's ``PCG64.jumped``. With ``XX = 128`` the multiples of the step - wrap around the period, and the golden ratio spreads the streams evenly + than 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 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 = 0x9e3779b97f4a7c15 + >>> 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 @@ -450,6 +458,63 @@ 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. Streams ``0`` to ``n - 1`` do not overlap + when ``n * step <= 2**128``. The Notes of ``advance`` explain this + choice of step. + + 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 @@ -931,8 +996,12 @@ cdef class LCG128Mix(BitGenerator): 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 Notes describe how to choose a - step that splits a stream safely. + bits and never in the lowest 64. ``advance_step`` returns a step that + splits a stream safely, and the Notes explain how to choose one. + + See Also + -------- + advance_step : Step for splitting one stream into several. Notes ----- @@ -966,15 +1035,19 @@ cdef class LCG128Mix(BitGenerator): 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 larger - than the number of draws per stream. 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 - NumPy's ``PCG64.jumped``. With ``XX = 128`` the multiples of the step - wrap around the period, and the golden ratio spreads the streams evenly + than 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 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 = 0x9e3779b97f4a7c15 + >>> 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 @@ -996,6 +1069,64 @@ 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. + Streams ``0`` to ``n - 1`` do not overlap when + ``n * step <= 2**128``. The Notes of ``advance`` explain this choice of + step. + + 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 diff --git a/randomgen/tests/test_direct.py b/randomgen/tests/test_direct.py index d4ed51195a..29a50eb037 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,82 @@ 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 + + +@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", "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): From 737f3c3bcb7acd7170559bcf8c875d7653dedc28 Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Wed, 4 Nov 2026 13:31:41 +0000 Subject: [PATCH 5/6] DOC: Add advance_step to the 2.6.0 release notes List advance_step under the new features, and mention it in the entry for the advance warnings (#450). With the odd jumped steps from #506 now merged, the advance Notes say that the XX = 128 step (XX = 64 for PCG32) is also the step of jumped, and a test checks that jumped(i) equals advance(i * step) for that step. Co-Authored-By: Claude Opus 5.5 --- doc/source/change-log.rst | 15 ++++++++++++++- randomgen/pcg32.pyx | 6 +++--- randomgen/pcg64.pyx | 12 ++++++------ randomgen/tests/test_direct.py | 13 +++++++++++++ 4 files changed, 36 insertions(+), 10 deletions(-) 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/randomgen/pcg32.pyx b/randomgen/pcg32.pyx index 31cc8b90e3..a8819a7cc6 100644 --- a/randomgen/pcg32.pyx +++ b/randomgen/pcg32.pyx @@ -240,9 +240,9 @@ cdef class PCG32(BitGenerator): 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``. With ``XX = 64`` the multiples of the step wrap - around the period, and the golden ratio spreads the streams evenly - around it. + ``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) diff --git a/randomgen/pcg64.pyx b/randomgen/pcg64.pyx index 7ef77b80d3..f0416b31cd 100644 --- a/randomgen/pcg64.pyx +++ b/randomgen/pcg64.pyx @@ -427,9 +427,9 @@ cdef class PCG64(BitGenerator): 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 NumPy's - ``PCG64.jumped``. With ``XX = 128`` the multiples of the step wrap - around the period, and the golden ratio spreads the streams evenly + ``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) @@ -1051,9 +1051,9 @@ cdef class LCG128Mix(BitGenerator): 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 NumPy's - ``PCG64.jumped``. With ``XX = 128`` the multiples of the step wrap - around the period, and the golden ratio spreads the streams evenly + ``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) diff --git a/randomgen/tests/test_direct.py b/randomgen/tests/test_direct.py index 29a50eb037..fc21d82d68 100644 --- a/randomgen/tests/test_direct.py +++ b/randomgen/tests/test_direct.py @@ -2475,6 +2475,19 @@ def test_advance_step_numpy_jumped(bg_cls): 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] From 338711e595b23f52a2b7fc40801e5f90e3d01d03 Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Wed, 4 Nov 2026 13:43:01 +0000 Subject: [PATCH 6/6] DOC: State the overlap limit on the number of PCG streams Streams advanced by i * step are only guaranteed not to overlap when n * step is at most the period. Every advance docstring now says so in its Warnings and Notes, with the requirement that the step be at least the number of draws per stream, and the advance_step Notes say that it does not check the limit because it does not know n. The period of PCG32 is only 2**64, so for PCG32 the docs of advance, advance_step and the class give the largest number of streams for 1e6 to 1e18 draws per stream, note that n streams of m draws fit when n * m <= 2**63, and recommend PCG64, PCG64DXSM or LCG128Mix when many streams or many draws per stream are needed. parallel.rst does the same. The class docs of PCG64, PCG64DXSM and PCG32 now point to advance_step for splitting a stream. Tests check the documented limits and that the step is less than 2 * max_draws. Co-Authored-By: Claude Opus 5.5 --- doc/source/parallel.rst | 14 ++++-- randomgen/pcg32.pyx | 90 +++++++++++++++++++++++++++++----- randomgen/pcg64.pyx | 83 +++++++++++++++++++++---------- randomgen/tests/test_direct.py | 15 ++++++ 4 files changed, 161 insertions(+), 41 deletions(-) diff --git a/doc/source/parallel.rst b/doc/source/parallel.rst index 6c08558e56..fdb32de720 100644 --- a/doc/source/parallel.rst +++ b/doc/source/parallel.rst @@ -128,9 +128,10 @@ does not support advancing a counter. 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, and the size of the step only has to be larger than - the number of draws that each stream makes, so that the streams do not - overlap. A convenient step is the odd integer closest to + 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`, @@ -141,6 +142,13 @@ does not support advancing a counter. 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 diff --git a/randomgen/pcg32.pyx b/randomgen/pcg32.pyx index a8819a7cc6..d73c7e9b29 100644 --- a/randomgen/pcg32.pyx +++ b/randomgen/pcg32.pyx @@ -79,10 +79,16 @@ cdef class PCG32(BitGenerator): ... rg[i].bit_generator.advance(i * 2**32) Each instance above uses a different increment ``inc``. To split a single - stream, advance by multiples of an odd step such as - ``0x9e3779b97f4a7c15``, or use ``jumped``, rather than by a large power of - two such as ``2**63``, which gives strongly related streams (see - ``advance``). + 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** @@ -201,8 +207,20 @@ cdef class PCG32(BitGenerator): 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. ``advance_step`` returns a step that - splits a stream safely, and the Notes explain how to choose one. + 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 -------- @@ -232,11 +250,14 @@ cdef class PCG32(BitGenerator): 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 larger than the number of draws that any stream makes. + ``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 larger - than the number of draws per stream. ``advance_step(max_draws)`` + 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 @@ -249,6 +270,29 @@ cdef class PCG32(BitGenerator): '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 @@ -300,9 +344,31 @@ cdef class PCG32(BitGenerator): 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. Streams ``0`` to ``n - 1`` do not overlap - when ``n * step <= 2**64``. The Notes of ``advance`` explain this - choice of step. + 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``. diff --git a/randomgen/pcg64.pyx b/randomgen/pcg64.pyx index f0416b31cd..fa4ef738df 100644 --- a/randomgen/pcg64.pyx +++ b/randomgen/pcg64.pyx @@ -144,10 +144,11 @@ cdef class PCG64(BitGenerator): ... rg[i].bit_generator.advance(i * 2**64) Each instance above uses a different increment ``inc``. To split a single - stream, advance by multiples of an odd step such as - ``0x9e3779b97f4a7c15f39cc0605cedc835``, or use ``jumped``, rather than by a - large power of two such as ``2**127``, which gives strongly related streams - (see ``advance``). + 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 ---------- @@ -384,8 +385,14 @@ cdef class PCG64(BitGenerator): 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. ``advance_step`` returns a step that - splits a stream safely, and the Notes explain how to choose one. + 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 -------- @@ -418,11 +425,15 @@ cdef class PCG64(BitGenerator): 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 larger than the number of draws that any stream makes. + ``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 larger - than the number of draws per stream. ``advance_step(max_draws)`` + 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 @@ -498,9 +509,14 @@ cdef class PCG64(BitGenerator): 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. Streams ``0`` to ``n - 1`` do not overlap - when ``n * step <= 2**128``. The Notes of ``advance`` explain this - choice of step. + 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``. @@ -1007,8 +1023,14 @@ cdef class LCG128Mix(BitGenerator): 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. ``advance_step`` returns a step that - splits a stream safely, and the Notes explain how to choose one. + 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 -------- @@ -1041,12 +1063,16 @@ cdef class LCG128Mix(BitGenerator): 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 larger than the - number of draws that any stream makes. + ``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 larger - than the number of draws per stream. ``advance_step(max_draws)`` + 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 @@ -1120,10 +1146,14 @@ cdef class LCG128Mix(BitGenerator): 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. - Streams ``0`` to ``n - 1`` do not overlap when - ``n * step <= 2**128``. The Notes of ``advance`` explain this choice of - step. + ``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``. @@ -1290,10 +1320,11 @@ cdef class PCG64DXSM(PCG64): ... rg[i].bit_generator.advance(i * 2**64) Each instance above uses a different increment ``inc``. To split a single - stream, advance by multiples of an odd step such as - ``0x9e3779b97f4a7c15f39cc0605cedc835``, or use ``jumped``, rather than by a - large power of two such as ``2**127``, which gives strongly related streams - (see ``advance``). + 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 ---------- diff --git a/randomgen/tests/test_direct.py b/randomgen/tests/test_direct.py index fc21d82d68..0e0966e4a7 100644 --- a/randomgen/tests/test_direct.py +++ b/randomgen/tests/test_direct.py @@ -2449,6 +2449,21 @@ def test_advance_step(bg_cls, bits): 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(