fix(language): dual(c) is the rate at which the optimal objective rises with the right side of c, so an equality has a sign too

[FBumann]

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

Note

The following content was generated by AI.

What this changes

dual(c) is now the rate at which the optimal objective rises with the right side of c, for every comparator and under either sense. The old wording left an equality without a sign and disagreed with specsolve on <=. fluxopt/specsolve#1774 pins every specsolve sink to this definition.

The ambiguity, the evidence, what moves

Before

named.md: "dual(c) is the rate at which the optimal objective improves as c is relaxed in the direction its comparator points."

• An == row points in no direction, so its dual had no sign.
• A <= row under minimize came out non-negative. specsolve returns the opposite sign, and specsolve's own examples/benders/run.py builds its cut slope on the returned sign.

After

named.md and the Dual docstring: read lhs <= rhs as lhs <= rhs + d; the dual is the rate in d at d = 0. The same for >= and ==, under minimize and maximize. Which side a term is written on decides the sign: p <= cap and -p >= -cap are one row with opposite duals. A table gives the sign of a binding row of each comparator under minimize.

Evidence

specsolve main at e78c1a3, HiGHS, Gurobi and Xpress. One row, "p is at least 2 + b", written six ways, under both senses; the dual against a finite difference in b (step 1e-3), times how b moves the right side:

Written	Sign of b in rhs − lhs
p >= 2 + b	+
2 + b <= p	−
-p <= -2 - b	−
p - b >= 2	+
p == 2 + b	+
2 + b == p	−

36 of 36 cases match (6 rows × 2 senses × 3 sinks). The test is in fluxopt/specsolve#1774. On specsolve's Benders subproblem the same reading gives the cut slope that finite differences give (67.5 for cap[wind]); the old reading gives 112.5.

What does not change

• No code path: the loader never reads a dual's value.
• examples/operators/dual.yaml uses a >= row under minimize, where the two readings agree.

Gates

• pixi run lint: pass.
• pixi run test: 1684 passed.
• docs-build and compile-tex were not run in the session (network). CI runs both.

Relation to the open stack

#749 (spec.sensitivity) carries the same named.md hunk, because its formula depends on this definition. Once this merges, that hunk is already on main.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CvcU9JRnsinc9e9syvVcHS

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34821067 | 📁 Comparing d843596 against latest (0efbf59)

  🔍 Preview build  

56 files changed · + 32 added · ± 20 modified · - 4 deleted

+ Added

• several-files/index.html
• examples/library/index.html
• howto/compare/index.html
• howto/compose/index.html
• examples/library/composed/index.html
• examples/library/generator/index.html
• examples/library/load/index.html
• examples/library/surface/index.html
• examples/pypsa/carrier/index.html
• examples/pypsa/cost/index.html
• and 22 more...

± Modified

• changelog/index.html
• examples/index.html
• about/limits/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/language/index.html
• reference/notation/index.html
• and 10 more...

- Deleted

• examples/pypsa_losses/index.html
• examples/pypsa_multi_period/index.html
• examples/pypsa_quadratic/index.html
• examples/pypsa_stochastic/index.html