feat: TruthVertexSeeder for Examples (#3364)

A truth vertex seeding implementation for the Examples framework. This can be used for studying vertexing performance in case of optimal vertex seeding. This `TruthVertexSeeder` will return the truth vertex locations in the same order as they were generated. A potential future enhancement could be to reorder them or drop some of them depending on location and track content.

blocked by
- #3368
- #3421
- #3423

Core/include/Acts/Vertexing/AdaptiveMultiVertexFinder.hpp

@@ -1,6 +1,6 @@
 // This file is part of the Acts project.
 //
-// Copyright (C) 2020 CERN for the benefit of the Acts project
+// Copyright (C) 2020-2024 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
@@ -25,6 +25,7 @@
 #include <type_traits>
 
 namespace Acts {
+
 /// @brief Implements an iterative vertex finder
 class AdaptiveMultiVertexFinder final : public IVertexFinder {
   using VertexFitter = AdaptiveMultiVertexFitter;
@@ -147,13 +148,20 @@ class AdaptiveMultiVertexFinder final : public IVertexFinder {
     /// to true, and time seeding should be enabled.
     bool useTime = false;
 
+    /// If set to true, the vertex finder will not break the finding loop.
+    /// Some seeders are not able to cope with this therefore this is
+    /// disabled by default.
+    bool doNotBreakWhileSeeding = false;
+
     /// Function to extract parameters from InputTrack
     InputTrack::Extractor extractParameters;
   };
 
   /// State struct for fulfilling interface
   struct State {
     std::reference_wrapper<const MagneticFieldContext> magContext;
+
+    IVertexFinder::State seedFinderState;
   };
 
   /// @brief Constructor for user-defined InputTrack_t type !=
@@ -197,7 +205,8 @@ class AdaptiveMultiVertexFinder final : public IVertexFinder {
 
   IVertexFinder::State makeState(
       const Acts::MagneticFieldContext& mctx) const override {
-    return IVertexFinder::State{State{mctx}};
+    return IVertexFinder::State{
+        State{mctx, IVertexFinder::State{m_cfg.seedFinder->makeState(mctx)}}};
   }
 
   void setTracksToRemove(

Core/include/Acts/Vertexing/AdaptiveMultiVertexFitter.hpp

@@ -41,6 +41,7 @@ class AdaptiveMultiVertexFitter {
           const Acts::MagneticFieldContext& magContext)
         : ipState{field.makeCache(magContext)},
           fieldCache(field.makeCache(magContext)) {}
+
     // Vertex collection to be fitted
     std::vector<Vertex*> vertexCollection;
 

Core/src/Vertexing/AdaptiveMultiVertexFinder.cpp

@@ -1,6 +1,6 @@
 // This file is part of the Acts project.
 //
-// Copyright (C) 2020-2023 CERN for the benefit of the Acts project
+// Copyright (C) 2020-2024 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
@@ -9,11 +9,12 @@
 #include "Acts/Vertexing/AdaptiveMultiVertexFinder.hpp"
 
 #include "Acts/Utilities/AlgebraHelpers.hpp"
+#include "Acts/Vertexing/IVertexFinder.hpp"
 #include "Acts/Vertexing/VertexingError.hpp"
 
 namespace Acts {
 
-Acts::Result<std::vector<Acts::Vertex>> AdaptiveMultiVertexFinder::find(
+Result<std::vector<Vertex>> AdaptiveMultiVertexFinder::find(
     const std::vector<InputTrack>& allTracks,
     const VertexingOptions& vertexingOptions,
     IVertexFinder::State& anyState) const {
@@ -23,19 +24,13 @@ Acts::Result<std::vector<Acts::Vertex>> AdaptiveMultiVertexFinder::find(
   }
 
   State& state = anyState.template as<State>();
-
-  // Original tracks
-  const std::vector<InputTrack>& origTracks = allTracks;
-
-  // Seed tracks
-  std::vector<InputTrack> seedTracks = allTracks;
-
+  IVertexFinder::State& seedFinderState = state.seedFinderState;
   VertexFitterState fitterState(*m_cfg.bField,
                                 vertexingOptions.magFieldContext);
-  auto seedFinderState = m_cfg.seedFinder->makeState(state.magContext);
 
+  const std::vector<InputTrack>& origTracks = allTracks;
+  std::vector<InputTrack> seedTracks = allTracks;
   std::vector<std::unique_ptr<Vertex>> allVertices;
-
   std::vector<Vertex*> allVerticesPtr;
 
   int iteration = 0;
@@ -91,7 +86,11 @@ Acts::Result<std::vector<Acts::Vertex>> AdaptiveMultiVertexFinder::find(
           "Could not prepare for fit. Discarding the vertex candindate.");
       allVertices.pop_back();
       allVerticesPtr.pop_back();
-      break;
+      if (m_cfg.doNotBreakWhileSeeding) {
+        continue;
+      } else {
+        break;
+      }
     }
     // Update fitter state with all vertices
     fitterState.addVertexToMultiMap(vtxCandidate);
@@ -201,7 +200,7 @@ void AdaptiveMultiVertexFinder::setConstraintAfterSeeding(
   }
 }
 
-Acts::Result<double> AdaptiveMultiVertexFinder::getIPSignificance(
+Result<double> AdaptiveMultiVertexFinder::getIPSignificance(
     const InputTrack& track, const Vertex& vtx,
     const VertexingOptions& vertexingOptions) const {
   // TODO: In original implementation the covariance of the given vertex is set
@@ -240,7 +239,7 @@ Acts::Result<double> AdaptiveMultiVertexFinder::getIPSignificance(
   return significance;
 }
 
-Acts::Result<void> AdaptiveMultiVertexFinder::addCompatibleTracksToVertex(
+Result<void> AdaptiveMultiVertexFinder::addCompatibleTracksToVertex(
     const std::vector<InputTrack>& tracks, Vertex& vtx,
     VertexFitterState& fitterState,
     const VertexingOptions& vertexingOptions) const {
@@ -269,7 +268,7 @@ Acts::Result<void> AdaptiveMultiVertexFinder::addCompatibleTracksToVertex(
   return {};
 }
 
-Acts::Result<bool> AdaptiveMultiVertexFinder::canRecoverFromNoCompatibleTracks(
+Result<bool> AdaptiveMultiVertexFinder::canRecoverFromNoCompatibleTracks(
     const std::vector<InputTrack>& allTracks,
     const std::vector<InputTrack>& seedTracks, Vertex& vtx,
     const Vertex& currentConstraint, VertexFitterState& fitterState,
@@ -323,7 +322,7 @@ Acts::Result<bool> AdaptiveMultiVertexFinder::canRecoverFromNoCompatibleTracks(
   return Result<bool>::success(true);
 }
 
-Acts::Result<bool> AdaptiveMultiVertexFinder::canPrepareVertexForFit(
+Result<bool> AdaptiveMultiVertexFinder::canPrepareVertexForFit(
     const std::vector<InputTrack>& allTracks,
     const std::vector<InputTrack>& seedTracks, Vertex& vtx,
     const Vertex& currentConstraint, VertexFitterState& fitterState,
@@ -577,7 +576,7 @@ Result<bool> AdaptiveMultiVertexFinder::isMergedVertex(
   return Result<bool>::success(false);
 }
 
-Acts::Result<void> AdaptiveMultiVertexFinder::deleteLastVertex(
+Result<void> AdaptiveMultiVertexFinder::deleteLastVertex(
     Vertex& vtx, std::vector<std::unique_ptr<Vertex>>& allVertices,
     std::vector<Vertex*>& allVerticesPtr, VertexFitterState& fitterState,
     const VertexingOptions& vertexingOptions) const {
@@ -616,8 +615,7 @@ Acts::Result<void> AdaptiveMultiVertexFinder::deleteLastVertex(
   return {};
 }
 
-Acts::Result<std::vector<Acts::Vertex>>
-AdaptiveMultiVertexFinder::getVertexOutputList(
+Result<std::vector<Vertex>> AdaptiveMultiVertexFinder::getVertexOutputList(
     const std::vector<Vertex*>& allVerticesPtr,
     VertexFitterState& fitterState) const {
   std::vector<Vertex> outputVec;

Examples/Algorithms/Vertexing/CMakeLists.txt

@@ -4,6 +4,7 @@ add_library(
   src/IterativeVertexFinderAlgorithm.cpp
   src/VertexFitterAlgorithm.cpp
   src/SingleSeedVertexFinderAlgorithm.cpp
+  src/TruthVertexSeeder.cpp
 )
 target_include_directories(
   ActsExamplesVertexing

Examples/Algorithms/Vertexing/include/ActsExamples/Vertexing/AdaptiveMultiVertexFinderAlgorithm.hpp

@@ -22,10 +22,13 @@
 #include "Acts/Vertexing/AdaptiveMultiVertexFitter.hpp"
 #include "Acts/Vertexing/GaussianTrackDensity.hpp"
 #include "Acts/Vertexing/HelicalTrackLinearizer.hpp"
+#include "Acts/Vertexing/IVertexFinder.hpp"
 #include "Acts/Vertexing/ImpactPointEstimator.hpp"
 #include "Acts/Vertexing/TrackDensityVertexFinder.hpp"
 #include "Acts/Vertexing/Vertex.hpp"
 #include "ActsExamples/EventData/ProtoVertex.hpp"
+#include "ActsExamples/EventData/SimParticle.hpp"
+#include "ActsExamples/EventData/SimVertex.hpp"
 #include "ActsExamples/EventData/Track.hpp"
 #include "ActsExamples/EventData/Trajectories.hpp"
 #include "ActsExamples/Framework/DataHandle.hpp"
@@ -58,11 +61,16 @@ class AdaptiveMultiVertexFinderAlgorithm final : public IAlgorithm {
 
   using VertexCollection = std::vector<Acts::Vertex>;
 
-  enum class SeedFinder { GaussianSeeder, AdaptiveGridSeeder };
+  enum class SeedFinder { TruthSeeder, GaussianSeeder, AdaptiveGridSeeder };
 
   struct Config {
     /// Input track parameters collection
     std::string inputTrackParameters;
+    /// Optional
+    std::string inputTruthParticles;
+    /// Optional: Input truth vertex collection. This will only be used if
+    /// `seedFinder == SeedFinder::TruthSeeder`.
+    std::string inputTruthVertices;
     /// Output proto vertex collection
     std::string outputProtoVertices;
     /// Output vertex collection
@@ -117,21 +125,26 @@ class AdaptiveMultiVertexFinderAlgorithm final : public IAlgorithm {
   const Config& config() const { return m_cfg; }
 
  private:
-  Acts::AdaptiveMultiVertexFinder makeVertexFinder() const;
+  std::unique_ptr<Acts::IVertexFinder> makeVertexSeeder() const;
+  Acts::AdaptiveMultiVertexFinder makeVertexFinder(
+      std::shared_ptr<const Acts::IVertexFinder> seedFinder) const;
 
   Config m_cfg;
 
   std::shared_ptr<const Acts::BasePropagator> m_propagator;
   Acts::ImpactPointEstimator m_ipEstimator;
   Linearizer m_linearizer;
+  std::shared_ptr<Acts::IVertexFinder> m_vertexSeeder;
   Acts::AdaptiveMultiVertexFinder m_vertexFinder;
 
   ReadDataHandle<TrackParametersContainer> m_inputTrackParameters{
       this, "InputTrackParameters"};
-
+  ReadDataHandle<SimParticleContainer> m_inputTruthParticles{
+      this, "InputTruthParticles"};
+  ReadDataHandle<SimVertexContainer> m_inputTruthVertices{this,
+                                                          "InputTruthVertices"};
   WriteDataHandle<ProtoVertexContainer> m_outputProtoVertices{
       this, "OutputProtoVertices"};
-
   WriteDataHandle<VertexCollection> m_outputVertices{this, "OutputVertices"};
 };