boost_1_45_0/libs/math/doc/sf_and_dist/common_overviews.qbk

[template policy_overview[]

Policies are a powerful fine-grain mechanism that allow you to customise the
behaviour of this library according to your needs.  There is more information
available in the [link math_toolkit.policy.pol_tutorial policy tutorial] 
and the [link math_toolkit.policy.pol_ref policy reference].

Generally speaking, unless you find that the 
[link math_toolkit.policy.pol_tutorial.policy_tut_defaults
 default policy behaviour]
when encountering 'bad' argument values does not meet your needs,
you should not need to worry about policies.

Policies are a compile-time mechanism that allow you to change 
error-handling or calculation precision either
program wide, or at the call site.

Although the policy mechanism itself is rather complicated,
in practice it is easy to use, and very flexible.

Using policies you can control:

* [link math_toolkit.policy.pol_ref.error_handling_policies How results from 'bad' arguments are handled],
   including those that cannot be fully evaluated.
* How [link math_toolkit.policy.pol_ref.internal_promotion accuracy is controlled by internal promotion] to use more precise types.
* What working [link math_toolkit.policy.pol_ref.precision_pol precision] should be used to calculate results.
* What to do when a [link math_toolkit.policy.pol_ref.assert_undefined mathematically undefined function]
  is used:  Should this raise a run-time or compile-time error?
* Whether [link math_toolkit.policy.pol_ref.discrete_quant_ref discrete functions],
  like the binomial, should return real or only integral values, and how they are rounded.
* How many iterations a special function is permitted to perform in
  a series evaluation or root finding algorithm before it gives up and raises an
  __evaluation_error.
  
You can control policies:

* Using [link math_toolkit.policy.pol_ref.policy_defaults macros] to 
change any default policy: the is the prefered method for installation
wide policies.
* At your chosen [link math_toolkit.policy.pol_ref.namespace_pol 
namespace scope] for distributions and/or functions: this is the 
prefered method for project, namespace, or translation unit scope
policies.
* In an ad-hoc manner [link math_toolkit.policy.pol_tutorial.ad_hoc_sf_policies 
by passing a specific policy to a special function], or to a 
[link math_toolkit.policy.pol_tutorial.ad_hoc_dist_policies 
statistical distribution].

]

[template performance_overview[]

By and large the performance of this library should be acceptable
for most needs.  However, you should note that this library's primary
emphasis is on accuracy and numerical stability, and /not/ speed.

In terms of the algorithms used, this library aims to use the same "best
of breed" algorithms as many other libraries: the principle difference
is that this library is implemented in C++ - taking advantage of all
the abstraction mechanisms that C++ offers - where as most traditional
numeric libraries are implemented in C or FORTRAN.  Traditionally
languages such as C or FORTRAN are perceived as easier to optimise
than more complex languages like C++, so in a sense this library
provides a good test of current compiler technology, and the 
"abstraction penalty" - if any - of C++ compared to other languages.

The two most important things you can do to ensure the best performance
from this library are:

# Turn on your compilers optimisations: the difference between "release"
and "debug" builds can easily be a [link math_toolkit.perf.getting_best factor of 20].
# Pick your compiler carefully: [link math_toolkit.perf.comp_compilers
performance differences of up to 
8 fold] have been found between some Windows compilers for example.

The [link math_toolkit.perf performance section] contains more 
information on the performance
of this library, what you can do to fine tune it, and how this library
compares to some other open source alternatives.

]

[template compilers_overview[]

This section contains some information about how various compilers 
work with this library.
It is not comprehensive and updated experiences are always welcome.
Some effort has been made to suppress unhelpful warnings but it is 
difficult to achieve this on all systems.

[table Supported/Tested Compilers
[[Platform][Compiler][Has long double support][Notes]]
[[Windows][MSVC 7.1 and later][Yes]
   [All tests OK.
   
   We aim to keep our headers warning free at level 4 with
   this compiler.]]
[[Windows][Intel 8.1 and later][Yes]
   [All tests OK.
   
   We aim to keep our headers warning free at level 4 with
   this compiler.  However, The tests cases tend to generate a lot of
      warnings relating to numeric underflow of the test data: these are 
      harmless.]]
[[Windows][GNU Mingw32 C++][Yes]
   [All tests OK.
   
   We aim to keep our headers warning free with -Wall with this compiler.]]
[[Windows][GNU Cygwin C++][No]
   [All tests OK.
   
   We aim to keep our headers warning free with -Wall with this compiler.
   
   Long double support has been disabled because there are no native
   long double C std library functions available.]]
[[Windows][Borland C++ 5.8.2 (Developer studio 2006)][No]
   [We have only partial compatability with this compiler: 
   
   Long double support has been disabled because the native
   long double C standard library functions really only forward to the
   double versions.  This can result in unpredictable behaviour when
   using the long double overloads: for example `sqrtl` applied to a 
   finite value, can result in an infinite result.
   
   Some functions still fail to compile, there are no known workarounds at present.]]
   
[[Linux][GNU C++ 3.4 and later][Yes]
   [All tests OK.
   
   We aim to keep our headers warning free with -Wall with this compiler.]]
[[Linux][Intel C++ 10.0 and later][Yes]
   [All tests OK.
   
   We aim to keep our headers warning free with -Wall with this compiler.
   However, The tests cases tend to generate a lot of
   warnings relating to numeric underflow of the test data: these are 
   harmless.]]
[[Linux][Intel C++ 8.1 and 9.1][No]
   [All tests OK.
   
   Long double support has been disabled with these compiler releases
   because calling the standard library long double math functions
   can result in a segfault.  The issue is Linux distribution and
   glibc version specific and is Intel bug report #409291.  Fully up to date
   releases of Intel 9.1 (post version l_cc_c_9.1.046)
   shouldn't have this problem.  If you need long 
   double support with this compiler, then comment out the define of
   BOOST_MATH_NO_LONG_DOUBLE_MATH_FUNCTIONS at line 55 of 
   [@../../../../../boost/math/tools/config.hpp boost/math/tools/config.hpp].
   
   We aim to keep our headers warning free with -Wall with this compiler.
   However, The tests cases tend to generate a lot of
   warnings relating to numeric underflow of the test data: these are 
   harmless.]]
[[Linux][QLogic PathScale 3.0][Yes]
   [Some tests involving conceptual checks fail to build, otherwise
   there appear to be no issues.]]
[[Linux][Sun Studio 12][Yes]
   [Some tests involving function overload resolution fail to build, 
   these issues should be rairly encountered in practice.]]
[[Solaris][Sun Studio 12][Yes]
   [Some tests involving function overload resolution fail to build, 
   these issues should be rairly encountered in practice.]]
[[Solaris][GNU C++ 4.x][Yes]
   [All tests OK.
   
   We aim to keep our headers warning free with -Wall with this compiler.]]
[[HP Tru64][Compaq C++ 7.1][Yes]
   [All tests OK.]]
[[HP-UX Itanium][HP aCC 6.x][Yes]
   [All tests OK.
   
   Unfortunately this compiler emits quite a few warnings from libraries 
   upon which we depend (TR1, Array etc).]]
[[HP-UX PA-RISC][GNU C++ 3.4][No]
   [All tests OK.]]
[[Apple Mac OS X, Intel][Darwin/GNU C++ 4.x][Yes][All tests OK.]]
[[Apple Mac OS X, PowerPC][Darwin/GNU C++ 4.x][No]
   [All tests OK.
   
   Long double support has been disabled on this platform due to the
   rather strange nature of Darwin's 106-bit long double
   implementation.  It should be possible to make this work if someone
   is prepared to offer assistance.]]
[[IMB AIX][IBM xlc 5.3][Yes]
   [All tests pass except for our fpclassify tests which fail due to a 
   bug in `std::numeric_limits`, the bug effects the test code, not
   fpclassify itself.  The IBM compiler group
   are aware of the problem.]]
]

[table Unsupported Compilers
[[Platform][Compiler]]
[[Windows][Borland C++ 5.9.2 (Borland Developer Studio 2007)]]
[[Windows][MSVC 6 and 7]]
]

If you're compiler or platform is not listed above, please try running the
regression tests: cd into boost-root/libs/math/test and do a:

   bjam mytoolset

where "mytoolset" is the name of the 
[@../../../../../tools/build/index.html Boost.Build] toolset used for your
compiler.  The chances are that [*many of the accuracy tests will fail
at this stage] - don't panic - the default acceptable error tolerances
are quite tight, especially for long double types with an extended
exponent range (these cause more extreme test cases to be executed
for some functions).  
You will need to cast an eye over the output from
the failing tests and make a judgement as to whether 
the error rates are acceptable or not.

]

[/ math.qbk
  Copyright 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).
]