ucon 0.3.5rc2__tar.gz → 0.4.0__tar.gz

{ucon-0.3.5rc2 → ucon-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.5rc2
+Version: 0.4.0
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -70,22 +70,24 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the 8-component exponent tuple of a physical quantity's base dimensions (T, L, M, I, Θ, J, N, B). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
 | **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
 | **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
 | **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
 | **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
 | **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
-| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
-| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
+| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
+| **`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.                                  |
+| **`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
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/5df6a7fb2a6426ee6804096c092c10bed1b30b6f/ucon.data-model_v040.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -167,8 +169,24 @@ print(km.fold_scale())  # 1000.0
 print(mg.fold_scale())  # 0.001
 ```
 
-> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
-> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
+Units are callable for ergonomic quantity construction:
+```python
+from ucon import units, Scale
+
+# Callable syntax: unit(quantity) → Number
+height = units.meter(1.8)
+speed = (units.mile / units.hour)(60)
+
+# Convert between units
+height_ft = height.to(units.foot)
+print(height_ft)  # <5.905... ft>
+
+# Scaled units work too
+km = Scale.kilo * units.meter
+distance = km(5)
+distance_mi = distance.to(units.mile)
+print(distance_mi)  # <3.107... mi>
+```
 
 ---
 
@@ -177,7 +195,7 @@ print(mg.fold_scale())  # 0.001
 | Version | Theme | Focus | Status |
 |----------|-------|--------|--------|
 | **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()`, callable units | 🚧 In Progress |
 | [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
 | [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 

{ucon-0.3.5rc2 → ucon-0.4.0}/README.md

@@ -33,22 +33,24 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the 8-component exponent tuple of a physical quantity's base dimensions (T, L, M, I, Θ, J, N, B). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
 | **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
 | **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
 | **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
 | **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
 | **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
-| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
-| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
+| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
+| **`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.                                  |
+| **`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
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/5df6a7fb2a6426ee6804096c092c10bed1b30b6f/ucon.data-model_v040.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -130,8 +132,24 @@ print(km.fold_scale())  # 1000.0
 print(mg.fold_scale())  # 0.001
 ```
 
-> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
-> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
+Units are callable for ergonomic quantity construction:
+```python
+from ucon import units, Scale
+
+# Callable syntax: unit(quantity) → Number
+height = units.meter(1.8)
+speed = (units.mile / units.hour)(60)
+
+# Convert between units
+height_ft = height.to(units.foot)
+print(height_ft)  # <5.905... ft>
+
+# Scaled units work too
+km = Scale.kilo * units.meter
+distance = km(5)
+distance_mi = distance.to(units.mile)
+print(distance_mi)  # <3.107... mi>
+```
 
 ---
 
@@ -140,7 +158,7 @@ print(mg.fold_scale())  # 0.001
 | Version | Theme | Focus | Status |
 |----------|-------|--------|--------|
 | **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()`, callable units | 🚧 In Progress |
 | [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
 | [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 

{ucon-0.3.5rc2 → ucon-0.4.0}/ROADMAP.md

@@ -4,13 +4,16 @@
 
 ---
 
-## 🪜 Current Version: **v0.3.5**
+## 🪜 Current Version: **v0.4.0** (in progress)
 
-Stable baseline for:
-- `ucon.core` (`Dimension`, `Scale`, `Unit`, `UnitFactor`, `UnitProduct`)
-- `ucon.quantity` (`Number`, `Ratio`)
-- `ucon.units` (canonical SI definitions)
-- Initial CI, testing, and packaging
+Building on v0.3.5 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 units, callable syntax)
+- Callable unit API: `meter(5)`, `(mile / hour)(60)`
+- `Number.simplify()` for base-scale normalization
+- `Dimension.information` with `units.bit`, `units.byte`
 
 ---
 
@@ -46,18 +49,26 @@ Stable baseline for:
 
 ---
 
-## ⚙️ v0.4.x — Conversion System Foundations (Up Next)
+## ⚙️ v0.4.x — Conversion System Foundations (In Progress)
 
 ### 🔹 Summary
 > Implements unified conversion engine for standard, linear, and affine conversions.
+> Introduces callable unit API for ergonomic quantity construction.
 
 ### ✅ Goals
-- [ ] Introduce `ConversionGraph` registry keyed by `Dimension`
-- [ ] Add support for `standard`, `linear`, and `affine` conversion types
-- [ ] Implement `Number.to(target_unit)` and `Number.simplify()`
-- [ ] Scale-only conversions short-circuit without graph lookup
-- [ ] Composite-to-composite conversion via per-component decomposition
-- [ ] Round-trip validation for reversible conversions
+- [x] Introduce `ConversionGraph` registry keyed by `Dimension`
+- [x] Add support for `standard`, `linear`, and `affine` conversion types
+- [x] Implement `Number.to(target_unit)` conversion API
+- [x] Scale-only conversions short-circuit without graph lookup
+- [x] Composite-to-composite conversion via per-component decomposition
+- [x] Round-trip validation for reversible conversions (inverse maps)
+- [x] Callable unit syntax: `meter(5)`, `(mile / hour)(60)`
+- [x] Default graph with common SI and imperial conversions
+- [x] Imperial units: `foot`, `mile`, `yard`, `inch`, `pound`, `ounce`, `fahrenheit`, `gallon`
+- [x] `Number.simplify()` — Express in base scale
+- [x] `Dimension.information` with `units.bit` and `units.byte`
+- [x] `Vector` extended to 8 components (added B for information)
+- [x] Information unit conversions in default graph (byte ↔ bit)
 - [ ] Extend tests to include temperature, pressure, and base SI conversions
 - [ ] Document Exponent/Scale relationship in developer guide
 
@@ -65,6 +76,9 @@ Stable baseline for:
 - Unified conversion taxonomy
 - Reversible, dimension-checked conversions
 - Scale-aware graph that leverages the `Unit`/`UnitFactor` separation from v0.3.x
+- Ergonomic API: units are callable, returning `Number` instances
+- Information dimension support (bit, byte) with binary prefix compatibility
+- `Number.simplify()` for expressing quantities in base scale
 - Forms the basis for nonlinear and domain-specific conversion families
 
 ---
@@ -202,7 +216,7 @@ Stable baseline for:
 | Version | Theme | Key Focus | Status |
 |----------|--------|------------|---------|
 | **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
-| **0.4.0** | Conversion Engine | `ConversionGraph`, `Number.to()`, scale-aware lookup | 🚧 Up Next |
+| **0.4.0** | Conversion Engine | `ConversionGraph`, `Number.to()`, callable units | 🚧 In Progress |
 | **0.5.0** | Unit Systems & Registries | Extensible registry system | ⏳ Planned |
 | **0.6.0** | Nonlinear Conversions | Logarithmic / exponential families | ⏳ Planned |
 | **0.7.0** | Testing & API Polish | Coverage, ergonomics, stability | ⏳ Planned |

ucon-0.4.0/tests/ucon/conversion/test_graph.py

@@ -0,0 +1,175 @@
+# © 2026 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
+import unittest
+
+from ucon import units
+from ucon.core import Dimension, Scale, Unit, UnitFactor, UnitProduct
+from ucon.graph import (
+    ConversionGraph,
+    DimensionMismatch,
+    ConversionNotFound,
+    CyclicInconsistency,
+)
+from ucon.maps import LinearMap, AffineMap
+
+
+class TestConversionGraphEdgeManagement(unittest.TestCase):
+
+    def setUp(self):
+        self.graph = ConversionGraph()
+        self.meter = units.meter
+        self.foot = Unit(name='foot', dimension=Dimension.length, aliases=('ft',))
+        self.inch = Unit(name='inch', dimension=Dimension.length, aliases=('in',))
+        self.gram = units.gram
+
+    def test_add_and_retrieve_edge(self):
+        self.graph.add_edge(src=self.meter, dst=self.foot, map=LinearMap(3.28084))
+        m = self.graph.convert(src=self.meter, dst=self.foot)
+        self.assertAlmostEqual(m(1), 3.28084, places=4)
+
+    def test_inverse_auto_stored(self):
+        self.graph.add_edge(src=self.meter, dst=self.foot, map=LinearMap(3.28084))
+        m = self.graph.convert(src=self.foot, dst=self.meter)
+        self.assertAlmostEqual(m(1), 0.3048, places=4)
+
+    def test_dimension_mismatch_rejected(self):
+        with self.assertRaises(DimensionMismatch):
+            self.graph.add_edge(src=self.meter, dst=self.gram, map=LinearMap(1))
+
+    def test_cyclic_consistency_check(self):
+        self.graph.add_edge(src=self.meter, dst=self.foot, map=LinearMap(3.28084))
+        # Adding inconsistent reverse should raise
+        with self.assertRaises(CyclicInconsistency):
+            self.graph.add_edge(src=self.foot, dst=self.meter, map=LinearMap(0.5))  # wrong!
+
+
+class TestConversionGraphUnitConversion(unittest.TestCase):
+
+    def setUp(self):
+        self.graph = ConversionGraph()
+        self.meter = units.meter
+        self.foot = Unit(name='foot', dimension=Dimension.length, aliases=('ft',))
+        self.inch = Unit(name='inch', dimension=Dimension.length, aliases=('in',))
+        self.yard = Unit(name='yard', dimension=Dimension.length, aliases=('yd',))
+
+    def test_identity_conversion(self):
+        m = self.graph.convert(src=self.meter, dst=self.meter)
+        self.assertTrue(m.is_identity())
+
+    def test_direct_edge(self):
+        self.graph.add_edge(src=self.meter, dst=self.foot, map=LinearMap(3.28084))
+        m = self.graph.convert(src=self.meter, dst=self.foot)
+        self.assertAlmostEqual(m(1), 3.28084, places=4)
+
+    def test_composed_path(self):
+        self.graph.add_edge(src=self.meter, dst=self.foot, map=LinearMap(3.28084))
+        self.graph.add_edge(src=self.foot, dst=self.inch, map=LinearMap(12))
+        m = self.graph.convert(src=self.meter, dst=self.inch)
+        self.assertAlmostEqual(m(1), 39.37008, places=3)
+
+    def test_multi_hop_path(self):
+        self.graph.add_edge(src=self.meter, dst=self.foot, map=LinearMap(3.28084))
+        self.graph.add_edge(src=self.foot, dst=self.inch, map=LinearMap(12))
+        self.graph.add_edge(src=self.inch, dst=self.yard, map=LinearMap(1/36))
+        m = self.graph.convert(src=self.meter, dst=self.yard)
+        self.assertAlmostEqual(m(1), 1.0936, places=3)
+
+    def test_no_path_raises(self):
+        mile = Unit(name='mile', dimension=Dimension.length, aliases=('mi',))
+        with self.assertRaises(ConversionNotFound):
+            self.graph.convert(src=self.meter, dst=mile)
+
+    def test_dimension_mismatch_on_convert(self):
+        with self.assertRaises(DimensionMismatch):
+            self.graph.convert(src=self.meter, dst=units.second)
+
+
+class TestConversionGraphProductConversion(unittest.TestCase):
+
+    def setUp(self):
+        self.graph = ConversionGraph()
+        self.meter = units.meter
+        self.second = units.second
+        self.mile = Unit(name='mile', dimension=Dimension.length, aliases=('mi',))
+        self.hour = Unit(name='hour', dimension=Dimension.time, aliases=('h',))
+
+        # Register unit conversions
+        self.graph.add_edge(src=self.meter, dst=self.mile, map=LinearMap(0.000621371))
+        self.graph.add_edge(src=self.second, dst=self.hour, map=LinearMap(1/3600))
+
+    def test_factorwise_velocity_conversion(self):
+        m_per_s = UnitProduct({
+            UnitFactor(self.meter, Scale.one): 1,
+            UnitFactor(self.second, Scale.one): -1,
+        })
+        mi_per_hr = UnitProduct({
+            UnitFactor(self.mile, Scale.one): 1,
+            UnitFactor(self.hour, Scale.one): -1,
+        })
+
+        m = self.graph.convert(src=m_per_s, dst=mi_per_hr)
+        # 1 m/s = 2.23694 mi/h
+        self.assertAlmostEqual(m(1), 2.237, places=2)
+
+    def test_scale_ratio_in_factorwise(self):
+        km = UnitProduct({UnitFactor(self.meter, Scale.kilo): 1})
+        m = UnitProduct({UnitFactor(self.meter, Scale.one): 1})
+
+        conversion = self.graph.convert(src=km, dst=m)
+        self.assertAlmostEqual(conversion(1), 1000, places=6)
+
+    def test_direct_product_edge(self):
+        # Define joule and watt_hour as UnitProducts
+        g = units.gram
+        joule = UnitProduct({
+            UnitFactor(g, Scale.one): 1,
+            UnitFactor(self.meter, Scale.one): 2,
+            UnitFactor(self.second, Scale.one): -2,
+        })
+        watt = UnitProduct({
+            UnitFactor(g, Scale.one): 1,
+            UnitFactor(self.meter, Scale.one): 2,
+            UnitFactor(self.second, Scale.one): -3,
+        })
+        watt_hour = watt * UnitProduct({UnitFactor(self.hour, Scale.one): 1})
+
+        # Register direct edge
+        self.graph.add_edge(src=joule, dst=watt_hour, map=LinearMap(1/3600))
+
+        m = self.graph.convert(src=joule, dst=watt_hour)
+        self.assertAlmostEqual(m(7200), 2.0, places=6)
+
+    def test_product_identity(self):
+        m_per_s = UnitProduct({
+            UnitFactor(self.meter, Scale.one): 1,
+            UnitFactor(self.second, Scale.one): -1,
+        })
+        m = self.graph.convert(src=m_per_s, dst=m_per_s)
+        self.assertTrue(m.is_identity())
+
+
+class TestConversionGraphTemperature(unittest.TestCase):
+
+    def setUp(self):
+        self.graph = ConversionGraph()
+        self.celsius = Unit(name='celsius', dimension=Dimension.temperature, aliases=('°C',))
+        self.kelvin = Unit(name='kelvin', dimension=Dimension.temperature, aliases=('K',))
+        self.fahrenheit = Unit(name='fahrenheit', dimension=Dimension.temperature, aliases=('°F',))
+
+    def test_celsius_to_kelvin(self):
+        self.graph.add_edge(src=self.celsius, dst=self.kelvin, map=AffineMap(1, 273.15))
+        m = self.graph.convert(src=self.celsius, dst=self.kelvin)
+        self.assertAlmostEqual(m(0), 273.15, places=2)
+        self.assertAlmostEqual(m(100), 373.15, places=2)
+
+    def test_celsius_to_fahrenheit_via_kelvin(self):
+        # C → K: K = C + 273.15
+        self.graph.add_edge(src=self.celsius, dst=self.kelvin, map=AffineMap(1, 273.15))
+        # F → K: K = (F - 32) * 5/9 + 273.15 = 5/9 * F + 255.372
+        self.graph.add_edge(src=self.fahrenheit, dst=self.kelvin, map=AffineMap(5/9, 255.372))
+
+        m = self.graph.convert(src=self.celsius, dst=self.fahrenheit)
+        self.assertAlmostEqual(m(0), 32, places=0)
+        self.assertAlmostEqual(m(100), 212, places=0)

ucon-0.4.0/tests/ucon/conversion/test_map.py

@@ -0,0 +1,163 @@
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
+import unittest
+
+from ucon.maps import AffineMap, ComposedMap, LinearMap, Map
+
+
+class TestLinearMap(unittest.TestCase):
+
+    def test_apply(self):
+        m = LinearMap(39.37)
+        self.assertAlmostEqual(m(1.0), 39.37)
+        self.assertAlmostEqual(m(0.0), 0.0)
+        self.assertAlmostEqual(m(2.5), 98.425)
+
+    def test_inverse(self):
+        m = LinearMap(39.37)
+        inv = m.inverse()
+        self.assertIsInstance(inv, LinearMap)
+        self.assertAlmostEqual(inv.a, 1.0 / 39.37)
+
+    def test_inverse_zero_raises(self):
+        m = LinearMap(0)
+        with self.assertRaises(ZeroDivisionError):
+            m.inverse()
+
+    def test_round_trip(self):
+        m = LinearMap(39.37)
+        for x in [0.0, 1.0, -5.5, 1000.0]:
+            self.assertAlmostEqual(m.inverse()(m(x)), x, places=10)
+
+    def test_compose_closed(self):
+        f = LinearMap(39.37)
+        g = LinearMap(1.0 / 12.0)
+        composed = f @ g
+        self.assertIsInstance(composed, LinearMap)
+        self.assertAlmostEqual(composed.a, 39.37 / 12.0)
+
+    def test_compose_apply(self):
+        f = LinearMap(2.0)
+        g = LinearMap(3.0)
+        # (f @ g)(x) = f(g(x)) = 2 * (3 * x) = 6x
+        self.assertAlmostEqual((f @ g)(5.0), 30.0)
+
+    def test_identity(self):
+        ident = LinearMap.identity()
+        self.assertAlmostEqual(ident(42.0), 42.0)
+        m = LinearMap(7.0)
+        self.assertEqual(m @ ident, m)
+        self.assertEqual(ident @ m, m)
+
+    def test_invertible(self):
+        self.assertTrue(LinearMap(5.0).invertible)
+        self.assertFalse(LinearMap(0).invertible)
+
+    def test_eq(self):
+        self.assertEqual(LinearMap(3.0), LinearMap(3.0))
+        self.assertNotEqual(LinearMap(3.0), LinearMap(4.0))
+
+    def test_repr(self):
+        self.assertIn("39.37", repr(LinearMap(39.37)))
+
+    def test_matmul_non_map_returns_not_implemented(self):
+        m = LinearMap(2.0)
+        result = m.__matmul__(42)
+        self.assertIs(result, NotImplemented)
+
+
+class TestAffineMap(unittest.TestCase):
+
+    def test_apply(self):
+        # Celsius to Fahrenheit: F = 1.8 * C + 32
+        c_to_f = AffineMap(1.8, 32.0)
+        self.assertAlmostEqual(c_to_f(0.0), 32.0)
+        self.assertAlmostEqual(c_to_f(100.0), 212.0)
+        self.assertAlmostEqual(c_to_f(-40.0), -40.0)
+
+    def test_inverse(self):
+        c_to_f = AffineMap(1.8, 32.0)
+        f_to_c = c_to_f.inverse()
+        self.assertIsInstance(f_to_c, AffineMap)
+        self.assertAlmostEqual(f_to_c(32.0), 0.0)
+        self.assertAlmostEqual(f_to_c(212.0), 100.0)
+
+    def test_inverse_zero_raises(self):
+        m = AffineMap(0, 5.0)
+        with self.assertRaises(ZeroDivisionError):
+            m.inverse()
+
+    def test_round_trip(self):
+        m = AffineMap(1.8, 32.0)
+        for x in [0.0, 100.0, -40.0, 37.5]:
+            self.assertAlmostEqual(m.inverse()(m(x)), x, places=10)
+
+    def test_compose_closed(self):
+        f = AffineMap(2.0, 3.0)
+        g = AffineMap(4.0, 5.0)
+        composed = f @ g
+        self.assertIsInstance(composed, AffineMap)
+        # f(g(x)) = 2*(4x+5)+3 = 8x+13
+        self.assertAlmostEqual(composed.a, 8.0)
+        self.assertAlmostEqual(composed.b, 13.0)
+
+    def test_compose_apply(self):
+        f = AffineMap(2.0, 3.0)
+        g = AffineMap(4.0, 5.0)
+        for x in [0.0, 1.0, -2.0]:
+            self.assertAlmostEqual((f @ g)(x), f(g(x)), places=10)
+
+    def test_invertible(self):
+        self.assertTrue(AffineMap(1.8, 32.0).invertible)
+        self.assertFalse(AffineMap(0, 32.0).invertible)
+
+    def test_eq(self):
+        self.assertEqual(AffineMap(1.8, 32.0), AffineMap(1.8, 32.0))
+        self.assertNotEqual(AffineMap(1.8, 32.0), AffineMap(1.8, 0.0))
+
+    def test_repr(self):
+        r = repr(AffineMap(1.8, 32.0))
+        self.assertIn("1.8", r)
+        self.assertIn("32.0", r)
+
+
+class TestComposedMap(unittest.TestCase):
+
+    def test_heterogeneous_composition(self):
+        # LinearMap @ AffineMap now returns AffineMap (closed composition)
+        # Use ComposedMap directly to test the fallback behavior
+        lin = LinearMap(2.0)
+        aff = AffineMap(3.0, 1.0)
+        composed = ComposedMap(lin, aff)
+        # lin(aff(x)) = 2 * (3x + 1) = 6x + 2
+        self.assertAlmostEqual(composed(0.0), 2.0)
+        self.assertAlmostEqual(composed(1.0), 8.0)
+
+    def test_inverse(self):
+        composed = ComposedMap(LinearMap(2.0), AffineMap(3.0, 1.0))
+        for x in [0.0, 1.0, -3.0, 10.0]:
+            self.assertAlmostEqual(composed.inverse()(composed(x)), x, places=10)
+
+    def test_invertible(self):
+        self.assertTrue(ComposedMap(LinearMap(2.0), AffineMap(3.0, 1.0)).invertible)
+        self.assertFalse(ComposedMap(LinearMap(0), AffineMap(3.0, 1.0)).invertible)
+
+    def test_non_invertible_raises(self):
+        composed = ComposedMap(LinearMap(0), AffineMap(3.0, 1.0))
+        with self.assertRaises(ValueError):
+            composed.inverse()
+
+    def test_repr(self):
+        composed = ComposedMap(LinearMap(2.0), AffineMap(3.0, 1.0))
+        r = repr(composed)
+        self.assertIn("LinearMap", r)
+        self.assertIn("AffineMap", r)
+
+
+class TestMapABC(unittest.TestCase):
+
+    def test_cannot_instantiate(self):
+        with self.assertRaises(TypeError):
+            Map()