docs: Update magnetic field documentation (#1518)

Updates the magnetic field documentation page, and also removes the obsolete `SharedBField`.

Core/include/Acts/MagneticField/BFieldMapUtils.hpp

@@ -61,11 +61,12 @@ class SolenoidBField;
 /// @param[in] lengthUnit The unit of the grid points
 /// @param[in] BFieldUnit The unit of the magnetic field
 /// @param[in] firstQuadrant Flag if set to true indicating that only the first
-/// quadrant of the grid points and the BField values has been given and that
-/// the BFieldMap should be created symmetrically for all quadrants.
-/// e.g. we have the grid values r={0,1} with BFieldValues={2,3} on the r axis.
-/// If the flag is set to true the r-axis grid values will be set to {-1,0,1}
-/// and the BFieldValues will be set to {3,2,3}.
+/// quadrant of the grid points and the BField values has been given.
+/// @note If @p firstQuadrant is true will create a field that is symmetric for all quadrants.
+///       e.g. we have the grid values r={0,1} with BFieldValues={2,3} on the r
+///       axis. If the flag is set to true the r-axis grid values will be set to
+///       {-1,0,1} and the BFieldValues will be set to {3,2,3}.
+/// @return A field map instance for use in interpolation.
 Acts::InterpolatedBFieldMap<
     Acts::detail::Grid<Acts::Vector2, Acts::detail::EquidistantAxis,
                        Acts::detail::EquidistantAxis>>
@@ -79,7 +80,7 @@ fieldMapRZ(const std::function<size_t(std::array<size_t, 2> binsRZ,
 
 /// Method to setup the FieldMap
 /// @param localToGlobalBin Function mapping the local bins of x,y,z to the
-/// global bin of the map magnetic field value
+///                         global bin of the map magnetic field value
 ///
 /// e.g.: we have small grid with the
 /// values: x={2,3}, y={3,4}, z ={4,5}, the corresponding indices are i
@@ -106,27 +107,25 @@ fieldMapRZ(const std::function<size_t(std::array<size_t, 2> binsRZ,
 ///        + binsXYZ.at(2));
 /// }
 /// @endcode
+/// @note The grid point values @p xPos, @p yPos and @p zPos do not need to be
+///       sorted or unique (this will be done inside the function)
 /// @param[in] xPos Values of the grid points in x
-/// @note The values do not need to be sorted or unique (this will be done
-/// inside the function)
 /// @param[in] yPos Values of the grid points in y
-/// @note The values do not need to be sorted or unique (this will be done
-/// inside the function)
 /// @param[in] zPos Values of the grid points in z
-/// @note The values do not need to be sorted or unique (this will be done
-/// inside the function)
 /// @param[in] bField The magnetic field values inr r and z for all given grid
-/// points stored in a vector
-/// @note The function localToGlobalBin determines how the magnetic field was
-/// stored in the vector in respect to the grid values
+///                   points stored in a vector
+/// @note The function @p localToGlobalBin determines how the magnetic field was
+///       stored in the vector in respect to the grid values
 /// @param[in] lengthUnit The unit of the grid points
 /// @param[in] BFieldUnit The unit of the magnetic field
 /// @param[in] firstOctant Flag if set to true indicating that only the first
-/// octant of the grid points and the BField values has been given and that
-/// the BFieldMap should be created symmetrically for all quadrants.
-/// e.g. we have the grid values z={0,1} with BFieldValues={2,3} on the r axis.
-/// If the flag is set to true the z-axis grid values will be set to {-1,0,1}
-/// and the BFieldValues will be set to {3,2,3}.
+/// octant of the grid points and the BField values has been given.
+/// @note If @p firstOctant is true, the function will assume a symmetrical
+///       field for all quadrants.  e.g. we have the grid values z={0,1} with
+///       BFieldValues={2,3} on the r axis.  If the flag is set to true the
+///       z-axis grid values will be set to {-1,0,1} and the BFieldValues will
+///       be set to {3,2,3}.
+/// @return A field map instance for use in interpolation.
 Acts::InterpolatedBFieldMap<Acts::detail::Grid<
     Acts::Vector3, Acts::detail::EquidistantAxis, Acts::detail::EquidistantAxis,
     Acts::detail::EquidistantAxis>>
@@ -147,7 +146,7 @@ fieldMapXYZ(const std::function<size_t(std::array<size_t, 3> binsXYZ,
 /// @param nbins pair of bin counts
 /// @param field the solenoid field instance
 ///
-/// @return A field mapper instance for use in interpolation.
+/// @return A field map instance for use in interpolation.
 Acts::InterpolatedBFieldMap<
     Acts::detail::Grid<Acts::Vector2, Acts::detail::EquidistantAxis,
                        Acts::detail::EquidistantAxis>>

Core/include/Acts/MagneticField/InterpolatedBFieldMap.hpp

@@ -46,6 +46,11 @@ class InterpolatedMagneticField : public MagneticFieldProvider {
   ///         otherwise @c false
   virtual bool isInside(const Vector3& position) const = 0;
 
+  /// Get a field value without checking if the lookup position is within the
+  /// interpolation domain.
+  ///
+  /// @param position The lookup position in 3D
+  /// @return The field value at @p position
   virtual Vector3 getFieldUnchecked(const Vector3& position) const = 0;
 };
 
@@ -212,22 +217,22 @@ class InterpolatedBFieldMap : public InterpolatedMagneticField {
   /// @brief get the number of bins for all axes of the field map
   ///
   /// @return vector returning number of bins for all field map axes
-  std::vector<size_t> getNBins() const override {
+  std::vector<size_t> getNBins() const final {
     auto nBinsArray = m_cfg.grid.numLocalBins();
     return std::vector<size_t>(nBinsArray.begin(), nBinsArray.end());
   }
 
   /// @brief get the minimum value of all axes of the field map
   ///
   /// @return vector returning the minima of all field map axes
-  std::vector<double> getMin() const override {
+  std::vector<double> getMin() const final {
     return std::vector<double>(m_lowerLeft.begin(), m_lowerLeft.end());
   }
 
   /// @brief get the maximum value of all axes of the field map
   ///
   /// @return vector returning the maxima of all field map axes
-  std::vector<double> getMax() const override {
+  std::vector<double> getMax() const final {
     return std::vector<double>(m_upperRight.begin(), m_upperRight.end());
   }
 
@@ -236,7 +241,7 @@ class InterpolatedBFieldMap : public InterpolatedMagneticField {
   /// @param [in] position global 3D position
   /// @return @c true if position is inside the defined look-up grid,
   ///         otherwise @c false
-  bool isInside(const Vector3& position) const override {
+  bool isInside(const Vector3& position) const final {
     return isInsideLocal(m_cfg.transformPos(position));
   }
 
@@ -262,7 +267,7 @@ class InterpolatedBFieldMap : public InterpolatedMagneticField {
 
   /// @copydoc MagneticFieldProvider::makeCache(const MagneticFieldContext&) const
   MagneticFieldProvider::Cache makeCache(
-      const MagneticFieldContext& mctx) const override {
+      const MagneticFieldContext& mctx) const final {
     return MagneticFieldProvider::Cache::make<Cache>(mctx);
   }
 
@@ -283,15 +288,15 @@ class InterpolatedBFieldMap : public InterpolatedMagneticField {
         m_cfg.transformBField(m_cfg.grid.interpolate(gridPosition), position));
   }
 
-  Vector3 getFieldUnchecked(const Vector3& position) const override {
+  Vector3 getFieldUnchecked(const Vector3& position) const final {
     const auto gridPosition = m_cfg.transformPos(position);
     return m_cfg.transformBField(m_cfg.grid.interpolate(gridPosition),
                                  position);
   }
 
   /// @copydoc MagneticFieldProvider::getField(const Vector3&,MagneticFieldProvider::Cache&) const
   Result<Vector3> getField(const Vector3& position,
-                           MagneticFieldProvider::Cache& cache) const override {
+                           MagneticFieldProvider::Cache& cache) const final {
     Cache& lcache = cache.get<Cache>();
     const auto gridPosition = m_cfg.transformPos(position);
     if (!lcache.fieldCell || !(*lcache.fieldCell).isInside(gridPosition)) {
@@ -311,7 +316,7 @@ class InterpolatedBFieldMap : public InterpolatedMagneticField {
   /// @todo return derivative
   Result<Vector3> getFieldGradient(
       const Vector3& position, ActsMatrix<3, 3>& derivative,
-      MagneticFieldProvider::Cache& cache) const override {
+      MagneticFieldProvider::Cache& cache) const final {
     (void)derivative;
     return getField(position, cache);
   }

Core/include/Acts/MagneticField/MagneticFieldProvider.hpp

@@ -21,24 +21,30 @@ namespace Acts {
 /// Base class for all magnetic field providers
 class MagneticFieldProvider {
  public:
+  /// Opaque cache type that can store arbitrary implementation specific cache
+  /// data. Examples are an interpolation cell, or an experiment specific
+  /// conditions data handle.
   using Cache = detail::SmallObjectCache;
 
-  /// @brief Make an opaque cache for the magnetic field
+  /// Make an opaque cache for the magnetic field. Instructs the specific
+  /// implementation to generate a @c Cache instance for magnetic field lookup.
   ///
   /// @param mctx The magnetic field context to generate cache for
   /// @return Cache The opaque cache object
   virtual Cache makeCache(const MagneticFieldContext& mctx) const = 0;
 
-  /// @brief retrieve magnetic field value
+  /// Retrieve magnetic field value at a given location. Requires a cache object
+  /// created through makeCache().
   ///
-  /// @param [in] position global 3D position
+  /// @param [in] position global 3D position for the lookup
   /// @param [in,out] cache Field provider specific cache object
   ///
   /// @return magnetic field vector at given position
   virtual Result<Vector3> getField(const Vector3& position,
                                    Cache& cache) const = 0;
 
-  /// @brief retrieve magnetic field value & its gradient
+  /// Retrieve magnetic field value its its gradient. Requires a cache object
+  /// created through makeCache().
   ///
   /// @param [in]  position   global 3D position
   /// @param [out] derivative gradient of magnetic field vector as (3x3) matrix
@@ -53,4 +59,4 @@ class MagneticFieldProvider {
 
 inline MagneticFieldProvider::~MagneticFieldProvider() = default;
 
-}  // namespace Acts
+}  // namespace Acts

Examples/Algorithms/Alignment/src/AlignmentAlgorithmFunction.cpp

@@ -8,7 +8,6 @@
 
 #include "Acts/Definitions/TrackParametrization.hpp"
 #include "Acts/Geometry/GeometryIdentifier.hpp"
-#include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/Propagator/EigenStepper.hpp"
 #include "Acts/Propagator/Navigator.hpp"
 #include "Acts/Propagator/Propagator.hpp"

Examples/Algorithms/Fatras/src/FatrasSimulation.cpp

@@ -8,7 +8,6 @@
 
 #include "ActsExamples/Fatras/FatrasSimulation.hpp"
 
-#include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/Propagator/EigenStepper.hpp"
 #include "Acts/Propagator/Navigator.hpp"
 #include "Acts/Propagator/Propagator.hpp"

Examples/Algorithms/TrackFitting/src/TrackFittingAlgorithmFunctionsGsf.cpp

@@ -9,7 +9,6 @@
 #include "Acts/Definitions/TrackParametrization.hpp"
 #include "Acts/Geometry/GeometryIdentifier.hpp"
 #include "Acts/Geometry/TrackingGeometry.hpp"
-#include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/Propagator/MultiEigenStepperLoop.hpp"
 #include "Acts/Propagator/Navigator.hpp"
 #include "Acts/Propagator/Propagator.hpp"

Examples/Algorithms/TrackFitting/src/TrackFittingAlgorithmFunctionsKalman.cpp

@@ -9,7 +9,6 @@
 #include "Acts/Definitions/TrackParametrization.hpp"
 #include "Acts/Geometry/GeometryIdentifier.hpp"
 #include "Acts/Geometry/TrackingGeometry.hpp"
-#include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/Propagator/EigenStepper.hpp"
 #include "Acts/Propagator/Navigator.hpp"
 #include "Acts/Propagator/Propagator.hpp"

Examples/Run/Common/src/MaterialValidationBase.cpp

@@ -6,7 +6,6 @@
 // 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/SharedBField.hpp"
 #include "Acts/Propagator/DefaultExtension.hpp"
 #include "Acts/Propagator/DenseEnvironmentExtension.hpp"
 #include "ActsExamples/Detector/IBaseDetector.hpp"

Examples/Run/Common/src/PropagationExampleBase.cpp

@@ -7,7 +7,6 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 #include "Acts/Geometry/TrackingGeometry.hpp"
-#include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/Propagator/AtlasStepper.hpp"
 #include "Acts/Propagator/EigenStepper.hpp"
 #include "Acts/Propagator/Navigator.hpp"

Tests/IntegrationTests/PropagationTestsAtlasField.cpp

@@ -106,19 +106,16 @@ std::shared_ptr<const InterpolatedBFieldMap> atlasBField(
 double Bz = 2_T;
 
 using BFieldType = InterpolatedBFieldMap;
-using SharedFieldType = SharedBField<InterpolatedBFieldMap>;
 using EigenStepperType = EigenStepper<>;
 using AtlasStepperType = AtlasStepper;
 using EigenPropagatorType = Propagator<EigenStepperType>;
 using AtlasPropagatorType = Propagator<AtlasStepperType>;
 
 auto bField = atlasBField("Field.txt");
-auto bFieldSharedA = SharedFieldType(bField);
-auto bFieldSharedE = SharedFieldType(bField);
 
-EigenStepperType estepper(bFieldSharedE);
+EigenStepperType estepper(bField);
 EigenPropagatorType epropagator(std::move(estepper));
-AtlasStepperType astepper(bFieldSharedA);
+AtlasStepperType astepper(bField);
 AtlasPropagatorType apropagator(std::move(astepper));
 
 // The actual test - needs to be included to avoid

Tests/UnitTests/Core/MagneticField/MagneticFieldInterfaceConsistencyTests.cpp

@@ -18,7 +18,6 @@
 #include "Acts/MagneticField/InterpolatedBFieldMap.hpp"
 #include "Acts/MagneticField/MagneticFieldContext.hpp"
 #include "Acts/MagneticField/MagneticFieldProvider.hpp"
-#include "Acts/MagneticField/SharedBField.hpp"
 #include "Acts/MagneticField/SolenoidBField.hpp"
 
 namespace bdata = boost::unit_test::data;
@@ -93,10 +92,6 @@ BOOST_AUTO_TEST_CASE(TestInterpolatedBFieldMapInterfaceConsistency) {
   testInterfaceConsistency(b);
 }
 
-BOOST_AUTO_TEST_CASE(TestSharedBFieldInterfaceConsistency) {
-  SharedBField field(std::make_shared<ConstantBField>(Vector3(1, 1, 1)));
-  testInterfaceConsistency(field);
-}
 }  // namespace Test
 
 }  // namespace Acts