Ref: Add concepts and restructure io directories (#911)

Restructure the io folder to make it easier to understand which classes are part of the backend and which belong to the frontend:

    merge the json reader and writer to the json_converter. This way only the backend types are called "reader" and "writer"
    rename the "common" folder to "backend"
    move the detector related concepts to detray/core

Also factors out a function read_components_from_file from the detector reader, so that readers can be added to a detector construction workflow without calling the read_detector function (e.g. if some components should be read from file, while others are built/converted directly).

I tried to fix a nullptr dereferencing warning in the surface_factory_interface that appeared with gcc 14, but it seems to be a false positive

Author: niermann999

core/include/detray/builders/surface_factory_interface.hpp

@@ -7,13 +7,19 @@
 
 #pragma once
 
+// TODO: Remove this when gcc fixes their false positives.
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC diagnostic warning "-Wnull-dereference"
+#endif
+
 // Project include(s).
 #include "detray/definitions/detail/indexing.hpp"
 #include "detray/definitions/detail/qualifiers.hpp"
 #include "detray/definitions/geometry.hpp"
 
 // System include(s)
 #include <memory>
+#include <stdexcept>
 #include <tuple>
 #include <vector>
 
@@ -160,7 +166,11 @@ class factory_decorator : public surface_factory_interface<detector_t> {
     explicit factory_decorator(
         std::unique_ptr<surface_factory_interface<detector_t>> factory)
         : m_factory(std::move(factory)) {
-        assert(m_factory != nullptr);
+        if (m_factory == nullptr || m_factory.get() == nullptr) {
+            throw std::runtime_error(
+                "Surface factory decorator constructed with invalid base "
+                "factory");
+        }
     }
 
     /// @returns access to the underlying factory - const

core/include/detray/core/concepts.hpp

@@ -0,0 +1,46 @@
+/** 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/core/detail/type_traits.hpp"
+
+namespace detray::concepts {
+
+/// Check for the the presence of any type of grids in a detector definition
+template <class detector_t>
+concept has_grids = detail::contains_grids_v<typename detector_t::accel> ||
+                    detail::contains_grids_v<typename detector_t::materials>;
+
+/// Check for the the presence of surface grids in a detector definition
+template <class detector_t>
+concept has_surface_grids =
+    detail::contains_surface_grids_v<typename detector_t::accel>;
+
+/// Check for the the presence of material slabs in a detector definition
+template <class detector_t>
+concept has_material_slabs =
+    detail::contains_material_slabs_v<typename detector_t::materials>;
+
+/// Check for the the presence of material rods in a detector definition
+template <class detector_t>
+concept has_material_rods =
+    detail::contains_material_rods_v<typename detector_t::materials>;
+
+/// Check for the the presence of homogeneous material types in a detector
+/// definition
+template <class detector_t>
+concept has_homogeneous_material =
+    detail::contains_homogeneous_material_v<typename detector_t::materials>;
+
+/// Check for the the presence of material maps in a detector definition
+template <class detector_t>
+concept has_material_maps =
+    detail::contains_material_maps_v<typename detector_t::materials>;
+
+}  // namespace detray::concepts

io/include/detray/io/frontend/detail/type_traits.hpp core/include/detray/core/detail/type_traits.hpp

@@ -1,6 +1,6 @@
 /** Detray library, part of the ACTS project (R&D line)
  *
- * (c) 2023-2024 CERN for the benefit of the ACTS project
+ * (c) 2022-2025 CERN for the benefit of the ACTS project
  *
  * Mozilla Public License Version 2.0
  */
@@ -14,14 +14,11 @@
 #include "detray/navigation/accelerators/concepts.hpp"
 #include "detray/utils/grid/detail/concepts.hpp"
 #include "detray/utils/type_registry.hpp"
-#include "detray/utils/type_traits.hpp"
 
 // System include(s)
 #include <type_traits>
 
-namespace detray {
-
-namespace detail {
+namespace detray::detail {
 
 /// Check for grid types in a data store
 /// @{
@@ -115,41 +112,4 @@ inline constexpr bool contains_material_maps_v =
     contains_material_maps<T>::value;
 /// @}
 
-}  // namespace detail
-
-namespace concepts {
-
-/// Check for the the presence of any type of grids in a detector definition
-template <class detector_t>
-concept has_grids = detail::contains_grids_v<typename detector_t::accel> ||
-                    detail::contains_grids_v<typename detector_t::materials>;
-
-/// Check for the the presence of surface grids in a detector definition
-template <class detector_t>
-concept has_surface_grids =
-    detail::contains_surface_grids_v<typename detector_t::accel>;
-
-/// Check for the the presence of material slabs in a detector definition
-template <class detector_t>
-concept has_material_slabs =
-    detail::contains_material_slabs_v<typename detector_t::materials>;
-
-/// Check for the the presence of material rods in a detector definition
-template <class detector_t>
-concept has_material_rods =
-    detail::contains_material_rods_v<typename detector_t::materials>;
-
-/// Check for the the presence of homogeneous material types in a detector
-/// definition
-template <class detector_t>
-concept has_homogeneous_material =
-    detail::contains_homogeneous_material_v<typename detector_t::materials>;
-
-/// Check for the the presence of material maps in a detector definition
-template <class detector_t>
-concept has_material_maps =
-    detail::contains_material_maps_v<typename detector_t::materials>;
-
-}  // namespace concepts
-
-}  // namespace detray
+}  // namespace detray::detail

io/CMakeLists.txt

@@ -21,12 +21,14 @@ detray_add_library( detray_io_utils io_utils
 file(
     GLOB _detray_io_public_headers
     RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}"
-    "include/detray/io/common/*.hpp"
+    "include/detray/io/backend/*.hpp"
+    "include/detray/io/backend/detail/*.hpp"
     "include/detray/io/covfie/*.hpp"
     "include/detray/io/frontend/*.hpp"
     "include/detray/io/frontend/detail/*.hpp"
-    "include/detray/io/frontend/implementation/*.hpp"
+    "include/detray/io/frontend/impl/*.hpp"
     "include/detray/io/json/*.hpp"
+    "include/detray/io/json/detail/*.hpp"
 )
 detray_add_library( detray_io io
    ${_detray_io_public_headers}

io/include/detray/io/backend/concepts.hpp

@@ -0,0 +1,51 @@
+/** 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/builders/detector_builder.hpp"
+
+// System include(s)
+#include <concepts>
+#include <string_view>
+
+namespace detray::io::concepts {
+
+/// Concept for detray io reader backends
+template <typename D, typename R>
+concept reader_backend =
+    requires(const R rb, detector_builder<typename D::metadata> det_builder,
+             typename D::name_map names) {
+
+    typename R::payload_type;
+
+    { R::tag }
+    ->std::same_as<const std::string_view&>;
+
+    {
+        R::template from_payload<D>(det_builder, names,
+                                    typename R::payload_type())
+    }
+    ->std::same_as<void>;
+};
+
+/// Concept for detray io writer backends
+template <typename D, typename W>
+concept writer_backend = requires(const W wb, D det,
+                                  typename D::name_map names) {
+
+    typename W::payload_type;
+
+    { W::tag }
+    ->std::same_as<const std::string_view&>;
+
+    { W::to_payload(det, names) }
+    ->std::same_as<typename W::payload_type>;
+};
+
+}  // namespace detray::io::concepts

io/include/detray/io/common/detail/basic_converter.hpp io/include/detray/io/backend/detail/basic_converter.hpp

@@ -1,29 +1,29 @@
 /** Detray library, part of the ACTS project (R&D line)
  *
- * (c) 2023-2024 CERN for the benefit of the ACTS project
+ * (c) 2023-2025 CERN for the benefit of the ACTS project
  *
  * Mozilla Public License Version 2.0
  */
 
 #pragma once
 
 // Project include(s)
-#include "detray/io/frontend/detail/io_metadata.hpp"
 #include "detray/io/frontend/payloads.hpp"
+#include "detray/io/utils/io_metadata.hpp"
 
 // System include(s)
 #include <string_view>
 
-// Convert basic information like links and header data
+// Convert basic information like links and header data to and from payloads
 namespace detray::io::detail::basic_converter {
 
 /// @returns a link from its io payload @param link_data
-inline dindex convert(const single_link_payload& link_data) {
+inline dindex from_payload(const single_link_payload& link_data) {
     return static_cast<dindex>(link_data.link);
 }
 
 /// Convert a link @param idx into its io payload
-inline single_link_payload convert(const std::size_t idx) {
+inline single_link_payload to_payload(const std::size_t idx) {
     single_link_payload link_data;
     link_data.link = idx;
 
@@ -33,8 +33,8 @@ inline single_link_payload convert(const std::size_t idx) {
 /// Convert a typed link with a type id @param id and index @param idx into its
 /// io payload
 template <typename type_id>
-inline typed_link_payload<type_id> convert(const type_id id,
-                                           const std::size_t idx) {
+inline typed_link_payload<type_id> to_payload(const type_id id,
+                                              const std::size_t idx) {
     typed_link_payload<type_id> link_data;
 
     link_data.type = id;
@@ -46,8 +46,8 @@ inline typed_link_payload<type_id> convert(const type_id id,
 /// Convert the common header information using the detector name
 /// @param det_name and the file tag @param tag that describes the data file
 /// content
-inline common_header_payload convert(const std::string_view det_name,
-                                     const std::string_view tag) {
+inline common_header_payload to_payload(const std::string_view det_name,
+                                        const std::string_view tag) {
     common_header_payload header_data;
 
     header_data.version = io::detail::get_detray_version();