| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Additional Implementation Notes</title> |
| <link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.74.0"> |
| <link rel="home" href="../../index.html" title="Math Toolkit"> |
| <link rel="up" href="../backgrounders.html" title="Backgrounders"> |
| <link rel="prev" href="../backgrounders.html" title="Backgrounders"> |
| <link rel="next" href="relative_error.html" title="Relative Error"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> |
| <td align="center"><a href="../../../../../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../../../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="../backgrounders.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section" lang="en"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="math_toolkit.backgrounders.implementation"></a><a class="link" href="implementation.html" title="Additional Implementation Notes"> Additional |
| Implementation Notes</a> |
| </h3></div></div></div> |
| <p> |
| The majority of the implementation notes are included with the documentation |
| of each function or distribution. The notes here are of a more general nature, |
| and reflect more the general implementation philosophy used. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.implemention_philosophy"></a><h5> |
| <a name="id1282739"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.implemention_philosophy">Implemention |
| philosophy</a> |
| </h5> |
| <p> |
| "First be right, then be fast." |
| </p> |
| <p> |
| There will always be potential compromises to be made between speed and accuracy. |
| It may be possible to find faster methods, particularly for certain limited |
| ranges of arguments, but for most applications of math functions and distributions, |
| we judge that speed is rarely as important as accuracy. |
| </p> |
| <p> |
| So our priority is accuracy. |
| </p> |
| <p> |
| To permit evaluation of accuracy of the special functions, production of |
| extremely accurate tables of test values has received considerable effort. |
| </p> |
| <p> |
| (It also required much CPU effort - there was some danger of molten plastic |
| dripping from the bottom of JM's laptop, so instead, PAB's Dual-core desktop |
| was kept 50% busy for <span class="bold"><strong>days</strong></span> calculating some |
| tables of test values!) |
| </p> |
| <p> |
| For a specific RealType, say float or double, it may be possible to find |
| approximations for some functions that are simpler and thus faster, but less |
| accurate (perhaps because there are no refining iterations, for example, |
| when calculating inverse functions). |
| </p> |
| <p> |
| If these prove accurate enough to be "fit for his purpose", then |
| a user may substitute his custom specialization. |
| </p> |
| <p> |
| For example, there are approximations dating back from times when computation |
| was a <span class="bold"><strong>lot</strong></span> more expensive: |
| </p> |
| <p> |
| H Goldberg and H Levine, Approximate formulas for percentage points and normalisation |
| of t and chi squared, Ann. Math. Stat., 17(4), 216 - 225 (Dec 1946). |
| </p> |
| <p> |
| A H Carter, Approximations to percentage points of the z-distribution, Biometrika |
| 34(2), 352 - 358 (Dec 1947). |
| </p> |
| <p> |
| These could still provide sufficient accuracy for some speed-critical applications. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.accuracy_and_representation_of_test_values"></a><h5> |
| <a name="id1282803"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.accuracy_and_representation_of_test_values">Accuracy |
| and Representation of Test Values</a> |
| </h5> |
| <p> |
| In order to be accurate enough for as many as possible real types, constant |
| values are given to 50 decimal digits if available (though many sources proved |
| only accurate near to 64-bit double precision). Values are specified as long |
| double types by appending L, unless they are exactly representable, for example |
| integers, or binary fractions like 0.125. This avoids the risk of loss of |
| accuracy converting from double, the default type. Values are used after |
| static_cast<RealType>(1.2345L) to provide the appropriate RealType |
| for spot tests. |
| </p> |
| <p> |
| Functions that return constants values, like kurtosis for example, are written |
| as |
| </p> |
| <p> |
| <code class="computeroutput"><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>(-</span><span class="number">3</span><span class="special">)</span> <span class="special">/</span> |
| <span class="number">5</span><span class="special">;</span></code> |
| </p> |
| <p> |
| to provide the most accurate value that the compiler can compute for the |
| real type. (The denominator is an integer and so will be promoted exactly). |
| </p> |
| <p> |
| So tests for one third, <span class="bold"><strong>not</strong></span> exactly representable |
| with radix two floating-point, (should) use, for example: |
| </p> |
| <p> |
| <code class="computeroutput"><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>(</span><span class="number">1</span><span class="special">)</span> <span class="special">/</span> |
| <span class="number">3</span><span class="special">;</span></code> |
| </p> |
| <p> |
| If a function is very sensitive to changes in input, specifying an inexact |
| value as input (such as 0.1) can throw the result off by a noticeable amount: |
| 0.1f is "wrong" by ~1e-7 for example (because 0.1 has no exact |
| binary representation). That is why exact binary values - halves, quarters, |
| and eighths etc - are used in test code along with the occasional fraction |
| <code class="computeroutput"><span class="identifier">a</span><span class="special">/</span><span class="identifier">b</span></code> with <code class="computeroutput"><span class="identifier">b</span></code> |
| a power of two (in order to ensure that the result is an exactly representable |
| binary value). |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.tolerance_of_tests"></a><h5> |
| <a name="id1282947"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.tolerance_of_tests">Tolerance |
| of Tests</a> |
| </h5> |
| <p> |
| The tolerances need to be set to the maximum of: |
| </p> |
| <div class="itemizedlist"><ul type="disc"> |
| <li> |
| Some epsilon value. |
| </li> |
| <li> |
| The accuracy of the data (often only near 64-bit double). |
| </li> |
| </ul></div> |
| <p> |
| Otherwise when long double has more digits than the test data, then no amount |
| of tweaking an epsilon based tolerance will work. |
| </p> |
| <p> |
| A common problem is when tolerances that are suitable for implementations |
| like Microsoft VS.NET where double and long double are the same size: tests |
| fail on other systems where long double is more accurate than double. Check |
| first that the suffix L is present, and then that the tolerance is big enough. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.handling_unsuitable_arguments"></a><h5> |
| <a name="id1282991"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.handling_unsuitable_arguments">Handling |
| Unsuitable Arguments</a> |
| </h5> |
| <p> |
| In <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1665.pdf" target="_top">Errors |
| in Mathematical Special Functions</a>, J. Marraffino & M. Paterno |
| it is proposed that signalling a domain error is mandatory when the argument |
| would give an mathematically undefined result. |
| </p> |
| <div class="itemizedlist"><ul type="disc"><li> |
| Guideline 1 |
| </li></ul></div> |
| <div class="blockquote"><blockquote class="blockquote"><p> |
| A mathematical function is said to be defined at a point a = (a1, a2, . |
| . .) if the limits as x = (x1, x2, . . .) 'approaches a from all directions |
| agree'. The defined value may be any number, or +infinity, or -infinity. |
| </p></blockquote></div> |
| <p> |
| Put crudely, if the function goes to + infinity and then emerges 'round-the-back' |
| with - infinity, it is NOT defined. |
| </p> |
| <div class="blockquote"><blockquote class="blockquote"><p> |
| The library function which approximates a mathematical function shall signal |
| a domain error whenever evaluated with argument values for which the mathematical |
| function is undefined. |
| </p></blockquote></div> |
| <div class="itemizedlist"><ul type="disc"><li> |
| Guideline 2 |
| </li></ul></div> |
| <div class="blockquote"><blockquote class="blockquote"><p> |
| The library function which approximates a mathematical function shall signal |
| a domain error whenever evaluated with argument values for which the mathematical |
| function obtains a non-real value. |
| </p></blockquote></div> |
| <p> |
| This implementation is believed to follow these proposals and to assist compatibility |
| with <span class="emphasis"><em>ISO/IEC 9899:1999 Programming languages - C</em></span> and |
| with the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">Draft |
| Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph |
| 5</a>. <a class="link" href="../main_overview/error_handling.html" title="Error Handling">See |
| also domain_error</a>. |
| </p> |
| <p> |
| See <a class="link" href="../policy/pol_ref.html" title="Policy Reference">policy reference</a> for |
| details of the error handling policies that should allow a user to comply |
| with any of these recommendations, as well as other behaviour. |
| </p> |
| <p> |
| See <a class="link" href="../main_overview/error_handling.html" title="Error Handling">error handling</a> |
| for a detailed explanation of the mechanism, and <a class="link" href="../dist/stat_tut/weg/error_eg.html" title="Error Handling Example">error_handling |
| example</a> and <a href="../../../../../example/error_handling_example.cpp" target="_top">error_handling_example.cpp</a> |
| </p> |
| <div class="caution"><table border="0" summary="Caution"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td> |
| <th align="left">Caution</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| If you enable throw but do NOT have try & catch block, then the program |
| will terminate with an uncaught exception and probably abort. Therefore |
| to get the benefit of helpful error messages, enabling <span class="bold"><strong>all</strong></span> |
| exceptions <span class="bold"><strong>and</strong></span> using try&catch is |
| recommended for all applications. However, for simplicity, this is not |
| done for most examples. |
| </p></td></tr> |
| </table></div> |
| <a name="math_toolkit.backgrounders.implementation.handling_of_functions_that_are_not_mathematically_defined"></a><h5> |
| <a name="id1283121"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.handling_of_functions_that_are_not_mathematically_defined">Handling |
| of Functions that are Not Mathematically defined</a> |
| </h5> |
| <p> |
| Functions that are not mathematically defined, like the Cauchy mean, fail |
| to compile by default. A <a class="link" href="../policy/pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">policy</a> |
| allows control of this. |
| </p> |
| <p> |
| If the policy is to permit undefined functions, then calling them throws |
| a domain error, by default. But the error policy can be set to not throw, |
| and to return NaN instead. For example, |
| </p> |
| <p> |
| <code class="computeroutput"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> |
| <span class="identifier">ignore_error</span></code> |
| </p> |
| <p> |
| appears before the first Boost include, then if the un-implemented function |
| is called, mean(cauchy<>()) will return std::numeric_limits<T>::quiet_NaN(). |
| </p> |
| <div class="warning"><table border="0" summary="Warning"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td> |
| <th align="left">Warning</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| If <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">has_quiet_NaN</span></code> is false (for example T |
| is a User-defined type), then an exception will always be thrown when a |
| domain error occurs. Catching exceptions is therefore strongly recommended. |
| </p></td></tr> |
| </table></div> |
| <a name="math_toolkit.backgrounders.implementation.median_of_distributions"></a><h5> |
| <a name="id1285308"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.median_of_distributions">Median |
| of distributions</a> |
| </h5> |
| <p> |
| There are many distributions for which we have been unable to find an analytic |
| formula, and this has deterred us from implementing <a href="http://en.wikipedia.org/wiki/Median" target="_top">median |
| functions</a>, the mid-point in a list of values. |
| </p> |
| <p> |
| However a useful numerical approximation for distribution <code class="computeroutput"><span class="identifier">dist</span></code> |
| is available as usual as an accessor non-member function median using <code class="computeroutput"><span class="identifier">median</span><span class="special">(</span><span class="identifier">dist</span><span class="special">)</span></code>, |
| that may be evaluated (in the absence of an analytic formula) by calling |
| </p> |
| <p> |
| <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">0.5</span><span class="special">)</span></code> (this |
| is the <span class="emphasis"><em>mathematical</em></span> definition of course). |
| </p> |
| <p> |
| <a href="http://www.amstat.org/publications/jse/v13n2/vonhippel.html" target="_top">Mean, |
| Median, and Skew, Paul T von Hippel</a> |
| </p> |
| <p> |
| <a href="http://documents.wolfram.co.jp/teachersedition/MathematicaBook/24.5.html" target="_top">Descriptive |
| Statistics,</a> |
| </p> |
| <p> |
| <a href="http://documents.wolfram.co.jp/v5/Add-onsLinks/StandardPackages/Statistics/DescriptiveStatistics.html" target="_top">and |
| </a> |
| </p> |
| <p> |
| <a href="http://documents.wolfram.com/v5/TheMathematicaBook/AdvancedMathematicsInMathematica/NumericalOperationsOnData/3.8.1.html" target="_top">Mathematica |
| Basic Statistics.</a> give more detail, in particular for discrete distributions. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity"></a><h5> |
| <a name="id1285426"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity">Handling |
| of Floating-Point Infinity</a> |
| </h5> |
| <p> |
| Some functions and distributions are well defined with + or - infinity as |
| argument(s), but after some experiments with handling infinite arguments |
| as special cases, we concluded that it was generally more useful to forbid |
| this, and instead to return the result of <a class="link" href="../main_overview/error_handling.html#domain_error">domain_error</a>. |
| </p> |
| <p> |
| Handling infinity as special cases is additionally complicated because, unlike |
| built-in types on most - but not all - platforms, not all User-Defined Types |
| are specialized to provide <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</span><span class="identifier">infinity</span><span class="special">()</span></code> and would return zero rather than any representation |
| of infinity. |
| </p> |
| <p> |
| The rationale is that non-finiteness may happen because of error or overflow |
| in the users code, and it will be more helpful for this to be diagnosed promptly |
| rather than just continuing. The code also became much more complicated, |
| more error-prone, much more work to test, and much less readable. |
| </p> |
| <p> |
| However in a few cases, for example normal, where we felt it obvious, we |
| have permitted argument(s) to be infinity, provided infinity is implemented |
| for the realType on that implementation. |
| </p> |
| <p> |
| Users who require special handling of infinity (or other specific value) |
| can, of course, always intercept this before calling a distribution or function |
| and return their own choice of value, or other behavior. This will often |
| be simpler than trying to handle the aftermath of the error policy. |
| </p> |
| <p> |
| Overflow, underflow, denorm can be handled using <a class="link" href="../policy/pol_ref/error_handling_policies.html" title="Error Handling Policies">error |
| handling policies</a>. |
| </p> |
| <p> |
| We have also tried to catch boundary cases where the mathematical specification |
| would result in divide by zero or overflow and signalling these similarly. |
| What happens at (and near), poles can be controlled through <a class="link" href="../policy/pol_ref/error_handling_policies.html" title="Error Handling Policies">error |
| handling policies</a>. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.scale__shape_and_location"></a><h5> |
| <a name="id1285513"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.scale__shape_and_location">Scale, |
| Shape and Location</a> |
| </h5> |
| <p> |
| We considered adding location and scale to the list of functions, for example: |
| </p> |
| <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">></span> |
| <span class="keyword">inline</span> <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">triangular_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>&</span> <span class="identifier">dist</span><span class="special">)</span> |
| <span class="special">{</span> |
| <span class="identifier">RealType</span> <span class="identifier">lower</span> <span class="special">=</span> <span class="identifier">dist</span><span class="special">.</span><span class="identifier">lower</span><span class="special">();</span> |
| <span class="identifier">RealType</span> <span class="identifier">mode</span> <span class="special">=</span> <span class="identifier">dist</span><span class="special">.</span><span class="identifier">mode</span><span class="special">();</span> |
| <span class="identifier">RealType</span> <span class="identifier">upper</span> <span class="special">=</span> <span class="identifier">dist</span><span class="special">.</span><span class="identifier">upper</span><span class="special">();</span> |
| <span class="identifier">RealType</span> <span class="identifier">result</span><span class="special">;</span> <span class="comment">// of checks. |
| </span> <span class="keyword">if</span><span class="special">(</span><span class="keyword">false</span> <span class="special">==</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">check_triangular</span><span class="special">(</span><span class="identifier">BOOST_CURRENT_FUNCTION</span><span class="special">,</span> <span class="identifier">lower</span><span class="special">,</span> <span class="identifier">mode</span><span class="special">,</span> <span class="identifier">upper</span><span class="special">,</span> <span class="special">&</span><span class="identifier">result</span><span class="special">))</span> |
| <span class="special">{</span> |
| <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> |
| <span class="special">}</span> |
| <span class="keyword">return</span> <span class="special">(</span><span class="identifier">upper</span> <span class="special">-</span> <span class="identifier">lower</span><span class="special">);</span> |
| <span class="special">}</span> |
| </pre> |
| <p> |
| but found that these concepts are not defined (or their definition too contentious) |
| for too many distributions to be generally applicable. Because they are non-member |
| functions, they can be added if required. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.notes_on_implementation_of_specific_functions__amp__distributions"></a><h5> |
| <a name="id1285848"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.notes_on_implementation_of_specific_functions__amp__distributions">Notes |
| on Implementation of Specific Functions & Distributions</a> |
| </h5> |
| <div class="itemizedlist"><ul type="disc"><li> |
| Default parameters for the Triangular Distribution. We are uncertain |
| about the best default parameters. Some sources suggest that the Standard |
| Triangular Distribution has lower = 0, mode = half and upper = 1. However |
| as a approximation for the normal distribution, the most common usage, |
| lower = -1, mode = 0 and upper = 1 would be more suitable. |
| </li></ul></div> |
| <a name="math_toolkit.backgrounders.implementation.rational_approximations_used"></a><h5> |
| <a name="id1285872"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">Rational |
| Approximations Used</a> |
| </h5> |
| <p> |
| Some of the special functions in this library are implemented via rational |
| approximations. These are either taken from the literature, or devised by |
| John Maddock using <a class="link" href="../toolkit/internals2/minimax.html" title="Minimax Approximations and the Remez Algorithm">our |
| Remez code</a>. |
| </p> |
| <p> |
| Rational rather than Polynomial approximations are used to ensure accuracy: |
| polynomial approximations are often wonderful up to a certain level of accuracy, |
| but then quite often fail to provide much greater accuracy no matter how |
| many more terms are added. |
| </p> |
| <p> |
| Our own approximations were devised either for added accuracy (to support |
| 128-bit long doubles for example), or because literature methods were unavailable |
| or under non-BSL compatible license. Our Remez code is known to produce good |
| agreement with literature results in fairly simple "toy" cases. |
| All approximations were checked for convergence and to ensure that they were |
| not ill-conditioned (the coefficients can give a theoretically good solution, |
| but the resulting rational function may be un-computable at fixed precision). |
| </p> |
| <p> |
| Recomputing using different Remez implementations may well produce differing |
| coefficients: the problem is well known to be ill conditioned in general, |
| and our Remez implementation often found a broad and ill-defined minima for |
| many of these approximations (of course for simple "toy" examples |
| like approximating <code class="computeroutput"><span class="identifier">exp</span></code> the |
| minima is well defined, and the coeffiecents should agree no matter whose |
| Remez implementation is used). This should not in general effect the validity |
| of the approximations: there's good literature supporting the idea that coefficients |
| can be "in error" without necessarily adversely effecting the result. |
| Note that "in error" has a special meaning in this context, see |
| <a href="http://front.math.ucdavis.edu/0101.5042" target="_top">"Approximate construction |
| of rational approximations and the effect of error autocorrection.", |
| Grigori Litvinov, eprint arXiv:math/0101042</a>. Therefore the coefficients |
| still need to be accurately calculated, even if they can be in error compared |
| to the "true" minimax solution. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.representation_of_mathematical_constants"></a><h5> |
| <a name="id1285916"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.representation_of_mathematical_constants">Representation |
| of Mathematical Constants</a> |
| </h5> |
| <p> |
| A macro BOOST_DEFINE_MATH_CONSTANT in constants.hpp is used to provide high |
| accuracy constants to mathematical functions and distributions, since it |
| is important to provide values uniformly for both built-in float, double |
| and long double types, and for User Defined types like NTL::quad_float and |
| NTL::RR. |
| </p> |
| <p> |
| To permit calculations in this Math ToolKit and its tests, (and elsewhere) |
| at about 100 decimal digits with NTL::RR type, it is obviously necessary |
| to define constants to this accuracy. |
| </p> |
| <p> |
| However, some compilers do not accept decimal digits strings as long as this. |
| So the constant is split into two parts, with the 1st containing at least |
| long double precision, and the 2nd zero if not needed or known. The 3rd part |
| permits an exponent to be provided if necessary (use zero if none) - the |
| other two parameters may only contain decimal digits (and sign and decimal |
| point), and may NOT include an exponent like 1.234E99 (nor a trailing F or |
| L). The second digit string is only used if T is a User-Defined Type, when |
| the constant is converted to a long string literal and lexical_casted to |
| type T. (This is necessary because you can't use a numeric constant since |
| even a long double might not have enough digits). |
| </p> |
| <p> |
| For example, pi is defined: |
| </p> |
| <pre class="programlisting"><span class="identifier">BOOST_DEFINE_MATH_CONSTANT</span><span class="special">(</span><span class="identifier">pi</span><span class="special">,</span> |
| <span class="number">3.141592653589793238462643383279502884197169399375105820974944</span><span class="special">,</span> |
| <span class="number">5923078164062862089986280348253421170679821480865132823066470938446095505</span><span class="special">,</span> |
| <span class="number">0</span><span class="special">)</span> |
| </pre> |
| <p> |
| And used thus: |
| </p> |
| <pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">;</span> |
| |
| <span class="keyword">double</span> <span class="identifier">diameter</span> <span class="special">=</span> <span class="number">1.</span><span class="special">;</span> |
| <span class="keyword">double</span> <span class="identifier">radius</span> <span class="special">=</span> <span class="identifier">diameter</span> <span class="special">*</span> <span class="identifier">pi</span><span class="special"><</span><span class="keyword">double</span><span class="special">>();</span> |
| |
| <span class="keyword">or</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special"><</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">>()</span> |
| </pre> |
| <p> |
| Note that it is necessary (if inconvenient) to specify the type explicitly. |
| </p> |
| <p> |
| So you cannot write |
| </p> |
| <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special"><>();</span> <span class="comment">// could not deduce template argument for 'T' |
| </span></pre> |
| <p> |
| Neither can you write: |
| </p> |
| <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">;</span> <span class="comment">// Context does not allow for disambiguation of overloaded function |
| </span><span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">();</span> <span class="comment">// Context does not allow for disambiguation of overloaded function |
| </span></pre> |
| <a name="math_toolkit.backgrounders.implementation.thread_safety"></a><h5> |
| <a name="id1286302"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.thread_safety">Thread |
| safety</a> |
| </h5> |
| <p> |
| Reporting of error by setting errno should be thread safe already (otherwise |
| none of the std lib math functions would be thread safe?). If you turn on |
| reporting of errors via exceptions, errno gets left unused anyway. |
| </p> |
| <p> |
| Other than that, the code is intended to be thread safe <span class="bold"><strong>for |
| built in real-number types</strong></span> : so float, double and long double |
| are all thread safe. |
| </p> |
| <p> |
| For non-built-in types - NTL::RR for example - initialisation of the various |
| constants used in the implementation is potentially <span class="bold"><strong>not</strong></span> |
| thread safe. This most undesiable, but it would be a signficant challenge |
| to fix it. Some compilers may offer the option of having static-constants |
| initialised in a thread safe manner (Commeau, and maybe others?), if that's |
| the case then the problem is solved. This is a topic of hot debate for the |
| next C++ std revision, so hopefully all compilers will be required to do |
| the right thing here at some point. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.sources_of_test_data"></a><h5> |
| <a name="id1286338"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.sources_of_test_data">Sources |
| of Test Data</a> |
| </h5> |
| <p> |
| We found a large number of sources of test data. We have assumed that these |
| are <span class="emphasis"><em>"known good"</em></span> if they agree with the results |
| from our test and only consulted other sources for their <span class="emphasis"><em>'vote'</em></span> |
| in the case of serious disagreement. The accuracy, actual and claimed, vary |
| very widely. Only <a href="http://functions.wolfram.com/" target="_top">Wolfram Mathematica |
| functions</a> provided a higher accuracy than C++ double (64-bit floating-point) |
| and was regarded as the most-trusted source by far. The <a href="http://www.r-project.org/" target="_top">The |
| R Project for Statistical Computing</a> provided the widest range of |
| distributions, but the usual Intel X86 distribution uses 64-but doubles, |
| so our use was limited to the 15 to 17 decimal digit accuracy. |
| </p> |
| <p> |
| A useful index of sources is: <a href="http://www.sal.hut.fi/Teaching/Resources/ProbStat/table.html" target="_top">Web-oriented |
| Teaching Resources in Probability and Statistics</a> |
| </p> |
| <p> |
| <a href="http://espse.ed.psu.edu/edpsych/faculty/rhale/hale/507Mat/statlets/free/pdist.htm" target="_top">Statlet</a>: |
| Is a Javascript application that calculates and plots probability distributions, |
| and provides the most complete range of distributions: |
| </p> |
| <div class="blockquote"><blockquote class="blockquote"><p> |
| Bernoulli, Binomial, discrete uniform, geometric, hypergeometric, negative |
| binomial, Poisson, beta, Cauchy-Lorentz, chi-sequared, Erlang, exponential, |
| extreme value, Fisher, gamma, Laplace, logistic, lognormal, normal, Parteo, |
| Student's t, triangular, uniform, and Weibull. |
| </p></blockquote></div> |
| <p> |
| It calculates pdf, cdf, survivor, log survivor, hazard, tail areas, & |
| critical values for 5 tail values. |
| </p> |
| <p> |
| It is also the only independent source found for the Weibull distribution; |
| unfortunately it appears to suffer from very poor accuracy in areas where |
| the underlying special function is known to be difficult to implement. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.creating_and_managing_the_equations"></a><h5> |
| <a name="id1286407"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.creating_and_managing_the_equations">Creating |
| and Managing the Equations</a> |
| </h5> |
| <p> |
| Equations that fit on a single line can most easily be produced by inline |
| Quickbook code using templates for Unicode Greek and Unicode Math symbols. |
| All Greek letter and small set of Math symbols is available at /boost-path/libs/math/doc/sf_and_dist/html4_symbols.qbk |
| </p> |
| <p> |
| Where equations need to use more than one line, real Math editors were used. |
| </p> |
| <p> |
| The primary source for the equations is now <a href="http://www.w3.org/Math/" target="_top">MathML</a>: |
| see the *.mml files in libs/math/doc/sf_and_dist/equations/. |
| </p> |
| <p> |
| These are most easily edited by a GUI editor such as <a href="http://mathcast.sourceforge.net/home.html" target="_top">Mathcast</a>, |
| please note that the equation editor supplied with Open Office currently |
| mangles these files and should not currently be used. |
| </p> |
| <p> |
| Conversion to SVG was achieved using <a href="http://www.grigoriev.ru/svgmath/" target="_top">SVGMath</a> |
| and a command line such as: |
| </p> |
| <pre class="programlisting">$for file in *.mml; do |
| >/cygdrive/c/Python25/python.exe 'C:\download\open\SVGMath-0.3.1\math2svg.py' \ |
| >>$file > $(basename $file .mml).svg |
| >done |
| </pre> |
| <p> |
| See also the section on "Using Python to run Inkscape" and "Using |
| inkscape to convert scalable vector SVG files to Portable Network graphic |
| PNG". |
| </p> |
| <p> |
| Note that SVGMath requires that the mml files are <span class="bold"><strong>not</strong></span> |
| wrapped in an XHTML XML wrapper - this is added by Mathcast by default - |
| one workaround is to copy an existing mml file and then edit it with Mathcast: |
| the existing format should then be preserved. This is a bug in the XML parser |
| used by SVGMath which the author is aware of. |
| </p> |
| <p> |
| If neccessary the XHTML wrapper can be removed with: |
| </p> |
| <pre class="programlisting">cat filename | tr -d "\r\n" | sed -e 's/.*\(<math[^>]*>.*</math>\).*/\1/' > newfile</pre> |
| <p> |
| Setting up fonts for SVGMath is currently rather tricky, on a Windows XP |
| system JM's font setup is the same as the sample config file provided with |
| SVGMath but with: |
| </p> |
| <pre class="programlisting"><!-- Double-struck --> |
| <mathvariant name="double-struck" family="Mathematica7, Lucida Sans Unicode"/> |
| </pre> |
| <p> |
| changed to: |
| </p> |
| <pre class="programlisting"><!-- Double-struck --> |
| <mathvariant name="double-struck" family="Lucida Sans Unicode"/> |
| </pre> |
| <p> |
| Note that unlike the sample config file supplied with SVGMath, this does |
| not make use of the Mathematica 7 font as this lacks sufficient Unicode information |
| for it to be used with either SVGMath or XEP "as is". |
| </p> |
| <p> |
| Also note that the SVG files in the repository are almost certainly Windows-specific |
| since they reference various Windows Fonts. |
| </p> |
| <p> |
| PNG files can be created from the SVG's using <a href="http://xmlgraphics.apache.org/batik/tools/rasterizer.html" target="_top">Batik</a> |
| and a command such as: |
| </p> |
| <pre class="programlisting">java -jar 'C:\download\open\batik-1.7\batik-rasterizer.jar' -dpi 120 *.svg</pre> |
| <p> |
| Or using Inkscape and a command such as: |
| </p> |
| <pre class="programlisting">for file in *.svg; do |
| /cygdrive/c/progra~1/Inkscape/inkscape -d 120 -e $(cygpath -a -w $(basename $file .svg).png) $(cygpath -a -w $file); |
| done</pre> |
| <p> |
| Currently Inkscape seems to generate the better looking png's. |
| </p> |
| <p> |
| The PDF is generated into \pdf\math.pdf using a command from a shell or command |
| window with current directory \math_toolkit\libs\math\doc\sf_and_dist, typically: |
| </p> |
| <pre class="programlisting">bjam -a pdf >math_pdf.log</pre> |
| <p> |
| Note that XEP will have to be configured to <span class="bold"><strong>use and |
| embed</strong></span> whatever fonts are used by the SVG equations (almost certainly |
| editing the sample xep.xml provided by the XEP installation). If you fail |
| to do this you will get XEP warnings in the log file like |
| </p> |
| <pre class="programlisting">[warning]could not find any font family matching "Times New Roman"; replaced by Helvetica</pre> |
| <p> |
| (html is the default so it is generated at math_toolkit\libs\math\doc\sf_and_dist\html\index.html |
| using command line >bjam -a > math_docs.log). |
| </p> |
| <pre class="programlisting"><span class="special"><!--</span> <span class="identifier">Sample</span> <span class="identifier">configuration</span> <span class="keyword">for</span> <span class="identifier">Windows</span> <span class="identifier">TrueType</span> <span class="identifier">fonts</span><span class="special">.</span> <span class="special">--></span> |
| </pre> |
| <p> |
| <!-- Sample configuration for Windows TrueType fonts. --> is provided |
| in the xep.xml downloaded, but the Windows TrueType fonts are commented out. |
| </p> |
| <p> |
| JM's XEP config file \xep\xep.xml has the following font configuration section |
| added: |
| </p> |
| <pre class="programlisting"><font-group xml:base="file:/C:/Windows/Fonts/" label="Windows TrueType" embed="true" subset="true"> |
| <font-family name="Arial"> |
| <font><font-data ttf="arial.ttf"/></font> |
| <font style="oblique"><font-data ttf="ariali.ttf"/></font> |
| <font weight="bold"><font-data ttf="arialbd.ttf"/></font> |
| <font weight="bold" style="oblique"><font-data ttf="arialbi.ttf"/></font> |
| </font-family> |
| |
| <font-family name="Times New Roman" ligatures="&#xFB01; &#xFB02;"> |
| <font><font-data ttf="times.ttf"/></font> |
| <font style="italic"><font-data ttf="timesi.ttf"/></font> |
| <font weight="bold"><font-data ttf="timesbd.ttf"/></font> |
| <font weight="bold" style="italic"><font-data ttf="timesbi.ttf"/></font> |
| </font-family> |
| |
| <font-family name="Courier New"> |
| <font><font-data ttf="cour.ttf"/></font> |
| <font style="oblique"><font-data ttf="couri.ttf"/></font> |
| <font weight="bold"><font-data ttf="courbd.ttf"/></font> |
| <font weight="bold" style="oblique"><font-data ttf="courbi.ttf"/></font> |
| </font-family> |
| |
| <font-family name="Tahoma" embed="true"> |
| <font><font-data ttf="tahoma.ttf"/></font> |
| <font weight="bold"><font-data ttf="tahomabd.ttf"/></font> |
| </font-family> |
| |
| <font-family name="Verdana" embed="true"> |
| <font><font-data ttf="verdana.ttf"/></font> |
| <font style="oblique"><font-data ttf="verdanai.ttf"/></font> |
| <font weight="bold"><font-data ttf="verdanab.ttf"/></font> |
| <font weight="bold" style="oblique"><font-data ttf="verdanaz.ttf"/></font> |
| </font-family> |
| |
| <font-family name="Palatino" embed="true" ligatures="&#xFB00; &#xFB01; &#xFB02; &#xFB03; &#xFB04;"> |
| <font><font-data ttf="pala.ttf"/></font> |
| <font style="italic"><font-data ttf="palai.ttf"/></font> |
| <font weight="bold"><font-data ttf="palab.ttf"/></font> |
| <font weight="bold" style="italic"><font-data ttf="palabi.ttf"/></font> |
| </font-family> |
| |
| <font-family name<code class="literal">"Lucida Sans Unicode"> |
| <!-- <font><font-data ttf</code>"lsansuni.ttf"><<span class="emphasis"><em>font> --> |
| <!-- actually called l_10646.ttf on Windows 2000 and Vista Sp1 --> |
| <font><font-data ttf="l_10646.ttf"</em></span>></font> |
| </font-family> |
| </pre> |
| <p> |
| PAB had to alter his because the Lucida Sans Unicode font had a different |
| name. Other changes are very likely to be required if you are not using Windows. |
| </p> |
| <p> |
| XZ authored his equations using the venerable Latex, JM converted these to |
| MathML using <a href="http://gentoo-wiki.com/HOWTO_Convert_LaTeX_to_HTML_with_MathML" target="_top">mxlatex</a>. |
| This process is currently unreliable and required some manual intervention: |
| consequently Latex source is not considered a viable route for the automatic |
| production of SVG versions of equations. |
| </p> |
| <p> |
| Equations are embedded in the quickbook source using the <span class="emphasis"><em>equation</em></span> |
| template defined in math.qbk. This outputs Docbook XML that looks like: |
| </p> |
| <pre class="programlisting"><inlinemediaobject> |
| <imageobject role<code class="literal">"html"> |
| <imagedata fileref</code>"../equations/myfile.png"></imagedata> |
| </imageobject> |
| <imageobject role<code class="literal">"print"> |
| <imagedata fileref</code>"../equations/myfile.svg"></imagedata> |
| </imageobject> |
| </inlinemediaobject> |
| </pre> |
| <p> |
| MathML is not currently present in the Docbook output, or in the generated |
| HTML: this needs further investigation. |
| </p> |
| <a name="math_toolkit.backgrounders.implementation.producing_graphs"></a><h5> |
| <a name="id1286664"></a> |
| <a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.producing_graphs">Producing |
| Graphs</a> |
| </h5> |
| <p> |
| Graphs were produced in SVG format and then converted to PNG's using the |
| same process as the equations. |
| </p> |
| <p> |
| The programs <code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">doc</span><span class="special">/</span><span class="identifier">sf_and_dist</span><span class="special">/</span><span class="identifier">graphs</span><span class="special">/</span><span class="identifier">dist_graphs</span><span class="special">.</span><span class="identifier">cpp</span></code> and |
| <code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">doc</span><span class="special">/</span><span class="identifier">sf_and_dist</span><span class="special">/</span><span class="identifier">graphs</span><span class="special">/</span><span class="identifier">sf_graphs</span><span class="special">.</span><span class="identifier">cpp</span></code> generate |
| the SVG's directly using the <a href="http://code.google.com/soc/2007/boost/about.html" target="_top">Google |
| Summer of Code 2007</a> project of Jacob Voytko (whose work so far, considerably |
| enhanced and now reasonably mature and usable, by Paul A. Bristow, is at |
| .\boost-sandbox\SOC\2007\visualization). |
| </p> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2006 , 2007, 2008, 2009, 2010 John Maddock, Paul A. Bristow, |
| Hubert Holin, Xiaogang Zhang, Bruno Lalande, Johan Råde, Gautam Sewani and |
| Thijs van den Berg<p> |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="../backgrounders.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |
