ucon 0.4.2__tar.gz → 0.5.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.4.2
+Version: 0.5.1
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -35,7 +35,12 @@ Dynamic: maintainer
 Dynamic: maintainer-email
 Dynamic: summary
 
-<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="200" />
+<table>
+  <tr>
+    <td width="200">
+      <img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/221c60e85ac8361c7d202896b52c1a279081b54c/ucon-logo.png" align="left" width="200" />
+    </td>
+    <td>
 
 # ucon
 
@@ -45,6 +50,10 @@ Dynamic: summary
 [![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)
 
+   </td>
+  </tr>
+</table>
+
 > A lightweight, **unit-aware computation library** for Python — built on first-principles.
 
 ---
@@ -57,6 +66,8 @@ It combines **units**, **scales**, and **dimensions** into a composable algebra
 - Dimensional analysis through `Number` and `Ratio`
 - 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.
@@ -188,16 +199,54 @@ distance_mi = distance.to(units.mile)
 print(distance_mi)  # <3.107... mi>
 ```
 
+Dimensionless units have semantic isolation — angles, solid angles, and ratios are distinct:
+```python
+import math
+from ucon import units
+
+# Angle conversions
+angle = units.radian(math.pi)
+print(angle.to(units.degree))  # <180.0 deg>
+
+# Ratio conversions
+ratio = units.percent(50)
+print(ratio.to(units.ppm))  # <500000.0 ppm>
+
+# Cross-family conversions are prevented
+units.radian(1).to(units.percent)  # raises ConversionNotFound
+```
+
+Uncertainty propagates through arithmetic and conversions:
+```python
+from ucon import units
+
+# Measurements with uncertainty
+length = units.meter(1.234, uncertainty=0.005)
+width = units.meter(0.567, uncertainty=0.003)
+
+print(length)  # <1.234 ± 0.005 m>
+
+# Uncertainty propagates through arithmetic (quadrature)
+area = length * width
+print(area)  # <0.699678 ± 0.00424... m²>
+
+# Uncertainty propagates through conversion
+length_ft = length.to(units.foot)
+print(length_ft)  # <4.048... ± 0.0164... ft>
+```
+
 ---
 
 ## Roadmap Highlights
 
 | 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()`, 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 |
+| **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** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
+| **0.5.x** | Unit Systems | `BasisMap`, `UnitSystem` | 🚧 In Progress |
+| **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 

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

@@ -1,4 +1,9 @@
-<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="200" />
+<table>
+  <tr>
+    <td width="200">
+      <img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/221c60e85ac8361c7d202896b52c1a279081b54c/ucon-logo.png" align="left" width="200" />
+    </td>
+    <td>
 
 # ucon
 
@@ -8,6 +13,10 @@
 [![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)
 
+   </td>
+  </tr>
+</table>
+
 > A lightweight, **unit-aware computation library** for Python — built on first-principles.
 
 ---
@@ -20,6 +29,8 @@ It combines **units**, **scales**, and **dimensions** into a composable algebra
 - Dimensional analysis through `Number` and `Ratio`
 - 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.
@@ -151,16 +162,54 @@ distance_mi = distance.to(units.mile)
 print(distance_mi)  # <3.107... mi>
 ```
 
+Dimensionless units have semantic isolation — angles, solid angles, and ratios are distinct:
+```python
+import math
+from ucon import units
+
+# Angle conversions
+angle = units.radian(math.pi)
+print(angle.to(units.degree))  # <180.0 deg>
+
+# Ratio conversions
+ratio = units.percent(50)
+print(ratio.to(units.ppm))  # <500000.0 ppm>
+
+# Cross-family conversions are prevented
+units.radian(1).to(units.percent)  # raises ConversionNotFound
+```
+
+Uncertainty propagates through arithmetic and conversions:
+```python
+from ucon import units
+
+# Measurements with uncertainty
+length = units.meter(1.234, uncertainty=0.005)
+width = units.meter(0.567, uncertainty=0.003)
+
+print(length)  # <1.234 ± 0.005 m>
+
+# Uncertainty propagates through arithmetic (quadrature)
+area = length * width
+print(area)  # <0.699678 ± 0.00424... m²>
+
+# Uncertainty propagates through conversion
+length_ft = length.to(units.foot)
+print(length_ft)  # <4.048... ± 0.0164... ft>
+```
+
 ---
 
 ## Roadmap Highlights
 
 | 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()`, 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 |
+| **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** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
+| **0.5.x** | Unit Systems | `BasisMap`, `UnitSystem` | 🚧 In Progress |
+| **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 

ucon-0.5.1/ROADMAP.md

@@ -0,0 +1,271 @@
+# ucon Roadmap
+
+> *A clear path from algebraic foundation to a stable 1.0 release.*
+
+---
+
+## Vision
+
+ucon is a dimensional analysis library for engineers building systems where unit handling is infrastructure, not just convenience.
+
+**Target users:**
+
+- Library authors embedding unit handling without global state
+- Domain specialists defining dimensions that match their field
+- Modern stack developers wanting first-class Pydantic, Polars, MCP support
+
+---
+
+## Release Timeline
+
+| Version | Theme | Status |
+|---------|-------|--------|
+| v0.3.x | Dimensional Algebra | Complete |
+| 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.8.0 | String Parsing | Planned |
+| v0.9.0 | Constants + Logarithmic Units | Planned |
+| v0.10.0 | DataFrame Integration | Planned |
+| v1.0.0 | API Stability | Planned |
+
+---
+
+## Current Version: **v0.5.x** (in progress)
+
+Building on v0.5.0 baseline:
+- `ucon.core` (`Dimension`, `Scale`, `Unit`, `UnitFactor`, `UnitProduct`, `Number`, `Ratio`)
+- `ucon.maps` (`Map`, `LinearMap`, `AffineMap`, `ComposedMap` with `derivative()`)
+- `ucon.graph` (`ConversionGraph`, default graph, `get_default_graph()`, `using_graph()`)
+- `ucon.units` (SI + imperial + information + angle + ratio units, callable syntax)
+- Callable unit API: `meter(5)`, `(mile / hour)(60)`
+- `Number.simplify()` for base-scale normalization
+- `Dimension.information` with `units.bit`, `units.byte`
+- Pseudo-dimensions: `angle`, `solid_angle`, `ratio` with semantic isolation
+- Uncertainty propagation: `meter(1.234, uncertainty=0.005)` with quadrature arithmetic
+
+---
+
+## v0.3.x — Dimensional Algebra (Complete)
+
+**Theme:** Algebraic foundation.
+
+- [x] `Vector` and `Dimension` classes
+- [x] Unit/Scale separation: `Unit` is atomic, `UnitFactor` pairs unit+scale
+- [x] `UnitProduct` with `fold_scale()` and `_residual_scale_factor`
+- [x] `Exponent` algebraic operations (`__mul__`, `__truediv__`, `to_base`)
+- [x] Scale/Exponent integration for prefix arithmetic
+
+**Outcomes:**
+- All units acquire explicit dimensional semantics
+- Enables composable and type-safe dimensional operations
+- Establishes the mathematical foundation for future conversions
+- Unified algebraic foundation for all scaling and magnitude operations
+- Clean Unit/Scale separation: `Unit` is an atomic symbol, `UnitFactor` pairs it with a `Scale`
+- `UnitProduct` correctly tracks residual scale from cancelled units
+- Type system is ready for a `ConversionGraph` to be built on top
+
+---
+
+## v0.4.x — Conversion System Foundations (Complete)
+
+**Theme:** First useful release.
+
+- [x] `Map` hierarchy (`LinearMap`, `AffineMap`, `ComposedMap`)
+- [x] `Quantity` class (callable unit constructor)
+- [x] `ConversionGraph` with edge API and BFS path finding
+- [x] `Number.to()` wired to graph
+- [x] Default graph with SI + Imperial + conventional units
+- [x] Unit registry with `get_unit_by_name()`
+- [x] Graph management (`get_default_graph`, `set_default_graph`, `using_graph`)
+- [x] `Dimension.information` with `bit`, `byte`
+- [x] `Vector` extended to 8 components (added B for information)
+- [x] Binary scale prefixes: `kibi`, `mebi`, `gibi`, `tebi`, `pebi`, `exbi`
+- [x] `Number.simplify()` for base-scale normalization
+- [x] Temperature, pressure, and base SI conversion tests
+- [x] Exponent/Scale developer guide
+
+**Outcomes:**
+- 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
+
+---
+
+## v0.5.0 — Dimensionless Units (Complete)
+
+**Theme:** Complete the dimension model.
+
+- [x] Pseudo-dimensions: `angle`, `solid_angle`, `ratio` (same zero vector, distinct enum identity)
+- [x] Angle units: `radian`, `degree`, `gradian`, `arcminute`, `arcsecond`, `turn`
+- [x] Solid angle units: `steradian`, `square_degree`
+- [x] Ratio units: `percent`, `permille`, `ppm`, `ppb`, `basis_point`
+- [x] Cross-pseudo-dimension conversion fails (enforced isolation)
+- [x] Conversion edges for all new units
+
+**Outcomes:**
+- Semantic isolation prevents nonsensical conversions (radian → percent)
+- Rich dimensionless unit coverage for geometry, optics, finance, chemistry
+- Complete dimension model ready for metrology extensions
+
+---
+
+## v0.5.x — Uncertainty Propagation (Complete)
+
+**Theme:** Metrology foundation.
+
+- [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
+- Correct propagation through both arithmetic and unit conversion
+- Foundation for full metrology capabilities
+
+---
+
+## v0.5.x — BasisMap + UnitSystem
+
+**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
+
+**Outcomes:**
+- `BasisMap` enables system-aware "express in base units" functionality
+- Named unit systems for domain-specific workflows
+- Foundation for plugin-style system extensions
+
+---
+
+## 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
+
+**Theme:** API and persistence integration.
+
+- [ ] Native Pydantic v2 support for `Number`
+- [ ] JSON serialization/deserialization
+- [ ] Pickle support
+- [ ] Optional: MCP server for unit conversion tool
+
+**Outcomes:**
+- Native validation and serialization for dimensioned quantities
+- Enables safe configuration in data models and APIs
+- Bridges ucon's algebraic model with modern Python typing ecosystems
+
+---
+
+## v0.8.0 — String Parsing
+
+**Theme:** Ergonomic input.
+
+- [ ] `parse("60 mph")` → `Number`
+- [ ] `parse("kg * m / s^2")` → `UnitProduct`
+- [ ] Alias resolution (`meters`, `metre`, `m` all work)
+- [ ] Uncertainty parsing: `parse("1.234 ± 0.005 m")`
+
+**Outcomes:**
+- Human-friendly unit input for interactive and configuration use cases
+- Robust alias handling for international and domain-specific conventions
+- Complete round-trip: parse → compute → serialize
+
+---
+
+## v0.9.0 — Constants + Logarithmic Units
+
+**Theme:** Physical completeness.
+
+- [ ] Physical constants with uncertainties: `c`, `h`, `G`, `k_B`, `N_A`, etc.
+- [ ] `LogMap` for logarithmic conversions
+- [ ] Logarithmic units: `decibel`, `bel`, `neper`
+- [ ] pH scale support
+- [ ] Currency dimension (with caveats about exchange rates)
+
+**Outcomes:**
+- Support for function-based (nonlinear) physical conversions
+- Enables acoustics (dB), chemistry (pH), and signal processing domains
+- Physical constants with CODATA uncertainties
+
+---
+
+## v0.10.0 — DataFrame Integration
+
+**Theme:** Data science workflows.
+
+- [ ] Polars integration: `NumberColumn` type
+- [ ] Pandas integration: `NumberSeries` type
+- [ ] Column-wise conversion
+- [ ] Unit-aware arithmetic on columns
+
+**Outcomes:**
+- First-class support for data science workflows
+- Unit-safe transformations on tabular data
+- Interoperability with modern DataFrame ecosystems
+
+---
+
+## v1.0.0 — API Stability
+
+**Theme:** Production ready.
+
+- [ ] API freeze with semantic versioning commitment
+- [ ] Comprehensive documentation
+- [ ] Performance benchmarks documented
+- [ ] Security review complete
+- [ ] 2+ year LTS commitment
+
+**Outcomes:**
+- Stable, well-tested release
+- Fully type-safe and validated core
+- Production-ready for integration into scientific and engineering workflows
+
+---
+
+## Post-1.0 Vision
+
+| Feature | Notes |
+|---------|-------|
+| Uncertainty correlation | Full covariance tracking |
+| Cython optimization | Performance parity with unyt |
+| Additional integrations | SQLAlchemy, msgpack, protobuf |
+| Localization | Unit names in multiple languages |
+| NIST/CODATA updates | Automated constant updates |
+| Type-safe generics | `Number[Dimension.length]` for IDE hints |
+| Symbolic bridge to SymPy | Export units for symbolic manipulation |
+| Visualization | Dimensional relationship graphs |
+
+---
+
+## Guiding Principle
+
+> "If it can be measured, it can be represented.
+> If it can be represented, it can be validated.
+> If it can be validated, it can be trusted."

ucon-0.5.1/docs/decisions/pseudo-dimension-tuple-values.md

@@ -0,0 +1,183 @@
+# Tuple Values for Pseudo-Dimensions
+*(Preventing Python Enum Aliasing)*
+
+## 1. Context
+
+ucon v0.5.0 introduced **pseudo-dimensions**—semantic categories for dimensionless quantities:
+
+- `Dimension.angle` (radian, degree, etc.)
+- `Dimension.solid_angle` (steradian, square_degree)
+- `Dimension.ratio` (percent, ppm, etc.)
+
+These pseudo-dimensions share the **zero vector** with `Dimension.none`, preserving algebraic consistency:
+
+```python
+angle × length = length  # angle has zero vector, so it's multiplicatively transparent
+```
+
+However, they must remain **semantically distinct** to prevent nonsensical conversions like `radian(1).to(percent)`.
+
+---
+
+## 2. The Problem
+
+Python's `Enum` treats members with identical values as **aliases**:
+
+```python
+class Dimension(Enum):
+    none  = Vector()
+    angle = Vector()  # Alias for `none`!
+```
+
+With this definition:
+
+```python
+>>> Dimension.angle is Dimension.none
+True
+>>> Dimension.angle == Dimension.none
+True
+```
+
+This defeats the purpose of pseudo-dimensions.
+
+---
+
+## 3. Decision
+
+Use **tuple values** `(Vector(), "tag")` for pseudo-dimensions:
+
+```python
+class Dimension(Enum):
+    # Base dimensions (single Vector values)
+    time   = Vector(T=1)
+    length = Vector(L=1)
+    # ...
+
+    # Dimensionless
+    none = Vector()
+
+    # Pseudo-dimensions (tuple values to prevent aliasing)
+    angle       = (Vector(), "angle")
+    solid_angle = (Vector(), "solid_angle")
+    ratio       = (Vector(), "ratio")
+
+    @property
+    def vector(self) -> Vector:
+        """Extract the Vector component, handling both regular and pseudo-dimensions."""
+        if isinstance(self.value, tuple):
+            return self.value[0]
+        return self.value
+```
+
+---
+
+## 4. Rationale
+
+### 4.1. Why Tuples Work
+
+Python Enum compares member values for identity. Since each tuple is a distinct object—even if the first element is equal—Enum treats them as separate members:
+
+```python
+>>> (Vector(), "angle") == (Vector(), "solid_angle")
+False
+>>> Dimension.angle is Dimension.solid_angle
+False
+```
+
+### 4.2. Why Not Override `__eq__` and `__hash__`?
+
+Enum's comparison behavior is baked into its metaclass and cannot be cleanly overridden without breaking Enum invariants. The tuple approach works with Enum's existing machinery rather than against it.
+
+### 4.3. Why Use a `vector` Property?
+
+The `@property vector` provides a uniform interface for accessing the dimensional vector regardless of whether the dimension is regular or pseudo:
+
+```python
+Dimension.length.vector  # → Vector(L=1)
+Dimension.angle.vector   # → Vector()
+```
+
+This keeps algebraic operations simple—they always operate on vectors.
+
+---
+
+## 5. Advantages
+
+1. **Zero runtime overhead** — No metaclass hacks, no __eq__ overrides
+2. **Enum-native** — Uses standard Enum behavior, not fighting it
+3. **Clear semantics** — The tag string documents intent
+4. **Stable hashing** — Pseudo-dimensions can be dict keys and set members
+5. **Algebraic consistency preserved** — `angle.vector == none.vector`, so algebra works correctly
+
+---
+
+## 6. Shortcomings
+
+1. **Two value shapes** — Regular dimensions have `Vector` values; pseudo-dimensions have `(Vector, str)` tuples. The `vector` property abstracts this, but it's an internal irregularity.
+
+2. **`Dimension.angle.value` is a tuple** — Direct access to `.value` returns the tuple, which may surprise users expecting a `Vector`. Users should use `.vector` instead.
+
+3. **Tag strings are arbitrary** — The "angle", "solid_angle", "ratio" strings exist only to differentiate tuple values. They're not used programmatically beyond ensuring uniqueness.
+
+4. **Not extensible to many pseudo-dimensions** — While sufficient for the three current pseudo-dimensions, adding many more would require careful tag management. (This is unlikely to be an issue in practice.)
+
+---
+
+## 7. Alternatives Considered
+
+### 7.1. Subclass Vector for Each Pseudo-Dimension
+
+```python
+class AngleVector(Vector): pass
+class Dimension(Enum):
+    angle = AngleVector()
+```
+
+**Rejected** — Creates unnecessary class proliferation and complicates vector arithmetic.
+
+### 7.2. Use Integer Tags
+
+```python
+angle = (Vector(), 1)
+solid_angle = (Vector(), 2)
+```
+
+**Rejected** — String tags are self-documenting; integers require external lookup.
+
+### 7.3. Custom Enum Metaclass
+
+Override Enum's value handling to allow identical Vector values as distinct members.
+
+**Rejected** — Too complex, fragile across Python versions, and violates principle of least surprise.
+
+### 7.4. Separate Enum for Pseudo-Dimensions
+
+```python
+class PseudoDimension(Enum):
+    angle = auto()
+    solid_angle = auto()
+```
+
+**Rejected** — Requires parallel type handling throughout the codebase and complicates `Dimension` as the single source of truth.
+
+---
+
+## 8. Consequences
+
+### Positive
+
+- Pseudo-dimensions work correctly as dict keys and set members
+- Algebraic operations continue to use vector arithmetic unchanged
+- `Dimension._resolve()` returns `none` for zero-vector results (not pseudo-dimensions)
+- Cross-pseudo-dimension conversions fail with `ConversionNotFound`
+
+### Negative
+
+- Internal complexity: two value shapes in one Enum
+- Users must use `.vector` instead of `.value` for consistent access
+
+---
+
+## 9. Related Decisions
+
+- **Dimension._resolve()** — Always returns `none` for zero vectors, never pseudo-dimensions

{ucon-0.4.2 → ucon-0.5.1}/tests/ucon/test_algebra.py

@@ -71,10 +71,10 @@ class TestVectorEdgeCases(TestCase):
 
     def test_vector_equality_with_non_vector(self):
         v = Vector()
-        with self.assertRaises(AssertionError):
-            v == "not a vector"
-        with self.assertRaises(AssertionError):
-            v == None
+        # Non-Vector comparisons return NotImplemented, which Python
+        # resolves to False (not equal) rather than raising an error
+        self.assertFalse(v == "not a vector")
+        self.assertFalse(v == None)
 
     def test_hash_consistency_for_equal_vectors(self):
         v1 = Vector(1, 0, 0, 0, 0, 0, 0, 0)