ucon 0.5.0__tar.gz → 0.5.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.5.0
+Version: 0.5.2
 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.
@@ -91,6 +92,9 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 | **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
 | **`Map`** hierarchy           | `ucon.maps`                             | Composable conversion morphisms: `LinearMap`, `AffineMap`, `ComposedMap`.                           | Defining conversion functions between units (e.g., meter→foot, celsius→kelvin).                                        |
 | **`ConversionGraph`**         | `ucon.graph`                            | Registry of unit conversion edges with BFS path composition.                                        | Converting between units via `Number.to(target)`; managing default and custom graphs.                                  |
+| **`UnitSystem`**              | `ucon.core`                             | Named mapping from dimensions to base units (e.g., SI, Imperial).                                   | Defining coherent unit systems; grouping base units by dimension.                                                      |
+| **`BasisTransform`**          | `ucon.core`                             | Matrix-based transformation between dimensional exponent spaces.                                    | Converting between incompatible dimensional structures; exact arithmetic with `Fraction`.                              |
+| **`RebasedUnit`**             | `ucon.core`                             | A unit rebased to another system's dimension, preserving provenance.                                | Cross-basis conversions; tracking original unit through basis changes.                                                 |
 | **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI, imperial, information, and derived units).                    | Quick access to standard physical units (`units.meter`, `units.foot`, `units.byte`, etc.).                             |
 
 ### Under the Hood
@@ -215,6 +219,102 @@ 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>
+```
+
+Unit systems and basis transforms enable conversions between incompatible dimensional structures.
+This goes beyond simple unit conversion (meter → foot) into structural transformation:
+
+```python
+from fractions import Fraction
+from ucon import BasisTransform, Dimension, Unit, UnitSystem, units
+from ucon.graph import ConversionGraph
+from ucon.maps import LinearMap
+
+# The realm of Valdris has three fundamental dimensions:
+#   - Aether (A): magical energy substrate
+#   - Resonance (R): vibrational frequency of magic
+#   - Substance (S): physical matter
+#
+# These combine into SI dimensions via a transformation matrix:
+#
+#   | L |   | 2  0  0 |   | A |
+#   | M | = | 1  0  1 | × | R |
+#   | T |   |-2 -1  0 |   | S |
+#
+# Reading the columns:
+#   - 1 aether contributes: L², M, T⁻²  (energy-like)
+#   - 1 resonance contributes: T⁻¹      (frequency-like)
+#   - 1 substance contributes: M         (mass-like)
+
+# Fantasy base units
+mote = Unit(name='mote', dimension=Dimension.energy, aliases=('mt',))
+chime = Unit(name='chime', dimension=Dimension.frequency, aliases=('ch',))
+ite = Unit(name='ite', dimension=Dimension.mass, aliases=('it',))
+
+valdris = UnitSystem(
+    name="Valdris",
+    bases={
+        Dimension.energy: mote,
+        Dimension.frequency: chime,
+        Dimension.mass: ite,
+    }
+)
+
+# The basis transform encodes how Valdris dimensions compose into SI
+valdris_to_si = BasisTransform(
+    src=valdris,
+    dst=units.si,
+    src_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
+    dst_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
+    matrix=(
+        (2, 0, 0),    # energy: 2 × aether
+        (1, 0, 1),    # frequency: aether + substance
+        (-2, -1, 0),  # mass: -2×aether - resonance
+    ),
+)
+
+# Physical calibration: how many SI units per fantasy unit
+graph = ConversionGraph()
+graph.connect_systems(
+    basis_transform=valdris_to_si,
+    edges={
+        (mote, units.joule): LinearMap(42),           # 1 mote = 42 J
+        (chime, units.hertz): LinearMap(7),           # 1 chime = 7 Hz
+        (ite, units.kilogram): LinearMap(Fraction(1, 2)),  # 1 ite = 0.5 kg
+    }
+)
+
+# Game engine converts between physics systems
+energy_map = graph.convert(src=mote, dst=units.joule)
+energy_map(10)  # 420 joules from 10 motes
+
+# Inverse: display real-world values in game units
+joule_to_mote = graph.convert(src=units.joule, dst=mote)
+joule_to_mote(420)  # 10 motes
+
+# The transform is invertible with exact Fraction arithmetic
+valdris_to_si.is_invertible  # True
+```
+
+This enables fantasy game physics, or any field where the dimensional structure differs from SI.
+
 ---
 
 ## Roadmap Highlights
@@ -224,8 +324,10 @@ 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.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.5.x** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
+| **0.5.x** | Unit Systems | `BasisTransform`, `UnitSystem`, cross-basis conversion | ✅ Complete |
+| **0.6.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.7.x** | NumPy Arrays | Vectorized conversion and arithmetic | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 

{ucon-0.5.0 → ucon-0.5.2}/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.
@@ -54,6 +55,9 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 | **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
 | **`Map`** hierarchy           | `ucon.maps`                             | Composable conversion morphisms: `LinearMap`, `AffineMap`, `ComposedMap`.                           | Defining conversion functions between units (e.g., meter→foot, celsius→kelvin).                                        |
 | **`ConversionGraph`**         | `ucon.graph`                            | Registry of unit conversion edges with BFS path composition.                                        | Converting between units via `Number.to(target)`; managing default and custom graphs.                                  |
+| **`UnitSystem`**              | `ucon.core`                             | Named mapping from dimensions to base units (e.g., SI, Imperial).                                   | Defining coherent unit systems; grouping base units by dimension.                                                      |
+| **`BasisTransform`**          | `ucon.core`                             | Matrix-based transformation between dimensional exponent spaces.                                    | Converting between incompatible dimensional structures; exact arithmetic with `Fraction`.                              |
+| **`RebasedUnit`**             | `ucon.core`                             | A unit rebased to another system's dimension, preserving provenance.                                | Cross-basis conversions; tracking original unit through basis changes.                                                 |
 | **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI, imperial, information, and derived units).                    | Quick access to standard physical units (`units.meter`, `units.foot`, `units.byte`, etc.).                             |
 
 ### Under the Hood
@@ -178,6 +182,102 @@ 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>
+```
+
+Unit systems and basis transforms enable conversions between incompatible dimensional structures.
+This goes beyond simple unit conversion (meter → foot) into structural transformation:
+
+```python
+from fractions import Fraction
+from ucon import BasisTransform, Dimension, Unit, UnitSystem, units
+from ucon.graph import ConversionGraph
+from ucon.maps import LinearMap
+
+# The realm of Valdris has three fundamental dimensions:
+#   - Aether (A): magical energy substrate
+#   - Resonance (R): vibrational frequency of magic
+#   - Substance (S): physical matter
+#
+# These combine into SI dimensions via a transformation matrix:
+#
+#   | L |   | 2  0  0 |   | A |
+#   | M | = | 1  0  1 | × | R |
+#   | T |   |-2 -1  0 |   | S |
+#
+# Reading the columns:
+#   - 1 aether contributes: L², M, T⁻²  (energy-like)
+#   - 1 resonance contributes: T⁻¹      (frequency-like)
+#   - 1 substance contributes: M         (mass-like)
+
+# Fantasy base units
+mote = Unit(name='mote', dimension=Dimension.energy, aliases=('mt',))
+chime = Unit(name='chime', dimension=Dimension.frequency, aliases=('ch',))
+ite = Unit(name='ite', dimension=Dimension.mass, aliases=('it',))
+
+valdris = UnitSystem(
+    name="Valdris",
+    bases={
+        Dimension.energy: mote,
+        Dimension.frequency: chime,
+        Dimension.mass: ite,
+    }
+)
+
+# The basis transform encodes how Valdris dimensions compose into SI
+valdris_to_si = BasisTransform(
+    src=valdris,
+    dst=units.si,
+    src_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
+    dst_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
+    matrix=(
+        (2, 0, 0),    # energy: 2 × aether
+        (1, 0, 1),    # frequency: aether + substance
+        (-2, -1, 0),  # mass: -2×aether - resonance
+    ),
+)
+
+# Physical calibration: how many SI units per fantasy unit
+graph = ConversionGraph()
+graph.connect_systems(
+    basis_transform=valdris_to_si,
+    edges={
+        (mote, units.joule): LinearMap(42),           # 1 mote = 42 J
+        (chime, units.hertz): LinearMap(7),           # 1 chime = 7 Hz
+        (ite, units.kilogram): LinearMap(Fraction(1, 2)),  # 1 ite = 0.5 kg
+    }
+)
+
+# Game engine converts between physics systems
+energy_map = graph.convert(src=mote, dst=units.joule)
+energy_map(10)  # 420 joules from 10 motes
+
+# Inverse: display real-world values in game units
+joule_to_mote = graph.convert(src=units.joule, dst=mote)
+joule_to_mote(420)  # 10 motes
+
+# The transform is invertible with exact Fraction arithmetic
+valdris_to_si.is_invertible  # True
+```
+
+This enables fantasy game physics, or any field where the dimensional structure differs from SI.
+
 ---
 
 ## Roadmap Highlights
@@ -187,8 +287,10 @@ 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.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.5.x** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
+| **0.5.x** | Unit Systems | `BasisTransform`, `UnitSystem`, cross-basis conversion | ✅ Complete |
+| **0.6.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.7.x** | NumPy Arrays | Vectorized conversion and arithmetic | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 

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

@@ -23,10 +23,10 @@ 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 | BasisMap + UnitSystem | Planned |
-| v0.6.0 | NumPy Array Support | Planned |
-| v0.7.0 | Pydantic + Serialization | Planned |
+| v0.5.x | Uncertainty Propagation | Complete |
+| v0.5.x | BasisTransform + UnitSystem | Complete |
+| v0.6.0 | Pydantic + Serialization | Planned |
+| v0.7.0 | NumPy Array Support | Planned |
 | v0.8.0 | String Parsing | Planned |
 | v0.9.0 | Constants + Logarithmic Units | Planned |
 | v0.10.0 | DataFrame Integration | Planned |
@@ -34,17 +34,21 @@ ucon is a dimensional analysis library for engineers building systems where unit
 
 ---
 
-## Current Version: **v0.5.x** (in progress)
+## Current Version: **v0.5.x** (complete)
 
 Building on v0.5.0 baseline:
-- `ucon.core` (`Dimension`, `Scale`, `Unit`, `UnitFactor`, `UnitProduct`, `Number`, `Ratio`)
-- `ucon.maps` (`Map`, `LinearMap`, `AffineMap`, `ComposedMap`)
-- `ucon.graph` (`ConversionGraph`, default graph, `get_default_graph()`, `using_graph()`)
-- `ucon.units` (SI + imperial + information + angle + ratio units, callable syntax)
+- `ucon.core` (`Dimension`, `Scale`, `Unit`, `UnitFactor`, `UnitProduct`, `Number`, `Ratio`, `UnitSystem`, `BasisTransform`, `RebasedUnit`)
+- `ucon.maps` (`Map`, `LinearMap`, `AffineMap`, `ComposedMap` with `derivative()`)
+- `ucon.graph` (`ConversionGraph`, default graph, `get_default_graph()`, `using_graph()`, cross-basis conversion)
+- `ucon.units` (SI + imperial + information + angle + ratio units, callable syntax, `si` and `imperial` systems)
+- `ucon.algebra` (`Vector` with `Fraction` exponents, `Exponent`)
 - 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
+- `BasisTransform` for cross-system dimensional mapping with exact matrix arithmetic
+- `UnitSystem` for named dimension-to-unit groupings
 
 ---
 
@@ -116,15 +120,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
@@ -133,40 +137,31 @@ Building on v0.5.0 baseline:
 
 ---
 
-## v0.5.x — BasisMap + UnitSystem
+## v0.5.x — BasisTransform + UnitSystem (Complete)
 
 **Theme:** Cross-system architecture.
 
-- [ ] `UnitSystem` class (named grouping of base units)
-- [ ] `BasisMap` class (structural equivalence between systems)
-- [ ] Prebuilt systems: `si`, `imperial`, `cgs`
-- [ ] `graph.connect_systems()` for bulk edge creation
-- [ ] Support for custom domain dimensions
+- [x] `Vector` with `Fraction` exponents for exact arithmetic
+- [x] `UnitSystem` class (named dimension-to-unit mapping)
+- [x] `BasisTransform` class (matrix-based dimensional basis transformation)
+- [x] `RebasedUnit` class (provenance-preserving cross-basis unit)
+- [x] `NonInvertibleTransform` exception for surjective transforms
+- [x] Prebuilt systems: `units.si`, `units.imperial`
+- [x] `graph.add_edge()` with `basis_transform` parameter
+- [x] `graph.connect_systems()` for bulk edge creation
+- [x] Cross-basis conversion via rebased paths
+- [x] Introspection: `list_transforms()`, `list_rebased_units()`, `edges_for_transform()`
 
 **Outcomes:**
-- `BasisMap` enables system-aware "express in base units" functionality
+- `BasisTransform` enables conversions between incompatible dimensional structures
+- Matrix operations with exact `Fraction` arithmetic (no floating-point drift)
+- Invertibility detection with clear error messages for surjective transforms
 - Named unit systems for domain-specific workflows
-- Foundation for plugin-style system extensions
+- Foundation for custom dimension domains
 
 ---
 
-## v0.6.0 — NumPy Array Support
-
-**Theme:** Scientific computing integration.
-
-- [ ] `Number` wraps `np.ndarray` values
-- [ ] Vectorized conversion
-- [ ] Vectorized arithmetic with uncertainty propagation
-- [ ] Performance benchmarks
-
-**Outcomes:**
-- Seamless integration with NumPy-based scientific workflows
-- Efficient batch conversions for large datasets
-- Performance characteristics documented and optimized
-
----
-
-## v0.7.0 — Pydantic + Serialization
+## v0.6.0 — Pydantic + Serialization
 
 **Theme:** API and persistence integration.
 
@@ -182,6 +177,22 @@ Building on v0.5.0 baseline:
 
 ---
 
+## v0.7.0 — NumPy Array Support
+
+**Theme:** Scientific computing integration.
+
+- [ ] `Number` wraps `np.ndarray` values
+- [ ] Vectorized conversion
+- [ ] Vectorized arithmetic with uncertainty propagation
+- [ ] Performance benchmarks
+
+**Outcomes:**
+- Seamless integration with NumPy-based scientific workflows
+- Efficient batch conversions for large datasets
+- Performance characteristics documented and optimized
+
+---
+
 ## v0.8.0 — String Parsing
 
 **Theme:** Ergonomic input.