energy.carbon-emissions

kgCO2e = quantity x conversion factor

def carbon_emissions(fuel: str, quantity: int, year: int) -> CarbonEmissions

@dataclass(frozen=True)
class CarbonEmissions:
    """The emissions and the factor they came from, for an audit trail."""

    fuel: str
    #: kWh or litres
    unit: str
    year: int
    #: the GHG Protocol scope the factor belongs to: 1, 2 or 3
    scope: int
    #: kgCO2e per unit, in hundred-thousandths: 0.20705 kg/kWh is 20705
    factor: int
    #: emissions in grams of CO2e (kgCO2e to three decimals), rounded half-up
    grams: int

from fune.energy.carbon_emissions import carbon_emissions  # energy.carbon-emissions@^1

from .energy_carbon_emissions_data import CONVERSION_FACTORS  ← this capability’s own data, compiled from data/conversion-factors.json into the same file by fune build
from .energy_carbon_emissions_types import CarbonEmissions
from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune

# quantity (thousandths of a unit) x factor (hundred-thousandths of a kg)
# / 100000 is grams.
DIVISOR = 100_000
MAX_SAFE = 9007199254740991


def carbon_emissions(fuel: str, quantity: int, year: int) -> CarbonEmissions:
    """kgCO2e, as whole grams, for an amount of a fuel, from the UK government
    conversion factor set for ``year``.
    """
    if not isinstance(quantity, int) or isinstance(quantity, bool) or quantity < 0:
        raise ValueError(
            "quantity must be a whole number of thousandths of a unit, 0 or more, received %s" % (quantity,)
        )
    if not any(f.fuel == fuel for f in CONVERSION_FACTORS):
        raise ValueError('unknown fuel "%s"' % (fuel,))
    row = next((f for f in CONVERSION_FACTORS if f.fuel == fuel and f.year == year), None)
    if row is None:
        raise ValueError("no conversion factor for %s in %s" % (fuel, year))
    whole, rest = divmod(quantity, DIVISOR)
    grams = whole * row.factor + round_div(rest * row.factor, DIVISOR, "half-up")
    if grams > MAX_SAFE:
        raise ValueError("emissions too large to calculate exactly")
    return CarbonEmissions(fuel=fuel, unit=row.unit, year=year, scope=row.scope, factor=row.factor, grams=grams)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add energy.carbon-emissions

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./energy.carbon-emissions-1.0.1-python.fune, or fetch it from a terminal with fune pull energy.carbon-emissions@1.0.1:python.

The whole function, every language, is one file too: energy.carbon-emissions-1.0.1.fune, 22,579 bytes, sha256 2c79961b918cd1eb475f3c88476437760af9a41cf4c3a20b71b338f11d0e9451. It installs into a project of any language.

# fune: before energy.carbon-emissions

# fune: after energy.carbon-emissions

# fune: replace math.round-div in energy.carbon-emissions

# fune: step energy.carbon-emissions after <n|label>

More from the author

using the UK government's greenhouse gas conversion factors for company reporting (published each June by DESNZ, previously BEIS), for the 2023, 2024, 2025 and 2026 sets. They are the factors Streamlined Energy and Carbon Reporting (SECR) and most UK carbon footprints use.

## Fuels

| fuel | unit | factor used | scope | |---|---|---|---| | `electricity` | kWh | UK electricity, "Electricity generated" | 2 | | `electricity-td` | kWh | UK electricity transmission and distribution losses | 3 | | `natural-gas` | kWh | Natural gas, kWh (Gross CV) | 1 | | `lpg` | litres | LPG, litres | 1 | | `burning-oil` | litres | Burning oil (kerosene, heating oil), litres | 1 | | `gas-oil` | litres | Gas oil (red diesel), litres | 1 | | `fuel-oil` | litres | Fuel oil, litres | 1 | | `diesel` | litres | Diesel (average biofuel blend), litres | 1 | | `petrol` | litres | Petrol (average biofuel blend), litres | 1 |

Gas bills are in kWh on gross calorific value (see `energy.gas-kwh`), which is why the gas factor is the Gross CV one. A full electricity footprint is `electricity` plus `electricity-td` for the same kWh.

## Units and rounding

- Quantities are integers in **thousandths** of the fuel's unit (watt-hours, millilitres), so fractional litres and kWh are exact. - Factors are integers in **hundred-thousandths of a kg** per unit: the five decimal places DESNZ publishes (0.20705 kg/kWh is `20705`). The 2023 flat file carries more digits than the published tables show (0.2070742...); those were rounded half-up to the five places the condensed set displays. - The result is **grams of CO2e**, rounded once, half-up (kgCO2e to three decimals). The product is split so it stays exact for any quantity whose answer fits an exact integer.

## Why the year is an argument, and there are no effective dates

A factor set is chosen by reporting year, not by the date the fuel was burned: a company reporting its 2025 financial year uses the 2025 set (or states which it used). Older sets stay valid for restating older years, so they are never "no longer in force" and the table deliberately has no `effective` columns: a `history=current` build keeps every year. A year that is not in the table is an error rather than falling back to another year's factors.

## Sources

Department for Energy Security and Net Zero, "Greenhouse gas reporting: conversion factors", flat-format workbooks, rows "Fuels", "UK electricity" and "Transmission and distribution", column "kg CO2e":

- 2023: https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2023 (ghg-conversion-factors-2023-flat-file-update.xlsx) - 2024: https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2024 (ghg-conversion-factors-2024-FlatFormat_v1_1.xlsx) - 2025: https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2025 (ghg-conversion-factors-2025-flat-format.xlsx) - 2026: https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2026 (ghg-conversion-factors-2026-flat-format-revised.xlsx)

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

1.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files