Repository files navigation

This package intends to provide a simple RNG withstable streams, suitablefor tests in packages which need reproducible streams of random numbersacross Julia versions. Indeed, the Julia RNGs provided by default aredocumentedto have non-stable streams (which for example enables some performanceimprovements).

TheStableRNG type provided by this package strivesfor stability, but if bugs which require breaking this promise are found,a new major version will be released with the fix.

StableRNG is currently an alias forLehmerRNG, and implements a well understoodlinear congruential generator (LCG); an LCG is not state of the art,but is fast and is believed to have reasonably good statistical properties [1],suitable at least for tests of a wide range of packages.The choice of this particular RNG is based on its simplicity, which limitsthe chances for bugs.Note that onlyStableRNG is exported from the package, and should be the onlytype used in client code;LehmerRNG might be renamed, or might be made a distincttype fromStableRNG in any upcomingminor (i.e. non-breaking) release.

Currently, this RNG requires explicit seeding (in the constructoror viaRandom.seed!), i.e. no random seed will be chosen for the useras is the case in e.g.MersenneTwister().

The stable (guaranteed) API is

• construction:rng = StableRNG(seed::Integer) (in particular the aliasLehmerRNG is currentlynot part of the API)
• seeding:Random.seed!(rng::StableRNG, seed::Integer)(with0 <= seed <= typemax(UInt64))
• rand(rng, X) whereX is any of the standard bitInteger types(Bool,Int8,Int16,Int32,Int64,Int128,UInt8,UInt16,UInt32,UInt64,UInt128)
• rand(rng, X),randn(rng, X),randexp(rng, X) whereX is a standardbitAbstractFloat types (Float16,Float32,Float64)
• array versions for these types, includingthe mutating methodsrand!,randn! andrandexp!
• rand(rng, ::AbstractArray) (e.g.rand(rng, 1:9)); the streams are the sameon 32-bits and 64-bits architectures
• shuffle(rng, ::AbstractArray) andshuffle!(rng, ::AbstractArray)

Note that the generated streams of numbers for scalars and arrays are the same,i.e.rand(rng, X, n) is equal to[rand(rng, X) for _=1:n] for a givenrngstate.

Please open an issue for missing needed APIs.

[1]LehmerRNG is implemented after the specific constants published byMelissa E. O'Neill in thisC++ implementation,and passes the Big Crush test (thanks to Kristoffer Carlsson for running it).See also for example thisblog post.

In your tests, simply initialize an RNG with a given seed, and useit instead of the default provided one, e.g.

rng=StableRNG(123)A=randn(rng,10,10)# instead of randn(10, 10)@testinv(inv(A))≈ A