No user-facing documentation of what the fast/accurate thermal heuristics actually compute

[aoustry]

Summary

The docs cover how to declare thermal heuristics in optim-config.yml, but nowhere explain what the fast and accurate heuristics actually do — their algorithms, the two-pass solve mechanism they plug into, or their known boundary-condition caveats. The only place this logic is currently explained is in code docstrings, which a study author configuring optim-config.yml is unlikely to read.

What exists today

• docs/user-guide/optim-config.md (§"heuristics — integer strategy and thermal heuristics") documents the config schema: how to set integer-strategy: heuristic, wire inputs/outputs, and the fixed heuristic-element names each built-in heuristic expects. It's a wiring reference only.
• docs/user-guide/building.md mentions HeuristicId.FAST only as a usage example for setting integer_strategy on a component.
• AGENTS.md has a one-line pointer to find_min_generation_fast / find_num_units_accurate in thermal_heuristic.py, with no mechanism description.

What's missing

No doc page explains, in terms a study author can use without reading the source:

• The two-pass solve mechanism (heuristic_runner.py): first LP solve with the component relaxed to continuous, heuristic computes tightened bounds from that solution, second solve enforces them.
• What fast computes: the sliding-window / offset-search logic that derives a minimum generation floor from the relaxed generation-power timeseries (find_min_generation_fast, thermal_heuristic.py:74-157).
• What accurate computes: the small LP enforcing true min-up/min-down dynamics on unit counts (find_num_units_accurate, thermal_heuristic.py:160-287), including that its min-up/min-down constraints assume a cyclic (wrap-around) horizon — a caveat a user would need to know before combining it with resolution.mode: sequential-subproblems (see Accurate thermal heuristic's cyclic min-up/down model is unsound in sequential-subproblems mode #268).
• General guidance on when to prefer fast vs accurate (accuracy/cost trade-off).

This logic is currently documented only in the docstrings of find_min_generation_fast, find_num_units_accurate (thermal_heuristic.py), and the module docstring of heuristic_runner.py.

Suggested scope

Add a user-guide page (or a new section in optim-config.md) explaining the two heuristics' mechanics and caveats, cross-linked from the existing config-schema section. Not prescribing exact placement/format here — just tracking that the gap exists.

Related

• Accurate thermal heuristic's cyclic min-up/down model is unsound in sequential-subproblems mode #268 (cyclic assumption vs. sequential-subproblems) — documenting the accurate heuristic's algorithm would naturally surface this caveat to users.