random state
0.1.0Portable random number generation.
About random-state
This is a collection of pseudo random number generators (PRNGs). 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 can be 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)
repeat 10
collect (random-state:random-int generator 0 10))
=> (5 6 6 3 2 8 6 9 6 1)
The library does make some efforts to be reasonably efficient while preserving usability, but each of the implementations could be optimised further. For performance critical sections, you might want to take matters into your own hands and only rely on random-byte
for the most direct access to the generator. If that still is not sufficiently fast, creating a tailored implementation of an algorithm based on the source code of this library should not be difficult.
Several methods to compute random numbers in certain ranges are provided in advance: random-byte
, random-bytes
, 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.
System Information
Definition Index
-
RANDOM-STATE
- ORG.SHIRAKUMO.RANDOM-STATE
No documentation provided.-
EXTERNAL CLASS GENERATOR
General class for any random number generator. See SEED See BYTES See MAKE-GENERATOR See RANDOM-BYTE See RANDOM-BYTES See RANDOM-UNIT See RANDOM-FLOAT See RANDOM-INT See RESEED
-
EXTERNAL CLASS LINEAR-CONGRUENCE
A very simple random number generator based on linear congruence. See https://en.wikipedia.org/wiki/Linear_congruential_generator
-
EXTERNAL CLASS MERSENNE-TWISTER-32
The de-facto standard random number generator algorithm. See https://en.wikipedia.org/wiki/Mersenne_Twister See http://www.acclab.helsinki.fi/~knordlun/mc/mt19937.c
-
EXTERNAL CLASS MERSENNE-TWISTER-64
A 64 bit variant of the Mersenne Twister algorithm. See MERSENNE-TWISTER-32 See http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/VERSIONS/C-LANG/mt19937-64.c
-
EXTERNAL CLASS MIDDLE-SQUARE
An incredibly primitive, and basically in practise useless, random number algorithm. See https://en.wikipedia.org/wiki/Middle-square_method
-
EXTERNAL CLASS PCG
An adaptation of the PCG rng. See http://www.pcg-random.org
-
EXTERNAL CLASS RC4
The RC4 cryptographic random number generator. See https://en.wikipedia.org/wiki/RC4
-
EXTERNAL CLASS TT800
The predecessor to the Mersenne Twister algorithm. See http://random.mat.sbg.ac.at/publics/ftp/pub/data/tt800.c
-
EXTERNAL FUNCTION GENERATOR-CLASS
- NAME
Attempts to find the named generator class. Accepts strings, symbols, and classes. If no generator can be found, an error is signalled.
-
EXTERNAL FUNCTION GLOBAL-GENERATOR
- NAME
Returns a global instance of a generator. See MAKE-GENERATOR
-
EXTERNAL FUNCTION HOPEFULLY-SUFFICIENTLY-RANDOM-SEED
Attempts to find a sufficiently random seed. On Unix, this reads 64 bits from /dev/urandom On Windows+SBCL, this reads 64 bits from SB-WIN32:CRYPT-GEN-RANDOM Otherwise it uses an XOR of GET-INTERNAL-REAL-TIME and GET-UNIVERSAL-TIME.
-
EXTERNAL FUNCTION MAKE-GENERATOR
- GENERATOR
- &OPTIONAL
- SEED
- &REST
- INITARGS
Creates a generator of the given type. The GENERATOR can be any name supported by GENERATOR-CLASS. SEED must be an integer. After construction, RESEED is called on the generator with the given SEED. Example: (random-state:make-generator :mersenne-twister-32 42) See GENERATOR-CLASS See RESEED
-
EXTERNAL GENERIC-FUNCTION BYTES
- OBJECT
Returns the number of bytes (bits) that a RANDOM-BYTE call of this generator produces.
-
EXTERNAL GENERIC-FUNCTION RANDOM-BYTE
- GENERATOR
-
EXTERNAL GENERIC-FUNCTION RANDOM-BYTES
- GENERATOR
- BYTES
Returns an integer of fresh random output from the generator. The integer is at most 2^(BYTES)-1 and at least 0. See GENERATOR See RANDOM-BYTE
-
EXTERNAL GENERIC-FUNCTION RANDOM-FLOAT
- GENERATOR
- FROM
- TO
Returns a float of fresh random output from the generator. The returned value is a double-float between FROM and TO. See GENERATOR
-
EXTERNAL GENERIC-FUNCTION RANDOM-INT
- GENERATOR
- FROM
- TO
Returns an integer of fresh random output from the generator. The returned value is an integer between FROM (inclusive) and TO (inclusive). See GENERATOR
-
EXTERNAL GENERIC-FUNCTION RANDOM-UNIT
- GENERATOR
Returns a unit float of fresh random output from the generator. The returned value is a double-float between 0.0 and 1.0. See GENERATOR
-
EXTERNAL GENERIC-FUNCTION RESEED
- GENERATOR
- &OPTIONAL
- NEW-SEED
Reinitialises the generator with the new seed. The seed should be an integer. If not given, the current value returned by HOPEFULLY-SUFFICIENTLY-RANDOM-SEED is used.
-
EXTERNAL GENERIC-FUNCTION SEED
- OBJECT
Returns the seed that was used to initialise the generator.