The VINCIA package includes a few add-on tools that rely on
ROOT. These
can be used in any program, independently of VINCIA, though we note
that they make use of the PYTHIA 8 settings database to store
parameters. As such, PYTHIA 8 must be linked and initialised (though
not necessarily used). In addition, the VINCIA ROOT libraries must be linked,
and the VinciaRoot.h
header included. The VINCIA Makefile
includes a dedicated make target, make vinciaroot
, which
will compile just the VINCIAROOT libraries independently of the rest
of VINCIA.
These tools are mainly intended as an aid to visualise 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 the VINCIA ROOT displays were 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 -lThread
, 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 vinciaroot/include/
subdirectory. This is automatically included in the VINCIA Makefile, when compiling programs ending in libvinciaroot.a
library (again handled automatically by the VINCIA Makefile). The other VINCIA libraries do not
need to be linked; the VinciaRoot.h
header only relies on itself, on the ROOT libraries, and on the auxiliary header files 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
(via VRsettings.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:
"all"
in any of the
following methods:
"new"
instead
of "all"
above.
You can also change only the properties of a
specific (named) display by using the name of that display. For
example, if you have created a display named "Thrust"
and
you want to change the Y axis to a linear scale only for that display,
use
Note that VINCIA does not read all the properties of the TH1D. The example above gives the most commonly used ones, with a few additional ones, such as custom axis labels, illustrated in the example main programs.
"Thrust"
) 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,
setShowRatio()
and setRatioRange()
below.
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 |
13 exp(xL) |
14 10xL |
|
Bin Center | 20 xCenter |
21 xWeighted |
22 1-xCenter |
23 exp(x) |
24 10x |
25 ++iBin |
Right Bin Edge | 30 xRight |
31 errX+ |
32 1-xLeft |
33 exp(xR) |
34 10xR |
|
Bin Content | 40 y |
43 y [logX] |
45 k Factor |
46 1/k Factor |
||
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 ... |
95 ... |
Generic Info (optional, read as strings, ignored by reader) | 1 Experiment Name |
2-9 Other string-type information |
||||
Ignore column | 0 Ignore |
addDataFile()
in the example
above tells VinciaRoot that this particular data file should be interpreted as having the columns
Optionally, to modify the properties of a single display without modifying the global ones set in step 1, you can use the same methods as in step 1 but inserting the display identifier as the first argument, e.g.,
setLegend()
method uses an integer to specify the placement of the legend: -1
for left-hand placement, +1
for right-hand placement, and 0
for automatic left/right placement depending on where the data (or first MC) histogram is largest.
The second variant of the setLegend()
method instead uses absolute coordinates to specify the placement and size of the legend (only the first two arguments are mandatory).
Note that some properties are so far only modifiable at the global level and cannot (yet) be changed for each individual display.
TLine
class. You create the line yourself and modify its properties to suit you, then send a pointer to it, to a named display (here called "Thrust"
) using:
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 initialised 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 colours 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 either locally, for a single display, or globally, using the method
Displays can be updated periodically during the event generation by
adding a call to the bool VinciaRoot::update()
method. For ordinary applications, just add a call to this method for
every processed event (in which case VinciaROOT will count
internally how many events have been processed so far)
or it can be given an optional argument telling it how far we got,
update(int iEvent)
. To save time, displays will not be
refreshed at every call but instead with a frequency controlled by
mode
VinciaRoot:nUpdate
(default = 400
; minimum = 1
)update()
will be true if the displays
were refreshed in this call, otherwise false.
If desired, the event number at which the displays will next be
refreshed by update()
can be retrieved with
int VinciaRoot:nextUpdate()
.
Note: for ordinary applications, the automated functionality described above should be sufficient. Forced updates are only intended to cover special cases where the user would want to override the automated functionality.
To force an update of a particular display during event generation,
the updateDisplay(string displayName)
method can be called, which, if not
given an argument, updates all of the displays.
The ROOT example programs included with VINCIA give some further examples of updating, including adjusting the frequency of the updates as the run progresses.
Displays can be automatically saved to graphics files (see paragraph
below for how to save histogram data files)
as part of the call to update()
.
This is controlled by the parameter
flag
VinciaRoot:saveDisplays
(default = on
)
Again, to save time, not every call to update()
produces a new set of saved displays. The base interval between savings
is controlled by the parameter
mode
VinciaRoot:nSave
(default = 2000
; minimum = 1
)nSave
are
only used at the beginning of a run. A transition is automatically
made to the following form at the point when it produces a longer
interval than the linear one:
nSave
* pow(2,i/fSave
) ,
fSave
controlling the frequency of
saves in the asymptotic part.
parm
VinciaRoot:fSave
(default = 4
; minimum = 0.5
; maximum = 8
)fSave=1
would correspond to saving the
displays each time the statistics have doubled, at which point
statistical uncertainties will have been reduced by a factor
sqrt(2)~1.4, while the default
fSave=4
produces a save each time the statistical
uncertainties are reduced by roughly 10% relative to the previous save.
When saveDisplays = on
the produced file type(s) are
controlled by the following flags:
flag
VinciaRoot:saveDisplays:pdf
(default = on
)flag
VinciaRoot:saveDisplays:png
(default = off
)flag
VinciaRoot:saveDisplays:gif
(default = off
)flag
VinciaRoot:saveDisplays:jpg
(default = off
)flag
VinciaRoot:saveDisplays:eps
(default = off
)flag
VinciaRoot:saveDisplays:ps
(default = off
)flag
VinciaRoot:saveDisplays:Portrait
(default = off
)flag
VinciaRoot:saveDisplays:Landscape
(default = off
)flag
VinciaRoot:saveDisplays:svg
(default = off
)flag
VinciaRoot:saveDisplays:xpm
(default = off
)flag
VinciaRoot:saveDisplays:xml
(default = off
)flag
VinciaRoot:saveDisplays:root
(default = off
)flag
VinciaRoot:saveDisplays:cxx
(default = off
)flag
VinciaRoot:saveDisplays:tex
(default = off
)By default, file names for the saved graphics files will be formed from the name of the saved display(s), followed by the appropriate graphics extension (so a display named "Thrust" will be saved to "Thrust.png"). User-specifiable prefixes and/or suffixes can also be provided (e.g., to distinguish plots made in different runs), via the following strings:
word
VinciaRoot:saveFilePrefix word
VinciaRoot:saveFileSuffix If desired, the event number at which the displays will next be
saved by update()
can be retrieved with
int VinciaRoot:nextSave()
.
Note: for ordinary applications, the automated functionality described above should be sufficient. Forced saves are only intended to cover special cases where the user would want to override the automated functionality.
To save a display during or after event generation,
call the saveDisplay
method,
displayName
specifies which display to
save.
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
recognised 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".
It is also possible to save your VinciaRoot histograms to simple ASCII data files, for later plotting with another program or for overplotting in a subsequent VINCIA run. This is controlled by the
flag
VinciaRoot:saveHistograms
(default = on
)By default, the data format is that used by mcplots.cern.ch,
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.
Note 2: in order to preserve total normalisations, VINCIA writes the underflow and overflow bins in the file as well, as the first and last line of the data points, respectively. They are assigned fictitious x values, displaced by one bin from the main bins, so they will not show up on plots restricted to the range of the original histogram. Feel free to edit the files to comment them out or remove them entirely, as suits your purpose, but be aware that by default, the first and last bins represent the under- and overflow bins and are assigned x values displaced from the main histogram range.
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.vincia10-root.cc
: run
several centre-of-mass energies,
plotting how various quantities scale with energy. 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.
Sep 2013 Vincia 1.101 + Pythia 8.180 |
![]() |
May 2012 Vincia 1.028 + Pythia 8.162 |
![]() |
Jul 2011 Vincia 1.026 + Pythia 8.150 |
![]() |
Dec 2010 Vincia 1.023 + Pythia 8.140 |
![]() |