ucon#206: natural & custom units

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-02-26
+
+### Added
+
+- Natural units support with `ConstantAwareBasisTransform` (#206)
+  - `NATURAL` basis where c = ℏ = k_B = 1 (all quantities reduce to powers of energy)
+  - `SI_TO_NATURAL` transform maps SI dimensions to natural units (e.g., velocity → dimensionless)
+  - `NATURAL_TO_SI` inverse transform with constant bindings for reconstruction
+  - `ConstantBinding` records relationships between dimensions via physical constants
+  - `LossyProjection` exception for dimensions without natural unit representation (e.g., current)
+  - `allow_projection=True` option to drop unrepresentable dimensions
+- Example demos for alternative unit systems (`examples/basis/`)
+  - `natural_units_demo.py` — particle physics natural units
+  - `geometrized_units_demo.py` — general relativity units (c = G = 1)
+  - `elemental_units_demo.py` — custom "elemental" basis
+- Natural units guide in `docs/guides/natural-units.md`
+- Natural units section in API reference `docs/reference/api.md`
+- Custom constants documentation in README and API reference
+- Comprehensive test suite for natural units (`tests/ucon/test_natural_units.py`)
+
 ### Fixed
 
 - MCP session state persistence across tool calls (#209)
@@ -418,7 +438,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial commit
 
 <!-- Links -->
-[Unreleased]: https://github.com/withtwoemms/ucon/compare/0.9.2...HEAD
+[Unreleased]: https://github.com/withtwoemms/ucon/compare/0.9.3...HEAD
+[0.9.3]: https://github.com/withtwoemms/ucon/compare/0.9.2...0.9.3
 [0.9.2]: https://github.com/withtwoemms/ucon/compare/0.9.1...0.9.2
 [0.9.1]: https://github.com/withtwoemms/ucon/compare/0.9.0...0.9.1
 [0.9.0]: https://github.com/withtwoemms/ucon/compare/0.8.5...0.9.0

README.md

@@ -128,11 +128,14 @@ AI agents can then convert units, check dimensions, and perform factor-label cal
 ## Features
 
 - **Physical constants** — CODATA 2022 values with uncertainty propagation (`E = m * c**2`)
+- **Custom constants** — Define domain-specific constants with uncertainty propagation via MCP or Python API
 - **String parsing** — `parse("9.81 m/s^2")` with uncertainty support (`1.234 ± 0.005 m`)
 - **Dimensional algebra** — Units combine through multiplication/division with automatic dimension tracking
 - **Scale prefixes** — Full SI (kilo, milli, micro, etc.) and binary (kibi, mebi) prefix support
 - **Uncertainty propagation** — Errors propagate through arithmetic and conversions
 - **Pseudo-dimensions** — Semantically isolated handling of angles, ratios, and counts
+- **Natural units** — Custom dimensional bases where c=ℏ=k_B=1 for particle physics
+- **Logarithmic units** — dB, pH, and neper conversions with uncertainty propagation
 - **Pydantic v2** — Type-safe API validation and JSON serialization
 - **MCP server** — AI agent integration with Claude, Cursor, and other MCP clients
 - **ConversionGraph** — Extensible conversion registry with custom unit support
@@ -149,7 +152,7 @@ AI agents can then convert units, check dimensions, and perform factor-label cal
 | **0.6.x** | Pydantic + MCP Server | Complete |
 | **0.7.x** | Compute Tool + Extension API | Complete |
 | **0.8.x** | Basis Abstraction + String Parsing | Complete |
-| **0.9.x** | Constants + Logarithmic Units | In Progress |
+| **0.9.x** | Constants + Natural Units | Complete |
 | **0.10.x** | NumPy/Polars Integration | Planned |
 | **1.0.0** | API Stability | Planned |
 

ROADMAP.md

@@ -46,23 +46,24 @@ ucon is a dimensional analysis library for engineers building systems where unit
 | v0.9.0 | Physical Constants | Complete |
 | v0.9.1 | Logarithmic Units | Complete |
 | v0.9.2 | MCP Constants Tools | Complete |
-| v0.9.3 | Natural Units | Planned |
+| v0.9.3 | Natural Units + MCP Session Fixes | Complete |
 | v0.10.0 | Scientific Computing | Planned |
 | v1.0.0 | API Stability | Planned |
 
 ---
 
-## Current Version: **v0.9.2** (complete)
+## Current Version: **v0.9.3** (complete)
 
-Building on v0.9.1 baseline:
-- `ucon.basis` (`Basis`, `BasisComponent`, `Vector`, `BasisTransform`, `BasisGraph`)
-- `ucon.bases` (standard bases: `SI`, `CGS`, `CGS_ESU`; standard transforms)
+Building on v0.9.2 baseline:
+- `ucon.basis` (`Basis`, `BasisComponent`, `Vector`, `BasisTransform`, `BasisGraph`, `ConstantAwareBasisTransform`)
+- `ucon.bases` (standard bases: `SI`, `CGS`, `CGS_ESU`, `NATURAL`; standard transforms including `SI_TO_NATURAL`)
 - `ucon.dimension` (`Dimension` as frozen dataclass backed by basis-aware `Vector`)
 - `ucon.core` (`Scale`, `Unit`, `UnitFactor`, `UnitProduct`, `Number`, `Ratio`, `UnitSystem`, `RebasedUnit`, `Exponent`)
 - `ucon.maps` (`Map`, `LinearMap`, `AffineMap`, `ComposedMap`, `LogMap`, `ExpMap`)
 - `ucon.graph` (`ConversionGraph`, default graph, `get_default_graph()`, `using_graph()`, cross-basis conversion)
 - `ucon.units` (SI + imperial + information + angle + ratio units, callable syntax, `si` and `imperial` systems, `get_unit_by_name()`)
 - `ucon.pydantic` (`Number` type for Pydantic v2 models)
+- `ucon.mcp` (`SessionState`, `DefaultSessionState` for injectable session management)
 - Callable unit API: `meter(5)`, `(mile / hour)(60)`
 - `Number.simplify()` for base-scale normalization
 - Pseudo-dimensions: `ANGLE`, `SOLID_ANGLE`, `RATIO`, `COUNT` with semantic isolation
@@ -77,6 +78,8 @@ Building on v0.9.1 baseline:
 - Physical constants: `Constant` class with CODATA 2022 values and uncertainty propagation
 - Logarithmic units: pH with concentration dimension, dBm, dBW, dBV, dBSPL
 - MCP constants tools: `list_constants()`, `define_constant()` for AI agent access
+- Natural units: `NATURAL` basis with c=ℏ=k_B=1, `ConstantAwareBasisTransform` for non-square transforms
+- MCP session persistence: lifespan-scoped session state across tool calls
 
 ---
 
@@ -628,18 +631,27 @@ Prerequisite for factor-label chains with countable items (tablets, doses).
 
 ---
 
-## v0.9.3 — Natural Units
+## v0.9.3 — Natural Units + MCP Session Fixes (Complete)
 
-**Theme:** Custom dimensional bases where c=ℏ=1.
+**Theme:** Custom dimensional bases where c=ℏ=1, plus MCP reliability fixes.
 
-- [ ] `ConstantAwareBasisTransform` with `inverse()` for non-square transforms
-- [ ] `NATURAL` basis with single energy dimension
-- [ ] SI ↔ NATURAL transform using constant bindings
-- [ ] Documentation and examples
+### Natural Units
+
+- [x] `ConstantAwareBasisTransform` with `inverse()` for non-square transforms
+- [x] `ConstantBinding` dataclass for tracking which constants absorb dimensions
+- [x] `NATURAL` basis with single energy dimension
+- [x] SI → NATURAL transform: T→E⁻¹, L→E⁻¹, M→E, Θ→E (via ℏ, c, k_B)
+- [x] NATURAL → SI inverse transform
+- [x] Documentation and examples (`examples/basis/`)
+
+### MCP Safety Improvements (Feedback Issues)
+
+- [x] All session-dependent tools use FastMCP `Context` injection
 
 **Outcomes:**
 - Natural units leverage custom basis infrastructure
 - Foundation for particle physics and quantum field theory domains
+- MCP tools are more reliable for multi-call agent workflows
 
 ---