Linear Congruential Generator

A linear congruential pseudorandom number generator (lcg).

Installation

$ npm install compute-lcg

For use in the browser, use browserify.

Usage

To use the module,

var lcg = require( 'compute-lcg' );

lcg( [seed] )

Returns a pseudorandom number generator.

var rand = lcg();

To seed the generator, provide a positive integer seed

var rand = lcg( 1234 );

rand( [n] )

Returns a pseudorandom floating-point number between 0 and 1.

var val = rand();

If provided a length n, the method returns an array of pseudorandom numbers.

var arr = rand( 10 );
// returns [...]

Notes

For a general lcg reference, see Wikipedia. Linear congruential generators use the following recurrence relation:

In this implementation, the constants a, c, and m have the following values:

The values for a, c, and m are taken from Park and Miller, "Random Number Generators: Good Ones Are Hard To Find". Park's and Miller's article is also the basis for a recipe in the second edition of Numerical Recipes in C. For the most part, this implementation follows Numerical Recipes.

Period

The generator has a period of approximately 2.1e9 [4].

When To Use

Lcg is fast and uses little memory. On the other hand, because the generator is a simple linear congruential generator, it has recognized shortcomings. By today's PRNG standards, its period, on the order of 2e9, is relatively short. More importantly, the "randomness quality" of its output is not of the best quality. These defects rule it out, for example, in Monte Carlo simulations and in cryptographic applications. For more on the advantages and disadvantages of LCGs see [5].

Examples

var lcg = require( 'compute-lcg' );

// Create a new (unseeded) generator:
var rand = lcg();

// Generate some pseudorandom numbers...
for ( var i = 0; i < 10; i++ ) {
	console.log( rand() );
}

// Create a new (seeded) generator:
rand = lcg( 1 );
for ( var j = 0; j < 10; j++ ) {
	console.log( rand() );
}

// Create a new generator seeded with the same seed as the previous generator:
rand = lcg( 1 );
console.log( rand( 10 ).join( '\n' ) );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Test Notes

Test data generated from the C code published in Numerical Recipes.

References

1. Wikipedia. [Linear Congruential Generator](https://en.wikipedia.org/wiki/Linear_ congruential_ generator)

2. S.K. Park and K.W. Miller (1988). "Random Number Generators: Good Ones Are Hard To Find". Communications of the ACM 31 (10): 1192-1201.

3. William H. Press, et. al., Numerical Recipes in C: The Art of Scientific Computing, Section 7.1 "Uniform Deviates" (2d ed. 1992) (hereinafter Numerical Recipes).

4. Numerical Recipes, p. 279.

5. Wikipedia. Linear Congruential Generator.

License

MIT license.

Copyright

Copyright © 2014. rgizz.