
BoostCommit : 
Subject: [Boostcommit] svn:boost r50073  sandbox/math_toolkit/libs/math/doc/sf_and_dist
From: pbristow_at_[hidden]
Date: 20081202 10:30:58
Author: pbristow
Date: 20081202 10:30:57 EST (Tue, 02 Dec 2008)
New Revision: 50073
URL: http://svn.boost.org/trac/boost/changeset/50073
Log:
Typo corrected
Text files modified:
sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk  156 +++++++++++++++++++++
1 files changed, 82 insertions(+), 74 deletions()
Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk
==============================================================================
 sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk 20081202 10:30:57 EST (Tue, 02 Dec 2008)
@@ 72,12 +72,12 @@
`static_cast<RealType>(1) / 3;`
If a function is very sensitive to changes in input,
specifying an inexact value as input (such as 0.1) can throw
+specifying an inexact value as input (such as 0.1) can throw
the result off by a noticeable amount: 0.1f is "wrong"
by ~1e7 for example (because 0.1 has no exact binary representation).
+by ~1e7 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 `a/b` with `b`
a power of two (in order to ensure that the result is an exactly
+are used in test code along with the occasional fraction `a/b` with `b`
+a power of two (in order to ensure that the result is an exactly
representable binary value).
[h4 Tolerance of Tests]
@@ 87,7 +87,7 @@
* Some epsilon value.
* The accuracy of the data (often only near 64bit double).
Otherwise when long double has more digits than the test data, then no
+Otherwise when long double has more digits than the test data, then no
amount of tweaking an epsilon based tolerance will work.
A common problem is when tolerances that are suitable for implementations
@@ 127,13 +127,13 @@
[@http://www.openstd.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf Draft Technical Report on C++ Library Extensions, 20050624, section 5.2.1, paragraph 5].
[link math_toolkit.main_overview.error_handling See also domain_error].
See __policy_ref for details of the error handling policies that should allow
+See __policy_ref for details of the error handling policies that should allow
a user to comply with any of these recommendations, as well as other behaviour.
See [link math_toolkit.main_overview.error_handling error handling]
for a detailed explanation of the mechanism, and
[link math_toolkit.dist.stat_tut.weg.error_eg error_handling example]
and
+and
[@../../../example/error_handling_example.cpp error_handling_example.cpp]
[caution If you enable throw but do NOT have try & catch block,
@@ 146,14 +146,14 @@
Functions that are not mathematically defined,
like the Cauchy mean, fail to compile by default.
[link math_toolkit.policy.pol_ref.assert_undefined A policy]
+[link math_toolkit.policy.pol_ref.assert_undefined A policy]
allows control of this.
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,
+to not throw, and to return NaN instead. For example,
`#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error`
+`#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error`
appears before the first Boost include,
then if the unimplemented function is called,
@@ 161,7 +161,7 @@
[warning If `std::numeric_limits<T>::has_quiet_NaN` is false
(for example T is a Userdefined type),
then an exception will always be thrown when a domain error occurs.
+then an exception will always be thrown when a domain error occurs.
Catching exceptions is therefore strongly recommended.]
[h4 Median of distributions]
@@ 186,19 +186,19 @@
[h4 Handling of FloatingPoint Infinity]
Some functions and distributions are well defined with + or  infinity as
argument(s), but after some experiments with handling infinite arguments
+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 __domain_error.
+and instead to return the result of __domain_error.
Handling infinity as special cases is additionally complicated
because, unlike builtin types on most  but not all  platforms,
not all UserDefined Types are
+Handling infinity as special cases is additionally complicated
+because, unlike builtin types on most  but not all  platforms,
+not all UserDefined Types are
specialized to provide `std::numeric_limits<RealType>::infinity()`
and would return zero rather than any representation of infinity.
The rationale is that nonfiniteness may happen because of error
or overflow in the users code, and it will be more helpful for this
+The rationale is that nonfiniteness 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 errorprone,
much more work to test, and much less readable.
@@ 207,7 +207,7 @@
we have permitted argument(s) to be infinity,
provided infinity is implemented for the realType on that implementation.
Users who require special handling of infinity (or other specific value) can,
+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.
@@ 235,7 +235,7 @@
}
return (upper  lower);
}

+
but found that these concepts are not defined (or their definition too contentious)
for too many distributions to be generally applicable.
Because they are nonmember functions, they can be added if required.
@@ 253,7 +253,7 @@
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
+or devised by John Maddock using
[link math_toolkit.toolkit.internals2.minimax our Remez code].
Rational rather than Polynomial approximations are used to ensure
@@ 266,24 +266,24 @@
literature methods were unavailable or under nonBSL
compatible license. Our Remez code is known to produce good
agreement with literature results in fairly simple "toy" cases.
All approximations were checked
+All approximations were checked
for convergence and to ensure that
they were not illconditioned (the coefficients can give a
theoretically good solution, but the resulting rational function
may be uncomputable at fixed precision).
+they were not illconditioned (the coefficients can give a
+theoretically good solution, but the resulting rational function
+may be uncomputable at fixed precision).
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 illdefined minima for many of these approximations
(of course for simple "toy" examples like approximating `exp` the minima
+(of course for simple "toy" examples like approximating `exp` the minima
is well defined, and the coeffiecents should agree no matter whose Remez
implementation is used). This should not in general effect the validity
of the approximations: there's good literature supporting the idea that
coefficients can be "in error" without necessarily adversely effecting
+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 [@http://front.math.ucdavis.edu/0101.5042
"Approximate construction of rational approximations and the effect
+see [@http://front.math.ucdavis.edu/0101.5042
+"Approximate construction of rational approximations and the effect
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.
@@ 294,8 +294,8 @@
to provide high accuracy constants to mathematical functions and distributions,
since it is important to provide values uniformly for both builtin
float, double and long double types,
and for User Defined types like NTL::quad_float and NTL::RR.

+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.
@@ 316,7 +316,7 @@
BOOST_DEFINE_MATH_CONSTANT(pi,
3.141592653589793238462643383279502884197169399375105820974944,
5923078164062862089986280348253421170679821480865132823066470938446095505,
 0)
+ 0)
And used thus:
@@ 324,19 +324,19 @@
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'
+ 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
+ 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]
@@ 344,16 +344,16 @@
(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
+Other than that, the code is intended to be thread safe *for built in
realnumber types* : so float, double and long double are all thread safe.
For nonbuiltin types  NTL::RR for example  initialisation of the various
constants used in the implementation is potentially *not* thread safe.
+For nonbuiltin 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
staticconstants 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
+Some compilers may offer the option of having
+staticconstants 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]
@@ 386,32 +386,32 @@
& 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
+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
+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
+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
+Convertion to SVG was achieved using
[@http://www.grigoriev.ru/svgmath/ SVGMath] and a command line
such as:
[pre
$for file in *.mml; do
+[pre
+$for file in *.mml; do
>/cygdrive/c/Python25/python.exe 'C:\download\open\SVGMath0.3.1\math2svg.py' \\
>>$file > $(basename $file .mml).svg
>done
]
Note that SVGMath requires that the mml files are *not* wrapped in an XHTML
+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
@@ 444,7 +444,7 @@
Also note that the SVG files in the repository are almost certainly
Windowsspecific since they reference various Windows Fonts.
PNG files can be created from the SVG's using
+PNG files can be created from the SVG's using
[@http://xmlgraphics.apache.org/batik/tools/rasterizer.html Batik]
and a command such as:
@@ 452,8 +452,8 @@
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);
+[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.
@@ 462,19 +462,25 @@
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]
+[pre bjam a pdf >math_pdf.log]
Note that XEP will have to be configured to *use and embed*
+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).
+(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
(html is generated at math_toolkit\libs\math\doc\sf_and_dist\html\index.html
using just bjam a).
+[pre \[warning\]could not find any font family matching "Times New Roman"; replaced by Helvetica]
JM's XEP config file has the following font configuration section added:
+(html is the default so it is generated at math_toolkit\libs\math\doc\sf_and_dist\html\index.html
+using command line >bjam a > math_docs.log).
+
+ <! Sample configuration for Windows TrueType fonts. >
+is provided in the xep.xml downloaded, but the Windows TrueType fonts are commented out.
+
+JM's XEP config file \xep\xep.xml has the following font configuration section added:
[pre
 <font\group xml:base\="file:\/C:\/Windows\/Fonts\/" label\="Windows TrueType" embed\="true" subset\="true">
+ <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>
@@ 514,18 +520,20 @@
<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>
+
+ <fontfamily name="Lucida Sans Unicode">
+ <! <font><fontdata ttf="lsansuni.ttf"></font> >
+ <! actually called l_10646.ttf on Windows 2000 and Vista Sp1 >
+ <font><fontdata ttf="l_10646.ttf"/></font>
+ </fontfamily>
]
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.
+Other 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://gentoowiki.com/HOWTO_Convert_LaTeX_to_HTML_with_MathML mxlatex].
This process is currently unreliable and required some manual intervention:
+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.
@@ 543,24 +551,24 @@
</inlinemediaobject>
]
MathML is not currently present in the Docbook output, or in the
+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.
+process as the equations.
The programs
+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
+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 .\boostsandbox\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
BoostCommit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk