RandomTesting: Kokkos Pseudo Random Number Generators Validation with PractRand

For now, this repository provides a testing framework to evaluate the statistical quality of Kokkos pseudo-random number generators (PRNGs) using PractRand (Practically Random), developed by Chris Doty-Humphrey.

The application kokkos_random_generator generates a continuous stream of random binary data using the Kokkos default execution space, which can be piped directly into PractRand's RNG_test suite via standard output (stdout). The application allows you to choose:

• the generator (SFC64, XorShift64, XorShift1024)
• the type of data to generate (uint32, uint64)
• the seed (default: 12345, a purposely bad seed)
• the size of the buffer used to output the data (only has an impact on speed performance)
• the execution mode (basic for a classic Kokkos multi-stream execution, mono for a single-stream and single-thread sequential execution)

In the same fashion, the application kokkos_init_tester generates a sequence from the first random numbers produced by each stream of the tested PRNG.

---

Repository Structure

• CMakeLists.txt - Build configuration for the Kokkos test executables.
• kokkos_random_generator.cpp - Target source code generating random buffers from multiple streams or a single one.
• kokkos_init_tester.cpp - Target source code generating random buffers from the first random numbers of multiple streams.
• install_practrand.sh - (Optional) Bash script to compile PractRand locally, either from a provided zip file or from automatically fetched downloaded sources.
• run_test.sh - (Example) Bash script that runs the execution pipeline.

---

Prerequisites

Before building and running the tests, ensure you have the following dependencies installed depending of what you want to use:

• kokkos_random_generator and kokkos_init_tester:
  • CMake (version 3.23 or higher)
  • A C++20 compliant compiler (e.g., GCC, Clang)
  • Kokkos Library with SFC64 (commit > 0520f48), configured and installed on your system with the backend you want to test.
• install_practrand.sh:
  • Either:
    • a zip file of PractRand v0.96 (could be found here)
    • wget, or curl if you don't provide the zip file
  • python3 with the zipfile package to unzip the PractRand sources
  • g++ and ar to compile PractRand using author's instructions.
• run_test.sh:
  • kokkos_random_generator compiled
  • RNG_Test compiled

---

Setup & Installation

Install PractRand

You need the RNG_test executable from PractRand. You can either use a system-wide installation or use the provided script to build it locally.

Option A: Automated Download & Build Run the script without arguments to automatically download, unpack, and compile a stable version of PractRand into a local directory (./practrand_bin/):

bash install_practrand.sh

or

chmod u+x install_practrand.sh
./install_practrand.sh

Option B: Supply a Local Source Archive If you have a local offline .zip source of PractRand, pass its path as an argument. The script will automatically validate its SHA-256 integrity hash before compiling it:

./install_practrand.sh /path/to/PractRand-0.96.zip

Note: If RNG_test is already available in your system's PATH, the script will recognize it and skip the installation step.

Compile the Kokkos Executables

Build the project using standard CMake workflow.

cmake -B ./build .
cmake --build ./build

Note: You can optionally append -DUSE_ASAN=ON or -DUSE_TSAN=ON to the cmake configuration command if you need but you have to know what you 're doing, especially with TSAN.

Running the Pipeline

The test pipeline runs by feeding the binary stream generated by Kokkos into the standard input (stdin) of PractRand.

An example script is provided to test the SFC64 generator:

bash ./run_test.sh

or

chmod u+x ./run_test.sh
./run_test.sh

Manual Usage & Customization

If you want to manually run tests or adjust parameters, the kokkos_random_generator executable accepts the following command-line arguments:

./build/kokkos_random_generator [generator] [datatype] [seed] [buffer_size] [exec_mode] | RNG_test [practrand_generator] [optionnals practrand flags]

Arguments Reference:

1. generator: The PRNG engine to use. Options are sfc64, xorshift64, or xorshift1024.
2. datatype: The type of data to produce. Options are uint64 or uint32 (Defaults to uint64).
3. seed: Initial integer seed for the pool (Defaults to 12345, a bad seed to purposely test the generators on bad seed).
4. buffer_size: The number of elements in the buffer used internally in the kokkos kernel and send to PracRand through stdout. This have impact on the performance of the run, try to use multiples of 2. (Default to 8192, which is 64KiB for uint64. This number exibit better performances than lower values on my laptop with the SERIAL, OPENMP and CUDA backend. In my case, "reasonable" higher values doesn't appears to impact the performances.)
5. exec_mode: The execution mode. Options are basic or mono. basic uses a standard parallel kernel filling the buffer, while mono uses a single Kokkos thread running a loop sequentially (useful to evaluate mono-stream generation behavior). (Defaults to basic).

The use of 1. is MANDATORY. The others are optionnal but requires to be in consecutive order (i.e: $[1], [1, 2], [1, 2, 3]$, $[1, 2, 3, 4]$ or $[1, 2, 3, 4, 5]$).

PractRand Arguments: Refer to ./RNG_test --help for better reference. Quick summary of notable options:

• pracrand_generator: MANDATORY should be stdin64 or stdin32 when you pipe from kokkos_random_generator. Or you could use a native PractRand generator. Note: native sfc64 vs kokkos sfc64 don't behave exactly in the same way.
• -tlmaxonly avoid pracrand to stop early if some tests failed, usefull for xorshift* since they will fail early...
• -tlmax [value] to specifie the size of data to test. (Default: 32TB)
• -multithreaded to used multiples threads for the tests. Speedup the process.
• -seed [value] only for better display when a piped generator is used.

Example of manual execution for XorShift1024:

./build/kokkos_random_generator xorshift1024 uint64 98765 1048576 basic | ./practrand_bin/RNG_test stdin64 -tlmax 16GB -tlmaxonly -multithreaded -seed 98765

Telemetry & Outputs

• stdout: Reserved strictly for the raw binary streams sent to the test suite. Do not print tracking text here as it will corrupt test data.
• stderr: Displays progress counters (e.g., Data sent : X GiB) and PractRand's real-time report evaluations safely without interfering with the data pipeline.
• Kokkos Tools could be used to profile kokkos_random_generator. For proper documentation refer to the official documentation.