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