EventsPerBC calibration task for FT0 (O2-6563) (#14986)

Implements the EventsPerBC calibration task for FT0, which generates a histogram of VTX events above a defined amplitude threshold plotted against the BC.

* FT0: created first sketch of implementation of generation of TVX per Event calibration object

* FT0: Updated CMakeLists for calibration

* FT0: Added missing entry in FT0CalibrationLinkDef.h

* FT0 calibration: fixed ROOT directory compilation, fixed CCDB output

* FT0: refined logs in EventsPerBc calibration, fixed setting TF info in run method

* FT0: Added readme to calibrations

* FT0: Changed calibration object name, implemented missing OrbitReset fetching

* FT0 EventsPerBc calibration: storing histograms in float format, updated readme

* Changed type of EventsPerBc calibration object to std::array

* FT0: corrected macro FT0readEventsPerBc, corrected typo in calibration README

* Created CCDB object class for EvetnsPerBC calibration

* FT0: formatted EvensPerBc.h

* FT0: removed amplitudes thresholds from EventsPerBc

* FT0: Removed from EventsPerBc calibarion option to define slot lenght in TFs; Small code cleaning

* Changed default value of min number of entries in EventsPerBcProcessor from 5000 to 5000u

Author: wpierozak

DataFormats/Detectors/FIT/FT0/CMakeLists.txt

@@ -47,4 +47,5 @@ o2_target_root_dictionary(DataFormatsFT0
           include/DataFormatsFT0/GlobalOffsetsCalibrationObject.h
           include/DataFormatsFT0/SpectraInfoObject.h
           include/DataFormatsFT0/SlewingCoef.h
+          include/DataFormatsFT0/EventsPerBc.h
 )

DataFormats/Detectors/FIT/FT0/include/DataFormatsFT0/EventsPerBc.h

@@ -0,0 +1,25 @@
+// 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 _FT0_EVENTS_PER_BC_CALIB_OBJECT
+#define _FT0_EVENTS_PER_BC_CALIB_OBJECT
+
+#include "CommonConstants/LHCConstants.h"
+#include <Rtypes.h>
+
+namespace o2::ft0
+{
+struct EventsPerBc {
+  std::array<double, o2::constants::lhc::LHCMaxBunches> histogram;
+  ClassDefNV(EventsPerBc, 1);
+};
+} // namespace o2::ft0
+#endif

DataFormats/Detectors/FIT/FT0/src/DataFormatsFT0LinkDef.h

@@ -56,4 +56,6 @@
 #pragma link C++ class std::pair < std::vector < double>, std::vector < double>> + ;
 #pragma link C++ class o2::ft0::SlewingCoef + ;
 
+#pragma link C++ class o2::ft0::EventsPerBc + ;
+
 #endif

Detectors/FIT/FT0/calibration/CMakeLists.txt

@@ -10,26 +10,50 @@
 # or submit itself to any jurisdiction.
 
 o2_add_library(FT0Calibration
-        SOURCES
-        src/FT0TimeOffsetSlotContainer.cxx
-        PUBLIC_LINK_LIBRARIES
-         O2::DataFormatsFT0
-         O2::CommonDataFormat
-         O2::DetectorsCalibration
-           )
-       o2_target_root_dictionary(FT0Calibration
-        HEADERS
-        include/FT0Calibration/FT0TimeOffsetSlotContainer.h
-        )
-      o2_add_executable(ft0-time-offset-calib
-        COMPONENT_NAME calibration
-        SOURCES workflow/FT0TimeOffsetCalibration-Workflow.cxx
-        PUBLIC_LINK_LIBRARIES
-        O2::FT0Calibration O2::FITCalibration
-        )
-      o2_add_executable(ft0-time-spectra-processor
-        COMPONENT_NAME calibration
-        SOURCES workflow/FT0TimeSpectraProcessor-Workflow.cxx
-        PUBLIC_LINK_LIBRARIES
-        O2::FT0Calibration
-        )
+  SOURCES
+    src/FT0TimeOffsetSlotContainer.cxx
+    src/EventsPerBcCalibrator.cxx
+  PUBLIC_LINK_LIBRARIES
+    O2::DetectorsCalibration
+    O2::Framework
+    O2::CommonUtils
+    Microsoft.GSL::GSL
+    O2::DataFormatsFT0
+    O2::CommonDataFormat
+    O2::Steer
+    O2::CCDB
+    ROOT::Minuit
+    ROOT::Hist
+  )
+
+o2_target_root_dictionary(FT0Calibration
+  HEADERS
+    include/FT0Calibration/FT0TimeOffsetSlotContainer.h
+    include/FT0Calibration/EventsPerBcCalibrator.h
+  )
+
+o2_add_executable(ft0-time-offset-calib
+  COMPONENT_NAME calibration
+  SOURCES
+    workflow/FT0TimeOffsetCalibration-Workflow.cxx
+  PUBLIC_LINK_LIBRARIES
+    O2::FT0Calibration O2::FITCalibration
+  )
+
+o2_add_executable(ft0-time-spectra-processor
+  COMPONENT_NAME calibration
+  SOURCES
+    workflow/FT0TimeSpectraProcessor-Workflow.cxx
+  PUBLIC_LINK_LIBRARIES
+    O2::FT0Calibration
+  )
+
+o2_add_executable(ft0-events-per-bc-processor
+  COMPONENT_NAME calibration
+  SOURCES
+    workflow/FT0EventsPerBcProcessor-Workflow.cxx
+  PUBLIC_LINK_LIBRARIES
+    O2::FT0Calibration
+    O2::Framework
+    O2::CCDB
+)

Detectors/FIT/FT0/calibration/README.md

@@ -0,0 +1,62 @@
+# Calibrations
+
+## Events per BC Calibration
+### Description
+Generates histograms of **Events per Bunch Crossing (BC)**. Events can be filtered by applying amplitude thresholds to the **A-side** and **C-side**.
+
+### Command-Line Options
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--slot-len-sec` | `3600` | Duration of each slot in seconds. |
+| `--slot-len-tf` | `0` | Slot length in Time Frames (TFs). |
+| `--one-object-per-run` | — | If set, the workflow creates only one calibration object per run. |
+| `--min-entries-number` | `0` | Minimum number of entries required for a slot to be valid. |
+| `--min-ampl-side-a` | `-2147483648` | Amplitude threshold for Side A events. |
+| `--min-ampl-side-c` | `-2147483648` | Amplitude threshold for Side C events. |
+
+---
+
+## How to Run
+
+### Simulation Data
+First, it is important to digitize data with a non-zero run number, orbit, and timestamp. To set these parameters, one can use the `--configKeyValues` option, as shown in the example below.
+```
+o2-sim-digitizer-workflow \
+--onlyDet FT0 \
+--configKeyValues="HBFUtils.nHBFPerTF=128;HBFUtils.orbitFirst=128;HBFUtils.orbitFirstSampled=256;HBFUtils.runNumber=560560;HBFUtils.startTime=1768464099000"
+```
+
+To process simulation data, digits must first be converted to RAW format. The `o2-ft0-digi2raw` tool performs this conversion and generates the required configuration file.
+
+Once converted, you can run the calibration either as a single integrated workflow or by spawning as the sender and receiver components separately.
+
+#### Single Workflow Example
+Execute the following command within the simulation directory:
+```
+o2-raw-file-reader-workflow --input-conf FT0raw.cfg --loop -1 \
+| o2-ft0-flp-dpl-workflow --condition-backend=http://localhost:8080 \
+| o2-calibration-ft0-events-per-bc-processor --FT0EventsPerBcProcessor "--slot-len-sec=10" \
+| o2-calibration-ccdb-populator-workflow --ccdb-path=http://localhost:8080
+```
+
+Sender example (in simulation directory):
+```
+o2-raw-file-reader-workflow --input-conf FT0raw.cfg --loop -1 \
+| o2-ft0-flp-dpl-workflow --condition-backend=http://localhost:8080 \
+| o2-dpl-output-proxy --channel-config "name=downstream,method=connect,address=tcp://localhost:30453,type=push,transport=zeromq" --dataspec "downstream:FT0/DIGITSBC"
+```
+
+Receiver example:
+```
+o2-dpl-raw-proxy --channel-config "name=readout-proxy,type=pull,method=bind,address=tcp://localhost:30453,rateLogging=1,transport=zeromq" --dataspec "A:FT0/DIGITSBC/0" \
+| o2-calibration-ft0-events-per-bc-processor --FT0EventsPerBcProcessor "--slot-len-sec=10 --min-ampl-side-a=0" \
+| o2-calibration-ccdb-populator-workflow --ccdb-path=http://localhost:8080/
+```
+
+### CTF Data
+Example:
+```
+o2-ctf-reader-workflow --ctf-input ctf.root --onlyDet FT0 \
+| o2-calibration-ft0-events-per-bc-processor --FT0EventsPerBcProcessor "--slot-len-sec=10" \
+| o2-calibration-ccdb-populator-workflow --ccdb-path=http://localhost:8080/
+```

Detectors/FIT/FT0/calibration/include/FT0Calibration/EventsPerBcCalibrator.h

@@ -0,0 +1,81 @@
+// 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_FT0TVXPERBCID
+#define O2_FT0TVXPERBCID
+
+#include <bitset>
+#include <array>
+#include <limits>
+#include <TH1F.h>
+
+#include "CommonDataFormat/FlatHisto2D.h"
+#include "CommonConstants/LHCConstants.h"
+#include "DataFormatsFT0/SpectraInfoObject.h"
+#include "DataFormatsFT0/Digit.h"
+#include "DataFormatsFT0/EventsPerBc.h"
+#include "DetectorsCalibration/TimeSlotCalibration.h"
+#include "DetectorsCalibration/TimeSlot.h"
+#include "CommonDataFormat/TFIDInfo.h"
+#include "TH1F.h"
+#include "Rtypes.h"
+
+namespace o2::ft0
+{
+struct EventsPerBcContainer {
+  EventsPerBcContainer(int32_t minAmplitudeSideA, int32_t minAmplitudeSideC) : mMinAmplitudeSideA(minAmplitudeSideA), mMinAmplitudeSideC(minAmplitudeSideC) {}
+
+  size_t getEntries() const { return entries; }
+  void print() const;
+  void fill(const o2::dataformats::TFIDInfo& ti, const gsl::span<const o2::ft0::Digit> data);
+  void merge(const EventsPerBcContainer* prev);
+
+  const int32_t mMinAmplitudeSideA;
+  const int32_t mMinAmplitudeSideC;
+
+  std::array<double, o2::constants::lhc::LHCMaxBunches> mTvx{0.0};
+  size_t entries{0};
+  long startTimeStamp{0};
+  long stopTimeStamp{0};
+
+  ClassDefNV(EventsPerBcContainer, 1);
+};
+
+class EventsPerBcCalibrator final : public o2::calibration::TimeSlotCalibration<o2::ft0::EventsPerBcContainer>
+{
+  using Slot = o2::calibration::TimeSlot<o2::ft0::EventsPerBcContainer>;
+  using TFType = o2::calibration::TFType;
+  using EventsHistogram = std::array<double, o2::constants::lhc::LHCMaxBunches>;
+
+ public:
+  EventsPerBcCalibrator(uint32_t minNumberOfEntries, int32_t minAmplitudeSideA, int32_t minAmplitudeSideC);
+
+  bool hasEnoughData(const Slot& slot) const override;
+  void initOutput() override;
+  void finalizeSlot(Slot& slot) override;
+  Slot& emplaceNewSlot(bool front, TFType tstart, TFType tend) override;
+
+  const std::vector<EventsPerBc>& getTvxPerBc() { return mTvxPerBcs; }
+  std::vector<std::unique_ptr<o2::ccdb::CcdbObjectInfo>>& getTvxPerBcCcdbInfo() { return mTvxPerBcInfos; }
+
+ private:
+  const uint32_t mMinNumberOfEntries;
+  const int32_t mMinAmplitudeSideA;
+  const int32_t mMinAmplitudeSideC;
+
+  std::vector<EventsPerBc> mTvxPerBcs;
+  std::vector<std::unique_ptr<o2::ccdb::CcdbObjectInfo>> mTvxPerBcInfos;
+
+  ClassDefOverride(EventsPerBcCalibrator, 1);
+};
+} // namespace o2::ft0
+
+#endif

Detectors/FIT/FT0/calibration/src/EventsPerBcCalibrator.cxx

@@ -0,0 +1,81 @@
+// 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 "FT0Calibration/EventsPerBcCalibrator.h"
+#include "CommonUtils/MemFileHelper.h"
+
+namespace o2::ft0
+{
+void EventsPerBcContainer::print() const
+{
+  LOG(info) << entries << " entries";
+}
+
+void EventsPerBcContainer::fill(const o2::dataformats::TFIDInfo& ti, const gsl::span<const o2::ft0::Digit> data)
+{
+  size_t oldEntries = entries;
+  for (const auto& digit : data) {
+    if (digit.mTriggers.getVertex() && digit.mTriggers.getAmplA() >= mMinAmplitudeSideA && digit.mTriggers.getAmplC() >= mMinAmplitudeSideC) {
+      mTvx[digit.mIntRecord.bc]++;
+      entries++;
+    }
+  }
+  LOG(debug) << "Container is filled with " << entries - oldEntries << " new events";
+}
+
+void EventsPerBcContainer::merge(const EventsPerBcContainer* prev)
+{
+  for (int bc = 0; bc < o2::constants::lhc::LHCMaxBunches; bc++) {
+    mTvx[bc] += prev->mTvx[bc];
+  }
+  entries += prev->entries;
+}
+
+void EventsPerBcCalibrator::initOutput()
+{
+  mTvxPerBcs.clear();
+  mTvxPerBcInfos.clear();
+}
+
+EventsPerBcCalibrator::EventsPerBcCalibrator(uint32_t minNumberOfEntries, int32_t minAmplitudeSideA, int32_t minAmplitudeSideC) : mMinNumberOfEntries(minNumberOfEntries), mMinAmplitudeSideA(minAmplitudeSideA), mMinAmplitudeSideC(minAmplitudeSideC)
+{
+  LOG(info) << "Defined threshold for number of entires per slot: " << mMinNumberOfEntries;
+  LOG(info) << "Defined threshold for side A amplitude for event: " << mMinAmplitudeSideA;
+  LOG(info) << "Defined threshold for side C amplitude for event: " << mMinAmplitudeSideC;
+}
+
+bool EventsPerBcCalibrator::hasEnoughData(const EventsPerBcCalibrator::Slot& slot) const
+{
+  return slot.getContainer()->entries > mMinNumberOfEntries;
+}
+
+void EventsPerBcCalibrator::finalizeSlot(EventsPerBcCalibrator::Slot& slot)
+{
+  LOG(info) << "Finalizing slot from " << slot.getStartTimeMS() << " to " << slot.getEndTimeMS();
+  o2::ft0::EventsPerBcContainer* data = slot.getContainer();
+  mTvxPerBcs.emplace_back(data->mTvx);
+
+  auto clName = o2::utils::MemFileHelper::getClassName(mTvxPerBcs.back());
+  auto flName = o2::ccdb::CcdbApi::generateFileName(clName);
+
+  std::map<std::string, std::string> metaData;
+  mTvxPerBcInfos.emplace_back(std::make_unique<o2::ccdb::CcdbObjectInfo>("FT0/Calib/EventsPerBc", clName, flName, metaData, slot.getStartTimeMS(), slot.getEndTimeMS()));
+  LOG(info) << "Created object valid from " << mTvxPerBcInfos.back()->getStartValidityTimestamp() << " to " << mTvxPerBcInfos.back()->getEndValidityTimestamp();
+}
+
+EventsPerBcCalibrator::Slot& EventsPerBcCalibrator::emplaceNewSlot(bool front, TFType tstart, TFType tend)
+{
+  auto& cont = getSlots();
+  auto& slot = front ? cont.emplace_front(tstart, tend) : cont.emplace_back(tstart, tend);
+  slot.setContainer(std::make_unique<EventsPerBcContainer>(mMinAmplitudeSideA, mMinAmplitudeSideC));
+  return slot;
+}
+} // namespace o2::ft0

Detectors/FIT/FT0/calibration/src/FT0CalibrationLinkDef.h

@@ -16,7 +16,9 @@
 #pragma link off all functions;
 
 #pragma link C++ class o2::ft0::FT0TimeOffsetSlotContainer + ;
+#pragma link C++ class o2::ft0::EventsPerBcCalibrator + ;
 #pragma link C++ class o2::calibration::TimeSlot < o2::ft0::FT0TimeOffsetSlotContainer>;
 #pragma link C++ class o2::calibration::TimeSlotCalibration < o2::ft0::FT0TimeOffsetSlotContainer>;
-
+#pragma link C++ class o2::calibration::TimeSlot < o2::ft0::EventsPerBcContainer> + ;
+#pragma link C++ class o2::calibration::TimeSlotCalibration < o2::ft0::EventsPerBcContainer> + ;
 #endif