<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="id1286429"></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="id1286492"></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="id1286636"></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="id1286681"></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="id1286810"></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 class="link" href="../policy/pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">A
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="id1286896"></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 median approximation for distribution <code class="computeroutput"><span class="identifier">dist</span></code>
may be available from
</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>.
</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="id1286993"></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="id1287079"></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="id1287414"></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="id1287438"></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="id1287482"></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="id1288042"></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="id1288078"></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.
</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="id1288142"></a>
<a class="link" href="implementation.html#math_toolkit.backgrounders.implementation.creating_and_managing_the_equations">Creating
and Managing the Equations</a>
</h5>
<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>
Convertion 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>
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="id1288388"></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 /libs/math/doc/sf_and_dist/graphs/dist_graphs.cpp and /libs/math/doc/sf_and_dist/graphs/sf_graphs.cpp
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 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 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>
