Tidy up circularity testing of reciprocal function pairs (#2102)

* A circularity test acts as a functional sanity check.
   Each test acts on pairs of unary operator type functions which reciprocally convert float inputs
   (typically for the two directions of quantity conversion between two similar units
    Celsius <--> Fahrenheit could hypothetically be a valid example)

* Replace sanity checks that were written from scratch independently
   with a set-once use-again, mutually-inverse function pairing

* N.B. The use of a class for the pair rather than a 3 argument util function,
    places the two operator functions on a clearly equal footing,
    distinct from the arbitarily valued numerical probe argument used in verfication;
    whereas a util function muddies the waters, forcing cognitive load back onto the human reader.

Fixes #2102

Author: CoePaul

tests/common/general_maths/operator_inversion_pairing.py

@@ -0,0 +1,45 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import pytest
+
+@dataclass(frozen=True)
+class OperatorInversionPairing:
+    """Represents a pair of mutually reciprocal maths functions, with unique mappings of input to output.
+        Useful for sanity check behavioural tests above the unit level but below integration level.
+        A typical use case is to ensure that after two mutually cancelling numerical operations,
+         an original input number is restored.  This helps tests flag whenever one function breaks,
+         for example - owing to a typo or incorrect or inverted multiplication factor.
+         ( Yes there are even numbers of self-cancelling mistakes which can still hide bugs but
+           hopefully the individual functions, functional tests flush those out ).
+
+    Attributes:
+        unary_op: A unary operation mathematical function (specifically with unique one-to-one mapping).
+        inverse_op: The inverse unary operation.
+    """
+    unary_op: Callable[[float], float]
+    inverse_op: Callable[[float], float]
+
+    def composed_operator(self, x: float) -> float:
+        """Applies both the unary operation followed by the inverse operation on a numerical input.
+            On, for example, the happy path of a test, this round-trip can be expected to result in the original value x.
+
+        Args:
+            x (float): Any numerical argument suitable for the unary operations under test.
+
+        Returns:
+            float: The result from nested application of first the unary operation and then its inverse on x.
+        """
+        f_of_x = self.unary_op(x)
+        return self.inverse_op(f_of_x)
+
+    def composed_operator_is_consistent_with_identity_operator(self, probe_x: float) -> bool:
+        """Assertion used in tests to verify that a pair of functions compose to act like the identity operator.
+            Namely that for f, g where g is the inverse of f, asserts that g(f(x)) is consistent with x to good approximation.
+
+        Args:
+            probe_x (float): Any numerical argument suitable for the unary operations under test.
+        """
+        _round_trip_net_effect = self.composed_operator(probe_x)
+        return _round_trip_net_effect == pytest.approx(probe_x)
+

tests/common/general_maths/test_arithmetic_conversions.py

@@ -1,4 +1,5 @@
 import math
+from collections.abc import Callable
 
 import pydantic
 import pytest
@@ -14,6 +15,8 @@
     convert_percentage_to_factor,
 )
 
+from .operator_inversion_pairing import OperatorInversionPairing
+
 
 # expected success tests (the 'Happy Path'): All numbers here are arbitrary
 @pytest.mark.parametrize("input,result", [(1.0, 0.1), (100.0, 10.0)])
@@ -56,29 +59,51 @@ def test_conversion_from_microns_to_centimetres(input, result):
     assert convert_microns_to_cm(input) == pytest.approx(result)
 
 
-# Circular tests (all numbers here arbitrary)
-
-
-@pytest.mark.parametrize("input", [0.0, 1.0, 10.0, 100.0])
-def test_circular_cm_to_mm_and_back(input):
-    assert convert_cm_to_mm(convert_mm_to_cm(input)) == pytest.approx(input)
-    assert convert_mm_to_cm(convert_cm_to_mm(input)) == pytest.approx(input)
-
+# Circular "sanity check" tests, exercise pairs of reciprocating functions
+# proving the result of applying a function and its inverse results in the original value
 
-@pytest.mark.parametrize("input", [0.0, 1.0, 10.0, 100.0])
-def test_circular_microns_to_mm_and_back(input):
-    assert convert_microns_to_mm(convert_mm_to_microns(input)) == pytest.approx(input)
-    assert convert_mm_to_microns(convert_microns_to_mm(input)) == pytest.approx(input)
 
-
-@pytest.mark.parametrize("input", [0.0, 1.0, 10.0, 100.0])
-def test_circular_percentage_to_factor_and_back(input):
-    assert convert_percentage_to_factor(
-        convert_factor_to_percentage(input)
-    ) == pytest.approx(input)
-    assert convert_factor_to_percentage(
-        convert_percentage_to_factor(input)
-    ) == pytest.approx(input)
+@pytest.mark.parametrize(
+    "f, g, numerical_args",
+    [
+        (
+            convert_ev_to_kev,
+            lambda k: k * 1000.0,
+            [16.83, 0.0, 0.037, 1.0, 6.208, 18, 12345.6, 28906.4],
+        ),
+        (
+            convert_mm_to_cm,
+            convert_cm_to_mm,
+            [-16.83, 0.0, 0.037, 1.0, 6.208, 18, 102.99],
+        ),
+        (
+            convert_microns_to_cm,
+            lambda x: convert_mm_to_microns(convert_cm_to_mm(x)),
+            [-6.119, 0.0, 0.764, 1.02, 62.45, 12754, 3154.59],
+        ),
+        (
+            convert_microns_to_mm,
+            convert_mm_to_microns,
+            [-12.38, 0.0, 0.307, 1.0, 6.45, 24, 231.089],
+        ),
+        (
+            convert_factor_to_percentage,
+            convert_percentage_to_factor,
+            [0.0, 1.0, 0.5, 0.367, 27.404, 100.0, 99.8, 53.647],
+        ),
+    ],
+)
+def test_reciprocal_function_pairs_nest_consistent_with_identity(
+    f: Callable[[float], float],
+    g: Callable[[float], float],
+    numerical_args: list[float],
+):
+    for op_pair in [
+        OperatorInversionPairing(f, g),
+        OperatorInversionPairing(g, f),
+    ]:
+        for x in numerical_args:
+            assert op_pair.composed_operator_is_consistent_with_identity_operator(x)
 
 
 # The inauspicuous path