feat: Truth Jet Algorithm using FastJet (#4267)

This PR introduces a not-yet-tuned truth jet algorithm that uses the FastJet plug-in as implemented in [PR: 3617](#3617). The algorithm takes truth particles from Pythia8 and, by using their kinematic information, applies jet clustering. 

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

- **New Features**
  - Introduced a FastJet plugin with optional build support, enabling jet clustering capabilities.
  - Added a new TruthJet algorithm for clustering simulated particles into jets using FastJet.
  - Integrated the TruthJet algorithm into the Python interface and provided corresponding Python utilities and scripts.
  - Added example and test scripts for truth jet reconstruction workflows.
- **Documentation**
  - Updated documentation to describe the new FastJet plugin build option.
- **Chores**
  - Enhanced build configuration to support conditional inclusion of FastJet components and plugins.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Paul Gessinger <[email protected]>

Author: delitez

.github/actions/dependencies/action.yml

@@ -13,7 +13,7 @@ inputs:
   spack_version:
     description: 'Version of Spack to use'
     required: false
-    default: 'develop-2025-04-20'
+    default: 'develop-2025-05-25'
 
 runs:
   using: 'composite'

.github/workflows/analysis.yml

@@ -22,7 +22,7 @@ env:
   CCACHE_MAXSIZE: 1.25G
   CCACHE_KEY_SUFFIX: r2
   ACTS_LOG_FAILURE_THRESHOLD: WARNING
-  DEPENDENCY_TAG: v9.0.0
+  DEPENDENCY_TAG: v10.0.0
 
 # NOTE this only builds core unittests to reduce the output size. if we
 #      found a way to have Github actions not fail regularly with this job

.github/workflows/builds.yml

@@ -20,7 +20,7 @@ env:
   CCACHE_DIR: ${{ github.workspace }}/ccache
   CCACHE_MAXSIZE: 500M
   CCACHE_KEY_SUFFIX: r2
-  DEPENDENCY_TAG: v9.0.0
+  DEPENDENCY_TAG: v10.0.0
 
 jobs:
   linux_ubuntu:

.gitlab-ci.yml

@@ -4,10 +4,10 @@ variables:
   CCACHE_KEY_SUFFIX: r2
   CTEST_OUTPUT_ON_FAILURE: 1
 
-  SPACK_VERSION: develop-2025-04-20
+  SPACK_VERSION: develop-2025-05-25
   LOCKFILE_CACHE_DIR: ${CI_PROJECT_DIR}/spack_lockfile_cache
 
-  DEPENDENCY_TAG: v9.0.0
+  DEPENDENCY_TAG: v10.0.0
 
 .ccache_base:
   cache:

CMakeLists.txt

@@ -81,6 +81,7 @@ option(ACTS_BUILD_PLUGIN_DD4HEP "Build DD4hep plugin" OFF)
 option(ACTS_BUILD_PLUGIN_PODIO "Build Podio plugin" OFF)
 option(ACTS_BUILD_PLUGIN_EDM4HEP "Build EDM4hep plugin" OFF)
 option(ACTS_BUILD_PLUGIN_FPEMON "Build FPE monitoring plugin" OFF)
+option(ACTS_BUILD_PLUGIN_FASTJET "Build FastJet plugin" OFF)
 option(ACTS_BUILD_PLUGIN_GEOMODEL "Build GeoModel plugin" OFF)
 option(ACTS_BUILD_PLUGIN_TRACCC "Build Traccc plugin" OFF)
 option(ACTS_BUILD_PLUGIN_GEANT4 "Build Geant4 plugin" OFF)
@@ -290,6 +291,7 @@ set(_acts_covfie_version 0.12.1)
 set(_acts_vecmem_version 1.14.0)
 set(_acts_algebraplugins_version 0.26.2)
 set(_acts_annoy_version 1.17.3)
+set(_acts_fastjet_version 3.4.1)
 
 # recommended dependency version. if there is an opportunity to reach
 # this version we will try so.
@@ -403,6 +405,9 @@ if(ACTS_BUILD_PLUGIN_JSON)
         add_subdirectory(thirdparty/nlohmann_json)
     endif()
 endif()
+if(ACTS_BUILD_PLUGIN_FASTJET)
+    find_package(FastJet ${_acts_fastjet_version} REQUIRED)
+endif()
 if(ACTS_BUILD_PLUGIN_GEOMODEL)
     find_package(GeoModelCore CONFIG)
     if(NOT GeoModelCore_FOUND)

CMakePresets.json

@@ -68,6 +68,7 @@
                 "ACTS_BUILD_PLUGIN_JSON": "ON",
                 "ACTS_BUILD_PLUGIN_ONNX": "OFF",
                 "ACTS_BUILD_PLUGIN_TGEO": "ON",
+                "ACTS_BUILD_PLUGIN_FASTJET": "ON",
                 "ACTS_BUILD_EXAMPLES_EDM4HEP": "ON",
                 "ACTS_BUILD_EXAMPLES_PODIO": "ON",
                 "ACTS_BUILD_EXAMPLES_EXATRKX": "OFF",

Examples/Algorithms/CMakeLists.txt

@@ -12,6 +12,7 @@ add_subdirectory(TrackFinding)
 add_subdirectory_if(TrackFindingExaTrkX ACTS_BUILD_EXAMPLES_EXATRKX)
 add_subdirectory_if(TrackFindingML ACTS_BUILD_PLUGIN_ONNX)
 add_subdirectory(TrackFitting)
+add_subdirectory_if(Jets ACTS_BUILD_PLUGIN_FASTJET)
 add_subdirectory(TruthTracking)
 add_subdirectory(Vertexing)
 add_subdirectory_if(Alignment ACTS_BUILD_ALIGNMENT)

Examples/Algorithms/Jets/CMakeLists.txt

@@ -0,0 +1,13 @@
+add_library(ActsExamplesJets SHARED src/TruthJetAlgorithm.cpp)
+target_include_directories(
+    ActsExamplesJets
+    PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+)
+target_link_libraries(
+    ActsExamplesJets
+    PUBLIC ActsCore ActsPluginFastJet ActsExamplesFramework
+)
+
+acts_compile_headers(ActsExamplesJets GLOB "include/**/*.hpp")
+
+install(TARGETS ActsExamplesJets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})

Examples/Algorithms/Jets/include/ActsExamples/Jets/TruthJetAlgorithm.hpp

@@ -0,0 +1,52 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 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 https://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Utilities/Logger.hpp"
+#include "ActsExamples/EventData/SimParticle.hpp"
+#include "ActsExamples/Framework/DataHandle.hpp"
+#include "ActsExamples/Framework/IAlgorithm.hpp"
+#include "ActsExamples/Framework/ProcessCode.hpp"
+
+#include <string>
+
+namespace fastjet {
+class PseudoJet;
+}
+
+namespace ActsExamples {
+struct AlgorithmContext;
+
+class TruthJetAlgorithm final : public IAlgorithm {
+ public:
+  struct Config {
+    /// Input particles collection.
+    std::string inputTruthParticles;
+    /// Output jets collection.
+    std::string outputJets;
+    /// Minimum jet pT.
+    double jetPtMin;
+  };
+
+  TruthJetAlgorithm(const Config& cfg, Acts::Logging::Level lvl);
+
+  ProcessCode execute(const AlgorithmContext& ctx) const override;
+  ProcessCode finalize() override;
+
+  const Config& config() const { return m_cfg; }
+
+ private:
+  Config m_cfg;
+  ReadDataHandle<SimParticleContainer> m_inputTruthParticles{
+      this, "inputTruthParticles"};
+  WriteDataHandle<std::vector<fastjet::PseudoJet>> m_outputJets{this,
+                                                                "outputJets"};
+};
+
+}  // namespace ActsExamples

Examples/Algorithms/Jets/src/TruthJetAlgorithm.cpp

@@ -0,0 +1,77 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 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 https://mozilla.org/MPL/2.0/.
+
+#include "ActsExamples/Jets/TruthJetAlgorithm.hpp"
+
+#include "Acts/Definitions/Units.hpp"
+#include "Acts/Utilities/Logger.hpp"
+#include "ActsExamples/EventData/SimParticle.hpp"
+#include "ActsExamples/Framework/AlgorithmContext.hpp"
+#include "ActsFatras/EventData/ProcessType.hpp"
+
+#include <ostream>
+#include <stdexcept>
+
+#include <fastjet/ClusterSequence.hh>
+#include <fastjet/JetDefinition.hh>
+#include <fastjet/PseudoJet.hh>
+
+namespace ActsExamples {
+
+TruthJetAlgorithm::TruthJetAlgorithm(const Config& cfg,
+                                     Acts::Logging::Level lvl)
+    : IAlgorithm("TruthJetAlgorithm", lvl), m_cfg(cfg) {
+  if (m_cfg.inputTruthParticles.empty()) {
+    throw std::invalid_argument("Input particles collection is not configured");
+  }
+  m_inputTruthParticles.initialize(m_cfg.inputTruthParticles);
+  m_outputJets.initialize(m_cfg.outputJets);
+}
+
+ProcessCode ActsExamples::TruthJetAlgorithm::execute(
+    const ActsExamples::AlgorithmContext& ctx) const {
+  const auto& truthParticles = m_inputTruthParticles(ctx);
+
+  ACTS_DEBUG("Number of truth particles: " << truthParticles.size());
+
+  const fastjet::JetDefinition defaultJetDefinition =
+      fastjet::JetDefinition(fastjet::antikt_algorithm, 0.4);
+
+  // Get the 4-momentum information from the simulated truth particles
+  // and create fastjet::PseudoJet objects
+  std::vector<fastjet::PseudoJet> inputPseudoJets;
+
+  int particleIndex = 0;
+  for (const auto& particle : truthParticles) {
+    fastjet::PseudoJet pseudoJet(particle.momentum().x(),
+                                 particle.momentum().y(),
+                                 particle.momentum().z(), particle.energy());
+
+    pseudoJet.set_user_index(particleIndex);
+    inputPseudoJets.push_back(pseudoJet);
+    particleIndex++;
+  }
+  ACTS_DEBUG("Number of input pseudo jets: " << inputPseudoJets.size());
+  // Run the jet clustering
+  fastjet::ClusterSequence clusterSeq(inputPseudoJets, defaultJetDefinition);
+  // Get the jets above a certain pt threshold
+  std::vector<fastjet::PseudoJet> jets =
+      sorted_by_pt(clusterSeq.inclusive_jets(m_cfg.jetPtMin));
+  ACTS_DEBUG("Number of clustered jets: " << jets.size());
+  // Store the jets in the output data handle
+  m_outputJets(ctx, std::move(jets));
+
+  return ProcessCode::SUCCESS;
+}
+
+ProcessCode ActsExamples::TruthJetAlgorithm::finalize() {
+  ACTS_INFO("Finalizing truth jet clustering");
+  return ProcessCode::SUCCESS;
+}
+
+};  // namespace ActsExamples

Examples/Python/CMakeLists.txt

@@ -258,6 +258,13 @@ else()
     target_sources(ActsPythonBindings PRIVATE src/OnnxNeuralCalibratorStub.cpp)
 endif()
 
+if(ACTS_BUILD_PLUGIN_FASTJET)
+    target_link_libraries(ActsPythonBindings PUBLIC ActsExamplesJets)
+    target_sources(ActsPythonBindings PRIVATE src/TruthJet.cpp)
+else()
+    target_sources(ActsPythonBindings PRIVATE src/TruthJetStub.cpp)
+endif()
+
 if(ACTS_BUILD_EXAMPLES_HASHING)
     target_link_libraries(ActsPythonBindings PUBLIC ActsPluginHashing)
     target_sources(ActsPythonBindings PRIVATE src/Hashing.cpp)

Examples/Python/python/acts/examples/simulation.py

@@ -53,6 +53,12 @@
     defaults=[(None, None)] * 10 + [None] * 4,
 )
 
+TruthJetConfig = namedtuple(
+    "TruthJetConfig",
+    ["inputTruthParticles", "outputJets", "jetPtMin"],
+    defaults=[None, None],
+)
+
 
 def _getParticleSelectionKWargs(config: ParticleSelectorConfig) -> dict:
     return {
@@ -83,6 +89,14 @@ def _getParticleSelectionKWargs(config: ParticleSelectorConfig) -> dict:
     }
 
 
+def _getTruthJetKWargs(config: TruthJetConfig) -> dict:
+    return {
+        "inputTruthParticles": config.inputTruthParticles,
+        "outputJets": config.outputJets,
+        "jetPtMin": config.jetPtMin,
+    }
+
+
 @acts.examples.NamedTypeArgs(
     momentumConfig=MomentumConfig,
     etaConfig=EtaConfig,
@@ -836,3 +850,19 @@ def addDigiParticleSelection(
     s.addWhiteboardAlias(
         "particles_digitized_selected", selector.config.outputParticles
     )
+
+
+def addTruthJetAlg(
+    s: acts.examples.Sequencer,
+    config: TruthJetConfig,
+    loglevel: Optional[acts.logging.Level] = None,
+) -> None:
+    from acts.examples import TruthJetAlgorithm
+
+    customLogLevel = acts.examples.defaultLogging(s, loglevel)
+    truthJetAlg = acts.examples.TruthJetAlgorithm(
+        **acts.examples.defaultKWArgs(**_getTruthJetKWargs(config)),
+        level=customLogLevel(),
+    )
+
+    s.addAlgorithm(truthJetAlg)

Examples/Python/src/ModuleEntry.cpp

@@ -52,6 +52,7 @@ void addGenerators(Context& ctx);
 void addTruthTracking(Context& ctx);
 void addTrackFitting(Context& ctx);
 void addTrackFinding(Context& ctx);
+void addTruthJet(Context& ctx);
 void addVertexing(Context& ctx);
 void addAmbiguityResolution(Context& ctx);
 void addUtilities(Context& ctx);
@@ -127,6 +128,7 @@ PYBIND11_MODULE(ActsPythonBindings, m) {
   addTruthTracking(ctx);
   addTrackFitting(ctx);
   addTrackFinding(ctx);
+  addTruthJet(ctx);
   addVertexing(ctx);
   addAmbiguityResolution(ctx);
   addUtilities(ctx);

Examples/Python/src/TruthJet.cpp

@@ -0,0 +1,33 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 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 https://mozilla.org/MPL/2.0/.
+
+#include "Acts/Plugins/Python/Utilities.hpp"
+#include "Acts/Utilities/Logger.hpp"
+#include "ActsExamples/Jets/TruthJetAlgorithm.hpp"
+
+#include <cstddef>
+#include <memory>
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+namespace py = pybind11;
+
+using namespace ActsExamples;
+using namespace Acts;
+
+namespace Acts::Python {
+
+void addTruthJet(Context& ctx) {
+  auto mex = ctx.get("examples");
+
+  ACTS_PYTHON_DECLARE_ALGORITHM(ActsExamples::TruthJetAlgorithm, mex,
+                                "TruthJetAlgorithm", inputTruthParticles,
+                                outputJets, jetPtMin);
+}  // addTruthJet
+}  // namespace Acts::Python

Examples/Python/src/TruthJetStub.cpp

@@ -0,0 +1,14 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 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 https://mozilla.org/MPL/2.0/.
+
+// This is a stub version when the FastJet plugin is not available
+#include "Acts/Plugins/Python/Utilities.hpp"
+
+namespace Acts::Python {
+void addTruthJet(Context& /*ctx*/) {}
+}  // namespace Acts::Python

Examples/Scripts/Python/truth_jet_test.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+import acts
+import acts.examples
+from acts.examples.simulation import addPythia8, addTruthJetAlg, TruthJetConfig
+
+
+outputDir = "./truth_jet_test_output"
+u = acts.UnitConstants
+rnd = acts.examples.RandomNumbers(seed=42)
+
+s = acts.examples.Sequencer(events=10, outputDir=outputDir)
+
+addPythia8(
+    s,
+    hardProcess=["Top:qqbar2ttbar=on"],
+    npileup=50,
+    vtxGen=acts.examples.GaussianVertexGenerator(
+        mean=acts.Vector4(0, 0, 0, 0),
+        stddev=acts.Vector4(0.0125 * u.mm, 0.0125 * u.mm, 55.5 * u.mm, 5.0 * u.ns),
+    ),
+    rnd=rnd,
+    outputDirRoot=outputDir,
+    outputDirCsv=outputDir,
+)
+
+addTruthJetAlg(
+    s,
+    TruthJetConfig(
+        inputTruthParticles="particles_generated",
+        outputJets="output_jets",
+        jetPtMin=20 * u.GeV,
+    ),
+    loglevel=acts.logging.INFO,
+)
+
+s.run()

Plugins/CMakeLists.txt

@@ -3,6 +3,7 @@
 # independent plugins
 add_component_if(ActSVG PluginActSVG ACTS_BUILD_PLUGIN_ACTSVG)
 add_component_if(Cuda PluginCuda ACTS_BUILD_PLUGIN_CUDA)
+add_component_if(FastJet PluginFastJet ACTS_BUILD_PLUGIN_FASTJET)
 add_component_if(FpeMonitoring PluginFpeMonitoring ACTS_BUILD_PLUGIN_FPEMON)
 add_component_if(Geant4 PluginGeant4 ACTS_BUILD_PLUGIN_GEANT4)
 add_component_if(GeoModel PluginGeoModel ACTS_BUILD_PLUGIN_GEOMODEL)