refactor(Examples): clean up magnetic field handling (#696)

Clean up the magnetic field types and options in the examples:

Magnetic field related headers are now consistently located in the ActsExamples/MagneticField include directory and all code is in the ActsExamples namespace. Before, the code still had the old Examples/Plugins/... layout and inconsistent or missing namespacing inherited from the old framework.
Move the magnetic field variant type ActsExamples::MagneticField into a separate header.
Magnetic field options have a well-documented order of preferrence (constant field overrides field map). If no field options are given, a null field is created, e.g. to support telescope-like detectors without a field. Expected units are clearly communicated as part of the parameter name, similar to what is done in other algorithms.
The field map readers are private implementation details and are not publicly available anymore.
Detector construction and magnetic field setup are now completely orthogonal: all magnetic fields can be setup for all detectors.

Examples/Algorithms/TrackFinding/include/ActsExamples/TrackFinding/TrackFindingAlgorithm.hpp

@@ -14,7 +14,7 @@
 #include "ActsExamples/EventData/Measurement.hpp"
 #include "ActsExamples/EventData/Track.hpp"
 #include "ActsExamples/Framework/BareAlgorithm.hpp"
-#include "ActsExamples/Plugins/BField/BFieldOptions.hpp"
+#include "ActsExamples/MagneticField/MagneticField.hpp"
 
 #include <functional>
 #include <vector>
@@ -40,7 +40,7 @@ class TrackFindingAlgorithm final : public BareAlgorithm {
   /// contains shared_ptr anyways.
   static TrackFinderFunction makeTrackFinderFunction(
       std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry,
-      Options::BFieldVariant magneticField);
+      MagneticField magneticField);
 
   struct Config {
     /// Input measurements collection.

Examples/Algorithms/TrackFinding/include/ActsExamples/TrackFinding/TrackParamsEstimationAlgorithm.hpp

@@ -13,10 +13,8 @@
 #include "Acts/Geometry/TrackingGeometry.hpp"
 #include "Acts/MagneticField/ConstantBField.hpp"
 #include "Acts/MagneticField/InterpolatedBFieldMap.hpp"
-#include "Acts/MagneticField/SharedBField.hpp"
 #include "ActsExamples/Framework/BareAlgorithm.hpp"
-#include "ActsExamples/Plugins/BField/BFieldOptions.hpp"
-#include "ActsExamples/Plugins/BField/ScalableBField.hpp"
+#include "ActsExamples/MagneticField/MagneticField.hpp"
 
 #include <functional>
 #include <memory>
@@ -43,7 +41,7 @@ class TrackParamsEstimationAlgorithm final : public BareAlgorithm {
     /// Tracking geometry for surface lookup.
     std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry;
     /// Magnetic field variant.
-    Options::BFieldVariant magneticField;
+    MagneticField magneticField;
     /// The minimum magnetic field to trigger the track parameters estimation
     double bFieldMin = 0.1 * Acts::UnitConstants::T;
     /// Constant term of the loc0 resolution.
@@ -86,17 +84,4 @@ class TrackParamsEstimationAlgorithm final : public BareAlgorithm {
   Acts::Vector3 getField(const Acts::Vector3& position) const;
 };
 
-inline Acts::Vector3 TrackParamsEstimationAlgorithm::getField(
-    const Acts::Vector3& position) const {
-  return std::visit(
-      [&](auto&& inputField) -> Acts::Vector3 {
-        using InputMagneticField =
-            typename std::decay_t<decltype(inputField)>::element_type;
-        using MagneticField = Acts::SharedBField<InputMagneticField>;
-        MagneticField field(std::move(inputField));
-        return field.getField(position);
-      },
-      std::move(m_cfg.magneticField));
-}
-
 }  // namespace ActsExamples

Examples/Algorithms/TrackFinding/src/TrackFindingAlgorithmFunction.cpp

@@ -1,20 +1,17 @@
 // This file is part of the Acts project.
 //
-// Copyright (C) 2020 CERN for the benefit of the Acts project
+// Copyright (C) 2021 CERN for the benefit of the Acts project
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-#include "Acts/MagneticField/ConstantBField.hpp"
-#include "Acts/MagneticField/InterpolatedBFieldMap.hpp"
 #include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/Propagator/EigenStepper.hpp"
 #include "Acts/Propagator/Navigator.hpp"
 #include "Acts/Propagator/Propagator.hpp"
 #include "Acts/TrackFitting/GainMatrixSmoother.hpp"
 #include "Acts/TrackFitting/GainMatrixUpdater.hpp"
-#include "ActsExamples/Plugins/BField/ScalableBField.hpp"
 #include "ActsExamples/TrackFinding/TrackFindingAlgorithm.hpp"
 
 #include <random>
@@ -42,7 +39,7 @@ struct TrackFinderFunctionImpl {
 ActsExamples::TrackFindingAlgorithm::TrackFinderFunction
 ActsExamples::TrackFindingAlgorithm::makeTrackFinderFunction(
     std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry,
-    Options::BFieldVariant magneticField) {
+    MagneticField magneticField) {
   using Updater = Acts::GainMatrixUpdater;
   using Smoother = Acts::GainMatrixSmoother;
 
@@ -54,15 +51,15 @@ ActsExamples::TrackFindingAlgorithm::makeTrackFinderFunction(
         // need ::element_type to get the real magnetic field type
         using InputMagneticField =
             typename std::decay_t<decltype(inputField)>::element_type;
-        using MagneticField = Acts::SharedBField<InputMagneticField>;
-        using Stepper = Acts::EigenStepper<MagneticField>;
+        using SharedMagneticField = Acts::SharedBField<InputMagneticField>;
+        using Stepper = Acts::EigenStepper<SharedMagneticField>;
         using Navigator = Acts::Navigator;
         using Propagator = Acts::Propagator<Stepper, Navigator>;
         using CKF =
             Acts::CombinatorialKalmanFilter<Propagator, Updater, Smoother>;
 
         // construct all components for the track finder
-        MagneticField field(std::move(inputField));
+        SharedMagneticField field(std::move(inputField));
         Stepper stepper(std::move(field));
         Navigator navigator(trackingGeometry);
         navigator.resolvePassive = false;

Examples/Algorithms/TrackFinding/src/TrackParamsEstimationAlgorithm.cpp

@@ -55,6 +55,15 @@ ActsExamples::TrackParamsEstimationAlgorithm::TrackParamsEstimationAlgorithm(
       m_cfg.sigmaT0 * m_cfg.sigmaT0;
 }
 
+Acts::Vector3 ActsExamples::TrackParamsEstimationAlgorithm::getField(
+    const Acts::Vector3& position) const {
+  return std::visit(
+      [&](const auto& inputField) -> Acts::Vector3 {
+        return inputField->getField(position);
+      },
+      m_cfg.magneticField);
+}
+
 ActsExamples::ProcessCode ActsExamples::TrackParamsEstimationAlgorithm::execute(
     const ActsExamples::AlgorithmContext& ctx) const {
   // @todo storing the seed as a ProtoTrack in the SeedingAlgorithm. The input

Examples/Algorithms/TrackFitting/include/ActsExamples/TrackFitting/TrackFittingAlgorithm.hpp

@@ -1,6 +1,6 @@
 // This file is part of the Acts project.
 //
-// Copyright (C) 2019-2020 CERN for the benefit of the Acts project
+// Copyright (C) 2019-2021 CERN for the benefit of the Acts project
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -14,7 +14,7 @@
 #include "ActsExamples/EventData/Measurement.hpp"
 #include "ActsExamples/EventData/Track.hpp"
 #include "ActsExamples/Framework/BareAlgorithm.hpp"
-#include "ActsExamples/Plugins/BField/BFieldOptions.hpp"
+#include "ActsExamples/MagneticField/MagneticField.hpp"
 
 #include <functional>
 #include <memory>
@@ -50,10 +50,10 @@ class TrackFittingAlgorithm final : public BareAlgorithm {
   /// contains shared_ptr anyways.
   static TrackFitterFunction makeTrackFitterFunction(
       std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry,
-      Options::BFieldVariant magneticField);
+      MagneticField magneticField);
 
   static DirectedTrackFitterFunction makeTrackFitterFunction(
-      Options::BFieldVariant magneticField);
+      MagneticField magneticField);
 
   struct Config {
     /// Input measurements collection.

Examples/Algorithms/TrackFitting/src/TrackFittingAlgorithmFunction.cpp

@@ -1,6 +1,6 @@
 // This file is part of the Acts project.
 //
-// Copyright (C) 2019-2020 CERN for the benefit of the Acts project
+// Copyright (C) 2019-2021 CERN for the benefit of the Acts project
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -9,8 +9,6 @@
 #include "Acts/Definitions/TrackParametrization.hpp"
 #include "Acts/Geometry/GeometryIdentifier.hpp"
 #include "Acts/Geometry/TrackingGeometry.hpp"
-#include "Acts/MagneticField/ConstantBField.hpp"
-#include "Acts/MagneticField/InterpolatedBFieldMap.hpp"
 #include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/Propagator/EigenStepper.hpp"
 #include "Acts/Propagator/Navigator.hpp"
@@ -19,7 +17,7 @@
 #include "Acts/TrackFitting/GainMatrixSmoother.hpp"
 #include "Acts/TrackFitting/GainMatrixUpdater.hpp"
 #include "Acts/Utilities/Helpers.hpp"
-#include "ActsExamples/Plugins/BField/ScalableBField.hpp"
+#include "ActsExamples/MagneticField/MagneticField.hpp"
 #include "ActsExamples/TrackFitting/TrackFittingAlgorithm.hpp"
 
 namespace {
@@ -52,12 +50,13 @@ struct DirectedFitterFunctionImpl {
     return fitter.fit(sourceLinks, initialParameters, options, sSequence);
   };
 };
+
 }  // namespace
 
 ActsExamples::TrackFittingAlgorithm::TrackFitterFunction
 ActsExamples::TrackFittingAlgorithm::makeTrackFitterFunction(
     std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry,
-    Options::BFieldVariant magneticField) {
+    MagneticField magneticField) {
   using Updater = Acts::GainMatrixUpdater;
   using Smoother = Acts::GainMatrixSmoother;
 
@@ -68,14 +67,14 @@ ActsExamples::TrackFittingAlgorithm::makeTrackFitterFunction(
         // need ::element_type to get the real magnetic field type
         using InputMagneticField =
             typename std::decay_t<decltype(inputField)>::element_type;
-        using MagneticField = Acts::SharedBField<InputMagneticField>;
-        using Stepper = Acts::EigenStepper<MagneticField>;
+        using SharedMagneticField = Acts::SharedBField<InputMagneticField>;
+        using Stepper = Acts::EigenStepper<SharedMagneticField>;
         using Navigator = Acts::Navigator;
         using Propagator = Acts::Propagator<Stepper, Navigator>;
         using Fitter = Acts::KalmanFitter<Propagator, Updater, Smoother>;
 
         // construct all components for the fitter
-        MagneticField field(std::move(inputField));
+        SharedMagneticField field(std::move(inputField));
         Stepper stepper(std::move(field));
         Navigator navigator(trackingGeometry);
         navigator.resolvePassive = false;
@@ -92,7 +91,7 @@ ActsExamples::TrackFittingAlgorithm::makeTrackFitterFunction(
 
 ActsExamples::TrackFittingAlgorithm::DirectedTrackFitterFunction
 ActsExamples::TrackFittingAlgorithm::makeTrackFitterFunction(
-    Options::BFieldVariant magneticField) {
+    MagneticField magneticField) {
   using Updater = Acts::GainMatrixUpdater;
   using Smoother = Acts::GainMatrixSmoother;
 
@@ -103,14 +102,14 @@ ActsExamples::TrackFittingAlgorithm::makeTrackFitterFunction(
         // need ::element_type to get the real magnetic field type
         using InputMagneticField =
             typename std::decay_t<decltype(inputField)>::element_type;
-        using MagneticField = Acts::SharedBField<InputMagneticField>;
-        using Stepper = Acts::EigenStepper<MagneticField>;
+        using SharedMagneticField = Acts::SharedBField<InputMagneticField>;
+        using Stepper = Acts::EigenStepper<SharedMagneticField>;
         using Navigator = Acts::DirectNavigator;
         using Propagator = Acts::Propagator<Stepper, Navigator>;
         using Fitter = Acts::KalmanFitter<Propagator, Updater, Smoother>;
 
         // construct all components for the fitter
-        MagneticField field(std::move(inputField));
+        SharedMagneticField field(std::move(inputField));
         Stepper stepper(std::move(field));
         Navigator navigator;
         Propagator propagator(std::move(stepper), std::move(navigator));

Examples/Detectors/ContextualDetector/CMakeLists.txt

@@ -11,7 +11,7 @@ target_link_libraries(
   ActsExamplesDetectorContextual
   PUBLIC
     ActsCore ActsPluginIdentification ActsPluginDigitization
-    ActsExamplesFramework ActsExamplesDetectorsCommon ActsExamplesDetectorGeneric ActsExamplesMagneticField)
+    ActsExamplesFramework ActsExamplesDetectorsCommon ActsExamplesDetectorGeneric)
 
 install(
   TARGETS ActsExamplesDetectorContextual

Examples/Detectors/ContextualDetector/src/AlignedDetector.cpp

@@ -16,18 +16,13 @@
 #include "ActsExamples/Framework/IContextDecorator.hpp"
 #include "ActsExamples/GenericDetector/BuildGenericDetector.hpp"
 #include "ActsExamples/GenericDetector/GenericDetectorOptions.hpp"
-#include "ActsExamples/Plugins/BField/BFieldOptions.hpp"
-#include "ActsExamples/Plugins/BField/BFieldScalor.hpp"
-#include "ActsExamples/Plugins/BField/ScalableBField.hpp"
 
 #include <boost/program_options.hpp>
 
 void AlignedDetector::addOptions(
     boost::program_options::options_description& opt) const {
   // Add the generic geometry options
   ActsExamples::Options::addGenericGeometryOptions(opt);
-  // Add the bfield options for the magnetic field scaling
-  ActsExamples::Options::addBFieldOptions(opt);
   // specify the rotation setp
   opt.add_options()(
       "align-seed",
@@ -118,16 +113,6 @@ auto AlignedDetector::finalize(
       agcsConfig,
       Acts::getDefaultLogger("AlignmentDecorator", decoratorLogLevel))};
 
-  if (vm["bf-context-scalable"].template as<bool>()) {
-    ActsExamples::BField::BFieldScalor::Config bfsConfig;
-    bfsConfig.scalor = vm["bf-bscalor"].template as<double>();
-
-    auto bfDecorator =
-        std::make_shared<ActsExamples::BField::BFieldScalor>(bfsConfig);
-
-    aContextDecorators.push_back(bfDecorator);
-  }
-
   // return the pair of geometry and the alignment decorator(s)
   return std::make_pair<TrackingGeometryPtr, ContextDecorators>(
       std::move(aTrackingGeometry), std::move(aContextDecorators));

Examples/Detectors/ContextualDetector/src/PayloadDetector.cpp

@@ -15,18 +15,13 @@
 #include "ActsExamples/Framework/IContextDecorator.hpp"
 #include "ActsExamples/GenericDetector/BuildGenericDetector.hpp"
 #include "ActsExamples/GenericDetector/GenericDetectorOptions.hpp"
-#include "ActsExamples/Plugins/BField/BFieldOptions.hpp"
-#include "ActsExamples/Plugins/BField/BFieldScalor.hpp"
-#include "ActsExamples/Plugins/BField/ScalableBField.hpp"
 
 #include <boost/program_options.hpp>
 
 void PayloadDetector::addOptions(
     boost::program_options::options_description& opt) const {
   /// Add the generic geometry options
   ActsExamples::Options::addGenericGeometryOptions(opt);
-  // Add the bfield options for the magnetic field scaling
-  ActsExamples::Options::addBFieldOptions(opt);
   // specify the rotation setp
   opt.add_options()(
       "align-rotation-step",
@@ -76,16 +71,6 @@ auto PayloadDetector::finalize(
       Acts::getDefaultLogger("PayloadDecorator", decoratorLogLevel));
   pContextDecorators.push_back(agcDecorator);
 
-  if (vm["bf-context-scalable"].template as<bool>()) {
-    ActsExamples::BField::BFieldScalor::Config bfsConfig;
-    bfsConfig.scalor = vm["bf-bscalor"].template as<double>();
-
-    auto bfDecorator =
-        std::make_shared<ActsExamples::BField::BFieldScalor>(bfsConfig);
-
-    pContextDecorators.push_back(bfDecorator);
-  }
-
   // return the pair of geometry and the alignment decorator(s)
   return std::make_pair<TrackingGeometryPtr, ContextDecorators>(
       std::move(pTrackingGeometry), std::move(pContextDecorators));

Examples/Detectors/MagneticField/CMakeLists.txt

@@ -1,14 +1,18 @@
 add_library(
   ActsExamplesMagneticField SHARED
-  src/BFieldOptions.cpp
-  src/BFieldScalor.cpp
-  src/BFieldUtils.cpp)
+  src/FieldMapperRootIo.cpp
+  src/FieldMapperTextIo.cpp
+  src/MagneticFieldOptions.cpp
+  src/ScalableBFieldService.cpp)
 target_include_directories(
   ActsExamplesMagneticField
   PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>)
 target_link_libraries(
   ActsExamplesMagneticField
-  PUBLIC ActsCore ActsExamplesFramework Boost::program_options ROOT::Core ROOT::Tree)
+  # the ROOT libraries should be private, but if we do that then the linker
+  # fails with some missing ROOT symbols.
+  PUBLIC ActsCore ActsExamplesFramework ROOT::Core ROOT::Tree
+  PRIVATE Boost::filesystem Boost::program_options)
 
 install(
   TARGETS ActsExamplesMagneticField

Examples/Detectors/MagneticField/include/ActsExamples/MagneticField/MagneticField.hpp

@@ -0,0 +1,52 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2017-2020 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Definitions/Algebra.hpp"
+#include "Acts/MagneticField/ConstantBField.hpp"
+#include "Acts/MagneticField/InterpolatedBFieldMap.hpp"
+#include "Acts/MagneticField/NullBField.hpp"
+#include "ActsExamples/MagneticField/ScalableBField.hpp"
+
+#include <memory>
+#include <variant>
+
+namespace ActsExamples {
+namespace detail {
+
+using InterpolatedMagneticFieldMapper2 = Acts::InterpolatedBFieldMapper<
+    Acts::detail::Grid<Acts::Vector2, Acts::detail::EquidistantAxis,
+                       Acts::detail::EquidistantAxis>>;
+using InterpolatedMagneticField2 =
+    Acts::InterpolatedBFieldMap<InterpolatedMagneticFieldMapper2>;
+
+using InterpolatedMagneticFieldMapper3 =
+    Acts::InterpolatedBFieldMapper<Acts::detail::Grid<
+        Acts::Vector3, Acts::detail::EquidistantAxis,
+        Acts::detail::EquidistantAxis, Acts::detail::EquidistantAxis>>;
+using InterpolatedMagneticField3 =
+    Acts::InterpolatedBFieldMap<InterpolatedMagneticFieldMapper3>;
+
+}  // namespace detail
+
+/// Magnetic field variant with all supported fields.
+///
+/// This is a value-like type, i.e. can be copied and stored by-value, that can
+/// be used wherever magnetic field information is needed. The examples support
+/// only the finite set of magnetic field type contained in this variant. This
+/// enables the use of a single concrete value-like type that can be used in
+/// interfaces.
+using MagneticField =
+    std::variant<std::shared_ptr<Acts::NullBField>,
+                 std::shared_ptr<Acts::ConstantBField>,
+                 std::shared_ptr<ScalableBField>,
+                 std::shared_ptr<detail::InterpolatedMagneticField2>,
+                 std::shared_ptr<detail::InterpolatedMagneticField3>>;
+
+}  // namespace ActsExamples