Acts/MagneticField/MagneticFieldProvider.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/Utilities/Any.hpp"
0014 #include "Acts/Utilities/Result.hpp"
0015
0016 namespace Acts {
0017
0018 /// Base class for all magnetic field providers
0019 /// @ingroup magnetic_field
0020 ///
0021 /// All magnetic field implementations inherit and implement from this
0022 /// interface.
0023 ///
0024 /// It provides a generic interface over different implementations. To speed up
0025 /// magnetic field lookup, each implementation can have a *cache* object. The
0026 /// cache object can for example be used to store a local interpolation domain,
0027 /// to speed up nearby field lookups. The client is expected to pass into
0028 /// lookup calls an instance of @ref Acts::MagneticFieldProvider::Cache.
0029 ///
0030 /// The implementation is then free to use and update this cache instance as
0031 /// needed. Before a client can issue field lookup calls, it needs to obtain an
0032 /// initialized instance of this cache object. This can be achieved generically
0033 /// for all implementations by using
0034 /// @ref Acts::MagneticFieldProvider::makeCache. This function accepts an
0035 /// instance of @ref Acts::MagneticFieldContext.
0036 ///
0037 /// The main lookup method of @ref Acts::MagneticFieldProvider is @ref
0038 /// Acts::MagneticFieldProvider::getField
0039 ///
0040 /// Aside from the lookup position as a global position vector, it accepts an
0041 /// instance of the opaque cache object mentioned before. The return value is a
0042 /// @ref Acts::Result object. It either contains the field value at the
0043 /// requested location, or an @ref Acts::MagneticFieldError in case of a lookup
0044 /// failure, like an out-of-bounds lookup position.
0045 ///
0046 /// Below is an example of how a client can interact with an instance of
0047 /// @ref Acts::MagneticFieldProvider.
0048 ///
0049 /// ```cpp
0050 /// // In event context
0051 /// auto fieldContext = getExperimentFieldContext();
0052 /// const Acts::MagneticFieldProvider& fieldProvider = getFieldProvider();
0053 /// // Make an opaque cache for field lookups
0054 /// auto cache = fieldProvider.makeCache(fieldContext);
0055 ///
0056 /// auto lookupResult = fieldProvider.getField(Acts::Vector3{10, 10, 10},
0057 ///                                   cache);
0058 /// if(!lookupResult.ok()) {
0059 ///    throw std::runtime_error{"Field lookup failure"};
0060 /// }
0061 ///
0062 /// Acts::Vector3 fieldValue = *lookupResult;
0063 /// ```
0064 class MagneticFieldProvider {
0065  public:
0066   /// Opaque cache type that can store arbitrary implementation specific cache
0067   /// data. Examples are an interpolation cell, or an experiment specific
0068   /// conditions data handle.
0069   ///
0070   /// The cache is always creaded through @ref makeCache.
0071   using Cache = Acts::AnyBase<sizeof(char) * 512>;
0072
0073   /// Make an opaque cache for the magnetic field. Instructs the specific
0074   /// implementation to generate a @ref Acts::MagneticFieldProvider::Cache instance
0075   /// for magnetic field lookup.
0076   ///
0077   /// @param mctx The magnetic field context to generate cache for
0078   /// @return Cache The opaque cache object
0079   virtual Cache makeCache(const MagneticFieldContext& mctx) const = 0;
0080
0081   /// Retrieve magnetic field value at a given location. Requires an instance
0082   /// of @ref Acts::MagneticFieldProvider::Cache created through @ref makeCache.
0083   ///
0084   /// @param [in] position global 3D position for the lookup
0085   /// @param [in,out] cache Field provider specific cache object
0086   ///
0087   /// @return magnetic field vector at given position
0088   virtual Result<Vector3> getField(const Vector3& position,
0089                                    Cache& cache) const = 0;
0090
0091   virtual ~MagneticFieldProvider() = default;
0092 };
0093
0094 }  // namespace Acts