diff options
Diffstat (limited to 'lib/stdlib/doc/src/rand.xml')
| -rw-r--r-- | lib/stdlib/doc/src/rand.xml | 152 |
1 files changed, 130 insertions, 22 deletions
diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 89fb858823..27d2d99f3c 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -32,7 +32,7 @@ <rev>A</rev> <file>rand.xml</file> </header> - <module>rand</module> + <module since="OTP 18.0">rand</module> <modulesummary>Pseudo random number generation.</modulesummary> <description> <p> @@ -133,8 +133,9 @@ variable <c>rand_seed</c> to remember the current state.</p> <p>If a process calls - <seealso marker="#uniform-0"><c>uniform/0</c></seealso> or - <seealso marker="#uniform-1"><c>uniform/1</c></seealso> without + <seealso marker="#uniform-0"><c>uniform/0</c></seealso>, + <seealso marker="#uniform-1"><c>uniform/1</c></seealso> or + <seealso marker="#uniform_real-0"><c>uniform_real/0</c></seealso> without setting a seed first, <seealso marker="#seed-1"><c>seed/1</c></seealso> is called automatically with the default algorithm and creates a non-constant seed.</p> @@ -168,10 +169,17 @@ R3 = rand:uniform(),</pre> S0 = rand:seed_s(exrop), {R4, S1} = rand:uniform_s(S0),</pre> + <p>Textbook basic form Box-Muller standard normal deviate</p> + + <pre> +R5 = rand:uniform_real(), +R6 = rand:uniform(), +SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)</pre> + <p>Create a standard normal deviate:</p> <pre> -{SND0, S2} = rand:normal_s(S1),</pre> +{SND1, S2} = rand:normal_s(S1),</pre> <p>Create a normal deviate with mean -3 and variance 0.5:</p> @@ -265,7 +273,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> <funcs> <func> - <name name="export_seed" arity="0"/> + <name name="export_seed" arity="0" since="OTP 18.0"/> <fsummary>Export the random number generation state.</fsummary> <desc><marker id="export_seed-0"/> <p>Returns the random number state in an external format. @@ -274,7 +282,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="export_seed_s" arity="1"/> + <name name="export_seed_s" arity="1" since="OTP 18.0"/> <fsummary>Export the random number generation state.</fsummary> <desc><marker id="export_seed_s-1"/> <p>Returns the random number generator state in an external format. @@ -283,7 +291,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="jump" arity="0"/> + <name name="jump" arity="0" since="OTP 20.0"/> <fsummary>Return the seed after performing jump calculation to the state in the process dictionary.</fsummary> <desc><marker id="jump-0" /> @@ -298,7 +306,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="jump" arity="1"/> + <name name="jump" arity="1" since="OTP 20.0"/> <fsummary>Return the seed after performing jump calculation.</fsummary> <desc><marker id="jump-1" /> <p>Returns the state after performing jump calculation @@ -310,7 +318,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal" arity="0"/> + <name name="normal" arity="0" since="OTP 18.0"/> <fsummary>Return a standard normal distributed random float.</fsummary> <desc> <p>Returns a standard normal deviate float (that is, the mean @@ -320,7 +328,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal" arity="2"/> + <name name="normal" arity="2" since="OTP 20.0"/> <fsummary>Return a normal distributed random float.</fsummary> <desc> <p>Returns a normal N(Mean, Variance) deviate float @@ -329,7 +337,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal_s" arity="1"/> + <name name="normal_s" arity="1" since="OTP 18.0"/> <fsummary>Return a standard normal distributed random float.</fsummary> <desc> <p>Returns, for a specified state, a standard normal @@ -339,7 +347,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal_s" arity="3"/> + <name name="normal_s" arity="3" since="OTP 20.0"/> <fsummary>Return a normal distributed random float.</fsummary> <desc> <p>Returns, for a specified state, a normal N(Mean, Variance) @@ -348,7 +356,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="seed" arity="1"/> + <name name="seed" arity="1" since="OTP 18.0"/> <fsummary>Seed random number generator.</fsummary> <desc> <marker id="seed-1"/> @@ -364,7 +372,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="seed" arity="2"/> + <name name="seed" arity="2" since="OTP 18.0"/> <fsummary>Seed the random number generation.</fsummary> <desc> <p>Seeds random number generation with the specified algorithm and @@ -373,7 +381,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="seed_s" arity="1"/> + <name name="seed_s" arity="1" since="OTP 18.0"/> <fsummary>Seed random number generator.</fsummary> <desc> <p> @@ -388,7 +396,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="seed_s" arity="2"/> + <name name="seed_s" arity="2" since="OTP 18.0"/> <fsummary>Seed the random number generation.</fsummary> <desc> <p>Seeds random number generation with the specified algorithm and @@ -397,7 +405,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="uniform" arity="0"/> + <name name="uniform" arity="0" since="OTP 18.0"/> <fsummary>Return a random float.</fsummary> <desc><marker id="uniform-0"/> <p> @@ -414,7 +422,8 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> This function may return exactly <c>0.0</c> which can be fatal for certain applications. If that is undesired you can use <c>(1.0 - rand:uniform())</c> to get the - interval <c>0.0 < <anno>X</anno> =< 1.0</c>. + interval <c>0.0 < <anno>X</anno> =< 1.0</c>, or instead use + <seealso marker="#uniform_real-0"><c>uniform_real/0</c></seealso>. </p> <p> If neither endpoint is desired you can test and re-try @@ -432,7 +441,43 @@ end.</pre> </func> <func> - <name name="uniform" arity="1"/> + <name name="uniform_real" arity="0" since="OTP 21.0"/> + <fsummary>Return a random float.</fsummary> + <desc><marker id="uniform_real-0"/> + <p> + Returns a random float + uniformly distributed in the value range + <c>DBL_MIN =< <anno>X</anno> < 1.0</c> + and updates the state in the process dictionary. + </p> + <p> + Conceptually, a random real number <c>R</c> is generated + from the interval <c>0 =< R < 1</c> and then the + closest rounded down normalized number + in the IEEE 754 Double precision format + is returned. + </p> + <note> + <p> + The generated numbers from this function has got better + granularity for small numbers than the regular + <seealso marker="#uniform-0"><c>uniform/0</c></seealso> + because all bits in the mantissa are random. + This property, in combination with the fact that exactly zero + is never returned is useful for algoritms doing for example + <c>1.0 / <anno>X</anno></c> or <c>math:log(<anno>X</anno>)</c>. + </p> + </note> + <p> + See + <seealso marker="#uniform_real_s-1"><c>uniform_real_s/1</c></seealso> + for more explanation. + </p> + </desc> + </func> + + <func> + <name name="uniform" arity="1" since="OTP 18.0"/> <fsummary>Return a random integer.</fsummary> <desc><marker id="uniform-1"/> <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>, @@ -443,7 +488,7 @@ end.</pre> </func> <func> - <name name="uniform_s" arity="1"/> + <name name="uniform_s" arity="1" since="OTP 18.0"/> <fsummary>Return a random float.</fsummary> <desc> <p> @@ -460,7 +505,8 @@ end.</pre> This function may return exactly <c>0.0</c> which can be fatal for certain applications. If that is undesired you can use <c>(1.0 - rand:uniform(State))</c> to get the - interval <c>0.0 < <anno>X</anno> =< 1.0</c>. + interval <c>0.0 < <anno>X</anno> =< 1.0</c>, or instead use + <seealso marker="#uniform_real_s-1"><c>uniform_real_s/1</c></seealso>. </p> <p> If neither endpoint is desired you can test and re-try @@ -478,7 +524,69 @@ end.</pre> </func> <func> - <name name="uniform_s" arity="2"/> + <name name="uniform_real_s" arity="1" since="OTP 21.0"/> + <fsummary>Return a random float.</fsummary> + <desc> + <p> + Returns, for a specified state, a random float + uniformly distributed in the value range + <c>DBL_MIN =< <anno>X</anno> < 1.0</c> + and updates the state in the process dictionary. + </p> + <p> + Conceptually, a random real number <c>R</c> is generated + from the interval <c>0 =< R < 1</c> and then the + closest rounded down normalized number + in the IEEE 754 Double precision format + is returned. + </p> + <note> + <p> + The generated numbers from this function has got better + granularity for small numbers than the regular + <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso> + because all bits in the mantissa are random. + This property, in combination with the fact that exactly zero + is never returned is useful for algoritms doing for example + <c>1.0 / <anno>X</anno></c> or <c>math:log(<anno>X</anno>)</c>. + </p> + </note> + <p> + The concept implicates that the probability to get + exactly zero is extremely low; so low that this function + is in fact guaranteed to never return zero. The smallest + number that it might return is <c>DBL_MIN</c>, which is + 2.0^(-1022). + </p> + <p> + The value range stated at the top of this function + description is technically correct, but + <c>0.0 =< <anno>X</anno> < 1.0</c> + is a better description of the generated numbers' + statistical distribution. Except that exactly 0.0 + is never returned, which is not possible to observe + statistically. + </p> + <p> + For example; for all sub ranges + <c>N*2.0^(-53) =< X < (N+1)*2.0^(-53)</c> + where + <c>0 =< integer(N) < 2.0^53</c> + the probability is the same. + Compare that with the form of the numbers generated by + <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso>. + </p> + <p> + Having to generate extra random bits for + small numbers costs a little performance. + This function is about 20% slower than the regular + <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso> + </p> + </desc> + </func> + + <func> + <name name="uniform_s" arity="2" since="OTP 18.0"/> <fsummary>Return a random integer.</fsummary> <desc> <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c> |