libs/math/doc/html/math_toolkit/sf_implementation.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Additional Implementation Notes</title>
   5 <link rel="stylesheet" href="../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../index.html" title="Math Toolkit 2.11.0">
   8 <link rel="up" href="../backgrounders.html" title="Chapter&#160;22.&#160;Backgrounders">
   9 <link rel="prev" href="../backgrounders.html" title="Chapter&#160;22.&#160;Backgrounders">
  10 <link rel="next" href="special_tut.html" title="Tutorial: How to Write a New Special Function">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <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="special_tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="math_toolkit.sf_implementation"></a><a class="link" href="sf_implementation.html" title="Additional Implementation Notes">Additional Implementation
  28     Notes</a>
  29 </h2></div></div></div>
  30 <p>
  31       The majority of the implementation notes are included with the documentation
  32       of each function or distribution. The notes here are of a more general nature,
  33       and reflect more the general implementation philosophy used.
  34     </p>
  35 <h5>
  36 <a name="math_toolkit.sf_implementation.h0"></a>
  37       <span class="phrase"><a name="math_toolkit.sf_implementation.implementation_philosophy"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.implementation_philosophy">Implementation
  38       philosophy</a>
  39     </h5>
  40 <p>
  41       "First be right, then be fast."
  42     </p>
  43 <p>
  44       There will always be potential compromises to be made between speed and accuracy.
  45       It may be possible to find faster methods, particularly for certain limited
  46       ranges of arguments, but for most applications of math functions and distributions,
  47       we judge that speed is rarely as important as accuracy.
  48     </p>
  49 <p>
  50       So our priority is accuracy.
  51     </p>
  52 <p>
  53       To permit evaluation of accuracy of the special functions, production of extremely
  54       accurate tables of test values has received considerable effort.
  55     </p>
  56 <p>
  57       (It also required much CPU effort - there was some danger of molten plastic
  58       dripping from the bottom of JM's laptop, so instead, PAB's Dual-core desktop
  59       was kept 50% busy for <span class="bold"><strong>days</strong></span> calculating some
  60       tables of test values!)
  61     </p>
  62 <p>
  63       For a specific RealType, say <code class="computeroutput"><span class="keyword">float</span></code>
  64       or <code class="computeroutput"><span class="keyword">double</span></code>, it may be possible
  65       to find approximations for some functions that are simpler and thus faster,
  66       but less accurate (perhaps because there are no refining iterations, for example,
  67       when calculating inverse functions).
  68     </p>
  69 <p>
  70       If these prove accurate enough to be "fit for his purpose", then
  71       a user may substitute his custom specialization.
  72     </p>
  73 <p>
  74       For example, there are approximations dating back from times when computation
  75       was a <span class="bold"><strong>lot</strong></span> more expensive:
  76     </p>
  77 <p>
  78       H Goldberg and H Levine, Approximate formulas for percentage points and normalisation
  79       of t and chi squared, Ann. Math. Stat., 17(4), 216 - 225 (Dec 1946).
  80     </p>
  81 <p>
  82       A H Carter, Approximations to percentage points of the z-distribution, Biometrika
  83       34(2), 352 - 358 (Dec 1947).
  84     </p>
  85 <p>
  86       These could still provide sufficient accuracy for some speed-critical applications.
  87     </p>
  88 <h5>
  89 <a name="math_toolkit.sf_implementation.h1"></a>
  90       <span class="phrase"><a name="math_toolkit.sf_implementation.accuracy_and_representation_of_t"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.accuracy_and_representation_of_t">Accuracy
  91       and Representation of Test Values</a>
  92     </h5>
  93 <p>
  94       In order to be accurate enough for as many as possible real types, constant
  95       values are given to 50 decimal digits if available (though many sources proved
  96       only accurate near to 64-bit double precision). Values are specified as long
  97       double types by appending L, unless they are exactly representable, for example
  98       integers, or binary fractions like 0.125. This avoids the risk of loss of accuracy
  99       converting from double, the default type. Values are used after <code class="computeroutput"><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="number">1.2345L</span><span class="special">)</span></code> to provide
 100       the appropriate RealType for spot tests.
 101     </p>
 102 <p>
 103       Functions that return constants values, like kurtosis for example, are written
 104       as
 105     </p>
 106 <p>
 107       <code class="computeroutput"><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(-</span><span class="number">3</span><span class="special">)</span> <span class="special">/</span>
 108       <span class="number">5</span><span class="special">;</span></code>
 109     </p>
 110 <p>
 111       to provide the most accurate value that the compiler can compute for the real
 112       type. (The denominator is an integer and so will be promoted exactly).
 113     </p>
 114 <p>
 115       So tests for one third, <span class="bold"><strong>not</strong></span> exactly representable
 116       with radix two floating-point, (should) use, for example:
 117     </p>
 118 <p>
 119       <code class="computeroutput"><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="number">1</span><span class="special">)</span> <span class="special">/</span>
 120       <span class="number">3</span><span class="special">;</span></code>
 121     </p>
 122 <p>
 123       If a function is very sensitive to changes in input, specifying an inexact
 124       value as input (such as 0.1) can throw the result off by a noticeable amount:
 125       0.1f is "wrong" by ~1e-7 for example (because 0.1 has no exact binary
 126       representation). That is why exact binary values - halves, quarters, and eighths
 127       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>
 128       with <code class="computeroutput"><span class="identifier">b</span></code> a power of two (in order
 129       to ensure that the result is an exactly representable binary value).
 130     </p>
 131 <h5>
 132 <a name="math_toolkit.sf_implementation.h2"></a>
 133       <span class="phrase"><a name="math_toolkit.sf_implementation.tolerance_of_tests"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.tolerance_of_tests">Tolerance
 134       of Tests</a>
 135     </h5>
 136 <p>
 137       The tolerances need to be set to the maximum of:
 138     </p>
 139 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 140 <li class="listitem">
 141           Some epsilon value.
 142         </li>
 143 <li class="listitem">
 144           The accuracy of the data (often only near 64-bit double).
 145         </li>
 146 </ul></div>
 147 <p>
 148       Otherwise when long double has more digits than the test data, then no amount
 149       of tweaking an epsilon based tolerance will work.
 150     </p>
 151 <p>
 152       A common problem is when tolerances that are suitable for implementations like
 153       Microsoft VS.NET where double and long double are the same size: tests fail
 154       on other systems where long double is more accurate than double. Check first
 155       that the suffix L is present, and then that the tolerance is big enough.
 156     </p>
 157 <h5>
 158 <a name="math_toolkit.sf_implementation.h3"></a>
 159       <span class="phrase"><a name="math_toolkit.sf_implementation.handling_unsuitable_arguments"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.handling_unsuitable_arguments">Handling
 160       Unsuitable Arguments</a>
 161     </h5>
 162 <p>
 163       In <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1665.pdf" target="_top">Errors
 164       in Mathematical Special Functions</a>, J. Marraffino &amp; M. Paterno it
 165       is proposed that signalling a domain error is mandatory when the argument would
 166       give an mathematically undefined result.
 167     </p>
 168 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 169           Guideline 1
 170         </li></ul></div>
 171 <div class="blockquote"><blockquote class="blockquote"><p>
 172         A mathematical function is said to be defined at a point a = (a1, a2, . .
 173         .) if the limits as x = (x1, x2, . . .) 'approaches a from all directions
 174         agree'. The defined value may be any number, or +infinity, or -infinity.
 175       </p></blockquote></div>
 176 <p>
 177       Put crudely, if the function goes to + infinity and then emerges 'round-the-back'
 178       with - infinity, it is NOT defined.
 179     </p>
 180 <div class="blockquote"><blockquote class="blockquote"><p>
 181         The library function which approximates a mathematical function shall signal
 182         a domain error whenever evaluated with argument values for which the mathematical
 183         function is undefined.
 184       </p></blockquote></div>
 185 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 186           Guideline 2
 187         </li></ul></div>
 188 <div class="blockquote"><blockquote class="blockquote"><p>
 189         The library function which approximates a mathematical function shall signal
 190         a domain error whenever evaluated with argument values for which the mathematical
 191         function obtains a non-real value.
 192       </p></blockquote></div>
 193 <p>
 194       This implementation is believed to follow these proposals and to assist compatibility
 195       with <span class="emphasis"><em>ISO/IEC 9899:1999 Programming languages - C</em></span> and with
 196       the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">Draft
 197       Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph
 198       5</a>. <a class="link" href="error_handling.html" title="Error Handling">See also domain_error</a>.
 199     </p>
 200 <p>
 201       See <a class="link" href="pol_ref.html" title="Policy Reference">policy reference</a> for details
 202       of the error handling policies that should allow a user to comply with any
 203       of these recommendations, as well as other behaviour.
 204     </p>
 205 <p>
 206       See <a class="link" href="error_handling.html" title="Error Handling">error handling</a> for a
 207       detailed explanation of the mechanism, and <a class="link" href="stat_tut/weg/error_eg.html" title="Error Handling Example">error_handling
 208       example</a> and <a href="../../../example/error_handling_example.cpp" target="_top">error_handling_example.cpp</a>
 209     </p>
 210 <div class="caution"><table border="0" summary="Caution">
 211 <tr>
 212 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../doc/src/images/caution.png"></td>
 213 <th align="left">Caution</th>
 214 </tr>
 215 <tr><td align="left" valign="top"><p>
 216         If you enable throw but do NOT have try &amp; catch block, then the program
 217         will terminate with an uncaught exception and probably abort. Therefore to
 218         get the benefit of helpful error messages, enabling <span class="bold"><strong>all</strong></span>
 219         exceptions <span class="bold"><strong>and</strong></span> using try&amp;catch is recommended
 220         for all applications. However, for simplicity, this is not done for most
 221         examples.
 222       </p></td></tr>
 223 </table></div>
 224 <h5>
 225 <a name="math_toolkit.sf_implementation.h4"></a>
 226       <span class="phrase"><a name="math_toolkit.sf_implementation.handling_of_functions_that_are_n"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.handling_of_functions_that_are_n">Handling
 227       of Functions that are Not Mathematically defined</a>
 228     </h5>
 229 <p>
 230       Functions that are not mathematically defined, like the Cauchy mean, fail to
 231       compile by default. A <a class="link" href="pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">policy</a>
 232       allows control of this.
 233     </p>
 234 <p>
 235       If the policy is to permit undefined functions, then calling them throws a
 236       domain error, by default. But the error policy can be set to not throw, and
 237       to return NaN instead. For example,
 238     </p>
 239 <p>
 240       <code class="computeroutput"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span>
 241       <span class="identifier">ignore_error</span></code>
 242     </p>
 243 <p>
 244       appears before the first Boost include, then if the un-implemented function
 245       is called, mean(cauchy&lt;&gt;()) will return std::numeric_limits&lt;T&gt;::quiet_NaN().
 246     </p>
 247 <div class="warning"><table border="0" summary="Warning">
 248 <tr>
 249 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
 250 <th align="left">Warning</th>
 251 </tr>
 252 <tr><td align="left" valign="top"><p>
 253         If <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">has_quiet_NaN</span></code> is false (for example, if
 254         T is a User-defined type without NaN support), then an exception will always
 255         be thrown when a domain error occurs. Catching exceptions is therefore strongly
 256         recommended.
 257       </p></td></tr>
 258 </table></div>
 259 <h5>
 260 <a name="math_toolkit.sf_implementation.h5"></a>
 261       <span class="phrase"><a name="math_toolkit.sf_implementation.median_of_distributions"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.median_of_distributions">Median of
 262       distributions</a>
 263     </h5>
 264 <p>
 265       There are many distributions for which we have been unable to find an analytic
 266       formula, and this has deterred us from implementing <a href="http://en.wikipedia.org/wiki/Median" target="_top">median
 267       functions</a>, the mid-point in a list of values.
 268     </p>
 269 <p>
 270       However a useful numerical approximation for distribution <code class="computeroutput"><span class="identifier">dist</span></code>
 271       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
 272       an analytic formula) by calling
 273     </p>
 274 <p>
 275       <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>
 276       definition of course).
 277     </p>
 278 <p>
 279       <a href="http://www.amstat.org/publications/jse/v13n2/vonhippel.html" target="_top">Mean,
 280       Median, and Skew, Paul T von Hippel</a>
 281     </p>
 282 <p>
 283       <a href="http://documents.wolfram.co.jp/teachersedition/MathematicaBook/24.5.html" target="_top">Descriptive
 284       Statistics,</a>
 285     </p>
 286 <p>
 287       <a href="http://documents.wolfram.co.jp/v5/Add-onsLinks/StandardPackages/Statistics/DescriptiveStatistics.html" target="_top">and
 288       </a>
 289     </p>
 290 <p>
 291       <a href="http://documents.wolfram.com/v5/TheMathematicaBook/AdvancedMathematicsInMathematica/NumericalOperationsOnData/3.8.1.html" target="_top">Mathematica
 292       Basic Statistics.</a> give more detail, in particular for discrete distributions.
 293     </p>
 294 <h5>
 295 <a name="math_toolkit.sf_implementation.h6"></a>
 296       <span class="phrase"><a name="math_toolkit.sf_implementation.handling_of_floating_point_infin"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.handling_of_floating_point_infin">Handling
 297       of Floating-Point Infinity</a>
 298     </h5>
 299 <p>
 300       Some functions and distributions are well defined with + or - infinity as argument(s),
 301       but after some experiments with handling infinite arguments as special cases,
 302       we concluded that it was generally more useful to forbid this, and instead
 303       to return the result of <a class="link" href="error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
 304     </p>
 305 <p>
 306       Handling infinity as special cases is additionally complicated because, unlike
 307       built-in types on most - but not all - platforms, not all User-Defined Types
 308       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">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code> and would return zero rather than any representation
 309       of infinity.
 310     </p>
 311 <p>
 312       The rationale is that non-finiteness may happen because of error or overflow
 313       in the users code, and it will be more helpful for this to be diagnosed promptly
 314       rather than just continuing. The code also became much more complicated, more
 315       error-prone, much more work to test, and much less readable.
 316     </p>
 317 <p>
 318       However in a few cases, for example normal, where we felt it obvious, we have
 319       permitted argument(s) to be infinity, provided infinity is implemented for
 320       the <code class="computeroutput"><span class="identifier">RealType</span></code> on that implementation,
 321       and it is supported and tested by the distribution.
 322     </p>
 323 <p>
 324       The range for these distributions is set to infinity if supported by the platform,
 325       (by testing <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">has_infinity</span></code>) else the maximum value provided
 326       for the <code class="computeroutput"><span class="identifier">RealType</span></code> by Boost.Math.
 327     </p>
 328 <p>
 329       Testing for has_infinity is obviously important for arbitrary precision types
 330       where infinity makes much less sense than for IEEE754 floating-point.
 331     </p>
 332 <p>
 333       So far we have not set <code class="computeroutput"><span class="identifier">support</span><span class="special">()</span></code> function (only range) on the grounds that
 334       the PDF is uninteresting/zero for infinities.
 335     </p>
 336 <p>
 337       Users who require special handling of infinity (or other specific value) can,
 338       of course, always intercept this before calling a distribution or function
 339       and return their own choice of value, or other behavior. This will often be
 340       simpler than trying to handle the aftermath of the error policy.
 341     </p>
 342 <p>
 343       Overflow, underflow, denorm can be handled using <a class="link" href="pol_ref/error_handling_policies.html" title="Error Handling Policies">error
 344       handling policies</a>.
 345     </p>
 346 <p>
 347       We have also tried to catch boundary cases where the mathematical specification
 348       would result in divide by zero or overflow and signalling these similarly.
 349       What happens at (and near), poles can be controlled through <a class="link" href="pol_ref/error_handling_policies.html" title="Error Handling Policies">error
 350       handling policies</a>.
 351     </p>
 352 <h5>
 353 <a name="math_toolkit.sf_implementation.h7"></a>
 354       <span class="phrase"><a name="math_toolkit.sf_implementation.scale_shape_and_location"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.scale_shape_and_location">Scale, Shape
 355       and Location</a>
 356     </h5>
 357 <p>
 358       We considered adding location and scale to the list of functions, for example:
 359     </p>
 360 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
 361 <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">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">)</span>
 362 <span class="special">{</span>
 363   <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>
 364   <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>
 365   <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>
 366   <span class="identifier">RealType</span> <span class="identifier">result</span><span class="special">;</span>  <span class="comment">// of checks.</span>
 367   <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">&amp;</span><span class="identifier">result</span><span class="special">))</span>
 368   <span class="special">{</span>
 369     <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span>
 370   <span class="special">}</span>
 371   <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>
 372 <span class="special">}</span>
 373 </pre>
 374 <p>
 375       but found that these concepts are not defined (or their definition too contentious)
 376       for too many distributions to be generally applicable. Because they are non-member
 377       functions, they can be added if required.
 378     </p>
 379 <h5>
 380 <a name="math_toolkit.sf_implementation.h8"></a>
 381       <span class="phrase"><a name="math_toolkit.sf_implementation.notes_on_implementation_of_speci"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.notes_on_implementation_of_speci">Notes
 382       on Implementation of Specific Functions &amp; Distributions</a>
 383     </h5>
 384 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 385           Default parameters for the Triangular Distribution. We are uncertain about
 386           the best default parameters. Some sources suggest that the Standard Triangular
 387           Distribution has lower = 0, mode = half and upper = 1. However as a approximation
 388           for the normal distribution, the most common usage, lower = -1, mode =
 389           0 and upper = 1 would be more suitable.
 390         </li></ul></div>
 391 <h5>
 392 <a name="math_toolkit.sf_implementation.h9"></a>
 393       <span class="phrase"><a name="math_toolkit.sf_implementation.rational_approximations_used"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.rational_approximations_used">Rational
 394       Approximations Used</a>
 395     </h5>
 396 <p>
 397       Some of the special functions in this library are implemented via rational
 398       approximations. These are either taken from the literature, or devised by John
 399       Maddock using <a class="link" href="internals/minimax.html" title="Minimax Approximations and the Remez Algorithm">our Remez code</a>.
 400     </p>
 401 <p>
 402       Rational rather than Polynomial approximations are used to ensure accuracy:
 403       polynomial approximations are often wonderful up to a certain level of accuracy,
 404       but then quite often fail to provide much greater accuracy no matter how many
 405       more terms are added.
 406     </p>
 407 <p>
 408       Our own approximations were devised either for added accuracy (to support 128-bit
 409       long doubles for example), or because literature methods were unavailable or
 410       under non-BSL compatible license. Our Remez code is known to produce good agreement
 411       with literature results in fairly simple "toy" cases. All approximations
 412       were checked for convergence and to ensure that they were not ill-conditioned
 413       (the coefficients can give a theoretically good solution, but the resulting
 414       rational function may be un-computable at fixed precision).
 415     </p>
 416 <p>
 417       Recomputing using different Remez implementations may well produce differing
 418       coefficients: the problem is well known to be ill conditioned in general, and
 419       our Remez implementation often found a broad and ill-defined minima for many
 420       of these approximations (of course for simple "toy" examples like
 421       approximating <code class="computeroutput"><span class="identifier">exp</span></code> the minima
 422       is well defined, and the coefficients should agree no matter whose Remez implementation
 423       is used). This should not in general effect the validity of the approximations:
 424       there's good literature supporting the idea that coefficients can be "in
 425       error" without necessarily adversely effecting the result. Note that "in
 426       error" has a special meaning in this context, see <a href="http://front.math.ucdavis.edu/0101.5042" target="_top">"Approximate
 427       construction of rational approximations and the effect of error autocorrection.",
 428       Grigori Litvinov, eprint arXiv:math/0101042</a>. Therefore the coefficients
 429       still need to be accurately calculated, even if they can be in error compared
 430       to the "true" minimax solution.
 431     </p>
 432 <h5>
 433 <a name="math_toolkit.sf_implementation.h10"></a>
 434       <span class="phrase"><a name="math_toolkit.sf_implementation.representation_of_mathematical_c"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.representation_of_mathematical_c">Representation
 435       of Mathematical Constants</a>
 436     </h5>
 437 <p>
 438       A macro BOOST_DEFINE_MATH_CONSTANT in constants.hpp is used to provide high
 439       accuracy constants to mathematical functions and distributions, since it is
 440       important to provide values uniformly for both built-in float, double and long
 441       double types, and for User Defined types in <a href="../../../../../libs/multiprecision/doc/html/index.html" target="_top">Boost.Multiprecision</a>
 442       like <a href="../../../../../libs/multiprecision/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html" target="_top">cpp_dec_float</a>.
 443       and others like NTL::quad_float and NTL::RR.
 444     </p>
 445 <p>
 446       To permit calculations in this Math ToolKit and its tests, (and elsewhere)
 447       at about 100 decimal digits with NTL::RR type, it is obviously necessary to
 448       define constants to this accuracy.
 449     </p>
 450 <p>
 451       However, some compilers do not accept decimal digits strings as long as this.
 452       So the constant is split into two parts, with the 1st containing at least long
 453       double precision, and the 2nd zero if not needed or known. The 3rd part permits
 454       an exponent to be provided if necessary (use zero if none) - the other two
 455       parameters may only contain decimal digits (and sign and decimal point), and
 456       may NOT include an exponent like 1.234E99 (nor a trailing F or L). The second
 457       digit string is only used if T is a User-Defined Type, when the constant is
 458       converted to a long string literal and lexical_casted to type T. (This is necessary
 459       because you can't use a numeric constant since even a long double might not
 460       have enough digits).
 461     </p>
 462 <p>
 463       For example, pi is defined:
 464     </p>
 465 <pre class="programlisting"><span class="identifier">BOOST_DEFINE_MATH_CONSTANT</span><span class="special">(</span><span class="identifier">pi</span><span class="special">,</span>
 466   <span class="number">3.141592653589793238462643383279502884197169399375105820974944</span><span class="special">,</span>
 467   <span class="number">5923078164062862089986280348253421170679821480865132823066470938446095505</span><span class="special">,</span>
 468   <span class="number">0</span><span class="special">)</span>
 469 </pre>
 470 <p>
 471       And used thus:
 472     </p>
 473 <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>
 474
 475 <span class="keyword">double</span> <span class="identifier">diameter</span> <span class="special">=</span> <span class="number">1.</span><span class="special">;</span>
 476 <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">&lt;</span><span class="keyword">double</span><span class="special">&gt;();</span>
 477
 478 <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">&lt;</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">&gt;()</span>
 479 </pre>
 480 <p>
 481       Note that it is necessary (if inconvenient) to specify the type explicitly.
 482     </p>
 483 <p>
 484       So you cannot write
 485     </p>
 486 <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">&lt;&gt;();</span>  <span class="comment">// could not deduce template argument for 'T'</span>
 487 </pre>
 488 <p>
 489       Neither can you write:
 490     </p>
 491 <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>
 492 <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>
 493 </pre>
 494 <h5>
 495 <a name="math_toolkit.sf_implementation.h11"></a>
 496       <span class="phrase"><a name="math_toolkit.sf_implementation.thread_safety"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.thread_safety">Thread
 497       safety</a>
 498     </h5>
 499 <p>
 500       Reporting of error by setting <code class="computeroutput"><span class="identifier">errno</span></code>
 501       should be thread-safe already (otherwise none of the std lib math functions
 502       would be thread safe?). If you turn on reporting of errors via exceptions,
 503       <code class="computeroutput"><span class="identifier">errno</span></code> gets left unused anyway.
 504     </p>
 505 <p>
 506       For normal C++ usage, the Boost.Math <code class="computeroutput"><span class="keyword">static</span>
 507       <span class="keyword">const</span></code> constants are now thread-safe
 508       so for built-in real-number types: <code class="computeroutput"><span class="keyword">float</span></code>,
 509       <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
 510       <span class="keyword">double</span></code> are all thread safe.
 511     </p>
 512 <p>
 513       For User_defined types, for example, <a href="../../../../../libs/multiprecision/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html" target="_top">cpp_dec_float</a>,
 514       the Boost.Math should also be thread-safe, (thought we are unsure how to rigorously
 515       prove this).
 516     </p>
 517 <p>
 518       (Thread safety has received attention in the C++11 Standard revision, so hopefully
 519       all compilers will do the right thing here at some point.)
 520     </p>
 521 <h5>
 522 <a name="math_toolkit.sf_implementation.h12"></a>
 523       <span class="phrase"><a name="math_toolkit.sf_implementation.sources_of_test_data"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.sources_of_test_data">Sources
 524       of Test Data</a>
 525     </h5>
 526 <p>
 527       We found a large number of sources of test data. We have assumed that these
 528       are <span class="emphasis"><em>"known good"</em></span> if they agree with the results
 529       from our test and only consulted other sources for their <span class="emphasis"><em>'vote'</em></span>
 530       in the case of serious disagreement. The accuracy, actual and claimed, vary
 531       very widely. Only <a href="http://functions.wolfram.com/" target="_top">Wolfram Mathematica
 532       functions</a> provided a higher accuracy than C++ double (64-bit floating-point)
 533       and was regarded as the most-trusted source by far. The <a href="http://www.r-project.org/" target="_top">The
 534       R Project for Statistical Computing</a> provided the widest range of distributions,
 535       but the usual Intel X86 distribution uses 64-but doubles, so our use was limited
 536       to the 15 to 17 decimal digit accuracy.
 537     </p>
 538 <p>
 539       A useful index of sources is: <a href="http://www.sal.hut.fi/Teaching/Resources/ProbStat/table.html" target="_top">Web-oriented
 540       Teaching Resources in Probability and Statistics</a>
 541     </p>
 542 <p>
 543       <a href="http://espse.ed.psu.edu/edpsych/faculty/rhale/hale/507Mat/statlets/free/pdist.htm" target="_top">Statlet</a>:
 544       Is a Javascript application that calculates and plots probability distributions,
 545       and provides the most complete range of distributions:
 546     </p>
 547 <div class="blockquote"><blockquote class="blockquote"><p>
 548         Bernoulli, Binomial, discrete uniform, geometric, hypergeometric, negative
 549         binomial, Poisson, beta, Cauchy-Lorentz, chi-sequared, Erlang, exponential,
 550         extreme value, Fisher, gamma, Laplace, logistic, lognormal, normal, Parteo,
 551         Student's t, triangular, uniform, and Weibull.
 552       </p></blockquote></div>
 553 <p>
 554       It calculates pdf, cdf, survivor, log survivor, hazard, tail areas, &amp; critical
 555       values for 5 tail values.
 556     </p>
 557 <p>
 558       It is also the only independent source found for the Weibull distribution;
 559       unfortunately it appears to suffer from very poor accuracy in areas where the
 560       underlying special function is known to be difficult to implement.
 561     </p>
 562 <h5>
 563 <a name="math_toolkit.sf_implementation.h13"></a>
 564       <span class="phrase"><a name="math_toolkit.sf_implementation.testing_for_invalid_parameters_t"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.testing_for_invalid_parameters_t">Testing
 565       for Invalid Parameters to Functions and Constructors</a>
 566     </h5>
 567 <p>
 568       After finding that some 'bad' parameters (like NaN) were not throwing a <code class="computeroutput"><span class="identifier">domain_error</span></code> exception as they should, a
 569       function
 570     </p>
 571 <p>
 572       <code class="computeroutput"><span class="identifier">check_out_of_range</span></code> (in <code class="computeroutput"><span class="identifier">test_out_of_range</span><span class="special">.</span><span class="identifier">hpp</span></code>) was devised by JM to check (using Boost.Test's
 573       BOOST_CHECK_THROW macro) that bad parameters passed to constructors and functions
 574       throw <code class="computeroutput"><span class="identifier">domain_error</span></code> exceptions.
 575     </p>
 576 <p>
 577       Usage is <code class="computeroutput"><span class="identifier">check_out_of_range</span><span class="special">&lt;</span> <span class="identifier">DistributionType</span>
 578       <span class="special">&gt;(</span><span class="identifier">list</span><span class="special">-</span><span class="identifier">of</span><span class="special">-</span><span class="identifier">params</span><span class="special">);</span></code>
 579       Where list-of-params is a list of <span class="bold"><strong>valid</strong></span> parameters
 580       from which the distribution can be constructed - ie the same number of args
 581       are passed to the function, as are passed to the distribution constructor.
 582     </p>
 583 <p>
 584       The values of the parameters are not important, but must be <span class="bold"><strong>valid</strong></span>
 585       to pass the constructor checks; the default values are suitable, but must be
 586       explicitly provided, for example:
 587     </p>
 588 <pre class="programlisting"><span class="identifier">check_out_of_range</span><span class="special">&lt;</span><span class="identifier">extreme_value_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;</span> <span class="special">&gt;(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
 589 </pre>
 590 <p>
 591       Checks made are:
 592     </p>
 593 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 594 <li class="listitem">
 595           Infinity or NaN (if available) passed in place of each of the valid params.
 596         </li>
 597 <li class="listitem">
 598           Infinity or NaN (if available) as a random variable.
 599         </li>
 600 <li class="listitem">
 601           Out-of-range random variable passed to pdf and cdf (ie outside of "range(DistributionType)").
 602         </li>
 603 <li class="listitem">
 604           Out-of-range probability passed to quantile function and complement.
 605         </li>
 606 </ul></div>
 607 <p>
 608       but does <span class="bold"><strong>not</strong></span> check finite but out-of-range
 609       parameters to the constructor because these are specific to each distribution,
 610       for example:
 611     </p>
 612 <pre class="programlisting"><span class="identifier">BOOST_CHECK_THROW</span><span class="special">(</span><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">pareto_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">),</span> <span class="number">0</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">);</span>
 613 <span class="identifier">BOOST_CHECK_THROW</span><span class="special">(</span><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">pareto_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="number">1</span><span class="special">,</span> <span class="number">0</span><span class="special">),</span> <span class="number">0</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">);</span>
 614 </pre>
 615 <p>
 616       checks <code class="computeroutput"><span class="identifier">scale</span></code> and <code class="computeroutput"><span class="identifier">shape</span></code> parameters are both &gt; 0 by checking
 617       that <code class="computeroutput"><span class="identifier">domain_error</span></code> exception
 618       is thrown if either are == 0.
 619     </p>
 620 <p>
 621       (Use of <code class="computeroutput"><span class="identifier">check_out_of_range</span></code>
 622       function may mean that some previous tests are now redundant).
 623     </p>
 624 <p>
 625       It was also noted that if more than one parameter is bad, then only the first
 626       detected will be reported by the error message.
 627     </p>
 628 <h5>
 629 <a name="math_toolkit.sf_implementation.h14"></a>
 630       <span class="phrase"><a name="math_toolkit.sf_implementation.creating_and_managing_the_equati"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.creating_and_managing_the_equati">Creating
 631       and Managing the Equations</a>
 632     </h5>
 633 <p>
 634       Equations that fit on a single line can most easily be produced by inline Quickbook
 635       code using templates for Unicode Greek and Unicode Math symbols. All Greek
 636       letter and small set of Math symbols is available at /boost-path/libs/math/doc/sf_and_dist/html4_symbols.qbk
 637     </p>
 638 <p>
 639       Where equations need to use more than one line, real Math editors were used.
 640     </p>
 641 <p>
 642       The primary source for the equations is now <a href="http://www.w3.org/Math/" target="_top">MathML</a>:
 643       see the *.mml files in libs/math/doc/sf_and_dist/equations/.
 644     </p>
 645 <p>
 646       These are most easily edited by a GUI editor such as <a href="http://mathcast.sourceforge.net/home.html" target="_top">Mathcast</a>,
 647       please note that the equation editor supplied with Open Office currently mangles
 648       these files and should not currently be used.
 649     </p>
 650 <p>
 651       Conversion to SVG was achieved using <a href="https://sourceforge.net/projects/svgmath/" target="_top">SVGMath</a>
 652       and a command line such as:
 653     </p>
 654 <pre class="programlisting">$for file in *.mml; do
 655 &gt;/cygdrive/c/Python25/python.exe 'C:\download\open\SVGMath-0.3.1\math2svg.py' \
 656 &gt;&gt;$file &gt; $(basename $file .mml).svg
 657 &gt;done
 658 </pre>
 659 <p>
 660       See also the section on "Using Python to run Inkscape" and "Using
 661       inkscape to convert scalable vector SVG files to Portable Network graphic PNG".
 662     </p>
 663 <p>
 664       Note that SVGMath requires that the mml files are <span class="bold"><strong>not</strong></span>
 665       wrapped in an XHTML XML wrapper - this is added by Mathcast by default - one
 666       workaround is to copy an existing mml file and then edit it with Mathcast:
 667       the existing format should then be preserved. This is a bug in the XML parser
 668       used by SVGMath which the author is aware of.
 669     </p>
 670 <p>
 671       If necessary the XHTML wrapper can be removed with:
 672     </p>
 673 <pre class="programlisting">cat filename | tr -d "\r\n" | sed -e 's/.*\(&lt;math[^&gt;]*&gt;.*&lt;/math&gt;\).*/\1/' &gt; newfile</pre>
 674 <p>
 675       Setting up fonts for SVGMath is currently rather tricky, on a Windows XP system
 676       JM's font setup is the same as the sample config file provided with SVGMath
 677       but with:
 678     </p>
 679 <pre class="programlisting">    &lt;!-- Double-struck --&gt;
 680     &lt;mathvariant name="double-struck" family="Mathematica7, Lucida Sans Unicode"/&gt;
 681 </pre>
 682 <p>
 683       changed to:
 684     </p>
 685 <pre class="programlisting">    &lt;!-- Double-struck --&gt;
 686     &lt;mathvariant name="double-struck" family="Lucida Sans Unicode"/&gt;
 687 </pre>
 688 <p>
 689       Note that unlike the sample config file supplied with SVGMath, this does not
 690       make use of the <a href="http://support.wolfram.com/technotes/fonts/windows/latestfonts.html" target="_top">Mathematica
 691       7 font</a> as this lacks sufficient Unicode information for it to be used
 692       with either SVGMath or XEP "as is".
 693     </p>
 694 <p>
 695       Also note that the SVG files in the repository are almost certainly Windows-specific
 696       since they reference various Windows Fonts.
 697     </p>
 698 <p>
 699       PNG files can be created from the SVGs using <a href="http://xmlgraphics.apache.org/batik/tools/rasterizer.html" target="_top">Batik</a>
 700       and a command such as:
 701     </p>
 702 <pre class="programlisting">java -jar 'C:\download\open\batik-1.7\batik-rasterizer.jar' -dpi 120 *.svg</pre>
 703 <p>
 704       Or using Inkscape (File, Export bitmap, Drawing tab, bitmap size (default size,
 705       100 dpi), Filename (default). png)
 706     </p>
 707 <p>
 708       or Using Cygwin, a command such as:
 709     </p>
 710 <pre class="programlisting">for file in *.svg; do
 711   /cygdrive/c/progra~1/Inkscape/inkscape -d 120 -e $(cygpath -a -w $(basename $file .svg).png) $(cygpath -a -w $file);
 712 done</pre>
 713 <p>
 714       Using BASH
 715     </p>
 716 <pre class="programlisting"># Convert single SVG to PNG file.
 717 # /c/progra~1/Inkscape/inkscape -d 120 -e a.png a.svg
 718 </pre>
 719 <p>
 720       or to convert All files in folder SVG to PNG.
 721     </p>
 722 <pre class="programlisting">for file in *.svg; do
 723 /c/progra~1/Inkscape/inkscape -d 120 -e $(basename $file .svg).png $file
 724 done
 725 </pre>
 726 <p>
 727       Currently Inkscape seems to generate the better looking PNGs.
 728     </p>
 729 <p>
 730       The PDF is generated into \pdf\math.pdf using a command from a shell or command
 731       window with current directory \math_toolkit\libs\math\doc\sf_and_dist, typically:
 732     </p>
 733 <pre class="programlisting">bjam -a pdf &gt;math_pdf.log</pre>
 734 <p>
 735       Note that XEP will have to be configured to <span class="bold"><strong>use and embed</strong></span>
 736       whatever fonts are used by the SVG equations (almost certainly editing the
 737       sample xep.xml provided by the XEP installation). If you fail to do this you
 738       will get XEP warnings in the log file like
 739     </p>
 740 <pre class="programlisting">[warning]could not find any font family matching "Times New Roman"; replaced by Helvetica</pre>
 741 <p>
 742       (html is the default so it is generated at libs\math\doc\html\index.html using
 743       command line &gt;bjam -a &gt; math_toolkit.docs.log).
 744     </p>
 745 <pre class="programlisting"><span class="special">&lt;!--</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">--&gt;</span>
 746 </pre>
 747 <p>
 748       is provided in the xep.xml downloaded, but the Windows TrueType fonts are commented
 749       out.
 750     </p>
 751 <p>
 752       JM's XEP config file \xep\xep.xml has the following font configuration section
 753       added:
 754     </p>
 755 <pre class="programlisting">    &lt;font-group xml:base="file:/C:/Windows/Fonts/" label="Windows TrueType" embed="true" subset="true"&gt;
 756       &lt;font-family name="Arial"&gt;
 757         &lt;font&gt;&lt;font-data ttf="arial.ttf"/&gt;&lt;/font&gt;
 758         &lt;font style="oblique"&gt;&lt;font-data ttf="ariali.ttf"/&gt;&lt;/font&gt;
 759         &lt;font weight="bold"&gt;&lt;font-data ttf="arialbd.ttf"/&gt;&lt;/font&gt;
 760         &lt;font weight="bold" style="oblique"&gt;&lt;font-data ttf="arialbi.ttf"/&gt;&lt;/font&gt;
 761       &lt;/font-family&gt;
 762
 763       &lt;font-family name="Times New Roman" ligatures="&amp;#xFB01; &amp;#xFB02;"&gt;
 764         &lt;font&gt;&lt;font-data ttf="times.ttf"/&gt;&lt;/font&gt;
 765         &lt;font style="italic"&gt;&lt;font-data ttf="timesi.ttf"/&gt;&lt;/font&gt;
 766         &lt;font weight="bold"&gt;&lt;font-data ttf="timesbd.ttf"/&gt;&lt;/font&gt;
 767         &lt;font weight="bold" style="italic"&gt;&lt;font-data ttf="timesbi.ttf"/&gt;&lt;/font&gt;
 768       &lt;/font-family&gt;
 769
 770       &lt;font-family name="Courier New"&gt;
 771         &lt;font&gt;&lt;font-data ttf="cour.ttf"/&gt;&lt;/font&gt;
 772         &lt;font style="oblique"&gt;&lt;font-data ttf="couri.ttf"/&gt;&lt;/font&gt;
 773         &lt;font weight="bold"&gt;&lt;font-data ttf="courbd.ttf"/&gt;&lt;/font&gt;
 774         &lt;font weight="bold" style="oblique"&gt;&lt;font-data ttf="courbi.ttf"/&gt;&lt;/font&gt;
 775       &lt;/font-family&gt;
 776
 777       &lt;font-family name="Tahoma" embed="true"&gt;
 778         &lt;font&gt;&lt;font-data ttf="tahoma.ttf"/&gt;&lt;/font&gt;
 779         &lt;font weight="bold"&gt;&lt;font-data ttf="tahomabd.ttf"/&gt;&lt;/font&gt;
 780       &lt;/font-family&gt;
 781
 782       &lt;font-family name="Verdana" embed="true"&gt;
 783         &lt;font&gt;&lt;font-data ttf="verdana.ttf"/&gt;&lt;/font&gt;
 784         &lt;font style="oblique"&gt;&lt;font-data ttf="verdanai.ttf"/&gt;&lt;/font&gt;
 785         &lt;font weight="bold"&gt;&lt;font-data ttf="verdanab.ttf"/&gt;&lt;/font&gt;
 786         &lt;font weight="bold" style="oblique"&gt;&lt;font-data ttf="verdanaz.ttf"/&gt;&lt;/font&gt;
 787       &lt;/font-family&gt;
 788
 789       &lt;font-family name="Palatino" embed="true" ligatures="&amp;#xFB00; &amp;#xFB01; &amp;#xFB02; &amp;#xFB03; &amp;#xFB04;"&gt;
 790         &lt;font&gt;&lt;font-data ttf="pala.ttf"/&gt;&lt;/font&gt;
 791         &lt;font style="italic"&gt;&lt;font-data ttf="palai.ttf"/&gt;&lt;/font&gt;
 792         &lt;font weight="bold"&gt;&lt;font-data ttf="palab.ttf"/&gt;&lt;/font&gt;
 793         &lt;font weight="bold" style="italic"&gt;&lt;font-data ttf="palabi.ttf"/&gt;&lt;/font&gt;
 794       &lt;/font-family&gt;
 795
 796     &lt;font-family name="Lucida Sans Unicode"&gt;
 797          &lt;!-- &lt;font&gt;&lt;font-data ttf="lsansuni.ttf"&gt;&lt;<span class="emphasis"><em>font&gt; --&gt;
 798          &lt;!-- actually called l_10646.ttf on Windows 2000 and Vista Sp1 --&gt;
 799          &lt;font&gt;&lt;font-data ttf="l_10646.ttf"</em></span>&gt;&lt;/font&gt;
 800     &lt;/font-family&gt;
 801 </pre>
 802 <p>
 803       PAB had to alter his because the Lucida Sans Unicode font had a different name.
 804       Other changes are very likely to be required if you are not using Windows.
 805     </p>
 806 <p>
 807       XZ authored his equations using the venerable Latex, JM converted these to
 808       MathML using <a href="http://gentoo-wiki.com/HOWTO_Convert_LaTeX_to_HTML_with_MathML" target="_top">mxlatex</a>.
 809       This process is currently unreliable and required some manual intervention:
 810       consequently Latex source is not considered a viable route for the automatic
 811       production of SVG versions of equations.
 812     </p>
 813 <p>
 814       Equations are embedded in the quickbook source using the <span class="emphasis"><em>equation</em></span>
 815       template defined in math.qbk. This outputs Docbook XML that looks like:
 816     </p>
 817 <pre class="programlisting">&lt;inlinemediaobject&gt;
 818 &lt;imageobject role="html"&gt;
 819 &lt;imagedata fileref="../equations/myfile.png"&gt;&lt;/imagedata&gt;
 820 &lt;/imageobject&gt;
 821 &lt;imageobject role="print"&gt;
 822 &lt;imagedata fileref="../equations/myfile.svg"&gt;&lt;/imagedata&gt;
 823 &lt;/imageobject&gt;
 824 &lt;/inlinemediaobject&gt;
 825 </pre>
 826 <p>
 827       MathML is not currently present in the Docbook output, or in the generated
 828       HTML: this needs further investigation.
 829     </p>
 830 <h5>
 831 <a name="math_toolkit.sf_implementation.h15"></a>
 832       <span class="phrase"><a name="math_toolkit.sf_implementation.producing_graphs"></a></span><a class="link" href="sf_implementation.html#math_toolkit.sf_implementation.producing_graphs">Producing
 833       Graphs</a>
 834     </h5>
 835 <p>
 836       Graphs were produced in SVG format and then converted to PNG's using the same
 837       process as the equations.
 838     </p>
 839 <p>
 840       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
 841       the SVG's directly using the <a href="http://code.google.com/soc/2007/boost/about.html" target="_top">Google
 842       Summer of Code 2007</a> project of Jacob Voytko (whose work so far, considerably
 843       enhanced and now reasonably mature and usable, by Paul A. Bristow, is at .\boost-sandbox\SOC\2007\visualization).
 844     </p>
 845 </div>
 846 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 847 <td align="left"></td>
 848 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 849       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 850       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 851       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 852       Daryle Walker and Xiaogang Zhang<p>
 853         Distributed under the Boost Software License, Version 1.0. (See accompanying
 854         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>)
 855       </p>
 856 </div></td>
 857 </tr></table>
 858 <hr>
 859 <div class="spirit-nav">
 860 <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="special_tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 861 </div>
 862 </body>
 863 </html>