TPC: Processing of common mode values in O2

DataFormats/Detectors/TPC/include/DataFormatsTPC/CMV.h

@@ -0,0 +1,122 @@
+// 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.
+
+/// @file   CMV.h
+/// @author Tuba Gündem, tuba.gundem@cern.ch
+/// @brief  Common mode values data format definition
+
+/// The data is sent by the CRU as 256+16 bit words. The CMV data layout is as follows:
+/// - 256-bit Header: [version:8][packetID:8][errorCode:8][magicWord:8][heartbeatOrbit:32][heartbeatBC:16][padding:176]
+/// - 16-bit CMV value: [sign:1][I8F7:15] where bit 15 is the sign (1=positive, 0=negative) and the lower 15 bits are a fixed point I8F7 value (8 integer bits, 7 fractional bits)
+///   Float conversion: sign ? (value & 0x7FFF) / 128.0 : -(value & 0x7FFF) / 128.0
+
+#ifndef ALICEO2_DATAFORMATSTPC_CMV_H
+#define ALICEO2_DATAFORMATSTPC_CMV_H
+
+#include <cstdint>
+#include <cmath>
+
+namespace o2::tpc::cmv
+{
+
+static constexpr uint32_t NTimeBinsPerPacket = 3564;                                 ///< number of time bins (covering 8 heartbeats)
+static constexpr uint32_t NPacketsPerTFPerCRU = 4;                                   ///< 4 packets per timeframe
+static constexpr uint32_t NTimeBinsPerTF = NTimeBinsPerPacket * NPacketsPerTFPerCRU; ///< maximum number of timebins per timeframe (14256)
+
+/// Data padding: NTimeBinsPerPacket * sizeof(Data) = 3564 * 2 = 7128 bytes
+static constexpr uint32_t DataSizeBytes = NTimeBinsPerPacket * sizeof(uint16_t); ///< 7128 bytes
+static constexpr uint32_t DataPaddingBytes = (32 - (DataSizeBytes % 32)) % 32;   ///< 8 bytes
+
+/// Header definition of the CMVs
+struct Header {
+  static constexpr uint8_t MagicWord = 0xDC;
+  union {
+    uint64_t word0 = 0; ///< bits 0 - 63
+    struct {
+      uint8_t version : 8;          ///< version
+      uint8_t packetID : 8;         ///< packet id
+      uint8_t errorCode : 8;        ///< errors
+      uint8_t magicWord : 8;        ///< magic word
+      uint32_t heartbeatOrbit : 32; ///< first heart beat timing of the package
+    };
+  };
+  union {
+    uint64_t word1 = 0; ///< bits 64 - 127
+    struct {
+      uint16_t heartbeatBC : 16; ///< first BC id of the package
+      uint16_t unused1 : 16;     ///< reserved
+      uint32_t unused2 : 32;     ///< reserved
+    };
+  };
+  union {
+    uint64_t word3 = 0; ///< bits 128 - 191
+    struct {
+      uint64_t unused3 : 64; ///< reserved
+    };
+  };
+  union {
+    uint64_t word4 = 0; ///< bits 192 - 255
+    struct {
+      uint64_t unused4 : 64; ///< reserved
+    };
+  };
+};
+
+/// CMV single data container
+struct Data {
+  uint16_t cmv{0}; ///< 16-bit signed fixed point value: bit 15 = sign (1=positive, 0=negative), bits 14-0 = I8F7 magnitude
+
+  uint16_t getCMV() const { return cmv; }      ///< raw 16-bit integer representation
+  void setCMV(uint16_t value) { cmv = value; } ///< set raw 16-bit integer representation
+
+  // Decode to float: sign-magnitude with 7 fractional bits, range ±255.992
+  float getCMVFloat() const
+  {
+    const bool positive = (cmv >> 15) & 1;          // bit 15: sign (1=positive, 0=negative)
+    const float magnitude = (cmv & 0x7FFF) / 128.f; // lower 15 bits, shift right by 7 (divide by 2^7)
+    return positive ? magnitude : -magnitude;
+  }
+
+  // Encode from float: clamps magnitude to 15 bits, range ±255.992
+  void setCMVFloat(float value)
+  {
+    const bool positive = (value >= 0.f);
+    const uint16_t magnitude = static_cast<uint16_t>(std::abs(value) * 128.f + 0.5f) & 0x7FFF;
+    cmv = (positive ? 0x8000 : 0x0000) | magnitude;
+  }
+};
+
+/// CMV full data container: one packet carries NTimeBinsPerPacket CMV values followed by padding
+/// Layout: Header (32 bytes) + Data[NTimeBinsPerPacket] (7128 bytes) + padding (8 bytes) = 7168 bytes total (224 * 32 = 7168)
+/// The padding bytes at the end of the data array are rubbish/unused and must not be interpreted as CMV values
+struct Container {
+  Header header;                       ///< CMV data header
+  Data data[NTimeBinsPerPacket];       ///< data values
+  uint8_t padding[DataPaddingBytes]{}; ///< trailing padding to align data to 32-byte boundary
+
+  // Header and data accessors
+  const Header& getHeader() const { return header; }
+  Header& getHeader() { return header; }
+
+  const Data* getData() const { return data; }
+  Data* getData() { return data; }
+
+  // Per timebin CMV accessors
+  uint16_t getCMV(uint32_t timeBin) const { return data[timeBin].getCMV(); }
+  void setCMV(uint32_t timeBin, uint16_t value) { data[timeBin].setCMV(value); }
+
+  float getCMVFloat(uint32_t timeBin) const { return data[timeBin].getCMVFloat(); }
+  void setCMVFloat(uint32_t timeBin, float value) { data[timeBin].setCMVFloat(value); }
+};
+
+} // namespace o2::tpc::cmv
+
+#endif

Detectors/TPC/base/include/TPCBase/RDHUtils.h

@@ -13,7 +13,7 @@
 #define AliceO2_TPC_RDHUtils_H
 
 #include "DetectorsRaw/RDHUtils.h"
-//#include "Headers/RAWDataHeader.h"
+// #include "Headers/RAWDataHeader.h"
 
 namespace o2
 {
@@ -28,6 +28,7 @@ static constexpr FEEIDType UserLogicLinkID = 15; ///< virtual link ID for ZS dat
 static constexpr FEEIDType IDCLinkID = 20;       ///< Identifier for integrated digital currents
 static constexpr FEEIDType ILBZSLinkID = 21;     ///< Identifier for improved link-based ZS
 static constexpr FEEIDType DLBZSLinkID = 22;     ///< Identifier for dense link-based ZS
+static constexpr FEEIDType CMVLinkID = 23;       ///< Identifier for common mode values
 static constexpr FEEIDType SACLinkID = 25;       ///< Identifier for sampled analog currents
 
 /// compose feeid from cru, endpoint and link

Detectors/TPC/calibration/CMakeLists.txt

@@ -58,6 +58,7 @@ o2_add_library(TPCCalibration
                        src/DigitAdd.cxx
                        src/CorrectdEdxDistortions.cxx
                        src/PressureTemperatureHelper.cxx
+                       src/CMVContainer.cxx
                PUBLIC_LINK_LIBRARIES O2::DataFormatsTPC O2::TPCBaseRecSim
                                      O2::TPCReconstruction ROOT::Minuit
                                      Microsoft.GSL::GSL
@@ -115,7 +116,8 @@ o2_target_root_dictionary(TPCCalibration
                                   include/TPCCalibration/TPCMShapeCorrection.h
                                   include/TPCCalibration/DigitAdd.h
                                   include/TPCCalibration/CorrectdEdxDistortions.h
-                                  include/TPCCalibration/PressureTemperatureHelper.h)
+                                  include/TPCCalibration/PressureTemperatureHelper.h
+                                  include/TPCCalibration/CMVContainer.h)
 
 o2_add_test_root_macro(macro/comparePedestalsAndNoise.C
                        PUBLIC_LINK_LIBRARIES O2::TPCBaseRecSim

Detectors/TPC/calibration/include/TPCCalibration/CMVContainer.h

@@ -0,0 +1,87 @@
+// 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.
+
+/// @file   CMVContainer.h
+/// @author Tuba Gündem, tuba.gundem@cern.ch
+/// @brief  Structs for storing CMVs to the CCDB
+
+#ifndef ALICEO2_TPC_CMVCONTAINER_H_
+#define ALICEO2_TPC_CMVCONTAINER_H_
+
+#include <vector>
+#include <string>
+#include <memory>
+#include <stdexcept>
+#include <fmt/format.h>
+
+#include "TTree.h"
+#include "DataFormatsTPC/CMV.h"
+
+namespace o2::tpc
+{
+
+/// CMV data for one TF across all CRUs
+struct CMVPerTF {
+  int64_t firstOrbit{0}; ///< First orbit of this TF, from heartbeatOrbit of the first CMV packet
+  int64_t firstBC{0};    ///< First bunch crossing of this TF, from heartbeatBC of the first CMV packet
+
+  /// CMV float values indexed as [CRU ID][time bin]
+  std::vector<std::vector<float>> mDataPerTF;
+
+  /// Return the CMV value for a given CRU and time bin within this TF
+  float getCMV(const int cru, const int timeBin) const
+  {
+    if (cru < 0 || static_cast<std::size_t>(cru) >= mDataPerTF.size()) {
+      throw std::out_of_range(fmt::format("CMVPerTF::getCMV: cru {} out of range [0, {})", cru, mDataPerTF.size()));
+    }
+    if (timeBin < 0 || static_cast<uint32_t>(timeBin) >= cmv::NTimeBinsPerTF) {
+      throw std::out_of_range(fmt::format("CMVPerTF::getCMV: timeBin {} out of range [0, {})", timeBin, cmv::NTimeBinsPerTF));
+    }
+    return mDataPerTF[cru][timeBin];
+  }
+
+  ClassDefNV(CMVPerTF, 1)
+};
+
+/// Container holding CMVs for one aggregation interval
+struct CMVPerInterval {
+  int64_t firstTF{0}; ///< First TF counter seen in this interval
+  int64_t lastTF{0};  ///< Last TF counter seen in this interval
+
+  /// CMV data, one CMVPerTF entry per TF, indexed by relative TF [0, nTimeFrames)
+  std::vector<CMVPerTF> mCMVPerTF;
+
+  /// Pre-allocate nTFs TF slots; each slot gets mDataPerTF resized to nCRUs entries
+  void reserve(uint32_t nTFs, uint32_t nCRUs);
+
+  std::size_t size() const { return mCMVPerTF.size(); }
+  bool empty() const { return mCMVPerTF.empty(); }
+
+  /// Clear all data and reset counters
+  void clear();
+
+  std::string summary() const;
+
+  /// Serialise into a TTree with a single branch holding the whole CMVPerInterval object
+  std::unique_ptr<TTree> toTTree() const;
+
+  /// Write the TTree to a ROOT file
+  void writeToFile(const std::string& filename, const std::unique_ptr<TTree>& tree) const;
+
+  /// Restore a CMVPerInterval from a TTree previously written by toTTree()
+  static CMVPerInterval fromTTree(TTree* tree, int entry = 0);
+
+  ClassDefNV(CMVPerInterval, 1)
+};
+
+} // namespace o2::tpc
+
+#endif // ALICEO2_TPC_CMVCONTAINER_H_

Detectors/TPC/calibration/src/CMVContainer.cxx

@@ -0,0 +1,95 @@
+// 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.
+
+/// @file   CMVContainer.cxx
+/// @author Tuba Gündem, tuba.gundem@cern.ch
+
+#include <stdexcept>
+#include <fmt/format.h>
+
+#include "TFile.h"
+
+#include "TPCCalibration/CMVContainer.h"
+
+namespace o2::tpc
+{
+
+void CMVPerInterval::reserve(uint32_t nTFs, uint32_t nCRUs)
+{
+  mCMVPerTF.resize(nTFs);
+  for (auto& tfData : mCMVPerTF) {
+    tfData.mDataPerTF.resize(nCRUs);
+  }
+}
+
+void CMVPerInterval::clear()
+{
+  mCMVPerTF.clear();
+  firstTF = 0;
+  lastTF = 0;
+}
+
+std::string CMVPerInterval::summary() const
+{
+  const std::size_t nCRUs = empty() ? 0 : mCMVPerTF.front().mDataPerTF.size();
+  return fmt::format("CMVPerInterval: {} TFs, {} CRU slots, firstTF={}, lastTF={}",
+                     size(), nCRUs, firstTF, lastTF);
+}
+
+std::unique_ptr<TTree> CMVPerInterval::toTTree() const
+{
+  if (empty()) {
+    throw std::runtime_error("CMVPerInterval::toTTree() called on empty container");
+  }
+
+  auto tree = std::make_unique<TTree>("ccdb_object", "ccdb_object");
+  tree->SetAutoSave(0);
+  tree->SetDirectory(nullptr);
+
+  const CMVPerInterval* ptr = this;
+  tree->Branch("CMVPerInterval", &ptr);
+  tree->Fill();
+
+  tree->ResetBranchAddresses();
+
+  return tree;
+}
+
+void CMVPerInterval::writeToFile(const std::string& filename, const std::unique_ptr<TTree>& tree) const
+{
+  TFile f(filename.c_str(), "RECREATE");
+  if (f.IsZombie()) {
+    throw std::runtime_error(fmt::format("CMVPerInterval::writeToFile: cannot open '{}'", filename));
+  }
+  tree->Write();
+  f.Close();
+}
+
+CMVPerInterval CMVPerInterval::fromTTree(TTree* tree, int entry)
+{
+  if (!tree) {
+    throw std::runtime_error("CMVPerInterval::fromTTree: null TTree pointer");
+  }
+
+  CMVPerInterval* ptr = nullptr;
+  tree->SetBranchAddress("CMVPerInterval", &ptr);
+  tree->GetEntry(entry);
+
+  if (!ptr) {
+    throw std::runtime_error("CMVPerInterval::fromTTree: failed to read object from TTree");
+  }
+
+  CMVPerInterval result = std::move(*ptr);
+  delete ptr;
+  return result;
+}
+
+} // namespace o2::tpc

Detectors/TPC/calibration/src/TPCCalibrationLinkDef.h

@@ -123,4 +123,10 @@
 #pragma link C++ class o2::tpc::DigitAdd + ;
 #pragma link C++ class std::vector < o2::tpc::DigitAdd> + ;
 #pragma link C++ class o2::tpc::PressureTemperatureHelper + ;
+
+#pragma link C++ class o2::tpc::CMVPerTF + ;
+#pragma link C++ class o2::tpc::CMVPerInterval + ;
+#pragma link C++ class std::vector < o2::tpc::CMVPerTF> + ;
+#pragma link C++ class std::vector < std::vector < float>> + ;
+
 #endif

Detectors/TPC/workflow/CMakeLists.txt

@@ -25,6 +25,7 @@ o2_add_library(TPCWorkflow
                        src/KryptonRawFilterSpec.cxx
                        src/OccupancyFilterSpec.cxx
                        src/SACProcessorSpec.cxx
+                       src/CMVToVectorSpec.cxx
                        src/IDCToVectorSpec.cxx
                        src/CalibdEdxSpec.cxx
                        src/CalibratordEdxSpec.cxx
@@ -288,4 +289,19 @@ o2_add_executable(pressure-temperature
                   SOURCES src/tpc-pressure-temperature.cxx
                   PUBLIC_LINK_LIBRARIES O2::TPCWorkflow)
 
-add_subdirectory(readers)
+o2_add_executable(cmv-to-vector
+                  COMPONENT_NAME tpc
+                  SOURCES src/tpc-cmv-to-vector.cxx
+                  PUBLIC_LINK_LIBRARIES O2::TPCWorkflow)
+
+o2_add_executable(cmv-flp
+                  COMPONENT_NAME tpc
+                  SOURCES src/tpc-flp-cmv.cxx
+                  PUBLIC_LINK_LIBRARIES O2::TPCWorkflow)
+
+o2_add_executable(cmv-distribute
+                  COMPONENT_NAME tpc
+                  SOURCES src/tpc-distribute-cmv.cxx
+                  PUBLIC_LINK_LIBRARIES O2::TPCWorkflow)
+
+add_subdirectory(readers)