random state
1.0.1Portable random number generation.
About random-state
This is a collection of pseudo random number generators (PRNGs) and quasi-random 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 = (random-state:make-generator :mersenne-twister-32 123)
2 | repeat 10
3 | collect (random-state:random-int generator 0 10))
4 | ; => (8 10 9 5 3 10 9 2 9 2)
Several methods to compute random numbers in certain ranges are provided in advance: random-byte, random-bytes, random-sequence, random-unit, random-float, and random-int. 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 hash-based, such as squirrel, additional noise functions are provided: random-1d, random-2d, and random-3d, 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 random-state.
System Information
Definition Index
-
RANDOM-STATE
- ORG.SHIRAKUMO.RANDOM-STATE
No documentation provided.-
EXTERNAL SPECIAL-VARIABLE *GENERATOR*
The default random number generator used by RANDOM. 5 | 6 | See RANDOM
-
EXTERNAL STRUCTURE ADLER32
An RNG based on the Adler32 hash. 7 | 8 | See https://en.wikipedia.org/wiki/Adler-32
-
EXTERNAL STRUCTURE CITYHASH-64
An RNG based on the 64-bit CityHash. 9 | 10 | See https://github.com/google/cityhash
-
EXTERNAL STRUCTURE GENERATOR
General class for any random number generator. 11 | 12 | See LIST-GENERATOR-TYPES 13 | See SEED 14 | See RESEED 15 | See NEXT-BYTE 16 | See BITS-PER-BYTE 17 | See COPY 18 | See MULTIVARIATE-P 19 | See MAKE-GENERATOR 20 | See STATEFUL-GENERATOR 21 | See HASH-GENERATOR
-
EXTERNAL STRUCTURE HAMMERSLEY
The Hammersley quasi-random number sequence. 22 | 23 | This is a multivariate generator with default dimensionality of 3. 24 | To change the dimensionality, pass a :LEAP initarg that is an array of 25 | the desired dimensionality. Each element in the LEAP array should be 26 | an integer greater or equal to 1, and can be used to advance the 27 | sequence more quickly for each dimension. 28 | 29 | See https://en.wikipedia.org/wiki/Low-discrepancy_sequence
-
EXTERNAL STRUCTURE HASH-GENERATOR
-
EXTERNAL STRUCTURE KISS11
An implementation of the Kiss11 RNG. 38 | 39 | See https://eprint.iacr.org/2011/007.pdf
-
EXTERNAL STRUCTURE LINEAR-CONGRUENCE
A very simple random number generator based on linear congruence. 40 | 41 | See https://en.wikipedia.org/wiki/Linear_congruential_generator
-
EXTERNAL STRUCTURE MERSENNE-TWISTER-32
The de-facto standard random number generator algorithm. 42 | 43 | See https://en.wikipedia.org/wiki/Mersenne_Twister 44 | See http://www.acclab.helsinki.fi/~knordlun/mc/mt19937.c
-
EXTERNAL STRUCTURE MERSENNE-TWISTER-64
A 64 bit variant of the Mersenne Twister algorithm. 45 | 46 | See MERSENNE-TWISTER-32 47 | See http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/VERSIONS/C-LANG/mt19937-64.c
-
EXTERNAL STRUCTURE MIDDLE-SQUARE
An incredibly primitive, and basically in practise useless, random number algorithm. 48 | 49 | See https://en.wikipedia.org/wiki/Middle-square_method
-
EXTERNAL STRUCTURE MURMURHASH3
A hash-based RNG using the Murmurhash3 method. 50 | 51 | See https://en.wikipedia.org/wiki/MurmurHash
-
EXTERNAL STRUCTURE PCG
An adaptation of the PCG rng. 52 | 53 | See http://www.pcg-random.org
-
EXTERNAL STRUCTURE QUASI
A quasi-random number generator based on a uniform RNG. 54 | 55 | When constructing the generator you may pass the :SOURCE initarg, 56 | which should be a GENERATOR instance to use as a source of 57 | randomness. By default the current value of *GENERATOR* is used. 58 | 59 | See https://en.wikipedia.org/wiki/Low-discrepancy_sequence
-
EXTERNAL STRUCTURE RC4
The RC4 cryptographic random number generator. 60 | 61 | See https://en.wikipedia.org/wiki/RC4
-
EXTERNAL STRUCTURE SOBOL
The Sobol quasi-random number sequence. 62 | 63 | This is a multivariate generator with default dimensionality of 3. 64 | You can pass the :DIM initarg to specify the dimensionality of the 65 | result. :DIM must be in [ 1, 1111 [ 66 | 67 | See https://en.wikipedia.org/wiki/Low-discrepancy_sequence
-
EXTERNAL STRUCTURE SQUIRREL
An adaptation of the "squirrel hash v3". 68 | 69 | See https://www.youtube.com/watch?v=LWFzPP8ZbdU
-
EXTERNAL STRUCTURE STATEFUL-GENERATOR
Superclass for all generators that rely on state to produce random numbers. 70 | 71 | See GENERATOR
-
EXTERNAL STRUCTURE TT800
The predecessor to the Mersenne Twister algorithm. 72 | 73 | See http://random.mat.sbg.ac.at/publics/ftp/pub/data/tt800.c
-
EXTERNAL STRUCTURE XKCD
XKCD-221 random number generator 74 | 75 | See https://xkcd.com/221/
-
EXTERNAL STRUCTURE XORSHIFT-1024*
Sixteen 64-bit word state variation of XORSHIFT-64*. 76 | 77 | See XORSHIFT-64*
-
EXTERNAL STRUCTURE XORSHIFT-128
The four times 32-bit word state variant of the Xorshift algorithm. 78 | 79 | See XORSHIFT-32
-
EXTERNAL STRUCTURE XORSHIFT-128+
Non-linear double 64-bit state variant of XORSHIFT-64 that's currently the standard on modern browsers' JavaScript engines. 80 | 81 | See XORSHIFT-64 82 | See https://en.wikipedia.org/wiki/Xorshift#xorshift+ 83 | See https://v8.dev/blog/math-random
-
EXTERNAL STRUCTURE XORSHIFT-32
Linear 32-bit word state shift-register generator. 84 | 85 | See https://en.wikipedia.org/wiki/Xorshift 86 | See https://www.jstatsoft.org/article/view/v008i14
-
EXTERNAL STRUCTURE XORSHIFT-64
The 64-bit variant of the Xorshift algorithm.. 87 | 88 | See XORSHIFT-32
-
EXTERNAL STRUCTURE XORSHIFT-64*
Non-linear variation of XORSHIFT-64 by adding a modulo multiplier. 89 | 90 | See XORSHIFT-64 91 | See https://en.wikipedia.org/wiki/Xorshift#xorshift*
-
EXTERNAL STRUCTURE XORWOW
Non-linear five times 32-bit word state shift-register generator. 92 | 93 | See XORSHIFT-128 94 | See https://en.wikipedia.org/wiki/Xorshift#xorwow
-
EXTERNAL STRUCTURE XOSHIRO-128**
32-bit variant of XOSHIRO-256**. 95 | 96 | See XOSHIRO-256** 97 | See https://prng.di.unimi.it/xoshiro128starstar.c
-
EXTERNAL STRUCTURE XOSHIRO-128+
32-bit variant of XOSHIRO-256+. 98 | 99 | See XOSHIRO-256+ 100 | See https://prng.di.unimi.it/xoshiro128plus.c
-
EXTERNAL STRUCTURE XOSHIRO-256**
Non-linear rotating general-purpose 64-bit number algorithm. 101 | 102 | See https://prng.di.unimi.it/ 103 | See https://prng.di.unimi.it/xoshiro256starstar.c 104 | See https://en.wikipedia.org/wiki/Xorshift#xoshiro
-
EXTERNAL STRUCTURE XOSHIRO-256+
Slightly faster variant of XOSHIRO-256++ meant solely for generating 64-bit floating-point numbers by extracting the upper 53-bits due to the linearity of the lower bits. 105 | 106 | See XOSHIRO-256++ 107 | 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. 108 | 109 | Prints the duration, # samples, samples/s, and s/sample to STREAM. 110 | Returns samples/s. 111 | 112 | See BENCHMARK-ALL
-
EXTERNAL FUNCTION BENCHMARK-ALL
- &KEY
- SAMPLES
- STREAM
Run a benchmark for all known generator types. 113 | 114 | When completed, orders the the results from fastest to slowest and 115 | prints them to STREAM. If a generator fails to be benchmarked, its 116 | result is shown as -1. 117 | 118 | See BENCHMARK
-
EXTERNAL FUNCTION DRAW
- N
- &OPTIONAL
- GENERATOR
Returns a vector with N random samples in [0,1[. 119 | 120 | See ENSURE-GENERATOR 121 | See RANDOM-UNIT
-
EXTERNAL FUNCTION ENSURE-GENERATOR
- GENERATOR-ISH
Ensures the argument is an object usable for random number generation. 122 | 123 | See GLOBAL-GENERATOR 124 | See GENERATOR
-
EXTERNAL FUNCTION GLOBAL-GENERATOR
- NAME
Returns a global instance of a generator. 125 | 126 | You may also SETF this place to name specific generators of your own. 127 | 128 | See MAKE-GENERATOR
-
EXTERNAL FUNCTION (SETF GLOBAL-GENERATOR)
- VALUE
- NAME
No documentation provided. -
EXTERNAL FUNCTION HISTOGRAM
- RNG
- BINS
- &KEY
- SAMPLES
- WIDTH
- STREAM
Compute a histogram from the given sample vector. 129 | 130 | This will collect the samples into N bins, where the value of the bin 131 | is the contribution of the samples in the bin towards all samples. 132 | 133 | See PRINT-HISTOGRAM 134 | See DRAW
-
EXTERNAL FUNCTION HOPEFULLY-SUFFICIENTLY-RANDOM-SEED
Attempts to find a sufficiently random seed. 135 | 136 | On Unix, this reads 64 bits from /dev/urandom 137 | On Windows+SBCL, this reads 64 bits from SB-WIN32:CRYPT-GEN-RANDOM 138 | Otherwise it uses an XOR of GET-INTERNAL-REAL-TIME and GET-UNIVERSAL-TIME.
-
EXTERNAL FUNCTION INDEX
- INSTANCE
Accesses the index of the hash-generator. 139 | 140 | The index must be an (unsigned-byte 64). 141 | The index is advanced for each call to NEXT-BYTE. 142 | 143 | See HASH-GENERATOR
-
EXTERNAL FUNCTION (SETF INDEX)
- VALUE
- INSTANCE
No documentation provided. -
EXTERNAL FUNCTION LIST-GENERATOR-TYPES
Lists the types of generators supported by the library. 144 | 145 | You may use any of these types to call MAKE-GENERATOR with. 146 | 147 | See MAKE-GENERATOR
-
EXTERNAL FUNCTION MAKE-GENERATOR
- TYPE
- &OPTIONAL
- SEED
- &REST
- INITARGS
-
EXTERNAL FUNCTION MULTIVARIATE-P
- GENERATOR
-
EXTERNAL FUNCTION PRINT-HISTOGRAM
- HISTOGRAM
- &KEY
- STREAM
- WIDTH
Display the histogram vector in a user-friendly manner. 158 | 159 | Prints a visual representation of the deviation of each bin from the 160 | ideal uniform distribution as well as the cumulative deviation of all 161 | bins. 162 | 163 | See HISTOGRAM
-
EXTERNAL FUNCTION RANDOM
- MAX
- &OPTIONAL
- GENERATOR
Returns a number in [0, MAX[. 164 | 165 | This is a drop-in replacement for CL:RANDOM. 166 | The returned type is the same as MAX, where MAX must be an INTEGER or 167 | a FLOAT greater than zero. The returned number must be smaller than MAX. 168 | 169 | GENERATOR may be anything accepted by ENSURE-GENERATOR. 170 | 171 | See RANDOM-INT 172 | See RANDOM-FLOAT 173 | See ENSURE-GENERATOR
-
EXTERNAL FUNCTION RANDOM-1D
- GENERATOR
- INDEX
- &OPTIONAL
- SEED
Returns a byte for the given index and seed. 174 | 175 | This is only usable with HASH-GENERATOR types. 176 | Does *NOT* advance the generator's index. 177 | 178 | See HASH-GENERATOR 179 | See NEXT-BYTE
-
EXTERNAL FUNCTION RANDOM-2D
- GENERATOR
- X
- Y
- &OPTIONAL
- SEED
Returns a byte for the given location and seed. 180 | 181 | This is only usable with HASH-GENERATOR types. 182 | Does *NOT* advance the generator's index. 183 | 184 | See HASH-GENERATOR 185 | See NEXT-BYTE
-
EXTERNAL FUNCTION RANDOM-3D
- GENERATOR
- X
- Y
- Z
- &OPTIONAL
- SEED
Returns a byte for the given location and seed. 186 | 187 | This is only usable with HASH-GENERATOR types. 188 | Does *NOT* advance the generator's index. 189 | 190 | See HASH-GENERATOR 191 | See NEXT-BYTE
-
EXTERNAL FUNCTION RANDOM-BYTE
- GENERATOR
-
EXTERNAL FUNCTION RANDOM-BYTES
- GENERATOR
- BITS
-
EXTERNAL FUNCTION RANDOM-FLOAT
- GENERATOR
- FROM
- TO
Returns a random float in [FROM, TO]. 200 | 201 | The returned float is of the same type as whatever type is larger 202 | between FROM and TO. 203 | 204 | See GENERATOR 205 | See RANDOM-UNIT
-
EXTERNAL FUNCTION RANDOM-INT
- GENERATOR
- FROM
- TO
Returns a random integer in [FROM, TO]. 206 | 207 | See GENERATOR 208 | See RANDOM-BYTES
-
EXTERNAL FUNCTION RANDOM-SEQUENCE
- GENERATOR
- SEQUENCE
- &KEY
- START
- END
Fills SEQUENCE between START and END with random numbers. 209 | 210 | Note: it is up to you to ensure that SEQUENCE is capable of holding 211 | numbers returned by the generator's NEXT-BYTE, and that doing so makes 212 | sense. As in, do not fill a vector with element-type (unsigned-byte 8) 213 | with a generator whose BITS-PER-BYTE is 32 or vice-versa. 214 | 215 | Equivalent to: 216 | 217 | (map-into sequence (lambda () (next-byte generator))) 218 | 219 | See GENERATOR 220 | See NEXT-BYTE
-
EXTERNAL FUNCTION RANDOM-UNIT
- GENERATOR
- &OPTIONAL
- TYPE
Returns a random float in [0, 1]. 221 | 222 | The returned float is of the type specified in TYPE. 223 | 224 | See GENERATOR 225 | See RANDOM-BYTES
-
EXTERNAL GENERIC-FUNCTION BITS-PER-BYTE
- GENERATOR
Returns the number of bits of randomness returned by the generator for each NEXT-BYTE call. 226 | 227 | This may either be an integer, describing the bits of randomness returned, 228 | the symbol SINGLE-FLOAT or DOUBLE-FLOAT in which case NEXT-BYTE returns a unit float, 229 | or a list composed of the aforementioned, in which case NEXT-BYTE returns an array 230 | of such bytes. 231 | 232 | See NEXT-BYTE 233 | See GENERATOR
-
EXTERNAL GENERIC-FUNCTION COPY
- GENERATOR
Creates a fresh copy of the given generator. 234 | 235 | This copy will return an identical sequence of bytes as the 236 | original. Meaning, the following invariant holds true: 237 | 238 | (loop with copy = (copy generator) always (= (next-byte generator) (next-byte copy))) 239 | 240 | See GENERATOR
-
EXTERNAL GENERIC-FUNCTION NEXT-BYTE
- GENERATOR
Returns the next byte (not octet) of random state. 241 | 242 | The value returned is in accordance to the spec of BITS-PER-BYTE. 243 | If the spec is an integer, the returned integer must be in the range 244 | of 245 | 246 | [ 0, 1 << BITS-PER-BYTE GENERATOR [ 247 | 248 | If the spec is SINGLE-FLOAT or DOUBLE-FLOAT, the returned float must 249 | be in the range of 250 | 251 | [ 0, 1 [ 252 | 253 | If the spec is a list, the returned value is an array with each of its 254 | elements according to the above description. 255 | 256 | See RANDOM-INT 257 | See RANDOM-BYTES 258 | See GENERATOR
-
EXTERNAL GENERIC-FUNCTION RESEED
- GENERATOR
- NEW-SEED
Reset the RNG and seed it with the given seed number. 259 | 260 | If T is passed for the new seed, a random seed as determined by 261 | HOPEFULLY-SUFFICIENTLY-RANDOM-SEED is used. 262 | 263 | See HOPEFULLY-SUFFICIENTLY-RANDOM-SEED 264 | See GENERATOR
-
EXTERNAL GENERIC-FUNCTION REWIND
- HASH-GENERATOR
- &OPTIONAL
- BY
Rewind the hash-generator by BY numbers. 265 | 266 | The following invariant holds for any N: 267 | 268 | (= (next-byte generator) (progn (rewind generator N) (loop repeat (1- N) (next-byte generator)) (next-byte generator))) 269 | 270 | See HASH-GENERATOR
-
EXTERNAL GENERIC-FUNCTION SEED
- GENERATOR
Returns the seed that was used to initialise the generator. 271 | 272 | See GENERATOR
-
EXTERNAL MACRO DEFINE-GENERATOR
- NAME
- BITS-PER-BYTE
- SUPER
- SLOTS
- &BODY
- BODIES
Define a new random number generator type. 273 | 274 | BITS-PER-BYTE is a form that should evaluate to the byte spec for the 275 | generator. 276 | 277 | SUPER should be a list of the following structure: 278 | 279 | SUPER ::= (type SLOT*) 280 | SLOT ::= (slot-name initform) 281 | type --- The structure-type name to use as supertype 282 | slot-name --- The name of a slot in the supertype 283 | initform --- The initial value for the slot 284 | 285 | SLOTS should be a list of additional structure slot specs to hold the 286 | generator's state. 287 | 288 | BODIES should be any number of body expressions, each of which is a 289 | list composed of a body type and any number of body forms, each of 290 | which are evaluated in an environment where every specified slot in 291 | SLOTS as well as every specified supertype slot in SUPER is 292 | symbol-macrolet-bound to their respective name. The following body 293 | types are permitted: 294 | 295 | :COPY --- Provides the body forms for the COPY function. The 296 | generator instance is bound to GENERATOR. If this body 297 | expression is not provided, a copy function based on the 298 | SLOTS is automatically provided for you. 299 | This must be provided for HASH-GENERATORs. 300 | :RESEED --- Provides the body forms for the RESEED function. The 301 | generator instance is bound to GENERATOR and the seed to 302 | SEED. 303 | This must be provided for STATEFUL-GENERATORs. 304 | :NEXT --- Provides the body forms for the NEXT-BYTE function. The 305 | generator instance is bound to GENERATOR. Must return a 306 | suitable byte for the generator. 307 | This must be provided for STATEFUL-GENERATORs. 308 | :HASH --- Provides the stateless hashing function. The generator 309 | instance is notably NOT bound. However, the 64-bit index 310 | to hash is bound to INDEX. This will also automatically 311 | provide the NEXT-BYTE function for you. 312 | This must be provided for HASH-GENERATORs. 313 | 314 | Each of the additional bindings in the body expressions is bound to a 315 | symbol from the current package. 316 | 317 | See BITS-PER-BYTE 318 | See RESEED 319 | See NEXT-BYTE 320 | See HASH 321 | See COPY 322 | See HASH-GENERATOR 323 | See STATEFUL-GENERATOR 324 | See GENERATOR
-
EXTERNAL SOURCE-TRANSFORM INDEX
No documentation provided. -
EXTERNAL SOURCE-TRANSFORM (SETF INDEX)
No documentation provided.