random state

1.0.0

Portable 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 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)
      repeat 10
      collect (random-state:random-int 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: 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.

System Information

Version: 1.0.0

Dependencies:

documentation-utils

Author: Nicolas Hafner

License: zlib

Homepage: https://Shinmera.github.io/random-state/

Sources: https://github.com/Shinmera/random-state.git

Definition Index

RANDOM-STATE

ORG.SHIRAKUMO.RANDOM-STATE

No documentation provided.

EXTERNAL STRUCTURE

GENERATOR

General class for any random number generator.

See LIST-GENERATOR-TYPES
See SEED
See RESEED
See NEXT-BYTE
See BITS-PER-BYTE
See COPY
See MAKE-GENERATOR
See STATEFUL-GENERATOR
See HASH-GENERATOR

EXTERNAL STRUCTURE

HASH-GENERATOR

Superclass for all generators that rely on a hashing function to generate numbers.

These generators are special in that numbers for any index can be
generated, so they can be rewound or arbitrarily stepped in their
sequence.

See GENERATOR
See INDEX
See REWIND

EXTERNAL STRUCTURE

LINEAR-CONGRUENCE

A very simple random number generator based on linear congruence.

See https://en.wikipedia.org/wiki/Linear_congruential_generator

EXTERNAL STRUCTURE

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 STRUCTURE

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 STRUCTURE

MIDDLE-SQUARE

An incredibly primitive, and basically in practise useless, random number algorithm.

See https://en.wikipedia.org/wiki/Middle-square_method

EXTERNAL STRUCTURE

PCG

An adaptation of the PCG rng.

See http://www.pcg-random.org

EXTERNAL STRUCTURE

RC4

The RC4 cryptographic random number generator.

See https://en.wikipedia.org/wiki/RC4

EXTERNAL STRUCTURE

SQUIRREL

An adaptation of the "squirrel hash v3".

See https://www.youtube.com/watch?v=LWFzPP8ZbdU

EXTERNAL STRUCTURE

STATEFUL-GENERATOR

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 FUNCTION

ENSURE-GENERATOR

GENERATOR-ISH

Ensures the argument is an object usable for random number generation.

See GLOBAL-GENERATOR
See GENERATOR

EXTERNAL FUNCTION

GLOBAL-GENERATOR

NAME

Returns a global instance of a generator.

You may also SETF this place to name specific generators of your own.

See MAKE-GENERATOR

EXTERNAL FUNCTION
(SETF GLOBAL-GENERATOR)
- VALUE
- NAME
Source
No documentation provided.

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

INDEX

INSTANCE

Accesses the index of the hash-generator.

The index must be an (unsigned-byte 64).
The index is advanced for each call to NEXT-BYTE.

See HASH-GENERATOR

EXTERNAL FUNCTION
(SETF INDEX)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LIST-GENERATOR-TYPES

Lists the types of generators supported by the library.

You may use any of these types to call MAKE-GENERATOR with.

See MAKE-GENERATOR

EXTERNAL FUNCTION

MAKE-GENERATOR

TYPE
&OPTIONAL
SEED
&REST
INITARGS

Creates a new generator of the given type.

You may pass an optional seed to initialise the generator with. If no
seed is specified, each constructed generator of the same type will
return the same sequence of numbers.

See RESEED
See GENERATOR

EXTERNAL FUNCTION

RANDOM-1D

GENERATOR
INDEX
&OPTIONAL
SEED

Returns a byte for the given index and seed.

This is only usable with HASH-GENERATOR types.
Does *NOT* advance the generator's index.

See HASH-GENERATOR
See NEXT-BYTE

EXTERNAL FUNCTION

RANDOM-2D

GENERATOR
X
Y
&OPTIONAL
SEED

Returns a byte for the given location and seed.

This is only usable with HASH-GENERATOR types.
Does *NOT* advance the generator's index.

See HASH-GENERATOR
See NEXT-BYTE

EXTERNAL FUNCTION

RANDOM-3D

GENERATOR
X
Y
Z
&OPTIONAL
SEED

Returns a byte for the given location and seed.

This is only usable with HASH-GENERATOR types.
Does *NOT* advance the generator's index.

See HASH-GENERATOR
See NEXT-BYTE

EXTERNAL FUNCTION

RANDOM-BYTE

GENERATOR

Alias for NEXT-BYTE.

See GENERATOR
See NEXT-BYTE

EXTERNAL FUNCTION

RANDOM-BYTES

GENERATOR
BITS

Returns an (UNSIGNED-BYTE BITS) sized random number.

May advance the generator more than once.

See GENERATOR
See NEXT-BYTE

EXTERNAL FUNCTION

RANDOM-FLOAT

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 RANDOM-UNIT

EXTERNAL FUNCTION

RANDOM-INT

GENERATOR
FROM
TO

Returns a random integer in [FROM, TO].

See GENERATOR
See RANDOM-BYTES

EXTERNAL FUNCTION

RANDOM-SEQUENCE

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 NEXT-BYTE, and that doing so makes
sense. As in, do not fill a vector with element-type (unsigned-byte 8)
with a generator whose BITS-PER-BYTE is 32 or vice-versa.

Equivalent to:

  (map-into sequence (lambda () (next-byte generator)))

See GENERATOR
See NEXT-BYTE

EXTERNAL FUNCTION

RANDOM-UNIT

GENERATOR
&OPTIONAL
TYPE

Returns a random float in [0, 1].

The returned float is of the type specified in TYPE.

See GENERATOR
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.

See NEXT-BYTE
See GENERATOR

EXTERNAL GENERIC-FUNCTION

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 (= (next-byte generator) (next-byte copy)))

See GENERATOR

EXTERNAL GENERIC-FUNCTION

NEXT-BYTE

GENERATOR

Returns the next byte (not octet) of random state.

The returned integer must be in the range of
  [ 0, 1 << BITS-PER-BYTE GENERATOR [

See RANDOM-INT
See RANDOM-BYTES
See GENERATOR

EXTERNAL GENERIC-FUNCTION

RESEED

GENERATOR
NEW-SEED

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
HOPEFULLY-SUFFICIENTLY-RANDOM-SEED is used.

See HOPEFULLY-SUFFICIENTLY-RANDOM-SEED
See GENERATOR

EXTERNAL GENERIC-FUNCTION

REWIND

HASH-GENERATOR
&OPTIONAL
BY

Rewind the hash-generator by BY numbers.

The following invariant holds for any N:

  (= (next-byte generator) (progn (rewind generator N) (loop repeat (1- N) (next-byte generator)) (next-byte generator)))

See HASH-GENERATOR

EXTERNAL GENERIC-FUNCTION

SEED

GENERATOR

Returns the seed that was used to initialise the generator.

See GENERATOR

EXTERNAL MACRO
DEFINE-GENERATOR
- NAME
- BITS-PER-BYTE
- SUPER
- SLOTS
- &BODY
- BODIES
Source
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
INDEX
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
(SETF INDEX)
No documentation provided.