implementation.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

of error autocorrection.", Grigori Litvinov, eprint arXiv:math/0101042].
Therefore the coefficients still need to be accurately calculated, even if they can
be in error compared to the "true" minimax solution.

[h4 Representation of Mathematical Constants]

A macro BOOST_DEFINE_MATH_CONSTANT in constants.hpp is used
to provide high accuracy constants to mathematical functions and distributions,
since it is important to provide values uniformly for both built-in
float, double and long double types,
and for User Defined types like NTL::quad_float and NTL::RR.  
                                        
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.

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).

For example, pi is defined:

  BOOST_DEFINE_MATH_CONSTANT(pi,
    3.141592653589793238462643383279502884197169399375105820974944,
    5923078164062862089986280348253421170679821480865132823066470938446095505,
    0)                                              

And used thus:

  using namespace boost::math::constants;

  double diameter = 1.;
  double radius = diameter * pi<double>();
  
  or boost::math::constants::pi<NTL::RR>()

Note that it is necessary (if inconvenient) to specify the type explicitly.

So you cannot write

  double p = boost::math::constants::pi<>();  // could not deduce template argument for 'T'  

Neither can you write:

  double p = boost::math::constants::pi; // Context does not allow for disambiguation of overloaded function     
  double p = boost::math::constants::pi(); // Context does not allow for disambiguation of overloaded function     

[h4 Thread safety]

Reporting of error by setting errno should be thread safe already
(otherwise none of the std lib math functions would be thread safe?).
If you turn on reporting of errors via exceptions, errno gets left unused anyway.

Other than that, the code is intended to be thread safe *for built in 
real-number types* : so float, double and long double are all thread safe.

For non-built-in types - NTL::RR for example - initialisation of the various 
constants used in the implementation is potentially *not* thread safe.  
This most undesiable, but it would be a signficant challenge to fix it.
Some compilers may offer the option of having 
static-constants initialised in a thread safe manner (Commeau, and maybe 
others?), if that's the case then the problem is solved.  This is a topic of 
hot debate for the next C++ std revision, so hopefully all compilers 
will be required to do the right thing here at some point.

[h4 Sources of Test Data]

We found a large number of sources of test data.
We have assumed that these are /"known good"/
if they agree with the results from our test
and only consulted other sources for their /'vote'/
in the case of serious disagreement.
The accuracy, actual and claimed, vary very widely.
Only [@http://functions.wolfram.com/ Wolfram Mathematica functions]
provided a higher accuracy than
C++ double (64-bit floating-point) and was regarded as
the most-trusted source by far.

A useful index of sources is:
[@http://www.sal.hut.fi/Teaching/Resources/ProbStat/table.html
Web-oriented Teaching Resources in Probability and Statistics]

[@http://espse.ed.psu.edu/edpsych/faculty/rhale/hale/507Mat/statlets/free/pdist.htm Statlet]:
Is a Javascript application that calculates and plots probability distributions,
and provides the most complete range of distributions:

[: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.]

It calculates pdf, cdf, survivor, log survivor, hazard, tail areas,
& critical values for 5 tail values.

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.

[h4 Creating and Managing the Equations]

The primary source for the equations is now 
[@http://www.w3.org/Math/ MathML]: see the 
*.mml files in libs\/math\/doc\/sf_and_dist\/equations\/.

These are most easily edited by a GUI editor such as 
[@http://mathcast.sourceforge.net/home.html Mathcast],
please note that the equation editor supplied with Open Office
currently mangles these files and should not currently be used.

Convertion to SVG was achieved using 
[@http://www.grigoriev.ru/svgmath/ SVGMath] and a command line
such as:

[pre 
$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
]

Note that SVGMath requires that the mml files are *not* 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.

If neccessary the XHTML wrapper can be removed with:

[pre cat filename | tr -d "\\r\\n" \| sed -e 's\/.*\\(<math\[^>\]\*>.\*<\/math>\\).\*\/\\1\/' > newfile]

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:

[pre
    <!\-\- Double\-struck \-\->
    <mathvariant name\="double\-struck" family\="Mathematica7, Lucida Sans Unicode"\/>
]

changed to:

[pre
    <!\-\- Double\-struck \-\->
    <mathvariant name\="double\-struck" family\="Lucida Sans Unicode"\/>
]

Note that unlike the sample config file supplied with SVGMath, this does not
make use of the Mathematica 7 font as this lacks sufficient Unicode information
for it to be used with either SVGMath or XEP "as is".

Also note that the SVG files in the repository are almost certainly
Windows-specific since they reference various Windows Fonts.

PNG files can be created from the SVG's using 
[@http://xmlgraphics.apache.org/batik/tools/rasterizer.html Batik]
and a command such as:

[pre java -jar 'C:\download\open\batik-1.7\batik-rasterizer.jar' -dpi 120 *.svg]

Or using Inkscape and a command such as:

[pre 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]

Currently Inkscape seems to generate the better looking png's.

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:

[pre bjam -a pdf]

Note that XEP will have to be configured to *use and embed* 
whatever fonts are used by the SVG equations
(if necessary editing the sample xep.xml provided by the XEP installation). 

(html is generated at math_toolkit\libs\math\doc\sf_and_dist\html\index.html
using just bjam -a).

JM's XEP config file has the following font configuration section added:

[pre
    <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"\/><\/font>
    <\/font\-family>
]

PAB had to alter his because the Lucida Sans Unicode font had a different name.
Changes are very likely to be required if you are not using Windows.

XZ authored his equations using the venerable Latex, JM converted these to
MathML using [@http://gentoo-wiki.com/HOWTO_Convert_LaTeX_to_HTML_with_MathML mxlatex].
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.

Equations are embedded in the quickbook source using the /equation/
template defined in math.qbk.  This outputs Docbook XML that looks like:

[pre
<inlinemediaobject>
<imageobject role="html">
<imagedata fileref="../equations/myfile.png"></imagedata>
</imageobject>
<imageobject role="print">
<imagedata fileref="../equations/myfile.svg"></imagedata>
</imageobject>
</inlinemediaobject>
]

MathML is not currently present in the Docbook output, or in the 
generated HTML: this needs further investigation.

[h4 Producing Graphs]

Graphs were produced in SVG format and then converted to PNG's using the same
process as the equations.  

The programs 
/libs/math/doc/sf_and_dist/graphs/dist_graphs.cpp
and /libs/math/doc/sf_and_dist/graphs/sf_graphs.cpp
generate the SVG's directly using the 
[@http://code.google.com/soc/2007/boost/about.html Google Summer of Code 2007]
project of Jacob Voytko (whose work so far is at .\boost-sandbox\SOC\2007\visualization).

[endsect] [/section:implementation Implementation Notes]

[/ 
  Copyright 2006, 2007 John Maddock and Paul A. Bristow.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]