doc/overview/faq.qbk

[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 representation 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 familiar, 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 allergic 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).
]