detray/utils/unit_vectors.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 // Project include(s).
0012 #include "detray/definitions/algebra.hpp"
0013 #include "detray/definitions/containers.hpp"
0014 #include "detray/definitions/detail/qualifiers.hpp"
0015
0016 namespace detray {
0017
0018 template <concepts::vector3D vector3_t>
0019 struct unit_vectors {
0020   /// Construct the first curvilinear unit vector `U` for the given direction.
0021   ///
0022   /// @param dir is the input direction vector
0023   /// @returns a normalized vector in the x-y plane orthogonal to the
0024   /// direction.
0025   ///
0026   /// The special case of the direction vector pointing along the z-axis is
0027   /// handled by forcing the unit vector to along the x-axis.
0028   DETRAY_HOST_DEVICE inline vector3_t make_curvilinear_unit_u(
0029       const vector3_t& dir) {
0030     vector3_t unit_u{0.f, 0.f, 0.f};
0031     // explicit version of U = Z x T
0032     unit_u[0] = -dir[1];
0033     unit_u[1] = dir[0];
0034
0035     // if the absolute scale is tiny, the initial direction vector is
0036     // aligned with the z-axis. the ZxT product is ill-defined since any
0037     // vector in the x-y plane would be orthogonal to the direction. fix the
0038     // U unit vector along the x-axis to avoid this numerical instability.
0039     if (const auto scale = vector::norm(unit_u); scale < 1e-6f) {
0040       unit_u[0] = 1;
0041       unit_u[1] = 0;
0042     } else {
0043       unit_u = unit_u * (1.f / scale);
0044     }
0045
0046     return unit_u;
0047   }
0048
0049   /// Construct the curvilinear unit vectors `U` and `V` for the given
0050   /// direction.
0051   ///
0052   /// @param dir is the input direction vector
0053   /// @returns normalized unit vectors `U` and `V` orthogonal to the
0054   /// direction.
0055   ///
0056   /// With `T` the normalized input direction, the three vectors `U`, `V`, and
0057   /// `T` form an orthonormal basis set, i.e. they satisfy
0058   ///
0059   ///     U x V = T
0060   ///     V x T = U
0061   ///     T x U = V
0062   ///
0063   /// with the additional condition that `U` is located in the global x-y
0064   /// plane.
0065   DETRAY_HOST_DEVICE inline darray<vector3_t, 2> make_curvilinear_unit_vectors(
0066       const vector3_t& dir) {
0067     darray<vector3_t, 2> uv;
0068     uv[0] = make_curvilinear_unit_u(dir);
0069     uv[1] = vector::normalize(vector::cross(dir, uv[0]));
0070
0071     return uv;
0072   }
0073 };
0074
0075 }  // namespace detray