fleet.emissions

def fleet_emissions(activity: str, quantity: str, unit: EmissionsUnit, factor_year: int) -> FleetEmissions

EmissionsUnit = Literal["litres", "km", "miles"]

@dataclass(frozen=True)
class FleetEmissions:
    """The emissions and the factor that produced them, for the audit trail."""

    #: quantity times factor, rounded half up to the gram
    co2e_grams: int
    #: the factor as published, kg CO2e per unit, to 5 decimal places
    factor: str
    factor_year: int
    activity: str
    unit: str

from fune.fleet.emissions import fleet_emissions  # fleet.emissions@^1

import re
from typing import Optional

from .fleet_emissions_data import GHG_FACTORS  ← this capability’s own data, compiled from data/ghg-factors.json into the same file by fune build
from .fleet_emissions_types import EmissionsUnit, FleetEmissions

DECIMAL = re.compile(r"([0-9]+)(?:\.([0-9]+))?")
MAX_SAFE = 9007199254740991


def _format_factor(factor: int) -> str:
    return "%d.%05d" % (factor // 100000, factor % 100000)


def fleet_emissions(activity: str, quantity: str, unit: EmissionsUnit, factor_year: int) -> FleetEmissions:
    """Scope 1 emissions for fuel burned or distance driven, from the UK
    government's conversion factors for company reporting.

    The quantity is decimal text and the factor an integer in 1e-5 kg, so the
    product is exact and rounded once, to the gram. Multiplying floats instead
    drifts in the last place and can round a half-gram the wrong way.
    """
    if unit not in ("litres", "km", "miles"):
        raise ValueError('unknown unit "%s": use litres, km or miles' % (unit,))
    if isinstance(factor_year, bool) or not isinstance(factor_year, int):
        raise ValueError("factorYear must be a whole year, received %s" % (factor_year,))
    match = DECIMAL.fullmatch(quantity) if isinstance(quantity, str) else None
    if match is None:
        raise ValueError('quantity must be plain decimal text, not negative, received "%s"' % (quantity,))
    fraction = match.group(2) or ""
    digits = (match.group(1) + fraction).lstrip("0")
    if len(digits) > 15 or len(fraction) > 9:
        raise ValueError(
            'quantity must have at most 15 significant digits and 9 decimal places, received "%s"' % (quantity,)
        )

    found: Optional[int] = None
    year_known = False
    activity_known = False
    for row in GHG_FACTORS:
        if row.factor_year != factor_year:
            continue
        year_known = True
        if row.activity != activity:
            continue
        activity_known = True
        if row.unit == unit:
            found = row.factor
    if not year_known:
        raise ValueError("no conversion factors for %d: this package carries 2023 to 2026" % (factor_year,))
    if not activity_known:
        raise ValueError('unknown activity "%s" in the %d factors' % (activity, factor_year))
    if found is None:
        raise ValueError("no conversion factor for %s per %s in %d" % (activity, unit, factor_year))

    # grams = quantity x factor x 1e-5 kg x 1000 g/kg = quantity x factor / 100
    numerator = int(match.group(1) + fraction) * found
    denominator = 10 ** len(fraction) * 100
    grams = (2 * numerator + denominator) // (2 * denominator)
    if grams > MAX_SAFE:
        raise ValueError("the result exceeds 2^53 - 1 grams")
    return FleetEmissions(
        co2e_grams=grams, factor=_format_factor(found), factor_year=factor_year, activity=activity, unit=unit
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, 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 fleet.emissions

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

The whole function, every language, is one file too: fleet.emissions-1.0.1.fune, 142,757 bytes, sha256 889b6473407bbb10b8b415ea8a5d9fa9ddc9d09a15beacbd289c885db32cce5c. It installs into a project of any language.

# fune: before fleet.emissions

# fune: after fleet.emissions

# fune: step fleet.emissions after <n|label>

More from the author

Fuel is the better measure when you have it (fuel cards, bunkered fuel): it already reflects how the vehicles were driven. Distance by vehicle class is the fallback. The factors are the **Scope 1** figures, direct tailpipe emissions in kg CO2e (CO2, CH4 and N2O together):

- fuels, per litre: `fuel-diesel` and `fuel-petrol` (UK forecourt fuel with its average biofuel blend), `fuel-diesel-mineral` and `fuel-petrol-mineral` (100% mineral), `fuel-lpg`; - cars by size, per km or mile: `car-{small|medium|large|average}-{diesel|petrol|hybrid|phev|cng|lpg|unknown}` where DESNZ publishes one (there is no small CNG or LPG car); - `motorbike-{small|medium|large|average}`; - vans: `van-{class-1|class-2|class-3|average}-{diesel|petrol}`, and `van-average-{cng|lpg|unknown|phev}` and `van-class-3-phev` (the van PHEV factors appear from 2024); - HGVs (all diesel): `hgv-{rigid-3.5-7.5t|rigid-7.5-17t|rigid-over-17t|all-rigids|artic-3.5-33t|artic-over-33t|all-artics|all-hgvs}-laden-{0|50|100|average}`.

Battery electric vehicles are deliberately absent: their Scope 1 factor is zero, and their emissions belong to the electricity used (Scope 2, DESNZ's "UK electricity for EVs" table), which this package does not carry. A plug-in hybrid's factor likewise covers only the fuel it burns.

Per-mile factors are DESNZ's own, not the per-km factor times 1.609344, so a report matches the published spreadsheet exactly.

## Which year

`factorYear` picks the DESNZ set: 2023, 2024, 2025 or 2026. DESNZ publishes each set in June for reporting periods in that year; use the set for the year you are reporting, and keep it for restatements. The sets are publications, not rules that expire, so the table has no effective columns and ships whole.

In the 2026 set DESNZ split HGVs into refrigerated and non-refrigerated and renamed the averages; the `hgv-*` codes read the non-refrigerated rows for 2026 (earlier years' "HGV (all diesel)" table is the non-refrigerated fleet, refrigerated HGVs having had their own table), so the codes mean the same vehicle in every year.

## Exactness

Each factor is stored as an integer in units of 0.00001 kg (10 mg): DESNZ publishes five decimal places. The 2023 flat file holds the unrounded values behind them (2.5120638845637586 for diesel); they are rounded half up to the five places shown in the published tables (2.51206). The quantity is decimal text, so quantity times factor is exact, and the only rounding is the final one, half up to a whole gram. Quantities are limited to 15 significant digits and 9 decimal places, and a result above 2^53 - 1 grams is an error, so all three languages agree.

## Relationship to energy.*

This package is self-contained. If an `energy.carbon-emissions` capability with the same DESNZ tables appears in the registry, a later version of this one should read its data instead of carrying a second copy.

## Sources

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

Every row of `data/ghg-factors.json` names the spreadsheet path it came from (Level 1 / Level 2 / Level 3 / column), always the "kg CO2e" row of Scope 1.

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