[vigna]

This PR adds a warning to the documentation of the generators: for linear congruential generators with a power-of-two modulus, such as rand48, discard() by a power of two yields strongly correlated streams. Since discard() is logarithmic, it is natural to use it to split the period into subsequences, and 2^47 (half the period of rand48) is a natural choice. However, these are the first outputs of a default-constructed rand48 and of a copy after discard(UINT64_C(1) << 47):

0x055424a4  0x455424a4
0x3a2ccef5  0x7a2ccef5
0x6adb4a65  0x2adb4a65
0x2b019719  0x6b019719
0x4861f4ef  0x0861f4ef
0x0039e5ef  0x4039e5ef
0x1802eeec  0x5802eeec
0x7ec68b3f  0x3ec68b3f

The two streams differ only in the top bit, at every step. This happens because, modulo 2^48, bit j of the state has period 2^(j+1), so a jump by 2^e leaves the lowest e bits of the state unchanged; as rand48 returns bits 17 to 47 of the state, discard() by 2^(17+t) leaves the lowest t bits of the outputs of the two streams identical. In the case of 2^47, the two states differ by 2^47 at every step, that is, only in their top bit.

The other linear congruential generators of the library (minstd_rand0, minstd_rand, and those of ecuyer1988) are multiplicative generators with a prime modulus, and are not affected.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.80%. Comparing base (459f9c2) to head (874b736).
⚠️ Report is 3 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #173   +/-   ##
========================================
  Coverage    95.80%   95.80%           
========================================
  Files          118      118           
  Lines         7653     7653           
========================================
  Hits          7332     7332           
  Misses         321      321           

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 459f9c2...874b736. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.