Standard Normal Random Numbers

Usage

var iterator = require( '@stdlib/random/iter/box-muller' );

iterator( [options] )

Returns an iterator for generating pseudorandom numbers drawn from a standard normal distribution using the Box-Muller transform.

var it = iterator();
// returns <Object>

var r = it.next().value;
// returns <number>

r = it.next().value;
// returns <number>

r = it.next().value;
// returns <number>

// ...

The function accepts the following options:

• prng: pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval [0,1). If provided, the function ignores both the state and seed options. In order to seed the returned iterator, one must seed the provided prng (assuming the provided prng is seedable).
• seed: pseudorandom number generator seed.
• state: a 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 iterator has exclusive control over its internal pseudorandom number generator state. Default: true.
• iter: number of iterations.

To use a custom PRNG as the underlying source of uniformly distributed pseudorandom numbers, set the prng option.

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

var it = iterator({
    'prng': minstd.normalized
});

var r = it.next().value;
// returns <number>

To return an iterator having a specific initial state, set the iterator state option.

var bool;
var it1;
var it2;
var r;
var i;

it1 = iterator();

// Generate pseudorandom numbers, thus progressing the generator state:
for ( i = 0; i < 1000; i++ ) {
    r = it1.next().value;
}

// Create a new iterator initialized to the current state of `it1`:
it2 = iterator({
    'state': it1.state
});

// Test that the generated pseudorandom numbers are the same:
bool = ( it1.next().value === it2.next().value );
// returns true

To seed the iterator, set the seed option.

var it = iterator({
    'seed': 12345
});

var r = it.next().value;
// returns ~0.349

it = iterator({
    'seed': 12345
});

r = it.next().value;
// returns ~0.349

To limit the number of iterations, set the iter option.

var it = iterator({
    'iter': 2
});

var r = it.next().value;
// returns <number>

r = it.next().value;
// returns <number>

r = it.next().done;
// returns true

The returned iterator protocol-compliant object has the following properties:

• next: function which returns an iterator protocol-compliant object containing the next iterated value (if one exists) assigned to a value property and a done property having a boolean value indicating whether the iterator is finished.
• return: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.
• seed: pseudorandom number generator seed. If provided a prng option, the property value is null.
• seedLength: length of generator seed. If provided a prng option, the property value is null.
• state: writable property for getting and setting the generator state. If provided a prng option, the property value is null.
• stateLength: length of generator state. If provided a prng option, the property value is null.
• byteLength: size (in bytes) of generator state. If provided a prng option, the property value is null.
• PRNG: underlying pseudorandom number generator.