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