[R3C-465] MCH: pedestals calibration workflow (#5627)

* [MCH] introduced workflow for pedestals analysis

This workflow processes pedestal data, builds the list
of bad/noisy channels and stores the list in the CCDB.

* [MCH] added output for sending the pedestal values to the QC

A "MCH/PEDESTALS" output spec has been added, which
allows to send the computed pedestal mean/rms values
to a downstream DPL device, for example to the QC.
The QC in this case can simply plot and checks the
pre-computed pedestals, without having to re-process
the raw data.

Author: aferrero2707

DataFormats/Detectors/MUON/MCH/CMakeLists.txt

@@ -14,4 +14,5 @@ o2_add_library(DataFormatsMCH
 
 o2_target_root_dictionary(DataFormatsMCH
                           HEADERS include/DataFormatsMCH/ROFRecord.h
-                                  include/DataFormatsMCH/TrackMCH.h)
+                                  include/DataFormatsMCH/TrackMCH.h
+                                  include/DataFormatsMCH/DsChannelGroup.h)

DataFormats/Detectors/MUON/MCH/include/DataFormatsMCH/DsChannelGroup.h

@@ -0,0 +1,83 @@
+// Copyright CERN and copyright holders of ALICE O2. This software is
+// distributed under the terms of the GNU General Public License v3 (GPL
+// Version 3), copied verbatim in the file "COPYING".
+//
+// See http://alice-o2.web.cern.ch/license for full licensing information.
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+/// \file DsChannleGroup.h
+/// \brief Implementation of a group of DualSampa channels
+///
+/// \author Andrea Ferrero, CEA-Saclay
+
+#ifndef ALICEO2_MCH_DSCHANNELGROUP_H_
+#define ALICEO2_MCH_DSCHANNELGROUP_H_
+
+#include <vector>
+#include "Rtypes.h"
+
+namespace o2
+{
+namespace mch
+{
+
+/// Unique 32-bit identifier of a DulaSampa channel. The ID is generated from the following indexes:
+/// - the unique ID of the corresponding solar board
+/// - the index of the DulaSampa board within the Solar board, from 0 to 39
+/// - the channel number, from 0 to 63
+class DsChannelId
+{
+ public:
+  DsChannelId() = default;
+  DsChannelId(uint32_t channelId) : mChannelId(channelId) {}
+  DsChannelId(uint16_t solarId, uint8_t dsId, uint8_t channel)
+  {
+    set(solarId, dsId, channel);
+  }
+
+  static uint32_t make(uint16_t solarId, uint8_t dsId, uint8_t channel)
+  {
+    uint32_t id = (static_cast<uint32_t>(solarId) << 16) +
+                  (static_cast<uint32_t>(dsId) << 8) + channel;
+    return id;
+  }
+
+  void set(uint16_t solarId, uint8_t dsId, uint8_t channel)
+  {
+    mChannelId = DsChannelId::make(solarId, dsId, channel);
+  }
+
+  uint16_t getSolarId() const { return static_cast<uint16_t>((mChannelId >> 16) & 0xFFFF); }
+  uint8_t getDsId() const { return static_cast<uint8_t>((mChannelId >> 8) & 0xFF); }
+  uint8_t getChannel() const { return static_cast<uint8_t>(mChannelId & 0xFF); }
+
+ private:
+  uint32_t mChannelId{0};
+
+  ClassDefNV(DsChannelId, 1); // class for MCH readout channel
+};
+
+/// A group of DualSampa channels, implemented as a vector of 32-bit channel identifiers
+class DsChannelGroup
+{
+ public:
+  DsChannelGroup() = default;
+
+  const std::vector<DsChannelId>& getChannels() const { return mChannels; }
+  std::vector<DsChannelId>& getChannels() { return mChannels; }
+
+  void reset() { mChannels.clear(); }
+
+ private:
+  std::vector<DsChannelId> mChannels;
+
+  ClassDefNV(DsChannelGroup, 1); // class for MCH bad channels list
+};
+
+} // end namespace mch
+} // end namespace o2
+
+#endif /* ALICEO2_MCH_DSCHANNELGROUP_H_ */

DataFormats/Detectors/MUON/MCH/src/DataFormatsMCHLinkDef.h

@@ -16,4 +16,6 @@
 
 #pragma link C++ class o2::mch::ROFRecord + ;
 #pragma link C++ class o2::mch::TrackMCH + ;
+#pragma link C++ class o2::mch::DsChannelId + ;
+#pragma link C++ class o2::mch::DsChannelGroup + ;
 #endif

Detectors/MUON/MCH/Base/CMakeLists.txt

@@ -17,4 +17,4 @@ o2_add_library(MCHBase
 	       PUBLIC_LINK_LIBRARIES ROOT::Core FairRoot::Base FairMQ::FairMQ ms_gsl::ms_gsl)
 
 o2_target_root_dictionary(MCHBase
-  HEADERS include/MCHBase/Digit.h)
+  HEADERS include/MCHBase/Digit.h include/MCHBase/DecoderError.h)

Detectors/MUON/MCH/Base/include/MCHBase/DecoderError.h

@@ -0,0 +1,52 @@
+// Copyright CERN and copyright holders of ALICE O2. This software is
+// distributed under the terms of the GNU General Public License v3 (GPL
+// Version 3), copied verbatim in the file "COPYING".
+//
+// See http://alice-o2.web.cern.ch/license for full licensing information.
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+/** @file DecoderError.h
+ * C++ definition of a decoder error
+ * @author  Andrea Ferrero, CEE-Saclay
+ */
+
+#ifndef ALICEO2_MCH_BASE_DECODERERROR_H_
+#define ALICEO2_MCH_BASE_DECODERERROR_H_
+
+#include "Rtypes.h"
+
+namespace o2
+{
+namespace mch
+{
+
+// \class DecoderError
+/// \brief MCH decoder error implementation
+class DecoderError
+{
+ public:
+  DecoderError() = default;
+
+  DecoderError(int solarid, int dsid, int chip, uint32_t error) : mSolarID(solarid), mChipID(dsid * 2 + chip), mError(error) {}
+  ~DecoderError() = default;
+
+  uint16_t getSolarID() const { return mSolarID; }
+  uint8_t getDsID() const { return mChipID / 2; }
+  uint8_t getChip() const { return mChipID % 2; }
+
+  uint32_t getError() const { return mError; }
+
+ private:
+  uint16_t mSolarID;
+  uint8_t mChipID;
+  uint32_t mError;
+
+  ClassDefNV(DecoderError, 1);
+}; //class DecoderError
+
+} //namespace mch
+} //namespace o2
+#endif // ALICEO2_MCH_BASE_DECODERERROR_H_

Detectors/MUON/MCH/CMakeLists.txt

@@ -19,3 +19,4 @@ add_subdirectory(Tracking)
 add_subdirectory(Raw)
 add_subdirectory(Workflow)
 add_subdirectory(Conditions)
+add_subdirectory(Calibration)

Detectors/MUON/MCH/Calibration/CMakeLists.txt

@@ -0,0 +1,31 @@
+# Copyright CERN and copyright holders of ALICE O2. This software is distributed
+# under the terms of the GNU General Public License v3 (GPL Version 3), copied
+# verbatim in the file "COPYING".
+#
+# See http://alice-o2.web.cern.ch/license for full licensing information.
+#
+# In applying this license CERN does not waive the privileges and immunities
+# granted to it by virtue of its status as an Intergovernmental Organization or
+# submit itself to any jurisdiction.
+
+o2_add_library(MCHCalibration
+         SOURCES
+	       src/PedestalDigit.cxx
+	       src/PedestalProcessor.cxx
+	       src/MCHChannelCalibrator.cxx
+	       PUBLIC_LINK_LIBRARIES ms_gsl::ms_gsl O2::DetectorsCalibration O2::CCDB O2::MCHBase O2::MCHRawDecoder O2::DataFormatsMCH)
+
+o2_target_root_dictionary(MCHCalibration
+  HEADERS include/MCHCalibration/PedestalDigit.h include/MCHCalibration/PedestalProcessor.h include/MCHCalibration/MCHChannelCalibrator.h)
+
+o2_add_executable(pedestals-decoding-workflow
+        SOURCES src/pedestals-decoding-workflow.cxx
+        COMPONENT_NAME mch
+        PUBLIC_LINK_LIBRARIES Boost::program_options O2::Framework O2::DPLUtils O2::MCHCalibration)
+
+o2_add_executable(mch-channel-calib-workflow
+                  COMPONENT_NAME calibration
+                  SOURCES src/channel-calib-workflow.cxx
+                  PUBLIC_LINK_LIBRARIES O2::Framework O2::MCHCalibration O2::DetectorsCalibration)
+
+  

Detectors/MUON/MCH/Calibration/include/MCHCalibration/MCHChannelCalibrator.h

@@ -0,0 +1,119 @@
+// Copyright CERN and copyright holders of ALICE O2. This software is
+// distributed under the terms of the GNU General Public License v3 (GPL
+// Version 3), copied verbatim in the file "COPYING".
+//
+// See http://alice-o2.web.cern.ch/license for full licensing information.
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+/// \file MCHChannelCalibrator.h
+/// \brief Implementation of the MCH calibrator using pedestal data
+///
+/// \author Andrea Ferrero, CEA-Saclay
+
+#ifndef MCH_CHANNEL_CALIBRATOR_H_
+#define MCH_CHANNEL_CALIBRATOR_H_
+
+#include "DataFormatsMCH/DsChannelGroup.h"
+#include "DetectorsCalibration/TimeSlotCalibration.h"
+#include "DetectorsCalibration/TimeSlot.h"
+#include "CCDB/CcdbObjectInfo.h"
+#include "MCHCalibration/PedestalDigit.h"
+#include "MCHCalibration/PedestalProcessor.h"
+
+#include <array>
+
+namespace o2
+{
+namespace mch
+{
+namespace calibration
+{
+
+/// Implementation of the processor that computes the mean and RMS of the channel-by-channel pedestals
+/// from the data corresponding to a time slot.
+/// In the MCH case the time slot has by default an infinite duration, therefore there is only a single
+/// set of pedestal values for each calibration run.
+class MCHChannelData
+{
+  using Slot = o2::calibration::TimeSlot<o2::mch::calibration::MCHChannelData>;
+
+ public:
+  MCHChannelData() = default;
+  ~MCHChannelData() = default;
+
+  void print() const;
+
+  /// function to update the pedestal values from the data of a single TimeFrame
+  void fill(const gsl::span<const o2::mch::calibration::PedestalDigit> data);
+  void merge(const MCHChannelData* prev);
+
+  /// function to access the table of computed pedestals for each readout channel
+  const PedestalProcessor::PedestalsMap& getPedestals() { return mPedestalProcessor.getPedestals(); }
+
+ private:
+  /// helper class that performs the actual computation of the pedestals from the input digits
+  PedestalProcessor mPedestalProcessor;
+
+  ClassDefNV(MCHChannelData, 1);
+};
+
+/// Implementation of a calibrator object that checks the computed mean and RMS of the pedestals and compares the
+/// values with user-supplied thresholds.
+/// The channels whose values exceed one of the thresholds are considered bad/noisy and they are stored into a
+/// "bad channels" list that is sent to the CDDB populator.
+class MCHChannelCalibrator final : public o2::calibration::TimeSlotCalibration<o2::mch::calibration::PedestalDigit, o2::mch::calibration::MCHChannelData>
+{
+  using TFType = uint64_t;
+  using Slot = o2::calibration::TimeSlot<o2::mch::calibration::MCHChannelData>;
+  using BadChannelsVector = o2::mch::DsChannelGroup;
+  using CcdbObjectInfo = o2::ccdb::CcdbObjectInfo;
+
+ public:
+  struct ChannelPedestal {
+    ChannelPedestal() = default;
+    ChannelPedestal(o2::mch::DsChannelId chid, double mean, double rms) : mDsChId(chid), mPedMean(mean), mPedRms(rms) {}
+
+    o2::mch::DsChannelId mDsChId;
+    double mPedMean{0};
+    double mPedRms{0};
+  };
+  using PedestalsVector = std::vector<ChannelPedestal>;
+
+  MCHChannelCalibrator(float pedThreshold, float noiseThreshold) : mPedestalThreshold(pedThreshold), mNoiseThreshold(noiseThreshold), mTFStart(0xffffffffffffffff){};
+
+  ~MCHChannelCalibrator() final = default;
+
+  bool hasEnoughData(const Slot& slot) const final;
+  void initOutput() final;
+  void finalizeSlot(Slot& slot) final;
+  Slot& emplaceNewSlot(bool front, TFType tstart, TFType tend) final;
+  void endOfStream();
+
+  const BadChannelsVector& getBadChannelsVector() const { return mBadChannelsVector; }
+  const CcdbObjectInfo& getBadChannelsInfo() const { return mBadChannelsInfo; }
+  CcdbObjectInfo& getBadChannelsInfo() { return mBadChannelsInfo; }
+
+  const PedestalsVector& getPedestalsVector() const { return mPedestalsVector; }
+
+ private:
+  float mNoiseThreshold;
+  float mPedestalThreshold;
+
+  TFType mTFStart;
+
+  // output
+  BadChannelsVector mBadChannelsVector; /// vector containing the unique IDs of the bad/noisy channels
+  CcdbObjectInfo mBadChannelsInfo;      /// vector of CCDB Infos , each element is filled with the CCDB description of the accompanying BadChannelsVector object
+  PedestalsVector mPedestalsVector;
+
+  ClassDefOverride(MCHChannelCalibrator, 1);
+};
+
+} // end namespace calibration
+} // end namespace mch
+} // end namespace o2
+
+#endif /* MCH_CHANNEL_CALIBRATOR_H_ */