ucon 0.3.2rc6__tar.gz → 0.3.3__tar.gz

{ucon-0.3.2rc6 → ucon-0.3.3}/.github/workflows/publish.yaml

@@ -14,6 +14,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0  # needed for ancestry check
+          ref: ${{ github.ref_name }}
 
       - name: Set up Python
         uses: actions/setup-python@v5

{ucon-0.3.2rc6 → ucon-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.2rc6
+Version: 0.3.3
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -34,17 +34,18 @@ Dynamic: maintainer
 Dynamic: maintainer-email
 Dynamic: summary
 
-<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="420" />
+<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="200" />
 
 # ucon
 
 > Pronounced: _yoo · cahn_
-> A lightweight, **unit-aware computation library** for Python — built on first-principles.
 
 [![tests](https://github.com/withtwoemms/ucon/workflows/tests/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Atests)
 [![codecov](https://codecov.io/gh/withtwoemms/ucon/graph/badge.svg?token=BNONQTRJWG)](https://codecov.io/gh/withtwoemms/ucon)
 [![publish](https://github.com/withtwoemms/ucon/workflows/publish/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Apublish)
 
+> A lightweight, **unit-aware computation library** for Python — built on first-principles.
+
 ---
 
 ## Overview
@@ -81,35 +82,7 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-```mermaid
----
-config:
-  layout: elk
-  elk:
-    mergeEdges: true  # Combines parallel edges
-    nodePlacementStrategy: SIMPLE # Other options: SIMPLE, NETWORK_SIMPLEX, BRANDES_KOEPF (default)
----
-flowchart LR
-%% --- Algebraic substrate ---
-subgraph "Algebraic Substrate"
-  A[Exponent] --> B[Scale]
-end
-%% --- Physical ontology ---
-subgraph "Physical Ontology"
-  D[Dimension] --> E[Unit]
-end
-%% --- Value layer ---
-subgraph "Value Layer"
-  F[Number]
-  G[Ratio]
-end
-%% --- Cross-layer relationships ---
-E --> F
-B --> F
-%% Ratio composes Numbers and also evaluates to a Number
-F --> G
-G --> F
-```
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 

{ucon-0.3.2rc6 → ucon-0.3.3}/README.md

@@ -1,14 +1,15 @@
-<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="420" />
+<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="200" />
 
 # ucon
 
 > Pronounced: _yoo · cahn_
-> A lightweight, **unit-aware computation library** for Python — built on first-principles.
 
 [![tests](https://github.com/withtwoemms/ucon/workflows/tests/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Atests)
 [![codecov](https://codecov.io/gh/withtwoemms/ucon/graph/badge.svg?token=BNONQTRJWG)](https://codecov.io/gh/withtwoemms/ucon)
 [![publish](https://github.com/withtwoemms/ucon/workflows/publish/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Apublish)
 
+> A lightweight, **unit-aware computation library** for Python — built on first-principles.
+
 ---
 
 ## Overview
@@ -45,35 +46,7 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-```mermaid
----
-config:
-  layout: elk
-  elk:
-    mergeEdges: true  # Combines parallel edges
-    nodePlacementStrategy: SIMPLE # Other options: SIMPLE, NETWORK_SIMPLEX, BRANDES_KOEPF (default)
----
-flowchart LR
-%% --- Algebraic substrate ---
-subgraph "Algebraic Substrate"
-  A[Exponent] --> B[Scale]
-end
-%% --- Physical ontology ---
-subgraph "Physical Ontology"
-  D[Dimension] --> E[Unit]
-end
-%% --- Value layer ---
-subgraph "Value Layer"
-  F[Number]
-  G[Ratio]
-end
-%% --- Cross-layer relationships ---
-E --> F
-B --> F
-%% Ratio composes Numbers and also evaluates to a Number
-F --> G
-G --> F
-```
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 

{ucon-0.3.2rc6 → ucon-0.3.3}/ROADMAP.md

@@ -25,9 +25,9 @@ Stable baseline for:
 - [x] Refactor `ucon.units` to use dimensional definitions  
 - [ ] Publish documentation for dimensional operations  
 - [x] Verify uniqueness and hashing correctness across all Dimensions  
-- [ ] Redesign `Exponent` to support algebraic operations (`__mul__`, `__truediv__`, `to_base`, etc.)  
-- [ ] Remove redundant evaluated caching in favor of property-based computation  
-- [ ] Integrate `Scale` with Exponent for consistent prefix arithmetic  
+- [x] Redesign `Exponent` to support algebraic operations (`__mul__`, `__truediv__`, `to_base`, etc.)  
+- [x] Remove redundant evaluated caching in favor of property-based computation  
+- [x] Integrate `Scale` with Exponent for consistent prefix arithmetic  
 - [ ] Update `Number` and `Ratio` to use Exponent-driven scaling  
 - [ ] Add regression tests for prefix math (`kilo / milli → mega`, `2¹⁰ / 10³ → 1.024×`)  
 - [ ] Document Exponent/Scale relationship in developer guide 

ucon-0.3.3/docs/proposals/interface-unifying-the-value-layer.md

@@ -0,0 +1,131 @@
+# Design Note: Quantifiable and the Ucon Algebra
+
+## Overview
+
+`Quantifiable` defines the core behavioral contract for all measurable entities in *ucon* —
+including `Number`, `Ratio`, and any future algebraic quantity (e.g. `VectorQuantity`, `TensorQuantity`, or `UncertainQuantity`).
+
+It establishes a unified interface for interacting with physical quantities that carry *unit*,
+*scale*, and *magnitude*, providing both consistency and extensibility across the library.
+
+---
+
+## Why It Exists
+
+Before `Quantifiable`, `Number` and `Ratio` implemented overlapping methods such as
+`evaluated`, `simplify`, and `to`, but independently. This led to duplicated logic,
+ad hoc comparisons, and specialized handling in conversions and arithmetic.
+
+`Quantifiable` resolves this by formalizing the idea of “quantity-ness” as an algebraic
+typeclass — a single interface for all objects that represent measurable magnitudes.
+
+This abstraction brings:
+- **Polymorphism**: shared behavior across `Number`, `Ratio`, and future types.
+- **Code reuse**: common equality, serialization, and algebraic defaults.
+- **Type safety**: all measurable types must define the same contract.
+- **Simplified conversions**: the conversion graph can treat all quantities uniformly.
+
+---
+
+## The Quantifiable Contract
+
+Every `Quantifiable` must define:
+
+| Method | Purpose |
+|---------|----------|
+| `unit` | The dimensional anchor (e.g., meter, second, volt). |
+| `scale` | The exponential prefix (e.g., kilo, milli, one). |
+| `evaluated` | Numeric magnitude as `quantity × scale`. |
+| `simplify()` | Collapse scale to base (Scale.one). |
+| `to(target)` | Convert to another unit or scale. |
+
+Optional methods (provided by defaults):
+- `__eq__()` — Dimension-aware equality.
+- `__repr__()` — Standardized developer representation.
+- `as_dict()` — Serialization for persistence or validation.
+
+---
+
+## What It Enables
+
+### 1. Unified Algebraic Operations
+
+Functions can now operate generically on *any measurable thing*:
+
+```python
+def normalize(q: Quantifiable) -> Quantifiable:
+    return q.simplify()
+```
+
+Works for both `Number` and `Ratio` — no branching required.
+
+### 2. Simplified Conversion Logic
+
+The conversion system can be defined once:
+
+```python
+def convert(q: Quantifiable, target_unit: Unit) -> Quantifiable:
+    factor = conversion_graph[q.unit, target_unit]
+    return q.__class__(
+        quantity=q.evaluated * factor,
+        unit=target_unit,
+        scale=q.scale
+    )
+```
+
+### 3. Pydantic Integration
+
+A single model can represent any measurable value:
+
+```python
+class Measurement(BaseModel):
+    value: Quantifiable
+```
+
+This allows runtime validation of units, scales, and dimensions.
+
+### 4. Cross-Type Extensibility
+
+New classes like `VectorQuantity`, `MatrixQuantity`, or `UncertainQuantity`
+can integrate by simply implementing the same interface.
+
+```python
+class VectorQuantity(Quantifiable):
+    def evaluated(self): ...
+    def simplify(self): ...
+    def to(self, target): ...
+```
+
+### 5. Formalization and Verification
+
+The Quantifiable interface defines the algebraic properties of measurable quantities,
+making it possible to express invariants in TLA+, Coq, or other formal tools:
+
+```
+∀ q1, q2 ∈ Quantifiable :
+    q1.unit == q2.unit ⇒ simplify(q1 + q2) == simplify(q2 + q1)
+```
+
+This provides a pathway for formal verification of `ucon`'s correctness across languages.
+
+---
+
+## Summary
+
+| Benefit | Description |
+|----------|--------------|
+| **Polymorphism** | All measurable types share a common interface. |
+| **Code Simplification** | Shared behavior eliminates duplication. |
+| **Conversion Consistency** | The conversion system can treat all quantities uniformly. |
+| **Type Safety** | Explicitly enforces dimensional and scale semantics. |
+| **Formal Verifiability** | Provides a foundation for mathematical proofs of correctness. |
+| **Extensibility** | Future types can plug into `ucon`'s algebra seamlessly. |
+
+---
+
+## Closing Thoughts
+
+`Quantifiable` transforms *ucon* from a collection of data structures into a true **domain algebra** —
+a framework that defines measurable quantities as first-class algebraic entities. It bridges
+type safety, composability, and mathematical rigor, making future extensions — from vectorization
+to distributed computation — both safe and elegant.

ucon-0.3.3/docs/proposals/support-for-fractional-exponents.md

@@ -0,0 +1,144 @@
+# Discrete vs Continuous `Exponent` Comparison
+
+## Overview
+
+This document compares the **discrete (integer-only)** `Exponent` implementation used in *ucon v0.3.2*
+with the prospects of a new `Exponent` design that embraces fractional powers. It highlights how the
+continuous model restores algebraic closure, improves precision, and simplifies higher-level `Scale`
+operations.
+
+---
+
+## 1. Motivation
+
+In *ucon v0.3.2*, `Exponent` was defined as an integer power over fixed bases (2 and 10).
+This worked for standard prefixes like kilo or mebi but failed for mixed-base or non-integer scaling.
+
+The continuous design instead treats `Exponent` as a **real-valued exponential** where a given exponent of base _b_ can be written in terms of another base, _a_:
+
+$$
+a^x \times b^y = a^{x + y \cdot \log_a(b)}
+$$
+
+This modification closes the algebra under all operations avoiding fallbacks or rounding while remaining fully compatible with integer-based scales.
+
+---
+
+## 2. Feature Comparison
+
+| Property | Discrete Exponent | Continuous Exponent |
+|-----------|------------------|---------------------|
+| Power type | Integer | Float (real) |
+| Closure | Partial | Complete |
+| Mixed-base operations | Approximate or invalid | Exact |
+| Reversibility (a×b)/b=a | Approximate | Exact |
+| Fractional exponents | Not supported | Supported |
+| Precision | Rounded to prefix | Full algebraic precision |
+| Comparison | Magnitude-based | Power-difference-based |
+| Scale interaction | Enum lookup | Continuous projection |
+
+---
+
+## 3. Example Comparisons
+
+### Same-Base Operations
+
+| Operation | Discrete | Continuous |
+|------------|-----------|-------------|
+| 10³ × 10² | `<10^5>` | `<10^5.00000>` |
+| 2¹⁰ × 2⁵ | `<2^15>` | `<2^15.00000>` |
+
+No change: _integer powers remain consistent._
+
+### Mixed-Base Operations
+
+| Operation | Discrete | Continuous |
+|------------|-----------|-------------|
+| 10³ × 2¹⁰ | `nearest(10⁶)` | `<10^6.01030>` |
+| 2¹⁰ × 10³ | `nearest(2¹⁹)` | `<2^19.93157>` |
+| 10⁶ ÷ 2¹⁰ | `nearest(10⁶)` | `<10^5.98970>` |
+
+The continuous system captures **exact** mixed-base scaling.
+
+---
+
+## 4. Simplified Scale Operations
+
+The continuous `Exponent` model greatly simplifies `Scale` arithmetic.
+
+In v0.3.2, `Scale.__mul__` and `Scale.__truediv__` had to juggle base mismatches, lookups, and fallbacks.
+Now, `Scale` can delegate directly to its underlying `Exponent`:
+
+```python
+def __mul__(self, other: 'Scale') -> 'Scale':
+    result_exp = self.value * other.value  # exact Exponent
+    return Scale.dynamic(result_exp)
+```
+
+No more `nearest()` logic, no more rounding errors.
+
+### Before
+```python
+# had to guess nearest scale name
+return Scale.nearest(float(result), include_binary=include_binary)
+```
+
+### After
+```python
+# exact algebraic scaling
+return Scale.dynamic(self.value * other.value)
+```
+
+This removes three major branches of logic in the old implementation, simplifying the `Scale` layer to a thin symbolic wrapper around continuous exponents.
+
+---
+
+## 5. Conceptual Model
+
+| Level | Entity | Description |
+|--------|---------|-------------|
+| 1 | **Exponent** | Continuous exponential algebra (base^power) |
+| 2 | **Scale** | Human-readable projection onto named prefixes |
+| 3 | **Number** | Quantified magnitude combining Scale and Unit |
+
+With closure restored at the core, everything beyond it becomes simpler and more expressive.
+`Scale` no longer needs lookup heuristics or error handling.
+It can always delegate cleanly to algebraic truth.
+
+---
+
+## 6. Practical Outcomes
+
+| Aspect | Benefit |
+|---------|----------|
+| Algebraic closure | No undefined or lossy operations |
+| Extensibility | Future support for arbitrary user-defined bases |
+| Precision | Exact mixed-base conversions (e.g. kilo × kibi) |
+| Maintainability | Scale logic reduced to 1–2 lines |
+| Mathematical integrity | Continuous and reversible model |
+
+---
+
+## 7. Example
+
+```python
+from ucon.core import Exponent
+
+a = Exponent(10, 3)   # kilo
+b = Exponent(2, 10)   # kibi
+
+print(a * b)          # <10^6.01030>
+print(a / b)          # <10^-0.01030>
+print((a * b) / b)    # <10^3.00000>
+```
+
+Exact, reversible, and smooth: _no registry lookup or rounding required._
+
+---
+
+## 8. Closing Thoughts
+
+This continuous approach:
+- unifies all scaling operations algebraically,  
+- removes arbitrary lookup logic from the `Scale` layer, and  
+- lays the groundwork for reversibility across all scale relationships.

{ucon-0.3.2rc6 → ucon-0.3.3}/tests/ucon/test_core.py

@@ -109,6 +109,15 @@ class TestScale(TestCase):
         self.assertEqual(Scale.one, Scale.kibi / Scale.kibi)
         self.assertEqual(Scale.one, Scale.kibi / Scale.kilo)
 
+    def test___mul__(self):
+        self.assertEqual(Scale.kilo, Scale.kilo * Scale.one)
+        self.assertEqual(Scale.kilo, Scale.one * Scale.kilo)
+        self.assertEqual(Scale.one, Scale.kilo * Scale.milli)
+        self.assertEqual(Scale.deca, Scale.hecto * Scale.deci)
+        self.assertEqual(Scale.mega, Scale.kilo * Scale.kibi)
+        self.assertEqual(Scale.giga, Scale.mega * Scale.kilo)
+        self.assertEqual(Scale.one, Scale.one * Scale.one)
+
     def test___lt__(self):
         self.assertLess(Scale.one, Scale.kilo)
 
@@ -121,6 +130,43 @@ class TestScale(TestCase):
         self.assertIsInstance(Scale.all(), dict)
 
 
+class TestScaleMultiplicationAdditional(TestCase):
+
+    def test_decimal_combinations(self):
+        self.assertEqual(Scale.kilo * Scale.centi, Scale.deca)
+        self.assertEqual(Scale.kilo * Scale.milli, Scale.one)
+        self.assertEqual(Scale.hecto * Scale.deci, Scale.deca)
+
+    def test_binary_combinations(self):
+        # kibi (2^10) * mebi (2^20) = 2^30 (should round to nearest known)
+        result = Scale.kibi * Scale.mebi
+        self.assertEqual(result.value.base, 2)
+        self.assertTrue(isinstance(result, Scale))
+
+    def test_mixed_base_combination(self):
+        self.assertEqual(Scale.mega, Scale.kilo * Scale.kibi)
+
+    def test_result_has_no_exact_match_fallbacks_to_nearest(self):
+        # Suppose the exponent product is not in Scale.all()
+        # e.g. kilo (10^3) * deci (10^-1) = 10^2 = hecto
+        result = Scale.kilo * Scale.deci
+        self.assertEqual(result, Scale.hecto)
+
+    def test_order_independence(self):
+        # Associativity of multiplication
+        self.assertEqual(Scale.kilo * Scale.centi, Scale.centi * Scale.kilo)
+
+    def test_non_scale_operand_returns_not_implemented(self):
+        with self.assertRaises(TypeError):
+            Scale.kilo * 2
+
+    def test_large_exponent_clamping(self):
+        # simulate a very large multiplication, should still resolve
+        result = Scale.mega * Scale.mega  # 10^12, not defined -> nearest Scale
+        self.assertIsInstance(result, Scale)
+        self.assertEqual(result.value.base, 10)
+
+
 class TestScaleDivisionAdditional(TestCase):
 
     def test_division_same_base_large_gap(self):
@@ -255,7 +301,7 @@ class TestNumber(TestCase):
 
     def test___eq__(self):
         self.assertEqual(self.number, Ratio(self.number))  # 1 gram / 1
-        with self.assertRaises(ValueError):
+        with self.assertRaises(TypeError):
             self.number == 1
 
 
@@ -290,10 +336,12 @@ class TestRatio(TestCase):
         self.assertEqual(self.one_half * self.three_halves, self.three_fourths)
 
     def test___mul__(self):
-        bromine_density = Ratio(Number(units.gram, quantity=3.119), Number(units.liter, Scale.milli))
+        n1 = Number(unit=units.gram, quantity=3.119)
+        n2 = Number(unit=units.liter, scale=Scale.milli)
+        bromine_density = Ratio(n1, n2)
     
         # How many grams of bromine are in 2 milliliters?
-        two_milliliters_bromine = Number(units.liter, Scale.milli, 2)
+        two_milliliters_bromine = Number(unit=units.liter, scale=Scale.milli, quantity=2)
         ratio = two_milliliters_bromine.as_ratio() * bromine_density
         answer = ratio.evaluate()
         self.assertEqual(answer.unit.dimension, Dimension.mass)
@@ -319,7 +367,7 @@ class TestRatio(TestCase):
 
     def test___repr__(self):
         self.assertEqual(str(self.one_ratio), '<1.0 >')
-        self.assertEqual(str(self.two_ratio), '<2 > / <1 >')
+        self.assertEqual(str(self.two_ratio), '<2 > / <1.0 >')
         self.assertEqual(str(self.two_ratio.evaluate()), '<2.0 >')
 
 
@@ -458,8 +506,8 @@ class TestNumberEdgeCases(TestCase):
 
     def test_equality_with_non_number_raises_value_error(self):
         n = Number()
-        with self.assertRaises(ValueError):
-            _ = (n == "5")
+        with self.assertRaises(TypeError):
+            n == '5'
 
     def test_equality_between_numbers_and_ratios(self):
         n1 = Number(quantity=10)

{ucon-0.3.2rc6 → ucon-0.3.3}/ucon/core.py

@@ -15,6 +15,7 @@ Classes
 Together, these classes allow full arithmetic, conversion, and introspection
 of physical quantities with explicit dimensional semantics.
 """
+from dataclasses import dataclass, field
 from enum import Enum
 from functools import lru_cache, reduce, total_ordering
 from math import log2
@@ -33,6 +34,8 @@ class Exponent:
 
     Provides comparison and division semantics used internally to represent
     magnitude prefixes (e.g., kilo, mega, micro).
+
+    TODO (wittwemms): embrace fractional exponents for closure on multiplication/division.
     """
     bases = {2: log2, 10: log10}
 
@@ -198,6 +201,31 @@ class Scale(Enum):
 
         return min(candidates, key=distance)
 
+    def __mul__(self, other: 'Scale'):
+        """
+        Multiply two Scales together.
+
+        Always returns a `Scale`, representing the resulting order of magnitude.
+        If no exact prefix match exists, returns the nearest known Scale.
+        """
+        if not isinstance(other, Scale):
+            return NotImplemented
+
+        if self is Scale.one:
+            return other
+        if other is Scale.one:
+            return self
+
+        result = self.value * other.value  # delegates to Exponent.__mul__
+        include_binary = 2 in {self.value.base, other.value.base}
+
+        if isinstance(result, Exponent):
+            match = Scale.all().get(result.parts())
+            if match:
+                return Scale[match]
+
+        return Scale.nearest(float(result), include_binary=include_binary)
+
     def __truediv__(self, other: 'Scale'):
         """
         Divide one Scale by another.
@@ -210,7 +238,6 @@ class Scale(Enum):
 
         if self == other:
             return Scale.one
-
         if other is Scale.one:
             return self
 
@@ -241,7 +268,9 @@ class Scale(Enum):
         return self.value == other.value
 
 
-# TODO -- consider using a dataclass
+Quantifiable = Union['Number', 'Ratio']
+
+@dataclass
 class Number:
     """
     Represents a **numeric quantity** with an associated :class:`Unit` and :class:`Scale`.
@@ -256,11 +285,14 @@ class Number:
         >>> speed
         <2.5 (m/s)>
     """
-    def __init__(self, unit: Unit = units.none, scale: Scale = Scale.one, quantity = 1):
-        self.unit = unit
-        self.scale = scale
-        self.quantity = quantity
-        self.value = round(self.quantity * self.scale.value.evaluated, 15)
+    quantity: Union[float, int] = 1.0
+    unit: Unit = units.none
+    scale: Scale = field(default_factory=lambda: Scale.one)
+
+    @property
+    def value(self) -> float:
+        """Return numeric magnitude as quantity × scale factor."""
+        return round(self.quantity * self.scale.value.evaluated, 15)
 
     def simplify(self):
         return Number(unit=self.unit, quantity=self.value)
@@ -272,28 +304,44 @@ class Number:
     def as_ratio(self):
         return Ratio(self)
 
-    def __mul__(self, another_number: 'Number') -> 'Number':
+    def __mul__(self, other: Quantifiable) -> 'Number':
+        if not isinstance(other, (Number, Ratio)):
+            return NotImplemented
+
+        if isinstance(other, Ratio):
+            other = other.evaluate()
+
         return Number(
-            unit=self.unit * another_number.unit,
-            scale=self.scale,
-            quantity=self.quantity * another_number.quantity,
+            quantity=self.quantity * other.quantity,
+            unit=self.unit * other.unit,
+            scale=self.scale * other.scale,
         )
 
-    def __truediv__(self, another_number: 'Number') -> 'Number':
-        unit = self.unit / another_number.unit
-        scale = self.scale / another_number.scale
-        quantity = self.quantity / another_number.quantity
-        return Number(unit, scale, quantity)
-
-    def __eq__(self, another_number):
-        if isinstance(another_number, Number):
-            return (self.unit == another_number.unit) and \
-                   (self.quantity == another_number.quantity) and \
-                   (self.value == another_number.value)
-        elif isinstance(another_number, Ratio):
-            return self == another_number.evaluate()
-        else:
-            raise ValueError(f'"{another_number}" is not a Number or Ratio. Comparison not possible.')
+    def __truediv__(self, other: Quantifiable) -> 'Number':
+        if not isinstance(other, (Number, Ratio)):
+            return NotImplemented
+
+        if isinstance(other, Ratio):
+            other = other.evaluate()
+
+        return Number(
+            quantity=self.quantity / other.quantity,
+            unit=self.unit / other.unit,
+            scale=self.scale / other.scale,
+        )
+
+    def __eq__(self, other: Quantifiable) -> bool:
+        if not isinstance(other, (Number, Ratio)):
+            raise TypeError(f'Cannot compare Number to non-Number/Ratio type: {type(other)}')
+
+        elif isinstance(other, Ratio):
+            other = other.evaluate()
+
+        # Compare on evaluated numeric magnitude and exact unit
+        return (
+            self.unit == other.unit and
+            abs(self.value - other.value) < 1e-12
+        )
 
     def __repr__(self):
         return f'<{self.quantity} {"" if self.scale.name == "one" else self.scale.name}{self.unit.name}>'

{ucon-0.3.2rc6 → ucon-0.3.3}/ucon.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.2rc6
+Version: 0.3.3
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -34,17 +34,18 @@ Dynamic: maintainer
 Dynamic: maintainer-email
 Dynamic: summary
 
-<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="420" />
+<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="200" />
 
 # ucon
 
 > Pronounced: _yoo · cahn_
-> A lightweight, **unit-aware computation library** for Python — built on first-principles.
 
 [![tests](https://github.com/withtwoemms/ucon/workflows/tests/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Atests)
 [![codecov](https://codecov.io/gh/withtwoemms/ucon/graph/badge.svg?token=BNONQTRJWG)](https://codecov.io/gh/withtwoemms/ucon)
 [![publish](https://github.com/withtwoemms/ucon/workflows/publish/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Apublish)
 
+> A lightweight, **unit-aware computation library** for Python — built on first-principles.
+
 ---
 
 ## Overview
@@ -81,35 +82,7 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-```mermaid
----
-config:
-  layout: elk
-  elk:
-    mergeEdges: true  # Combines parallel edges
-    nodePlacementStrategy: SIMPLE # Other options: SIMPLE, NETWORK_SIMPLEX, BRANDES_KOEPF (default)
----
-flowchart LR
-%% --- Algebraic substrate ---
-subgraph "Algebraic Substrate"
-  A[Exponent] --> B[Scale]
-end
-%% --- Physical ontology ---
-subgraph "Physical Ontology"
-  D[Dimension] --> E[Unit]
-end
-%% --- Value layer ---
-subgraph "Value Layer"
-  F[Number]
-  G[Ratio]
-end
-%% --- Cross-layer relationships ---
-E --> F
-B --> F
-%% Ratio composes Numbers and also evaluates to a Number
-F --> G
-G --> F
-```
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 

{ucon-0.3.2rc6 → ucon-0.3.3}/ucon.egg-info/SOURCES.txt

@@ -7,7 +7,9 @@ requirements.txt
 setup.py
 .github/workflows/publish.yaml
 .github/workflows/tests.yaml
-docs/unity-distance-metric-for-nearest-scale.md
+docs/decisions/unity-distance-metric-for-nearest-scale.md
+docs/proposals/interface-unifying-the-value-layer.md
+docs/proposals/support-for-fractional-exponents.md
 tests/__init__.py
 tests/ucon/__init__.py
 tests/ucon/test_core.py