Install BAMPSBAMPS is developed and tested on Linux systems. In principle however, the code should be rather platform independent and should be able to e.g. run on Windows or MacOS with little to no modifications. The following software and libraries are necessary in order to build the BAMPS source code:
CMake (Cross Platform Make)
Version >= 2.6br
CMake is the build system used by BAMPS. It is used by many open source projects and should be available in basically any Linux distribution.
Version >= 1.40br
The Boost C++ libraries provide functions that go beyond standard C++. BAMPS for example relies on Boost to generate random numbers (see random.h) in a way that allows for a flexible incorporation of different random number generators. Furthermore Boost is used to parse program options from input files or the command line, to dump data files that allow for later reconstruction of BAMPS events, etc.
There exist two types of Boost libraries, header-only libraries that
require no building of libraries at all and separately-compiled
libraries that need to be built (or installed via the Linux
distribution). As of r218 the [source:full/trunk/ main version of BAMPS]
depends on Boost libraries that need to be built. Currently the binary
Most Linux distributions provide packages for the Boost libraries. Note however, that the libraries are evolving rather rapidly and thus packages provided by distributions might be outdated. Furthermore changes in the naming scheme of Boost libraries have occurred that might cause issues with the scripts of the build system trying to locate the libraries. Manual fine tuning might be necessary in these cases (should however be necessary only on rare occasions).
Obtaining and building Boost
Detailed instructions on building the Boost libraries on Linux systems (if not provided by the distribution) can be found at
What follows is a very short instruction on how to build and install the boost libraries as needed for BAMPS. It should be sufficient in most cases, but please refer to the boost homepage for more details.
Assuming that you are at the root of the directory in which the Boost source has been extracted, do the following:
This will install the Boost headers to
User-based and system-wide Boost installations
When both a system-wide and a user-based installation of Boost are present, BAMPS should be configured such that the user-based installation is used.
When Boost has been installed to the prefix
Failing to do so might result in viscous linking errors due to version conflicts between the Boost headers and the Boost binary libraries. This happens when
In this case the Boost headers might get included from the user-based installation, while the binary libraries are taken from the system-wide installation. This cannot be easily prevented within the build system as fixing such mixtures of include and linking directories would require dirty and inflexible hacks on the level of the linking options. The scenario is therefore not supported.
LHAPDF library (optional)
Version >= 5.4, < 6.0br
> NOTE: If you want to prepare for the new v6.0 of LHAPDF, here some hints:
> * the option
> * you probably have to install yaml-cpp. You can get it at http://code.google.com/p/yaml-cpp and compile it yourself, while switching on building of shared libraries explicitely: cmake -DBUILD_SHARED_LIBS=on ..
> * there is no lhpdf-getdata anymore
> * the members of the namespace LHAPDF have changed, the BAMPS code has to be changed
As of r351 BAMPS supports the usage of the LHAPDF library that provides parton distribution functions (PDF). Currently the usage of LHAPDF is optional, i.e. the code compiles and runs without it (in this case falling back to a built-in parametrization of the GRV PDFs), but this might change in the future.
Information on how to actually use the LHAPDF interface together with BAMPS can be found in the [wiki:RestrictedWiki/ManualsAndReadmes#UsageandconfigurationofLHAPDFdatasets usage manual], this section only describes the installation of LHAPDF.
LHAPDF can be obtained from
where also extensive information on the available PDF sets can be found. BAMPS has been tested to work with version 5.8.6, but in general versions >= 5.4 AND < 6.0.0 (!!!) should be fine (see comment above).
In order to install the LHAPDF library download the
chain of commands to configure, build and install the library. Change
the location of the installed files by adjusting the
Obtaining and installing PDF sets
The LHAPDF library from version 5.7.1 on does not include any PDF sets by default. These need to be downloaded and installed separately. This can either be done manually by downloading individual sets from the LHAPDF homepage and putting the files into a folder called
in the case of an installation prefix as in the above example) or by using the download script that is provided by the library (see below). The latter option is of course recommended.
The download script
GNU Scientific Library (GSL)
Version >= 1.14 (earlier versions probably work as well)br
BAMPS makes use of routines from the GNU Scientific Library (GSL) for numerical interpolation, sampling from given probability distributions, etc. The usage of GSL is likely to be extended in the future in order to remove the last dependencies on legacy routines from Numerical Recipies.
GSL is available from packages provided by virtually all Linux
distributions. For example, when using Ubuntu, install the package
Version >= 2.0br (At the moment only versions 2.0 and 2.1 are officially supported.)
The Cuba library provides routines for numerical integration based on various methods. Though currently not used it is implemented into the integration routines and can be easily switched to (see [source:lib/src/integrate.h integrate.h] and e.g. the preprocessor macros in [source:lib/src/scattering32.cpp scattering32.cpp]). Thus the current version of BAMPS requires the Cuba library to build. To do this download the package from http://www.feynarts.de/cuba/ and extract the source files. Run in the extracted folder
In the folder is now the header file (cuba.h) and a library file
(libcuba.a). Copy the header file to the include path (usually
$HOME/usr/include) and the library file to the lib path (usually
$HOME/usr/lib). The [source:full/trunk/cmake_modules/FindCuba.cmake
custom CMake module] provided with BAMPS searches for the Cuba library
in the default places (e.g.
Please note that the current version of BAMPS (as of [changeset:30 revision 30]) is not compatible with Cuba versions older than 2.0 any more.
PYTHIA event generator (optional)
Version >= 8.180br
Version >= 8.2 is not tested and does not work at the moment.br
PYTHIA is a possible option to sample online the initial momenta of the particles. In addition, preprocessed files for PYTHIA initial conditions can also read in from a file. In this case the file has to be produced before, and PYTHIA itself must not be linked to BAMPS. However, the first option is recommended.
Furthermore, PYTHIA is used for the decay of heavy flavor mesons.
To use online PYTHIA initial conditions or heavy flavor decays download PYTHIA from http://home.thep.lu.se/~torbjorn/Pythia.html and unzip it to your desired path. You have to modify two files to link it properly to BAMPS:
1. Open <path to PYTHIA>/src/Pythia.cc and add the following code outside the Pythia8 namespace:
2. Replace the file <path to PYTHIA>/include/Pythia8/LHAPDFInterface.h with this file: [attachment:LHAPDFInterface.h] (tested with version PYTHIA 8.175)
3. Replace the file <path to PYTHIA>/lhapdfdummy/LHAPDFDummy.cc with this file: [attachment:LHAPDFDummy.cc] (tested with version PYTHIA 8.175)
In typical versions like 8.186 (most recent version < 8.2), shared libraries are not created by default. Use
before you run
in the main PYTHIA folder <path to PYTHIA>. (Otherwise, 'make' will run 'configure' automatically with default settings, and does not generate the .so files.)
After compiling create some soft links in $HOME/usr to use PYTHIA in BAMPS:
It is highly recommended to also install LHAPDF since it is needed to use a shadowing parametrization or more advanced parton distribution functions.
How to Build
Usage of CMake
BAMPS uses CMake as a build system, see [#depSectionId dependencies] above.
The instructions below are valid on Linux systems, the steps necessary on Windows should be similar though. "~$ " indicates the terminal prompt. Arguments given in < > are mandatory, arguments given in [ ] are optional.
Short version: In the main directory of the program (e.g. in
Then configure the build directory with
to actually compile and build the source.
In general the code should be built in a separate directory (e.g.
Suppose the source (e.g. [source:full/trunk/]) has been extracted into a folder ~/BAMPS. Now a subfolder ~/BAMPS/build is created in which the program should be built. In order to build with the standard options, first change into the subfolder and then issue cmake followed by make.
If all goes well the executable (e.g. called
In order to see a more detailed output of the make processes, try
On a side note, a convenient option to make is -j n or --jobs=n that tells make to spawn multiple jobs for the build process. On a multi-core machine this can considerably speed up the compilation process. So, for example, on a machine with a CPU that has 4 cores, one could issue
Omitting the blank also seems to work, i.e. -j4 instead of -j 4.
Build options specific to BAMPS
The most important option to CMake is usually
Without any further configuration CMake uses the default compiler of the system, which is
In addition to
The first part indicates the compiler in use, currently the GNU compiler gcc (http://gcc.gnu.org/), the Intel compiler icc (http://software.intel.com/sites/products/documentation/hpc/compilerpro/en-us/cpp/lin/compiler_c/index.htm) and AMD's variant of the open64 compiler (http://developer.amd.com/tools/open64/pages/default.aspx).
The different variants for each compiler are meant to be tailored to specific system architectures. The Intel compiler has been found to significantly outperform the other compilers in various test cases - your mileage may vary though.
See the section on
compiler-based optimization] for background information on the various
optimization options available via different compilers and especially
for details on using profile-guided optimization (PGO) via
Disabling build extras (svn info and doxygen)
By default the BAMPS build system provides some goodies:
In case this is not desired, these goodies can be deactivated by virtue of the
When the source is not a valid svn working copy, the usage of this
option is currently mandatory as due to design flaws in the
Creating a source tarball for distribution
in the main
Creating documentation from the source code
BAMPS uses the tool [http://www.doxygen.org Doxygen] for generating documentation of the source code. Doxygen scans the source code and automatically documents classes, files, functions, etc. But in order to provide useful documentation the source code needs to be thoroughly commented - in a way that is recognized by Doxygen. See [http://www.stack.nl/~dimitri/doxygen/manual.html here] for instructions. Please always adhere to the [http://www.stack.nl/~dimitri/doxygen/docblocks.html Doxygen conventions] for commenting the source code when writing new routines and help documenting existing routines wherever possible. This will further improve the usefulness of this documentation.
Based on the Doxygen system, an up-to-date documentation of the trunk versions of [source:full/trunk/ full] and [source:box/trunk/ box] is provided in nightly builds of the source code in the trac system under [/doxygen API documentation].
In case a manual generation of the documentation is needed, simply issue
in a previously configured build directory (see above). The
configuration of the Doxygen documentation is based on the template file
This section is meant to supplement the information on [wiki:RestrictedWiki/BuildInstructions#BuildoptionsspecifictoBAMPS BAMPS-specific build options]. While the aforementioned instructions detail how to activate certain options during the build processes of BAMPS, the present section provides background information on the capabilities of certain compilers. It is therefore meant for people that are (a) curios, (b) want to modify the BAMPS optimization flags (e.g. in [source:full/trunk/SetCompilersAndBuildFlags.cmake]) or (c) would like some hints on how to optimize other programs.BR
So, here's how to use your compiler to optimize the s* out of your code:
When working on Linux (and this is the only scenario that is discussed
here), the [http://gcc.gnu.org/ GNU compiler
By the way, when using gcc without CMake as a build system, these
options could either be given as command line parameters when compiling
or could be assigned to the environment variable
When gcc with
The GNU compiler is an incredible piece of software. It is one of the most widely used C and C++ compilers out there, it supports virtually all platforms, it is one of the most standard-compliant compilers and it is for free! This said, commercial software might (!) beat gcc in some disciplines. The [http://en.wikipedia.org/wiki/Intel_C%2B%2B_Compiler Intel C++ compiler icc] is such a piece of commercial software. It is considered to be the C++ compiler that produces the most performant, i.e. the fastest, code. It can vectorize (parallelize) loops, use interprocedural optimization (IPO), use profile-guided optimization (PGO) and tailors the compiled code to available hardware, making excessive use of processor-specific instruction sets. The latter is of course especially true for Intel processors on which icc-compiled code performs best. Intel makes no promises as to the applicability of some optimization options on other platforms and indeed the compiler is sometimes accused of deliberately degrading performance on AMD hardware. This debate however seems to not to be really settled and tests with BAMPS seem to suggest, that it optimizes BAMPS comparatively well on both Intel and AMD processors.
This said, the
[http://software.intel.com/en-us/articles/intel-compilers/ Intel C++
compiler] is the most aggressively optimizing compiler that is currently
available. But this comes at a price, it is commercial software and it
is indeed very expensive. The current version of
There are actually some ways of using
Now, finally, here are some remarks on optimization features that are special to the Intel compiler:
Combing the above mentioned optimization options, especially PGO together with IPO and the rather aggressive loop vectorization of icc, can substantially speed up your program. Some tests with BAMPS (icc v12.1 versus gcc v4.4 on Intel quad-core) show that improving the performance by roughly 30% to 40% is possible.BR Your mileage may vary though. Largely vary! In both directions! So the advice would be: test, profile and evaluate whether using the above mentioned optimizations is actually of any benefit for the specific program and hardware at hand.
The BAMPS Source Tree - BAMPS Library and Main Programs
The source code of the different BAMPS versions (i.e. [source:full/trunk/ full] and [source:box/trunk/ box]) has been split into a BAMPS library and the main programs. The library contains all parts of the source code that are common to all variants - scattering routines, integration routines, auxiliary routines etc. Seen from the root of the svn repository the source code is thus structured as follows
Now, when building either full or box from source there are two slightly different ways of integrating the library into the build:
Which of the two options is chosen clearly depends on the use case. In the development process the first alternative (the default) might be more appropriate as it guarantees that the latest version of the library files is used. Whereas the second alternative might be more appropriate in an environment where the core routines of BAMPS remain unchanged but different variants of the main programs need to make use of these core routines, e.g. on the CSC cluster.==== Building the library together with the main program ==== #InPlaceBuildOfLibrary
As this is the default for the current trunk versions
[source:full/trunk/ full] and [source:box/trunk/ box], nothing special
needs to be done. A simple CMake configuration of the build directory
For the more curious, here's how it works:BR
For convenience the library directory is symbolically linked into the main directories of full and box
(assuming the build is done in a directory one level below the main
directory as described [#HowToBuild above]). The library path specified
on the command line takes precedence over the default value (which is
Building and installing
Alternatively the library can be separately build using the very same
CMake build system as all other parts of BAMPS. Simply go to
[source:lib/trunk/], create a build directory, change into this
directory and issue
To ease this configuration, the BAMPS library can be automatically installed simply by
By default this tries to install the library files into the system's
standard locations (e.g.
On a side note:
The installation prefix is controlled by the CMake variable
Linking against the BAMPS library
As described [#InPlaceBuildOfLibrary above] the default behavior of the
main BAMPS programs is to always build the library. In case linking
against a previously build library (i.e.
CMake then tries to automatically find the installed version of the
BAMPS library by virtue of the custom CMake module
[source:full/trunk/cmake_modules/FindBAMPS.cmake FindBAMPS.cmake]. The
module is able to detect and configure BAMPS library installed in the
default system locations as well as in a home directory-based
No further configuration should be necessary.