Change Log¶
v2.5.1¶
This release adds wheels for Windows on ARM64. It does not change the API or any random stream.
Added wheels for Windows on ARM64 for Python 3.11 to 3.15, including free-threaded 3.14t and 3.15t. Python 3.10 has no Windows ARM64 build, so it has no wheel.
Fixed compiling with MSVC for Windows on ARM64. The Random123 headers used by
PhiloxandThreeFryaccepted only x86, and the byte order was not detected, which stoppedAESCounter,DSFMTandSFMTfrom compiling. On ARM64,Philoxuses__umulhfor the high half of its 64-bit products.Windows on ARM64 is now tested on GitHub Actions.
v2.5.0¶
Note
The version number now follows NumPy’s, so there was no version 2.4.0.
Warning
Some streams differ from randomgen 2.3.0 for the same seed and calls. Most of these changes fix output that was wrong; see Changes to random streams before upgrading code that must reproduce earlier results.
New features¶
Added the scrambled multiply-with-carry generators
MWC192X,MWC128X,MWC128X32, andMWC64X32of Vigna. All supportadvance()andjumped(), which take time logarithmic in the number of steps or jumps, respectively, and accept negative values to move backward.Added support for free-threaded Python. The extensions are declared free-threading compatible, so importing randomgen does not re-enable the GIL. Every bit generator now holds its lock while it reads or sets its state, seeds, advances or jumps, so one bit generator can be shared between threads. The lock is now always a reentrant
threading.RLock.The SIMD switches
use_aesni(AESCounter),use_avx2(BlaBla),use_simd(ChaCha) anduse_sse41(SPECK128) now apply to a single instance. 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)toPCG64,PCG64DXSM,LCG128MixandPCG32(advance_step()). It returns a step for splitting one stream into several, where streamiis advanced byi * stepand makes at mostmax_drawsdraws. The step is the odd integer closest to \(2^{XX}/\phi\), where \(\phi\) is the golden ratio, for the smallest \(XX\) with \(2^{XX}/\phi\) larger thanmax_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 leastmax_draws,nstreams do not overlap as long asn * stepis no larger than the period.
Changes to random streams¶
These changes alter values that randomgen 2.3.0 produced for the same seed and calls.
jumpedinPCG64,PCG64DXSMandLCG128Mixnow jumps by the odd integer closest to \(2^{128}/\phi\), where \(\phi\) is the golden ratio, andPCG32by the odd integer closest to \(2^{64}/\phi\). The previous steps were even, sojumped(2**126)(jumped(2**63)forPCG32) returned the original state.jumpedofPCG64withnumpy_seed=Trueand ofPCG64DXSMnow matches NumPy (#398).advance()andadvance()now default tocounter=False, soadvance(delta)moves the stream bydeltadraws. This change has been announced by aFutureWarningsince randomgen 1.18. Passcounter=Trueto advance the counter, as the previous default did.Fixed
advance()andadvance(). Withnumber=2andcounter=False, advancing a newly seeded generator by an even number of draws did not move it. With any configuration, steps that reach the highest word of the counter, which include every negative step, lost that word.Fixed
wishart()withmethod"svd","eigh"or"cholesky"when the factor ofscaleis not symmetric, which includes every non-diagonalscale. The draws had the wrong distribution, with a mean different fromdf * scale. Rank-deficientscalewith"cholesky"is also fixed.Philoxwithnumpy_seed=Truenow usescounter, which was ignored, so it matchesnumpy.random.Philox.Fixed
weyl_increments(). The number of values with 30 to 35 non-zero bits overflowed, which includes the defaultmax_bits=32, so increments were drawn with the wrong probabilities whenmin_bits < max_bits. A draw at the end of the range could also return a value with the wrong number of bits, or loop forever.Setting the state of
Squaresnow restores the buffered 32-bit value (has_uint32anduinteger).Setting the state of
LCG128Mixnow updates all of its parameters (multiplier,dxsm_multiplier,postand the output function), which a laterseedused.multivariate_normal()andmultivariate_complex_normal()with a size containing 0 now draw nothing and return an empty array. Withsize=1they return shape(1, N), as NumPy does, instead of(N,).random_raw(size, output=False)now advances byprod(size)values. It used to advance bysum(size)whensizewas a tuple.
Stricter validation¶
These calls used to run, often with wrong results, and now raise.
Setting
statewith a different configuration, for example aPCG64state with anothervariantor aPhiloxstate with anothernumberorwidth, raisesValueError. Generators created from the bit generator kept using the old configuration. Create a new bit generator instead. Unpickling is not affected.Setting
statewith values out of range, such as a position or buffer index, the number of rounds, or an unknownPCG64variant, raisesValueErrorinstead of using them. So does aSquaresstate with an invalidkey.An unknown
methodinmultivariate_normal(),multivariate_complex_normal()orwishart()raisesValueError. It used to be treated as"cholesky".multivariate_complex_normal()does not accept"factor".complex_normal()validates scalar parameters as it does arrays, and asizesmaller than the broadcast shape of the parameters raises, as innumpy.random.Generator.normal(). It used to return a partly filled array.standard_wishart()raises whendfis not positive.An
incout of range inPCG32andPCG64raisesValueError, andPCG64withnumpy_seed=Truerejectsinc, which it used to ignore.UserBitGeneratorchecks that the functions it is given are callable.
Removals¶
Removed the in-place
jumpmethod, deprecated since 1.18, from every bit generator. Usejumped, which returns a new bit generator.Removed
BitGenerator.generator, which has only raisedNotImplementedErrorsince 1.18.Removed
randomgen.legacy, which could not be imported since the move to meson, themtrandstubs, and the internalrandomgen.compatmodule.
Other fixes¶
complex_normal()acceptsgammaandrelationarrays of different shapes that broadcast.wishart()accepts a list forscaleandsize.PCG64(None, inc=...)usesinc, which used to be replaced by a random increment.random_entropy()checks for errors on Windows, where it could return uninitialized memory, and retries short reads on other platforms.random_entropy(0)returns an empty array.RDRANDkeepsretriesinjumped, no longer reads past its buffer after a failure, and raises pending errors without printing them.generate_keys()and seedingSquaresare thread safe.64-bit values built from two 32-bit draws now use a defined order. The order matches what GCC, Clang and MSVC produced before.
A failed aligned allocation raises
MemoryErrorinstead of crashing, and HC-128 no longer relies on unaligned pointer casts.The
advancemethods of the PCG generators warn against splitting one stream with a large power of two, and explain how to choose an odd step, whichadvance_stepcomputes (#450).The documentation of
random(dtype=np.longdouble)explains why it gives different values across platforms.
Build and packaging¶
randomgen requires Python 3.10 or later and NumPy 1.26 or later. randomgen 2.3.0 supported Python 3.9 and NumPy 1.22.3.
Wheels are built for free-threaded Python 3.14 and 3.15. There are no wheels for free-threaded Python 3.13.
Building requires Cython 3.1 or later.
NumPy 2.4.0 is excluded: it renamed a class in a way that stops randomgen from importing. NumPy 2.4.1 restored the name.
Extensions are no longer all compiled with AVX2 (
-mavx2or/arch:AVX2). SIMD instructions are only enabled in the functions that check the CPU first, so importing randomgen no longer crashes on x86-64 CPUs without AVX2.The
disable-sse2build option now takes effect, and the newmwcx-force-portableoption forces the portable multiplication in the MWCX generators.Wheels no longer install the C sources, build helpers or examples, and the sdist no longer includes CI configuration or test results. The license is declared as
NCSA OR BSD-3-Clause, and the licenses of the included third-party code are part of the package metadata.The build no longer installs an empty
randomgen/compatdirectory, which also removes a meson deprecation warning (install_subdirwith an empty directory).The
test,docanddevextras are removed. The development dependencies are now dependency groups (PEP 735) inpyproject.toml, which replacerequirements.txt,requirements-dev.txtanddoc/requirements.txt. With pip 25.1 or later, install them with, for example,python -m pip install --group dev.The flake8, pep8speaks and Codecov configuration files are removed. flake8 no longer runs: ruff covers its pyflakes and flake8-pyi checks, and black’s formatting covers pycodestyle’s whitespace checks. The remaining tool configuration is in
pyproject.toml, including pytest’s native TOML configuration, which needs pytest 9.Tested on Python 3.10 to 3.15, including free-threaded 3.14 and 3.15.
v2.3.0¶
Added the
BlaBlaPRNG which is based on the Blake 2b hash function.BlaBlais a counter-based PRNG likeAESCounterand supports bothadvance()andjumped().Removed
modefrom bit generator initialization. This argument has been deprecated since release 2.0.0.
Warning
This change is backward incompatible. If mode is essential, you should continue to use legacy
versions.
Moved to the build system to meson which improves build time.
Fixed a breaking change that affected the use of
functools.partial()test suite in Python 3.14.
Note
There was no version 2.2.0.
v2.1.0¶
Fixed a bug in
LCG128Mixthat resulted inincnot being correctly set when initialized without a user-providedinc.Added the
TychePRNG of Neves and Araujo. Supports two variants. One is the original implementation in the 2012 paper. The second implementation matches the version inOpenRand.Added the
SquaresPRNG of Widynski. Supports two variants. The default uses 5 rounds of the middle square algorithm and outputs a 64-bit value. Ifvariant=32, then 4 rounds are used but only 32 bits returned.Added the helper function
generate_keys()forSquares. This function can be used to pre-generate keys for use withSquares.Refactored the broadcasting helper functions out of
randomgen.commontorandomgen.broadcast. Tests have been added and some edge case bugs have been found and fixed.Improve test coverage.
Additional code clean-up.
v2.0.0¶
Final compatibility with NumPy 2
Minimum NumPy is now 1.22.3.
Removed
"legacy"seeding in favor of usingSeedSequence.Removed the vendored copy of
SeedSequence.Deprecated using the
modekeyword argument to set the seed mode, since onlySeedSequencesare supported.Changed
randomgen.common.BitGeneratorto inherit fromnumpy.random.BitGeneratorso that numpy will recognize these asBitGenerators.Removed C distribution functions that are available in NumPy (see libnpyrandom)`.
General code cleanup and modernization.
v1.26.1¶
Initial compatibility with Cython 3 and NumPy 2
v1.26.0¶
Fixed a bug that affected the
randomgen.xoroshiro128.Xoroshiro128.jumped()method ofrandomgen.xoroshiro128.Xoroshiro128where the ** version was swapped with the standard version.Fixed a bug where
numpy.random.SeedSequencewas not copied when advancing generators usingjumped.Small compatibility fixes for change in NumPy.
Changes the documentation theme to sphinx-immaterial.
Added builds for Python 3.11.
Increased the minimum Python to 3.8.
v1.23.1¶
Registered the bit generators included in
randomgenwith NumPy so that NumPyGeneratorinstances can be pickled and unpickled when using arandomstatebit generator.Changed the canonical name of the bit generators to be their fully qualified name. For example,
PCG64is not named"randomgen.pcg64.PCG64"instead of"PCG64". This was done to avoid ambiguity with NumPy’s supplied bit generators with the same name.
v1.23.0¶
Removed
GeneratorandRandomState.
v1.20.2¶
Fixed a bug in
SFC64the used the wrong value from the Weyl sequence. In the original implementation, the current value is added to the next random integer and then incremented. The buggy version was incrementing then adding, and so was shifted by one value. This sequence should be similarly random in appearance, but it does not match the original specification and so has been changed.Added
mode="numpy"support toPCG64,MT19937,Philox, andSFC64. When using this mode, the sequence generated is guaranteed to match the sequence produced using the NumPy implementations as long as arandomgen.seed_sequence.SeedSequenceornumpy.random.SeedSequenceis used with the same initial seed values.Added
random()with support fordtype="longdouble"to produce extended precision random floats.
In [1]: import numpy as np
In [2]: from randomgen import ExtendedGenerator, PCG64
In [3]: eg = ExtendedGenerator(PCG64(20210501))
In [4]: eg.random(5, dtype=np.longdouble)
Out[4]:
array([0.66851489, 0.01769784, 0.87316102, 0.86532386, 0.85384162],
dtype=float128)
v1.20.1¶
Fixed a bug that affects
standard_gammawhen used withoutand a Fortran contiguous array.Added
standard_wishart()andwishart()variate generators.
v1.20.0¶
Sync upstream changes from NumPy
Added typing information
Fixed a bug in
AESCounterthat prevented a small number of counter values from being directly set.
v1.19.3¶
Future proofed setup against
setuptoolsanddistutilschanges.Enhanced documentation for
RDRAND.
v1.19.2¶
Corrected
RDRANDto retry on failures with pause between retries. Add a parameterretrywhich allows the number of retries to be set. It defaults to the Intel recommended value of 10. Also sets an exception when the number of retries has been exhausted (very unlikely). See theRDRANDdocstring with unique considerations when usingRDRANDthat do not occur with deterministic PRNGs.
v1.19.1¶
Added
randomgen.romu.Romuwhich is among the fastest available bit generators.Added
weyl_increments()to simplify generating increments for use in parallel applications ofSFC64.Completed * Quality Assurance of all bit generators to at least 4TB.
v1.19.0¶
Tested all bit generators out to at least 1TB using PractRand.
Added
randomgen.pcg64.PCG64DXSMwhich is an alias forrandomgen.pcg64.PCG64withvariant="dxsm"andmode="sequence". This is the 2.0 version of PCG64 and will likely become the default bit generator in NumPy in the near future.Added
randomgen.efiix64.EFIIX64which is both fast and high-quality.Added
randomgen.sfc.SFC64which supports generating streams using distinct Weyl constants.Added a
randomgen.pcg64.LCG128Mixwhich supports setting the LCG multiplier, changing the output function (including support for user-defined output functions) and pre- or post-state update generation.Added a
randomgen.lxm.LXMwhich generates variates using a mix of two simple, but flawed generators: an Xorshift and a 64-bit LCG. This has been proposed for including in in Java.Added a
randomgen.wrapper.UserBitGeneratorwhich allows bit generators to be written in Python or numba.Added
randomgen.generator.ExtendedGeneratorwhich contains features not innumpy.random.Generator.Added support for the
dxsmanddxsm-128variants ofrandomgen.pcg64.PCG64. Thedxsmvariant is the official PCG 2.0 generator.Added support for broadcasting inputs in
randomgen.generator.ExtendedGenerator.multivariate_normal.Added support for the ++ variant of
randomgen.xoroshiro128.Xoroshiro128.Fixed a bug the produced incorrect results in
jumped().Fixed multiple bugs in
Generatorthat were fixed innumpy.random.Generator.
v1.18.0¶
choicepulled in upstream performance improvement that use a hash set when choosing without replacement and without user-provided probabilities.Added support for
randomgen.seed_sequence.SeedSequence(and NumPy’sSeedSequence).Fixed a bug that affected both
randomgen.generator.Generator.randintinGeneratorandrandintinRandomStatewhenhigh=2**32. This value is inbounds for a 32-bit unsigned closed interval generator, and so should have been redirected to a 32-bit generator. It was erroneously sent to the 64-bit path. The random values produced are fully random but inefficient. This fix breaks the stream inrandomgen.generator.Generatoris the value forhighis used. The fix restoresRandomStateto NumPy 1.16 compatibility. only affects the output ifdtypeis'int64'This release brings many breaking changes. Most of these have been implemented using
DeprecationWarnings. This has been done to bringrandomgenin-line with the API changes of the version going into NumPy.Two changes that are more abrupt are:
The
.generatormethod of the bit generators raiseNotImplementedErrorThe internal structures that is used in C have been renamed. The main rename is
brng_ttobitgen_t
The other key changes are:
Rename
RandomGeneratortoGenerator.Rename
randinttointegers.Rename
random_integerstointegers.Rename
random_sampletorandom.Change
jumpwhich operated in-place tojumped()which returns a newBitGenerator.Rename Basic RNG to bit generator, which has been consistently applied across the docs and references
Add the integer-based SIMD-based Fast Mersenne Twister (SFMT) generator
SFMT.Add the 64-bit Mersenne Twister (MT64) generator
MT64.Renamed Xoshiro256StarStar to
Xoshiro256and Xoshiro512StarStar toXoshiro512
v1.17.0¶
This release was skipped
v1.16.6¶
Changed the default jump step size to phi times the period of the generator for
PCG32andPCG64.Improved the performance of
PCG64on Windows.Improved performance of
jump()andjumped().Improves backward compatibility of
RandomState
v1.16.5¶
Fixed bugs in
laplace,gumbel,logseries,normal,standard_normal,standard_exponential,exponential, andlogisticthat could result innanvalues in rare circumstances (about 1 in \(10^{53}\) draws).Added keyword
closedtorandintwhich changes sampling from the half-open interval[low, high)to the closed interval[low, high].Fixed a bug in
random_integersthat could lead to valid values being treated as invalid.
v1.16.4¶
Add a fast path for broadcasting
randintwhen usinguint64orint64.Refactor PCG64 so that it does not rely on Cython conditional compilation.
Add
brngto access the basic RNG.Allow multidimensional arrays in
choice.Speed-up
choicewhen not replacing. The gains can be very large (1000x or more) when the input array is large but the sample size is small.Add parameter checks in
multinomial.Fix an edge-case bug in
zipf.Allow 0 for sample in
hypergeometric.Add broadcasting to
multinomial(see NumPy issue 9710)
v1.16.3¶
Release fixing Python 2.7 issues
v1.16.2¶
Updated Xoroshiro120 to use Author’s latest parametrization
Closely synchronized with the version of randomgen being integrated into NumPy, including removing:
random_raw, which have been moved to the individual bit generatorsrandom_uintegers, which can be replaced withrandint.
Added
RandomStateas a clone of NumPy’s RandomState.Removed
LegacyGeneratorsince this is no longer neededFixed many small bugs, including in cffi and ctype interfaces
v1.16.1¶
Synchronized with upstream changes.
Fixed a bug in gamma generation if the shape parameters is 0.0.
v1.16.0¶
Fixed a bug that affected
DSFMTwhen callingjump()orseed()that failed to reset the buffer. This resulted in up to 381 values from the previous state being used before the buffer was refilled at the new state.Fixed bugs in
Xoshiro512andXorshift1024where the fallback entropy initialization used too few bytes. This bug is unlikely to be encountered since this path is only encountered if the system random number generator fails.Synchronized with upstream changes.
v1.15.1¶
Added Xoshiro256** and Xoshiro512**, the preferred generators of this class.
Fixed bug in jump method of Random123 generators which did not specify a default value.
Added support for generating bounded uniform integers using Lemire’s method.
Synchronized with upstream changes, which requires moving the minimum supported NumPy to 1.13.
v1.15¶
Synced empty choice changes
Synced upstream docstring changes
Synced upstream changes in permutation
Synced upstream doc fixes
Added absolute_import to avoid import noise on Python 2.7
Add legacy generator which allows NumPy replication
Improve type handling of integers
Switch to array-fillers for 0 parameter distribution to improve performance
Small changes to build on manylinux
Build wheels using multibuild