From a2e9b5a19d874c590b1227f6cd725627345e1214 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Sun, 23 Sep 2018 19:19:43 +0200 Subject: Update test suite and documentation --- lib/stdlib/doc/src/rand.xml | 81 ++++++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 27 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 25eec216ef..8e657698c6 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -38,34 +38,50 @@

This module provides a pseudo random number generator. The module contains a number of algorithms. - The uniform distribution algorithms use the + The uniform distribution algorithms are based on the - xoroshiro116+ and xorshift1024* algorithms by Sebastiano Vigna. + Xoroshiro and Xorshift algorithms + by Sebastiano Vigna. The normal distribution algorithm uses the Ziggurat Method by Marsaglia and Tsang on top of the uniform distribution algorithm.

-

For some algorithms, jump functions are provided for generating - non-overlapping sequences for parallel computations. - The jump functions perform calculations - equivalent to perform a large number of repeated calls - for calculating new states.

+

+ For most algorithms, jump functions are provided for generating + non-overlapping sequences for parallel computations. + The jump functions perform calculations + equivalent to perform a large number of repeated calls + for calculating new states. +

The following algorithms are provided:

- exrop + exsss -

Xoroshiro116+, 58 bits precision and period of 2^116-1

+

Xorshift116**, 58 bits precision and period of 2^116-1

Jump function: equivalent to 2^64 calls

- - exs1024s - -

Xorshift1024*, 64 bits precision and a period of 2^1024-1

-

Jump function: equivalent to 2^512 calls

+

+ This is the Xorshift116 generator combined with the StarStar scrambler + from the 2018 paper by David Blackman and Sebastiano Vigna: + + Scrambled Linear Pseudorandom Number Generators + +

+

+ The generator does not need 58-bit rotates so it is faster + than the Xoroshiro116 generator, and when combined with + the StarStar scrambler it does not have any weak low bits + like exrop (Xoroshiro116+). +

+

+ Alas, this combination is about 10% slower than exrop, + but is despite that the default algorithm thanks to its + statistical qualities. +

exro928ss @@ -77,8 +93,8 @@ Scrambled Linear Pseudorandom Number Generators - that on a 64 bit Erlang system executes only about 30% slower than - the default exrop algorithm but with much longer period + that on a 64 bit Erlang system executes only about 40% slower than + the default exsss algorithm but with much longer period and better statistical properties, and on the flip side a larger state.

@@ -87,6 +103,16 @@ the 58 bit adaption.

+ exrop + +

Xoroshiro116+, 58 bits precision and period of 2^116-1

+

Jump function: equivalent to 2^64 calls

+ + exs1024s + +

Xorshift1024*, 64 bits precision and a period of 2^1024-1

+

Jump function: equivalent to 2^512 calls

+ exsp

Xorshift116+, 58 bits precision and period of 2^116-1

@@ -103,7 +129,7 @@

- The default algorithm is exrop (Xoroshiro116+). + The default algorithm is exsss (Xorshift116**). If a specific algorithm is required, ensure to always use seed/1 to initialize the state. @@ -174,19 +200,19 @@ R1 = rand:uniform(),

Use a specified algorithm:

-_ = rand:seed(exs1024s),
+_ = rand:seed(exs928ss),
 R2 = rand:uniform(),

Use a specified algorithm with a constant seed:

-_ = rand:seed(exs1024s, {123, 123534, 345345}),
+_ = rand:seed(exs928ss, {123, 123534, 345345}),
 R3 = rand:uniform(),

Use the functional API with a non-constant seed:

-S0 = rand:seed_s(exrop),
+S0 = rand:seed_s(exsss),
 {R4, S1} = rand:uniform_s(S0),

Textbook basic form Box-Muller standard normal deviate

@@ -215,8 +241,9 @@ SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)

- For all these generators except exro928ss the lowest bit(s) - has got a slightly less random behaviour than all other bits. + For all these generators except exro928ss and exsss + the lowest bit(s) has got a slightly less + random behaviour than all other bits. 1 bit for exrop (and exsp), and 3 bits for exs1024s. See for example the explanation in the @@ -231,7 +258,7 @@ up to (and included) 16TB, with the exception of binary rank tests, which fail due to the lowest bit being an LFSR; all other bits pass all tests. We suggest to use a sign test to extract a random Boolean value.

- If this is a problem; to generate a boolean + If this is a problem; to generate a boolean with these algorithms use something like this: 

(rand:uniform(16) > 8)
@@ -299,19 +326,19 @@ tests. We suggest to use a sign test to extract a random Boolean value. - +

Algorithm specific internal state

 - +

Algorithm specific internal state

 - +

Algorithm specific internal state

 - +

Algorithm specific internal state

 -- cgit v1.2.3