Installation and Linking

  1. Compatibility
  2. Installation
  3. Linking
  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.180 1.101 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 and compile PYTHIA 8
  2. Download the VINCIA plug-in, vincia-N.N.NN.tgz (with N.N.NN being the version number) from the VINCIA homepage: http://projects.hepforge.org/vincia/

  3. Go to the thus created subfolder vincia-N.N.NN/ and type "make"
  4. Vincia is now installed (assuming your PYTHIA distribution is functional).
  5. The default make target also compiles a test program, vincia01.exe. 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 recognizes 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

The only further change required in your main program is the creation of the VINCIA object, which automatically initializes 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.)

When you next run your main program, VINCIA will automatically take over the showering, using default settings. To initialize 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 initialize, generate, and store events as usual, see A Brief Introduction to PYTHIA 8.1.

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 version of gcc. This may require some tinkering and, possibly, recompilation of existing packages using the same gcc version you used to compile VINCIA. If you attempt to link libraries that have been compiled with different gcc versions, incompatibilities may arise.

FASTJET:

The default Makefile shipping with VINCIA automatically looks for the FASTJET libraries and include files in the location specified by the FASTJETLOCATION environment variable.

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.

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:

Documentation on linking to ROOT is provided in the section on the VINCIA ROOT interface.

Advanced Installation Options

Location of the XML file set

Important note for non-default installations: If the directory containing the VINCIA XML parameter files is not in the same location as the executable, a specific path to the directory where the XML 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 XML file set 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, "./xmldoc". Note that the location name should not contain a trailing slash. Note also that VINCIA will look for its default antenna file sets in the relative position path_to_xmldoc/../antennae/, and hence it is important that the antennae/ subdirectory is located in the same parent directory as the xmldoc directory.

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.

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 default VINCIA Makefile includes the flag -lgfortran, which should link in the gfortran library libgfortran.a on most systems. However, for reasons that are not yet clear, this appears not to be sufficient in some cases. If you 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.