ITS: add scaffolding for tuning of reco-parameters

Detectors/ITSMFT/ITS/macros/CMakeLists.txt

@@ -11,4 +11,5 @@
 
 add_subdirectory(EVE)
 add_subdirectory(test)
+add_subdirectory(tune)
 add_subdirectory(DCS)

Detectors/ITSMFT/ITS/macros/tune/CMakeLists.txt

@@ -0,0 +1,14 @@
+# Copyright 2019-2026 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.
+
+o2_add_test_root_macro(CheckTracklets.C
+                       PUBLIC_LINK_LIBRARIES O2::ITStracking
+                       LABELS its COMPILE_ONLY)

Detectors/ITSMFT/ITS/tracking/CMakeLists.txt

@@ -21,9 +21,11 @@ o2_add_library(ITStracking
                        src/IOUtils.cxx
                        src/Tracker.cxx
                        src/TrackerTraits.cxx
+                       src/TrackerTraitsMC.cxx
                        src/TrackingConfigParam.cxx
                        src/Vertexer.cxx
                        src/VertexerTraits.cxx
+                       src/TuneExt.cxx
                PUBLIC_LINK_LIBRARIES
                        O2::GPUCommon
                        Microsoft.GSL::GSL
@@ -55,6 +57,7 @@ o2_target_root_dictionary(ITStracking
                                   include/ITStracking/Definitions.h
                                   include/ITStracking/FastMultEstConfig.h
                                   include/ITStracking/TrackingConfigParam.h
+                                  include/ITStracking/TuneExt.h
                           LINKDEF src/TrackingLinkDef.h)
 
 if(CUDA_ENABLED OR HIP_ENABLED)

Detectors/ITSMFT/ITS/tracking/include/ITStracking/TrackerTraits.h

@@ -85,11 +85,12 @@ class TrackerTraits
   std::shared_ptr<tbb::task_arena> mTaskArena;
 
  protected:
-  o2::gpu::GPUChainITS* mChain = nullptr;
-  TimeFrame<NLayers>* mTimeFrame;
-  std::vector<TrackingParameters> mTrkParams;
+  void createTrackletMC();
 
-  float mBz{-999.f};
+  o2::gpu::GPUChainITS* mChain{nullptr};
+  TimeFrame<NLayers>* mTimeFrame{nullptr};
+  std::vector<TrackingParameters> mTrkParams;
+  float mBz{constants::UnsetValue};
 };
 
 } // namespace its

Detectors/ITSMFT/ITS/tracking/include/ITStracking/TrackerTraitsMC.h

@@ -0,0 +1,44 @@
+// Copyright 2019-2026 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 TRACKINGITSU_INCLUDE_TRACKERTRAITSMC_H_
+#define TRACKINGITSU_INCLUDE_TRACKERTRAITSMC_H_
+
+#include "ITStracking/TrackerTraits.h"
+
+namespace o2::its
+{
+
+// This class faciliates the tuning of the reconstruction parameters.
+// Two modes are foreseen:
+// 1. Inspect and dump the artefacts the reconstrcution produces
+// 2. Run the same over MC truth
+// Both should faciliate finding sources of in-efficiency (c.f., missing links)
+// and allow to tune overall the imposed parameters in a consistent way.
+template <int NLayers>
+class TrackerTraitsMC : public TrackerTraits<NLayers>
+{
+ public:
+  TrackerTraitsMC() = default;
+  ~TrackerTraitsMC() override = default;
+
+  void computeLayerTracklets(const int iteration, int iVertex) override;
+  void computeLayerCells(const int iteration) override;
+  void findCellsNeighbours(const int iteration) override;
+  void findRoads(const int iteration) override;
+
+  const char* getName() const noexcept override { return "TUNE"; }
+};
+
+} // namespace o2::its
+
+#endif /* TRACKINGITSU_INCLUDE_TRACKERTRAITSMC_H_ */

Detectors/ITSMFT/ITS/tracking/include/ITStracking/TuneExt.h

@@ -0,0 +1,42 @@
+// Copyright 2019-2026 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.
+///
+/// Holder of auxiallary information used for tuning
+///
+
+#include "ITStracking/Constants.h"
+#include "GPUCommonRtypes.h"
+
+namespace o2::its
+{
+struct TrackletMC final {
+  float tgl{constants::UnsetValue}; // tanLambda
+  float phi{constants::UnsetValue}; // phi
+  float rIn{constants::UnsetValue};
+  float zIn{constants::UnsetValue};
+  float phiIn{constants::UnsetValue};
+  float rOut{constants::UnsetValue};
+  float zOut{constants::UnsetValue};
+  float phiOut{constants::UnsetValue};
+  float dr{constants::UnsetValue};
+  float dz{constants::UnsetValue};
+  float dPhi{constants::UnsetValue};
+  bool ok{false}; // truth
+  /// below only metrics valid if ok
+  bool prim{false};                 // primary
+  float dXY{constants::UnsetValue}; // transverse distance to event
+  float dZ{constants::UnsetValue};  // longitudinal distance to event
+  float deltaZEvent{constants::UnsetValue};
+  float tglEvent{constants::UnsetValue};
+  ClassDefNV(TrackletMC, 2);
+};
+
+} // namespace o2::its

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

@@ -223,26 +223,7 @@ void TrackerTraits<NLayers>::computeLayerTracklets(const int iteration, int iVer
 
     /// Create tracklets labels
     if (mTimeFrame->hasMCinformation() && mTrkParams[iteration].CreateArtefactLabels) {
-      tbb::parallel_for(0, static_cast<int>(topology.nTransitions), [&](const int transitionId) {
-        const auto& transition = topology.getTransition(transitionId);
-        for (auto& trk : mTimeFrame->getTracklets()[transitionId]) {
-          MCCompLabel label;
-          int currentId{mTimeFrame->getClusters()[transition.fromLayer][trk.firstClusterIndex].clusterId};
-          int nextId{mTimeFrame->getClusters()[transition.toLayer][trk.secondClusterIndex].clusterId};
-          for (const auto& lab1 : mTimeFrame->getClusterLabels(transition.fromLayer, currentId)) {
-            for (const auto& lab2 : mTimeFrame->getClusterLabels(transition.toLayer, nextId)) {
-              if (lab1 == lab2 && lab1.isValid()) {
-                label = lab1;
-                break;
-              }
-            }
-            if (label.isValid()) {
-              break;
-            }
-          }
-          mTimeFrame->getTrackletsLabel(transitionId).emplace_back(label);
-        }
-      });
+      createTrackletMC();
     }
   });
 }
@@ -907,6 +888,32 @@ void TrackerTraits<NLayers>::markTracks(int iteration)
   }
 }
 
+template <int NLayers>
+void TrackerTraits<NLayers>::createTrackletMC()
+{
+  const auto topology = mTimeFrame->getTrackingTopologyView();
+  tbb::parallel_for(0, static_cast<int>(topology.nTransitions), [&](const int transitionId) {
+    const auto& transition = topology.getTransition(transitionId);
+    for (auto& trk : mTimeFrame->getTracklets()[transitionId]) {
+      MCCompLabel label;
+      int currentId{mTimeFrame->getClusters()[transition.fromLayer][trk.firstClusterIndex].clusterId};
+      int nextId{mTimeFrame->getClusters()[transition.toLayer][trk.secondClusterIndex].clusterId};
+      for (const auto& lab1 : mTimeFrame->getClusterLabels(transition.fromLayer, currentId)) {
+        for (const auto& lab2 : mTimeFrame->getClusterLabels(transition.toLayer, nextId)) {
+          if (lab1 == lab2 && lab1.isValid()) {
+            label = lab1;
+            break;
+          }
+        }
+        if (label.isValid()) {
+          break;
+        }
+      }
+      mTimeFrame->getTrackletsLabel(transitionId).emplace_back(label);
+    }
+  });
+}
+
 template <int NLayers>
 void TrackerTraits<NLayers>::setBz(float bz)
 {

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

@@ -0,0 +1,128 @@
+// Copyright 2019-2026 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 <cmath>
+#include <format>
+#include <limits>
+
+#include "ITStracking/TrackerTraitsMC.h"
+#include "ITStracking/TuneExt.h"
+#include "CommonUtils/TreeStreamRedirector.h"
+#include "CommonConstants/MathConstants.h"
+#include "Steer/MCKinematicsReader.h"
+
+#include "Framework/Logger.h"
+
+namespace o2::its
+{
+
+static o2::utils::TreeStreamRedirector* gDBG{nullptr};
+static o2::steer::MCKinematicsReader* gMCReader{nullptr};
+
+template <int NLayers>
+void TrackerTraitsMC<NLayers>::computeLayerTracklets(const int iteration, int iVertex)
+{
+  if (!gDBG) {
+    gDBG = new o2::utils::TreeStreamRedirector("its_tune.root");
+  }
+  if (!gMCReader) {
+    gMCReader = new o2::steer::MCKinematicsReader("collisioncontext.root");
+  }
+
+  // Create all tracklets we find in this iteration and dump them.
+  const std::string treeName = std::format("trklt_{}", iteration);
+  TrackerTraits<NLayers>::computeLayerTracklets(iteration, iVertex);
+  this->createTrackletMC();
+  const auto topology = this->mTimeFrame->getTrackingTopologyView();
+  for (int transitionId{0}; transitionId < topology.nTransitions; ++transitionId) {
+    const auto& transition = topology.getTransition(transitionId);
+    for (int iTrklt{0}; iTrklt < this->mTimeFrame->getTracklets()[transitionId].size(); ++iTrklt) {
+      const auto& lbl = this->mTimeFrame->getTrackletsLabel(transitionId)[iTrklt];
+      const auto trklt = this->mTimeFrame->getTracklets()[transitionId][iTrklt];
+      const auto& firstCluster = this->mTimeFrame->getClusters()[transition.fromLayer][trklt.firstClusterIndex];
+      const auto& secondCluster = this->mTimeFrame->getClusters()[transition.toLayer][trklt.secondClusterIndex];
+      const float deltaPhi = std::abs(firstCluster.phi - secondCluster.phi);
+      TrackletMC trkltMC{
+        .tgl = trklt.tanLambda,
+        .phi = trklt.phi,
+        .rIn = firstCluster.radius,
+        .zIn = firstCluster.zCoordinate,
+        .phiIn = firstCluster.phi,
+        .rOut = secondCluster.radius,
+        .zOut = secondCluster.zCoordinate,
+        .phiOut = secondCluster.phi,
+        .dr = secondCluster.radius - firstCluster.radius,
+        .dz = secondCluster.zCoordinate - firstCluster.zCoordinate,
+        .dPhi = std::min(deltaPhi, static_cast<float>(o2::constants::math::TwoPI) - deltaPhi),
+        .ok = lbl.isValid(),
+      };
+      float dcaXY = std::numeric_limits<float>::max(), dcaZ = std::numeric_limits<float>::max();
+      if (lbl.isValid()) {
+        const auto& eve = gMCReader->getMCEventHeader(lbl.getSourceID(), lbl.getEventID());
+        const float dx = secondCluster.xCoordinate - firstCluster.xCoordinate;
+        const float dy = secondCluster.yCoordinate - firstCluster.yCoordinate;
+        const float dz = secondCluster.zCoordinate - firstCluster.zCoordinate;
+        trkltMC.tglEvent = (firstCluster.zCoordinate - eve.GetZ()) / firstCluster.radius;
+        trkltMC.deltaZEvent = std::abs((trkltMC.tglEvent * (secondCluster.radius - firstCluster.radius)) + firstCluster.zCoordinate - secondCluster.zCoordinate);
+        const float dxy2 = math_utils::hypot(dx, dy);
+        if (dxy2 > constants::Tolerance) {
+          const float t = ((eve.GetX() - firstCluster.xCoordinate) * dx + (eve.GetY() - firstCluster.yCoordinate) * dy) / dxy2;
+          const float xAtDCA = firstCluster.xCoordinate + t * dx;
+          const float yAtDCA = firstCluster.yCoordinate + t * dy;
+          const float zAtDCA = firstCluster.zCoordinate + t * dz;
+          const float curDCAx = xAtDCA - eve.GetX();
+          const float curDCAy = yAtDCA - eve.GetY();
+          dcaXY = math_utils::hypot(curDCAx, curDCAy);
+          dcaZ = zAtDCA - eve.GetZ();
+          trkltMC.dXY = dcaXY;
+          trkltMC.dZ = dcaZ;
+        }
+        const auto* mcTrk = gMCReader->getTrack(lbl);
+        if (mcTrk) {
+          trkltMC.prim = mcTrk->isPrimary();
+        }
+      }
+      (*gDBG) << treeName.c_str()
+              << "from=" << transition.fromLayer
+              << "to=" << transition.toLayer
+              << "trklt=" << trkltMC
+              << "\n";
+    }
+  }
+}
+
+template <int NLayers>
+void TrackerTraitsMC<NLayers>::computeLayerCells(const int iteration)
+{
+  TrackerTraits<NLayers>::computeLayerCells(iteration);
+}
+
+template <int NLayers>
+void TrackerTraitsMC<NLayers>::findCellsNeighbours(const int iteration)
+{
+  TrackerTraits<NLayers>::findCellsNeighbours(iteration);
+}
+
+template <int NLayers>
+void TrackerTraitsMC<NLayers>::findRoads(const int iteration)
+{
+  TrackerTraits<NLayers>::findRoads(iteration);
+
+  if (this->mTrkParams.size() - 1 == iteration) {
+    gDBG->Close();
+  }
+}
+
+template class TrackerTraitsMC<7>;
+
+} // namespace o2::its

Detectors/ITSMFT/ITS/tracking/src/TrackingLinkDef.h

@@ -18,6 +18,9 @@
 #pragma link C++ class o2::its::Tracklet + ;
 #pragma link C++ class std::vector < o2::its::Tracklet> + ;
 
+#pragma link C++ class o2::its::TrackletMC + ;
+#pragma link C++ class std::vector < o2::its::TrackletMC> + ;
+
 #pragma link C++ class o2::its::Cluster + ;
 #pragma link C++ class std::vector < o2::its::Cluster> + ;
 

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

@@ -0,0 +1,13 @@
+// Copyright 2019-2026 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 "ITStracking/TuneExt.h"
+ClassImp(o2::its::TrackletMC);

Detectors/ITSMFT/ITS/workflow/include/ITSWorkflow/RecoWorkflow.h

@@ -28,7 +28,7 @@ namespace reco_workflow
 
 framework::WorkflowSpec getWorkflow(bool useMC, bool doStag, TrackingMode::Type trmode, const bool overrideBeamPosition = false,
                                     bool upstreamDigits = false, bool upstreamClusters = false, bool clrofOnly = false, bool disableRootOutput = false, bool useGeom = false, int useTrig = 0,
-                                    bool useGPUWF = false, o2::gpu::gpudatatypes::DeviceType dType = o2::gpu::gpudatatypes::DeviceType::CPU);
+                                    bool useGPUWF = false, o2::gpu::gpudatatypes::DeviceType dType = o2::gpu::gpudatatypes::DeviceType::CPU, bool enableTuning = false);
 }
 
 } // namespace its

Detectors/ITSMFT/ITS/workflow/include/ITSWorkflow/TrackerSpec.h

@@ -46,7 +46,8 @@ class TrackerDPL : public framework::Task
              int trgType,
              const TrackingMode::Type trMode = TrackingMode::Unset,
              const bool overrBeamEst = false,
-             o2::gpu::gpudatatypes::DeviceType dType = o2::gpu::gpudatatypes::DeviceType::CPU);
+             o2::gpu::gpudatatypes::DeviceType dType = o2::gpu::gpudatatypes::DeviceType::CPU,
+             bool enableTuning = false);
   ~TrackerDPL() override = default;
   void init(framework::InitContext& ic) final;
   void run(framework::ProcessingContext& pc) final;
@@ -61,10 +62,11 @@ class TrackerDPL : public framework::Task
   std::unique_ptr<o2::gpu::GPUChainITS> mChainITS = nullptr;
   std::shared_ptr<o2::base::GRPGeomRequest> mGGCCDBRequest;
   ITSTrackingInterface mITSTrackingInterface;
+  bool mEnableTuning = false;
   TStopwatch mTimer;
 };
 
-framework::DataProcessorSpec getTrackerSpec(bool useMC, bool doStag, bool useGeom, int useTrig, TrackingMode::Type trMode, const bool overrBeamEst = false, o2::gpu::gpudatatypes::DeviceType dType = o2::gpu::gpudatatypes::DeviceType::CPU);
+framework::DataProcessorSpec getTrackerSpec(bool useMC, bool doStag, bool useGeom, int useTrig, TrackingMode::Type trMode, const bool overrBeamEst = false, o2::gpu::gpudatatypes::DeviceType dType = o2::gpu::gpudatatypes::DeviceType::CPU, bool enableTuning = false);
 
 } // namespace o2::its