EventData/detail/ParameterTraits.hpp

0001 // This file is part of the Acts project.
0002 //
0003 // Copyright (C) 2016-2020 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 http://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Definitions/TrackParametrization.hpp"
0012
0013 #include <algorithm>
0014 #include <cmath>
0015 #include <cstddef>
0016
0017 namespace Acts::detail {
0018
0019 /// Traits class for an unrestricted parameter.
0020 struct UnrestrictedParameterTraits {
0021   /// Values need no adjustment.
0022   static constexpr bool may_modify_value = false;
0023
0024   /// Get the corrected value within the limits. This is a no-op here.
0025   template <typename value_t>
0026   static constexpr const value_t& getValue(const value_t& value) {
0027     return value;
0028   }
0029   /// Compute the difference between two values.
0030   template <typename value_t>
0031   static constexpr value_t getDifference(const value_t& lhs,
0032                                          const value_t& rhs) {
0033     return lhs - rhs;
0034   }
0035 };
0036
0037 /// Traits class for a parameter with a restricted value range.
0038 ///
0039 /// @tparam limits_t a type with static `lowest()` and `max()` member functions
0040 ///
0041 /// This parameter type could be useful to describe parameter with physical
0042 /// meaningful bounds (e.g. radius).
0043 template <typename limits_t>
0044 struct RestrictedParameterTraits {
0045   /// Parameter values may need adjustment.
0046   static constexpr bool may_modify_value = true;
0047   /// Lower bound of range.
0048   static constexpr double min = limits_t::lowest();
0049   /// Upper bound of range.
0050   static constexpr double max = limits_t::max();
0051
0052   /// Get the corrected value within the limits.
0053   template <typename value_t>
0054   static constexpr value_t getValue(const value_t& value) {
0055     return std::clamp(value, static_cast<value_t>(min),
0056                       static_cast<value_t>(max));
0057   }
0058   /// Compute the difference between two values with limit handling.
0059   template <typename value_t>
0060   static constexpr value_t getDifference(const value_t& lhs,
0061                                          const value_t& rhs) {
0062     return getValue(lhs) - getValue(rhs);
0063   }
0064 };
0065
0066 /// Traits class for a parameter with a cyclic value range.
0067 ///
0068 /// @tparam limits_t a type with static `lowest()` and `max()` member functions
0069 ///
0070 /// This parameter type is useful to e.g. describe angles.
0071 template <typename limits_t>
0072 struct CyclicParameterTraits {
0073   /// Parameter values may need adjustment.
0074   static constexpr bool may_modify_value = true;
0075   /// Lower bound of range.
0076   static constexpr double min = limits_t::lowest();
0077   /// Upper bound of range.
0078   static constexpr double max = limits_t::max();
0079
0080   /// Get the corrected value folded into the central range.
0081   template <typename value_t>
0082   static constexpr value_t getValue(const value_t& value) {
0083     if ((min <= value) && (value < max)) {
0084       return value;
0085     } else {
0086       return value - (max - min) * std::floor((value - min) / (max - min));
0087     }
0088   }
0089   /// Compute the smallest equivalent difference when using the periodicity.
0090   template <typename value_t>
0091   static constexpr value_t getDifference(const value_t& lhs,
0092                                          const value_t& rhs) {
0093     constexpr value_t range = (max - min);
0094     value_t delta = getValue(lhs) - getValue(rhs);
0095     if ((2 * delta) < -range) {
0096       return delta + range;
0097     } else if (range < (2 * delta)) {
0098       return delta - range;
0099     } else {
0100       return delta;
0101     }
0102   }
0103 };
0104
0105 // Limit types for parameter traits.
0106 //
0107 // The functions names are chosen to be consistent w/ std::numeric_limits
0108 struct PhiBoundParameterLimits {
0109   static constexpr double lowest() { return -M_PI; }
0110   static constexpr double max() { return M_PI; }
0111 };
0112 struct ThetaBoundParameterLimits {
0113   static constexpr double lowest() { return 0; }
0114   static constexpr double max() { return M_PI; }
0115 };
0116
0117 // Traits implementation structs for single parameters.
0118 //
0119 // Separate implementation structs are needed to generate a compile-time error
0120 // in case of an unsupported enum type/ index combination.
0121 template <typename index_t, index_t kIndex>
0122 struct ParameterTraitsImpl;
0123 template <>
0124 struct ParameterTraitsImpl<BoundIndices, BoundIndices::eBoundPhi> {
0125   using Type = CyclicParameterTraits<PhiBoundParameterLimits>;
0126 };
0127 template <>
0128 struct ParameterTraitsImpl<BoundIndices, BoundIndices::eBoundTheta> {
0129   using Type = RestrictedParameterTraits<ThetaBoundParameterLimits>;
0130 };
0131 template <BoundIndices kIndex>
0132 struct ParameterTraitsImpl<BoundIndices, kIndex> {
0133   // other bound parameters not explicitly specified above are unrestricted
0134   using Type = UnrestrictedParameterTraits;
0135 };
0136 template <FreeIndices kIndex>
0137 struct ParameterTraitsImpl<FreeIndices, kIndex> {
0138   // all free parameters components are unrestricted
0139   using Type = UnrestrictedParameterTraits;
0140 };
0141
0142 /// Parameter traits for one specific parameter in one of the indices enums.
0143 ///
0144 /// @tparam index_t Parameter indices enum
0145 /// @tparam kIndex Enum index value to identify a parameter
0146 ///
0147 /// This type resolves directly to one of the parameter traits classes defined
0148 /// above and allows for uniform access.
0149 template <typename index_t, index_t kIndex>
0150 using ParameterTraits = typename ParameterTraitsImpl<index_t, kIndex>::Type;
0151
0152 // Traits implementation structs for all parameters in an indices enum.
0153 //
0154 // Separate implementation structs are needed to generate a compile-time error
0155 // in case of an unsupported indices enum. Also required since template
0156 // variables can not have an undefined default case.
0157 template <typename indices_t>
0158 struct ParametersTraitsImpl;
0159 template <>
0160 struct ParametersTraitsImpl<BoundIndices> {
0161   static constexpr std::size_t kSize =
0162       static_cast<std::size_t>(BoundIndices::eBoundSize);
0163 };
0164 template <>
0165 struct ParametersTraitsImpl<FreeIndices> {
0166   static constexpr std::size_t kSize =
0167       static_cast<std::size_t>(FreeIndices::eFreeSize);
0168 };
0169
0170 /// The maximum parameters vector size definable for an indices enum.
0171 template <typename indices_t>
0172 constexpr std::size_t kParametersSize = ParametersTraitsImpl<indices_t>::kSize;
0173
0174 }  // namespace Acts::detail