From 294a18cd2dc682581ec3596002d36c71bf7899ec Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 13 Oct 2020 13:27:04 -0700 Subject: [PATCH 1/5] Move the conceptual equivalent to the end --- Doc/library/random.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index c19a8e0a7cb5ba..d59a8adf4236cd 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -526,16 +526,10 @@ are not possible selections. For example, ``0.05954861408025609`` isn't an integer multiple of 2⁻⁵³. The following recipe takes a different approach. All floats in the -interval are possible selections. Conceptually it works by choosing -from evenly spaced multiples of 2⁻¹⁰⁷⁴ and then rounding down to the -nearest representable float. - -For efficiency, the actual mechanics involve calling -:func:`~math.ldexp` to construct a representable float. The mantissa -comes from a uniform distribution of integers in the range *2⁵² ≤ -mantissa < 2⁵³*. The exponent comes from a geometric distribution -where exponents smaller than *-53* occur half as often as the next -larger exponent. +interval are possible selections. The mantissa comes from a uniform +distribution of integers in the range *2⁵² ≤ mantissa < 2⁵³*. The +exponent comes from a geometric distribution where exponents smaller +than *-53* occur half as often as the next larger exponent. :: @@ -561,6 +555,12 @@ All of the real valued distributions will use the new method:: >>> fr.expovariate(0.25) 8.87925541791544 +Conceptually, the recipe is equivalent to choosing from all multiples of +2⁻¹⁰⁷⁴ in the range *0.0 ≤ x < 1.0*. All such numbers are evenly spaced +but most have to be rounded down to the nearest representable Python +float. (The value 2⁻¹⁰⁷⁴ is the smallest possible unnormalized float +and is equal to ``math.ulp(0.0)``.) + .. seealso:: From b770747ffa8704e3c3a302870458ecb53c0d2c71 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 13 Oct 2020 13:57:30 -0700 Subject: [PATCH 2/5] Separate the see also sections. Other minor edits. --- Doc/library/random.rst | 56 +++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index d59a8adf4236cd..009c2b4469b51f 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -253,6 +253,8 @@ Functions for sequences order so that the sample is reproducible. +.. _real-valued-distributions: + Real-valued distributions ------------------------- @@ -516,11 +518,33 @@ Simulation of arrival times and service deliveries for a multiserver queue:: print(f'Mean wait: {mean(waits):.1f} Max wait: {max(waits):.1f}') print('Quartiles:', [round(q, 1) for q in quantiles(waits)]) +.. seealso:: + + `Statistics for Hackers `_ + a video tutorial by + `Jake Vanderplas `_ + on statistical analysis using just a few fundamental concepts + including simulation, sampling, shuffling, and cross-validation. + + `Economics Simulation + `_ + a simulation of a marketplace by + `Peter Norvig `_ that shows effective + use of many of the tools and distributions provided by this module + (gauss, uniform, sample, betavariate, choice, triangular, and randrange). + + `A Concrete Introduction to Probability (using Python) + `_ + a tutorial by `Peter Norvig `_ covering + the basics of probability theory, how to write simulations, and + how to perform data analysis using Python. + + Recipes ------- The default :func:`.random` returns multiples of 2⁻⁵³ in the range -*0.0 ≤ x < 1.0*. All such numbers are evenly spaced and exactly +*0.0 ≤ x < 1.0*. All such numbers are evenly spaced and are exactly representable as Python floats. However, many floats in that interval are not possible selections. For example, ``0.05954861408025609`` isn't an integer multiple of 2⁻⁵³. @@ -547,7 +571,8 @@ than *-53* occur half as often as the next larger exponent. exponent += x.bit_length() - 32 return ldexp(mantissa, exponent) -All of the real valued distributions will use the new method:: +All of the :ref:`real valued distributions ` +in the class will use the new method:: >>> fr = FullRandom() >>> fr.random() @@ -556,33 +581,14 @@ All of the real valued distributions will use the new method:: 8.87925541791544 Conceptually, the recipe is equivalent to choosing from all multiples of -2⁻¹⁰⁷⁴ in the range *0.0 ≤ x < 1.0*. All such numbers are evenly spaced -but most have to be rounded down to the nearest representable Python -float. (The value 2⁻¹⁰⁷⁴ is the smallest possible unnormalized float -and is equal to ``math.ulp(0.0)``.) +2⁻¹⁰⁷⁴ in the range *0.0 ≤ x < 1.0*. All such numbers are evenly +spaced, but most have to be rounded down to the nearest representable +Python float. (The value 2⁻¹⁰⁷⁴ is the smallest positive unnormalized +float and is equal to ``math.ulp(0.0)``.) .. seealso:: - `Statistics for Hackers `_ - a video tutorial by - `Jake Vanderplas `_ - on statistical analysis using just a few fundamental concepts - including simulation, sampling, shuffling, and cross-validation. - - `Economics Simulation - `_ - a simulation of a marketplace by - `Peter Norvig `_ that shows effective - use of many of the tools and distributions provided by this module - (gauss, uniform, sample, betavariate, choice, triangular, and randrange). - - `A Concrete Introduction to Probability (using Python) - `_ - a tutorial by `Peter Norvig `_ covering - the basics of probability theory, how to write simulations, and - how to perform data analysis using Python. - `Generating Pseudo-random Floating-Point Values `_ a paper by Allen B. Downey describing ways to generate more From 136e7bb51a688a764bc8d971cda4481570b6c34b Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 13 Oct 2020 14:02:16 -0700 Subject: [PATCH 3/5] Tighten-up the final paragraph wording --- Doc/library/random.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 009c2b4469b51f..51185a2d235011 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -580,11 +580,11 @@ in the class will use the new method:: >>> fr.expovariate(0.25) 8.87925541791544 -Conceptually, the recipe is equivalent to choosing from all multiples of -2⁻¹⁰⁷⁴ in the range *0.0 ≤ x < 1.0*. All such numbers are evenly -spaced, but most have to be rounded down to the nearest representable -Python float. (The value 2⁻¹⁰⁷⁴ is the smallest positive unnormalized -float and is equal to ``math.ulp(0.0)``.) +Conceptually, the recipe chooses from the multiples of 2⁻¹⁰⁷⁴ in the +range *0.0 ≤ x < 1.0*. All such numbers are evenly spaced, but most +have to be rounded down to the nearest representable Python float. (The +value 2⁻¹⁰⁷⁴ is the smallest positive unnormalized float and is equal to +``math.ulp(0.0)``.) .. seealso:: From d379e35b5716d0ec6f65f5f91154740b262010b4 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 13 Oct 2020 14:11:16 -0700 Subject: [PATCH 4/5] Grammar fix --- Doc/library/random.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 51185a2d235011..b5aea7c2a0baf1 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -571,7 +571,7 @@ than *-53* occur half as often as the next larger exponent. exponent += x.bit_length() - 32 return ldexp(mantissa, exponent) -All of the :ref:`real valued distributions ` +All :ref:`real valued distributions ` in the class will use the new method:: >>> fr = FullRandom() From 168fb5669edeba2b788d5096123af62389867d32 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 13 Oct 2020 16:20:58 -0700 Subject: [PATCH 5/5] Tweak wording of the final paragraph. --- Doc/library/random.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index b5aea7c2a0baf1..635f9e1c032da3 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -580,11 +580,11 @@ in the class will use the new method:: >>> fr.expovariate(0.25) 8.87925541791544 -Conceptually, the recipe chooses from the multiples of 2⁻¹⁰⁷⁴ in the -range *0.0 ≤ x < 1.0*. All such numbers are evenly spaced, but most -have to be rounded down to the nearest representable Python float. (The -value 2⁻¹⁰⁷⁴ is the smallest positive unnormalized float and is equal to -``math.ulp(0.0)``.) +The recipe is conceptually equivalent to an algorithm that chooses from +all the multiples of 2⁻¹⁰⁷⁴ in the range *0.0 ≤ x < 1.0*. All such +numbers are evenly spaced, but most have to be rounded down to the +nearest representable Python float. (The value 2⁻¹⁰⁷⁴ is the smallest +positive unnormalized float and is equal to ``math.ulp(0.0)``.) .. seealso::