Inhomogeneous Magnetic Field Examples, main branch (2025.06.25.) (#1042)

* Introduced traccc::opts::magnetic_field.

Plus a small helper function for constructing an appropriate
traccc::bfield object based on the command line options.

* Made all non-throughput examples use opts::magnetic_field.

Author: krasznaa

examples/options/CMakeLists.txt

@@ -15,6 +15,7 @@ traccc_add_library( traccc_options options TYPE SHARED
   "include/traccc/options/detector.hpp"
   "include/traccc/options/generation.hpp"
   "include/traccc/options/input_data.hpp"
+  "include/traccc/options/magnetic_field.hpp"
   "include/traccc/options/output_data.hpp"
   "include/traccc/options/performance.hpp"
   "include/traccc/options/program_options.hpp"
@@ -33,6 +34,7 @@ traccc_add_library( traccc_options options TYPE SHARED
   "src/detector.cpp"
   "src/generation.cpp"
   "src/input_data.cpp"
+  "src/magnetic_field.cpp"
   "src/output_data.cpp"
   "src/performance.cpp"
   "src/program_options.cpp"

examples/options/include/traccc/options/magnetic_field.hpp

@@ -0,0 +1,58 @@
+/** 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/io/data_format.hpp"
+#include "traccc/options/details/interface.hpp"
+
+// Project include(s).
+#include "traccc/definitions/common.hpp"
+
+// System include(s).
+#include <string>
+
+namespace traccc::opts {
+
+/// Options for the used magnetic field
+struct magnetic_field : public interface {
+
+    /// @name Options
+    /// @{
+
+    /// Use an inhomogeneous magnetic field from an input file
+    bool read_from_file = false;
+    /// The file containing the magnetic field description
+    std::string file = "geometries/odd/odd-bfield.cvf";
+    /// The data format of the magnetic field file
+    traccc::data_format format = data_format::binary;
+    /// Magnetic field value when not reading from a file
+    float value = 2.f * unit<float>::T;
+
+    /// @}
+
+    /// Constructor
+    magnetic_field();
+
+    /// @name Functions implemented from @c traccc::opts::interface
+    /// @{
+
+    /// Read/process the command line options
+    ///
+    /// @param vm The command line options to interpret/read
+    ///
+    void read(const boost::program_options::variables_map& vm) override;
+
+    /// Get a printable representation of the configuration
+    std::unique_ptr<configuration_printable> as_printable() const override;
+
+    /// @}
+
+};  // class magnetic_field
+
+}  // namespace traccc::opts

examples/options/src/magnetic_field.cpp

@@ -0,0 +1,77 @@
+/** 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
+ */
+
+// Local include(s).
+#include "traccc/options/magnetic_field.hpp"
+
+// Project include(s).
+#include "traccc/examples/utils/printable.hpp"
+
+// System include(s).
+#include <format>
+#include <sstream>
+#include <stdexcept>
+
+namespace traccc::opts {
+
+/// Helper namespace for convenience
+namespace po = boost::program_options;
+
+/// Type alias for the data format enumeration
+using format_type = std::string;
+/// Name of the data format option
+static const char* format_option = "bfield-file-format";
+
+magnetic_field::magnetic_field() : interface("Magnetic Field Options") {
+
+    m_desc.add_options()("read-bfield-from-file",
+                         po::bool_switch(&read_from_file),
+                         "Read the magnetic field from a file");
+    m_desc.add_options()("bfield-file", po::value(&file)->default_value(file),
+                         "Magnetic field file");
+    m_desc.add_options()(format_option,
+                         po::value<format_type>()->default_value("binary"),
+                         "Format of the magnetic field file");
+    m_desc.add_options()("bfield-value",
+                         po::value(&value)->default_value(value),
+                         "Magnetic field value (when not reading from a file)");
+}
+
+void magnetic_field::read(const po::variables_map& vm) {
+
+    // Decode the magnetic field file data format.
+    if (vm.count(format_option)) {
+        const std::string format_string = vm[format_option].as<format_type>();
+        if (format_string == "csv") {
+            format = data_format::csv;
+        } else if (format_string == "binary") {
+            format = data_format::binary;
+        } else {
+            throw std::invalid_argument("Unknown magnetic field data format");
+        }
+    }
+}
+
+std::unique_ptr<configuration_printable> magnetic_field::as_printable() const {
+
+    auto cat = std::make_unique<configuration_category>(m_description);
+
+    cat->add_child(std::make_unique<configuration_kv_pair>(
+        "Read magnetic field from file", std::format("{}", read_from_file)));
+    cat->add_child(
+        std::make_unique<configuration_kv_pair>("Magnetic field file", file));
+    std::ostringstream format_ss;
+    format_ss << format;
+    cat->add_child(std::make_unique<configuration_kv_pair>(
+        "Magnetic field file format", format_ss.str()));
+    cat->add_child(std::make_unique<configuration_kv_pair>(
+        "Magnetic field value", std::format("{} T", value / unit<float>::T)));
+
+    return cat;
+}
+
+}  // namespace traccc::opts

examples/run/CMakeLists.txt

@@ -7,6 +7,18 @@
 # Project include(s).
 include( traccc-compiler-options-cpp )
 
+# Create the common library.
+add_library(traccc_examples_common STATIC
+   "common/make_magnetic_field.hpp"
+   "common/make_magnetic_field.cpp"
+   "common/throughput_mt.hpp"
+   "common/throughput_mt.ipp"
+   "common/throughput_st.hpp"
+   "common/throughput_st.ipp")
+target_link_libraries(traccc_examples_common
+   PUBLIC traccc::core traccc::options
+   PRIVATE traccc::io)
+
 # Add all the subdirectories that can be built.
 add_subdirectory(cpu)
 

examples/run/common/make_magnetic_field.cpp

@@ -0,0 +1,28 @@
+/** 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
+ */
+
+// Local include(s).
+#include "make_magnetic_field.hpp"
+
+// Project include(s).
+#include "traccc/definitions/primitives.hpp"
+#include "traccc/io/read_bfield.hpp"
+
+namespace traccc::details {
+
+bfield make_magnetic_field(const opts::magnetic_field& opts) {
+
+    if (opts.read_from_file) {
+        covfie::field<inhom_bfield_backend_t<scalar>> field;
+        io::read_bfield(field, opts.file, opts.format);
+        return bfield{std::move(field)};
+    } else {
+        return bfield{construct_const_bfield<scalar>({0.f, 0.f, opts.value})};
+    }
+}
+
+}  // namespace traccc::details

examples/run/common/make_magnetic_field.hpp

@@ -0,0 +1,23 @@
+/** 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
+
+// Project include(s).
+#include "traccc/options/magnetic_field.hpp"
+#include "traccc/utils/bfield.hpp"
+
+namespace traccc::details {
+
+/// Create a magnetic field object based on the provided options
+///
+/// @param opts The command line options for the magnetic field
+/// @return A magnetic field object configured according to the options
+///
+bfield make_magnetic_field(const opts::magnetic_field& opts);
+
+}  // namespace traccc::details

examples/run/cpu/CMakeLists.txt

@@ -1,28 +1,30 @@
 # TRACCC library, part of the ACTS project (R&D line)
 #
-# (c) 2021-2024 CERN for the benefit of the ACTS project
+# (c) 2021-2025 CERN for the benefit of the ACTS project
 #
 # Mozilla Public License Version 2.0
 
 traccc_add_executable( seeding_example "seeding_example.cpp"
    LINK_LIBRARIES vecmem::core traccc::core traccc::io
-   traccc::performance traccc::options detray::detectors detray::io)
+   traccc::performance traccc::options detray::detectors detray::io
+   traccc_examples_common )
 
 traccc_add_executable( seq_example "seq_example.cpp"
    LINK_LIBRARIES vecmem::core traccc::core traccc::io
-   traccc::performance traccc::options detray::detectors detray::io)
+   traccc::performance traccc::options detray::detectors detray::io
+   traccc_examples_common )
 
 traccc_add_executable( truth_finding_example "truth_finding_example.cpp"
    LINK_LIBRARIES vecmem::core detray::detectors traccc::core traccc::io
-   traccc::performance traccc::options)
+   traccc::performance traccc::options traccc_examples_common )
 
 traccc_add_executable( truth_fitting_example "truth_fitting_example.cpp"
    LINK_LIBRARIES vecmem::core detray::io detray::detectors traccc::core
-   traccc::io traccc::performance traccc::options)
+   traccc::io traccc::performance traccc::options traccc_examples_common )
 
 traccc_add_executable( misaligned_truth_fitting_example "misaligned_truth_fitting_example.cpp"
    LINK_LIBRARIES vecmem::core detray::io detray::detectors traccc::core
-   traccc::io traccc::performance traccc::options)
+   traccc::io traccc::performance traccc::options traccc_examples_common )
 
 #
 # Set up the "throughput applications".
@@ -31,7 +33,8 @@ add_library( traccc_examples_cpu STATIC
    "full_chain_algorithm.hpp"
    "full_chain_algorithm.cpp" )
 target_link_libraries( traccc_examples_cpu
-   PUBLIC vecmem::core detray::core detray::detectors traccc::core )
+   PUBLIC vecmem::core detray::core detray::detectors traccc::core
+   traccc_examples_common )
 
 traccc_add_executable( throughput_st "throughput_st.cpp"
    LINK_LIBRARIES indicators::indicators vecmem::core detray::detectors

examples/run/cpu/misaligned_truth_fitting_example.cpp

@@ -6,6 +6,7 @@
  */
 
 // Project include(s).
+#include "../common/make_magnetic_field.hpp"
 #include "traccc/definitions/common.hpp"
 #include "traccc/definitions/primitives.hpp"
 #include "traccc/fitting/kalman_fitting_algorithm.hpp"
@@ -14,6 +15,7 @@
 #include "traccc/io/utils.hpp"
 #include "traccc/options/detector.hpp"
 #include "traccc/options/input_data.hpp"
+#include "traccc/options/magnetic_field.hpp"
 #include "traccc/options/performance.hpp"
 #include "traccc/options/program_options.hpp"
 #include "traccc/options/track_fitting.hpp"
@@ -49,13 +51,14 @@ int main(int argc, char* argv[]) {
 
     // Program options.
     traccc::opts::detector detector_opts;
+    traccc::opts::magnetic_field bfield_opts;
     traccc::opts::input_data input_opts;
     traccc::opts::track_propagation propagation_opts;
     traccc::opts::track_fitting fitting_opts;
     traccc::opts::performance performance_opts;
     traccc::opts::program_options program_opts{
         "Truth Track Fitting on the Host",
-        {detector_opts, input_opts, propagation_opts, fitting_opts,
+        {detector_opts, bfield_opts, input_opts, propagation_opts, fitting_opts,
          performance_opts},
         argc,
         argv,
@@ -78,11 +81,8 @@ int main(int argc, char* argv[]) {
      * Build a geometry
      *****************************/
 
-    // B field value and its type
-    // @TODO: Set B field as argument
-    const traccc::vector3 B{0, 0, 2 * traccc::unit<traccc::scalar>::T};
-    const traccc::bfield field{
-        traccc::construct_const_bfield<traccc::scalar>(B)};
+    // B field value
+    const traccc::bfield field = details::make_magnetic_field(bfield_opts);
 
     // Read the detector
     detray::io::detector_reader_config reader_cfg{};

examples/run/cpu/seeding_example.cpp

@@ -6,6 +6,7 @@
  */
 
 // Project include(s).
+#include "../common/make_magnetic_field.hpp"
 #include "traccc/definitions/common.hpp"
 #include "traccc/definitions/primitives.hpp"
 #include "traccc/geometry/detector.hpp"
@@ -34,6 +35,7 @@
 // options
 #include "traccc/options/detector.hpp"
 #include "traccc/options/input_data.hpp"
+#include "traccc/options/magnetic_field.hpp"
 #include "traccc/options/performance.hpp"
 #include "traccc/options/program_options.hpp"
 #include "traccc/options/track_finding.hpp"
@@ -60,6 +62,7 @@ int seq_run(const traccc::opts::track_seeding& seeding_opts,
             const traccc::opts::track_fitting& fitting_opts,
             const traccc::opts::input_data& input_opts,
             const traccc::opts::detector& detector_opts,
+            const traccc::opts::magnetic_field& bfield_opts,
             const traccc::opts::performance& performance_opts,
             std::unique_ptr<const traccc::Logger> ilogger) {
     TRACCC_LOCAL_LOGGER(std::move(ilogger));
@@ -98,11 +101,9 @@ int seq_run(const traccc::opts::track_seeding& seeding_opts,
      * Build a geometry
      *****************************/
 
-    // B field value and its type
-    // @TODO: Set B field as argument
-    const traccc::vector3 B{0, 0, 2 * traccc::unit<traccc::scalar>::T};
-    const traccc::bfield field{
-        traccc::construct_const_bfield<traccc::scalar>(B)};
+    // B field value
+    const traccc::bfield field =
+        traccc::details::make_magnetic_field(bfield_opts);
 
     // Construct a Detray detector object, if supported by the configuration.
     traccc::default_detector::host detector{host_mr};
@@ -274,6 +275,7 @@ int main(int argc, char* argv[]) {
 
     // Program options.
     traccc::opts::detector detector_opts;
+    traccc::opts::magnetic_field bfield_opts;
     traccc::opts::input_data input_opts;
     traccc::opts::track_seeding seeding_opts;
     traccc::opts::track_finding finding_opts;
@@ -283,7 +285,7 @@ int main(int argc, char* argv[]) {
     traccc::opts::performance performance_opts;
     traccc::opts::program_options program_opts{
         "Full Tracking Chain on the Host (without clusterization)",
-        {detector_opts, input_opts, seeding_opts, finding_opts,
+        {detector_opts, bfield_opts, input_opts, seeding_opts, finding_opts,
          propagation_opts, resolution_opts, fitting_opts, performance_opts},
         argc,
         argv,
@@ -292,5 +294,5 @@ int main(int argc, char* argv[]) {
     // Run the application.
     return seq_run(seeding_opts, finding_opts, propagation_opts,
                    resolution_opts, fitting_opts, input_opts, detector_opts,
-                   performance_opts, logger->clone());
+                   bfield_opts, performance_opts, logger->clone());
 }