Your first Rivet run
So, we assume you've got Rivet installed and that the rivet command is available in your executable path (i.e. the $PATH environment variable). Now it's time to run some events, make some analysis data, and plot the results.
Generating and analysing
The main interface to Rivet is the rivet command. We will demonstrate how to use this to analyse HepMC events from a text file in the "IO_GenEvent" HepMC format.
Firstly, we recommend using a named pipe (or 'FIFO') so that your events don't create a huge file that takes all your disk space. The idea is that the generator will push events into what looks like a file, and Rivet will read from it. However, this 'file' is a direct pipe between the two processes (just like the shell pipe in e.g. echo foo | less), so no slow filesystem access needs to take place, no disk space is occupied, and the system will automatically balance the data flow between the writing and reading processes. All this is completely transparent to the user: good old Unix! Here's how you do it (with a fictional generator command, as an example):
> mkfifo fifo.hepmc > my-generator --num-events=500000 --hepmc-output=fifo.hepmc & > rivet --analysis=ANALYSIS_NAME fifo.hepmc
The backgrounding of the generator process -- i.e. the & character -- is important: the generator will wait until the fifo.hepmc pipe is being read by Rivet, so unless it is backgrounded you will never get the terminal focus back to run rivet!
WARNING: FIFOs don't work on AFS filesystems, probably so you don't get confused and think that they will allow you to exchange data between processes on different machines. If you are working on an AFS system, e.g. the home directories on CERN lxplus, you just need to make the FIFO on the local filesystem instead, e.g. mkfifo /tmp/$USER/fifo.hepmc.
If you have trouble with this FIFO approach, try writing a few -- 10 or so -- events to a normal file and look at the file (e.g. with emacs, less, gedit or any other text editor). If your generator is writing the events to file properly your HepMC file should consist of a short header, followed by lots of largely numeric lines starting with a letter (E, P, V in particular). If you don't see this, something has gone wrong "upstream" and you should fix it before blaming the FIFO or Rivet ;-)
Checking the data
By default, Rivet outputs its histograms in the YODA text format. To get a clearer view of the data values in histogram bins, you can use the yoda2flat script, e.g. yoda2flat Rivet.yoda - | less.
There is also a yoda2root command which provides the data as ROOT histogram (or TGraph) objects for those of a ROOTy disposition. Due to a ROOT bug, you may have to specify the "AP" options in the top right-hand box of the ROOT TBrowser, or alternatively draw the TGraph programmatically using myTGraph->Draw("AP"). This isn't a Rivet bug!
Rivet comes with three commands --- rivet-mkhtml, compare-histos and make-plots --- for comparing and plotting data files. These commands produce nice comparison plots of publication quality from the AIDA format text files.
The high-level program rivet-mkhtml will automatically create a plot webpage from the given AIDA files. It searches for reference data automatically and uses the other two commands internally. Example:
rivet-mkhtml withUE.yoda:'Title=With UE' withoutUE.yoda:'LineColor=blue'
Run rivet-mkhtml --help to find out about all features and options.
Plotting options will be taken from *.plot files installed in Rivet's share directory. These contain plotting instructions according to the make-plots syntax as documented in http://rivet.hepforge.org/make-plots.html . Such files can also be written for any plugin analysis and will be found if they are in the RIVET_ANALYSIS_PATH.
You can also run the other two commands separately:
compare-histos will accept a number of YODA files as input (ending in .yoda), identify which plots are available in them, and combine the MC and reference plots appropriately into a set of plot data files ending with .dat. More options are described by running compare-histos --help.
Incidentally, the reference files for each Rivet analysis are to be found in the installed Rivet shared data directory, installdir/share/Rivet. You can find the location of this by using the rivet-config command: rivet-config --datadir
You can plot the created data files using the make-plots command:
make-plots --pdf *.dat
The --pdf flag makes the output plots in PDF format: by default the output is in postscript (.ps), and flags for conversion to EPS and PNG are also available.
Note that the plotting tools internally use LaTeX for drawing, and for very complex plots it might sometimes fail with an error message like "TeX memory exceeded" (or "DVI file can't be opened"). In such a case it is recommended to increase the allowed TeX memory size as described e.g. in the pgfplots manual in Section 6.2.
We hope this was useful as a quick guide to getting started with running Rivet's built-in analyses for Monte Carlo generator validation.
If you're having trouble, there may well be some relevant help on the TroubleShooting page.