HEP Units and Constants

2.4.4 · active · verified Mon Apr 13

hepunits is a Python library that provides a comprehensive set of units and physical constants specifically tailored for the High Energy Physics (HEP) system of units. It simplifies working with quantities in HEP research by offering well-defined units like MeV and constants such as the speed of light. The library is actively maintained, with regular updates for Python version compatibility and minor feature enhancements, currently at version 2.4.4.

Warnings

breaking Python version support is frequently updated. For example, Python 3.8 support was removed in v2.4.3, and Python 3.7 support was removed in v2.3.4. Always check `requires_python` in `pyproject.toml` or `setup.py` for your target version.
Fix: Ensure your Python environment meets the minimum `requires_python` specified for the `hepunits` version you are using. Upgrade Python if necessary.
gotcha The `Pint` integration for unit-aware quantity objects is optional and requires `pip install hepunits[pint]`. If you attempt to use `hepunits.pint` functionality without installing the extra dependency, you will encounter an `ImportError`.
Fix: Install `hepunits` with the `pint` extra: `pip install hepunits[pint]`.
gotcha hepunits is based on the High Energy Physics (HEP) system of units, where common units like energy are in MeV and length in mm, and constants like the speed of light are defined accordingly (e.g., `c_light` is in mm/ns). This differs from standard SI, which can lead to unexpected results if not accounted for.
Fix: Always be mindful of the specific unit system (HEP) that hepunits employs. Convert to or from other unit systems explicitly when interacting with external libraries or data not using HEP units.
gotcha Unit and constant objects (e.g., `units.GeV`, `constants.c_light`) are not themselves `Pint` Quantities unless you explicitly use the `hepunits.pint` integration and its unit registry. Basic unit access provides bare numeric values when multiplied or divided.
Fix: If you require unit-aware arithmetic and type safety, use the `hepunits.pint` integration by importing the `hepunits.pint` module and obtaining its unit registry.

Install

pip install hepunits Basic installation
pip install hepunits[pint] With Pint integration

Imports

units
```
from hepunits import units
```
Importing 'units' directly from the top-level package is the idiomatic way to access unit definitions. The submodule 'hepunits.units' is implicitly exposed via the top-level 'units' object, so 'from hepunits.units import units' creates a redundant nesting (e.g., 'units.units.GeV').
constants
```
from hepunits import constants
```
get_unit_registry
```
import hepunits.pint; ureg = hepunits.pint.get_unit_registry()
```
While 'from hepunits.pint import get_unit_registry' technically works, the recommended pattern for using the Pint integration is to import the 'hepunits.pint' module directly to keep it clear that Pint functionality is being accessed through the hepunits wrapper.

Quickstart

This example demonstrates how to import and use units and physical constants. It also shows the optional integration with the Pint library for more advanced quantity handling, which requires installing `hepunits[pint]`.

from hepunits import units, constants

# Accessing units
energy = 100 * units.GeV
print(f"Energy: {energy}")

# Accessing constants
speed_of_light = constants.c_light
print(f"Speed of light: {speed_of_light} in mm/ns")

# Using Pint integration (requires pip install hepunits[pint])
try:
    import hepunits.pint
    ureg = hepunits.pint.get_unit_registry()
    mass = 938.27 * ureg.MeV / ureg.c**2
    print(f"Proton mass (Pint): {mass}")
except ImportError:
    print("Pint integration not installed. Skipping Pint example.")

view raw JSON →