From 7d16030d2ffb3d5ba6bdf7d13f8cf8135e021c12 Mon Sep 17 00:00:00 2001 From: David Berenstein Date: Wed, 12 Aug 2026 23:39:55 +0200 Subject: [PATCH 1/2] docs: add a how-it-works overview page Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanation/how-it-works.md | 102 +++++++++++++++++++++++++++++++ docs/index.md | 1 + mkdocs.yml | 1 + 3 files changed, 104 insertions(+) create mode 100644 docs/explanation/how-it-works.md diff --git a/docs/explanation/how-it-works.md b/docs/explanation/how-it-works.md new file mode 100644 index 000000000..535bab0f7 --- /dev/null +++ b/docs/explanation/how-it-works.md @@ -0,0 +1,102 @@ +# How CodeCarbon works + +CodeCarbon samples the power drawn by your hardware, integrates it into energy +over the lifetime of your run, and multiplies that energy by the carbon +intensity of the grid supplying the machine. + +That is the whole idea. This page is the mental model — enough to read your own +output and know what it means. When you need the exact backend, constant or +fallback that produced a given number, [Methodology](methodology.md) states each +one with the line of source it comes from. + +## The formula + +```text +emissions = Σ_intervals (power × Δt × PUE) × carbon_intensity +``` + +- **power** — watts drawn by the CPU, GPU and RAM at the moment of sampling. +- **Δt** — the sampling interval, `measure_power_secs`, 15 seconds by default. + Power × Δt is energy; summing over every interval gives the energy of the run. +- **PUE** — power usage effectiveness, an optional multiplier for datacentre + overhead such as cooling. It defaults to 1.0, meaning no overhead assumed. +- **carbon_intensity** — grams of CO₂-equivalent emitted per kilowatt-hour on + the grid the machine draws from. + +Everything else in the documentation is detail about how those four terms are +obtained. + +## What is measured and what is modelled + +This is the single most important thing to understand about a CodeCarbon +number, and the thing most likely to be assumed rather than checked. + +| Component | On a good day | Otherwise | +|---|---|---| +| **CPU** | Measured. Hardware energy counters via RAPL on Linux, the Energy Meter Interface on Windows 11, or `powermetrics` on macOS. | **Modelled** from CPU load and a table lookup of your processor's TDP — or, if the model is unrecognised, a flat guess. | +| **RAM** | **Always modelled.** There is no RAM power counter on any supported platform. CodeCarbon guesses your DIMM count from total memory and assigns watts per DIMM. | — | +| **GPU** | Measured. NVML counters read directly from the Nvidia device. | Not counted. Without NVML there is no GPU estimate — the figure is simply absent. | + +The consequence is worth stating outright: **the same column in the same CSV can +be a hardware reading on one machine and an educated guess on another.** A run +on a Linux box with readable RAPL files is measurement. The identical script on +a cloud VM without RAPL exposed produces a number of the same shape from a +model. Nothing in the output distinguishes them; the startup log names the CPU +backend that was selected. + +Which of those two you got is the biggest driver of how far your number is from +reality — larger than the grid data, larger than the sampling interval, larger +than anything you can tune. [Accuracy and validation](accuracy.md) puts figures +on the gap. + +The RAM estimate deserves its own caution. Its central constant — watts per +memory module — is asserted in the code with no source behind it, and on a +low-power machine RAM can be a large share of the total. If you know your real +configuration, override it with `force_ram_power`. The +[RAM section of the methodology](methodology.md#ram) gives the full step +function and the override recipe. + +## Where the carbon intensity comes from + +CodeCarbon resolves the grid figure through a six-level ladder, taking the first +level that answers: a value you forced explicitly, then a cloud provider and +region lookup, then a live reading from Electricity Maps if you have configured +a token, then a sub-national region for the handful of countries with regional +data, then a national average, and finally the 475 gCO₂eq/kWh world average. + +The important property is that **the ladder degrades silently**. A cloud region +that is missing from the dataset falls back to the country; an unrecognised +country falls back to the world average. Nothing in the CSV, the API payload or +the emissions figure records which level answered — a live regional reading and +a global fallback produce output of identical shape. If provenance matters for +your use, check the startup logs or set the intensity explicitly. The +[carbon intensity section](methodology.md#carbon-intensity) lists each level, +its data source and its condition. + +## What this page deliberately leaves out + +Sampling is per-machine by default; `tracking_mode="process"` narrows CPU and +RAM attribution to your process, though never the GPU, which is always measured +device-wide. Disk, network and peripherals are outside the measurement boundary +entirely. Both of these change how a number should be read, and both are +covered in [Methodology](methodology.md). + +## Where to go next + +CodeCarbon is useful and its estimates are imperfect, and both of those are +true at the same time. The honest way to use it is to know which of the two you +are holding. + +- **Evaluating whether to trust the tool?** + [Methodology](methodology.md) is the full chain, constant by constant, with + every fallback condition stated and every value traced to its source line. +- **Want to know how far off you are?** + [Accuracy and validation](accuracy.md) reports measured deviations between + the estimation path and hardware counters, plus the known gaps. +- **Want the largest single improvement available to you?** + On Linux, make the RAPL counters readable. That converts your CPU number from + a model into a measurement, and it is a one-time setup: + [Enable RAPL](../how-to/enable-rapl.md). +- **Citing CodeCarbon in a paper or a report?** + [References](references.md) holds the bibliography, including the primary + literature on RAPL's own accuracy. diff --git a/docs/index.md b/docs/index.md index 5abc05cba..d0203dc45 100644 --- a/docs/index.md +++ b/docs/index.md @@ -77,6 +77,7 @@ A single datacenter can consume large amounts of energy to run computing code. A | [Troubleshooting](how-to/troubleshooting.md) | Fix warnings and numbers that look wrong | | [API Reference](reference/api.md) | Full parameter documentation | | [Framework Examples](how-to/scikit-learn.md) | Example usage patterns | +| [How CodeCarbon works](explanation/how-it-works.md) | The mental model in one page | | [Methodology](explanation/methodology.md) | How emissions are calculated | | [Accuracy and validation](explanation/accuracy.md) | How accurate the numbers are, and why | | [Alternatives comparison](explanation/alternatives.md) | CodeCarbon vs other carbon tracking tools | diff --git a/mkdocs.yml b/mkdocs.yml index 5a1ace21b..a0b6d7bf1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -186,6 +186,7 @@ nav: - Agent Instructions: how-to/agent-instructions.md - Security Policy: how-to/security.md - Explanation: + - How CodeCarbon Works: explanation/how-it-works.md - Why CodeCarbon: explanation/why.md - When to Use CodeCarbon vs EcoLogits: explanation/when-to-use.md - CodeCarbon vs Alternatives: explanation/alternatives.md From 71dbe06af6cf74fd653e75cd67f3367c521c440a Mon Sep 17 00:00:00 2001 From: David Berenstein Date: Thu, 13 Aug 2026 08:34:25 +0200 Subject: [PATCH 2/2] docs: credit AMDSMI alongside NVML in the GPU row AMD GPUs are read through AMDSMI in codecarbon/core/gpu_amd.py, so 'Nvidia only' understated the measured case. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanation/how-it-works.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/how-it-works.md b/docs/explanation/how-it-works.md index 535bab0f7..69f9156bb 100644 --- a/docs/explanation/how-it-works.md +++ b/docs/explanation/how-it-works.md @@ -35,7 +35,7 @@ number, and the thing most likely to be assumed rather than checked. |---|---|---| | **CPU** | Measured. Hardware energy counters via RAPL on Linux, the Energy Meter Interface on Windows 11, or `powermetrics` on macOS. | **Modelled** from CPU load and a table lookup of your processor's TDP — or, if the model is unrecognised, a flat guess. | | **RAM** | **Always modelled.** There is no RAM power counter on any supported platform. CodeCarbon guesses your DIMM count from total memory and assigns watts per DIMM. | — | -| **GPU** | Measured. NVML counters read directly from the Nvidia device. | Not counted. Without NVML there is no GPU estimate — the figure is simply absent. | +| **GPU** | Measured. Energy counters read directly from the device — NVML on Nvidia, AMDSMI on AMD. | Not counted. Without a supported GPU library there is no GPU estimate — the figure is simply absent. | The consequence is worth stating outright: **the same column in the same CSV can be a hardware reading on one machine and an educated guess on another.** A run