Metadata-Version: 2.1
Name: hepunits
Version: 2.1.1
Summary: Units and constants in the HEP system of units
Home-page: https://github.com/scikit-hep/hepunits
Author: Eduardo Rodrigues
Author-email: eduardo.rodrigues@cern.ch
Maintainer: Eduardo Rodrigues
Maintainer-email: eduardo.rodrigues@cern.ch
License: BSD-3-Clause
Description: ``hepunits``: units and constants in the HEP system of units
        ============================================================
        
        .. image:: https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg
           :alt: Scikit-HEP project package
           :target: https://scikit-hep.org
        
        .. image:: https://img.shields.io/pypi/v/hepunits.svg
           :alt: PyPI
           :target: https://pypi.python.org/pypi/hepunits
        
        .. image:: https://img.shields.io/conda/vn/conda-forge/hepunits.svg
           :alt: conda-forge
           :target: https://anaconda.org/conda-forge/hepunits
        
        .. image:: https://github.com/scikit-hep/hepunits/workflows/CI/badge.svg
           :alt: Actions Status
           :target: https://github.com/scikit-hep/hepunits/actions
        
        .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
           :alt: Code style: black
           :target: https://github.com/psf/black
        
        
        ``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 -c conda-forge hepunits
        
        .. _conda-forge: https://github.com/conda-forge/hepunits-feedstock
        
        
        Getting started
        ---------------
        
        The package contains 2 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:: python
        
            >>> 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:: python
        
            >>> # 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, 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:: python
        
            >>> 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 100 keV
            ...    return 500. * keV
            ...
            >>> energy_resolution() / GeV # get the energy resolution in GeV
            0.0005
        
Platform: UNKNOWN
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7
Provides-Extra: test
Provides-Extra: dev
Provides-Extra: all
