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
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.
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 ---
make-plots --- for comparing and plotting data files. These commands
produce nice comparison plots of publication quality from the AIDA format text
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'
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
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
Incidentally, the reference files for each Rivet analysis are to be found in the installed Rivet shared data directory,
can find the location of this by using the
You can plot the created data files using the make-plots command:
make-plots --pdf *.dat
.ps), and flags for conversion to EPS and PNG are also
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.