Adds attenuation transmission interconversion calculations

src/dodal/common/general_maths/transmission_interconversion.py

@@ -0,0 +1,55 @@
+import math
+
+
+def attenuation_from_natural_log_of_transmission(ln_t: float):
+    """Converts from natural log of transmission fraction into Barnett attenuation units
+    .
+
+    Args:
+        ln_t (float): natural log of transmission fraction
+
+    Returns:
+        (float): Barnett attenuation units
+    """
+    _canonical_barnett_conversion = -1.0e3
+    return _canonical_barnett_conversion * ln_t
+
+
+def attenuation_from_transmission(transmission_as_fraction: float):
+    """Converts from transmission fraction into Barnett attenuation units.
+
+    Args:
+        transmission_as_fraction (float): transmission fraction
+
+    Returns:
+        (float): Barnett attenuation units.
+    """
+    ln_t = math.log(transmission_as_fraction)
+    return attenuation_from_natural_log_of_transmission(ln_t)
+
+
+def natural_log_of_transmission_from_attenuation(attenuation_bn: float):
+    """Converts from Barnett attenuation units into natural log of transmission fraction
+    .
+
+    Args:
+        attenuation_bn (float): Barnett attenuation units
+
+    Returns:
+        (float): natural log of transmission fraction
+    """
+    _reverse_barnett_conversion = -1.0e-3
+    return _reverse_barnett_conversion * attenuation_bn
+
+
+def transmission_from_attenutation(attenuation_bn: float):
+    """Converts from Barnett attenuation units into transmission fraction.
+
+    Args:
+        attenuation_bn (float): Barnett attenuation units
+
+    Returns:
+        (float): transmission fraction
+    """
+    ln_t = natural_log_of_transmission_from_attenuation(attenuation_bn)
+    return math.exp(ln_t)

tests/common/general_maths/test_attenuation_from_ln_transmission.py

@@ -0,0 +1,38 @@
+import math
+
+import pytest
+
+from dodal.common.general_maths import transmission_interconversion
+
+
+# happy path
+@pytest.mark.parametrize(
+    "ln_t,result",
+    [
+        (-1, 1000),  # tests negative unity log of transmission is 1000 (canonical)
+        (0, 0),  # tests natural log of transparency is zero (canonical)
+        (
+            -0.4367,
+            436.7,
+        ),  # tests log from arbitrary high transmission is -1000 * log
+        (
+            -5.9017,
+            5901.7,
+        ),  # tests log from arbitrary low transmission is -1000 * log
+    ],
+)
+def test_attenuation_from_natural_log_of_transmission(ln_t, result):
+    assert transmission_interconversion.attenuation_from_natural_log_of_transmission(
+        ln_t
+    ) == pytest.approx(result)
+
+
+# inauspicious:
+
+
+@pytest.mark.parametrize("bad_input", ["a", [], None, math.sin, object()])
+def test_attenuation_from_natural_log_of_transmission_raises_error(bad_input):
+    with pytest.raises(TypeError):
+        transmission_interconversion.attenuation_from_natural_log_of_transmission(
+            bad_input
+        )

tests/common/general_maths/test_attenuation_from_transmission.py

@@ -0,0 +1,37 @@
+import math
+
+import pytest
+
+from dodal.common.general_maths import transmission_interconversion
+
+# happy:
+
+
+@pytest.mark.parametrize(
+    "transmission_as_fraction,result",
+    [
+        (1, 0),  # tests attenuation from transparency is zero (canonical)
+        (0.37, 994.25227334),  # tests attenuation from 37% is close to 1000 (canonical)
+        (
+            0.871,
+            138.1133,
+        ),  # tests attenuation from arbitrary high transmission has expected value
+        (
+            4.2e-4,
+            7775.2558,
+        ),  # tests attenuation from arbitrary high attenuation has expected value
+    ],
+)
+def test_attenuation_from_transmission(transmission_as_fraction, result):
+    assert transmission_interconversion.attenuation_from_transmission(
+        transmission_as_fraction
+    ) == pytest.approx(result)
+
+
+# inauspicious:
+
+
+@pytest.mark.parametrize("bad_input", ["a", [], None, math.sin, object()])
+def test_attenuation_from_transmission_raises_error(bad_input):
+    with pytest.raises(TypeError):
+        transmission_interconversion.attenuation_from_transmission(bad_input)

tests/common/general_maths/test_ln_transmission_from_attenuation.py

@@ -0,0 +1,42 @@
+import math
+
+import pytest
+
+from dodal.common.general_maths import transmission_interconversion
+
+
+# happy:
+@pytest.mark.parametrize(
+    "attenuation_bn,result",
+    [
+        (0, 0),  # tests natural log of transparency from attenuation (canonical)
+        (
+            1e3,
+            -1,
+        ),  # tests natural log of transmission from canonical transmission is negative
+        # unity (canonical)
+        (
+            712.6,
+            -0.7126,
+        ),  # tests attenuation from natural log arbitrary high transmission is -1000 *
+        # attenuation
+        (
+            8034.1,
+            -8.0341,
+        ),  # tests attenuation from natural log arbitrary low transmission is -1000 *
+        # attenuation
+    ],
+)
+def test_natural_log_of_transmission_from_attenuation(attenuation_bn, result):
+    assert transmission_interconversion.natural_log_of_transmission_from_attenuation(
+        attenuation_bn
+    ) == pytest.approx(result)
+
+
+# inauspicious:
+@pytest.mark.parametrize("bad_input", ["a", [], None, math.sin, object()])
+def test_natural_log_of_transmission_from_attenuation_raises_error(bad_input):
+    with pytest.raises(TypeError):
+        transmission_interconversion.natural_log_of_transmission_from_attenuation(
+            bad_input
+        )

tests/common/general_maths/test_transmission_from_attenuation.py

@@ -0,0 +1,39 @@
+import math
+
+import pytest
+
+from dodal.common.general_maths import transmission_interconversion
+
+
+# happy:
+@pytest.mark.parametrize(
+    "attenuation_bn,result",
+    [
+        (0, 1),  # tests transparency from zero attenuation (canonical)
+        (
+            1e3,
+            0.3678794,
+        ),  # tests transmission from canonical attenuation is  1/e (canonical)
+        (
+            145.1,
+            0.8649358,
+        ),  # tests transmission from arbitrary weak attenuation is -1000*attenuation
+        (
+            7221.9,
+            7.3041331435179e-4,
+        ),  # tests transmission from arbitrary strong attenuation is -1000*attenuation
+    ],
+)
+def test_transmission_from_attenutation(attenuation_bn, result):
+    assert transmission_interconversion.transmission_from_attenutation(
+        attenuation_bn
+    ) == pytest.approx(result)
+
+
+# inauspicious:
+
+
+@pytest.mark.parametrize("bad_input", ["a", [], None, math.sin, object()])
+def test_transmission_from_attenutation_raises_error(bad_input):
+    with pytest.raises(TypeError):
+        transmission_interconversion.transmission_from_attenutation(bad_input)