feat: python generators for detector metadata

CMakeLists.txt

@@ -45,6 +45,8 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY
     "Directory for the built static libraries"
 )
 
+set(DETRAY_PYTHON_INSTALL_DIR "python/detray")
+
 # Include the Detray CMake code.
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 include(detray-functions)
@@ -67,6 +69,11 @@ set_property(
     PROPERTY STRINGS "NONE" "WARNING" "INFO" "VERBOSE" "DEBUG"
 )
 option(DETRAY_BUILD_CLI_TOOLS "Build the command line tools of Detray" OFF)
+option(
+    DETRAY_BUILD_PYTHON_BINDINGS
+    "Build python bindings for all enabled components"
+    OFF
+)
 
 # Device compilation
 
@@ -83,7 +90,6 @@ option(DETRAY_BUILD_SYCL "Build the SYCL sources included in detray" OFF)
 
 # Check if HIP is available
 option(DETRAY_BUILD_HIP "Build the HIP sources included in detray" OFF)
-
 cmake_dependent_option(
     DETRAY_BUILD_HOST
     "Build the host sources included in detray"
@@ -132,7 +138,23 @@ elseif(DETRAY_SET_LOGGING STREQUAL "DEBUG")
     set(DETRAY_LOG_LVL 3 CACHE INTERNAL "Print expert information" FORCE)
 endif()
 
-# Need test utils for the example detector generation
+#
+# Resolve build options and option dependencies
+#
+
+# Set the internal log level from user input
+set(DETRAY_LOG_LVL -1 CACHE INTERNAL "Disable logging")
+if(DETRAY_SET_LOGGING STREQUAL "WARN")
+    set(DETRAY_LOG_LVL 0 CACHE INTERNAL "Print warnings and errors" FORCE)
+elseif(DETRAY_SET_LOGGING STREQUAL "INFO")
+    set(DETRAY_LOG_LVL 1 CACHE INTERNAL "Print general information" FORCE)
+elseif(DETRAY_SET_LOGGING STREQUAL "VERBOSE")
+    set(DETRAY_LOG_LVL 2 CACHE INTERNAL "Print detailed information" FORCE)
+elseif(DETRAY_SET_LOGGING STREQUAL "DEBUG")
+    set(DETRAY_LOG_LVL 3 CACHE INTERNAL "Print expert information" FORCE)
+endif()
+
+# Need test utils in CLI tools for the example detector generation
 if(DETRAY_BUILD_CLI_TOOLS)
     set(DETRAY_BUILD_TEST_UTILS ON)
 endif()
@@ -145,12 +167,9 @@ if(${DETRAY_BUILD_CUDA} AND ${CMAKE_CUDA_STANDARD} LESS 20)
     )
 endif()
 
-if(${DETRAY_BUILD_SYCL} AND ${CMAKE_SYCL_STANDARD} LESS 20)
-    message(
-        SEND_ERROR
-        "CMAKE_SYCL_STANDARD=${CMAKE_SYCL_STANDARD}, but detray requires C++>=20"
-    )
-endif()
+#
+# Configure dependencies
+#
 
 if(${DETRAY_BUILD_HIP} AND ${CMAKE_HIP_STANDARD} LESS 20)
     message(
@@ -461,11 +480,15 @@ if(DETRAY_SETUP_COVFIE)
     endif()
 endif()
 
+#
 # Set up all of the libraries of the project.
+#
+
 add_subdirectory(core)
 add_subdirectory(detectors)
 add_subdirectory(io)
 add_subdirectory(plugins)
+add_subdirectory(python)
 
 # Test utils and validation tools can also be required standalone
 # (e.g. in ACTS detray plugin)
@@ -479,7 +502,6 @@ if(
     add_subdirectory(tests)
 endif()
 
-# Set up the tutorial(s).
 if(DETRAY_BUILD_TUTORIALS)
     add_subdirectory(tutorials)
 endif()

README.md

@@ -62,13 +62,13 @@ The following cmake options are available and can also be specified explicitly f
 | DETRAY_SET_LOGGING  | Set log level (NONE, WARN, INFO, VERBOSE, DEBUG) | INFO |
 | DETRAY_BUILD_CUDA  | Build the CUDA sources included in detray | ON (if available) |
 | DETRAY_BUILD_SYCL  | Build the SYCL sources included in detray | OFF |
-| DETRAY_BUILD_TEST_UTILS  | Build the detray test utilities library (contains e.g. test detectors) | OFF |
-| DETRAY_BUILD_UNITTESTS  | Build the detray unit tests | OFF |
-| DETRAY_BUILD_INTEGRATIONTESTS  | Build the detray integration tests | OFF |
-| DETRAY_BUILD_ALL_TESTS  | Build the detray unit and integration tests | OFF |
-| DETRAY_BUILD_BENCHMARKS  | Build the detray benchmarks | OFF |
 | DETRAY_BUILD_CLI_TOOLS  | Build the detray command line tools | OFF |
+| DETRAY_BUILD_BENCHMARKS  | Build the detray benchmarks | OFF |
 | DETRAY_BUILD_TUTORIALS  | Build the examples of detray | OFF |
+| DETRAY_BUILD_ALL_TESTS  | Build the detray unit and integration tests | OFF |
+| DETRAY_BUILD_UNITTESTS  | Build the detray unit tests | OFF |
+| DETRAY_BUILD_INTEGRATIONTESTS  | Build the detray integration tests | OFF |
+| DETRAY_BUILD_TEST_UTILS  | Build the detray test utilities library (test detectors etc.) | OFF |
 | DETRAY_CUSTOM_SCALARTYPE | Floating point precision | float |
 | DETRAY_EIGEN_PLUGIN | Build Eigen math plugin | OFF |
 | DETRAY_FASTOR_PLUGIN | Build Fastor math plugin | OFF |
@@ -87,6 +87,10 @@ extra navigation tracing information
 - Moving a detector to device
 - Host and device track propagation
 
+In order to define a custom detector geometry type (called a detector 'metadata'), please follow the instructions in `detray/detectors/README.md`.
+
+Otherwise, the default detector metadata (`#include detray/detectors/default_metadata.hpp`) can be used in most cases to define the detector type, however, incurring increased build times and likely also increased runtime of client algorithms.
+
 ## Detector Validation
 
 Given a detray detector (and optionally also a grid and a material) json file, a number of validation test can be run from the command-line. For this, the library has to be built with the `-DDETRAY_BUILD_CLI_TOOLS=ON` option enabled. An example detector file can then be obtained using e.g.

core/include/detray/builders/cuboid_portal_generator.hpp

@@ -116,7 +116,7 @@ class cuboid_portal_generator final
         auto surfaces_offset{static_cast<dindex>(n_surfaces)};
 
         // Fetch the position in the mask tuple for the rectangle portals
-        constexpr auto rectangle_id{detector_t::masks::id::e_portal_rectangle2};
+        constexpr auto rectangle_id{detector_t::masks::id::e_rectangle2D};
 
         // The material will be added in a later step
         constexpr auto no_material = surface_t::material_id::e_none;

core/include/detray/builders/cylinder_portal_generator.hpp

@@ -305,14 +305,14 @@ class cylinder_portal_generator final
 
         // Add transform and mask data
         transforms.emplace_back(ctx, tsl);
-        masks.template emplace_back<mask_id::e_portal_cylinder2>(
+        masks.template emplace_back<mask_id::e_concentric_cylinder2D>(
             empty_context{}, vol_link, r, min_z, max_z);
 
         // Add surface links
         mask_link_t mask_link{};
         const auto mask_idx{static_cast<dindex>(
-            masks.template size<mask_id::e_portal_cylinder2>() - 1u)};
-        set_mask_link(mask_link, mask_id::e_portal_cylinder2, mask_idx);
+            masks.template size<mask_id::e_concentric_cylinder2D>() - 1u)};
+        set_mask_link(mask_link, mask_id::e_concentric_cylinder2D, mask_idx);
 
         material_link_t material_link{material_id::e_none, dindex_invalid};
 
@@ -341,14 +341,14 @@ class cylinder_portal_generator final
 
         // Add transform and mask data
         transforms.emplace_back(ctx, tsl);
-        masks.template emplace_back<mask_id::e_portal_ring2>(
-            empty_context{}, vol_link, min_r, max_r);
+        masks.template emplace_back<mask_id::e_ring2D>(empty_context{},
+                                                       vol_link, min_r, max_r);
 
         // Add surface links
         mask_link_t mask_link{};
-        const auto mask_idx{static_cast<dindex>(
-            masks.template size<mask_id::e_portal_ring2>() - 1u)};
-        set_mask_link(mask_link, mask_id::e_portal_ring2, mask_idx);
+        const auto mask_idx{
+            static_cast<dindex>(masks.template size<mask_id::e_ring2D>() - 1u)};
+        set_mask_link(mask_link, mask_id::e_ring2D, mask_idx);
 
         material_link_t material_link{material_id::e_none, dindex_invalid};
 

core/include/detray/builders/detail/volume_connector.hpp

@@ -248,8 +248,9 @@ void connect_cylindrical_volumes(
                     0., 0., volume_bounds[bound_index]};
 
                 // Get the mask context group and fill it
-                constexpr auto disc_id = detector_t::masks::id::e_portal_ring2;
-                constexpr auto slab_id = detector_t::materials::id::e_slab;
+                constexpr auto disc_id = detector_t::masks::id::e_ring2D;
+                constexpr auto slab_id =
+                    detector_t::materials::id::e_material_slab;
                 typename portal_t::mask_link mask_index = {
                     disc_id, portal_masks.template size<disc_id>()};
                 typename portal_t::material_link material_index = {
@@ -298,7 +299,8 @@ void connect_cylindrical_volumes(
                     detector_t::masks::id::e_portal_cylinder3;
                 typename portal_t::mask_link mask_index = {
                     cylinder_id, portal_masks.template size<cylinder_id>()};
-                constexpr auto slab_id = detector_t::materials::id::e_slab;
+                constexpr auto slab_id =
+                    detector_t::materials::id::e_material_slab;
 
                 for (auto &info_ : portals_info) {
                     // Add new mask to container

core/include/detray/builders/homogeneous_material_builder.hpp

@@ -97,34 +97,38 @@
         for (auto &sf : this->surfaces()) {
             DETRAY_DEBUG_HOST("-> sf=" << sf);
             DETRAY_DEBUG_HOST("  -> material_id=" << sf.material().id());
-            if (sf.material().id() == material_id::e_slab) {
-                dindex offset = material.template size<material_id::e_slab>();
+            if (sf.material().id() == material_id::e_material_slab) {
+                dindex offset =
+                    material.template size<material_id::e_material_slab>();
                 DETRAY_DEBUG_HOST("-> update material slab offset: " << offset);
                 sf.update_material(offset);
                 DETRAY_DEBUG_HOST("-> material now: " << sf.material());
             }
             if constexpr (types::contains<typename detector_t::materials,
                                           material_rod<scalar_type>>) {
-                if (sf.material().id() == material_id::e_rod) {
+                if (sf.material().id() == material_id::e_material_rod) {
                     DETRAY_DEBUG_HOST(
                         "-> update material rod offset: "
-                        << material.template size<material_id::e_rod>());
+                        << material
+                               .template size<material_id::e_material_rod>());
                     sf.update_material(
-                        material.template size<material_id::e_rod>());
+                        material.template size<material_id::e_material_rod>());
                 }
             }
         }
 
         // Add material to the detector
-        DETRAY_DEBUG_HOST("-> Appending "
-                          << m_materials.template size<material_id::e_slab>()
-                          << " slabs into detector materials");
+        DETRAY_DEBUG_HOST(
+            "-> Appending "
+            << m_materials.template size<material_id::e_material_slab>()
+            << " slabs into detector materials");
 
         if constexpr (types::contains<typename detector_t::materials,
                                       material_rod<scalar_type>>) {
-            DETRAY_DEBUG_HOST("-> Appending "
-                              << m_materials.template size<material_id::e_rod>()
-                              << " rods into detector materials");
+            DETRAY_DEBUG_HOST(
+                "-> Appending "
+                << m_materials.template size<material_id::e_material_rod>()
+                << " rods into detector materials");
         }
         det._materials.append(std::move(m_materials));
         m_materials.clear_all();

core/include/detray/builders/homogeneous_material_factory.hpp

@@ -352,18 +352,19 @@ class homogeneous_material_factory final
             DETRAY_DEBUG_HOST("           mat=" << mat << " thickness=" << t);
 
             dindex mat_idx{0u};
-            if (m_links.at(sf_idx).first == material_id::e_slab) {
-                auto &mat_coll = materials.template get<material_id::e_slab>();
+            if (m_links.at(sf_idx).first == material_id::e_material_slab) {
+                auto &mat_coll =
+                    materials.template get<material_id::e_material_slab>();
 
                 material_slab<scalar_type> mat_slab{mat, t};
                 mat_idx = this->insert_in_container(mat_coll, mat_slab,
                                                     m_links.at(sf_idx).second);
             }
             if constexpr (types::contains<typename detector_t::materials,
                                           material_rod<scalar_type>>) {
-                if (m_links.at(sf_idx).first == material_id::e_rod) {
+                if (m_links.at(sf_idx).first == material_id::e_material_rod) {
                     auto &mat_coll =
-                        materials.template get<material_id::e_rod>();
+                        materials.template get<material_id::e_material_rod>();
 
                     material_rod<scalar_type> mat_rod{mat, t};
                     mat_idx = this->insert_in_container(mat_coll, mat_rod,

core/include/detray/builders/homogeneous_material_generator.hpp

@@ -198,20 +198,21 @@ class homogeneous_material_generator final
                     is_line = true;
 
                     auto &mat_coll =
-                        materials.template get<material_id::e_rod>();
+                        materials.template get<material_id::e_material_rod>();
                     mat_coll.emplace_back(*mat_ptr, m_cfg.thickness());
 
-                    mat_link = {material_id::e_rod,
+                    mat_link = {material_id::e_material_rod,
                                 static_cast<dindex>(mat_coll.size() - 1u)};
                 }
             }
 
             // For all surfaces that are not lines, generate a material slab
             if (!is_line) {
-                auto &mat_coll = materials.template get<material_id::e_slab>();
+                auto &mat_coll =
+                    materials.template get<material_id::e_material_slab>();
                 mat_coll.emplace_back(*mat_ptr, m_cfg.thickness());
 
-                mat_link = {material_id::e_slab,
+                mat_link = {material_id::e_material_slab,
                             static_cast<dindex>(mat_coll.size() - 1u)};
             }
 

core/include/detray/builders/volume_builder.hpp

@@ -53,7 +53,7 @@ class volume_builder : public volume_builder_interface<detector_t> {
         // force method that will at least contain the portals
         m_volume.template set_accel_link<
             static_cast<typename volume_type::object_id>(0)>(
-            detector_t::accel::id::e_default, 0);
+            detector_t::accel::id::e_surface_default, 0);
 
         DETRAY_VERBOSE_HOST("Created builder for volume: " << idx);
     };
@@ -254,7 +254,7 @@ class volume_builder : public volume_builder_interface<detector_t> {
         }
 
         // Place the appropriate surfaces in the brute force search method.
-        constexpr auto default_acc_id{detector_t::accel::id::e_default};
+        constexpr auto default_acc_id{detector_t::accel::id::e_surface_default};
 
         // Strip the source link from the lookup data structure
         typename detector_t::surface_container descriptors;

core/include/detray/core/detector.hpp

@@ -232,7 +232,7 @@ class detector {
         // TODO: Add volume accelerator builder
         volume_type v_desc{};
         v_desc.template set_accel_link<geo_obj_ids::e_volume>(
-            accel::id::e_default_volume_searcher, 0u);
+            accel::id::e_volume_default, 0u);
         tracking_volume world{*this, v_desc};
 
         dindex volume_index{0u};
@@ -248,7 +248,8 @@ class detector {
     DETRAY_HOST_DEVICE
     inline const auto &portals() const {
         // All portals are registered with the brute force search
-        return _accelerators.template get<accel::id::e_brute_force>().all();
+        return _accelerators.template get<accel::id::e_surface_brute_force>()
+            .all();
     }
 
     /// @returns the sub-volumes of the detector - const access

core/include/detray/utils/detector_statistics.hpp

@@ -89,7 +89,7 @@ DETRAY_HOST_DEVICE inline std::size_t n_material_maps(const detector_t& det) {
 template <typename detector_t>
 DETRAY_HOST_DEVICE inline std::size_t n_material_slabs(const detector_t& det) {
     if constexpr (detray::concepts::has_material_slabs<detector_t>) {
-        constexpr auto slab_id{detector_t::materials::id::e_slab};
+        constexpr auto slab_id{detector_t::materials::id::e_material_slab};
         return det.material_store().template size<slab_id>();
     } else {
         return 0u;
@@ -100,7 +100,7 @@ DETRAY_HOST_DEVICE inline std::size_t n_material_slabs(const detector_t& det) {
 template <typename detector_t>
 DETRAY_HOST_DEVICE inline std::size_t n_material_rods(const detector_t& det) {
     if constexpr (detray::concepts::has_material_rods<detector_t>) {
-        constexpr auto rod_id{detector_t::materials::id::e_rod};
+        constexpr auto rod_id{detector_t::materials::id::e_material_rod};
         return det.material_store().template size<rod_id>();
     } else {
         return 0u;

detectors/README.md

@@ -0,0 +1,33 @@
+## Generating custom Detector Metadata
+
+The detector metadata is a C++ `struct` used by the detray core library as a template parameter to gather the compile-time information on the capabilities of the detector modelling, for example:
+
+`using odd_detector_t = detray::detector<detray::odd_metadata<algebra_t>>`,
+
+with the `algebra_t` defined according to the linear algebra backend to be used, for instance the `detray::array<float>` plugin.
+
+A generic metadata type (the default metadata) exists, which comprises most of the geometry modelling capabilities detray has to offer, however, at the expense of increased build times and likely higher runtime of subsequent track reconstruction pipelines. A custom metadata can be defined by providing a python script that configures the detray metadata code generator,
+which can be invoked during the configuration stage of the cmake build:
+```shell
+cmake -S detray -B detray-build -DDETRAY_METADATA_GENERATOR=path/to/custom_metadata.py
+```
+The resulting metadata header, ready to be used in downstream projects, will be available in the `detray/detectors` folder. Example metadata generation scripts, for instance for the ACTS Open Data Detector (ODD detector mentioned above), can be found in the `detray/detectors/python/` folder. They can be invoked manually by:
+```shell
+python3 detray/detectors/python/odd_metadata.py
+```
+
+### Metadata Configuration Manual
+
+Generate a metadata representation and dump the header file:
+
+```python
+from detray.detectors import metadata, metadata_generator
+
+md = metadata("detector_name")
+
+[...]
+
+metadata_generator(md)
+```
+
+Adding surface shapes for passive or sensitive detector elements or portals between detector sub-volumes: