ucon 0.11.0

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.

---

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 — 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

---

Roadmap Highlights

Version	Theme	Status
0.3.x	Dimensional Algebra	Complete
0.4.x	Conversion System	Complete
0.5.x	Dimensionless Units + Uncertainty	Complete
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 + Natural Units	Complete
0.10.x	NumPy/Pandas/Polars Integration	Complete
0.11.x	Module Reorganization	Current
1.0.0	API Stability	Planned

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.

---

License

Apache 2.0. See LICENSE.