physure 0.2.2

Unit-aware, dimension-correct computing for Python — powered by a Rust core

Units, dimensions, and correlated uncertainty tracked through every calculation, with zero overhead under torch.compile / jax.jit.

Why physure?

Most unit libraries make you choose between correctness and speed. physure (physics + measure) refuses the trade-off:

• Correlated uncertainty propagation. Full sparse-covariance tracking between quantities (GUM-style), not just independent error bars. If x and y share history, x - y knows it.
• Native-speed dimensional analysis. Unit arithmetic runs in Rust (~50 ns per operation) with rational exponents — no floating-point drift in dimensions, zero-copy buffer FFI to NumPy.
• ML-ready. Quantity wraps NumPy, PyTorch, and JAX arrays. Under @physure.jit, units are validated at trace time and evaporate at runtime: ~1.17× vs. raw compiled PyTorch.
• Static unit checking. A mypy plugin narrows Q_(3, "m/s") to Quantity[..., Literal["m/s"]], so unit mismatches can fail before your code even runs.
• Zero runtime dependencies. pip install physure pulls in nothing else. NumPy/PyTorch/JAX/pandas support activates automatically when those packages are present.

Quick start

from physure import Q_

d = Q_(10, "km")
t = Q_(2, "hr")
print((d / t).to("m/s"))    # 1.3888888888888888 m/s

# Uncertainty propagates automatically — correlations included
g = Q_(9.8, "m/s^2", uncertainty=0.02)
m = Q_(2.5, "kg", uncertainty=0.001)
E = m * g * Q_(12, "m")
print(E.to("J"))            # (294.0 ± 0.61) J

Or straight from the command line — physure ships a unit-aware calculator and REPL:

$ python -m physure "500 N / 2 m^2 => kPa"
0.25 kPa

Highlights

Units that vanish at compile time

@physure.jit traces your function once, validates every dimension in Rust, then runs on raw tensors — dimensional safety with no per-call cost:

from physure import Q_, jit

@jit
def kinetic_energy(mass, velocity):
    return 0.5 * mass * velocity**2

kinetic_energy(Q_(10.0, "kg"), Q_(5.0, "m/s"))   # 125.0 kg·m²/s²
kinetic_energy(Q_(1.0, "m"), Q_(1.0, "s"))       # raises at trace time: incompatible units

Works with plain floats, NumPy arrays, PyTorch tensors (via __torch_dispatch__ + torch.compile), and JAX (jax.jit).

Uncertainty done properly

Choose the propagation mode globally or per-block:

import physure

physure.propagation_mode("correlated")     # full covariance (default: uncorrelated)

with physure.uncertainty_mode("uncorrelated"):
    ...                                    # scoped override

Backends include Gaussian (first-order), Monte Carlo, and Unscented Transform. Covariance lives in a sparse Rust store, so large lineages stay fast and memory stays flat.

Batteries included, loaded lazily

Pandas ExtensionArray, pydantic validation, SymPy symbolic quantities, unit-aware torch.nn layers, Arrow IPC serialization, plotting helpers, and a physics-as-text DSL (stress = 500 N / 2 m^2) — each activates only when you use it. Cold import stays around 20 ms.

How it compares

If you need a battle-tested converter with a decade of integrations, pint and astropy are excellent. physure is for when you also need uncertainty you can defend and units inside compiled ML code.

Performance

Full methodology and reproduction steps: BENCHMARKS.md.

Installation

pip install physure            # Rust-compiled wheel, no other dependencies
pip install "physure[numpy]"   # + NumPy/SciPy/Numba acceleration
pip install "physure[torch]"   # + PyTorch backend
pip install "physure[jax]"     # + JAX backend
pip install "physure[all]"     # everything

From source

git clone https://github.com/Alexisrx96/physure
cd physure
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # Rust, if needed
maturin develop --release
uv sync --group dev

Architecture

physure/                     # Cargo workspace root
├── physure-core/            # 🦀 Pure Rust physics engine — no FFI deps
│   └── src/                 #    units, quantity, covariance, uncertainty,
│                            #    symbolic, Arrow serialization
└── physure-python/          # 🐍 PyO3 bindings + Python application layer
    └── physure/
        ├── domain/          # Quantity, units, dimensions, uncertainty
        ├── application/     # Q_ factory, unit-system context, startup
        ├── backends/        # NumPy / PyTorch / JAX adapters
        ├── _jit/            # tracing + compile-time dimension checks
        ├── ext/             # grammar DSL, IO, pandas, numba
        └── nn/              # unit-aware neural network layers

The rule: physure-core is the single source of truth. All math lives in Rust; Python is a thin, zero-copy translation layer.

Documentation

• Unit reference — every unit, prefix, and constant
• Tutorials and examples — including a unit-checked PINN notebook
• torch.compile integration

Contributing

Issues and PRs are welcome. The quality bar is enforced in CI: ruff clean, tests green on Python 3.11–3.14 with ≥ 80 % coverage, and zero new SonarQube violations. See CLAUDE.md for the full development guide.

License

MIT — Irvin Torres