## RIVET usage

RIVET is a toolkit for the validation of Monte Carlo event generators [Buc10]. It contains the results of many experimental analyses, so that generator output can easily be compared to data, as well as providing a framework to implement your own analyses. Although using PYTHIA with RIVET is not officially supported, some helpful hints are given below. The full RIVET manual is available online.

### Using PYTHIA with RIVET

The following assumes that you already have RIVET installed. Instructions for this may be found here.
Events are passed from PYTHIA to RIVET using the HepMC format. PYTHIA must be compiled with HepMC support, using the same version of HepMC used when compiling RIVET. This is setup through the PYTHIA `configure` script e.g.

      ./configure --with-hepmc=/path/to/HepMC

The PYTHIA library itself does not need to be recompiled.
The `examples/main42.cc` sample program can then be used to generate events in HepMC format (which `examples/main43.cc` extends by allowing subruns). When in the `examples` directory, the main program can be built and used as follows

      make main42
      ./main42 main42.cmnd main42.hepmc

The first argument is the input file which provides the options for event generation, while the second is the output file where the HepMC events should be written.
This HepMC file may now be read and processed by RIVET

      rivet --analysis=ANALYSIS_NAME main42.hepmc

where `ANALYSIS_NAME` is a built-in RIVET analysis, or one you have created yourself. The output of RIVET is in the form of `.aida` files, containing the histograms for the analysis, which can be processed further with RIVET (see the RIVET documentation for more details).
The above examples requires that (potentially large) HepMC events are stored to disk before being read by RIVET. It is possible, instead, to pass the events directly to RIVET as they are produced by using a `FIFO` pipe. This is done with the `mkfifo` command

      mkfifo my_fifo
      ./main42.exe main42.cmnd my_fifo &
      rivet --analysis=ANALYSIS_NAME my_fifo

Note that `main42` is run in the background.

### Compiling PYTHIA with RIVET

It is also possible to compile a PYTHIA main program together with the RIVET library. To facilitate this, there is a header file called `Pythia8Plugins/Pythia8Rivet.h` defining a helper class called `Pythia8::Pythia8Rivet`. To use this class, a main program needs to be modified as follows:

      #include "Pythia8/Pythia.h"

      // Include the Pythia8Rivet header file.
      #include "Pythia8Plugins/Pythia8Rivet.h"

      int main() {

        Pythia pythia;

        // Setup the run by reading strings or a command file.

        pythia.init();

        // Create a Pythia8Rivet object and add (one or several) analyses.

        Pythia8Rivet rivet(pythia, "outputfile.yoda");
        rivet.addAnalysis("AnalysisName");
        rivet.addAnalysis("AnotherAnalysisName");

        for (int iEvent = 0; iEvent < 100; ++iEvent) {
          if (!pythia.next()) continue;

          // Push event to Rivet.
          rivet();

          // Maybe do other non-Rivet analysis.
        }

        // Tell Rivet to finalise the run.
        rivet.done();

      }

To compile the program, information about where Rivet and YODA are installed is needed. Hence the compile flag `-I/path/to/rivet/installation/include` is needed, as well as the link flag `-L/path/to/rivet/installation/lib -lRivet -lYODA`. (Further information about how to compile and link Rivet can be found using the `rivet-config` script distributed with Rivet.)

The example program `main111.cc` includes optional analysis with `Pythia8::Pythia8Rivet`. To use it, compile the program with the flags above and add `-DUSE_PYTHIA8_RIVET`.

The most common user case (run PYTHIA with a run card, using one or several RIVET analyses) is implemented in the example `main93`. The sample command file `main93.cmnd` provides a good starting point. The lines:

        Main:runRivet = on
        Main:analyses = ATLAS_2010_S8817804,ALICE_2010_S8625980,CMS_2011_S8957746
        Main:writeHepMC = on

provides the switch to run RIVET, and gives the user the possibility to add any number of (installed) RIVET analyses to the run, as a comma separated list. The last line is the switch needed to write a HepMC file. The example is run with:

        ./main93 -c main93.cmnd

and a .yoda file (the RIVET output) is then written. There are several other useful command line options to `main93`. They are all displayed by running `./main93 -h`.