This package provides the Xoshiro family of pseudo-random number generators for OCaml, with an interface mimmicing that of the standard library. The Xoshiro generator are not cryptographically safe, but they provide better randomness than the standard library.
By default, this package comes as C bindings for efficiency. If bindings are not welcome (eg. to compile to JS), one may depend on xoshiro.pure instead, providing the exact same interface, implemented as pure OCaml.
Published: 30 Jun 2021
This library includes OCaml implementation of some pseudorandom number generators (PRNGs) designed by David Blackman and Sebastiano Vigna behind an interface that mimmics that of the
Random module of the standard library.
The Xoshiro generators (for XOR/shift/rotate) are all-purpose generators (not cryptographically secure). Compared to the standard library, they:
have a bigger state space:
xoshiro256**generators have a period of 2²⁵⁶-1.
pass more tests:
xoshiro256**pass the whole BigCrush test suite while the
Randommodule of the standard library systematically fails some of the tests.
The modules in this library are drop-in replacements of the
Random module of the standard library. This means you can use
Xoshiro everywhere where you would use
Random. For instance:
bool, etc. and also for the
open Xoshiroinstead of
or even write
module Random = Xoshiroat the beginning of every file.
Bindings vs. Pure
xoshiro.pure. By default,
xoshiro depends on
For instance, say you have an executable
crazyrandom which uses the standard
Random module as source of randomness. You can easily switch to using
Xoshiro instead by replacing all occurrences of
Xoshiro (a simple search and replace should do the trick). You can then compile your executable with a Dune file similar to:
crazyrandom.ml and change your Dune file to:
We recommend installing via OPAM with
opam install xoshiro. Otherwise,
make followed by
make install should do the trick, provided you have the required dependencies.
Documentation is available online. It can also be built locally with
make doc and by pointing a browser to
Tests & Benchmarks
The library comes with a set of tests and benchmarks. Tests are ran at every push to the repository. The tests include:
checking that bindings and pure implementation yield the same bits;
checking that implementations comply with our claims with respect to the *Crush test batteries (note that, because of time considerations, only SmallCrush is ran in continuous integration).
checking that the
MakeRandomfunctors build the same interface as the standard library.
It is easy to run other test batteries on generators. For instance, one can run BigCrush on
xoshiro256++ by calling:
dune exec xoshiro256plusplus/test/crusher/crusher.exe -- --bigcrush --verbose
The benchmarks allow to compare various PRNGs from this library against each other and, more importantly, against the standard library. They can be ran using
dune exec bench/run.exe. For
xoshiro256++, we observe that the bindings are slightly slower than the standard library, and almost twice faster than the pure implementations.
Xavier Leroy's PRINGO, “pseudo-random number generators that support splitting and two interfaces: one stateful, one purely functional”. Xavier Leroy's work is very similar to ours: it provides new PRNGs for OCaml (including Split mix which we can also find in the package
xoshiro) in an interface similar to that of the standard library (although not exactly the same, contrary to what can be obtained with
Mirage's Crypto Library, including in particular the strong, cryptographically secure, PRNG Fortuna. This is further from our work as usage is really not the same.