random-extra

Seedable random number generator supporting many common distributions.

this module fork from transitive-bullshit/random, with typescript support and some other change (include breaking change)

Welcome to the most random module on npm! 😜

Highlights

Wellcome send PR for more API support or performance up

• Simple API (make easy things easy and hard things possible)
• Seedable based on entropy or user input
• Plugin support for different pseudo random number generators (PRNGs)
• Sample from many common distributions
  • dfUniform, dfNormal, dfPoisson, dfBernoulli, etc see distributions
• Validates all user input via chai
• Integrates with seedrandom
• Supports node.js >= 7 and browser (if here has no break)

breaking change: v2.x to v3.x

• for more easy know what api do by method name
• all (distribution function) method rename and add prefix df
  (ex: itemByWeight => dfItemByWeight)
  when run in loop, or wanna performance, pls use (distribution function) version
• remove shortid

Install

npm install random-extra seedrandom

benchmark

random.d.ts

Usage (new)

import random from 'random-extra';
import random = require('random-extra');

.use vs .newUse

• .use will change current random object
• .newUse will create new random object

preset

seedrandom

use seedrandom for make seed-able

import seedrandom from 'random-extra/preset/seedrandom';
import { seedrandom } from 'random-extra/preset/seedrandom';

when use seedrandom, srand will able use

seedrandom.rand() // use current seed
seedrandom.srand() // every time call srand will make new seed
seedrandom.rand() // use new seed

other way make seedrandom

import random from 'random-extra';
const seedrandom = random.newUse('seedrandom')

import _seedrandom = require('seedrandom')

random.newUse(_seedrandom('hello.', { entropy: true }))
random.newUse(_seedrandom('hello.', { entropy: false }))

random.newUse(_seedrandom('hello.'))

Usage (original)

const random = require('random-extra')

// quick uniform shortcuts
random.float(min = 0, max = 1) // uniform float in [ min, max )
random.int(min = 0, max = 1) // uniform integer in [ min, max ]
random.boolean() // true or false

// uniform
random.dfUniform(min = 0, max = 1) // () => [ min, max )
random.dfUniformInt(min = 0, max = 1) // () => [ min, max ]
random.dfUniformBoolean() // () => [ false, true ]

// normal
random.dfNormal(mu = 0, sigma = 1)
random.dfLogNormal(mu = 0, sigma = 1)

// bernoulli
random.dfBernoulli(p = 0.5)
random.dfBinomial(n = 1, p = 0.5)
random.dfGeometric(p = 0.5)

// poisson
random.dfPoisson(lambda = 1)
random.dfExponential(lambda = 1)

// misc
random.dfIrwinHall(n)
random.dfBates(n)
random.dfPareto(alpha)

For convenience, several common dfUniform samplers are exposed directly:

random.float()     // 0.2149383367670885
random.int(0, 100) // 72
random.boolean()   // true

All distribution methods return a thunk (function with no params), which will return a series of independent, identically distributed random variables from the specified distribution.

// create a normal distribution with default params (mu=1 and sigma=0)
const normal = random.dfNormal()
normal() // 0.4855465422678824
normal() // -0.06696771815439678
normal() // 0.7350852689834705

// create a poisson distribution with default params (lambda=1)
const poisson = random.dfPoisson()
poisson() // 0
poisson() // 4
poisson() // 1

Note that returning a thunk here is more efficient when generating multiple samples from the same distribution.

You can change the underlying PRNG or its seed as follows:

const seedrandom = require('seedrandom')

// change the underlying pseudo random number generator
// by default, Math.random is used as the underlying PRNG
random.use(seedrandom('foobar'))

// create a new independent random number generator
const rng = random.clone('my-new-seed')

// create a second independent random number generator and use a seeded PRNG
const rng2 = random.clone(seedrandom('kittyfoo'))

// replace Math.random with rng.uniform
rng.patch()

// restore original Math.random
rng.unpatch()

API

Table of Contents

• Random

Random

Seedable random number generator supporting many common distributions.

Defaults to Math.random as its underlying pseudorandom number generator.

Type: function (rng)

• rng (Rng | function) Underlying pseudorandom number generator. (optional, default Math.random)

Todo

• Distributions

  • [x] dfUniform
  • [x] dfUniformInt
  • [x] dfUniformBoolean
  • [x] dfNormal
  • [x] dfLogNormal
  • [ ] chiSquared
  • [ ] cauchy
  • [ ] fischerF
  • [ ] studentT
  • [x] dfBernoulli
  • [x] dfBinomial
  • [ ] negativeBinomial
  • [x] dfGeometric
  • [x] dfPoisson
  • [x] dfExponential
  • [ ] gamma
  • [ ] hyperExponential
  • [ ] weibull
  • [ ] beta
  • [ ] laplace
  • [x] dfIrwinHall
  • [x] dfBates
  • [x] dfPareto

• Generators

  • [x] pluggable prng
  • [ ] port more prng from boost
  • [ ] custom entropy

• Misc

  • [x] browser support via rollup
  • [x] basic docs
  • [x] basic tests
  • [ ] full test suite
  • [x] initial release!

Related

• d3-random - D3's excellent random number generation library.
• seedrandom - Seedable pseudo random number generator.
• random-int - For the common use case of generating dfUniform random ints.
• random-float - For the common use case of generating dfUniform random floats.
• randombytes - Random crypto bytes for Node.js and the browser.

Credit

Huge shoutout to Roger Combs for donating the random npm package for this project!

Lots of inspiration from d3-random (@mbostock and @svanschooten).

Some distributions and PRNGs are ported from C++ boost::random.

License

MIT © Travis Fischer