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

1npm install random-extra seedrandom

benchmark

random.d.ts

Usage (new)

1import random from 'random-extra';
2import 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

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

when use seedrandom, srand will able use

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

other way make seedrandom

1import random from 'random-extra';
2const seedrandom = random.newUse('seedrandom')
3
4import _seedrandom = require('seedrandom')
5
6random.newUse(_seedrandom('hello.', { entropy: true }))
7random.newUse(_seedrandom('hello.', { entropy: false }))
8
9random.newUse(_seedrandom('hello.'))

Usage (original)

1const random = require('random-extra')
2
3// quick uniform shortcuts
4random.float(min = 0, max = 1) // uniform float in [ min, max )
5random.int(min = 0, max = 1) // uniform integer in [ min, max ]
6random.boolean() // true or false
7
8// uniform
9random.dfUniform(min = 0, max = 1) // () => [ min, max )
10random.dfUniformInt(min = 0, max = 1) // () => [ min, max ]
11random.dfUniformBoolean() // () => [ false, true ]
12
13// normal
14random.dfNormal(mu = 0, sigma = 1)
15random.dfLogNormal(mu = 0, sigma = 1)
16
17// bernoulli
18random.dfBernoulli(p = 0.5)
19random.dfBinomial(n = 1, p = 0.5)
20random.dfGeometric(p = 0.5)
21
22// poisson
23random.dfPoisson(lambda = 1)
24random.dfExponential(lambda = 1)
25
26// misc
27random.dfIrwinHall(n)
28random.dfBates(n)
29random.dfPareto(alpha)

For convenience, several common dfUniform samplers are exposed directly:

1random.float()     // 0.2149383367670885
2random.int(0, 100) // 72
3random.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.

1// create a normal distribution with default params (mu=1 and sigma=0)
2const normal = random.dfNormal()
3normal() // 0.4855465422678824
4normal() // -0.06696771815439678
5normal() // 0.7350852689834705
6
7// create a poisson distribution with default params (lambda=1)
8const poisson = random.dfPoisson()
9poisson() // 0
10poisson() // 4
11poisson() // 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:

1const seedrandom = require('seedrandom')
2
3// change the underlying pseudo random number generator
4// by default, Math.random is used as the underlying PRNG
5random.use(seedrandom('foobar'))
6
7// create a new independent random number generator
8const rng = random.clone('my-new-seed')
9
10// create a second independent random number generator and use a seeded PRNG
11const rng2 = random.clone(seedrandom('kittyfoo'))
12
13// replace Math.random with rng.uniform
14rng.patch()
15
16// restore original Math.random
17rng.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

  • 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