docs(api): a dual is the rate at which the optimal objective rises with its row's right side, on every sink

[FBumann]

Prompt: Let's do a pr in mathspec and specsolve fixing the dual ambiguity

Note

The following content was generated by AI.

Result.dual states its sign: the rate at which the optimal objective rises with the row's right side, for every comparator and sense. That is the definition energy-models/mathspec#751 gives dual(c). A test pins it on every sink against finite differences.

Method, mutation, gates, departures

What was ambiguous

Result.dual said "shadow prices" and nothing about sign. mathspec's page said a dual is the rate at which the objective improves as the row is relaxed. That makes a <= dual under minimize non-negative, where every sink here returns it non-positive, and it leaves an == row without a sign. No code changes here: all three sinks already return the rate in the right side, as written in the YAML. energy-models/mathspec#751 moves mathspec's definition to match.

The test

test_a_dual_is_the_rate_of_the_optimum_in_its_rows_right_side, in tests/test_duals.py. One row, "p is at least 2 + b", is written six ways: p >= 2 + b, 2 + b <= p, -p <= -2 - b, p - b >= 2, p == 2 + b and 2 + b == p. Each runs under minimize and maximize, on every sink solver_name yields. The dual has to equal the finite difference of the objective in b (step 1e-3; the row binds, so the difference is exact), times how b moves rhs - lhs.

Result: 36 passed, highs, gurobi and xpress. Gurobi and Xpress ran on the size-limited licences their PyPI wheels carry.

Mutation

Mutation	Result
HiGHS's row_dual negated in highs.py	12 failed: every HiGHS case

Gates

pixi install could not run in the session: it fetches the conda-to-PyPI mapping from a host the session's network refuses. The gates ran from uv sync --group dev --extra gurobi --extra xpress on Python 3.12, with the tool versions the dev group pins.

• ruff check .: clean.
• ruff format --check .: clean.
• pyrefly check, both configs: 0 errors.
• pytest -q -n auto: 4078 passed, 320 skipped, 1 xfailed.

docs-build was not run.

Not done

• examples/benders/run.py already reads the slope with this sign, so it is unchanged.
• dual_ray has its own convention, stated in test_dual_ray.py, and is untouched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CvcU9JRnsinc9e9syvVcHS

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34825053 | 📁 Comparing 9b1278d against latest (e78c1a3)

  🔍 Preview build  

4 files changed

± about/architecture/index.html
± about/changelog/index.html
± reference/api/index.html
± reference/data/index.html

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/mathspec-analysis-features-zy7x4n-dual-sign (9b1278d) with main (2ff1cff)²}

Footnotes

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

2. No successful run was found on main (854c6b4) during the generation of this report, so 2ff1cff was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩