Track Fit/State SoA, main branch (2025.08.05.) (#1112)

* Introduced an SoA EDM for the track fit in traccc::core.

* Adapted traccc::device_common and traccc::cuda to the SoA track fit EDM.

* Adapted traccc::alpaka and traccc::sycl to the SoA track fit EDM.

* Adapted the tests and benchmarks to the SoA track fit EDM.

* Adapted the examples to the SoA track fit EDM.

* Introduced track_candidates_container::device and track_fit_container::device.

To make it a bit easier to deal with the slightly complex EDMs
of track finding and fitting in the code.

* Moved "complex EDM operations" to helper functions.

* Adjusted the host Kalman fit testing code a little.

Taking into account that the updated code now returns tracks
that have not been successfully fitted. Previously it would not
return the tracks for which the fit failed.

* Reintroduce print_fitted_tracks_statistics(...).

But now as a function in the examples code. Not as part of
traccc::core.

* Small changes in the host fitting code.

Based on the PR feedback.

* Made the plotting tool documentation more explicit.

Author: krasznaa

benchmarks/cuda/toy_detector_cuda.cpp

@@ -73,10 +73,6 @@ BENCHMARK_DEFINE_F(ToyDetectorBenchmark, CUDA)(benchmark::State& state) {
     // Detector view object
     auto det_view = detray::get_data(det_buffer);
 
-    // D2H copy object
-    traccc::device::container_d2h_copy_alg<traccc::track_state_container_types>
-        track_state_d2h{{device_mr, &host_mr}, copy};
-
     for (auto _ : state) {
 
         state.PauseTiming();
@@ -129,7 +125,7 @@ BENCHMARK_DEFINE_F(ToyDetectorBenchmark, CUDA)(benchmark::State& state) {
                                params_cuda_buffer);
 
             // Run track fitting
-            traccc::track_state_container_types::buffer
+            traccc::edm::track_fit_container<traccc::default_algebra>::buffer
                 track_states_cuda_buffer = device_fitting(
                     det_view, field,
                     {track_candidates_cuda_buffer, measurements_cuda_buffer});

core/CMakeLists.txt

@@ -21,10 +21,11 @@ traccc_add_library( traccc_core core TYPE SHARED
   "include/traccc/edm/details/device_container.hpp"
   "include/traccc/edm/details/host_container.hpp"
   "include/traccc/edm/measurement.hpp"
+  "include/traccc/edm/measurement_helpers.hpp"
+  "include/traccc/edm/impl/measurement_helpers.ipp"
   "include/traccc/edm/particle.hpp"
   "include/traccc/edm/track_parameters.hpp"
   "include/traccc/edm/container.hpp"
-  "include/traccc/edm/track_state.hpp"
   "include/traccc/edm/silicon_cell_collection.hpp"
   "include/traccc/edm/impl/silicon_cell_collection.ipp"
   "include/traccc/edm/silicon_cluster_collection.hpp"
@@ -35,6 +36,12 @@ traccc_add_library( traccc_core core TYPE SHARED
   "include/traccc/edm/track_candidate_collection.hpp"
   "include/traccc/edm/impl/track_candidate_collection.ipp"
   "include/traccc/edm/track_candidate_container.hpp"
+  "include/traccc/edm/track_state_collection.hpp"
+  "include/traccc/edm/impl/track_state_collection.ipp"
+  "include/traccc/edm/track_state_helpers.hpp"
+  "include/traccc/edm/impl/track_state_helpers.ipp"
+  "include/traccc/edm/track_fit_outcome.hpp"
+  "include/traccc/edm/track_fit_collection.hpp"
   # Magnetic field description.
   "include/traccc/bfield/magnetic_field_types.hpp"
   "include/traccc/bfield/magnetic_field.hpp"

core/include/traccc/edm/impl/measurement_helpers.ipp

@@ -0,0 +1,80 @@
+/** TRACCC library, part of the ACTS project (R&D line)
+ *
+ * (c) 2025 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+
+#pragma once
+
+namespace traccc::edm {
+
+template <detray::concepts::algebra algebra_t, std::integral size_t, size_t D>
+TRACCC_HOST_DEVICE void get_measurement_local(
+    const measurement& meas, detray::dmatrix<algebra_t, D, 1>& pos) {
+
+    static_assert(((D == 1u) || (D == 2u)),
+                  "The measurement dimension must be 1 or 2");
+
+    assert((meas.subs.get_indices()[0] == e_bound_loc0) ||
+           (meas.subs.get_indices()[0] == e_bound_loc1));
+
+    const point2& local = meas.local;
+
+    switch (meas.subs.get_indices()[0]) {
+        case e_bound_loc0:
+            getter::element(pos, 0, 0) = local[0];
+            if constexpr (D == 2u) {
+                getter::element(pos, 1, 0) = local[1];
+            }
+            break;
+        case e_bound_loc1:
+            getter::element(pos, 0, 0) = local[1];
+            if constexpr (D == 2u) {
+                getter::element(pos, 1, 0) = local[0];
+            }
+            break;
+        default:
+#if defined(__GNUC__)
+            __builtin_unreachable();
+#endif
+    }
+}
+
+template <detray::concepts::algebra algebra_t, std::integral size_t, size_t D>
+TRACCC_HOST_DEVICE void get_measurement_covariance(
+    const measurement& meas, detray::dmatrix<algebra_t, D, D>& cov) {
+
+    static_assert(((D == 1u) || (D == 2u)),
+                  "The measurement dimension must be 1 or 2");
+
+    assert((meas.subs.get_indices()[0] == e_bound_loc0) ||
+           (meas.subs.get_indices()[0] == e_bound_loc1));
+
+    const variance2& variance = meas.variance;
+
+    switch (meas.subs.get_indices()[0]) {
+        case e_bound_loc0:
+            getter::element(cov, 0, 0) = variance[0];
+            if constexpr (D == 2u) {
+                getter::element(cov, 0, 1) = 0.f;
+                getter::element(cov, 1, 0) = 0.f;
+                getter::element(cov, 1, 1) = variance[1];
+            }
+            break;
+        case e_bound_loc1:
+            getter::element(cov, 0, 0) = variance[1];
+            if constexpr (D == 2u) {
+                getter::element(cov, 0, 1) = 0.f;
+                getter::element(cov, 1, 0) = 0.f;
+                getter::element(cov, 1, 1) = variance[0];
+            }
+            break;
+        default:
+#if defined(__GNUC__)
+            __builtin_unreachable();
+#endif
+    }
+}
+
+}  // namespace traccc::edm

core/include/traccc/edm/impl/track_fit_collection.ipp

@@ -0,0 +1,21 @@
+/** TRACCC library, part of the ACTS project (R&D line)
+ *
+ * (c) 2022-2025 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+
+#pragma once
+
+namespace traccc::edm {
+
+template <typename BASE>
+TRACCC_HOST_DEVICE void track_fit<BASE>::reset_quality() {
+
+    ndf() = {};
+    chi2() = {};
+    pval() = {};
+    nholes() = {};
+}
+
+}  // namespace traccc::edm

core/include/traccc/edm/impl/track_state_collection.ipp

@@ -0,0 +1,44 @@
+/** TRACCC library, part of the ACTS project (R&D line)
+ *
+ * (c) 2022-2025 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+
+#pragma once
+
+namespace traccc::edm {
+
+template <typename BASE>
+TRACCC_HOST_DEVICE bool track_state<BASE>::is_hole() const {
+
+    return (state() & IS_HOLE_MASK);
+}
+
+template <typename BASE>
+TRACCC_HOST_DEVICE void track_state<BASE>::set_hole(bool value) {
+
+    if (value) {
+        state() |= IS_HOLE_MASK;
+    } else {
+        state() &= ~IS_HOLE_MASK;
+    }
+}
+
+template <typename BASE>
+TRACCC_HOST_DEVICE bool track_state<BASE>::is_smoothed() const {
+
+    return (state() & IS_SMOOTHED_MASK);
+}
+
+template <typename BASE>
+TRACCC_HOST_DEVICE void track_state<BASE>::set_smoothed(bool value) {
+
+    if (value) {
+        state() |= IS_SMOOTHED_MASK;
+    } else {
+        state() &= ~IS_SMOOTHED_MASK;
+    }
+}
+
+}  // namespace traccc::edm

core/include/traccc/edm/impl/track_state_helpers.ipp

@@ -0,0 +1,39 @@
+/** TRACCC library, part of the ACTS project (R&D line)
+ *
+ * (c) 2025 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+
+#pragma once
+
+namespace traccc::edm {
+
+template <typename algebra_t>
+TRACCC_HOST_DEVICE
+    typename track_state_collection<algebra_t>::device::object_type
+    make_track_state(
+        const measurement_collection_types::const_device& measurements,
+        unsigned int mindex) {
+
+    // Create the result object.
+    typename track_state_collection<algebra_t>::device::object_type state{
+        track_state_collection<algebra_t>::device::object_type::IS_HOLE_MASK,
+        0.f,
+        0.f,
+        0.f,
+        {},
+        {},
+        mindex};
+
+    // Set the correct surface link for the track parameters.
+    state.filtered_params().set_surface_link(
+        measurements.at(mindex).surface_link);
+    state.smoothed_params().set_surface_link(
+        measurements.at(mindex).surface_link);
+
+    // Return the initialized state.
+    return state;
+}
+
+}  // namespace traccc::edm

core/include/traccc/edm/measurement_helpers.hpp

@@ -0,0 +1,46 @@
+/** TRACCC library, part of the ACTS project (R&D line)
+ *
+ * (c) 2025 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+
+#pragma once
+
+// Local include(s).
+#include "traccc/definitions/primitives.hpp"
+#include "traccc/definitions/qualifiers.hpp"
+#include "traccc/edm/measurement.hpp"
+
+namespace traccc::edm {
+
+/// Get the local position of a measurement as a matrix
+///
+/// @tparam algebra_t The algebra type used to describe the tracks
+/// @tparam size_t The type of the matrix size variable
+/// @tparam D The dimension of the matrix
+///
+/// @param meas The measurement to extract the local position from
+/// @param pos The matrix to fill with the local position of the measurement
+///
+template <detray::concepts::algebra algebra_t, std::integral size_t, size_t D>
+TRACCC_HOST_DEVICE void get_measurement_local(
+    const measurement& meas, detray::dmatrix<algebra_t, D, 1>& pos);
+
+/// Get the covariance of a measurement as a matrix
+///
+/// @tparam algebra_t The algebra type used to describe the tracks
+/// @tparam size_t The type of the matrix size variable
+/// @tparam D The dimension of the matrix
+///
+/// @param meas The measurement to extract the covariance from
+/// @param cov The matrix to fill with the covariance of the measurement
+///
+template <detray::concepts::algebra algebra_t, std::integral size_t, size_t D>
+TRACCC_HOST_DEVICE void get_measurement_covariance(
+    const measurement& meas, detray::dmatrix<algebra_t, D, D>& cov);
+
+}  // namespace traccc::edm
+
+// Include the implementation.
+#include "traccc/edm/impl/measurement_helpers.ipp"

core/include/traccc/edm/track_candidate_container.hpp

@@ -8,6 +8,7 @@
 #pragma once
 
 // Local include(s).
+#include "traccc/definitions/qualifiers.hpp"
 #include "traccc/edm/measurement.hpp"
 #include "traccc/edm/track_candidate_collection.hpp"
 
@@ -71,6 +72,28 @@ struct track_candidate_container {
         measurement_collection_types::const_view measurements;
     };
 
+    struct device {
+        /// Constructor from a view
+        TRACCC_HOST_DEVICE
+        explicit device(const view& v)
+            : tracks{v.tracks}, measurements{v.measurements} {}
+        /// The track candidates
+        track_candidate_collection<ALGEBRA>::device tracks;
+        /// Measurements referenced by the tracks
+        measurement_collection_types::const_device measurements;
+    };
+
+    struct const_device {
+        /// Constructor from a view
+        TRACCC_HOST_DEVICE
+        explicit const_device(const const_view& v)
+            : tracks{v.tracks}, measurements{v.measurements} {}
+        /// The track candidates
+        track_candidate_collection<ALGEBRA>::const_device tracks;
+        /// Measurements referenced by the tracks
+        measurement_collection_types::const_device measurements;
+    };
+
 };  // struct track_candidate_container
 
 }  // namespace traccc::edm