feat: add Snell's Law refraction angle calculation

Author: soradacroi

physics/snells_law.py

@@ -0,0 +1,75 @@
+"""
+Snell's Law — Refraction Angle Calculation.
+
+Calculates the angle of refraction when light passes between two
+media using Snell's Law: n1 * sin(theta1) = n2 * sin(theta2).
+
+Reference: https://en.wikipedia.org/wiki/Snell%27s_law
+"""
+
+import math
+
+
+def calculate_refraction_angle(
+    index_of_refraction_1: float,
+    index_of_refraction_2: float,
+    incident_angle_degrees: float,
+) -> float:
+    """
+    Calculates the refraction angle of light passing from one medium to another.
+    The law states that, for a given pair of media, the ratio of the sines
+    of angle of incidence and angle of refraction s equal to the refractive
+    index of the second medium with regard to the first which is equal to the
+    ratio of the refractive indices of the two media, or equivalently, to the
+    ratio of the phase velocities in the two media.
+
+
+    Formula: n1 * sin(theta1) = n2 * sin(theta2)
+    or     : (sin(theta1) / sin(theta2)) = (n2 / n1)
+    Where:
+        n1 = refractive index of the first medium
+        n2 = refractive index of the second medium
+        theta1 = angle of incidence
+        theta2 = angle of refraction
+
+    Note: Total Internal Reflection (TIR) occurs when light travels from a
+    denser medium to a rarer medium and the incident angle exceeds the
+    critical angle, making refraction impossible.
+
+    Sources:
+        - https://en.wikipedia.org/wiki/Snell%27s_law
+
+    -----------------------------------------------------------------------------
+
+    >>> calculate_refraction_angle(1.0, 1.33, 60.0)
+    40.63
+    >>> calculate_refraction_angle(2.0, 1.0, 30.0)
+    90.0
+    >>> calculate_refraction_angle(1.33, 1.0, 60.0)
+    Traceback (most recent call last):
+        ...
+    ValueError: Invalid physical inputs: ratio cannot be outside [-1, 1].
+    >>> calculate_refraction_angle(-1.33, 1.0, 60.0)
+    Traceback (most recent call last):
+        ...
+    ValueError: Invalid physical inputs: ratio cannot be outside [-1, 1].
+    >>>
+    """
+
+    incident_angle_radians = math.radians(incident_angle_degrees)
+    refraction_sine = (index_of_refraction_1 / index_of_refraction_2) * math.sin(
+        incident_angle_radians
+    )
+
+    # If the sine value is approximately 1.0 or -1.0, it's at the critical angle
+    # We use math.isclose to account for floating-point precision errors
+    if math.isclose(refraction_sine, 1.0):
+        return 90.0
+    if math.isclose(refraction_sine, -1.0):
+        return -90.0
+
+    if not -1 <= refraction_sine <= 1:
+        raise ValueError("Invalid physical inputs: ratio cannot be outside [-1, 1].")
+
+    refraction_angle = round(math.degrees(math.asin(refraction_sine)), 2)
+    return refraction_angle