Repository navigation
Description
Goal
Reorganise OptimalControlProblems.jl around four ideas:
- Each modeling has its own list of problems, discovered automatically from the files: a problem may exist in OptimalControl without a JuMP version. No list of problems is written by hand anywhere.
- Every problem keeps a comparison: another modeling (automatic OptimalControl / JuMP tests on the intersection), or a sourced
reference_objective. - Drift is caught by tests: fast consistency tests on every PR, slow tests in a weekly cron (as in CTFlows.jl).
- The collection grows, including from SciML's OptimalControlBenchmarks (Corleone), with clean documentation of all this.
This builds on the port to OptimalControl v2 (#283) and the JuMP schemes (#284), both tracked in control-toolbox/CTBenchmarks.jl#200 for the benchmark paper. Roadmap: #257.
Work, in order
Step 0 brings the repository infrastructure in line with the other packages; steps 1 to 3 are the base; steps 4 to 7 can then go in parallel.
- Repository infrastructure: [Chore] Harmonize repository metadata and ct-conventions integration with CTBase #313 (harmonization with ct-conventions:
AGENTS.md, labels, templates, lint), then [Chore] Release and CI infrastructure: CHANGELOG, BREAKING, release workflows, label-gated CI #312 (release infrastructure). Agents working on the other sub-issues needAGENTS.mdand the pinned conventions. - Per-modeling lists and consistency tests: [Dev] Per-modeling lists of problems, discovered automatically, with a status per modeling #303, [Tests] Test layout per environment and consistency tests #304 (with [Doc] Typo in the docstrings #172, [Doc] Examples are not displayed correctly in the REPL #173 under [Dev] Per-modeling lists of problems, discovered automatically, with a status per modeling #303).
- Port to OptimalControl v2 and new problem interface: [Paper] Port to OptimalControl v2 and new problem interface #283 (with [Dev] Exa and problems #136). The problem returns the continuous problem and its initial guess; modeler, options, scheme and CPU/GPU are chosen in
solve, so this package no longer passes modeler options. - Weekly cron: [Tests] Crons per scope for the slow tests, with reports #305.
- JuMP with Euler, trapezoid and midpoint, factorised in
ext/JuMPModels/schemes.jl, and NLP equivalence tests against ADNLP and Exa: [Paper] JuMP models for Euler, trapeze and midpoint, and NLP equivalence tests #284 (with [General] Test comparaison NLP model #166). - Metadata and shared initial guess: [Metadata] Computed features, reference objective, shared initial guess #306 (with [Doc] Intial guess #151); measure, then keep or drop the
_svariants: Description and problems #174. - Plots in a Plots extension, shared by OptimalControl solutions and JuMP models: [General] Plots #175, [General] Visualisation #134; documentation: [Doc] Rewrite the documentation: getting started, user guide, problems, developers #307 (with [Doc] review of examples published on the website #229).
- Corleone's OptimalControlBenchmarks: [Problems] Proof of concept: a ModelingToolkit modeling, solved with Corleone, with our own bryson_denham #308.
- Precompile the problems, so that users and tests do not recompile them (later, not a priority): [Dev] Precompile the problems so that users and tests do not recompile them every time #373.
- Restore the full CI matrix (Julia 1.10, macOS, Windows) at the end of the reorganisation: Restore the full CI matrix (Julia 1.10, macOS, Windows) after the reorganisation #344.
Decisions
- Object returned by an OptimalControl problem: a struct
(name, ocp, init, metadata)holding the continuous (mathematical) problem, not a discretized one. Discretization is left to the user, throughsolve(descriptive or explicit mode) ordiscretize. See [Paper] Port to OptimalControl v2 and new problem interface #283. - Availability in a modeling: deduced from file presence, the single source of truth. See [Dev] Per-modeling lists of problems, discovered automatically, with a status per modeling #303.
- Problem available in OptimalControl only: a sourced
reference_objectiveis enough. - Euler in JuMP: explicit at least, implicit too (one more function once schemes are factorised). See [Paper] JuMP models for Euler, trapeze and midpoint, and NLP equivalence tests #284.
- Corleone: a proof of concept at the end, as an extension, on one problem. See [Problems] Proof of concept: a ModelingToolkit modeling, solved with Corleone, with our own bryson_denham #308.
- Branch: no long-lived branch. [Dev] Per-modeling lists of problems, discovered automatically, with a status per modeling #303, [Tests] Test layout per environment and consistency tests #304 and [Dev] Add AGENTS.md (referenced by CONTRIBUTING.md) #309 are not breaking and go to
mainon the 0.5 API. The port then goes tomainthrough PRs, with the version set to 0.6.0-beta (as OptimalControl, whosemainis 2.2.1-beta) anduse_ct_registry: truein the workflows.
What each modeling returns
Rule: each modeling returns the most abstract object it can represent, and takes at retrieval only what it needs to build it.
| Modeling | Returned object | Arguments at retrieval |
|---|---|---|
| OptimalControl | continuous problem: struct (name, ocp, init, metadata) |
parameters |
| JuMP | NLP, necessarily discretized | grid_size, scheme, JuMP.Model arguments |
| Corleone (PoC) | MTK system and its grids (path constraints are sampled in the constructor) | control_grid, shooting_grid, constraint_grid |
grid_size and scheme in JuMP use exactly the names and values of OptimalControl.Collocation (:euler, :euler_implicit, :trapeze, :midpoint), so that tests build both NLPs identically.
Checks between modelings
- Same discretization (JuMP, ADNLP, Exa): NLP equivalence ([Paper] JuMP models for Euler, trapeze and midpoint, and NLP equivalence tests #284). It also implies the same mathematical problem.
- Same mathematical problem, different methods (Corleone): evaluate the optimal control found by OptimalControl in the other model (cost, constraint violation), and compare optima with a loose tolerance ([Problems] Proof of concept: a ModelingToolkit modeling, solved with Corleone, with our own bryson_denham #308).
- Reference:
reference_objective([Metadata] Computed features, reference objective, shared initial guess #306).
How to work on this
Each sub-issue is closed by one or a few PRs. Tick the decisions above when taken, and record them in the relevant sub-issue.
Activity
ocots commentedon Nov 4, 2026
Decisions taken while detailing #303:
_svariants become a modeling of their own,OptimalControlScalarizedBackend, maintained like the others (no morep_sfunctions).:draftor:valid. A problem is provided (problems(backend)) only where it is:valid;:validin a second modeling requires consistency with the first. Drafts stay in the repository; calling one emits a warning. The status board (problem × modeling) is generated in the documentation, and the cron reports drafts ready to be validated.core, one per modeling,comparison,Corleone); the cron is a mode of each. Moved to [Tests] Test layout per environment and consistency tests #304.main.6 remaining items
test: replace the comparison tests by the comparison environment, wit…
ocots commentedon Nov 4, 2026
Update: #303 is closed (PR #320, with #319 = #304 steps 1–2 and 6, #321, #322). New follow-up #323 (test of the automatic discovery and of the precompilation cache), difficulty ★★, can be taken by an agent once #304 is done (it uses the layout
test/suite/core/). Julia matrix is now 1.10 and 1.13. The labelrun ci github-runnernow triggers the CI by itself.ocots commentedon Nov 4, 2026
Correction to my previous update: #323 can be taken now — it only needs the layout
test/suite/core/, already onmain(#319). Starting notes are in #323 (comment) (branch frommain; respect the metadata schema and the no-hand-written-list test of #324).ocots commentedon Nov 4, 2026
Follow-ups opened since the guide (so that they are not forgotten). They extend the table of the guide; same rules (claim, worktree, draft PR).
test/suite/core/(onmain)problem=a,b)problem=)SGN1–SGN6)-p(t)workaround of the docs (#307, #314) and add costate comparisons tocomparisontest …label from a release PRNotes recorded elsewhere, to apply when taking the issue concerned:
:reference_objectiveand a list of local objectives, per default grid and per scheme; three levels of test: converges, known solution, global), a cron test of the robustness of the initial guess (several Ipopt options), and the rule that an initial guess must converge without being too close to the solution.ExaModelsbound oftest/suite/OptimalControl/Project.toml(Julia 1.13 conflict of the v1 stack); replaceLocalTestRunnerbyCTBase.run_tests; the GPU jobs and theTST6contract belong there.:schemeto the JuMP contract.ocots commentedon Nov 5, 2026
Table of the sub-issues, updated 2026-11-05
This table replaces the two tables of the guide (section 1) and of the follow-ups comment. The rules for agents are unchanged and are in the guide: read it first (choosing and claiming an issue, one worktree per issue, draft PR, narration, stop and report, never merge, never edit a description). An issue can be started only when every issue it depends on is closed (its PR merged).
Difficulty: ★ mechanical · ★★ several files, a few choices · ★★★ design inside a detailed specification · ★★★★ delicate (exact equivalence, new infrastructure, cross-repository effects).
Done
To do, in order
Problemtype, continuous problems, CPU testsCTModels.Solutionfrom a solved JuMP modelLocalTestRunnerbyCTBase.run_testsIndependent follow-ups (any time, unless stated)
mainnow that #324 is mergedproblem=a,b, available since #324)SGN1–SGN6)-p(t)workaround of the docs (#307, #314)test …label from a release PRNot scheduled
_sproblem variants #285._sproblem variants #285 measure, then clean up the_svariants; [Paper] Problem metadata: reference objectives and shared initial guess #286 reference objectives and shared initial guess (specification of [Metadata] Computed features, reference objective, shared initial guess #306); [Paper] New problems: analytic solutions, large state dimension, roadmap #287 new problems for the paper; [Dev] Enrich the list of problems #179 enrich the list of problems; [Doc] review of examples published on the website #229 review of the examples of the website (with [Doc] Rewrite the documentation: getting started, user guide, problems, developers #307). They have no place in the order yet; do not start them without the maintainer.Notes recorded elsewhere, to apply when taking the issue concerned
:reference_objectiveand the local objectives, per default grid and per scheme: three levels of test, converges / known solution / global); a cron test of the robustness of the initial guess; an initial guess must converge without being too close to the solution.ExaModelsbound oftest/suite/OptimalControl/Project.toml(Julia 1.13 conflict of the v1 stack);CTBase.run_testsreplacesLocalTestRunner([Tests] Replace the local test runner by CTBase.run_tests #332); GPU jobs and theTST6contract belong to [Tests] GPU tests for the OptimalControl modelings (Exa + MadNLP on GPU) #330.:schemeto the JuMP contract.ocots commentedon Nov 5, 2026
CI matrix reduced during the reorganisation (decision of the maintainer).
run ci github-runnernow starts one job instead of six. The weekly crons ([Tests] Crons per scope for the slow tests, with reports #305) already run Julia 1.13 only.@testsettype, only on 1.10; test: verify automatic discovery and precompilation cache #325: Windows line endings). Agents must keep Julia 1.10-compatible code (no syntax or API newer than 1.10;@testsettakes a bare type name) and Windows-safe paths and line endings, even though the CI no longer checks them.Rules of the first comment of this issue are unchanged.
ocots commentedon Nov 5, 2026
Status, 2026-11-05: items outside the steps above
Open and not part of steps 0–7, to keep in view:
CTBase.run_tests, PR test: replace the local test runner by CTBase.run_tests (#332) #349 (draft, stacked on feat: port to OptimalControl v2, Problem type and continuous problems #331).demo/305-failures, commit "beam and chain fail", failures wanted). Not regressions:beamandchainreachLOCALLY_SOLVEDwith JuMP/Ipopt on the default grid. To close.Step 2 (#283): part 1 is PR #331 (draft, CI running), then #329 and #330.
🤖 Generated with Claude Code
ocots commentedon Nov 5, 2026
Table of the sub-issues, updated 2026-11-05 (evening)
This table replaces the table of this morning and the status of 11:02. The rules for agents are unchanged and are in the guide: read it first (choosing and claiming an issue, one worktree per issue, draft PR, narration, stop and report, never merge, never edit a description). An issue can be started only when every issue it depends on is closed.
Difficulty: ★ mechanical · ★★ several files, a few choices · ★★★ design inside a detailed specification · ★★★★ delicate (exact equivalence, new infrastructure, cross-repository effects).
Done
CTModels.Solutionfrom JuMP (#353), #330 GPU tests (#354, with #357), #332CTBase.run_tests(#349)test convergenceTo do, by independent package
Packages A, B and C can run in parallel; D waits for B; E is last.
A. JuMP schemes and NLP equivalence — theme #284 (spec in its comments)
schemes.jlducted_fanHessian discrepancy (#166)B. Metadata and references — #306
ext/JuMPModels/<problem>.jl, rewritten by #368: coordinate, or do it after #368Once references exist, the convergence report (#360) shows the gap to them; it is empty until then.
C. Documentation
D. Results and plots (after B and C)
E. Last
Independent, any time
moonlander(OptimalControl, Windows) no longer converges (ITERATION_LIMIT)SnoopCompilefirsttest …label from a release PRNot scheduled
_sproblem variants #285_svariants, [Paper] Problem metadata: reference objectives and shared initial guess #286 paper metadata (specification of [Metadata] Computed features, reference objective, shared initial guess #306), [Paper] New problems: analytic solutions, large state dimension, roadmap #287 new problems, [Dev] Enrich the list of problems #179 enrich the list: no place in the order yet; do not start them without the maintainer.Notes to apply when taking the issue concerned
:reference_objectiveand the local objectives, per default grid and per scheme); a cron test of the robustness of the initial guess; an initial guess must converge without being too close to the solution. The gap to the reference is reported only when a reference exists ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360).:schemeto the JuMP contract. Equivalence tests are hard tests, run on every PR ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360).SMOKE_GRID,SMOKE_MAX_ITER, finite objective) intest/suite/<env>/; a convergence result goes intest/cron/<env>/throughTestStatus.result!, never@test. Seetest/README.md.🤖 Generated with Claude Code
ocots commentedon Nov 7, 2026
Update, 2026-11-07: cron reports triaged, new issue #409.
moonlanderconverges again; the robustnessnew solutionrows came from the first run of that scope and are now known solutions (5c580b3); thecomparisonsection was stale sinceCronComparison.ymlwas removed ([Tests] Compare the JuMP schemes on problems chosen by their features, not on every problem #401). Thecomparisonscope was also removed fromresults(cron/comparison.md,cron/state.json).AbstractReferencetype withAnalyticReferenceandNumericalReference, and a qualified API. Never written by hand; no trajectories ([Doc] Results pipeline for the documentation, and a gallery of problems #314's). Two PRs: record in the tests, then (after crons onmain) store and expose.It joins package B of the table of 2026-11-05 (evening):
Coordination: #408 (docs) reads the reference files; #409 only adds fields. #314 keeps the trajectories, plots and full environments of the runs.
🤖 Generated with Claude Code
ocots commentedon Nov 7, 2026
Table of the sub-issues, updated 2026-11-07 (afternoon)
This table replaces the table of 2026-11-05 (evening) and the update of 2026-11-07.
Before taking an issue, read the guide for agents. It covers choosing and claiming an issue, one worktree per issue, the plan before code, draft PRs, narration, stopping and reporting, never merging and never editing a description. Its rules are unchanged. An issue can be started only when every issue it depends on is closed.
Difficulty: ★ mechanical · ★★ several files, a few choices · ★★★ design inside a detailed specification · ★★★★ delicate (exact equivalence, new infrastructure, cross-repository effects).
Free: to take, by theme
Code structure
src/into submodules (MOD1,MOD2), keeping the public exports (decision in the issue)References/.JuMP models
Documentation
SITE4)Results and plots
Waiting
docs/modelings.jl, #408)Independent, any time
bypassof the robustness teststest …label from a release PRbuild_solutionfrom model informationNot scheduled
_sproblem variants #285_svariants, [Paper] Problem metadata: reference objectives and shared initial guess #286 paper metadata (its specification is done by [Metadata] Computed features, reference objective, shared initial guess #306), [Paper] New problems: analytic solutions, large state dimension, roadmap #287 new problems, [Dev] Enrich the list of problems #179 enrich the list, [Roadmap] Update OptimalControlProblems for v2 and add new problems #257 roadmap: no place in the order yet. Do not start them without the maintainer.scripts/breakage/consumers.jlonce it is updated.Notes to apply when taking an issue
SMOKE_GRID,SMOKE_MAX_ITER, finite objective) intest/suite/<env>/.test/cron/<env>/throughTestStatus.result!, never@test.test/README.md.tools/references/update.jl, [Metadata] Reference objectives per scheme, computed by a script #375, [Cron] Robustness of the initial guess and known local objectives #378).:reference_solutionand is checked on the model ([Metadata] Declared fields: tags, references, Corleone, reference solution #379).:initof its metadata, read by every modeling. Never write one in a model file.ext/README.mdand the Developers pages (docs: rewrite the documentation, problem pages with one tab per modeling #408). No list of problems is written by hand; a test checks it.In progress, or almost done
AbstractReference,AnalyticReference,NumericalReference, qualified API (★★★)test/only, independent of #413). Part 2 comes after #413 and after crons onmain.Done
CTBase.run_testsducted_fanHessian; #399 scalarized models; #401 schemes compared on problems chosen by their featuresmu_initandbarrierreach MadNLP (#322)🤖 Generated with Claude Code
ocots commentedon Nov 11, 2026
Written by Claude (Claude Code) at the request of ocots.
Table of the sub-issues, updated 2026-11-11
This table replaces the table of 2026-11-07 (afternoon), which is kept as a trace. Most of what it listed as free or waiting has been delivered since.
Before taking an issue, read the guide for agents. It covers choosing and claiming an issue, one worktree per issue, the plan before code, draft PRs, narration, stopping and reporting, never merging and never editing a description. Its rules are unchanged. An issue can be started only when every issue it depends on is closed.
Difficulty: ★ mechanical · ★★ several files, a few choices · ★★★ design inside a detailed specification · ★★★★ delicate (exact equivalence, new infrastructure, cross-repository effects).
Where we are
Steps 0 to 6 of the plan above are delivered, and step 7 (#308, ModelingToolkit with Corleone) is merged and waits for its first cron result and a decision. What is left is the review of the result (#449), a few follow-ups, and the CI matrix (#344), the last step before the release.
Open: to take or to follow
JuMP models
rules/signs.md-JuMP.dual, stamped at the step midpoints, compared with OptimalControl intest_solution, docs workaround removed). Still open: to close by the maintainer, or to say what remains; the other duals are #430.Results and plots
solution(model, pb)exists (#353) and the costates now have the same sign. Problems available in JuMP only still wait for control-toolbox/CTModels.jl#515.Tests
test/common/optimalcontrol_tests.jlovertest/common/modeling_tests.jl.bypassof the robustness testsReview
Waiting
main(launched on 2026-11-11, run 43061056587) and the decision of the maintainer: write more problems this way, or not. See below.State of #308
Delivered by #440 (#437), #442 (#438) and #444 (#439):
ModelingToolkitBackendand theModelingToolkitModelsextension; four continuous problems,bryson_denham,vanderpol,robbinsandjackson(a Lagrange cost, state bounds with boundary conditions, a Mayer cost with state and control bounds).test/common/solve_modelingtoolkit.jl): single shooting, controls piecewise constant, path constraints imposed at the nodes of the grid, controls started from the initial guess of the problem, the violation of the constraints computed, the trajectory read from the problem solved.ModelingToolkitenvironment, opt-in (labeltest ModelingToolkit backend), and a weekly cron (Saturday 04:00 UTC, Ubuntu and Windows). The tests follow the three kinds of [Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360: the Problem API and the smoke solves are shared with the OptimalControl modelings (test/common/modeling_tests.jl), and the equivalence with the OptimalControl and the scalarized models is checked at the continuous level, without a solve, bysuite/ModelingToolkit/test_modelings(theSystemis read as the data of a JuMP problem and compared byContinuous.compare, Rationalize JuMP and comparison test suites: separate generic transcription unit tests from per-problem modeling checks #441).tools/ci/scope.py: an opt-in environment asked for by a label was lost when a shared file made the CI run everything.Differences with the specification of the issue, to take into account in the decision (the reasons are in this comment of #308):
test_reference_solutionand no cross-evaluation with Corleone's objective. Convergence is reported, not tested ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360), and the equivalence is checked at the continuous level, which catches a wrong model on every pull request (each change of a parameter of the ModelingToolkit model fails exactly the matching check).checked_againstisnothing, since the comparison runs in the opt-in environment only.reference_objectiveof [Metadata] Reference objectives per scheme, computed by a script #375 is the trapezoidal one.bryson_denham,cart_pendulum,dielectrophoretic_particle,double_oscillator,ducted_fan,jackson,mountain_car,robbins,van_der_pol,hang_glider,goddarts_rocket, ...), a source of inspiration for the problems to port.Independent, any time
test …label from a release PRbuild_solutionfrom model informationThe cron summary issues (#435
cron-failure, #436cron-convergence) are generated: triage them as described in.github/workflows/README.md.Done since the table of 2026-11-07
src/split into submodules_svariants measured and cleanedcomparison)The items of the earlier tables (infrastructure, lists and statuses, OptimalControl v2, crons, tests, CI, JuMP schemes, metadata) are unchanged: see the table of 2026-11-07.
Notes to apply when taking an issue
SMOKE_GRID,SMOKE_MAX_ITER, finite objective) intest/suite/<env>/.test/cron/<env>/throughTestStatus.result!, never@test.suite/comparison/test_modelings,suite/ModelingToolkit/test_modelings), and on the NLP for the JuMP discretization ([Tests] NLP equivalence tests between JuMP, ADNLP and Exa #371).Problemare written once (test/common/modeling_tests.jl); a new modeling gives an adapter, not a copy.test/README.md.ModelingToolkit,GPU), which a shared file no longer drops. PR CI is Ubuntu and Julia 1.13 only until Restore the full CI matrix (Julia 1.10, macOS, Windows) after the reorganisation #344, so keep code Julia 1.10-compatible and Windows-safe.tools/references/update.jl, [Metadata] Reference objectives per scheme, computed by a script #375, [Cron] Robustness of the initial guess and known local objectives #378).:reference_solutionand is checked on the model ([Metadata] Declared fields: tags, references, Corleone, reference solution #379).:initof its metadata, read by every modeling. Never write one in a model file.ext/README.mdand the Developers pages (docs: rewrite the documentation, problem pages with one tab per modeling #408). No list of problems is written by hand; a test checks it. A problem written in a new modeling also needs its:statusentry for that modeling.🤖 Generated with Claude Code