1[/These are templates used in many other Quickbook files.] 2 3[template policy_overview[] 4 5Policies are a powerful fine-grain mechanism that allow you to customise the 6behaviour of this library according to your needs. There is more information 7available in the [link math_toolkit.pol_tutorial policy tutorial] 8and the [link math_toolkit.pol_ref policy reference]. 9 10Generally speaking, unless you find that the 11[link math_toolkit.pol_tutorial.policy_tut_defaults 12 default policy behaviour] 13when encountering 'bad' argument values does not meet your needs, 14you should not need to worry about policies. 15 16Policies are a compile-time mechanism that allow you to change 17error-handling or calculation precision either 18program wide, or at the call site. 19 20Although the policy mechanism itself is rather complicated, 21in practice it is easy to use, and very flexible. 22 23Using 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 37You can control policies: 38 39* Using [link math_toolkit.pol_ref.policy_defaults macros] to 40change any default policy: the is the preferred method for installation 41wide policies. 42* At your chosen [link math_toolkit.pol_ref.namespace_pol 43namespace scope] for distributions and/or functions: this is the 44preferred method for project, namespace, or translation unit scope 45policies. 46* In an ad-hoc manner [link math_toolkit.pol_tutorial.ad_hoc_sf_policies 47by passing a specific policy to a special function], or to a 48[link math_toolkit.pol_tutorial.ad_hoc_dist_policies 49statistical distribution]. 50 51] [/template policy_overview] 52 53 54[template performance_overview[] 55 56By and large the performance of this library should be acceptable 57for most needs. However, often the library has to make a choice whether to 58be accurate or fast and by default it chooses accuracy over speed. If 59you would rather have fast rather than fully accurate routines, then 60refer to the [link perf performance section] for information and examples on how to 61achieve this. 62 63In terms of the algorithms used, this library aims to use the same "best 64of breed" algorithms as many other libraries: the principle difference 65is that this library is implemented in C++ - taking advantage of all 66the abstraction mechanisms that C++ offers - where as most traditional 67numeric libraries are implemented in C or FORTRAN. Traditionally 68languages such as C or FORTRAN are perceived as easier to optimise 69than more complex languages like C++, so in a sense this library 70provides a good test of current compiler technology, and the 71"abstraction penalty" - if any - of C++ compared to other languages. 72 73The three most important things you can do to ensure the best performance 74from this library are: 75 76# Turn on your compilers optimisations: the difference between "release" 77and "debug" builds can easily be a [link math_toolkit.getting_best factor of 20]. 78# Pick your compiler carefully: [link math_toolkit.comp_compilers 79performance differences of up to 808 fold] have been found between some Windows compilers for example. 81# Disable internal use of `long double`, this will reduce accuracy but 82typically yield a 2x speedup on modern x64 hardware/compilers. 83 84The [link perf performance section] contains more 85information on the performance 86of this library, what you can do to fine tune it, and how this library 87compares to some other open source alternatives. 88 89] [/template performance_overview] 90 91[template compilers_overview[] 92 93This section contains some information about how various compilers 94work with this library. 95It is not comprehensive and updated experiences are always welcome. 96Some effort has been made to suppress unhelpful warnings but it is 97difficult 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 208If your compiler or platform is not listed above, please try running the 209regression tests: cd into boost-root/libs/math/test and do a: 210 211 bjam mytoolset 212 213where "mytoolset" is the name of the 214[@http://www.boost.org/doc/html/bbv2.html Boost.Build] 215toolset used for your 216compiler. The chances are that [*many of the accuracy tests will fail 217at this stage] - don't panic - the default acceptable error tolerances 218are quite tight, especially for long double types with an extended 219exponent range (these cause more extreme test cases to be executed 220for some functions). 221You will need to cast an eye over the output from 222the failing tests and make a judgement as to whether 223the 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 233