well-rng

Fast Javascript implementation of the WELL-1024a RNG for node.js and browser

Overview

Install using npm

npm install well-rng

Then, create a new instance of a WELL-1024a generator and use it to produce random numbers:

var WELL = require('well-rng');
var rng = new WELL();
console.log(rng.randInt());

The complete API is very simple, intended to provide a minimal set of functionality while allowing you to maintain multiple PRNGs and manipulate their state. The primary usage case here is one where you wish to duplicate random calculations on both the client and server. For instance, if you have a game implemented in JavaScript and wish to offload processing to the client, you'd send a seed and use it for all of the random numbers produced. Then, if necessary, playback and verification can be performed later on the server to verify scores, etc.

The other obvious case, I suppose, is if you wanted something to replace Math.random() that was higher quality (WELL is relatively new but considered superior to the Mersenne Twister in functional performance and state recovery). I've made attempts at implementing this to be fast, but the implementation of Math.random() is of course still faster. It's still pretty quick though.

Complete API

// Generates a random integer between 0 and 2^31-1
well.randInt();

// Generates a random float between 0 and 1
well.random();

// Generates a random integer between a and b, inclusive
well.randInt(a, b);

// Generates a random integer with the specified number of bits
well.randBits(bits);

// Obtain the current state vector
well.get_state();
well._n;   // state pointer, arguably part of the state as well

// Set the current state vector, optionally as well as the state pointer, to produce
// specific results
well.set_state(state, n);

// The state vector should be a 32-entry array of 32-bit integers.

In terms of performance, well.randBits() offers the fastest generation for small-ish numbers, because it is able to amortize the cost of running the PRNG, which it does by computing 31 bits at once and then returning them in chunks of the requested sizes. Run the benchmark script, bench.js, to get an idea of the relative performance of well-rng and Math.random() for each usage case.