mirror of
https://github.com/saitohirga/WSJT-X.git
synced 2025-10-27 11:00:32 -04:00
863 lines
54 KiB
HTML
863 lines
54 KiB
HTML
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||
|
|
<title>Additional Implementation Notes</title>
|
||
|
|
<link rel="stylesheet" href="../math.css" type="text/css">
|
||
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
|
|
<link rel="home" href="../index.html" title="Math Toolkit 2.5.1">
|
||
|
|
<link rel="up" href="../backgrounders.html" title="Chapter 17. Backgrounders">
|
||
|
|
<link rel="prev" href="../backgrounders.html" title="Chapter 17. Backgrounders">
|
||
|
|
<link rel="next" href="special_tut.html" title="Tutorial: How to Write a New Special Function">
|
||
|
|
</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="special_tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||
|
|
</div>
|
||
|
|
<div class="section">
|
||
|
|
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
|
|
<a name="math_toolkit.sf_implementation"></a><a class="link" href="sf_implementation.html" title="Additional Implementation Notes">Additional Implementation
|
||
|
|
Notes</a>
|
||
|
|
</h2></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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h0"></a>
|
||
|
|
<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
|
||
|
|
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 <code class="computeroutput"><span class="keyword">float</span></code>
|
||
|
|
or <code class="computeroutput"><span class="keyword">double</span></code>, 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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h1"></a>
|
||
|
|
<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
|
||
|
|
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 <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.2345L</span><span class="special">)</span></code> 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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h2"></a>
|
||
|
|
<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
|
||
|
|
of Tests</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
The tolerances need to be set to the maximum of:
|
||
|
|
</p>
|
||
|
|
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
|
|
<li class="listitem">
|
||
|
|
Some epsilon value.
|
||
|
|
</li>
|
||
|
|
<li class="listitem">
|
||
|
|
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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h3"></a>
|
||
|
|
<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
|
||
|
|
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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
|
|
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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
|
|
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="error_handling.html" title="Error Handling">See also domain_error</a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a class="link" href="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="error_handling.html" title="Error Handling">error handling</a> for a
|
||
|
|
detailed explanation of the mechanism, and <a class="link" href="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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h4"></a>
|
||
|
|
<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
|
||
|
|
of Functions that are Not Mathematically defined</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
Functions that are not mathematically defined, like the Cauchy mean, fail to
|
||
|
|
compile by default. A <a class="link" href="pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">policy</a>
|
||
|
|
allows control of this.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If the policy is to permit undefined functions, then calling them throws a
|
||
|
|
domain error, by default. But the error policy can be set to not throw, and
|
||
|
|
to return NaN instead. For example,
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<code class="computeroutput"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span>
|
||
|
|
<span class="identifier">ignore_error</span></code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
appears before the first Boost include, then if the un-implemented function
|
||
|
|
is called, mean(cauchy<>()) will return std::numeric_limits<T>::quiet_NaN().
|
||
|
|
</p>
|
||
|
|
<div class="warning"><table border="0" summary="Warning">
|
||
|
|
<tr>
|
||
|
|
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
|
||
|
|
<th align="left">Warning</th>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top"><p>
|
||
|
|
If <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">has_quiet_NaN</span></code> is false (for example, if
|
||
|
|
T is a User-defined type without NaN support), then an exception will always
|
||
|
|
be thrown when a domain error occurs. Catching exceptions is therefore strongly
|
||
|
|
recommended.
|
||
|
|
</p></td></tr>
|
||
|
|
</table></div>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h5"></a>
|
||
|
|
<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
|
||
|
|
distributions</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
There are many distributions for which we have been unable to find an analytic
|
||
|
|
formula, and this has deterred us from implementing <a href="http://en.wikipedia.org/wiki/Median" target="_top">median
|
||
|
|
functions</a>, the mid-point in a list of values.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
However a useful numerical approximation for distribution <code class="computeroutput"><span class="identifier">dist</span></code>
|
||
|
|
is available as usual as an accessor non-member function median using <code class="computeroutput"><span class="identifier">median</span><span class="special">(</span><span class="identifier">dist</span><span class="special">)</span></code>, that may be evaluated (in the absence of
|
||
|
|
an analytic formula) by calling
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">0.5</span><span class="special">)</span></code> (this is the <span class="emphasis"><em>mathematical</em></span>
|
||
|
|
definition of course).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<a href="http://www.amstat.org/publications/jse/v13n2/vonhippel.html" target="_top">Mean,
|
||
|
|
Median, and Skew, Paul T von Hippel</a>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<a href="http://documents.wolfram.co.jp/teachersedition/MathematicaBook/24.5.html" target="_top">Descriptive
|
||
|
|
Statistics,</a>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<a href="http://documents.wolfram.co.jp/v5/Add-onsLinks/StandardPackages/Statistics/DescriptiveStatistics.html" target="_top">and
|
||
|
|
</a>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<a href="http://documents.wolfram.com/v5/TheMathematicaBook/AdvancedMathematicsInMathematica/NumericalOperationsOnData/3.8.1.html" target="_top">Mathematica
|
||
|
|
Basic Statistics.</a> give more detail, in particular for discrete distributions.
|
||
|
|
</p>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h6"></a>
|
||
|
|
<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
|
||
|
|
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="error_handling.html#math_toolkit.error_handling.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 <code class="computeroutput"><span class="identifier">RealType</span></code> on that implementation,
|
||
|
|
and it is supported and tested by the distribution.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The range for these distributions is set to infinity if supported by the platform,
|
||
|
|
(by testing <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">has_infinity</span></code>) else the maximum value provided
|
||
|
|
for the <code class="computeroutput"><span class="identifier">RealType</span></code> by Boost.Math.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Testing for has_infinity is obviously important for arbitrary precision types
|
||
|
|
where infinity makes much less sense than for IEEE754 floating-point.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
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
|
||
|
|
the PDF is uninteresting/zero for infinities.
|
||
|
|
</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="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="pol_ref/error_handling_policies.html" title="Error Handling Policies">error
|
||
|
|
handling policies</a>.
|
||
|
|
</p>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h7"></a>
|
||
|
|
<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
|
||
|
|
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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h8"></a>
|
||
|
|
<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
|
||
|
|
on Implementation of Specific Functions & Distributions</a>
|
||
|
|
</h5>
|
||
|
|
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
|
|
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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h9"></a>
|
||
|
|
<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
|
||
|
|
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="internals/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 coefficients 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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h10"></a>
|
||
|
|
<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
|
||
|
|
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 in <a href="../../../../../libs/multiprecision/doc/html/index.html" target="_top">Boost.Multiprecision</a>
|
||
|
|
like <a href="../../../../../libs/multiprecision/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html" target="_top">cpp_dec_float</a>.
|
||
|
|
and others 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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h11"></a>
|
||
|
|
<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
|
||
|
|
safety</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
Reporting of error by setting <code class="computeroutput"><span class="identifier">errno</span></code>
|
||
|
|
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,
|
||
|
|
<code class="computeroutput"><span class="identifier">errno</span></code> gets left unused anyway.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
For normal C++ usage, the Boost.Math <code class="computeroutput"><span class="keyword">static</span>
|
||
|
|
<span class="keyword">const</span></code> constants are now thread-safe
|
||
|
|
so for built-in real-number types: <code class="computeroutput"><span class="keyword">float</span></code>,
|
||
|
|
<code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
|
||
|
|
<span class="keyword">double</span></code> are all thread safe.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
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>,
|
||
|
|
the Boost.Math should also be thread-safe, (thought we are unsure how to rigorously
|
||
|
|
prove this).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(Thread safety has received attention in the C++11 Standard revision, so hopefully
|
||
|
|
all compilers will do the right thing here at some point.)
|
||
|
|
</p>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h12"></a>
|
||
|
|
<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
|
||
|
|
of Test Data</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
We found a large number of sources of test data. We have assumed that these
|
||
|
|
are <span class="emphasis"><em>"known good"</em></span> if they agree with the results
|
||
|
|
from our test and only consulted other sources for their <span class="emphasis"><em>'vote'</em></span>
|
||
|
|
in the case of serious disagreement. The accuracy, actual and claimed, vary
|
||
|
|
very widely. Only <a href="http://functions.wolfram.com/" target="_top">Wolfram Mathematica
|
||
|
|
functions</a> provided a higher accuracy than C++ double (64-bit floating-point)
|
||
|
|
and was regarded as the most-trusted source by far. The <a href="http://www.r-project.org/" target="_top">The
|
||
|
|
R Project for Statistical Computing</a> provided the widest range of distributions,
|
||
|
|
but the usual Intel X86 distribution uses 64-but doubles, so our use was limited
|
||
|
|
to the 15 to 17 decimal digit accuracy.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
A useful index of sources is: <a href="http://www.sal.hut.fi/Teaching/Resources/ProbStat/table.html" target="_top">Web-oriented
|
||
|
|
Teaching Resources in Probability and Statistics</a>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<a href="http://espse.ed.psu.edu/edpsych/faculty/rhale/hale/507Mat/statlets/free/pdist.htm" target="_top">Statlet</a>:
|
||
|
|
Is a Javascript application that calculates and plots probability distributions,
|
||
|
|
and provides the most complete range of distributions:
|
||
|
|
</p>
|
||
|
|
<div class="blockquote"><blockquote class="blockquote"><p>
|
||
|
|
Bernoulli, Binomial, discrete uniform, geometric, hypergeometric, negative
|
||
|
|
binomial, Poisson, beta, Cauchy-Lorentz, chi-sequared, Erlang, exponential,
|
||
|
|
extreme value, Fisher, gamma, Laplace, logistic, lognormal, normal, Parteo,
|
||
|
|
Student's t, triangular, uniform, and Weibull.
|
||
|
|
</p></blockquote></div>
|
||
|
|
<p>
|
||
|
|
It calculates pdf, cdf, survivor, log survivor, hazard, tail areas, & critical
|
||
|
|
values for 5 tail values.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
It is also the only independent source found for the Weibull distribution;
|
||
|
|
unfortunately it appears to suffer from very poor accuracy in areas where the
|
||
|
|
underlying special function is known to be difficult to implement.
|
||
|
|
</p>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h13"></a>
|
||
|
|
<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
|
||
|
|
for Invalid Parameters to Functions and Constructors</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
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
|
||
|
|
function
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<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
|
||
|
|
BOOST_CHECK_THROW macro) that bad parameters passed to constructors and functions
|
||
|
|
throw <code class="computeroutput"><span class="identifier">domain_error</span></code> exceptions.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Usage is <code class="computeroutput"><span class="identifier">check_out_of_range</span><span class="special"><</span> <span class="identifier">DistributionType</span>
|
||
|
|
<span class="special">>(</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>
|
||
|
|
Where list-of-params is a list of <span class="bold"><strong>valid</strong></span> parameters
|
||
|
|
from which the distribution can be constructed - ie the same number of args
|
||
|
|
are passed to the function, as are passed to the distribution constructor.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The values of the parameters are not important, but must be <span class="bold"><strong>valid</strong></span>
|
||
|
|
to pass the constructor checks; the default values are suitable, but must be
|
||
|
|
explicitly provided, for example:
|
||
|
|
</p>
|
||
|
|
<pre class="programlisting"><span class="identifier">check_out_of_range</span><span class="special"><</span><span class="identifier">extreme_value_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">></span> <span class="special">>(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
Checks made are:
|
||
|
|
</p>
|
||
|
|
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
|
|
<li class="listitem">
|
||
|
|
Infinity or NaN (if available) passed in place of each of the valid params.
|
||
|
|
</li>
|
||
|
|
<li class="listitem">
|
||
|
|
Infinity or NaN (if available) as a random variable.
|
||
|
|
</li>
|
||
|
|
<li class="listitem">
|
||
|
|
Out-of-range random variable passed to pdf and cdf (ie outside of "range(DistributionType)").
|
||
|
|
</li>
|
||
|
|
<li class="listitem">
|
||
|
|
Out-of-range probability passed to quantile function and complement.
|
||
|
|
</li>
|
||
|
|
</ul></div>
|
||
|
|
<p>
|
||
|
|
but does <span class="bold"><strong>not</strong></span> check finite but out-of-range
|
||
|
|
parameters to the constructor because these are specific to each distribution,
|
||
|
|
for example:
|
||
|
|
</p>
|
||
|
|
<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"><</span><span class="identifier">RealType</span><span class="special">>(</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>
|
||
|
|
<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"><</span><span class="identifier">RealType</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="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>
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
checks <code class="computeroutput"><span class="identifier">scale</span></code> and <code class="computeroutput"><span class="identifier">shape</span></code> parameters are both > 0 by checking
|
||
|
|
that <code class="computeroutput"><span class="identifier">domain_error</span></code> exception
|
||
|
|
is thrown if either are == 0.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(Use of <code class="computeroutput"><span class="identifier">check_out_of_range</span></code>
|
||
|
|
function may mean that some previous tests are now redundant).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
It was also noted that if more than one parameter is bad, then only the first
|
||
|
|
detected will be reported by the error message.
|
||
|
|
</p>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h14"></a>
|
||
|
|
<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
|
||
|
|
and Managing the Equations</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
Equations that fit on a single line can most easily be produced by inline Quickbook
|
||
|
|
code using templates for Unicode Greek and Unicode Math symbols. All Greek
|
||
|
|
letter and small set of Math symbols is available at /boost-path/libs/math/doc/sf_and_dist/html4_symbols.qbk
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Where equations need to use more than one line, real Math editors were used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The primary source for the equations is now <a href="http://www.w3.org/Math/" target="_top">MathML</a>:
|
||
|
|
see the *.mml files in libs/math/doc/sf_and_dist/equations/.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
These are most easily edited by a GUI editor such as <a href="http://mathcast.sourceforge.net/home.html" target="_top">Mathcast</a>,
|
||
|
|
please note that the equation editor supplied with Open Office currently mangles
|
||
|
|
these files and should not currently be used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Conversion to SVG was achieved using <a href="https://sourceforge.net/projects/svgmath/" target="_top">SVGMath</a>
|
||
|
|
and a command line such as:
|
||
|
|
</p>
|
||
|
|
<pre class="programlisting">$for file in *.mml; do
|
||
|
|
>/cygdrive/c/Python25/python.exe 'C:\download\open\SVGMath-0.3.1\math2svg.py' \
|
||
|
|
>>$file > $(basename $file .mml).svg
|
||
|
|
>done
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
See also the section on "Using Python to run Inkscape" and "Using
|
||
|
|
inkscape to convert scalable vector SVG files to Portable Network graphic PNG".
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Note that SVGMath requires that the mml files are <span class="bold"><strong>not</strong></span>
|
||
|
|
wrapped in an XHTML XML wrapper - this is added by Mathcast by default - one
|
||
|
|
workaround is to copy an existing mml file and then edit it with Mathcast:
|
||
|
|
the existing format should then be preserved. This is a bug in the XML parser
|
||
|
|
used by SVGMath which the author is aware of.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If necessary 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 <a href="http://support.wolfram.com/technotes/fonts/windows/latestfonts.html" target="_top">Mathematica
|
||
|
|
7 font</a> 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 SVGs 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 (File, Export bitmap, Drawing tab, bitmap size (default size,
|
||
|
|
100 dpi), Filename (default). png)
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
or Using Cygwin, 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>
|
||
|
|
Using BASH
|
||
|
|
</p>
|
||
|
|
<pre class="programlisting"># Convert single SVG to PNG file.
|
||
|
|
# /c/progra~1/Inkscape/inkscape -d 120 -e a.png a.svg
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
or to convert All files in folder SVG to PNG.
|
||
|
|
</p>
|
||
|
|
<pre class="programlisting">for file in *.svg; do
|
||
|
|
/c/progra~1/Inkscape/inkscape -d 120 -e $(basename $file .svg).png $file
|
||
|
|
done
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
Currently Inkscape seems to generate the better looking PNGs.
|
||
|
|
</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 libs\math\doc\html\index.html using
|
||
|
|
command line >bjam -a > math_toolkit.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>
|
||
|
|
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="Lucida Sans Unicode">
|
||
|
|
<!-- <font><font-data ttf="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="html">
|
||
|
|
<imagedata fileref="../equations/myfile.png"></imagedata>
|
||
|
|
</imageobject>
|
||
|
|
<imageobject role="print">
|
||
|
|
<imagedata fileref="../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>
|
||
|
|
<h5>
|
||
|
|
<a name="math_toolkit.sf_implementation.h15"></a>
|
||
|
|
<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
|
||
|
|
Graphs</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
Graphs were produced in SVG format and then converted to PNG's using the same
|
||
|
|
process as the equations.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The programs <code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">doc</span><span class="special">/</span><span class="identifier">sf_and_dist</span><span class="special">/</span><span class="identifier">graphs</span><span class="special">/</span><span class="identifier">dist_graphs</span><span class="special">.</span><span class="identifier">cpp</span></code> and <code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">doc</span><span class="special">/</span><span class="identifier">sf_and_dist</span><span class="special">/</span><span class="identifier">graphs</span><span class="special">/</span><span class="identifier">sf_graphs</span><span class="special">.</span><span class="identifier">cpp</span></code> generate
|
||
|
|
the SVG's directly using the <a href="http://code.google.com/soc/2007/boost/about.html" target="_top">Google
|
||
|
|
Summer of Code 2007</a> project of Jacob Voytko (whose work so far, considerably
|
||
|
|
enhanced and now reasonably mature and usable, by Paul A. Bristow, is at .\boost-sandbox\SOC\2007\visualization).
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||
|
|
<td align="left"></td>
|
||
|
|
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||
|
|
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||
|
|
Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan Råde, Gautam Sewani,
|
||
|
|
Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<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="special_tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|