Chapter 1: Introduction

1.1: About dVegas

dVegas is a library for adaptive Monte Carlo integration based on the VEGAS algorithm invented by G.P. Lepage. The "d" in dVegas stands for "discrete" and "decoded", because it extends Lepage's original VEGAS program in that it can not only handle continuous, but also discrete dimensions. dVegas is written as a C++ class in an object-oriented programming style, in an attempt to make its structure transparent and manifest. dVegas code was written to be robust and accessible, thus being more suited for customization and extension than the somewhat cryptic "black box" code of the original VEGAS program and its derivatives. For this purpose, dVegas was rewritten from scratch, with carefully chosen, meaningful variable names and comments. Its functionality is also made available to Fortran and C programmers through special interfaces. A parallel dVegas library is provided for use on multiprocessor machines.

A detailed description of G.P. Lepage's algorithm, its implementation in dVegas, as well as comparisons with and information about several earlier implementations, can be found in the references listed in section 8.

1.2: Platform notes

For up-to-date information regarding your platform consider visiting the dVegas Web site:
http://hepsource.org/dvegas/platforms.html

1.2.1: GNU Compiler Collection (GCC)

The dVegas libraries will compile and link with recent releases of the GNU compiler collection (GCC). To build all libraries g++, g77 and gcc are needed.

1.2.1.1: Intel/Linux

On Intel/Linux 2.2.5, gcc version egcs-2.91 (formely egcs-1.1.2) is known to work. Use the -fno-second-underscore option with g77.

1.2.2: Commercial compilers

1.2.2.1: Compaq/DEC

On Compaq Alpha platforms, the Compaq (formerly Digital) C++, Fortran and C compilers (cxx, f77, cc) should work. Success has been reported for Compaq C++ V6.2 and Compaq Fortran V5.3 on Alpha/Tru64 Unix 4.0F.

1.3: How to get dVegas

The distribution can be downloaded here:
http://sourceforge.net/projects/hepsource/

1.4: Installation

Obtain the source distribution as described in section 1.3. Then unpack the distribution tarball, for example with
gunzip -c dvegas-1.0.0.tar.gz | tar xf -
and change into the top directory. Installation proceeds in four steps
  1. Configuration: ./configure [--enable-fortran] [--enable-c] [--enable-getput]
  2. Build: make
  3. Test: make test
  4. Installation: mv lib/* destdir
which are described in more detail in the following sections.

The installation process works best with GNU make. If GNU make is available on your system I recommend you use GNU make instead of the vendor-supplied make program. If you have to use the latter consult section 1.4.6 for more information. If you can use GNU make, make sure that it is found before the vendor-supplied make and named 'make', so that the configure script can automatically detect it. You can use these commands, for example for tcsh:
setenv PATH ~/bin:${PATH}
ln -s /usr/local/bin/gmake ~/bin/make

1.4.1: Dependencies

dVegas needs random numbers to perform the numerical integration. The library, hence, relies on a random number generator that generates one or more random number streams.

Currently dVegas uses the CLHEP Random package to generate pseudo random numbers. If the CLHEP header files and library are installed in your compilers' search paths and you are using GNU make everything should be automatic. If you do have the CLHEP library and header files installed, but they are not automatically included by the linker, just set the variables LIBDIRCLHEP and INCLDIRCLHEP in the top-level Makefile. Otherwise, you need to obtain a CLHEP distribution for your platform (or the source code) from

http://wwwinfo.cern.ch/asd/lhc++/DISTRIBUTION/clhep.html

first and install it on your system (or ask your system administrator to do it). If you're not using GNU make and your compilers do not find the CLHEP files automatically, you'll have to modify all Makefiles. See section 1.4.6 for details.

Note that dVegas is not tied to CLHEP, and other random number generators can be integrated easily if the need arises.

1.4.2: Configuration

Remove traces of previous configurations with
make distclean

Then configure your distribution with
./configure [options]

To see a list of all options with brief descriptions do:
./configure --help

Special options for dVegas:

--enable-fortran
build Fortran interface

--enable-c
build C interface

--enable-getput
build "get/put" Fortran or C interface (serial only)

--with-gnu
use GNU compiler collection

The options --enable-fortran and --enable-c are exclusive. For details about --enable-getput see section 3.2. It is currently only available for the Fortran interface, but can be made available for the C interface on demand. The configure script tries to detect a viable compiler combination automatically. If you want to use GCC, but it is not automatically selected, you should specify the --with-gnu option when running configure. If you want to select the compilers used to build dVegas manually see section 1.4.6 for more information.

1.4.3: Build

make
builds one or more static libraries and copies them into the lib subdirectory. Consult section 1.4.6 if something goes wrong here.

1.4.4: Test

The libraries built in the previous step can be tested with small sample programs with
make test

This command creates a test executable for every library and tries to run it on your system. If the exit code indicates an error occured, the test fails. The diligent reader is encouraged to compare the obtained results with the expected results, which are recorded in the source files under subdirectory test.

1.4.5: Installation

The final installation step is to move the libraries in subdirectory lib into the library search path of the compiler (or use the -L linker flag to include this directory in the search path). Note that there is no make target install.

If you plan on using the C++ or C libraries you also have to copy the header files in subdirectory include to a suitable directory, so that the compiler can find them.

1.4.6: Troubleshooting

For up-to-date information about build problems and solutions consult the dVegas Web site:
http://hepsource.org/dvegas/troubleshooting.html

If you are using a vendor-supplied make that supports the export keyword, then just uncomment the corresponding line in the top-level Makefile. Otherwise certain variables will not be exported and you may have to define them in not only in the top-level Makefile, but also in the Makefiles in subdirectories. This applies particularly to the variables INCLDIRCLHEP, LIBCLHEP and LIBDIRCLHEP if the CLHEP files are not found automatically.

You can preselect specific compilers on your system to be used to build dVegas, by defining these variables:
CXX CXXCPP F77 CC

The first two have to be defined. Here's an example:

CXX=cxx CXXCPP=/lib/cpp F77=f77 ./configure --enable-fortran

1.5: Compiling and Linking with dVegas

1.5.1: C++

Fast track: read last paragraph

Compiling and linking C++ programs with dVegas should be straightforward. Just append -ldvegas to the compiler command. If your compiler cannot find the library you need to specify the path first: -Lpath -ldvegas

If you want to run your program in parallel mode on a multiprocessor machine, you have to link with the pthreads version -ldvegas_r. Some compilers will automatically link with the right version if you have -ldvegas specified. See section 5.1 for platform-specific details. Depending on the compiler you might have to link explicitly with libpthread or set a compiler flag like -pthread.

If the dVegas library utilizes CLHEP---typically it will---you also need to link to the CLHEP library. You need to specify the library after the dVegas library like in this example: -ldvegas -L/usr/local/lib/CLHEP -lCLHEP

To get started just run make test in the top-level directory. It will compile and link one or more test programs displaying the commands it uses. If the tests pass you can most likely just adapt these commands for your own programs.

1.5.2: Fortran

Fast track: read last paragraph

Compiling and linking Fortran programs with dVegas is slightly more complicated. You need to link to the Fortran dVegas library: -lf_dvegas or -Lpath -lf_dvegas. In addition the Fortran dVegas library needs to resolve references to standard C++ libraries that have to be specified after it, e.g. -lf_dvegas -L/usr/lib/cmplrs/cxx -lcxxstd -lcxx -lexc

If the dVegas library utilizes CLHEP---typically it will---you also need to link to the CLHEP library. A complete appendix will then look something like this: -lf_dvegas -L/usr/local/lib/CLHEP -lCLHEP -L/usr/lib/cmplrs/cxx -lcxxstd -lcxx -lexc

If you want to run your program in parallel mode on a multiprocessor machine, you have to link with the pthreads version -lf_dvegas_r. Some compilers will automatically link with the right version if you have -lf_dvegas specified. See section 5.1 for platform-specific details. Depending on the compiler you might have to link explicitly with libpthread or set a compiler flag like -pthread.

To get started just run make test in the top-level directory. It will compile and link one or more Fortran test programs displaying the commands it uses. If the tests pass you can most likely just adapt these commands for your own programs. An attempt is made to figure out the right standard C++ libraries automatically. If the test programs don't link on your system search for comments in section 1.2. If you don't find answers there, see section 1.6.

1.5.3: C

Fast track: read last paragraph

Compiling and linking C programs with dVegas is slightly more complicated. You need to link to the C dVegas library: -lc_dvegas or -Lpath -lc_dvegas. In addition the C dVegas library needs to resolve references to standard C++ libraries that have to be specified after it, e.g. -lc_dvegas -L/usr/lib/cmplrs/cxx -lcxxstd -lcxx -lexc

If the dVegas library utilizes CLHEP---typically it will---you also need to link to the CLHEP library. A complete appendix will then look something like this: -lc_dvegas -L/usr/local/lib/CLHEP -lCLHEP -L/usr/lib/cmplrs/cxx -lcxxstd -lcxx -lexc

If you want to run your program in parallel mode on a multiprocessor machine, you have to link with the pthreads version -lc_dvegas_r. Some compilers will automatically link with the right version if you have -lc_dvegas specified. See section 5.1 for platform-specific details. Depending on the compiler you might have to link explicitly with libpthread or set a compiler flag like -pthread.

To get started just run make test in the top-level directory. It will compile and link one or more C test programs displaying the commands it uses. If the tests pass you can most likely just adapt these commands for your own programs. An attempt is made to figure out the right standard C++ libraries automatically. If the test programs don't link on your system search for comments in section 1.2. If you don't find answers there, see section 1.6.

1.6: Support

Problem reports, comments and suggestions regarding this dVegas distribution should be emailed to nkauer@users.sourceforge.net

1.7: Porting dVegas

If you plan to test this dVegas distribution on a new platform or with a new compiler, please contact nkauer@users.sourceforge.net.

1.8: LGPL license

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA