random state

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

    Source

    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

    Source

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

  • EXTERNAL CLASS

    MERSENNE-TWISTER-32

    Source

    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

    Source

    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

    Source

    An incredibly primitive, and basically in practise useless, random number algorithm.
    
    See https://en.wikipedia.org/wiki/Middle-square_method

  • EXTERNAL CLASS

    PCG

    Source

    An adaptation of the PCG rng.
    
    See http://www.pcg-random.org

  • EXTERNAL CLASS

    RC4

    Source

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

  • EXTERNAL CLASS

    TT800

    Source

    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

    Source

    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

    Source

    Returns a global instance of a generator.
    
    See MAKE-GENERATOR

  • EXTERNAL FUNCTION

    HOPEFULLY-SUFFICIENTLY-RANDOM-SEED

    Source

    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

    Source

    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

    Source

    Returns an integer of fresh random output from the generator.
    
    The integer is at most 2^(BYTES GENERATOR)-1 and at least 0.
    
    See GENERATOR
    See BYTES

  • EXTERNAL GENERIC-FUNCTION

    RANDOM-BYTES

    • GENERATOR
    • BYTES

    Source

    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

    Source

    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

    Source

    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

    Source

    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

    Source

    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.