Box-Muller Transform

Standard normally distributed pseudorandom numbers using the Box-Muller transform.

Usage

var randn = require( '@stdlib/random/base/box-muller' );

randn()

Returns a standard normally distributed pseudorandom number.

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

randn.factory( [options] )

Returns a pseudorandom number generator (PRNG) for generating standard normally distributed pseudorandom numbers.

var rand = randn.factory();

The function accepts the following options:

  • prng: pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval [0,1).
  • seed: pseudorandom number generator seed.

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 rand = randn.factory({
    'prng': minstd.normalized
});

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

To seed a pseudorandom number generator, set the seed option.

var rand = randn.factory({
    'seed': 12345
});

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

randn.NAME

The generator name.

var str = randn.NAME;
// returns 'box-muller'

randn.PRNG

The underlying pseudorandom number generator for uniformly distributed numbers on the interval [0,1).

var prng = randn.PRNG;
// returns <Function>

randn.SEED

The value used to seed randn().

var rand;
var r;
var i;

// Generate pseudorandom values...
for ( i = 0; i < 100; i++ ) {
    r = randn();
}

// Generate the same pseudorandom values...
rand = randn.factory({
    'seed': randn.SEED
});
for ( i = 0; i < 100; i++ ) {
    r = rand();
}

If provided a PRNG for uniformly distributed numbers which does not have a SEED property, this value is null.

var rand = randn.factory({
    'prng': Math.random
});

var seed = rand.SEED;
// returns null

randn.MIN

Minimum possible value.

var min = randn.MIN;
// returns <number>

Note that this value is computed based on the minimum value of the underlying PRNG for uniformly distributed numbers. If the underlying PRNG does not have a MIN property, this value is null.

var rand = randn.factory({
    'prng': Math.random
});

var min = rand.MIN;
// returns null

randn.MAX

Maximum possible value.

var max = randn.MAX;
// returns <number>

Note that this value is computed based on the minimum value of the underlying PRNG for uniformly distributed numbers. If the underlying PRNG does not have a MIN property, this value is null.

var rand = randn.factory({
    'prng': Math.random
});

var max = rand.MAX;
// returns null

Notes

  • The minimum and maximum values are dependent on the number of bits used by the underlying PRNG. For instance, if a PRNG uses 32 bits, the smallest non-zero uniformly distributed pseudorandom number that can be generated is 2**-32. Accordingly, the algorithm would be unable to produce random variates more than 6.66 standard deviations from the mean. This corresponds to a 2.74 x 10**-11 loss due to tail truncation.

Examples

var randn = require( '@stdlib/random/base/box-muller' );

var seed;
var rand;
var i;

// Generate pseudorandom numbers...
for ( i = 0; i < 100; i++ ) {
    console.log( randn() );
}

// Create a new pseudorandom number generator...
seed = 1234;
rand = randn.factory({
    'seed': seed
});
for ( i = 0; i < 100; i++ ) {
    console.log( rand() );
}

// Create another pseudorandom number generator using a previous seed...
rand = randn.factory({
    'seed': randn.SEED
});
for ( i = 0; i < 100; i++ ) {
    console.log( rand() );
}

References

  • Box, G. E. P., and Mervin E. Muller. 1958. "A Note on the Generation of Random Normal Deviates." The Annals of Mathematical Statistics 29 (2). The Institute of Mathematical Statistics: 610–11. doi:10.1214/aoms/1177706645.
  • Bell, James R. 1968. "Algorithm 334: Normal Random Deviates." Communications of the ACM 11 (7). New York, NY, USA: ACM: 498. doi:10.1145/363397.363547.
  • Knop, R. 1969. "Remark on Algorithm 334 [G5]: Normal Random Deviates." Communications of the ACM 12 (5). New York, NY, USA: ACM: 281. doi:10.1145/362946.362996.
  • Marsaglia, G., and T. A. Bray. 1964. "A Convenient Method for Generating Normal Variables." SIAM Review 6 (3). Society for Industrial; Applied Mathematics: 260–64. doi:10.1137/1006063.
  • Thomas, David B., Wayne Luk, Philip H.W. Leong, and John D. Villasenor. 2007. "Gaussian Random Number Generators." ACM Computing Surveys 39 (4). New York, NY, USA: ACM. doi:10.1145/1287620.1287622.