HEPnOS client API: Runs, SubRuns, and Events

Down the hierarchy of datasets, we find Runs, SubRuns, and Events. This tutorial explains how these class work.

Runs

The Run class represents a handle to a run stored in an HEPnOS service. A Run is similar to a DataSet, except that it is identified by a run number (rather than a name for DataSet) and can only contain SubRuns.

Runs, just like the datasets, are typed key/value stores.

Creating Runs from DataSets

Runs are created inside a DataSet using DataSet::createRun(runNumber). This function returns a Run instance representing the newly-created run. If a run already exists with the same run number, the function returns a handle to it rather than creating a new one.

Accessing Runs from a DataSet

Given a DataSet instance ds, one can access existing runs using the bracket operator and passing it a run number:

Run run = ds[42];

If there is no run associated with the provided run number, this method returns a run instance such that run.valid() is false.

To navigate the runs inside a dataset, one can use the runs() member function of the DataSet class, which returns an instance of RunSet. This RunSet class offers the following functions:

• runs().begin(), runs().end(): return an iterator (or a const_iterator if the DataSet is const) pointing to the beginning and the end of the list of Runs contained by the DataSet object on which these functions are called, sorted by increasing run number.
• runs().cbegin(), runs().cend() return const_iterators to the beginning and the end of the runs contained in the DataSet.
• runs().find(runNumber): returns an iterator (or a const_iterator if the DataSet is const) pointing to the Run matching the provided run number (or runs().end() if there is no such Run).
• runs().lower_bound(runNumber): returns an iterator (or a const_iterator if the DataSet is const) pointing to the first Run in this DataSet whose run number is greater than or equal to the provided run number, or runs().end() if no such Run exists.
• runs().upper_bound(runNumber): returns an iterator (or a const_iterator if the DataSet is const) pointing to the first DataSet in this DataSet whose name is strictly less than the provided run number, or runs().end() if no such Run exists.
• operator[](subRunNumber): returns a SubRun object whose subrun number matches the provided one. Contrary to the bracket operator from std::map, this operator does not create the SubRun if it does not exist in the underlying service. Instead, it returns a SubRun instance sr such that sr.valid() is false.

SubRuns

SubRuns are created within Runs, using the Run::createSubRun(subRunNumber) method. SubRuns are identified by a sub run number and contain Events.

Accessing SubRuns

Given a Run r, one can access the SubRuns contained by Run r using the bracket operator as well as iterator functions (begin, end, find, lower_bound, upper_bound), just like when accessing Runs from a DataSet.

Events

Events are created within SubRuns using the SubRun::createEvent(eventNumber) method. Events are identified by an event number. They do not contain anything apart from typed key/value pairs.

Accessing Events

Given a SubRun sr, one can access the Events contained by SubRun sr using the bracket operator as well as iterator functions (begin, end, find, lower_bound, upper_bound), just like when accessing SubRuns from a Run.