Api thermal heuristic

[Juliette-Gerbaux]

Process ID

Process: GP-01

Description

Adds an integer-strategy field on components, letting a component choose how its model's integer/binary variables are built:

• exact (default, unchanged behavior) — kept as MILP.
• relaxed — relaxed to continuous.
• heuristic (+ heuristic-id) — relaxed to continuous for a first solve, then refined by a built-in heuristic (fast or accurate) that computes tighter bounds from that first solve, followed by an automatic second solve. Triggered transparently by SimulationSession when at least one component uses integer-strategy: heuristic.

Each model declares what its chosen heuristic reads from and writes to via a new models[].heuristics section in optim-config.yml (binding fixed heuristic-element names to the model's own parameter/variable ids and bound types). validate_optim_config() checks heuristic-id ↔ heuristics consistency, that every bound id exists on the model with the expected time-dependence, and that heuristic is not combined with resolution.mode: benders-decomposition.

This required a refactor of variable construction in optimization.py: when a model's components are split across relaxed/exact strategy groups, variables are built per-group and then merged into a read-only _MergedGroupVariable view, while a new _linopy_vars_by_component map keeps a reference to each component's real registered linopy Variable so heuristic bound mutations (and solution retrieval, via the new get_component_variable/get_variable_solution) reach the solver correctly instead of silently landing on a detached xr.concat copy.

Impact Analysis

Modules affected: optim_config/ (new HeuristicConfig, IntegerStrategy parsing/validation), study/ (integer_strategy field on ComponentSchema, system.py), simulation/ (optimization.py variable-building refactor, new heuristic_runner.py and thermal_heuristic.py, SimulationSession two-pass solve, simulation_table.py).

Solver output values: Not expected to change for existing configs — integer-strategy defaults to exact, which preserves current variable construction and the single-solve flow. Values only change for components that newly opt in to relaxed or heuristic, which is the intended effect of the feature.

Checklist

• Unit tests pass (pytest)
• Type checking passes (mypy)
• Formatting passes (black, isort)
• pyproject.toml version bumped if applicable
• AGENTS.md reviewed for impact and updated if needed

[tbittar]

We may flag all e2e heuristic test so that we are able to deactivate them easily from the CI at some point (if they get too long)

[tbittar]

Fix solution retrieval, window size in fast heuristic bugs (b96b782)

Follow-up commit addressing 4 issues surfaced by /code-review on this branch:

1. Root cause: solution reads keyed by an ambiguous merged-variable name
For a model that splits an INTEGER/BINARY variable across relaxed and exact integer_strategy groups, optimization.py registers two real linopy.Variables but merges them into a synthetic xr.concat-ed copy for the general linopy_vars lookup dict. That copy's .name arbitrarily reflects only one of the two real registered names. Anything that read solved values via linopy_model.solution[<name>] (heuristic variable-solution inputs, sequential-mode carry-over extraction, and the simulation table's output/extra-output collectors) would silently get NaN or drop the other group's components.

Fixed by adding OptimizationProblem.get_variable_solution(model_id, var_name), which reads .solution directly off the real per-component-registered variables (_linopy_vars_by_component) and reassembles them — the same mechanism already used for safe bound mutation via get_component_variable. Rewired all affected call sites in heuristic_runner.py, session.py, and simulation_table.py.

2. Heuristics/second solve ran before checking the first solve's status
SimulationSession._run_block applied heuristics and re-solved unconditionally before ever checking whether the first solve reached optimality. Moved the status check to run immediately after the first solve (via a small _check_solved helper), so a failed first solve fails fast instead of running the heuristic step against a non-optimal or missing solution.

3. Fast heuristic crashed on zero minimum durations
find_min_generation_fast computed window_size = max(min_up_duration, min_down_duration), which is 0 for a cluster with no minimum up/down time, and used it as a range() step — raising ValueError: range() arg 3 must not be zero. Clamped to max(..., 1), which degenerates correctly to per-timestep processing.

4. Minor: missing space in the solve-failure error message.

Also updated the FakeProblem test doubles in test_simulation_table_{accessor,export,mock}.py to implement get_variable_solution, matching the new interface.

Verification: full suite green (605 passed, 1 xfailed), mypy clean on all touched files.

[tbittar]

This is weird to parse the optim config file into the runner. why not enriching the Optimconfig class with the heuristic config, then simply use the optim config object (or its heuristics attribute here) ?

[Juliette-Gerbaux]

This will be treated in another PR.

[tbittar]

It seems some problems are too large to use Xpress in CI... use highs instead