├── iam_units ├── py.typed ├── data │ ├── emissions │ │ ├── metrics.txt │ │ ├── emissions.txt │ │ ├── SARGWP100.txt │ │ ├── species.txt │ │ ├── AR4GWP100.txt │ │ ├── AR5CCFGWP100.txt │ │ ├── AR6GTP100.txt │ │ ├── AR6GWP500.txt │ │ ├── AR5GWP100.txt │ │ ├── AR6GWP100.txt │ │ └── AR6GWP20.txt │ └── definitions.txt ├── emissions.py ├── currency.py ├── update.py ├── __init__.py └── test_all.py ├── .gitignore ├── AUTHORS ├── .pre-commit-config.yaml ├── .github ├── workflows │ ├── publish.yaml │ └── test.yaml └── dependabot.yml ├── conftest.py ├── pyproject.toml ├── DEVELOPING.rst ├── README.rst └── LICENSE /iam_units/py.typed: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Python 2 | __pycache__ 3 | .benchmarks 4 | .dmypy* 5 | .mypy_cache 6 | .pytest_cache 7 | .ruff_cache 8 | *.egg-info 9 | *.eggs 10 | build 11 | dist 12 | 13 | # Editors 14 | .idea/* 15 | .vscode 16 | -------------------------------------------------------------------------------- /AUTHORS: -------------------------------------------------------------------------------- 1 | Paul Natsuo Kishimoto (@khaeru, IIASA) 2 | Daniel Huppmann (@danielhuppmann, IIASA) 3 | Francesco Lovat (@francescolovat, IIASA) 4 | Philip Hackstock (@phackstock, IIASA) 5 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | repos: 2 | - repo: https://github.com/pre-commit/mirrors-mypy 3 | rev: v1.18.1 4 | hooks: 5 | - id: mypy 6 | pass_filenames: false 7 | additional_dependencies: 8 | - numpy 9 | - pint 10 | - pytest 11 | - repo: https://github.com/astral-sh/ruff-pre-commit 12 | rev: v0.13.0 13 | hooks: 14 | - id: ruff-check 15 | - id: ruff-format 16 | args: [ --check ] 17 | -------------------------------------------------------------------------------- /iam_units/data/emissions/metrics.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | 6 | # Define contexts for each set of metrics 7 | 8 | @import SARGWP100.txt 9 | @import AR4GWP100.txt 10 | @import AR5GWP100.txt 11 | @import AR5CCFGWP100.txt 12 | @import AR6GWP100.txt 13 | @import AR6GWP20.txt 14 | @import AR6GWP500.txt 15 | @import AR6GTP100.txt 16 | -------------------------------------------------------------------------------- /.github/workflows/publish.yaml: -------------------------------------------------------------------------------- 1 | name: Build package / publish 2 | 3 | on: 4 | push: 5 | branches: [ main ] 6 | tags: [ "v*" ] 7 | release: 8 | types: [ published ] 9 | # Check that package can be built even on PRs 10 | pull_request: 11 | branches: [ main ] 12 | 13 | 14 | jobs: 15 | publish: 16 | uses: iiasa/actions/.github/workflows/publish.yaml@main 17 | secrets: 18 | PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} 19 | -------------------------------------------------------------------------------- /conftest.py: -------------------------------------------------------------------------------- 1 | import os 2 | 3 | 4 | def pytest_sessionstart(session) -> None: 5 | """Set environment variables for test session.""" 6 | 7 | # Use a pytest temporary directory for cache, instead of the user's cache 8 | cache_path = session.config._tmp_path_factory.mktemp("pint-cache", numbered=False) 9 | os.environ.setdefault("IAM_UNITS_CACHE", str(cache_path)) 10 | 11 | # Preserve behaviour expected by test_units[EUR_2005--] 12 | os.environ.setdefault("IAM_UNITS_CURRENCY", "EXC,2005") 13 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | # Only update major versions 5 | ignore: 6 | - dependency-name: "*" 7 | update-types: 8 | - "version-update:semver-minor" 9 | - "version-update:semver-patch" 10 | # Below config mirrors the example at 11 | # https://github.com/dependabot/dependabot-core/blob/main/.github/dependabot.yml 12 | directory: "/" 13 | schedule: 14 | interval: "weekly" 15 | day: "sunday" 16 | time: "16:00" 17 | groups: 18 | all-actions: 19 | patterns: [ "*" ] 20 | -------------------------------------------------------------------------------- /iam_units/data/emissions/emissions.txt: -------------------------------------------------------------------------------- 1 | # Dummy base unit used for GWP conversions of [mass] -> [_GWP] -> [mass]. 2 | # This unit has no physical meaning and should not be used on its own. 3 | 4 | _gwp = [_GWP] 5 | 6 | # The reference species, CO2, has a conversion factor of 1. 7 | 8 | a_CO2 = 1.0 9 | 10 | # Define: 11 | # - Equivalents, e.g. a_CO2e = a_CO2. 12 | # - Conversion factors for each species, with NaN values. pint requires 13 | # that this is done before setting context-specific values. 14 | 15 | @import species.txt 16 | 17 | # Define contexts for each set of metrics 18 | 19 | @import metrics.txt 20 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["build", "setuptools-scm"] 3 | 4 | [project] 5 | dynamic = ["version"] 6 | name = "iam_units" 7 | description = "Unit definitions for integrated-assessment research" 8 | authors = [{ name = "IAM-units contributors" }] 9 | maintainers = [ 10 | { name = "Paul Natsuo Kishimoto", email = "mail@paul.kishimoto.name" }, 11 | ] 12 | license = { file = "LICENSE" } 13 | readme = "README.rst" 14 | classifiers = [ 15 | "Intended Audience :: Developers", 16 | "Intended Audience :: Science/Research", 17 | "Operating System :: OS Independent", 18 | "Programming Language :: Python", 19 | "Programming Language :: Python :: 3", 20 | "Programming Language :: Python :: 3.10", 21 | "Programming Language :: Python :: 3.11", 22 | "Programming Language :: Python :: 3.12", 23 | "Programming Language :: Python :: 3.13", 24 | "Programming Language :: Python :: 3.14", 25 | "Topic :: Scientific/Engineering", 26 | "Topic :: Scientific/Engineering :: Information Analysis", 27 | ] 28 | requires-python = ">= 3.10" 29 | dependencies = ["pint >= 0.24.4"] 30 | 31 | [project.urls] 32 | homepage = "https://github.com/IAMconsortium/units" 33 | 34 | [project.optional-dependencies] 35 | update = ["globalwarmingpotentials"] 36 | tests = ["iam_units[update]", "numpy", "pandas", "pytest", "pytest-cov"] 37 | 38 | [tool.mypy] 39 | files = ["iam_units"] 40 | warn_unused_ignores = true 41 | 42 | [[tool.mypy.overrides]] 43 | module = ["globalwarmingpotentials"] 44 | ignore_missing_imports = true 45 | 46 | [tool.ruff.lint] 47 | mccabe.max-complexity = 7 48 | select = ["C9", "E", "F", "I", "W"] 49 | 50 | [tool.setuptools.packages] 51 | find = {} 52 | 53 | [tool.setuptools_scm] 54 | -------------------------------------------------------------------------------- /iam_units/data/emissions/SARGWP100.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) SARGWP100 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C2F6 = 9200.0 17 | a_C3F8 = 7000.0 18 | a_C4F10 = 7000.0 19 | a_C5F12 = 7500.0 20 | a_C6F14 = 7400.0 21 | a_CCl4 = 1400.0 22 | a_CF4 = 6500.0 23 | a_CFC11 = 3800.0 24 | a_CFC113 = 4800.0 25 | a_CFC12 = 8100.0 26 | a_CH2Cl2 = 9.0 27 | a_CH3CCl3 = 100.0 28 | a_CH4 = 21.0 29 | a_CHCl3 = 4.0 30 | a_HCFC123 = 90.0 31 | a_HCFC124 = 470.0 32 | a_HCFC141b = 600.0 33 | a_HCFC142b = 1800.0 34 | a_HCFC22 = 1500.0 35 | a_HFC125 = 2800.0 36 | a_HFC134 = 1000.0 37 | a_HFC134a = 1300.0 38 | a_HFC143 = 300.0 39 | a_HFC143a = 3800.0 40 | a_HFC152a = 140.0 41 | a_HFC227ea = 2900.0 42 | a_HFC23 = 11700.0 43 | a_HFC236fa = 6300.0 44 | a_HFC245ca = 560.0 45 | a_HFC32 = 650.0 46 | a_HFC41 = 150.0 47 | a_HFC4310mee = 1300.0 48 | a_Halon1301 = 5400.0 49 | a_N2O = 310.0 50 | a_SF6 = 23900.0 51 | a_cC4F8 = 8700.0 52 | @end 53 | -------------------------------------------------------------------------------- /iam_units/data/emissions/species.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | a_CO2_eq = a_CO2 6 | a_CO2e = a_CO2 7 | a_CO2eq = a_CO2 8 | a_C = 44. / 12 * a_CO2 9 | a_Ce = 44. / 12 * a_CO2 10 | a_C10F18 = NaN 11 | a_C2F6 = NaN 12 | a_C3F8 = NaN 13 | a_C4F10 = NaN 14 | a_C5F12 = NaN 15 | a_C6F14 = NaN 16 | a_C7F16 = NaN 17 | a_C8F18 = NaN 18 | a_CCl4 = NaN 19 | a_CF4 = NaN 20 | a_CFC11 = NaN 21 | a_CFC113 = NaN 22 | a_CFC114 = NaN 23 | a_CFC115 = NaN 24 | a_CFC12 = NaN 25 | a_CFC13 = NaN 26 | a_CH2Cl2 = NaN 27 | a_CH3Br = NaN 28 | a_CH3CCl3 = NaN 29 | a_CH3Cl = NaN 30 | a_CH4 = NaN 31 | a_CHCl3 = NaN 32 | a_HCFC123 = NaN 33 | a_HCFC124 = NaN 34 | a_HCFC141b = NaN 35 | a_HCFC142b = NaN 36 | a_HCFC21 = NaN 37 | a_HCFC22 = NaN 38 | a_HCFC225ca = NaN 39 | a_HCFC225cb = NaN 40 | a_HCFE235da2 = NaN 41 | a_HFC125 = NaN 42 | a_HFC134 = NaN 43 | a_HFC134a = NaN 44 | a_HFC143 = NaN 45 | a_HFC143a = NaN 46 | a_HFC152 = NaN 47 | a_HFC152a = NaN 48 | a_HFC161 = NaN 49 | a_HFC227ea = NaN 50 | a_HFC23 = NaN 51 | a_HFC236cb = NaN 52 | a_HFC236ea = NaN 53 | a_HFC236fa = NaN 54 | a_HFC245ca = NaN 55 | a_HFC245fa = NaN 56 | a_HFC32 = NaN 57 | a_HFC365mfc = NaN 58 | a_HFC41 = NaN 59 | a_HFC4310mee = NaN 60 | a_HFE125 = NaN 61 | a_HFE134 = NaN 62 | a_HFE143a = NaN 63 | a_HFE227ea = NaN 64 | a_HFE236ca12 = NaN 65 | a_HFE236ea2 = NaN 66 | a_HFE236fa = NaN 67 | a_HFE245cb2 = NaN 68 | a_HFE245fa1 = NaN 69 | a_HFE245fa2 = NaN 70 | a_HFE263fb2 = NaN 71 | a_HFE329mcc2 = NaN 72 | a_HFE338mcf2 = NaN 73 | a_HFE338pcc13 = NaN 74 | a_HFE347mcc3 = NaN 75 | a_HFE347mcf2 = NaN 76 | a_HFE347pcf2 = NaN 77 | a_HFE356mec3 = NaN 78 | a_HFE356pcc3 = NaN 79 | a_HFE356pcf2 = NaN 80 | a_HFE356pcf3 = NaN 81 | a_HFE365mcf3 = NaN 82 | a_HFE374pc2 = NaN 83 | a_HFE4310pccc124 = NaN 84 | a_HFE569sf2 = NaN 85 | a_Halon1201 = NaN 86 | a_Halon1202 = NaN 87 | a_Halon1211 = NaN 88 | a_Halon1301 = NaN 89 | a_Halon2402 = NaN 90 | a_N2O = NaN 91 | a_NF3 = NaN 92 | a_PFPMIE = NaN 93 | a_SF5CF3 = NaN 94 | a_SF6 = NaN 95 | a_SO2F2 = NaN 96 | a_cC3F6 = NaN 97 | a_cC4F8 = NaN 98 | -------------------------------------------------------------------------------- /.github/workflows/test.yaml: -------------------------------------------------------------------------------- 1 | name: Test 2 | 3 | on: 4 | push: 5 | branches: [ main ] 6 | pull_request: 7 | branches: [ main ] 8 | schedule: 9 | - cron: "0 5 * * *" 10 | 11 | jobs: 12 | build: 13 | runs-on: ubuntu-latest 14 | 15 | strategy: 16 | matrix: 17 | pint-version: ["==0.24.4", ""] 18 | python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"] 19 | exclude: 20 | # latest version of pint requires minimum 3.11 21 | - pint-version: "" 22 | python-version: "3.10" 23 | 24 | fail-fast: false 25 | 26 | name: "python:${{ matrix.python-version }} pint:${{ matrix.pint-version }}" 27 | 28 | steps: 29 | - uses: actions/checkout@v6 30 | 31 | - name: Set up uv, Python 32 | uses: astral-sh/setup-uv@v7 33 | with: 34 | activate-environment: true 35 | enable-cache: true 36 | python-version: ${{ matrix.python-version }} 37 | 38 | - name: Install the package and dependencies 39 | # Force a specific version of pint 40 | run: uv pip install .[tests] pint${{ matrix.pint-version }} 41 | 42 | - name: Test 43 | run: | 44 | pytest iam_units \ 45 | -rA -vv --color=yes \ 46 | --cov=iam_units --cov-report=xml 47 | 48 | - name: Test update code 49 | # Analogous to "python -m iam_units.update …", but measures coverage 50 | run: coverage run --append -m iam_units.update emissions || exit 0 51 | 52 | - name: Upload test coverage to Codecov.io 53 | uses: codecov/codecov-action@v5 54 | with: 55 | token: ${{ secrets.CODECOV_TOKEN }} 56 | 57 | pre-commit: 58 | name: Code quality 59 | 60 | runs-on: ubuntu-latest 61 | 62 | steps: 63 | - uses: actions/checkout@v6 64 | - uses: astral-sh/setup-uv@v7 65 | with: { enable-cache: true, python-version: "3.14" } 66 | - name: Clear and re-create the pre-commit environments 67 | run: uvx pre-commit clean 68 | if: github.event_name == 'schedule' # Comment this line to force clear 69 | - run: | 70 | uvx --with=pre-commit-uv \ 71 | pre-commit run \ 72 | --all-files --color=always --show-diff-on-failure --verbose 73 | -------------------------------------------------------------------------------- /iam_units/data/emissions/AR4GWP100.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) AR4GWP100 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C2F6 = 12200.0 17 | a_C3F8 = 8830.0 18 | a_C4F10 = 8860.0 19 | a_C5F12 = 9160.0 20 | a_C6F14 = 9300.0 21 | a_CCl4 = 1400.0 22 | a_CF4 = 7390.0 23 | a_CFC11 = 4750.0 24 | a_CFC113 = 6130.0 25 | a_CFC114 = 10000.0 26 | a_CFC115 = 7370.0 27 | a_CFC12 = 10900.0 28 | a_CFC13 = 14400.0 29 | a_CH2Cl2 = 8.7 30 | a_CH3Br = 5.0 31 | a_CH3CCl3 = 146.0 32 | a_CH3Cl = 13.0 33 | a_CH4 = 25.0 34 | a_HCFC123 = 77.0 35 | a_HCFC124 = 609.0 36 | a_HCFC141b = 725.0 37 | a_HCFC142b = 2310.0 38 | a_HCFC22 = 1810.0 39 | a_HCFC225ca = 122.0 40 | a_HCFC225cb = 595.0 41 | a_HCFE235da2 = 350.0 42 | a_HFC125 = 3500.0 43 | a_HFC134a = 1430.0 44 | a_HFC143a = 4470.0 45 | a_HFC152a = 124.0 46 | a_HFC227ea = 3220.0 47 | a_HFC23 = 14800.0 48 | a_HFC236fa = 9810.0 49 | a_HFC245fa = 1030.0 50 | a_HFC32 = 675.0 51 | a_HFC365mfc = 794.0 52 | a_HFC4310mee = 1640.0 53 | a_HFE125 = 14900.0 54 | a_HFE134 = 6320.0 55 | a_HFE143a = 756.0 56 | a_HFE236ca12 = 2800.0 57 | a_HFE245cb2 = 708.0 58 | a_HFE245fa2 = 659.0 59 | a_HFE338pcc13 = 1500.0 60 | a_HFE347mcc3 = 575.0 61 | a_HFE347pcf2 = 580.0 62 | a_HFE356pcc3 = 110.0 63 | a_HFE4310pccc124 = 1870.0 64 | a_HFE569sf2 = 59.0 65 | a_Halon1211 = 1890.0 66 | a_Halon1301 = 7140.0 67 | a_Halon2402 = 1640.0 68 | a_N2O = 298.0 69 | a_NF3 = 17200.0 70 | a_PFPMIE = 10300.0 71 | a_SF5CF3 = 17700.0 72 | a_SF6 = 22800.0 73 | a_cC4F8 = 10300.0 74 | @end 75 | -------------------------------------------------------------------------------- /iam_units/emissions.py: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | import re 6 | 7 | GWP_VERSION = "0.9.3" 8 | 9 | # All available metrics usable with convert_gwp(). 10 | METRICS = [ 11 | "SARGWP100", 12 | "AR4GWP100", 13 | "AR5GWP100", 14 | "AR5CCFGWP100", 15 | "AR6GWP100", 16 | "AR6GWP20", 17 | "AR6GWP500", 18 | "AR6GTP100", 19 | ] 20 | 21 | # All recognised emission species usable with convert_gwp(). See *pattern*. 22 | SPECIES = [ 23 | "CO2", 24 | "CO2_eq", 25 | "CO2e", 26 | "CO2eq", 27 | "C", 28 | "Ce", 29 | "C10F18", 30 | "C2F6", 31 | "C3F8", 32 | "C4F10", 33 | "C5F12", 34 | "C6F14", 35 | "C7F16", 36 | "C8F18", 37 | "CCl4", 38 | "CF4", 39 | "CFC11", 40 | "CFC113", 41 | "CFC114", 42 | "CFC115", 43 | "CFC12", 44 | "CFC13", 45 | "CH2Cl2", 46 | "CH3Br", 47 | "CH3CCl3", 48 | "CH3Cl", 49 | "CH4", 50 | "CHCl3", 51 | "HCFC123", 52 | "HCFC124", 53 | "HCFC141b", 54 | "HCFC142b", 55 | "HCFC21", 56 | "HCFC22", 57 | "HCFC225ca", 58 | "HCFC225cb", 59 | "HCFE235da2", 60 | "HFC125", 61 | "HFC134", 62 | "HFC134a", 63 | "HFC143", 64 | "HFC143a", 65 | "HFC152", 66 | "HFC152a", 67 | "HFC161", 68 | "HFC227ea", 69 | "HFC23", 70 | "HFC236cb", 71 | "HFC236ea", 72 | "HFC236fa", 73 | "HFC245ca", 74 | "HFC245fa", 75 | "HFC32", 76 | "HFC365mfc", 77 | "HFC41", 78 | "HFC4310mee", 79 | "HFE125", 80 | "HFE134", 81 | "HFE143a", 82 | "HFE227ea", 83 | "HFE236ca12", 84 | "HFE236ea2", 85 | "HFE236fa", 86 | "HFE245cb2", 87 | "HFE245fa1", 88 | "HFE245fa2", 89 | "HFE263fb2", 90 | "HFE329mcc2", 91 | "HFE338mcf2", 92 | "HFE338pcc13", 93 | "HFE347mcc3", 94 | "HFE347mcf2", 95 | "HFE347pcf2", 96 | "HFE356mec3", 97 | "HFE356pcc3", 98 | "HFE356pcf2", 99 | "HFE356pcf3", 100 | "HFE365mcf3", 101 | "HFE374pc2", 102 | "HFE4310pccc124", 103 | "HFE569sf2", 104 | "Halon1201", 105 | "Halon1202", 106 | "Halon1211", 107 | "Halon1301", 108 | "Halon2402", 109 | "N2O", 110 | "NF3", 111 | "PFPMIE", 112 | "SF5CF3", 113 | "SF6", 114 | "SO2F2", 115 | "cC3F6", 116 | "cC4F8", 117 | ] 118 | 119 | # Sets of symbols that refer to the same species and are interchangeable. 120 | EQUIV = [ 121 | set(["CO2", "CO2_eq", "CO2e", "CO2eq", "C", "Ce"]), 122 | ] 123 | 124 | # Regular expression for one *SPECIES* in a pint-compatible unit string. 125 | pattern = re.compile("(?<=[ -])(" + "|".join(SPECIES) + r")(?=[ -/]|[^\w]|$)") 126 | -------------------------------------------------------------------------------- /iam_units/currency.py: -------------------------------------------------------------------------------- 1 | """Currency conversions. 2 | 3 | See the inline comments (NB) for possible extensions of this code; also 4 | iam_units.update.currency. 5 | """ 6 | 7 | from enum import Enum, auto 8 | from typing import TYPE_CHECKING 9 | 10 | if TYPE_CHECKING: 11 | from pint import UnitRegistry 12 | 13 | #: Exchange rate data for method=EXC, period=2005, from 14 | #: https://data.oecd.org/conversion/exchange-rates.htm 15 | #: 16 | #: NB this data could be extended to cover other currencies. 17 | DATA = { 18 | ("EUR", "2005"): 0.8038, 19 | } 20 | 21 | 22 | class METHOD(Enum): 23 | """Method of computing exchange rate data. 24 | 25 | From the code list OECD:CL_SNA_TABLE4_TRANSACT. The docstrings here are from their 26 | English-language descriptions. 27 | """ 28 | 29 | #: Exchange rates, period-average 30 | EXC = auto() 31 | #: Exchange rates, end of period. 32 | EXCE = auto() 33 | #: Purchasing Power Parities for GDP. 34 | PPPGDP = auto() 35 | #: Purchasing Power Parities for private consumption. 36 | PPPPRC = auto() 37 | #: Purchasing Power Parities for actual individual consumption. 38 | PPPP41 = auto() 39 | 40 | 41 | def configure_currency( 42 | method: METHOD | str = METHOD.EXC, 43 | period: str | int = 2005, 44 | *, 45 | _registry: "UnitRegistry | None" = None, 46 | ) -> None: 47 | """Configure currency conversions. 48 | 49 | Parameters 50 | ---------- 51 | method : METHOD or str 52 | Method of computing exchange rate data. 53 | period : int or str 54 | Time period (e.g. year) for exchange rates. 55 | 56 | Raises 57 | ------ 58 | NotImplementedError 59 | For unsupported values of `method` or `period`. Currently, only the defaults are 60 | supported. 61 | """ 62 | if _registry is None: 63 | from iam_units import registry 64 | else: 65 | registry = _registry 66 | 67 | # Ensure instance of METHOD 68 | try: 69 | method = METHOD[method] if isinstance(method, str) else method 70 | except KeyError: 71 | raise ValueError(f"method={method}; expected one of {[m.name for m in METHOD]}") 72 | 73 | # Ensure string 74 | period = str(period) 75 | 76 | # Select data for (method, period) 77 | if method is METHOD.EXC and period == "2005": 78 | # NB this code could be extended to: 79 | # - Load data for other combinations of (method, period). 80 | # - Load from file, instead of copying from values embedded in code. 81 | data = DATA.copy() 82 | else: 83 | message = [] 84 | if method is not METHOD.EXC: 85 | message.append(f"method={method!r}") 86 | if period != "2005": 87 | message.append(f"period={period}") 88 | raise NotImplementedError(", ".join(message)) 89 | 90 | # Insert definitions 91 | for (other, period), value in data.items(): 92 | registry.define(f"{other}_{period} = USD_{period} / {value} = {other}") 93 | -------------------------------------------------------------------------------- /iam_units/data/definitions.txt: -------------------------------------------------------------------------------- 1 | # Energy 2 | 3 | # Energy content of coal by mass 4 | # Source: https://cngcenter.com/wp-content/uploads/2013/09/UnitsAndConversions.pdf (1) 5 | # 6 | # - tonne_of_oil_equivalent is already defined in pint's default_en.txt 7 | 8 | tonne_of_coal_equivalent = 29.308 GJ = tce 9 | 10 | # Energy content of gasoline by volume 11 | # Source: https://theicct.org/sites/default/files/publications/GFEI_WP19_Final_V3_Web.pdf (2) 12 | # page 24, footnote 23. 13 | 14 | litre_of_gasoline_equivalent = 33.5 * MJ = Lge = lge 15 | # litre_of_gasoline_equivalent = 32.1 * MJ = Lge = lge # from source (1) 16 | 17 | # Energy content of diesel by volume (lower heating value) 18 | # Source: (1) 19 | 20 | litre_of_diesel_equivalent = 35.8 * MJ = Lde = lde 21 | 22 | # Short form of Watt-annum 23 | Wa = watt * year 24 | 25 | 26 | # Mass 27 | 28 | # Override pint's default `kt` = knot [velocity] rather than kilo-tonne. 29 | # See https://github.com/IAMconsortium/units/issues/13 30 | 31 | kt = 1e6 * kilogram 32 | 33 | 34 | # Orders of magnitude (short scale) to be used as prefix for other units 35 | # https://en.wikipedia.org/wiki/Order_of_magnitude 36 | 37 | hundred = 1e2 38 | thousand = 1e3 39 | million = 1e6 40 | billion = 1e9 41 | trillion = 1e12 42 | quadrillion = 1e15 43 | 44 | 45 | # Currency 46 | 47 | USD_2005 = [currency] = USD 48 | 49 | # Based on Germany's GDP deflator, data from 50 | # https://data.worldbank.org/indicator/NY.GDP.DEFL.ZS?locations=DE 51 | 52 | EUR_2005 = [currency_EUR] = EUR 53 | EUR_2000 = 1.0564 * EUR_2005 54 | EUR_2010 = 0.9463 * EUR_2005 55 | EUR_2020 = 0.8017 * EUR_2005 56 | 57 | # United States' GDP deflator, data from 58 | # https://data.worldbank.org/indicator/NY.GDP.DEFL.ZS?locations=US 59 | # last update: 2023-06-29 60 | 61 | USD_2015 = USD_2005 * 0.8358 62 | 63 | USD_2000 = USD_2015 / 0.7453 64 | USD_2001 = USD_2015 / 0.7621 65 | USD_2002 = USD_2015 / 0.774 66 | USD_2003 = USD_2015 / 0.7892 67 | USD_2004 = USD_2015 / 0.8104 68 | # USD_2005 = USD_2015 / 0.8358 69 | USD_2006 = USD_2015 / 0.8616 70 | USD_2007 = USD_2015 / 0.8849 71 | USD_2008 = USD_2015 / 0.9019 72 | USD_2009 = USD_2015 / 0.9077 73 | USD_2010 = USD_2015 / 0.9186 74 | USD_2011 = USD_2015 / 0.9377 75 | USD_2012 = USD_2015 / 0.9552 76 | USD_2013 = USD_2015 / 0.9719 77 | USD_2014 = USD_2015 / 0.9901 78 | # USD_2015 79 | USD_2016 = USD_2015 / 1.01 80 | USD_2017 = USD_2015 / 1.0292 81 | USD_2018 = USD_2015 / 1.054 82 | USD_2019 = USD_2015 / 1.0729 83 | USD_2020 = USD_2015 / 1.0869 84 | USD_2021 = USD_2015 / 1.1357 85 | USD_2022 = USD_2015 / 1.2152 86 | 87 | # Transportation activity 88 | 89 | vehicle = [vehicle] = v 90 | passenger = [passenger] = p = pass 91 | vkm = vehicle * kilometer 92 | pkm = passenger * kilometer 93 | tkm = tonne * kilometer 94 | @alias vkm = vkt = v_km 95 | @alias pkm = pkt = p_km 96 | @alias tkm = tkt = t_km 97 | 98 | # Emissions of various greenhouse gases 99 | @import emissions/emissions.txt 100 | -------------------------------------------------------------------------------- /iam_units/data/emissions/AR5CCFGWP100.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) AR5CCFGWP100 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C10F18 = 7977 17 | a_C2F6 = 12340 18 | a_C3F8 = 9878 19 | a_C4F10 = 10213 20 | a_C5F12 = 9484 21 | a_C6F14 = 8780 22 | a_C7F16 = 8681 23 | a_C8F18 = 8456 24 | a_CCl4 = 2019 25 | a_CF4 = 7349 26 | a_CFC11 = 5352 27 | a_CFC113 = 6586 28 | a_CFC114 = 9615 29 | a_CFC115 = 8516 30 | a_CFC12 = 11547 31 | a_CFC13 = 15451 32 | a_CH2Cl2 = 11 33 | a_CH3Br = 3 34 | a_CH3CCl3 = 193 35 | a_CH3Cl = 15 36 | a_CH4 = 34 37 | a_CHCl3 = 20 38 | a_HCFC123 = 96 39 | a_HCFC124 = 635 40 | a_HCFC141b = 938 41 | a_HCFC142b = 2345 42 | a_HCFC21 = 179 43 | a_HCFC22 = 2106 44 | a_HCFC225ca = 155 45 | a_HCFC225cb = 633 46 | a_HCFE235da2 = 595 47 | a_HFC125 = 3691 48 | a_HFC134 = 1337 49 | a_HFC134a = 1549 50 | a_HFC143 = 397 51 | a_HFC143a = 5508 52 | a_HFC152 = 20 53 | a_HFC152a = 167 54 | a_HFC161 = 4 55 | a_HFC227ea = 3860 56 | a_HFC23 = 13856 57 | a_HFC236cb = 1438 58 | a_HFC236ea = 1596 59 | a_HFC236fa = 8998 60 | a_HFC245ca = 863 61 | a_HFC245fa = 1032 62 | a_HFC32 = 817 63 | a_HFC365mfc = 966 64 | a_HFC41 = 141 65 | a_HFC4310mee = 1952 66 | a_HFE125 = 13951 67 | a_HFE134 = 6512 68 | a_HFE143a = 632 69 | a_HFE227ea = 7377 70 | a_HFE236ca12 = 6260 71 | a_HFE236ea2 = 2143 72 | a_HFE236fa = 1177 73 | a_HFE245cb2 = 790 74 | a_HFE245fa1 = 997 75 | a_HFE245fa2 = 981 76 | a_HFE263fb2 = 2 77 | a_HFE329mcc2 = 3598 78 | a_HFE338mcf2 = 1118 79 | a_HFE338pcc13 = 3466 80 | a_HFE347mcc3 = 641 81 | a_HFE347mcf2 = 1028 82 | a_HFE347pcf2 = 1072 83 | a_HFE356mec3 = 468 84 | a_HFE356pcc3 = 500 85 | a_HFE356pcf2 = 867 86 | a_HFE356pcf3 = 540 87 | a_HFE365mcf3 = 1 88 | a_HFE374pc2 = 758 89 | a_HFE4310pccc124 = 3353 90 | a_HFE569sf2 = 69 91 | a_Halon1201 = 454 92 | a_Halon1202 = 280 93 | a_Halon1211 = 2070 94 | a_Halon1301 = 7154 95 | a_Halon2402 = 1734 96 | a_N2O = 298 97 | a_NF3 = 17885 98 | a_PFPMIE = 10789 99 | a_SF5CF3 = 19396 100 | a_SF6 = 26087 101 | a_SO2F2 = 4732 102 | a_cC3F6 = 10208 103 | a_cC4F8 = 10592 104 | @end 105 | -------------------------------------------------------------------------------- /iam_units/data/emissions/AR6GTP100.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) AR6GTP100 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C10F18 = 9010.0 17 | a_C2F6 = 15200.0 18 | a_C3F8 = 11200.0 19 | a_C4F10 = 12100.0 20 | a_C5F12 = 11200.0 21 | a_C6F14 = 10500.0 22 | a_C7F16 = 10200.0 23 | a_C8F18 = 10000.0 24 | a_CCl4 = 810.0 25 | a_CF4 = 9050.0 26 | a_CFC11 = 3540.0 27 | a_CFC113 = 5210.0 28 | a_CFC114 = 9410.0 29 | a_CFC115 = 11000.0 30 | a_CFC12 = 10400.0 31 | a_CFC13 = 18800.0 32 | a_CH2Cl2 = 2.01 33 | a_CH3Br = 0.438 34 | a_CH3CCl3 = 29.7 35 | a_CH3Cl = 1.0 36 | a_CH4 = 5.38 37 | a_CHCl3 = 3.72 38 | a_HCFC123 = 16.4 39 | a_HCFC124 = 110.0 40 | a_HCFC141b = 162.0 41 | a_HCFC142b = 514.0 42 | a_HCFC21 = 29.0 43 | a_HCFC22 = 379.0 44 | a_HCFC225ca = 24.8 45 | a_HCFC225cb = 105.0 46 | a_HCFE235da2 = 98.4 47 | a_HFC125 = 1300.0 48 | a_HFC134 = 239.0 49 | a_HFC134a = 306.0 50 | a_HFC143 = 66.6 51 | a_HFC143a = 3250.0 52 | a_HFC152 = 3.89 53 | a_HFC152a = 29.8 54 | a_HFC161 = 0.872 55 | a_HFC227ea = 1490.0 56 | a_HFC23 = 15100.0 57 | a_HFC236cb = 268.0 58 | a_HFC236ea = 288.0 59 | a_HFC236fa = 8870.0 60 | a_HFC245ca = 146.0 61 | a_HFC245fa = 180.0 62 | a_HFC32 = 142.0 63 | a_HFC365mfc = 172.0 64 | a_HFC41 = 24.6 65 | a_HFC4310mee = 347.0 66 | a_HFE125 = 13100.0 67 | a_HFE134 = 2060.0 68 | a_HFE143a = 113.0 69 | a_HFE227ea = 4440.0 70 | a_HFE236ca12 = 1860.0 71 | a_HFE236ea2 = 521.0 72 | a_HFE236fa = 205.0 73 | a_HFE245cb2 = 137.0 74 | a_HFE245fa1 = 173.0 75 | a_HFE245fa2 = 162.0 76 | a_HFE329mcc2 = 1090.0 77 | a_HFE338mcf2 = 194.0 78 | a_HFE338pcc13 = 657.0 79 | a_HFE347mcc3 = 106.0 80 | a_HFE347mcf2 = 179.0 81 | a_HFE347pcf2 = 181.0 82 | a_HFE356mec3 = 48.0 83 | a_HFE356pcc3 = 50.4 84 | a_HFE356pcf2 = 154.0 85 | a_HFE356pcf3 = 88.4 86 | a_HFE365mcf3 = 0.289 87 | a_HFE374pc2 = 2.25 88 | a_HFE4310pccc124 = 647.0 89 | a_HFE569sf2 = 11.0 90 | a_Halon1201 = 69.8 91 | a_Halon1202 = 39.3 92 | a_Halon1211 = 406.0 93 | a_Halon1301 = 5060.0 94 | a_Halon2402 = 702.0 95 | a_N2O = 233.0 96 | a_NF3 = 20000.0 97 | a_PFPMIE = 12000.0 98 | a_SF5CF3 = 21600.0 99 | a_SF6 = 30600.0 100 | a_SO2F2 = 1920.0 101 | a_cC4F8 = 12400.0 102 | @end 103 | -------------------------------------------------------------------------------- /iam_units/data/emissions/AR6GWP500.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) AR6GWP500 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C10F18 = 9780.0 17 | a_C2F6 = 17500.0 18 | a_C3F8 = 12400.0 19 | a_C4F10 = 13400.0 20 | a_C5F12 = 12700.0 21 | a_C6F14 = 11600.0 22 | a_C7F16 = 11300.0 23 | a_C8F18 = 11100.0 24 | a_CCl4 = 658.0 25 | a_CF4 = 10600.0 26 | a_CFC11 = 2090.0 27 | a_CFC113 = 2830.0 28 | a_CFC114 = 6150.0 29 | a_CFC115 = 9880.0 30 | a_CFC12 = 5710.0 31 | a_CFC13 = 17500.0 32 | a_CH2Cl2 = 3.18 33 | a_CH3Br = 0.692 34 | a_CH3CCl3 = 46.0 35 | a_CH3Cl = 1.58 36 | a_CH4 = 7.95 37 | a_CHCl3 = 5.87 38 | a_HCFC123 = 25.8 39 | a_HCFC124 = 170.0 40 | a_HCFC141b = 246.0 41 | a_HCFC142b = 658.0 42 | a_HCFC21 = 45.6 43 | a_HCFC22 = 560.0 44 | a_HCFC225ca = 39.0 45 | a_HCFC225cb = 162.0 46 | a_HCFE235da2 = 154.0 47 | a_HFC125 = 1110.0 48 | a_HFC134 = 361.0 49 | a_HFC134a = 436.0 50 | a_HFC143 = 104.0 51 | a_HFC143a = 1940.0 52 | a_HFC152 = 6.14 53 | a_HFC152a = 46.8 54 | a_HFC161 = 1.38 55 | a_HFC227ea = 1100.0 56 | a_HFC23 = 10500.0 57 | a_HFC236cb = 387.0 58 | a_HFC236ea = 428.0 59 | a_HFC236fa = 6040.0 60 | a_HFC245ca = 225.0 61 | a_HFC245fa = 274.0 62 | a_HFC32 = 220.0 63 | a_HFC365mfc = 261.0 64 | a_HFC41 = 38.6 65 | a_HFC4310mee = 458.0 66 | a_HFE125 = 7680.0 67 | a_HFE134 = 1940.0 68 | a_HFE143a = 176.0 69 | a_HFE227ea = 2570.0 70 | a_HFE236ca12 = 1770.0 71 | a_HFE236ea2 = 741.0 72 | a_HFE236fa = 315.0 73 | a_HFE245cb2 = 213.0 74 | a_HFE245fa1 = 266.0 75 | a_HFE245fa2 = 251.0 76 | a_HFE329mcc2 = 1100.0 77 | a_HFE338mcf2 = 297.0 78 | a_HFE338pcc13 = 948.0 79 | a_HFE347mcc3 = 164.0 80 | a_HFE347mcf2 = 275.0 81 | a_HFE347pcf2 = 279.0 82 | a_HFE356mec3 = 75.3 83 | a_HFE356pcc3 = 79.0 84 | a_HFE356pcf2 = 237.0 85 | a_HFE356pcf3 = 138.0 86 | a_HFE365mcf3 = 0.457 87 | a_HFE374pc2 = 3.56 88 | a_HFE4310pccc124 = 920.0 89 | a_HFE569sf2 = 17.3 90 | a_Halon1201 = 108.0 91 | a_Halon1202 = 61.5 92 | a_Halon1211 = 552.0 93 | a_Halon1301 = 2750.0 94 | a_Halon2402 = 639.0 95 | a_N2O = 130.0 96 | a_NF3 = 18200.0 97 | a_PFPMIE = 11700.0 98 | a_SF5CF3 = 21100.0 99 | a_SF6 = 34100.0 100 | a_SO2F2 = 1410.0 101 | a_cC4F8 = 13800.0 102 | @end 103 | -------------------------------------------------------------------------------- /iam_units/data/emissions/AR5GWP100.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) AR5GWP100 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C10F18 = 7190.0 17 | a_C2F6 = 11100.0 18 | a_C3F8 = 8900.0 19 | a_C4F10 = 9200.0 20 | a_C5F12 = 8550.0 21 | a_C6F14 = 7910.0 22 | a_C7F16 = 7820.0 23 | a_C8F18 = 7620.0 24 | a_CCl4 = 1730.0 25 | a_CF4 = 6630.0 26 | a_CFC11 = 4660.0 27 | a_CFC113 = 5820.0 28 | a_CFC114 = 8590.0 29 | a_CFC115 = 7670.0 30 | a_CFC12 = 10200.0 31 | a_CFC13 = 13900.0 32 | a_CH2Cl2 = 9.0 33 | a_CH3Br = 2.0 34 | a_CH3CCl3 = 160.0 35 | a_CH3Cl = 12.0 36 | a_CH4 = 28.0 37 | a_CHCl3 = 16.0 38 | a_HCFC123 = 79.0 39 | a_HCFC124 = 527.0 40 | a_HCFC141b = 782.0 41 | a_HCFC142b = 1980.0 42 | a_HCFC21 = 148.0 43 | a_HCFC22 = 1760.0 44 | a_HCFC225ca = 127.0 45 | a_HCFC225cb = 525.0 46 | a_HCFE235da2 = 491.0 47 | a_HFC125 = 3170.0 48 | a_HFC134 = 1120.0 49 | a_HFC134a = 1300.0 50 | a_HFC143 = 328.0 51 | a_HFC143a = 4800.0 52 | a_HFC152 = 16.0 53 | a_HFC152a = 138.0 54 | a_HFC161 = 4.0 55 | a_HFC227ea = 3350.0 56 | a_HFC23 = 12400.0 57 | a_HFC236cb = 1210.0 58 | a_HFC236ea = 1330.0 59 | a_HFC236fa = 8060.0 60 | a_HFC245ca = 716.0 61 | a_HFC245fa = 858.0 62 | a_HFC32 = 677.0 63 | a_HFC365mfc = 804.0 64 | a_HFC41 = 116.0 65 | a_HFC4310mee = 1650.0 66 | a_HFE125 = 12400.0 67 | a_HFE134 = 5560.0 68 | a_HFE143a = 523.0 69 | a_HFE227ea = 6450.0 70 | a_HFE236ca12 = 5350.0 71 | a_HFE236ea2 = 1790.0 72 | a_HFE236fa = 979.0 73 | a_HFE245cb2 = 654.0 74 | a_HFE245fa1 = 828.0 75 | a_HFE245fa2 = 812.0 76 | a_HFE263fb2 = 1.0 77 | a_HFE329mcc2 = 3070.0 78 | a_HFE338mcf2 = 929.0 79 | a_HFE338pcc13 = 2910.0 80 | a_HFE347mcc3 = 530.0 81 | a_HFE347mcf2 = 854.0 82 | a_HFE347pcf2 = 889.0 83 | a_HFE356mec3 = 387.0 84 | a_HFE356pcc3 = 413.0 85 | a_HFE356pcf2 = 719.0 86 | a_HFE356pcf3 = 446.0 87 | a_HFE374pc2 = 627.0 88 | a_HFE4310pccc124 = 2820.0 89 | a_HFE569sf2 = 57.0 90 | a_Halon1201 = 376.0 91 | a_Halon1211 = 1750.0 92 | a_Halon1301 = 6290.0 93 | a_Halon2402 = 1470.0 94 | a_N2O = 265.0 95 | a_NF3 = 16100.0 96 | a_PFPMIE = 9710.0 97 | a_SF5CF3 = 17400.0 98 | a_SF6 = 23500.0 99 | a_SO2F2 = 4090.0 100 | a_cC3F6 = 9200.0 101 | a_cC4F8 = 9540.0 102 | @end 103 | -------------------------------------------------------------------------------- /iam_units/data/emissions/AR6GWP100.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) AR6GWP100 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C10F18 = 7480.0 17 | a_C2F6 = 12400.0 18 | a_C3F8 = 9290.0 19 | a_C4F10 = 10000.0 20 | a_C5F12 = 9220.0 21 | a_C6F14 = 8620.0 22 | a_C7F16 = 8410.0 23 | a_C8F18 = 8260.0 24 | a_CCl4 = 2200.0 25 | a_CF4 = 7380.0 26 | a_CFC11 = 6230.0 27 | a_CFC113 = 6520.0 28 | a_CFC114 = 9430.0 29 | a_CFC115 = 9600.0 30 | a_CFC12 = 12500.0 31 | a_CFC13 = 16200.0 32 | a_CH2Cl2 = 11.2 33 | a_CH3Br = 2.43 34 | a_CH3CCl3 = 161.0 35 | a_CH3Cl = 5.54 36 | a_CH4 = 27.9 37 | a_CHCl3 = 20.6 38 | a_HCFC123 = 90.4 39 | a_HCFC124 = 597.0 40 | a_HCFC141b = 860.0 41 | a_HCFC142b = 2300.0 42 | a_HCFC21 = 160.0 43 | a_HCFC22 = 1960.0 44 | a_HCFC225ca = 137.0 45 | a_HCFC225cb = 568.0 46 | a_HCFE235da2 = 539.0 47 | a_HFC125 = 3740.0 48 | a_HFC134 = 1260.0 49 | a_HFC134a = 1530.0 50 | a_HFC143 = 364.0 51 | a_HFC143a = 5810.0 52 | a_HFC152 = 21.5 53 | a_HFC152a = 164.0 54 | a_HFC161 = 4.84 55 | a_HFC227ea = 3600.0 56 | a_HFC23 = 14600.0 57 | a_HFC236cb = 1350.0 58 | a_HFC236ea = 1500.0 59 | a_HFC236fa = 8690.0 60 | a_HFC245ca = 787.0 61 | a_HFC245fa = 962.0 62 | a_HFC32 = 771.0 63 | a_HFC365mfc = 914.0 64 | a_HFC41 = 135.0 65 | a_HFC4310mee = 1600.0 66 | a_HFE125 = 14300.0 67 | a_HFE134 = 6630.0 68 | a_HFE143a = 616.0 69 | a_HFE227ea = 7520.0 70 | a_HFE236ca12 = 6060.0 71 | a_HFE236ea2 = 2590.0 72 | a_HFE236fa = 1100.0 73 | a_HFE245cb2 = 747.0 74 | a_HFE245fa1 = 934.0 75 | a_HFE245fa2 = 878.0 76 | a_HFE329mcc2 = 3770.0 77 | a_HFE338mcf2 = 1040.0 78 | a_HFE338pcc13 = 3320.0 79 | a_HFE347mcc3 = 576.0 80 | a_HFE347mcf2 = 963.0 81 | a_HFE347pcf2 = 980.0 82 | a_HFE356mec3 = 264.0 83 | a_HFE356pcc3 = 277.0 84 | a_HFE356pcf2 = 831.0 85 | a_HFE356pcf3 = 484.0 86 | a_HFE365mcf3 = 1.6 87 | a_HFE374pc2 = 12.5 88 | a_HFE4310pccc124 = 3220.0 89 | a_HFE569sf2 = 60.7 90 | a_Halon1201 = 380.0 91 | a_Halon1202 = 216.0 92 | a_Halon1211 = 1930.0 93 | a_Halon1301 = 7200.0 94 | a_Halon2402 = 2170.0 95 | a_N2O = 273.0 96 | a_NF3 = 17400.0 97 | a_PFPMIE = 10300.0 98 | a_SF5CF3 = 18500.0 99 | a_SF6 = 25200.0 100 | a_SO2F2 = 4630.0 101 | a_cC4F8 = 10200.0 102 | @end 103 | -------------------------------------------------------------------------------- /iam_units/data/emissions/AR6GWP20.txt: -------------------------------------------------------------------------------- 1 | # This file was generated using: 2 | # python -m iam_units.update emissions 3 | # DO NOT ALTER THIS FILE MANUALLY! 4 | 5 | @context(_a=NaN) AR6GWP20 6 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 7 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 8 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 9 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 10 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 11 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 12 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 13 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 14 | 15 | 16 | a_C10F18 = 5480.0 17 | a_C2F6 = 8940.0 18 | a_C3F8 = 6770.0 19 | a_C4F10 = 7300.0 20 | a_C5F12 = 6680.0 21 | a_C6F14 = 6260.0 22 | a_C7F16 = 6120.0 23 | a_C8F18 = 6010.0 24 | a_CCl4 = 3810.0 25 | a_CF4 = 5300.0 26 | a_CFC11 = 8320.0 27 | a_CFC113 = 6860.0 28 | a_CFC114 = 8260.0 29 | a_CFC115 = 7410.0 30 | a_CFC12 = 12700.0 31 | a_CFC13 = 12400.0 32 | a_CH2Cl2 = 40.2 33 | a_CH3Br = 8.74 34 | a_CH3CCl3 = 567.0 35 | a_CH3Cl = 19.9 36 | a_CH4 = 81.2 37 | a_CHCl3 = 74.2 38 | a_HCFC123 = 325.0 39 | a_HCFC124 = 2070.0 40 | a_HCFC141b = 2710.0 41 | a_HCFC142b = 5510.0 42 | a_HCFC21 = 575.0 43 | a_HCFC22 = 5690.0 44 | a_HCFC225ca = 491.0 45 | a_HCFC225cb = 1960.0 46 | a_HCFE235da2 = 1930.0 47 | a_HFC125 = 6740.0 48 | a_HFC134 = 3900.0 49 | a_HFC134a = 4140.0 50 | a_HFC143 = 1300.0 51 | a_HFC143a = 7840.0 52 | a_HFC152 = 77.6 53 | a_HFC152a = 591.0 54 | a_HFC161 = 17.4 55 | a_HFC227ea = 5850.0 56 | a_HFC23 = 12400.0 57 | a_HFC236cb = 3750.0 58 | a_HFC236ea = 4420.0 59 | a_HFC236fa = 7450.0 60 | a_HFC245ca = 2680.0 61 | a_HFC245fa = 3170.0 62 | a_HFC32 = 2690.0 63 | a_HFC365mfc = 2920.0 64 | a_HFC41 = 485.0 65 | a_HFC4310mee = 3960.0 66 | a_HFE125 = 13500.0 67 | a_HFE134 = 12700.0 68 | a_HFE143a = 2170.0 69 | a_HFE227ea = 9800.0 70 | a_HFE236ca12 = 11700.0 71 | a_HFE236ea2 = 7020.0 72 | a_HFE236fa = 3670.0 73 | a_HFE245cb2 = 2630.0 74 | a_HFE245fa1 = 3170.0 75 | a_HFE245fa2 = 3060.0 76 | a_HFE329mcc2 = 7550.0 77 | a_HFE338mcf2 = 3460.0 78 | a_HFE338pcc13 = 9180.0 79 | a_HFE347mcc3 = 2020.0 80 | a_HFE347mcf2 = 3270.0 81 | a_HFE347pcf2 = 3370.0 82 | a_HFE356mec3 = 949.0 83 | a_HFE356pcc3 = 995.0 84 | a_HFE356pcf2 = 2870.0 85 | a_HFE356pcf3 = 1730.0 86 | a_HFE365mcf3 = 5.77 87 | a_HFE374pc2 = 45.0 88 | a_HFE4310pccc124 = 8720.0 89 | a_HFE569sf2 = 219.0 90 | a_Halon1201 = 1340.0 91 | a_Halon1202 = 775.0 92 | a_Halon1211 = 4920.0 93 | a_Halon1301 = 8320.0 94 | a_Halon2402 = 4070.0 95 | a_N2O = 273.0 96 | a_NF3 = 13400.0 97 | a_PFPMIE = 7750.0 98 | a_SF5CF3 = 13900.0 99 | a_SF6 = 18300.0 100 | a_SO2F2 = 7510.0 101 | a_cC4F8 = 7400.0 102 | @end 103 | -------------------------------------------------------------------------------- /DEVELOPING.rst: -------------------------------------------------------------------------------- 1 | Development notes 2 | ***************** 3 | 4 | The repository and package aim to be ruthlessly simple, and thus as easy as possible to maintain. 5 | Thus: 6 | 7 | - No built documentation; like `pycountry `_, the README *is* the documentation. 8 | - Actual code (in \_\_init\_\_.py) kept to a minimum. 9 | - Versioning: 10 | 11 | - similar to pycountry: ``..``. 12 | - `setuptools-scm `_ and git tags used for all versioning; nothing hardcoded. 13 | 14 | - Minimal CI configuration: one service/OS/Python version. 15 | - AUTHORS: anyone adding a commit to the repo should also add their name to AUTHORS. 16 | 17 | 18 | Releasing 19 | ========= 20 | 21 | Before releasing, check https://github.com/IAMconsortium/units/actions/workflows/test.yaml to ensure that the push and scheduled builds are passing. 22 | Address any failures before releasing. 23 | 24 | 1. Create a new branch:: 25 | 26 | $ git checkout -b release/YYYY.MM.DD 27 | 28 | 2. Tag the release candidate (RC) version, i.e. with a ``rcN`` suffix, and push:: 29 | 30 | $ git tag v2021.3.22rc1 31 | $ git push --tags origin release/YYYY.MM.DD 32 | 33 | 3. Open a PR with the title “Release vYYYY.MM.DD” using this branch. 34 | Check: 35 | 36 | - at https://github.com/IAMconsortium/units/actions/workflows/publish.yaml that the workflow completes: the package builds successfully and is published to TestPyPI. 37 | - at https://pypi.org/project/iam-units/ that: 38 | 39 | - The release candidate package can be downloaded, installed and run. 40 | - The README is rendered correctly. 41 | 42 | Address any warnings or errors that appear. 43 | If needed, make a new commit and go back to step (2), incrementing the rc number. 44 | 45 | 4. Merge the PR using the ‘rebase and merge’ method. 46 | 47 | 5. (optional) Switch back to the ``main`` branch, tag the release itself (*without* an RC number) and push:: 48 | 49 | $ git checkout main 50 | $ git pull --fast-forward 51 | $ git tag v2021.3.22 52 | $ git push --tags origin main 53 | 54 | This step (but *not* step (2)) can also be performed directly on GitHub; see (6), next. 55 | 56 | 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. 57 | 58 | 7. Check at https://github.com/IAMconsortium/units/actions/workflows/publish.yaml and https://pypi.org/project/iam-units/ that the distributions are published. 59 | 60 | 61 | Generated data files for GWP contexts 62 | ===================================== 63 | 64 | iam_units/data/emissions/emissions.txt defines the base units for Pint, and imports the other files iam_units/data/emissions/\*.txt. 65 | These files each define one context, and contain a notice that they should not be edited manually. 66 | 67 | First, install the ``globalwarmingpotentials`` package:: 68 | 69 | $ pip install globalwarmingpotentials 70 | 71 | Update these files using the command:: 72 | 73 | $ python -m iam_units.update emissions 74 | 75 | The update submodule writes the context files. 76 | When adding a new context file, make sure to ``@import`` it in emissions.txt and expand the tests. 77 | -------------------------------------------------------------------------------- /iam_units/update.py: -------------------------------------------------------------------------------- 1 | import sys 2 | from itertools import chain 3 | from pathlib import Path 4 | 5 | # This package is only required when updating the emissions GWP conversion factors 6 | import globalwarmingpotentials as gwp 7 | 8 | # Base path for package code 9 | BASE_PATH = Path(__file__).parent 10 | 11 | # Base path for package data 12 | DATA_PATH = BASE_PATH / "data" 13 | 14 | 15 | # Format strings for emissions() 16 | _EMI_HEADER = """# This file was generated using: 17 | # python -m iam_units.update emissions 18 | # DO NOT ALTER THIS FILE MANUALLY! 19 | """ 20 | 21 | # Format string for individual metrics. To expand the set of supported conversions, 22 | # duplicate and modify the first pair of lines in the context. Currently supported: 23 | # 1. Mass. 24 | # 2. Mass rate, or mass per time. 25 | # 3. Flux, or mass per area per time. 26 | # 4. Mass per unit energy. 27 | _EMI_DATA = f"""{_EMI_HEADER} 28 | @context(_a=NaN) {{metric}} 29 | [mass] -> [_GWP]: value * (_a * _gwp / kg) 30 | [_GWP] -> [mass]: value / (_a * _gwp / kg) 31 | [mass] / [time] -> [_GWP] / [time]: value * (_a * _gwp / kg) 32 | [_GWP] / [time] -> [mass] / [time]: value / (_a * _gwp / kg) 33 | [mass] / [time] / [area] -> [_GWP] / [time] / [area]: value * (_a * _gwp / kg) 34 | [_GWP] / [time] / [area] -> [mass] / [time] / [area]: value / (_a * _gwp / kg) 35 | [time] ** 2 / [length] ** 2 -> [_GWP] * [time] ** 2 / [length] ** 2: value * (_a * _gwp) 36 | [_GWP] * [time] ** 2 / [length] ** 2 -> [time] ** 2 / [length] ** 2: value / (_a * _gwp) 37 | 38 | 39 | {{defs}} 40 | @end 41 | """ # noqa: E501 42 | 43 | # Format string for an importable Python module defining the *pattern* regex, 44 | # which resembles: (?<=[ -])(CO2|C|N2O|CH4)(?=[ -/]|[^\w]|$) 45 | # - Preceded by a space or '-' character. 46 | # - Followed by a space, '-', '/', end-of-string, or non-word (\w) character. 47 | # The latter avoids matching only the 'C' within 'CH4'. 48 | _EMI_CODE = rf"""{_EMI_HEADER} 49 | import re 50 | 51 | GWP_VERSION = '{gwp.__version__}' 52 | 53 | # All available metrics usable with convert_gwp(). 54 | METRICS = [ 55 | '{{metrics}}' 56 | ] 57 | 58 | # All recognised emission species usable with convert_gwp(). See *pattern*. 59 | SPECIES = [ 60 | '{{symbols}}', 61 | ] 62 | 63 | # Sets of symbols that refer to the same species and are interchangeable. 64 | EQUIV = [ 65 | set({{equiv}}), 66 | ] 67 | 68 | # Regular expression for one *SPECIES* in a pint-compatible unit string. 69 | pattern = re.compile( 70 | '(?<=[ -])(' 71 | + '|'.join(SPECIES) 72 | + r')(?=[ -/]|[^\w]|$)') 73 | """ 74 | 75 | # Format string for list of metrics. 76 | _EMI_METRICS = f"""{_EMI_HEADER} 77 | 78 | # Define contexts for each set of metrics 79 | 80 | {{metrics}} 81 | """ 82 | 83 | # Equivalents: different symbols for the same species. 84 | _EMI_EQUIV = { 85 | "CO2": { 86 | "CO2_eq": None, 87 | "CO2e": None, 88 | "CO2eq": None, 89 | "C": "44. / 12 * ", 90 | "Ce": "44. / 12 * ", 91 | } 92 | } 93 | 94 | 95 | def currency() -> None: 96 | """Update currency definitions files.""" 97 | # Currently no such files exist; see iam_units.currency.configure_currency(). 98 | # 99 | # An implementation here should, at minimum: 100 | # - Use the package `sdmx1` to query either the World Bank or OECD SDMX API. 101 | # - Confirm these the different data sources give the same results; if not, expose 102 | # to the user an option to select the source. 103 | # - Write to a simple text format that can be read by iam_units installation without 104 | # any dependencies; in a directory like iam_units/data/currency, with one file 105 | # per supported combination of (method, period). 106 | raise NotImplementedError 107 | 108 | 109 | def emissions() -> None: 110 | """Update emissions definitions files.""" 111 | data_path = DATA_PATH / "emissions" 112 | 113 | # Import data from `globalwarmingpotentials`, get list of species aka symbols. 114 | data = gwp.as_frame().sort_index() 115 | symbols = data.index 116 | 117 | # Format and write the species defs file 118 | lines = [_EMI_HEADER] 119 | for species, alias in _EMI_EQUIV.items(): 120 | lines.extend( 121 | f"a_{a} = {factor or ''}a_{species}" for a, factor in alias.items() 122 | ) 123 | lines.extend(f"a_{s} = NaN" for s in symbols) 124 | lines.append("") 125 | (data_path / "species.txt").write_text("\n".join(lines)) 126 | 127 | # Write a Python module with a regex matching the species names 128 | 129 | # Prepare list including all symbols 130 | all_alias_groups = list([key, *value] for key, value in _EMI_EQUIV.items()) 131 | all_symbols = list(chain(*all_alias_groups, symbols)) 132 | 133 | # Format and write `emissions.py` 134 | code = _EMI_CODE.format( 135 | metrics="',\n '".join(list(data.columns)), 136 | symbols="',\n '".join(all_symbols), 137 | equiv="),\n set(".join(map(repr, all_alias_groups)), 138 | ) 139 | (BASE_PATH / "emissions.py").write_text(code) 140 | 141 | # Format and write `metrics.txt"` 142 | code = _EMI_METRICS.format( 143 | metrics="\n".join([f"@import {m}.txt" for m in data.columns]) 144 | ) 145 | (data_path / "metrics.txt").write_text(code) 146 | 147 | # Write one file containing a context for each metric 148 | for metric in data.columns: 149 | # Conversion factor definitions 150 | defs = [ 151 | f"a_{species} = {value}" for species, value in data[metric].dropna().items() 152 | ] 153 | 154 | # Format the template with the definitions 155 | content = _EMI_DATA.format(metric=metric, defs="\n ".join(defs)) 156 | 157 | # Write to file 158 | (data_path / f"{metric}.txt").write_text(content) 159 | 160 | 161 | if __name__ == "__main__": 162 | # Invoked using 'python -m iam_units.update' 163 | # For each additional argument, call the function of the same name 164 | for module in sys.argv[1:]: 165 | locals()[module]() 166 | -------------------------------------------------------------------------------- /iam_units/__init__.py: -------------------------------------------------------------------------------- 1 | import logging 2 | import os 3 | from collections.abc import Sequence 4 | from pathlib import Path 5 | from typing import TYPE_CHECKING 6 | 7 | import pint 8 | from pint.formatting import format_unit 9 | from pint.util import to_units_container 10 | 11 | from . import emissions 12 | from .currency import configure_currency 13 | 14 | if TYPE_CHECKING: 15 | from numpy.typing import NDArray 16 | from pint._typing import Scalar 17 | 18 | __all__ = [ 19 | "convert_gwp", 20 | "configure_currency", 21 | "format_mass", 22 | "registry", 23 | ] 24 | 25 | 26 | def convert_gwp( 27 | metric: str | None, 28 | quantity: str | pint.Quantity | tuple["Scalar | Sequence[Scalar] | NDArray", str], 29 | *species: str | None, 30 | ) -> pint.Quantity: 31 | """Convert `quantity` between GHG `species` with a GWP `metric`. 32 | 33 | Parameters 34 | ---------- 35 | metric : str or None 36 | Metric conversion factors to use. May be :obj:`None` if the input and output 37 | species are the same. Use :code:`iam_units.emissions.METRICS` for a list of 38 | available metrics. 39 | quantity : str or pint.Quantity or tuple 40 | Quantity to convert. If a tuple of (magnitude, unit), these are passed as 41 | arguments to :class:`pint.Quantity`. 42 | species : sequence of str, length 1 or 2 43 | Output, or (input, output) species symbols, e.g. ('CH4', 'CO2') to convert mass 44 | of CH₄ to GWP-equivalent mass of CO₂. If only the output species is provided, 45 | `quantity` must contain the symbol of the input species in some location, e.g. 46 | '1.0 tonne CH4 / year'. 47 | 48 | Returns 49 | ------- 50 | pint.Quantity 51 | `quantity` converted from the input to output species. 52 | 53 | Notes 54 | ----- 55 | The conversion factors are taken from the `globalwarmingpotentials` package, 56 | see https://github.com/openclimatedata/globalwarmingpotentials. You can use 57 | :code:`iam_units.emissions.GWP_VERSION` to check from which version of that package 58 | the conversion tables in the `iam_units` package were generated. 59 | """ 60 | # Handle `species`: either (in, out) or only out 61 | try: 62 | species_in, species_out = species 63 | except ValueError: 64 | if len(species) != 1: 65 | raise ValueError("Must provide (from, to) or (to,) species") 66 | species_in, species_out = None, species[0] 67 | 68 | # Split `quantity` if it is a tuple. After this step: 69 | # - `mag` is the magnitude, or None. 70 | # - `expr` is a string expression for either just the units, or the entire quantity, 71 | # including magnitude, as a str or pint.Quantity. 72 | mag, expr = quantity if isinstance(quantity, tuple) else (None, quantity) 73 | 74 | # If species_in wasn't provided, then `expr` must contain it 75 | if not species_in: 76 | # Extract it using the regex, then re-assemble the expression for the units or 77 | # whole quantity 78 | q0, species_in, q1 = emissions.pattern.split(str(expr), maxsplit=1) 79 | expr = q0 + q1 80 | 81 | # `metric` can only be None if the input and output species symbols are identical or 82 | # equivalent 83 | if metric is None: 84 | if species_in == species_out or any( 85 | {species_in, species_out} <= g for g in emissions.EQUIV 86 | ): 87 | metric = "AR5GWP100" 88 | elif species_out and species_in in species_out: 89 | # Eg. 'CO2' in 'CO2 / a'. This is both a DimensionalityError and a 90 | # ValueError (no metric); raise the former for pyam compat 91 | raise pint.DimensionalityError(species_in, species_out) 92 | else: 93 | msg = f"Must provide GWP metric for ({species_in}, {species_out})" 94 | raise ValueError(msg) 95 | 96 | # Ensure a pint.Quantity object: 97 | # - If `quantity` was a tuple, use the 2-arg constructor. 98 | # - If a str, use the 1-arg form to parse it. 99 | # - If already a pint.Quantity, this is a no-op. 100 | args = (expr,) if mag is None else (mag, expr) 101 | quantity = registry.Quantity(*args) 102 | 103 | # Construct intermediate units with the same dimensionality as `quantity`, except 104 | # '[mass]' replaced with the dummy unit '_gwp' 105 | m_dim = quantity.dimensionality["[mass]"] 106 | dummy = quantity.units / registry.Unit(f"tonne ** {m_dim} / _gwp") 107 | 108 | # Convert to dummy units using 'a' for the input species; then back to the input 109 | # units using 'a' for the output species. 110 | return quantity.to(dummy, metric, _a=f"a_{species_in}").to( 111 | quantity.units, metric, _a=f"a_{species_out}" 112 | ) 113 | 114 | 115 | def format_mass( 116 | obj: pint.Quantity | pint.Unit, info: str, spec: str | None = None 117 | ) -> str: 118 | """Format the units of `obj` with `info` inserted after its mass unit. 119 | 120 | Parameters 121 | ---------- 122 | obj : pint.Quantity or pint.Unit 123 | info : str 124 | Any information, e.g. the symbol of a GHG species. 125 | spec : str, optional 126 | Pint formatting specifier such as "H" (HTML format), "~C" (compact format with 127 | symbols), etc. 128 | """ 129 | spec = spec or registry.formatter.default_format 130 | 131 | # Use only the units of a Quantity object 132 | obj_units = obj.units if isinstance(obj, pint.Quantity) else obj 133 | 134 | # Use the symbol if the modifier "~" is in `spec`; else the canonical name. cf. 135 | # pint.Unit.__format__() 136 | method = registry._get_symbol if "~" in spec else lambda k: k 137 | # Collect the pieces of the unit expression: tuples of (unit string, exponent) 138 | unit_power: list[tuple[str, "Scalar"]] = [ 139 | (method(unit), power) for unit, power in obj_units._units.items() 140 | ] 141 | 142 | # Index of the mass component 143 | index = list(obj_units.dimensionality.keys()).index("[mass]") 144 | # Append the information (e.g. species) to the mass component 145 | unit_power[index] = (f"{unit_power[index][0]} {info}", unit_power[index][1]) 146 | 147 | # Prepare pint.util.UnitsContainer and hand off to pint's formatting. Discard "~" 148 | # (used above) and ":" (invalid in pint ≥0.18). 149 | return format_unit( 150 | to_units_container(dict(unit_power), registry=registry), 151 | spec.replace("~", "").lstrip(":"), 152 | ) 153 | 154 | 155 | def _initialize() -> pint.UnitRegistry: 156 | from platformdirs import user_cache_path 157 | 158 | # Identify cache folder: from environment variable, or default 159 | cache_folder = os.environ.get("IAM_UNITS_CACHE", None) or user_cache_path( 160 | "iam-units" 161 | ) 162 | 163 | # Create the registry, using a disk cache 164 | registry: pint.UnitRegistry = pint.UnitRegistry(cache_folder=cache_folder) 165 | 166 | # Quiet the pint logger per redefinition of units 167 | pint_util_logger = logging.getLogger("pint.util") 168 | original_pint_util_log_level = pint_util_logger.getEffectiveLevel() 169 | pint_util_logger.setLevel(logging.ERROR) 170 | 171 | # Load definitions.txt 172 | registry.load_definitions(str(Path(__file__).parent / "data" / "definitions.txt")) 173 | 174 | if value := os.environ.get("IAM_UNITS_CURRENCY", ""): 175 | method, period = value.split(",") 176 | configure_currency(method, period, _registry=registry) 177 | 178 | # Restore level of pint.util logger 179 | pint_util_logger.setLevel(original_pint_util_log_level) 180 | 181 | return registry 182 | 183 | 184 | registry = _initialize() 185 | -------------------------------------------------------------------------------- /iam_units/test_all.py: -------------------------------------------------------------------------------- 1 | import importlib 2 | 3 | import numpy as np 4 | import pint 5 | import pytest 6 | from numpy.testing import assert_almost_equal, assert_array_almost_equal 7 | from pint.util import UnitsContainer 8 | 9 | from iam_units import configure_currency, convert_gwp, emissions, format_mass, registry 10 | from iam_units.currency import METHOD 11 | 12 | DEFAULTS = pint.get_application_registry() 13 | 14 | NIE = pytest.mark.xfail(raises=NotImplementedError) 15 | 16 | # Parameters for test_units(), tuple of: 17 | # 1. A literal string to be parsed as a unit. 18 | # 2. Expected dimensionality of the parsed unit. 19 | # 3. True if the units are not in pint's default_en.txt, but are defined in 20 | # definitions.txt. 21 | energy = UnitsContainer({"[energy]": 1}) 22 | PARAMS = [ 23 | ("GW a", energy, False), 24 | ("kWa", energy, True), 25 | ("Lge", energy, True), 26 | ("tce", energy, True), 27 | ("toe", energy, False), 28 | ("EUR_2005", UnitsContainer({"[currency]": 1}), True), 29 | ( 30 | "billion tkm/yr", 31 | UnitsContainer({"[length]": 1, "[mass]": 1, "[time]": -1}), 32 | True, 33 | ), 34 | ] 35 | 36 | 37 | @pytest.mark.parametrize( 38 | "unit_str, dim, new_def", PARAMS, ids=lambda v: v if isinstance(v, str) else "" 39 | ) 40 | def test_units(unit_str, dim, new_def) -> None: 41 | if new_def: 42 | # Units defined in dimensions.txt are not recognized by base pint 43 | with pytest.raises(pint.UndefinedUnitError): 44 | DEFAULTS("1 " + unit_str) 45 | 46 | # Physical quantity of units is recognized 47 | dim = registry.get_dimensionality(dim) 48 | 49 | # Units can be parsed and have the correct dimensionality 50 | assert registry("1 " + unit_str).dimensionality == dim 51 | 52 | 53 | def test_orders_of_magnitude() -> None: 54 | # The registry recognizes units prefixed by an order of magnitude 55 | assert registry("1.2 billion EUR").to("million EUR").magnitude == 1.2e3 56 | 57 | 58 | def test_kt() -> None: 59 | # The registry should correctly interpret `kt` as a weight (not velocity) 60 | assert str(registry("1000 kt").to("Mt")) == "1.0 megametric_ton" 61 | 62 | # A default UnitRegistry should interpret `kt` as velocity 63 | with pytest.raises(pint.DimensionalityError): 64 | pint.UnitRegistry()("kt").to("Mt") 65 | 66 | 67 | @pytest.mark.parametrize( 68 | "method, period", 69 | ( 70 | # Not supported method 71 | pytest.param("PPPGDP", 2005, marks=NIE), 72 | pytest.param(METHOD.PPPGDP, 2005, marks=NIE), 73 | # Not supported period 74 | pytest.param("EXC", 2010, marks=NIE), 75 | pytest.param(METHOD.EXC, 2010, marks=NIE), 76 | # Invalid method str 77 | pytest.param("FOO", 2005, marks=pytest.mark.xfail(raises=ValueError)), 78 | ), 79 | ) 80 | def test_currency(method: METHOD | str, period: int) -> None: 81 | configure_currency(method, period) 82 | 83 | 84 | def test_emissions_gwp_versions() -> None: 85 | assert isinstance(emissions.GWP_VERSION, str) 86 | 87 | 88 | def test_emissions_metrics() -> None: 89 | assert "SARGWP100" in emissions.METRICS 90 | 91 | 92 | def test_emissions_internal() -> None: 93 | # Dummy units can be created 94 | registry("0.5 _gwp").dimensionality == {"[_GWP]": 1.0} 95 | 96 | # Context can be enabled 97 | with registry.context("AR5GWP100", __a=1.0) as r: 98 | # Context-specific values are activated 99 | assert r("a_CH4 * a_N2O").to_base_units().magnitude == 28 * 265 100 | 101 | # Context-specific conversion rules are available 102 | r("0.5 t").to("_gwp") 103 | 104 | 105 | @pytest.mark.parametrize( 106 | "units", 107 | [ 108 | "t {}", # Mass 109 | "Mt {} / a", # Mass rate 110 | "kt {} / (ha * yr)", # Mass flux 111 | "kt {} / J", # Mass per unit energy 112 | ], 113 | ) 114 | @pytest.mark.parametrize( 115 | "metric, species_in, species_out, expected_value", 116 | [ 117 | ("AR6GWP20", "CH4", "CO2", 81.2), 118 | ("AR6GWP100", "CH4", "CO2", 27.9), 119 | ("AR5CCFGWP100", "CH4", "CO2", 34), 120 | ("AR5GWP100", "CH4", "CO2", 28), 121 | ("AR5GWP100", "CH4", "CO2e", 28), 122 | ("AR4GWP100", "CH4", "CO2", 25), 123 | ("SARGWP100", "CH4", "CO2", 21), 124 | # Same-species conversion with metric=None and compatible names 125 | (None, "CO2", "CO2_eq", 1.0), 126 | (None, "CO2eq", "CO2e", 1.0), 127 | # Species names which are substrings of one another match correctly 128 | ("AR5GWP100", "HFC143", "CO2", 328.0), 129 | ("AR5GWP100", "HFC143a", "CO2", 4800.0), 130 | ], 131 | ) 132 | def test_convert_gwp( 133 | units: str, metric, species_in, species_out, expected_value 134 | ) -> None: 135 | # Bare masses can be converted 136 | qty0 = registry.Quantity(1.0, units.format("")) 137 | expected = registry(f"{expected_value} {units}") 138 | 139 | observed = convert_gwp(metric, qty0, species_in, species_out) 140 | assert observed.units == expected.units 141 | np.testing.assert_almost_equal(observed.magnitude, expected.magnitude) 142 | 143 | # '[mass] [speciesname] (/ [time])' can be converted; the input species is extracted 144 | # from the *qty* argument 145 | qty1 = "1.0 " + units.format(species_in) 146 | expected = registry(f"{expected_value} {units}") 147 | 148 | observed = convert_gwp(metric, qty1, species_out) 149 | assert observed.units == expected.units 150 | np.testing.assert_almost_equal(observed.magnitude, expected.magnitude) 151 | 152 | # Tuple of (vector magnitude, unit expression) can be converted where the 153 | # the unit expression contains the input species name 154 | arr = np.array([1.0, 2.5, 0.1]) 155 | qty2 = (arr, units.format(species_in)) 156 | expected = arr * expected_value 157 | 158 | # Conversion works 159 | result = convert_gwp(metric, qty2, species_out) 160 | # Magnitudes are as expected 161 | assert_array_almost_equal(result.magnitude, expected) 162 | 163 | 164 | @pytest.mark.parametrize( 165 | "context", 166 | ["AR5GWP100", None], 167 | ) 168 | def test_convert_gwp_carbon(context) -> None: 169 | # CO2 can be converted to C 170 | qty = (44.0 / 12, "tonne CO2") 171 | result = convert_gwp(context, qty, "C") 172 | assert result.units == registry("tonne") 173 | assert_almost_equal(result.magnitude, 1.0) 174 | 175 | # C can be converted to CO2 176 | qty = (1, "tonne C") 177 | expected = registry.Quantity(44.0 / 12, "tonne") 178 | assert convert_gwp(context, qty, "CO2e") == expected 179 | 180 | 181 | @pytest.mark.parametrize( 182 | "units_in, species_str, spec, output", 183 | [ 184 | ("Mt", "CO2", None, "megametric_ton CO2"), 185 | ("kg / year", "CO2", None, "kilogram CO2 / year"), 186 | # Compact spec: no spaces around '/' 187 | ("kg / year", "CO2", ":C", "kilogram CO2/year"), 188 | # Abbreviated/symbol spec AND Unicode subscript 189 | ("Mt", "CO₂", ":~", "Mt CO₂"), 190 | ("kg / year", "CO₂", ":~", "kg CO₂ / a"), 191 | # Abitrary string, e.g. including a hint at the metric name 192 | ("gram / a", "CO₂-e (AR4)", ":~", "g CO₂-e (AR4) / a"), 193 | ], 194 | ) 195 | def test_format_mass(units_in, species_str, spec, output) -> None: 196 | # Quantity object can be formatted 197 | qty0 = registry.Quantity(3.5, units_in) 198 | assert format_mass(qty0, species_str, spec) == output 199 | 200 | # Unit object can be formatted 201 | qty1 = registry.Unit(units_in) 202 | assert format_mass(qty1, species_str, spec) == output 203 | 204 | 205 | def test_import_warnings(caplog) -> None: 206 | import iam_units 207 | 208 | importlib.reload(iam_units) 209 | 210 | pint_warning_logs = [ 211 | log 212 | for log in caplog.records 213 | if log.name == "pint.util" and log.levelname == "WARNING" 214 | ] 215 | assert len(pint_warning_logs) == 0 216 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | Unit definitions for integrated-assessment research 2 | *************************************************** 3 | |pypi| |gha| |coverage| 4 | 5 | .. |pypi| image:: https://img.shields.io/pypi/v/iam-units.svg 6 | :target: https://pypi.python.org/pypi/iam-units/ 7 | :alt: PyPI version 8 | 9 | .. |gha| image:: https://github.com/IAMconsortium/units/actions/workflows/test.yaml/badge.svg 10 | :target: https://github.com/IAMconsortium/units/actions/workflows/test.yaml 11 | :alt: Build status 12 | 13 | .. |coverage| image:: https://codecov.io/gh/IAMconsortium/units/branch/main/graph/badge.svg 14 | :target: https://codecov.io/gh/IAMconsortium/units 15 | :alt: Test coverage 16 | 17 | © 2020-2025 `IAM-units authors`_; licensed under the `GNU GPL version 3`_. 18 | 19 | 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`_. 20 | These definitions are used by: 21 | 22 | - the IIASA Energy Program `MESSAGEix-GLOBIOM`_ integrated assessment model (IAM), 23 | - the Python package `pyam`_ for analysis and visualization of integrated-assessment scenarios (see `pyam.IamDataFrame.convert_unit()`_ for details) 24 | 25 | and may be used for research in integrated assessment, energy systems, transportation, or other, related fields. 26 | 27 | Please open a GitHub `issue`_ or `pull request`_ to: 28 | 29 | - Add more units to definitions.txt. 30 | - Add your usage of iam-units to this README. 31 | - Request or contribute additional features. 32 | 33 | Usage 34 | ===== 35 | 36 | ``iam_units.registry`` is a ``pint.UnitRegistry`` object with the definitions from definitions.txt loaded: 37 | 38 | .. code-block:: python 39 | 40 | >>> from iam_units import registry 41 | 42 | # Parse an energy unit defined by iam-units 43 | >>> qty = registry('1.2 tce') 44 | >>> qty 45 | 1.2 46 | 47 | >>> qty.to('GJ') 48 | 29.308 49 | 50 | To make the registry from this package the default: 51 | 52 | .. code-block:: python 53 | 54 | >>> import pint 55 | >>> pint.set_application_registry(registry) 56 | 57 | # Now used by default for pint top-level classes and methods 58 | >>> pint.Quantity('1.2 tce') 59 | 1.2 60 | 61 | Environment variables 62 | --------------------- 63 | 64 | The package responds to two optional environment variables: 65 | 66 | ``IAM_UNITS_CACHE`` 67 | iam-units caches the created registry using `pint's caching mechanism`_. 68 | If set, this variable must contain the path of a directory for the cache. 69 | If not set, a default path is used. 70 | 71 | ``IAM_UNITS_CURRENCY`` 72 | If set, this variable must be a string like "EXC,2005". 73 | The two parts, separated by a comma (","), are separated 74 | and passed as the *method* and *period* arguments to ``configure_currency()`` 75 | (see below) 76 | when iam-units is imported. 77 | If not set, the function is not called. 78 | 79 | .. _pint's caching mechanism: https://pint.readthedocs.io/en/stable/advanced/performance.html#speed-up-registry-instantiation 80 | 81 | Warnings 82 | ======== 83 | 84 | ``iam_units`` overwrites Pint's default definitions in the following cases: 85 | 86 | .. list-table:: 87 | :header-rows: 1 88 | 89 | - - ``pint`` default 90 | - ``iam_units`` 91 | - Note 92 | - - 'kt' = knot [velocity] 93 | - 'kt' = 1000 metric tons 94 | - 'kt' is commonly used for emissions in the IAM-context. 95 | 96 | Technical details 97 | ================= 98 | 99 | Emissions and GWP 100 | ----------------- 101 | 102 | 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*. 103 | The supported species are listed in `species.txt`_ and the variable ``iam_units.emissions.SPECIES``. 104 | 105 | The metrics have names like ``GWP``, where ```` is the time period over which heat absorption was assessed. 106 | The supported metrics are listed in the variable ``iam_units.emissions.METRICS``. 107 | 108 | .. code-block:: python 109 | 110 | >>> qty = registry('3.5e3 t').to('Mt') 111 | >>> qty 112 | 3.5 113 | 114 | # Convert from mass of N2O to GWP-equivalent mass of CO2 115 | >>> convert_gwp('AR4GWP100', qty, 'N2O', 'CO2') 116 | 0.9275 117 | 118 | # Using a different metric 119 | >>> convert_gwp('AR5GWP100', qty, 'N2O', 'CO2') 120 | 1.085 121 | 122 | The function also accepts input with the commonly-used combination of mass (or related) *units* **and** the identity of a particular GHG species: 123 | 124 | .. code-block:: python 125 | 126 | # Expression combining magnitude, units, *and* GHG species 127 | >>> qty = '3.5 Mt N2O / year' 128 | 129 | # Input species is determined from *qty* 130 | >>> convert_gwp('AR5GWP100', qty, 'CO2') 131 | 1.085 132 | 133 | Strictly, the original species is not a unit but a *nominal property*; see the `International Vocabulary of Metrology`_ (VIM) used in the SI. 134 | To avoid ambiguity, code handling GHG quantities should also track and output these nominal properties, including: 135 | 136 | 1. Original species. 137 | 2. Species in which GWP-equivalents are expressed (e.g. CO₂ or C) 138 | 3. GWP metric used to convert (1) to (2). 139 | 140 | To aid with this, the function ``format_mass()`` is provided to re-assemble strings that include the GHG species or other information: 141 | 142 | .. code-block:: python 143 | 144 | # Perform a conversion 145 | >>> qty = convert_gwp('AR5GWP100', '3.5 Mt N2O / year', 'CO2e') 146 | >>> qty 147 | 927.5 148 | 149 | # Format a string with species and metric info after the mass units of *qty* 150 | >>> format_mass(qty, 'CO₂-e (AR5)', spec=':~') 151 | 'Mt CO₂-e (AR5) / a' 152 | 153 | See `Pint's formatting documentation`_ for values of the *spec* argument. 154 | 155 | Data sources 156 | ~~~~~~~~~~~~ 157 | 158 | The GWP unit definitions are generated from the package globalwarmingpotentials_. 159 | The version of that package used to generate the definitions is stated in the variable ``iam_units.emissions.GWP_VERSION``. 160 | 161 | See ``_ for details on updating the definitions. 162 | 163 | .. _global warming potential: https://en.wikipedia.org/wiki/Global_warming_potential 164 | .. _International Vocabulary of Metrology: https://www.bipm.org/utils/common/documents/jcgm/JCGM_200_2008.pdf 165 | .. _contexts: https://pint.readthedocs.io/en/latest/contexts.html 166 | .. _Pint's formatting documentation: https://pint.readthedocs.io/en/latest/tutorial.html#string-formatting 167 | .. _globalwarmingpotentials: https://github.com/openclimatedata/globalwarmingpotentials 168 | 169 | Currency 170 | -------- 171 | 172 | ``iam_units`` defines deflators for: 173 | 174 | - USD (United States dollar) for annual periods from 2000 to 2022 inclusive. 175 | - EUR (Euro) for the periods 2005, 2010, 2015, and 2020 only. 176 | 177 | These can be used via pint-compatible unit expressions like ``USD_2019`` that combine the `ISO 4217`_ alphabetic code with the period. 178 | 179 | To enable conversions between *different* currencies, use the function ``configure_currency()``: 180 | 181 | .. code-block:: python 182 | 183 | >>> configure_currency(method="EXC", period="2005") 184 | 185 | # Then, for example 186 | >>> qty = registry("42.1 USD_2020") 187 | >>> qty 188 | 42.1 189 | 190 | >>> qty.to("EUR_2005") 191 | 26.022132012144635 192 | 193 | Currently ``iam_units`` only supports: 194 | 195 | - period-average exchange rates for annual periods (method="EXC"); 196 | - period="2005"; and 197 | - the two currencies mentioned above. 198 | 199 | Up to v2025.9.12, ``configure_currency("EXC", 2005)`` was called automatically. 200 | 201 | Contributions that extend the supported currencies, methods, and periods are welcome. 202 | 203 | .. _ISO 4217: https://en.wikipedia.org/wiki/ISO_4217#Active_codes_(List_One) 204 | 205 | Tests and development 206 | ===================== 207 | 208 | Use ``pytest iam_units --verbose`` to run the test suite included in the submodule ``iam_units.test_all``. 209 | See ``_ for further details. 210 | 211 | .. _IAM-units authors: ./AUTHORS 212 | .. _GNU GPL version 3: ./LICENSE 213 | .. _definitions.txt: ./iam_units/data/definitions.txt 214 | .. _emissions.txt: ./iam_units/data/emissions/emissions.txt 215 | .. _species.txt: ./iam_units/data/emissions/species.txt 216 | .. _checks.csv: ./iam_units/data/checks.csv 217 | .. _Pint: https://pint.readthedocs.io 218 | .. _default_en.txt: https://github.com/hgrecco/pint/blob/master/pint/default_en.txt 219 | .. _MESSAGEix-GLOBIOM: https://docs.messageix.org/models/ 220 | .. _pyam: https://pyam-iamc.readthedocs.io 221 | .. _pyam.IamDataFrame.convert_unit(): https://pyam-iamc.readthedocs.io/en/stable/api/iamdataframe.html#pyam.IamDataFrame.convert_unit 222 | .. _issue: https://github.com/IAMconsortium/units/issues 223 | .. _pull request: https://github.com/IAMconsortium/units/pulls 224 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | --------------------------------------------------------------------------------