[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?" A follow-up set the shape of the values: "Why start: Result | Mapping[str, pl.DataFrame] ? Why not str, Sources?"

Note

The following content was generated by AI.

start= on a mixed-integer model gives the solver values as its first incumbent. They come from an earlier answer, or per variable in any shape a parameter's source takes. They are matched by coordinate and may be partial. This is #1869 part 2.

What it is

• One keyword, decided by the model: an LP starts from an earlier answer's basis (feat(api): an LP solve can start from an earlier answer's basis, matched by coordinate, so a model that gained a cut starts from where it was #1877); a mixed-integer model starts from values. An earlier answer (live, saved or archived) gives its primal. start= takes Result | Mapping[str, Source].
• Values enter as a parameter does: sources.read_values reads each through the parameter reader over the variable's dims, so a start takes a table (polars, pandas, Arrow), a parquet path, a {label: value} map, a sequence in label order, or one number for every coordinate. It is checked the same way: a missing dim column, a label the dimension lacks, a coordinate twice, a null, a sequence of the wrong length. The reader's refusals now name what they read (kind): parameter 'cost' as before, start= for variable 'take' here. One message changed for parameters too: "A missing row is a zero coefficient" became "A missing row means no value there", which is true of both.
• Read in Model.solve, not the engine, because test_engine_is_isolated keeps specsolve.sources out of relational/. The engine takes tidy frames per variable.
• Matched by coordinate (readback.matched_values), on the placement feat(api): an LP solve can start from an earlier answer's basis, matched by coordinate, so a model that gained a cut starts from where it was #1877 introduced, now shared by a basis and values (_place). A variable or a coordinate the start leaves out is NaN, and the solver completes it.
• Partial starts reach every solver: HiGHS by setSolution's sparse form, Gurobi by GRB.UNDEFINED, and Xpress by addMipSol over the columns given.
• Refused before the solver loads: a name that is no variable (with the near miss), anything a parameter over the same dims is refused for, a start that places no value at all (an earlier answer of another model, say), and values for an LP.
• sps.solve no longer checks a start before the build: whether it needs a basis or values depends on the model, which the build decides. feat(api): an LP solve can start from an earlier answer's basis, matched by coordinate, so a model that gained a cut starts from where it was #1877's test of the earlier check moved to "before the solver loads".

Why not a bare path for the whole start

A path is ambiguous where the rest of start= is not. It could be a saved answer or an archive, which have two loaders. An archive can also hold a sweep, which has no single answer to start from. start=sps.load_result(path) is one explicit line. A path per variable works, through the parameter reader.

How a start is observed

Each sink is stopped at its root node with presolve, heuristics and (Gurobi, Xpress) cuts off, so any incumbent it returns is one it was given. On the 12-item knapsack fixture, all three sinks give the same numbers:

	HiGHS	Gurobi	Xpress
no start	no solution	no solution	no solution
a full start worth 10	10	10	10
a partial start naming two items	35	35	35
one number, 0.0, for every item	0	0	0

In the partial case each solver filled in the rest itself. The test asserts that the named items stay in, not the 35.

Verification

Gates: ruff check ., ruff format --check ., pyrefly check, the full suite (pytest -n auto, with HiGHS, Gurobi and Xpress installed: 5371 passed), zensical build --strict.

New in tests/test_start.py, on every sink:

• The control: no incumbent at the root without a start.
• A full start is the incumbent, as a polars frame, a pandas frame, a parquet path, a map and a sequence.
• One number starts every coordinate.
• A partial start is completed, and keeps what it names.
• An earlier answer starts the solve at its optimum.

And, parametrized, the refusals:

• a misspelled variable, a missing dim column, a label the dimension lacks, a coordinate twice, and a sequence of the wrong length;
• an earlier answer of another model, which places nothing;
• values for an LP.

test_a_hint_the_solver_refuses_is_loud_not_a_silent_cold_start now stubs the sparse setSolution.

Mutation table, from python -m tools.mutate against the full suite, except the rows marked by hand, which were taken with its three precautions:

guard	result
a start naming no variable refused (api.py:394-395)	caught
a start placing nothing refused (engine.py:260-264)	caught
values for an LP refused (engine.py, the isinstance(start, Result) refusal)	caught, taken before the move to the reader
HiGHS: only the given values cross (by hand: the NaN filter removed)	caught (1 failed)
Xpress: only the given values cross (by hand: the NaN filter removed)	caught (1 failed)
Gurobi: a value not given is UNDEFINED (by hand: the mapping removed)	caught (1 failed)

The tree was clean after each run. The earlier rows for the table's own name and column checks are gone with those checks: the parameter reader does both now, under its own tests.

Deliberately not done

• A coordinate the model's dimension holds but the variable's mask leaves out is dropped without a word, as is a value outside a variable's bounds: a start is a hint, and the solver repairs it.
• No start= on solve_over, as in feat(api): an LP solve can start from an earlier answer's basis, matched by coordinate, so a model that gained a cut starts from where it was #1877.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GLBvwp6NU7YjszFz5QMRf1

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #35014979 | 📁 Comparing 64fcb1c 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-mipstart (64fcb1c) with claude/festive-carson-8x46sq-warm (70506b4)}

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