Docstrings

AbstractRNGStream is an abstraction for creating RNG objects with non-overlaping random numbers.

AbstractStreamableRNG is a special kind of RNG where one can move between different stream of number that are known to be non-overlapping.

MRG32k3a() will generate an instance of MRG32k3a with initial seeds DEFAULT_SEED = [ 12345, 12345, 12345, 12345, 12345, 12345 ]

MRG32k3a(x::Vector{Int}) will generate an instance of MRG32k3a with initial seeds x

MRG32k3a(x::Vector{Int}, y::Vector{Int}, z::Vector{Int}) will generate an instance of MRG32k3a with Cg = x, Bg = y and Ig = z

Examples

julia> rng = MRG32k3a();

julia> rand(rng)
0.12701112204657714

An object that generates independent random number streams.

Ensures a given seed is valid for MRG32k3a random number generator. Allocation-free.

LinRNG{N,S} <: AbstractStreamableRNG

Generic xoshiro/xoroshiro generator: state of N 64-bit words and scrambler S ∈ (:plus, :starstar, :plusplus). Holds three checkpoints — current state (Cg), substream start (Bg) and stream start (Ig) — enabling reset_stream!, reset_substream! and anchored jumps. Use the exported aliases (Xoroshiro128p, ..., Xoshiro512pp) instead.

Xoroshiro128p <: AbstractStreamableRNG

xoroshiro128+ (Blackman & Vigna): 128-bit state, period 2^128 - 1, output s0 + s1. Fastest small-state generator for floating-point use; the four lower bits have low linear complexity and it has a very mild Hamming-weight dependency after ~5 TB of output. Suitable only for mild parallelism (2^32 streams x 2^64 substreams).

Xoroshiro128ss <: AbstractStreamableRNG

xoroshiro128** (Blackman & Vigna): 128-bit state, period 2^128 - 1, all-purpose scrambler (rotl(s1*5,7)*9), 1-dimensionally equidistributed. Suitable only for mild parallelism (2^32 streams x 2^64 substreams).

Xoroshiro128pp <: AbstractStreamableRNG

xoroshiro128++ (Blackman & Vigna): 128-bit state, period 2^128 - 1, all-purpose scrambler (rotl(s0+s1,17)+s0). Same parallelism limits as the other 128-bit variants.

Xoshiro256p <: AbstractStreamableRNG

xoshiro256+ (Blackman & Vigna): 256-bit state, period 2^256 - 1, output s0 + s3. Slightly faster than **/++ when generating only floating-point numbers from the upper bits; avoid for raw 64-bit consumption.

Xoshiro256ss <: AbstractStreamableRNG

xoshiro256** (Blackman & Vigna): 256-bit state, period 2^256 - 1, all-purpose, 3-dimensionally equidistributed (default PRNG of Lua and .NET 6).

Xoshiro256pp <: AbstractStreamableRNG

xoshiro256++ (Blackman & Vigna): 256-bit state, period 2^256 - 1, all-purpose, 3-dimensionally equidistributed (default PRNG of Julia and Rust's SmallRng). The recommended general-purpose variant.

Examples

julia> rng = Xoshiro256pp(fill(UInt64(42), 4));

julia> rand(rng, UInt64)
0x000000002a00002a

Xoshiro512p <: AbstractStreamableRNG

xoshiro512+ (Blackman & Vigna): 512-bit state, period 2^512 - 1, output s0 + s2. Floating-point oriented; same caveats as Xoshiro256p.

Xoshiro512ss <: AbstractStreamableRNG

xoshiro512** (Blackman & Vigna): 512-bit state, period 2^512 - 1, all-purpose, 7-dimensionally equidistributed.

Xoshiro512pp <: AbstractStreamableRNG

xoshiro512++ (Blackman & Vigna): 512-bit state, period 2^512 - 1, all-purpose. Offers 2^256 substreams of 2^256 values — more than any application needs; prefer Xoshiro256pp unless you have a specific reason.

LinGen{N,S} <: AbstractRNGStream

Stream generator producing non-overlapping streams of LinRNG{N,S}: each call to next_stream! applies the family's long jump to the stored seed. Use the exported aliases (Xoroshiro128pGen, ..., Xoshiro512ppGen) instead.

Xoroshiro128pGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoroshiro128p streams via a long jump (2^96 values) per call. Seeds are 2 UInt64 words.

Xoroshiro128ssGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoroshiro128ss streams via a long jump (2^96 values) per call. Seeds are 2 UInt64 words.

Xoroshiro128ppGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoroshiro128pp streams via a long jump (2^96 values) per call. Seeds are 2 UInt64 words.

Xoshiro256plusGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoshiro256p streams via a long jump (2^192 values) per call. Seeds are 4 UInt64 words.

Xoshiro256ssGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoshiro256ss streams via a long jump (2^192 values) per call. Seeds are 4 UInt64 words.

Xoshiro256ppGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoshiro256pp streams via a long jump (2^192 values) per call. Seeds are 4 UInt64 words.

Xoshiro512pGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoshiro512p streams via a long jump (2^384 values) per call. Seeds are 8 UInt64 words.

Xoshiro512ssGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoshiro512ss streams via a long jump (2^384 values) per call. Seeds are 8 UInt64 words.

Xoshiro512ppGen <: AbstractRNGStream

Stream generator minting non-overlapping Xoshiro512pp streams via a long jump (2^384 values) per call. Seeds are 8 UInt64 words.

Produces a raw random number with 32 bits of precision.

Return a random Float64 in [0, 1).

Generates a Float32 from any xoshiro/xoroshiro generator.

Generates a Float16 from any xoshiro/xoroshiro generator.

Generates an Int64 uniformly distributed in the given range.

Hook required by Random's generic machinery for Float64-native generators: produces a Float64 in [1, 2). Everything else (ints, arrays, shuffle...) derives from this without further plumbing.

Jumps forward by 2^96 values (xoroshiro128), 2^128 (xoshiro256) or 2^256 (xoshiro512): the start of the next non-overlapping substream.

Jumps forward by 2^96 (xoroshiro128), 2^192 (xoshiro256) or 2^384 (xoshiro512) values: the start of the next independent stream.

Given a random number generator, jumps n steps forward if n > 0 (or -n steps backwards if n < 0), where

if e > 0, let n = 2^e + c; if e < 0, let n = -2^(-e) + c; if e = 0, let n = c.

Examples

julia> rng = MRG32k3a();

julia> advance_state!(rng, Int64(2), Int64(-1));   # skip n = 2^2 - 1 = 3 values

julia> rand(rng)
0.8258468629271136

Given a random number generator, jumps n steps forward if n > 0 (or -n steps backwards if n < 0), where

if e > 0, let n = 2^e + c; if e < 0, let n = -2^(-e) + c; if e = 0, let n = c.

The distance is reduced modulo the period (2^(64N) - 1), so any magnitude is accepted. Only the current position moves; the stream/substream boundaries (Bg, Ig) are left untouched. Costs O((64N)^2) GF(2) operations.

Seeds a generator with the first words of seed.

srand!(gen, seed::Vector{UInt64}) -> gen

Resets the seed that the next next_stream! call will use.

get_state return the seed used to generate non-overlaping MRGs

get_state(rng::LinRNG) -> Vector{UInt64}

Copy of the current state (Cg); restore it into a fresh generator via its three-argument constructor.

get_state(gen) -> Vector{UInt64}

Seed that will be used by the next next_stream! call.

Given an RNG generator object, returns the next RNG stream.

Given an RNG generator object, returns the next RNG stream.

Resets a given random number generator to the beginning of the current stream.

reset_stream!(rng) -> rng

Rewind the generator to the very beginning of its current stream (Cg = Bg = Ig).

Resets a given random number generator to the beginning of the current substream.

reset_substream!(rng) -> rng

Rewind the generator to the beginning of its current substream (Cg = Bg).

Takes a random number generator and shifts seed to next substream.

next_substream!(rng) -> rng

Move the generator to the start of the next substream (anchored jump from Bg): 2^64 values for xoroshiro128, 2^128 for xoshiro256, 2^256 for xoshiro512.