ucon 2.0.1

A tool for dimensional analysis: a 'Unit CONverter'

ucon Pronounced: yoo · cahn

A lightweight, unit-aware computation library for Python — built on first-principles.

Documentation · Quickstart · API Reference

---

What is ucon?

ucon helps Python understand the physical meaning of your numbers. It treats units, dimensions, and scales as first-class objects — enforcing physics, not just labels.

from ucon import units

length = units.meter(5)
time = units.second(2)

speed = length / time      # <2.5 m/s>
invalid = length + time    # raises: incompatible dimensions

---

Installation

pip install ucon

With extras:

pip install ucon[numpy]     # NumPy array support
pip install ucon[pandas]    # Pandas DataFrame integration
pip install ucon[polars]    # Polars DataFrame integration
pip install ucon[pydantic]  # Pydantic v2 integration
pip install ucon-tools[mcp] # MCP server for AI agents (separate package)

---

Quick Examples

Parse Quantities

from ucon import parse

velocity = parse("9.81 m/s^2")       # <9.81 m/s²>
measurement = parse("1.234 ± 0.005 m")  # <1.234 ± 0.005 m>

Unit Conversion

from ucon import units, Scale

km = Scale.kilo * units.meter
distance = km(5)

print(distance.to(units.mile))  # <3.107... mi>

Dimensional Safety

from ucon import Number, Dimension, enforce_dimensions

@enforce_dimensions
def speed(
    distance: Number[Dimension.length],
    time: Number[Dimension.time],
) -> Number:
    return distance / time

speed(units.meter(100), units.second(10))   # <10.0 m/s>
speed(units.second(100), units.second(10))  # raises ValueError

NumPy Arrays

from ucon import units

# Vectorized operations on arrays
heights = units.meter([1.7, 1.8, 1.9, 2.0])
heights_ft = heights.to(units.foot)  # <[5.577, 5.906, 6.234, 6.562] ft>

# Arithmetic with unit tracking
areas = heights * units.meter([2, 2, 2, 2])  # m^2

# Statistical reductions preserve units
avg = heights.mean()  # <1.85 m>

Pydantic Integration

from pydantic import BaseModel
from ucon.integrations.pydantic import Number

class Measurement(BaseModel):
    value: Number

m = Measurement(value={"quantity": 9.8, "unit": "m/s^2"})
print(m.model_dump_json())
# {"value": {"quantity": 9.8, "unit": "m/s^2", "uncertainty": null}}

MCP Server for AI Agents

Install ucon-tools and configure in Claude Desktop:

pip install ucon-tools[mcp]

{
  "mcpServers": {
    "ucon": {
      "command": "uvx",
      "args": ["--from", "ucon-tools[mcp]", "ucon-mcp"]
    }
  }
}

AI agents can then convert units, check dimensions, and perform factor-label calculations with dimensional validation at each step.

Composable Unit Systems

import ucon
from ucon import use

with use(ucon.active_system().restrict(units=["meter", "second", "kilogram"])):
    parse("9.81 m/s^2")    # ok — length and time are in scope
    parse("100 °F")        # raises — temperature is not

UnitSystem is an immutable value. extend / restrict / merge compose systems; use(...) activates one per scope via a ContextVar — no module-global state. Full walkthrough: examples/system/README.md.

---

Features

• NumPy arrays — Vectorized operations with NumberArray for batch computations
• Pandas/Polars — Unit-aware DataFrames with NumberSeries and NumberColumn
• Physical constants — CODATA 2022 values with uncertainty propagation (E = m * c**2)
• Custom constants — Define domain-specific constants with uncertainty propagation
• 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 — Measurement errors propagate through arithmetic and conversions; conversion factor uncertainty from measured constants (Planck, atomic) propagates on opt-in
• 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

---

Roadmap Highlights

Version	Theme	Status
0.x	Algebraic foundation: Unit/Scale separation, ConversionGraph, dimension/basis abstraction, uncertainty propagation, NumPy/Pandas/Polars, Pydantic, MCP	Complete
1.0.0	API stability + 2-year LTS commitment, ~215 units across 67+ dimensions	Complete
1.2.0	TOML round-trip ConversionGraph serialization	Complete
1.3.0	Graph-independent arithmetic via BaseForm decomposition	Complete
1.4.0	Basis isomorphisms: Atomic and Planck units as first-class bases	Complete
1.5.0	Conversion factor uncertainty (GUM propagation)	Complete
1.6.0	TOML takeover — single source of truth for unit definitions	Complete
1.7.0	Basis subpackage layout: types/vector extraction	Complete
1.8.0	UnitSystem as a value type, strict same-basis Vector, explicit cross-basis ops	Complete
1.9.0	Kind-of-Quantity (KOQ) sortal lattice and formula registry — opt-in preview surface	Complete
1.10.0	Number.to() routed through the active UnitSystem; top-level active() / use() exports	Complete
1.11.0	Eager UnitSystem initialization on import; module-global default-graph singletons deprecated	Complete
1.12.0	Cycle-break completion: _active and AlgebraCache as Layer-0 leaves; AST audit against cross-module injection	Complete
2.0.0	UnitSystem algebra (extend / restrict / merge / with_*), relations (subsystem_of / compatible_with / diff), cross-system movement (adopt, Bridge), first-class Number.kind with arithmetic dispatch, ActiveContext substrate, strict=True default, marshal-based graph cache	Complete

See full roadmap: ROADMAP.md

---

Documentation

Section	Description
Getting Started	Why ucon, quickstart, installation
Guides	NumPy/Pandas/Polars, MCP server, Pydantic, custom units
Reference	API docs, unit tables, MCP tool schemas
Architecture	Design principles, ConversionGraph, comparison with Pint

---

Contributing

make venv                        # Create virtual environment
source .ucon-3.12/bin/activate   # Activate
make test                        # Run tests
make test-all                    # Run tests across all Python versions

When modifying ucon/dimension.py (adding/removing dimensions), regenerate the type stubs:

make stubs                       # Regenerate ucon/dimension.pyi
make stubs-check                 # Verify stubs are current (used in CI)

All pull requests must include a CHANGELOG.md entry under the [Unreleased] section:

## [Unreleased]

### Added

- Your new feature description (#PR_NUMBER)

Use the appropriate category: Added, Changed, Deprecated, Removed, Fixed, or Security.

---

Policies

• Security — Vulnerability reporting and dependency policy
• Support — Versioning, LTS, and backward-compatibility guarantees

License

Apache 2.0. See LICENSE.