feat: Add examples (#472)

This add example executables:

    build_predefined_detectors : How to build the testing detectors
    detector_ray_scan: How to perform a ray scan on a detector
    do_it_yourself_detector: How to build a detector from scratch, including metadata, a new shape and surface generation
    read_detector_from_file: Uses the json_geometry_reader until the full reader becomes available
    write_detector_to_file: Writes the toy detector to file (geometry and material)
    define_an_actor: Taken from previous tutorial: How to build an actor and a composition of actors
    navigation_inspection: Taken from previous tutorial: How to run a navigation with inspectors and check it against a ray trace

In order to add portals to the example detector, I copied the portal creation from the telescope detector into a new surface generator. I will replace the code in the telescope creation with actual volume builders at some point.

CMakeLists.txt

@@ -60,6 +60,8 @@ option( DETRAY_BUILD_TESTING "Build the (unit) tests of Detray"
    TRUE )
 cmake_dependent_option( DETRAY_BENCHMARKS "Enable benchmark tests" TRUE
    "DETRAY_BUILD_TESTING" OFF )
+option( DETRAY_BUILD_TUTORIALS "Build the tutorial executables of Detray"
+   ON )
 
 # Clean up.
 unset( DETRAY_BUILD_CUDA_DEFAULT )
@@ -209,5 +211,10 @@ if( BUILD_TESTING AND DETRAY_BUILD_TESTING )
    add_subdirectory( tests )
 endif()
 
+# Set up the tutorial(s).
+if( DETRAY_BUILD_TUTORIALS )
+   add_subdirectory( tutorials )
+endif()
+
 # Set up the packaging of the project.
 include( detray-packaging )

cmake/detray-functions.cmake

@@ -133,6 +133,25 @@ function( detray_add_test name )
 
 endfunction( detray_add_test )
 
+# Helper function for setting up the detray tutorials.
+#
+# Usage: detray_add_tutorial( core source1.cpp source2.cpp
+#                             LINK_LIBRARIES detray::core )
+#
+function( detray_add_tutorial name )
+
+   # Parse the function's options.
+   cmake_parse_arguments( ARG "" "" "LINK_LIBRARIES" ${ARGN} )
+
+   # Create the tutorial executable.
+   set( tutorial_exe_name "detray_tutorial_${name}" )
+   add_executable( ${tutorial_exe_name} ${ARG_UNPARSED_ARGUMENTS} )
+   if( ARG_LINK_LIBRARIES )
+      target_link_libraries( ${tutorial_exe_name} PRIVATE ${ARG_LINK_LIBRARIES} )
+   endif()
+
+endfunction( detray_add_tutorial )
+
 # Helper function for adding individual flags to "flag variables".
 #
 # Usage: detray_add_flag( CMAKE_CXX_FLAGS "-Wall" )

core/include/detray/core/detail/multi_store.hpp

@@ -151,6 +151,18 @@ class multi_store {
             detail::get<value_types::to_index(id)>(m_tuple_container).size());
     }
 
+    /// Removes and destructs all elements in the container.
+    template <std::size_t current_idx = 0>
+    DETRAY_HOST_DEVICE auto total_size(const context_type &ctx = {},
+                                       dindex n = 0u) const noexcept -> dindex {
+        n += size<value_types::to_id(current_idx)>(ctx);
+
+        if constexpr (current_idx < sizeof...(Ts) - 1) {
+            return total_size<current_idx + 1>(ctx, n);
+        }
+        return n;
+    }
+
     /// @returns true if the collection given by @tparam ID is empty
     template <ID id>
     DETRAY_HOST_DEVICE constexpr auto empty(

core/include/detray/core/detector.hpp

@@ -178,8 +178,28 @@ class detector {
           _volume_finder(det_data._volume_finder_data),
           _bfield(det_data._bfield_view) {}
 
-    /// Add a new volume and retrieve a reference to it
+    /// Add a new volume and retrieve a reference to it.
     ///
+    /// @param id the shape id for the volume
+    /// @param sf_finder_link of the volume, where to entry the surface finder
+    ///
+    /// @return non-const reference to the new volume
+    DETRAY_HOST
+    volume_type &new_volume(
+        const volume_id id,
+        typename volume_type::link_type::index_type srf_finder_link = {}) {
+        volume_type &cvolume = _volumes.emplace_back(id);
+        cvolume.set_index(static_cast<dindex>(_volumes.size()) - 1u);
+        cvolume
+            .template set_link<static_cast<typename volume_type::object_id>(0)>(
+                srf_finder_link);
+
+        return cvolume;
+    }
+
+    /// Add a new volume and retrieve a reference to it.
+    ///
+    /// @param id the shape id for the volume
     /// @param bounds of the volume, they are expected to be already attaching
     /// @param sf_finder_link of the volume, where to entry the surface finder
     ///
@@ -188,9 +208,8 @@ class detector {
     volume_type &new_volume(
         const volume_id id, const array_type<scalar, 6> &bounds,
         typename volume_type::link_type::index_type srf_finder_link = {}) {
-        volume_type &cvolume = _volumes.emplace_back(id, bounds);
-        cvolume.set_index(static_cast<dindex>(_volumes.size()) - 1u);
-        cvolume.set_link(srf_finder_link);
+        volume_type &cvolume = new_volume(id, srf_finder_link);
+        cvolume.set_bounds(bounds);
 
         return cvolume;
     }
@@ -262,7 +281,7 @@ class detector {
     }
 
     /// @returns surfaces of a given type (@tparam sf_id) by volume - const
-    template <geo_obj_ids sf_id = geo_obj_ids::e_portal>
+    template <geo_obj_ids sf_id = static_cast<geo_obj_ids>(0)>
     DETRAY_HOST_DEVICE constexpr auto surfaces(const volume_type &v) const {
         dindex coll_idx{v.template link<sf_id>().index()};
         const auto sf_coll =
@@ -345,7 +364,7 @@ class detector {
     ///
     /// @note can throw an exception if input data is inconsistent
     // TODO: Provide volume builder structure separate from the detector
-    template <geo_obj_ids surface_id = geo_obj_ids::e_portal>
+    template <geo_obj_ids surface_id = static_cast<geo_obj_ids>(0)>
     DETRAY_HOST auto add_objects_per_volume(
         const geometry_context ctx, volume_type &vol,
         surface_container_t &surfaces_per_vol, mask_container &masks_per_vol,

core/include/detray/geometry/detector_volume.hpp

@@ -71,20 +71,31 @@ class detector_volume {
     /// Default constructor builds an infinitely long cylinder
     constexpr detector_volume() = default;
 
-    /// Constructor from boundary values.
+    /// Constructor from shape id.
+    ///
+    /// @param id id values that determines how to interpret the bounds.
+    explicit constexpr detector_volume(const volume_id id) : _id{id} {}
+
+    /// Constructor from shape id and boundary values.
     ///
     /// @param id id values that determines how to interpret the bounds.
     /// @param bounds values of volume boundaries. They depend on the volume
     ///               shape, which is defined by its portals and are chosen in
     ///               the detector builder.
     constexpr detector_volume(const volume_id id,
                               const array_t<scalar_t, 6> &bounds)
-        : _id{id}, _bounds(bounds) {}
+        : _id(id), _bounds(bounds) {}
 
     /// @return the volume shape id, e.g. 'cylinder'
     DETRAY_HOST_DEVICE
     constexpr auto id() const -> volume_id { return _id; }
 
+    /// Set the volume bounds to @param bounds
+    DETRAY_HOST
+    constexpr void set_bounds(const array_t<scalar_t, 6> &bounds) {
+        _bounds = bounds;
+    }
+
     /// @return the bounds - const access
     DETRAY_HOST_DEVICE
     constexpr auto bounds() const -> const array_t<scalar_t, 6> & {
@@ -111,25 +122,25 @@ class detector_volume {
     }
 
     /// @return link of a type of object - const access.
-    template <ID obj_id = ID::e_sensitive>
+    template <ID obj_id>
     DETRAY_HOST_DEVICE constexpr auto link() const -> const link_t & {
         return detail::get<obj_id>(_sf_finder_links);
     }
 
     /// @return link of a type of object - const access.
-    template <ID obj_id = ID::e_sensitive>
+    template <ID obj_id>
     DETRAY_HOST_DEVICE constexpr auto link() -> link_t & {
         return detail::get<obj_id>(_sf_finder_links);
     }
 
     /// set surface finder during detector building
-    template <ID obj_id = ID::e_sensitive>
+    template <ID obj_id>
     DETRAY_HOST constexpr auto set_link(const link_t &link) -> void {
         _sf_finder_links[obj_id] = link;
     }
 
     /// set surface finder during detector building
-    template <ID obj_id = ID::e_sensitive>
+    template <ID obj_id>
     DETRAY_HOST constexpr auto set_link(const typename link_t::id_type id,
                                         const typename link_t::index_type index)
         -> void {