diff --git a/example/fft_sines_table.cpp b/example/fft_sines_table.cpp index 96dd28c4b..71cab534a 100644 --- a/example/fft_sines_table.cpp +++ b/example/fft_sines_table.cpp @@ -22,9 +22,9 @@ /*`[h5 Using Boost.Multiprecision to generate a high-precision array of sin coefficents for use with FFT.] The Boost.Multiprecision library can be used for computations requiring precision -exceeding that of standard built-in types such as float, double -and long double. For extended-precision calculations, Boost.Multiprecision -supplies a template data type called cpp_dec_float. The number of decimal +exceeding that of standard built-in types such as `float`, `double` +and `long double`. For extended-precision calculations, Boost.Multiprecision +supplies a template data type called `cpp_dec_float`. The number of decimal digits of precision is fixed at compile-time via template parameter. To use these floating-point types and constants, we need some includes: @@ -44,8 +44,8 @@ To use these floating-point types and constants, we need some includes: #include /*`Define a text string which is a C++ comment with the program licence, copyright etc. -You could of course, tailor this to your needs, including copyright claim. -There are versions of `array` provided by Boost/array in boost::array or +You could of course, tailor this to your needs, including your copyright claim. +There are versions of `array` provided by Boost.Array in `boost::array` or the C++11 std::array, but since not all platforms provide C++11 support, this program provides the Boost version as fallback. */ @@ -69,8 +69,8 @@ static const char* prolog = using boost::multiprecision::cpp_dec_float_50; using boost::math::constants::pi; -// VS 2010 (wrongly) requires these at file scope, not local scope in main. -// This program also requires -std=c++11 option to compile using Clang and GCC. +// VS 2010 (wrongly) requires these at file scope, not local scope in `main`. +// This program also requires `-std=c++11` option to compile using Clang and GCC. int main() { @@ -174,7 +174,7 @@ Now output all the sine table, to a file of your chosen name. fout << " " << sin_values[i]; if (i == sin_values.size()-1) { // next is last value. - fout << "\n}};\n"; // 2nd } needed for some GCC compiler versions. + fout << "\n}};\n"; // 2nd } needed for some earlier GCC compiler versions. break; } else @@ -188,7 +188,7 @@ Now output all the sine table, to a file of your chosen name. std::cout << "Close file " << sines_name << " for output OK." << std::endl; } -//`The output file generated can be seen at [@..\\sines.hpp] +//`The output file generated can be seen at [@../../example/sines.hpp] //] [/fft_sines_table_example_1] return EXIT_SUCCESS; diff --git a/example/find_location_example.cpp b/example/find_location_example.cpp index 789b270a0..a20edb8c8 100644 --- a/example/find_location_example.cpp +++ b/example/find_location_example.cpp @@ -54,7 +54,7 @@ For this example, we will use the standard normal distribution, with mean (location) zero and standard deviation (scale) unity. This is also the default for this implementation. */ - normal N01; // Default 'standard' normal distribution with zero mean and + normal N01; // Default 'standard' normal distribution with zero mean and double sd = 1.; // normal default standard deviation is 1. /*`Suppose we want to find a different normal distribution whose mean is shifted so that only fraction p (here 0.001 or 0.1%) are below a certain chosen limit @@ -65,7 +65,7 @@ so that only fraction p (here 0.001 or 0.1%) are below a certain chosen limit cout << "Normal distribution with mean = " << N01.location() << ", standard deviation " << N01.scale() - << ", has " << "fraction <= " << z + << ", has " << "fraction <= " << z << ", p = " << cdf(N01, z) << endl; cout << "Normal distribution with mean = " << N01.location() << ", standard deviation " << N01.scale() @@ -95,11 +95,11 @@ with the offset mean (but same standard deviation): /*` And re-calculating the fraction below our chosen limit. */ -cout << "Normal distribution with mean = " << l - << " has " << "fraction <= " << z +cout << "Normal distribution with mean = " << l + << " has " << "fraction <= " << z << ", p = " << cdf(np001pc, z) << endl; - cout << "Normal distribution with mean = " << l - << " has " << "fraction > " << z + cout << "Normal distribution with mean = " << l + << " has " << "fraction > " << z << ", p = " << cdf(complement(np001pc, z)) << endl; /*` [pre @@ -109,7 +109,7 @@ Normal distribution with mean = 1.09023 has fraction > -2, p = 0.999 [h4 Controlling Error Handling from find_location] We can also control the policy for handling various errors. -For example, we can define a new (possibly unwise) +For example, we can define a new (possibly unwise) policy to ignore domain errors ('bad' arguments). Unless we are using the boost::math namespace, we will need: @@ -132,25 +132,24 @@ although it is not required, as the various examples below show. // A new policy, ignoring domain errors, without using a typedef. l = find_location(z, p, sd, policy >()); /*` -If we want to use a probability that is the -[link math_toolkit.stat_tut.overview.complements complement of our probability], +If we want to use a probability that is the __complements of our probability, we should not even think of writing `find_location(z, 1 - p, sd)`, -but, [link why_complements to avoid loss of accuracy], use the complement version. +but use the complement version, see __why_complements. */ z = 2.; double q = 0.95; // = 1 - p; // complement. l = find_location(complement(z, q, sd)); normal np95pc(l, sd); // Same standard_deviation (scale) but with mean(location) shifted - cout << "Normal distribution with mean = " << l << " has " + cout << "Normal distribution with mean = " << l << " has " << "fraction <= " << z << " = " << cdf(np95pc, z) << endl; - cout << "Normal distribution with mean = " << l << " has " + cout << "Normal distribution with mean = " << l << " has " << "fraction > " << z << " = " << cdf(complement(np95pc, z)) << endl; //] [/find_location2] } catch(const std::exception& e) - { // Always useful to include try & catch blocks because default policies - // are to throw exceptions on arguments that cause errors like underflow, overflow. + { // Always useful to include try & catch blocks because default policies + // are to throw exceptions on arguments that cause errors like underflow, overflow. // Lacking try & catch blocks, the program will abort without a message below, // which may give some helpful clues as to the cause of the exception. std::cout << diff --git a/example/find_mean_and_sd_normal.cpp b/example/find_mean_and_sd_normal.cpp index 42152c906..b3153c846 100644 --- a/example/find_mean_and_sd_normal.cpp +++ b/example/find_mean_and_sd_normal.cpp @@ -116,8 +116,8 @@ cout << "Setting the packer to " << nominal_mean << " will mean that " // Setting the packer to 3.06449 will mean that fraction of packs >= 2.9 is 0.95 /*` -This calculation is generalized as the free function called -[link math_toolkit.dist_ref.dist_algorithms find_location]. +This calculation is generalized as the free function called `find_location`, +see __algorithms. To use this we will need to */ @@ -261,8 +261,7 @@ cout <<"Fraction of packs >= " << minimum_weight << " with a mean of " << mean /*` Now we are getting really close, but to do the job properly, we might need to use root finding method, for example the tools provided, -and used elsewhere, in the Math Toolkit, see -[link math_toolkit.internals1.roots2 Root Finding Without Derivatives]. +and used elsewhere, in the Math Toolkit, see __root_finding_without_derivatives But in this (normal) distribution case, we can and should be even smarter and make a direct calculation. @@ -278,7 +277,7 @@ ensuring that 0.95 (95%) of packs are above the minimum weight. Rearranging, we can directly calculate the required standard deviation: */ -normal N01; // standard normal distribution with meamn zero and unit standard deviation. +normal N01; // standard normal distribution with mean zero and unit standard deviation. p = 0.05; double qp = quantile(N01, p); double sd95 = (minimum_weight - mean) / qp; @@ -328,7 +327,7 @@ cout << "find_scale(minimum_weight, under_fraction, packs.mean()); " << // find_scale(minimum_weight, under_fraction, packs.mean()); 0.0607957 /*`But notice that using '1 - over_fraction' - will lead to a -[link why_complements loss of accuracy, especially if over_fraction was close to unity.] +loss of accuracy, especially if over_fraction was close to unity. (See __why_complements). In this (very common) case, we should instead use the __complements, giving the most accurate result. */ diff --git a/example/find_root_example.cpp b/example/find_root_example.cpp index d318ef81c..6b7651dd9 100644 --- a/example/find_root_example.cpp +++ b/example/find_root_example.cpp @@ -33,7 +33,7 @@ First we need some includes to access the normal distribution using std::exception; //] //[/root_find1] - + int main() { cout << "Example: Normal distribution, root finding."; @@ -42,9 +42,9 @@ int main() //[root_find2 -/*`A machine is set to pack 3 kg of ground beef per pack. +/*`A machine is set to pack 3 kg of ground beef per pack. Over a long period of time it is found that the average packed was 3 kg -with a standard deviation of 0.1 kg. +with a standard deviation of 0.1 kg. Assuming the packing is normally distributed, we can find the fraction (or %) of packages that weigh more than 3.1 kg. */ @@ -58,7 +58,7 @@ cout << "Percentage of packs > " << max_weight << " is " << cdf(complement(packs, max_weight)) << endl; // P(X > 3.1) double under_weight = 2.9; -cout <<"fraction of packs <= " << under_weight << " with a mean of " << mean +cout <<"fraction of packs <= " << under_weight << " with a mean of " << mean << " is " << cdf(complement(packs, under_weight)) << endl; // fraction of packs <= 2.9 with a mean of 3 is 0.841345 // This is 0.84 - more than the target 0.95 @@ -67,7 +67,7 @@ cout <<"fraction of packs <= " << under_weight << " with a mean of " << mean double over_mean = 3.0664; normal xpacks(over_mean, standard_deviation); cout << "fraction of packs >= " << under_weight -<< " with a mean of " << xpacks.mean() +<< " with a mean of " << xpacks.mean() << " is " << cdf(complement(xpacks, under_weight)) << endl; // fraction of packs >= 2.9 with a mean of 3.06449 is 0.950005 double under_fraction = 0.05; // so 95% are above the minimum weight mean - sd = 2.9 @@ -77,7 +77,7 @@ double nominal_mean = mean + offset; normal nominal_packs(nominal_mean, standard_deviation); cout << "Setting the packer to " << nominal_mean << " will mean that " - << "fraction of packs >= " << under_weight + << "fraction of packs >= " << under_weight << " is " << cdf(complement(nominal_packs, under_weight)) << endl; /*` @@ -93,7 +93,7 @@ we need to get the 5% quantile to be located at the under_weight limit, 2.9 */ double p = 0.05; // wanted p th quantile. cout << "Quantile of " << p << " = " << quantile(packs, p) - << ", mean = " << packs.mean() << ", sd = " << packs.standard_deviation() << endl; // + << ", mean = " << packs.mean() << ", sd = " << packs.standard_deviation() << endl; // /*` Quantile of 0.05 = 2.83551, mean = 3, sd = 0.1 @@ -103,14 +103,14 @@ So we know that the standard deviation is going to have to be smaller. Let's start by guessing that it (now 0.1) needs to be halved, to a standard deviation of 0.05 */ -normal pack05(mean, 0.05); -cout << "Quantile of " << p << " = " << quantile(pack05, p) +normal pack05(mean, 0.05); +cout << "Quantile of " << p << " = " << quantile(pack05, p) << ", mean = " << pack05.mean() << ", sd = " << pack05.standard_deviation() << endl; -cout <<"Fraction of packs >= " << under_weight << " with a mean of " << mean +cout <<"Fraction of packs >= " << under_weight << " with a mean of " << mean << " and standard deviation of " << pack05.standard_deviation() << " is " << cdf(complement(pack05, under_weight)) << endl; -// +// /*` Fraction of packs >= 2.9 with a mean of 3 and standard deviation of 0.05 is 0.9772 @@ -119,11 +119,11 @@ so the standard deviation could be a tiny bit more. So we could do some more guessing to get closer, say by increasing to 0.06 */ -normal pack06(mean, 0.06); -cout << "Quantile of " << p << " = " << quantile(pack06, p) +normal pack06(mean, 0.06); +cout << "Quantile of " << p << " = " << quantile(pack06, p) << ", mean = " << pack06.mean() << ", sd = " << pack06.standard_deviation() << endl; -cout <<"Fraction of packs >= " << under_weight << " with a mean of " << mean +cout <<"Fraction of packs >= " << under_weight << " with a mean of " << mean << " and standard deviation of " << pack06.standard_deviation() << " is " << cdf(complement(pack06, under_weight)) << endl; /*` @@ -131,8 +131,7 @@ Fraction of packs >= 2.9 with a mean of 3 and standard deviation of 0.06 is 0.95 Now we are getting really close, but to do the job properly, we could use root finding method, for example the tools provided, and used elsewhere, -in the Math Toolkit, see -[link math_toolkit.internals1.roots2 Root Finding Without Derivatives]. +in the Math Toolkit, see __root_finding_without_derivatives. But in this normal distribution case, we could be even smarter and make a direct calculation. */ @@ -140,8 +139,8 @@ But in this normal distribution case, we could be even smarter and make a direct } catch(const std::exception& e) - { // Always useful to include try & catch blocks because default policies - // are to throw exceptions on arguments that cause errors like underflow, overflow. + { // Always useful to include try & catch blocks because default policies + // are to throw exceptions on arguments that cause errors like underflow, overflow. // Lacking try & catch blocks, the program will abort without a message below, // which may give some helpful clues as to the cause of the exception. std::cout << diff --git a/example/find_scale_example.cpp b/example/find_scale_example.cpp index b3b42b468..29e474f0f 100644 --- a/example/find_scale_example.cpp +++ b/example/find_scale_example.cpp @@ -21,7 +21,7 @@ the algorithms to find scale (and some std output of course). #include // for normal_distribution using boost::math::normal; // typedef provides default type is double. #include - using boost::math::find_scale; + using boost::math::find_scale; using boost::math::complement; // Needed if you want to use the complement version. using boost::math::policies::policy; // Needed to specify the error handling policy. @@ -55,7 +55,7 @@ so that only fraction p (here 0.001 or 0.1%) are below a certain chosen limit cout << "Normal distribution with mean = " << N01.location() // aka N01.mean() << ", standard deviation " << N01.scale() // aka N01.standard_deviation() - << ", has " << "fraction <= " << z + << ", has " << "fraction <= " << z << ", p = " << cdf(N01, z) << endl; cout << "Normal distribution with mean = " << N01.location() << ", standard deviation " << N01.scale() @@ -83,15 +83,15 @@ Then we can check that we have achieved our objective by constructing a new distribution with the new standard deviation (but same zero mean): */ - normal np001pc(N01.location(), s); + normal np001pc(N01.location(), s); /*` And re-calculating the fraction below (and above) our chosen limit. */ - cout << "Normal distribution with mean = " << l - << " has " << "fraction <= " << z + cout << "Normal distribution with mean = " << l + << " has " << "fraction <= " << z << ", p = " << cdf(np001pc, z) << endl; - cout << "Normal distribution with mean = " << l - << " has " << "fraction > " << z + cout << "Normal distribution with mean = " << l + << " has " << "fraction > " << z << ", p = " << cdf(complement(np001pc, z)) << endl; /*` [pre @@ -101,7 +101,7 @@ Normal distribution with mean = 0 has fraction > -2, p = 0.999 [h4 Controlling how Errors from find_scale are handled] We can also control the policy for handling various errors. -For example, we can define a new (possibly unwise) +For example, we can define a new (possibly unwise) policy to ignore domain errors ('bad' arguments). Unless we are using the boost::math namespace, we will need: @@ -127,16 +127,16 @@ although it is not required, as the various examples below show. /*` If we want to express a probability, say 0.999, that is a complement, `1 - p` we should not even think of writing `find_scale(z, 1 - p, l)`, -but [link why_complements instead], use the __complements version. +but use the __complements version (see __why_complements). */ z = -2.; double q = 0.999; // = 1 - p; // complement of 0.001. sd = find_scale(complement(z, q, l)); normal np95pc(l, sd); // Same standard_deviation (scale) but with mean(scale) shifted - cout << "Normal distribution with mean = " << l << " has " + cout << "Normal distribution with mean = " << l << " has " << "fraction <= " << z << " = " << cdf(np95pc, z) << endl; - cout << "Normal distribution with mean = " << l << " has " + cout << "Normal distribution with mean = " << l << " has " << "fraction > " << z << " = " << cdf(complement(np95pc, z)) << endl; /*` @@ -154,8 +154,8 @@ the (impossible) negative scale is quietly returned. //] [/find_scale2] } catch(const std::exception& e) - { // Always useful to include try & catch blocks because default policies - // are to throw exceptions on arguments that cause errors like underflow, overflow. + { // Always useful to include try & catch blocks because default policies + // are to throw exceptions on arguments that cause errors like underflow, overflow. // Lacking try & catch blocks, the program will abort without a message below, // which may give some helpful clues as to the cause of the exception. std::cout << diff --git a/example/geometric_examples.cpp b/example/geometric_examples.cpp index df171e957..903a8987d 100644 --- a/example/geometric_examples.cpp +++ b/example/geometric_examples.cpp @@ -8,7 +8,7 @@ // or copy at http://www.boost.org/LICENSE_1_0.txt) // This file is written to be included from a Quickbook .qbk document. -// It can still be compiled by the C++ compiler, and run. +// It can still be compiled by the C++ compiler, and run. // Any output can also be added here as comment or included or pasted in elsewhere. // Caution: this file contains Quickbook markup as well as code // and comments: don't change any of the special comment markups! @@ -17,7 +17,7 @@ //[geometric_eg1_1 /*` -For this example, we will opt to #define two macros to control +For this example, we will opt to #define two macros to control the error and discrete handling policies. For this simple example, we want to avoid throwing an exception (the default policy) and just return infinity. @@ -34,7 +34,7 @@ and we need some std library iostream, of course. */ #include // for geometric_distribution - using ::boost::math::geometric_distribution; // + using ::boost::math::geometric_distribution; // using ::boost::math::geometric; // typedef provides default type is double. using ::boost::math::pdf; // Probability mass function. using ::boost::math::cdf; // Cumulative density function. @@ -52,7 +52,7 @@ and we need some std library iostream, of course. using std::cout; using std::endl; using std::noshowpoint; using std::fixed; using std::right; using std::left; #include - using std::setprecision; using std::setw; + using std::setprecision; using std::setw; #include using std::numeric_limits; @@ -81,7 +81,7 @@ to get the first success in /k/ Bernoulli trials. is one with only two possible outcomes, success of failure, and /p/ is the probability of success). -Suppose an 'fair' 6-face dice is thrown repeatedly: +Suppose an 'fair' 6-face dice is thrown repeatedly: */ double success_fraction = 1./6; // success_fraction (p) = 0.1666 // (so failure_fraction is 1 - success_fraction = 5./6 = 1- 0.1666 = 0.8333) @@ -119,7 +119,7 @@ we can use the Cumulative Distribution Function CDF.*/ /*`If we allow many more (12) throws, the probability of getting our /three/ gets very high:*/ cout << "cdf(g6, 12) = " << cdf(g6, 12) << endl; // 0.9065 or 90% probability. -/*`If we want to be much more confident, say 99%, +/*`If we want to be much more confident, say 99%, we can estimate the number of throws to be this sure using the inverse or quantile. */ @@ -127,8 +127,8 @@ using the inverse or quantile. /*`Note that the value returned is not an integer: if you want an integer result you should use either floor, round or ceil functions, or use the policies mechanism. -See [link math_toolkit.pol_tutorial.understand_dis_quant -Understanding Quantiles of Discrete Distributions] + +See __understand_dis_quant. The geometric distribution is related to the negative binomial __spaces `negative_binomial_distribution(RealType r, RealType p);` with parameter /r/ = 1. @@ -159,13 +159,13 @@ So in Boost.Math the equivalent is #ifdef BOOST_NO_CXX11_NUMERIC_LIMITS int max_digits10 = 2 + (boost::math::policies::digits >() * 30103UL) / 100000UL; - cout << "BOOST_NO_CXX11_NUMERIC_LIMITS is defined" << endl; -#else + cout << "BOOST_NO_CXX11_NUMERIC_LIMITS is defined" << endl; +#else int max_digits10 = std::numeric_limits::max_digits10; #endif cout << "Show all potentially significant decimal digits std::numeric_limits::max_digits10 = " - << max_digits10 << endl; - cout.precision(max_digits10); // + << max_digits10 << endl; + cout.precision(max_digits10); // cout << cdf(g05, 0.0001) << endl; // returns 0.5000346561579232, not exact 0.5. /*`To get the R discrete behaviour, you simply need to round with, @@ -186,7 +186,7 @@ A company knows from warranty claims that 2% of their products will be faulty, so the 'success_fraction' of finding a fault is 0.02. It wants to interview a purchaser of faulty products to assess their 'user experience'. -To estimate how many customers they will probably need to contact +To estimate how many customers they will probably need to contact in order to find one who has suffered from the fault, we first construct a geometric distribution with probability 0.02, and then chose a confidence, say 80%, 95%, or 99% to finding a customer with a fault. @@ -202,20 +202,20 @@ the probability of finding a customer with a fault obviously improves.) double c = 0.95; // 95% confidence. cout << " quantile(g, " << c << ") = " << quantile(g, c) << endl; - cout << "To be " << c * 100 + cout << "To be " << c * 100 << "% confident of finding we customer with a fault, need to survey " << ceil(quantile(g, c)) << " customers." << endl; // 148 c = 0.99; // Very confident. - cout << "To be " << c * 100 + cout << "To be " << c * 100 << "% confident of finding we customer with a fault, need to survey " << ceil(quantile(g, c)) << " customers." << endl; // 227 c = 0.80; // Only reasonably confident. - cout << "To be " << c * 100 + cout << "To be " << c * 100 << "% confident of finding we customer with a fault, need to survey " << ceil(quantile(g, c)) << " customers." << endl; // 79 /*`[h6 Basket Ball Shooters] -According to Wikipedia, average pro basket ball players get +According to Wikipedia, average pro basket ball players get [@http://en.wikipedia.org/wiki/Free_throw free throws] in the baskets 70 to 80 % of the time, but some get as high as 95%, and others as low as 50%. @@ -224,7 +224,7 @@ of failing to get a score only on the first or on the fifth shot? To start we will consider the average shooter, say 75%. So we construct a geometric distribution with success_fraction parameter 75/100 = 0.75. -*/ +*/ cout.precision(2); geometric gav(0.75); // Shooter averages 7.5 out of 10 in the basket. /*`What is probability of getting 1st try in the basket, that is with no failures? */ @@ -255,8 +255,8 @@ This is the best estimate we can make, but while it is the truth, it is not the whole truth, for it hides the big uncertainty when estimating from a single event. "One swallow doesn't make a summer." -To show the magnitude of the uncertainty, the geometric -(or the negative binomial) distribution can be used. +To show the magnitude of the uncertainty, the geometric +(or the negative binomial) distribution can be used. If we chose the popular 95% confidence in the limits, corresponding to an alpha of 0.05, because we are calculating a two-sided interval, we must divide alpha by two. @@ -265,7 +265,7 @@ because we are calculating a two-sided interval, we must divide alpha by two. double k = 100; // So frequency of occurence is 1/100. cout << "Probability is failure is " << 1/k << endl; double t = geometric::find_lower_bound_on_p(k, alpha/2); - cout << "geometric::find_lower_bound_on_p(" << int(k) << ", " << alpha/2 << ") = " + cout << "geometric::find_lower_bound_on_p(" << int(k) << ", " << alpha/2 << ") = " << t << endl; // 0.00025 t = geometric::find_upper_bound_on_p(k, alpha/2); cout << "geometric::find_upper_bound_on_p(" << int(k) << ", " << alpha/2 << ") = " @@ -302,8 +302,8 @@ even if you hope not to use it! // an overflow exception should never be thrown. std::cout << "\nMessage from thrown exception was:\n " << e.what() << std::endl; /*` -For example, without a ignore domain error policy, -if we asked for ``pdf(g, -1)`` for example, +For example, without a ignore domain error policy, +if we asked for ``pdf(g, -1)`` for example, we would get an unhelpful abort, but with a catch: [pre Message from thrown exception was: @@ -321,7 +321,7 @@ Message from thrown exception was: Output is: Geometric distribution example - + success fraction of a six-sided dice is 0.1667 0.1667 0.1667 @@ -350,7 +350,7 @@ Output is: geometric::find_upper_bound_on_p(100, 0.05) = 0.03 geometric::find_lower_bound_on_p(100, 0.005) = 5e-005 geometric::find_upper_bound_on_p(100, 0.005) = 0.052 - + */