..
    SPDX-FileCopyrightText: 2022 Tanguy Fardet
    SPDX-License-Identifier: CC-BY-SA-4.0
    docs/modules/units.rst

============
Units module
============

This module contains the definitions of the units, as well as the unit-registry
object ``ureg``.


Main units
==========

* general mass units (``g``, ``t`` and their association with prefixes like
  ``kg``, ``Mt``, etc)
* length and volume units like ``m``, ``L``, ``m**3``
* time units (``year``, ``month``, ``week``, ``day``)

In addition, the following units are defined in ``unit_definitions.txt``.

.. literalinclude:: ../../orgmatt/unit_definitions.txt
    :lines: 8-47

These units are then combined to ``g`` and ``t`` so you can use directly
``gN``, ``gP``, or ``tCO2e``.

Any unit that is not directly defined here can be acces via the ``ureg`` object.

Please see the Pint_ documentation for more details on how to use units.


Contexts
========

In addition to the units, the ``unit_definitions.txt`` file defines contexts
that are used to convert between different units.

The following contexts are defined:

* "elements", to convert a mass of molecules to the mass of one of its basic
  components (e.g. amount of carbon in :math:`\text{CO}_2` or
  :math:`\text{CH}_4`),
* "AR4GWP100" (or just "GWP", global warming potential), to convert greenhouse
  gases to :math:`\text{CO}_2\text{e}` over a 100 year period,
* "eutrophication", to convert phosphorus-related molecules to
  :math:`\text{PO}_4^{3-}\text{e}` (phosphate equivalents),
* "acidification", to convert sulfur-related molecule to
  :math:`\text{SO}_2\text{e}`.

For each of them, you can convert a quantity `q` to another unit `u` under
context `c` via ``q.to(u, c)``.

.. literalinclude:: ../../orgmatt/unit_definitions.txt
    :lines: 50-


.. _Pint: https://pint.readthedocs.io