CKF Tracking based on Gen3 geometry

.github/workflows/downstream-build.yaml

@@ -17,5 +17,5 @@ jobs:
     strategy:
       fail-fast: false
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - uses: key4hep/key4hep-actions/downstream-build@main

.github/workflows/mucoll-ci.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Free Disk Space (Ubuntu)
-        uses: endersonmenezes/free-disk-space@v2
+        uses: endersonmenezes/free-disk-space@v3
         with:
           remove_android: true
           remove_dotnet: true
@@ -25,12 +25,14 @@ jobs:
           remove_swap: true
           remove_packages: "azure-cli google-cloud-cli microsoft-edge-stable google-chrome-stable firefox postgresql* temurin-* *llvm* mysql* dotnet-sdk-*"
           remove_packages_one_command: true
-          remove_folders: "/usr/share/swift /usr/share/miniconda /usr/share/az* /usr/share/glade* /usr/local/lib/node_modules /usr/local/share/chromium /usr/local/share/powershell"
+          remove_folders: "/usr/share/swift /usr/share/miniconda /usr/share/az* /usr/local/lib/node_modules /usr/local/share/chromium /usr/local/share/powershell /usr/local/julia /usr/local/aws-cli /usr/local/aws-sam-cli /usr/share/gradle"
+          rm_cmd: "rmz"  # Use 'rmz' for faster deletion (default: 'rm')
+          rmz_version: "3.1.1"  # Required when rm_cmd is 'rmz'
           testing: false
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - shell: bash
         run: echo "NOW=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-      - uses: actions/cache/restore@v4
+      - uses: actions/cache/restore@v5
         with:
           path: ~/.cache/ccache
           key: ccache-mucoll-image-${{ env.NOW }}
@@ -59,8 +61,7 @@ jobs:
             -DCMAKE_INSTALL_PREFIX=$(pwd)/install \
             -DCMAKE_CXX_FLAGS=" -fdiagnostics-color=always -Werror -Wno-error=deprecated-declarations"
           cmake --build build
-          # Tests need OpenDataDetector, which is not present in the mucoll image atm
-          # ctest --test-dir build -j$(nproc) --output-on-failure
+          ctest --test-dir build -j$(nproc) --output-on-failure -E "(CLD|ILD)"
           cmake --build build --target install
 
           ccache -s
@@ -69,7 +70,7 @@ jobs:
           chmod +x ${GITHUB_WORKSPACE}/build.sh
 
           docker exec ci_container /bin/bash -c "/packages/build.sh"
-      - uses: actions/cache/save@v4
+      - uses: actions/cache/save@v5
         if: always()
         with:
           path: ~/.cache/ccache

.gitignore

@@ -251,3 +251,10 @@ test/gaudi_opts/testConverterConstants.py
 .claude/
 .codex/
 .aider.*
+
+# OS junk
+.DS_Store
+
+# Detector/material files fetched by data/download_files.sh
+/data/*.root
+/data/*.json

README.md

@@ -1,25 +1,112 @@
 # k4ActsTracking
 
+[![Key4hep build](https://github.com/key4hep/k4ActsTracking/actions/workflows/key4hep-build.yaml/badge.svg)](https://github.com/key4hep/k4ActsTracking/actions/workflows/key4hep-build.yaml)
+[![downstream-build](https://github.com/key4hep/k4ActsTracking/actions/workflows/downstream-build.yaml/badge.svg)](https://github.com/key4hep/k4ActsTracking/actions/workflows/downstream-build.yaml)
+[![MuColl Image Build](https://github.com/key4hep/k4ActsTracking/actions/workflows/mucoll-ci.yml/badge.svg)](https://github.com/key4hep/k4ActsTracking/actions/workflows/mucoll-ci.yml)
+[![pre-commit](https://github.com/key4hep/k4ActsTracking/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/key4hep/k4ActsTracking/actions/workflows/pre-commit.yml)
 
-This repository contains the necessary tools to use ACTS functionality in Key4hep
-
+`k4ActsTracking` provides [ACTS](https://acts.readthedocs.io/)-based track
+reconstruction components for the [Key4hep](https://key4hep.github.io/key4hep-doc/)
+software stack. It converts DD4hep tracking geometries into ACTS geometries and
+exposes a set of Gaudi algorithms and services (geometry conversion, seeding,
+combinatorial Kalman filter track finding, duplicate removal, track filtering
+and truth matching) usable from `k4run` option files.
 
 ## Dependencies
 
-* Acts
+* [ACTS](https://github.com/acts-project/acts) (`Core`, `PluginDD4hep`,
+  `PluginJson`, `PluginRoot`)
+* [DD4hep](https://github.com/AIDASoft/DD4hep) (`DDCore`, `DDRec`)
+* [EDM4hep](https://github.com/key4hep/EDM4hep)
+* [k4FWCore](https://github.com/key4hep/k4FWCore)
+* [Gaudi](https://gitlab.cern.ch/gaudi/Gaudi)
+* TBB
 
-* DD4hep
+All of these are provided by a Key4hep release. The easiest way to get a working
+environment is to source a nightly or stable Key4hep stack, e.g.:
 
-* k4FWCore
+```sh
+source /cvmfs/sw-nightlies.hsf.org/key4hep/setup.sh
+```
 
-## Installation
+## Building
 
+```sh
+mkdir -p build install
+cmake -B build -S . -GNinja \
+  -DCMAKE_CXX_STANDARD=20 \
+  -DCMAKE_INSTALL_PREFIX=$(pwd)/install \
+  -DCMAKE_CXX_FLAGS=" -fdiagnostics-color=always -Werror -Wno-error=deprecated-declarations"
+cmake --build build
+cmake --build build --target install
+```
 
+After installing, make the package visible to Gaudi/`k4run`:
+
+```sh
+source ../install/setup.sh   # if generated, otherwise set the paths below
+# or, manually:
+export LD_LIBRARY_PATH=$PWD/install/lib:$LD_LIBRARY_PATH
+export PYTHONPATH=$PWD/install/python:$PYTHONPATH
 ```
-mkdir build install
-cd build;
-cmake .. -DCMAKE_INSTALL_PREFIX=../install
-make install
 
+## Components
+
+The Gaudi plugin module `k4ActsTrackingPlugins` provides, among others:
+
+* **`ActsGeoSvc`** — builds an ACTS tracking geometry from a DD4hep compact
+  file (consumed via `GeoSvc`). Can optionally dump the converted geometry to an
+  `.obj` file for visualization.
+* **`CKFTrackingAlg`** — seeding plus combinatorial Kalman filter (CKF) track
+  finding on EDM4hep tracker hits.
+* **`ACTSSeededCKFTrackingAlg`** — alternative seeded CKF tracking algorithm.
+* **`ACTSDuplicateRemoval`** — removes duplicate tracks produced by the CKF.
+* **`FilterTracksAlg`** — applies quality cuts to a track collection.
+* **`TrackTruthAlg`** — associates reconstructed tracks with truth particles.
+* **`ActsTestPropagator`** — propagates ACTS particle-gun tracks through the
+  converted geometry (useful for geometry validation).
+
+## Usage
+
+The algorithms are configured and run through `k4run` option files. See the
+examples and the test option files for working configurations:
+
+* [`k4ActsTracking/examples/test_visualize_acts_geo.py`](k4ActsTracking/examples/test_visualize_acts_geo.py)
+  — load a compact file, convert it to ACTS geometry, optionally dump an `.obj`
+  and run the test propagator:
 
+  ```sh
+  k4run k4ActsTracking/examples/test_visualize_acts_geo.py \
+        --compactFile <detector>.xml --test-propagation
+  ```
+
+* [`test/options/MAIA_CKFTrackingAlg.py`](test/options/MAIA_CKFTrackingAlg.py),
+  [`test/options/CLD_CKFTracking.py`](test/options/CLD_CKFTracking.py),
+  [`test/options/ILD_CKFTracking.py`](test/options/ILD_CKFTracking.py) — full
+  digitization + CKF tracking chains for the MAIA, CLD and ILD detectors. The
+  shared helpers live in
+  [`test/options/_ckf_helpers.py`](test/options/_ckf_helpers.py).
+
+  > **Note:** the parameters in these option files are tuned only for technical
+  > tests and are *not* a meaningful physics tracking configuration.
+
+## Tests
+
+Tests are built when `BUILD_TESTING` is on (default) and run with `ctest` from
+the build directory:
+
+```sh
+cd build
+ctest --output-on-failure
 ```
+
+The suite covers C++ unit tests plus end-to-end chains (`ddsim` simulation →
+reconstruction → CKF tracking) for the MAIA, CLD and ILD geometries. The CLD and
+ILD chains clone the corresponding upstream config repositories
+([`CLDConfig`](https://github.com/key4hep/CLDConfig),
+[`ILDConfig`](https://github.com/iLCSoft/ILDConfig)) on the fly, and geometries
+are taken from `k4geo` (via `$k4geo_DIR`).
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).

k4ActsTracking/CMakeLists.txt

@@ -21,7 +21,9 @@ set(ACTS_LIBRARY_TARGETS "Acts::Core")
 gaudi_add_library(k4ActsTracking
   SOURCES
     src/ActsGaudiLogger.cpp
+    src/CellIDSelector.cxx
   LINK
+    DD4hep::DDCore
     k4FWCore::k4FWCore
     ${ACTS_LIBRARY_TARGETS}
 )
@@ -43,6 +45,7 @@ set(_plugin_sources
   src/components/TrackTruthAlg.cxx
   src/components/ActsTestPropagator.cpp
   src/components/DD4hepBlueprintConstruction.cpp
+  src/components/CKFTrackingAlg.cpp
 )
 
 gaudi_add_module(k4ActsTrackingPlugins
@@ -69,12 +72,4 @@ install(TARGETS k4ActsTrackingPlugins
   COMPONENT dev)
 
 set(GAUDI_GENCONF_DIR "genConfDir")
-
-function(set_test_env _testname)
-  set_property(TEST ${_testname} APPEND PROPERTY ENVIRONMENT
-    LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}:$<TARGET_FILE_DIR:k4ActsTrackingPlugins>:$<TARGET_FILE_DIR:ROOT::Core>:$<TARGET_FILE_DIR:k4FWCore::k4FWCore>:$<TARGET_FILE_DIR:EDM4HEP::edm4hep>:$<TARGET_FILE_DIR:podio::podio>:$ENV{LD_LIBRARY_PATH}
-    PYTHONPATH=${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}/${GAUDI_GENCONF_DIR}:$<TARGET_FILE_DIR:k4FWCore::k4FWCore>/../python:$ENV{PYTHONPATH}
-    PATH=$<TARGET_FILE_DIR:k4FWCore::k4FWCore>/../bin:$ENV{PATH}
-    K4ACTSTRACKING=${CMAKE_CURRENT_LIST_DIR}/
-    )
-endfunction()
+set_property(TARGET k4ActsTrackingPlugins PROPERTY GAUDI_GENCONF TRUE)

k4ActsTracking/include/k4ActsTracking/ACTSSeededCKFTrackingAlg.hxx

@@ -203,9 +203,6 @@ protected:
   Gaudi::Property<int> m_numThreads{this, "NumThreads", 1, "Number of threads to use for internal multithreading."};
   ///@}
 
-  // Thread-safe counter
-  // mutable Gaudi::Accumulators::Counter<> m_fitFails{this, "FitFails"};
-
 private:
   // Mutexes for threadsafe container filling of seeds and tracks
   mutable std::mutex m_seedMutex{};
@@ -302,7 +299,7 @@ std::vector<Acts::BoundTrackParameters> ACTSSeededCKFTrackingAlg::findSeeds(
       seedTrack.addToTrackStates(seedTrackState);
     }
 
-    debug() << "Seed Paramemeters" << std::endl << paramseed << endmsg;
+    debug() << "Seed Parameters" << std::endl << paramseed << endmsg;
   }
 
   debug() << "Seeds found: " << std::endl << paramseeds.size() << endmsg;

k4ActsTracking/include/k4ActsTracking/CKFTrackingAlg.hxx

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2014-2024 Key4hep-Project.
+ *
+ * This file is part of Key4hep.
+ * See https://key4hep.github.io/key4hep-doc/ for further info.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+// ACTS
+#include <Acts/EventData/TrackParameters.hpp>
+
+// Standard
+#include <cmath>
+
+namespace ACTSTracking {
+
+  //! Build a diagonal initial track covariance matrix from per-parameter error estimates
+  /**
+   * \param p        Absolute momentum [ACTS units].
+   * \param errPos   Local-position error [ACTS units].
+   * \param errPhi   Azimuthal angle error [rad].
+   * \param errLambda Polar angle (lambda) error [rad].
+   * \param errRelP  Relative momentum error (dimensionless fraction).
+   * \param errTime  Time error [ACTS units].
+   * \return         5×5 diagonal bound covariance matrix.
+   */
+  inline Acts::BoundMatrix makeInitialCovariance(double p, double errPos, double errPhi, double errLambda,
+                                                 double errRelP, double errTime) {
+    Acts::BoundMatrix cov                       = Acts::BoundMatrix::Zero();
+    cov(Acts::eBoundLoc0, Acts::eBoundLoc0)     = std::pow(errPos, 2);
+    cov(Acts::eBoundLoc1, Acts::eBoundLoc1)     = std::pow(errPos, 2);
+    cov(Acts::eBoundTime, Acts::eBoundTime)     = std::pow(errTime, 2);
+    cov(Acts::eBoundPhi, Acts::eBoundPhi)       = std::pow(errPhi, 2);
+    cov(Acts::eBoundTheta, Acts::eBoundTheta)   = std::pow(errLambda, 2);
+    cov(Acts::eBoundQOverP, Acts::eBoundQOverP) = std::pow(errRelP * p / (p * p), 2);
+    return cov;
+  }
+
+}  // namespace ACTSTracking