Get started with OpenRNG

This is AMD's fork of the OpenRNG library originally developed at Arm. It is one of the components of the AOCL (AMD Optimizing CPU Libraries) suite.

OpenRNG is an open-source Random Number Generator library that provides various base random number generators — both pseudo-random (PRNG) and quasi-random (QRNG) — along with a range of statistical distributions. Its API is compatible with the random number generation component of Intel's Vector Statistics Library (VSL), making it a convenient alternative.

The set of random number functions currently included are listed in IMPLEMENTATION_STATUS.md. We are intending to increase the coverage in future releases, and we are very keen to hear from users who find missing functionality that they would like us to prioritize. If a user would like to request features or for any other form of assistance, please raise it under "Issues" in this GitHub repository.

This document describes how to build and install OpenRNG, including the tests and examples provided within the source code. If a user wishes to contribute to the development of OpenRNG, please see the Contribution guidelines.

Download, build and install OpenRNG

AOCL's User Guide may contain information about OpenRNG, including compiler and other toolchain dependencies.

Prerequisites: CMake >= 3.26, a C++20-capable compiler (GCC or AOCC on Linux, LLVM/clang-cl on Windows), Python 3, and — for AOCL builds — AOCL-LibM.

Clone the OpenRNG repository:

git clone https://github.com/amd/openrng

Navigate into the cloned repository and run the CMake workflow preset below, which performs the configure, build, and test steps. Pick the one matching your platform and compiler (Release, LP64 shown):

cmake --workflow --preset rel-gcc-lp64    # Linux, GCC
cmake --workflow --preset rel-aocc-lp64   # Linux, AOCC
cmake --workflow --preset rel-llvm-lp64   # Windows, LLVM

• Build directory: <openrng>/build/<presetName>
• Install directory: <openrng>/build/<presetName>/install

A Python script tools/find_cmake_command/find_cmake_command.py can be used to find the CMake command for various library configurations. Run this script on Linux or Windows to find a specific CMake command.

python tools/find_cmake_command/find_cmake_command.py

By default, OpenRNG builds both shared and static libraries with the LP64 interface, including the AMD-specific optimizations (AOCL-OpenRNG). Common overrides:

• -DOPENRNG_INTERFACE=ilp64 — build the ILP64 (64-bit integer) interface.
• -DAOCL_OPENRNG_BUILD=OFF — build Arm's upstream open-source (generic) library instead.
• -DAOCL_ROOT=<path> (or the AOCL_ROOT environment variable) — locate AOCL-LibM, which the AOCL build depends on.

For the full build matrix (all compilers, interfaces and target kinds such as obj, asan, examples, and pkg), the different command styles, packaging and standalone example builds, see the Build guide.

Documentation

At present, ARM's OpenRNG documentation ARM Performance Libraries documentation can be referred. In future releases, we might provide additional documentation for the changes and improvements that AMD contributes.

Building and running OpenRNG examples

The library ships with a set of examples under examples/ that demonstrate how the interface is used to generate random numbers. They can be built two ways:

• As part of the library build, using the -examples presets (e.g. cmake --workflow --preset rel-gcc-lp64-examples).
• Standalone, against an already-installed OpenRNG.

Step-by-step instructions for both, including the required options and how to run the resulting executables, are in examples/README.md. See the Build guide for the complete build reference.