Rivet is hosted by Hepforge, IPPP Durham

The Analysis Modules for Rivet

There is one Analysis for every physics paper implemented.

They produce the histograms which can be compared to the published plots in the paper.

They calculate event properties and implement kinematic cuts using RivetProjections.

They book, fill and output histograms using the YODA interface via auxilliary RivetHistogramming code. Each event is passed to the analysis and operated on by the projections. The result of the projections operating on the event determines whether the event is accepted and what is plotted.

All the Analyses to be used are instantiated at the beginning of a Rivet run.

All Analyses inherit from the Analysis abstract base class.

Writing your own analysis

Rivet uses pluggable analyses: this system allows users to build and run their own analysis without needing to re-build the Rivet library.

See WritingAnAnalysis for instructions on writing your own analysis routine.

How analyses get loaded

When you build your new analysis a RivetMyAnalysis.so library will be created, which Rivet needs to find. Rivet scans several directories at runtime to find the library files containing analyses. Specifically, the following search locations are tried, in order:

  • a directory listed in RIVET_ANALYSIS_PATH
  • the directory where libRivet.so is installed (i.e. the Rivet $prefix/lib directory)
  • the current directory.

If a duplicate analysis is found in more than one location, Rivet will complain but will not crash. The first version to be found will be used.

Note that (to reduce the number of attempted loadings) the library name must contain the word Rivet and end in the appropriate shared library suffix for the OS: this is .so for Linux and Macs.

Defining the kinematics

Each analyses should collect information from the Projections it uses as to what kinematic cuts and what input beams are need for this analysis. See CutsAndBeamConstraints.

Real Data

YODA files for all measurements are distributed with Rivet for comparison to the generated plots. These files are obtained from HepData, but distributed with the Rivet code for standalone running.

These data files are also used to auto-book the histograms which are filled by the Monte Carlo (See RivetHistogramming).


EXAMPLE.cc is a good example to start with.

ExampleTree.cc is a special analysis which shows you how to book and fill a root tree from Rivet. Please don't write analyses like this unless you really need to!

Analysis tutorial

A first simple example of an analysis can be found in a test analysis function, implemented in the form of EXAMPLE.cc. This example analysis shows the characteristic elements which have to be implemented, following the interface defined by the abstract Analysis class.

The histograms to be filled are declared as member variables in the class header and are booked in the init() member function of the class body. The booking can either be done "by hand" (i.e. either specifying the number of uniform-size bins in a range, or specifying all n+1 bin edges) or by a system we call "autobooking". The latter is the recommended way. It works as follows: at installation time, Rivet installs a set of YODA histogram files into the ${prefix}/share/Rivet directory, one file per analysis. At runtime, if the histogram booking has just specified the dataset, x-axis, and y-axis HepData codes of the histogram, these data files are used to look up the bin edges of the appropriate histogram and book the histogram based on them. This method is more compact than manual booking, and is also more robust as the binnings of the reference data and the generated data are guaranteed to match.

The actual evaluation of a given event and the filling of histograms is done in the analyze(const Event&) member function. Rivet will use this method repeatedly in the event loop. Pre-designed projections to obtain the wanted quantities to be filled in the histograms can be applied to an event. The example analysis makes use of several projections which determine some particle event properties. The projections explicitly used in the analysis code in turn use a final state projection which provides a list of final state particles, ignoring all particles with intermediate status in the HepMC event record particle history.

A finalize() function allows one to add needed steps if any at the end of an analysis. Here for example we normalize the histograms which have been filled during the event loop in the analyze function. The histograms are written to a file (Rivet.yoda by default) automatically -- this does not need to be added to the finalize() member function. Several analyses can be evaluated simultaneously, i.e. the same generated event is being analysed multiple times: in this case, equivalent projections used in multiple analyses only get evaluated once, making the system CPU-efficient.

Last modified 2 years ago Last modified on Apr 29, 2015, 6:54:30 PM