Intersection configuration (#1082)

Move the mask tolerances into dedicated config in order to clean up interfaces. Also moves intersection kernel file into the intersection folder

Author: niermann999

core/include/detray/navigation/detail/print_state.hpp

@@ -121,8 +121,9 @@ DETRAY_HOST inline std::string print_candidates(const state_type &state,
     constexpr int cw{20};
 
     debug_stream << std::left << std::setw(cw) << "Overstep tol.:"
-                 << cfg.overstep_tolerance / detray::unit<scalar_t>::um << " um"
-                 << std::endl;
+                 << cfg.intersection.overstep_tolerance /
+                        detray::unit<scalar_t>::um
+                 << " um" << std::endl;
 
     debug_stream << std::setw(cw) << "Track:"
                  << "pos: [r = " << vector::perp(track_pos)

core/include/detray/navigation/direct_navigator.hpp

@@ -17,8 +17,8 @@
 #include "detray/definitions/units.hpp"
 #include "detray/geometry/barcode.hpp"
 #include "detray/navigation/intersection/intersection.hpp"
+#include "detray/navigation/intersection/intersection_kernel.hpp"
 #include "detray/navigation/intersection/ray_intersector.hpp"
-#include "detray/navigation/intersection_kernel.hpp"
 #include "detray/navigation/navigation_config.hpp"
 #include "detray/navigation/navigation_state.hpp"
 #include "detray/navigation/navigator.hpp"
@@ -196,7 +196,7 @@ class direct_navigator {
         }
 
         assert(!navigation.get_target_barcode().is_invalid());
-        update_intersection(track, navigation, cfg, ctx);
+        update_intersection(track, navigation, cfg.intersection, ctx);
 
         if (is_before_actor_run) {
             if (navigation.has_reached_candidate(navigation.target(), cfg)) {
@@ -209,7 +209,8 @@ class direct_navigator {
                                                         cfg));
 
                 if (!navigation.no_next_external()) {
-                    update_intersection(track, navigation, cfg, ctx);
+                    update_intersection(track, navigation, cfg.intersection,
+                                        ctx);
                 }
 
                 DETRAY_VERBOSE_HOST_DEVICE("Update complete: On surface");
@@ -234,7 +235,8 @@ class direct_navigator {
     private:
     template <typename track_t>
     DETRAY_HOST_DEVICE inline void update_intersection(
-        const track_t &track, state &navigation, const navigation::config &cfg,
+        const track_t &track, state &navigation,
+        const intersection::config &intr_cfg,
         const context_type &ctx = {}) const {
 
         if (navigation.target().sf_desc.barcode().is_invalid()) {
@@ -250,11 +252,8 @@ class direct_navigator {
                     track.pos(),
                     static_cast<scalar_type>(navigation.direction()) *
                         track.dir()),
-                navigation.target(), det.transform_store(), ctx,
-                cfg.template mask_tolerance<scalar_type>(),
-                static_cast<scalar_type>(cfg.mask_tolerance_scalor),
-                scalar_type{0.f},
-                static_cast<scalar_type>(cfg.overstep_tolerance));
+                navigation.target(), det.transform_store(), ctx, intr_cfg,
+                scalar_type{0.f});
 
         // If an intersection is not found, proceed the track with safe step
         // size

core/include/detray/navigation/intersection/intersection_config.hpp

@@ -0,0 +1,52 @@
+/** Detray 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
+
+// Project include(s)
+#include "detray/definitions/detail/qualifiers.hpp"
+#include "detray/definitions/units.hpp"
+
+// System include(s)
+#include <ostream>
+
+namespace detray::intersection {
+
+/// Intersector configuration
+struct config {
+    /// Tolerance on the mask 'is_inside' check:
+    /// @{
+    /// Minimal tolerance: ~ position uncertainty on surface
+    float min_mask_tolerance{1e-5f * unit<float>::mm};
+    /// Maximal tolerance: loose tolerance when still far away from surface
+    float max_mask_tolerance{3.f * unit<float>::mm};
+    /// Scale factor on the path used for the mask tolerance calculation
+    float mask_tolerance_scalor{5e-2f};
+    /// @}
+    /// Maximal absolute path distance for a track to be considered 'on surface'
+    float path_tolerance{1.f * unit<float>::um};
+    /// How far behind the track position to look for candidates
+    float overstep_tolerance{-1000.f * unit<float>::um};
+
+    /// Print the intersector configuration
+    DETRAY_HOST
+    friend std::ostream& operator<<(std::ostream& out, const config& cfg) {
+        out << "  Min. mask tolerance   : "
+            << cfg.min_mask_tolerance / detray::unit<float>::mm << " [mm]\n"
+            << "  Max. mask tolerance   : "
+            << cfg.max_mask_tolerance / detray::unit<float>::mm << " [mm]\n"
+            << "  Mask tolerance scalor : " << cfg.mask_tolerance_scalor << "\n"
+            << "  Path tolerance        : "
+            << cfg.path_tolerance / detray::unit<float>::um << " [um]\n"
+            << "  Overstep tolerance    : "
+            << cfg.overstep_tolerance / detray::unit<float>::um << " [um]\n";
+
+        return out;
+    }
+};
+
+}  // namespace detray::intersection

core/include/detray/navigation/intersection_kernel.hpp renamed to core/include/detray/navigation/intersection/intersection_kernel.hpp

@@ -14,6 +14,7 @@
 #include "detray/definitions/units.hpp"
 #include "detray/geometry/concepts.hpp"
 #include "detray/navigation/intersection/intersection.hpp"
+#include "detray/navigation/intersection/intersection_config.hpp"
 #include "detray/tracks/ray.hpp"
 #include "detray/utils/ranges.hpp"
 
@@ -50,11 +51,8 @@ struct intersection_initialize {
         const surface_t &sf_desc,
         const transform_container_t &contextual_transforms,
         const typename transform_container_t::context_type &ctx,
-        const darray<scalar_t, 2u> &mask_tolerance = {0.f,
-                                                      1.f * unit<scalar_t>::mm},
-        const scalar_t mask_tol_scalor = 0.f,
-        const scalar_t external_mask_tolerance = 0.f,
-        const scalar_t overstep_tol = 0.f) const {
+        const intersection::config &cfg,
+        const scalar_t external_mask_tolerance = 0.f) const {
 
         using mask_t = typename mask_group_t::value_type;
         using shape_t = typename mask_t::shape;
@@ -82,9 +80,10 @@ struct intersection_initialize {
             assert(mask_idx < mask_group.size());
 
             result = intersector.point_of_intersection(
-                traj, ctf, mask_group[mask_idx], overstep_tol);
+                traj, ctf, mask_group[mask_idx], cfg.overstep_tolerance);
         } else {
-            result = intersector.point_of_intersection(traj, ctf, overstep_tol);
+            result = intersector.point_of_intersection(traj, ctf,
+                                                       cfg.overstep_tolerance);
         }
 
         // Check if any valid solutions were found
@@ -115,9 +114,8 @@ struct intersection_initialize {
                 std::uint8_t n_found{0u};
 
                 for (std::size_t i = 0u; i < n_sol; ++i) {
-                    resolve_mask(is, traj, result[i], sf_desc, mask, ctf,
-                                 mask_tolerance, mask_tol_scalor,
-                                 external_mask_tolerance, overstep_tol);
+                    resolve_mask(is, traj, result[i], sf_desc, mask, ctf, cfg,
+                                 external_mask_tolerance);
 
                     if (is.is_probably_inside()) {
                         insert_sorted(is, is_container);
@@ -128,9 +126,8 @@ struct intersection_initialize {
                     }
                 }
             } else {
-                resolve_mask(is, traj, result, sf_desc, mask, ctf,
-                             mask_tolerance, mask_tol_scalor,
-                             external_mask_tolerance, overstep_tol);
+                resolve_mask(is, traj, result, sf_desc, mask, ctf, cfg,
+                             external_mask_tolerance);
 
                 if (is.is_probably_inside()) {
                     insert_sorted(is, is_container);
@@ -181,11 +178,8 @@ struct intersection_update {
         const traj_t &traj, intersection_t &sfi,
         const transform_container_t &contextual_transforms,
         const typename transform_container_t::context_type &ctx,
-        const darray<scalar_t, 2u> &mask_tolerance = {0.f,
-                                                      1.f * unit<scalar_t>::mm},
-        const scalar_t mask_tol_scalor = 0.f,
-        const scalar_t external_mask_tolerance = 0.f,
-        const scalar_t overstep_tol = 0.f) const {
+        const intersection::config &cfg,
+        const scalar_t external_mask_tolerance = 0.f) const {
 
         using mask_t = typename mask_group_t::value_type;
         using shape_t = typename mask_t::shape;
@@ -212,9 +206,10 @@ struct intersection_update {
             assert(mask_idx < mask_group.size());
 
             result = intersector.point_of_intersection(
-                traj, ctf, mask_group[mask_idx], overstep_tol);
+                traj, ctf, mask_group[mask_idx], cfg.overstep_tolerance);
         } else {
-            result = intersector.point_of_intersection(traj, ctf, overstep_tol);
+            result = intersector.point_of_intersection(traj, ctf,
+                                                       cfg.overstep_tolerance);
         }
 
         // Check if any valid solutions were found
@@ -240,13 +235,11 @@ struct intersection_update {
 
             // Build the resulting intersecion(s) from the intersection point
             if constexpr (n_sol > 1) {
-                resolve_mask(sfi, traj, result[0], sfi.sf_desc, mask, ctf,
-                             mask_tolerance, mask_tol_scalor,
-                             external_mask_tolerance, overstep_tol);
+                resolve_mask(sfi, traj, result[0], sfi.sf_desc, mask, ctf, cfg,
+                             external_mask_tolerance);
             } else {
-                resolve_mask(sfi, traj, result, sfi.sf_desc, mask, ctf,
-                             mask_tolerance, mask_tol_scalor,
-                             external_mask_tolerance, overstep_tol);
+                resolve_mask(sfi, traj, result, sfi.sf_desc, mask, ctf, cfg,
+                             external_mask_tolerance);
             }
 
             if (sfi.is_probably_inside()) {

core/include/detray/navigation/intersection/intersector_base.hpp

@@ -16,6 +16,7 @@
 #include "detray/geometry/concepts.hpp"
 #include "detray/geometry/detail/shape_utils.hpp"
 #include "detray/navigation/intersection/intersection.hpp"
+#include "detray/navigation/intersection/intersection_config.hpp"
 #include "detray/utils/invalid_values.hpp"
 
 // System include(s)
@@ -76,18 +77,14 @@ struct intersector_base : public intersector_t {
     DETRAY_HOST_DEVICE constexpr intersection_type<surface_descr_t> operator()(
         const trajectory_type<other_algebra_t> &traj, const surface_descr_t &sf,
         const mask_t &mask, const transform3_type &trf,
-        const darray<scalar_type, 2u> mask_tolerance =
-            {0.f, 1.f * unit<value_type>::mm},
-        const scalar_type mask_tol_scalor = 0.f,
-        const scalar_type external_mask_tol = 0.f,
-        const scalar_type overstep_tol = 0.f) const {
+        const intersection::config &cfg = {},
+        const scalar_type external_mask_tol = 0.f) const {
 
-        result_type result = call_intersector(traj, mask, trf, overstep_tol);
+        result_type result =
+            call_intersector(traj, mask, trf, cfg.overstep_tolerance);
 
         intersection_type<surface_descr_t> is;
-
-        resolve_mask(is, traj, result, sf, mask, trf, mask_tolerance,
-                     mask_tol_scalor, external_mask_tol, overstep_tol);
+        resolve_mask(is, traj, result, sf, mask, trf, cfg, external_mask_tol);
 
         return is;
     }
@@ -100,23 +97,19 @@ struct intersector_base : public intersector_t {
                                         n_solutions>
     operator()(const trajectory_type<other_algebra_t> &traj,
                const surface_descr_t &sf, const mask_t &mask,
-               const transform3_type &trf,
-               const darray<scalar_type, 2u> mask_tolerance =
-                   {0.f, 100.f * unit<value_type>::um},
-               const scalar_type mask_tol_scalor = 0.f,
-               const scalar_type external_mask_tol = 0.f,
-               const scalar_type overstep_tol = 0.f) const {
+               const transform3_type &trf, const intersection::config &cfg = {},
+               const scalar_type external_mask_tol = 0.f) const {
 
         // One or both of these solutions might be invalid
-        result_type result = call_intersector(traj, mask, trf, overstep_tol);
+        result_type result =
+            call_intersector(traj, mask, trf, cfg.overstep_tolerance);
 
         darray<intersection_type<surface_descr_t>, n_solutions> ret;
 
         for (std::size_t i = 0u; i < n_solutions; ++i) {
             if (detray::detail::any_of(result[i].is_valid())) {
-                resolve_mask(ret[i], traj, result[i], sf, mask, trf,
-                             mask_tolerance, mask_tol_scalor, external_mask_tol,
-                             overstep_tol);
+                resolve_mask(ret[i], traj, result[i], sf, mask, trf, cfg,
+                             external_mask_tol);
             }
         }
 
@@ -135,9 +128,13 @@ struct intersector_base : public intersector_t {
         const scalar_type mask_tolerance,
         const scalar_type overstep_tol = 0.f) const {
 
-        return this->operator()(traj, sf, mask, trf,
-                                {mask_tolerance, mask_tolerance}, 0.f, 0.f,
-                                overstep_tol);
+        const intersection::config intr_cfg{
+            .min_mask_tolerance = static_cast<float>(mask_tolerance),
+            .max_mask_tolerance = static_cast<float>(mask_tolerance),
+            .mask_tolerance_scalor = 0.f,
+            .overstep_tolerance = static_cast<float>(overstep_tol)};
+
+        return this->operator()(traj, sf, mask, trf, intr_cfg, 0.f);
     }
 
     private:
@@ -176,23 +173,21 @@ DETRAY_HOST_DEVICE constexpr void resolve_mask(
     const intersection_point<algebra_t, point_t, intersection::contains_pos>
         &ip,
     const surface_descr_t sf_desc, const mask_t &mask, const transform3_t &trf,
-    const darray<scalar_t, 2> &mask_tolerance,
-    const scalar_t mask_tol_scalor = 0.f,
-    const scalar_t external_mask_tolerance = 0.f,
-    const scalar_t overstep_tol = 0.f) {
+    const intersection::config &cfg = {},
+    const scalar_t external_mask_tolerance = 0.f) {
 
     // Mask out solutions that don't meet the overstepping tolerance (SoA)
     if constexpr (concepts::soa<algebra_t>) {
         using status_t = typename intersection_t::status_t;
 
-        is.status(is.path() < overstep_tol) =
+        is.status(is.path() < cfg.overstep_tolerance) =
             static_cast<status_t>(intersection::status::e_outside);
     } else {
         is.set_status(intersection::status::e_outside);
     }
 
     // Build intersection struct from test trajectory, if the distance is valid
-    if (detray::detail::none_of(ip.path >= overstep_tol)) {
+    if (detray::detail::none_of(ip.path >= cfg.overstep_tolerance)) {
         // Not a valid intersection
         return;
     }
@@ -219,21 +214,28 @@ DETRAY_HOST_DEVICE constexpr void resolve_mask(
             mask_t::to_local_frame3D(trf, glob_pos, traj.dir(ip.path)));
     }
 
+    scalar_t base_tol = 0.f;
+    scalar_t ext_tol = 0.f;
+
     // Tol.: scale with distance of surface to account for track bending
-    const scalar_t base_tol = math::max(
-        mask_tolerance[0],
-        math::min(mask_tolerance[1], mask_tol_scalor * math::fabs(ip.path)));
+    if (!sf_desc.is_portal()) {
+        ext_tol = external_mask_tolerance;
+        base_tol = math::max(
+            static_cast<scalar_t>(cfg.min_mask_tolerance),
+            math::min(static_cast<scalar_t>(cfg.max_mask_tolerance),
+                      static_cast<scalar_t>(cfg.mask_tolerance_scalor) *
+                          math::fabs(ip.path)));
+    }
 
     // Mask check results with and without external tolerance
     typename mask_t::result_type mask_check{};
 
     // Intersector provides specialized local point
     if constexpr (std::same_as<point_t, dpoint2D<algebra_t>>) {
-        mask_check = mask.resolve(ip.point, base_tol, external_mask_tolerance);
+        mask_check = mask.resolve(ip.point, base_tol, ext_tol);
     } else {
         // Otherwise, let the shape transform the point to local
-        mask_check =
-            mask.resolve(trf, ip.point, base_tol, external_mask_tolerance);
+        mask_check = mask.resolve(trf, ip.point, base_tol, ext_tol);
     }
 
     // Set the less strict status first, then overwrite with more strict