energy.carbon-emissions

kgCO2e = quantity x conversion factor

pub fn carbon_emissions(fuel: &str, quantity: i64, year: i64) -> CarbonEmissions

/// The emissions and the factor they came from, for an audit trail.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CarbonEmissions {
    pub fuel: String,
    /// kWh or litres
    pub unit: String,
    pub year: i64,
    /// the GHG Protocol scope the factor belongs to: 1, 2 or 3
    pub scope: i64,
    /// kgCO2e per unit, in hundred-thousandths: 0.20705 kg/kWh is 20705
    pub factor: i64,
    /// emissions in grams of CO2e (kgCO2e to three decimals), rounded half-up
    pub grams: i64,
}

fune!(energy.carbon-emissions@^1);  // then call carbon_emissions(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::energy_carbon_emissions_data::CONVERSION_FACTORS;  ← this capability’s own data, compiled from data/conversion-factors.json into the same file by fune build
use super::math_round_div::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.
const DIVISOR: i64 = 100_000;
const MAX_SAFE: i128 = 9_007_199_254_740_991;

/// kgCO2e, as whole grams, for an amount of a fuel, from the UK government
/// conversion factor set for `year`.
///
/// # Panics
/// Panics on a negative quantity, an unknown fuel, a year with no factor set,
/// or a result too large to be exact in every language.
pub fn carbon_emissions(fuel: &str, quantity: i64, year: i64) -> CarbonEmissions {
    if quantity < 0 {
        panic!(
            "quantity must be a whole number of thousandths of a unit, 0 or more, received {}",
            quantity
        );
    }
    if !CONVERSION_FACTORS.iter().any(|f| f.fuel == fuel) {
        panic!("unknown fuel \"{}\"", fuel);
    }
    let row = match CONVERSION_FACTORS.iter().find(|f| f.fuel == fuel && f.year == year) {
        Some(row) => row,
        None => panic!("no conversion factor for {} in {}", fuel, year),
    };
    let whole = quantity / DIVISOR;
    let rest = quantity % DIVISOR;
    let grams = whole as i128 * row.factor as i128 + round_div(rest * row.factor, DIVISOR, "half-up") as i128;
    if grams > MAX_SAFE {
        panic!("emissions too large to calculate exactly");
    }
    CarbonEmissions {
        fuel: fuel.to_string(),
        unit: row.unit.to_string(),
        year,
        scope: row.scope,
        factor: row.factor,
        grams: grams as i64,
    }
}

pub fn carbon_emissions_to_value(e: &CarbonEmissions) -> Value {
    Value::obj(vec![
        ("fuel", Value::str(&e.fuel)),
        ("unit", Value::str(&e.unit)),
        ("year", Value::Int(e.year)),
        ("scope", Value::Int(e.scope)),
        ("factor", Value::Int(e.factor)),
        ("grams", Value::Int(e.grams)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    if let Value::Float(f) = &args[1] {
        panic!("quantity must be a whole number of thousandths of a unit, 0 or more, received {}", f);
    }
    carbon_emissions_to_value(&carbon_emissions(args[0].as_str(), args[1].as_i64(), args[2].as_i64()))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. 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 Rust implementation. Install it without the registry with fune add ./energy.carbon-emissions-1.0.0-rust.fune, or fetch it from a terminal with fune pull energy.carbon-emissions@1.0.0:rust.

The whole function, every language, is one file too: energy.carbon-emissions-1.0.0.fune, 22,106 bytes, sha256 bae07b09df8f0ef3bd4ff5ecfd0029294f6be101f8709fde8d1a549ce45c75aa. 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)

Files