From 304e378d8d350f9cc209023eb189202408632fc3 Mon Sep 17 00:00:00 2001 From: David Berenstein Date: Wed, 12 Aug 2026 23:28:58 +0200 Subject: [PATCH 1/3] docs: restructure three explanation pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the 165-line raw machine dumps in rapl.md into a clearly marked appendix so the explanation reads end to end. Retitle power-estimation.md to "From Energy Counters to Power" — the old title promised the TDP estimation model and delivered counter-to-power derivation. File path unchanged so external URLs keep working. Relabel model-comparisons.md: the numbers come from Azure tooling, not CodeCarbon. Provenance moved to a warning at the top and the nav entry moved out of Explanation. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanation/model-comparisons.md | 11 +++- docs/explanation/power-estimation.md | 9 ++- docs/explanation/rapl.md | 84 ++++++++++++++------------- docs/how-to/enable-rapl.md | 2 +- docs/how-to/troubleshooting.md | 2 +- mkdocs.yml | 4 +- 6 files changed, 67 insertions(+), 45 deletions(-) diff --git a/docs/explanation/model-comparisons.md b/docs/explanation/model-comparisons.md index 084c869c9..9fea04279 100644 --- a/docs/explanation/model-comparisons.md +++ b/docs/explanation/model-comparisons.md @@ -1,4 +1,13 @@ -# Model Comparisons {#model_examples} +# Model Comparisons (Third-Party Data) {#model_examples} + +!!! warning "These numbers were not produced by CodeCarbon" + + Every figure and chart on this page comes from published third-party + research that used **Microsoft Azure cloud tooling** to estimate emissions + (see [References](#references)). They are reproduced here only as an + illustration of the orders of magnitude involved in model training. + CodeCarbon measures differently and will report different values — see + [Methodology](methodology.md) for what CodeCarbon actually does. The following table shows the different electricity consumption of popular NLP and Computer Vision models: diff --git a/docs/explanation/power-estimation.md b/docs/explanation/power-estimation.md index b56880429..5bbf558d5 100644 --- a/docs/explanation/power-estimation.md +++ b/docs/explanation/power-estimation.md @@ -1,4 +1,11 @@ -# How Power Estimation Works in CodeCarbon +# From Energy Counters to Power + +!!! info + + This page explains how CodeCarbon derives **power** (Watts) from **energy** + counters. If you are looking for how CodeCarbon estimates power for hardware + that has no energy counter (TDP registry, constants, CPU load), see + [Methodology](methodology.md). CodeCarbon tracks energy consumption by periodically querying the underlying hardware interfaces (e.g., RAPL for Intel CPUs, NVML for NVIDIA GPUs, AMDSMI for AMD GPUs) or by falling back on constant power models for non-supported hardware (such as generic CPU or RAM matching). diff --git a/docs/explanation/rapl.md b/docs/explanation/rapl.md index eb6d37e21..832bb1560 100644 --- a/docs/explanation/rapl.md +++ b/docs/explanation/rapl.md @@ -148,7 +148,51 @@ Measurements," (K. N. Khan, M. Hirki, T. Niemi, J. K. Nurminen, and Z. Ou, ACM Trans. Model. Perform. Eval. Comput. Syst., vol. 3, no. 2, pp. 1--26, Apr. 2018, doi: 10.1145/3177754.) -## RAPL Measurements: Real-World Examples +## Key Takeaways for RAPL Measurements + +1. **CodeCarbon defaults to package domains**: This provides the most + reliable and consistent measurements that match CPU TDP + specifications. Package domains update correctly under load across + all Intel generations. +2. **psys can be unreliable**: While `psys` provides total platform + power, it: + - Can report higher values than expected (includes chipset, PCIe, + etc.) + - May not include all CPU components on older Intel systems : on + some computers, `psys` is lower than `package`. + - So it is disabled by default, you can enable it with + `prefer_psys=True` if desired +3. **Avoid summing overlapping domains**: Never sum psys + package + + core + uncore. They are hierarchical and overlapping. This causes + 2-3x over-counting! +4. **Domain hierarchy**: + - psys ⊃ package ⊃ {core, uncore} + - Correct: Use package alone (CodeCarbon default) OR psys alone + (with prefer_psys=True) + - Wrong: Sum multiple levels +5. **Interface deduplication**: The same domain may appear in both + `intel-rapl` (MSR) and `intel-rapl-mmio` interfaces. CodeCarbon + automatically deduplicates, preferring MMIO. +6. **DRAM measurement**: CodeCarbon does not include DRAM domains by + default (`include_dram=False`) for CPU hardware measurement. Set + `include_dram=True` to measure CPU package + DRAM domains. +7. **Platform-specific behavior**: + - Intel modern: package or psys (with prefer_psys=True) + - Intel older: package-0 for CPU only + - AMD: Sum all package-X-die-Y for multi-die CPUs +8. **Limitations**: RAPL does NOT measure: + - Discrete GPUs (use nvidia-smi/rocm-smi) + - SSDs, peripherals, fans + - Actual DRAM chips, we still have to investigate on this point + - Complete system power (use wall meter for accuracy) + +## Appendix: raw measurements from three machines + +!!! note + + Everything below is raw annotated output collected from three real machines. + It is kept as evidence for the domain-selection rules above; you do not need + to read it to understand how CodeCarbon picks RAPL domains. Choosing the right metric to track CPU power consumption depends on CPU hardware and available domains. Below are measurements from different @@ -314,41 +358,3 @@ Analysis: - `core` domain reports very low values (unclear if included in package) - Package measurements are generally reliable for total CPU power - -## Key Takeaways for RAPL Measurements - -1. **CodeCarbon defaults to package domains**: This provides the most - reliable and consistent measurements that match CPU TDP - specifications. Package domains update correctly under load across - all Intel generations. -2. **psys can be unreliable**: While `psys` provides total platform - power, it: - - Can report higher values than expected (includes chipset, PCIe, - etc.) - - May not include all CPU components on older Intel systems : on - some computers, `psys` is lower than `package`. - - So it is disabled by default, you can enable it with - `prefer_psys=True` if desired -3. **Avoid summing overlapping domains**: Never sum psys + package + - core + uncore. They are hierarchical and overlapping. This causes - 2-3x over-counting! -4. **Domain hierarchy**: - - psys ⊃ package ⊃ {core, uncore} - - Correct: Use package alone (CodeCarbon default) OR psys alone - (with prefer_psys=True) - - Wrong: Sum multiple levels -5. **Interface deduplication**: The same domain may appear in both - `intel-rapl` (MSR) and `intel-rapl-mmio` interfaces. CodeCarbon - automatically deduplicates, preferring MMIO. -6. **DRAM measurement**: CodeCarbon does not include DRAM domains by - default (`include_dram=False`) for CPU hardware measurement. Set - `include_dram=True` to measure CPU package + DRAM domains. -7. **Platform-specific behavior**: - - Intel modern: package or psys (with prefer_psys=True) - - Intel older: package-0 for CPU only - - AMD: Sum all package-X-die-Y for multi-die CPUs -8. **Limitations**: RAPL does NOT measure: - - Discrete GPUs (use nvidia-smi/rocm-smi) - - SSDs, peripherals, fans - - Actual DRAM chips, we still have to investigate on this point - - Complete system power (use wall meter for accuracy) diff --git a/docs/how-to/enable-rapl.md b/docs/how-to/enable-rapl.md index ea0f0c9db..4cd041dda 100644 --- a/docs/how-to/enable-rapl.md +++ b/docs/how-to/enable-rapl.md @@ -197,7 +197,7 @@ volumes: To understand RAPL in detail, including domain hierarchy, double-counting issues, and CodeCarbon's domain selection strategy, see: - [RAPL Metrics Explanation](../explanation/rapl.md) — Technical details on how RAPL works -- [CodeCarbon Power Estimation](../explanation/power-estimation.md) — How CodeCarbon uses RAPL data +- [From Energy Counters to Power](../explanation/power-estimation.md) — How CodeCarbon turns RAPL energy counters into power ## Next Steps diff --git a/docs/how-to/troubleshooting.md b/docs/how-to/troubleshooting.md index a4624f47c..769837be8 100644 --- a/docs/how-to/troubleshooting.md +++ b/docs/how-to/troubleshooting.md @@ -115,7 +115,7 @@ and treat comparisons across different machines with caution. Comparisons between two runs on the *same* machine remain meaningful, because the same approximation applies to both. -See [Power Estimation](../explanation/power-estimation.md) for what the +See [From Energy Counters to Power](../explanation/power-estimation.md) for what the estimation model does, and [Accuracy and validation](../explanation/accuracy.md) for how the backends compare. diff --git a/mkdocs.yml b/mkdocs.yml index e8aa19047..71159ce13 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -192,12 +192,12 @@ nav: - Methodology: explanation/methodology.md - Accuracy and Validation: explanation/accuracy.md - RAPL Metrics: explanation/rapl.md - - Power Estimation: explanation/power-estimation.md - - Model Comparisons: explanation/model-comparisons.md + - From Energy Counters to Power: explanation/power-estimation.md - FAQ: explanation/faq.md - Reference: - API Reference: reference/api.md - Output Formats: reference/output.md - CLI Reference: reference/cli.md + - Model Comparisons (Third-Party Data): explanation/model-comparisons.md - Track GenAI API Calls (EcoLogits) ↗: https://ecologits.ai/latest/?utm_source=codecarbon&utm_medium=docs - Join Our Discord 💬 ↗: https://discord.gg/GS9js2XkJR From 0fe3534589d78171198434707f5658cdc0b37d0f Mon Sep 17 00:00:00 2001 From: David Berenstein Date: Wed, 12 Aug 2026 23:30:53 +0200 Subject: [PATCH 2/3] docs: fix stale psys claims in rapl.md The three worked examples asserted CodeCarbon "uses psys only", which contradicted the Key Takeaways section on the same page. Verified against core/cpu.py: rapl_prefer_psys defaults to False (:453) and psys is used only when explicitly enabled (:694), with the else path logging "psys domain detected but not used" (:727). Key Takeaways was right. Each example now states the default package-domain behaviour and marks the psys arithmetic as requiring rapl_prefer_psys=True. Also reworded the open "we still have to investigate" note on DRAM as a stated limitation. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanation/rapl.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/explanation/rapl.md b/docs/explanation/rapl.md index 832bb1560..e4d44c1ce 100644 --- a/docs/explanation/rapl.md +++ b/docs/explanation/rapl.md @@ -183,7 +183,8 @@ Ou, ACM Trans. Model. Perform. Eval. Comput. Syst., vol. 3, no. 2, pp. 8. **Limitations**: RAPL does NOT measure: - Discrete GPUs (use nvidia-smi/rocm-smi) - SSDs, peripherals, fans - - Actual DRAM chips, we still have to investigate on this point + - Actual DRAM chips — the `dram` domain reports memory-controller + power, and CodeCarbon excludes it by default (`rapl_include_dram=False`) - Complete system power (use wall meter for accuracy) ## Appendix: raw measurements from three machines @@ -198,6 +199,15 @@ Choosing the right metric to track CPU power consumption depends on CPU hardware and available domains. Below are measurements from different systems showing the importance of avoiding double-counting. +!!! warning "The two Intel walkthroughs were collected with `rapl_prefer_psys=True`" + + Their `psys` readings and the "use psys only" annotations inside the code + blocks describe that non-default configuration. With the default + `rapl_prefer_psys=False`, CodeCarbon uses the **package** domain(s) instead: + psys is detected and explicitly skipped (`codecarbon/core/cpu.py:694-731`). + The package figure is given alongside psys in each block, so you can read + the default behaviour off the same numbers. + We investigate RAPL on various architectures : - 2017 Gaming computer with AMD Ryzen Threadripper 1950X @@ -227,8 +237,9 @@ RAPL domains (individual readings): ✅ CORRECT: Use psys only = 6.66W (matches battery discharge) ``` -**CodeCarbon behavior**: Uses **psys only** (6.66W) to avoid -double-counting. +**CodeCarbon behavior**: by default uses **package-0 only** (3.85W) — never a +sum of overlapping domains. With `rapl_prefer_psys=True` it uses **psys only** +(6.66W), which is what matches the battery discharge rate here. **Under Load (stress-ng)**: @@ -244,8 +255,9 @@ RAPL domains: ✅ CORRECT: Use psys only = 24.69W (close to battery discharge) ``` -**CodeCarbon measurement**: 22W using psys (accurate, within expected -range) +**CodeCarbon measurement**: 22W using psys, with `rapl_prefer_psys=True` +(accurate, within expected range). The default configuration would have +reported the package-0 figure (21.35W) instead. **Note**: The package-0 measurement (21.35W) excludes some platform components like chipset and PCIe that are included in psys (24.69W). @@ -289,11 +301,10 @@ Analysis: - Core power (14.00W) matches the CPU TDP spec (15W) ``` -**CodeCarbon behavior**: Uses **psys only** (29.97W) for accurate total -platform measurement. - -**Legacy behavior (before v2.x)**: Would have measured only package-0 -(15.73W), missing ~14W of platform power! +**CodeCarbon behavior**: by default uses **package-0 only** (15.73W). With +`rapl_prefer_psys=True` it uses **psys only** (29.97W), the total platform +figure — roughly 14W more, because psys also covers chipset, PCIe and other +platform components that are not CPU power. ### Desktop: AMD Ryzen Threadripper 1950X (16-Core, 32 threads, Multi-die) From c746cb33bc65c41d0d0ee5ca5a7109c2b1f778a8 Mon Sep 17 00:00:00 2001 From: David Berenstein Date: Wed, 12 Aug 2026 23:38:38 +0200 Subject: [PATCH 3/3] docs: flag AMD multi-die summing as open The Threadripper walkthrough presents a summed per-die figure as correct. Whether the two package-X-die-Y domains are independent or mirror the same counter is unresolved, so the page now links issue #1379 instead of vouching for the result. Observed numbers left untouched as evidence. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanation/rapl.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/explanation/rapl.md b/docs/explanation/rapl.md index e4d44c1ce..7c12c19d9 100644 --- a/docs/explanation/rapl.md +++ b/docs/explanation/rapl.md @@ -179,7 +179,10 @@ Ou, ACM Trans. Model. Perform. Eval. Comput. Syst., vol. 3, no. 2, pp. 7. **Platform-specific behavior**: - Intel modern: package or psys (with prefer_psys=True) - Intel older: package-0 for CPU only - - AMD: Sum all package-X-die-Y for multi-die CPUs + - AMD: Sum all package-X-die-Y for multi-die CPUs — this describes what + the code currently does; whether summing per-die domains is correct is + under review in + [issue #1379](https://github.com/mlco2/codecarbon/issues/1379) 8. **Limitations**: RAPL does NOT measure: - Discrete GPUs (use nvidia-smi/rocm-smi) - SSDs, peripherals, fans @@ -220,6 +223,15 @@ Power plug measure when idle (10% CPU): 125 W package-0-die-0: 68 W | package-0-die-1: 68 W | CodeCarbon: 137 W ``` +!!! warning "Multi-die summing is under review" + + On Linux, CodeCarbon sums every domain whose name contains `package`, so the + two per-die domains above are added together. Whether those domains report + independent power or mirror the same counter is unresolved, and it decides + whether 137 W is right or double the real figure. Tracked in + [issue #1379](https://github.com/mlco2/codecarbon/issues/1379). The numbers + here are left exactly as observed — they are the evidence behind that issue. + ### Laptop: Intel(R) Core(TM) Ultra 7 265H (TDP 28W) **Idle Measurements**: