README

Rivet quickstart guide
----------------------

Assuming you've got a copy of Rivet installed on your machine, you'll now want
to know how to use it. Here's an example session with the 'rivet' command, which
should be illustrative.


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 filesystem 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
the same 'file'. In fact, though, the 'file' is a disguised pipe between the two
processes, so no slow filesystem access needs to take place, and the system will
automatically balance the data flow between the writing and reading processes:
the generator will only write more event data when Rivet has read that currently
available in the FIFO buffer. All this is completely transparent to the user:
good old Unix!  Here's how you do it:

> mkfifo hepmc.fifo
> my-generator --num-events=500000 --hepmc-output=hepmc.fifo &
> rivet --analysis=ANALYSIS_NAME hepmc.fifo

The backgrounding of the generator process is important: the generator will wait
until the hepmc.fifo pipe is being read by Rivet, so unless it is backgrounded
you will never get the terminal focus back to run rivet!

The generator used above can be anything which writes HepMC text output to the
specified FIFO. As a concrete example, you could use a Pythia 8 main program to
write events to the FIFO, and pick them up on the other end with rivet:

> ./main42 py8config.cfg hepmc.fifo &
> rivet --analysis=CDF_2001_S4751469 hepmc.fifo

The rivet command provides extensive command line documentation when called
with the -h/--help flag.


CHECKING THE DATA

Rivet outputs its histograms in the YODA format. You can read it directly, but
more conveniently there are a variety of command-line utilities whose names
start with "yoda", for viewing and manipulating these files' contents.

There is also an yoda2root command which provides the data as ROOT TGraph
objects for those of a ROOTy disposition. Due to a ROOT bug, for TGraphs to
display properly you will have to specify the "AP" option 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: it's ROOT forgetting to draw the
graph axes!


PLOTTING

Rivet comes with two commands --- rivet-cmphistos and make-plots --- for comparing
and plotting our output data. These
commands respectively combine many YODA files in (usually) convenient ways, to make
.dat files describing plots to be made, and then render those plots to publication
quality PDFs. This way you can tweak the .dat file for optimal aesthetics without
re-running the data processing steps. rivet-cmphistos also accepts various
command-line modifiers to change major rendering features. The most convenient way
to make plots from Rivet YODA files, however, is with the rivet-mkhtml script:

> rivet-mkhtml path/to/CDF_2001_S4751469.aida py.aida:'Pythia 6.418' hw.aida:'Herwig++ 2.3.0'

will create a rivet-plots directory containing a set of web pages with thumbnail
plot images, linked to full PDF versions of the plots.

[In detail, this command compared the three named data files (ending in .yoda),
identified which plots are available in them, and combined the MC and reference
plots appropriately into a set of plot data files ending with .dat. The strings
after the ":" for the MC files are specifying ID strings to appear in the plot
legends. You can also run rivet-mkhtml to just compare MC-MC data files. More
options are described by running 'rivet-mkhtml --help'.]

Incidentally, the reference files for each Rivet analysis are to be found in the
installed Rivet shared data directory. You can find the location of this by
using the rivet-config command:

> rivet-config --datadir


THAT'S ALL!

We hope this was useful as a quick guide to getting started with running Rivet's
built-in analyses for Monte Carlo generator validation. Get in touch via the developer
mailing list if you need any assistance: rivet@projects.hepforge.org