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
(defparameter *gen* (make-pcg))
make-pcg takes two keyword parameters:
:seedshould be an
(unsigned-byte 64). If omitted a random seed will be generated with the underlying implementation's
:stream-idshould 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?)
bound is given, the function acts much like
max is also given, a random number in
[bound, max) is chosen.
inclusive? is also given, a random number in
[bound, max] is chosen.
(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
gen -10 10 :inclusive) if you feel it reads better.
pcg-random can also generate
max are given
(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
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
pcg-random%. All of these
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
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.