RNG_Options.md

RNG engine selection (RNG_IMPLEMENTATION) options

RNG_IMPLEMENTATION=: Choose which random number generator algorithm to use. If unset, then it chooses an unspecified default, possibly depending on platform, architecture, and optimization flags.

The random number generator chosen has a surprisingly outsized influence on the throughput of recipesAtHome, which is why there are so many options available

Supported values are: default, system, lehmer, wyhash, xoshiro, lcg, mersenne_twister, subtract_with_carry, pcg, pcg_cpp

WARNING: Any C++ based implementation will also require having the C++ standard library at runtime. For full binary distributions, this can lead to a noticeable increase in total package size, especially if debugging symbols are kept.

Options

• default: Use a sensible but unspecified default as defined by the project. This is (naturally) the default.

• system (aliases: sys, rand, builtin, stdlib): Use the built-in C standard library rand implementation (with mild wrapper logic to make it thread safe).

  Tends to be relatively expensive for poor quality randomness (especially on Windows), but has the advantage of needing no extra code compiled in to increase binary size.

• lehmer (alias: lehmer64): The Lehmer random number generator, named after (not authored by) D. H. Lehmer. https://lemire.me/blog/2019/03/19/the-fastest-conventional-random-number-generator-that-can-pass-big-crush/

  The included implementation was written by Daniel Lemire (lemire) https://github.com/lemire/testingRNG

  Despite "lemire-testingRNG" being a submodule, this option doesn't require it due to limitations of that implementation forcing local copies with modification.

  An extremely lightweight random number generator. It consists of only a multiply (by a large constant) and a shift, with 128 bits of state. High speed and with reasonable randomness characteristics.

  However, some processors are not very good at handling 128 bit integer operations quickly, in which case the performance gains may not be full realized.

  This is a pure C implementation, no C++ library will be needed at runtime.

• wyhash (aliases: wyhash64, wyhash-lemire, wyhash64-lemire, wyrand, wyrand-lemire): The wyhash algorithm, which has close connections to the MUM hash functions developed by Vladimir Makarov. https://lemire.me/blog/2019/03/19/the-fastest-conventional-random-number-generator-that-can-pass-big-crush/

  The included implementation was written by Daniel Lemire (lemire) https://github.com/lemire/testingRNG

  Despite "lemire-testingRNG" being a submodule, this option doesn't require it due to limitations of that implementation forcing local copies with modification.

  Also very similar to MUM-prng, also by Vladimir Makarov

  A quite lightweight random number generator. It consists of addition, multiplication (by large constants), xors, and shift operations, with 64 bits of state. High speed and with reasonable randomness characteristics.

  Despite the higher complexity, in practice it is competitive with lehmer64 in terms of throughput.

  Despite having only 64 bits of state, some intermediary computations use 128 bit integers. Some processors are not very good at handling 128 bit integer operations quickly, in which case the performance gains may not be full realized.

  Precisely which variant of the algorithm (32-bit is chosen is unspecified.

  This is a pure C implementation, no C++ library will be needed at runtime.

• xoshiro (aliases: xoshiro_cpp, xoshiro-cpp) The Xoshiro XOR/shift/rotate random number generator, developed by David Blackman and Sebastiano Vigna https://prng.di.unimi.it/

  This adaption to the C++ <random> API was written by Ryo Suzuki (Reputeless) https://github.com/Reputeless/Xoshiro-cpp

  If chosen, the "Xoshiro-cpp" submodule must be populated.

  Provides a fast random number generator with reasonable randomness characteristics, but has been noted to sometimes struggle with shorter then intended periods for some seed inputs. Compared to lehmer64, it has a much larger state space (twice as much) and a more complicated algorithm. But it avoids multiplications where both factors are potentially over the whole space of the data type, which are more likely to optimize cleanly.

  Precisely which variant of the algorithm is chosen is unspecified.

  If the overhead of the C++ "" library proves to be too high in practice, then a pure C implementation may be added. If this happens, then xoshiro_cpp will become this implementation, and xoshiro will become the pure C implementation.

• lcg (aliases: lcg-cpp, linear_congruential_engine, linear_congruential_engine-cpp) A linear congruential engine random number generator.

  This is exactly std::linear_congruential_engine from the C++ library standard https://en.cppreference.com/w/cpp/numeric/random/linear_congruential_engine

  The simplest random number algorithm in the standard C++ library, but exact characteristics will depend on the specific C++ library used.

  The exact algorithm parameters are unspecified, but is likely to be one of the standard variants (e.g. std::minstd_rand)

• mersenne_twister (aliases: mersenne_twister-cpp, mersenne_twister_engine, mersenne_twister_engine_cpp) The Mersenne Twister algorithm

  This is exactly std::linear_congruential_engine from the C++ library standard https://en.cppreference.com/w/cpp/numeric/random/linear_congruential_engine

  Provides quite high randomness characteristics (but obviously not cryptographically secure) at low to moderate speeds.

  The exact algorithm parameters are unspecified, but is likely to be one of the standard variants (e.g. std::mt19937_64)

• subtract_with_carry (aliases: subtract_with_carry-cpp, subtract_with_carry_engine, subtract_with_carry_engine-cpp, lagged_fibonacci, lagged_fibonacci-cpp) The lagged Fibonachi algorithm (a type of subtract with carry algorithm)

  This is exactly std::subtract_with_carry from the C++ library standard https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine

  Probably the fastest of the C++ standard library random generators, but the quality of the randomness is largely unexplored and unknown.

  The exact algorithm parameters are unspecified, but is likely to be one of the standard variants (e.g. std::ranlux48_base)

• pcg (aliases: pcg_c pcg-c, pcg-random) The PCG random number generator (pure C implementation), developed by Melissa E. O’Neill https://www.pcg-random.org/

  The implementation used here was written by imneme (GitHub user name, no other name given) https://github.com/imneme/pcg-c-basic

  If chosen, the pcg-c-basic submodule must be populated.

  A reasonably fast random number generator, but has been known to fail some randomness tests. Uses up to 128 bits of state.

  This is a pure C implementation, no C++ library will be needed at runtime.

  An alternate version, pcg-cpp, is available which does use C++'s <random> apis.

• pcg_cpp (aliases: pcg-cpp, pcg-random-cpp) The PCG random number generator, developed by Melissa E. O’Neill https://www.pcg-random.org/

  The implementation used here was written by imneme (GitHub user name, no other name given) https://github.com/imneme/pcg-cpp

  If chosen, the pcg-cpp submodule must be populated.

  A reasonably fast random number generator, but has been known to fail some randomness tests. Uses up to 128 bits of state. Some processors are not very good at handling 128 bit integer operations quickly, in which case the performance gains may not be full realized.