Fix mypy errors in lorentz_transformation_four_vector.py (#8075)

* updating DIRECTORY.md

* Fix mypy errors in lorentz_transformation_four_vector.py

* Remove unused symbol vars

* Add function documentation and rewrite algorithm explanation

Previous explanation was misleading, as the code only calculates Lorentz
transformations for movement in the x direction (0 velocity in the y and
z directions) and not movement in any direction

* updating DIRECTORY.md

* Update error message for speed

Co-authored-by: github-actions <${GITHUB_ACTOR}@users.noreply.github.com>

DIRECTORY.md

@@ -557,6 +557,7 @@
   * [Gamma Recursive](maths/gamma_recursive.py)
   * [Gaussian](maths/gaussian.py)
   * [Gaussian Error Linear Unit](maths/gaussian_error_linear_unit.py)
+  * [Gcd Of N Numbers](maths/gcd_of_n_numbers.py)
   * [Greatest Common Divisor](maths/greatest_common_divisor.py)
   * [Greedy Coin Change](maths/greedy_coin_change.py)
   * [Hamming Numbers](maths/hamming_numbers.py)

physics/lorentz_transformation_four_vector.py

@@ -1,39 +1,33 @@
 """
-Lorentz transformation describes the transition from a reference frame P
+Lorentz transformations describe the transition between two inertial reference
-to another reference frame P', each of which is moving in a direction with
+frames F and F', each of which is moving in some direction with respect to the
-respect to the other. The Lorentz transformation implemented in this code
+other. This code only calculates Lorentz transformations for movement in the x
-is the relativistic version using a four vector described by Minkowsky Space:
+direction with no spacial rotation (i.e., a Lorentz boost in the x direction).
-x0 = ct, x1 = x, x2 = y, and x3 = z
+The Lorentz transformations are calculated here as linear transformations of
+four-vectors [ct, x, y, z] described by Minkowski space. Note that t (time) is
+multiplied by c (the speed of light) in the first entry of each four-vector.
 
-NOTE: Please note that x0 is c (speed of light) times t (time).
+Thus, if X = [ct; x; y; z] and X' = [ct'; x'; y'; z'] are the four-vectors for
+two inertial reference frames and X' moves in the x direction with velocity v
+with respect to X, then the Lorentz transformation from X to X' is X' = BX,
+where
 
-So, the Lorentz transformation using a four vector is defined as:
+    | γ  -γβ  0  0|
+B = |-γβ  γ   0  0|
+    | 0   0   1  0|
+    | 0   0   0  1|
 
-|ct'|   | γ  -γβ  0  0|  |ct|
+is the matrix describing the Lorentz boost between X and X',
-|x' | = |-γβ  γ   0  0| *|x |
+γ = 1 / √(1 - v²/c²) is the Lorentz factor, and β = v/c is the velocity as
-|y' |   | 0   0   1  0|  |y |
+a fraction of c.
-|z' |   | 0   0   0  1|  |z |
-
-Where:
-           1
-γ = ---------------
-      -----------
-     /     v^2  |
-    /(1 -  ---
-  -/       c^2
-
-      v
-β = -----
-      c
 
 Reference: https://en.wikipedia.org/wiki/Lorentz_transformation
 """
-from __future__ import annotations
 
 from math import sqrt
 
-import numpy as np  # type: ignore
+import numpy as np
-from sympy import symbols  # type: ignore
+from sympy import symbols
 
 # Coefficient
 # Speed of light (m/s)
@@ -41,79 +35,77 @@ c = 299792458
 
 # Symbols
 ct, x, y, z = symbols("ct x y z")
-ct_p, x_p, y_p, z_p = symbols("ct' x' y' z'")
 
 
 # Vehicle's speed divided by speed of light (no units)
 def beta(velocity: float) -> float:
     """
+    Calculates β = v/c, the given velocity as a fraction of c
     >>> beta(c)
     1.0
-
     >>> beta(199792458)
     0.666435904801848
-
     >>> beta(1e5)
     0.00033356409519815205
-
     >>> beta(0.2)
     Traceback (most recent call last):
       ...
-    ValueError: Speed must be greater than 1!
+    ValueError: Speed must be greater than or equal to 1!
     """
     if velocity > c:
-        raise ValueError("Speed must not exceed Light Speed 299,792,458 [m/s]!")
+        raise ValueError("Speed must not exceed light speed 299,792,458 [m/s]!")
-
-    # Usually the speed u should be much higher than 1 (c order of magnitude)
     elif velocity < 1:
-        raise ValueError("Speed must be greater than 1!")
+        # Usually the speed should be much higher than 1 (c order of magnitude)
+        raise ValueError("Speed must be greater than or equal to 1!")
+
     return velocity / c
 
 
 def gamma(velocity: float) -> float:
     """
+    Calculate the Lorentz factor γ = 1 / √(1 - v²/c²) for a given velocity
     >>> gamma(4)
     1.0000000000000002
-
     >>> gamma(1e5)
     1.0000000556325075
-
     >>> gamma(3e7)
     1.005044845777813
-
     >>> gamma(2.8e8)
     2.7985595722318277
-
     >>> gamma(299792451)
     4627.49902669495
-
     >>> gamma(0.3)
     Traceback (most recent call last):
       ...
-    ValueError: Speed must be greater than 1!
+    ValueError: Speed must be greater than or equal to 1!
-
+    >>> gamma(2 * c)
-    >>> gamma(2*c)
     Traceback (most recent call last):
       ...
-    ValueError: Speed must not exceed Light Speed 299,792,458 [m/s]!
+    ValueError: Speed must not exceed light speed 299,792,458 [m/s]!
     """
-    return 1 / (sqrt(1 - beta(velocity) ** 2))
+    return 1 / sqrt(1 - beta(velocity) ** 2)
 
 
-def transformation_matrix(velocity: float) -> np.array:
+def transformation_matrix(velocity: float) -> np.ndarray:
     """
+    Calculate the Lorentz transformation matrix for movement in the x direction:
+
+    | γ  -γβ  0  0|
+    |-γβ  γ   0  0|
+    | 0   0   1  0|
+    | 0   0   0  1|
+
+    where γ is the Lorentz factor and β is the velocity as a fraction of c
     >>> transformation_matrix(29979245)
     array([[ 1.00503781, -0.10050378,  0.        ,  0.        ],
            [-0.10050378,  1.00503781,  0.        ,  0.        ],
            [ 0.        ,  0.        ,  1.        ,  0.        ],
            [ 0.        ,  0.        ,  0.        ,  1.        ]])
-
     >>> transformation_matrix(19979245.2)
     array([[ 1.00222811, -0.06679208,  0.        ,  0.        ],
            [-0.06679208,  1.00222811,  0.        ,  0.        ],
            [ 0.        ,  0.        ,  1.        ,  0.        ],
            [ 0.        ,  0.        ,  0.        ,  1.        ]])
-
     >>> transformation_matrix(1)
     array([[ 1.00000000e+00, -3.33564095e-09,  0.00000000e+00,
              0.00000000e+00],
@@ -123,16 +115,14 @@ def transformation_matrix(velocity: float) -> np.array:
              0.00000000e+00],
            [ 0.00000000e+00,  0.00000000e+00,  0.00000000e+00,
              1.00000000e+00]])
-
     >>> transformation_matrix(0)
     Traceback (most recent call last):
       ...
-    ValueError: Speed must be greater than 1!
+    ValueError: Speed must be greater than or equal to 1!
-
     >>> transformation_matrix(c * 1.5)
     Traceback (most recent call last):
       ...
-    ValueError: Speed must not exceed Light Speed 299,792,458 [m/s]!
+    ValueError: Speed must not exceed light speed 299,792,458 [m/s]!
     """
     return np.array(
         [
@@ -144,44 +134,39 @@ def transformation_matrix(velocity: float) -> np.array:
     )
 
 
-def transform(
+def transform(velocity: float, event: np.ndarray | None = None) -> np.ndarray:
-    velocity: float, event: np.array = np.zeros(4), symbolic: bool = True  # noqa: B008
-) -> np.array:
     """
-    >>> transform(29979245,np.array([1,2,3,4]), False)
+    Calculate a Lorentz transformation for movement in the x direction given a
-    array([ 3.01302757e+08, -3.01302729e+07,  3.00000000e+00,  4.00000000e+00])
+    velocity and a four-vector for an inertial reference frame
 
+    If no four-vector is given, then calculate the transformation symbolically
+    with variables
+    >>> transform(29979245, np.array([1, 2, 3, 4]))
+    array([ 3.01302757e+08, -3.01302729e+07,  3.00000000e+00,  4.00000000e+00])
     >>> transform(29979245)
     array([1.00503781498831*ct - 0.100503778816875*x,
            -0.100503778816875*ct + 1.00503781498831*x, 1.0*y, 1.0*z],
           dtype=object)
-
     >>> transform(19879210.2)
     array([1.0022057787097*ct - 0.066456172618675*x,
            -0.066456172618675*ct + 1.0022057787097*x, 1.0*y, 1.0*z],
           dtype=object)
-
+    >>> transform(299792459, np.array([1, 1, 1, 1]))
-    >>> transform(299792459, np.array([1,1,1,1]))
     Traceback (most recent call last):
       ...
-    ValueError: Speed must not exceed Light Speed 299,792,458 [m/s]!
+    ValueError: Speed must not exceed light speed 299,792,458 [m/s]!
-
+    >>> transform(-1, np.array([1, 1, 1, 1]))
-    >>> transform(-1, np.array([1,1,1,1]))
     Traceback (most recent call last):
       ...
-    ValueError: Speed must be greater than 1!
+    ValueError: Speed must be greater than or equal to 1!
     """
-    # Ensure event is not a vector of zeros
+    # Ensure event is not empty
-    if not symbolic:
+    if event is None:
-
+        event = np.array([ct, x, y, z])  # Symbolic four vector
-        # x0 is ct (speed of ligt * time)
-        event[0] = event[0] * c
     else:
+        event[0] *= c  # x0 is ct (speed of light * time)
 
-        # Symbolic four vector
+    return transformation_matrix(velocity) @ event
-        event = np.array([ct, x, y, z])
-
-    return transformation_matrix(velocity).dot(event)
 
 
 if __name__ == "__main__":
@@ -197,9 +182,8 @@ if __name__ == "__main__":
     print(f"y' = {four_vector[2]}")
     print(f"z' = {four_vector[3]}")
 
-    # Substitute symbols with numerical values:
+    # Substitute symbols with numerical values
-    values = np.array([1, 1, 1, 1])
+    sub_dict = {ct: c, x: 1, y: 1, z: 1}
-    sub_dict = {ct: c * values[0], x: values[1], y: values[2], z: values[3]}
+    numerical_vector = [four_vector[i].subs(sub_dict) for i in range(4)]
-    numerical_vector = [four_vector[i].subs(sub_dict) for i in range(0, 4)]
 
     print(f"\n{numerical_vector}")