Report a bug

If you spot a problem with this page, click here to create a Github issue.

Improve this page

Quickly fork, edit online, and submit a pull request for this page.
Requires a signed-in GitHub account. This works well for small changes.
If you'd like to make larger changes you may want to consider using
a local clone.

# mir.random.engine.xorshift

Generator name | Description |
---|---|

Xoshiro256StarStar | xoshiro256*: all-purpose, rock-solid generator |

Xoroshiro128Plus | xoroshiro128+: fast, small, and high-quality |

Xorshift1024StarPhi | xorshift1024*φ: when something larger than xoroshiro128+ is needed |

Xorshift64Star32 | xorshift64*/32: internal state of 64 bits and output of 32 bits |

Xorshift32 .. Xorshift160 | Basic `xorshift` generator with n bits of state (32, 64, 96, 128, 160) |

Xorshift192 | Generator from Marsaglia's paper combining 160-bit `xorshift` with a counter |

Xorshift | An alias to one of the generators in this package |

Template name | Description |
---|---|

XorshiftStarEngine | `xorshift` * generator with any word size and any number of bits of state. |

XorshiftEngine | `xorshift` generator with any word size and any number of bits of state. |

License:

Authors:

Masahiro Nakagawa, Ilya Yaroshenko (rework), Nathan Sashihara

- struct
`XorshiftEngine`

(UIntType, uint bits, int sa, int sb, int sc) if (isUnsigned!UIntType); - Xorshift generator. Implemented according to Xorshift RNGs (Marsaglia, 2003) with Sebastino Vigna's optimization for large arrays.Period is 2 ^^ bits - 1 except for a legacy 192-bit uint version (see note below).Parameters:
UIntType Word size of this xorshift generator and the return type of opCall. bits The number of bits of state of this generator. This must be a positive multiple of the size in bits of UIntType. If bits is large this struct may occupy slightly more memory than this so it can use a circular counter instead of shifting the entire array. sa The direction and magnitude of the 1st shift. Positive means left, negative means right. sb The direction and magnitude of the 2nd shift. Positive means left, negative means right. sc The direction and magnitude of the 3rd shift. Positive means left, negative means right. Note: For historical compatibility when bits == 192 and UIntType is uint a legacy hybrid PRNG is used consisting of a 160-bit xorshift combined with a 32-bit counter. This combined generator has period equal to the least common multiple of 2 ^^ 160 - 1 and 2 ^^ 32.

- enum auto
`isRandomEngine`

; - Marker for mir.random.
`isRandomEngine`

- enum UIntType
`max`

; - Largest generated value.
- pure nothrow @nogc @safe this()(UIntType
`x0`

)

if (UIntType.sizeof > (uint).sizeof);

pure nothrow @nogc @safe this()(uint`x0`

)

if (UIntType.sizeof <= (uint).sizeof); - Constructs a XorshiftEngine generator seeded with
`x0`

. - pure nothrow @nogc @safe UIntType
`opCall`

(); - Advances the random sequence.

- alias
`Xorshift32`

= XorshiftEngine!(uint, 32u, 13, -17, 15).XorshiftEngine;

alias`Xorshift64`

= XorshiftEngine!(uint, 64u, 10, -13, -10).XorshiftEngine;

alias`Xorshift96`

= XorshiftEngine!(uint, 96u, 10, -5, -26).XorshiftEngine;

alias`Xorshift128`

= XorshiftEngine!(uint, 128u, 11, -8, -19).XorshiftEngine;

alias`Xorshift160`

= XorshiftEngine!(uint, 160u, 2, -1, -4).XorshiftEngine;

alias`Xorshift192`

= XorshiftEngine!(uint, 192u, -2, 1, 4).XorshiftEngine;

alias`Xorshift`

= XorshiftEngine!(uint, 128u, 11, -8, -19).XorshiftEngine; - Define XorshiftEngine generators with well-chosen parameters for 32-bit architectures.
`Xorshift`

is an alias of one of the generators in this module.Examples:import mir.random.engine; auto rnd = Xorshift(cast(uint)unpredictableSeed); auto num = rnd(); import std.traits; static assert(is(ReturnType!rnd == uint)); static assert(isSaturatedRandomEngine!Xorshift);

- struct
`XorshiftStarEngine`

(StateUInt, uint nbits, int sa, int sb, int sc, StateUInt multiplier, OutputUInt = StateUInt) if (isUnsigned!StateUInt && isUnsigned!OutputUInt && OutputUInt.sizeof <= StateUInt.sizeof && !(sa > 0 && sb > 0 && sc > 0));

template`XorshiftStarEngine`

(StateUInt, uint nbits, int sa, int sb, int sc, StateUInt multiplier, OutputUInt = StateUInt) if (isUnsigned!StateUInt && isUnsigned!OutputUInt && OutputUInt.sizeof <= StateUInt.sizeof && (sa > 0 && sb > 0 && sc > 0)) - Template for the xorshift* family of generators (Vigna, 2016; draft 2014).
xorshift* generators are very fast, high-quality PRNGs (pseudorandom number generators) obtained by scrambling the output of a Marsaglia xorshift generator with a 64-bit invertible multiplier (as suggested by Marsaglia in his paper). They are an excellent choice for all non-cryptographic applications, as they are incredibly fast, have long periods and their output passes strong statistical test suites.

Parameters:StateUInt Word size of this xorshift generator. nbits The number of bits of state of this generator. This must be a positive multiple of the size in bits of UIntType. If nbits is large this struct may occupy slightly more memory than this so it can use a circular counter instead of shifting the entire array. sa The direction and magnitude of the 1st shift. Positive means left, negative means right. sb The direction and magnitude of the 2nd shift. Positive means left, negative means right. sc The direction and magnitude of the 3rd shift. Positive means left, negative means right. multiplier Output of the internal xorshift engine is multiplied by a constant to eliminate linear artifacts except in the low-order bits. This constant must be an odd number other than 1. OutputUInt Return type of opCall. By default same as StateUInt but can be set to a narrower unsigned type in which case the high bits of the multiplication result are returned. Note: If sa, sb, and sc are all positive (which if interpreted as same-direction shifts could not result in a full-period xorshift generator) the shift directions are instead implicitly right-left-right when bits == UIntType.sizeof * 8 and in all other cases left-right-right. This maintains full compatibility with older versions of

`XorshiftStarEngine`

that took all shifts as unsigned magnitudes.- enum auto
`isRandomEngine`

; - Marker for mir.random.
`isRandomEngine`

- enum OutputUInt
`max`

; - Largest generated value.
- enum bool
`preferHighBits`

; - Note that when StateUInt is the same size as OutputUInt the two lowest bits of this generator are LFSRs, and thus will fail binary rank tests. To provide some context,
*every*bit of a Mersenne Twister generator (either the 32-bit or 64-bit variant) is an LFSR.The rand!T functions in mir.random automatically will discard the low bits when generating output smaller than OutputUInt due to this generator having`preferHighBits`

defined true. - pure nothrow @nogc @safe this()(StateUInt
`x0`

); - Constructs a XorshiftStarEngine generator seeded with
`x0`

. - pure nothrow @nogc @safe OutputUInt
`opCall`

()(); - Advances the random sequence.
- pure nothrow @nogc @safe void
`jump`

()()

if (nbits == 1024 && N == 16 && sa == 31 && sb == -11 && sc == -30); - This is the
`jump`

function for the standard 1024-bit generator. It is equivalent to 2 ^^ 512 invocations of opCall(); it can be used to generate 2 ^^ 512 non-overlapping subsequences for parallel computations. This function will only be defined if the shifts are the same as for Xorshift1024StarPhi.

- alias
`Xorshift1024StarPhi`

= XorshiftStarEngine!(ulong, 1024u, 31, -11, -30, 11400714819323198483LU, ulong).XorshiftStarEngine; - Define XorshiftStarEngine with well-chosen parameters for large simulations on 64-bit machines.Period of (2 ^^ 1024) - 1, 16-dimensionally equidistributed, and faster and statistically superior to Mt19937_64 while occupying significantly less memory. This generator is recommended for random number generation on 64-bit systems except when 1024 + 32 bits of state are excessive. As described by Vigna in the 2014 draft of his paper published in 2016 detailing the xorshift* family, except with a better multiplier recommended by the author as of 2017-10-08. Public domain reference implementation: xoroshiro.di.unimi.it/xorshift1024star.c.Examples:
import mir.random.engine : EngineReturnType, isSaturatedRandomEngine; auto rnd = Xorshift1024StarPhi(12434UL); auto num = rnd(); assert(num != rnd()); static assert(is(EngineReturnType!Xorshift1024StarPhi == ulong)); static assert(isSaturatedRandomEngine!Xorshift1024StarPhi); //Xorshift1024StarPhi has a jump function that is equivalent //to 2 ^^ 512 invocations of opCall. rnd.jump(); num = rnd(); assert(num != rnd());

- alias
`Xorshift64Star32`

= XorshiftStarEngine!(ulong, 64u, -12, 25, -27, 2685821657736338717LU, uint).XorshiftStarEngine; - Generates 32 bits of output from 64 bits of state. A fast generator with excellent statistical properties for memory-constrained situations where more than 64 bits of state would be too much and generating only 32 bits with each opCall will not cause a slowdown. Today SplitMix64 (which has 64 bit output) or pcg32_oneseq from the PCG family of generators might fill this niche better but the wide popularity of this generator and its continued recommendation by some in 2017 merit its inclusion in a PRNG library.Note that xorshift64*/32 is slower than xorshift1024* even when only 32 bits of output are needed at a time. Per Vigna:
The three xor/shifts of a xorshift64* generator must be executed sequentially, as each one is dependent on the result of the previous one. In a xorshift1024* generator two of the xor/shifts are completely independent and can be parallelized internally by the CPU.

Public domain xorshift64* reference implementation (Internet Archive).Examples:import mir.random.engine : isSaturatedRandomEngine; static assert(isSaturatedRandomEngine!Xorshift64Star32); Xorshift64Star32 rnd = Xorshift64Star32(123456789); uint x = rnd(); assert(x == 3988833114);

- struct
`Xoroshiro128Plus`

; - xoroshiro128+ (XOR/rotate/shift/rotate) generator. 64 bit output. 128 bits of state. Period of (2 ^^ 128) - 1.Created in 2016 by David Blackman and Sebastiano Vigna as the successor to Vigna's extremely popular xorshift128+ generator used in the JavaScript engines of Google Chrome, Mozilla Firefox, Safari, and Microsoft Edge. From the authors:
This is the successor to xorshift128+. It is the fastest full-period generator passing BigCrush without systematic failures, but due to the relatively short period it is acceptable only for applications with a mild amount of parallelism; otherwise, use a xorshift1024* generator. Beside passing BigCrush, this generator passes the PractRand test suite up to (and included) 16TB, with the exception of binary rank tests, as the lowest bit of this generator is an LFSR. The next bit is not an LFSR, but in the long run it will fail binary rank tests, too. The other bits have no LFSR artifacts. We suggest to use a sign test to extract a random Boolean value, and right shifts to extract subsets of bits.

Public domain reference implementation: xoroshiro.di.unimi.it/xoroshiro128plus.c.Examples:import mir.random.engine : isSaturatedRandomEngine; static assert(isSaturatedRandomEngine!Xoroshiro128Plus); auto gen = Xoroshiro128Plus(1234u);//Seed with constant. assert(gen() == 5968561782418604543);//Generate number. foreach (i; 0 .. 8) gen(); assert(gen() == 8335647863237943914uL); //Xoroshiro128Plus has a jump function that is equivalent //to 2 ^^ 64 invocations of opCall. gen.jump(); auto n = gen();

- enum bool
`isRandomEngine`

; - enum ulong
`max`

; - Largest generated value.
- ulong[2]
`s`

; - State must not be entirely zero. The constructor ensures this condition is met.
- enum bool
`preferHighBits`

; - The lowest bit of this generator is an LFSR. The next bit is not an LFSR, but in the long run it will fail binary rank tests, too. The other bits have no LFSR artifacts. To provide some context,
*every*bit of a Mersenne Twister generator (either the 32-bit or 64-bit variant) is an LFSR.The rand!T functions in mir.random automatically will discard the low bits when generating output smaller than ulong due to this generator having`preferHighBits`

defined true. - pure nothrow @nogc @safe this()(ulong
`x0`

); - Constructs an Xoroshiro128Plus generator seeded with
`x0`

. - ulong
`opCall`

()(); - Advances the random sequence.
- pure nothrow @nogc @safe void
`jump`

()(); - This is the
`jump`

function for the generator. It is equivalent to 2^^64 calls to opCall(); it can be used to generate 2^^64 non-overlapping subsequences for parallel computations. - enum bool
`isUniformRandom`

;

enum typeof(this.max)`min`

;

enum bool`empty`

;

const @property ulong`front`

()();

void`popFront`

()();

void`seed`

()(ulong`x0`

); - Compatibility with Phobos library methods. Presents this RNG as an InputRange.This struct disables its default copy constructor and so will only work with Phobos functions that "do the right thing" and take RNGs by reference and do not accidentally make implicit copies.

- struct
`Xoshiro256StarStar`

; - xoshiro256** (XOR/shift/rotate) as described in Scrambled linear pseudorandom number generators (Blackman and Vigna, 2018). 64 bit output. 256 bits of state. Period of 2^^256-1. 4-dimensionally equidistributed. It is 15% slower than xoroshiro128+ but none of its bits fail binary rank tests and it passes tests for Hamming-weight dependencies introduced in the linked paper. From the authors:
This is xoshiro256** 1.0, our all-purpose, rock-solid generator. It has excellent (sub-ns) speed, a state (256 bits) that is large enough for any parallel application, and it passes all tests we are aware of.

A jump() function is included that skips ahead by 2^^128 calls, to generate non-overlapping subsequences for parallel computations. Public domain reference implementation: http://xoshiro.di.unimi.it/xoshiro256starstar.c.Examples:import mir.random : isSaturatedRandomEngine, rand; import mir.random.engine.xorshift : Xoshiro256StarStar; import mir.math.common: fabs; static assert(isSaturatedRandomEngine!Xoshiro256StarStar); auto gen = Xoshiro256StarStar(1234u);//Seed with constant. assert(gen.rand!double.fabs == 0x1.b45d9a0e3ae53p-2);//Generate number from 0 inclusive to 1 exclusive. assert(gen.rand!double.fabs == 0x1.640660c19433ep-3); //Xoshiro256StarStar has a jump function that is equivalent //to 2 ^^ 128 invocations of opCall. gen.jump(); assert(gen.rand!uint == 2505151307);

- enum bool
`isRandomEngine`

; - enum ulong
`max`

; - Largest generated value.
- enum bool
`preferHighBits`

; - No bits of this generator's output fail any tests, but the high bits provably have greater linear complexity than the low bits.
- ulong[4]
`s`

; - State must not be entirely zero. The constructor ensures this condition is met.
- pure nothrow @nogc @safe this(ulong
`x0`

); - Initializes the generator with a 64-bit seed.
- pure nothrow @nogc @safe ulong
`opCall`

(); - Advances the random sequence.Returns:A uniformly-distributed integer in the closed range [0, OutputUInt.max].
- pure nothrow @nogc @safe void
`jump`

()(); - This is the
`jump`

function for the generator. It is equivalent to 2^^128 calls to next(); it can be used to generate 2^^128 non-overlapping subsequences for parallel computations. - enum bool
`isUniformRandom`

;

enum typeof(this.max)`min`

;

enum bool`empty`

;

const @property ulong`front`

()();

void`popFront`

()();

void`seed`

()(ulong`x0`

); - Compatibility with Phobos library methods. Presents this RNG as an InputRange.This struct disables its default copy constructor and so will only work with Phobos functions that "do the right thing" and take RNGs by reference and do not accidentally make implicit copies.

Copyright © 1999-2018 by the D Language Foundation | Page generated by
Ddoc on Thu May 17 10:02:49 2018