188 lines
10 KiB
Plaintext
188 lines
10 KiB
Plaintext
[section:main_faq Boost.Math Frequently Asked Questions (FAQs)]
|
|
|
|
# ['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?]
|
|
|
|
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);`
|
|
|
|
# I'm a user of [@http://support.sas.com/rnd/app/da/new/probabilityfunctions.html New SAS Functions for Computing Probabilities].
|
|
|
|
You will find the interface more familar, but to be able to select a distribution (perhaps using a string)
|
|
see the Extras/Future Directions section,
|
|
and /boost/libs/math/dot_net_example/boost_math.cpp for an example that is used to create a C# (C sharp) utility
|
|
(that you might also find useful):
|
|
see [@http://sourceforge.net/projects/distexplorer/ Statistical Distribution Explorer].
|
|
|
|
# ['I'm allegic to reading manuals and prefer to learn from examples.]
|
|
|
|
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`,
|
|
for 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 (there are usually NO libraries that must be built).
|
|
|
|
# ['How do I make sure that the Boost library is in the Visual Studio include directories list?]
|
|
|
|
You can add an include path, for example, your Boost place /boost-latest_release,
|
|
for example `X:/boost_1_70_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?]
|
|
|
|
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?]
|
|
|
|
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#? (or ...)?]
|
|
|
|
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]
|
|
|
|
# ['What these "policies" things for?]
|
|
|
|
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?]
|
|
|
|
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?]
|
|
|
|
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?]
|
|
|
|
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?]
|
|
|
|
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?]
|
|
|
|
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?]
|
|
|
|
Yes - by selecting RealType template parameter as float:
|
|
for example normal_distribution<float> 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 (see __policy_section).
|
|
You might be able to squeeze a little more (or less) 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.
|
|
|
|
# ['How do I handle infinity and NaNs portably?]
|
|
|
|
See __fp_facets for Facets for Floating-Point Infinities and NaNs.
|
|
|
|
# ['Where are the pre-built libraries?]
|
|
|
|
Good news - you probably don't need any! - just `#include <boost/`['math/distribution_you_want>].
|
|
But in the unlikely event that you do, see __building.
|
|
|
|
# ['I don't see the function or distribution that I want.]
|
|
|
|
You could try an email to ask the authors - but no promises!
|
|
|
|
# ['I need more decimal digits for values/computations.]
|
|
|
|
You can use Boost.Math with __multiprecision: typically
|
|
__cpp_dec_float is a useful user-defined type to provide a fixed number of decimal digits, usually 50 or 100.
|
|
|
|
# Why can't I write something really simple like `cpp_int one(1); cpp_dec_float_50 two(2); one * two;`
|
|
|
|
Because `cpp_int` might be bigger than `cpp_dec_float can hold`, so you must make an [*explicit] conversion.
|
|
See [@http://svn.boost.org/svn/boost/trunk/libs/multiprecision/doc/html/boost_multiprecision/intro.html mixed multiprecision arithmetic]
|
|
and [@http://svn.boost.org/svn/boost/trunk/libs/multiprecision/doc/html/boost_multiprecision/tut/conversions.html conversion].
|
|
|
|
# ['How do I choose between Boost.Multiprecision cpp_bin_50 and cpp_dec_50?]
|
|
|
|
Unless you have a specific reason to choose `cpp_dec_`, then the default choice should be `cpp_bin_`, for example using the convenience `typedefs` like
|
|
`boost::multiprecision::cpp_bin_50` or `boost::multiprecision::cpp_bin_100`.
|
|
|
|
In general, both work well and give the same results and at roughly the same speed with `cpp_dec_50` sometimes faster.
|
|
|
|
cpp_dec_ was developed first paving the way for cpp_bin_. cpp_dec_ has several guard digits and is not rounded at all, using 'brute force' to get the promised number of decimal digits correct,
|
|
but making it difficult to reason about precision and computational uncertainty, for example
|
|
see [*https://svn.boost.org/trac10/ticket/12133].
|
|
It also has a fast but imprecise division operator giving surprising results sometimes,
|
|
see [*https://svn.boost.org/trac10/ticket/11178].
|
|
|
|
cpp_bin_ is correctly/exactly rounded making it possible to reason about both the precision and rounding of the results.
|
|
|
|
#['How do I see or report bugs and features, and request new functions?]
|
|
|
|
Currently open bug reports can be viewed
|
|
[@https://github.com/boostorg/math/issues here] on GITHUB.
|
|
|
|
All old bug reports including closed ones can be viewed on Trac (now read-only)
|
|
[@https://svn.boost.org/trac/boost/query?status=assigned&status=closed&status=new&status=reopened&component=math&col=id&col=summary&col=status&col=type&col=milestone&col=component&order=priority here]
|
|
and more recent issues on GIThub [@https://github.com/boostorg/math/issues?utf8=%E2%9C%93&q=is%3Aissue here].
|
|
|
|
#[' How can I tell if my compiler will work with Boost.Math?]
|
|
|
|
You should start by assuming that your compiler/platform *will* compile, even if it only supports a C++03 standard.
|
|
|
|
Boost in general does *not* 'support' a particular C++ standard or compiler or platform.
|
|
Each library has its own requirements, and for Boost.Math, each individual function or distribution
|
|
or tool may have different requirements and may or may not work on any particular compiler.
|
|
|
|
So the short answer is to try it and see what works for you.
|
|
|
|
Some recent functions are written to require more recent standards, even perhaps not-yet-standardized features.
|
|
Some clues about requirements can be gleaned from tests and examples (see jamfiles) and notes on requirements in documentation.
|
|
You can refer to the [@https://www.boost.org/development/tests/develop/developer/math.html Boost Test Matrix] to see the
|
|
current results for Boost.Math tests of many compilers on many platforms.
|
|
But bear in mind that the testing or demonstration code may use C++11 or higher features like
|
|
`std::numeric_limits<>max_digits10`, `auto`, `lambdas ...` for convenience;
|
|
these may not be needed for your application.
|
|
|
|
[endsect] [/section:faq Frequently Asked Questions]
|
|
|
|
[/
|
|
Copyright 2010, 2012 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).
|
|
]
|
|
|