random-extra
    TypeScript icon, indicating that this package has built-in type declarations

    3.6.16 • Public • Published

    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

      • [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

    Install

    npm i random-extra

    DownloadsWeekly Downloads

    65

    Version

    3.6.16

    License

    MIT

    Unpacked Size

    344 kB

    Total Files

    196

    Last publish

    Collaborators

    • bluelovers