Skip to content

README.md

Latest commit

 

History

History
271 lines (172 loc) · 6.9 KB

README.md

File metadata and controls

271 lines (172 loc) · 6.9 KB

Xorshift128+

A 128-bit xorshift+ pseudorandom number generator (PRNG).

Usage

var factory = require( '@stdlib/random/base/xorshift128' );

factory()

Returns a xorshift128+ pseudorandom number generator.

var rng = factory();

var r = rng();
// returns <number>

factory.normalized()

Returns a pseudorandom number on the interval [0,1).

var rng = factory();

var r = rng.normalized();
// returns <number>

factory( [options] )

Returns a xorshift128+ pseudorandom number generator (PRNG).

var rng = factory();

The function accepts the following options:

  • seed: pseudorandom number generator seed. Must be a non-negative integer. Default: a random seed.
  • state: a state array (Uint32Array) containing pseudorandom number generator state. If provided, the function ignores the seed option.
  • copy: boolean indicating whether to copy a provided pseudorandom number generator state. Setting this option to false allows sharing state between two or more pseudorandom number generators. Setting this option to true ensures that a returned generator has exclusive control over its internal state. Default: true.

By default, a random seed is used to seed the returned generator. To seed the generator, provide a non-negative integer:

var rng = factory({
    'seed': 1234
});

var r = rng();
// returns <number>

To return a generator having a specific initial state, set the generator state option:

var rng1 = factory();

var r;
var i;
for ( i = 0; i < 1000; i++ ) {
    r = rng1();
}

var state = rng1.state;

var rng2 = factory({
    'state': state
});

var bool = ( rng2() === rng1() );
// returns true

factory.NAME

The generator name.

var rng = factory();

var str = rng.NAME;
// returns 'xorshift128+'

rng.seed

The value used to seed the generator.

var rng = factory({
    'seed': 1234
});

var seed = rng.seed;
// returns <number>

rng.state

Writable property for getting and setting the generator state.

var rng = factory();

var r = rng();
// returns <number>

var state = rng.state;
// returns <Uint32Array>

r = rng();
// returns <number>

rng.state = state;

r = rng();
// returns <number>

rng.copy()

Returns a copy of the pseudorandom number generator.

var rng = factory({
    'seed': 1234
});

var rng2 = rng.copy();

var v1 = rng();
// returns <number>

var v2 = rng2();
// returns <number>

var bool = ( v1 === v2 );
// returns true

rng.toJSON()

Serializes the pseudorandom number generator as a JSON object.

var rng = factory();

var o = rng.toJSON();
// returns { 'type': 'PRNG', 'name': 'xorshift128+', 'state': [...], 'params': [] }

Notes

  • The generator has a period of approximately 2^128 (see References).
  • Xorshift128+ is a fast, simple pseudorandom number generator with good statistical properties for most applications.
  • The generator produces 32-bit pseudorandom integers using bitwise operations on 32-bit pairs.
  • Entropy mixing: the output is computed by XORing the upper and lower 32 bits of the 64-bit result to preserve entropy from the full state.
  • The "randomness quality" of the generator's output is suitable for general-purpose use, Monte Carlo simulations, parallel computations (with different seeds), and statistical sampling.
  • For cryptographic applications, use a cryptographically secure pseudorandom number generator (CSPRNG).
  • If PRNG state is "shared" (meaning a state array was provided during PRNG creation and not copied) and one sets the generator state to a state array having a different length, the PRNG does not update the existing shared state and, instead, points to the newly provided state array. In order to synchronize PRNG output according to the new shared state array, the state array for each relevant PRNG must be explicitly set.
  • If PRNG state is "shared" and one sets the generator state to a state array of the same length, the PRNG state is updated (along with the state of all other PRNGs sharing the PRNG's state array).

Examples

var factory = require( '@stdlib/random/base/xorshift128' );

var rng = factory({
    'seed': 1234
});

var i;
for ( i = 0; i < 10; i++ ) {
    console.log( rng() );
}

References

  • Vigna, S. (2014). "An experimental exploration of Marsaglia's xorshift generators, scrambled." ACM Transactions on Mathematical Software (TOMS), 42(4), 30. doi:10.1145/2714064.2714122.
  • Vigna, S. (2018). "Further scramblings of Marsaglia's xorshift generators." Journal of Computational and Applied Mathematics, 341, 273–282. doi:10.1016/j.cam.2018.03.024.

See Also