random state
1.0.1Portable random number generation.
About randomstate
This is a collection of pseudo random number generators (PRNGs) and quasirandom number generators (QRNGs). While Common Lisp does provide a RANDOM
function, it does not allow the user to pass an explicit seed, nor to portably exchange the random state between implementations. This can be a headache in cases like games, where a controlled seeding process is very useful.
How To
For both curiosity and convenience, this library offers multiple algorithms to generate random numbers, as well as a bunch of generally useful methods to produce desired ranges.
(loop with generator = (randomstate:makegenerator :mersennetwister32 123)
repeat 10
collect (randomstate:randomint generator 0 10))
; => (8 10 9 5 3 10 9 2 9 2)
Several methods to compute random numbers in certain ranges are provided in advance: randombyte
, randombytes
, randomsequence
, randomunit
, randomfloat
, and randomint
. Each of those can also be used with just the name of the generator you'd like to use as the first argument, in which case a global instance will be used.
For generators that are hashbased, such as squirrel
, additional noise functions are provided: random1d
, random2d
, and random3d
, and some functions to manipulate the stepping of the generator: index
, and rewind
.
Implementations
The following algorithms are currently implemented:
Adler
Cityhash
Generic QRNG
Hammersley
KISS
Linear Congruence
Mersenne Twister
Middle Square
Murmurhash
PCG
RC4
Sobol
Squirrelhash
TT800
XKCD
Xorshift / Yorshift RNGs
The protocol also implements a fallback to the implementation's own randomstate
.
System Information
Definition Index

RANDOMSTATE
 ORG.SHIRAKUMO.RANDOMSTATE
No documentation provided.
EXTERNAL SPECIALVARIABLE *GENERATOR*
The default random number generator used by RANDOM. See RANDOM

EXTERNAL STRUCTURE ADLER32
An RNG based on the Adler32 hash. See https://en.wikipedia.org/wiki/Adler32

EXTERNAL STRUCTURE CITYHASH64
An RNG based on the 64bit CityHash. See https://github.com/google/cityhash

EXTERNAL STRUCTURE GENERATOR
General class for any random number generator. See LISTGENERATORTYPES See SEED See RESEED See NEXTBYTE See BITSPERBYTE See COPY See MULTIVARIATEP See MAKEGENERATOR See STATEFULGENERATOR See HASHGENERATOR

EXTERNAL STRUCTURE HAMMERSLEY
The Hammersley quasirandom number sequence. This is a multivariate generator with default dimensionality of 3. To change the dimensionality, pass a :LEAP initarg that is an array of the desired dimensionality. Each element in the LEAP array should be an integer greater or equal to 1, and can be used to advance the sequence more quickly for each dimension. See https://en.wikipedia.org/wiki/Lowdiscrepancy_sequence

EXTERNAL STRUCTURE HASHGENERATOR

EXTERNAL STRUCTURE KISS11
An implementation of the Kiss11 RNG. See https://eprint.iacr.org/2011/007.pdf

EXTERNAL STRUCTURE LINEARCONGRUENCE
A very simple random number generator based on linear congruence. See https://en.wikipedia.org/wiki/Linear_congruential_generator

EXTERNAL STRUCTURE MERSENNETWISTER32
The defacto standard random number generator algorithm. See https://en.wikipedia.org/wiki/Mersenne_Twister See http://www.acclab.helsinki.fi/~knordlun/mc/mt19937.c

EXTERNAL STRUCTURE MERSENNETWISTER64
A 64 bit variant of the Mersenne Twister algorithm. See MERSENNETWISTER32 See http://www.math.sci.hiroshimau.ac.jp/~mmat/MT/VERSIONS/CLANG/mt1993764.c

EXTERNAL STRUCTURE MIDDLESQUARE
An incredibly primitive, and basically in practise useless, random number algorithm. See https://en.wikipedia.org/wiki/Middlesquare_method

EXTERNAL STRUCTURE MURMURHASH3
A hashbased RNG using the Murmurhash3 method. See https://en.wikipedia.org/wiki/MurmurHash

EXTERNAL STRUCTURE PCG
An adaptation of the PCG rng. See http://www.pcgrandom.org

EXTERNAL STRUCTURE QUASI
A quasirandom number generator based on a uniform RNG. When constructing the generator you may pass the :SOURCE initarg, which should be a GENERATOR instance to use as a source of randomness. By default the current value of *GENERATOR* is used. See https://en.wikipedia.org/wiki/Lowdiscrepancy_sequence

EXTERNAL STRUCTURE RC4
The RC4 cryptographic random number generator. See https://en.wikipedia.org/wiki/RC4

EXTERNAL STRUCTURE SOBOL
The Sobol quasirandom number sequence. This is a multivariate generator with default dimensionality of 3. You can pass the :DIM initarg to specify the dimensionality of the result. :DIM must be in [ 1, 1111 [ See https://en.wikipedia.org/wiki/Lowdiscrepancy_sequence

EXTERNAL STRUCTURE SQUIRREL
An adaptation of the "squirrel hash v3". See https://www.youtube.com/watch?v=LWFzPP8ZbdU

EXTERNAL STRUCTURE STATEFULGENERATOR
Superclass for all generators that rely on state to produce random numbers. See GENERATOR

EXTERNAL STRUCTURE TT800
The predecessor to the Mersenne Twister algorithm. See http://random.mat.sbg.ac.at/publics/ftp/pub/data/tt800.c

EXTERNAL STRUCTURE XKCD
XKCD221 random number generator See https://xkcd.com/221/

EXTERNAL STRUCTURE XORSHIFT1024*
Sixteen 64bit word state variation of XORSHIFT64*. See XORSHIFT64*

EXTERNAL STRUCTURE XORSHIFT128
The four times 32bit word state variant of the Xorshift algorithm. See XORSHIFT32

EXTERNAL STRUCTURE XORSHIFT128+
Nonlinear double 64bit state variant of XORSHIFT64 that's currently the standard on modern browsers' JavaScript engines. See XORSHIFT64 See https://en.wikipedia.org/wiki/Xorshift#xorshift+ See https://v8.dev/blog/mathrandom

EXTERNAL STRUCTURE XORSHIFT32
Linear 32bit word state shiftregister generator. See https://en.wikipedia.org/wiki/Xorshift See https://www.jstatsoft.org/article/view/v008i14

EXTERNAL STRUCTURE XORSHIFT64
The 64bit variant of the Xorshift algorithm.. See XORSHIFT32

EXTERNAL STRUCTURE XORSHIFT64*
Nonlinear variation of XORSHIFT64 by adding a modulo multiplier. See XORSHIFT64 See https://en.wikipedia.org/wiki/Xorshift#xorshift*

EXTERNAL STRUCTURE XORWOW
Nonlinear five times 32bit word state shiftregister generator. See XORSHIFT128 See https://en.wikipedia.org/wiki/Xorshift#xorwow

EXTERNAL STRUCTURE XOSHIRO128**
32bit variant of XOSHIRO256**. See XOSHIRO256** See https://prng.di.unimi.it/xoshiro128starstar.c

EXTERNAL STRUCTURE XOSHIRO128+
32bit variant of XOSHIRO256+. See XOSHIRO256+ See https://prng.di.unimi.it/xoshiro128plus.c

EXTERNAL STRUCTURE XOSHIRO256**
Nonlinear rotating generalpurpose 64bit number algorithm. See https://prng.di.unimi.it/ See https://prng.di.unimi.it/xoshiro256starstar.c See https://en.wikipedia.org/wiki/Xorshift#xoshiro

EXTERNAL STRUCTURE XOSHIRO256+
Slightly faster variant of XOSHIRO256++ meant solely for generating 64bit floatingpoint numbers by extracting the upper 53bits due to the linearity of the lower bits. See XOSHIRO256++ See https://prng.di.unimi.it/xoshiro256plus.c

EXTERNAL FUNCTION BENCHMARK
 RNG
 &KEY
 SAMPLES
 STREAM
Draw a number of samples from an NRG and determine how quickly it operates. Prints the duration, # samples, samples/s, and s/sample to STREAM. Returns samples/s. See BENCHMARKALL

EXTERNAL FUNCTION BENCHMARKALL
 &KEY
 SAMPLES
 STREAM
Run a benchmark for all known generator types. When completed, orders the the results from fastest to slowest and prints them to STREAM. If a generator fails to be benchmarked, its result is shown as 1. See BENCHMARK

EXTERNAL FUNCTION DRAW
 N
 &OPTIONAL
 GENERATOR
Returns a vector with N random samples in [0,1[. See ENSUREGENERATOR See RANDOMUNIT

EXTERNAL FUNCTION ENSUREGENERATOR
 GENERATORISH
Ensures the argument is an object usable for random number generation. See GLOBALGENERATOR See GENERATOR

EXTERNAL FUNCTION GLOBALGENERATOR
 NAME
Returns a global instance of a generator. You may also SETF this place to name specific generators of your own. See MAKEGENERATOR

EXTERNAL FUNCTION (SETF GLOBALGENERATOR)
 VALUE
 NAME
No documentation provided. 
EXTERNAL FUNCTION HISTOGRAM
 RNG
 BINS
 &KEY
 SAMPLES
 WIDTH
 STREAM
Compute a histogram from the given sample vector. This will collect the samples into N bins, where the value of the bin is the contribution of the samples in the bin towards all samples. See PRINTHISTOGRAM See DRAW

EXTERNAL FUNCTION HOPEFULLYSUFFICIENTLYRANDOMSEED
Attempts to find a sufficiently random seed. On Unix, this reads 64 bits from /dev/urandom On Windows+SBCL, this reads 64 bits from SBWIN32:CRYPTGENRANDOM Otherwise it uses an XOR of GETINTERNALREALTIME and GETUNIVERSALTIME.

EXTERNAL FUNCTION INDEX
 INSTANCE
Accesses the index of the hashgenerator. The index must be an (unsignedbyte 64). The index is advanced for each call to NEXTBYTE. See HASHGENERATOR

EXTERNAL FUNCTION (SETF INDEX)
 VALUE
 INSTANCE
No documentation provided. 
EXTERNAL FUNCTION LISTGENERATORTYPES
Lists the types of generators supported by the library. You may use any of these types to call MAKEGENERATOR with. See MAKEGENERATOR

EXTERNAL FUNCTION MAKEGENERATOR
 TYPE
 &OPTIONAL
 SEED
 &REST
 INITARGS

EXTERNAL FUNCTION MULTIVARIATEP
 GENERATOR

EXTERNAL FUNCTION PRINTHISTOGRAM
 HISTOGRAM
 &KEY
 STREAM
 WIDTH
Display the histogram vector in a userfriendly manner. Prints a visual representation of the deviation of each bin from the ideal uniform distribution as well as the cumulative deviation of all bins. See HISTOGRAM

EXTERNAL FUNCTION RANDOM
 MAX
 &OPTIONAL
 GENERATOR
Returns a number in [0, MAX[. This is a dropin replacement for CL:RANDOM. The returned type is the same as MAX, where MAX must be an INTEGER or a FLOAT greater than zero. The returned number must be smaller than MAX. GENERATOR may be anything accepted by ENSUREGENERATOR. See RANDOMINT See RANDOMFLOAT See ENSUREGENERATOR

EXTERNAL FUNCTION RANDOM1D
 GENERATOR
 INDEX
 &OPTIONAL
 SEED
Returns a byte for the given index and seed. This is only usable with HASHGENERATOR types. Does *NOT* advance the generator's index. See HASHGENERATOR See NEXTBYTE

EXTERNAL FUNCTION RANDOM2D
 GENERATOR
 X
 Y
 &OPTIONAL
 SEED
Returns a byte for the given location and seed. This is only usable with HASHGENERATOR types. Does *NOT* advance the generator's index. See HASHGENERATOR See NEXTBYTE

EXTERNAL FUNCTION RANDOM3D
 GENERATOR
 X
 Y
 Z
 &OPTIONAL
 SEED
Returns a byte for the given location and seed. This is only usable with HASHGENERATOR types. Does *NOT* advance the generator's index. See HASHGENERATOR See NEXTBYTE

EXTERNAL FUNCTION RANDOMBYTE
 GENERATOR

EXTERNAL FUNCTION RANDOMBYTES
 GENERATOR
 BITS

EXTERNAL FUNCTION RANDOMFLOAT
 GENERATOR
 FROM
 TO
Returns a random float in [FROM, TO]. The returned float is of the same type as whatever type is larger between FROM and TO. See GENERATOR See RANDOMUNIT

EXTERNAL FUNCTION RANDOMINT
 GENERATOR
 FROM
 TO
Returns a random integer in [FROM, TO]. See GENERATOR See RANDOMBYTES

EXTERNAL FUNCTION RANDOMSEQUENCE
 GENERATOR
 SEQUENCE
 &KEY
 START
 END
Fills SEQUENCE between START and END with random numbers. Note: it is up to you to ensure that SEQUENCE is capable of holding numbers returned by the generator's NEXTBYTE, and that doing so makes sense. As in, do not fill a vector with elementtype (unsignedbyte 8) with a generator whose BITSPERBYTE is 32 or viceversa. Equivalent to: (mapinto sequence (lambda () (nextbyte generator))) See GENERATOR See NEXTBYTE

EXTERNAL FUNCTION RANDOMUNIT
 GENERATOR
 &OPTIONAL
 TYPE
Returns a random float in [0, 1]. The returned float is of the type specified in TYPE. See GENERATOR See RANDOMBYTES

EXTERNAL GENERICFUNCTION BITSPERBYTE
 GENERATOR
Returns the number of bits of randomness returned by the generator for each NEXTBYTE call. This may either be an integer, describing the bits of randomness returned, the symbol SINGLEFLOAT or DOUBLEFLOAT in which case NEXTBYTE returns a unit float, or a list composed of the aforementioned, in which case NEXTBYTE returns an array of such bytes. See NEXTBYTE See GENERATOR

EXTERNAL GENERICFUNCTION COPY
 GENERATOR
Creates a fresh copy of the given generator. This copy will return an identical sequence of bytes as the original. Meaning, the following invariant holds true: (loop with copy = (copy generator) always (= (nextbyte generator) (nextbyte copy))) See GENERATOR

EXTERNAL GENERICFUNCTION NEXTBYTE
 GENERATOR
Returns the next byte (not octet) of random state. The value returned is in accordance to the spec of BITSPERBYTE. If the spec is an integer, the returned integer must be in the range of [ 0, 1 << BITSPERBYTE GENERATOR [ If the spec is SINGLEFLOAT or DOUBLEFLOAT, the returned float must be in the range of [ 0, 1 [ If the spec is a list, the returned value is an array with each of its elements according to the above description. See RANDOMINT See RANDOMBYTES See GENERATOR

EXTERNAL GENERICFUNCTION RESEED
 GENERATOR
 NEWSEED
Reset the RNG and seed it with the given seed number. If T is passed for the new seed, a random seed as determined by HOPEFULLYSUFFICIENTLYRANDOMSEED is used. See HOPEFULLYSUFFICIENTLYRANDOMSEED See GENERATOR

EXTERNAL GENERICFUNCTION REWIND
 HASHGENERATOR
 &OPTIONAL
 BY
Rewind the hashgenerator by BY numbers. The following invariant holds for any N: (= (nextbyte generator) (progn (rewind generator N) (loop repeat (1 N) (nextbyte generator)) (nextbyte generator))) See HASHGENERATOR

EXTERNAL GENERICFUNCTION SEED
 GENERATOR
Returns the seed that was used to initialise the generator. See GENERATOR

EXTERNAL MACRO DEFINEGENERATOR
 NAME
 BITSPERBYTE
 SUPER
 SLOTS
 &BODY
 BODIES
Define a new random number generator type. BITSPERBYTE is a form that should evaluate to the byte spec for the generator. SUPER should be a list of the following structure: SUPER ::= (type SLOT*) SLOT ::= (slotname initform) type  The structuretype name to use as supertype slotname  The name of a slot in the supertype initform  The initial value for the slot SLOTS should be a list of additional structure slot specs to hold the generator's state. BODIES should be any number of body expressions, each of which is a list composed of a body type and any number of body forms, each of which are evaluated in an environment where every specified slot in SLOTS as well as every specified supertype slot in SUPER is symbolmacroletbound to their respective name. The following body types are permitted: :COPY  Provides the body forms for the COPY function. The generator instance is bound to GENERATOR. If this body expression is not provided, a copy function based on the SLOTS is automatically provided for you. This must be provided for HASHGENERATORs. :RESEED  Provides the body forms for the RESEED function. The generator instance is bound to GENERATOR and the seed to SEED. This must be provided for STATEFULGENERATORs. :NEXT  Provides the body forms for the NEXTBYTE function. The generator instance is bound to GENERATOR. Must return a suitable byte for the generator. This must be provided for STATEFULGENERATORs. :HASH  Provides the stateless hashing function. The generator instance is notably NOT bound. However, the 64bit index to hash is bound to INDEX. This will also automatically provide the NEXTBYTE function for you. This must be provided for HASHGENERATORs. Each of the additional bindings in the body expressions is bound to a symbol from the current package. See BITSPERBYTE See RESEED See NEXTBYTE See HASH See COPY See HASHGENERATOR See STATEFULGENERATOR See GENERATOR

EXTERNAL SOURCETRANSFORM INDEX
No documentation provided. 
EXTERNAL SOURCETRANSFORM (SETF INDEX)
No documentation provided.