vincia-N.N.NN.tgz
(with N.N.NN
being the version number) from the VINCIA
homepage: http://projects.hepforge.org/vincia/
tar -xvzf vincia-N.N.NN.tgz
vincia-N.N.NN/
and
type "make"
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
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.
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.
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"
.