docs: correct the estimation chain reference

docs/explanation/accuracy.md

@@ -24,7 +24,7 @@ is not a whole-facility footprint, and it is not meant to be one.
 
 CodeCarbon prefers hardware energy counters and falls back to estimation when no
 counter is readable. The fallback order is documented in
-[Methodology → CPU metrics priority](methodology.md#cpu-metrics-priority).
+[Methodology → CPU metrics priority](methodology.md#which-backend-gets-chosen).
 
 | Backend | How it works | Agreement with a reference | When it is used |
 |---|---|---|---|
@@ -34,7 +34,7 @@ counter is readable. The fallback order is documented in
 | macOS `powermetrics` | System power reporting | Not yet measured against an external reference | macOS, Intel and Apple Silicon |
 | Windows EMI | Energy Meter Interface | Not yet measured against an external reference | Windows 11, where the platform exposes it |
 | Intel Power Gadget | Vendor tool, deprecated upstream | Not yet measured | Legacy path |
-| CPU load × TDP | Estimates power from CPU utilisation against the TDP listed in `cpu_power.csv` | See the profiling results below: on the machines profiled, the estimate deviated from RAPL by roughly −60% to +90% depending on CPU and load point | Fallback when no CPU counter is available |
+| CPU load × TDP | Estimates power from CPU utilisation against the TDP listed in `cpu_power.csv`. Two different curves, [selected by `tracking_mode`](methodology.md#the-two-cpu_load-models) | See the profiling results below: in **machine mode**, on the machines profiled, the estimate deviated from RAPL by roughly −60% to +90% depending on CPU and load point. Process mode is uncharacterised | Fallback when no CPU counter is available |
 | Default watts per thread | Estimates from thread count alone | Not characterised; this is the least accurate path | Last resort, when the CPU model is absent from `cpu_power.csv` |
 
 ### The CPU load × TDP fallback, measured
@@ -45,6 +45,20 @@ CodeCarbon would have produced. The raw sweeps live in
 `codecarbon/data/hardware/cpu_load_profiling/` and are plotted in
 `examples/compare_cpu_load_and_RAPL.ipynb`. Runs are dated January 2025.
 
+!!! warning "These figures are machine mode only"
+
+    The profiling script constructs its tracker with `force_mode_cpu_load=True`
+    and no `tracking_mode` argument (`compare_cpu_load_and_RAPL.py:289-292`), so
+    every number below was gathered under the default
+    `tracking_mode="machine"`.
+
+    That matters because `cpu_load` mode uses a **different power model** in
+    process mode — linear with no idle floor, rather than cubic with a 10%-of-TDP
+    floor. See
+    [Methodology → The two cpu_load models](methodology.md#the-two-cpu_load-models).
+    **The deviations below do not transfer to `tracking_mode="process"`.** No
+    equivalent profiling has been done for process mode.
+
 Deviation of the estimate from the RAPL reading, over load points above 5%
 (negative means the estimate is lower than RAPL):
 
@@ -63,8 +77,11 @@ for the pair, while RAPL reported about 117 W at full load — the chips are hel
 near their base frequency and never reach the rated figure. On the EPYC 8024P
 the gap is larger still.
 
-**The relationship between load and power is not linear.** CodeCarbon
-interpolates linearly between idle and TDP. Real curves are convex on some parts
+**The assumed load-to-power curve does not match the real one.** In machine
+mode CodeCarbon applies a cubic curve with a 10%-of-TDP floor
+(`hardware.py:287-288`); in process mode it interpolates linearly from zero
+(`hardware.py:346`). Neither shape is fitted to hardware. Real curves are convex
+on some parts
 (the E3-1240 v2 stays under 10 W up to 40% load, so the linear estimate
 overshoots it by well over 100%) and saturate early on others (the Threadripper
 reaches its power ceiling around 65% load, so the estimate *undershoots* at mid

docs/explanation/alternatives.md

@@ -126,7 +126,7 @@ Summarised, since the sections above are organised around other tools:
 
 - **Breadth of measurement backends** with a documented fallback order — RAPL,
   NVML, amdsmi, `powermetrics`, Windows EMI, then TDP-based estimation. See
-  [CPU metrics priority](methodology.md#cpu-metrics-priority).
+  [CPU metrics priority](methodology.md#which-backend-gets-chosen).
 - **Task-level attribution** within a single process.
 - **Offline mode** (`OfflineEmissionsTracker`) for air-gapped machines, with no
   no calls to the CodeCarbon API.

docs/explanation/equivalences.md

@@ -0,0 +1,71 @@
+# Equivalences
+
+The `carbonboard` dashboard translates a project's emissions into three
+everyday comparisons. They are presentation aids, not part of the measurement:
+nothing in the CSV output, the API payload or the emissions calculation depends
+on them.
+
+All three factors live in
+[`codecarbon/viz/data.py`](https://github.com/mlco2/codecarbon/blob/master/codecarbon/viz/data.py)
+and are used by `viz/carbonboard.py` and `viz/carbonboard_on_api.py`.
+
+| Comparison | Factor | Applied as | Source |
+|---|---|---|---|
+| Car travel | **0.409 kg CO₂e per mile** | `emissions_kg / 0.409` → miles driven (`data.py:65`) | US EPA |
+| Television | **0.097 kg CO₂ per hour** | `emissions_kg / 0.097` → hours of TV (`data.py:76`) | unsourced in code |
+| US household | **160.58 kg CO₂ per week** | `emissions_kg / 160.58 × 100` → % of a household-week (`data.py:96`) | US EPA |
+
+## How each factor is derived
+
+The derivations below are reproduced from the docstrings in `viz/data.py`; they
+are the only justification the code carries.
+
+**Car — 0.409 kg CO₂e/mile** (`data.py:54-65`)
+
+```text
+8.89 × 10⁻³ metric tons CO₂ per gallon of gasoline
+  × 1 / 22.0 miles per gallon (car/truck average)
+  × 1 CO₂, CH₄ and N₂O / 0.988 CO₂
+= 4.09 × 10⁻⁴ metric tons CO₂e per mile
+= 0.409 kg CO₂e per mile
+```
+
+This is the US EPA passenger-vehicle figure, so it reflects the US vehicle
+fleet and US fuel. It is not a European or global average, and the unit is
+**miles**, not kilometres.
+
+**Television — 0.097 kg CO₂/hour** (`data.py:67-76`)
+
+Described in the code only as the ratio for "a 32-inch LCD flat screen TV".
+**No source, screen power, or grid intensity is given in the code**, so the
+figure cannot be reproduced from what ships in the repository. Treat it as an
+illustrative round number rather than a defensible factor.
+
+**US household — 160.58 kg CO₂/week** (`data.py:86-96`)
+
+```text
+5.734 t CO₂  electricity
++ 2.06  t CO₂  natural gas
++ 0.26  t CO₂  liquid petroleum gas
++ 0.30  t CO₂  fuel oil
+= 8.35 t CO₂ per home per year
+÷ 52 weeks
+= 160.58 kg CO₂ per week
+```
+
+Again a US EPA figure for total *home energy* use — heating fuels included, not
+electricity alone — and specific to an average US home.
+
+## Caveats
+
+- All three factors are US-centric averages. A reader outside the US should
+  expect the comparison to be directionally useful and quantitatively off.
+- The factors are hardcoded and not versioned against a dated source release,
+  so they drift out of date silently as the underlying EPA figures are revised.
+- They are applied to the emissions total *after* the estimation chain
+  described in the [methodology](methodology.md), so every uncertainty in that
+  chain carries through unchanged.
+
+If you need a comparison you can defend, compute it yourself from the
+`emissions` column of the [CSV output](../reference/output.md) using a factor
+you can cite.

docs/explanation/faq.md

@@ -69,7 +69,7 @@ In a single Python process, the first tracker pays a one-time cost to detect har
 
 ## What hardware does CodeCarbon support?
 
-CodeCarbon supports various CPU architectures, GPUs, and cloud providers. For details on measurement priority and supported hardware, see the [Methodology](methodology.md#cpu-metrics-priority) page.
+CodeCarbon supports various CPU architectures, GPUs, and cloud providers. For details on measurement priority and supported hardware, see the [Methodology](methodology.md#which-backend-gets-chosen) page.
 
 ## How do I report a bug?