physure 0.2.4

Unit-aware, dimension-correct physics computing — from a shared Rust core

The same dimensional analysis and uncertainty engine, exposed as a standalone DSL (phs), this Python library, a Rust crate, and a JVM package — with zero overhead under torch.compile / jax.jit where it matters.

This is the Python package. physure also ships as a standalone CLI/DSL that needs no Python (PHS), a pure Rust crate, and JVM bindings on Maven Central — see the project README for all four and INSTALL.md for every install path.

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("uncorrelated")   # independent errors (default: correlated)

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.

The default is correlated because the alternative is quietly wrong: with independent errors x - x reports σ·√2 instead of zero, which looks plausible enough to publish. [Settings] propagation_mode in physure.conf sets it for a project, and both the core and PHS read it, so they cannot disagree.

Batteries included, loaded lazily

Pandas ExtensionArray, pydantic validation, SymPy symbolic quantities, unit-aware torch.nn layers, and Arrow IPC serialization each activate only when you use them. 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
cd physure-python
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 (this package)
    └── 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/             # IO, pandas, numba, chemistry, symbolic regression,
        │                    #   AOT compiler, PHS plugin loader
        └── 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