Imported Upstream version 1.72.0
[platform/upstream/boost.git] / libs / math / doc / html / math_toolkit / main_faq.html
1 <html>
2 <head>
3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Boost.Math Frequently Asked Questions (FAQs)</title>
5 <link rel="stylesheet" href="../math.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../index.html" title="Math Toolkit 2.11.0">
8 <link rel="up" href="../overview.html" title="Chapter&#160;1.&#160;Overview">
9 <link rel="prev" href="overview_tr1.html" title="C99 and C++ TR1 C-style Functions">
10 <link rel="next" href="contact.html" title="Contact Info and Support">
11 </head>
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
20 </tr></table>
21 <hr>
22 <div class="spirit-nav">
23 <a accesskey="p" href="overview_tr1.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="contact.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
24 </div>
25 <div class="section">
26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
27 <a name="math_toolkit.main_faq"></a><a class="link" href="main_faq.html" title="Boost.Math Frequently Asked Questions (FAQs)">Boost.Math Frequently Asked Questions
28     (FAQs)</a>
29 </h2></div></div></div>
30 <div class="orderedlist"><ol class="orderedlist" type="1">
31 <li class="listitem">
32 <p class="simpara">
33           <span class="emphasis"><em>I'm a FORTRAN/NAG/SPSS/SAS/Cephes/MathCad/R user and I don't
34           see where the functions like dnorm(mean, sd) are in Boost.Math?</em></span>
35         </p>
36 <p class="simpara">
37           Nearly all are provided, and many more like mean, skewness, quantiles,
38           complements ... but Boost.Math makes full use of C++, and it looks a bit
39           different. But do not panic! See section on construction and the many examples.
40           Briefly, the distribution is constructed with the parameters (like location
41           and scale) (things after the | in representation like P(X=k|n, p) or ;
42           in a common represention of pdf f(x; &#956;&#963;<sup>2</sup>). Functions like pdf, cdf are called
43           with the name of that distribution and the random variate often called
44           x or k. For example, <code class="computeroutput"><span class="identifier">normal</span> <span class="identifier">my_norm</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">my_norm</span><span class="special">,</span> <span class="number">2.0</span><span class="special">);</span></code>
45         </p>
46 </li>
47 <li class="listitem">
48 <p class="simpara">
49           I'm a user of <a href="http://support.sas.com/rnd/app/da/new/probabilityfunctions.html" target="_top">New
50           SAS Functions for Computing Probabilities</a>.
51         </p>
52 <p class="simpara">
53           You will find the interface more familar, but to be able to select a distribution
54           (perhaps using a string) see the Extras/Future Directions section, and
55           /boost/libs/math/dot_net_example/boost_math.cpp for an example that is
56           used to create a C# (C sharp) utility (that you might also find useful):
57           see <a href="http://sourceforge.net/projects/distexplorer/" target="_top">Statistical
58           Distribution Explorer</a>.
59         </p>
60 </li>
61 <li class="listitem">
62 <p class="simpara">
63           <span class="emphasis"><em>I'm allegic to reading manuals and prefer to learn from examples.</em></span>
64         </p>
65 <p class="simpara">
66           Fear not - you are not alone! Many examples are available for functions
67           and distributions. Some are referenced directly from the text. Others can
68           be found at <code class="computeroutput"><span class="special">\</span><span class="identifier">boost_latest_release</span><span class="special">\</span><span class="identifier">libs</span><span class="special">\</span><span class="identifier">math</span><span class="special">\</span><span class="identifier">example</span></code>,
69           for example If you are a Visual Studio user, you should be able to create
70           projects from each of these, making sure that the Boost library is in the
71           include directories list (there are usually NO libraries that must be built).
72         </p>
73 </li>
74 <li class="listitem">
75 <p class="simpara">
76           <span class="emphasis"><em>How do I make sure that the Boost library is in the Visual Studio
77           include directories list?</em></span>
78         </p>
79 <p class="simpara">
80           You can add an include path, for example, your Boost place /boost-latest_release,
81           for example <code class="computeroutput"><span class="identifier">X</span><span class="special">:/</span><span class="identifier">boost_1_70_0</span><span class="special">/</span></code>
82           if you have a separate partition X for Boost releases. Or you can use an
83           environment variable BOOST_ROOT set to your Boost place, and include that.
84           Visual Studio before 2010 provided Tools, Options, VC++ Directories to
85           control directories: Visual Studio 2010 instead provides property sheets
86           to assist. You may find it convenient to create a new one adding \boost-latest_release;
87           to the existing include items in $(IncludePath).
88         </p>
89 </li>
90 <li class="listitem">
91 <p class="simpara">
92           <span class="emphasis"><em>I'm a FORTRAN/NAG/SPSS/SAS/Cephes/MathCad/R user and I don't
93           see where the properties like mean, median, mode, variance, skewness of
94           distributions are in Boost.Math?</em></span>
95         </p>
96 <p class="simpara">
97           They are all available (if defined for the parameters with which you constructed
98           the distribution) via <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative
99           Distribution Function</a>, <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability
100           Density Function</a>, <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>,
101           <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.hazard">Hazard Function</a>,
102           <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.chf">Cumulative Hazard Function</a>,
103           <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>, <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.median">median</a>,
104           <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.mode">mode</a>, <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>,
105           <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
106           <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.skewness">skewness</a>, <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.kurtosis">kurtosis</a>, <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>,
107           <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.range">range</a> and <a class="link" href="dist_ref/nmp.html#math_toolkit.dist_ref.nmp.support">support</a>.
108         </p>
109 </li>
110 <li class="listitem">
111 <p class="simpara">
112           <span class="emphasis"><em>I am a C programmer. Can I user Boost.Math with C?</em></span>
113         </p>
114 <p class="simpara">
115           Yes you can, including all the special functions, and TR1 functions like
116           isnan. They appear as C functions, by being declared as "extern C".
117         </p>
118 </li>
119 <li class="listitem">
120 <p class="simpara">
121           <span class="emphasis"><em>I am a C# (Basic? F# FORTRAN? Other CLI?) programmer. Can I use
122           Boost.Math with C#? (or ...)?</em></span>
123         </p>
124 <p class="simpara">
125           Yes you can, including all the special functions, and TR1 functions like
126           isnan. But you <span class="bold"><strong>must build the Boost.Math as a dynamic
127           library (.dll) and compile with the /CLI option</strong></span>. See the boost/math/dot_net_example
128           folder which contains an example that builds a simple statistical distribution
129           app with a GUI. See <a href="http://sourceforge.net/projects/distexplorer/" target="_top">Statistical
130           Distribution Explorer</a>
131         </p>
132 </li>
133 <li class="listitem">
134 <p class="simpara">
135           <span class="emphasis"><em>What these "policies" things for?</em></span>
136         </p>
137 <p class="simpara">
138           Policies are a powerful (if necessarily complex) fine-grain mechanism that
139           allow you to customise the behaviour of the Boost.Math library according
140           to your precise needs. See <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policies</a>. But
141           if, very probably, the default behaviour suits you, you don't need to know
142           more.
143         </p>
144 </li>
145 <li class="listitem">
146 <p class="simpara">
147           <span class="emphasis"><em>I am a C user and expect to see global C-style<code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> set for overflow/errors etc?</em></span>
148         </p>
149 <p class="simpara">
150           You can achieve what you want - see <a class="link" href="pol_ref/error_handling_policies.html" title="Error Handling Policies">error
151           handling policies</a> and <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">user
152           error handling</a> and many examples.
153         </p>
154 </li>
155 <li class="listitem">
156 <p class="simpara">
157           <span class="emphasis"><em>I am a C user and expect to silently return a max value for overflow?</em></span>
158         </p>
159 <p class="simpara">
160           You (and C++ users too) can return whatever you want on overflow - see
161           <a class="link" href="error_handling.html#math_toolkit.error_handling.overflow_error">overflow_error</a>
162           and <a class="link" href="pol_ref/error_handling_policies.html" title="Error Handling Policies">error
163           handling policies</a> and several examples.
164         </p>
165 </li>
166 <li class="listitem">
167 <p class="simpara">
168           <span class="emphasis"><em>I don't want any error message for overflow etc?</em></span>
169         </p>
170 <p class="simpara">
171           You can control exactly what happens for all the abnormal conditions, including
172           the values returned. See <a class="link" href="error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>,
173           <a class="link" href="error_handling.html#math_toolkit.error_handling.overflow_error">overflow_error</a>
174           <a class="link" href="pol_ref/error_handling_policies.html" title="Error Handling Policies">error handling
175           policies</a> <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">user
176           error handling</a> etc and examples.
177         </p>
178 </li>
179 <li class="listitem">
180 <p class="simpara">
181           <span class="emphasis"><em>My environment doesn't allow and/or I don't want exceptions.
182           Can I still user Boost.Math?</em></span>
183         </p>
184 <p class="simpara">
185           Yes but you must customise the error handling: see <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">user
186           error handling</a> and <a class="link" href="pol_ref/policy_defaults.html" title="Using Macros to Change the Policy Defaults">changing
187           policies defaults</a> .
188         </p>
189 </li>
190 <li class="listitem">
191 <p class="simpara">
192           <span class="emphasis"><em>The docs are several hundreds of pages long! Can I read the docs
193           off-line or on paper?</em></span>
194         </p>
195 <p class="simpara">
196           Yes - you can download the Boost current release of most documentation
197           as a zip of pdfs (including Boost.Math) from Sourceforge, for example
198           <a href="https://sourceforge.net/projects/boost/files/boost-docs/1.45.0/boost_pdf_1_45_0.tar.gz/download" target="_top">https://sourceforge.net/projects/boost/files/boost-docs/1.45.0/boost_pdf_1_45_0.tar.gz/download</a>.
199           And you can print any pages you need (or even print all pages - but be
200           warned that there are several hundred!). Both html and pdf versions are
201           highly hyperlinked. The entire Boost.Math pdf can be searched with Adobe
202           Reader, Edit, Find ... This can often find what you seek, a partial substitute
203           for a full index.
204         </p>
205 </li>
206 <li class="listitem">
207 <p class="simpara">
208           <span class="emphasis"><em>I want a compact version for an embedded application. Can I use
209           float precision?</em></span>
210         </p>
211 <p class="simpara">
212           Yes - by selecting RealType template parameter as float: for example normal_distribution&lt;float&gt;
213           your_normal(mean, sd); (But double may still be used internally, so space
214           saving may be less that you hope for). You can also change the promotion
215           policy, but accuracy might be much reduced.
216         </p>
217 </li>
218 <li class="listitem">
219 <p class="simpara">
220           <span class="emphasis"><em>I seem to get somewhat different results compared to other programs.
221           Why?</em></span>
222         </p>
223 <p class="simpara">
224           We hope Boost.Math to be more accurate: our priority is accuracy (over
225           speed). See the section on accuracy. But for evaluations that require iterations
226           there are parameters which can change the required accuracy (see <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policies</a>). You might be able to squeeze a little
227           more (or less) accuracy at the cost of runtime.
228         </p>
229 </li>
230 <li class="listitem">
231 <p class="simpara">
232           <span class="emphasis"><em>Will my program run more slowly compared to other math functions
233           and statistical libraries?</em></span>
234         </p>
235 <p class="simpara">
236           Probably, thought not always, and not by too much: our priority is accuracy.
237           For most functions, making sure you have the latest compiler version with
238           all optimisations switched on is the key to speed. For evaluations that
239           require iteration, you may be able to gain a little more speed at the expense
240           of accuracy. See detailed suggestions and results on <a class="link" href="../perf.html" title="Chapter&#160;21.&#160;Performance">performance</a>.
241         </p>
242 </li>
243 <li class="listitem">
244 <p class="simpara">
245           <span class="emphasis"><em>How do I handle infinity and NaNs portably?</em></span>
246         </p>
247 <p class="simpara">
248           See <a class="link" href="fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">nonfinite fp_facets</a> for
249           Facets for Floating-Point Infinities and NaNs.
250         </p>
251 </li>
252 <li class="listitem">
253 <p class="simpara">
254           <span class="emphasis"><em>Where are the pre-built libraries?</em></span>
255         </p>
256 <p class="simpara">
257           Good news - you probably don't need any! - just <code class="computeroutput"><span class="preprocessor">#include</span>
258           <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span></code><span class="emphasis"><em>math/distribution_you_want&gt;</em></span>.
259           But in the unlikely event that you do, see <a class="link" href="building.html" title="If and How to Build a Boost.Math Library, and its Examples and Tests">building
260           libraries</a>.
261         </p>
262 </li>
263 <li class="listitem">
264 <p class="simpara">
265           <span class="emphasis"><em>I don't see the function or distribution that I want.</em></span>
266         </p>
267 <p class="simpara">
268           You could try an email to ask the authors - but no promises!
269         </p>
270 </li>
271 <li class="listitem">
272 <p class="simpara">
273           <span class="emphasis"><em>I need more decimal digits for values/computations.</em></span>
274         </p>
275 <p class="simpara">
276           You can use Boost.Math with <a href="../../../../../libs/multiprecision/doc/html/index.html" target="_top">Boost.Multiprecision</a>:
277           typically <a href="../../../../../libs/multiprecision/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html" target="_top">cpp_dec_float</a>
278           is a useful user-defined type to provide a fixed number of decimal digits,
279           usually 50 or 100.
280         </p>
281 </li>
282 <li class="listitem">
283 <p class="simpara">
284           Why can't I write something really simple like <code class="computeroutput"><span class="identifier">cpp_int</span>
285           <span class="identifier">one</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> <span class="identifier">cpp_dec_float_50</span>
286           <span class="identifier">two</span><span class="special">(</span><span class="number">2</span><span class="special">);</span> <span class="identifier">one</span>
287           <span class="special">*</span> <span class="identifier">two</span><span class="special">;</span></code>
288         </p>
289 <p class="simpara">
290           Because <code class="computeroutput"><span class="identifier">cpp_int</span></code> might be
291           bigger than <code class="computeroutput"><span class="identifier">cpp_dec_float</span> <span class="identifier">can</span> <span class="identifier">hold</span></code>,
292           so you must make an <span class="bold"><strong>explicit</strong></span> conversion.
293           See <a href="http://svn.boost.org/svn/boost/trunk/libs/multiprecision/doc/html/boost_multiprecision/intro.html" target="_top">mixed
294           multiprecision arithmetic</a> and <a href="http://svn.boost.org/svn/boost/trunk/libs/multiprecision/doc/html/boost_multiprecision/tut/conversions.html" target="_top">conversion</a>.
295         </p>
296 </li>
297 <li class="listitem">
298 <p class="simpara">
299           <span class="emphasis"><em>How do I choose between Boost.Multiprecision cpp_bin_50 and cpp_dec_50?</em></span>
300         </p>
301 <p class="simpara">
302           Unless you have a specific reason to choose <code class="computeroutput"><span class="identifier">cpp_dec_</span></code>,
303           then the default choice should be <code class="computeroutput"><span class="identifier">cpp_bin_</span></code>,
304           for example using the convenience <code class="computeroutput"><span class="identifier">typedefs</span></code>
305           like <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_bin_50</span></code> or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_bin_100</span></code>.
306         </p>
307 <p class="simpara">
308           In general, both work well and give the same results and at roughly the
309           same speed with <code class="computeroutput"><span class="identifier">cpp_dec_50</span></code>
310           sometimes faster.
311         </p>
312 <p class="simpara">
313           cpp_dec_ was developed first paving the way for cpp_bin_. cpp_dec_ has
314           several guard digits and is not rounded at all, using 'brute force' to
315           get the promised number of decimal digits correct, but making it difficult
316           to reason about precision and computational uncertainty, for example see
317           <span class="bold"><strong>https://svn.boost.org/trac10/ticket/12133</strong></span>.
318           It also has a fast but imprecise division operator giving surprising results
319           sometimes, see <span class="bold"><strong>https://svn.boost.org/trac10/ticket/11178</strong></span>.
320         </p>
321 <p class="simpara">
322           cpp_bin_ is correctly/exactly rounded making it possible to reason about
323           both the precision and rounding of the results.
324         </p>
325 </li>
326 <li class="listitem">
327 <p class="simpara">
328           <span class="emphasis"><em>How do I see or report bugs and features, and request new functions?</em></span>
329         </p>
330 <p class="simpara">
331           Currently open bug reports can be viewed <a href="https://github.com/boostorg/math/issues" target="_top">here</a>
332           on GITHUB.
333         </p>
334 <p class="simpara">
335           All old bug reports including closed ones can be viewed on Trac (now read-only)
336           <a href="https://svn.boost.org/trac/boost/query?status=assigned&amp;status=closed&amp;status=new&amp;status=reopened&amp;component=math&amp;col=id&amp;col=summary&amp;col=status&amp;col=type&amp;col=milestone&amp;col=component&amp;order=priority" target="_top">here</a>
337           and more recent issues on GIThub <a href="https://github.com/boostorg/math/issues?utf8=%E2%9C%93&amp;q=is%3Aissue" target="_top">here</a>.
338         </p>
339 </li>
340 <li class="listitem">
341           <span class="emphasis"><em>How can I tell if my compiler will work with Boost.Math?</em></span>
342         </li>
343 </ol></div>
344 <p>
345       You should start by assuming that your compiler/platform <span class="bold"><strong>will</strong></span>
346       compile, even if it only supports a C++03 standard.
347     </p>
348 <p>
349       Boost in general does <span class="bold"><strong>not</strong></span> 'support' a particular
350       C++ standard or compiler or platform. Each library has its own requirements,
351       and for Boost.Math, each individual function or distribution or tool may have
352       different requirements and may or may not work on any particular compiler.
353     </p>
354 <p>
355       So the short answer is to try it and see what works for you.
356     </p>
357 <p>
358       Some recent functions are written to require more recent standards, even perhaps
359       not-yet-standardized features. Some clues about requirements can be gleaned
360       from tests and examples (see jamfiles) and notes on requirements in documentation.
361       You can refer to the <a href="https://www.boost.org/development/tests/develop/developer/math.html" target="_top">Boost
362       Test Matrix</a> to see the current results for Boost.Math tests of many
363       compilers on many platforms. But bear in mind that the testing or demonstration
364       code may use C++11 or higher features like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;</span><span class="identifier">max_digits10</span></code>,
365       <code class="computeroutput"><span class="keyword">auto</span></code>, <code class="computeroutput"><span class="identifier">lambdas</span>
366       <span class="special">...</span></code> for convenience; these may not be
367       needed for your application.
368     </p>
369 </div>
370 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
371 <td align="left"></td>
372 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
373       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
374       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
375       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
376       Daryle Walker and Xiaogang Zhang<p>
377         Distributed under the Boost Software License, Version 1.0. (See accompanying
378         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
379       </p>
380 </div></td>
381 </tr></table>
382 <hr>
383 <div class="spirit-nav">
384 <a accesskey="p" href="overview_tr1.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="contact.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
385 </div>
386 </body>
387 </html>