{"id":5246,"library":"hepunits","title":"HEP Units and Constants","description":"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.","status":"active","version":"2.4.4","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/hepunits","tags":["physics","hep","units","constants","scikit-hep","pint"],"install":[{"cmd":"pip install hepunits","lang":"bash","label":"Basic installation"},{"cmd":"pip install hepunits[pint]","lang":"bash","label":"With Pint integration"}],"dependencies":[{"reason":"Optional integration for unit conversions and quantity objects.","package":"pint","optional":true}],"imports":[{"note":"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').","wrong":"from hepunits.units import units","symbol":"units","correct":"from hepunits import units"},{"symbol":"constants","correct":"from hepunits import constants"},{"note":"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.","wrong":"from hepunits.pint import get_unit_registry","symbol":"get_unit_registry","correct":"import hepunits.pint; ureg = hepunits.pint.get_unit_registry()"}],"quickstart":{"code":"from hepunits import units, constants\n\n# Accessing units\nenergy = 100 * units.GeV\nprint(f\"Energy: {energy}\")\n\n# Accessing constants\nspeed_of_light = constants.c_light\nprint(f\"Speed of light: {speed_of_light} in mm/ns\")\n\n# Using Pint integration (requires pip install hepunits[pint])\ntry:\n    import hepunits.pint\n    ureg = hepunits.pint.get_unit_registry()\n    mass = 938.27 * ureg.MeV / ureg.c**2\n    print(f\"Proton mass (Pint): {mass}\")\nexcept ImportError:\n    print(\"Pint integration not installed. Skipping Pint example.\")","lang":"python","description":"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]`."},"warnings":[{"fix":"Ensure your Python environment meets the minimum `requires_python` specified for the `hepunits` version you are using. Upgrade Python if necessary.","message":"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.","severity":"breaking","affected_versions":">=2.3.4"},{"fix":"Install `hepunits` with the `pint` extra: `pip install hepunits[pint]`.","message":"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`.","severity":"gotcha","affected_versions":">=2.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}