Note

The published rocRAND documentation is available here in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the docs folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see Contribute to ROCm documentation.

The rocRAND project provides functions that generate pseudorandom and quasirandom numbers. The rocRAND library is implemented in the HIP programming language and optimized for AMD's latest discrete GPUs. It is designed to run on top of AMD's ROCm runtime.

Prior to ROCm version 5.0, this project included the hipRAND wrapper. As of version 5.0, it was split into a separate library. As of version 6.0, hipRAND can no longer be built from rocRAND.

Supported random number generators

XORWOW
MRG31k3p
MRG32k3a
Mersenne Twister (MT19937)
Mersenne Twister for Graphic Processors (MTGP32)
Philox (4x32, 10 rounds)
LFSR113
Sobol32
Scrambled Sobol32
Sobol64
Scrambled Sobol64
ThreeFry

Requirements

CMake (3.16 or later)
C++ compiler with C++17 support to build the library.
- Recommended to use at least gcc 9
- clang uses the development headers and libraries from gcc, so a recent version of it must still be installed when compiling with clang
C++ compiler with C++11 support to consume the library.
For AMD platforms:
- ROCm (1.7 or later)
- HIP-clang compiler, which must be set as the C++ compiler for the ROCm platform.
Python 3.6 or higher (HIP on Windows only, only required for install script)
Visual Studio 2019 with clang support (HIP on Windows only)
Strawberry Perl (HIP on Windows only)

Optional:

GoogleTest (required only for tests; building tests is enabled by default)
- Use GTEST_ROOT to specify the GoogleTest location (see also FindGTest)
- Note: If GoogleTest is not already installed, it will be automatically downloaded and built
Fortran compiler (required only for Fortran wrapper)
- gfortran is recommended
Python 3.5+ (required only for Python wrapper)
doxygen to build the documentation
AMD SMI
- Required only for benchmarks. Building benchmarks is off by default.

If some dependencies are missing, the CMake script automatically downloads, builds, and installs them. Setting the DEPENDENCIES_FORCE_DOWNLOAD option to ON forces the script to download all dependencies, rather than using the system-installed libraries.

Build and install

Note

The following clone command downloads all components in the rocm-libraries GitHub repository. This is recommended for working with multiple library components, but can take a very long time to download. For a shorter download process that only clones the rocRAND library, see the rocRAND installation documentation for ROCm 7.0 or later.

git clone https://github.com/ROCm/rocm-libraries.git

# Go to rocRAND directory, create and go to build directory
cd rocm-libraries/projects/rocrand; mkdir build; cd build

# Configure rocRAND, setup options for your system
# Build options:
#   BUILD_SHARED_LIBS - ON by default.
#   BUILD_TEST        - OFF by default.
#   BUILD_BENCHMARK   - OFF by default.
#   USE_SYSTEM_LIB    - OFF by default. Setting it to ON will build tests using the existing ``rocrand``
#                       library installation from the system. This only takes effect when BUILD_TEST is ON
#                       and the ``rocrand`` installation must be compatible with the version of the tests.
#                       This option can be used to build tests exclusively when you do not intend to build
#                       the library nor the benchmarks.
# Additionally, the ROCm installation prefix should be passed using CMAKE_PREFIX_PATH or by setting the ROCM_PATH environment variable.
#
# ! IMPORTANT !
# Set C++ compiler to HIP-clang. You can do it by adding 'CXX=<path-to-compiler>'
# before 'cmake' or setting cmake option 'CMAKE_CXX_COMPILER' to path to the compiler.
#
# The python interface do not work with static library.
#
# The package and install scripts require Make, but otherwise passing -GNinja is recommended for faster building.
[CXX=hipcc] cmake -DBUILD_BENCHMARK=ON ../. -DCMAKE_PREFIX_PATH=/opt/rocm # or cmake-gui ../.

# Build
make -j4 # or `ninja`

# Optionally, run tests if they're enabled
ctest --output-on-failure

# Install
[sudo] make install

SPIR-V

rocRAND supports the amdgcnspirv target, it should be built with -DAMDGPU_TARGETS=amdgcnspirv.

HIP on Windows

We've added initial support for HIP on Windows, which you can install using the rmake.py python script:

git clone https://github.com/ROCm/rocm-libraries.git
cd rocm-libraries/projects/rocrand

# the -i option will install rocPRIM to C:\hipSDK by default
python rmake.py -i

# the -c option will build all clients including unit tests
python rmake.py -c

The existing GoogleTest library in the system (especially static GoogleTest libraries built with other compilers) may cause a build failure; if you encounter errors with the existing GoogleTest library or other dependencies, you can pass the DEPENDENCIES_FORCE_DOWNLOAD flag to CMake, which can help to solve the problem.

Running unit tests

# Go to rocRAND build directory
cd rocm-libraries/projects/rocrand; cd build

# To run all tests
ctest

# To run unit tests
./test/<unit-test-name>

Running benchmarks

rocRAND uses primbench for benchmarking; see its command-line options for advanced usage.

# Go to rocRAND build directory
cd rocm-libraries/projects/rocrand; cd build

# To run benchmark for the host generate functions:
# Specializations are named as `distribution: <dist>, engine: <engine>, ordering: <ordering>, type: <type>`, where
# engine -> lfsr113, mrg31k3p, mrg32k3a, mt19937, mtgp32, philox4_32_10,
#           scrambled_sobol32, scrambled_sobol64, sobol32, sobol64,
#           threefry2_32_20, threefry2_64_20, threefry4_32_20, threefry4_64_20, xorwow
# distribution -> log_normal, normal, poisson, uniform
# ordering -> default, dynamic, quasi_default
# type -> f32, f64, half, u8, u16, u32
# Further options can be found using --help
./benchmark/benchmark_rocrand_host_api
# To list all specializations without running them:
./benchmark/benchmark_rocrand_host_api --dry
# To run specific benchmarks:
./benchmark/benchmark_rocrand_host_api --filter <regex>
# For example, to run benchmarks with engine sobol64:
./benchmark/benchmark_rocrand_host_api --filter "engine: sobol64"
# The benchmark also supports user input:
./benchmark/benchmark_rocrand_host_api --size <number> --offset <number> --dimensions <number> --lambda <space-separated list of floats>
# Results are written to benchmark_rocrand_host_api.json by default; CSV output can also be enabled:
./benchmark/benchmark_rocrand_host_api --json-out benchmark_rocrand_host_api.json --csv-out benchmark_rocrand_host_api.csv

# To run benchmark for device kernel functions:
# Specializations are named as `cfg: { blocks: <n>, threads: <n> }, distribution: <dist>, engine: <engine>, type: <type>`, where
# engine -> lfsr113, mrg31k3p, mrg32k3a, mtgp32, philox4_32_10,
#           scrambled_sobol32, scrambled_sobol64, sobol32, sobol64,
#           threefry2_32_20, threefry2_64_20, threefry4_32_20, threefry4_64_20, xorwow
# distribution -> discrete_custom, discrete_poisson, log_normal, normal, poisson, uniform
# type -> f32, f64, u32, u64
# Further options can be found using --help
./benchmark/benchmark_rocrand_device_api
# To list all specializations without running them:
./benchmark/benchmark_rocrand_device_api --dry
# To run specific benchmarks:
./benchmark/benchmark_rocrand_device_api --filter <regex>
# For example, to run benchmarks with engine sobol64:
./benchmark/benchmark_rocrand_device_api --filter "engine: sobol64"
# The benchmark also supports user input:
./benchmark/benchmark_rocrand_device_api --size <number> --offset <number> --dimensions <number> --lambda <space-separated list of floats> --blocks <number> --threads <number>
# Results are written to benchmark_rocrand_device_api.json by default; CSV output can also be enabled:
./benchmark/benchmark_rocrand_device_api --json-out benchmark_rocrand_device_api.json --csv-out benchmark_rocrand_device_api.csv

# To compare against cuRAND (cuRAND must be supported):
./benchmark/benchmark_curand_host_api [primbench options]
./benchmark/benchmark_curand_device_api [primbench options]

Wrappers

C++ wrappers for the rocRAND host API are in rocrand.hpp.
Fortran wrappers.
Python wrappers: rocRAND.

Building the documentation locally

Requirements

Doxygen

The build system uses Doxygen version 1.9.4. You can try using a newer version, but that might cause issues.

After you have downloaded Doxygen version 1.9.4:

# Add doxygen to your PATH
echo 'export PATH=<doxygen 1.9.4 path>/bin:$PATH' >> ~/.bashrc

# Apply the updated .bashrc
source ~/.bashrc

# Confirm that you are using version 1.9.4
doxygen --version

Python

The build system uses Python version 3.10. You can try using a newer version, but that might cause issues.

You can install Python 3.10 alongside your other Python versions using pyenv:

# Install Python 3.10
pyenv install 3.10

# Create a Python 3.10 virtual environment
pyenv virtualenv 3.10 venv_rocrand

# Activate the virtual environment
pyenv activate venv_rocrand

Building

After cloning this repository, and cding into it:

# Install Python dependencies
python3 -m pip install -r docs/sphinx/requirements.txt

# Build the documentation
python3 -m sphinx -T -E -b html -d docs/_build/doctrees -D language=en docs docs/_build/html

You can then open docs/_build/html/index.html in your browser to view the documentation.

Support

Bugs and feature requests can be reported through the issue tracker.

Contributions and license

Contributions of any kind are most welcome! You can find more information at CONTRIBUTING.

Licensing information is located at LICENSE.