Repository navigation
Documentation: sign conventions (min/max, p⁰, constraints, duals) and how they appear in a solution #1015
Description
Summary
Add a page to the documentation that explains the sign conventions of the ecosystem and how they show up in a solution, once they are settled in the discussion #1014. This issue is the place for that page; it should not be written before the choices are made.
Related: #968 (documentation items waiting on other packages), control-toolbox/CTDirect.jl#639, control-toolbox/CTFlows.jl#472.
What the page should explain
minvsmax: the value ofp⁰, the Hamiltonian (with and without constraints), and whetherpand the duals change sign whenmin Jbecomesmax −J.- Inequality constraints:
g ≥ 0orc ≤ 0, the sign of the multiplier on each side, two-sided constraints, equalities. - What
dual(sol, ocp, :label)returns for each kind of constraint (path, box, boundary, variable box): sign, scaling (continuous-time density or raw NLP value), and its meaning at the first and last nodes. - The same constraint solved directly (
solve) and by an indirect method (Flow(ocp, law; constraint=:label, multiplier=μ)): how to read the duals on both sides, and the dictionary betweenμanddual. - Transversality and boundary constraints: the sign of
βand of the dual of a boundary constraint. - Which of these do not depend on the NLP solver (Ipopt, MadNLP).
Elements already available
- Probes of 2026-10-21 (closed-form problems; table in the discussion).
- The KKT derivation per scheme and the measurements in Box multipliers are not divided by the time step, and their sign is the opposite of the path multipliers CTDirect.jl#639.
- The existing section Formulation → Notation and conventions, to complete or to point to.
- A runnable probe such as
solution_duals.jl(see Documentation: issues to settle in the other packages before the final read and the stable release #968), extended with an indirect solve, so the page is checked by the documentation build.
Depends on
- Decision on the conventions: Sign conventions across the ecosystem: min/max, p⁰, inequality constraints, signs of p and of the duals #1014
- CTDirect alignment: Box multipliers are not divided by the time step, and their sign is the opposite of the path multipliers CTDirect.jl#639
- Duals of
Flow(ocp, law):Flow(ocp, law)Solution: reconstruct the constraint duals from the multipliers CTFlows.jl#472
Activity
ocots commentedon Oct 23, 2026
Update (2026-10-23): the convention is proposed, and what this page should say
The convention proposed in #1014 and control-toolbox/CTSolvers.jl#288 gives this page its content, once it is chosen. The page is written for the user of OptimalControl, with no mention of the solvers (the solver side is documented in CTSolvers, the pseudo-Hamiltonian side in CTFlows).
It should state that:
μ ≥ 0forc ≥ l, forc ≤ u, and for the bounds of the variables), andg ≥ 0and-g ≤ 0, being the same constraint, have the same dual;c = 0and-c = 0differ by a sign, since an equality has no preferred side;min fandmax -fare the same problem and have the same duals and the same adjointp: the adjoint does not change sign whenmin fis writtenmax -f;dual(sol, ocp, :label)for a constraint, a box, a boundary condition, and for the solution of a direct solve and of an indirect one (Flow(ocp, law; constraint=:label, multiplier=μ)), where the dual is theμgiven to the flow and is0off the boundary arc.The pieces already available are listed above (probes of 2026-10-21 and 2026-10-23, the derivation in control-toolbox/CTDirect.jl#639). The page depends on the decision in #1014 and on the implementation in control-toolbox/CTSolvers.jl#288, and on the alignment of CTDirect for a maximisation (its duals and costate currently flip with the sense).
ocots commentedon Oct 23, 2026
The examples for this page, and the tests that should come with them, are listed in #1016. Implementation: control-toolbox/CTSolvers.jl#289 (direct solvers), control-toolbox/CTFlows.jl#494 (flows), control-toolbox/CTModels.jl#483.