PyUnitWizard

A Python Units Wizard that streamlines work with physical quantities.

Overview

PyUnitWizard is a compatibility layer for working with physical quantities across multiple unit libraries through one consistent API.

It is designed for scientific Python projects that need to:

• accept heterogeneous quantity inputs,
• convert and compare quantities deterministically,
• keep stable unit contracts at API boundaries.

Why adopt PyUnitWizard

• One public API for quantity construction, conversion, validation, and normalization.
• Easier interoperability between libraries that use different unit backends.
• Explicit dimensional checks and compatibility checks in integration code.
• Stable unit behavior that is easier to test and document.

Installation

PyUnitWizard currently supports Linux and macOS on Python 3.11, 3.12, and 3.13. Windows packages and runtime support are intentionally deferred until a concrete ecosystem need justifies adding and maintaining that platform matrix.

Recommended:

conda install -c uibcdf pyunitwizard

Alternative:

pip install pyunitwizard

Quick start

import pyunitwizard as puw

puw.configure.reset()
puw.configure.load_library(["pint"])
puw.configure.set_default_form("pint")
puw.configure.set_default_parser("pint")
puw.configure.set_standard_units(["nm", "ps", "kcal", "mole"])

distance = puw.quantity(1.0, "nanometer")
distance_angstrom = puw.convert(distance, to_unit="angstrom")

print(puw.to_string(distance_angstrom))
print(puw.are_compatible(distance, distance_angstrom))

Core capabilities

• Quantity and unit construction: quantity, unit
• Conversion and formatting: convert, to_string
• Validation and comparison: check, has_unit, are_compatible, are_close, are_equal
• Introspection and extraction: get_form, get_dimensionality, get_value, get_unit
• Standardization: standardize, get_standard_units
• Runtime configuration: pyunitwizard.configure.*

Backend support

PyUnitWizard supports interoperation with:

• pint
• openmm.unit
• unyt
• astropy.units
• physipy
• quantities
• string form

Runtime loading of available backends/parsers is handled via configuration. Dependency policy:

• hard runtime dependency: pint;
• optional runtime dependencies: openmm.unit, unyt, astropy.units, physipy, quantities.

Objects supported in practice:

• quantities from all listed backends;
• unit objects from backends that expose distinct unit types (pint, openmm.unit, unyt, astropy.units);
• unit-like scalar objects for backends where unit/quantity share the same type (physipy, quantities).

String parser support:

• parser-capable: pint, astropy.units;
• explicit parser-not-supported errors: openmm.unit, unyt, physipy, quantities.

Matplotlib transparent integration:

• Keep using standard matplotlib imports.
• Enable unit-aware plotting for mixed backend quantities with:

import pyunitwizard as puw
puw.utils.matplotlib.setup_matplotlib()

NumPy transparent integration:

• Keep using standard numpy imports.
• Enable quantity-aware dispatch for common operations (mean, sum, std, var, dot, linalg.norm, trapezoid) with:

import numpy as np
import pyunitwizard as puw

puw.utils.numpy.setup_numpy(enable=True)
result = np.mean(puw.quantity([1.0, 2.0, 3.0], "meter"))

Explicit NumPy wrappers are also available in puw.utils.numpy (mean, sum, std, var, dot, linalg_norm, trapz).

Pandas interoperability helpers:

• Keep using standard pandas imports.
• Optional transparent accessor for DataFrames: df.puw.*.
• Metadata-preserving table helpers are available: concat, merge, set_units_map, sync_units_map.

import pyunitwizard as puw

puw.utils.pandas.setup_pandas(enable=True)
df = puw.utils.pandas.dataframe_from_quantities(
    {"length": puw.quantity([1.0, 2.0], "nanometer")}
)
q = df.puw.get_quantity("length")

Matplotlib coverage highlights:

• transparent bridge for supported quantity backends;
• mixed-backend plotting on compatible axes;
• advanced layout scenarios (shared axes, twin axes, multi-series overlays) covered by tests.

Diagnostics (SMonitor)

PyUnitWizard integrates with SMonitor for structured diagnostics. Runtime SMonitor configuration is loaded from:

• pyunitwizard/_smonitor.py
• pyunitwizard/_private/smonitor/catalog.py
• pyunitwizard/_private/smonitor/meta.py

Documentation

• Website: https://www.uibcdf.org/pyunitwizard
• User guide: docs/content/user/
• Developer guide: docs/content/developer/
• API reference: docs/api/
• Consolidation roadmap: devguide/roadmap.md

Development

Run tests:

pytest -q

Build docs:

make -C docs html

Status

PyUnitWizard is in pre-1.0 stabilization. The 0.19.x line is treated as a historical checkpoint, 0.20.x as interoperability expansion, 0.21.x as the completed RC consolidation window, and 0.22.x/0.23.x as subsequent performance and API hardening before the stable 1.0.0 tag. Current release planning and milestones are tracked in devguide/.

PyUnitWizard aims to become a units interoperability layer for Scientific Python.

Ecosystem

PyUnitWizard is part of the current UIBCDF interoperability stack:

• ArgDigest
• DepDigest
• SMonitor

License

MIT. See LICENSE.