iam-units 2020.4.9

Unit definitions for integrated-assessment research

© 2020 IAM-units authors; licensed under the GNU GPL version 3.

The file definitions.txt gives Pint-compatible definitions of energy, climate, and related units to supplement the SI and other units included in Pint’s default_en.txt. These definitions are used by:

• the IIASA Energy Program MESSAGEix-GLOBIOM integrated assessment model (IAM),

• the Python package pyam for analysis and visualization of integrated-assessment scenarios (see pyam.IamDataFrame.convert_unit() for details)

and may be used for research in integrated assessment, energy systems, transportation, or other, related fields. (Please open a pull request to add your usage to this README!)

Usage

>>> from iam_units import registry

>>> qty = registry('1.2 tce')
>>> qty
1.2 <Unit('tonne_of_coal_equivalent')>

>>> qty.to('GJ')
29.308 <Unit('gigajoule')>

To make the registry from this package the default:

>>> import pint
>>> pint.set_application_registry(registry)

# Now used by default for pint top-level classes and methods
>>> pint.Quantity('1.2 tce')
1.2 <Unit('tonne_of_coal_equivalent')>

Warnings

iam_units overwrites Pint’s default definitions in the following cases:

pint default	iam_units	Note
‘C’ = Coulomb	‘C’ = carbon	See emissions.txt at line 10.
‘kt’ = knot [velocity]	‘kt’ = 1000 metric tons	‘kt’ is commonly used for emissions in the IAM-context.

Technical details

Emissions and GWP

emissions.txt defines some greenhouse gases (GHGs) as Pint base units. Conversion of masses of these GHGs to CO₂ equivalents use selectable global warming potential (GWP) metrics, implemented as Pint contexts in the other files in the same directory. The contexts have names like gwp_<IPCC report>GWP<years>, where <years> is 100 and:

<IPCC report>	Meaning
SAR	Second Assessment Report (1995)
AR4	Fourth Assessment Report (2007)
AR5	Fifth Assessment Report (2014)

To use one of these contexts, give its name as the second argument to the pint.Quantity.to() method:

>>> qty = registry('3.5e3 t N20')
>>> qty
3500 <Unit('metric_ton * nitrous_oxide')>

>>> qty.to('Mt CO2', 'gwp_AR4GWP100')
0.9275 <Unit('carbon_dioxide * megametric_ton')>

# Using a different metric
>>> qty.to('Mt CO2', 'gwp_SARGWP100')
1.085 <Unit('carbon_dioxide * megametric_ton')>

Data sources

The GWP unit definitions are generated using the file metric_conversions.csv. The file is copied from lewisjared/scmdata v0.4, authored by @lewisjared, @swillner, and @znicholls and licensed under BSD-3. The version in scmdata was transcribed from this source (PDF link).

See DEVELOPING.rst for details on updating the definitions.

Tests and development

Use pytest iam_units to check that the definitions can be loaded. Example unit expressions in checks.csv are also checked. See DEVELOPING.rst for further details.