iam-units 2020.4.12

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 GitHub issue or pull request to:

• Add more units to definitions.txt.

• Add your usage of iam-units to this README.

• Request or contribute additional features.

Usage

iam_units.registry is a pint.UnitRegistry object with the definitions from definitions.txt loaded:

>>> from iam_units import registry

# Parse an energy unit defined by iam-units
>>> 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
‘kt’ = knot [velocity]	‘kt’ = 1000 metric tons	‘kt’ is commonly used for emissions in the IAM-context.

Technical details

Emissions and GWP

The function convert_gwp() converts from from mass (or mass-related units) of one specific greenhouse gas (GHG) species to an equivalent quantity of second species, based on global warming potential (GWP) metrics. The supported species are listed in species.txt and the variable iam_units.emissions.SPECIES. The metrics have names like <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)

>>> qty = registry('3.5e3 t').to('Mt')
>>> qty
3.5 <Unit('megametric_ton')>

# Convert from mass of N2O to GWP-equivalent mass of CO2
>>> convert_gwp('AR4GWP100', qty, 'N2O', 'CO2')
0.9275 <Unit('megametric_ton')>

# Using a different metric
>>> convert_gwp('AR5GWP100', qty, 'N2O', 'CO2')
1.085 <Unit('megametric_ton')>

The function also accepts input with the commonly-used combination of mass (or related) units and the identity of a particular GHG species:

# Expression combining magnitude, units, *and* GHG species
>>> qty = '3.5 Mt N2O / year'

# Input species is determined from *qty*
>>> convert_gwp('AR5GWP100', qty, 'CO2')
1.085 <Unit('megametric_ton / year')>

Strictly, the original species is not a unit but a nominal property; see the International Vocabulary of Metrology (VIM) used in the SI. To avoid ambiguity, code handling GHG quantities should also track and output these nominal properties, including:

1. Original species.

2. Species in which GWP-equivalents are expressed (e.g. CO₂ or C)

3. GWP metric used to convert (1) to (2).

To aid with this, the function format_mass() is provided to re-assemble strings that include the GHG species or other information:

# Perform a conversion
>>> qty = convert_gwp('AR5GWP100', '3.5 Mt N2O / year', 'CO2e')
>>> qty
927.5 <Unit('megametric_ton / year')>

# Format a string with species and metric info after the mass units of *qty*
>>> format_mass(qty, 'CO₂-e (AR5)', spec=':~')
'Mt CO₂-e (AR5) / a'

See Pint’s formatting documentation for values of the spec argument.

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 --verbose to run the test suite included in the submodule iam_units.test_all. See DEVELOPING.rst for further details.