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
@@ -153,6 +155,10 @@ o2_add_test_root_macro(macro/prepareITFiles.C
                        COMPILE_ONLY
                        PUBLIC_LINK_LIBRARIES O2::TPCCalibration
                        LABELS tpc)
+o2_add_test_root_macro(macro/drawCMV.C
+                       COMPILE_ONLY
+                       PUBLIC_LINK_LIBRARIES O2::TPCCalibration O2::TPCBase
+                       LABELS tpc)
 
 o2_add_test(IDCFourierTransform
             COMPONENT_NAME calibration

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

@@ -0,0 +1,141 @@
+// 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 <string>
+#include <memory>
+#include <vector>
+#include <cstdint>
+
+#include "TTree.h"
+#include "TPCBase/CRU.h"
+#include "DataFormatsTPC/CMV.h"
+
+namespace o2::tpc
+{
+
+struct CMVPerTF;           // forward declaration
+struct CMVPerTFCompressed; // forward declaration
+
+/// Bitmask flags describing which encoding stages are applied in CMVPerTFCompressed
+struct CMVEncoding {
+  static constexpr uint8_t kNone = 0x00;    ///< No compression — raw uint16 values stored flat
+  static constexpr uint8_t kSparse = 0x01;  ///< Non-zero positions stored sparsely (varint-encoded deltas)
+  static constexpr uint8_t kDelta = 0x02;   ///< Delta coding between consecutive values (dense only)
+  static constexpr uint8_t kZigzag = 0x04;  ///< Zigzag encoding of deltas or signed values
+  static constexpr uint8_t kVarint = 0x08;  ///< Varint compression of the value stream
+  static constexpr uint8_t kHuffman = 0x10; ///< Canonical Huffman compression of the value stream
+};
+
+/// Single compressed representation for one TF across all CRUs, stored in a TTree
+/// mFlags is a bitmask of CMVEncoding values that fully describes the encoding pipeline
+/// mData holds the encoded payload whose binary layout depends on mFlags:
+///
+///   Dense path (!kSparse):
+///     kZigzag absent → N × uint16_t LE  (raw values, CRU-major order)
+///     kZigzag + kVarint  → N × varint(zigzag(delta(signed(raw))))
+///     kZigzag + kHuffman → [Huffman table] + [bitstream] of zigzag(delta(signed(raw)))
+///
+///   Sparse path (kSparse):
+///     4 bytes LE uint32_t : posStreamSize
+///     posStream: for each CRU: varint(N), N × varint(tb_delta)
+///     valStream (one entry per non-zero):
+///       default          → uint16_t LE raw value
+///       kZigzag + kVarint  → varint(zigzag(signed(raw)))
+///       kZigzag + kHuffman → [Huffman table] + [bitstream] of zigzag(signed(raw))
+struct CMVPerTFCompressed {
+  uint32_t firstOrbit{0}; ///< First orbit of this TF
+  uint16_t firstBC{0};    ///< First bunch crossing of this TF
+  uint8_t mFlags{0};      ///< Bitmask of CMVEncoding values
+
+  std::vector<uint8_t> mData; ///< Encoded payload
+
+  /// Restore a CMVPerTF from this compressed object into *cmv (must not be null)
+  void decompress(CMVPerTF* cmv) const;
+
+  /// Serialise into a TTree; each Fill() call appends one entry (one TF)
+  std::unique_ptr<TTree> toTTree() const;
+
+ private:
+  /// Decode the sparse position stream; advances ptr past the position block
+  /// Returns (cru, timeBin) pairs for every non-zero entry, in CRU-major order
+  static std::vector<std::pair<int, uint32_t>> decodeSparsePositions(const uint8_t*& ptr, const uint8_t* end);
+
+  /// Decode the value stream into raw uint32_t symbols
+  /// Dispatches to Huffman, varint, or raw uint16 based on flags
+  static std::vector<uint32_t> decodeValueStream(const uint8_t*& ptr, const uint8_t* end, uint32_t N, uint8_t flags);
+
+  /// Apply inverse zigzag and scatter decoded values into the sparse positions of *cmv
+  static void decodeSparseValues(const std::vector<uint32_t>& symbols,
+                                 const std::vector<std::pair<int, uint32_t>>& positions,
+                                 uint8_t flags, CMVPerTF* cmv);
+
+  /// Apply inverse zigzag and inverse delta, then fill the full dense CMV array in *cmv
+  static void decodeDenseValues(const std::vector<uint32_t>& symbols, uint8_t flags, CMVPerTF* cmv);
+
+ public:
+  ClassDefNV(CMVPerTFCompressed, 1)
+};
+
+/// CMV data for one TF across all CRUs
+/// Raw 16-bit CMV values are stored in a flat C array indexed as [cru * NTimeBinsPerTF + timeBin]
+struct CMVPerTF {
+  uint32_t firstOrbit{0}; ///< First orbit of this TF, from heartbeatOrbit of the first CMV packet
+  uint16_t firstBC{0};    ///< First bunch crossing of this TF, from heartbeatBC of the first CMV packet
+
+  // Raw 16-bit CMV values, flat array indexed as [cru * NTimeBinsPerTF + timeBin]
+  uint16_t mDataPerTF[CRU::MaxCRU * cmv::NTimeBinsPerTF]{};
+
+  /// Return the raw 16-bit CMV value for a given CRU and timebin within this TF
+  uint16_t getCMV(const int cru, const int timeBin) const;
+
+  /// Return the float CMV value for a given CRU and timebin within this TF
+  float getCMVFloat(const int cru, const int timeBin) const;
+
+  /// Zero out raw CMV values whose float magnitude is below threshold
+  void zeroSmallValues(float threshold = 1.0f);
+
+  /// Round values to the nearest integer ADC for all values whose rounded magnitude is <= threshold
+  void roundToIntegers(uint16_t threshold);
+
+  /// Quantise |v| with a Gaussian-CDF recovery profile:
+  /// Coarse decimal-style precision below and around mean, then a smooth return to the full native I8F7 precision as the magnitude increases with width sigma
+  void trimGaussianPrecision(float mean, float sigma);
+
+  /// Compress this object into a CMVPerTFCompressed using the encoding pipeline described by flags
+  /// Quantisation (trimGaussianPrecision / roundToIntegers / zeroSmallValues) should be applied to this object before calling compress(); it is not part of the flags pipeline
+  CMVPerTFCompressed compress(uint8_t flags) const;
+
+  /// Serialise into a TTree; each Fill() call appends one entry (one TF)
+  std::unique_ptr<TTree> toTTree() const;
+
+  /// Write the TTree to a ROOT file
+  static void writeToFile(const std::string& filename, const std::unique_ptr<TTree>& tree);
+
+ private:
+  static int32_t cmvToSigned(uint16_t raw);                                                              ///< Sign-magnitude uint16_t → signed integer
+  static uint16_t quantizeBelowThreshold(uint16_t raw, float quantizationMean, float quantizationSigma); ///< Quantise sub-threshold values with a Gaussian-shaped recovery to full precision
+  static uint32_t zigzagEncode(int32_t value);                                                           ///< Zigzag encode
+  static void encodeVarintInto(uint32_t value, std::vector<uint8_t>& out);                               ///< Varint encode
+
+ public:
+  ClassDefNV(CMVPerTF, 1)
+};
+
+} // namespace o2::tpc
+
+#endif // ALICEO2_TPC_CMVCONTAINER_H_