hepunits collects the most commonly used units and constants in the HEP System of Units, as derived from the basic units originally defined by the CLHEP project, which are not the same as the SI system of units:
Quantity
Name
Unit
Length
millimeter
mm
Time
nanosecond
ns
Energy
Mega electron Volt
MeV
Positron charge
eplus
Temperature
kelvin
K
Amount of substance
mole
mol
Luminous intensity
candela
cd
Plane angle
radian
rad
Solid angle
steradian
sr
It is largely based on the international system of units (SI)
Quantity
Name
Unit
Length
meter
m
Time
second
s
Mass
kilogram
kg
Electric current
ampere
A
Temperature
kelvin
K
Amount of substance
mole
mol
Luminous intensity
candela
cd
but augments it with handy definitions, changing the basic length and time units.
This HEP system of units is in use in many software libraries such as GEANT4 and Gaudi.
Note that many units are now exact, such as the speed of light in vacuum. The package is in agreement with the values in the 2020 Particle Data Group review.
Installation
Install hepunits like any other Python package, typically:
python -m pip install hepunitsThe package is also available on conda-forge, and installable with
conda install conda-forge::hepunitsGetting started
The package contains 2 core modules, constants and units, whose names are self-explanatory. It may be more readable to import quantities explicitly from each of the modules though everything is available from the top-level as from hepunits import ....
The module hepunits.constants contains 2 sorts of constants: physical constants and commonly used constants.
The typical usage is the following:
>>> from hepunits.constants import c_light
>>> from hepunits.units import picosecond, micrometer
>>> tau_Bs = 1.5 * picosecond # a particle lifetime, say the Bs meson's
>>> ctau_Bs = c_light * tau_Bs # ctau of the particle, ~450 microns
>>> print(ctau_Bs) # result in HEP units, so mm
0.449688687
>>> print(ctau_Bs / micrometer) # result in micrometers
449.688687Typical usage of the hepunits.units module:
>>> # add two quantities with length units and get the result in meters
>>> from hepunits import units as u
>>> (1 * u.meter + 5 * u.cm) / u.meter
1.05
>>> # the default result is, of course, in HEP units, so mm
>>> 1 * u.meter + 5 * u.cm
1050.0Fancier usage
When working with data the user should not need to know what units are used in their internal representation (it makes sense, though, and is important, to be consistent throughout the “data storages”!).
These simple rules are enough - exemplified in the code below:
Dimensioned quantities in the “data stores” abide to the HEP system of units.
All definitions of dimensioned quantities are dimensioned by multiplying by the units, as in mass_window = 500 * keV.
All output of dimensioned quantities is converted to the required units by dividing by the units, as in energy_resolution() / GeV.
For the sake of argument, let’s consider below a function returning a dimensioned quantity. the function below stores a dimensioned quantity defined in keV (the actual value is represented in MeV, which is the standard unit) and the caller simply needs to ensure an explicit conversion to the desired unit dividing by it (GeV in the example):
>>> from hepunits.units import keV, MeV, GeV
>>> mass_window = 1 * GeV # define a 1 GeV mass window
>>> def energy_resolution():
... # returns the energy resolution of 500 keV
... return 500.0 * keV # numerical value is 0.5
...
>>> energy_resolution() / GeV # get the energy resolution in GeV
0.0005Pint integration
The package can interoperate with Pint, which provides a more full-featured units and quantities system. Pint is an optional dependency of hepunits. When Pint is installed, hepunits units and constants can be used to create Pint quantities, and Pint quantities can be converted to hepunits units, as shown below.
>>> import pint
>>> import hepunits
>>> from hepunits.pint import to_clhep, from_clhep
>>> ureg = pint.UnitRegistry()
>>> g = 9.8 * ureg.meter / ureg.second**2
>>> g
<Quantity(9.8, 'meter / second ** 2')>
>>> to_clhep(g)
9.800000000000001e-15
>>> from_clhep(hepunits.c_light, ureg.meter / ureg.second)
<Quantity(299792458.0, 'meter / second')>
>>> from_clhep(hepunits.c_light, ureg.fathom / ureg.fortnight)
<Quantity(1.98287528e+14, 'fathom / fortnight')>2 maintainers
Release files for hepunits 2.4.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hepunits-2.4.6.tar.gz | 18.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hepunits-2.4.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 35.1 kB
Release files / hepunits-2.4.6.tar.gz
| Download URL | hepunits-2.4.6.tar.gz |
|---|---|
| Size | 18.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bca6ada937147166d66e9fa152566f2378868d798211cad6990080399560fa34
|
|
BLAKE2b-256 checksum How to use checksums |
e71fc5f7525bf7e5d14d61750f91845f9f9350a8f33f5ac95672cec92f317038
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.
Transparency logRelease files / hepunits-2.4.6-py3-none-any.whl
| Download URL | hepunits-2.4.6-py3-none-any.whl |
|---|---|
| Size | 17.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
089c52c3b84ef67a159b5e9ee9bdd50e1a442e3fd0c101303cc409c1e9011c4d
|
|
BLAKE2b-256 checksum How to use checksums |
85107f9c58d1ec6a0b7f7783fe552f3593f39cda30c2e1d7a9d148ae711e748d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.
Transparency log
