Debian Codegraph @

include/deal.II/physics/vector_relations.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2022 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_vector_relations_h
16 #define dealii_vector_relations_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/tensor.h>
21
22 #include <cmath>
23 #include <limits>
24
25 DEAL_II_NAMESPACE_OPEN
26
27
28 namespace Physics
29 {
30 /**
31 * Functions to compute relations between spatial vectors.
32 */
33 namespace VectorRelations
34 {
35 /**
36 * Calculate the angle $\theta$ between two vectors @p a and @p b. The returned
37 * angle will be in the range $[0, \pi]$.
38 *
39 * This function uses the geometric definition of the scalar product.
40 * @f[
41 * \vec{a} \cdot \vec{b} = \|\vec{a}\| \|\vec{b}\| \cos(\theta)
42 * @f]
43 */
44 template <int spacedim, typename Number>
45 Number
46 angle(const Tensor<1, spacedim, Number> &a,
47 const Tensor<1, spacedim, Number> &b);
48
49 /**
50 * Calculate the angle $\theta$ between two vectors @p a and @p b, where both
51 * vectors are located in a plane described by a normal vector @p axis.
52 *
53 * The angle computed by this function corresponds to the rotation angle
54 * that would transform the vector @p a into the vector @p b around the vector
55 * @p axis. Thus, contrary to the function above, we get a @em signed angle
56 * which will be in the range $[-\pi, \pi]$.
57 *
58 * The vector @p axis needs to be a unit vector and be perpendicular to both
59 * vectors @p a and @p b.
60 *
61 * This function uses the geometric definitions of both the scalar and cross
62 * product.
63 * @f{align*}{
64 * \vec{a} \cdot \vec{b} &= \|\vec{a}\| \|\vec{b}\| \cos(\theta) \\
65 * \vec{a} \times \vec{b} &= \|\vec{a}\| \|\vec{b}\| \sin(\theta) \vec{n}
66 * @f}
67 * We can create the tangent of the angle using both products.
68 * @f[
69 * \tan{\theta}
70 * = \frac{\sin(\theta)}{\cos(theta)}
71 * = \frac{(\vec{a} \times \vec{b}) \cdot \vec{n}}{\vec{a} \cdot \vec{b}}
72 * @f]
73 *
74 * @note Only applicable for three-dimensional vectors `spacedim == 3`.
75 */
76 template <int spacedim, typename Number>
77 Number
78 signed_angle(const Tensor<1, spacedim, Number> &a,
79 const Tensor<1, spacedim, Number> &b,
80 const Tensor<1, spacedim, Number> &axis);
81 } // namespace VectorRelations
82 } // namespace Physics
83
84
85
86 #ifndef DOXYGEN
87
88
89
90 template <int spacedim, typename Number>
91 inline Number
92 Physics::VectorRelations::angle(const Tensor<1, spacedim, Number> &a,
93 const Tensor<1, spacedim, Number> &b)
94 {
95 const Number a_norm = a.norm();
96 const Number b_norm = b.norm();
97 Assert(a_norm > 1.e-12 * b_norm && a_norm > 1.e-12 * b_norm,
98 ExcMessage("Both vectors need to be non-zero!"));
99
100 Number argument = (a * b) / a_norm / b_norm;
101
102 // std::acos returns nan if argument is out of domain [-1,+1].
103 // if argument slightly overshoots these bounds, set it to the bound.
104 // allow for 8*eps as a tolerance.
105 if ((1. - std::abs(argument)) < 8. * std::numeric_limits<Number>::epsilon())
106 argument = std::copysign(1., argument);
107
108 return std::acos(argument);
109 }
110
111
112
113 template <int spacedim, typename Number>
114 inline Number
115 Physics::VectorRelations::signed_angle(const Tensor<1, spacedim, Number> &a,
116 const Tensor<1, spacedim, Number> &b,
117 const Tensor<1, spacedim, Number> &axis)
118 {
119 Assert(spacedim == 3,
120 ExcMessage("This function can only be used with spacedim==3!"));
121
122 Assert(std::abs(axis.norm() - 1.) < 1.e-12,
123 ExcMessage("The axial vector is not a unit vector."));
124 Assert(std::abs(axis * a) < 1.e-12 * a.norm() &&
125 std::abs(axis * b) < 1.e-12 * b.norm(),
126 ExcMessage("The vectors are not perpendicular to the axial vector."));
127
128 const Number dot = a * b;
129 const Number det = axis * cross_product_3d(a, b);
130
131 return std::atan2(det, dot);
132 }
133
134
135
136 #endif // DOXYGEN
137
138 DEAL_II_NAMESPACE_CLOSE
139
140 #endif