arbit

arbit

A tiny pseudo-random number generator.

Example

var arbit = require('arbit');

var random = arbit();

var HIT_CHANCE = 0.75;
var MIN_DAMAGE = 15, MAX_DAMAGE = 21;

if (random() <= HIT_CHANCE) {
  var damage = random.nextInt(MIN_DAMAGE, MAX_DAMAGE + 1);
  console.log('You hit the zombie for %d damage!', damage);
} else {
  console.log('You missed!');
}

Function reference

var generator = arbit(seed)

The package itself is just a single function which returns a number generator using the provided seed. The seed can be any string.

var generator = arbit.fromState(state)

Returns a number generator initialized to be in the provided state.

var number = generator()

Calling the generator itself returns a value greater than or equal to zero, and less than one.

var number = generator.nextFloat(max)

Returns a floating point that somewhere between zero and max. If a negative number is provided, the range will instead be (max, 0].

var number = generator.nextFloat(min, max)

Returns a floating point number within either the range [min, max) or (max, min] (if the range is reversed).

var number = generator.nextInt(max)

Same as nextFloat(max), but coerces the value to an integer with Math.floor.

var number = generator.nextInt(min, max)

Same as nextFloat(min, max), but coerces the value to an integer with Math.floor.

var state = generator.getState()

Returns the current state of the generator. This can be passed into arbit.fromState(state) to get back another generator in the same state (i.e., it will generate the same sequence of numbers).

Why arbit?

Reproducibility

This library provides guaranteed reproducibility of observed sequences of numbers, given that you supply the same state to the PRNG. This is not possible with Math.random.

Simplicity

arbit is very small but provides additional functions for getting random ranges and integers.

Quality

It's very difficult to reason about what is random and what is not, especially as a human being (we tend to see patterns where there are none). Some important qualities to look for in a PRNG are:

• No predictable/repeating patterns
• Even distribution of numbers (no number is more likely than another)
• Number of possible unique patterns that can be generated

Verifying the quality

In this repo you will find the script dieharder.bash. Running it will generate a ~5 GB file sampling numbers from arbit, then pass it on to Dieharder which will test the quality of the output (how unpredictable it is).

Compared to Math.random, arbit scores better in terms of randomness quality.

Before you can run the script, you need to install Dieharder. If you have Homebrew installed, doing so is easy:

brew install dieharder

You can now run the test:

./dieharder.bash

Have a look at an example output. You can compare this to Math.random's output.

Performance

The goal of this library is to provide simple, good, reproducible, and performant pseudo-random number generation. Here is a benchmark between Math.random and arbit, running on Node.js (v0.12.5):

arbit x 55,539,526 ops/sec ±3.12% (93 runs sampled)
Math.random x 62,497,530 ops/sec ±1.02% (93 runs sampled)