ppad-random-0.1.0: Fast random number generators.
Copyright(c) 2026 Jared Tobin
LicenseMIT
MaintainerJared Tobin <jared@ppad.tech>
Safe HaskellNone
LanguageHaskell2010

Crypto.PRNG

Description

A fast, non-cryptographic pseudorandom number generator: xoshiro256++, by David Blackman and Sebastiano Vigna.

The generator is mutable, living in any PrimMonad (e.g. IO or 'ST s'), and is not thread-safe. Use one generator per thread, deriving non-overlapping streams via copy and jump or long_jump.

Its output is predictable from a small sample; use Crypto.CSPRNG for anything that must be unpredictable. Crypto.PRNG.Pure offers the same generator, with the same output, as an immutable value.

Synopsis

Generator

data Gen s Source #

A xoshiro256++ generator.

new :: PrimMonad m => Word64 -> m (Gen (PrimState m)) Source #

Create a generator from a 64-bit seed, expanded to the full 256-bit state via splitmix64, per the xoshiro authors' recommendation.

>>> gen <- new 42
>>> word64 gen
15021278609987233951

new_system :: IO (Maybe (Gen RealWorld)) Source #

Create a generator with a 256-bit state drawn from the operating system's entropy source, returning Nothing if that fails.

>>> Just gen <- new_system

from_state :: PrimMonad m => Word64 -> Word64 -> Word64 -> Word64 -> m (Maybe (Gen (PrimState m))) Source #

Create a generator from the given 256-bit state, returning Nothing if it is all zero.

>>> Just gen <- from_state 1 2 3 4
>>> word64 gen
41943041

Output

word64 :: PrimMonad m => Gen (PrimState m) -> m Word64 Source #

Generate a uniformly-distributed Word64.

>>> Just gen <- from_state 1 2 3 4
>>> word64 gen
41943041
>>> word64 gen
58720359

word64_range :: PrimMonad m => Word64 -> Word64 -> Gen (PrimState m) -> m Word64 Source #

Generate a uniformly-distributed Word64 in the given inclusive range, whose bounds may be given in either order.

The result is unbiased; see int_range.

>>> gen <- new 42
>>> word64_range 1 6 gen
5

int_range :: PrimMonad m => Int -> Int -> Gen (PrimState m) -> m Int Source #

Generate a uniformly-distributed Int in the given inclusive range, whose bounds may be given in either order.

The result is unbiased, via Lemire's method: an occasional draw is rejected and replaced, so the number of words consumed varies.

>>> gen <- new 42
>>> int_range (-10) 10 gen
7

double :: PrimMonad m => Gen (PrimState m) -> m Double Source #

Generate a uniformly-distributed Double in [0, 1), from the upper 53 bits of a Word64.

>>> Just gen <- from_state 1 2 3 4
>>> double gen
2.2737367544323206e-12

Streams

copy :: PrimMonad m => Gen (PrimState m) -> m (Gen (PrimState m)) Source #

Copy a generator. The copy produces the same output as the original, independently of it.

>>> gen <- new 42
>>> cop <- copy gen
>>> (==) <$> word64 gen <*> word64 cop
True

jump :: PrimMonad m => Gen (PrimState m) -> m () Source #

Advance a generator by 2 ^ 128 outputs.

Copying and then jumping repeatedly yields up to 2 ^ 128 non-overlapping streams of 2 ^ 128 outputs each, e.g. one per thread.

>>> gen <- new 42
>>> one <- copy gen
>>> jump gen
>>> two <- copy gen
>>> jump gen

long_jump :: PrimMonad m => Gen (PrimState m) -> m () Source #

Advance a generator by 2 ^ 192 outputs.

Copying and long-jumping repeatedly yields up to 2 ^ 64 starting points, from each of which jump yields 2 ^ 64 non-overlapping streams.

>>> gen <- new 42
>>> long_jump gen