This library is an implementation in JavaScript of pseudo-randoms numbers generators, heavily based on Python's Random library.

• Live demo
• Documentation

• 11 differents probability distributions
  • Normal (+ Gauss faster implementation), Log-normal, Exponential, Uniform, Beta, Gamma, Pareto, Von Mises, Weibull, Triangular and Restricted set.
• Seeds support (both numeric and textual)
• Utilitaries to use with Arrays
  • Choice, Shuffle and Sample

First of all, you'll need to include the library :

    <script src="./bin/lowlight.random.js"></script>

You may include the minified library instead :

    <script src="./bin/lowlight.random.min.js"></script>

Then you may create alias for convenience :

    let Distribution = Lowlight.Random.Distribution

To create a new generator, just choose one of the 11 availables distributions. For example, to instantiate a new Normal distribution, type the following code.

    let generator = new Distribution.Normal(0, 1)

By default generator will be seeded with current timestamp. However you can seed it manually by using Generator.seed(seed) method.

Here are some possible ways to seed a generator :

    generator.seed(null) //Initialize seed with current timestamp (default behaviour)
    generator.seed(0xCAFE) //Initialize seed with a number
    generator.seed("Café") //Initialize seed with a string (will be hashed into a number)

Note that Generator.seed(seed) also return current instance so you can instantiate your generators this way :

    generator = Distribution.Normal(0, 1).seed(0xCAFE)

You can read a generator's seed by calling Generator.seed() without arguments.

Note that once you've started generating numbers with Generator.next(), you won't be able to seed it again. You can call Generator.reset(), which will create a new internal generator function but you'll lose iterations count.

    generator.seed("Tea") //No effect
    generator.reset().seed("Tea") //Will keep previous parameters and reseed generator

To setup or update a generator's parameter, just call their respective methods to do so. Note that they all return the instance so can just chain them if you need to edit multiples parameters.

For example, with our previous normal distribution generator, we can type the following :

    generator.mean(1).deviation(10)

You can also read their values by calling them with no arguments.

    generator.mean() //Output 1

In the end, you can instantiate a generator with a single line :

    generator = Distribution.Normal().mean(0).deviation(1).seed(0xCAFE)

Just call Generator.next() method to get a new pseudo-random number.

    generator.next() //Output a random number

This library also provide some miscelleanous functions to manage sets of values.

You may want create an alias for convenience :

    let Utilities = Lowlight.Random.Utilities

Utilities.shuffle(array, seed) method shuffles an array (it doesn't modify the original one) or a string.

    Utilities.shuffle([67, 65, 70, 69], 0) //Output [70, 69, 65, 67]
    Utilities.shuffle("cafe", 0) //Output "feac"

Utilities.sample(array, length, replace, seed) method sample values from an array or a string. You may specify which length you want for your sampled array and also if values should be replaced in set of possible drawable values.

    Utilities.sample([67, 65, 70, 69], 3, false, 0) //Output [67, 69, 65]
    Utilities.sample([67, 65, 70, 69], 6, true, 0) //Output [67, 69, 67, 69, 67, 67]

Utilities.choice(array, seed) method is equivalent to Utilities.sample(array, 1).

    Utilities.choice([67, 65, 70, 69], 0) //Output 67

You'll need to run the following command the first time to install dependencies.

npm install

Then to rebuild project, just run the following command :

npm run build

This will update /bin files with included /src files. Although package.json (which contains "source" and "output" paths) are preconfigured, you may need to reconfigure them if you're planning to expand this library.

To include a file just use the following syntax in the "source" file :

    /* #include <path/to/file.js> */

• File minification is performed with Babel minify.
• Documentation is generated with JSDoc 3.

Although package.json (which contains "jsdoc_source", "jsdoc_output", "jsdoc_config" and "jsdoc_readme") and docs/categories.json are preconfigured, you may need to reconfigure them if you're planning to expand this library.

This project is licensed under the MIT License.

See LICENSE.md file for details.