imneme / pcg-c

PCG — C Implementation

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.

Building

The code is written in C99-style C with no significant platform dependencies. On a Unix-style system (e.g., Linux, Mac OS X) you should be able to just type

make

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_random.a 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

make test

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.

pcg-c's Issues

Makefile install need fix

to properly create the lib and include directory and copy the files over, the Makefile needs to be fixed
PREFIX needs to be in brackets and directory need to be made if non existing.

here is the fix:
install: all
@mkdir -p $(PREFIX)
@mkdir -p $(PREFIX)/lib
@mkdir -p $(PREFIX)/include
install src/libpcg_random.a $(PREFIX)/lib/.
install -m 0644 include/pcg_variants.h $(PREFIX)/include/.

Compile failure on 32-bit Mac OS X

Current master fails to compile on Mac OS X 10.10 when compiling for i386 (32-bit).

$ CFLAGS=-m32 LDFLAGS=-m32 make
cd src; /Applications/Xcode.app/Contents/Developer/usr/bin/make
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-advance-8.o pcg-advance-8.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-advance-16.o pcg-advance-16.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-advance-32.o pcg-advance-32.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-advance-64.o pcg-advance-64.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-advance-128.o pcg-advance-128.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-output-8.o pcg-output-8.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-output-16.o pcg-output-16.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-output-32.o pcg-output-32.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-output-64.o pcg-output-64.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-output-128.o pcg-output-128.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-rngs-8.o pcg-rngs-8.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-rngs-16.o pcg-rngs-16.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-rngs-32.o pcg-rngs-32.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-rngs-64.o pcg-rngs-64.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-rngs-128.o pcg-rngs-128.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-global-32.o pcg-global-32.c
cc -m32 -O3 -std=c99 -I../include  -c -o pcg-global-64.o pcg-global-64.c
pcg-global-32.c:35:38: error: use of undeclared identifier 'PCG_STATE_SETSEQ_64_INITIALIZER'
static pcg32_random_t pcg32_global = PCG32_INITIALIZER;
                                     ^
../include/pcg_variants.h:2178:33: note: expanded from macro 'PCG32_INITIALIZER'
#define PCG32_INITIALIZER       PCG_STATE_SETSEQ_64_INITIALIZER
                                ^
1 error generated.
make[1]: *** [pcg-global-32.o] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [all] Error 2

Digging a little more, seems to be related to the absence of 128-bit ops (PCG_HAS_128BIT_OPS is undefined). Any ideas?

Thanks!

Add support for CMake

A lot of projects are using CMake now for portability and other reasons. For pcg-cpp, an issue with further rationale and pull request exists here: imneme/pcg-cpp#43

I would love to see CMake support for pcg-c as well, since it would make it very easy to drop into projects using CMake.

HowTo: interject intermittent entropy?

Not an issue per-se; just a usage query.
My existing RNG is based on grabbing bits from a SHA2 stream. It passes tests very well; but it is computationally expensive. However, as a by-product of doing it this way, when I need another 512 bits of entropy, I call a callback that adds data to the sequence; if nothing additional is added it uses the previous output as the input, if additional data is provided, the previous output plus the additional data is used as the input the SHA2 generator...
https://github.com/d3x0r/-/blob/master/org.d3x0r.common/salty_random_generator.js#L3

Other than the initial seed, I would like to retain that sort of ability... I was planning on using a RNG something like this instead, grabbing 4 or 8 128 bit values at a time... (maybe a configurable length) and then having the ability to modify the seed...

--
Edit: I do plan on using this for procedural generators; (like perlin noise) so reproducability is key; Also for building sectors of voxels using 3d perlin noise to describee like ore content; so I can use the x,y,z of the sector as a seed for the noise generated for that sector...

Possibility of relicensing using BSD 3-clause or similar (GPL compat)

Apologies for the cross-post. I would really like to see PCG appear in NumPy. It is both high performance and easy to use in complex applications. We have the code ready and have also written the extension that allows it to run on systems without __uint128, e.g., Windows.

The main PR is close to being merged in numpy/numpy#13163 . NumPy is BSD licensed but has a strict requirement for GPL compatibility. Unfortunately, this means the Apache 2.0 cannot be included.

Is there any chance that you could consider dual-licensing?

pcg website's pcg-c download link: use github's automated zipball

We should probably use git to tag a release, and then provide 2 links on the website: (1) zipball for the tagged release (something like https://help.github.com/articles/linking-to-releases/) and (2) zipball for master.

(2) is easy to do right away because it already exists: https://github.com/imneme/pcg-c/zipball/master.

(1) requires creating a tagged commit, then pushing it here, and then linking it using the 'zipball' syntax somehow.

I just think it's better to do this as it is more automated and also offloads the storage/bandwidth (however trivial) from pcg-random.org to github.

pcg-c fails to build unless 128-bit ops are supported (as e.g. on NetBSD/powerpc)

This popped up on my radar due to a build failure on NetBSD/powerpc. This platform
does not have native support for 128-bit integer operations.

gcc -O2 -D_FORTIFY_SOURCE=2 -O3 -std=c99 -I../include  -c -o pcg-global-32.o pcg-global-32.c
In file included from pcg-global-32.c:33:
../include/pcg_variants.h:2178:33: error: 'PCG_STATE_SETSEQ_64_INITIALIZER' undeclared here (not in a function)
 2178 | #define PCG32_INITIALIZER       PCG_STATE_SETSEQ_64_INITIALIZER
      |                                 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
pcg-global-32.c:35:38: note: in expansion of macro 'PCG32_INITIALIZER'
   35 | static pcg32_random_t pcg32_global = PCG32_INITIALIZER;
      |                                      ^~~~~~~~~~~~~~~~~
gmake[1]: *** [<builtin>: pcg-global-32.o] Error 1

Inspecting include/pcg_variants.h reveals that PCG_HAS_128BIT_OPS ends up
as undefined on this platform, due to lack of __SIZEOF_INT128__ being defined, and
hence PCG_STATE_SETSEQ_64_INITIALIZER also ends up being undefined, as it's
only defined if PCG_HAS_128BIT_OPS is defined.

Undefined behavior: Upper bound of zero

When a function such as pcg_setseq_64_xsh_rr_32_boundedrand_r is called with a bound of 0 and bound is the denominator of a modulus operation, the result is undefined behavior -- possibly a division by zero error.

Such functions should check for and return zero in such cases to avoid undefined behavior.

add extensibility feature for longer periods?

I noticed that the CPP version (line 1617 in pcg_random.hpp) of this library has extended generation schemes allowing arbitrary periods (section 7.1 in the paper). Could we add this to this C version as well?

When compiling with Xcode 10.2.1, there are a couple of compiler warnings

pcg_variants.h:158:49: warning: implicit conversion loses integer precision: 'unsigned long long' to 'uint32_t' (aka 'unsigned int') [-Wshorten-64-to-32]
return pcg_rotr_32(((state >> 18u) ^ state) >> 27u, state >> 59u);
pcg-c/extras/entropy.c:76:36: warning: comparison of integers of different signs: 'ssize_t' (aka 'long') and 'size_t' (aka 'unsigned long') [-Wsign-compare]
return (close(fd) == 0) && (sz == size);