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

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.

Creating a Generator

To create a generator you can use the make-pcg function:

(defparameter *gen* (make-pcg))

make-pcg takes two keyword parameters:

Once you've got a PCG object you can use it to generate some numbers.

Generating 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]

The Global Generator

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)

Advancing & Rewinding

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

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.