Examples

The examples/ directory contains usage examples for the components of the Random123 library.

Compiling and Running the code

Installing and using Random123 requires only the use of the header files, and has no prerequisites other than a reasonable C99 or C++98 compiler.

With a modern GNU make (3.80 or newer), building and running the core tests and examples can be as easy as running gmake with no arguments. Note, though, that the provided examples/GNUmakefile intentionally avoids setting any of the standard make variables: CC, CXX, CPPFLAGS, CFLAGS, CXXFLAGS, TARGET_ARCH, LDFLAGS, LOADLIBES, LDLIBS. GNU make will inherit settings for these variables from the environment, or they may be set on the command line. If none are set, compilation will proceed using system-wide default flags, generally without advanced optimization, architectural tuning, warnings, or other common options.

Before putting the Random123 library to use in an application, it is important to test it using the same compiler flags and features that the application will use. In other words, the conventional make variables should be set the same way when testing the library as they will be set when the library is actually compiled into your application. Something like:

gmake CFLAGS="-std=c99" CXXFLAGS="-std=c++0x" CPPFLAGS="/alternate/location/include -O3 -Wall -Wstrict-aliasing=2" TARGET_ARCH="-march=native"

would confirm that all is well with optimization on, and output targeted at an architecture with the same capabilities as the machine running the compilation.

Very old versions of GNU make (pre-2002) or non-GNU make will not work with examples/GNUmakefile.. Lacking a suitably modern GNU make, our advice is to invoke the C or C++ compiler directly on the source files in the examples/ directory.

Examples

Simple examples in C and C++

There are two extremely short examples that show all the code necessary to obtain and print a few random numbers in C and C++:

• simple.c
• simplepp.cpp

Estimating pi using different APIs

Using random numbers to estimate pi is a classic example. The idea is to choose points at random in a square and to count how many of them lie within the inscribed circle. Since the area of the square is 4*r^2 and the area of the circle is pi*r^2, the ratio of the number of points in the circle to the total number of points should approach pi/4 as the number of points grows.

We give several examples of pi estimation, each of which illustrates a slightly different API

• pi_capi - using only the basic C API
• pi_cppapi - using only the basic C++ API
• pi_u01 - using the C++ API and uniform.hpp
• pi_gsl - using a Random123 generator, but a gsl distribution to obtain real-valued random numbers. Requires the GNU Scientific Library
• pi_microurng - using a Random123 generator, but a C++0x <random> distribution to obtain real-valued random numbers
• pi_cuda - using the Random123 library with CUDA, runnable on an NVIDIA GPU
• pi_cudapp - using the C++ API with CUDA, runnable on an NVIDIA GPU
• pi_opencl - using the Random123 library with OpenCL, runnable on any OpenCL platform: e.g. NVIDIA or ATI GPUs or Intel or AMD CPUs. The actual compute kernel lives in the pi_opencl_kernel.ocl file and is transformed by gencl.sh into strings that get included in pi_opencl.c, since the OpenCL kernels get compiled for the target OpenCL platform at run-time
• pi_aes - uses the AESNI4x32 Random123 generator