nish/random

A seeded generator of pseudo-random numbers whose every answer is the same natively and under Node.

import {
  Rng,
} from "nish/random";
import { Rng } from "nish/random";

export const main = (): i32 => {
  const r = new Rng(42);
  const die: i32 = r.nextInt(1, 6); // 1 to 6, each with equal chance
  const u: f64 = r.nextF64(); // in [0, 1)
  return die;
};
The state is one 32-bit integer

Each step adds the odd constant 0x9E3779B9 (2^32 divided by the golden ratio) to it, wrapping, so the states walk all 2^32 values before any repeats, whatever the seed — 0 included. Each answer is MurmurHash3's 32-bit finaliser applied to the new state (Austin Appleby's fmix32; MurmurHash3 is public domain, and these are its constants): two multiplies and three shifted exclusive ors that mix every bit of the state into every bit of the answer, so seeds 1, 2 and 3 answer three unrelated sequences. That pairing of a Weyl sequence with a mixing function is the shape of SplitMix (Steele, Lea and Flood, "Fast splittable pseudorandom number generators", OOPSLA 2014), on 32 bits.

The same bits under Node

The two operations that wrap are spelled wrappingAdd and wrappingMul from nish:unsafe, which define the two's-complement wrap natively and answer (a + b) | 0 and Math.imul(a, b) under Node (docs/LANGUAGE.md, "nish "); every shift has a constant count, and ^ and >>> 16 answer the same 32 bits in JavaScript as in the compiled program.

nextInt reads its span and its draws as unsigned counts with no u32 (whose conversions saturate under Node): the sign bit flipped orders them under a signed compare, and the remainder is taken in pieces that stay below 2^31. nextF64 builds its double from integers below 2^53, so its products and sums are exact both ways. The program a test prints under Node is the one it prints compiled (docs/RUN_UNDER_NODE.md).

It is not for cryptography

a key or a nonce comes from crypto.getRandomValues.

An `Rng` is an ordinary object

An Rng is an ordinary object, so a parallel body or a task that makes one of its own may step it as it likes: what a function allocates is its own memory (docs/LANGUAGE.md, "Data parallelism"). One shared by several tasks would be a write their caller can see, and is refused as any such write is; give each task its own, seeded from its index.

Classes

Rng

A generator of pseudo-random numbers: a Weyl sequence from its seed, each state mixed.

class Rng
Member
new Rng(seed: i32) A generator whose sequence seed decides: two made from one seed answer the same numbers.
nextF64(): f64 The next number in [0, 1), from two steps: the high 27 bits of one and the high 26 of the next make a 53-bit integer, which a double holds exactly, scaled by 2^-53.
nextI32(): i32 The next 32 bits, as an i32: over 2^32 steps each value is answered exactly once.
nextInt(lo: i32, hi: i32): i32 An integer in [lo, hi], both ends included, each with equal chance; nextInt(1, 6) is a die. It panics when lo is greater than hi, and the whole i32 range, nextInt(-2147483648, 2147483647), is one nextI32().

There is no modulo bias: where the span hi - lo + 1, an unsigned count up to 2^32, does not divide 2^32 evenly, a draw among the lowest 2^32 mod span is refused and drawn again, and what is left holds every answer equally often. Fewer than half the draws are ever refused, so an answer takes one nextI32() step usually and fewer than two on average, and a sequence is still the seed's.