diff --git a/doc/sf_and_dist/FAQ.qbk b/doc/sf_and_dist/FAQ.qbk new file mode 100644 index 000000000..2ad5f62bd --- /dev/null +++ b/doc/sf_and_dist/FAQ.qbk @@ -0,0 +1,87 @@ +[section:faq Frequently Asked Questions FAQ] + +# ['I'm a FORTRAN/NAG/SPSS/SAS/Cephes/MathCad/R user and I don't see where the functions like dnorm(mean, sd) are in Boost.Math?] [br] +Nearly all are provided, and many more like mean, skewness, quantiles, complements ... +but Boost.Math makes full use of C++, and it looks a bit different. +But do not panic! See section on construction and the many examples. +Briefly, the distribution is constructed with the parameters (like location and scale) +(things after the | in representation like P(X=k|n, p) or ; in a common represention of pdf f(x; [mu][sigma][super [2]). +Functions like pdf, cdf are called with the name of that distribution and the random variate often called x or k. +For example, `normal my_norm(0, 1); pdf(my_norm, 2.0);` [br] +# ['I'm allegic to reading manuals and prefer to learn from examples.][br] +Fear not - you are not alone! Many examples are available for functions and distributions. +Some are referenced directly from the text. Others can be found at \boost_latest_release\libs\math\example. +If you are a Visual Studio user, you should be able to create projects from each of these, +making sure that the Boost library is in the include directories list. +# ['How do I make sure that the Boost library is in the Visual Studio include directories list?][br] +You can add an include path, for example, your Boost place /boost-latest_release, +for example `X:/boost_1_45_0/` if you have a separate partition X for Boost releases. +Or you can use an environment variable BOOST_ROOT set to your Boost place, and include that. +Visual Studio before 2010 provided Tools, Options, VC++ Directories to control directories: +Visual Studio 2010 instead provides property sheets to assist. +You may find it convenient to create a new one adding \boost-latest_release; +to the existing include items in $(IncludePath). +# ['I'm a FORTRAN/NAG/SPSS/SAS/Cephes/MathCad/R user and +I don't see where the properties like mean, median, mode, variance, skewness of distributions are in Boost.Math?][br] +They are all available (if defined for the parameters with which you constructed the distribution) via __usual_accessors. +# ['I am a C programmer. Can I user Boost.Math with C?][br] +Yes you can, including all the special functions, and TR1 functions like isnan. +They appear as C functions, by being declared as "extern C". +# ['I am a C# (Basic? F# FORTRAN? Other CLI?) programmer. Can I use Boost.Math with C#?] [br] +Yes you can, including all the special functions, and TR1 functions like isnan. +But you [*must build the Boost.Math as a dynamic library (.dll) and compile with the /CLI option]. +See the boost/math/dot_net_example folder which contains an example that +builds a simple statistical distribution app with a GUI. +See [@http://sourceforge.net/projects/distexplorer/ Statistical Distribution Explorer] [br] +# ['What these "policies" things for?] [br] +Policies are a powerful (if necessarily complex) fine-grain mechanism that +allow you to customise the behaviour of the Boost.Math library according to your precise needs. +See __policy_section. But if, very probably, the default behaviour suits you, you don't need to know more. +# ['I am a C user and expect to see global C-style`::errno` set for overflow/errors etc?] [br] +You can achieve what you want - see __error_policy and __user_error_handling and many examples. +# ['I am a C user and expect to silently return a max value for overflow?] [br] +You (and C++ users too) can return whatever you want on overflow +- see __overflow_error and __error_policy and several examples. +# ['I don't want any error message for overflow etc?] [br] +You can control exactly what happens for all the abnormal conditions, including the values returned. +See __domain_error, __overflow_error __error_policy __user_error_handling etc and examples. +# ['My environment doesn't allow and/or I don't want exceptions. Can I still user Boost.Math?] [br] +Yes but you must customise the error handling: see __user_error_handling and __changing_policy_defaults . +# ['The docs are several hundreds of pages long! Can I read the docs off-line or on paper?] [br] +Yes - you can download the Boost current release of most documentation +as a zip of pdfs (including Boost.Math) from Sourceforge, +for example [@https://sourceforge.net/projects/boost/files/boost-docs/1.45.0/boost_pdf_1_45_0.tar.gz/download]. +And you can print any pages you need (or even print all pages - but be warned that there are several hundred!). +Both html and pdf versions are highly hyperlinked. +The entire Boost.Math pdf can be searched with Adobe Reader, Edit, Find ... +This can often find what you seek, a partial substitute for a full index. +# ['I want a compact version for an embedded application. Can I use float precision?] [br] +Yes - by selecting RealType template parameter as float: +for example normal_distribution your_normal(mean, sd); +(But double may still be used internally, so space saving may be less that you hope for). +You can also change the promotion policy, but accuracy might be much reduced. +# ['I seem to get somewhat different results compared to other programs. Why?] +We hope Boost.Math to be more accurate: our priority is accuracy (over speed). +See the section on accuracy. But for evaluations that require iterations +there are parameters which can change the required accuracy. You might be able to +squeeze a little more accuracy at the cost of runtime. +# ['Will my program run more slowly compared to other math functions and statistical libraries?] +Probably, thought not always, and not by too much: our priority is accuracy. +For most functions, making sure you have the latest compiler version with all optimisations switched on is the key to speed. +For evaluations that require iteration, you may be able to gain a little more speed at the expense of accuracy. +See detailed suggestions and results on __performance. +# ['Where are the pre-built libraries?] [br] +Good news - you probably don't need any! - just #include . +But in the unlikely event that you do, see __building. +# ['I don't see the function or distribution that I want.] [br] +You could try an email to ask the authors - but no promises! + +[endsect] [/section:faq Frequently Asked Questions] + +[/ + Copyright 2010 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). +] +