diff options
author | Raimo Niskanen <[email protected]> | 2018-09-23 19:19:43 +0200 |
---|---|---|
committer | Raimo Niskanen <[email protected]> | 2018-10-05 11:12:45 +0200 |
commit | a2e9b5a19d874c590b1227f6cd725627345e1214 (patch) | |
tree | ad2e3575b9d11e872e3d8fe3cabb72085f3a4bce /lib/stdlib/doc/src | |
parent | 4a08841634b726fdd0c45bf8944a069813162794 (diff) | |
download | otp-a2e9b5a19d874c590b1227f6cd725627345e1214.tar.gz otp-a2e9b5a19d874c590b1227f6cd725627345e1214.tar.bz2 otp-a2e9b5a19d874c590b1227f6cd725627345e1214.zip |
Update test suite and documentation
Diffstat (limited to 'lib/stdlib/doc/src')
-rw-r--r-- | lib/stdlib/doc/src/rand.xml | 81 |
1 files changed, 54 insertions, 27 deletions
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 @@ <p> 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 <url href="http://xorshift.di.unimi.it"> - xoroshiro116+ and xorshift1024* algorithms by Sebastiano Vigna. + Xoroshiro and Xorshift algorithms </url> + by Sebastiano Vigna. The normal distribution algorithm uses the <url href="http://www.jstatsoft.org/v05/i08"> Ziggurat Method by Marsaglia and Tsang </url> on top of the uniform distribution algorithm. </p> - <p>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. </p> + <p> + 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. + </p> <p>The following algorithms are provided:</p> <taglist> - <tag><c>exrop</c></tag> + <tag><c>exsss</c></tag> <item> - <p>Xoroshiro116+, 58 bits precision and period of 2^116-1</p> + <p>Xorshift116**, 58 bits precision and period of 2^116-1</p> <p>Jump function: equivalent to 2^64 calls</p> - </item> - <tag><c>exs1024s</c></tag> - <item> - <p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p> - <p>Jump function: equivalent to 2^512 calls</p> + <p> + This is the Xorshift116 generator combined with the StarStar scrambler + from the 2018 paper by David Blackman and Sebastiano Vigna: + <url href="http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf"> + Scrambled Linear Pseudorandom Number Generators + </url> + </p> + <p> + 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 <c>exrop</c> (Xoroshiro116+). + </p> + <p> + Alas, this combination is about 10% slower than <c>exrop</c>, + but is despite that the default algorithm thanks to its + statistical qualities. + </p> </item> <tag><c>exro928ss</c></tag> <item> @@ -77,8 +93,8 @@ <url href="http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf"> Scrambled Linear Pseudorandom Number Generators </url> - that on a 64 bit Erlang system executes only about 30% slower than - the default <c>exrop</c> algorithm but with much longer period + that on a 64 bit Erlang system executes only about 40% slower than + the default <c>exsss</c> algorithm but with much longer period and better statistical properties, and on the flip side a larger state. </p> @@ -87,6 +103,16 @@ the 58 bit adaption. </p> </item> + <tag><c>exrop</c></tag> + <item> + <p>Xoroshiro116+, 58 bits precision and period of 2^116-1</p> + <p>Jump function: equivalent to 2^64 calls</p> + </item> + <tag><c>exs1024s</c></tag> + <item> + <p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p> + <p>Jump function: equivalent to 2^512 calls</p> + </item> <tag><c>exsp</c></tag> <item> <p>Xorshift116+, 58 bits precision and period of 2^116-1</p> @@ -103,7 +129,7 @@ </taglist> <p> - The default algorithm is <c>exrop</c> (Xoroshiro116+). + The default algorithm is <c>exsss</c> (Xorshift116**). If a specific algorithm is required, ensure to always use <seealso marker="#seed-1"> <c>seed/1</c></seealso> to initialize the state. @@ -174,19 +200,19 @@ R1 = rand:uniform(),</pre> <p>Use a specified algorithm:</p> <pre> -_ = rand:seed(exs1024s), +_ = rand:seed(exs928ss), R2 = rand:uniform(),</pre> <p>Use a specified algorithm with a constant seed:</p> <pre> -_ = rand:seed(exs1024s, {123, 123534, 345345}), +_ = rand:seed(exs928ss, {123, 123534, 345345}), R3 = rand:uniform(),</pre> <p>Use the functional API with a non-constant seed:</p> <pre> -S0 = rand:seed_s(exrop), +S0 = rand:seed_s(exsss), {R4, S1} = rand:uniform_s(S0),</pre> <p>Textbook basic form Box-Muller standard normal deviate</p> @@ -215,8 +241,9 @@ SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)</pre> </note> <p> - For all these generators except <c>exro928ss</c> the lowest bit(s) - has got a slightly less random behaviour than all other bits. + For all these generators except <c>exro928ss</c> and <c>exsss</c> + the lowest bit(s) has got a slightly less + random behaviour than all other bits. 1 bit for <c>exrop</c> (and <c>exsp</c>), and 3 bits for <c>exs1024s</c>. 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.</pre> <p> - 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: </p> <pre>(rand:uniform(16) > 8)</pre> @@ -299,19 +326,19 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </desc> </datatype> <datatype> - <name name="exrop_state"/> + <name name="exsplus_state"/> <desc><p>Algorithm specific internal state</p></desc> </datatype> <datatype> - <name name="exs1024_state"/> + <name name="exro928_state"/> <desc><p>Algorithm specific internal state</p></desc> </datatype> <datatype> - <name name="exro928_state"/> + <name name="exrop_state"/> <desc><p>Algorithm specific internal state</p></desc> </datatype> <datatype> - <name name="exsplus_state"/> + <name name="exs1024_state"/> <desc><p>Algorithm specific internal state</p></desc> </datatype> <datatype> |