Random Number Generators

Thor supports multiple RNG implementations for its Monte Carlo simulations, selectable at compile time and tested in CI.

Available RNGs

xoshiro128++ (Default)

Default. Fast and statistically excellent.

• Period: 2^128 - 1
• State size: 128 bits (4 × 32-bit)
• PractRand: Passed 32GB single-stream, 8GB multi-stream (16 streams)

Philox4x32R10

A counter-based RNG designed for parallel computing by D.E. Shaw Research. Ideal for GPU workloads.

• Period: 2^128
• State size: 128-bit counter + 64-bit key
• PractRand: Passed 32GB single-stream, 8GB multi-stream
• Advantage: Statistically independent streams by design

PCG32

The Permuted Congruential Generator with excellent statistical quality.

• Period: 2^64
• State size: 128 bits (64-bit state + 64-bit increment)
• PractRand: Passed 32GB single-stream, 8GB multi-stream (16 streams)
• Note: Slower on GPU due to 64-bit operations

PCG32fast

A simplified PCG variant optimized for speed. Not recommended due to poor statistical quality.

• Period: 2^32 (short!)
• State size: 32 bits
• PractRand: Failed at 1GB (FPF-14+6/16 test)

Changing the RNG

The RNG is selected at compile time via CMake:

# Use xoshiro128++ (default)
cmake -S . -B build -DTHOR_RNG_TYPE=xoshiro

# Use Philox (best for parallel/GPU)
cmake -S . -B build -DTHOR_RNG_TYPE=philox

# Use PCG32
cmake -S . -B build -DTHOR_RNG_TYPE=pcg32

Valid options: xoshiro (default), philox, pcg32

After changing, rebuild Thor:

cmake --build <build_dir> --target thor

The selected RNG is shown during CMake configuration:

-- RNG type: xoshiro (ID: 0)

Parallel Streams

For parallel simulations, each thread should use an independent stream. Initialize streams using:

RNG rng;
rng.set_seed(global_seed);
rng.set_sequence(thread_id);  // Creates independent stream

All recommended RNGs (xoshiro128++, Philox, PCG32) pass multi-stream statistical tests.

Statistical Testing with PractRand

Thor includes scripts for testing RNG quality using PractRand.

Install PractRand

./scripts/install_practrand.sh

This downloads, builds, and installs PractRand to ~/.local/bin/.

Run Tests

# Quick test (10 seconds)
./scripts/run_practrand.sh 10s xoshiro

# Thorough test (1GB of data)
./scripts/run_practrand.sh 1GB xoshiro

# Multi-stream test (4 interleaved streams)
./scripts/run_practrand.sh 8GB xoshiro 4

# Test all RNGs
./scripts/run_practrand.sh 1GB all

Interpreting Results

• "no anomalies": RNG passed all tests
• "unusual": Minor deviation, generally acceptable
• "suspicious": Worth investigating but not a failure
• "FAIL": RNG has statistical flaws, do not use

CI Testing

Thor includes automated CI testing for RNG quality. A weekly GitHub Actions job runs PractRand tests on all "reliable" RNGs.

Reliable RNGs

Each RNG class has a static constexpr bool reliable field indicating whether it should be tested in CI:

Workflow Details

• Schedule: Weekly on Sundays at 3:00 AM UTC
• Path triggers: Runs when src/rngs/** or test scripts are modified
• Test: 1GB PractRand for each reliable RNG
• Manual trigger: Available via workflow_dispatch

To run locally:

# Quick test
./scripts/run_practrand.sh 256MB reliable

# Full CI test
./scripts/run_practrand.sh 1GB reliable

Comparison RNGs

Thor also includes RNG implementations from other projects for comparison testing:

These are available in tests/rng_stdout_generator but not recommended for production use.