feat(api): a solve or a sweep asked for outputs={'reduced_cost'} reads each variable's reduced cost, with the same sign on every solver

[FBumann]

Prompt: Lets work on this as a pr from main

…of a plan whose first item was: "Reduced costs computed from duals, with a cross-check test against each solver." A follow-up set scope: "Reduced cost must work for sweeps the same way as it does for regular solves!" It now builds on #1865's outputs=.

Note

The following content was generated by AI.

outputs={'reduced_cost'} makes a solve or a sweep carry each variable's reduced cost, computed from the duals, so its sign is dual's on every sink. A result, a sweep, their saves, spills and archives all read it.

What it is, and what it refuses

• The value is the rate at which the optimal objective rises as the variable's binding bound rises. That is dual's convention moved from a row's right-hand side to a column's bound, so one rule holds for both senses, every comparator, and either side a term is written on. A variable strictly between its bounds reads zero.
• How it is computed: ∇f(x) − Σ yᵣ∇gᵣ(x), in one numpy pass over the CSR matrix (readback.reduced_costs). The pass includes a quadratic objective's gradient and a quadratic row's gradient (Gurobi with QCPDual). No sink changes.
• 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. Result.reduced_cost and Sweep.reduced_cost, kind='reduced_cost' on the bridges, reduced_cost/<name>.parquet in a save, a spill and an archive, and a catalog row per variable. No LAYOUT bump: an older answer reads it as not asked for.
• Where it is refused: wherever dual refuses, with the duals' own reason (mixed-integer, a quadratic row without QCPDual, a run with no basis), through the reader and the bridges alike. That reason is saved once in reasons.parquet. PRICED = {'dual', 'reduced_cost'} is the one home of "exists exactly where the duals do", read by Result._carried and the sweep readers. It is also refused when not asked for, for a closed result, and with NoSolutionError when there are no values.
• Computed only when asked, so a default solve pays neither the time nor the memory.

Verification

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

The review fix (768ae3e, 9ebc0a2) was gated at 6a03f5d with ruff check ., ruff format --check ., pyrefly check (0 errors), and the full suite with the dev group, Gurobi and Xpress installed: 5151 passed, 566 skipped, 1 xfailed. The docs build was not re-run.

tests/test_reduced_cost.py has three oracles:

• A finite difference: raise the binding bound by 1e-3, solve again, and the objective moves at the reduced cost. Run on every sink, for six ways of writing the balance (min/max × >=/<= reversed/==).
• Each solver's own value: HiGHS col_dual, Gurobi RC, Xpress getRedCosts. All three agree with the computed value for both senses, so no sink needs a sign conversion.
• A hand-derived optimum.

On top of those: quadratic objectives (HiGHS, Gurobi) and quadratic rows (Gurobi QCPDual); a save that loads back; an integer answer, live and loaded, giving the duals' reason through the reader and through to_dataset; and a two-scenario sweep held, spilled and archived. In that sweep each slice is priced at its own marginal generator, and an integer sweep gives the duals' reason.

The to_dataset case was a bug found in review: a mixed-integer answer's bridge listed no names and failed unpacking them (ValueError). It was reproduced as a strict xfail (768ae3e), seen failing live and loaded, then fixed by giving the duals' reason where any output is read (9ebc0a2).

Mutation table, python -m tools.mutate against the full suite, unless marked by hand. Line numbers are at the commit each row was taken on:

guard	result
the objective cost term (readback.py:164)	caught
the rows weighted by their duals (readback.py:165)	caught
the quadratic objective gradient (readback.py:167)	caught
the quadratic rows weighted by their duals (readback.py:168)	caught
the gradient on the left column of a pair (readback.py:170)	caught
the gradient on the right column of a pair (readback.py:171)	caught
a priced output gives the duals' reason (result.py:605-606, at 9ebc0a2)	caught
a slice skips an output its result left empty (strategy.py:611, at 3fcba30, by hand: if laid: → if True:)	caught (36 failed)
a sweep gives the duals' reason for a priced kind (sweep.py:391, by hand: kind in PRICED → kind == 'dual')	caught (3 failed)

Tree clean after each run.

Cost, only when asked

Method: a dispatch LP with 200,000 snapshots × 10 generators (2,000,000 columns, 200,000 rows, 2,000,000 nonzeros) on HiGHS. One build, at 28aa7d6. Engine._answered was timed with and without outputs={'reduced_cost'}, alternating, median of 7. The solve is the median of 3. Three runs, load average under 1.1 with nothing else running.

	run 1	run 2	run 3
read-back, no outputs	0.1 ms	0.1 ms	0.1 ms
read-back, outputs={'reduced_cost'}	54.8 ms	66.9 ms	55.5 ms
HiGHS solve	20.68 s	20.27 s	20.29 s

Asking costs about 0.3% of the solve on this model. Not asking costs nothing. These numbers predate the review simplification, which changes where the computation is called from and not what it computes. They were not re-run.

Deliberately not done

• No language construct (reduced_cost(x) in a spec).
• The name reduced_cost was discussed and kept: it is the name HiGHS, Gurobi, Xpress and JuMP use. Its sign is stated in the docstring, because JuMP's convention (relaxing the bound) flips the sign at a lower bound.
• Slack is the next output, in its own PR stacked on this one.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GLBvwp6NU7YjszFz5QMRf1
https://claude.ai/code/session_01UFX6qbCYnXKTVkucgxEqfS

[codspeed]

Merging this PR will not alter performance

✅ 67 untouched benchmarks
⏩ 307 skipped benchmarks¹

---

_{Comparing claude/festive-carson-8x46sq (2ce4c0e) with claude/festive-carson-8x46sq-outputs (b136129)}

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

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #35014786 | 📁 Comparing 2ce4c0e against latest (79258b1)

  🔍 Preview build  

12 files changed · ± 11 modified · - 1 deleted

± Modified

• about/index.html
• tables/index.html
• about/architecture/index.html
• about/benchmarks/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
• and 1 more...

- Deleted

• about/benchmarks-scaling.html