cuopt-agent: add duals-interpretation guidance to the debugging skill by cafzal · Pull Request #159 · NVIDIA/cuopt-examples

cafzal · 2026-06-18T16:17:34Z

What

Adds resources/interpreting_duals.md to the cuopt-agent's cuopt-debugging skill: guidance for turning a solved LP/QP's DualValue / ReducedCost / Slack into a decision read — which constraint is the binding bottleneck and what relaxing it is worth (its dual value), and which unused option is the closest near-miss (reduced cost) — with the one-way implications and degeneracy / no-basis caveats that keep those reads honest (rankings as shortlists; any quoted number confirmed by a differencing re-solve). Linked from the skill's SKILL.md.

Why

The skill already shows how to read duals (diagnostic_snippets.md) but not what they mean for the decision. It also makes the scope explicit — consistent with the main-repo dual/sensitivity work (NVIDIA/cuopt#1393, #1406): duals exist for continuous (LP/QP) solves off linear constraints. Two cases return none — an integer model (the max-supply model is a MILP) and a quadratic constraint (a quadratic objective is fine) — with the difference-adjacent-solves / LP-relaxation fallback called out for the MILP.

Notes

Pure guidance — a skill resources/ markdown plus a one-line SKILL.md pointer; no code or model changes.
Grounded in the max-supply shape (resource-hour caps and per-period supply limits as the binding bottlenecks).

Companion to the dual / sensitivity work in #154 (LP duals in the diet example) and #157 (the agent's multi-objective scenario).

Signed-off-by: cafzal <cameron.afzal@gmail.com>

cafzal · 2026-06-18T17:42:39Z

@ramakrishnap-nv small one: adds duals-interpretation guidance (decision read of DualValue/ReducedCost) to the agent's debugging skill. Ready for review.

At a degenerate optimum (many constraints binding at once) the basis is non-unique, so a single dual is one-sided. Report the ranking of binding constraints and present a dual as a direction (confirmed by the one-unit re-solve) rather than a hard per-unit rate. LP/simplex effect; strictly convex QP duals stay unique. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: cafzal <cameron.afzal@gmail.com>

mlubin · 2026-06-29T14:28:19Z

+
+## Constraint dual value — the marginal value of relaxing a limit
+
+A constraint's `DualValue` is the **sensitivity** of the optimum to that constraint: the change in


The smooth sensitivity interpretation is true only in the absence of degeneracy, and degeneracy is very common in real-world problems. I don't know how to precisely describe the perturbation sensitivity of the objective without invoking subgradients.

Thanks @mlubin . Follow-up commits make the ranking of binding constraints a more robust read and demote a single dual to a direction:

The headline now conditions the exact per-unit equality on a non-degenerate optimum; under degeneracy it is one-sided.

The bullet under it drops the unconditional "relax by one unit, objective improves by DualValue."

The When a dual is soft section adds the one-sided, non-unique caveat, the trap that the dual looks most precise where it is least reliable, and a one-unit re-solve to confirm any rate before quoting it.

Happy to tighten further if anything still reads too strong. We can also cover subgradients explicitly if you think it's warranted.

…n-degeneracy Review feedback: the headline stated the smooth sensitivity reading unconditionally. Hedge it where the claim is made — exact change per unit only at a non-degenerate optimum; one-sided under degeneracy (the common case), read as a direction. Detail stays in the existing degeneracy note. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: cafzal <cameron.afzal@gmail.com>

…t rate Follow-through on the degeneracy hedge. The bullet under the headline still quoted the unconditional per-unit reading ("relax by one unit and the objective improves by DualValue") two lines below the hedge that conditions it. Align it: the ranking of binding constraints by |DualValue| is the degeneracy-robust read; a single dual is a direction, not a guaranteed per-unit rate. Points to the existing 'When a dual is soft' section. Signed-off-by: cafzal <cameron.afzal@gmail.com>

mlubin · 2026-07-02T00:49:12Z

+that is the exact change in objective per unit relaxed; under **degeneracy** (common in practice) it
+is one-sided, so read it as a direction (see *When a dual is soft*).
+
+- A **binding** constraint (`Slack ≈ 0`) carries a nonzero dual — it is actively limiting


The implication is in one direction. Slack > 0 implies zero dual. Slack = 0 does not imply nonzero dual (if it doesn't hold, you have a form of degeneracy)

Fixed: now stated one-way, with the 'binding but no dual' case noted as degeneracy.

mlubin · 2026-07-02T00:51:50Z

+- A **binding** constraint (`Slack ≈ 0`) carries a nonzero dual — it is actively limiting
+  the objective. A **slack** constraint (`Slack > 0`) prices to ~0: relaxing it changes
+  nothing, because it is not the bottleneck.
+- **Rank the binding constraints by `|DualValue|`** → the largest is the highest-leverage limit to


You need some level of comparability of the units of the constraints for this ranking to make sense. You can always scale a constraint (multiply the coefficients and right-hand side by a constant) to increase or decrease the optimal dual, which would change this ranking but have no real meaning in practice.

Fixed: ranking scoped to comparable units, with a common-scale conversion for mixed ones

mlubin · 2026-07-02T00:55:35Z

+## Reduced cost — how far an unused option is from entering
+
+A variable resting at a bound (often `0`) carries a `ReducedCost`: how much its objective
+coefficient must improve before it would enter the optimal solution. It is the **near-miss** signal.


"enter the optimal solution" - the variable is already in the optimal solution, with a value of zero.
"how much its objective coefficient must improve" - what does this mean precisely? You're allowed to have a variable at it's bound 0 with zero reduced cost (again, degeneracy).

Fixed: now stated as the pay-off threshold on the coefficient with the at-bound zero-reduced-cost case noted as degeneracy

mlubin · 2026-07-02T00:55:59Z

+coefficient must improve before it would enter the optimal solution. It is the **near-miss** signal.
+
+- A variable with `Value > 0` is already in the mix; its reduced cost is ~0.
+- Among the variables left at `0`, the one with the **smallest `|ReducedCost|`** is closest to


Variables need to be in comparable units for this sorting to make sense, see above.

Fixed: same unit scoping for reduced costs, or compared as a fraction of each variable's own coefficient.

mlubin · 2026-07-02T00:56:36Z

+
+## When a dual is soft (degeneracy)
+
+A dual is exact for the basis the solver returned, but at a **degenerate** optimum — many


cuOpt often doesn't return a basis. It depends on which solver ran.

Fixed: the degeneracy section now covers the no-basis (PDLP) case.

Barrier also does not need to return a basis

Fixed: generalized to any basis-free solve

mlubin · 2026-07-02T00:59:25Z

+- Report the **ranking** of binding constraints as solid; present a single dual as a *direction*
+  ("this is the lever to renegotiate"), not a hard per-unit rate.
+- Confirm any rate you quote with the one-unit re-solve (below): if the objective change does not
+  match `DualValue`, the optimum is degenerate — give the direction, not the number.


This isn't correct. Even if there's no degeneracy, the dual just gives you the marginal change but not the actual change for a unit perturbation; the basis could change multiple times in the process of solving the perturbed problem.

Fixed: the dual is now presented as a marginal rate, with any finite change quoted from a differencing re-solve

mlubin · 2026-07-02T00:59:59Z

+- Confirm any rate you quote with the one-unit re-solve (below): if the objective change does not
+  match `DualValue`, the optimum is degenerate — give the direction, not the number.
+
+An LP / simplex effect; a strictly convex QP (quadratic _objective_, not constraint) has unique


Most QPs are not strictly convex.

Fixed: cut the claim.

…arability, no-basis duals - State the slack/dual implication one-way: slack > 0 forces a ~0 dual, but a binding constraint can still price to 0 (degeneracy) - Caveat the |DualValue| ranking: only meaningful across constraints in comparable units; suggest a common scale (e.g. value of a 1% relaxation) - Same units caveat for sorting unused variables by |ReducedCost| - Note cuOpt often returns no basis (PDLP / concurrent path): duals are tolerance-accurate directions and reduced costs lose the crisp at-bound split

The one-way implication, unit-comparability, and no-basis caveats were stated once but contradicted downstream. Align the rest of the doc: - Ranking snippets, the decision-read summary, the max-supply example, and the soft-dual bullet now all scope |dual| / |reduced cost| comparisons to comparable-unit groups - Sign-conventions re-solve check conditioned on non-degeneracy instead of asserting the difference always matches the dual - QP aside no longer claims unique duals outright (degenerate active constraints can leave multipliers non-unique) - Drop a redundant restatement of the implication direction

… drop strict-convexity aside - Even without degeneracy the active set can change within a finite step, so dual x step is not the realized change: present the dual as a derivative and route any finite-change quote through a differencing re-solve (intro, snippet label, soft-dual bullet, sign conventions, decision read, MILP callout) - Remove the strictly-convex-QP reassurance: most QPs are not strictly convex, and the claim carried no decision weight

…oss, could-enter wording)

…ncing for MILPs

…-RC-at-bound as degenerate Signed-off-by: cafzal <cameron.afzal@gmail.com>

…, rankings as shortlists, between-bounds not Value>0 Signed-off-by: cafzal <cameron.afzal@gmail.com>

Signed-off-by: cafzal <cameron.afzal@gmail.com>

mlubin · 2026-07-15T13:17:40Z

+> **Continuous models, linear constraints.** Duals and reduced costs exist for **continuous**
+> (LP / QP) solutions off **linear** constraints. Two cases return none: an **integer model
+> (MILP)** — **including the max-supply model** — has no usable duals, and a **quadratic
+> _constraint_** makes cuOpt NaN-fill every dual (a quadratic _objective_ is fine — it is a


We have this description of the NaN behavior written down in many skills. What happens in an upcoming release when the behavior changes and duals are available for quadratic constraints?

Removed, references other skill instead.

mlubin · 2026-07-15T13:20:43Z

+    print(f"{name}: dual {dual:+.4g}  (marginal rate as this limit relaxes)")
+```
+
+In the max-supply shape the constraints that typically bind are the **resource-hour capacities**


What is "max-supply shape"?

Clarified to "model"

mlubin · 2026-07-15T13:22:44Z

+It is the **near-miss** signal.
+
+- A variable strictly **between** its bounds prices to ~0. One pressed against an *upper* bound can
+  carry a nonzero reduced cost with `Value > 0` — there it reads as the marginal value of raising


Is this description consistent with the discussion of signs below?

Good catch. Now stated as a magnitude

mlubin · 2026-07-15T13:25:04Z

+
+## When a dual is soft (degeneracy)
+
+A dual is exact for the basis the solver returned, but at a **degenerate** optimum — many


Barrier also does not need to return a basis

- Defer the duals-availability rule to its canonical statement (the cuopt-numerical-optimization-api skill, Dual Values) instead of restating it; keep a runtime check - finite duals are provided, NaN-filled are not - that stays correct across releases. - At-upper-bound reduced cost stated as a magnitude, direction read as for any bound relaxation (Sign conventions). - No-basis treatment generalized: PDLP or barrier/interior-point without crossover; the exact-for-its-basis claim scoped to simplex. - 'max-supply shape' named plainly: the max-supply model, this agent's multi-period supply-chain planning example. - Apply reviewer wording suggestion ('This page explains').

cafzal added 3 commits June 18, 2026 09:13

cuopt-agent: add duals-interpretation guidance to the debugging skill

eb919d3

Signed-off-by: cafzal <cameron.afzal@gmail.com>

Note quadratic-constraint dual scope; lead with marginal-value framing

fbcf2ca

Signed-off-by: cafzal <cameron.afzal@gmail.com>

Drop 'shadow price'; use dual-value terminology throughout

592b1de

Signed-off-by: cafzal <cameron.afzal@gmail.com>

cafzal marked this pull request as ready for review June 18, 2026 17:26

mlubin reviewed Jun 29, 2026

View reviewed changes

cafzal and others added 2 commits June 29, 2026 14:28

cafzal requested a review from mlubin June 29, 2026 22:19

mlubin reviewed Jul 2, 2026

View reviewed changes

cafzal force-pushed the agent-duals-narration branch from 95076da to ec792c7 Compare July 2, 2026 03:42

claude and others added 7 commits July 2, 2026 03:57

interpreting_duals: finish the rate-not-forecast sweep (max-supply gl…

21408dc

…oss, could-enter wording)

interpreting_duals: rank LP-relaxation duals as a guide below differe…

8e36712

…ncing for MILPs

interpreting_duals: reduced cost as a pay-off threshold; surface zero…

65bb517

…-RC-at-bound as degenerate Signed-off-by: cafzal <cameron.afzal@gmail.com>

interpreting_duals: degeneracy sweep — one-way reduced-cost threshold…

6ec9680

…, rankings as shortlists, between-bounds not Value>0 Signed-off-by: cafzal <cameron.afzal@gmail.com>

interpreting_duals: rewrap two ragged lines

f1ec6ff

Signed-off-by: cafzal <cameron.afzal@gmail.com>

cafzal requested a review from mlubin July 2, 2026 04:44

mlubin reviewed Jul 15, 2026

View reviewed changes

cafzal added 2 commits July 15, 2026 15:10

interpreting_duals: trim meta-commentary from the availability note

c96d9d2

cafzal requested a review from mlubin July 15, 2026 22:31


		## Constraint dual value — the marginal value of relaxing a limit

		A constraint's `DualValue` is the sensitivity of the optimum to that constraint: the change in


		## When a dual is soft (degeneracy)

		A dual is exact for the basis the solver returned, but at a degenerate optimum — many

Uh oh!

Conversation

cafzal commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Notes

Uh oh!

cafzal commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cafzal Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cafzal commented Jun 18, 2026 •

edited

Loading

cafzal commented Jun 18, 2026 •

edited

Loading

cafzal Jun 29, 2026 •

edited

Loading