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

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

outputs={'variable_basis', 'constraint_basis'} makes a solve or a sweep carry the basis status it ended on. The words are the same on HiGHS, Gurobi and Xpress. This is #1869 part 1, and the warm start stacked on it reads it.

What it is

• One vocabulary (BASIS_STATUSES), read back as an Enum: basic, at_lower, at_upper, fixed, superbasic. A row's bound is its right-hand side, so a binding <= row is at_upper, a binding >= row at_lower, and a binding == row fixed. A column at equal bounds is fixed, whichever bound its solver names.
• Two outputs, not one, because a constraint may share a variable's name (mathspec's flat namespace leaves constraints out). Each output holds one frame per declaration, as every other output does.
• How each member reads its basis: _basis() maps the solver's own codes to the shared ones. It reads only basic or not, and which bound a column is at. Solver.run(handoff, basis=True) then reads each nonbasic status against the model (settled): a row's bound from its sense, fixed from equal bounds. That is also why all three sinks agree, even though Gurobi says only "nonbasic" for a row and Xpress names a row's slack.
• Read only when asked: the engine passes basis=True only where outputs names one of the two.
• Where there is no basis — a mixed-integer model, a quadratic constraint, interior point with crossover off — the reader raises NO_BASIS, which names the solver options that give one. A sweep raises it only where some slice solved. Otherwise it gives its "nothing to read" message.
• An output under feat(api): every answer holds an optional output only when outputs= asks for it, and a sweep can hold the activity too #1865's rule, stacked on feat(api): a solve or a sweep asked for outputs={'slack'} reads how far each constraint is from binding #1868: Result.variable_basis / constraint_basis, the same on Sweep, kind= on the bridges, <output>/<name>.parquet in a save, a spill and an archive, and a catalog row per declaration. No LAYOUT bump.

Verification

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

The local runs above were taken while one test of the base, test_a_solution_is_read_back_in_label_order_without_sorting_for_it, failed there, so they deselect it. The base has fixed it since, it is merged in, and CI runs the whole suite.

tests/test_basis.py covers the following:

• The vertex of a five-variable, four-row LP, worked out by hand so that every status but superbasic appears, read in the same words on every sink.
• The Enum dtype.
• A save that loads back.
• The refusal when not asked for, per output.
• No basis after a mixed-integer solve and after interior point without crossover, on each sink.
• No basis with a quadratic constraint, on Gurobi.
• A sweep held, on a process pool, spilled and archived.
• A sweep whose every slice ended on no basis.
• A basis a member reads short, refused.

Mutation table, from python -m tools.mutate against the full suite (that one test deselected through PYTEST_ADDOPTS), except one row taken by hand with the same three precautions:

guard	result
a basis that does not span the model refused (base.py:271-272)	caught
a column at equal bounds reads fixed (base.py:274)	caught
a nonbasic row reads its bound off its sense (base.py:277)	caught
a result that ended on no basis says so (result.py:666-667)	caught
a sweep whose slices ended on no basis says so (sweep.py:733-734)	caught, on a second run; the first was interrupted by the load of another run on the box and proved nothing
HiGHS: an invalid basis is none (highs.py:244-245)	caught
Xpress: no basis after a mixed-integer solve (xpress.py:140-141)	caught
Xpress: no basis after barrier without crossover (by hand: the try/except SolverError removed)	caught (1 failed)

The tree was clean after each run. One guard is not in the table: run reads a basis only after a run that left a primal. Reading one after a failed run would be harmless and invisible, because the reader refuses on the status first.

Deliberately not done

• Gurobi's _basis has no guard for a quadratic constraint: Gurobi refuses VBasis there itself, which the new test shows.
• No fixed read from a solver for a row: every row is single-sided, so its nonbasic status follows from its sense.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GLBvwp6NU7YjszFz5QMRf1

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #35014854 | 📁 Comparing 452789c against latest (9e47978)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• tables/index.html
• about/architecture/index.html
• about/changelog/index.html
• howto/archiving/index.html
• howto/debug/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-basis (452789c) with claude/festive-carson-8x46sq-slack (5b54514)}

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