package xoshiro

  1. Overview
  2. Docs

Xoshiro

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++/xoshiro256** generators have a period of 2²⁵⁶-1.
  • pass more tests: xoshiro256++/xoshiro256** pass the whole BigCrush test suite while the Random module of the standard library systematically fails some of the tests.
  • run similarly fast for the bindings and twice slower for the pure implementation.

This module and all the variants (see below) 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:

  • use Xoshiro.bits instead of Random.bits
  • (same for int, bool, etc. and also for the State submodule)
  • use open Xoshiro instead of open Random
  • or even write module Random = Xoshiro at the beginning of every file.

Variants

David Blackman and Sebastiano Vigna present several variants of their generators depending on the state size and implementation details.

module Xoshiro256plusplus : sig ... end

Default

The module Xoshiro includes by default an implementation of Xoshiro256plusplus.

include module type of Xoshiro256plusplus
include MakeRandom.Sig.Full
val init : int -> unit

Initialize the generator, using the argument as a seed. The same seed will always yield the same sequence of numbers.

val full_init : int array -> unit

Same as init but takes more data as seed.

val self_init : unit -> unit

Initialize the generator with a random seed chosen in a system-dependent way. If /dev/urandom is available on the host machine, it is used to provide a highly random initial seed. Otherwise, a less random seed is computed from system parameters (current time, process IDs).

include MakeRandom.Sig.Basic
val bits : unit -> int

Return 30 random bits in a nonnegative integer.

val int : int -> int

int bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 0 and less than 230.

val int32 : Stdlib.Int32.t -> Stdlib.Int32.t

int32 bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 0.

val nativeint : Stdlib.Nativeint.t -> Stdlib.Nativeint.t

nativeint bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 0.

val int64 : Stdlib.Int64.t -> Stdlib.Int64.t

int64 bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 0.

val float : float -> float

float bound returns a random floating-point number between 0 and bound (inclusive). If bound is negative, the result is negative or zero. If bound is 0, the result is 0.

val bool : unit -> bool

bool () returns true or false with probability 0.5 each.

Advanced functions

The functions from module State manipulate the current state of the random generator explicitly. This allows using one or several deterministic PRNGs, even in a multi-threaded program, without interference from other parts of the program.

module State : sig ... end
val get_state : unit -> State.t

Return the current state of the generator used by the basic functions.

val set_state : State.t -> unit

Set the state of the generator used by the basic functions.

Low-level Interface

Direct bindings of the functions provided in the original implementation.

module LowLevel : sig ... end

Others