Package: hepunits
hepunitscollects the most commonly used units and constants in the
HEP System of Units, as derived from the basic units originally defined by theCLHEPproject,
which arenotthe same as the SI system of units:QuantityNameUnitLengthmillimetermmTimenanosecondnsEnergyMega electron VoltMeVPositron chargeeplusTemperaturekelvinKAmount of substancemolemolLuminous intensitycandelacdPlane angleradianradSolid anglesteradiansrIt is largely based on the international system of units (SI)QuantityNameUnitLengthmetermTimesecondsMasskilogramkgElectric currentampereATemperaturekelvinKAmount of substancemolemolLuminous intensitycandelacdbut 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 nowexact, such as the speed of light in vacuum.
The package is in agreement with the values in the 2020 Particle Data Group review.InstallationInstallhepunitslike any other Python package, typically:python-mpipinstallhepunitsThe package is also available onconda-forge, and installable withcondainstall-cconda-forgehepunitsGetting startedThe package contains 2 modules,constantsandunits,
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 asfrom hepunits import ....The modulehepunits.constantscontains 2 sorts of constants:
physical constants and commonly used constants.The typical usage is the following:>>>fromhepunits.constantsimportc_light>>>fromhepunits.unitsimportpicosecond,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>>>printctau_Bs# result in HEP units, so mm0.449688687>>>printctau_Bs/micrometer# result in micrometers449.688687Typical usage of thehepunits.unitsmodule:>>># add two quantities with length units and get the result in meters>>>fromhepunitsimportunitsasu>>>(1*u.meter+5*u.cm)/u.meter1.05>>># the default result is, of course, in HEP units, so mm>>>1*u.meter+5*u.cm1050.0Fancier usageWhen working with data the user should not need to know what units are used in their
internal representation (it makes sense, though, andis 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 inmass_window = 500 * keV.All output of dimensioned quantities is converted to the required units
by dividing by the units, as inenergy_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):>>>fromhepunits.unitsimportkeV,MeV,GeV>>>mass_window=1*GeV# define a 1 GeV mass window>>>defenergy_resolution():...# returns the energy resolution of 500 keV...return500.*keV# numerical value is 0.5...>>>energy_resolution()/GeV# get the energy resolution in GeV0.0005