This repository was forked from the original at 83252d9 , which had several bug fixes from the officially released 0.94 version. The aim of this repository is to provide a tagged version for packagers and should have minimal changes to it. andy5995 has replaced the Makefiles with a mesonbuild to also aid in packaging. Installing the library also provides a pkg-config (.pc) file so build systems can locate pcg-c's headers and library automatically (e.g. pkg-config --cflags --libs pcg-c).

PCG Random Number Generation, C Edition

This code provides an implementation of the PCG family of random number generators, which are fast, statistically excellent, and offer a number of useful features.

Full details can be found at the PCG-Random website. This version of the code provides many family members -- if you just want one simple generator, you may prefer the minimal version of the library.

There are two APIs, a low-level one which explicitly names the output functions, and a higher-level one (which maps directly to the low-level code). Generally, you should use the high-level API.

Documentation and Examples

Visit PCG-Random website for information on how to use this library, or look at the sample code in the sample directory -- hopefully it should be fairly self explanatory.

For background on the design, watch the Stanford Seminar talk PCG: A Family of Better Random Number Generators.

Building

The code is written in C99-style C with no significant platform dependencies. With Meson installed, configure and build with

meson setup build
meson compile -C build

Almost all the real code is in include/pcg_variants.h. Because the individual RNGs have a very small amount of code, they are provided as inline functions to allow the compiler the option of inlining them. But because C requires there to also be an external definition, the src directory contains code to build libpcg-c which provides non-inline definitions for all the PCG generators.

On other systems, it should be straightforward to build a library by compiling the files in the src directory. Or, write your own file giving an extern declaration for every function you actually use.

Testing

Run

meson test -C build

Directory Structure

The directories are arranged as follows:

• include -- contains pcg_variants.h
• src -- code to define external versions of the inline functions from pcg_variants.h plus all the _advance_r functions.
• test-low -- test code for the low-level API where the functions have long scary-looking names
• test-high -- test code for the high-level API where the functions have shorter, less scary-looking names.
• extras -- other useful code, such as code to read /dev/random
• sample -- sample code, similar to the code in test-high but more human readable

128-bit Math

On systems that support it (64-bit systems using GCC or Clang), the library provides RNGs that use 128-bit integer math. These generators produce 64-bit output (or more) and have a period of 2^128.

If you don't have 128-bit support on your system, you aren't losing that much. Thanks to the 2^63 random streams/sequences, you can gang together multiple 32-bit generators. (Note: This approach would not work well with generators that only have a single stream/sequence). Example code is provided in sample/pcg32x2-demo.c.

The C++ implementation provides 128-bit integers even on systems that don't natively support it, but doing so would be too much trouble in C.