Repository navigation
Description
Agents: read the guide for agents in #310 first (order, difficulty, how to claim an issue, working method). The specification is in this description and in the comments below.
Updated on 2026-11-06 after #360 (convergence is reported, not tested) and #375 (reference objectives). Where an older comment contradicts this description, the description wins; what changed is listed in the update comment.
Goal
Rewrite the documentation for the new package: continuous problems (#283), per-modeling lists and statuses (#303), JuMP schemes (#284), metadata (#306), results pipeline and gallery (#314). Most of today's content describes the v1 API (direct_transcription, docp, nlp_model(docp)) and is rewritten, not patched. English (GEN1).
Part of #310, step 6. Order: after the mechanical migration to VitePress (#311), so that the new content is written once, directly in the VitePress structure; #314 in parallel.
References
- OptimalControl.jl dev documentation, https://control-toolbox.org/OptimalControl.jl/dev/ (the stable site is not up to date): structure (Getting started → usage sections → Examples gallery → API → migration page), the Installation page ("you will also need…", table "to do X, load Y"), the gallery table (story / introduces), hidden checks (
@assert isapprox(objective(sol), 6; rtol=1e-3) # hide, used in 36 pages). - CTBase.jl and CTFlows.jl documentation: Getting Started, guides by topic, developer notes, API Reference.
- ct-conventions
rules/site.md(SITE1–SITE18).
Current state
Six hand-written pages (index.md, problems-introduction.md, tutorial-get.md, tutorial-solve.md, dev-add.md, dev-api.md), generated problem pages (docs/problems.jl) and the browser (docs/browser.jl). The problem page template assumes both OptimalControl and JuMP exist and solves both at build time.
Structure
| Section | Pages |
|---|---|
| Home | VitePress home page |
| Getting started | Installation: what to install for what, as a table (OptimalControl modeling: OptimalControl and a solver package; GPU: MadNLPGPU, CUDA, CUDSS; JuMP: JuMP and Ipopt; Corleone: its package, #308; plots: Plots), explaining that each modeling is an extension; Your first problem; Guided tour |
| User guide | Get a problem (lists per modeling, statuses, parameters, features); Solve with OptimalControl (descriptive and explicit modes, GPU); Solve with JuMP (schemes, ordering, getting a Solution); Initial guess (#151, and how to override it); Compare modelings (same NLP, #284; solutions are not compared: two solves are two optimization paths); Plot and visualize (plot(sol), plot!, visualize, #175, #134) |
| Problems | Overview (modelings, statuses, metadata, reference objective and how it is computed, references); Gallery (#314); Status (public: statuses per modeling, and the latest convergence report of the cron, #305: solver status and gap to the reference per configuration, change since the previous run; no pass/fail on convergence); one page per problem, reached from the gallery, not listed in the sidebar |
| Developers | Add a problem (checklist, from :draft to :valid, what is automatic, which tests run); Tests and CI (the three kinds of tests of #360: does not break, model equivalence, convergence report; environments, labels run ci …, test …, test convergence, #304); Crons and automatic issues (#305); Results pipeline (#314) |
| API Reference | generated with with_api_reference (SITE1, SITE2, SITE10): problems, metadata, status, Problem and its API, backends, features, visualize. The generated docstrings of each problem go on its page, not in the API Reference |
| Migrating from 0.5 | short page, low priority: the breaking changes of 0.6, taken from BREAKING.md |
The word "tutorial" is not used.
Problem page
Generated from one template; each section appears only if its content exists (a problem may exist in OptimalControl only, in JuMP only, with or without Corleone):
- Header: name, status badge per modeling, tags, freshness of the results ([Doc] Results pipeline for the documentation, and a gallery of problems #314).
- Description and mathematical formulation (
ext/Descriptions/<p>.md). - Parameters and features ([Metadata] Computed features, reference objective, shared initial guess #306).
- Get and solve: one tab per available modeling (VitePress
::: code-group), short code, not executed beyond trivial calls. - Results (from
result.json, [Doc] Results pipeline for the documentation, and a gallery of problems #314, produced by the convergence cron): table per modeling and configuration with the solver status, the objective, the iterations, the time and the relative gap to the reference objective ([Metadata] Reference objectives per scheme, computed by a script #375), with how the reference was computed. No ✓ or ✗ on convergence and no tolerance ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360): the gap is shown as it is. ✓ or ✗ only for what is tested: does not break, model equivalence. The build never fails on them. - Plots: available solutions overlaid;
visualize.svgwhen it exists. - Comparison, only if the problem is
:validin at least two modelings: NLP equivalence status ([Paper] JuMP models for Euler, trapeze and midpoint, and NLP equivalence tests #284). Not the gap between the objectives of two modelings: that compares two optimization paths, not two models; each configuration's gap to the reference is in the results. - Reproducibility block ([Doc] Results pipeline for the documentation, and a gallery of problems #314).
Executed code
- No heavy computation at build time: solves come from the
resultsbranch ([Doc] Results pipeline for the documentation, and a gallery of problems #314). - User guide pages execute short code, with hidden checks (
@assert … # hide) as in OptimalControl.jl.
Also closes
- [Doc] review of examples published on the website #229: wrong first-line comment, formatting of named tuples, plot labels (solved by
plot!(sol)), a note on the MKL warning on macOS ARM (upstream), stale CT* versions (gone with [Paper] Port to OptimalControl v2 and new problem interface #283). - [Doc] Intial guess #151: Initial guess page.
Done when
- Structure above in the VitePress site; old pages removed.
- Installation page explains each extension and what to install.
- Problem pages generated with conditional sections; shown on a problem with one modeling, one with two, one with missing results.
- User guide pages execute short code with hidden checks.
- Status page public; gallery links to it.
- [Doc] review of examples published on the website #229 and [Doc] Intial guess #151 closed.
Activity
ocots commentedon Nov 4, 2026
Additions (decided in #305):
:draft/:valid, from the metadata, [Dev] Per-modeling lists of problems, discovered automatically, with a status per modeling #303), and the latest cron results per scope (date, run link, pass/fail per configuration, known failures), read from the report files the crons commit to thecron-reportsbranch. Public page or developer page: to decide when writing it. If the branch or a report is missing, the page says so instead of failing the build.ocots commentedon Nov 4, 2026
Updates:
cron/directory of the sharedresultsbranch ([Doc] Results pipeline for the documentation, and a gallery of problems #314), not from acron-reportsbranch.[-][Doc] Documentation for v2 and per-modeling lists[/-][+][Doc] Rewrite the documentation: getting started, user guide, problems, developers[/+]ocots commentedon Nov 4, 2026
Every modeling handled generically (OptimalControl, OptimalControlScalarized, JuMP, and Corleone later, #308):
docs/): display name; the short code to get and solve a problem (the::: code-grouptab of the problem page); how its result is computed and written toresult.json([Doc] Results pipeline for the documentation, and a gallery of problems #314); how its solution is plotted (aCTModels.Solutionwhen there is one, see [Paper] Port to OptimalControl v2 and new problem interface #283; otherwise what is available).ocots commentedon Nov 4, 2026
Correction: where this issue says "Corleone" as a modeling, read ModelingToolkit (
ModelingToolkitBackend, #308): the problem is a ModelingToolkit system, and the documentation adapter shows how to get it and solve it with Corleone. Installation page: ModelingToolkit for the modeling, Corleone to solve it.ocots commentedon Nov 4, 2026
Decision: Developers section = one generic page + READMEs next to the code.
Instead of four hand-written pages (Add a problem, Tests and CI, Crons and automatic issues, Results pipeline), which would drift as #303, #304, #305 and #314 land, the documentation keeps a single generic Developers page: overview, the guiding principle (everything that can be computed is generated or checked, never maintained by hand), and links to READMEs placed in the directories they describe.
ext/README.md(main one: the plan):draft→:valid; add a problem; add a modeling (entry in the modeling table + documentation adapter); table "I want to do X → read Y"ext/<Modeling>/README.mdext/MetaData/README.mdreference_objectiveext/Descriptions/README.mdtest/README.mdrun ci …/test …, how to add a test (#304).github/workflows/README.mdRules:
main). To revisit if [Doc] Migrate the documentation to DocumenterVitepress #311 offers a clean way to include the READMEs at build time.docs/src/dev-add.mddescribes the v1 API and is removed, not patched.Changes to the structure table above: the Developers row becomes "one generic page, linking to the READMEs"; the 'Done when' item "Structure above" is read accordingly.
ocots commentedon Nov 6, 2026
Update after #360 and #375
Principle since #360: three kinds of tests. Does not break (every CI run, short) and model equivalence (every CI run, no solve) can fail; the convergence report (cron, or label
test convergence) gives the solver status and the relative gap of the objective to the reference objective (#375), never fails, no tolerance. The description is updated::known_failuresis dropped ([Metadata] Computed features, reference objective, shared initial guess #306).tools/references/README.md([Metadata] Reference objectives per scheme, computed by a script #375), the tests intest/README.md;ext/MetaData/README.mdcovers the metadata format and statuses and links to them.🤖 Generated with Claude Code
ocots commentedon Nov 7, 2026
Taken by an agent; draft PR to follow. A plan is proposed to the maintainer before any code.
ocots commentedon Nov 7, 2026
Written by Claude (Claude Code) at the request of ocots.
Draft PR #408. Choices made there, to review:
docs/modelings.jl; nothing solved at build time.ext/MetaData/references/<problem>.toml([Metadata] Reference objectives per scheme, computed by a script #375) already holds every result per modeling, configuration and platform, and the distinct solutions, so the pages show results and comparisons without waiting for [Doc] Results pipeline for the documentation, and a gallery of problems #314.ext/README.mdwritten in docs: rewrite the documentation, problem pages with one tab per modeling #408: the Developers page links to READMEs, and the main one (add a problem, add a modeling) did not exist.🤖 Generated with Claude Code
ocots commentedon Nov 8, 2026
Done: every item of "Done when" is checked and verified on
main.tutorial-*.mdpages are gone.modelings().@assert … # hide).One divergence from the specification, intentional:
visualize/visualize.svgare obsolete since #134 was closed not planned — solutions are drawn in the browser (ProblemPlot.vue) from the trajectories the convergence crons publish.