Merge branch 'main' into refactor-stepper-interface-naming

Core/include/Acts/Surfaces/ConeSurface.hpp

@@ -111,12 +111,12 @@ class ConeSurface : public Surface {
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position is the global position where the measurement frame is
   /// constructed
-  /// @param momentum is the momentum used for the measurement frame
+  /// @param direction is the momentum direction used for the measurement frame
   /// construction
   /// @return matrix that indicates the measurement frame
   RotationMatrix3 referenceFrame(const GeometryContext& gctx,
                                  const Vector3& position,
-                                 const Vector3& momentum) const final;
+                                 const Vector3& direction) const final;
 
   /// Return method for surface normal information
   ///
@@ -151,24 +151,24 @@ class ConeSurface : public Surface {
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param lposition is the local position to be transformed
-  /// @param momentum is the global momentum (ignored in this operation)
+  /// @param direction is the global momentum direction (ignored in this operation)
   ///
   /// @return The global position by value
   Vector3 localToGlobal(const GeometryContext& gctx, const Vector2& lposition,
-                        const Vector3& momentum) const final;
+                        const Vector3& direction) const final;
 
   /// Global to local transformation
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position is the global position to be transformed
-  /// @param momentum is the global momentum (ignored in this operation)
+  /// @param direction is the global momentum direction (ignored in this operation)
   /// @param tolerance optional tolerance within which a point is considered
   /// valid on surface
   ///
   /// @return a Result<Vector2> which can be !ok() if the operation fails
   Result<Vector2> globalToLocal(
       const GeometryContext& gctx, const Vector3& position,
-      const Vector3& momentum,
+      const Vector3& direction,
       double tolerance = s_onSurfaceTolerance) const final;
 
   /// Straight line intersection schema from position/direction

Core/include/Acts/Surfaces/CylinderSurface.hpp

@@ -111,11 +111,11 @@ class CylinderSurface : public Surface {
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position is the position where the measurement frame is defined
-  /// @param momentum is the momentum vector (ignored)
+  /// @param direction is the momentum direction vector (ignored)
   /// @return rotation matrix that defines the measurement frame
   RotationMatrix3 referenceFrame(const GeometryContext& gctx,
                                  const Vector3& position,
-                                 const Vector3& momentum) const final;
+                                 const Vector3& direction) const final;
 
   /// Return the surface type
   SurfaceType type() const override;
@@ -161,24 +161,24 @@ class CylinderSurface : public Surface {
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param lposition is the local position to be transformed
-  /// @param momentum is the global momentum (ignored in this operation)
+  /// @param direction is the global momentum direction (ignored in this operation)
   ///
   /// @return The global position by value
   Vector3 localToGlobal(const GeometryContext& gctx, const Vector2& lposition,
-                        const Vector3& momentum) const final;
+                        const Vector3& direction) const final;
 
   /// Global to local transformation
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position is the global position to be transformed
-  /// @param momentum is the global momentum (ignored in this operation)
+  /// @param direction is the global momentum direction (ignored in this operation)
   /// @param tolerance optional tolerance within which a point is considered
   /// valid on surface
   ///
   /// @return a Result<Vector2> which can be !ok() if the operation fails
   Result<Vector2> globalToLocal(
       const GeometryContext& gctx, const Vector3& position,
-      const Vector3& momentum,
+      const Vector3& direction,
       double tolerance = s_onSurfaceTolerance) const final;
 
   /// Straight line intersection schema from position/direction
@@ -201,7 +201,7 @@ class CylinderSurface : public Surface {
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position is the global position as a starting point
-  /// @param direction is the global momentum at the starting point
+  /// @param direction is the global momentum direction at the starting point
   ///
   /// @return is the correction factor due to incident
   double pathCorrection(const GeometryContext& gctx, const Vector3& position,

Core/include/Acts/Surfaces/DiscSurface.hpp

@@ -146,31 +146,31 @@ class DiscSurface : public Surface {
   const SurfaceBounds& bounds() const final;
 
   /// Local to global transformation
-  /// For planar surfaces the momentum is ignored in the local to global
-  /// transformation
+  /// For planar surfaces the momentum direction is ignored in the local to
+  /// global transformation
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param lposition local 2D position in specialized surface frame
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction (optionally ignored)
   ///
   /// @return global position by value
   Vector3 localToGlobal(const GeometryContext& gctx, const Vector2& lposition,
-                        const Vector3& momentum) const final;
+                        const Vector3& direction) const final;
 
   /// Global to local transformation
-  /// @note the momentum is ignored for Disc surfaces in this calculateion
+  /// @note the direction is ignored for Disc surfaces in this calculateion
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global 3D position - considered to be on surface but not
   /// inside bounds (check is done)
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction (optionally ignored)
   /// @param tolerance optional tolerance within which a point is considered
   /// valid on surface
   ///
   /// @return a Result<Vector2> which can be !ok() if the operation fails
   Result<Vector2> globalToLocal(
       const GeometryContext& gctx, const Vector3& position,
-      const Vector3& momentum,
+      const Vector3& direction,
       double tolerance = s_onSurfaceTolerance) const final;
 
   /// Special method for DiscSurface : local<->local transformations polar <->
@@ -242,7 +242,7 @@ class DiscSurface : public Surface {
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position The global position as a starting point
-  /// @param direction The global momentum at the starting point
+  /// @param direction The global momentum direction at the starting point
   /// @return The correction factor due to incident
   double pathCorrection(const GeometryContext& gctx, const Vector3& position,
                         const Vector3& direction) const final;

Core/include/Acts/Surfaces/LineSurface.hpp

@@ -120,13 +120,13 @@ class LineSurface : public Surface {
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position is the global position where the measurement frame is
   /// constructed
-  /// @param momentum is the momentum used for the measurement frame
+  /// @param direction is the momentum direction used for the measurement frame
   /// construction
   ///
   /// @return is a rotation matrix that indicates the measurement frame
   RotationMatrix3 referenceFrame(const GeometryContext& gctx,
                                  const Vector3& position,
-                                 const Vector3& momentum) const final;
+                                 const Vector3& direction) const final;
 
   /// Calculate the jacobian from local to global which the surface knows best,
   /// hence the calculation is done here.
@@ -149,23 +149,24 @@ class LineSurface : public Surface {
       const GeometryContext& gctx, const FreeVector& parameters) const final;
 
   /// Local to global transformation
-  /// for line surfaces the momentum is used in order to interpret the drift
-  /// radius
+  ///
+  /// @note for line surfaces the momentum direction is used in order to interpret the
+  /// drift radius
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param lposition is the local position to be transformed
-  /// @param momentum is the global momentum (used to sign the closest approach)
+  /// @param direction is the global momentum direction (used to sign the closest approach)
   ///
   /// @return global position by value
   Vector3 localToGlobal(const GeometryContext& gctx, const Vector2& lposition,
-                        const Vector3& momentum) const final;
+                        const Vector3& direction) const final;
 
   /// Specified for LineSurface: global to local method without dynamic
   /// memory allocation
   ///
   /// This method is the true global->local transformation.<br>
   /// makes use of globalToLocal and indicates the sign of the Acts::eBoundLoc0
-  /// by the given momentum
+  /// by the given momentum direction
   ///
   /// The calculation of the sign of the radius (or \f$ d_0 \f$) can be done as
   /// follows:<br>
@@ -192,13 +193,13 @@ class LineSurface : public Surface {
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global 3D position - considered to be on surface but not
   /// inside bounds (check is done)
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction (optionally ignored)
   /// @param tolerance (unused)
   ///
   /// @return a Result<Vector2> which can be !ok() if the operation fails
   Result<Vector2> globalToLocal(
       const GeometryContext& gctx, const Vector3& position,
-      const Vector3& momentum,
+      const Vector3& direction,
       double tolerance = s_onSurfaceTolerance) const final;
 
   /// @brief Straight line intersection schema
@@ -249,7 +250,7 @@ class LineSurface : public Surface {
   /// @note input parameters are ignored
   /// @note there's no material associated to the line surface
   double pathCorrection(const GeometryContext& gctx, const Vector3& position,
-                        const Vector3& momentum) const override;
+                        const Vector3& direction) const override;
 
   /// This method returns the bounds of the Surface by reference */
   const SurfaceBounds& bounds() const final;
@@ -288,10 +289,10 @@ class LineSurface : public Surface {
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position is the global position
-  /// @param momentum is the momentum
+  /// @param direction is the momentum direction
   /// @param lposition is the local position to be filled
   bool globalToLocalPlain(const GeometryContext& gctx, const Vector3& position,
-                          const Vector3& momentum, Vector2& lposition) const;
+                          const Vector3& direction, Vector2& lposition) const;
 };
 
 }  // namespace Acts

Core/include/Acts/Surfaces/PlaneSurface.hpp

@@ -117,33 +117,35 @@ class PlaneSurface : public Surface {
   const SurfaceBounds& bounds() const override;
 
   /// Local to global transformation
-  /// For planar surfaces the momentum is ignored in the local to global
+  ///
+  /// @note For planar surfaces the momentum direction is ignored in the local to global
   /// transformation
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param lposition local 2D position in specialized surface frame
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction (optionally ignored)
   ///
   /// @return the global position by value
   Vector3 localToGlobal(const GeometryContext& gctx, const Vector2& lposition,
-                        const Vector3& momentum) const override;
+                        const Vector3& direction) const override;
 
   /// Global to local transformation
-  /// For planar surfaces the momentum is ignored in the global to local
+  ///
+  /// @note For planar surfaces the momentum direction is ignored in the global to local
   /// transformation
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global 3D position - considered to be on surface but not
   /// inside bounds (check is done)
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction (optionally ignored)
   /// method symmetry)
   /// @param tolerance optional tolerance within which a point is considered
   /// valid on surface
   ///
   /// @return a Result<Vector2> which can be !ok() if the operation fails
   Result<Vector2> globalToLocal(
       const GeometryContext& gctx, const Vector3& position,
-      const Vector3& momentum,
+      const Vector3& direction,
       double tolerance = s_onSurfaceTolerance) const override;
 
   /// Method that calculates the correction due to incident angle

Core/include/Acts/Surfaces/Surface.hpp

@@ -271,12 +271,12 @@ class Surface : public virtual GeometryObject,
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global position to be evaludated
-  /// @param momentum global momentum (required for line-type surfaces)
+  /// @param direction global momentum direction (required for line-type surfaces)
   /// @param bcheck BoundaryCheck directive for this onSurface check
   ///
   /// @return boolean indication if operation was successful
   bool isOnSurface(const GeometryContext& gctx, const Vector3& position,
-                   const Vector3& momentum,
+                   const Vector3& direction,
                    const BoundaryCheck& bcheck = true) const;
 
   /// The insideBounds method for local positions
@@ -294,12 +294,12 @@ class Surface : public virtual GeometryObject,
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param lposition local 2D position in specialized surface frame
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction
   ///
   /// @return The global position by value
   virtual Vector3 localToGlobal(const GeometryContext& gctx,
                                 const Vector2& lposition,
-                                const Vector3& momentum) const = 0;
+                                const Vector3& direction) const = 0;
 
   /// Global to local transformation
   /// Generalized global to local transformation for the surface types. Since
@@ -309,14 +309,14 @@ class Surface : public virtual GeometryObject,
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global 3D position - considered to be on surface but not
   /// inside bounds (check is done)
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction
   /// @param tolerance optional tolerance within which a point is considered
   /// valid on surface
   ///
   /// @return a Result<Vector2> which can be !ok() if the operation fails
   virtual Result<Vector2> globalToLocal(
       const GeometryContext& gctx, const Vector3& position,
-      const Vector3& momentum,
+      const Vector3& direction,
       double tolerance = s_onSurfaceTolerance) const = 0;
 
   /// Return method for the reference frame
@@ -326,13 +326,13 @@ class Surface : public virtual GeometryObject,
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global 3D position - considered to be on surface but not
   /// inside bounds (check is done)
-  /// @param momentum global 3D momentum representation (optionally ignored)
+  /// @param direction global 3D momentum direction (optionally ignored)
   ///
   /// @return RotationMatrix3 which defines the three axes of the measurement
   /// frame
   virtual Acts::RotationMatrix3 referenceFrame(const GeometryContext& gctx,
                                                const Vector3& position,
-                                               const Vector3& momentum) const;
+                                               const Vector3& direction) const;
 
   /// Calculate the jacobian from local to global which the surface knows best,
   /// hence the calculation is done here.

Core/include/Acts/Utilities/VectorHelpers.hpp

@@ -15,6 +15,7 @@
 #include "Acts/Utilities/TypeTraits.hpp"
 
 #include <array>
+#include <limits>
 
 #include "Eigen/Dense"
 
@@ -119,7 +120,11 @@ double eta(const Eigen::MatrixBase<Derived>& v) noexcept {
     assert(v.rows() == 3 && "Eta function not valid for non-3D vectors.");
   }
 
-  return std::atanh(v[2] / v.norm());
+  if (v[0] == 0. && v[1] == 0.) {
+    return std::copysign(std::numeric_limits<double>::infinity(), v[2]);
+  } else {
+    return std::asinh(v[2] / perp(v));
+  }
 }
 
 /// @brief Fast evaluation of trigonomic functions.

Core/src/Surfaces/ConeSurface.cpp

@@ -88,7 +88,7 @@ Acts::Vector3 Acts::ConeSurface::rotSymmetryAxis(
 
 Acts::RotationMatrix3 Acts::ConeSurface::referenceFrame(
     const GeometryContext& gctx, const Vector3& position,
-    const Vector3& /*momentum*/) const {
+    const Vector3& /*direction*/) const {
   RotationMatrix3 mFrame;
   // construct the measurement frame
   // measured Y is the local z axis
@@ -109,7 +109,7 @@ Acts::RotationMatrix3 Acts::ConeSurface::referenceFrame(
 
 Acts::Vector3 Acts::ConeSurface::localToGlobal(
     const GeometryContext& gctx, const Vector2& lposition,
-    const Vector3& /*momentum*/) const {
+    const Vector3& /*direction*/) const {
   // create the position in the local 3d frame
   double r = lposition[Acts::eBoundLoc1] * bounds().tanAlpha();
   double phi = lposition[Acts::eBoundLoc0] / r;
@@ -119,7 +119,7 @@ Acts::Vector3 Acts::ConeSurface::localToGlobal(
 
 Acts::Result<Acts::Vector2> Acts::ConeSurface::globalToLocal(
     const GeometryContext& gctx, const Vector3& position,
-    const Vector3& /*momentum*/, double tolerance) const {
+    const Vector3& /*direction*/, double tolerance) const {
   Vector3 loc3Dframe = transform(gctx).inverse() * position;
   double r = loc3Dframe.z() * bounds().tanAlpha();
   if (std::abs(perp(loc3Dframe) - r) > tolerance) {