Ranx

Ranx is a next-generation parallel algorithmic (pseudo) random number generator available as both a utility, as well as a modern header-only C++ library supporting OpenMP, CUDA, ROCm and oneAPI.

As a library, Ranx 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, ranx::generate() and ranx::generate_n() can do it hassle-free with almost the same interface.

One important feature of generate() algorithms provided by Ranx 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 difficult, if not impossible, to get the the same sequence of random numbers using them.

• Features
• Building from source
• Running unit tests
• Running benchmarks
• Using ranx
  • Example
• Ranx utility

• Multiplatform
  • Linux
  • macOS
  • Windows 10/11
• 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
• Included engines:
  • PCG Family
• Include all 32 distributions provided by TRNG library
• Support CMake for building and auto configuration
• Include unit tests using Catch2
• Include benchmarks using Google Benchmark

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/ranx.git
cd ranx
cmake -S . -B build
cmake --build build -j
sudo cmake --install build

cd build
ctest

cd build
perf/benchmarks --benchmark_counters_tabular=true

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

• ranx::cuda
• ranx::oneapi
• ranx::openmp
• ranx::rocm

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

find_package(ranx CONFIG COMPONENTS openmp cuda)

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

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

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

# include the module
include(FetchContent)

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

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

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

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

Ranx library also comes with a command-line random number generator. Check the Ranx utility page.