NuHepMC Specification Version 1.0.0

Abstract

In this specification we present an additional set of Requirements, Conventions, and Suggestions for simulated interactions stored in HepMC3 format. These are designed to be used in the specific context of neutrino event generators and associated simulation and analysis toolchains. By doing so, we hope to lower the barrier for interfacing with the output of a range of interaction simulations.

Introduction
The NuHepMC Specification
Generator Adoption of NuHepMC
Contributing and NuHepMC Revisions
Major Changelog
Contact

Introduction

In the accelerator neutrino HEP subfield, currently, each event generator, experimental simulation, and analysis framework maintains their own proprietary set of interfaces and format converters. By developing an extensible and extendable set of conventions on top of the versatile and mature HepMC3 we aim to cater to analysers and simulation framework developers who want to handle interactions in a tool-agnostic way, while also not putting any constraints on the information that individual event generators output, enabling lossless, bidirectional format conversion with existing proprietary formats.

The specification is broken down into Requirements, Conventions, and Suggestions for each of the following HepMC3 components.

G: Generator Run Metadata
E: Event Metadata
V: Vertex Information
P: Particle Information

Elements of the specification are enumerated like <Component>.<Category>.<Index>, i.e. the fifth Convention for Event information should be referred to as E.C.5.

Following named conventions is optional. If conventions prove useful and are considered stable, they may become requirements in future revisions. Suggestions cover information that is useful to make available to users, but has not routinely been included in proprietary formats or may not be simple to include in every implementation. G.R.4 provides a requirement on signalling which optional Conventions or Suggestions have been followed.

See NuHepMC/ReferenceImplementation for utilities for writing, reading, and interpreting NuHepMC files in C++ and Python; NuHepMC/ReferenceImplementation for the reference implementation of a NuHepMC event writer; NuHepMC/Validator for a validator that can be used to test NuHepMC files; and Generator Adoption of NuHepMC for a snapshot of the NuHepMC adoption status.

NuHepMC

This document is a living version of the NuHepMC specification paper.

A Note on the Usage of HepMC3 C++ Class Names

Throughout this standard, references are made to various HepMC3 C++ types, e.g. HepMC3::GenRunInfo, which are equivalent to the namespace-qualified C++ typename in the HepMC3 reference implementation. However, these are used as a convenient handle for data objects. This specification should not be considered specific to the HepMC3 C++ reference implementation.

Generator Run Metadata

The generator run metadata describes the overall setup of the event generator, i.e., information that is not unique to a specific event. The NuHepMC specifications for this metadata are as follows:

Requirements

G.R.1 Valid GenRunInfo

All NuHepMC vectors must contain a HepMC3::GenRunInfo instance.

n.b. The term vector is used herein, rather than file, as HepMC3 events are frequently piped or streamed between MC tools without ever being wholly persisted to memory or disk.

G.R.2 NuHepMC Version

A NuHepMC HepMC3::GenRunInfo instance must contain the following three HepMC3::IntAttributes that specify the version of NuHepMC that is implemented

"NuHepMC.Version.Major"
"NuHepMC.Version.Minor"
"NuHepMC.Version.Patch"

This document describes version 1.0.0 of NuHepMC. For a list of breaking changes between major versions, see Major Changelog.

n.b. A script is provided for converting existing NuHepMC files from an older version of the standard to the latest version of the standard at scripts/NuHepMC_update_standard.py.

G.R.3 Generator Identification

A NuHepMC HepMC3::GenRunInfo instance must contain a HepMC3::GenRunInfo::ToolInfo for each 'tool' involved in the production of the vector thus far. The ToolInfo instance must contain non-empty name and version fields.

G.R.4 Signaling Followed Conventions

To signal to a user that an implementation follows a named convention from this specification, a HepMC3::VectorStringAttribute attribute must be added to the HepMC3::GenRunInfo instance named "NuHepMC.Conventions" containing the labels of the conventions adhered to, e.g. "G.C.2".

n.b. G.R.5 requires the implementation of at least one convention and so this attribute must exist.

G.R.5 Flux-Averaged Total Cross Section

The flux-averaged total cross section is a scaling factor that is needed to convert a distribution of simulated events into a cross-section prediction. Details on the mathematical definition of this quantity are given in the NuHepMC specification paper, Sec. 3.1. If the value is known at the start of a generator run, convention G.C.2 should be used to store it in the HepMC3::GenRunInfo.

In general, the value is not known at the start of a generator run, but it can be calculated as events are produced (see NuHepMC specification paper Appendix A). In this case, convention E.C.4 should be used to store the running estimate and associated statistical uncertainty in each HepMC3::GenEvent.

One of these two methods for communicating the flux-averaged total cross section to users must be implemented and signaled via G.R.4.

G.R.6 Cross Section Units and Target Scaling

There are a variety of units typically used to report both measured and predicted cross sections in HEP. For neutrino cross sections specifically, 10^{-38} cm^2 per nucleon is common, but not ubiquitous. Both of the following HepMC3::StringAttributes must be included on the HepMC3::GenRunInfo to indicate the cross section units used within a vector. Possible values of the attributes are not restricted by this specification, but the meanings of the following values are reserved to standardize existing conventions. It is strongly recommended that new implementations use these wherever possible.

"NuHepMC.Units.CrossSection.Unit"
- "pb": Picobarns or 10^{-36} cm^2. Our recommendation
- "10-38 cm2": The choice of 10^{-38} cm^2 is the most frequent in the neutrino literature.
- "cm2": Using bare cm^2 in this option, without any power-of-ten scaling, is not recommended due to numerical precision concerns. The natural scale of neutrino--nucleon cross sections is approximately 10^{-38}, which is very close to the minimum representable IEEE 754 single-precision floating point number.
"NuHepMC.Units.CrossSection.TargetScale"
- "PerAtom": Our recommendation.
- "PerNucleon": A common alternative in the literature.

The chosen units should be assumed to apply to the reported value of the flux-averaged total cross section, which is a property of the generator run and may be stored according to either G.C.2 or E.C.4. Consistent units must also be used for the total (E.C.2) and process-specific (E.C.3) cross sections describing the primary interaction in each individual event, if they are provided.

It is ultimately up to the user to parse these attributes and decide whether any additional scaling is needed for their purposes, but the use of the above reserved values will facilitate automated processing. The recommended value of picobarns per atom is chosen to remain consistent with the assumptions of other tools that read and write HepMC3 files beyond the neutrino community, such as Rivet. Consistency facilitates interoperability and reduces maintenance burdens.

G.R.7 Event Weights

For weights that will be calculated for every event, HepMC3 provides an interface for storing the weight names only once in the HepMC3::GenRunInfo instance. At least one event weight named "CV" must be declared on the HepMC3::GenRunInfo instance and fille

Spec

Install / Use

README