This document specifies the necessary requirements and suggested components of a data quality monitoring system for the AIDA-2020 Work Package 5, using DQM4HEP. This document uses the same conventions for RULE, RECOMMENDATION, SUGGESTION, PERMISSION and OBSERVATION as the Hardware and Software Interface Specification [reference]. Refer to that document for the meanings of capitalised keywords.
In order to do online monitoring within DQM4HEP:
RULE: The designer MUST make data output from EUDAQ available in an LCIO format. This can be done either by using a pre-defined LCIO object (e.g. CalorimeterHit) or a custom format using an LCGenericObject.
RULE: If an LCGenericObject is being used, the designer MUST provide timing information within it in the form of a bunch crossing ID (BxID), an event number, or both.
RULE: The designer MUST create a DQM4HEP analysis module to define plots, interpret data, do any needed processing and push data to plots. A DQM4HEP analysis module comprises three files: a C++ source code file, a C++ header file, and an XML steering file. These are discussed in more detail below.
RECOMMENDATION: The designer SHOULD provide an electronics mapping, in order to produce geometrically corrected hitmaps of the detector. This should be done in the form of an XML file.
C++ Source Code File
The source code file (.cc) is the main file that executes the process of the analysis module. This is a normal C++ file created from a template provided by the developers of DQM4HEP [ 1 ]. Names within the file should be changed to a unique name to identify the analysis module. This includes the name of the file itself, declared names, namespaces, function scopes, etc. To write an analysis module, only two functions are necessary to change: the readSettings and processEvent functions. These are described below.
The readSettings function handles reading data from the XML steering file, initialising and booking histograms as well as reading in any other variables that may be set from the steering file.
The processEvent function is the main loop and handles extracting events from the data, doing any processing (sorting, calculation, discrimination, etc.) then filling histograms or plots with data. The structure of this function is highly dependent upon the structure of the input data.
C++ Header File
The header file (.h) is an auxiliary file for the analysis module. This is a normal C++ header file created from a template provided by the developers of DQM4HEP [ 2 ]. Names within the file should be changed to the same unique name as the above file to identify the analysis module. This includes the name of the file itself, declared names, namespaces, function scopes, etc.
The header file should declare all of the histograms and plots (the DQMMonitorElementPtr type) as well as all internal variables that are set from the steering file (below).
XML Steering File
The steering file (.xml) defines the histograms and plots that the monitor will use, including the type, axes, titles and labels, number of bins, draw options, and so on. These are ROOT histograms and follow all conventions for declaration used in ROOT. The steering file can also set other any other type of variables, like booleans, floats, integers, etc. These are read in during the readSettings function of the source code file (above) and once read in act as ordinary C++ variables. An example is provided. [ 3 ]