File 2874-Clarify-default-algorithm.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

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.
 
 
- The following algorithms are provided:
+ 
+ <marker id="algorithms"/>
+ The following algorithms are provided:
+ 
 
 <taglist>
 <tag><c>exsss</c></tag>
@@ -79,8 +82,11 @@
 	
 	
 	 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">
+ default algorithm
+ </seeerl>
+ thanks to its statistical qualities.
 	
 </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">
+ default <c>exsss</c> algorithm
+ </seeerl>
+ but with much longer period and better statistical properties,
+ but on the flip side a larger state.
 	
 	
 	 Many thanks to Sebastiano Vigna for his help with
@@ -118,7 +127,10 @@
 Xorshift116+, 58 bits precision and period of 2^116-1
 Jump function: equivalent to 2^64 calls
 	
-	 This is a corrected version of the previous default algorithm,
+	 This is a corrected version of the previous
+ <seeerl marker="#default-algorithm">
+ default algorithm,
+ </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 &lt; 15%) faster than <c>exrop</c>.
@@ -129,11 +141,20 @@
 </taglist>
 
 
- The default algorithm is <c>exsss</c> (Xorshift116**).
+ <marker id="default-algorithm"/>
+ The current default algorithm 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.
 
+ 
+ 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.
+ 
 
 
 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.
+ is called automatically with the
+ <seeerl marker="#default-algorithm">
+ default algorithm
+ </seeerl>
+ and creates a non-constant seed.
 
 The functions with explicit state never use the process dictionary.
 
 Examples:
 
- Simple use; creates and seeds the default algorithm
- with a non-constant seed if not already done:
+ 
+ Simple use; creates and seeds the
+ <seeerl marker="#default-algorithm">
+ default algorithm
+ </seeerl>
+ with a non-constant seed if not already done:
+ 
 
 <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>&nbsp;=&nbsp;default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ default algorithm.
+ </seeerl>
 	
 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>&nbsp;=&nbsp;default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ default algorithm.
+ </seeerl>
 
 </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>&nbsp;=&nbsp;default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ default algorithm.
+ </seeerl>
 	
 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>&nbsp;=&nbsp;default</c>
- is an alias for the default algorithm.
+ is an alias for the
+ <seeerl marker="#default-algorithm">
+ default algorithm.
+ </seeerl>
 
 </desc>
 </func>
-- 
2.26.2

Places

File 2874-Clarify-default-algorithm.patch of Package erlang

Places