libs/math/doc/overview/common_overviews.qbk

   1 [/These are templates used in many other Quickbook files.]
   2
   3 [template policy_overview[]
   4
   5 Policies are a powerful fine-grain mechanism that allow you to customise the
   6 behaviour of this library according to your needs.  There is more information
   7 available in the [link math_toolkit.pol_tutorial policy tutorial]
   8 and the [link math_toolkit.pol_ref policy reference].
   9
  10 Generally speaking, unless you find that the
  11 [link math_toolkit.pol_tutorial.policy_tut_defaults
  12  default policy behaviour]
  13 when encountering 'bad' argument values does not meet your needs,
  14 you should not need to worry about policies.
  15
  16 Policies are a compile-time mechanism that allow you to change
  17 error-handling or calculation precision either
  18 program wide, or at the call site.
  19
  20 Although the policy mechanism itself is rather complicated,
  21 in practice it is easy to use, and very flexible.
  22
  23 Using policies you can control:
  24
  25 * [link math_toolkit.pol_ref.error_handling_policies How results from 'bad' arguments are handled],
  26    including those that cannot be fully evaluated.
  27 * How [link math_toolkit.pol_ref.internal_promotion accuracy is controlled by internal promotion] to use more precise types.
  28 * What working [link math_toolkit.pol_ref.precision_pol precision] should be used to calculate results.
  29 * What to do when a [link math_toolkit.pol_ref.assert_undefined mathematically undefined function]
  30   is used:  Should this raise a run-time or compile-time error?
  31 * Whether [link math_toolkit.pol_ref.discrete_quant_ref discrete functions],
  32   like the binomial, should return real or only integral values, and how they are rounded.
  33 * How many iterations a special function is permitted to perform in
  34   a series evaluation or root finding algorithm before it gives up and raises an
  35   __evaluation_error.
  36
  37 You can control policies:
  38
  39 * Using [link math_toolkit.pol_ref.policy_defaults macros] to
  40 change any default policy: the is the preferred method for installation
  41 wide policies.
  42 * At your chosen [link math_toolkit.pol_ref.namespace_pol
  43 namespace scope] for distributions and/or functions: this is the
  44 preferred method for project, namespace, or translation unit scope
  45 policies.
  46 * In an ad-hoc manner [link math_toolkit.pol_tutorial.ad_hoc_sf_policies
  47 by passing a specific policy to a special function], or to a
  48 [link math_toolkit.pol_tutorial.ad_hoc_dist_policies
  49 statistical distribution].
  50
  51 ] [/template policy_overview]
  52
  53
  54 [template performance_overview[]
  55
  56 By and large the performance of this library should be acceptable
  57 for most needs.  However, often the library has to make a choice whether to
  58 be accurate or fast and by default it chooses accuracy over speed.  If
  59 you would rather have fast rather than fully accurate routines, then
  60 refer to the [link perf performance section] for information and examples on how to
  61 achieve this.
  62
  63 In terms of the algorithms used, this library aims to use the same "best
  64 of breed" algorithms as many other libraries: the principle difference
  65 is that this library is implemented in C++ - taking advantage of all
  66 the abstraction mechanisms that C++ offers - where as most traditional
  67 numeric libraries are implemented in C or FORTRAN.  Traditionally
  68 languages such as C or FORTRAN are perceived as easier to optimise
  69 than more complex languages like C++, so in a sense this library
  70 provides a good test of current compiler technology, and the
  71 "abstraction penalty" - if any - of C++ compared to other languages.
  72
  73 The three most important things you can do to ensure the best performance
  74 from this library are:
  75
  76 # Turn on your compilers optimisations: the difference between "release"
  77 and "debug" builds can easily be a [link math_toolkit.getting_best factor of 20].
  78 # Pick your compiler carefully: [link math_toolkit.comp_compilers
  79 performance differences of up to
  80 8 fold] have been found between some Windows compilers for example.
  81 # Disable internal use of `long double`, this will reduce accuracy but
  82 typically yield a 2x speedup on modern x64 hardware/compilers.
  83
  84 The [link perf performance section] contains more
  85 information on the performance
  86 of this library, what you can do to fine tune it, and how this library
  87 compares to some other open source alternatives.
  88
  89 ] [/template performance_overview]
  90
  91 [template compilers_overview[]
  92
  93 This section contains some information about how various compilers
  94 work with this library.
  95 It is not comprehensive and updated experiences are always welcome.
  96 Some effort has been made to suppress unhelpful warnings but it is
  97 difficult to achieve this on all systems.
  98
  99 [table Supported/Tested Compilers
 100 [[Platform][Compiler][Has long double support][Notes]]
 101 [[Windows][MSVC 7.1 and later][Yes]
 102    [All tests OK.
 103
 104    We aim to keep our headers warning free at level 4 with
 105    this compiler.]]
 106 [[Windows][Intel 8.1 and later][Yes]
 107    [All tests OK.
 108
 109    We aim to keep our headers warning free at level 4 with
 110    this compiler.  However, The tests cases tend to generate a lot of
 111       warnings relating to numeric underflow of the test data: these are
 112       harmless.]]
 113 [[Windows][GNU Mingw32 C++][Yes]
 114    [All tests OK.
 115
 116    We aim to keep our headers warning free with -Wall with this compiler.]]
 117 [[Windows][GNU Cygwin C++][No]
 118    [All tests OK.
 119
 120    We aim to keep our headers warning free with -Wall with this compiler.
 121
 122    Long double support has been disabled because there are no native
 123    long double C std library functions available.]]
 124 [[Windows][Borland C++ 5.8.2 (Developer studio 2006)][No]
 125    [We have only partial compatibility with this compiler:
 126
 127    Long double support has been disabled because the native
 128    long double C standard library functions really only forward to the
 129    double versions.  This can result in unpredictable behaviour when
 130    using the long double overloads: for example `sqrtl` applied to a
 131    finite value, can result in an infinite result.
 132
 133    Some functions still fail to compile, there are no known workarounds at present.]]
 134 [[Windows 7/Netbeans 7.2][Clang 3.1][Yes][Spot examples OK. Expect all tests to compile and run OK.]]
 135
 136 [[Linux][GNU C++ 3.4 and later][Yes]
 137    [All tests OK.
 138
 139    We aim to keep our headers warning free with -Wall with this compiler.]]
 140 [[Linux][Clang 3.2][Yes][All tests OK.]]
 141 [[Linux][Intel C++ 10.0 and later][Yes]
 142    [All tests OK.
 143
 144    We aim to keep our headers warning free with -Wall with this compiler.
 145    However, The tests cases tend to generate a lot of
 146    warnings relating to numeric underflow of the test data: these are
 147    harmless.]]
 148 [[Linux][Intel C++ 8.1 and 9.1][No]
 149    [All tests OK.
 150
 151    Long double support has been disabled with these compiler releases
 152    because calling the standard library long double math functions
 153    can result in a segfault.  The issue is Linux distribution and
 154    glibc version specific and is Intel bug report #409291.  Fully up to date
 155    releases of Intel 9.1 (post version l_cc_c_9.1.046)
 156    shouldn't have this problem.  If you need long
 157    double support with this compiler, then comment out the define of
 158    BOOST_MATH_NO_LONG_DOUBLE_MATH_FUNCTIONS at line 55 of
 159    [@../../../../boost/math/tools/config.hpp boost/math/tools/config.hpp].
 160
 161    We aim to keep our headers warning free with -Wall with this compiler.
 162    However, The tests cases tend to generate a lot of
 163    warnings relating to numeric underflow of the test data: these are
 164    harmless.]]
 165 [[Linux][QLogic PathScale 3.0][Yes]
 166    [Some tests involving conceptual checks fail to build, otherwise
 167    there appear to be no issues.]]
 168 [[Linux][Sun Studio 12][Yes]
 169    [Some tests involving function overload resolution fail to build,
 170    these issues should be rarely encountered in practice.]]
 171 [[Solaris][Sun Studio 12][Yes]
 172    [Some tests involving function overload resolution fail to build,
 173    these issues should be rarely encountered in practice.]]
 174 [[Solaris][GNU C++ 4.x][Yes]
 175    [All tests OK.
 176
 177    We aim to keep our headers warning free with -Wall with this compiler.]]
 178 [[HP Tru64][Compaq C++ 7.1][Yes]
 179    [All tests OK.]]
 180 [[HP-UX Itanium][HP aCC 6.x][Yes]
 181    [All tests OK.
 182
 183    Unfortunately this compiler emits quite a few warnings from libraries
 184    upon which we depend (TR1, Array etc).]]
 185 [[HP-UX PA-RISC][GNU C++ 3.4][No]
 186    [All tests OK.]]
 187 [[Apple Mac OS X, Intel][Darwin/GNU C++ 4.x][Yes][All tests OK.]]
 188 [[Apple Mac OS X, PowerPC][Darwin/GNU C++ 4.x][No]
 189    [All tests OK.
 190
 191    Long double support has been disabled on this platform due to the
 192    rather strange nature of Darwin's 106-bit long double
 193    implementation.  It should be possible to make this work if someone
 194    is prepared to offer assistance.]]
 195 [[Apple Mac OS X,][Clang 3.2][Yes][All tests expected to be OK.]]
 196 [[IBM AIX][IBM xlc 5.3][Yes]
 197    [All tests pass except for our fpclassify tests which fail due to a
 198    bug in `std::numeric_limits`, the bug effects the test code, not
 199    fpclassify itself.  The IBM compiler group are aware of the problem.]]
 200 ]
 201
 202 [table Unsupported Compilers
 203 [[Platform][Compiler]]
 204 [[Windows][Borland C++ 5.9.2 (Borland Developer Studio 2007)]]
 205 [[Windows][MSVC 6 and 7]]
 206 ]
 207
 208 If your compiler or platform is not listed above, please try running the
 209 regression tests: cd into boost-root/libs/math/test and do a:
 210
 211    bjam mytoolset
 212
 213 where "mytoolset" is the name of the
 214 [@http://www.boost.org/doc/html/bbv2.html Boost.Build]
 215 toolset used for your
 216 compiler.  The chances are that [*many of the accuracy tests will fail
 217 at this stage] - don't panic - the default acceptable error tolerances
 218 are quite tight, especially for long double types with an extended
 219 exponent range (these cause more extreme test cases to be executed
 220 for some functions).
 221 You will need to cast an eye over the output from
 222 the failing tests and make a judgement as to whether
 223 the error rates are acceptable or not.
 224 ] [/template compilers_overview]
 225
 226 [/ common_overviews.qbk
 227   Copyright 2007, 2012, 2014 John Maddock and Paul A. Bristow.
 228   Distributed under the Boost Software License, Version 1.0.
 229   (See accompanying file LICENSE_1_0.txt or copy at
 230   http://www.boost.org/LICENSE_1_0.txt).
 231 ]
 232