ucon 0.3.1rc4__tar.gz → 0.3.2__tar.gz

{ucon-0.3.1rc4 → ucon-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.1rc4
+Version: 0.3.2
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi

ucon-0.3.2/docs/unity-distance-metric-for-nearest-scale.md

@@ -0,0 +1,72 @@
+# The Unity-Distance Metric
+
+The **Unity-Distance Metric** provides a principled method for selecting the most natural scale prefix (e.g., kilo, mega, milli) for a given value.
+
+It defines “nearness” not as linear numerical proximity, but as proximity in **order of magnitude** — that is, how close a value is to **unity (1)** when normalized by a candidate scale. This shift from linear to logarithmic thinking brings mathematical rigor to what users intuitively mean when they say a quantity _“belongs”_ to a certain scale.
+
+---
+
+## 1. Why Linear Distance Fails
+
+Linear distance (`|x − s|`) feels intuitive because it mirrors ordinary subtraction. However, it collapses at extremes: the gap between 10³ and 10⁶ is treated as 999,000 rather than just _“three orders apart.”_
+
+As magnitudes grow, linear distance overweights large scales and underweights small ones.
+This causes the selection to favor higher prefixes (like **mega**) even when a value (like 50,000) clearly fits better under **kilo**.
+In physical reasoning, a thousandfold difference should count equally regardless of where it occurs and **logarithmic distance** achieves that symmetry.
+
+---
+
+## 2. Defining the Unity-Distance
+
+For a given value _x_ and candidate scale _s_, the unity-distance is defined as:
+
+```
+d(s, x) = | log₁₀(x / s) |
+```
+
+This measures how far _x_ is from **unity (1)** after being divided by the scale.
+
+- If dividing by _s_ yields exactly 1, then _d = 0_ (perfect match).
+- If _x/s = 10_ or _0.1_, the distance is 1 (one order of magnitude away).
+
+This formulation directly expresses the idea: _“How close to 1 does this value become when scaled?”_
+
+---
+
+## 3. The Bias Factor: Human Perception of Overshoot
+
+While logarithmic distance correctly measures proportional difference, human intuition distinguishes between **overshooting** and **undershooting** unity.
+
+Describing 50,000 as _“fifty thousands”_ feels natural, while _“0.05 millions”_ feels wrong even though both are one order of magnitude apart.
+To capture this asymmetry, the Unity-Distance Metric introduces a **bias factor**:
+
+```
+if ratio < 1:
+    diff /= undershoot_bias   # undershoot_bias < 1
+```
+
+When the ratio `x/s < 1` (meaning the scale candidate is too large), the distance is **divided by a bias constant < 1**, penalizing undershoots more heavily.
+This anchors the metric in _perceptual realism_ favoring scales yielding results slightly above 1 over those just below.
+
+---
+
+## 4. Why Log Base 10 Works for Binary Prefixes
+
+Even though binary prefixes (kibi, mebi) use base 2, the base-10 logarithm remains effective because it measures **proportional magnitude**, not representation base.
+
+Key insight:
+`log₁₀(2¹⁰) ≈ 3` — meaning a binary thousand (1024) is roughly one decimal order above 10³.
+
+Thus, log₁₀ space preserves the **relative alignment** between decimal and binary prefixes.
+A suitable bias factor ensures that **1024** can be interpreted as either _kilo_ or _kibi_, depending on user preference — without distorting order relationships.
+
+---
+
+## 5. Summary
+
+The Unity-Distance Metric offers a unified, perceptually accurate method for determining the most natural scale prefix.
+By measuring distance in orders of magnitude and adjusting with a bias that reflects human expectation, it harmonizes **mathematical rigor** with **intuitive scale reasoning**.
+
+Linear proximity is easy to compute, but logarithmic unity-distance expresses what users mean when they say:
+
+> _“It’s about a thousand,”* or *“roughly a megabyte.”_

{ucon-0.3.1rc4 → ucon-0.3.2}/tests/ucon/test_core.py

@@ -105,6 +105,7 @@ class TestScale(TestCase):
         self.assertEqual(Scale.deca, Scale.kilo / Scale.hecto)
         self.assertEqual(Scale._kibi, Scale.one / Scale.kibi)
         self.assertEqual(Scale.kibi, Scale.kibi / Scale.one)
+        self.assertEqual(Scale.one, Scale.one / Scale.one)
         self.assertEqual(Scale.one, Scale.kibi / Scale.kibi)
         self.assertEqual(Scale.one, Scale.kibi / Scale.kilo)
 
@@ -120,6 +121,92 @@ class TestScale(TestCase):
         self.assertIsInstance(Scale.all(), dict)
 
 
+class TestScaleDivisionAdditional(TestCase):
+
+    def test_division_same_base_large_gap(self):
+        # kilo / milli = mega
+        self.assertEqual(Scale.kilo / Scale.milli, Scale.mega)
+        # milli / kilo = micro
+        self.assertEqual(Scale.milli / Scale.kilo, Scale.micro)
+
+    def test_division_cross_base_scales(self):
+        # Decimal vs binary cross-base — should return nearest matching scale
+        result = Scale.kilo / Scale.kibi
+        self.assertIsInstance(result, Scale)
+        # They’re roughly equal, so nearest should be Scale.one
+        self.assertEqual(result, Scale.one)
+
+    def test_division_binary_inverse_scales(self):
+        self.assertEqual(Scale.kibi / Scale.kibi, Scale.one)
+        self.assertEqual(Scale.kibi / Scale.mebi, Scale._kibi)
+        self.assertEqual(Scale.mebi / Scale.kibi, Scale.kibi)
+
+    def test_division_unmatched_returns_nearest(self):
+        # giga / kibi is a weird combo → nearest mega or similar
+        result = Scale.giga / Scale.kibi
+        self.assertIsInstance(result, Scale)
+        self.assertIn(result, Scale)
+
+    def test_division_type_safety(self):
+        # Ensure non-Scale raises NotImplemented
+        with self.assertRaises(TypeError):
+            Scale.kilo / 42
+
+
+class TestScaleNearestAdditional(TestCase):
+
+    def test_nearest_handles_zero(self):
+        self.assertEqual(Scale.nearest(0), Scale.one)
+
+    def test_nearest_handles_negative_values(self):
+        # Only magnitude matters, not sign
+        self.assertEqual(Scale.nearest(-1000), Scale.kilo)
+        self.assertEqual(Scale.nearest(-0.001), Scale.milli)
+
+    def test_nearest_with_undershoot_bias_effect(self):
+        # Lower bias should make undershoot (ratios < 1) less penalized
+        # This test ensures the bias argument doesn’t break ordering
+        s_default = Scale.nearest(50_000, undershoot_bias=0.75)
+        s_stronger_bias = Scale.nearest(50_000, undershoot_bias=0.9)
+        # The result shouldn't flip to something wildly different
+        self.assertIn(s_default, [Scale.kilo, Scale.mega])
+        self.assertIn(s_stronger_bias, [Scale.kilo, Scale.mega])
+
+    def test_nearest_respects_binary_preference_flag(self):
+        # Confirm that enabling binary changes candidate set
+        decimal_result = Scale.nearest(2**10)
+        binary_result = Scale.nearest(2**10, include_binary=True)
+        self.assertNotEqual(decimal_result, binary_result)
+        self.assertEqual(binary_result, Scale.kibi)
+
+    def test_nearest_upper_and_lower_extremes(self):
+        self.assertEqual(Scale.nearest(10**9), Scale.giga)
+        self.assertEqual(Scale.nearest(10**-9), Scale.nano)
+
+
+class TestScaleInternals(TestCase):
+
+    def test_decimal_and_binary_sets_are_disjoint(self):
+        decimal_bases = {s.value.base for s in Scale._decimal_scales()}
+        binary_bases = {s.value.base for s in Scale._binary_scales()}
+        self.assertNotEqual(decimal_bases, binary_bases)
+        self.assertEqual(decimal_bases, {10})
+        self.assertEqual(binary_bases, {2})
+
+    def test_all_and_by_value_consistency(self):
+        mapping = Scale.all()
+        value_map = Scale.by_value()
+        # Each value’s evaluated form should appear in by_value keys
+        for (base, power), name in mapping.items():
+            val = Scale[name].value.evaluated
+            self.assertIn(round(val, 15), value_map)
+
+    def test_all_and_by_value_are_cached(self):
+        # Call multiple times and ensure they’re same object (cached)
+        self.assertIs(Scale.all(), Scale.all())
+        self.assertIs(Scale.by_value(), Scale.by_value())
+
+
 class TestNumber(TestCase):
 
     number = Number(unit=units.gram, quantity=1)
@@ -288,6 +375,21 @@ class TestExponentEdgeCases(TestCase):
 
 class TestScaleEdgeCases(TestCase):
 
+    def test_nearest_prefers_decimal_by_default(self):
+        self.assertEqual(Scale.nearest(1024), Scale.kilo)
+        self.assertEqual(Scale.nearest(50_000), Scale.kilo)
+        self.assertEqual(Scale.nearest(1/1024), Scale.milli)
+
+    def test_nearest_includes_binary_when_opted_in(self):
+        self.assertEqual(Scale.nearest(1/1024, include_binary=True), Scale._kibi)
+        self.assertEqual(Scale.nearest(1024, include_binary=True), Scale.kibi)
+        self.assertEqual(Scale.nearest(50_000, include_binary=True), Scale.kibi)
+        self.assertEqual(Scale.nearest(2**20, include_binary=True), Scale.mebi)
+
+    def test_nearest_subunit_behavior(self):
+        self.assertEqual(Scale.nearest(0.0009), Scale.milli)
+        self.assertEqual(Scale.nearest(1e-7), Scale.micro)
+
     def test_division_same_base_scales(self):
         result = Scale.kilo / Scale.milli
         self.assertIsInstance(result, Scale)

{ucon-0.3.1rc4 → ucon-0.3.2}/ucon/core.py

@@ -16,10 +16,10 @@ Together, these classes allow full arithmetic, conversion, and introspection
 of physical quantities with explicit dimensional semantics.
 """
 from enum import Enum
-from functools import reduce, total_ordering
+from functools import lru_cache, reduce, total_ordering
 from math import log2
 from math import log10
-from typing import Tuple, Union
+from typing import Dict, Tuple, Union
 
 from ucon import units
 from ucon.unit import Unit
@@ -131,8 +131,10 @@ class Scale(Enum):
 
     Each entry stores its numeric scaling factor (e.g., `kilo = 10³`).
     """
+    gibi  = Exponent(2, 30)
     mebi  = Exponent(2, 20)
     kibi  = Exponent(2, 10)
+    giga  = Exponent(10, 9)
     mega  = Exponent(10, 6)
     kilo  = Exponent(10, 3)
     hecto = Exponent(10, 2)
@@ -142,43 +144,101 @@ class Scale(Enum):
     centi = Exponent(10,-2)
     milli = Exponent(10,-3)
     micro = Exponent(10,-6)
-    _kibi = Exponent(2,-10)
-    _mebi = Exponent(2,-20)
+    nano = Exponent(10,-9)
+    _kibi = Exponent(2,-10)   # "kibi" inverse
+    _mebi = Exponent(2,-20)   # "mebi" inverse
+    _gibi = Exponent(2,-30)   # "gibi" inverse
 
     @staticmethod
-    def all():
-        return dict(map(lambda x: ((x.value.base, x.value.power), x.name), Scale))
+    @lru_cache(maxsize=1)
+    def all() -> Dict[Tuple[int, int], str]:
+        """Return a map from (base, power) → Scale name."""
+        return {(s.value.base, s.value.power): s.name for s in Scale}
 
     @staticmethod
-    def by_value():
-        return dict(map(lambda x: (x.value.evaluated, x.name), Scale))
+    @lru_cache(maxsize=1)
+    def by_value() -> Dict[float, str]:
+        """
+        Return a map from evaluated numeric value → Scale name.
+        Cached after first access.
+        """
+        return {round(s.value.evaluated, 15): s.name for s in Scale}
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def _decimal_scales(cls):
+        """Return decimal (base-10) scales only."""
+        return list(s for s in cls if s.value.base == 10)
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def _binary_scales(cls):
+        """Return binary (base-2) scales only."""
+        return list(s for s in cls if s.value.base == 2)
+
+    @classmethod
+    def nearest(cls, value: float, include_binary: bool = False, undershoot_bias: float = 0.75) -> "Scale":
+        """
+        Return the Scale that best normalizes `value` toward 1 in log-space.
+        Optionally restricts to base-10 prefixes unless `include_binary=True`.
+        """
+        if value == 0:
+            return Scale.one
+
+        abs_val = abs(value)
+        candidates = cls._decimal_scales() if not include_binary else list(cls)
+
+        def distance(scale: "Scale") -> float:
+            ratio = abs_val / scale.value.evaluated
+            diff = log10(ratio)
+            # Bias overshoots slightly more than undershoots
+            if ratio < 1:
+                diff /= undershoot_bias
+            return abs(diff)
+
+        return min(candidates, key=distance)
 
-    def __truediv__(self, another_scale):
-        power_diff = self.value.power - another_scale.value.power
-        if self.value == another_scale.value:
+    def __truediv__(self, other: 'Scale'):
+        """
+        Divide one Scale by another.
+
+        Always returns a `Scale`, representing the resulting order of magnitude.
+        If no exact prefix match exists, returns the nearest known Scale.
+        """
+        if not isinstance(other, Scale):
+            return NotImplemented
+
+        if self == other:
             return Scale.one
-        if self.value.base == another_scale.value.base:
-            return Scale[Scale.all()[Exponent(self.value.base, power_diff).parts()]]
 
-        base_quotient = self.value.base / another_scale.value.base
-        exp_quotient = round((base_quotient ** another_scale.value.power) * (self.value.base ** power_diff), 15)
+        if other is Scale.one:
+            return self
+
+        should_consider_binary = (self.value.base == 2) or (other.value.base == 2)
+
+        if self is Scale.one:
+            result = Exponent(other.value.base, -other.value.power)
+            name = Scale.all().get((result.base, result.power))
+            if name:
+                return Scale[name]
+            return Scale.nearest(float(result), include_binary=should_consider_binary)
 
-        if Scale.one in [self, another_scale]:
-            power = Exponent.bases[2](exp_quotient)
-            return Scale[Scale.all()[Exponent(2, int(power)).parts()]]
+        result: Union[Exponent, float] = self.value / other.value
+        if isinstance(result, Exponent):
+            match = Scale.all().get(result.parts())
+            if match:
+                return Scale[match]
         else:
-            scale_exp_values = [Scale[Scale.all()[pair]].value.evaluated for pair in Scale.all().keys()]
-            closest_val = min(scale_exp_values, key=lambda val: abs(val - exp_quotient))
-            return Scale[Scale.by_value()[closest_val]]
+            return Scale.nearest(float(result), include_binary=should_consider_binary)
 
-    def __lt__(self, another_scale):
-        return self.value < another_scale.value
+    def __lt__(self, other: 'Scale'):
+        return self.value < other.value
 
-    def __gt__(self, another_scale):
-        return self.value > another_scale.value
+    def __gt__(self, other: 'Scale'):
+        return self.value > other.value
 
-    def __eq__(self, another_scale):
-        return self.value == another_scale.value
+    def __eq__(self, other: 'Scale'):
+        return self.value == other.value
 
 
 # TODO -- consider using a dataclass

{ucon-0.3.1rc4 → ucon-0.3.2}/ucon.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.1rc4
+Version: 0.3.2
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi

{ucon-0.3.1rc4 → ucon-0.3.2}/ucon.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ requirements.txt
 setup.py
 .github/workflows/publish.yaml
 .github/workflows/tests.yaml
+docs/unity-distance-metric-for-nearest-scale.md
 tests/__init__.py
 tests/ucon/__init__.py
 tests/ucon/test_core.py