Repository navigation
ENH/DOC: Add advance_step and warn against splitting PCG streams by powers of two - #505
Merged
Merged
Conversation
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #505 +/- ##
==========================================
+ Coverage 94.76% 94.81% +0.04%
==========================================
Files 56 56
Lines 9837 9923 +86
Branches 206 214 +8
==========================================
+ Hits 9322 9408 +86
Misses 495 495
Partials 20 20
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
bashtage
marked this pull request as ready for review
November 4, 2026 10:37
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…owers-of-two Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes #450
Documents the problem Sebastiano Vigna reported in #450. Splitting a single PCG stream with
advanceby a large power of two gives strongly related streams. Also addsadvance_step(max_draws), which returns a safe step for splitting a stream.An LCG modulo
2**128(or2**64forPCG32) has lowestebits that repeat every2**esteps, so advancing by2**eleaves those bits unchanged. Afteradvance(2**127), the two states differ only in the top bit at every step.Changes
advance_step(max_draws)onPCG64(inherited byPCG64DXSM),LCG128MixandPCG32:2**XX / phifor the smallestXXwith2**XX / phi > max_draws. For example,PCG64.advance_step(10**10)is0x278dde6e5(XX = 34).2**XX / phiis(isqrt(5 * 4**XX) - 2**XX) // 2, which is exact becausesqrt(5) * 2**XXis irrational.XXis eithermax_draws.bit_length()or one more, so at most twoisqrtcalls are needed.max_draws, so streams advanced byi * stepdon't overlap whilen * step <= 2**128(2**64forPCG32).max_drawsmust be between 1 and the integer part of2**128 / phi(2**64 / phiforPCG32), or aValueErroris raised. Non-integers raiseTypeError. NumPy integers are accepted.cdeffunction,golden_advance_step, incommon.pyx. Type stubs are updated... versionadded:: 2.6.0.advancedocstring points to it three times: in the Warnings box, in a new See Also section, and in the Notes, whose example now uses it. It is listed under "Parallel generation" on the API pages of all four generators, andparallel.rstmentions it and uses it in its example.Streams advanced by
i * stepare only guaranteed not to overlap whenn * stepis at most the period, because the startsi * stepare taken modulo the period.Every
advancedocstring states this limit in its Warnings box and in its Notes, together with the rule that the step must be at least the number of draws per stream.The
advance_stepNotes say it does not check the limit, because it doesn't known. I left it that way on purpose: there is nonum_streamsargument.For
PCG64,PCG64DXSMandLCG128Mixthe docs note that the limit is not practical: about2.5e26streams of10**12draws.PCG32's period is only2**64, so thePCG32.advanceandPCG32.advance_stepNotes include a table of the largest number of streams. A summary appears in its Warnings box and class docstring, and inparallel.rst.10**61.4e1310**91.4e1010**121.4e710**1510**18They also give the simpler rule that
nstreams ofmdraws always fit whenn * m <= 2**63, because the step is less than2 * max_draws. They recommendPCG64,PCG64DXSMorLCG128Mixwhen many streams or many draws per stream are needed.The "Parallel Features" sections of the
PCG64,PCG64DXSMandPCG32class docstrings now point toadvance_stepfor splitting a stream. They previously named a fixed step.change-log.rst, 2.6.0):advance_stepis listed under "New features".advancewarnings (advance() by large powers of two yields correlated streams #450) mentions it.jumpedsteps (BUG: Use odd golden-ratio steps in the PCG jumped methods #506), is merged into this branch.advanceNotes now say that theXX = 128step (XX = 64forPCG32) is also randomgen's ownjumpedstep. A test checks thatjumped(i)equalsadvance(i * advance_step(2**127))(2**63forPCG32).PCG64.advance(whichPCG64DXSMinherits),LCG128Mix.advanceandPCG32.advanceget a numpydoc "Warnings" section. Napoleon renders it as a warning box. Each one says what happens to that generator's output functions:"xsl-rr": the 32-bit halves are swapped and one bit is flipped. More generally,2**(128 - t)gives rotations with at mosttbits flipped."dxsm","dxsm-128"andPCG64DXSM: the outputs are never congruent modulo 4, and PractRand fails the interleaved streams at 1 MB.LCG128Mix:"upper": identical except for the top bit. In general, the low64 - tbits are shared."lower": identical, as after any advance by a multiple of2**64."murmur3": no visible pattern.PCG32with2**63: the 16-bit halves are swapped and one bit is flipped.advance(2**64)(2**32forPCG32) and points to the Notes.ibyi * stepwith an oddstep.Any odd step makes the states of two streams differ as if at random, whatever its size, apart from the lowest few bits, which repeat every few steps in any LCG. About half the bits differ, with a binomial spread.
The size of the step only has to exceed the number of draws per stream, so that stream
idoesn't run into streami + 1.A convenient step is the odd integer closest to
2**XX / phi, withXXchosen to fit the draws per stream. The examples given:XX = 48:0x9e3779b97f4b, about1.7e14draws per stream.XX = 64:0x9e3779b97f4a7c15, about1.1e19.XX = 128: NumPy'sPCG64.jumpedstep.XX = 32forPCG32:0x9e3779b9, about2.7e9.Each has a short
advance(i * step)example.Streams
iandjshare the lowestvstate bits, where2**vis the largest power of two dividingj - i. With fewer than2**20streams that is at most 19 bits. NumPy's "Upgrading PCG64 with PCG64DXSM" page reports that XSL-RR streams sharing their lowest 58 bits (and the increment) fail PractRand when interleaved.jumped(iter)multiplies its golden-ratio step byiter, soitershould not be a large power of two.PCG64,PCG64DXSMandPCG32now say that each instance uses its owninc, and that a single stream should be split withjumped(seeadvance).doc/source/parallel.rst, the advancing section gets a short warning with the recommended step and an example, and now listsPCG64DXSMamong the PCG generators that supportadvance.LCG128Mix.advancedocstring, which saidPCG64.Checked
xsl-rr,upper,lowerandPCG32: checked directly. Forupperandxsl-rr, the general2**(128 - t)statements were checked for severalt.dxsm: no draw was congruent modulo 4 to its partner in 100,000 draws.2**XX / phiforXX= 16, 24, 32, 40, 48, 56, 64, 96 and 128 (8 to 64 forPCG32), and odd steps 1, 3 and 999.PCG32), as for random flips.2**127gives 1 differing bit.2**64gives 32, and the lowest 64 never differ.2**32gives 48, and the lowest 32 never differ.jumpedstep (...834) shares its lowest 2 bits.jumped, whose golden-ratio step "spreads out the states around the period optimally", and the need not to reuse jump indices.PCG64.advancehas no warning about step sizes.advance(2**N)leaves the lowestNbits identical, and gives the 58-bit PractRand result quoted above.advance_step:XXboundary (the integer part of2**XX / phi, and one either side) and powers of two, for 64 and 128 bits.test_direct.py:advance_step(2**127)is NumPy'sPCG64.jumpedstep.advance_step(1000)match consecutive 1000-draw blocks of one stream, so they don't overlap.2 * max_draws. Separately, 200,000 randommax_drawsvalues gave a largest ratio of 1.99999.2**64 // step(2**128 // stepfor the 128-bit generators).advanceandadvance_stepdocstrings go through Napoleon and docutils, eachadvanceproducing one warning box. All 28 docstring examples pass underdoctest, including thehex(step)outputs.parallel.rstparses cleanly and its example runs.parallel.rstandchange-log.rstproduces eachadvance_steppage.PCG64DXSM's inherited docstrings included.parallel.rstand change-log links resolve.PCG32pages render the stream table, and their links toPCG64,PCG64DXSMandLCG128Mixresolve.advanceare the existingdelta : integer, positivetype warnings, plus change-log references to pages this minimal build leaves out.🤖 Generated with Claude Code