random-extra

Seedable random number generator supporting many common distributions.

Usage no npm install needed!

<script type="module">
  import randomExtra from 'https://cdn.skypack.dev/random-extra';
</script>

README

random-extra

Seedable random number generator supporting many common distributions.

NPM Build Status

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

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

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

    • pluggable prng
    • port more prng from boost
    • custom entropy
  • Misc

    • browser support via rollup
    • basic docs
    • basic tests
    • full test suite
    • 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