[Boost-commit] svn:boost r38644 - sandbox/math_toolkit/libs/math/example

From: pbristow_at_[hidden]
Date: 2007-08-14 04:35:46

Author: pbristow
Date: 2007-08-14 04:35:44 EDT (Tue, 14 Aug 2007)
New Revision: 38644
URL: http://svn.boost.org/trac/boost/changeset/38644

Log:
New example of how to construct distributions
Text files modified: 
   sandbox/math_toolkit/libs/math/example/distribution_construction.cpp |   143 ++++++++++++++++++++------------------- 
   1 files changed, 72 insertions(+), 71 deletions(-)

Modified: sandbox/math_toolkit/libs/math/example/distribution_construction.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/distribution_construction.cpp	(original)
+++ sandbox/math_toolkit/libs/math/example/distribution_construction.cpp	2007-08-14 04:35:44 EDT (Tue, 14 Aug 2007)
@@ -7,84 +7,68 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-// Examples of using constructing distributions, mainly negative_binomial.
-// The structure of distributions is rather different from some other
-// statistical libraries, in less object oriented language like FOTRTRAN and C,
-// that provide a few arguments to each free function.
-// This 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 functions of a random variate.
+// Caution: this file contains Quickbook markup as well as code
+// and comments, don't change any of the special comment markups!
+
+//[distribution_construction1
+
+/*`
+
+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.
+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).
+
+*/
 
 #include <boost/math/distributions/negative_binomial.hpp> // for negative_binomial_distribution
   using boost::math::negative_binomial_distribution; // default type is double.
-	using boost::math::negative_binomial; // typedef provides default type is double.
+  using boost::math::negative_binomial; // typedef provides default type is double.
 #include <boost/math/distributions/binomial.hpp> // for binomial_distribution.
 #include <boost/math/distributions/beta.hpp> // for beta_distribution.
 #include <boost/math/distributions/gamma.hpp> // for gamma_distribution.
 
-#include <iostream>
-	using std::cout;
-	using std::endl;
+//] [/distribution_construction1 end of Quickbook in C++ markup]
+
+//[distribution_construction2
+
+/*`
+Several examples of constructing distributions follow:
+*/
 
 int main()
 {
-	cout << "Examples of constructing Distributions (negative_binomial).";
-  #if defined(__FILE__) && defined(__TIMESTAMP__)
-  	cout << "  " << __FILE__ << ' ' << __TIMESTAMP__ << ' '<< _MSC_FULL_VER << "\n";
-  #endif
-	cout << endl;
-
-  // Several examples of constructing distributions, for example, negative binomial:
+  // First, a negative binomial distribution with 8 successes
+  // and a success fraction 0.25, 25% or 1 in 4, is constructed like this:
 
-  // Distributions are fundamentally constructed like this:
   boost::math::negative_binomial_distribution<double> mydist0(8., 0.25);
   // But this is inconveniently long, so by writing
   using namespace boost::math;
-  // or 
+  // or
   using boost::math::negative_binomial_distribution;
-  // can reduce typing.
+  // we can reduce typing.
 
   // Since the vast majority of applications use double,
-  // the RealType default is made double, so one can write:
+  // the RealType default is chosen to be 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 typedef is provided, for example:
   // typedef negative_binomial_distribution<double> negative_binomial; // Reserved name of type double.
-  // (Unless a  clash would occur with the name of a function, for example gamma, beta)
-
+  // (Unless a  clash would occur with the name of a function, for example gamma & beta)
+  // So, after a using statement,
   using boost::math::negative_binomial;
-  // Allows convenient reference to negative_binomial_distribution<double> thus:
+  // we have a convenient reference to negative_binomial_distribution<double> thus:
   negative_binomial mydist(8., 0.25); //
 
-  // You can, of course, still provide the type explicitly thus:
-  negative_binomial_distribution<double> mydist1(8., 0.25); // Explicit double.
-  negative_binomial_distribution<float>  mydist2(8., 0.25); // Explicit float, double arguments -> float.
-  negative_binomial_distribution<float>  mydist3(8, 0.25); // Explicit float, integer & double arguments -> float.
-  negative_binomial_distribution<float>  mydist4(8.F, 0.25F); // Explicit float, float arguments, no conversion.
-  negative_binomial_distribution<float>  mydist5(8, 1); // Explicit integer, integer arguments -> float.
-  negative_binomial_distribution<double> mydist6(8., 0.25); // Explicit double.
-  negative_binomial_distribution<long double> mydist7(8., 0.25); // Explicit long double.
-  // And if you have your own RealType called MyFPType,
-  // for example NTL quad_float (128-bit floating-point), then:
-  // negative_binomial_distribution<MyFPType>  mydist6(8, 1); // Integer arguments -> MyFPType.
-
-  // Deafult arguments to distribution constructors.
-  // Note that default constructor arguments are only provided for some distributions.
-  //   negative_binomial_distribution<> mydist8;
-  //   error C2512 no appropriate default constructor available.
-  // No default constructor are provided,
-  // because it is difficult to chose any sensible default values for this distribution.
-  // For other distribution, like the normal distribution,
-  // it is obviously very useful to provide 'standard'
-  // defaults for the mean and standard deviation thus:
-  // normal_distribution(RealType mean = 0, RealType sd = 1)
-
-  // Some examples using the provided typedef:
-  using boost::math::negative_binomial; // Convenient access to the name.
-  // Allows convenient reference to negative_binomial of default type double.
+  // Some more examples using the provided convenience typedef:
   negative_binomial mydist10(5., 0.4); // Both arguments double.
   // And automatic conversion takes place, so you can use integers and floats:
   negative_binomial mydist11(5, 0.4); // Using provided typedef double, int and double arguments.
@@ -92,14 +76,14 @@
   negative_binomial mydist12(5., 0.4F); // Double and float arguments.
   negative_binomial mydist13(5, 1); // Both arguments integer.
 
-  // For cases when the typdef distribution name
-  // would clash with a math special function
-  // (for example: binomial, beta and gamma)
+  // Similarly for most other distributions like the binomial.
+  binomial mybinomial(1, 0.5); // is more concise than
+  binomial_distribution<> mybinomd1(1, 0.5);
+
+  // For cases when the typdef distribution name would clash with a math special function
+  // (for example: beta and gamma)
   // the typedef is deliberately not provided, and the longer version(s) must be used.
   // For example:
-  using namespace boost::math;
-  // NOT binomial mybd0(1, 0.5); // error C2065: 'binomial' : undeclared identifier
-
   using boost::math::beta;
   // NOT beta mybetad0(1, 0.5); because beta is a math FUNCTION!
   // error C2146: syntax error : missing ';' before identifier 'mybetad0'
@@ -108,23 +92,40 @@
   // Instead use:
   using boost::math::beta_distribution;
   beta_distribution<> mybetad1(1, 0.5);
-  // Other examples are:
-  binomial_distribution<> mybinomd1(1, 0.5);
+  // or for the gamm distribution:
   gamma_distribution<> mygammad1(1, 0.5);
 
-  return 0;
-}  // int main()
-
-/*
-
-Output is:
-
-Examples of constructing Distributions (Negative_binomial).  ..\..\..\..\..\..\Boost-sandbox\
-
-*/
+  // We can, of course, still provide the type explicitly thus:
+  negative_binomial_distribution<double> mydist1(8., 0.25); // Explicit double.
+  negative_binomial_distribution<float>  mydist2(8., 0.25); // Explicit float, double arguments -> float.
+  negative_binomial_distribution<float>  mydist3(8, 0.25); // Explicit float, integer & double arguments -> float.
+  negative_binomial_distribution<float>  mydist4(8.F, 0.25F); // Explicit float, float arguments, no conversion.
+  negative_binomial_distribution<float>  mydist5(8, 1); // Explicit integer, integer arguments -> float.
+  negative_binomial_distribution<double> mydist6(8., 0.25); // Explicit double.
+  negative_binomial_distribution<long double> mydist7(8., 0.25); // Explicit long double.
+  // And if you have your own RealType called MyFPType,
+  // for example NTL quad_float (128-bit floating-point), then:
+  // negative_binomial_distribution<MyFPType>  mydist6(8, 1); // Integer arguments -> MyFPType.
 
+  /*`
+  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;
+  //   error C2512 no appropriate default constructor available.
 
+  // 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:
+  // normal_distribution(RealType mean = 0, RealType sd = 1)
 
+  return 0;
+}  // int main()
 
+/*`There is no useful output from this program, of course. */
 
+//] [/end of distribution_construction2]