From 0248865dea315253618e733d77177b5a80679e20 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 14 Sep 2017 15:57:16 +0200 Subject: Implement uniform_real/0 and uniform_real_s/1 --- lib/stdlib/doc/src/rand.xml | 118 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 113 insertions(+), 5 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 89fb858823..21f680a0ee 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -133,8 +133,9 @@ variable rand_seed to remember the current state.

If a process calls - uniform/0 or - uniform/1 without + uniform/0, + uniform/1 or + uniform_real/0 without setting a seed first, seed/1 is called automatically with the default algorithm and creates a non-constant seed.

@@ -168,10 +169,17 @@ R3 = rand:uniform(), S0 = rand:seed_s(exrop), {R4, S1} = rand:uniform_s(S0), +

Textbook basic form Box-Muller standard normal deviate

+ + 
+R5 = rand:uniform_real(),
+R6 = rand:uniform(),
+SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)
+

Create a standard normal deviate:

-{SND0, S2} = rand:normal_s(S1),
+{SND1, S2} = rand:normal_s(S1),

Create a normal deviate with mean -3 and variance 0.5:

@@ -414,7 +422,8 @@ tests. We suggest to use a sign test to extract a random Boolean value. This function may return exactly 0.0 which can be fatal for certain applications. If that is undesired you can use (1.0 - rand:uniform()) to get the - interval 0.0 < X =< 1.0. + interval 0.0 < X =< 1.0, or instead use + uniform_real/0.

If neither endpoint is desired you can test and re-try @@ -431,6 +440,42 @@ end. + + + Return a random float. + +

+ Returns a random float + uniformly distributed in the value range + DBL_MIN =< X < 1.0 + and updates the state in the process dictionary. +

+

+ Conceptually, a random real number R is generated + from the interval 0 =< R < 1 and then the + closest rounded down normalized number + in the IEEE 754 Double precision format + is returned. +

+ +

+ The generated numbers from this function has got better + granularity for small numbers than the regular + uniform/0 + 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 + 1.0 / X or math:log(X). +

+ +

+ See + uniform_real_s/1 + for more explanation. +

+ + + Return a random integer. @@ -460,7 +505,8 @@ end. This function may return exactly 0.0 which can be fatal for certain applications. If that is undesired you can use (1.0 - rand:uniform(State)) to get the - interval 0.0 < X =< 1.0. + interval 0.0 < X =< 1.0, or instead use + uniform_real_s/1.

If neither endpoint is desired you can test and re-try @@ -477,6 +523,68 @@ end. + + + Return a random float. + +

+ Returns, for a specified state, a random float + uniformly distributed in the value range + DBL_MIN =< X < 1.0 + and updates the state in the process dictionary. +

+

+ Conceptually, a random real number R is generated + from the interval 0 =< R < 1 and then the + closest rounded down normalized number + in the IEEE 754 Double precision format + is returned. +

+ +

+ The generated numbers from this function has got better + granularity for small numbers than the regular + uniform_s/1 + 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 + 1.0 / X or math:log(X). +

+ +

+ 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 DBL_MIN, which is + 2.0^(-1022). +

+

+ The value range stated at the top of this function + description is technically correct, but + 0.0 =< X < 1.0 + 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. +

+

+ For example; for all sub ranges + N*2.0^(-53) =< X < (N+1)*2.0^(-53) + where + 0 =< integer(N) < 2.0^53 + the probability is the same. + Compare that with the form of the numbers generated by + uniform_s/1. +

+

+ Having to generate extra random bits for + small numbers costs a little performance. + This function is about 20% slower than the regular + uniform_s/1 +

+ + + Return a random integer. -- cgit v1.2.3