feat: Track level improvements (acts-project#2012) -- squash

commit 98355e0
Author: Paul Gessinger <[email protected]>
Date:   Tue Apr 4 15:04:58 2023 +0200

    doxygen

commit a162b2d
Author: Paul Gessinger <[email protected]>
Date:   Mon Apr 3 16:25:25 2023 +0200

    fix wrong function

commit 6021ea2
Author: Paul Gessinger <[email protected]>
Date:   Mon Apr 3 16:13:33 2023 +0200

    unit test, append track state functionality

commit 9a25c0a
Author: Paul Gessinger <[email protected]>
Date:   Mon Apr 3 15:58:43 2023 +0200

    some basic unit testing

commit 83aa3e9
Author: Paul Gessinger <[email protected]>
Date:   Mon Apr 3 14:35:38 2023 +0200

    feat: Fitters calculate track quantities

    Adds a central helper function that calculates number of holes,
    outliers, measurements and shared hits based on the type flags, and
    stores them in the track.

commit 2235f82
Author: Paul Gessinger <[email protected]>
Date:   Mon Apr 3 14:21:25 2023 +0200

    refactor: Changce TrackProxy chi2 method name

commit aa6bc1d
Author: Paul Gessinger <[email protected]>
Date:   Fri Mar 31 14:31:08 2023 +0200

    add ndf and chi2 to track container

Core/include/Acts/EventData/TrackHelpers.hpp

@@ -0,0 +1,53 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2023 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#pragma once
+
+#include "Acts/EventData/MultiTrajectory.hpp"
+#include "Acts/EventData/TrackContainer.hpp"
+
+namespace Acts {
+
+/// Helper function to calculate a number of track level quantities and store
+/// them on the track itself
+/// @tparam track_container_t the track container backend
+/// @tparam track_state_container_t the track state container backend
+/// @tparam holder_t the holder type for the track container backends
+/// @param track A track proxy to operate on
+template <typename track_container_t, typename track_state_container_t,
+          template <typename> class holder_t>
+void calculateTrackQuantities(
+    Acts::TrackProxy<track_container_t, track_state_container_t, holder_t,
+                     false>
+        track) {
+  track.chi2() = 0;
+  track.nDoF() = 0;
+
+  track.nHoles() = 0;
+  track.nMeasurements() = 0;
+  track.nSharedHits() = 0;
+  track.nOutliers() = 0;
+
+  for (const auto& trackState : track.trackStates()) {
+    auto typeFlags = trackState.typeFlags();
+
+    if (typeFlags.test(Acts::TrackStateFlag::MeasurementFlag)) {
+      if (typeFlags.test(Acts::TrackStateFlag::SharedHitFlag)) {
+        track.nSharedHits()++;
+      }
+
+      track.nMeasurements()++;
+      track.chi2() += trackState.chi2();
+      track.nDoF() += trackState.calibratedSize();
+    } else if (typeFlags.test(Acts::TrackStateFlag::OutlierFlag)) {
+      track.nOutliers()++;
+    } else if (typeFlags.test(Acts::TrackStateFlag::HoleFlag)) {
+      track.nHoles()++;
+    }
+  }
+}
+}  // namespace Acts

Core/include/Acts/EventData/TrackProxy.hpp

@@ -11,6 +11,7 @@
 #include "Acts/Definitions/TrackParametrization.hpp"
 #include "Acts/EventData/Charge.hpp"
 #include "Acts/EventData/MultiTrajectory.hpp"
+#include "Acts/EventData/TrackStatePropMask.hpp"
 #include "Acts/Utilities/UnitVectors.hpp"
 
 #include <iterator>
@@ -385,6 +386,19 @@ class TrackProxy {
     return m_container->trackStateRange(m_index);
   }
 
+  /// Append a track state to this track. This will modify the tip index to
+  /// point at the newly created track state, which will be directly after the
+  /// previous track state at tip index.
+  /// @param mask The allocation prop mask for the new track state
+  /// @return The newly added track state
+  template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
+  auto appendTrackState(TrackStatePropMask mask = TrackStatePropMask::All) {
+    auto& tsc = m_container->trackStateContainer();
+    auto ts = tsc.getTrackState(tsc.addTrackState(mask, tipIndex()));
+    tipIndex() = ts.index();
+    return ts;
+  }
+
   /// Return the number of track states associated to this track
   /// @note This is calculated by iterating over the track states which is
   ///       somewhat expensive. Consider caching this value if you need It
@@ -429,6 +443,60 @@ class TrackProxy {
     return component<unsigned int>(hashString("nHoles"));
   }
 
+  /// Return a mutable reference to the number of outliers for the track.
+  /// Mutable version
+  /// @return The number of outliers
+  template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
+  unsigned int& nOutliers() {
+    return component<unsigned int>(hashString("nOutliers"));
+  }
+
+  /// Return the number of outliers for the track. Const version
+  /// @return The number of outliers
+  unsigned int nOutliers() const {
+    return component<unsigned int>(hashString("nOutliers"));
+  }
+
+  /// Return a mutable reference to the number of shared hits for the track.
+  /// Mutable version
+  /// @return The number of shared hits
+  template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
+  unsigned int& nSharedHits() {
+    return component<unsigned int>(hashString("nSharedHits"));
+  }
+
+  /// Return the number of shared hits for the track. Const version
+  /// @return The number of shared hits
+  unsigned int nSharedHits() const {
+    return component<unsigned int>(hashString("nSharedHits"));
+  }
+
+  /// Return a mutable reference to the chi squared
+  /// Mutable version
+  /// @return The chi squared
+  template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
+  float& chi2() {
+    return component<float>(hashString("chi2"));
+  }
+
+  /// Return the chi squared for the track. Const version
+  /// @return The chi squared
+  float chi2() const { return component<float>(hashString("chi2")); }
+
+  /// Return a mutable reference to the number of degrees of freedom for the
+  /// track. Mutable version
+  /// @return The the number of degrees of freedom
+  template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
+  unsigned int& nDoF() {
+    return component<unsigned int>(hashString("ndf"));
+  }
+
+  /// Return the number of degrees of freedom for the track. Const version
+  /// @return The number of degrees of freedom
+  unsigned int nDoF() const {
+    return component<unsigned int>(hashString("ndf"));
+  }
+
   /// Return the index of this track in the track container
   /// @note This is separate from the tip index
   /// @return the track index

Core/include/Acts/EventData/VectorTrackContainer.hpp

@@ -67,6 +67,14 @@ class VectorTrackContainerBase {
         return &instance.m_nMeasurements[itrack];
       case "nHoles"_hash:
         return &instance.m_nHoles[itrack];
+      case "chi2"_hash:
+        return &instance.m_chi2[itrack];
+      case "ndf"_hash:
+        return &instance.m_ndf[itrack];
+      case "nOutliers"_hash:
+        return &instance.m_nOutliers[itrack];
+      case "nSharedHits"_hash:
+        return &instance.m_nSharedHits[itrack];
       default:
         auto it = instance.m_dynamic.find(key);
         if (it == instance.m_dynamic.end()) {
@@ -97,6 +105,14 @@ class VectorTrackContainerBase {
     result = result && m_nMeasurements.size() == size;
     assert(result);
     result = result && m_nHoles.size() == size;
+    assert(result);
+    result = result && m_chi2.size() == size;
+    assert(result);
+    result = result && m_ndf.size() == size;
+    assert(result);
+    result = result && m_nOutliers.size() == size;
+    assert(result);
+    result = result && m_nSharedHits.size() == size;
 
     for (const auto& [key, col] : m_dynamic) {
       (void)key;
@@ -128,6 +144,10 @@ class VectorTrackContainerBase {
 
   std::vector<unsigned int> m_nMeasurements;
   std::vector<unsigned int> m_nHoles;
+  std::vector<float> m_chi2;
+  std::vector<unsigned int> m_ndf;
+  std::vector<unsigned int> m_nOutliers;
+  std::vector<unsigned int> m_nSharedHits;
 
   std::unordered_map<HashedString, std::unique_ptr<detail::DynamicColumnBase>>
       m_dynamic;

Core/include/Acts/TrackFinding/CombinatorialKalmanFilter.hpp

@@ -18,6 +18,7 @@
 #include "Acts/EventData/MultiTrajectory.hpp"
 #include "Acts/EventData/MultiTrajectoryHelpers.hpp"
 #include "Acts/EventData/TrackContainer.hpp"
+#include "Acts/EventData/TrackHelpers.hpp"
 #include "Acts/EventData/TrackParameters.hpp"
 #include "Acts/EventData/TrackStatePropMask.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
@@ -1379,6 +1380,9 @@ class CombinatorialKalmanFilter {
       track.parameters() = parameters.parameters();
       track.covariance() = *parameters.covariance();
       track.setReferenceSurface(parameters.referenceSurface().getSharedPtr());
+
+      calculateTrackQuantities(track);
+
       tracks.push_back(track);
     }
 

Core/include/Acts/TrackFitting/Chi2Fitter.hpp

@@ -18,6 +18,7 @@
 #include "Acts/EventData/MultiTrajectory.hpp"
 #include "Acts/EventData/MultiTrajectoryHelpers.hpp"
 #include "Acts/EventData/SourceLink.hpp"
+#include "Acts/EventData/TrackHelpers.hpp"
 #include "Acts/EventData/TrackParameters.hpp"
 #include "Acts/EventData/VectorMultiTrajectory.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
@@ -791,6 +792,8 @@ class Chi2Fitter {
     track.nMeasurements() = c2r.measurementStates;
     track.nHoles() = c2r.measurementHoles;
 
+    calculateTrackQuantities(track);
+
     if (trackContainer.hasColumn(hashString("chi2"))) {
       track.template component<ActsScalar, hashString("chi2")>() =
           c2r.chisquare;

Core/include/Acts/TrackFitting/GaussianSumFitter.hpp

@@ -8,6 +8,7 @@
 
 #pragma once
 
+#include "Acts/EventData/TrackHelpers.hpp"
 #include "Acts/EventData/VectorMultiTrajectory.hpp"
 #include "Acts/Propagator/EigenStepper.hpp"
 #include "Acts/Propagator/MultiStepperAborters.hpp"
@@ -442,6 +443,8 @@ struct GaussianSumFitter {
       track.setReferenceSurface(params.referenceSurface().getSharedPtr());
     }
 
+    calculateTrackQuantities(track);
+
     track.nMeasurements() = measurementStatesFinal;
     track.nHoles() = fwdGsfResult.measurementHoles;
 

Core/include/Acts/TrackFitting/KalmanFitter.hpp

@@ -17,6 +17,7 @@
 #include "Acts/EventData/MultiTrajectory.hpp"
 #include "Acts/EventData/MultiTrajectoryHelpers.hpp"
 #include "Acts/EventData/SourceLink.hpp"
+#include "Acts/EventData/TrackHelpers.hpp"
 #include "Acts/EventData/TrackParameters.hpp"
 #include "Acts/EventData/VectorMultiTrajectory.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
@@ -1126,6 +1127,9 @@ class KalmanFitter {
     }
     track.nMeasurements() = kalmanResult.measurementStates;
     track.nHoles() = kalmanResult.measurementHoles;
+
+    calculateTrackQuantities(track);
+
     if (trackContainer.hasColumn(hashString("smoothed"))) {
       track.template component<bool, hashString("smoothed")>() =
           kalmanResult.smoothed;
@@ -1259,6 +1263,9 @@ class KalmanFitter {
     }
     track.nMeasurements() = kalmanResult.measurementStates;
     track.nHoles() = kalmanResult.measurementHoles;
+
+    calculateTrackQuantities(track);
+
     if (trackContainer.hasColumn(hashString("smoothed"))) {
       track.template component<bool, hashString("smoothed")>() =
           kalmanResult.smoothed;

Core/src/EventData/VectorTrackContainer.cpp

@@ -19,7 +19,11 @@ VectorTrackContainerBase::VectorTrackContainerBase(
       m_cov{other.m_cov},
       m_referenceSurfaces{other.m_referenceSurfaces},
       m_nMeasurements{other.m_nMeasurements},
-      m_nHoles{other.m_nHoles} {
+      m_nHoles{other.m_nHoles},
+      m_chi2{other.m_chi2},
+      m_ndf{other.m_ndf},
+      m_nOutliers{other.m_nOutliers},
+      m_nSharedHits{other.m_nSharedHits} {
   for (const auto& [key, value] : other.m_dynamic) {
     m_dynamic.insert({key, value->clone()});
   }
@@ -39,6 +43,12 @@ VectorTrackContainer::IndexType VectorTrackContainer::addTrack_impl() {
   m_nMeasurements.emplace_back();
   m_nHoles.emplace_back();
 
+  m_chi2.emplace_back();
+  m_ndf.emplace_back();
+
+  m_nOutliers.emplace_back();
+  m_nSharedHits.emplace_back();
+
   // dynamic columns
   for (auto& [key, vec] : m_dynamic) {
     vec->add();
@@ -66,6 +76,12 @@ void VectorTrackContainer::removeTrack_impl(IndexType itrack) {
   erase(m_nMeasurements);
   erase(m_nHoles);
 
+  erase(m_chi2);
+  erase(m_ndf);
+
+  erase(m_nOutliers);
+  erase(m_nSharedHits);
+
   for (auto& [key, vec] : m_dynamic) {
     vec->erase(itrack);
   }
@@ -103,6 +119,12 @@ void VectorTrackContainer::reserve(IndexType size) {
   m_nMeasurements.reserve(size);
   m_nHoles.reserve(size);
 
+  m_chi2.reserve(size);
+  m_ndf.reserve(size);
+
+  m_nOutliers.reserve(size);
+  m_nSharedHits.reserve(size);
+
   for (auto& [key, vec] : m_dynamic) {
     vec->reserve(size);
   }