PaperlayerView exact revision on arXiv

Source-linked AI summary

Rivet user manual

Andy Buckley, Jonathan Butterworth, David Grellscheid, Hendrik Hoeth, Leif Lonnblad, James Monk, Holger Schulz, Frank Siegert

arXiv:1003.0694v8hep-ph

TL;DR

Rivet addresses the need for portable, scalable validation and tuning of Monte Carlo event generators with reusable collider analyses. The manual presents its C++ framework, command-line and extensibility workflows, and analysis practices, including caching and physically meaningful event selection. It concludes that Rivet enables generator validation with minimal effort and maximum portability, while some infrastructure choices retain runtime-safety and portability limitations.

  • Problem

    Rivet targets the challenge of validating and tuning different Monte Carlo generators with portable, reusable collider analyses.

  • Method

    Rivet provides a C++ analysis framework operating on generic HepMC records, with reusable analyses, automated result caching, and guidance for physically meaningful particle-level selections.

  • Results

    Rivet provides infrastructure and calculational tools for generator validation and tuning with minimal effort and maximum portability, scaling to large numbers of analyses through automated result caching.

  • Takeaways & Limitations

    The manual supplies users with workflows for running existing analyses and examples for implementing analysis modules within a flexible validation framework.

  • Takeaways & Limitations

    MC analyses should avoid relying on ambiguous generator truth records, and projection caching may trade compile-time type safety for runtime errors.

Abstract

from arXiv · show

This is the manual and user guide for the Rivet system for the validation and tuning of Monte Carlo event generators for high energy physics. As well as the core Rivet library, this manual describes the usage of the rivet program and the AGILe generator interface library. The depth and level of description is chosen for users of the system, starting with the basics of using validation code written by others, and then covering sufficient details to write new Rivet analyses and calculational components.

PROGRAM SUMMARY

Rivet is a portable C++ framework and user-facing toolkit for validating and tuning Monte Carlo event generators through particle-level analyses. It supports command-line, library, and plugin-based workflows, with automated caching designed to scale across many analyses.

  • Framework purpose: Rivet provides infrastructure and calculational tools for particle-level collider analyses, enabling generator validation and tuning with minimal effort and high portability.Its automated result caching supports scaling to large numbers of analyses for global validation.
  • Framework purpose: Analyses operate on generic HepMC event records, making generator independence an explicit design requirement.The framework hides most machinery while retaining power and extensibility for analysis authors.
  • Using Rivet: The rivet command reads generated HepMC events and produces structured textual output, while Rivet can also run as a library inside larger frameworks.AGILe, especially agile-runmc, helps generators without a native HepMC production interface.
  • Using Rivet: Users can work at three levels: run existing analyses, write plugin analyses, or develop against Rivet’s internal infrastructure.The manual prioritizes quickly reaching physics plots, while detailed implementation guidance is provided for authors and developers.
  • Installation: A bootstrap script downloads and builds Rivet, AGILe, and required libraries in the correct order, with workarounds for CERN AFS software versions.It also writes environment settings that can be sourced before running Rivet.

3. Running Rivet analyses

Rivet runs analyses on HepMC streams or files through the rivet executable, with FIFO streaming recommended to avoid large intermediate files and filesystem overhead. Analyses are classified by validation status, and command-line tools support discovery, execution, output, and debugging.

  • Running analyses: The rivet executable reads HepMC events in standard ASCII format from either a file or a text stream.It is presented as the easiest way to use Rivet.
  • The FIFO idiom: FIFO streaming avoids storing simulated events and can prevent a 1M-event LHC run from occupying ∼60GB on disk.Filesystem involvement typically doubles the time needed to make and analyse the events.
  • The FIFO idiom: FIFO streaming has no performance penalty because the filesystem object is not written during the process.The generator is backgrounded before Rivet reads from the named pipe.
  • Analysis status: Standard analyses are classified as validated, preliminary, obsolete, or unvalidated, in roughly decreasing order of academic acceptability.Validated analyses are checked against published Monte Carlo points and normally code-checked for maintainability.
  • Analysis status: Preliminary analyses may change or disappear, and their names commonly change when they enter the standard library.They lack Spires/Inspire identifiers, so scripts using them may break across Rivet upgrades.
  • Analysis status: Unvalidated analyses are incomplete, flawed, or doubtful and are not built by default.They can be enabled with --enable-unvalidated, while obsolete analyses are retained for one major Rivet version before removal.
  • Command-line tools: Command-line options list analyses, show details, run selected analyses, write histogram files, and control hierarchical logging for debugging.The logging controls can target individual analyses and projections without enabling debug output everywhere.

4. Using analysis data

Rivet produces histogram data for validation, tuning, comparison, and plotting, with tools to convert, trim, normalize, compare, and render AIDA files. The workflow supports reference-data normalization and publication-quality plots.

  • Data formats: Rivet output can be converted from AIDA XML to ROOT TGraphs or a hand-readable flat text format.The aida2flat script is useful for inspecting AIDA contents, while ROOT rendering requires the AP drawing option for TGraphs loaded from file.
  • Histogram processing: rivet-chopbins keeps only specified x-value ranges for individual histograms, which is useful when tuning generators against selected bins.The example retains x values from 5 to 13 for a leading-jet p⊥ histogram.
  • Histogram processing: rivet-rescale normalizes histograms to generator cross-sections, arbitrary areas, or corresponding reference-data areas.A selected histogram can be normalized to 1.0, or its remaining bins can be normalized after chopping a specified range.
  • Reference data: Reference files are installed in Rivet’s shared data directory, whose location can be found with rivet-config --datadir.Reference-data normalization can be restricted to named histograms and selected bin ranges.
  • Plotting and comparison: Rivet’s plotting tools produce publication-quality comparison plots from AIDA-format text files.The command set includes rivet-mkhtml, compare-histos, and make-plots.
  • Plotting and comparison: rivet-mkhtml automatically creates a plot webpage, searches for reference data, and uses the comparison and plotting commands internally.The other commands can also be run separately to create plot data files and render them.

Selected analyses

Each Rivet release includes a broad standard library covering 250 experimental measurements or Monte Carlo validation studies. The catalogue provides publication, collider, status, authorship, and run-detail information for comparing predictions with data.

  • Library scope: The standard Rivet library implements 250 experimental measurements or Monte Carlo validation studies.The analyses span the full spectrum of collider experiments, with the complete listing available online and in the release documentation.
  • Analysis information: Each analysis record includes its collider, original publication references, implementation status, authors, and run details for comparison with data.These metadata support selecting and running analyses across the library.

5. Selection of analyses available in the Rivet framework

Rivet provides a broad library of validated analyses spanning collider processes, experiments, energies, and observables for generator validation and tuning. The available analyses include particle production, event shapes, underlying-event activity, jet observables, and cross sections.

  • Particle production: Particle-production analyses measure identified pions, kaons, protons, charm hadrons, taus, photons, and neutral pions.These analyses address fragmentation, decay, inclusive production, and photon-plus-jet processes.
  • Coverage: Validated analyses cover e+e−, pp, and p¯p collisions across experiments including ALEPH, ALICE, ATLAS, BABAR, Belle, CDF, CMS, D0, DELPHI, H1, LHCb, LHCf, and CLEO.The listed measurements span energies from several GeV to 7 TeV-scale collider collisions.
  • Generator setup: Several analyses document explicit generator conditions, such as enabling diffractive events, selecting dileptonic ttbar events, or restricting hard gamma-plus-jet processes.These requirements define the event samples needed to populate the corresponding histograms.
  • Underlying event and jets: Underlying-event and additional-activity analyses use regional or veto-based observables to probe soft and extra-jet activity.The CDF analysis defines toward, away, and transverse regions relative to the leading jet, while the ATLAS analysis studies veto fractions across rapidity intervals.
  • Event shapes and flows: Event-shape and energy-flow analyses include thrust, jet mass, broadenings, Y23, transverse thrust, minor, and transverse energy flow.The measurements cover e+e− annihilation, pp collisions, and deep-inelastic ep scattering.

How Rivet works

Rivet analyses are collections of routines that produce histograms for comparison with reference data, while projections provide reusable event-analysis calculations. The framework uses object-oriented abstractions to organize these components.

  • Analyses: Analyses contain routines that make histograms for comparison with reference data.The manual contrasts this histogramming system with earlier HZTool experience.
  • Projections: Projections are event-analysis calculations whose outputs can represent event shapes or selective views of the final state.They are introduced as a more compact name for observable calculators.
  • Composition: Projections can be nested inside analyses and other projections, allowing complex calculations to be composed from simpler components.The manual presents nesting as part of Rivet’s object-oriented organization.

6. The science and art of physically valid MC analysis

The manual argues that physically valid MC analyses must avoid treating simulated event records as literal truth. Rivet instead emphasizes portable analyses based on experimentally meaningful reconstructed objects and final-state information.

  • Role of simulation: MC generators provide fully exclusive events useful for exploring correlations and optimizing analyses, but experiment remains the authority on how the world behaves.The manual cautions that simulation encodes known physics while phenomenologically exploring non-perturbative QCD.
  • Bias and misuse: Using MC-derived quantities as measured data can introduce systematic biases, and publishing inferred quantities such as measured quarks can produce results of limited later use.The manual urges caution against both obvious and subtle forms of MC misuse.
  • Validation challenge: Tevatron Z-boson p⊥ measurements are difficult to use portably because QED-unfolded or MC-filled regions depend on generator event-record conventions.The peak near O(1-2 GeV) is sensitive to intrinsic p⊥, soft initial-state radiation, and QED bremsstrahlung, while the published treatments complicate analysis construction.
  • Portability: Generator event records differ in graph structures and particle content, so analyses that depend on generator-specific truth records may silently produce systematically wrong results.The manual notes that much of the event record is intended for debugging rather than physics interpretation.
  • Preferred practice: Analyses can usually remain functional and portable by using final-state particles and physically meaningful on-shell decay parents, standardized with HepMC status codes 1 and 2.The manual gives reconstructed Z finding from decay-lepton candidates and invariant-mass selection as an example.

7. Projections

Rivet projections act as composable calculators and are central to the framework’s computational scalability. Their cached, comparable results avoid repeated calculations while accommodating differing projection settings.

  • Projection model: Projections are calculator-like objects that return event shapes, scalar or vector quantities, or selective views of the final state.They inherit from the Projection base class and may be nested recursively without dependency loops.
  • Caching: Projection results are cached between events, reducing repeated computation and supporting Rivet’s scalability to many analyses.The manual motivates caching through the repeated k⊥-clustering calculations that slowed earlier HZTool validation code.
  • Shared calculations: Equivalent FinalState and Thrust projections can be shared across analyses for the same event instead of being recalculated.The first analysis attaches the computed projections to the event, and later analyses receive references to them.
  • Configuration matching: Projection comparison operators determine whether a cached result matches requested settings such as particle selection, acceptance, or p⊥ thresholds.If settings differ, Rivet reruns the calculation with the required configuration.
  • Registration: All projections are centrally registered through ProjectionHandler, while addProjection manages their registration and lifetime.The manual recommends local stack objects in Projection and Analysis constructors.
  • Type-safety trade-off: The central dynamic-casting approach trades compile-time type safety for protection against projection lifetime and object-slicing bugs, with failures appearing as runtime errors.The manual presents this as a practical static-versus-dynamic typing trade-off.

8. Analyses

Rivet analyses are built from projections and lifecycle methods that process generic HepMC events, fill weighted histograms, and support extensible plugin deployment. The section also introduces physics objects and HepData-linked histogram booking for implementing analyses.

  • Analysis structure: New analyses inherit from Rivet::Analysis and implement init(), analyze(const Event&) and finalize(), called at setup, per event and end of run.The constructor registers the analysis name, while init() configures projections and histograms.
  • Analysis structure: Projections are added in init() under names such as "FS", then referenced during event analysis to obtain particles and other event-level objects.The FinalState projection example uses addProjection(Projection, std::string).
  • Histogramming: Histograms are booked in init(), filled in analyze() with event weights, and normalized or scaled in finalize().The Analysis class provides convenience booking, normalization and scaling methods.
  • Physics objects: Rivet provides FourMomentum, Particle and jet interfaces for accessing kinematics, PDG identifiers, jet constituents and related physics properties.Utilities include transverse momentum, angular variables, ΔR-style distances and particle-content checks.
  • Histogramming: 31 integer-based histogram booking links HepData dataset and axis identifiers, avoiding copied bin definitions and incorporating later HepData fixes.The recommended naming scheme combines dataset, x-axis and y-axis identifiers.
  • Pluggable analyses: Custom analyses can be compiled as plugin libraries and run with Rivet without modifying the main sources or build system.A newer Rivet version may still require recompilation because of binary-interface changes.

9. Using Rivet as a library

Rivet can be embedded directly in applications through its C++ API, with a more restricted Python interface, instead of being used only through command-line programs. The API processes HepMC events through an AnalysisHandler and supports generator integration through AGILe.

  • Why use the library: Direct integration avoids rendering HepMC events to strings and rereading them when CPU and I/O costs outweigh FIFO convenience.The manual presents this as one reason to use Rivet programmatically.
  • Why use the library: In-memory histogram objects can be manipulated during a run before final output is produced.This is useful for applications that periodically process histogram data.
  • Core API: Applications create an AnalysisHandler, select analyses, call analyze(evt) for each HepMC event, then finalize and write the results.The example also sets a cross-section and sum of event weights before writing output.
  • API scope: The C++ API is intended to be stable except for histogramming components, whose planned replacement was expected to affect related API parts.Python access is available in a more restricted form.
  • AGILe integration: AGILe can load a generator, configure its initial state, seed and parameters, generate events, pass them directly to Rivet, and finalize both systems.The example uses Pythia6 and a LEP analysis over 10000 events.

10. Conclusions

The manual presents Rivet as a portable framework for validating event-generator models and tunings through simulation-level collider analyses. It combines framework guidance with examples for implementing user analyses and demonstrates scalability through automated result caching.

  • Conclusions: Rivet is a C++ class library providing infrastructure and calculational tools for simulation-level analyses in high-energy collider experiments.The stated purpose is validation of event-generator models and tunings with minimal effort and maximum portability.
  • Conclusions: Automated result caching is presented as the mechanism enabling Rivet to scale to large numbers of analyses for global validation.The caching system is described as transparent to users.
  • Conclusions: The manual introduces Rivet’s framework philosophy and gives examples for implementing custom analysis modules.It also lists selected analyses to illustrate the flexibility of the full framework.

Appendix A. Typical agile-runmc commands

The agile-runmc examples show how to generate LEP or LHC events, alter generator parameters, and write HepMC output from the command line. Options control generator choice, beam settings, event counts, parameter files, overrides and output destinations.

  • Basic generation: agile-runmc Herwig:6510 with --beams=LEP:91.2 and -n 1000 generates 1000 LEP1-mode events using Herwig 6.5.10.The example supplies a parameter file with -P.
  • Parameter changes: agile-runmc Pythia6:425 supports parameter files with -P and command-line overrides such as PARJ(82)=5.27 via -p.The example uses these controls for parameter scans and rapid testing.
  • Writing HepMC events: The -o option writes generated HepMC events to a plain-text file, while filename "-" sends the event stream to standard output.The example writes 50 Pythia LHC events to out.hepmc.
Loading 1003.0694v8…