Encode the ITS layer into the per-layer ITS track cluster references

With the per-layer (staggered readout) ITS clusters input the cluster index kept
by TrackITS is local to its layer, so the layer must be encoded into the stored
reference for the consumers to be able to find the cluster. MatchTPCITS already
decoded the ITS/TRACKCLSID entries as such composed IDs, but the tracker pushed
the bare per-layer index, which was correct only for the layer 0.

- ITSTrackingInterface::run composes the stored reference as
  (layer << ClusLayerShift) + index_in_layer; with the monolithic clusters input
  the layer slot is 0 and the composed ID stays equal to the flat index, so the
  non-staggered output is unchanged
- the ID composition/decomposition and the max number of separately provided
  ITS/MFT cluster layers move from MatchTPCITS.h to the new lightweight
  DataFormatsITSMFT/ClusterID.h, so that both the producer and the (many)
  consumers can use them without pulling in GlobalTracking; RecoContainer.h
  includes it and keeps MaxITSLayers/MaxMFTLayers as aliases
- the layer field is shifted by 27 rather than 28 bits, so that it can
  accommodate the MFT layers too: the bit 31 is unusable, since the negative
  values of the composed ID are reserved for the "no cluster" flags
- the unused TrackITSExt::setClusterIndex, carrying its own hardcoded copy of
  the composition (and writing to the packed slot while getClusterIndex reads
  the layer slot), is removed

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: shahor02

DataFormats/Detectors/GlobalTracking/include/DataFormatsGlobalTracking/RecoContainer.h

@@ -27,6 +27,7 @@
 #include "SimulationDataFormat/MCTruthContainer.h"
 #include "SimulationDataFormat/ConstMCTruthContainer.h"
 #include "DataFormatsCTP/LumiInfo.h"
+#include "DataFormatsITSMFT/ClusterID.h"
 #include <gsl/span>
 #include <memory>
 
@@ -188,8 +189,8 @@ namespace globaltracking
 {
 
 // max number of layers for which the ITS/MFT clusters, ROF records and patterns can be provided separately
-constexpr int MaxITSLayers = 7;
-constexpr int MaxMFTLayers = 10;
+constexpr int MaxITSLayers = o2::itsmft::MaxITSClusLayers;
+constexpr int MaxMFTLayers = o2::itsmft::MaxMFTClusLayers;
 
 // helper class to request DPL input data from the processor specs definition
 struct DataRequest {

DataFormats/Detectors/ITSMFT/ITS/include/DataFormatsITS/TrackITS.h

@@ -221,13 +221,6 @@ class TrackITSExt : public TrackITS
 
   GPUhdDefault() TrackITSExt(const TrackITSExt& t) = default;
 
-  void setClusterIndex(int l, int i)
-  {
-    int ncl = getNumberOfClusters();
-    mIndex[ncl++] = (l << 28) + i;
-    getClusterRefs().setEntries(ncl);
-  }
-
   GPUhdi() int getClusterIndex(int lr) const { return mIndex[lr]; }
 
   GPUh() int getFirstLayerClusterIndex() const

DataFormats/Detectors/ITSMFT/common/include/DataFormatsITSMFT/ClusterID.h

@@ -0,0 +1,43 @@
+// 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 ClusterID.h
+/// \brief Composition/decomposition of the ITS/MFT cluster IDs referring to per-layer cluster arrays
+/// \author ruben.shahoyan@cern.ch
+
+#ifndef ALICEO2_ITSMFT_CLUSTERID_H
+#define ALICEO2_ITSMFT_CLUSTERID_H
+
+namespace o2::itsmft
+{
+
+// max number of layers for which the ITS/MFT clusters, ROF records and patterns can be provided separately
+constexpr int MaxITSClusLayers = 7;
+constexpr int MaxMFTClusLayers = 10;
+constexpr int MaxClusLayers = MaxITSClusLayers > MaxMFTClusLayers ? MaxITSClusLayers : MaxMFTClusLayers;
+
+///< With the per-layer (staggered readout) ITS/MFT clusters input the clusters are referred to by the
+///< composed ID (layer << ClusLayerShift) + index_in_layer. With a single (monolithic) clusters input
+///< all clusters sit in the layer slot 0, hence the composed ID coincides with the flat cluster index
+///< and the same decoding works for both cases.
+///< Note: the bit 31 is excluded from the layer field, since the negative values of the composed ID
+///< are reserved for the "no cluster" flags.
+constexpr int ClusLayerShift = 27;
+constexpr int ClusIndexMask = (0x1 << ClusLayerShift) - 1;
+static_assert((1 << (31 - ClusLayerShift)) >= MaxClusLayers, "ClusLayerShift leaves no room for the layer ID");
+
+constexpr int composeClusID(int lr, int idx) { return (lr << ClusLayerShift) + idx; }
+constexpr int clusID2Layer(int id) { return id >> ClusLayerShift; }
+constexpr int clusID2Index(int id) { return id & ClusIndexMask; }
+
+} // namespace o2::itsmft
+
+#endif

Detectors/GlobalTracking/include/GlobalTracking/MatchTPCITS.h

@@ -55,6 +55,7 @@
 #include "GlobalTracking/MatchTPCITSParams.h"
 #include "DataFormatsITSMFT/TopologyDictionary.h"
 #include "DataFormatsITSMFT/TrkClusRef.h"
+#include "DataFormatsITSMFT/ClusterID.h"
 #include "ITSMFTReconstruction/ChipMappingITS.h"
 #include "TPCFastTransformPOD.h"
 #if !defined(__CINT__) && !defined(__MAKECINT__) && !defined(__ROOTCLING__) && !defined(__CLING__)
@@ -109,14 +110,6 @@ constexpr int MinusOne = -1;
 constexpr int MinusTen = -10;
 constexpr int Validated = -2;
 
-///< ITS clusters are referred to by the composed index (layer << ITSClusLayerShift) + index_in_layer.
-///< With a single ITS clusters input (not per layer) all clusters are in the layer slot 0.
-constexpr int ITSClusLayerShift = 28;
-constexpr int ITSClusIndexMask = (0x1 << ITSClusLayerShift) - 1;
-constexpr int composeITSClusID(int lr, int idx) { return (lr << ITSClusLayerShift) + idx; }
-constexpr int ITSClusID2Layer(int id) { return id >> ITSClusLayerShift; }
-constexpr int ITSClusID2Index(int id) { return id & ITSClusIndexMask; }
-
 ///< per-layer status of ITS clusters (e.g. for the AfterBurner)
 using ITSClusStatus = std::array<std::vector<int>, o2::its::RecoGeomHelper::getNLayers()>;
 
@@ -282,7 +275,7 @@ struct TPCABSeed {
     // check if some clusters used by the link or its parents are forbidden (already used by validatet track)
     while (linkID > MinusOne) {
       const auto& link = getLink(linkID);
-      if (link.clID > MinusOne && clStatus[ITSClusID2Layer(link.clID)][ITSClusID2Index(link.clID)] != MinusOne) {
+      if (link.clID > MinusOne && clStatus[o2::itsmft::clusID2Layer(link.clID)][o2::itsmft::clusID2Index(link.clID)] != MinusOne) {
         return true;
       }
       linkID = link.parentID;
@@ -295,7 +288,7 @@ struct TPCABSeed {
     while (linkID > MinusOne) {
       const auto& link = getLink(linkID);
       if (link.clID > MinusOne) {
-        clStatus[ITSClusID2Layer(link.clID)][ITSClusID2Index(link.clID)] = MinusTen;
+        clStatus[o2::itsmft::clusID2Layer(link.clID)][o2::itsmft::clusID2Index(link.clID)] = MinusTen;
       }
       linkID = link.parentID;
     }
@@ -320,7 +313,7 @@ struct InteractionCandidate : public o2::InteractionRecord {
 struct ABClusterInfo {
   ///< compact info on an ITS cluster usable by the AfterBurner
   float y = 0.f, z = 0.f; ///< Y, Z of the cluster in the tracking frame of its sensor
-  int id = MinusOne;      ///< composed cluster ID, see composeITSClusID
+  int id = MinusOne;      ///< composed cluster ID, see o2::itsmft::composeClusID
   int chip = -1;          ///< global chip (sensor) ID
 };
 
@@ -631,7 +624,7 @@ class MatchTPCITS
 
   const ITSCluster& getITSCluster(int composedID) const
   {
-    return mITSClustersArray[ITSClusID2Layer(composedID)][ITSClusID2Index(composedID)];
+    return mITSClustersArray[o2::itsmft::clusID2Layer(composedID)][o2::itsmft::clusID2Index(composedID)];
   }
 
   // ========================= AFTERBURNER =========================

Detectors/GlobalTracking/src/MatchTPCITS.cxx

@@ -2147,7 +2147,7 @@ void MatchTPCITS::prepareABClusters()
       int chip = cls.getSensorID();
       if ((perLayer || (chip >= chipMin && chip < chipMax)) && status[icl] != MinusTen) {
         assert(chip >= chipMin && chip < chipMax); // clusters of a per-layer slot must belong to its layer
-        dst[nCl++] = {cls.getY(), cls.getZ(), composeITSClusID(slot, icl), chip};
+        dst[nCl++] = {cls.getY(), cls.getZ(), o2::itsmft::composeClusID(slot, icl), chip};
       }
     }
     assert(nCl == blk.nCl);
@@ -2365,7 +2365,7 @@ void MatchTPCITS::refitABWinners(pmr::vector<o2::dataformats::TrackTPCITS>& matc
 
   std::map<o2::MCCompLabel, int> labelOccurence;
   auto accountClusterLabel = [&labelOccurence, this](int clID) {
-    auto labels = mITSClsLabels[ITSClusID2Layer(clID)]->getLabels(ITSClusID2Index(clID));
+    auto labels = mITSClsLabels[o2::itsmft::clusID2Layer(clID)]->getLabels(o2::itsmft::clusID2Index(clID));
     for (auto lab : labels) { // check all labels of the cluster
       if (lab.isSet()) {
         labelOccurence[lab]++;
@@ -2384,7 +2384,7 @@ void MatchTPCITS::refitABWinners(pmr::vector<o2::dataformats::TrackTPCITS>& matc
         ABTrackletClusterIDs.push_back(winL.clID);
         ncl++;
         clref.pattern |= 0x1 << winL.layerID;
-        clref.setClusterSize(winL.layerID, mITSClusterSizes[ITSClusID2Layer(winL.clID)][ITSClusID2Index(winL.clID)]);
+        clref.setClusterSize(winL.layerID, mITSClusterSizes[o2::itsmft::clusID2Layer(winL.clID)][o2::itsmft::clusID2Index(winL.clID)]);
         if (mMCTruthON) {
           accountClusterLabel(winL.clID);
         }
@@ -2907,10 +2907,10 @@ void MatchTPCITS::flagUsedITSClusters(const o2::its::TrackITS& track)
   // flag clusters used by this track
   int clEntry = track.getFirstClusterEntry();
   for (int icl = track.getNumberOfClusters(); icl--;) {
-    const int clID = mITSTrackClusIdx[clEntry++]; // composed ID: (layer << ITSClusLayerShift) + index_in_layer
-    auto& clStatus = mABClusterStatus[ITSClusID2Layer(clID)];
+    const int clID = mITSTrackClusIdx[clEntry++]; // composed ID: (layer << o2::itsmft::ClusLayerShift) + index_in_layer
+    auto& clStatus = mABClusterStatus[o2::itsmft::clusID2Layer(clID)];
     if (!clStatus.empty()) { // layers not used by the AfterBurner are not booked
-      clStatus[ITSClusID2Index(clID)] = MinusTen;
+      clStatus[o2::itsmft::clusID2Index(clID)] = MinusTen;
     }
   }
 }

Detectors/ITSMFT/ITS/tracking/src/TrackingInterface.cxx

@@ -26,6 +26,7 @@
 #include "ITSMFTTracking/ITSTrackingConfigParam.h"
 #include "ITStracking/TrackingInterface.h"
 
+#include "DataFormatsITSMFT/ClusterID.h"
 #include "DataFormatsITSMFT/ROFRecord.h"
 #include "DataFormatsITSMFT/PhysTrigger.h"
 #include "DataFormatsTRD/TriggerRecord.h"
@@ -333,7 +334,9 @@ void ITSTrackingInterface::run(framework::ProcessingContext& pc)
       auto clid = trc.getClusterIndex(ic);
       if (clid >= 0) {
         trc.setClusterSize(ic, mTimeFrame->getClusterSize((mDoStaggering) ? ic : 0, clid));
-        allClusIdx.push_back(clid);
+        // with the per-layer clusters input the index is local to the layer, hence the layer must be
+        // encoded into the stored reference; with the monolithic input the composed ID is just the index
+        allClusIdx.push_back(o2::itsmft::composeClusID((mDoStaggering) ? ic : 0, clid));
         nclf++;
       }
     }