[FBumann]

Prompt: Add stacked PRs about the new things we discussed

The discussion it refers to began with: "What about basis, warmstaer initial solution etc? What kind of things would be reasonable to add to boost sovler performance?"

Note

The following content was generated by AI.

solve(start=earlier_answer) starts an LP from the basis an earlier answer ended on. The basis is matched by coordinate, so a master that gained a cut starts where it was. On the Benders bench this saved 66–73% of the simplex iterations. This is #1869 part 3 and closes the gap #382 left.

What it is

• Matched by coordinate (readback.matched_basis). A coordinate both builds hold keeps its status. A column only the new build holds starts at a bound. A row only the new build holds starts basic, so a gained cut enters without moving the vertex. A declaration whose dims changed is new.
• Made takeable. _counted makes it one basic entry per row: a surplus leaves from the last basic columns, and a shortfall is made up by the last nonbasic rows. settled (now shared with the read side) then puts every nonbasic column at a bound the new build has. Each solver repairs a singular basis itself.
• Any answer, any solver: live, from load_result, or from an archive, and read on one solver to warm another, because feat(api): a solve or a sweep asked for outputs={'variable_basis', 'constraint_basis'} reads the basis it ended on, in the same words on every solver #1876's statuses are one vocabulary. The answer must carry both basis outputs. The refusal names the outputs= to solve it with, before the solver loads.
• A mixed-integer model is refused: it has no basis to start from. The PR stacked on this one makes start= on a MIP take values instead.
• The sink family is simpler. WarmStart, warm_start(), and the refusal of another solver's statuses are gone. A member now implements _warm(basis) in its own statuses and _start(values) for an incumbent, and the base checks spans. No caller used warm_start() outside tests and the bench.

Measured: bench/warm_payoff.py, the Benders master

Method: python -m bench.warm_payoff xs s m --wall, HiGHS, at ecdefd1. At every rebuild the master is solved cold, and with start= the previous started answer (keep='nothing' both, so each solve has a fresh solver). Simplex iterations are read off HiGHS and are deterministic. Wall seconds count the whole solve call, including reading the basis back and matching it.

generators	rebuilds	iterations cold	iterations started	saved	wall cold	wall started
6	28	112	35	68.8%	0.099 s	0.339 s
100	34	283	97	65.7%	0.164 s	0.465 s
1,000	47	856	235	72.5%	0.809 s	0.839 s

The wall columns were taken at load averages between 1.7 and 2.0 on 4 cores. They are a direction, not a measurement: below 1,000 generators the extra work of a started solve (reading the basis back and matching it, a polars join per declaration, about 9 ms a solve here) costs more than the iterations save. A run at 10,000 generators reached the 30-minute limit of a background job before it printed, so it is not in the table. A wall measurement on an idle machine is still owed before the how-to claims time. The conclusion that goes into the warm-start how-to is the iteration count only.

Verification

Gates: ruff check ., ruff format --check ., pyrefly check, the full suite (pytest -n auto, with HiGHS, Gurobi and Xpress installed), pytest bench/test_harness.py -k started_master, test_docstring_links.py, test_assertions.py, zensical build --strict.

tests/test_start.py covers the following, on every sink unless a row says otherwise:

• An unchanged model started from its own answer does no simplex work.
• A model that gained or lost snapshots takes fewer iterations than cold and reaches the same objective.
• A constraint gained: the Warm starts: rebuild-over-edit is only cheap if the solve is warm #382 case.
• HiGHS's basis starts Gurobi and Xpress.
• A saved answer and an archived one start a solve.
• A declaration whose dims changed starts as new.
• The refusals: an answer without its basis, one that ended on no basis, a MIP, a closed answer.
• settled and _counted, case by case.

tests/test_warm_start.py's sink half moved onto warm(basis) and start(values). Its test of the other-solver refusal is gone with the refusal, and test_start.py asserts the opposite now.

Mutation table, from python -m tools.mutate against the full suite, except the rows marked by hand, which were taken with its three precautions (a clean tree, git checkout -- to restore, __pycache__ dropped on both sides):

guard	result
a mixed-integer model takes no basis (engine.py:228-229)	caught
a declaration whose dims changed is new (readback.py:362-363)	caught
an answer without its basis refused (result.py:660-665)	caught
sps.solve checks the start before the build (api.py:563-564)	caught
a basis that does not span the model refused (base.py:171-172)	caught
a column at equal bounds is fixed (base.py:332)	caught
a nonbasic column moves to a bound it has (base.py:333)	caught
a surplus leaves from the columns (by hand: if surplus > 0 → if False)	caught (1 failed)
a shortfall enters as rows (by hand: elif surplus < 0 → elif False)	caught (1 failed)
Xpress: a nonbasic row names its slack's side (by hand: rows mapped as columns)	still green. A probe was added (test_a_basis_is_loaded_in_the_row_statuses_xpress_itself_reports), and it is green too: Xpress puts a nonbasic slack at its one finite bound when it loads the basis, whichever side it was given. So the side cannot be observed. The mapping stays the one Xpress reports, and the probe holds the rest of the round trip.

The tree was clean after each run.

Deliberately not done

• No start= on solve_over: keep='progress' already carries a sweep's work from slice to slice. A sweep that rebuilds between slices is a separate case.
• No repair choice beyond the count. Which basic column leaves is arbitrary, and each solver repairs a singular basis. A smarter choice waits for a model that shows it matters.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GLBvwp6NU7YjszFz5QMRf1

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #35014931 | 📁 Comparing 70506b4 against latest (9e47978)

  🔍 Preview build  

10 files changed · ± 10 modified

± Modified

• tables/index.html
• about/architecture/index.html
• about/changelog/index.html
• howto/archiving/index.html
• howto/debug/index.html
• howto/warm-start/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/internals/index.html
• reference/sweeps/index.html

[codspeed]

Merging this PR will not alter performance

✅ 67 untouched benchmarks
⏩ 307 skipped benchmarks¹

---

_{Comparing claude/festive-carson-8x46sq-warm (70506b4) with claude/festive-carson-8x46sq-basis (452789c)}

Footnotes

1. 307 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩