ucon 0.5.1__tar.gz → 0.5.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.5.1
+Version: 0.5.2
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -92,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
@@ -235,6 +238,83 @@ 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
@@ -245,8 +325,9 @@ print(length_ft)  # <4.048... ± 0.0164... ft>
 | **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** | 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 |
+| **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.1 → ucon-0.5.2}/README.md

@@ -55,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
@@ -198,6 +201,83 @@ 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
@@ -208,8 +288,9 @@ print(length_ft)  # <4.048... ± 0.0164... ft>
 | **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** | 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 |
+| **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.1 → ucon-0.5.2}/ROADMAP.md

@@ -24,9 +24,9 @@ ucon is a dimensional analysis library for engineers building systems where unit
 | v0.4.x | Core Conversion + Information | Complete |
 | v0.5.0 | Dimensionless Units | Complete |
 | 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 |
+| 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,18 +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.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()`)
-- `ucon.units` (SI + imperial + information + angle + ratio units, callable syntax)
+- `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
 
 ---
 
@@ -134,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.
 
@@ -183,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.