The VINCIA package includes a few add-on tools that rely on
ROOT. These
can be used in any PYTHIA 8 (or other) program, independently of
whether VINCIA itself is switched on
or not (the VINCIA libraries do not even have
to be linked, only the self-contained VinciaRoot.h
header
file must be included).
These tools are mainly intended as an aid to
visualize event generation during running, by allowing the user to
create runtime display(s)
of ROOT histograms that can be updated in realtime
during the event generation process. (Helpful, e.g., to quickly check
whether the generated events look as expected.)
This should of course not be regarded as the only way to generate ROOT output from VINCIA. The user can still define his/her own histograms and ntuples as usual, and is encouraged to use the full arsenal of ROOT utilities in addition to the ones provided by VINCIA.
Note: for help on ROOT-specific issues, please consult the ROOT documentation and forums, not the VINCIA authors.
Note 2: feel free to use VINCIA's ROOT displays for your own publications, using the saveDisplay() method. We ask only that you respect the MCnet guidelines by including a reference to [GKS11] in which this capability was first developed.
Include the ROOT libraries and the ROOT include/ path when
linking. For main programs beginning with vincia...
and
ending with ...-root.cc
(such as
the example programs),
the default Makefile shipping with VINCIA automatically looks for the
ROOT libraries and include files in the location specified by
the ROOTSYS
environment variable. If linking still fails,
try specifying the ROOTLIBDIR
and ROOTINCDIR
environment variables as well, to define the path to your ROOT libraries and
include files, respectively. If this still fails,
the Makefile has been written so that it should hopefully be easy
for you to fix the problem yourself with a minimum of editing, see
the Makefile's section on "Linking to ROOT".
Note also that it is important that your ROOT libraries were compiled with the same C++ compiler version as the PYTHIA 8 (and VINCIA) libraries were, see the section on Installation & Linking. Otherwise you may get errors related to inconsistent architectures.
We recommend including at least the following ROOT
libraries: -lCore -lCint -lGpad -lGraf -lHist -lMathCore
-lMatrix -lRIO
, with a few alternatives also provided (but
commented out by default) in the VINCIA Makefile.
To use the VINCIA ROOT utilities, simply add
VinciaRoot.h
to the list of header files included in your
main program,
VinciaRoot.h
header file is VINCIA's include/
subdirectory, i.e., the same location as that of the other VINCIA
header files, so if you are already linking VINCIA,
you should not have to
specify any new include paths. If your program is not already
linking to VINCIA, you may have to add this include path
explicitly. The other VINCIA libraries do not
need to be linked; the VinciaRoot.h
header is
self-contained and can be used standalone.
All functionality of the VINCIA ROOT interface resides in a
single class called VinciaRoot
, which is defined when the
header above is included.
All of the functions described on this page are member functions of
this class. You should therefore start by constructing an instance of
this class, as follows:
VinciaRoot
can be constructed per main program.
The interface relies on (and will automatically include) the following ROOT header files:
VinciaRoot.h
,
you should not need to include them in your main
program explicitly, but the linker will of course need to be told where to find
them, i.e., a ROOT include path will need to be specified.
See the section on interfacing to ROOT in VINCIA's default Makefile.
VinciaRoot
class called vroot
has already been constructed
(see Constructing the VinciaRoot object).
Note that each display is associated with a
unique name (the first argument of createDisplay
) which
will be used to identify that particular display in the functions below.
By default, the created displays will cascade from the upper left-hand corner of your screen. If you wish to place a display with a specific offset from that location, two additional arguments may optionally be given,
Your histograms should be completely ordinary ROOT histograms. Currently, only the TH1F ROOT histogram type is supported for runtime display. You instruct VinciaRoot to show your histogram on a runtime display (see illustration on the right) by giving it a pointer to the histogram, using the following method
hisPtrIn
,
the pointer to your ROOT histogram.
The optional arguments are:
displayName
: in case several displays were
created using the createDisplay
method, this gives the name of
the specific display on which the plot should appear
(e.g., "Particles"
, "Shapes"
,
or "Jets"
in the example above). By default (or
if displayName
does not correspond to any booked display),
the plot will be sent to the display that was created first. logy
: logarithmic
(true
) or linear (false
) y scale. normalize
: normalized to unity (true
)
or not (false
).showStatErr
: whether the statistical
uncertainty due to the finite number of generated events should be
shown (true
) or not
(false
). The default size of the statistical error
bars shown on the MC points is 2σ in
VINCIA, which in our experience is more consistent with how they are
interpreted visually. The size of the error bars shown (and saved to
data files, etc) can be adjusted by the method
dataFile
: can be used to give the name of a
file containing data points for comparison to the generated
distribution. In this case, the plot will be split into two halves,
the upper of which shows the absolute values of data (black squares)
compared to theory (histogram), and the lower of which shows
theory/data, with the uncertainty on the data shown as a yellow band
(divided into different shades for statistical and systematic, when
available, using linear addition of the stat and sys errors). Note
that the format of the data file is important. By default, the data
format used on
mcplots.cern.ch is
assumed,
VinciaRoot.h
and edit
the addDataFile
method yourself.
Continuing the above example, we could e.g., book a histogram to correspond to the charged multiplicity and send it to the display labeled "Particles" in the following way:
For compactness, VINCIA's ROOT display tool is not intended to be a full-fledged graphics package, nor does it allow access to all the ROOT plotting functionality. A few methods are provided, however, to cover the most common tasks, such as switching the statistics box on and off, adding legend labels and MC version numbers, and to select between a few predefined color schemes.
Note: if you need more advanced plotting options, remember that your histograms are ordinary ROOT ones and can therefore be saved to a standard ROOT file for later processing/plotting. Alternatively, you can save them to a plain ASCII file using VINCIA's saveHistogram() method.
int
can take values like 1101
etc, see
the ROOT documentation.
The only difference is
that in VINCIA the special value 0
switches of the box
entirely. We therefore recommend using
The label used in the legend for the MC curve can be set by the method:
To clear all references given and reset the reference string to one entry, use the method:
Three color schemes are available for the MC curves shown on the plots, and can be accessed through
mCols = 1,2,3
specifies which of the three color
schemes are to be used. Optionally, a second argument can be given,
To update a display during event generation,
periodically call the updateDisplay
method, which, if not
given an argument, updates all of the displays, e.g.,
To save a display during or after event generation,
call the saveDisplay
method,
displayName
specifies which display to
save and the return value is true
if the command
succeeded. The default name for the saved file
is displayName.png
. To give
the file a more descriptive name, a second argument can optionally be
given,
fileName-displayName.png
. To save
the display in a different graphics format, a third argument can
optionally be given,
fileType
recognized by the
program: eps, gif, jpg, pdf, png, ps. Note that ROOT is noot
universally good at saving graphics in a visually pleasing way. Check
your output files and experiment with different formats if results are
not as desired. Finally, a fourth argument can be
used to specify options to ROOT's save function, such as "Landscape".
Note: by default, VINCIA displays and saves statistical
uncertainties corresponding to 2σ variation. See the
method setSigmaMC()
if you wish
to use a different definition.
If you are running VINCIA with automated uncertainty bands, two additional columns will be added, representing the estimate of the theory uncertainty
The total uncertainty should be computed by adding the statistical and theory uncertainties. It is up to the user to decide whether to add them linearly or in quadrature.
Note: the theory uncertainties are computed from reweighted events, and hence have a slightly larger intrinsic statistical uncertainty than the central y values. This uncertainty is, however, still tightly correlated with the statistical uncertainty on the central result (which by default is output as a 2σ equivalent, see above). For the time being, therefore, VINCIA does not output a separate statistical error on the theory uncertainties.
The following example programs are included with the VINCIA distribution and illustrate how to use the ROOT interface:
vincia03-root.cc
vincia04-root.cc
vincia05-root.cc
vincia03-root.cc
run using an older VINCIA
version:
![]() |
![]() |