[MCH] filter digits based on HV status (#13308)

pillot · comrademarvin · alcaliva · commit 5020bf2dde56 · 2025-03-04T14:11:32.000+01:00
* preparation for recording HV status in status map

* Addition of HV issues algorithm

* improve TF timestamp calculation and add time margin

* activate the digit filtering on bad HV

* update documentation

* add protection against invalid DCS alias

---------

Co-authored-by: Stephan Potgieter &lt;77969712+comrademarvin@users.noreply.github.com&gt;
diff --git a/Detectors/MUON/MCH/DigitFiltering/README.md b/Detectors/MUON/MCH/DigitFiltering/README.md
@@ -11,6 +11,10 @@ o2-mch-digits-filtering-workflow
 
 Filter out some digits.
 
+**StatusMap based filtering :**
+
+The [status map](/Detectors/MUON/MCH/Status/README.md) lists all the pads that are not perfect and assigns them a status word summarizing the origin of the issue(s). The filtering based on the status map is governed by the [MCHDigitFilterParam](/Detectors/MUON/MCH/DigitFiltering/include/MCHDigitFiltering/DigitFilterParam.h)`.statusMask` parameter, from which we can select the issue(s) to be filtered.
+
 **Noise filtering :**
 
 The exact behavior of the noise filtering is governed by the [MCHDigitFilterParam](/Detectors/MUON/MCH/DigitFiltering/include/MCHDigitFiltering/DigitFilterParam.h) configurable param, where you can select the minimum ADC value to consider, and whether to select signal (i.e. killing as much background as possible, possibly killing some signal as well) and/or to reject background (while not killing signal).
diff --git a/Detectors/MUON/MCH/DigitFiltering/include/MCHDigitFiltering/DigitFilterParam.h b/Detectors/MUON/MCH/DigitFiltering/include/MCHDigitFiltering/DigitFilterParam.h
@@ -14,6 +14,7 @@
 
 #include "CommonUtils/ConfigurableParam.h"
 #include "CommonUtils/ConfigurableParamHelper.h"
+#include "MCHStatus/StatusMap.h"
 
 namespace o2::mch
 {
@@ -29,7 +30,8 @@ struct DigitFilterParam : public o2::conf::ConfigurableParamHelper<DigitFilterPa
   bool rejectBackground = true; ///< attempts to reject background (loose background selection, don't kill signal)
   bool selectSignal = false;    ///< attempts to select only signal (strict background selection, might loose signal)
   int timeOffset = 120;         ///< digit time calibration offset
-  uint32_t statusMask = 3;      ///< mask to reject digits based on the statusmap (0=no rejection,1=badchannels from ped calib only,2=badchannels from rejectlist,3=1+2)
+  /// mask to reject digits based on the statusmap (0 = no rejection)
+  uint32_t statusMask = StatusMap::kBadPedestal | StatusMap::kRejectList | StatusMap::kBadHV;
 
   O2ParamDef(DigitFilterParam, "MCHDigitFilter");
 };
diff --git a/Detectors/MUON/MCH/Status/CMakeLists.txt b/Detectors/MUON/MCH/Status/CMakeLists.txt
@@ -11,11 +11,13 @@
 
 o2_add_library(MCHStatus
         SOURCES
+          src/HVStatusCreator.cxx
           src/StatusMap.cxx
           src/StatusMapCreatorParam.cxx
           src/StatusMapCreatorSpec.cxx
         PUBLIC_LINK_LIBRARIES
           fmt::fmt
+          O2::DetectorsDCS
           O2::DataFormatsMCH
           O2::MCHGlobalMapping)
 
diff --git a/Detectors/MUON/MCH/Status/README.md b/Detectors/MUON/MCH/Status/README.md
@@ -6,7 +6,7 @@ The status map is an object that list all pads that are not perfect, for some re
 
 The gathering of all the sources of information is performed by the [StatusMapCreatorSpec](src/StatusMapCreatorSpec.cxx), either in standalone [o2-mch-statusmap-creator-workflow](src/statusmap-creator-workflow.cxx) device, or, most probably, as part of the regular [o2-mch-reco-workflow](../Workflow/src/reco-workflow.cxx).
 
-So far only we have only implemented the bad channel list from pedestal runs and the manual reject list. Next in line will be the usage of the HV and LV values.
+So far we have implemented the bad channel list from pedestal runs, HV status and the manual reject list.
 
 ## StatusMap usage
 
diff --git a/Detectors/MUON/MCH/Status/include/MCHStatus/HVStatusCreator.h b/Detectors/MUON/MCH/Status/include/MCHStatus/HVStatusCreator.h
@@ -0,0 +1,116 @@
+// Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+// All rights not expressly granted are reserved.
+//
+// This software is distributed under the terms of the GNU General Public
+// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+//
+// 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.
+
+#ifndef O2_MCH_HV_STATUS_CREATOR_H_
+#define O2_MCH_HV_STATUS_CREATOR_H_
+
+#include <set>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "DetectorsDCS/DataPointIdentifier.h"
+#include "DetectorsDCS/DataPointValue.h"
+
+namespace o2::mch
+{
+
+class StatusMap;
+
+/**
+ * @class HVStatusCreator
+ * @brief Find HV issues from DCS data points and add them to the status map
+ *
+ * This is a 3 step procedure:
+ *
+ * 1) Find all potential issues from the DCS data points stored in one HV file.
+ * This must be done each time a new HV file is read from the CCDB. It stores in
+ * an internal map the time range(s) of the issue(s) for each affected HV channel.
+ *
+ * 2) Find all real issues at a given time stamp.
+ * This must be done for every TF. It updates the internal list of bad HV
+ * channels if it is different from the current one and tells if that happens.
+ *
+ * 3) Update the status maps if needed.
+ * This must be done each time the current list of bad HV channel has changed.
+ * It adds every electronics channels associated to the bad HV channels into the
+ * status map given as a parameter.
+ */
+class HVStatusCreator
+{
+ public:
+  using DPID = o2::dcs::DataPointIdentifier;
+  using DPVAL = o2::dcs::DataPointValue;
+  using DPMAP = std::unordered_map<DPID, std::vector<DPVAL>>;
+
+  /// Internal structure to define a time range
+  struct TimeRange {
+    uint64_t begin = 0; ///< beginning of time range
+    uint64_t end = 0;   ///< end of time range
+
+    /**
+     * Constructor of time range
+     * @param begin beginning of time range (ms)
+     * @param end end of time range (ms)
+     */
+    TimeRange(uint64_t begin, uint64_t end) : begin(begin), end(end){};
+
+    /**
+     * Check if the time range contains the given time stamp
+     * @param timestamp time stamp of interest (ms)
+     * @return true if the time stamp is in the time range
+     */
+    bool contains(uint64_t timestamp) const { return timestamp >= begin && timestamp < end; }
+  };
+
+  using BADHVMAP = std::unordered_map<std::string, std::vector<TimeRange>>;
+
+  /**
+   * Getter for the internal map of HV issues
+   * @return map of bad HV channels with the time ranges concerned
+   */
+  const BADHVMAP& getBadHVs() const { return mBadHVTimeRanges; }
+
+  /**
+   * Find all HV issues and their time ranges
+   * @param dpMap DCS HV data points from CCDB
+   */
+  void findBadHVs(const DPMAP& dpMap);
+
+  /**
+   * Find HV issues at a given time stamp
+   * @param timestamp time stamp of interest
+   * @return true if the list of issues has changed
+   */
+  bool findCurrentBadHVs(uint64_t timestamp);
+
+  /**
+   * Add channels affected by current HV issues to the status map
+   * @param statusMap statusMap to update
+   */
+  void updateStatusMap(StatusMap& statusMap) const;
+
+  /// Clear the internal lists of HV issues
+  void clear()
+  {
+    mBadHVTimeRanges.clear();
+    mCurrentBadHVs.clear();
+  }
+
+ private:
+  /// map of bad HV channels with the time ranges concerned
+  BADHVMAP mBadHVTimeRanges{};
+  std::set<std::string> mCurrentBadHVs{}; ///< current list of bad HV channels
+};
+
+} // namespace o2::mch
+
+#endif // O2_MCH_HV_STATUS_CREATOR_H_
diff --git a/Detectors/MUON/MCH/Status/include/MCHStatus/StatusMapCreatorParam.h b/Detectors/MUON/MCH/Status/include/MCHStatus/StatusMapCreatorParam.h
@@ -25,9 +25,16 @@ namespace o2::mch
 struct StatusMapCreatorParam : public o2::conf::ConfigurableParamHelper<StatusMapCreatorParam> {
 
   bool useBadChannels = true; ///< reject bad channels (obtained during pedestal calibration runs)
-  bool useRejectList = true;  ///< use extra (relative to bad channels above) rejection list
+  bool useRejectList = true;  ///< use extra rejection list (relative to other bad channels sources)
+  bool useHV = true;          ///< reject channels connected to bad HV sectors
 
-  bool isActive() const { return useBadChannels || useRejectList; }
+  /// chambers HV thresholds for detecting issues
+  double hvLimits[10] = {1550., 1550., 1600., 1600., 1600., 1600., 1600., 1600., 1600., 1600.};
+  uint64_t hvMinDuration = 10000; ///< minimum duration of HV issues in ms
+
+  uint64_t timeMargin = 2000; ///< time margin for comparing DCS and TF timestamps in ms
+
+  bool isActive() const { return useBadChannels || useRejectList || useHV; }
 
   O2ParamDef(StatusMapCreatorParam, "MCHStatusMap");
 };
diff --git a/Detectors/MUON/MCH/Status/src/HVStatusCreator.cxx b/Detectors/MUON/MCH/Status/src/HVStatusCreator.cxx
@@ -0,0 +1,155 @@
+// Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+// All rights not expressly granted are reserved.
+//
+// This software is distributed under the terms of the GNU General Public
+// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+//
+// 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.
+
+#include <algorithm>
+#include <map>
+
+#include "MCHStatus/HVStatusCreator.h"
+
+#include "MCHConditions/DCSAliases.h"
+#include "MCHConditions/DetectionElement.h"
+#include "MCHGlobalMapping/Mapper.h"
+#include "MCHStatus/StatusMap.h"
+#include "MCHStatus/StatusMapCreatorParam.h"
+
+using DPMAP2 = std::unordered_map<std::string, std::map<uint64_t, double>>;
+
+/// Converts DCS data point value to double HV value
+double dpConverter(o2::dcs::DataPointValue v)
+{
+  union Converter {
+    uint64_t raw_data;
+    double value;
+  } converter;
+  converter.raw_data = v.payload_pt1;
+  return converter.value;
+};
+
+/// Decode the DCS DPMAP to be processed for HV issues
+DPMAP2 decodeDPMAP(const o2::mch::HVStatusCreator::DPMAP& dpMap)
+{
+  DPMAP2 dpsMapPerAlias{};
+
+  auto timeMargin = o2::mch::StatusMapCreatorParam::Instance().timeMargin;
+
+  for (const auto& [dpId, dpsHV] : dpMap) {
+    std::string alias = dpId.get_alias();
+
+    if (alias.find("vMon") != std::string::npos && o2::mch::dcs::isValid(alias)) {
+      auto& dps2 = dpsMapPerAlias[alias];
+
+      // copy first point to the beginning of time + margin (will be subtracted later on)
+      dps2.emplace(timeMargin, dpConverter(dpsHV.front()));
+
+      for (const auto& value : dpsHV) {
+        dps2.emplace(value.get_epoch_time(), dpConverter(value));
+      }
+
+      // copy last point to the end of time - margin (will be added later on)
+      dps2.emplace(std::numeric_limits<uint64_t>::max() - timeMargin, dpConverter(dpsHV.back()));
+    }
+  }
+
+  return dpsMapPerAlias;
+}
+
+namespace o2::mch
+{
+
+void HVStatusCreator::findBadHVs(const DPMAP& dpMap)
+{
+  // clear current list of issues
+  mBadHVTimeRanges.clear();
+
+  // decode the DCS DPMAP
+  DPMAP2 dpsMapPerAlias = decodeDPMAP(dpMap);
+
+  auto minDuration = StatusMapCreatorParam::Instance().hvMinDuration;
+  auto timeMargin = StatusMapCreatorParam::Instance().timeMargin;
+
+  // find list of HV issues per alias
+  for (const auto& [alias, dpsHV] : dpsMapPerAlias) {
+    int chamber = o2::mch::dcs::toInt(o2::mch::dcs::aliasToChamber(alias));
+    auto chamberThreshold = StatusMapCreatorParam::Instance().hvLimits[chamber];
+
+    std::vector<TimeRange> hvIssuesList{};
+    uint64_t tStart = 0;
+    uint64_t tStop = 0;
+    bool ongoingIssue = false;
+
+    for (auto [timestamp, valueHV] : dpsHV) {
+      if (valueHV < chamberThreshold) {
+        if (!ongoingIssue) {
+          tStart = timestamp;
+          tStop = tStart;
+          ongoingIssue = true;
+        } else {
+          tStop = timestamp;
+        }
+      } else {
+        if (ongoingIssue) {
+          tStop = timestamp;
+          if (tStop - tStart > minDuration) {
+            hvIssuesList.emplace_back(tStart - timeMargin, tStop + timeMargin);
+          }
+          ongoingIssue = false;
+        }
+      }
+    }
+
+    // ongoing issue at the end of the object
+    if (ongoingIssue && tStop - tStart > minDuration) {
+      hvIssuesList.emplace_back(tStart - timeMargin, tStop + timeMargin);
+    }
+
+    // add issues for the alias if non-empty
+    if (!hvIssuesList.empty()) {
+      mBadHVTimeRanges.emplace(alias, hvIssuesList);
+    }
+  }
+}
+
+bool HVStatusCreator::findCurrentBadHVs(uint64_t timestamp)
+{
+  // list issues at the given time stamp
+  std::set<std::string> currentBadHVs{};
+  for (const auto& [alias, timeRanges] : mBadHVTimeRanges) {
+    auto it = std::find_if(timeRanges.begin(), timeRanges.end(),
+                           [timestamp](const TimeRange& r) { return r.contains(timestamp); });
+    if (it != timeRanges.end()) {
+      currentBadHVs.emplace(alias);
+    }
+  }
+
+  // check if the list of issues has changed and update it in this case
+  if (currentBadHVs != mCurrentBadHVs) {
+    mCurrentBadHVs.swap(currentBadHVs);
+    return true;
+  }
+
+  return false;
+}
+
+void HVStatusCreator::updateStatusMap(StatusMap& statusMap) const
+{
+  for (const auto& alias : mCurrentBadHVs) {
+    int deId = dcs::aliasToDetElemId(alias).value();
+    if (deId < 500) {
+      for (auto dsIndex : dcs::aliasToDsIndices(alias)) {
+        statusMap.addDS(dsIndex, StatusMap::kBadHV);
+      }
+    } else {
+      statusMap.addDE(deId, StatusMap::kBadHV);
+    }
+  }
+}
+
+} // namespace o2::mch
diff --git a/Detectors/MUON/MCH/Status/src/StatusMapCreatorSpec.cxx b/Detectors/MUON/MCH/Status/src/StatusMapCreatorSpec.cxx
