cl-pcg is a permuted congruential generator implementation in pure
Common Lisp. It provides a high-level API and a low-level API.
PCGs are not cryptographically secure. If you need that, look elsewhere.
The high-level API is what you should start (and probably end) with. It typechecks the arguments you pass in and offers a nice interface for generating random numbers.
To create a generator you can use the make-pcg function:
(defparameter *gen* (make-pcg))
make-pcg takes two keyword parameters:
:seed should be an (unsigned-byte 64). If omitted a random seed will be
generated with the underlying implementation's cl:random function.:stream-id should be an (unsigned-byte 32). The default is 0. Streams
provide a way to "split" a PCG into multiple generators — check out the PCG
site for more information on this.Once you've got a PCG object you can use it to generate some numbers.
You can use the pcg-random function to generate random numbers:
(defparameter *gen* (make-pcg)) (pcg-random *gen* 10) ; => a random number from 0 (inclusive) to 10 (exclusive)
pcg-random is flexible and takes a number of optional arguments to help you
generate the kinds of numbers you need. Its lambda list looks like this:
(pcg bound &optional max inclusive?)
If only bound is given, the function acts much like cl:random.
If max is also given, a random number in [bound, max) is chosen.
If inclusive? is also given, a random number in [bound, max] is chosen.
For example:
(defparameter *gen* (make-pcg)) (pcg-random *gen* 10) ; => [0, 10) (pcg-random *gen* 15 28) ; => [15, 28) (pcg-random *gen* 15 28 t) ; => [15, 28] <- inclusive endpoint!
inclusive? is treated as a generalized boolean, so you can write (pcg-random
gen -10 10 :inclusive) if you feel it reads better.
pcg-random can also generate single-floats if bound and/or max are given
as single-floats:
(defparameter *gen* (make-pcg)) (pcg-random *gen* 10.0) ; => [0.0, 10.0] (pcg-random *gen* 0 10.0) ; => [0.0, 10.0] (pcg-random *gen* -1.0 1.0) ; => [-1.0, 1.0]
If you don't want to bother creating a fresh PCG object you can pass t to the
high-level API to use a globally-defined one:
(pcg-random t 10)
Sometimes it can be useful to advance or rewind a generator by a certain number
of steps. The (pcg-advance pcg steps) and (pcg-rewind pcg steps) functions
can be used to do this:
(defparameter *gen* (make-pcg)) ;; Get three numbers (pcg-random *gen* 1000) ; => 708 (pcg-random *gen* 1000) ; => 964 (pcg-random *gen* 1000) ; => 400 ;; Rewind three steps (pcg-rewind *gen* 3) ;; Get the same three numbers (pcg-random *gen* 1000) ; => 708 (pcg-random *gen* 1000) ; => 964 (pcg-random *gen* 1000) ; => 400
These functions are O(log₂(steps)) so they'll be fast even for ludicrously
large values of steps.
The low-level API is what you want if you need raw speed. It consists of all
functions in the API whose names end in %, like pcg-random%. All of these
functions are declaimed inline for easy embedding into hot loops.
As an arbitrary example, the main function in this API (pcg-random%) is about
100 bytes of machine code, so it's suitable for inlining when you really need
performance.
The low-level API assumes you will pass in arguments of the correct type. If you fuck this up, all bets are off. Read the code to figure out exactly what you need to pass in (or just use the high-level API like a sane person).
You can only generate 32-bit integers, and only single floats. This will change whenever I get around to fixing things up.