Installation, Linking, and Initialization

Installation from scratch

  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

   #include "Vincia.h"

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

   VinciaPlugin vincia(&pythia);

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 below.

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 External Packages

For successful C++/F77 linking, all F77 and C++ objects must have been compiled with the *same* version of gcc. This may require some tinkering and, possibly, recompilation of existing packages using your current gcc version. If you attempt to link libraries that have been compiled with different gcc versions, incompatibilities may arise.

Initialization

VINCIA initializes its default values from a set of XML files included together with the code. The same XML files are also used to generate this documentation, ensuring consistency between the default code and the documentation (this behaviour is inherited from PYTHIA). It is strongly discouraged to change any of the XML, HTML, or PHP documentation files directly. Instead, the following methods, common to PYTHIA 8, should be used to set/modify both PYTHIA and VINCIA parameters:

VINCIA shares the PYTHIA 8 settings database, which is automatically expanded to include the VINCIA parameters whenever VINCIA is linked. All options and parameters, including the additional VINCIA ones described in this documentation, can therefore be set exactly as in PYTHIA 8, i.e., using

   pythia.readString("Vincia:parameter = value");

and/or collections of such strings in a PYTHIA 8 command file,

   pythia.readFile("commandFile.cmnd");

where Vincia:parameter can be any of the parameters described in this documentation (all VINCIA parameters are prefaced by Vincia: in order to disambiguate them clearly from PYTHIA ones), and commandFile.cmnd may contain both VINCIA and PYTHIA 8 parameters together (be careful not to overwrite parameters if reading in several command files).

For optimal performance, you should simply give the name of your command file directly as a second argument to the constructor, i.e., replacing the default constructor above by

   VinciaPlugin vincia(&pythia,"commandFile.cmnd");

The default value for the command file is "none" in which case no command file is read in by the constructor.

Regardless of whether the name of a command file is given to the constructor or not, (further) commands and command files may of course still be read in after construction, using the methods above. The constructor simply provides an efficient and convenient way of doing it, and adds a bit of extra functionality in the process, such as the possibility of reading in the name of a second command file, containing non-default antenna presets, and processing that file automatically. When bypassing the constructor, this would have to be handled manually.

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 including a third argument to the constructor,

   VinciaPlugin vincia(&pythia,"commandFile.cmnd",string xmlDir);

The default value for the location is based on the current directory, xmlDir="./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 xmlDir/../antennae/, and hence it is important that the antennae/ subdirectory is located in the same parent directory as the xmlDir 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,

   VinciaPlugin vincia(&pythia,"commandFile.cmnd","xmldoc","VinciaIndex.xml");

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

Last modified: