diff --git a/Makefile.am b/Makefile.am index 7ba1b78..912916a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,6 +1,6 @@ ACLOCAL_AMFLAGS = -I m4 -EXTRA_DIST = README.rst +EXTRA_DIST = NEWS.rst README.rst # if doxygen is enabled include doc subdir if HAVE_DOXYGEN diff --git a/NEWS.rst b/NEWS.rst new file mode 100644 index 0000000..2e8cf2b --- /dev/null +++ b/NEWS.rst @@ -0,0 +1,30 @@ +New in 0.2.1.9999: +================== + +- added two examples showing the advanced use of the VEGAS integration routine +- added a callback mechanism for the VEGAS routines; this enables one to print + intermediate results from completed iterations +- added VEGAS routines to reuse an existing grid +- grids can now be easily saved to files with iostream shift operators, see the + example 'examples/read_linear_grid.cpp' which can be used with the grid file + in 'examples/grid_file' + +New in 0.2.1: +============= + +- added MPI-parallelized PLAIN integration algorithm +- lowered dependency on autotools features + +New in 0.2: +=========== + +- added new functions for combining several VEGAS results +- added MPI-based paralellized VEGAS integration algorithm +- improved documentation +- improved VEGAS performance + +New in 0.1: +=========== + +- added PLAIN integrator +- added VEGAS integrator diff --git a/README.rst b/README.rst index fd9a474..df83950 100644 --- a/README.rst +++ b/README.rst @@ -2,23 +2,48 @@ Project Description =================== ``hep-mc`` is a C++11 template library providing Monte Carlo integration -algorithms, currently only PLAIN and VEGAS. +algorithms, currently only PLAIN and VEGAS. In addition, this library comes with +MPI-parallelized routines. + +The aim of this project is to provide functions and classes that are: + +- *easily usable*, e.g. the default VEGAS routine can be called with only three + parameters. More can be given if the default parameters are not satisfactory, +- *templatized* in order to support a wide range of floating point types used to + perform the numerical computations (e.g. ``float``, ``double``, + ``long double`` and custom types), +- *modularized* which makes it easy to develop new integration algorithms on top + of known ones - e.g. VEGAS with a modified rebinning algorithm, +- *compatible* to the new C++11 random number generators [1]_. As a side effect, + it is possible to write and use custom generators, e.g. to generate + quasi-random numbers. + +Furthermore, for VEGAS + +- one can specify the sample size for each iteration separately; afterwards +- one can selectively include/exclude each iteration's result in a cumulative + estimate, +- it is possible to set the bin count to study its effect on the precision for + complicated integrands, for example. In other VEGAS implementations the bin + count is set to a fixed number, e.g. 50 in GSL and 128 in CUBA. Installation and Testing ======================== -hep-mc is a header-only library which requires no compilation. To install it, -use the usual sequence of commands for autotools-based projects, for example:: +``hep-mc`` is a header-only library which requires no compilation. To install +it, use the usual sequence of commands for autotools-based projects, for +example:: ./configure --prefix=/usr/local --enable-doxygen make make install -This will generate the Doxygen documentation for this library first and installs -it in the second step to /usr/local/doc/hep-ga. The headers are installed to -/usr/local/include. You may change these directories by specifying additional -options to ./configure. The following command gives you a complete list of -available configuration options:: +The ``prefix`` specifies the directory in which the library will be installed +to. If you enable Doxygen, ``make`` will generate the HTML documentation for +this library which will be installed as well. Note that you need a recent +version of this program [2]_. + +A complete list of configuration options is available by typing:: ./configure --help @@ -30,10 +55,8 @@ by autotools ... - run ``autoreconf -fiv`` to generate the files which are not under revision control -- if the last step failed, your autotools are most likely outdated. Update +- if the last step fails, your autotools are most likely outdated. Update autoconf and automake and try again. -Usage -===== - -See Doxygen documentation. +.. [1] See e.g. http://en.cppreference.com/w/cpp/numeric/random +.. [2] http://www.doxygen.org/