## ROOT usage

Many PYTHIA users wish to use ROOT to produce histograms, or even to run PYTHIA as a plugin to ROOT. This is possible. It is not a task supported by the PYTHIA team, however. All issues involving ROOT usage should be directed to the ROOT team, or to the local support team of your collaboration. Below some helpful hints have been collected. The text is based on contributions by Rene Brun, Andreas Morsch and Axel Naumann. Another example may be found in the VINCIA add-on program for parton showers, but this should also work for a PYTHIA standalone run.
Note that in all that follows, a Linux-type system with a Bash shell and GNU Make is assumed. In particular, for Mac OS X, the `LD_LIBRARY_PATH` should be replaced with `DYLD_LIBRARY_PATH` and the extension for shared libraries `.so` should be replaced with `.dylib`.

### Standalone usage

One can perform the generation and analysis of events in a completely standalone fashion, and only use ROOT to process the completed events. Some example programs are provided in the `rootexamples` directory, with details provided below and in the `README` file. The examples assume that you have already compiled the PYTHIA library, ROOT is installed, and that all paths have been setup correctly (e.g. PATH and LD_LIBRARY_PATH). If these paths are not already set, ROOT typically comes with a shell script to set these paths, which can be run with

        source /path_to_ROOT_installation/bin/thisroot.sh

#### Histogramming with ROOT

An example of histogramming with ROOT is provided in `rootexamples/hist.cc`. It may be compiled and run with the following commands

        make hist
        ./hist.exe

After PYTHIA has run, a ROOT histogram of the charged multiplicity in the events will be shown. This is now stored in the `hist.root` file.

#### Storing PYTHIA events in ROOT trees

Instead of only generating histograms, it is possible to store entire PYTHIA events in ROOT trees. The `tree` example in the `rootexamples` subdirectory provides an example of this and is comprised of the following files

- `tree.cc` is the main example program showing how PYTHIA events can be stored in ROOT trees.
- `pythiaLinkdef.h` is used by Makefile to generate the dictionary for all PYTHIA classes involved in the IO, as needed for the example.
- `pythiaROOT.h` is a small include declaring the `Pythia8` namespace as default.

The example may be compiled and run with

        make tree
        ./tree.exe

After the example has run, the `pytree.root` file will now be present containing the PYTHIA events. Note that files can become quite large when many events are generated.

### PYTHIA as a plugin to ROOT

In more ROOT-centric applications, PYTHIA can be run as a ROOT plug-in. This requires a version of ROOT that has been installed from source. The reason is that the interfaces depend on PYTHIA header files that are not distributed with ROOT. Installing ROOT is not more difficult than the PYTHIA installation, and some guidelines are provided below.

#### Installation

To be run as a plugin, PYTHIA must be compiled as a shared library. This is achieved by running the PYTHIA `configure` script with the `--enable-shared` option before `make` is run.
Define an environment variable for the path to your PYTHIA installation directory

        export PYTHIA8=path_to_PYTHIA8_installation

Before compiling ROOT, configure ROOT by running the `configure` command including the following options

        --enable-pythia8
        --with-pythia8-incdir=$PYTHIA8/include
        --with-pythia8-libdir=$PYTHIA8/lib

In case ROOT has already been compiled before, it will only recompile the PYTHIA module and build the library `libEGPythia8`.

#### Interfaces

When running PYTHIA as a plugin, the exact interface structure becomes very relevant. ROOT provides two simple interfaces (wrappers) for PYTHIA 8. The code for these interfaces are located in

        path_to_ROOT_source/montecarlo/pythia8

The two interfaces are

- `TPythia8` is an implementation of the `TGenerator` interface for PYTHIA 8.
  It allows you to use PYTHIA within a ROOT macro or as a plug-in for a general-purpose particle generator based on this interface. The main methods of the interface are
  - `GenerateEvent()` which triggers the generation of the next event, and
  - `ImportParticles(TClonesArray* particles)` which copies the native PYTHIA stack into a `TClonesArray` of `TParticles`.
  In addition, some methods that are directly related to corresponding PYTHIA methods are implemented
  - `ReadString(const char* string)` -> `readString(...)`
  - `ReadConfigFile(const char* string)` -> `readFile(...)`
  - `Initialize(int idAin, int idBin, double ecms)` -> `init(...)`
  - `EventListing()` -> `event.list()`
  - `PrintStatistic()` -> `statistics()`
  These methods provide already the basic PYTHIA functionality interactively from the ROOT command line. However, this does not mean that the usage of PYTHIA from within ROOT is restricted to these methods. In compiled code, one can always obtain a pointer to the `Pythia` instance e.g.

          TPythia8        *tp = new TPythia8();
          Pythia8::Pythia *p  = tp->Pythia8();

  giving access to the full PYTHIA functionality. To access this functionality in the CINT interpreter see the "Advanced usage" section below.
- `TPythia8Decayer` is an implementation of the `TVirtualMCDecayer` interface.
  It allows you to use PYTHIA as a plug-in decayer for simulation frameworks based on the Virtual Monte Carlo (VMC) interface classes. The main methods of the interface are
  - `TPythia8Decayer::Init()` for initialisation,
  - `TPythia8Decayer::Decay(Int_t pdg, TLorentzVector* p)` to decay a particle with PDG code `pdg` and 4-momentum `p`, and
  - `ImportParticles(TClonesArray* particles)` to retrieve the decay products as `TParticles` in the `TClonesArray particles`.

#### An example

A basic example for generating minimum-bias events with PYTHIA 8 inside a ROOT macro, and filling some histograms with the kinematics of the final-state particles is provided in either of the locations below

        /path_to_ROOT_source/tutorials/pythia/pythia8.C
        /path_to_ROOT_installation/share/doc/root/tutorials/pythia/pythia8.C

Note that before executing this script

- the environment variables `PYTHIA8` and `PYTHIA8DATA` must be setup correctly e.g.

          export PYTHIA8=/path_to_PYTHIA_installation
          export PYTHIA8DATA=$PYTHIA8/xmldoc

- your LD_LIBRARY_PATH must contain the location of the PYTHIA 8 shared library, e.g.

          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:path_to_PYTHIA8_installation/lib

The script can then be run with ROOT

        root pythia8.C

After execution, ROOT will display some histograms from the event generation.

#### Advanced usage

To access the full PYTHIA functionality from the CINT interpreter, a ROOT dictionary must be created. An example of creating this dictionary is contained in the `rootexamples` directory. The `pythiaDict.so` library may be created by running

        make dict

This may then be loaded in ROOT giving full access to the full PYTHIA 8 functionality, e.g. in an interactive session

        gSystem->Load("path_to_PYTHIA8_installation/rootexamples/pythiaDict");
        Pythia8::Pythia *p = new Pythia8::Pythia();
        p->readString("SoftQCD:nonDiffractive = on");