Acts/Definitions/Direction.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
0013 #include <cassert>
0014 #include <cstddef>
0015 #include <iosfwd>
0016 #include <string>
0017
0018 namespace Acts {
0019
0020 /// The direction is always with respect to a given momentum, surface normal or
0021 /// other general axes
0022 class Direction final {
0023  private:
0024   enum class Value : int {
0025     Negative = -1,
0026     Positive = 1,
0027   };
0028
0029  public:
0030   /// Create negative direction (-1)
0031   /// @return Direction with negative value
0032   static constexpr Direction Negative() { return Direction{Value::Negative}; }
0033   /// Create positive direction (+1)
0034   /// @return Direction with positive value
0035   static constexpr Direction Positive() { return Direction{Value::Positive}; }
0036
0037   /// Create backward direction (equivalent to negative)
0038   /// @return Direction with negative value for backward propagation
0039   static constexpr Direction Backward() { return Direction{Value::Negative}; }
0040   /// Create forward direction (equivalent to positive)
0041   /// @return Direction with positive value for forward propagation
0042   static constexpr Direction Forward() { return Direction{Value::Positive}; }
0043
0044   /// Create direction opposite to normal (negative)
0045   /// @return Direction with negative value, opposite to surface normal
0046   static constexpr Direction OppositeNormal() {
0047     return Direction{Value::Negative};
0048   }
0049   /// Create direction along normal (positive)
0050   /// @return Direction with positive value, along surface normal
0051   static constexpr Direction AlongNormal() {
0052     return Direction{Value::Positive};
0053   }
0054
0055   /// This turns a signed value into a direction. Will assert on zero.
0056   ///
0057   /// @param scalar is the signed value
0058   ///
0059   /// @return a direction enum
0060   static constexpr Direction fromScalar(double scalar) {
0061     assert(scalar != 0);
0062     return scalar >= 0 ? Positive() : Negative();
0063   }
0064
0065   /// This turns a signed value into a direction and 0 will be handled as a
0066   /// positive direction. Only use this when you are convinced that the 0 case
0067   /// is properly handled downstream.
0068   ///
0069   /// @param scalar is the signed value
0070   ///
0071   /// @return a direction enum
0072   static constexpr Direction fromScalarZeroAsPositive(double scalar) {
0073     return scalar >= 0 ? Positive() : Negative();
0074   }
0075
0076   /// Convert and index [0,1] to a direction e.g. for sorting in
0077   /// std::array<T, 2u>
0078   ///
0079   /// @param index is the direction at input
0080   /// @return Direction corresponding to the index (0->Negative, 1->Positive)
0081   static constexpr Direction fromIndex(std::size_t index) {
0082     return index == 0u ? Negative() : Positive();
0083   }
0084
0085   /// Convert dir to index [0,1] which allows to store direction dependent
0086   /// objects in std::array<T, 2u>
0087   ///
0088   /// @return either 0 or 1
0089   constexpr std::size_t index() const {
0090     if (m_value == Value::Negative) {
0091       return 0u;
0092     }
0093     return 1u;
0094   }
0095
0096   /// Turns the direction into a signed value
0097   ///
0098   /// @return a signed value
0099   constexpr int sign() const { return static_cast<int>(m_value); }
0100
0101   /// Reverse the direction
0102   ///
0103   /// @return an opposite direction
0104   constexpr Direction invert() const {
0105     return *this == Positive() ? Negative() : Positive();
0106   }
0107
0108   /// Convert direction to string representation
0109   /// @return String representation of the direction ("positive" or "negative")
0110   std::string toString() const;
0111
0112   friend constexpr bool operator==(Direction lhs, Direction rhs) {
0113     return lhs.m_value == rhs.m_value;
0114   }
0115
0116  private:
0117   explicit constexpr Direction(Value value) : m_value(value) {}
0118
0119   Value m_value = Value::Positive;
0120 };
0121
0122 /// Stream operator for Direction
0123 /// @param os Output stream
0124 /// @param dir Direction to output
0125 /// @return Reference to output stream
0126 std::ostream& operator<<(std::ostream& os, Direction dir);
0127
0128 // Direction * T
0129
0130 /// Multiply Direction with integer
0131 /// @param dir Direction value
0132 /// @param value Integer to multiply
0133 /// @return Signed integer result
0134 constexpr int operator*(Direction dir, int value) {
0135   return dir.sign() * value;
0136 }
0137
0138 /// Multiply Direction with float
0139 /// @param dir Direction value
0140 /// @param value Float to multiply
0141 /// @return Signed float result
0142 constexpr float operator*(Direction dir, float value) {
0143   return dir.sign() * value;
0144 }
0145
0146 /// Multiply Direction with double
0147 /// @param dir Direction value
0148 /// @param value Double to multiply
0149 /// @return Signed double result
0150 constexpr double operator*(Direction dir, double value) {
0151   return dir.sign() * value;
0152 }
0153
0154 /// Multiply Direction with Vector3
0155 /// @param dir Direction value
0156 /// @param value Vector3 to multiply
0157 /// @return Signed Vector3 result
0158 inline Acts::Vector3 operator*(Direction dir, const Acts::Vector3& value) {
0159   return dir.sign() * value;
0160 }
0161
0162 // T * Direction
0163
0164 /// Multiply integer with Direction
0165 /// @param value Integer to multiply
0166 /// @param dir Direction value
0167 /// @return Signed integer result
0168 constexpr int operator*(int value, Direction dir) {
0169   return value * dir.sign();
0170 }
0171
0172 /// Multiply float with Direction
0173 /// @param value Float to multiply
0174 /// @param dir Direction value
0175 /// @return Signed float result
0176 constexpr float operator*(float value, Direction dir) {
0177   return value * dir.sign();
0178 }
0179
0180 /// Multiply double with Direction
0181 /// @param value Double to multiply
0182 /// @param dir Direction value
0183 /// @return Signed double result
0184 constexpr double operator*(double value, Direction dir) {
0185   return value * dir.sign();
0186 }
0187
0188 /// Multiply Vector3 with Direction
0189 /// @param value Vector3 to multiply
0190 /// @param dir Direction value
0191 /// @return Signed Vector3 result
0192 inline Acts::Vector3 operator*(const Acts::Vector3& value, Direction dir) {
0193   return value * dir.sign();
0194 }
0195
0196 // T *= Direction
0197
0198 /// Multiply-assign integer with Direction
0199 /// @param value Integer reference to modify
0200 /// @param dir Direction value
0201 /// @return Reference to modified integer
0202 constexpr int operator*=(int& value, Direction dir) {
0203   value *= dir.sign();
0204   return value;
0205 }
0206
0207 /// Multiply-assign float with Direction
0208 /// @param value Float reference to modify
0209 /// @param dir Direction value
0210 /// @return Reference to modified float
0211 constexpr float operator*=(float& value, Direction dir) {
0212   value *= dir.sign();
0213   return value;
0214 }
0215
0216 /// Multiply-assign double with Direction
0217 /// @param value Double reference to modify
0218 /// @param dir Direction value
0219 /// @return Reference to modified double
0220 constexpr double operator*=(double& value, Direction dir) {
0221   value *= dir.sign();
0222   return value;
0223 }
0224
0225 /// Multiply-assign Vector3 with Direction
0226 /// @param value Vector3 reference to modify
0227 /// @param dir Direction value
0228 /// @return Reference to modified Vector3
0229 inline Acts::Vector3& operator*=(Acts::Vector3& value, Direction dir) {
0230   value *= dir.sign();
0231   return value;
0232 }
0233
0234 }  // namespace Acts