Random utilities based on WELL-1024a PRNG.
npm install randy
Randy is a utility module inspired by Python's very handy standard
module "random". It contains a PRNG and useful randomness functions.
All functions are based on a JavaScript implementation of
WELL-1024a,
with up to 53-bit precision. The reason for this is that the built-inMath.random() function is
implementation-dependent
and therefore of very limited usefulness, as you risk running into
crappy implementations. Even the V8 engine (used by Node.js) only
provides 32-bit entropy, and is based on the platform-dependent C++rand() function.
``javascript`
var a = randy.randInt(100);
// a == 42
`javascript`
var d = randy.shuffle(["J spades", "K hearts", "10 hearts"]);
// d == [ "K hearts", "J spades", "10 hearts" ]
`javascript`
var c = randy.choice(["heads", "tails"]);
// c == "heads"
npm install randy
Download and include as a
`
* randInt
* choice
* shuffle
* shuffleInplace
* sample
* random
* uniform
* triangular
* getRandBits
* getState
* setState
* instance
All the above randomness functions use 32-bit precision if possible,
but will use 53-bit precision if they need to go outside the 32-bit
range.
The randomness functions are also available in always-53-bit-precision
versions, under the good namespace. If you're working with values
over 65536 or so, imbalances of 0.01% will start to creep in, and a
higher precision will reduce this problem.
These functions take about 35% longer to run than the ones available
directly under randy.
__Example__
`javascript`
// Generate example salary between 1,000,000 and 5,000,000
// with values clustering around 2,000,000.
var salary = randy.good.triangular(1000000, 5000000, 2000000);
The randomness functions are also available in maximally uniform
versions, under the best namespace.
Random integer calculations in the randy and randy.good functions
are done via a modulo of a large random unsigned integer. This will
slightly favour lower numbers, but it is fast, and good enough for
most use cases. However, if you wish to avoid this imbalance, you can
use these functions.
These functions take on average 110% longer to run than the ones
available directly under randy.
__Example__
`javascript`
var numbers = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
13, 14, 15, 16, 17, 18, 19, 20, 21, 22 ];
var lottery = randy.best.sample(numbers, 7);
---------------------------------------
Returns a random integer i such that min <= i < max.
If step is provided, then additionally (i - min) % step = 0.
Return value is based on a random 32-bit integer.
If max >= 2^32, will call good.getInt(), which goes up to
2^53.
__Arguments__
* min - default=0. Returned integer will be min or greater.
* max - default=2^32. Returned integer will be less than max.
* step - default=1. Returned integer will be a multiple of this, counting from min.
__Example__
`javascript`
console.log("Rolling the dice:");
var d1 = randy.randInt(1, 7);
var d2 = randy.randInt(1, 7);
console.log(d1 + " + " + d2 + " = " + (d1 + d2));
if (d1 + d2 == 2)
console.log("Snake eyes!");
---------------------------------------
Returns a randomly chosen element from the array arr.
Throws an exception if arr is empty.
__Arguments__
* arr - Array of elements of any type. Length > 0. Return value will be an element of arr.
__Example__
`javascript`
var breakfast = randy.choice(["whisky", "bacon", "panic"]);
console.log("Good morning! Enjoy some " + breakfast + "!");
`javascript`
// Set direction vector for a ghost from Pac-Man.
ghost.currentDirection = randy.choice([
{x:0, y:-1}, {x:1, y:0}, {x:0, y:1}, {x:-1, y:0}
]);
---------------------------------------
Returns a shuffled copy of arr. Returned array contains the exact
same elements as arr, and equally many elements, but in a new order.
Uses the Fisher-Yates algorithm, aka the Knuth Shuffle.
__Arguments__
* arr - Array of elements of any type.
__Example__
`javascript`
var runners = ["Andy", "Bob", "Clarence", "David"];
var startingOrder = randy.shuffle(runners);
---------------------------------------
Shuffles the array arr. A more memory-efficient version of shuffle.
Uses the Fisher-Yates algorithm, aka the Knuth Shuffle.
__Arguments__
* arr - Array of elements of any type. Will be modified.
__Example__
`javascript
// Reorder elements at random until they happen to be sorted.
function bogosort (arr) {
while (true) {
randy.shuffleInplace(arr);
var sorted = true;
for (var i=0; i
if (sorted)
return;
}
}
`
`javascript`
// Create new draw deck from card discard pile.
if (deck.length == 0) {
deck = discardPile.splice(0);
randy.shuffleInplace(deck);
}
---------------------------------------
Returns an array of length count, containing unique elements chosen
from the array population. Like a raffle draw.
Mathematically equivalent to shuffle(population).slice(0, count), butcount > population.length
more efficient. Catches fire if .
__Arguments__
* population - Array of elements of any type.
* count - How many elements to pick from array population.
__Example__
`javascript
// Raffle draw for 3 bottles of wine. Cindy has bought 2 tickets.
var raffleTickets = ["Alice", "Beatrice", "Cindy", "Cindy", "Donna"];
var winners = randy.sample(raffleTickets, 3);
console.log("The winners are: " + winners.join(", "));
`
---------------------------------------
Returns a floating point number n, such that 0.0 <= n < 1.0.
Exactly as uniform(), but provided for familiarity.
---------------------------------------
Returns a floating point number n, such that min <= n < max.
__Arguments__
* min - Default=0.0. Returned value will be equal to or larger than this.
* max - Default=1.0. Returned value will be less than this.
__Example__
`javascript`
// Torpedo guidance system.
var heading = randy.uniform(360.0);
`javascript`
// Random event repeating every 1-5 minutes.
function flashLightning () {
flash();
var delayNext = randy.uniform(1.0 60000, 5.0 60000);
setTimeout(flashLightning, delayNext);
}
---------------------------------------
The triangular distribution is typically used as a subjective
description of a population for which there is only limited sample
data, and especially in cases where the relationship between variables
is known but data is scarce (possibly because of the high cost of
collection). It is based on a knowledge of the minimum and maximum and
an "inspired guess" as to the modal value.
__Arguments__
* min - Default=0.0. Returned value will be equal to or larger than this.
* max - Default=1.0. Returned value will be less than this.
* mode - Default is average of min and max. Returned values are likely to be close to this value.
__Example__
`javascript`
// Generate customer test data. Customers are aged 18 to 40, but
// most of them are in their twenties. Their income is between
// 40000-150000 Hyrulean Rupees per year, but typically around
// 60000.
for (i=0; i<1000; i++) {
db.insertCustomer({
name: "Bruce",
birthYear: Math.floor( randy.triangular(1972, 1990, 1983) ),
income: randy.triangular(40000, 150000, 60000)
});
}
---------------------------------------
Returns a random integer of bit width n, where n <= 53.
__Arguments__
* n - Number of random bits in return value.
__Example__
`javascript`
// A perfect distribution function, which rejects overflow values
// instead of squeezing them into the desired range by use of modulo.
function perfectInt (max) {
if (max == 0)
return 0;
var log2 = 0;
var mult = 1;
while (mult < max) {
log2 += 1;
mult *= 2;
}
while (false == false) {
var r = randy.getRandBits(log2);
if (r < max)
return r;
}
}
---------------------------------------
Returns a JavaScript object representing the current state of the generator.
This object can be used as a parameter to setState().
Sets the generator to a specific state, allowing for replay of random values.
__Arguments__
* state - Must be object retrieved from an earlier call to getState().
__Example__
This will roll a pair of dice, reset the generator state, and roll the
dice again with the exact same output.
`javascript
var state = randy.getState();
console.log("Rolling the dice:");
var d1 = randy.randInt(1, 7);
var d2 = randy.randInt(1, 7);
console.log(d1 + " + " + d2 + " = " + (d1 + d2));
console.log("Instant replay:");
randy.setState(state);
d1 = randy.randInt(1, 7);
d2 = randy.randInt(1, 7);
console.log(d1 + " + " + d2 + " = " + (d1 + d2));
`
Creates a separate randy instance, for those use cases where a
global object is a bad fit. The instance has the same functions as
the global object.
If no state parameter is given, the new instance will be initialized
randomly.
Calling this will not affect the generator state.
__Arguments__
* state - Must be object retrieved from an earlier call to getState().
__Example__
Create two instances, one a copy of the global object. Sync the
copies to the original randy state.
`javascript`
var origState = randy.getState();
var r1 = randy.instance(origState);
var r2 = randy.instance();
console.log(randy.randInt(50), r1.randInt(50), r2.randInt(50)); // 34 34 17
console.log(randy.randInt(50), r1.randInt(50), r2.randInt(50)); // 12 12 4
r1.setState(origState);
r2.setState(origState);
console.log(randy.randInt(50), r1.randInt(50), r2.randInt(50)); // 15 34 34
console.log(randy.randInt(50), r1.randInt(50), r2.randInt(50)); // 36 12 12
---------------------------------------
No functions rely on this, so it's safe to e.g. assignrandy.good.randInt` to a variable or pass it around as a
parameter.
Due to floating point rounding, functions returning floating point
values may extremely rarely tangent the upper bound.
Maximum integer range is 2^53 = 9007199254740992. This is the maximum
integer available in JavaScript without losing precision. Any calls
requiring a larger range than this, explicitly or implicitly, will not
yield correct results.