ROOT Interface

  1. Linking
  2. Runtime ROOT Displays
  3. Plot Appearance
  4. Updating and Saving Displays (in realtime)
  5. Saving Histograms to .dat files
  6. Example Programs

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.

Linking

Link to ROOT

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.

Include the VinciaRoot.h header file

To use the VINCIA ROOT utilities, simply add VinciaRoot.h to the list of header files included in your main program,

The default location of the 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.

Construct 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:

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:

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. 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, This example would construct 2 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.

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,

In this example, the second display is offset by an amount equal to the width of the first and hence will appear to the right of it, rather than cascading over it.

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

where the only mandatory argument is hisPtrIn, the pointer to your ROOT histogram.

The optional arguments are:

  1. 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.
  2. logy: logarithmic (true) or linear (false) y scale.
  3. normalize: normalized to unity (true) or not (false).
  4. 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 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
  5. 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, This unfortunately inherits the issue from RIVET that only the total uncertainty is given, without a breakdown into statistical and systematical components. The interface therefore also contains a number of other custom data formats, based directly on the HEPDATA formats. Currently, the only way of making use of these custom formats is to open 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:

Plot Appearance

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.

Statistics Box

The ROOT statistics box can be controlled by a method inheriting from the standard ROOT setOptStat method, where 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 for producing plots for papers, etc, while this command can be commented out during development.

MC Legend

The label used in the legend for the MC curve can be set by the method:

MC Codes and Versions

Several codes and version numbers can be given. Each can be added by the method:

To clear all references given and reset the reference string to one entry, use the method:

Color Scheme

Three color schemes are available for the MC curves shown on the plots, and can be accessed through

where mCols = 1,2,3 specifies which of the three color schemes are to be used. Optionally, a second argument can be given, naming a specific display to apply the scheme to. The default is to apply the scheme to all displays.

Updating and Saving Displays

Updating

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.,

Saving

To save a display during or after event generation, call the saveDisplay method,

where 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, which saves the display to a file named fileName-displayName.png. To save the display in a different graphics format, a third argument can optionally be given, with the following values of 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".

Saving Histograms to .dat files

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. By default, the data format is that used by mcplots.cern.ch,

Note: by default, VINCIA displays and saves statistical uncertainties corresponding to 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.

Example Programs

The following example programs are included with the VINCIA distribution and illustrate how to use the ROOT interface:

The following graphics show some sample displays from a vincia03-root.cc run using an older VINCIA version: