p2rng

p2rng (Parallel Pseudo Random Number Generator) is a modern header-only C++ library for parallel algorithmic (pseudo) random number generation supporting OpenMP, CUDA, ROCm and oneAPI.

Table of contents

• Features
• Building from source
• Running unit tests
• Running benchmarks
• Using p2rng

Features

• Support four target APIs
  • CUDA
  • oneAPI
  • OpenMP
  • ROCm
• Provide parallel versions of STL’s std::generate() and std::generate_n() algorithms with the same interface
• Play fair on all supported platforms (using the same seed and distribution you always get the same sequence of random numbers)
• Included engines:
  • PCG Family
• Support CMake for building and auto configuration
• Include unit tests using Catch2
• Include benchmarks using Google Benchmark

Building from source

You need:

• C++ compiler supporting the C++17 standard (e.g. gcc 9.3)
• CMake version 3.21 or higher.

And the following optional third-party libraries:

• Catch2 v3.1 or higher for unit testing
• Google Benchmark for benchmarks

The CMake script configured in a way that if it cannot find the optional third-party libraries it tries to fetch and build them automatically. So, there is no need to do anything if they are missing but you need an internet connection for that to work.

On the Alliance clusters, you can activate the above environment by the following module command:

module load cmake googlebenchmark catch2

Once you have all the requirements you can build and install it using the following commands:

git clone https://github.com/arminms/p2rng.git
cd p2rng
cmake -S . -B build
cmake --build build -j
sudo cmake --install build

Running unit tests

cd build
ctest

Running benchmarks

cd build
perf/benchmarks --benchmark_counters_tabular=true

Using p2rng

Ideally you should be using p2rng through its CMake integration. CMake build of p2rng exports four (namespaced) targets:

• p2rng::cuda
• p2rng::oneapi
• p2rng::openmp
• p2rng::rocm

Linking against them adds the proper include paths and links your target with proper libraries depending on the API. This means that if p2rng has been installed on the system, it should be enough to do:

find_package(p2rng REQUIRED)

# link test1 with p2rng using OpenMP API
add_executable(test1 test1.cpp)
target_link_libraries(test1 PRIVATE p2rng::openmp)

# link test2 with p2rng using CUDA API
add_executable(test2 test2.cpp)
target_link_libraries(test2 PRIVATE p2rng::cuda)

Another possibility is to check if p2rng is installed and if not use FetchContent:

find_package(p2rng)
if(NOT p2rng_FOUND)
  message(STATUS "Fetching p2rng library...")
  FetchContent_Declare(
    p2rng
    GIT_REPOSITORY https://github.com/arminms/p2rng.git
    GIT_TAG        v0.1.0
  )
  FetchContent_MakeAvailable(p2rng)
endif()

# link test with p2rng using oneapi API
add_executable(test test.cpp)
target_link_libraries(test PRIVATE p2rng::oneapi)