Package: iam-units
© 2020–2023IAM-units authors; licensed under theGNU GPL version 3.The filedefinitions.txtgivesPint-compatible definitions of energy, climate, and related units to supplement the SI and other units included in Pint’sdefault_en.txt.
These definitions are used by:the IIASA Energy ProgramMESSAGEix-GLOBIOMintegrated assessment model (IAM),the Python packagepyamfor analysis and visualization of integrated-assessment scenarios (seepyam.IamDataFrame.convert_unit()for details)and may be used for research in integrated assessment, energy systems, transportation, or other, related fields.Please open a GitHubissueorpull requestto:Add more units to definitions.txt.Add your usage of iam-units to this README.Request or contribute additional features.Usageiam_units.registryis apint.UnitRegistryobject with the definitions from definitions.txt loaded:>>>fromiam_unitsimportregistry# Parse an energy unit defined by iam-units>>>qty=registry('1.2 tce')>>>qty1.2<Unit('tonne_of_coal_equivalent')>>>>qty.to('GJ')29.308<Unit('gigajoule')>To make the registry from this package the default:>>>importpint>>>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')>Warningsiam_unitsoverwrites Pint’s default definitions in the following cases:pintdefaultiam_unitsNote‘kt’ = knot [velocity]‘kt’ = 1000 metric tons‘kt’ is commonly used for emissions in the IAM-context.Technical detailsEmissions and GWPThe functionconvert_gwp()converts from mass (or mass-related units) of one specific greenhouse gas (GHG) species to an equivalent quantity of second species, based onglobal warming potential(GWP)metrics.
The supported species are listed inspecies.txtand the variableiam_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 variableiam_units.emissions.METRICS.>>>qty=registry('3.5e3 t').to('Mt')>>>qty3.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)unitsandthe 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 anominal property; see theInternational Vocabulary of Metrology(VIM) used in the SI.
To avoid ambiguity, code handling GHG quantities should also track and output these nominal properties, including:Original species.Species in which GWP-equivalents are expressed (e.g. CO₂ or C)GWP metric used to convert (1) to (2).To aid with this, the functionformat_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')>>>qty927.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'SeePint’s formatting documentationfor values of thespecargument.Data sourcesThe GWP unit definitions are generated from the packageglobalwarmingpotentials.
The version of that package used to generate the definitions is stated in the variableiam_units.emissions.GWP_VERSION.SeeDEVELOPING.rstfor details on updating the definitions.Currencyiam_unitsdefines deflators for:USD (United States dollar) for annual periods from 2000 to 2022 inclusive.EUR (Euro) for the periods 2005, 2010, 2015, and 2020 only.These can be used via pint-compatible unit expressions likeUSD_2019that combine theISO 4217alphabetic code with the period.To enable conversions betweendifferentcurrencies, use the functionconfigure_currency():>>>configure_currency(method="EXC",period="2005")# Then, for example>>>qty=registry("42.1 USD_2020")>>>qty42.1<Unit('USD_2020')>>>>qty.to("EUR_2005")26.022132012144635<Unit('EUR_2005')>Currentlyiam_unitsonly supports:period-average exchange rates for annual periods (method=”EXC”);period=”2005”; andthe two currencies mentioned above.Contributions that extend the supported currencies, methods, and periods are welcome.Tests and developmentUsepytest iam_units--verboseto run the test suite included in the submoduleiam_units.test_all.
SeeDEVELOPING.rstfor further details.