feat: Allow user to supply root branch to Core CKF (acts-project#3534)

Adding an overload to the Core CKF which allows the user to supply a root branch. This is useful if the finding has multiple stages, i.e. forward and backward, and the tip state quantities like `nMeasurements` and `nHoles` should persist so the branch stopper can observe them.

blocked by
- acts-project#3586
- acts-project#3587

Core/include/Acts/TrackFinding/CombinatorialKalmanFilter.hpp

@@ -1235,7 +1235,9 @@ class CombinatorialKalmanFilter {
   /// @param initialParameters The initial track parameters
   /// @param tfOptions CombinatorialKalmanFilterOptions steering the track
   ///                  finding
-  /// @param trackContainer Input track container to use
+  /// @param trackContainer Track container in which to store the results
+  /// @param rootBranch The track to be used as the root branch
+  ///
   /// @note The input measurements are given in the form of @c SourceLinks.
   ///       It's @c calibrator_t's job to turn them into calibrated measurements
   ///       used in the track finding.
@@ -1247,7 +1249,8 @@ class CombinatorialKalmanFilter {
   auto findTracks(const start_parameters_t& initialParameters,
                   const CombinatorialKalmanFilterOptions<
                       source_link_iterator_t, track_container_t>& tfOptions,
-                  track_container_t& trackContainer) const
+                  track_container_t& trackContainer,
+                  typename track_container_t::TrackProxy rootBranch) const
       -> Result<std::vector<
           typename std::decay_t<decltype(trackContainer)>::TrackProxy>> {
     using SourceLinkAccessor =
@@ -1310,7 +1313,6 @@ class CombinatorialKalmanFilter {
     r.tracks = &trackContainer;
     r.trackStates = &trackContainer.trackStateContainer();
 
-    auto rootBranch = trackContainer.makeTrack();
     r.activeBranches.push_back(rootBranch);
 
     auto propagationResult = m_propagator.propagate(propState);
@@ -1349,6 +1351,34 @@ class CombinatorialKalmanFilter {
 
     return std::move(combKalmanResult.collectedTracks);
   }
+
+  /// Combinatorial Kalman Filter implementation, calls the Kalman filter
+  ///
+  /// @tparam source_link_iterator_t Type of the source link iterator
+  /// @tparam start_parameters_t Type of the initial parameters
+  /// @tparam parameters_t Type of parameters used for local parameters
+  ///
+  /// @param initialParameters The initial track parameters
+  /// @param tfOptions CombinatorialKalmanFilterOptions steering the track
+  ///                  finding
+  /// @param trackContainer Track container in which to store the results
+  /// @note The input measurements are given in the form of @c SourceLinks.
+  ///       It's @c calibrator_t's job to turn them into calibrated measurements
+  ///       used in the track finding.
+  ///
+  /// @return a container of track finding result for all the initial track
+  /// parameters
+  template <typename source_link_iterator_t, typename start_parameters_t,
+            typename parameters_t = BoundTrackParameters>
+  auto findTracks(const start_parameters_t& initialParameters,
+                  const CombinatorialKalmanFilterOptions<
+                      source_link_iterator_t, track_container_t>& tfOptions,
+                  track_container_t& trackContainer) const
+      -> Result<std::vector<
+          typename std::decay_t<decltype(trackContainer)>::TrackProxy>> {
+    auto rootBranch = trackContainer.makeTrack();
+    return findTracks(initialParameters, tfOptions, trackContainer, rootBranch);
+  }
 };
 
 }  // namespace Acts

Examples/Algorithms/TrackFinding/include/ActsExamples/TrackFinding/TrackFindingAlgorithm.hpp

@@ -69,7 +69,7 @@ class TrackFindingAlgorithm final : public IAlgorithm {
     virtual ~TrackFinderFunction() = default;
     virtual TrackFinderResult operator()(const TrackParameters&,
                                          const TrackFinderOptions&,
-                                         TrackContainer&) const = 0;
+                                         TrackContainer&, TrackProxy) const = 0;
   };
 
   /// Create the track finder function implementation.

Examples/Algorithms/TrackFinding/src/TrackFindingAlgorithm.cpp

@@ -470,8 +470,9 @@ ProcessCode TrackFindingAlgorithm::execute(const AlgorithmContext& ctx) const {
     const Acts::BoundTrackParameters& firstInitialParameters =
         initialParameters.at(iSeed);
 
-    auto firstResult =
-        (*m_cfg.findTracks)(firstInitialParameters, firstOptions, tracksTemp);
+    auto firstRootBranch = tracksTemp.makeTrack();
+    auto firstResult = (*m_cfg.findTracks)(firstInitialParameters, firstOptions,
+                                           tracksTemp, firstRootBranch);
     nSeed++;
 
     if (!firstResult.ok()) {
@@ -531,8 +532,11 @@ ProcessCode TrackFindingAlgorithm::execute(const AlgorithmContext& ctx) const {
           Acts::BoundTrackParameters secondInitialParameters =
               trackCandidate.createParametersFromState(*firstMeasurement);
 
-          auto secondResult = (*m_cfg.findTracks)(secondInitialParameters,
-                                                  secondOptions, tracksTemp);
+          auto secondRootBranch = tracksTemp.makeTrack();
+          secondRootBranch.copyFrom(trackCandidate, false);
+          auto secondResult =
+              (*m_cfg.findTracks)(secondInitialParameters, secondOptions,
+                                  tracksTemp, secondRootBranch);
 
           if (!secondResult.ok()) {
             ACTS_WARNING("Second track finding failed for seed "

Examples/Algorithms/TrackFinding/src/TrackFindingAlgorithmFunction.cpp

@@ -49,8 +49,10 @@ struct TrackFinderFunctionImpl
   ActsExamples::TrackFindingAlgorithm::TrackFinderResult operator()(
       const ActsExamples::TrackParameters& initialParameters,
       const ActsExamples::TrackFindingAlgorithm::TrackFinderOptions& options,
-      ActsExamples::TrackContainer& tracks) const override {
-    return trackFinder.findTracks(initialParameters, options, tracks);
+      ActsExamples::TrackContainer& tracks,
+      ActsExamples::TrackProxy rootBranch) const override {
+    return trackFinder.findTracks(initialParameters, options, tracks,
+                                  rootBranch);
   };
 };
 

Examples/Algorithms/TrackFindingExaTrkX/src/TrackFindingFromPrototrackAlgorithm.cpp

@@ -142,7 +142,9 @@ ActsExamples::ProcessCode TrackFindingFromPrototrackAlgorithm::execute(
       }
     }
 
-    auto result = (*m_cfg.findTracks)(initialParameters.at(i), options, tracks);
+    auto rootBranch = tracks.makeTrack();
+    auto result = (*m_cfg.findTracks)(initialParameters.at(i), options, tracks,
+                                      rootBranch);
     nSeed++;
 
     if (!result.ok()) {