Repository: IAMconsortium/units (language: python)

Issue:
Add defs based on MIT Energy Club fact sheet
I have this 2007 (!) fact sheet produced by a former member of the MIT Energy Club: [UnitsAndConversions.pdf](https://github.com/IAMconsortium/units/files/5781143/UnitsAndConversions.pdf)

This suggests several possible conversions that could be incorporated in `iam-units` to make it more broadly useful:

- Density: conversion from `[volume]` to `[mass]` and vice versa. Like GWP, this would require a context and substance identifier.
- Energy content, e.g. Lower Heating Value (LHV): conversion from `[mass]` to `[energy]` and vice versa.
  - With density, this also allows conversion from `[volume]` to `[energy]`.
  - Note that `pint` already includes some definitions like `tonne_of_oil_equivalent = 1e10 * international_calorie = toe`; these "_equivalent" would be duplicated somewhat by the new context.
- Emissions factors, prices: these are technology- and location- specific, so probably not appropriate for this package.
- The other conversions on the fact sheet should be supported by pint defaults and thus by `iam_units.registry`, but could still be added to the test suite. They could also be added in a user-friendly format like a Jupyter notebook/Binder.


Discussion / hints:
@khaeru I'm adding the conversion to `litres of gasoline-equivalent` (`Lge`) in #27.

Fix patch:
diff --git a/DEVELOPING.rst b/DEVELOPING.rst
index 6a6adc8..559b872 100644
--- a/DEVELOPING.rst
+++ b/DEVELOPING.rst
@@ -18,19 +18,20 @@ Thus:
 Releasing
 =========
 
+Before releasing, check https://github.com/IAMconsortium/units/actions/workflows/test.yaml to ensure that the push and scheduled builds are passing.
+Address any failures before releasing.
 
-Releasing
-*********
+1. Create a new branch::
 
-1. Before releasing, check https://github.com/IAMconsortium/units/actions/workflows/test.yaml to ensure that the push and scheduled builds are passing.
-   Address any failures before releasing.
+    $ git checkout -b release/vYYYY.MM.DD
 
-2. Tag the release candidate version, i.e. with a ``rcN`` suffix, and push::
+2. Tag the release candidate (RC) version, i.e. with a ``rcN`` suffix, and push::
 
     $ git tag v2021.3.22rc1
-    $ git push --tags origin main
+    $ git push --tags origin release/vYYYY.MM.DD
 
-3. Check:
+3. Open a PR with the title “Release vYYYY.MM.DD” using this branch.
+   Check:
 
    - at https://github.com/IAMconsortium/units/actions/workflows/publish.yaml that the workflow completes: the package builds successfully and is published to TestPyPI.
    - at https://test.pypi.org/project/iam-units/ that:
@@ -41,16 +42,20 @@ Releasing
    Address any warnings or errors that appear.
    If needed, make a new commit and go back to step (2), incrementing the rc number.
 
-4. (optional) Tag the release itself and push::
+4. Merge the PR using the ‘rebase and merge’ method.
+
+5. (optional) Switch back to the ``main`` branch, tag the release itself (*without* an RC number) and push::
 
+    $ git checkout main
+    $ git pull --fast-forward
     $ git tag v2021.3.22
     $ git push --tags origin main
 
-   This step (but *not* step (2)) can also be performed directly on GitHub; see (5), next.
+   This step (but *not* step (2)) can also be performed directly on GitHub; see (6), next.
 
-5. Visit https://github.com/IAMconsortium/units/releases and mark the new release: either using the pushed tag from (4), or by creating the tag and release simultaneously.
+6. Visit https://github.com/IAMconsortium/units/releases and mark the new release: either using the pushed tag from (5), or by creating the tag and release simultaneously.
 
-6. Check at https://github.com/IAMconsortium/units/actions/workflows/publish.yaml and https://pypi.org/project/iam-units/ that the distributions are published.
+7. Check at https://github.com/IAMconsortium/units/actions/workflows/publish.yaml and https://pypi.org/project/iam-units/ that the distributions are published.
 
 
 Generated data files for GWP contexts
diff --git a/iam_units/data/definitions.txt b/iam_units/data/definitions.txt
index 0bd91c5..8d7b42d 100644
--- a/iam_units/data/definitions.txt
+++ b/iam_units/data/definitions.txt
@@ -1,17 +1,23 @@
 # Energy
 
 # Energy content of coal by mass
-# Source: https://cngcenter.com/wp-content/uploads/2013/09/UnitsAndConversions.pdf
+# Source: https://cngcenter.com/wp-content/uploads/2013/09/UnitsAndConversions.pdf (1)
 #
 # - tonne_of_oil_equivalent is already defined in pint's default_en.txt
 
 tonne_of_coal_equivalent = 29.308 GJ = tce
 
 # Energy content of gasoline by volume
-# Source: https://theicct.org/sites/default/files/publications/GFEI_WP19_Final_V3_Web.pdf
+# Source: https://theicct.org/sites/default/files/publications/GFEI_WP19_Final_V3_Web.pdf (2)
 # page 24, footnote 23.
 
 litre_of_gasoline_equivalent = 33.5 * MJ = Lge = lge
+# litre_of_gasoline_equivalent = 32.1 * MJ = Lge = lge  # from source (1)
+
+# Energy content of diesel by volume (lower heating value)
+# Source: (1)
+
+litre_of_diesel_equivalent = 35.8 * MJ = Lde = lde
 
 # Short form of Watt-annum
 Wa = watt * year
@@ -61,10 +67,9 @@ USD_2010 = USD_2005 * 83.426 / 91.718
 
 vehicle = [vehicle] = v
 passenger = [passenger] = p = pass
-tonne_freight = [tonne_freight] = tfr = tonnef
 vkm = vehicle * kilometer
 pkm = passenger * kilometer
-tkm = tonne_freight * kilometer
+tkm = tonne * kilometer
 @alias vkm = vkt = v km
 @alias pkm = pkt = p km
 @alias tkm = tkt = t km


Test patch:
diff --git a/iam_units/test_all.py b/iam_units/test_all.py
index 2081b36..e9a8ff9 100644
--- a/iam_units/test_all.py
+++ b/iam_units/test_all.py
@@ -21,6 +21,11 @@
     ("tce", energy, True),
     ("toe", energy, False),
     ("EUR_2005", UnitsContainer({"[currency]": 1}), True),
+    (
+        "billion tkm/yr",
+        UnitsContainer({"[length]": 1, "[mass]": 1, "[time]": -1}),
+        True,
+    ),
 ]