Adds basic unit conversions for attenuator in general_maths folder

src/dodal/common/general_maths/arithmetic_conversions.py

@@ -0,0 +1,107 @@
+"""Provides functions to convert between common units for attenuation."""
+
+from pydantic import StrictFloat, validate_call
+
+
+@validate_call
+def convert_percentage_to_factor(pc: StrictFloat) -> float:
+    """Takes a percentage value and converts it the corresponding multiplication factor.
+
+    Args:
+        pc (StrictFloat): a percentage
+    Returns:
+        pc (float): a factor
+    """
+    return pc * 1e-2
+
+
+@validate_call
+def convert_factor_to_percentage(f: StrictFloat) -> float:
+    """Takes a multiplication factor and converts it to the corresponding percentage.
+
+    Args:
+        f (StrictFloat): a factor
+
+    Returns:
+        f (float): a percentage
+    """
+    return f * 1e2
+
+
+@validate_call
+def convert_microns_to_cm(t_um: StrictFloat) -> float:
+    """Takes the numerical part of a distance in microns and converts this to cm.
+
+    Args:
+        t_um (StrictFloat): a distance in microns
+
+    Returns:
+        t_um (float): a distance in cm
+    """
+    return t_um * 1e-4
+
+
+@validate_call
+def convert_microns_to_mm(v_um: StrictFloat) -> float:
+    """Takes the numerical part of a distance in microns and converts this to mm.
+
+    Args:
+        v_um (StrictFloat): a distance in microns
+
+    Returns:
+        v_um (float): a distance in mm
+    """
+    return v_um * 1e-3
+
+
+@validate_call
+def convert_mm_to_microns(w_mm: StrictFloat) -> float:
+    """Takes the numerical part of a distance in mm and converts this to microns.
+
+    Args:
+        w_mm (StrictFloat): a distance in mm
+
+    Returns:
+        w_um (float): a distance in microns
+    """
+    return w_mm * 1e3
+
+
+@validate_call
+def convert_mm_to_cm(x_mm: StrictFloat) -> float:
+    """Takes the numerical part of a distance in mm and converts this to cm.
+
+    Args:
+        x_mm (StrictFloat): a distance in mm
+
+    Returns:
+        w_um (float): a distance in cm
+    """
+    return x_mm * 1e-1
+
+
+@validate_call
+def convert_cm_to_mm(y_cm: StrictFloat) -> float:
+    """Takes the numerical part of a distance in cm and converts this to mm.
+
+    Args:
+        y_cm (StrictFloat): a distance in cm
+
+    Returns:
+        w_um (float): a distance in mm
+    """
+    return y_cm * 1e1
+
+
+@validate_call
+def convert_ev_to_kev(energy_ev: StrictFloat) -> float:
+    """Takes the numerical part of an x-ray energy in electron volts and converts this
+    to keV.
+
+    Args:
+        energy_ev (StrictFloat): a value of electron volts
+
+    Returns:
+        energy_ev (float): a value of kilo-electron volts
+    """
+    return energy_ev * 1e-3

src/dodal/common/general_maths/check_bounds.py

@@ -0,0 +1,46 @@
+"""Provides a checker to determine if a value is within a certain range."""
+
+from pydantic import BaseModel, StrictFloat, model_validator, validate_call
+
+
+def subordinate_range_test(
+    lower_bound: StrictFloat, upper_bound: StrictFloat, x: StrictFloat
+) -> bool:
+    outside_range = x < lower_bound or x > upper_bound
+    return not outside_range
+
+
+@validate_call
+def is_within_range(
+    lower_bound: StrictFloat,
+    upper_bound: StrictFloat,
+    tested_value: StrictFloat,
+) -> bool:
+    """Checks if a single value falls between two bounds, a lower (first) and an upper
+    (second).
+
+    Args:
+        lower_bound (StrictFloat): the smaller of the two values
+        upper_bound (StrictFloat): the greater of the two values
+        tested_value (StrictFloat): the value to be tested
+
+    Returns:
+        outside_range (bool): True if the tested value falls between, or False if not
+    """
+
+    class ValueRange(BaseModel):
+        lo: StrictFloat
+        hi: StrictFloat
+
+        @model_validator(mode="after")
+        def validate_bounds(self) -> "ValueRange":
+            if self.hi < self.lo:
+                raise ValueError(f"Upper bound {self.hi} < Lower bound {self.lo}")
+            return self
+
+    ValueRange(lo=lower_bound, hi=upper_bound)
+    return subordinate_range_test(
+        lower_bound,
+        upper_bound,
+        tested_value,
+    )

tests/common/general_maths/test_arithmetic_conversions.py

@@ -0,0 +1,129 @@
+import math
+
+import pydantic
+import pytest
+
+from dodal.common.general_maths.arithmetic_conversions import (
+    convert_cm_to_mm,
+    convert_ev_to_kev,
+    convert_factor_to_percentage,
+    convert_microns_to_cm,
+    convert_microns_to_mm,
+    convert_mm_to_cm,
+    convert_mm_to_microns,
+    convert_percentage_to_factor,
+)
+
+
+# expected success tests (the 'Happy Path'): All numbers here are arbitrary
+@pytest.mark.parametrize("input,result", [(1.0, 0.1), (100.0, 10.0)])
+def test_conversion_from_millimetres_to_centimetres(input, result):
+    assert convert_mm_to_cm(input) == pytest.approx(result)
+
+
+@pytest.mark.parametrize("input,result", [(1.0, 10), (0.1, 1.0)])
+def test_conversion_from_centimetres_to_millimetres(input, result):
+    assert convert_cm_to_mm(input) == pytest.approx(result)
+
+
+@pytest.mark.parametrize("input,result", [(0.01, 1.0), (1.0, 100.0)])
+def test_conversion_to_percentage_from_factor(input, result):
+    assert convert_factor_to_percentage(input) == pytest.approx(result)
+
+
+@pytest.mark.parametrize("input,result", [(1.0, 0.01), (100, 1.0)])
+def test_conversion_to_factor_from_percentage(input, result):
+    assert convert_percentage_to_factor(input) == pytest.approx(result)
+
+
+@pytest.mark.parametrize("input,result", [(1000.0, 1.0), (10000.0, 10.0)])
+def test_conversion_from_microns_to_millimeters(input, result):
+    assert convert_microns_to_mm(input) == pytest.approx(result)
+
+
+@pytest.mark.parametrize("input,result", [(1.0, 1000.0), (10, 10000.0)])
+def test_conversion_from_millimeters_to_microns(input, result):
+    assert convert_mm_to_microns(input) == pytest.approx(result)
+
+
+@pytest.mark.parametrize("input,result", [(1000, 1.0), (100, 0.1)])
+def test_conversion_from_electronvolts_to_kiloelectronvolts(input, result):
+    assert convert_ev_to_kev(input) == pytest.approx(result)
+
+
+@pytest.mark.parametrize("input,result", [(10000.0, 1.0), (1000, 0.1)])
+def test_conversion_from_microns_to_centimetres(input, result):
+    assert convert_microns_to_cm(input) == pytest.approx(result)
+
+
+# The inauspicuous path
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_microns_to_cm_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_microns_to_cm(bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_ev_to_kev_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_ev_to_kev(bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_microns_to_mm_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_microns_to_mm(bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_mm_to_microns_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_mm_to_microns(bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_factor_to_percentage_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_factor_to_percentage(bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_percentage_to_factor_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_percentage_to_factor(bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_mm_to_cm_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_mm_to_cm(bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    ["a", [], None, math.sin, object(), False],
+)
+def test_convert_cm_to_mm_raises_error_with_bad_input(bad_input):
+    with pytest.raises(pydantic.ValidationError):
+        convert_cm_to_mm(bad_input)

tests/common/general_maths/test_check_bounds.py

@@ -0,0 +1,99 @@
+import math
+
+import pydantic_core
+import pytest
+
+from dodal.common.general_maths.check_bounds import is_within_range
+
+
+# Happy Path
+@pytest.mark.parametrize(
+    "lower_bound,upper_bound,tested_value,result",
+    [
+        (1.0, 3.0, 2.0, True),
+        (-3.0, -1.0, -2, True),
+        (-1.0, 1.0, 0.0, True),
+        (-1.0, -0.1, -0.5, True),
+        (0.1, 1, 0.5, True),
+    ],
+)
+def test_is_within_range(
+    lower_bound: float, upper_bound: float, tested_value: float, result: bool
+):
+    assert is_within_range(lower_bound, upper_bound, tested_value) == result
+
+
+@pytest.mark.parametrize(
+    "lower_bound,upper_bound,tested_value,result",
+    [
+        (1, 2, 3, False),
+        (-3, -1, -4, False),
+        (1, 2, 0, False),
+        (-1, -0.1, -10.0, False),
+        (0.1, 1, 1.5, False),
+    ],
+)
+def test_is_outside_range(
+    lower_bound: float, upper_bound: float, tested_value: float, result: bool
+):
+    assert is_within_range(lower_bound, upper_bound, tested_value) == result
+
+
+# Inauspicious Path
+def test_has_misordered_inputs():
+    with pytest.raises(ValueError):
+        is_within_range(4, -4, 1)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    [
+        (
+            "a",
+            None,
+            math.sin,
+            object(),
+        ),
+    ],
+)
+def test_is_within_range_raises_error_with_bad_tested_value(
+    bad_input,
+):
+    with pytest.raises(pydantic_core.ValidationError):
+        is_within_range(-4, 4, bad_input)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    [
+        (
+            "a",
+            None,
+            math.sin,
+            object(),
+        ),
+    ],
+)
+def test_is_within_range_raises_error_with_bad_upper_bound(
+    bad_input,
+):
+    with pytest.raises(pydantic_core.ValidationError):
+        is_within_range(-4, bad_input, 4)
+
+
+@pytest.mark.parametrize(
+    "bad_input",
+    [
+        (
+            "a",
+            None,
+            math.sin,
+            object(),
+        ),
+    ],
+)
+def test_is_within_range_raises_error_with_bad_lower_bound(
+    bad_input,
+):
+    with pytest.raises(pydantic_core.ValidationError):
+        is_within_range(bad_input, 4, 0)