ucon 0.5.0__tar.gz → 0.5.1__tar.gz

{ucon-0.5.0 → ucon-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.5.0
+Version: 0.5.1
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -67,6 +67,7 @@ It combines **units**, **scales**, and **dimensions** into a composable algebra
 - Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
 - Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - Pseudo-dimensions for angles, solid angles, and ratios with semantic isolation
+- Uncertainty propagation through arithmetic and conversions
 - A clean foundation for physics, chemistry, data modeling, and beyond
 
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -215,6 +216,25 @@ print(ratio.to(units.ppm))  # <500000.0 ppm>
 units.radian(1).to(units.percent)  # raises ConversionNotFound
 ```
 
+Uncertainty propagates through arithmetic and conversions:
+```python
+from ucon import units
+
+# Measurements with uncertainty
+length = units.meter(1.234, uncertainty=0.005)
+width = units.meter(0.567, uncertainty=0.003)
+
+print(length)  # <1.234 ± 0.005 m>
+
+# Uncertainty propagates through arithmetic (quadrature)
+area = length * width
+print(area)  # <0.699678 ± 0.00424... m²>
+
+# Uncertainty propagates through conversion
+length_ft = length.to(units.foot)
+print(length_ft)  # <4.048... ± 0.0164... ft>
+```
+
 ---
 
 ## Roadmap Highlights
@@ -224,7 +244,8 @@ units.radian(1).to(units.percent)  # raises ConversionNotFound
 | **0.3.x** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
 | **0.4.x** | Conversion System | `ConversionGraph`, `Number.to()`, callable units | ✅ Complete |
 | **0.5.0** | Dimensionless Units | Pseudo-dimensions for angle, solid angle, ratio | ✅ Complete |
-| **0.5.x** | Metrology | Uncertainty propagation, `UnitSystem` | 🚧 In Progress |
+| **0.5.x** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
+| **0.5.x** | Unit Systems | `BasisMap`, `UnitSystem` | 🚧 In Progress |
 | **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)

{ucon-0.5.0 → ucon-0.5.1}/README.md

@@ -30,6 +30,7 @@ It combines **units**, **scales**, and **dimensions** into a composable algebra
 - Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
 - Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - Pseudo-dimensions for angles, solid angles, and ratios with semantic isolation
+- Uncertainty propagation through arithmetic and conversions
 - A clean foundation for physics, chemistry, data modeling, and beyond
 
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -178,6 +179,25 @@ print(ratio.to(units.ppm))  # <500000.0 ppm>
 units.radian(1).to(units.percent)  # raises ConversionNotFound
 ```
 
+Uncertainty propagates through arithmetic and conversions:
+```python
+from ucon import units
+
+# Measurements with uncertainty
+length = units.meter(1.234, uncertainty=0.005)
+width = units.meter(0.567, uncertainty=0.003)
+
+print(length)  # <1.234 ± 0.005 m>
+
+# Uncertainty propagates through arithmetic (quadrature)
+area = length * width
+print(area)  # <0.699678 ± 0.00424... m²>
+
+# Uncertainty propagates through conversion
+length_ft = length.to(units.foot)
+print(length_ft)  # <4.048... ± 0.0164... ft>
+```
+
 ---
 
 ## Roadmap Highlights
@@ -187,7 +207,8 @@ units.radian(1).to(units.percent)  # raises ConversionNotFound
 | **0.3.x** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
 | **0.4.x** | Conversion System | `ConversionGraph`, `Number.to()`, callable units | ✅ Complete |
 | **0.5.0** | Dimensionless Units | Pseudo-dimensions for angle, solid angle, ratio | ✅ Complete |
-| **0.5.x** | Metrology | Uncertainty propagation, `UnitSystem` | 🚧 In Progress |
+| **0.5.x** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
+| **0.5.x** | Unit Systems | `BasisMap`, `UnitSystem` | 🚧 In Progress |
 | **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)

{ucon-0.5.0 → ucon-0.5.1}/ROADMAP.md

@@ -23,7 +23,7 @@ ucon is a dimensional analysis library for engineers building systems where unit
 | v0.3.x | Dimensional Algebra | Complete |
 | v0.4.x | Core Conversion + Information | Complete |
 | v0.5.0 | Dimensionless Units | Complete |
-| v0.5.x | Uncertainty Propagation | Planned |
+| v0.5.x | Uncertainty Propagation | Complete |
 | v0.5.x | BasisMap + UnitSystem | Planned |
 | v0.6.0 | NumPy Array Support | Planned |
 | v0.7.0 | Pydantic + Serialization | Planned |
@@ -38,13 +38,14 @@ ucon is a dimensional analysis library for engineers building systems where unit
 
 Building on v0.5.0 baseline:
 - `ucon.core` (`Dimension`, `Scale`, `Unit`, `UnitFactor`, `UnitProduct`, `Number`, `Ratio`)
-- `ucon.maps` (`Map`, `LinearMap`, `AffineMap`, `ComposedMap`)
+- `ucon.maps` (`Map`, `LinearMap`, `AffineMap`, `ComposedMap` with `derivative()`)
 - `ucon.graph` (`ConversionGraph`, default graph, `get_default_graph()`, `using_graph()`)
 - `ucon.units` (SI + imperial + information + angle + ratio units, callable syntax)
 - Callable unit API: `meter(5)`, `(mile / hour)(60)`
 - `Number.simplify()` for base-scale normalization
 - `Dimension.information` with `units.bit`, `units.byte`
 - Pseudo-dimensions: `angle`, `solid_angle`, `ratio` with semantic isolation
+- Uncertainty propagation: `meter(1.234, uncertainty=0.005)` with quadrature arithmetic
 
 ---
 
@@ -116,15 +117,15 @@ Building on v0.5.0 baseline:
 
 ---
 
-## v0.5.x — Uncertainty Propagation
+## v0.5.x — Uncertainty Propagation (Complete)
 
 **Theme:** Metrology foundation.
 
-- [ ] `Number.uncertainty: float | None`
-- [ ] Propagation through arithmetic (uncorrelated, quadrature)
-- [ ] Propagation through conversion via `Map.derivative()`
-- [ ] Construction: `meter(1.234, uncertainty=0.005)`
-- [ ] Display: `1.234 ± 0.005 meter`
+- [x] `Number.uncertainty: float | None`
+- [x] Propagation through arithmetic (uncorrelated, quadrature)
+- [x] Propagation through conversion via `Map.derivative()`
+- [x] Construction: `meter(1.234, uncertainty=0.005)`
+- [x] Display: `1.234 ± 0.005 meter`
 
 **Outcomes:**
 - First-class uncertainty support for scientific and engineering workflows

ucon-0.5.1/tests/ucon/test_uncertainty.py

@@ -0,0 +1,264 @@
+# © 2026 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
+"""
+Tests for v0.5.x uncertainty propagation.
+
+Tests Number construction with uncertainty, display formatting,
+arithmetic propagation, and conversion propagation.
+"""
+
+import math
+import unittest
+
+from ucon import units, Scale
+from ucon.core import Number, UnitProduct
+
+
+class TestUncertaintyConstruction(unittest.TestCase):
+    """Test constructing Numbers with uncertainty."""
+
+    def test_number_with_uncertainty(self):
+        n = units.meter(1.234, uncertainty=0.005)
+        self.assertEqual(n.value, 1.234)
+        self.assertEqual(n.uncertainty, 0.005)
+
+    def test_number_without_uncertainty(self):
+        n = units.meter(1.234)
+        self.assertEqual(n.value, 1.234)
+        self.assertIsNone(n.uncertainty)
+
+    def test_unit_product_callable_with_uncertainty(self):
+        km = Scale.kilo * units.meter
+        n = km(5.0, uncertainty=0.1)
+        self.assertEqual(n.value, 5.0)
+        self.assertEqual(n.uncertainty, 0.1)
+
+    def test_composite_unit_with_uncertainty(self):
+        mps = units.meter / units.second
+        n = mps(10.0, uncertainty=0.5)
+        self.assertEqual(n.value, 10.0)
+        self.assertEqual(n.uncertainty, 0.5)
+
+
+class TestUncertaintyDisplay(unittest.TestCase):
+    """Test display formatting with uncertainty."""
+
+    def test_repr_with_uncertainty(self):
+        n = units.meter(1.234, uncertainty=0.005)
+        r = repr(n)
+        self.assertIn("1.234", r)
+        self.assertIn("±", r)
+        self.assertIn("0.005", r)
+        self.assertIn("m", r)
+
+    def test_repr_without_uncertainty(self):
+        n = units.meter(1.234)
+        r = repr(n)
+        self.assertIn("1.234", r)
+        self.assertNotIn("±", r)
+
+    def test_repr_dimensionless_with_uncertainty(self):
+        n = Number(quantity=0.5, uncertainty=0.01)
+        r = repr(n)
+        self.assertIn("0.5", r)
+        self.assertIn("±", r)
+        self.assertIn("0.01", r)
+
+
+class TestAdditionSubtractionPropagation(unittest.TestCase):
+    """Test uncertainty propagation through addition and subtraction."""
+
+    def test_addition_both_uncertain(self):
+        a = units.meter(10.0, uncertainty=0.3)
+        b = units.meter(5.0, uncertainty=0.4)
+        c = a + b
+        self.assertAlmostEqual(c.value, 15.0, places=9)
+        # sqrt(0.3² + 0.4²) = sqrt(0.09 + 0.16) = sqrt(0.25) = 0.5
+        self.assertAlmostEqual(c.uncertainty, 0.5, places=9)
+
+    def test_subtraction_both_uncertain(self):
+        a = units.meter(10.0, uncertainty=0.3)
+        b = units.meter(5.0, uncertainty=0.4)
+        c = a - b
+        self.assertAlmostEqual(c.value, 5.0, places=9)
+        # sqrt(0.3² + 0.4²) = 0.5
+        self.assertAlmostEqual(c.uncertainty, 0.5, places=9)
+
+    def test_addition_one_uncertain(self):
+        a = units.meter(10.0, uncertainty=0.3)
+        b = units.meter(5.0)  # no uncertainty
+        c = a + b
+        self.assertAlmostEqual(c.value, 15.0, places=9)
+        self.assertAlmostEqual(c.uncertainty, 0.3, places=9)
+
+    def test_addition_neither_uncertain(self):
+        a = units.meter(10.0)
+        b = units.meter(5.0)
+        c = a + b
+        self.assertAlmostEqual(c.value, 15.0, places=9)
+        self.assertIsNone(c.uncertainty)
+
+
+class TestMultiplicationPropagation(unittest.TestCase):
+    """Test uncertainty propagation through multiplication."""
+
+    def test_multiplication_both_uncertain(self):
+        a = units.meter(10.0, uncertainty=0.2)  # 2% relative
+        b = units.meter(5.0, uncertainty=0.15)  # 3% relative
+        c = a * b
+        self.assertAlmostEqual(c.value, 50.0, places=9)
+        # relative: sqrt((0.2/10)² + (0.15/5)²) = sqrt(0.0004 + 0.0009) = sqrt(0.0013) ≈ 0.0361
+        # absolute: 50 * 0.0361 ≈ 1.803
+        expected = 50.0 * math.sqrt((0.2/10)**2 + (0.15/5)**2)
+        self.assertAlmostEqual(c.uncertainty, expected, places=6)
+
+    def test_multiplication_one_uncertain(self):
+        a = units.meter(10.0, uncertainty=0.2)
+        b = units.meter(5.0)  # no uncertainty
+        c = a * b
+        self.assertAlmostEqual(c.value, 50.0, places=9)
+        # Only a contributes: |c| * (δa/a) = 50 * 0.02 = 1.0
+        expected = 50.0 * (0.2/10)
+        self.assertAlmostEqual(c.uncertainty, expected, places=9)
+
+    def test_multiplication_neither_uncertain(self):
+        a = units.meter(10.0)
+        b = units.meter(5.0)
+        c = a * b
+        self.assertAlmostEqual(c.value, 50.0, places=9)
+        self.assertIsNone(c.uncertainty)
+
+
+class TestDivisionPropagation(unittest.TestCase):
+    """Test uncertainty propagation through division."""
+
+    def test_division_both_uncertain(self):
+        a = units.meter(10.0, uncertainty=0.2)  # 2% relative
+        b = units.second(2.0, uncertainty=0.04)  # 2% relative
+        c = a / b
+        self.assertAlmostEqual(c.value, 5.0, places=9)
+        # relative: sqrt((0.2/10)² + (0.04/2)²) = sqrt(0.0004 + 0.0004) = sqrt(0.0008) ≈ 0.0283
+        # absolute: 5 * 0.0283 ≈ 0.1414
+        expected = 5.0 * math.sqrt((0.2/10)**2 + (0.04/2)**2)
+        self.assertAlmostEqual(c.uncertainty, expected, places=6)
+
+    def test_division_one_uncertain(self):
+        a = units.meter(10.0, uncertainty=0.2)
+        b = units.second(2.0)  # no uncertainty
+        c = a / b
+        self.assertAlmostEqual(c.value, 5.0, places=9)
+        expected = 5.0 * (0.2/10)
+        self.assertAlmostEqual(c.uncertainty, expected, places=9)
+
+    def test_division_neither_uncertain(self):
+        a = units.meter(10.0)
+        b = units.second(2.0)
+        c = a / b
+        self.assertAlmostEqual(c.value, 5.0, places=9)
+        self.assertIsNone(c.uncertainty)
+
+
+class TestScalarOperations(unittest.TestCase):
+    """Test uncertainty propagation with scalar multiplication/division."""
+
+    def test_scalar_multiply_number(self):
+        a = units.meter(10.0, uncertainty=0.2)
+        c = a * 3  # scalar multiplication
+        self.assertAlmostEqual(c.value, 30.0, places=9)
+        self.assertAlmostEqual(c.uncertainty, 0.6, places=9)
+
+    def test_scalar_divide_number(self):
+        a = units.meter(10.0, uncertainty=0.2)
+        c = a / 2  # scalar division
+        self.assertAlmostEqual(c.value, 5.0, places=9)
+        self.assertAlmostEqual(c.uncertainty, 0.1, places=9)
+
+
+class TestConversionPropagation(unittest.TestCase):
+    """Test uncertainty propagation through unit conversion."""
+
+    def test_linear_conversion(self):
+        # meter to foot: factor ≈ 3.28084
+        length = units.meter(1.0, uncertainty=0.01)
+        length_ft = length.to(units.foot)
+        self.assertAlmostEqual(length_ft.value, 3.28084, places=4)
+        # uncertainty scales by same factor
+        self.assertAlmostEqual(length_ft.uncertainty, 0.01 * 3.28084, places=4)
+
+    def test_affine_conversion(self):
+        # Celsius to Kelvin: K = C + 273.15
+        # Derivative is 1, so uncertainty unchanged
+        temp = units.celsius(25.0, uncertainty=0.5)
+        temp_k = temp.to(units.kelvin)
+        self.assertAlmostEqual(temp_k.value, 298.15, places=9)
+        self.assertAlmostEqual(temp_k.uncertainty, 0.5, places=9)
+
+    def test_fahrenheit_to_celsius(self):
+        # F to C: C = (F - 32) * 5/9
+        # Derivative is 5/9 ≈ 0.5556
+        temp = units.fahrenheit(100.0, uncertainty=1.0)
+        temp_c = temp.to(units.celsius)
+        self.assertAlmostEqual(temp_c.value, 37.7778, places=3)
+        self.assertAlmostEqual(temp_c.uncertainty, 1.0 * (5/9), places=6)
+
+    def test_conversion_without_uncertainty(self):
+        length = units.meter(1.0)
+        length_ft = length.to(units.foot)
+        self.assertIsNone(length_ft.uncertainty)
+
+
+class TestEdgeCases(unittest.TestCase):
+    """Test edge cases for uncertainty handling."""
+
+    def test_zero_uncertainty(self):
+        a = units.meter(10.0, uncertainty=0.0)
+        b = units.meter(5.0, uncertainty=0.0)
+        c = a + b
+        self.assertAlmostEqual(c.uncertainty, 0.0, places=9)
+
+    def test_very_small_uncertainty(self):
+        a = units.meter(10.0, uncertainty=1e-15)
+        b = units.meter(5.0, uncertainty=1e-15)
+        c = a * b
+        self.assertIsNotNone(c.uncertainty)
+        self.assertGreater(c.uncertainty, 0)
+
+    def test_uncertainty_preserved_through_simplify(self):
+        km = Scale.kilo * units.meter
+        n = km(5.0, uncertainty=0.1)
+        simplified = n.simplify()
+        self.assertAlmostEqual(simplified.value, 5000.0, places=9)
+        # uncertainty also scales
+        self.assertAlmostEqual(simplified.uncertainty, 100.0, places=9)
+
+
+class TestMapDerivative(unittest.TestCase):
+    """Test Map.derivative() implementations."""
+
+    def test_linear_map_derivative(self):
+        from ucon.maps import LinearMap
+        m = LinearMap(3.28084)
+        self.assertAlmostEqual(m.derivative(0), 3.28084, places=9)
+        self.assertAlmostEqual(m.derivative(100), 3.28084, places=9)
+
+    def test_affine_map_derivative(self):
+        from ucon.maps import AffineMap
+        m = AffineMap(5/9, -32 * 5/9)  # F to C
+        self.assertAlmostEqual(m.derivative(0), 5/9, places=9)
+        self.assertAlmostEqual(m.derivative(100), 5/9, places=9)
+
+    def test_composed_map_derivative(self):
+        from ucon.maps import LinearMap, AffineMap
+        # Compose: first scale by 2, then add 10
+        inner = LinearMap(2)
+        outer = AffineMap(1, 10)
+        composed = outer @ inner
+        # d/dx [1*(2x) + 10] = 2
+        self.assertAlmostEqual(composed.derivative(0), 2, places=9)
+        self.assertAlmostEqual(composed.derivative(5), 2, places=9)
+
+
+if __name__ == "__main__":
+    unittest.main()

{ucon-0.5.0 → ucon-0.5.1}/ucon/core.py

@@ -445,15 +445,24 @@ class Unit:
 
     # ----------------- callable (creates Number) -----------------
 
-    def __call__(self, quantity: Union[int, float]) -> "Number":
+    def __call__(self, quantity: Union[int, float], uncertainty: Union[float, None] = None) -> "Number":
         """Create a Number with this unit.
 
+        Parameters
+        ----------
+        quantity : int or float
+            The numeric value.
+        uncertainty : float, optional
+            The measurement uncertainty.
+
         Example
         -------
         >>> meter(5)
         <5 m>
+        >>> meter(1.234, uncertainty=0.005)
+        <1.234 ± 0.005 m>
         """
-        return Number(quantity=quantity, unit=UnitProduct.from_unit(self))
+        return Number(quantity=quantity, unit=UnitProduct.from_unit(self), uncertainty=uncertainty)
 
 
 @dataclass(frozen=True)
@@ -872,15 +881,24 @@ class UnitProduct:
         # Sort by name; UnitFactor exposes .name, so this is stable.
         return hash(tuple(sorted(self.factors.items(), key=lambda x: x[0].name)))
 
-    def __call__(self, quantity: Union[int, float]) -> "Number":
+    def __call__(self, quantity: Union[int, float], uncertainty: Union[float, None] = None) -> "Number":
         """Create a Number with this unit product.
 
+        Parameters
+        ----------
+        quantity : int or float
+            The numeric value.
+        uncertainty : float, optional
+            The measurement uncertainty.
+
         Example
         -------
         >>> (meter / second)(10)
         <10 m/s>
+        >>> (meter / second)(10, uncertainty=0.5)
+        <10 ± 0.5 m/s>
         """
-        return Number(quantity=quantity, unit=self)
+        return Number(quantity=quantity, unit=self, uncertainty=uncertainty)
 
 
 # --------------------------------------------------------------------------------------
@@ -908,9 +926,16 @@ class Number:
         >>> speed = length / time
         >>> speed
         <2.5 m/s>
+
+    Optionally includes measurement uncertainty for error propagation:
+
+        >>> length = meter(1.234, uncertainty=0.005)
+        >>> length
+        <1.234 ± 0.005 m>
     """
     quantity: Union[float, int] = 1.0
     unit: Union[Unit, UnitProduct] = None
+    uncertainty: Union[float, None] = None
 
     def __post_init__(self):
         if self.unit is None:
@@ -952,7 +977,7 @@ class Number:
         """
         if not isinstance(self.unit, UnitProduct):
             # Plain Unit already has no scale
-            return Number(quantity=self.quantity, unit=self.unit)
+            return Number(quantity=self.quantity, unit=self.unit, uncertainty=self.uncertainty)
 
         # Compute the combined scale factor
         scale_factor = self.unit.fold_scale()
@@ -965,8 +990,16 @@ class Number:
 
         base_unit = UnitProduct(base_factors)
 
-        # Adjust quantity by the scale factor
-        return Number(quantity=self.quantity * scale_factor, unit=base_unit)
+        # Adjust quantity and uncertainty by the scale factor
+        new_uncertainty = None
+        if self.uncertainty is not None:
+            new_uncertainty = self.uncertainty * abs(scale_factor)
+
+        return Number(
+            quantity=self.quantity * scale_factor,
+            unit=base_unit,
+            uncertainty=new_uncertainty,
+        )
 
     def to(self, target, graph=None):
         """Convert this Number to a different unit expression.
@@ -999,7 +1032,10 @@ class Number:
         # Scale-only conversion (same base unit, different scale)
         if self._is_scale_only_conversion(src, dst):
             factor = src.fold_scale() / dst.fold_scale()
-            return Number(quantity=self.quantity * factor, unit=target)
+            new_uncertainty = None
+            if self.uncertainty is not None:
+                new_uncertainty = self.uncertainty * abs(factor)
+            return Number(quantity=self.quantity * factor, unit=target, uncertainty=new_uncertainty)
 
         # Graph-based conversion (use default graph if none provided)
         if graph is None:
@@ -1008,7 +1044,14 @@ class Number:
         conversion_map = graph.convert(src=src, dst=dst)
         # Use raw quantity - the conversion map handles scale via factorwise decomposition
         converted_quantity = conversion_map(self.quantity)
-        return Number(quantity=converted_quantity, unit=target)
+
+        # Propagate uncertainty through conversion using derivative
+        new_uncertainty = None
+        if self.uncertainty is not None:
+            derivative = abs(conversion_map.derivative(self.quantity))
+            new_uncertainty = derivative * self.uncertainty
+
+        return Number(quantity=converted_quantity, unit=target, uncertainty=new_uncertainty)
 
     def _is_scale_only_conversion(self, src: UnitProduct, dst: UnitProduct) -> bool:
         """Check if conversion is just a scale change (same base units)."""
@@ -1040,12 +1083,82 @@ class Number:
         if isinstance(other, Ratio):
             other = other.evaluate()
 
+        # Scalar multiplication
+        if isinstance(other, (int, float)):
+            new_uncertainty = None
+            if self.uncertainty is not None:
+                new_uncertainty = abs(other) * self.uncertainty
+            return Number(
+                quantity=self.quantity * other,
+                unit=self.unit,
+                uncertainty=new_uncertainty,
+            )
+
         if not isinstance(other, Number):
             return NotImplemented
 
+        # Uncertainty propagation for multiplication
+        # δc = |c| * sqrt((δa/a)² + (δb/b)²)
+        new_uncertainty = None
+        result_quantity = self.quantity * other.quantity
+        if self.uncertainty is not None or other.uncertainty is not None:
+            rel_a = (self.uncertainty / abs(self.quantity)) if (self.uncertainty and self.quantity != 0) else 0
+            rel_b = (other.uncertainty / abs(other.quantity)) if (other.uncertainty and other.quantity != 0) else 0
+            rel_c = math.sqrt(rel_a**2 + rel_b**2)
+            new_uncertainty = abs(result_quantity) * rel_c if rel_c > 0 else None
+
         return Number(
-            quantity=self.quantity * other.quantity,
+            quantity=result_quantity,
             unit=self.unit * other.unit,
+            uncertainty=new_uncertainty,
+        )
+
+    def __add__(self, other: 'Number') -> 'Number':
+        if not isinstance(other, Number):
+            return NotImplemented
+
+        # Dimensions must match for addition
+        if self.unit.dimension != other.unit.dimension:
+            raise TypeError(
+                f"Cannot add Numbers with different dimensions: "
+                f"{self.unit.dimension} vs {other.unit.dimension}"
+            )
+
+        # Uncertainty propagation for addition: δc = sqrt(δa² + δb²)
+        new_uncertainty = None
+        if self.uncertainty is not None or other.uncertainty is not None:
+            ua = self.uncertainty if self.uncertainty is not None else 0
+            ub = other.uncertainty if other.uncertainty is not None else 0
+            new_uncertainty = math.sqrt(ua**2 + ub**2)
+
+        return Number(
+            quantity=self.quantity + other.quantity,
+            unit=self.unit,
+            uncertainty=new_uncertainty,
+        )
+
+    def __sub__(self, other: 'Number') -> 'Number':
+        if not isinstance(other, Number):
+            return NotImplemented
+
+        # Dimensions must match for subtraction
+        if self.unit.dimension != other.unit.dimension:
+            raise TypeError(
+                f"Cannot subtract Numbers with different dimensions: "
+                f"{self.unit.dimension} vs {other.unit.dimension}"
+            )
+
+        # Uncertainty propagation for subtraction: δc = sqrt(δa² + δb²)
+        new_uncertainty = None
+        if self.uncertainty is not None or other.uncertainty is not None:
+            ua = self.uncertainty if self.uncertainty is not None else 0
+            ub = other.uncertainty if other.uncertainty is not None else 0
+            new_uncertainty = math.sqrt(ua**2 + ub**2)
+
+        return Number(
+            quantity=self.quantity - other.quantity,
+            unit=self.unit,
+            uncertainty=new_uncertainty,
         )
 
     def __truediv__(self, other: Quantifiable) -> "Number":
@@ -1053,25 +1166,47 @@ class Number:
         if isinstance(other, Ratio):
             other = other.evaluate()
 
+        # Scalar division
+        if isinstance(other, (int, float)):
+            new_uncertainty = None
+            if self.uncertainty is not None:
+                new_uncertainty = self.uncertainty / abs(other)
+            return Number(
+                quantity=self.quantity / other,
+                unit=self.unit,
+                uncertainty=new_uncertainty,
+            )
+
         if not isinstance(other, Number):
             raise TypeError(f"Cannot divide Number by non-Number/Ratio type: {type(other)}")
 
         # Symbolic quotient in the unit algebra
         unit_quot = self.unit / other.unit
 
+        # Uncertainty propagation for division
+        # δc = |c| * sqrt((δa/a)² + (δb/b)²)
+        def compute_uncertainty(result_quantity):
+            if self.uncertainty is None and other.uncertainty is None:
+                return None
+            rel_a = (self.uncertainty / abs(self.quantity)) if (self.uncertainty and self.quantity != 0) else 0
+            rel_b = (other.uncertainty / abs(other.quantity)) if (other.uncertainty and other.quantity != 0) else 0
+            rel_c = math.sqrt(rel_a**2 + rel_b**2)
+            return abs(result_quantity) * rel_c if rel_c > 0 else None
+
         # --- Case 1: Dimensionless result ----------------------------------
         # If the net dimension is none, we want a pure scalar:
         # fold *all* scale factors into the numeric magnitude.
         if not unit_quot.dimension:
             num = self._canonical_magnitude
             den = other._canonical_magnitude
-            return Number(quantity=num / den, unit=_none)
+            result = num / den
+            return Number(quantity=result, unit=_none, uncertainty=compute_uncertainty(result))
 
         # --- Case 2: Dimensionful result -----------------------------------
         # For "real" physical results like g/mL, m/s², etc., preserve the
         # user's chosen unit scales symbolically. Only divide the raw quantities.
         new_quantity = self.quantity / other.quantity
-        return Number(quantity=new_quantity, unit=unit_quot)
+        return Number(quantity=new_quantity, unit=unit_quot, uncertainty=compute_uncertainty(new_quantity))
 
     def __eq__(self, other: Quantifiable) -> bool:
         if not isinstance(other, (Number, Ratio)):
@@ -1094,6 +1229,10 @@ class Number:
         return True
 
     def __repr__(self):
+        if self.uncertainty is not None:
+            if not self.unit.dimension:
+                return f"<{self.quantity} ± {self.uncertainty}>"
+            return f"<{self.quantity} ± {self.uncertainty} {self.unit.shorthand}>"
         if not self.unit.dimension:
             return f"<{self.quantity}>"
         return f"<{self.quantity} {self.unit.shorthand}>"

{ucon-0.5.0 → ucon-0.5.1}/ucon/maps.py

@@ -25,7 +25,7 @@ from dataclasses import dataclass
 class Map(ABC):
     """Abstract base for all conversion morphisms.
 
-    Subclasses must implement ``__call__``, ``inverse``, and ``__pow__``.
+    Subclasses must implement ``__call__``, ``inverse``, ``__pow__``, and ``derivative``.
     Composition via ``@`` defaults to :class:`ComposedMap`; subclasses may
     override for closed composition within their own type.
     """
@@ -50,6 +50,14 @@ class Map(ABC):
         """Raise map to a power (for exponent handling in factorwise conversion)."""
         ...
 
+    @abstractmethod
+    def derivative(self, x: float) -> float:
+        """Return the derivative of the map at point x.
+
+        Used for uncertainty propagation: δy = |f'(x)| * δx
+        """
+        ...
+
     def is_identity(self, tol: float = 1e-9) -> bool:
         """Check if this map is approximately the identity."""
         return abs(self(1.0) - 1.0) < tol and abs(self(0.0) - 0.0) < tol
@@ -86,6 +94,10 @@ class LinearMap(Map):
     def __pow__(self, exp: float) -> LinearMap:
         return LinearMap(self.a ** exp)
 
+    def derivative(self, x: float) -> float:
+        """Derivative of y = a*x is a (constant)."""
+        return self.a
+
     @classmethod
     def identity(cls) -> LinearMap:
         return cls(1.0)
@@ -128,6 +140,10 @@ class AffineMap(Map):
             return self.inverse()
         raise ValueError("AffineMap only supports exp=1 or exp=-1")
 
+    def derivative(self, x: float) -> float:
+        """Derivative of y = a*x + b is a (constant)."""
+        return self.a
+
 
 @dataclass(frozen=True)
 class ComposedMap(Map):
@@ -159,3 +175,8 @@ class ComposedMap(Map):
         if exp == -1:
             return self.inverse()
         raise ValueError("ComposedMap only supports exp=1 or exp=-1")
+
+    def derivative(self, x: float) -> float:
+        """Chain rule: d/dx [outer(inner(x))] = outer'(inner(x)) * inner'(x)."""
+        inner_val = self.inner(x)
+        return self.outer.derivative(inner_val) * self.inner.derivative(x)

{ucon-0.5.0 → ucon-0.5.1}/ucon.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.5.0
+Version: 0.5.1
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -67,6 +67,7 @@ It combines **units**, **scales**, and **dimensions** into a composable algebra
 - Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
 - Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - Pseudo-dimensions for angles, solid angles, and ratios with semantic isolation
+- Uncertainty propagation through arithmetic and conversions
 - A clean foundation for physics, chemistry, data modeling, and beyond
 
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -215,6 +216,25 @@ print(ratio.to(units.ppm))  # <500000.0 ppm>
 units.radian(1).to(units.percent)  # raises ConversionNotFound
 ```
 
+Uncertainty propagates through arithmetic and conversions:
+```python
+from ucon import units
+
+# Measurements with uncertainty
+length = units.meter(1.234, uncertainty=0.005)
+width = units.meter(0.567, uncertainty=0.003)
+
+print(length)  # <1.234 ± 0.005 m>
+
+# Uncertainty propagates through arithmetic (quadrature)
+area = length * width
+print(area)  # <0.699678 ± 0.00424... m²>
+
+# Uncertainty propagates through conversion
+length_ft = length.to(units.foot)
+print(length_ft)  # <4.048... ± 0.0164... ft>
+```
+
 ---
 
 ## Roadmap Highlights
@@ -224,7 +244,8 @@ units.radian(1).to(units.percent)  # raises ConversionNotFound
 | **0.3.x** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
 | **0.4.x** | Conversion System | `ConversionGraph`, `Number.to()`, callable units | ✅ Complete |
 | **0.5.0** | Dimensionless Units | Pseudo-dimensions for angle, solid angle, ratio | ✅ Complete |
-| **0.5.x** | Metrology | Uncertainty propagation, `UnitSystem` | 🚧 In Progress |
+| **0.5.x** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
+| **0.5.x** | Unit Systems | `BasisMap`, `UnitSystem` | 🚧 In Progress |
 | **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)

{ucon-0.5.0 → ucon-0.5.1}/ucon.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ tests/ucon/test_core.py
 tests/ucon/test_default_graph_conversions.py
 tests/ucon/test_dimensionless_units.py
 tests/ucon/test_quantity.py
+tests/ucon/test_uncertainty.py
 tests/ucon/test_units.py
 tests/ucon/conversion/__init__.py
 tests/ucon/conversion/test_graph.py