Rivet is hosted by Hepforge, IPPP Durham


The Rivet project (Robust Independent Validation of Experiment and Theory) is a toolkit for validation of Monte Carlo event generators. It provides a large (and ever growing) set of experimental analyses useful for MC generator development, validation, and tuning, as well as a convenient infrastructure for adding your own analyses. Rivet is the most widespread way by which analysis code from the LHC and other high-energy collider experiments is preserved for comparison to and development of future theory models.

Take me to the code!

Jump to Rivet library and analysis releases

Key features

Rivet is an object oriented C++ replacement for the venerable HZTool/HZSteer system. It is used by both phenomenologists/generator developers and by the LHC experiments for generator tuning, analysis prototyping, and MC-data comparisons.

Rivet's design emphasises the separation between HepMC records and where they came from, allowing it to be a completely cross-generator validation platform. Internally, it uses a computationally efficient mechanism (known as the "projections" system) to compute physical observables, so that re-calculation of common quantities is avoided.

Another key feature of Rivet is the avoidance of hard-coding reference data or histogram binnings in the analysis code: Rivet provides functions to extract this information from bundled data files, meaning that it is much easier to keep reference and generated data synchronised.

The Rivet user manual is kept up to date on the arXiv (1003.0694 [hep-ph]).

For Fortran generators you may find it useful to combine Rivet with the AGILe generator steering interface, but for C++ generators such as Herwig++ and Sherpa the built-in control programs are much better. For Pythia8, we recommend using the Sacrifice interface, which behaves much like AGILe.

More information on the status of the project, as well as a more detailed description and documentation, can be found via the links on the left.

2016-05-05: Rivet release 2.4.2

We are happy to announce the release of Rivet 2.4.2.

This is a minor release which adds 5 new LHC analyses, adds various robustness and logistical improvements, and fixes bugs in analyses and in PID code interpretation.

The last of these was introduced only in 2.4.1 and could lead to small errors in jet tagging and unstable particle decay studies: for this reason we recommend immediate upgrade of any Rivet 2.4.1 installations to 2.4.2. It is available, as always, for manual or script-assisted build from the Rivet website.

Please note that in most cases Rivet 2.4.2 should be built against version 1.5.9 of the YODA histogramming package. The YODA 1.6.x series requires C++11 and is primarily intended for the approaching Rivet 2.5.x releases. However, if you are already building Rivet with a -std=c++11 compiler flag (or similar) then there should be no problem with using the latest YODA.

Download source code

2016-04-22: Rivet beta test release 2.5.0beta1

We are very pleased to provide a first beta-testing release of Rivet 2.5 (and the 1.6 series of the YODA histogramming package), with three major new developments that we think you'll like:

  1. Addition of simple (but very flexible and efficient!) detector smearing machinery, mainly for use in BSM analyses.
  2. Tools to easily calculate Lorentz transformations to boost into the beam centre-of-mass system (for fixed-target and cosmics analyses)
  3. Elimination of the Boost library in favour of C++11. A technicality, but a nice one!
To use the beta, use the special bootstrap script, run in the usual fashion. Since the new release requires C++11, you will need to ensure that your environment has a capable compiler before running the script. Then it should "just work". Let us know if you require assistance, and please provide feedback and suggestions for improvements.

Now a few more details on the two new physics features:

Detector effect smearing

We have added new SmearedParticle and SmearedJet projection classes. Examples of these in use can be found in the new EXAMPLE_SMEAR analysis. They are very simple and flexible: the SmearedParticles projection can be wrapped around any particle-finding projection (e.g. a FinalState), while the SmearedJets wraps around any JetAlg — in practice this will almost certainly be FastJets. This nicely decouples the smearing from the usual physics object operations.

Both smearing classes are configured with objects that parameterise reconstruction efficiencies and kinematic/identification/tagging inaccuracies: you can write your own functions for this, including C++11 inline lambda functions if you like that sort of thing, but we imagine that most people will want to use the new standard set of LHC detector/reco smearings encoded in Rivet. This way of doing things means that each analysis routine can apply the smearings and efficiencies appropriate to its "epoch" of the detector and reco software, and the ID/tagger working points used in the data analysis. Thanks to our usual automatic projection caching, when running many analyses from the same epoch each smearing will be performed only once, keeping us computationally efficient.

Beam boosts

To make Rivet friendlier for asymmetric beam analyses, we have removed an old feature which would automatically rotate the event to ensure that the +z beam was a proton. This was originally added to work-around a limitation in Fortran HERWIG for HERA analyses, but is now more of a problem than a solution. We have also provided tools to easily calculate a LorentzTransformation into the beam centre-of-mass frame — for example:

  #include "Rivet/Projections/Beam.hh"
  const LorentzTransform beamboost = beamCMSTransform(event);
  Particles fsparticles = myfinalstate.particles();
  for (Particle& p : fsparticles)

Something similar can be done to transform Jet objects into the beam frame — or by any LorentzTransform you happen to calculate. It's not rocket science, but it is significantly more user-friendly than what's been available so far. We hope to build frame-boost features directly into projections in future, which will be even more convenient, but that requires a bit of careful engineering and we hope that this stop-gap solution will make life easier for several users. Please try it out.

Previous releases

2016-03-09: Rivet release 2.4.1

We're very pleased to announce the release of Rivet 2.4.1 and an accompanying release of version 1.5.9 of the YODA histogramming package.

New features:

  • 6 new analyses, and various code and data fixes
  • Various framework improvements, including the ability to skip events from input files, pass trimming configurations to FastJets, and book YODA Counters in analyses
  • Improved plotting functionality and backend improvements
  • Intermediate histogram files are now written every 10k events by default
  • Compiler happiness and HEP-library compatibility improvements
  • Please see the ChangeLog for full details
As always, this new version is recommended for immediate use. Please keep sending us your feedback and analysis codes!

2015-10-07: Rivet release 2.4.0

We're very pleased to announce the release of Rivet 2.4.0 and an accompanying release of version 1.5.5 of the YODA histogramming package.

New features:

  • 12 new analyses, including first 13 TeV data!
  • The WFinder has been further improved to make the best information hypothesis of neutrino kinematics without needing to rely on "detecting" a particular neutrino with a zero mass hypothesis -- this avoids a too-large energy (and hence mass) being set due to out-of-acceptance particles.
  • The MissingMomentum projection and FourMomentum have acquired extra methods to help with 3-momentum balance operations like converting visible momentum into missing momentum without accidentally getting a negative energy or having to modify the individual vector components.
  • A function has been added to ZFinder to retrieve all fiducial dressed leptons, for example to allow vetoing on a third one.
  • By request, you can now pass an arbitrary Cut to the Jet.bTags() and similar methods, to exclude very soft, experimentally unavailable truth-tag particles.
  • The FastJets projection is now more compatible with FastJet's own "pure ghosts": these will be excluded from the reported Jet constituents, without interfering with Rivet's own ghost approach to flavour tagging.
  • Cross-section and event counter are now written out by default -- these should be very useful for run merging of multiparton generation with separate partonic multiplicity samples, cf. MadGraph and Alpgen. The Rivet scripts do not yet use these, so please get in touch if it sounds useful! You'll need the latest YODA to read them correctly.
  • Since the latest versions of YODA fully support reading the 1D and 3D scatter data types, we've now templated the Analysis::refData() functions so you can book analysis objects other than 1D histograms and profiles based on the reference data.
As always, this new version is recommended for immediate use. Please keep sending us your feedback and analysis codes!

2015-07-24: Rivet release 2.3.0

We're very pleased to announce the release of Rivet 2.3.0 and an accompanying release of version 1.4.0 of the YODA histogramming package.

This new release of Rivet adds an amazing 15 new analysis routines, as well as validating several long-standing analyses from the UNVALIDATED set (and two re-UNVALIDATions!) and making a variety of minor analysis fixes and improvements. As you'd expect from the non-trivial release number change, the framework has also received some significant improvements.

One long-standing issue has been whether neutrinos are to be included in jet finding or not: detectors do not see them, of course, but MC-driven calibrations can add their average contributions back to the 4-vectors. But telling the FastJets projection to useInvisibles() would include hard-process neutrinos (and invisible BSM hypotheticals), while calibrations would typically only be intended to account for neutrinos from hadron decays. We have changed the behaviour of useInvisibles() to only accept non-prompt stable invisibles, and added both an optional argument to that method and the FastJets constructor to allow any of the three sane invisibles strategies to be specified via enums. A similar method, enum, and optional constructor parameter has been added for the treatment of muons. We've checked that there are no substantial changes to any VALIDATED analyses. Some very specific jet-splitting analysis features have also been removed from FastJets — it's nowadays better to use FastJet's API directly — and we've added a convenient extra constructor from a FastJet::JetDefinition.

The second major change has been to the behaviour of the WFinder. Previously this used a missing ET cut to decide whether an event could be considered as containing a leptonic W, but then a specific neutrino was selected in an l+nu pair used to build the pseudo-W. That's not experimentally possible, of course, and given Rivet's emphasis on observable measurements we have changed the default to allocate all the MET to the W candidate. No significant changes in analysis outputs were found by our testing system. This has, however, introduced a discussion on whether a W finder is a sensible object for us to provide: neither leptonic or hadronic W's are fully constructible from final-state observables via an unambiguous procedure, and we expect that each analysis that tries may have a different approach. Hence in a later release the WFinder may disappear entirely, but for now it is still in place, but with a more portable — but less accurate — behaviour.

Other technical improvements have been made to e.g. protect against accidental 'slicing' of C++ objects when using the remainingFinalState() method. Please see the ChangeLog for the full list of substantial changes since release 2.2.0.

As always, this new version is recommended for immediate use. Please keep sending us your feedback and analysis codes!

2015-03-24: Rivet release 2.2.1

We're very pleased to announce the release of Rivet 2.2.1 and an accompanying release of version 1.3.1 of the YODA histogramming package.

This new release of Rivet is a minor update but contains several important bug fixes and improvements: a bugfix in isCharmHadron(pid), use of vector rather than scalar pT for the MET cut in WFinder, a fix to the transverse mass setting (also) in WFinder, improvement of numerical tolerance handling in the Vector3::angle() function, and adding a missing projection comparison operator to the HeavyHadrons class.

In addition, the Cuts system has been improved with new Cuts::abseta and Cuts::absrap selectors, and the ability to logically combine them with standard &&, || etc. operators. Many Projection interfaces have also been updated to use the new Cuts functionality. We've also added a --cmd option to rivet-buildplugin to help users of LCG Grid distributions, and the possibiity to pass PLOT parameters via a pseudo-file argument to rivet-cmphistos and rivet-mkhtml. Finally we have provided a FinalPartons projection to help, for example, with the new QCDAware Fastjet plugin, a set of particle charge/sign comparison functions, and 16 new analyses! Please see the ChangeLog for the full list of substantial changes since release 2.2.0.

As always, this new version is recommended for immediate use. Please keep sending us your feedback and analysis codes!

2014-09-30: Rivet release 2.2.0

We're very pleased to announce the release of Rivet 2.2.0 and an accompanying release of version 1.3.0 of the YODA histogramming package.

This major new release of Rivet adds long-planned improved integration with FastJet; new jet tagging mechanisms based on ghost association; a new super-flexible system for kinematic cuts; new ParticleFinder, TauFinder, and improved Hemispheres projections; fixes galore; and a mighty 12 new data analyses.

As always, this new version is recommended for immediate use. Please keep sending us your feedback and analysis codes!

2014-06-02: Rivet release 2.1.2

We are very happy to announce the release of Rivet version 2.1.2.

This release adds seven new analysis routines from ATLAS and CMS, fixes a few bugs in CMS_2013_I1209721, OPAL_1998_S3749908, ALEPH_2001_S4656318, and in the Rivet::Particle::abspid function, improves clang and Boost compiler compatibility, and adds new utility functions, more handy direct kinematics functions on Jet and Particle, and finally reactivates our support for 2D histogramming, including 2D profile histograms.

As always, this new version is recommended for immediate use. Please keep sending us your feedback and analysis codes!

2014-03-10: Rivet release 2.1.1

We are very happy to announce the release of the third Rivet version in the 2.x series, version 2.1.1.

This version updates the Rivet 2.1.0 analysis content to contain four new analyses (two each from ATLAS and CMS: see the analysis content diff page), and providing better tools for Particle/Jet sorting (e.g. a new sortByPt() function for Jets and Particles vectors) and querying Particles about their decay products. Access has been provided to the YODA analysis object collection via the AnalysisHandler interface.

There are of course also bug-fixes and as always we encourage everyone to upgrade immediately. Installation requires the new YODA version 1.0.6, released at the same time. Build scripts for LCG and stand-alone systems are available: check the "Getting started" doc page.

We intend to continue with more 2.1.x minor releases to provide analysis updates as rapidly as practically possible. The next major release will be version 2.2.0, in which the jet, histogram, and kinematic cuts systems will be significantly upgraded.

2013-10-25: Rivet release 2.0.0

After an epic journey of code migration, testing, and endless technical bugfixing, we are extremely pleased to finally announce the release of Rivet 2.0!

The main difference in this release series is the complete overhaul of the histogramming system to use the new YODA package. This is a vast improvement over the AIDA system that we have used since the origins of Rivet, and makes much analysis statistics handling code far simpler and cleaner. It also automatically handles gaps in binning, allows statistical merging of histograms from multiple generator runs, and sets us up to add some very nice features involving multiple weights, NLO counter-events, writing final-style histograms throughout a run, and merging of more complex data objects.

On the physics tools side, we also have big plans for the Rivet 2 series, including improvements to the jet system for flavour tagging and substructure analyses. Plus more and more data and MC validation analyses, of course!

We recommend that everyone begin to migrate their production systems to use Rivet 2. Please let us know if you have any teething troubles and we will do what we can to alleviate them. There will be one more release in the 1.x series: 1.8.4 and 2.0.1 will be released in parallel to add all the analyses which have been supplied to us but have not yet appeared in a release due to the length of time that it has taken to produce Rivet 2.0.0. After that, it will be version 2 all the way ;-) Apologies and thanks to everyone who has been patiently waiting for their analyses to appear in a release.

2013-12-16: Rivet release 1.9.0

Release 1.9.0 of Rivet is now available. This is the final release in the 1.x series, primarily to supply new analyses which were provided to us during the development of version 2.0.0. A version 2.1 will be provided to bring the analysis content of the 2.x line up to the same point. As always, many thanks to everyone involved in preparing the new analyses!

Rivet 1.9.0 is recommended for immediate production use for those who have not yet moved to the 2.x series. An updated manual – documenting use of the system, the standard analyses, and the underlying mechanisms – is available in the tarball, on this website, and on the arXiv. All 1.x users are encouraged to upgrade immediately... and to then immediately move on to 2.x!

Please let us know your experiences using Rivet, send us your analysis code to be included in future releases, and suggest improvements by emailing us at rivet@NOSPAMprojects.hepforge.org