Vincia ROOT Interface

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. They 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 developers, not the VINCIA authors.

Linking

To use the VINCIA ROOT utilities, simply

Constructing the VinciaRoot object

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;
Note that only one instance of VinciaRoot can be constructed per main program.

Dependencies

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
Since these declarations are contained in 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.

Runtime ROOT Displays

The following utilities are available to create, update, and save runtime displays via VINCIA's ROOT interface. The examples assume that an instance of the VinciaRoot class called vroot has already been constructed (see Constructing the VinciaRoot object).

Creating Displays

Any number of displays of varying sizes can be booked as follows,
// Initialize some ROOT displays (name,x-pixels,y-pixels)
vroot.createDisplay("Particles",1150,750);
vroot.createDisplay("Shapes",1050,680);
vroot.createDisplay("Jets",800,500);
This example would construct 3 displays of different sizes, onto which we can now put any 1-dimensional ROOT histograms for display during event generation (see below).

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.

Adding Histograms to Displays

Example

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)
where the only mandatory argument is 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);

Updating Displays

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();

Saving Displays

To save a display during event generation, call the saveDisplay method,
bool saveDisplay(string displayName, string fileName="eps", string option="");
where 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".

Examples

The following example programs illustrate how to use the ROOT interface:

The following graphics show some sample displays from a vincia01-root.cc run.

See also the comments on ROOT interfacing in the default Makefile.