rivet is hosted by Hepforge, IPPP Durham


The Rivet toolkit (Robust Independent Validation of Experiment and Theory) is a system 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. It is used by phenomenologists, MC generator developers, and experimentalists on the LHC and other facilities.


  • Object-oriented C++ framework for analysis algorithms
  • Ever-increasing collection of analyses, more than 400 so far...
  • Python interface and suite of user-friendly data handling scripts
  • Large collection of generator-independent event analysis tools
  • Automatic caching of expensive calculations, for efficiently running many analyses on each event
  • Flexible system for fast detector effect simulation in BSM analyses
  • Close matching of standard observables to experimental analysis definitions
  • Reference data connection to HepData, avoid hard-coding

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

The C++ MC generators Herwig and Sherpa have convenient user interfaces for producing input events for Rivet analysis, as well as built-in Rivet support. Users may find the Sacrifice interface convenient for running Pythia 8, and the AGILe steering interface useful for older Fortran generators like PYTHIA6 and HERWIG6.

2019-02-16: Rivet release 2.7.0

We are very pleased to release Rivet 2.7.0, which includes a several new features. Many of these should be considered to be experimental, in that they may not work perfectly and may therefore be modified in coming minor releases. Many of the new features are related to heavy ion analyses and will not affect any other analyses in previous release. But some changes will be noticeable to non heavy ion users.

The most visible change is that the size of the produced yoda files has doubled. This is done in order to enable having reentrant finalize. The produced yoda files will thus include the same analysis objects as previous versions, but will be supplemented by the same objects in the state they were before finalize() was called. These objects will have the same names as the normal ones but prefixed with "/RAW". The reentrant finalize does not yet work for all analyses, since it requires that all information is stored in analysis objects, but this will be fixed in upcoming minor releases.

Another visible change is that analyses can now be given pre-defined options. Specifying analyses on the form "MyAnalysis:Opt1=val1:Opt2=val2" will create and add a MyAnalysis object making the options available through the Analysis::getOption() function. Several objects of MyAnalysis with different options can be added in the same run. This is used to replace the duplication of some previous analyses, eg. ATLAS_2017_I1589844 which was duplicated in ATLAS_2017_I1589844_EL and ATLAS_2017_I1589844_MU for running with electron and muon channels separately.

The heavy ion features include a new way of handling centrality binning (which can also be influenced by options). Other things related to typical heavy ion analyses include an EventMixingFinalState projection and a Correlators framework for flow analyses.

For more details on these and other new features we refer you to the ChangeLog File.

This version (with YODA 1.7.4) is recommended for immediate production use. Enjoy!

Download source code

We also draw your attention to the new Rivet "LHC analysis coverage" web pages, where we have cross-referenced the Rivet analysis collection with all the LHC papers known to the CERN CDS system: https://rivet.hepforge.org/rivet-coverage . We have broken down the completion rates by each experiment, to provide a bit of competition!

Clearly-unsuitable papers have been removed from this tabulation, and "urgent" and in-progress analysis implementations are indicated: please let us know if you would like an analysis to be marked as in-progress or as high-priority and we'll update our files. The coverage pages will be periodically updated: complete coverage will always be a moving target!

Previous releases

2018-12-10: Rivet release 2.6.2

We are very pleased to release Rivet 2.6.2. This release mainly adds new analyses, plus consistency updates for reference data synchronisation with HepData, improvements to detector efficiency functions, bundling of more FastJet Contrib functionality, addition of (optionally) signed deltaPhi calculation, and a few small build-system improvements.

2018-08-14: Rivet release 2.6.1

We are very pleased to release Rivet 2.6.1 after a longer than intended gap. This release fixes several emergent build issues due to platform evolution, adds many new analyses, and includes many important bug-fixes and feature improvements.

2017-12-21: Rivet release 2.6.0

We are very pleased to release Rivet 2.6.0. This major release heralds several new analyses, and minor improvements and bugfixes, but also lots of important stuff behind the scenes:

  • Rivet (and YODA) can now read and write gzipped HepMC and YODA files :-)
  • Addition of a recursive composite structure to Particle, which enables a lot of cool stuff and is taking us toward an even more unified picture of particles and jets in the Rivet framework, although the latter is not there yet.
  • A new analysis build system, making builds faster and more uniform, and integration of contrib analyses *much* easier.
  • Lots of extensions to the filtering and functors system, and improvements to the detector parametrisation and machinery. In particular there's now a very lightweight way to pass multiple smearing/efficiency functors in a list, and they'll be executed sequentially through a uniform interface.

2017-06-18: Rivet release 2.5.4

We are very pleased to release Rivet 2.5.4.

A total of 36 new analyses have been added, covering experimental results from LEP, LHC, and a variety of smaller experiments. The ATLAS and CMS ICHEP 2016 0-lepton SUSY search analyses have been validated against official cut-flow data.

In addition, there are many small but worthwhile bugfixes and improvements in the Rivet scripts, analyses and data files, and the projection, functor and core class code interfaces. In particular this release contains several improvements and fixes to DIS projection classes, and a finally complete version of the ZEUS dijet photoproduction analysis from Rivet's earliest days!

2016-12-13: Rivet release 2.5.3

We are very pleased to release Rivet 2.5.3.

A total of 18 new analyses have been added, covering experimental results from all four LHC collaborations, as well as a LEP jet and event shapes analysis, and several BSM search analyses using the new detector simulation features.

In addition, the detector smearing machinery has been extended to include PID-specific tracking efficiencies and photon efficiencies based on Delphes' tabulation (NB. both sets of efficiencies are identical between ATLAS and CMS!), and a bug has been fixed in how the SmearedJets projection handles tagging efficiencies.

Finally, a 'keyword' mechanism has been introduced to the 'rivet' script to allow convenient calling of groups of related analyses; MissingMomentum now provides 'p' as well as 'E' kinematics; and a number of small bugfixes and syntactic/interface improvements have been made.

2016-09-22: Rivet release 2.5.2

We are very pleased to release Rivet 2.5.2. A total of 20 new analyses, both searches and measurements from LEP to Tevatron to LHC have been added in this release!

This release extends the new smearing machinery to include standard MET and electron efficiencies as well as their application in several new (search) analyses.

The Particle and Jet classes have also been enhanced significantly, allowing very expressive analysis code based on filter_select and filter_discard, useful in particular for decay analyses.

A new projection for PartonicTops has been added. This analysis approach is strongly discouraged, but the provision of a standard method means that we can still benefit from analyses done that way, and that those analyses are straightforward to write with minimal validation.

2016-08-09: Rivet release 2.5.1

We are very pleased to release Rivet 2.5.1 and the YODA histogramming package v1.6.3.

This patch release adds a new projection for smearing missing transverse energy in addition to the jet and identified-particle smearing machinery (for non-unfolded BSM analyses) first introduced in Rivet 2.5.0.

In addition it adds more internal sophistication to the smearing machinery, useful new particle classifier machinery for convenient passing of cuts, filtering functions, and smearing functions. This allows even more expressive one-liners and neater, more compact analysis code, e.g. in studying particle decays.

We have also fixed several bugs and enhanced the plotting machinery, the utility functions, the search path handling, etc., and have validated several older but incomplete analyses.

This version is recommended for immediate use: please update asap! The next release, 2.5.2, will focus on adding LHC BSM analysis codes demonstrating the new smearing features.

2016-07-07: Rivet release 2.5.0

We are very pleased to release Rivet 2.5.0 (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.

2016-06-28: Rivet release 2.4.3

We are happy to announce the release of Rivet 2.4.3.

This is a minor release which adds 5 new LHC analyses, finally validates several older unofficial analyses, and provides minor fixes to two more. In addition several bug fixes, and robustness & logistical improvements have been made to the build system, error logging, script user interfaces, and plotting code.

As usual we recommend all users to upgrade to this version immediately. It is available, as always, for manual or script-assisted build from the Rivet website.

Please note that in most cases Rivet 2.4.3 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.

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.

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