ucon 0.3.5rc2__tar.gz → 0.4.1__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.5rc2
+Version: 0.4.1
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
 Maintainer: Emmanuel I. Obi
 Maintainer-email: withtwoemms@gmail.com
 License: Apache-2.0
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
@@ -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.1}/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.1}/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,25 +49,36 @@ 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
-- [ ] Extend tests to include temperature, pressure, and base SI conversions
-- [ ] Document Exponent/Scale relationship in developer guide
+- [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)
+- [x] Extend tests to include temperature, pressure, and base SI conversions
+- [x] Document Exponent/Scale relationship in 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
 
 ---
@@ -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.1/docs/explainers/exponent-scale-relationship.md

@@ -0,0 +1,347 @@
+# Developer Guide: Exponent and Scale Relationship
+
+> Understanding the algebraic foundation of magnitude prefixes in ucon.
+
+---
+
+## Overview
+
+The `Exponent` and `Scale` classes form the algebraic foundation for handling magnitude prefixes (kilo, milli, mebi, etc.) in ucon. This guide explains their relationship and how they work together.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Scale (Enum)                           │
+│  kilo, milli, mega, kibi, mebi, etc.                       │
+│                          │                                  │
+│                          ▼                                  │
+│              ScaleDescriptor (dataclass)                    │
+│              shorthand: "k", alias: "kilo"                  │
+│                          │                                  │
+│                          ▼                                  │
+│                 Exponent (class)                            │
+│              base: 10, power: 3                             │
+│              evaluated: 1000.0                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Exponent: The Algebraic Primitive
+
+`Exponent` (`ucon.algebra`) represents a base-power pair like 10³ or 2¹⁰.
+
+### Structure
+
+```python
+class Exponent:
+    base: int   # 2 or 10 only
+    power: int | float
+
+    @property
+    def evaluated(self) -> float:
+        return self.base ** self.power
+```
+
+### Supported Bases
+
+Only two bases are supported, chosen for their prevalence in scientific and computing contexts:
+
+| Base | Use Case | Examples |
+|------|----------|----------|
+| **10** | SI prefixes (metric) | kilo (10³), milli (10⁻³), mega (10⁶) |
+| **2** | Binary prefixes (IEC) | kibi (2¹⁰), mebi (2²⁰), gibi (2³⁰) |
+
+### Arithmetic Operations
+
+Exponent supports algebraic operations that mirror the rules of exponents:
+
+```python
+from ucon.algebra import Exponent
+
+kilo = Exponent(10, 3)   # 10³ = 1000
+milli = Exponent(10, -3) # 10⁻³ = 0.001
+
+# Multiplication: add powers (same base)
+kilo * milli  # → Exponent(10, 0) = 1
+
+# Division: subtract powers (same base)
+kilo / milli  # → Exponent(10, 6) = 1,000,000
+
+# Exponentiation: multiply power
+kilo ** 2     # → Exponent(10, 6) = 1,000,000
+
+# Cross-base operations return float
+kibi = Exponent(2, 10)  # 2¹⁰ = 1024
+kilo / kibi   # → 0.9765625 (float, not Exponent)
+```
+
+### Base Conversion
+
+Convert between bases while preserving numeric value:
+
+```python
+kibi = Exponent(2, 10)  # 1024
+kibi.to_base(10)        # → Exponent(10, 3.0103...) ≈ 1024
+```
+
+---
+
+## ScaleDescriptor: Adding Human-Readable Labels
+
+`ScaleDescriptor` (`ucon.core`) wraps an `Exponent` with display information:
+
+```python
+@dataclass(frozen=True)
+class ScaleDescriptor:
+    exponent: Exponent
+    shorthand: str  # "k", "M", "Ki"
+    alias: str      # "kilo", "mega", "kibi"
+```
+
+### Properties
+
+```python
+desc = ScaleDescriptor(Exponent(10, 3), "k", "kilo")
+
+desc.evaluated  # 1000.0 (delegates to exponent)
+desc.base       # 10
+desc.power      # 3
+desc.parts()    # (10, 3)
+```
+
+---
+
+## Scale: The User-Facing Enum
+
+`Scale` (`ucon.core`) is an enum where each member's value is a `ScaleDescriptor`.
+
+### Available Scales
+
+```python
+class Scale(Enum):
+    # Binary (base 2)
+    gibi  = ScaleDescriptor(Exponent(2, 30), "Gi", "gibi")  # 2³⁰
+    mebi  = ScaleDescriptor(Exponent(2, 20), "Mi", "mebi")  # 2²⁰
+    kibi  = ScaleDescriptor(Exponent(2, 10), "Ki", "kibi")  # 2¹⁰
+
+    # Decimal (base 10)
+    peta  = ScaleDescriptor(Exponent(10, 15), "P", "peta")
+    tera  = ScaleDescriptor(Exponent(10, 12), "T", "tera")
+    giga  = ScaleDescriptor(Exponent(10, 9),  "G", "giga")
+    mega  = ScaleDescriptor(Exponent(10, 6),  "M", "mega")
+    kilo  = ScaleDescriptor(Exponent(10, 3),  "k", "kilo")
+    hecto = ScaleDescriptor(Exponent(10, 2),  "h", "hecto")
+    deca  = ScaleDescriptor(Exponent(10, 1),  "da", "deca")
+    one   = ScaleDescriptor(Exponent(10, 0),  "",  "")      # identity
+    deci  = ScaleDescriptor(Exponent(10, -1), "d", "deci")
+    centi = ScaleDescriptor(Exponent(10, -2), "c", "centi")
+    milli = ScaleDescriptor(Exponent(10, -3), "m", "milli")
+    micro = ScaleDescriptor(Exponent(10, -6), "µ", "micro")
+    nano  = ScaleDescriptor(Exponent(10, -9), "n", "nano")
+    pico  = ScaleDescriptor(Exponent(10, -12),"p", "pico")
+    femto = ScaleDescriptor(Exponent(10, -15),"f", "femto")
+```
+
+### Scale Arithmetic
+
+Scale operations delegate to Exponent arithmetic, then resolve back to a Scale:
+
+```python
+from ucon.core import Scale
+
+# Multiplication
+Scale.kilo * Scale.kilo   # → Scale.mega (10³ × 10³ = 10⁶)
+Scale.kilo * Scale.milli  # → Scale.one  (10³ × 10⁻³ = 10⁰)
+
+# Division
+Scale.mega / Scale.kilo   # → Scale.kilo (10⁶ / 10³ = 10³)
+Scale.kilo / Scale.mega   # → Scale.milli (10³ / 10⁶ = 10⁻³)
+
+# Exponentiation
+Scale.kilo ** 2           # → Scale.mega (10³)² = 10⁶
+Scale.milli ** -1         # → Scale.kilo (10⁻³)⁻¹ = 10³
+```
+
+### Nearest Scale Resolution
+
+When arithmetic produces a non-standard power, `Scale.nearest()` finds the closest match:
+
+```python
+# Non-exact result resolves to nearest scale
+Scale.kilo * Scale.kibi   # Cross-base: 1000 × 1024 = 1,024,000
+                          # → resolves to Scale.mega (closest)
+
+# Manual nearest lookup
+Scale.nearest(5000)       # → Scale.kilo (10³ = 1000 is closest)
+Scale.nearest(500)        # → Scale.one (undershoot bias)
+```
+
+The `undershoot_bias` parameter (default 0.75) penalizes scales smaller than the value, preferring slight overestimation for cleaner display.
+
+### Scale × Unit → UnitProduct
+
+The primary use case: applying a scale to a unit:
+
+```python
+from ucon.core import Scale
+from ucon import units
+
+km = Scale.kilo * units.meter   # → UnitProduct with kilo-scaled meter
+mg = Scale.milli * units.gram   # → UnitProduct with milli-scaled gram
+
+print(km.shorthand)  # "km"
+print(mg.shorthand)  # "mg"
+
+# Used in Number construction
+distance = km(5)     # 5 kilometers
+mass = mg(250)       # 250 milligrams
+```
+
+---
+
+## The Complete Stack
+
+Here's how it all fits together:
+
+```
+User writes:          km = Scale.kilo * units.meter
+                            │
+                            ▼
+Scale.kilo           ScaleDescriptor(Exponent(10, 3), "k", "kilo")
+                            │
+                            ▼
+Scale.__mul__(Unit)  Returns UnitProduct({UnitFactor(meter, kilo): 1})
+                            │
+                            ▼
+UnitProduct          Stores the unit with its scale prefix
+                            │
+                            ▼
+Number(5, unit=km)   <5 km> with quantity=5, preserving "kilo" scale
+```
+
+---
+
+## Key Design Decisions
+
+### Why Separate Exponent from Scale?
+
+1. **Algebraic Closure**: Exponent handles the pure math of base-power pairs without display concerns
+2. **Cross-Base Operations**: 2¹⁰ / 10³ returns a float because no single base can represent it
+3. **Nearest Resolution**: Scale can find the "closest" human-readable prefix for arbitrary values
+
+### Why Only Base 2 and 10?
+
+These are the only bases with standardized prefix names:
+- **Base 10**: SI prefixes (kilo, mega, giga, etc.)
+- **Base 2**: IEC binary prefixes (kibi, mebi, gibi, etc.)
+
+Other bases would require inventing new prefix names.
+
+### Why ScaleDescriptor?
+
+Separates concerns:
+- `Exponent`: Pure numeric computation
+- `ScaleDescriptor`: Adds shorthand ("k") and alias ("kilo") for display
+- `Scale`: Enum providing named access and class methods like `nearest()`
+
+---
+
+## Common Patterns
+
+### Creating Scaled Units
+
+```python
+from ucon.core import Scale
+from ucon import units
+
+# Standard metric prefixes
+km = Scale.kilo * units.meter
+MHz = Scale.mega * units.hertz
+ns = Scale.nano * units.second
+
+# Binary prefixes (for information units)
+KiB = Scale.kibi * units.byte
+GiB = Scale.gibi * units.byte
+```
+
+### Scale Arithmetic in Practice
+
+```python
+# Velocity: km/h involves scale
+km = Scale.kilo * units.meter
+speed = (km / units.hour)(100)  # 100 km/h
+
+# Energy: kJ
+kJ = Scale.kilo * units.joule
+energy = kJ(4.184)  # 4.184 kJ = 1 kcal
+```
+
+### Folding Scale into Quantity
+
+```python
+km = Scale.kilo * units.meter
+distance = km(5)
+
+# Get the scale factor
+distance.unit.fold_scale()  # 1000.0
+
+# Canonical magnitude (quantity × scale)
+distance._canonical_magnitude  # 5000.0
+```
+
+---
+
+## Testing Scale/Exponent Relationships
+
+From `tests/ucon/test_core.py`:
+
+```python
+def test_scale_multiplication_same_base(self):
+    self.assertEqual(Scale.kilo * Scale.kilo, Scale.mega)
+    self.assertEqual(Scale.kilo * Scale.milli, Scale.one)
+
+def test_scale_division(self):
+    self.assertEqual(Scale.mega / Scale.kilo, Scale.kilo)
+    self.assertEqual(Scale.kilo / Scale.mega, Scale.milli)
+
+def test_scale_exponentiation(self):
+    self.assertEqual(Scale.kilo ** 2, Scale.mega)
+    self.assertEqual(Scale.milli ** -1, Scale.kilo)
+```
+
+From `tests/ucon/test_algebra.py`:
+
+```python
+def test_exponent_multiplication(self):
+    kibibyte = Exponent(2, 10)
+    mebibyte = Exponent(2, 20)
+    product = kibibyte * mebibyte
+    self.assertEqual(product.power, 30)  # 2³⁰
+
+def test_exponent_division_same_base(self):
+    thousand = Exponent(10, 3)
+    thousandth = Exponent(10, -3)
+    ratio = thousand / thousandth
+    self.assertEqual(ratio.power, 6)  # 10⁶
+```
+
+---
+
+## Summary
+
+| Class | Module | Purpose |
+|-------|--------|---------|
+| `Exponent` | `ucon.algebra` | Base-power arithmetic (10³, 2¹⁰) |
+| `ScaleDescriptor` | `ucon.core` | Wraps Exponent with shorthand/alias |
+| `Scale` | `ucon.core` | Enum of named prefixes with algebra |
+
+The relationship flows downward:
+- `Scale.kilo` → `ScaleDescriptor` → `Exponent(10, 3)`
+
+Arithmetic flows upward:
+- `Exponent` math → resolve to `Scale` via lookup or `nearest()`
+
+This layered design provides:
+- **Type safety**: Scale operations return Scale, not raw numbers
+- **Algebraic closure**: `kilo * kilo = mega`, not just `1000000`
+- **Human readability**: Quantities display with appropriate prefixes

{ucon-0.3.5rc2 → ucon-0.4.1}/setup.py

@@ -23,7 +23,7 @@ setup(
     maintainer_email='withtwoemms@gmail.com',
     url='https://github.com/withtwoemms/ucon',
     classifiers=[
-        'Development Status :: 3 - Alpha',
+        'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',
         'Intended Audience :: Education',
         'Intended Audience :: Science/Research',