[Boost-commit] svn:boost r65668 - trunk/libs/math/doc/sf_and_dist

Subject: [Boost-commit] svn:boost r65668 - trunk/libs/math/doc/sf_and_dist
From: pbristow_at_[hidden]
Date: 2010-09-29 09:23:02

Author: pbristow
Date: 2010-09-29 09:23:00 EDT (Wed, 29 Sep 2010)
New Revision: 65668
URL: http://svn.boost.org/trac/boost/changeset/65668

Log:
New section.
Added:
   trunk/libs/math/doc/sf_and_dist/FAQ.qbk   (contents, props changed)

Added: trunk/libs/math/doc/sf_and_dist/FAQ.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/FAQ.qbk	2010-09-29 09:23:00 EDT (Wed, 29 Sep 2010)
@@ -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<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.  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 <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.] [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).
+]
+