Ranx Command Line Tool

Ranx command line tool is a parallel random number generator utility built on the Ranx library. It provides functionality similar to the Ubuntu rand utility but leverages the high-performance, reproducible random number generation capabilities of the Ranx library.

Features¶

• Fast parallel random number generation using the PCG family of generators
• Reproducible sequences across all platforms when using the same seed
• Multiple output formats: integers, floats, unique values
• Flexible formatting: custom delimiters and output boundaries
• High-quality randomness using PCG32 engine with TRNG distributions

Building¶

The utility is built automatically when building the Ranx library (unless disabled):

cmake -S . -B build
cmake --build build -j

To disable building the utility:

cmake -S . -B build -DRANX_BUILD_UTILITY=OFF

Installation¶

cmake --install build

This installs the ranx executable to your system’s binary directory (typically /usr/local/bin).

Usage¶

ranx [OPTION]

Options¶

• -N count - Number of random numbers to generate (default=1)
• -L, --min number - The lower limit of the random numbers (default=0)
• -M, --max number - The upper limit of the random numbers (default: 32576)
• -u, --unique - Generate unique numbers without duplicates
• -f - Generate floating-point numbers between 0 and 1
• -p precision - Set decimal precision for floats (activates -f)
• -s number - Set the random seed (default: current time)
• -d STRING - Delimiter between numbers (default: space)
• --bof STRING - String to print at the beginning
• --eof STRING - String to print at the end (default: newline)
• --help - Display help message
• --version - Show version information

Examples¶

Generate 10 random numbers:

!ranx -N 10

5278 3664 13264 19241 8205 12455 2035 18563 21814 24187

Generate 5 numbers from 0 to 100 (closed range):

!ranx -N 5 -M 100

88 74 60 61 2

Generate 10 unique numbers from 10 to 20 (closed range):

!ranx -N 10 -u -L 10 -M 20

20 18 17 12 11 13 14 19 16 10

Generate 5 floating-point numbers with 4 decimal places:

!ranx -f -p 4 -N 5

0.1297 0.8652 0.7456 0.4184 0.0218

Generate numbers separated by commas:

!ranx -N 5 -d ", "

26483, 29423, 27826, 30380, 12425

Generate reproducible sequence with a specific seed:

!ranx -N 10 -s 42

24808 13619 14597 8669 31263 13328 25930 27223 15641 32458

Format as a JSON array:

!ranx -N 5 -d ", " --bof "[" --eof "]"

[17493, 30869, 16604, 18438, 11029]

Technical Details¶

Random Number Engine¶

The utility uses the PCG32 (Permuted Congruential Generator) engine from the PCG family, which provides:

• Excellent statistical properties
• Fast generation speed
• Small state size
• Reproducible sequences

Distributions¶

• Integers: Uses trng::uniform_int_dist for uniform integer distribution
• Floats: Uses trng::uniform01_dist for uniform distribution between 0 and 1
• Unique values: Uses Fisher-Yates shuffle via std::shuffle with PCG32 (not parallel yet)

Reproducibility¶

When you provide the same seed with -s, the utility guarantees identical output on all supported platforms (Linux/macOS/Windows):

!ranx -N 5 -s 123

27606 20324 14982 6188 27424

Comparison with Ubuntu rand¶

This implementation provides similar functionality to the Ubuntu rand utility with some enhancements:

Similarities¶

• Command-line interface and option names
• Support for integer and float generation
• Custom delimiters and formatting options
• Seed-based reproducibility

Differences¶

• Does support a new flag for the low limit (-L/--min flags)
• Uses high-quality PCG32 engine (vs. standard C library RNG)
• Built on the ranx parallel generation library
• Does not support backslash escape interpretation (-e/-E flags)
• Does not support mask formatting (--mask flag)

License¶

MIT License - Copyright (c) 2025 Armin Sobhani

See Also¶

• PCG Random Number Generators
• TRNG library
• Ubuntu rand utility