iam-units 2026.8.5

Environment variables

The package responds to two optional environment variables:

IAM_UNITS_CACHE

iam-units caches the created registry using pint’s caching mechanism. If set, this variable must contain the path of a directory for the cache. If not set, a default path is used.

IAM_UNITS_CURRENCY

If set, this variable must be a string like “EXC,2005”. The two parts, separated by a comma (“,”), are separated and passed as the method and period arguments to configure_currency() (see below) when iam-units is imported. If not set, the function is not called.

Emissions and GWP

The function convert_gwp() converts 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 the time period over which heat absorption was assessed. The supported metrics are listed in the variable iam_units.emissions.METRICS.

>>> 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.

Currency

iam_units defines deflators for:

• USD (United States dollar) for annual periods from 2000 to 2022 inclusive.

• EUR (Euro) for the periods 2005, 2010, 2015, 2020, and 2024 only.

These can be used via pint-compatible unit expressions like USD_2019 that combine the ISO 4217 alphabetic code with the time period.

To enable conversions between different currencies, use the function configure_currency():

>>> configure_currency(method="EXC", period="2005")

# Then, for example
>>> qty = registry("42.1 USD_2020")
>>> qty
42.1 <Unit('USD_2020')>

>>> qty.to("EUR_2005")
26.022132012144635 <Unit('EUR_2005')>

Calling configure_currency() again with the same method and currency/period pair on the same registry is a no-op. Calling it with a different method for an already configured pair raises ValueError rather than silently reusing the first definition.

Currently iam_units supports:

• annual OECD Table 4 exchange-rate / PPP methods EXC, EXCE, PPPGDP, PPPPRC, and PPPP41;

• EUR for the periods 2005, 2010, 2015, 2020, and 2024; and

• USD as the base currency for those conversions.

Up to v2025.9.12, configure_currency("EXC", 2005) was called automatically.

Contributions that extend the supported currencies, methods, and periods are welcome.