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 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 ending with ...-root.cc
(such as
some of 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".
When linking to VINCIA and PYTHIA 8, 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 only relies on itself, on the ROOT libraries, and on an auxiliary header file VinciaRootFile.h
, which is automatically included in VinciaRoot.h
.
The VINCIA ROOT classes and functions have all been defined to live inside the Vincia
namespace, so to use them in your code they must either be prefaced by Vincia::
, or you can include the Vincia
namespace:
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.
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 normalizing to unity, setting logarithmic axes, adding legend labels, etc.
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.
Create your own runtime ROOT displays using the following step-by-step procedure:
VinciaRoot
object.
Only one such instance should be constructed for each main program:
"T"
) serves to identify
this particular display in subsequent calls to VinciaRoot member functions (see subsequent steps). It is typecast as a string.
The two last arguments give the size of the display in pixels. Any number of histograms and displays can be created by repeating steps 2-3.
By default, additional displays cascade from the top left-hand corner of the screen. Optionally, if you wish a new display to appear somewhere else, two additional coordinate values can be given, specifying the desired offset (in pixels) from the top left-hand corner of your screen,
setDataFile()
,
the numerical values following the name of the data file
specify the type and order of data columns in the file, column by column.
The possible format specifiers are listed here:
Left Bin Edge | 10 xLeft |
11 errX- |
12 1-xRight |
||
Bin Center | 20 xCenter |
21 xWeighted |
22 1-xCenter |
Right Bin Edge | 30 xRight |
31 errX+ |
32 1-xLeft |
Bin Content | 40 y |
||||
Stat Errors | 50 errStat |
51 errStat+ |
52 errStat- |
||
Sys/Th Errors 1 (optional) | 60 errSys |
61 errSys+ |
62 errSys- |
||
Sys/Th Errors 2 (optional) | 70 2nd errSys |
71 2nd errSys+ |
72 2nd errSys- |
||
Total Errors (optional) | 80 errTot |
81 errTot+ |
82 errTot- |
||
Merging Info (optional) | 90 N |
91 ... |
92 ... |
93 ... |
94 ... |
addDataFile()
in the example
above tells VinciaRoot that this particular data file should be interpreted as having the columns
Optionally, vectors of histograms can be used to represent uncertainty variations. This is especially convenient when using VINCIA's
automatic uncertainty estimates,
but can in principle also be used for making uncertainty estimates with other Monte Carlo generators. Instead of a single pointer to a TH1D, the
display should then be initialized using an object of the type
TH1D*
, including vertical lines showing the statistical MC uncertainty.
However, if myTH1Dvec
contains more than one element,
VINCIA will also add a shaded box below the point, computed from a simple max
and min
operation on the uncertainty variations. Note that the size of the shaded box is obtained by summing the max and min variations in
quadrature with the statistical MC uncertainty on the central point.
By default, VINCIA also adds a pane below the main plot showing the relative decomposition of the total variation into its components. A legend for this pane is given in the illustration here to the right, with names corresponding to VINCIA's automatic uncertainties and numbers indicating the vector index. As an aid to visualizing the many possible contributions, blue colors are used for even vector indices (generally corresponding to "High" variations in VINCIA) and red ones for odd indices (generally corresponding to "Low" variations in VINCIA), with the exception of index numbers 1, 8, and 9 which are drawn as black lines.
The y axis of the relative-uncertainty pane goes from -1 to 1. Above (below) zero, each variation greater than (smaller than) the central one is shown expressed as a fraction of the largest (smallest) variation. Thus, this pane illustrates, bin by bin, which source of uncertainty generates the largest contribution to the total. Due to unitarity, one generally sees a cross-over between reds and blues at the intersection between Sudakov- and hard-radiaton-dominated regions.
The pane showing the decomposition of the uncertainty into relative components can be switched off using the method
See the example program vincia03-root.cc
for an explicit example of how to do this.
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,
fileNameBase-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. 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
: create and save
runtime displays, including comparisons to files containing
experimental data points in a variety of formats. vincia04-root.cc
: save ROOT
histograms to a ROOT file, eg for later manipulation and/or custom plotting.vincia05-root.cc
: save the output of a previous run
to a histogram file and overplot it on the current one.vincia07-root.cc
: using the runtime displays to plot ratios of
VINCIA radiation functions to MADGRAPH matrix
elements. vincia08-root.cc
: run
several PYTHIA and VINCIA instances concurrently, plotting the
results of all them simultaneously.The snapshots below give a brief history of how the look of the VinciaRoot interface has evolved over time. Shown is the Thrust event-shape variable in e+e- collisions at 91.2 GeV.
May 2012 Vincia 1.028 + Pythia 8.162 |
![]() |
Jul 2011 Vincia 1.026 + Pythia 8.150 |
![]() |
Dec 2010 Vincia 1.023 + Pythia 8.140 |
![]() |