The VINCIA package includes a few add-on tools that rely on ROOT. These 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.
For help on ROOT-specific issues, please consult the ROOT developers, not the VINCIA authors.
The VINCIA ROOT utilities can be used in any PYTHIA 8 program, independently of whether VINCIA itself is switched on or not.
To use the VINCIA ROOT utilities, simply
VinciaRoot.h
to the list of header files included in your
main program,
#include "VinciaRoot.h" //Include VINCIA ROOT tools
|
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. In that case, however, the other VINCIA libraries do not
need to be linked; the VinciaRoot.h
header is
self-contained and can be used standalone.
VinciaRoot
class, see below,...-root.cc
. If this 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. 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. 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
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:
// Construct VinciaRoot object
VinciaRoot vroot;
|
VinciaRoot
can be constructed per main program.
The interface relies on (and will automatically include) the following ROOT header files:
#include "TROOT.h" //Main ROOT headers
#include "TH1.h" // for 1D histograms
#include "TH2.h" // for 2D histograms
#include "TGraphAsymmErrors.h" // for graphs
#include "TLine.h" // for lines
#include "TCanvas.h" // for widget canvas(es)
#include "TPaveStats.h" // for adjusting the stats box
#include "TApplication.h" // for main vincia widget
#include "TDirectory.h" // for file/dir structure
#include "TFile.h" // for file I/O
|
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).
// Initialize some ROOT displays (name,x-pixels,y-pixels)
vroot.createDisplay("Particles",1150,750);
vroot.createDisplay("Shapes",1050,680);
vroot.createDisplay("Jets",800,500);
|
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.
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
// Add histogram to runtime display
vroot.addTH1FPtr(TH1F* histPtrIn, string displayName="none",
bool logy=false, bool normalize=true, bool showStatErr=false,
string dataFile)
|
hisPtrIn
,
the pointer to your ROOT histogram.
The first optional argument
is displayName
which, in case several displays were
created using the createDisplay
method, 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.
The three booleans
denote, respectively, whether the plot should be shown with a logarithmic
(logy=true
) or linear (logy=false
) y scale,
whether it should be normalized to unity (normalize=true
)
or not (normalize=false
), and whether the statistical
uncertainty due to the finite number of generated events should be
shown (showStatErr=true
) or not
(showStatErr=false
). The latter will obviously be updated
and become smaller during running.
The last optional
argument, 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).
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:
// Book nCharged Histogram
TH1F *HnCharged=new TH1F("nCharged","nCharged (udsc)", 60, -0.5, 59.5);
// Add it to the display labeled "Particles"
// and give name of data file to compare to
vroot.addTH1FPtr(HnCharged,"Particles",true,true,true,"data/L3-91-Nch-udsc.vec");
// Set fill color and yMin and yMax values for plot.
HnCharged->SetFillColor(3);
HnCharged->SetMinimum(0.00001);
HnCharged->SetMaximum(0.5);
|
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.,
// Periodically update displays (and also for last event)
if (iEvent%500 == 99 || iEvent == nEvent-1) vroot.updateDisplay();
|
To save a display during event generation,
call the saveDisplay
method,
bool saveDisplay(string displayName, string fileName="eps",
string option="");
|
DisplayName
specifies which display to
save and fileName
can either be a full file name
or just a filename extension. In the former case, the name of the
saved file will be fileName
, and in the latter case it
will be displayName.fileName
. The third argument can be
used to specify options to ROOT's save function, such as "Landscape".
The following example programs illustrate how to use the ROOT interface:
vincia01-root.cc
vincia01-root.cc
run.
![]() |
![]() |
See also the comments on ROOT interfacing in the default Makefile.