File 2874-Clarify-default-algorithm.patch of Package erlang
From 2287f07d142f9f37c3afec524990f87a3cb3b593 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 9 Dec 2020 14:39:19 +0100
Subject: [PATCH 4/6] Clarify "default algorithm"
---
lib/stdlib/doc/src/rand.xml | 75 ++++++++++++++++++++++++++++---------
1 file changed, 58 insertions(+), 17 deletions(-)
diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml
index 9e3c628920..bae50d2582 100644
--- a/lib/stdlib/doc/src/rand.xml
+++ b/lib/stdlib/doc/src/rand.xml
@@ -57,7 +57,10 @@
for calculating new states.
</p>
- <p>The following algorithms are provided:</p>
+ <p>
+ <marker id="algorithms"/>
+ The following algorithms are provided:
+ </p>
<taglist>
<tag><c>exsss</c></tag>
@@ -79,8 +82,11 @@
</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.
+ but is despite that the
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>
+ </seeerl>
+ thanks to its statistical qualities.
</p>
</item>
<tag><c>exro928ss</c></tag>
@@ -93,10 +99,13 @@
<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 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.
+ that on a 64 bit Erlang system executes only
+ about 40% slower than the
+ <seeerl marker="#default-algorithm">
+ <em>default</em> <c>exsss</c> <em>algorithm</em>
+ </seeerl>
+ but with much longer period and better statistical properties,
+ but on the flip side a larger state.
</p>
<p>
Many thanks to Sebastiano Vigna for his help with
@@ -118,7 +127,10 @@
<p>Xorshift116+, 58 bits precision and period of 2^116-1</p>
<p>Jump function: equivalent to 2^64 calls</p>
<p>
- This is a corrected version of the previous default algorithm,
+ This is a corrected version of the previous
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>,
+ </seeerl>
that now has been superseded by Xoroshiro116+ (<c>exrop</c>).
Since there is no native 58 bit rotate instruction this
algorithm executes a little (say < 15%) faster than <c>exrop</c>.
@@ -129,11 +141,20 @@
</taglist>
<p>
- The default algorithm is <c>exsss</c> (Xorshift116**).
+ <marker id="default-algorithm"/>
+ The current <em>default algorithm</em> is
+ <seeerl marker="#algorithms">
+ <c>exsss</c> (Xorshift116**).
+ </seeerl>
If a specific algorithm is
required, ensure to always use <seemfa marker="#seed/1">
<c>seed/1</c></seemfa> to initialize the state.
</p>
+ <p>
+ Which algorithm that is the default may change between
+ Erlang/OTP releases, and is selected to be one with high
+ speed, small state and "good enough" statistical properties.
+ </p>
<p>
Undocumented (old) algorithms are deprecated but still implemented
@@ -183,15 +204,23 @@
<seemfa marker="#uniform/1"><c>uniform/1</c></seemfa> or
<seemfa marker="#uniform_real/0"><c>uniform_real/0</c></seemfa> without
setting a seed first, <seemfa marker="#seed/1"><c>seed/1</c></seemfa>
- is called automatically with the default algorithm and creates a
- non-constant seed.</p>
+ is called automatically with the
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>
+ </seeerl>
+ and creates a non-constant seed.</p>
<p>The functions with explicit state never use the process dictionary.</p>
<p><em>Examples:</em></p>
- <p>Simple use; creates and seeds the default algorithm
- with a non-constant seed if not already done:</p>
+ <p>
+ Simple use; creates and seeds the
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>
+ </seeerl>
+ with a non-constant seed if not already done:
+ </p>
<pre>
R0 = rand:uniform(),
@@ -473,7 +502,10 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre>
time-dependent data if <c><anno>AlgOrStateOrExpState</anno></c>
is an algorithm.
<c><anno>Alg</anno> = default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>.
+ </seeerl>
</p>
<p>Otherwise recreates the exported seed in the process dictionary,
and returns the state. See also
@@ -490,7 +522,10 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre>
Seeds random number generation with the specified algorithm and
integers in the process dictionary and returns the state.
<c><anno>Alg</anno> = default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>.
+ </seeerl>
</p>
</desc>
</func>
@@ -505,7 +540,10 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre>
time-dependent data if <c><anno>AlgOrStateOrExpState</anno></c>
is an algorithm.
<c><anno>Alg</anno> = default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>.
+ </seeerl>
</p>
<p>Otherwise recreates the exported seed and returns the state.
See also <seemfa marker="#export_seed/0">
@@ -522,7 +560,10 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre>
Seeds random number generation with the specified algorithm and
integers and returns the state.
<c><anno>Alg</anno> = default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ <em>default algorithm</em>.
+ </seeerl>
</p>
</desc>
</func>
--
2.26.2
