Module quickrand

Quick Random Number Generation

.

Copyright © 2012-2023 Michael Truog

Version: 2.0.7 Oct 26 2023 11:37:41 ------------------------------------------------------------------------

Authors: Michael Truog (mjtruog at protonmail dot com).

Description

Quick Random Number Generation

Data Types

algorithms()

algorithms() = lcg35x | mwc59x | mwc256 | rand | random_wh06_int | random_wh82

Function Index

lcg35x_32/1

35-bit state 32-bit value Linear Congruential Generators xor.

Both algorithms used for the variables LCG and MCG provide fast low-quality pseudo-random number generation without using Erlang bignums.
mwc256/1

256-bit state Marsaglia multiply-with-carry generator.

  T = A * X0 + C0
  X1 = Y0
  Y1 = Z0
  C1 = T bsr 64
  Z1 = T band 16#ffffffffffffffff
  A = 16#ff377e26f82da74a, 0 < X0, 0 < Y0, 0 < Z0, 0 < C0 < A - 1
 
  Simulates a multiplicative LCG with prime modulus
  M = 16#ff377e26f82da749ffffffffffffffffffffffffffffffffffffffffffffffff .
  The period is approximately 2^255.

Vigna, Sebastiano. https://prng.di.unimi.it/MWC256.c https://prng.di.unimi.it/#quality TestU01 BigCrush passed (p-value statistics are in [0.001..0.999]) when starting from 100 equispaced points of the state space.

Marsaglia, George.
mwc256_128/1

256-bit state 128-bit value Marsaglia multiply-with-carry generator.

mwc256/1 limited to a 128-bit return value for less latency.
mwc256_64/1

256-bit state 64-bit value Marsaglia multiply-with-carry generator.

mwc256/1 limited to a 64-bit return value for less latency.
mwc59x_32/1

59-bit state 32-bit value Marsaglia multiply-with-carry generator xor.

  T = A * X0 + C0
  C1 = T bsr 32
  X1 = T band 16#ffffffff
  A = 16#7fa6502, 0 < X0, 0 < C0 < A - 1
 
  Simulates a multiplicative LCG with prime modulus
  M = 16#7fa6501ffffffff (M = A * 2^32 - 1).
  The period is approximately 2^58.

X1 and C1 are combined with xor to produce a 32-bit random number. TestU01 SmallCrush/Crush/BigCrush have been used to test the 32-bit result (both with the bits forward and reversed) and the p-value statistics are in [0.0000001..0.9999999] (when starting from 100 equispaced points of the state space). The wider bounds (i.e., wider than [0.001..0.999]) are due to the shorter period.

.
seed/0

Randomized seeding of random number generators.

Backwards-compatible seeding of random number generators for this module's uniform prefix functions and the external modules used (rand, random_wh06_int and random_wh82). Use seed/1 to seed specific random number generators.

Instead of using this function, it is better to use a jump function for obtaining non-overlapping sequences, if a jump function is available and the number of Erlang processes used is limited (to ensure concurrent usage of the same algorithm has no collisions).
seed/1

Randomized seeding of specific random number generators.

Instead of using this function, it is better to use a jump function for obtaining non-overlapping sequences, if a jump function is available and the number of Erlang processes used is limited (to ensure concurrent usage of the same algorithm has no collisions).
strong_float/0

Return an Erlang double-precision random number with the range [0.0 .. 1.0].

.
strong_floatL/0

Return an Erlang double-precision random number with the range [0.0 .. 1.0).

Left portion of the 0.0 to 1.0 range.
strong_floatM/0

Return an Erlang double-precision random number with the range (0.0 .. 1.0).

Middle portion of the 0.0 to 1.0 range.
strong_floatR/0

Return an Erlang double-precision random number with the range (0.0 .. 1.0].

Right portion of the 0.0 to 1.0 range.
strong_uniform/1

Strong uniform random number generation.

.
strong_uniform_range/2

Strong uniform random number generation in a range.

.
uniform/1

Quick uniform random number generation.

Not meant for cryptographic purposes.
uniform_cache/1

Quick uniform random number generation with cached data.

Not meant for cryptographic purposes.
uniform_cache/2

Quick uniform random number generation with cached data.

Not meant for cryptographic purposes.

Function Details

lcg35x_32/1

lcg35x_32(N::1..4294967296) -> 1..4294967296

35-bit state 32-bit value Linear Congruential Generators xor.

Both algorithms used for the variables LCG and MCG provide fast low-quality pseudo-random number generation without using Erlang bignums.
  LCG:
    35-bit classical Linear Congruential Generator
    based on Erlang/OTP 25.0-rc3 rand:lcg35/1.
 
    X1 = (A * X0 + C) rem M
    A = 15319397, C = 15366142135, M = 2^35
 
    C is an odd value close to M / sqrt(5).
    The period is M (i.e., 2^35).
 
  MCG:
    35-bit Multiplicative Congruential Generator
    (i.e., Lehmer random number generator,
     Park-Miller random number generator)
    based on Erlang/OTP 25.0-rc3 rand:mcg35/1.
 
    X1 = (A * X0) rem M
    A = 185852, B = 35, D = 31, M = 2^B - D
 
    D makes M prime (M == 34359738337) so X0 is always coprime.
    The period is M (i.e., 2^35 - 31).

The LCG and MCG are combined with xor to produce a 32-bit random number. TestU01 SmallCrush/Crush/BigCrush have been used to test the 32-bit result (both with the bits forward and reversed) and the p-value statistics are in [0.0000001..0.9999999] (when starting from 100 equispaced points of the state space). The wider bounds (i.e., wider than [0.001..0.999]) are due to the shorter period.

mwc59x_32/1 is slighly more efficient but provides slightly less randomness (same p-value statistics bounds but the separate sums of (1e-8 .. 1e-4] and [1 - 1e-4 .. 1 - 1e-8) are less extreme for lcg35x_32/1, i.e., the mwc59x_32/1 (1e-8 .. 1e-4] sum is 25.5% smaller and the mwc59x_32/1 [1 - 1e-4 .. 1 - 1e-8) sum is 16.1% larger while mwc59x_32/1 provides roughly a 1.08x speedup with Erlang/OTP 25.0).

Pierre L'Ecuyer, Richard Simard. TestU01: A C Library for Empirical Testing of Random Number Generators. ACM Transactions on Mathematical Software, vol. 33, iss. 4, article 22, 2007. http://portal.acm.org/citation.cfm?doid=1268776.1268777 http://simul.iro.umontreal.ca/testu01/tu01.html

(A is selected from) L'Ecuyer, Pierre. Tables of linear congruential generators of different sizes and good lattice structure. Mathematics of Computation, vol. 68, no. 225, pp. 249–260, 1999. https://www.ams.org/journals/mcom/1999-68-225/S0025-5718-99-00996-5/ https://www.iro.umontreal.ca/~lecuyer/myftp/papers/latrules99Errata.pdf

mwc256/1

mwc256(N::pos_integer()) -> pos_integer()

256-bit state Marsaglia multiply-with-carry generator.

  T = A * X0 + C0
  X1 = Y0
  Y1 = Z0
  C1 = T bsr 64
  Z1 = T band 16#ffffffffffffffff
  A = 16#ff377e26f82da74a, 0 < X0, 0 < Y0, 0 < Z0, 0 < C0 < A - 1
 
  Simulates a multiplicative LCG with prime modulus
  M = 16#ff377e26f82da749ffffffffffffffffffffffffffffffffffffffffffffffff .
  The period is approximately 2^255.

Vigna, Sebastiano. https://prng.di.unimi.it/MWC256.c https://prng.di.unimi.it/#quality TestU01 BigCrush passed (p-value statistics are in [0.001..0.999]) when starting from 100 equispaced points of the state space.

Marsaglia, George. Xorshift RNGs. Journal of Statistical Software, vol. 8, no. 14, pp. 1–6, 2003-07. https://doi.org/10.18637/jss.v008.i14

mwc256_128/1

mwc256_128(N::1..340282366920938463463374607431768211456) -> 1..340282366920938463463374607431768211456

256-bit state 128-bit value Marsaglia multiply-with-carry generator.

mwc256/1 limited to a 128-bit return value for less latency.

mwc256_64/1

mwc256_64(N::1..18446744073709551616) -> 1..18446744073709551616

256-bit state 64-bit value Marsaglia multiply-with-carry generator.

mwc256/1 limited to a 64-bit return value for less latency.

mwc59x_32/1

mwc59x_32(N::1..4294967296) -> 1..4294967296

59-bit state 32-bit value Marsaglia multiply-with-carry generator xor.

  T = A * X0 + C0
  C1 = T bsr 32
  X1 = T band 16#ffffffff
  A = 16#7fa6502, 0 < X0, 0 < C0 < A - 1
 
  Simulates a multiplicative LCG with prime modulus
  M = 16#7fa6501ffffffff (M = A * 2^32 - 1).
  The period is approximately 2^58.

X1 and C1 are combined with xor to produce a 32-bit random number. TestU01 SmallCrush/Crush/BigCrush have been used to test the 32-bit result (both with the bits forward and reversed) and the p-value statistics are in [0.0000001..0.9999999] (when starting from 100 equispaced points of the state space). The wider bounds (i.e., wider than [0.001..0.999]) are due to the shorter period.

rand:mwc59/1 in Erlang/OTP 25.0 is similar. However, usage of rand:mwc59/1 with rand:mwc59_value32/1 clearly fails the TestU01 Crush and BigCrush tests (e.g., with X0 and C0 initially set to 1). mwc59x_32/1 was created to provide more statistically significant randomness than is possible when using rand:mwc59/1 .

Pierre L'Ecuyer, Richard Simard. TestU01: A C Library for Empirical Testing of Random Number Generators. ACM Transactions on Mathematical Software, vol. 33, iss. 4, article 22, 2007. http://portal.acm.org/citation.cfm?doid=1268776.1268777 http://simul.iro.umontreal.ca/testu01/tu01.html

Marsaglia, George. Xorshift RNGs. Journal of Statistical Software, vol. 8, no. 14, pp. 1–6, 2003-07. https://doi.org/10.18637/jss.v008.i14

seed/0

seed() -> ok

Randomized seeding of random number generators.

Backwards-compatible seeding of random number generators for this module's uniform prefix functions and the external modules used (rand, random_wh06_int and random_wh82). Use seed/1 to seed specific random number generators.

Instead of using this function, it is better to use a jump function for obtaining non-overlapping sequences, if a jump function is available and the number of Erlang processes used is limited (to ensure concurrent usage of the same algorithm has no collisions).

seed/1

seed(L::[all | quickrand | algorithms(), ...]) -> ok

Randomized seeding of specific random number generators.

Instead of using this function, it is better to use a jump function for obtaining non-overlapping sequences, if a jump function is available and the number of Erlang processes used is limited (to ensure concurrent usage of the same algorithm has no collisions).

strong_float/0

strong_float() -> float()

Return an Erlang double-precision random number with the range [0.0 .. 1.0].

strong_floatL/0

strong_floatL() -> float()

Return an Erlang double-precision random number with the range [0.0 .. 1.0).

Left portion of the 0.0 to 1.0 range.

strong_floatM/0

strong_floatM() -> float()

Return an Erlang double-precision random number with the range (0.0 .. 1.0).

Middle portion of the 0.0 to 1.0 range.

strong_floatR/0

strong_floatR() -> float()

Return an Erlang double-precision random number with the range (0.0 .. 1.0].

Right portion of the 0.0 to 1.0 range.

strong_uniform/1

strong_uniform(N::pos_integer()) -> pos_integer()

Strong uniform random number generation.

strong_uniform_range/2

strong_uniform_range(Min::integer(), Max::non_neg_integer()) -> integer()

Strong uniform random number generation in a range.

uniform/1

uniform(N::pos_integer()) -> pos_integer()

Quick uniform random number generation.

Not meant for cryptographic purposes.

uniform_cache/1

uniform_cache(N::pos_integer()) -> pos_integer()

Quick uniform random number generation with cached data.

Not meant for cryptographic purposes.

uniform_cache/2

uniform_cache(N::pos_integer(), State::quickrand_cache:state()) -> {pos_integer(), quickrand_cache:state()}

Quick uniform random number generation with cached data.

Not meant for cryptographic purposes.


Generated by EDoc