Chapter 1: Essentials

1.1: About Dvegas

Dvegas facilitates adaptive Monte Carlo integration based on an enhanced and extended version of Peter Lepage's VEGAS algorithm. It allows to automatically take into account correlations between sets of dimensions, and allows to fully adapt the sampling of sums of integrals. The code is genuinely object-oriented, written in ISO/ANSI standard C++, makes extensive use of the C++ Standard Library and includes an interface to OmniComp.

OmniComp is an intuitive system that is easy to install and use which allows to accelerate Monte Carlo programs through distributed execution on workstation clusters or PC farms as well as multi- processor machines. It is based on omniORB, a high-performance, open-source CORBA implementation from AT&T Laboratories Cambridge. Notably, it does not require thread-safe integrand implementations.

The D in Dvegas stands for decoded and deconstructed, because the somewhat cryptic "black box" code of the original VEGAS program and its derivatives was decoded and the algorithm recoded from scratch, in a modern, highly modular, const-correct object-oriented way, aggressively applying modern software development fundamentals and best practices as layed out in Bjarne Stroustrup's "The C++ Programming Language", Andy Hunt and Dave Thomas's "The Pragmatic Programmer", Scott Meyers's "Effective C++" and Martin Fowler's "Refactoring". The resulting code is well-structured, accessible and robust, thus being well suited for easy and safe modification and extension.

A detailed description of the VEGAS algorithm, its enhanced and extended implementation in Dvegas, as well as comparisons with and information about several earlier implementations, can be found in the references listed in section 4.

1.2: Platform notes

In principle, Dvegas can be built with any sufficiently standard compliant C++ compiler on any platform. In practice, Dvegas has been sucessfully employed in the following environments:

1.2.1: GNU C++ compiler

Programs based on Dvegas will compile and link with recent releases (3.x) of the C++ compiler of the GNU compiler collection, which can be obtained at http://gcc.gnu.org.

1.2.1.1: Linux/i386

gcc-3.0 on Red Hat Linux 7 with Intel Pentium III, Intel Xeon or AMD Athlon is known to work.

1.2.1.2: Tru64 Unix/Alpha

gcc-3.0 on Compaq Tru64 Unix 5 with DEC Alpha EV6.7 is known to work.

1.2.1.3: Windows2000/i386

gcc-3.0 on Windows2000 with Pentium III is known to work. See README.win32 for special instructions.

1.2.2: Compaq C++ compiler

The Compaq C++ compiler cxx is available for Alpha platforms with either Tru64 Unix or Linux.
http://www.compaq.com/products/software/compilers/candcxx.html

1.2.2.1: Tru64 Unix/Alpha

Compaq C++ V6.3 on Compaq Tru64 Unix 5 with DEC Alpha EV6.7 is known to work.

If you are working on Linux/Alpha with either g++ or cxx and find Dvegas to work please drop me a note.

For up-to-date information about supported platforms visit
http://hepsource.org/dvegas/platforms.html

1.3: How to get Dvegas

The Dvegas source code can be downloaded as .tar.gz archives or via CVS here:
http://sourceforge.net/projects/hepsource/

The .tar.gz archives can, for example, be unpacked with
gunzip -c dvegas-2.0.0.tar.gz | tar xf -

1.4: Using Dvegas

How to use Dvegas in your programs and its capabilities are illustrated with the help of two demo programs (also see section 2). Copy the sample Makefile for your compiler to Makefile, possibly edit it, and run make. If more than one compiler is installed on your system, make sure the correct compiler is used, i.e. comes first in your path. The build process will attempt to create the following demo programs:
dvegas_demo and omnicomp_demo

Note that in order to build omnicomp_demo, omniORB headers and libraries need to be available on your system and the corresponding Makefile variables set appropriately. Please refer to section 3 for more information.

1.5: Random Number Generation

To allow easy substitution of the random number generator employed by Dvegas, the RandomNumberGenerator interface defined in rng.h is used. Three implementations are provided:

1.5.1: Built-in: ranlux.cpp

For convenience, the Dvegas distribution includes code in ranlux.cpp that provides a default random number generator based on Martin Luscher's chaos theory-improved RANLUX algorithm, which has excellent characteristics. To vary the seed go to the top of the file and modify the setting of seedForGSLRandomNumberGenerator.

1.5.2: Class Library for High Energy Physics (CLHEP)

The Random package of the CLHEP library provides C++ implementations for a variety of quality random number generators. If CLHEP headers and library are available on your system, you can use any CLHEP random number generator by setting the corresponding Makefile variables appropriately, and linking with clhep_rng.o instead of ranlux.o. The sample Makefiles include an example. The default CLHEP random number generator is RANLUX. To select a different generator, simply replace RanluxEngine in the following line in clhep_rng.cpp:
RandomNumberGenerator *const randomNumberGenerator = new CLHEPRandomNumberGenerator(new RanluxEngine(), 19780503, 3);

1.5.3: GNU Scientific Library (GSL)

The Random Number Generation module of the GSL library provides C implementations for a variety of quality random number generators. If GSL headers and library are available on your system, you can use any GSL random number generator by setting the corresponding Makefile variables appropriately, and linking with gsl_rng.o instead of ranlux.o. The sample Makefiles include an example. The default GSL random number generator is RANLUX. To select a different generator, simply replace gsl_rng_ranlxs1 in the following line in gsl_rng.cpp:
RandomNumberGenerator *const randomNumberGenerator = new GSLRandomNumberGenerator(gsl_rng_alloc(gsl_rng_ranlxs1), 19780503);

1.6: Troubleshooting and Support

For up-to-date information about Dvegas-related problems and solutions visit
http://hepsource.org/dvegas/troubleshooting.html

Problems not addressed there should be sent to hepsource-support@lists.sourceforge.net. Comments and suggestions should be sent to hepsource-devel@lists.sourceforge.net.

1.7: Porting Dvegas

If you want to use Dvegas on a new platform or with a new compiler, please contact hepsource-devel@lists.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