[Boost-commit] svn:boost r82687 - trunk/libs/math/example

Subject: [Boost-commit] svn:boost r82687 - trunk/libs/math/example
From: pbristow_at_[hidden]
Date: 2013-02-06 20:24:11

Author: pbristow
Date: 2013-02-02 11:31:57 EST (Sat, 02 Feb 2013)
New Revision: 82687
URL: http://svn.boost.org/trac/boost/changeset/82687

Log:
Update to distribution construction examples  to include examples of multiprecision.
Text files modified: 
   trunk/libs/math/example/distribution_construction.cpp |   133 +++++++++++++++++++++++++++------------ 
   1 files changed, 93 insertions(+), 40 deletions(-)

Modified: trunk/libs/math/example/distribution_construction.cpp
==============================================================================
--- trunk/libs/math/example/distribution_construction.cpp	(original)
+++ trunk/libs/math/example/distribution_construction.cpp	2013-02-02 11:31:57 EST (Sat, 02 Feb 2013)
@@ -1,6 +1,6 @@
 // distribution_construction.cpp
 
-// Copyright Paul A. Bristow 2007, 2010.
+// Copyright Paul A. Bristow 2007, 2010, 2012.
 
 // Use, modification and distribution are subject to the
 // Boost Software License, Version 1.0.
@@ -10,21 +10,26 @@
 // Caution: this file contains Quickbook markup as well as code
 // and comments, don't change any of the special comment markups!
 
-//[distribution_construction1
+#ifdef _MSC_VER
+#  pragma warning (disable : 4996) // disable -D_SCL_SECURE_NO_WARNINGS C++ 'Checked Iterators'
+#endif
+//[distribution_construction_1
 
 /*`
-
 The structure of distributions is rather different from some other statistical libraries,
-for example in less object-oriented language like FORTRAN and C,
-that provide a few arguments to each free function.
-This library provides each distribution as a template C++ class.
+for example, those written in less object-oriented language like FORTRAN and C:
+these provide a few arguments to each free function.
+
+Boost.Math library provides each distribution as a template C++ class.
 A distribution is constructed with a few arguments, and then
 member and non-member functions are used to find values of the
 distribution, often a function of a random variate.
 
-First we need some includes to access the negative binomial distribution
-(and the binomial, beta and gamma too).
+For this demonstration, first we need some includes to access the
+negative binomial distribution (and the binomial, beta and gamma distributions too).
 
+To demonstrate the use with a high precision User-defined floating-point type
+`cpp_dec_float` we also need an include from Boost.Multiprecision.
 */
 
 #include <boost/math/distributions/negative_binomial.hpp> // for negative_binomial_distribution
@@ -34,14 +39,16 @@
 #include <boost/math/distributions/beta.hpp> // for beta_distribution.
 #include <boost/math/distributions/gamma.hpp> // for gamma_distribution.
 #include <boost/math/distributions/normal.hpp> // for normal_distribution.
+
+#include <boost/multiprecision/cpp_dec_float.hpp> // for cpp_dec_float_100
 /*`
 Several examples of constructing distributions follow:
 */
-//] [/distribution_construction1 end of Quickbook in C++ markup]
+//] [/distribution_construction_1 end of Quickbook in C++ markup]
 
 int main()
 {
-//[distribution_construction2
+//[distribution_construction_2
 /*`
 First, a negative binomial distribution with 8 successes
 and a success fraction 0.25, 25% or 1 in 4, is constructed like this:
@@ -52,29 +59,29 @@
   */
   using namespace boost::math;
   /*`
-  but this might risk ambiguity with names in std random so
-  *much better is explicit `using boost::math:: ` * ... statements like
+  but this might risk ambiguity with names in `std random` so
+  [*much] better is explicit `using boost::math::` statements, for example:
   */
   using boost::math::negative_binomial_distribution;
   /*`
   and we can still reduce typing.
 
-  Since the vast majority of applications use will be using double precision,
-  the template argument to the distribution (RealType) defaults
-  to type double, so we can also write:
+  Since the vast majority of applications use will be using `double` precision,
+  the template argument to the distribution (`RealType`) defaults
+  to type `double`, so we can also write:
   */
 
-  negative_binomial_distribution<> mydist9(8., 0.25); // Uses default RealType = double.
+  negative_binomial_distribution<> mydist9(8., 0.25); // Uses default `RealType = double`.
 
   /*`
-  But the name "negative_binomial_distribution" is still inconveniently long,
-  so for most distributions, a convenience typedef is provided, for example:
+  But the name `negative_binomial_distribution` is still inconveniently long,
+  so, for most distributions, a convenience `typedef` is provided, for example:
 
      typedef negative_binomial_distribution<double> negative_binomial; // Reserved name of type double.
 
   [caution
-  This convenience typedef is /not/ provided if a clash would occur
-  with the name of a function: currently only "beta" and "gamma"
+  This convenience typedef is [*not provided] if a clash would occur
+  with the name of a function: currently only `beta` and `gamma`
   fall into this category.
   ]
 
@@ -138,13 +145,13 @@
   We can, of course, still provide the type explicitly thus:
   */
 
-  // Explicit double precision:
+  // Explicit double precision:  both arguments are double:
   negative_binomial_distribution<double>        mydist1(8., 0.25);
 
   // Explicit float precision, double arguments are truncated to float:
   negative_binomial_distribution<float>         mydist2(8., 0.25);
 
-  // Explicit float precision, integer & double arguments converted to float.
+  // Explicit float precision, integer & double arguments converted to float:
   negative_binomial_distribution<float>         mydist3(8, 0.25);
 
   // Explicit float precision, float arguments, so no conversion:
@@ -160,30 +167,76 @@
   negative_binomial_distribution<long double>   mydist7(8., 0.25);
 
   /*`
-  And if you have your own RealType called MyFPType,
-  for example NTL RR (an arbitrary precision type), then we can write:
+  And you can use your own RealType,
+  for example, `boost::math::cpp_dec_float_50` (an arbitrary 50 decimal digits precision type),
+  then we can write:
+  */
+  using namespace boost::multiprecision;
 
-     negative_binomial_distribution<MyFPType>  mydist6(8, 1); // Integer arguments -> MyFPType.
+  negative_binomial_distribution<cpp_dec_float_50>  mydist8(8, 0.25);
+  // `integer` arguments are promoted to your RealType exactly, but
+  // `double` argument are converted to RealType,
+  // possibly losing precision, so don't write:
 
-  [heading Default arguments to distribution constructors.]
+  negative_binomial_distribution<cpp_dec_float_50>  mydist20(8, 0.23456789012345678901234567890);
+ // to avoid truncation of second parameter to `0.2345678901234567`.
 
-  Note that default constructor arguments are only provided for some distributions.
-  So if you wrongly assume a default argument you will get an error message, for example:
+  negative_binomial_distribution<cpp_dec_float_50>  mydist21(8, cpp_dec_float_50("0.23456789012345678901234567890") );
 
-     negative_binomial_distribution<> mydist8;
+  // Ensure that all potentially significant digits are shown.
+  std::cout.precision(std::numeric_limits<cpp_dec_float_50>::digits10);
+  cpp_dec_float_50 x("1.23456789012345678901234567890");
+  std::cout << pdf(mydist8, x) << std::endl;
+/*` showing  0.00012630010495970320103876754721976419438231705359935
 
-  [pre error C2512 no appropriate default constructor available.]
+[warning When using multiprecision, it is all too easy to get accidental truncation!]
 
-  No default constructors are provided for the negative binomial,
-  because it is difficult to chose any sensible default values for this distribution.
-  For other distributions, like the normal distribution,
-  it is obviously very useful to provide 'standard'
-  defaults for the mean and standard deviation thus:
+For example, if you write
+*/
+  std::cout << pdf(mydist8, 1.23456789012345678901234567890) << std::endl;
+/*`
+showing  0.00012630010495970318465064569310967179576805651692929,
+which is wrong at about the 17th decimal digit!
 
-      normal_distribution(RealType mean = 0, RealType sd = 1);
+This is because the value provided is truncated to a `double`, effectively
+  `double x = 1.23456789012345678901234567890;`
 
-  So in this case we can write:
-  */
+Then the now `double x` is passed to function `pdf`,
+and this truncated `double` value is finally promoted to `cpp_dec_float_50`.
+
+Another way of quietly getting the wrong answer is to write:
+*/
+  std::cout << pdf(mydist8, cpp_dec_float_50(1.23456789012345678901234567890)) << std::endl;
+/*`
+A correct way from a multi-digit string value is
+*/
+  std::cout << pdf(mydist8, cpp_dec_float_50("1.23456789012345678901234567890")) << std::endl;
+/*`
+
+[tip Getting about 17 decimal digits followed by many zeros is often a sign of accidental truncation.]
+*/
+
+/*`
+[h4 Default arguments to distribution constructors.]
+
+Note that default constructor arguments are only provided for some distributions.
+So if you wrongly assume a default argument, you will get an error message, for example:
+
+   negative_binomial_distribution<> mydist8;
+
+[pre error C2512 no appropriate default constructor available.]
+
+No default constructors are provided for the `negative binomial` distribution,
+because it is difficult to chose any sensible default values for this distribution.
+
+For other distributions, like the normal distribution,
+it is obviously very useful to provide 'standard'
+defaults for the mean (zero) and standard deviation (unity) thus:
+
+    normal_distribution(RealType mean = 0, RealType sd = 1);
+
+So in this case we can write:
+*/
   using boost::math::normal;
 
   normal norm1;       // Standard normal distribution.
@@ -193,7 +246,7 @@
   return 0;
 }  // int main()
 
-/*`There is no useful output from this program, of course. */
+/*`There is no useful output from this demonstration program, of course. */
 
-//] [/end of distribution_construction2]
+//] [/end of distribution_construction_2]