Skip to content

Commit 7344154

Browse files
mfasDamfasDa
committed
[EMCAL-630] Improve documentation of RawToCellConverterSpec
- Document functions which were missing a documentation so far - Add class documentation
1 parent 88838a8 commit 7344154

File tree

1 file changed

+143
-9
lines changed

1 file changed

+143
-9
lines changed

‎Detectors/EMCAL/workflow/include/EMCALWorkflow/RawToCellConverterSpec.h‎

Lines changed: 143 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,72 @@ namespace reco_workflow
4747
{
4848

4949
/// \class RawToCellConverterSpec
50-
/// \brief Coverter task for Raw data to EMCAL cells
50+
/// \brief Coverter task for Raw data to EMCAL cells and trigger objects
5151
/// \author Hadi Hassan <hadi.hassan@cern.ch>, Oak Ridge National Laboratory
52+
/// \author Markus Fasel <markus.fasel@cern.ch>, Oak Ridge National Laboratory
53+
/// \ingroup EMCALworkflow
5254
/// \since December 10, 2019
55+
////
56+
/// General reconstruction task of EMCAL raw data of FEC and trigger sources, running during the synchronous
57+
/// reconstruction. The task decodees pages from ALTRO, Fake ALTRO and STU sources, and mergees the data according
58+
/// to events (triggers). The data is then further processed based on the origin of the data:
5359
///
60+
/// - in case of FEC data (cells or LEDMONS) a raw fit is performed, and data from high- and low-gain channels are
61+
/// merged, always preferring the high-gain data if not saturated (better resolution)
62+
/// - in case of Fake ALTRO data (TRU) the L0 timesums, trigger patches and TRU information are reconstructed. For
63+
/// the trigger patches a small peak finder selects the time sample with the max. patch energy. For the L0 timesums
64+
/// a fixed L0 time (8) is used for all event types
65+
///
66+
/// FEC and trigger information are ordered according to events and streamed to their output buffers, where corresponding
67+
/// trigger records mark ranges in the buffer belonging to the same trigger. Tasks subscribing to outputs from this
68+
/// task must always subscribe to teh trigger records in addition.
69+
///
70+
/// Several components of the task (raw parsing, ALTRO decoding, channel mapping and geometry, raw fit) can end in error
71+
/// states, particularly due to unexpected data. Error handling is performed internally at different stages. Errors are
72+
/// cathegoriezed as major or minor errors, where major errors prevent decoding the page while minor errors only lead
73+
/// to loss of certain segments. For monitoring tasks must subscribe to EMC/DECODERERR.
74+
///
75+
/// In order to guarantee data consistency a link checker compares the links contributing to data from a certain trigger
76+
/// to the links activated in the DCS. If not all links are present the timeframe is discarded. In order to switch off
77+
/// that feature the option --no-checkactivelinks must be activated.
78+
///
79+
/// Inputs:
80+
/// | Input spec | Optional | CCDB | Purpose |
81+
/// |----------------------|----------|------|----------------------------------------------|
82+
/// | EMC/RAWDATA | no | no | EMCAL raw data |
83+
/// | FLP/DISTSUBTIMEFRAME | yes | no | Message send when no data was received in TF |
84+
/// | EMC/RECOPARAM | no | yes | Reconstruction parameters |
85+
/// | EMC/FEEDCS | no | yes | FEE DCS information |
86+
///
87+
/// Outputs:
88+
/// | Input spec | Subspec (default) | Optional | Purpose |
89+
/// |----------------------|-------------------|-----------|----------------------------------------------------|
90+
/// | EMC/CELLS | 1 | no | EMCAL cell (tower) data |
91+
/// | EMC/CELLSTRGR | 1 | no | Trigger records related to cell data |
92+
/// | EMC/DECODERERR | 1 | yes | Decoder errors (for QC), if enabled |
93+
/// | EMC/TRUS | 1 | yes | TRU information, if trigger reconstruction enabled |
94+
/// | EMC/TRUSTRGR | 1 | yes | Trigger reconrds related to TRU information |
95+
/// | EMC/PATCHES | 1 | yes | Trigger patches, if trigger reconstruction enabled |
96+
/// | EMC/PATCHESTRGR | 1 | yes | Trigger reconrds related to trigger patches |
97+
/// | EMC/FASTORS | 1 | yes | L0 timesums, if trigger reconstruction enabled |
98+
/// | EMC/FASTORSTRGR | 1 | yes | Trigger reconrds related to L0 timesums |
99+
///
100+
/// Workflow options (via --EMCALRawToCellConverterSpec ...):
101+
/// | Option | Default | Possible values | Purpose |
102+
/// |---------------------|---------|-----------------|------------------------------------------------|
103+
/// | fitmethod | gamma2 | gamma2,standard | Raw fit method |
104+
/// | maxmessage | 100 | any int | Max. amount of error messages on infoLogger |
105+
/// | printtrailer | false | set (bool) | Print RCU trailer (for debugging) |
106+
/// | no-mergeHGLG | false | set (bool) | Do not merge HG and LG channels for same tower |
107+
/// | no-checkactivelinks | false | set (bool) | Do not check for active links per BC |
108+
/// | no-evalpedestal | false | set (bool) | Disable pedestal evaluation |
109+
///
110+
/// Global switches of the EMCAL reco workflow related to the RawToCellConverter:
111+
/// | Option | Default | Purpose |
112+
/// | -------------------------------|---------|-----------------------------------------------|
113+
/// | disable-decoding-errors | false | Disable sending decoding errors |
114+
/// | disable-trigger-reconstruction | false | Disable trigger reconstruction |
115+
/// | ignore-dist-stf | false | disable subscribing to FLP/DISTSUBTIMEFRAME/0 |
54116
class RawToCellConverterSpec : public framework::Task
55117
{
56118
public:
@@ -297,27 +359,99 @@ class RawToCellConverterSpec : public framework::Task
297359
/// maximum. The patch time is the start time of the 4-integral
298360
std::tuple<uint16_t, uint8_t> reconstructTriggerPatch(const gsl::span<const FastORTimeSeries*> fastors) const;
299361

362+
/// \brief Handling of mapper hardware address errors
363+
/// \param error Exception raised by the mapper
364+
/// \param ddlID DDL ID of the segment raising the exception
365+
/// \param hwaddress Hardware address raising the exception
366+
///
367+
/// Errors are printed to the infoLogger until a user-defiened
368+
/// threshold is reached. In case the export of decoder errors
369+
/// is activated an error object with additional information is
370+
/// produced.
300371
void handleAddressError(const Mapper::AddressNotFoundException& error, int ddlID, int hwaddress);
301372

373+
/// \brief Handler function for major ALTRO decoder errors
374+
/// \param altroerror Exception raised by the ALTRO decoder
375+
/// \param ddlID DDL ID of the segment raising the exception
376+
/// \param hwaddress Hardware address raising the exception
377+
///
378+
/// Errors are printed to the infoLogger until a user-defiened
379+
/// threshold is reached. In case the export of decoder errors
380+
/// is activated an error object with additional information is
381+
/// produced.
302382
void handleAltroError(const o2::emcal::AltroDecoderError& altroerror, int ddlID);
303383

384+
/// \brief Handler function for minor ALTRO errors
385+
/// \param altroerror Minor errors created by the ALTRO decoder
386+
/// \param ddlID DDL ID of the segment raising the exception
387+
///
388+
/// Errors are printed to the infoLogger until a user-defiened
389+
/// threshold is reached. In case the export of decoder errors
390+
/// is activated an error object with additional information is
391+
/// produced.
304392
void handleMinorAltroError(const o2::emcal::MinorAltroDecodingError& altroerror, int ddlID);
305393

394+
/// \brief Handler function of mapper errors related to invalid DDL
395+
/// \param error Exception raised by the mapper
396+
/// \param feeID FEE ID (DDL ID) of the segment raising the exception
397+
///
398+
/// Errors are printed to the infoLogger until a user-defiened
399+
/// threshold is reached. In case the export of decoder errors
400+
/// is activated an error object with additional information is
401+
/// produced.
306402
void handleDDLError(const MappingHandler::DDLInvalid& error, int feeID);
307403

308-
void handleGeometryError(const ModuleIndexException& e, int supermoduleID, int cellID, int hwaddress, ChannelType_t chantype);
309-
404+
/// \brief Handler function of errors related to geometry (invalid supermodule / module/ tower ...)
405+
/// \param error Geometry exception
406+
/// \param supermoduleID Supermodule ID of the exception
407+
/// \param cellID Cell (Tower) ID of the exception
408+
/// \param hwaddress Hardware address raising the exception
409+
/// \param chantype Channel type of the exception
410+
///
411+
/// Errors are printed to the infoLogger until a user-defiened
412+
/// threshold is reached. In case the export of decoder errors
413+
/// is activated an error object with additional information is
414+
/// produced.
415+
void handleGeometryError(const ModuleIndexException& error, int supermoduleID, int cellID, int hwaddress, ChannelType_t chantype);
416+
417+
/// \brief Handler function of mapper errors related to invalid DDL
418+
/// \param error Exception raised by the mapper
419+
/// \param feeID FEE ID (DDL ID) of the segment raising the exception
420+
///
421+
/// Errors are printed to the infoLogger until a user-defiened
422+
/// threshold is reached. In case the export of decoder errors
423+
/// is activated an error object with additional information is
424+
/// produced.
310425
void handleFitError(const o2::emcal::CaloRawFitter::RawFitterError_t& fiterror, int ddlID, int cellID, int hwaddress);
311426

312-
/// \brief handler function for gain type errors
427+
/// \brief Handler function for gain type errors
313428
/// \param errortype Gain error type
314-
/// \param ddlID ID of the DDL
315-
/// \param hwaddress Hardware address
429+
/// \param ddlID DDL ID of the segment raising the exception
430+
/// \param hwaddress Hardware address raising the exception
431+
///
432+
/// Errors are printed to the infoLogger until a user-defiened
433+
/// threshold is reached. In case the export of decoder errors
434+
/// is activated an error object with additional information is
435+
/// produced.
316436
void handleGainError(const o2::emcal::reconstructionerrors::GainError_t& errortype, int ddlID, int hwaddress);
317437

318-
void handlePageError(const RawDecodingError& e);
319-
320-
void handleMinorPageError(const RawReaderMemory::MinorError& e);
438+
/// \brief Handler function for raw page decoding errors (i.e. header/trailer corruptions)
439+
/// \param error Raw page error
440+
///
441+
/// Errors are printed to the infoLogger until a user-defiened
442+
/// threshold is reached. In case the export of decoder errors
443+
/// is activated an error object with additional information is
444+
/// produced.
445+
void handlePageError(const RawDecodingError& error);
446+
447+
/// \brief Handler function for minor raw page decoding errors (i.e. header/trailer corruptions)
448+
/// \param error Raw page error
449+
///
450+
/// Errors are printed to the infoLogger until a user-defiened
451+
/// threshold is reached. In case the export of decoder errors
452+
/// is activated an error object with additional information is
453+
/// produced.
454+
void handleMinorPageError(const RawReaderMemory::MinorError& error);
321455

322456
header::DataHeader::SubSpecificationType mSubspecification = 0; ///< Subspecification for output channels
323457
int mNoiseThreshold = 0; ///< Noise threshold in raw fit

0 commit comments

Comments
 (0)