PyUnitWizard

Coverage: PyUnitWizard Python tests, uploaded by the routine Linux/Python 3.14 CI lane. The badge reflects the last uploaded report, which may lag later direct or skip-CI commits; it does not certify a full matrix or scientific correctness.

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 0.26.0 and later support Linux and macOS Apple Silicon (arm64) on Python 3.11–3.14. Intel-based macOS (x86_64) is outside the supported matrix. A concrete user need may reopen this decision under MolSysSuite #59. Earlier releases were validated only through Python 3.13. Windows packages and runtime support are intentionally deferred until a concrete ecosystem need justifies adding and maintaining that platform matrix.

Install a published release from the uibcdf Conda channel:

conda install -c uibcdf 'pyunitwizard>=0.26.0'

PyUnitWizard and its required SMonitor and DepDigest versions are not currently distributed on the public PyPI index. A source installation needs those dependencies from Conda first; see the installation guide.

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
• openff.units (optional; Python 3.12–3.14/Pint <0.26)
• 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, openff.units.

Objects supported in practice:

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

String parser support:

• parser-capable: pint, astropy.units, openff.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.

Optional CF unit tools and verified HDF5 snapshots use actual UDUNITS and h5py with explicit unit and temperature contracts. The qrec-hdf5/0.1 binding is provisional and preserves existing QuantityRecord seals.