1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
``hepunits``: units and constants in the HEP system of units
============================================================
|Scikit-HEP| |PyPI version| |Conda-forge version| |Zenodo DOI|
|GitHub Actions Status: CI| |Code Coverage|
``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.
.. _CLHEP: http://proj-clhep.web.cern.ch/proj-clhep/
.. _SI: http://www.physics.nist.gov/cuu/Units/index.html
Installation
------------
Install ``hepunits`` like any other Python package, typically:
.. code-block:: bash
python -m pip install hepunits
The package is also available on `conda-forge`_, and installable with
.. code-block:: bash
conda install conda-forge::hepunits
.. _conda-forge: https://github.com/conda-forge/hepunits-feedstock
Getting 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:
.. code-block:: pycon
>>> 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.688687
Typical usage of the ``hepunits.units`` module:
.. code-block:: pycon
>>> # 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.0
Fancier 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):
.. code-block:: pycon
>>> 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.0005
Pint 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.
.. code-block:: pycon
>>> 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')>
.. _Pint: https://pint.readthedocs.io/
.. |Scikit-HEP| image:: https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg
:target: https://scikit-hep.org
.. |PyPI version| image:: https://img.shields.io/pypi/v/hepunits.svg
:target: https://pypi.org/project/hepunits/
.. |Conda-forge version| image:: https://img.shields.io/conda/vn/conda-forge/hepunits.svg
:target: https://github.com/conda-forge/hepunits-feedstock
.. |Zenodo DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7244906.svg
:target: https://doi.org/10.5281/zenodo.7244906
.. |GitHub Actions Status: CI| image:: https://github.com/scikit-hep/hepunits/workflows/CI/badge.svg
:target: https://github.com/scikit-hep/hepunits/actions
.. |Code Coverage| image:: https://codecov.io/gh/scikit-hep/hepunits/graph/badge.svg?branch=main
:target: https://codecov.io/gh/scikit-hep/hepunits?branch=main
|
