Acts/MagneticField/MultiRangeBField.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Definitions/Algebra.hpp"
0012 #include "Acts/MagneticField/MagneticFieldContext.hpp"
0013 #include "Acts/MagneticField/MagneticFieldProvider.hpp"
0014 #include "Acts/Utilities/RangeXD.hpp"
0015
0016 namespace Acts {
0017
0018 /// Magnetic field provider modelling a magnetic field consisting of
0019 /// several (potentially overlapping) regions of constant values.
0020 ///
0021 /// @ingroup magnetic_field
0022 ///
0023 /// The multi-range constant field allows modelling cases where a magnetic field
0024 /// can be described as multiple (potentially overlapping) regions, each of
0025 /// which has its own constant magnetic field. This provides more flexibility
0026 /// than the
0027 /// @ref Acts::ConstantBField while providing higher performance than
0028 /// @ref Acts::InterpolatedBFieldMap.
0029 ///
0030 /// This magnetic field provider is configured using a list of pairs, where each
0031 /// pair defines a region in three-dimensional space as well as a field vector.
0032 /// Magnetic field lookup then proceeds by finding the *last* region in the
0033 /// user-provided list that contains the requested coordinate and returning the
0034 /// corresponding field vector.
0035 ///
0036 /// The implementation uses a simple caching mechanism to store the last matched
0037 /// region, providing improved performance for consecutive lookups within the
0038 /// same region. This is thread-safe when each thread uses its own cache
0039 /// instance. The field configuration itself is immutable after construction.
0040 class MultiRangeBField final : public MagneticFieldProvider {
0041  private:
0042   struct Cache {
0043     explicit Cache(const MagneticFieldContext& /*unused*/);
0044
0045     std::optional<std::size_t> index = {};
0046   };
0047
0048   using BFieldRange = std::pair<RangeXD<3, double>, Vector3>;
0049
0050   // The different ranges and their corresponding field vectors. Note that
0051   // regions positioned _later_ in this vector take priority over earlier
0052   // regions.
0053   std::vector<BFieldRange> fieldRanges;
0054
0055  public:
0056   /// @brief Construct a magnetic field from a vector of ranges.
0057   ///
0058   /// @param ranges Vector of magnetic field ranges to use
0059   /// @warning These ranges are listed in increasing order of precedence,
0060   /// i.e. ranges further along the vector have higher priority.
0061   explicit MultiRangeBField(const std::vector<BFieldRange>& ranges);
0062
0063   /// Construct from a vector of magnetic field ranges (move version).
0064   /// @param ranges Vector of magnetic field ranges to use (moved)
0065   /// @warning These ranges are listed in increasing order of precedence,
0066   /// i.e. ranges further along the vector have higher priority.
0067   explicit MultiRangeBField(std::vector<BFieldRange>&& ranges);
0068
0069   /// @brief Construct a cache object.
0070   /// @param mctx Magnetic field context for cache creation
0071   /// @return Cache object for magnetic field computations
0072   MagneticFieldProvider::Cache makeCache(
0073       const MagneticFieldContext& mctx) const override;
0074
0075   /// @brief Request the value of the magnetic field at a given position.
0076   ///
0077   /// @param [in] position Global 3D position for the lookup.
0078   /// @param [in, out] cache Cache object.
0079   /// @returns A successful value containing a field vector if the given
0080   /// location is contained inside any of the regions, or a failure value
0081   /// otherwise.
0082   Result<Vector3> getField(const Vector3& position,
0083                            MagneticFieldProvider::Cache& cache) const override;
0084 };
0085
0086 }  // namespace Acts