docs: restructure three explanation pages

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:

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). 
 

docs/explanation/rapl.md

@@ -148,12 +148,69 @@ 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 — 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
+    -   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
+
+!!! 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
 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
@@ -166,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**:
@@ -183,8 +249,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)**:
 
@@ -200,8 +267,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).
@@ -245,11 +313,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)
 
@@ -314,41 +381,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)

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
 

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.
 

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