Skip to content

Redraw docs/images/cpu_fallback.png — it shows a CPU fallback ladder the code does not implement #1378

Description

@davidberenstein1957

docs/images/cpu_fallback.png illustrates the CPU backend selection ladder. That ladder was corrected in #1377 after it was found not to match codecarbon/core/resource_tracker.py, and the diagram illustrates the old, incorrect version. #1377 therefore removed the reference to it from docs/explanation/methodology.md rather than ship a diagram contradicting the prose beside it.

The image file is still in the repository and is now unreferenced. It should be redrawn rather than quietly orphaned — a decision tree is the right form for this content, and the table that replaced it is harder to scan.

What the diagram should show

The real selection order, from resource_tracker.py:249-279, first match wins:

  1. force_cpu_power set → fixed constant. This is the branch most worth making visually obvious: it skips every platform backend, so RAPL is not consulted even when available (:255-260, guard at :272).
  2. force_mode_cpu_load set, psutil present, TDP known → cpu_load (:263-270)
  3. Linux + RAPL readable → intel_rapl (:223-225)
  4. macOS + Apple Silicon + psutilcpu_load (:228-230) — note this precedes powermetrics
  5. macOS + Apple Silicon + no psutil + powermetrics → powermetrics (:231-233)
  6. macOS + Intel + Power Gadget → intel_power_gadget (:234-236)
  7. macOS + Intel + powermetrics → powermetrics (:237-239)
  8. Windows + EMI → windows_emi (:241-243)
  9. Windows + Power Gadget → intel_power_gadget (:244-246)
  10. otherwise, psutil present → cpu_load (:179-190, :201-212)
  11. otherwise → constant (:191-198, :213-218)

Two things the old diagram got wrong and the new one must get right:

  • cpu_load is preferred over constant whenever psutil is present. constant mode is the no-psutil path only.
  • On Apple Silicon, powermetrics is effectively unreachable, because step 4 fires before step 5 and psutil is a hard dependency.

Also worth showing

The TDP resolution that feeds the two estimation modes (core/cpu.py:1002-1032):

  • registry hit → registry TDP
  • model detected, absent from registry, psutil present → threads × DEFAULT_POWER_PER_CORE (4 W, cpu.py:29)
  • otherwise → POWER_CONSTANT (85 W, hardware.py:23)

and that the resulting TDP is consumed by two different curves — cubic with a 10% floor in machine mode, linear in process mode (hardware.py:287-288 and :346).

That may be more than one diagram can carry legibly; splitting into "which backend" and "how the TDP becomes watts" is fine.

Acceptance

  • The diagram matches resource_tracker.py at the commit it lands on.
  • It is referenced from docs/explanation/methodology.md#which-backend-gets-chosen.
  • Ideally it is generated from a text source (Mermaid or Graphviz) checked into the repo, so the next correction to the ladder is a diff rather than a redraw in an image editor.

Context: #1377.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions