HGCal raw data handling: Unpacker, Geometry, Local Reco

The following is a squashed commit of the contributions of different people

Co-authored-by: IzaakWN <[email protected]>
Co-authored-by: Lovisa <[email protected]>
Co-authored-by: Matti Kortelainen <[email protected]>
Co-authored-by: Pedro Silva <[email protected]>
Co-authored-by: Yulun Miao <[email protected]>
Co-authored-by: ineuteli <[email protected]>
Co-authored-by: ywkao <[email protected]>

A summary of contents follows. Note this has been edited (ammended by @pfs):

- HGCal Electronics Mapping for alpaka (cms-sw#161)
   - add dense index map for HGCalElectronicsId
   - add getMaxDataSize & getMaxERxSize functions
   - fix getDenseIndex bug; add typcode map to ModuleIndexer (to retrieve module dense index offset); use regexp for type code
   - add getFedAndModuleIndex; rename getDenseIndex -> getIndexForModule(Data) for elecID
   - add typecode regexp; pass typecode to modIndexer_.processNewModule
   - adding dense index info producer
   - adding hgcalmapping customise
   - fix misunderstanding in max data size expected from indexer
   - remove_if was missing a call to std::vector::erase to effectively remove unused entries
   - typecodemap was missing a reset with the final indices
   - usage of command line options was missing in module map tester
   - do not use moduleLUT in DenseIndexInfoESProducer!! it has the full dimensions before trimming to the actual number of ECON-Ds in a FED
   - Add irot to module mapper (#134)
   - move variables to private, use getters and move bulky code to .cc in HGCalMappingModuleIndexer / apply code checks

- CondFormats
   - add calibrations Alpaka ESProducer
   - rename ES_HGCal*Parameter.cc -> HGCal*ParameterHostCollection.cc for clarity
   - moving to single record as all conds produced have the same IOV
   - add HGCal configuration ESProducers + record + tester
   - Record descriptions added
   - Re-introducing 1 record per payload, addressing additional code comments
   - rename ES_HGCal*Parameter.cc -> HGCal*ParameterHostCollection.cc for clarity
   - rename HGCal*ParameterHostCollection.cc -> HGCal*ParameterDeviceCollection.cc for clarity
   - rename 'HGCal.*(Device|Host)Collection -> (Device|Host)' for readability; move calib SoAs to CondFormats/HGCalObjects/; move TestHGCalRecHitESProducers to test
   - fill HGCal config structs for unpacker (header marks, charMode)
   - read HGCal FED & ECON-D configuration from JSON

- Adding digi SoAs
   - moving digi soa filler to alpaka and adding extra tools
   - rename 'HGCal.*(Device|Host)Collection -> HGCal.*(Device|Host)' for readability

- Refactor unpacker.
   - parse arrays of gain-dependent calibration parameters in eRx-blocks (simplified in latter commits to remove explicit gain-dependence)
   - add missing Noise attribute
   - Convert ECON-D payload to 32b words.
   - rebase the unpacker on denseIdx and SoA digis
   - Moving emulators to SimCalorimetry/HGCalSimAlgos, adapting paths
      - fix undefined left shift in HGCalRawDataPackingTools.cc; remove duplicate line in HGCalMappingTools.h (32 -> 31 to solve undefined left shift)
   - SoA format of HGCal ECON-D header
   - Unpack header information to HGCalECONDInfoSoA; Add in quality checks for ECON-D
   - Update unpacker to use HGCalConfiguration structure
   - Add flags for passthrough ECON-Ds
   - Fix the number of channel in eRx;Add default flag for digi, representing digi not read in raw data
   - Add parsing function for econd flag; renaming HGCalECONDInfo to HGCalECONDPacketInfo
   - Add in common mode in ECOND packet information
   - enable FED-level Parallelization through config
   - Remove change of location when something wrong in S-Link trailer

- Add HGCalRecHit
   - add DIGI2RECO calibration algorithms (see https://gitlab.cern.ch/hgcal-dpg/hgcal-comm/-/merge_requests/3)[C; remove detId/elecId from SoAs (should be redundant since common indexer); add HGCROCChannelDataFrame<HGCalDetId> to classes_def.xml
   - Move HGCalRawDataDefinitions.h.
   - Update and rename HGCalRecHitProducer.cc to HGCalRecHitProducers.cc
   - update calibration kernels
   - bugfix in the cm Sum
   - fill rec hitflags
   - update kernel after closure
   - swap arguments in tot kernel

- Code formats / checks
   - Removing unused includes and delarations
   - Re-introducing headers.h file needed for serialization classes
   - Remove data and change locations to cms-data folder
   - moving to printf, removing unused product, and message logger
   - int -> uint32_t; uncomment debugging print out
   - Change to LogDebug

CondFormats/DataRecord/interface/HGCalDenseIndexInfoRcd.h

@@ -0,0 +1,29 @@
+#ifndef CondFormats_HGCalDenseIndexInfoRcd_h
+#define CondFormats_HGCalDenseIndexInfoRcd_h
+// -*- C++ -*-
+//
+// Package:     CondFormats/DataRecord
+// Class  :     HGCalDenseIndexInfoRcd
+//
+/**\class HGCalDenseIndexInfoRcd HGCalDenseIndexInfoRcd.h CondFormats/DataRecord/interface/HGCalDenseIndexInfoRcd.h
+ *
+ * Description:
+ *   This record is used join information from the geometry and logical mapping
+ *   This record depends on the HGCalElectronicsMappingRcd and CaloGeometryRecord
+ *
+ */
+//
+// Author:      Pedro Da Silva, Izaak Neutelings
+// Created:     Mon, 29 May 2023 09:13:07 GMT
+//
+
+#include "FWCore/Framework/interface/DependentRecordImplementation.h"
+#include "FWCore/Utilities/interface/mplVector.h"
+#include "CondFormats/DataRecord/interface/HGCalElectronicsMappingRcd.h"
+#include "Geometry/Records/interface/CaloGeometryRecord.h"
+
+class HGCalDenseIndexInfoRcd : public edm::eventsetup::DependentRecordImplementation<
+                                   HGCalDenseIndexInfoRcd,
+                                   edm::mpl::Vector<HGCalElectronicsMappingRcd, CaloGeometryRecord> > {};
+
+#endif

CondFormats/DataRecord/interface/HGCalModuleConfigurationRcd.h

@@ -0,0 +1,28 @@
+#ifndef CondFormats_HGCalModuleConfigurationRcd_h
+#define CondFormats_HGCalModuleConfigurationRcd_h
+// -*- C++ -*-
+//
+// Package:     CondFormats/DataRecord
+// Class  :     HGCalModuleConfigurationRcd
+//
+/**\class HGCalModuleConfigurationRcd HGCalModuleConfigurationRcd.h CondFormats/DataRecord/interface/HGCalModuleConfigurationRcd.h
+ *
+ * Description:
+ *   This record is used for passing the configuration parameters to the calibration step in RAW -> RECO,
+ *   This record depends on the HGCalMappingModuleIndexerRcd.
+ *
+ */
+//
+// Author:      Pedro Da Silva, Izaak Neutelings
+// Created:     Mon, 29 May 2023 09:13:07 GMT
+//
+
+#include "FWCore/Framework/interface/DependentRecordImplementation.h"
+#include "FWCore/Utilities/interface/mplVector.h"
+#include "CondFormats/DataRecord/interface/HGCalElectronicsMappingRcd.h"
+
+class HGCalModuleConfigurationRcd
+    : public edm::eventsetup::DependentRecordImplementation<HGCalModuleConfigurationRcd,
+                                                            edm::mpl::Vector<HGCalElectronicsMappingRcd> > {};
+
+#endif

CondFormats/DataRecord/src/HGCalDenseIndexInfoRcd.cc

@@ -0,0 +1,15 @@
+// -*- C++ -*-
+//
+// Package:     CondFormats/DataRecord
+// Class  :     HGCalDenseIndexInfoRcd
+//
+// Implementation:
+//     [Notes on implementation]
+//
+// Author:      Pedro Da Silva, Izaak Neutelings
+// Created:     Mon, 29 May 2023 09:13:07 GMT
+
+#include "CondFormats/DataRecord/interface/HGCalDenseIndexInfoRcd.h"
+#include "FWCore/Framework/interface/eventsetuprecord_registration_macro.h"
+
+EVENTSETUP_RECORD_REG(HGCalDenseIndexInfoRcd);

CondFormats/DataRecord/src/HGCalModuleConfigurationRcd.cc

@@ -0,0 +1,15 @@
+// -*- C++ -*-
+//
+// Package:     CondFormats/DataRecord
+// Class  :     HGCalModuleConfigurationRcd
+//
+// Implementation:
+//     [Notes on implementation]
+//
+// Author:      Pedro Da Silva, Izaak Neutelings
+// Created:     Mon, 29 May 2023 09:13:07 GMT
+
+#include "CondFormats/DataRecord/interface/HGCalModuleConfigurationRcd.h"
+#include "FWCore/Framework/interface/eventsetuprecord_registration_macro.h"
+
+EVENTSETUP_RECORD_REG(HGCalModuleConfigurationRcd);

CondFormats/HGCalObjects/BuildFile.xml

@@ -11,4 +11,4 @@
 <flags ALPAKA_BACKENDS="1"/>
 <export>
   <lib name="1"/>
-</export>
+</export>

CondFormats/HGCalObjects/interface/HGCalCalibParamSoA.h

@@ -0,0 +1,36 @@
+#ifndef CondFormats_HGCalObjects_interface_HGCalCalibParamSoA_h
+#define CondFormats_HGCalObjects_interface_HGCalCalibParamSoA_h
+
+#include <Eigen/Core>
+#include <Eigen/Dense>
+
+#include "DataFormats/SoATemplate/interface/SoACommon.h"
+#include "DataFormats/SoATemplate/interface/SoALayout.h"
+#include "DataFormats/SoATemplate/interface/SoAView.h"
+
+//#include "CondFormats/HGCalObjects/interface/HGCalMappingModuleIndexer.h"
+
+namespace hgcalrechit {
+
+  // Generate structure of channel-level arrays (SoA) layout with RecHit dataformat
+  GENERATE_SOA_LAYOUT(HGCalCalibParamSoALayout,
+                      SOA_COLUMN(float, ADC_ped),       // ADC pedestals, O(91)
+                      SOA_COLUMN(float, Noise),         // noise, O(3)
+                      SOA_COLUMN(float, CM_slope),      // common mode slope, O(0.25)
+                      SOA_COLUMN(float, CM_ped),        // common mode pedestal (offset), O(92)
+                      SOA_COLUMN(float, BXm1_slope),    // leakage correction from previous bunch, O(0.0)
+                      SOA_COLUMN(float, TOTtoADC),      // TOT linearization in ADC units, O(15)
+                      SOA_COLUMN(float, TOT_ped),       // TOT pedestal (offset), O(9.0)
+                      SOA_COLUMN(float, TOT_lin),       // threshold at which TOT is linear, O(200)
+                      SOA_COLUMN(float, TOT_P0),        // coefficient pol2 in nonlinear region, O(145)
+                      SOA_COLUMN(float, TOT_P1),        // coefficient pol2 in nonlinear region, O(1.0)
+                      SOA_COLUMN(float, TOT_P2),        // coefficient pol2 in nonlinear region, O(0.004)
+                      SOA_COLUMN(float, TOAtops),       // TOA conversion to time (ps)
+                      SOA_COLUMN(float, MIPS_scale),    // MIPS scale
+                      SOA_COLUMN(unsigned char, valid)  // only 1 bit used: if false = mask dead channel
+  )
+  using HGCalCalibParamSoA = HGCalCalibParamSoALayout<>;
+
+}  // namespace hgcalrechit
+
+#endif  // CondFormats_HGCalObjects_interface_HGCalCalibParamSoA_h

CondFormats/HGCalObjects/interface/HGCalCalibrationParameterHost.h

@@ -0,0 +1,20 @@
+#ifndef CondFormats_HGCalObjects_interface_HGCalCalibrationParameterHost_h
+#define CondFormats_HGCalObjects_interface_HGCalCalibrationParameterHost_h
+
+#include "DataFormats/Portable/interface/PortableHostCollection.h"
+#include "CondFormats/HGCalObjects/interface/HGCalCalibParamSoA.h"
+#include "CondFormats/HGCalObjects/interface/HGCalConfigParamSoA.h"
+
+namespace hgcalrechit {
+
+  // SoA with channel-level calibration parameters in host memory:
+  //   pedestal, CM_slope, CM_ped, BXm1_kappa
+  using HGCalCalibParamHost = PortableHostCollection<HGCalCalibParamSoA>;
+
+  // SoA with ROC-level configuration parameters in host memory:
+  //   gain
+  using HGCalConfigParamHost = PortableHostCollection<HGCalConfigParamSoA>;
+
+}  // namespace hgcalrechit
+
+#endif  // CondFormats_HGCalObjects_interface_HGCalCalibrationParameterHost_h

CondFormats/HGCalObjects/interface/HGCalConfigParamSoA.h

@@ -0,0 +1,23 @@
+#ifndef CondFormats_HGCalObjects_interface_HGCalConfigParamSoA_h
+#define CondFormats_HGCalObjects_interface_HGCalConfigParamSoA_h
+
+#include <Eigen/Core>
+#include <Eigen/Dense>
+
+#include "DataFormats/SoATemplate/interface/SoACommon.h"
+#include "DataFormats/SoATemplate/interface/SoALayout.h"
+#include "DataFormats/SoATemplate/interface/SoAView.h"
+
+//#include "CondFormats/HGCalObjects/interface/HGCalMappingModuleIndexer.h"
+
+namespace hgcalrechit {
+
+  // Generate structure of ROC-level arrays (SoA) layout with RecHit dataformat
+  GENERATE_SOA_LAYOUT(HGCalConfigParamSoALayout,
+                      SOA_COLUMN(uint8_t, gain)  // for ADC to charge (fC) conversion (80, 160, 320 fC)
+  )
+  using HGCalConfigParamSoA = HGCalConfigParamSoALayout<>;
+
+}  // namespace hgcalrechit
+
+#endif  // CondFormats_HGCalObjects_interface_HGCalConfigParamSoA_h

CondFormats/HGCalObjects/interface/HGCalConfiguration.h

@@ -0,0 +1,67 @@
+// Authors: Izaak Neutelings (May 2024)
+// Sources: https://docs.google.com/spreadsheets/d/13G7sOjssqw4B5AtOcQV3g0W01oZUOMM6Hm_DduxBEPU
+#ifndef CondFormats_HGCalObjects_HGCalConfiguraton_h
+#define CondFormats_HGCalObjects_HGCalConfiguraton_h
+#include "CondFormats/Serialization/interface/Serializable.h"
+#include "CondFormats/HGCalObjects/interface/HGCalMappingModuleIndexer.h"
+#include <map>
+#include <vector>
+
+// @short configuration for ECON eRX (one half of HGROC)
+struct HGCalROCConfig {
+  uint32_t charMode;  // characterization mode; determines data fields in ROC dataframe
+  uint8_t gain;       // pre-amp gain used (1: 80 fC, 2: 160 fC, 4: 320 fC)
+  //uint32_t clockPhase;     // fine adjustment of the phase within the 40 MHz
+  //uint32_t L1AcceptOffset; // coarse adjustment to get the peak in the right place
+  //uint32_t injChannels;    // injected channels for injection scan: 2b word to identify if connected or not+info no capacitor chosen
+  //uint32_t injCharge;      // injected charge for injection scan: convert it to a float in units of fC offline (DAC setting?)
+  COND_SERIALIZABLE;
+};
+
+// @short configuration for ECON-D module
+struct HGCalECONDConfig {
+  //std::string typecode;
+  uint32_t headerMarker;  // begin of event marker/identifier for ECON-D
+  uint32_t passThrough;   //pass through mode (this is just as check as it'll be in the ECON-D header anyway)
+  std::vector<HGCalROCConfig> rocs;
+  COND_SERIALIZABLE;
+};
+
+// @short configuration for FED
+struct HGCalFedConfig {
+  bool mismatchPassthroughMode;  // ignore ECON-D packet mismatches
+  uint32_t cbHeaderMarker;       // begin of event marker/identifier for capture block
+  uint32_t slinkHeaderMarker;    // begin of event marker/identifier for S-link
+  //uint32_t delay; // delay
+  std::vector<HGCalECONDConfig> econds;
+  COND_SERIALIZABLE;
+};
+
+/**
+ *  @short Main HGCal configuration with a tree structure of vectors of
+ *         HGCalFedConfig/HGCalECONDConfig/HGCalROCConfig structs as follows:
+ %         config.feds[dense_fed_idx].econds[dense_econd_idx].rocs[dense_eRx_idx]
+ **/
+class HGCalConfiguration {
+public:
+  std::vector<HGCalFedConfig> feds;
+
+private:
+  COND_SERIALIZABLE;
+};
+
+inline std::ostream& operator<<(std::ostream& os, const HGCalConfiguration& config) {
+  uint32_t nfed = config.feds.size();
+  uint32_t ntotmod = 0;
+  uint32_t ntotroc = 0;
+  for (auto const& fed : config.feds) {
+    ntotmod += fed.econds.size();  // number of ECON-D modules for this FED
+    for (auto const& mod : fed.econds) {
+      ntotroc += mod.rocs.size();  // number of eRx half-ROCs for this ECON-D module
+    }
+  }
+  os << "HGCalConfiguration(nfed=" << nfed << ",ntotmod=" << ntotmod << ",ntotroc=" << ntotroc << ")";
+  return os;
+}
+
+#endif