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.200 - 8.205 1.200 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.
  3. 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/

  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 FASTJET and use of ROOT, and linking to non-standard PYTHIA installations.
  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 share/Vincia/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 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 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 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 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 the /opt/local directory and we include the option --with-fastjet3=/opt/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.

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 or --with-root5=PATH_TO_YOUR_ROOT5. 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 installation, our .bashrc shell initialization file contains the following:

and we include the following flag to configure: --with-root5=/opt/local. 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.