feat(api): a solve or a sweep can start from tables of values and basis statuses, and a sweep from an earlier sweep or from the slice before it

[FBumann]

Prompt: Review the R stack with 1878. Look for room for simplification, refactoring, better naming, better seams and if better encapsulation.

Prompt: Id like to unify the start for lp and mip. But we need to find a simple and intuitive api. Users need to be able to pass basis values easily too!

Prompt: I think start on a sweep is prefectly reasonable! And it makes no sense for it to not exist if its availlable on regular solve!

Note

The following content was generated by AI.

start= is one shape for an LP and a mixed-integer model: an earlier answer, or tables keyed by reader (primal, variable_basis, constraint_basis). solve_over also takes an earlier Sweep or 'previous', cut by the axis as a source is. outputs={'basis'} asks for the basis.

The API

start: Result | Start | None                              # solve, Model.solve
start: Result | Sweep | Start | Literal['previous'] | None   # solve_over

• Start is a TypedDict in specsolve.types: {'primal': {name: table}, 'variable_basis': {...}, 'constraint_basis': {...}}. Each table takes every shape a parameter's source takes (feat(api): a mixed-integer solve can start from values, an earlier answer's or any source a parameter takes, matched by coordinate #1878), read by the same reader. Basis tables are read as strings and held to basic, at_lower, at_upper, fixed and superbasic.
• An LP starts from a basis where one is given, else from values. A mixed-integer model starts from values. An LP answer solved without outputs={'basis'} now starts a solve from its primal rather than being refused.
• Values for an LP follow each solver's lp_values. HiGHS uses a complete primal and warns of a partial one. Gurobi warns of either. Xpress warns of a complete one and refuses a partial one, which loadLPSol cannot take. A warning asks the user to report a gain at the issue tracker.
• A sweep's start is cut by its axis, as a source is. A table over the sliced dimension gives each slice its rows: a scenario its scenario's, a window the coordinates it covers, lookahead included, over its local index. A table without it reaches every slice whole. An earlier sweep is its answer, so an archive without kept windows starts a sweep too. Each Slice carries the cut it applied to its sources, and the start goes through the same function.
• A slice its start leaves no row starts from nothing, with a warning. That covers a table short of the slice's key, and an earlier sweep whose slice left no values. A missing start costs time, never the answer, so it no longer refuses the sweep. This changed after review: "For empty tables we should warn, not error".
• 'previous' starts each slice from the answer of the one before it, matched by the slice model's own coordinates (local t for a window). Each slice is solved with its basis for the next to start from, whether or not outputs= asks for it; the answer, the spill and the archive keep only what outputs= asks for. The first slice, and a slice after one that left no values, starts cold. Refused under an executor. A slice read back off a spill starts the next from what the spill holds. (refactor(api): keep= is gone, and a re-solve carries on from where the last solve ended unless start=None says otherwise #1884 changes this.)
• start= combines with keep='solver' only. keep='progress' and keep='nothing' also say what the solve begins from, so the two together are refused, on solve and solve_over.
• outputs={'basis'} replaces {'variable_basis', 'constraint_basis'}. The readers keep their names, and the files stay under variable_basis/ and constraint_basis/.

From the review of #1865–#1878

• The basis vocabulary (BASIS_STATUSES, the BASIS dtype, the codes) moved from the sinks to answer_layout, beside the outputs read back in it.
• The engine matches a start to a Basis or to values and branches on it, rather than returning a closure. It reads an earlier answer through Result._start rather than its private frames.
• Result and Sweep dispatch an output kind explicitly rather than by getattr, and the output readers share one path.
• Each sink's write-back table names the status it maps rather than listing bare codes.
• The spill manifest check compares the key first, then the outputs.
• Result.dual no longer says slacks are not read.

Values for an LP: the probe behind lp_values

A random 300×400 LP (5% density, seed 0), solved once cold and once started from its own optimum, outside specsolve. This is the best case for a values start, one run each, and it was not taken on a machine checked for idleness.

	cold	from the full primal	from half the columns
HiGHS setSolution (simplex iterations)	661	0	661
Gurobi PStart	877	877	—
Xpress loadLPSol	760	760	refused: needs every column

Separately, on HiGHS, DISPATCH at 40 snapshots started from a variable_basis alone (rows left at their default) took 40 iterations against 29 cold. The test asserts only that such a start is taken.

Mutation tables

python -m tools.mutate, scoped to tests/test_start.py (and test_basis, test_warm_start, test_outputs for the first group), rather than the full suite. A guard the subset catches, the full suite catches too.

guard	result
a key that names no reader (sources.py)	caught
a name its reader has no declaration for (sources.py)	caught
a basis status outside the five words (sources.py)	caught
lp_values refused (engine.py)	caught
lp_values no_gain warns (engine.py, body → pass)	caught
nothing the model starts from (engine.py)	caught
a start that lands nowhere (readback.py)	caught
start beside keep progress or nothing (result.py)	caught
a word other than previous (strategy.py)	caught
previous under an executor (strategy.py)	caught
a table over the local index alone (strategy.py)	caught
the warning for a slice its start leaves no row (strategy.py:407-413)	caught
by hand: that slice's empty start passed on rather than none	caught (3 failed)
a slice after one with no values starts cold (strategy.py)	caught
a word on one solve (api.py, taken before the merge in engine.py)	caught
a constraint named as a variable keeps its own basis (by hand: both halves in one directory)	caught
a slice keeps only the outputs asked for (by hand: every output the result holds copied)	caught

Three guards first survived, and each got a purpose-built probe before the table was taken: the up-front check on a sweep's start and the up-front windows check, which now spy on the build, and the outputs filter, whose test now looks for a basis in the spill. The tree was clean after every run.

Verification

• ruff check ., ruff format --check ., pyrefly check, and the full suite (pytest -n 4, with HiGHS, Gurobi and Xpress): 5301 passed, 0 failed, on the tree of the last source change. The collected tests (5867) are the same as at the commit before it. An earlier run on the merge reported 5311 passed; I have not found why the two counts differ.
• On ef01170 (the empty-start warning): pixi run check gave 5329 passed, 566 skipped, 1 xfailed. docs-test gave 112 passed. The new test was a strict xfail first, and failed on the refusal.
• pixi run test-bench: 263 passed. An earlier version of this line said it passed, which was wrong: it had last run before the keep/start= rule, which refused bench/warm_payoff.py's warm arm (keep='nothing' beside start=). CI caught it. The warm arm now asks for keep='solver' and runs first after each update, where the gained cut loads a fresh solver anyway, and an assertion on Result.kept holds both arms to a fresh solver.
• pixi run -e docs docs-test and docs-build --strict pass.
• feat(api): a mixed-integer solve can start from values, an earlier answer's or any source a parameter takes, matched by coordinate #1878's branch moved while this was open (any-shape values). It is merged in here, not rebased, and its tests now pass their tables under 'primal'.

Deliberately not done, and departures

• One PR rather than a stack. The review refactors, the basis output, the unified start and the sweep start all reshape 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–feat(api): a mixed-integer solve can start from values, an earlier answer's or any source a parameter takes, matched by coordinate #1878 before release, and each builds on the one before.
• keep is unchanged apart from the refusal beside start=. Whether start= replaces keep='progress', and which alignment 'previous' uses for windows, needs a measurement first: a follow-up.
• No dual values in a start. Gurobi's PStart showed no gain, and duals would need the sign conversion reversed per solver. Measure first.
• The other PRs' changelog lines are unchanged. 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 line still reads outputs={'variable_basis', 'constraint_basis'}, and its title would need the same edit.

🤖 Generated with Claude Code

https://claude.ai/code/session_014wLrXpeSGDqoBFxyrs8NEz

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #35015316 | 📁 Comparing ef01170 against latest (5adfc58)

  🔍 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/wizardly-lamport-e3g6om (ef01170) with claude/festive-carson-8x46sq-mipstart (64fcb1c)}

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. ↩