Skip to content
/ p2rng Public

A modern header-only C++ library for parallel algorithmic (pseudo) random number generation supporting OpenMP, CUDA, ROCm and oneAPI

License

Notifications You must be signed in to change notification settings

arminms/p2rng

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

79 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build and Test (Linux/macOS/Windows) License: MIT

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.

p2rng provides alternatives to STL generate() family of algorithms that exclusively designed for parallel random number generation on CPUs and GPUs. Unlike C++17 parallel version of std::generate() and std::generate_n() that cannot be readily used for random number generation, p2rng::generate() and p2rng::generate_n() can do it hassle-free with almost the same interface.

One important feature of generate() algorithms provided by p2rng is that they play fair: using the same seed and distribution, you can get the same sequence of random numbers on all supported platforms regardless of the number of parallel threads. CUDA, ROCm and oneAPI provide their own parallel random number libraries: cuRAND, rocRAND and oneMKL. Aside from the fact that their interface is not compatible with STL, it's almost impossible to get the the same sequence of random numbers using them.

Table of contents

Features

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:

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 CONFIG COMPONENTS openmp cuda)

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

# link test.cu with p2rng using CUDA API
add_executable(test_cuda test.cu)
target_link_libraries(test_cuda PRIVATE p2rng::cuda)

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

# include the module
include(FetchContent)

# first check if p2rng is already installed
find_package(p2rng CONFIG COMPONENTS oneapi)

# if not, try to fetch and make it available
if(NOT p2rng_FOUND)
  message(STATUS "Fetching p2rng library...")
  FetchContent_Declare(
    p2rng
    GIT_REPOSITORY https://github.com/arminms/p2rng.git
    GIT_TAG main
  )
  # setting required p2rng components
  set(P2RNG_COMPONENTS oneapi CACHE STRING "Required components")
  FetchContent_MakeAvailable(p2rng)
endif()

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

Example

You can find a complete example of the above approach in the example folder along with build instructions.

YouTube Video

There is a recorded video about p2rng on SHARCNET YouTube Channel:

You can find PDF of the slides in the doc folder. All the codes shown in the above video are also included in the doc/codes folder along with a CMake script to build them.