Installation and Linking

  1. Compatibility
  2. Installation: Setup and Prerequisites. Linux, Mac, Windows.
  3. Linking: FASTJET, ROOT, HEPMC, LHAPDF
  4. Advanced Installation Options
  5. Troubleshooting

Compatibility

Use the following compatibility table to ensure that your VINCIA and PYTHIA versions are compatible


With
PYTHIA Versions
Use
VINCIA Versions
Comments
8.226 2.200 New initialisation structure.
8.212 - 8.223 2.000 - 2.001 Updates for VINCIA ISR showers. New TimeShower::pTnext() in PYTHIA.
8.200 - 8.210 1.200 - 1.202 Significant restructuring for PYTHIA 8.2
8.183 - 8.185 1.102 - 1.103 PYTHIA changed prepare() signature in TimeShower.h
8.180 1.101 - 1.103 PYTHIA moved header files from include/ to include/Pythia8/
8.176 1.100 PYTHIA changed ownership structure of ParticleDataPtr between Particle and Event
8.175 N/A PYTHIA rearranged use of namespace std. No compatible VINCIA version
8.170 N/A PYTHIA fragmentation bug
8.162 - 8.165 1.028 - 1.029 New Pythia::init()
8.160 N/A (crashes) PYTHIA initialization bug
8.145 - 8.157 1.025 - 1.027 PYTHIA 8.145 changed CoupSM to Couplings
8.135 - 8.140 1.024 PYTHIA 8.140 modified inherited TimeShower::prepare() function (VINCIA 1.024 made backwards compatible with 8.135 also).
8.135 1.019 - 1.023 PYTHIA 8.135 dropped all static dependencies

Installation from scratch

Prerequisites:

Installation:

  1. Download, configure, compile, and install PYTHIA 8.
  2. Important: to be able to execute main programs that link to PYTHIA, you must ensure that you set the PYTHIA8DATA environment variable to point to the location of the runtime data files required by PYTHIA 8. For example, if you installed PYTHIA in the directory Users/skands/pythia8200/, you should set PYTHIA8DATA to the value /Users/skands/pythia8200/share/Pythia8/xmldoc, eg via (for bash-syntax shells)
  3. Download the VINCIA plug-in, vincia-N.N.NN.tgz (with N.N.NN being the version number) from the VINCIA homepage: http://vincia.hepforge.org

  4. Go to the thus created subfolder vincia-N.N.NN/ and execute ./configure followed by make. (This assumes a default minimal setup. Use ./configure --help to see what options are available, including linking to HEPMC, FASTJET, ROOT, and linking to non-standard PYTHIA installations. Note that many of these options closely parallel ones available in standalone PYTHIA.
  5. Vincia should now be installed (assuming your PYTHIA distribution is functional). Let us know if you experience problems at this stage, including as elaborate as possible a report on your architecture and compiler setup.
  6. Analogously to PYTHIA8, several example main programs are included with VINCIA. Move to the subfolder examples to find these, and eg type make vincia01 to compile the first example program. Run it to test the installation. To compile a program written by yourself, e.g., vincia-test.cc, use "make vincia-test" (the Makefile included with VINCIA automatically recognises program names that begin with "vincia")

For further instructions, see also

Linking

Using VINCIA in your own PYTHIA 8 program

To use VINCIA in your own program, you must first of all make sure the main header is included

Within your main() program, you must then create a VINCIA object, which automatically initialises itself and links to PYTHIA without further user intervention. Assuming you included the VINCIA header as above, you can create a VINCIA object by

where &pythia should be a pointer to the specific PYTHIA 8 object that VINCIA is desired plugged into. (That is, instead of telling PYTHIA 8 to use VINCIA, you are telling VINCIA to plug itself into PYTHIA, but the result is the same, and in this way the whole procedure can be done with just this single line of code.)

Finally, to ensure that both PYTHIA and VINCIA are initialised properly, the standalone PYTHIA call pythia.init() should be replaced by an equivalent VINCIA one, vincia.init() (which automatically calls the PYTHIA one so you don't need two separate init() calls). When you next run your main program, VINCIA will automatically take over the showering, using default settings. To initialise VINCIA with user-specified settings (including the possibility to switch VINCIA back off without recompiling), see the section on Initialization.

The rest of the run proceeds as a normal PYTHIA 8 run, i.e., using the same functions to generate and store events as usual, see An Introduction to PYTHIA 8.2.

Linking to Other Packages

If you wish to link to additional external packages (such as FASTJET, ROOT, LHAPDF, HEPMC, etc), again note that all libraries must normally have been compiled with the same C++ compiler. This may require some tinkering and, possibly, recompilation of existing packages using the same gcc or clang version you used to compile VINCIA. If you attempt to link libraries that have been compiled with different gcc/clang versions, incompatibilities may arise.

FASTJET:

The default configure script and Makefile shipping with VINCIA incorporates support for linking to the FASTJET libraries and include files. For example, on our test machine, we have installed FASTJET in its defauly location, /usr/local, and we include the option --with-fastjet3=/usr/local to the VINCIA configure script:

This enables compilation of the VINCIA example programs that use FASTJET, like vincia04-root.cc.

HepMC:

Linking and interfacing to HepMC is based on the PYTHIA HepMC interface, with the same methods applicable to VINCIA. See the PYTHIA documentation for further information on setting up PYTHIA to use HepMC and the vincia24.cc example program for an explicit VINCIA example. Assuming HepMC is installed in /usr/local, the VINCIA configuration script needs to be invoked with:

Assuming PYTHIA has been set up correctly (test this, e.g., by compiling and running the PYTHIA standalone HepMC example programs provided with PYTHIA), the default VINCIA Makefile includes a section on linking to HepMC. The variables HEPMCINC and HEPMCOPTION should be uncommented for proper linking to HepMC.

ROOT:

The configure script supports the options --with-root=PATH_TO_YOUR_ROOT, --with-root5=PATH_TO_YOUR_ROOT5, or --with-root6=PATH_TO_YOUR_ROOT6. When these are successfully executed, the VINCIAROOT utilities can be compiled and used. On our Mac OS X test machine, which uses the MacPorts ROOT 6 installation, which resides in /opt/local, we use the following option to the VINCIA configuration script:

Our .bashrc shell initialisation file further contains the following environment variables: Further documentation on linking to ROOT is provided in the section on the VINCIA ROOT interface.

Advanced Installation Options

Location of the XML file set and other Data Files needed at Run-Time

Important note for non-default installations: If the share/Vincia directory containing the VINCIA XML parameter files and other run-time data files is not in the same location as the executable, a specific path to the directory where these files are located can (optionally) be specified by setting the environment variable VINCIADATA to the location of the file set,

If VINCIADATA is undefined, you may also specify the path to the settings directory explicitly by giving a third argument to the constructor,

Note that, if both VINCIADATA and a constructor argument is given, VINCIADATA takes precedence and overrides the constructor argument.

The default value for the location is based on the current directory, and corresponds to ./share/Vincia. Thus, the default location of the XML data files is "./share/Vincia/xmldoc" and the default VINCIA tune files reside in "./share/Vincia/tunes", etc. Note that it is unimportant whether the settings location contains a trailing slash or not.

Finally, if the name of the main XML index file is modified for any reason (strongly discouraged!), the name of the modified index file can (optionally) be given as a fourth and last argument to the constructor,

The default value for the main XML index file is "VinciaIndex.xml".

Installation Problems: Troubleshooting

The following is a non-exhaustive list of issues people have encountered during installation / linking of VINCIA, together with what advice we are able to give on how to troubleshoot each one. Please do communicate any further input on these issues to the authors.

Linking errors may result if you use f77 to compile your fortran code. We advise using gfortran.

undefined reference to `_gfortran_st_write' and similar errors: these errors typically occur during the last step of the compilation (linking), and indicate a problem with the C-Fortran libraries. The flag -lgfortran links the GNU FORTRAN libraries, but this is only valid if using the GNU compiler suite, and will not work eg with the clang C++ compiler. The most recent versions of VINCIA should be able to compile without the -lgfortran flag, and hence should work with clang as well. If you experience this error, try removing the -lgfortran flag from your compilation options. This may require editing the PYTHIA 8 config.mk file. If you still experience this problem, we recommend to check thoroughly the compatibility of your C and Fortran compilers (especially as concerns linking of C and F code together), your FC, CC, and CXX environment variables (see above), and the config.mk file in the main PYTHIA directory. Also check the LD_LIBRARY_PATH environment variable: is the path to the correct libgfortran.a included, and/or are any paths that contain incompatible versions of libgfortran.a included. E.g., it is possible that incompatible compilers and/or libraries are being found in the paths included by FASTJET, when it is being linked. To check this, make sure the environment variable FASTJETLOCATION is empty / not set, and try compiling again. Also remember to issue a make clean and then a make first in the PYTHIA and then in the VINCIA directory after making any changes to your setup, to make sure that all code is recompiled and linked with the correct up-to-date settings.