Revamp documentation

NEWS.rst

@@ -1,6 +1,7 @@
 New in 0.2.2.9999:
 ==================
 
+- revamped documentation
 - changed function names of ``hep::cumulative_result`` and
   ``hep::chi_square_dof`` to the same names with a ``0`` and ``1`` at the end
   of their names; ``0`` uses the same algorithm as before, ``1`` weighs all

doc/Doxyfile.in

@@ -1,5 +1,6 @@
 AUTOLINK_SUPPORT       = NO
 BUILTIN_STL_SUPPORT    = YES
+BRIEF_MEMBER_DESC      = NO
 CITE_BIB_FILES         = @srcdir@/references.bib
 ENABLE_PREPROCESSING   = YES
 EXAMPLE_PATH           = @top_srcdir@/examples
@@ -11,7 +12,7 @@ HTML_FOOTER            = @srcdir@/footer.html
 HTML_OUTPUT            = @builddir@/html
 INPUT                  = @top_srcdir@/include @top_srcdir@/doc
 INTERNAL_DOCS          = NO
-JAVADOC_AUTOBRIEF      = YES
+JAVADOC_AUTOBRIEF      = NO
 FILE_PATTERNS          = *.cpp *.dox *.hpp
 LAYOUT_FILE            = @srcdir@/DoxygenLayout.xml
 MACRO_EXPANSION        = NO
@@ -21,7 +22,8 @@ PROJECT_NAME           = @PACKAGE_NAME@
 PROJECT_NUMBER         = @PACKAGE_VERSION@
 QUIET                  = YES
 RECURSIVE              = YES
-SHOW_INCLUDE_FILES     = NO
+REPEAT_BRIEF           = NO
+SHOW_FILES             = NO
 SHOW_USED_FILES        = NO
 SOURCE_BROWSER         = NO
 SORT_MEMBERS_CTORS_1ST = YES

doc/DoxygenLayout.xml

@@ -2,20 +2,21 @@
   <!-- Generated by doxygen 1.8.5 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
-    <tab type="mainpage" visible="yes" title=""/>
-    <tab type="pages" visible="yes" title="" intro=""/>
-    <tab type="modules" visible="yes" title="" intro=""/>
-    <tab type="namespaces" visible="yes" title="">
+    <tab type="mainpage" visible="yes" title="Introduction"/>
+    <tab type="pages" visible="no" title="" intro=""/>
+    <tab type="modules" visible="yes" title="Topics" intro=""/>
+    <tab type="namespaces" visible="no" title="">
       <tab type="namespacelist" visible="no" title="" intro=""/>
       <tab type="namespacemembers" visible="no" title="" intro=""/>
     </tab>
-    <tab type="classes" visible="yes" title="">
+    <tab type="user" url="@ref hep" title="API Listing"/>
+    <tab type="classes" visible="no" title="">
       <tab type="classlist" visible="no" title="" intro=""/>
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="classindex" visible="no" title=""/>
       <tab type="hierarchy" visible="no" title="" intro=""/>
       <tab type="classmembers" visible="no" title="" intro=""/>
     </tab>
-    <tab type="files" visible="yes" title="">
+    <tab type="files" visible="no" title="">
       <tab type="filelist" visible="no" title="" intro=""/>
       <tab type="globals" visible="no" title="" intro=""/>
     </tab>
@@ -26,7 +27,7 @@
   <class>
     <briefdescription visible="yes"/>
     <detaileddescription title=""/>
-    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includes visible="no"/>
     <inheritancegraph visible="$CLASS_GRAPH"/>
     <collaborationgraph visible="$COLLABORATION_GRAPH"/>
     <memberdecl>

doc/Makefile.am

@@ -10,12 +10,12 @@ EXTRA_DIST = \
 	global_configuration.dox \
 	integrands.dox \
 	mainpage.dox \
-	mc_helper.dox \
 	plain.dox \
 	references.bib \
 	results.dox \
 	vegas.dox \
-	vegas_callback.dox
+	vegas_callback.dox \
+	vegas_pdf.dox
 
 $(docpkg): Doxyfile $(EXTRA_DIST) $(top_builddir)/include/stamp-headers
 	$(AM_V_GEN)$(DOXYGEN) Doxyfile

doc/global_configuration.dox

@@ -1,5 +1,16 @@
 /**
 
-\defgroup global_configuration Global configuration
+\defgroup global_configuration Global Configuration Options
+
+\brief Specifying details of the integration algorithms
+
+To keep the number of arguments small that one has to pass to the integration functions the less
+frequently used arguments can be set as a global options, i.e. as a function call before the actual
+integration. For example, to use the grid refinement method employed by CUBA for integrand with
+sharp peaks in VEGAS, one first calls
+\code
+hep::vegas_cuba_refinement(true);
+\endcode
+All subsequent calls to VEGAS (including the MPI versions) will now use the CUBA refinement method.
 
 */

doc/integrands.dox

@@ -2,23 +2,19 @@
 
 \defgroup integrands Integrand Functions
 
-\brief The form of integrands that can be integrated by the `hep-mc` library.
+\brief How integrand functions are written
 
-Functions that are integrated by the Monte Carlo algorithms must accept a single parameter of the
-type \ref hep::mc_point and return a value of type `T`. For example, an integrand of the form
-\f[
-f(x) := x^2
-\f]
-for double precision numbers would look like:
+Functions that can be integrated by the Monte Carlo algorithms must accept a single parameter of the
+type \ref mc_point and return a value of type `T`. For example, an integrand of the form \f$
+f(x) := x^2 \f$ implemented with double precision numbers would like:
 \code
 double square(hep::mc_point<double> const& x)
 {
     return x.point[0] * x.point[0];
 }
 \endcode
-Some integration algorithms, e.g. the \ref vegas, supply additional information that can be accessed
-by capturing the argument with a different type, e.g. for VEGAS by `hep::vegas_point` instead of
-`hep::mc_point`:
+Some integration algorithms, e.g. \ref vegas, supply additional information that can be accessed by
+capturing the argument with a different type, e.g. for VEGAS by \ref vegas_point :
 \code
 double square(hep::vegas_point<double> const& x)
 {
@@ -44,7 +40,7 @@ struct integrand
     }
 };
 \endcode
-which would be called using the \ref plain by
+which would be called using \ref plain by
 \code
 hep::mc_result<double> result = hep::plain<double>(1, 1000, integrand(2.0));
 \endcode

doc/mainpage.dox

@@ -16,5 +16,32 @@ Example
 The following example illustrates how to integrate the square-function using
 VEGAS:
 \include vegas_example.cpp
+This program will produce the following output:
+\verbatim
+computing integral of x^2 from 0 to 1 which is 0.333333
+
+iteration 0 finished.
+this iteration: N=1000 E=0.33691 +- 0.00966589 (2.86898%)
+all iterations: N=1000 E=0.33691 +- 0.00966589 (2.86898%) chi^2/dof=inf
+
+iteration 1 finished.
+this iteration: N=1000 E=0.336297 +- 0.00381044 (1.13306%)
+all iterations: N=2000 E=0.33638 +- 0.00354493 (1.05385%) chi^2/dof=0.00347637
+
+iteration 2 finished.
+this iteration: N=1000 E=0.332836 +- 0.00176979 (0.531731%)
+all iterations: N=3000 E=0.333543 +- 0.00158343 (0.47473%) chi^2/dof=0.401838
+
+iteration 3 finished.
+this iteration: N=1000 E=0.332933 +- 0.00132342 (0.397504%)
+all iterations: N=4000 E=0.333184 +- 0.00101545 (0.304772%) chi^2/dof=0.296971
+
+iteration 4 finished.
+this iteration: N=1000 E=0.333122 +- 0.000828935 (0.248838%)
+all iterations: N=5000 E=0.333147 +- 0.000642145 (0.192751%) chi^2/dof=0.22328
+
+cumulative result (without first iteration):
+N=4000 I=0.33313 +- 0.000643567 chi^2/dof=0.246959
+\endverbatim
 
 */

doc/plain.dox

@@ -1,5 +1,17 @@
 /**
 
-\defgroup plain PLAIN Integrator
+\defgroup plain_group PLAIN Integrator
+
+\brief The PLAIN Monte Carlo integration algorithm
+
+The PLAIN Monte Carlo integration algorithm is the most simple integration that simply generates
+random numbers \f$ \vec{x}_i \in [0,1]^d \f$ in the \f$ d \f$-dimensional hypercube \f$ [0,1]^d \f$
+and averages the integrand evaluated at these points.
+
+The algorithm is available in two forms:
+
+- \ref plain, the single process interface and
+- \ref mpi_plain which uses the Message Passing Interface (MPI) to distribute the calculation among
+  parallel running processes.
 
 */

doc/results.dox

@@ -1,9 +1,15 @@
 /**
 
-\defgroup results Results and Further Processing
-
-\brief Obtaining results after completing integration and dealing with them.
+\defgroup results Results
 
+\brief Obtaining, combining and checking results
 
+Results can always be obtained by capturing the return-value of the integration functions. The types
+depend on the algorithm used, e.g. \ref plain returns an instance of \ref mc_result which stores
+the estimate of the integral, its error and the number of integrand calls used to obtain this
+result. The \ref vegas and \ref vegas_iteration functions return one or a vector of instances of
+\ref vegas_iteration_result that gives additional information about the PDF that was used during
+this iteration and the data accumulated that would be used to compute the PDF for the next
+iteration.
 
 */

doc/vegas.dox

@@ -1,5 +1,17 @@
 /**
 
-\defgroup vegas VEGAS Integrator
+\defgroup vegas_group VEGAS Integrator
+
+\brief The VEGAS Monte Carlo integration algorithm
+
+The VEGAS Monte Carlo integration algorithm divides the integration into several sub-integrations,
+called iterations, and uses the results to automatically construct a PDF that is then used to do
+importance sampling in order to reduce the error, e.g. compared to \ref plain.
+
+The VEGAS algorithm is available in two forms:
+
+- \ref vegas, the single process interface and
+- \ref mpi_vegas which uses the Message Passing Interface (MPI) to distribute the calculation among
+  parallel running processes.
 
 */

doc/vegas_callback.dox

@@ -2,29 +2,30 @@
 
 \defgroup vegas_callback_group VEGAS Callback Functions
 
-The VEGAS iteration callback functions.
+\brief Obtaining the results for each VEGAS iteration as soon as they are available
 
 VEGAS is an iterative algorithm, i.e. it produces intermediate results after each completed
 iteration. One usually wants to monitor these, e.g. to ensure results are converging. The callback
 mechanism lets the user do exactly this, by setting an appropriate callback function via
 \ref vegas_callback. This function is then called after each completed iteration.
 
-The function must accept a vector of \ref vegas_iteration_result that contains the iteration results
-so far. Furthermore it must return a boolean signaling if the VEGAS algorithm should proceed with
-the remaining iterations, i.e. if `false` is returned, VEGAS will stop and discard the remaining
-iterations. The MPI version of the callback must accept the MPI communicator as first argument in
-addition.
+The function must accept a vector of \ref vegas_iteration_result that will contain the results of
+every iteration performed so far. Using these results the function must decide if VEGAS should
+proceed with the remaining iterations (in that case the function returns `true`) or if VEGAS should
+stop and discard the remaining iterations (return `false`). In addition to the iteration results the
+MPI version of the callback must accept the MPI communicator as its first argument.
 
 This library comes with two predefined callback functions,
 
-  - \ref vegas_default_callback that is set by default and does nothing,
-  - \ref vegas_verbose_callback that prints both the result of recently completed iteration as well
-    as a cumulative result of all iterations and the corresponding chi-square,
+  - \ref vegas_default_callback that is set by default and does nothing and
+  - \ref vegas_verbose_callback that prints both the result of the recently completed iteration and
+    cumulative result (using \ref cumulative_result0) of all iterations and the corresponding
+    chi-square per degree of freedom (using \ref chi_square_dof0)
 
 for the \ref vegas functions, and the corresponding functions for their MPI counterpart,
 \ref mpi_vegas_default_callback and \ref mpi_vegas_verbose_callback.
 
-An example on how to use the reurn value to stop after a certain precision is reached is contained
-in \ref vegas_stop_after_precision.cpp.
+An example on how to use the return value to stop after a certain precision is reached is shown in
+\ref vegas_stop_after_precision.cpp.
 
 */

doc/vegas_pdf.dox

@@ -0,0 +1,8 @@
+/**
+
+\defgroup vegas_pdf_group VEGAS PDFs
+
+\brief Functions and Classes that implement that VEGAS grid
+
+
+*/

include/hep/mc/global_configuration.hpp

@@ -26,12 +26,12 @@ namespace hep
 /// @{
 
 /**
- * This function returns `true` if the MPI functions should use a single random number generator. If
- * this is the case the generator of each process discards an approriate amount of random numbers to
- * ascertain independent numbers are used. This make sure the result is independent of the number of
- * processes. However, since each process consumes as many random numbers as calls are made in
- * total, this may slow down the integration if the integrand evaluates too fast. In this case a
- * faster random number generator can be used.
+ * This function returns `true` the MPI functions use a single random number generator. This means
+ * that the generator of each processor discards an appropriate amount of random numbers to
+ * ascertain independent numbers are used. This make sure the result is independent of the number
+ * of processesor and the same as the non-MPI routine. Since each process consumes as many random
+ * numbers as calls are made in total, this may slow down the integration if the integrand evaluates
+ * too fast. In this case a faster random number generator should be used.
  */
 inline bool& mpi_single_generator()
 {
@@ -41,25 +41,34 @@ inline bool& mpi_single_generator()
 }
 
 /**
- * If `enabled` is true, the MPI function's results are independent of the number of processes used
- * to integrate.
+ * If `enabled` is `true` the MPI integration routines use a single random number generator so that
+ * results are independent from the number of processors, in particular the same result than the
+ * non-MPI integrators yield.
  *
- * \see mpi_single_generator
+ * \see \ref mpi_single_generator
  */
 inline void mpi_single_generator(bool enabled)
 {
 	mpi_single_generator() = enabled;
 }
 
-///
+/**
+ * Returns `true` if the VEGAS routines should use the grid refinement method of CUBA \cite Cuba for
+ * integrands with sharp edges. If the return value is `false` the original method is used. Default
+ * is `false`.
+ */
 inline bool& vegas_cuba_refinement()
 {
 	static bool use_cuba_refinement = false;
 
 	return use_cuba_refinement;
 }
 
-///
+/**
+ * If `enabled` is `true` the VEGAS routines use CUBA's grid refinement method.
+ *
+ * \see \ref vegas_cuba_refinement
+ */
 inline void vegas_cuba_refinement(bool enabled)
 {
 	vegas_cuba_refinement() = enabled;

include/hep/mc/mc_helper.hpp

@@ -35,7 +35,7 @@ using get_T = typename std::iterator_traits<Iterator>::value_type::numeric_type;
 namespace hep
 {
 
-/// \addtogroup mc_helper
+/// \addtogroup results
 /// @{
 
 /**

include/hep/mc/mc_result.hpp

@@ -25,7 +25,7 @@
 namespace hep
 {
 
-/// @addtogroup results
+/// \addtogroup results
 /// @{
 
 /**

include/hep/mc/mpi_plain.hpp

@@ -34,7 +34,7 @@
 namespace hep
 {
 
-/// \addtogroup plain
+/// \addtogroup plain_group
 /// @{
 
 /**