Skip to content

[Tracking] Review of the rewritten repository, by theme #449

Open

Description

@ocots

Goal

The repository has been rewritten end to end: code, tests, documentation, workflows. Most of it comes from #310, but not all of it. This issue tracks a review of the result by theme. It does not check that the plan of #310 was followed. It checks that the result holds together:

  • Coherence: code, docstrings, READMEs, documentation and AGENTS.md say the same thing.
  • Conventions: the code follows ct-conventions v0.14.0 (pinned in AGENTS.md). Cite rules by identifier.
  • Presentation: developers find their way through the READMEs, and users through the documentation.
  • Improvements: what could be simpler, clearer, or more automated.

How to work on this

  • Review one theme at a time. Post findings as a comment here, headed by the theme number (T3 — …).
  • Trivial fixes: one small PR per theme, Refs #<this issue>. Anything larger gets its own issue, linked from the theme.
  • Tick a theme when it has been reviewed and its findings are fixed or turned into issues.
  • The "Known leads" below were spotted while preparing this issue. Check them first, but the review is not limited to them.

Suggested order: T1 → T2 → T3 → T4 → T5 → T8, with T6 and T7 in parallel. The user documentation describes everything else, so it is best re-read after the code has settled.


Themes

T1 — Package architecture and public API (src/)

Scope: src/OptimalControlProblems.jl, the submodules Modelings, Metadata, References, Catalogue, Problems, src/README.md.

  • Each submodule has one responsibility, and they depend on each other in the right order (MOD1, MOD2, MOD7).
  • Imports are qualified and the public / internal split is explicit (MOD3, MOD4, MOD8).
  • Errors are typed and chosen by the choice rule (EXC1). Hot paths are type-stable (TYP8, PERF*), and 1-D values are scalars (DIM1).
  • Docstrings of public symbols are complete and match the code (DOC1–DOC8).
  • The API is right-sized: no redundant accessors, and names are consistent with OptimalControl v2.

Reviewed and fixed in #457 (findings); the API levels page is #458.

Known leads:

T2 — Problem data: metadata, descriptions, references (ext/MetaData, with the descriptions since #465, ext/MetaData/references)

  • METADATA_SCHEMA covers every field in use, and no field is unused.
  • Every <problem>.jl uses the same structure (:grid_size, :parameters, :status, :init, :notes, :reference_solution…).
  • Descriptions: same outline, correct mathematical formulation (matching the models), and sourced ### References.
  • Reference TOML files: provenance is clear, and tools/references regenerates them.
  • :draft statuses and :notes are still current.

Reviewed and fixed in #460 and #461 (findings). The descriptions share one outline, checked by a test. One thing is left: whether each mathematical formulation matches its models (to read in T6/T7). The descriptions are now next to the metadata, ext/MetaData/<problem>.md (#465).

T3 — Modelings (ext/*Models, ext/*.jl)

Scope: OptimalControl, OptimalControlScalarized, JuMP (and JuMPModels/schemes/), ModelingToolkit (proof of concept, #308).

Progress: the linter of the problems (#467: what it checks, what other tools check, what is left to check by hand, as a PR checklist; bounds from the parameters, dead reads removed), the skeleton of a new problem or modeling (#468), bryson_denham JuMP named as in OptimalControl and :valid (#469), qualified imports in the OptimalControl and JuMP extensions (#471, MOD4). The cart_pendulum comment on J = mcart is left for the check of the formulations (T6/T7). The layout block of AGENTS.md goes to T8.

Known leads:

  • The layout block in ext/README.md does not list ModelingToolkitModels.jl / ModelingToolkitModels/.
  • The layout block in AGENTS.md lists OptimalControlScalarizedModels, MetaData and Descriptions as extensions and omits ModelingToolkitModels. Project.toml declares three extensions: JuMPModels, ModelingToolkitModels, OptimalControlModels.

T4 — Test suite (test/)

Scope: test/runtests.jl, test/common/, test/suite/<env>/, test/cron/, test/robustness/, test/extras/, test/README.md.

T5 — CI, crons, references pipeline, release (.github/, tools/)

Scope: .github/workflows/*.yml, cron-reusable.yml, labels, tools/ci/, tools/cron/, tools/references/, .github/workflows/README.md, CHANGELOG.md, BREAKING.md.

  • Every workflow is still needed. Triggers and labels are consistent with the label list and test/README.md (label dispatch, CTActions#149).
  • Cron issues ([Cron] cron-failure #435, [Cron] cron-convergence — 1 finding #436) are readable and actionable, as .github/workflows/README.md describes.
  • The Python tools are tested and documented. Is a tool duplicated in CTActions?
  • CHANGELOG.md / BREAKING.md cover all user-visible changes since 0.5 (CHG*), and the migration guide matches them.
  • The release path is ready (REL1–REL7, ct-agents v0.4.0).

Known leads:

T6 — User documentation, hand-written pages (read by the maintainer)

Scope: docs/src/index.md, getting-started/*, guide/*, problems-overview.md, migration.md.

  • Reading path: Introduction → Installation → First problem → Guided tour. A newcomer can follow it.
  • Each guide page answers one question, without overlapping the others.
  • The code examples run and are up to date with OptimalControl v2 (dev site).
  • Tone, length and terminology are consistent (problem / modeling / backend / scheme).
  • migration.md matches BREAKING.md.
  • ModelingToolkit / Corleone: no page shows how to solve a ModelingToolkit problem with Corleone. The ModelingToolkit snippet in docs/modelings.jl stops at sys = model(pb). Add a "Solve with ModelingToolkit" guide page, similar to "Solve with OptimalControl" and "Solve with JuMP". It should cover the grids, initial_guess(pb) and the Ipopt solve, and link to the Corleone documentation for details. The problem-page tab is in [Cron/Doc] ModelingToolkit convergence cron, trajectories, and documentation (#308) #439.

Per-page reading checklist:

  • index.md
  • getting-started/installation.md
  • getting-started/first-problem.md
  • getting-started/guided-tour.md
  • guide/get.md
  • guide/solve-optimalcontrol.md
  • guide/solve-jump.md
  • guide/jump-schemes.md
  • guide/initial-guess.md
  • guide/compare.md
  • guide/plot.md
  • problems-overview.md
  • migration.md

T7 — Generated documentation and site machinery

Scope: docs/make.jl, docs/{problems,modelings,results,browser,status,api_reference}.jl, docs/src/components/*.vue, docs/src/.vitepress/.

  • Problem pages: content, tabs per modeling, plots, results from the crons. Read a few pages in full (one per kind of problem).
  • Problems browser, gallery and Status page: usable, filters useful, client-side rendering (SITE*).
  • API Reference: complete, nothing internal leaking, extensions documented.
  • Build scripts: readable, no logic duplicated with src/ (one source of truth), and the build fails loudly when data is missing.
  • Light/dark theme, mobile width, version picker.

Known leads:

T8 — Entry points for developers and repository metadata

Scope: README.md, README.template.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md, docs/src/developers.md, CITATION.*, .zenodo.json, Project.toml (authors, compat).

  • A developer arriving on the repository knows where to go: README.md → developers.md → the per-directory READMEs. Nothing is duplicated, and nothing is missing.
  • AGENTS.md matches the repository (layout, key conventions, recurring tasks).
  • Citation metadata is consistent: authors, title, DOI.

Known leads:

  • README.md says "Each problem is available both in the OptimalControl DSL and in JuMP". This is no longer true: modelings have their own lists, and ModelingToolkit has been added.
  • README.md says the package requires Julia 1.10 or later. Check this against CI (Restore the full CI matrix (Julia 1.10, macOS, Windows) after the reorganisation #344).
  • The LICENSE badge in README.md points to the master branch, but the default branch is main.
  • CONTRIBUTING.md copies the "Contributing" and "Developer Resources" sections of README.md word for word. Keep one, and link to it from the other.
  • Project.toml authors lists one person, while the citation lists four.

Versions: ct-conventions v0.14.0, ct-agents v0.5.0 (updated from v0.11.0 / v0.4.0 on 2026-11-19).

Activity

  1. ocots commented on Nov 19, 2026

    @ocots
    MemberAuthor

    T1 — Package architecture and public API (src/)

    Reviewed against ct-conventions v0.14.0, ct-agents v0.5.0, on main at eba3d484.

    What holds

    • Layout (MOD1, MOD2, MOD7). One directory per submodule, manifests that only declare, dependencies in the documented order (Modelings, Metadata → References, Catalogue → Problems). src/README.md matches the code.
    • Imports (MOD3, MOD4). All qualified (using X: X, using ..Sub: Sub), no import.
    • Exports (MOD8), the known lead. The split is consistent: what the package exports is what the documentation writes unqualified (problems, the backends, the problem functions, Problem, the accessors, problem_metadata, grid_size_data, parameters_data); what it leaves to its submodules is what the documentation writes qualified (status, features, reference_objective, initial_guess_data). test/suite/core/test_modules.jl enforces the structure (every package export is a binding of a submodule, every submodule export is reachable from the package). Whether a name is user API is a judgment no test can make; nothing to change here.
    • Type stability, DIM1. No hot path in src/: it reads metadata (OrderedDict{Symbol,Any} by design) and builds values once. Nothing to check with JET here; the hot paths are in the extensions (T3).

    Findings

    1. EXC1: untyped errors at load time. src/Metadata/loading.jl (4× error(...): missing, unknown or mistyped metadata field) and src/References/objectives.jl (2×: malformed reference table). Each says that one value of a data file is wrong → CTBase.Exceptions.IncorrectArgument with got/expected.
    2. EXC1: features(:unknown) throws an UndefVarError (getfield(Catalogue, problem) in src/Problems/problem.jl) instead of the IncorrectArgument of problem_metadata(:unknown). Check the name first, through Metadata.problem_metadata.
    3. Duplicated check in Catalogue.status. It repeats the unknown-problem check of Metadata.problem_metadata, with an unstructured message (no got/expected/suggestion). It can be Metadata.problem_metadata(problem)[:status].
    4. Metadata.merge re-implements Base.merge. Four methods of a new function merge (shadowing Base.merge in Metadata), each with a full docstring though they are internal, and parameters_data(problem, parameters) catches the PreconditionError of one of them to rethrow another. Simpler: one internal helper on the four cases (nothing/NamedTuple), throwing the final PreconditionError directly, and Base.merge for two NamedTuples.
    5. Coherence: ModelingToolkit missing from two module docstrings. src/OptimalControlProblems.jl ("OptimalControl, its scalarized form, JuMP") and src/Modelings/Modelings.jl (lists three backends) predate the ModelingToolkit modeling.
    6. Minor. Metadata/discovery.jl computes the path of ext/ again instead of sharing Modelings.EXT_PATH. Acceptable: Metadata depends on no submodule, and moving the constant would add a dependency for one path. Leave as is.

    Proposal

    Findings 1–5 in one small PR, Refs #449. No change to the exported API.

    🤖 Generated with Claude Code

  2. ocots commented on Nov 19, 2026

    @ocots
    MemberAuthor

    T2 — Problem data: metadata, descriptions, references

    Reviewed against ct-conventions v0.14.0, ct-agents v0.5.0, on main at eba3d484, with the cron results of the results branch (JuMP 2026-11-17, OptimalControl 2026-11-18, OptimalControlScalarized 2026-11-19).

    What holds

    • Schema. Every field in use is in METADATA_SCHEMA and every field of the schema is used (notes: bryson_denham, mountain_car; reference_solution: beam, bryson_denham). The schema is enforced at load time (typed errors since refactor(src): typed errors and simpler parameter merge (T1 of #449) #457) and by test_consistency.jl, which also checks that a status is declared exactly for the modelings having a model file.
    • Structure. All 22 files have the same order: grid_size, parameters, status, notes, init, reference_solution. The status written on one line or several is the formatter's choice.
    • Reference files. Provenance is clear: a header says they are generated by tools/references/update.jl and must not be edited by hand, and each result keeps its modeling, configuration, platform and run. tools/references/README.md says when to compute them again. Last regenerated on 2026-11-07 ([Metadata] Reference solutions with how they were obtained: typed references and API #409).
    • Sources. Every description has a ### References with entries (test_sources).

    Findings

    1. bryson_denham: a stale note and draft. JuMP is :draft, and the note says "JuMP uses ASCII state component names while the OptimalControl model uses Unicode names". This is no longer true: both models use x1, x2. JuMP passes the convergence cron on Ubuntu and Windows and the robustness cron, with the objective of OptimalControl (4.000143). → Remove the note and set JuMP to :valid. The drafts cron ([Cron] cron-drafts — 2 ready drafts #454) did not list it as ready: to check in T5.
    2. mountain_car: an inaccurate note. It puts the gap on the scalarized model with MadNLP (102.381 against 102.398). The crons show the same 102.381 for modeler=exa solver=madnlp in both OptimalControl and OptimalControlScalarized, and 102.3976 with Ipopt in every modeling. The gap comes from the configuration (exa + MadNLP), not from the scalarized modeling. → Rewrite the note.
    3. Descriptions: the outline differs.
      • The parameters section has three names, "Parameters" (5), "Parameter values" (5) and "System parameters" (7), and is missing in 5 descriptions (beam, brachistochrone, bryson_denham, cart_pendulum, ducted_fan).
      • balanced_field has no "Qualitative behaviour".
      • robbins has no "Mathematical formulation" heading: its formulation is in the introduction.
      • space_shuttle has "References and relevance".
        → Use one outline: Mathematical formulation, Parameters (if any), Qualitative behaviour, Characteristics, References. Check it with a test next to test_sources, so that it cannot drift again.
    4. Descriptions: "Characteristics" repeats computed facts. Several bullets restate what the problem page already shows from features (docs/problems.jl, facts): dimensions, free final time, the kinds of constraints (e.g. mountain_car, chain). They are correct today, but they are written by hand and can drift from the models. → Keep only what cannot be computed (the structure of the solution, why the problem is a benchmark), and drop the restated facts. Maintainer's call.
    5. For T3 / T5.
      • The ModelingToolkit result of bryson_denham (Windows, 2026-11-11, shooting=single solver=ipopt) has the objective 6.875, against 4.000 for the other modelings.
      • It is not in the reference files today. To check in T5: when update.jl runs again, does a ModelingToolkit row (a shooting method, not a scheme) go into the trapeze table?
      • The ModelingToolkit cron itself is failing ([Cron] cron-failure #435).
    6. The formulation matches the models: not checked here. Checking it means reading 22 descriptions against their models. It is in the T6/T7 per-page reading ("Problem pages: content").

    Proposal

    Findings 1–3, with the outline test, in one small PR, Refs #449. Finding 4 waits for the maintainer.

    🤖 Generated with Claude Code

  3. ocots commented on Nov 19, 2026

    @ocots
    MemberAuthor

    T2 — correction of finding 1. The note of bryson_denham is right: the OptimalControl model declares x ∈ R², whose components are x₁, x₂, while the JuMP model names them x1, x2; the comparison of the modelings (test_features) fails when JuMP is :valid. The review had only looked at the parameter names. The status stays :draft (reverted in #460). Making it valid means renaming the JuMP components x₁, x₂ (T3).

    🤖 Generated with Claude Code

  4. added a commit that references this issue on Nov 19, 2026
  5. ocots commented on Nov 19, 2026

    @ocots
    MemberAuthor

    Status on 2026-11-19, and what comes next

    Conventions: ct-conventions v0.14.0, ct-agents v0.5.0.

    Done

    Open pull requests

    Next

    1. The ModelingToolkit cron ([Cron] cron-failure #435). It fails on Ubuntu after about 1h20, with no failed step and no log. GitHub's annotation: "The hosted runner lost communication with the server … starves it for CPU/Memory". The runner dies, not the tests: most likely out of memory. The whole ModelingToolkit/Corleone suite runs in one Julia process. The plan:

      • first, measure the memory locally on all the ModelingToolkit problems, to confirm;
      • then, run each problem in its own Julia process;
      • if that is not enough, move this cron to a self-hosted runner.

      This is also T5.

    2. T2, after fix(data): stale notes, one outline for the descriptions (T2 of #449) #460 and feat(data): the unit and the meaning of every parameter, in the metadata (T2 of #449) #461: move ext/Descriptions/<problem>.md next to ext/MetaData/<problem>.jl, one directory for the hand-written data of a problem. No renaming, no folder per problem.

    3. T3, already found:

      • brachistochrone bounds its control by ±1.57 written in the code (u_min, u_max are unused), and its final time by 0.1 and 20;
      • balanced_field: v_min, v_max, α_min are unused, and its bounds are written in the code;
      • space_shuttle: α_t0 is unused;
      • cart_pendulum: a comment questions J = mcart;
      • bryson_denham: the JuMP components x1, x2 should be x₁, x₂ for it to become valid.
    4. T3/T5:

      • the ModelingToolkit objective of bryson_denham (6.875 against 4.000);
      • whether a ModelingToolkit row could end in the trapeze table of the references;
      • whether the drafts cron is right about bryson_denham.
    5. ModelingToolkit: the other problems with the reduced-time convention, from main, one commit per problem; and the documentation page on the reduced time. Wait for a working cron (1.) before setting them :valid.

    6. The remaining themes: T3 → T4 → T5 → T8, with T6 and T7 in parallel.

    🤖 Generated with Claude Code

  6. added 4 commits that reference this issue on Nov 20, 2026
  7. ocots commented on Nov 20, 2026

    @ocots
    MemberAuthor

    T3 — Modelings

    Reviewed against ct-conventions v0.14.0, ct-agents v0.5.0, on main at 79465cdf. The checks of the template, of the parameters and of the bounds were run by script on the 72 model files, not read by eye.

    What holds

    Findings

    1. Bounds written in the code, parameters unused.

      • brachistochrone (OptimalControl, scalarized, JuMP) bounds the control by -1.57 ≤ u ≤ 1.57 and the final time by 0.1 ≤ tf ≤ 20, written in the code. The parameters u_min, u_max (±π) are read but unused.
      • balanced_field writes tf ≥ 0.1 and v ≥ 1 in its OptimalControl models, and v ≥ 1, h ≥ 0, tf ≥ 0.1 in JuMP. Its α_min is read but unused (the models use 0 ≤ α), and v_min, v_max are never read.

      → Read every bound from the parameters, with the defaults set to the values the models use today, so that no objective changes. Then drop the "not used yet" from their :parameter_info.

    2. Dead reads. mountain_car reads tf_start, and space_shuttle reads α_s, β_s, in all three modelings; only the initial guess of the metadata uses them, a leftover of [Metadata] Shared initial guess in the metadata, read by every modeling #377. space_shuttle's α_t0 is used nowhere. The ModelingToolkit models of chain and jackson read t0 without using it. → Remove the reads, and the parameter α_t0.

    3. MOD4 in two extensions. ext/OptimalControlModels.jl and ext/JuMPModels.jl use bare using OptimalControlProblems, using OptimalControl, using JuMP, using DocStringExtensions; ext/ModelingToolkitModels.jl is compliant. Fixing it qualifies every name in about 60 problem files (OptimalControl.@def, OptimalControlProblems.parameters_data…). It is mechanical, but it changes how the files read. Maintainer's call.

    4. bryson_denham in JuMP: rename the components x1, x2 to x₁, x₂, those of the OptimalControl model (x ∈ R²). Then it can become :valid (see the correction in T2).

    5. cart_pendulum: the dynamics carry the comment J = mcart # should be -(m+mcart) but was mcart?. Check it against the source of the problem.

    6. AGENTS.md (the second known lead): its layout block lists OptimalControlScalarizedModels and MetaData as extensions and omits ModelingToolkitModels. Project.toml declares three: JuMPModels, ModelingToolkitModels, OptimalControlModels. → Fix the block (T8).

    7. Signs of the costates and duals: still open in [Dev] Align the costate and dual signs of the JuMP models with OptimalControl #326 and [Dev] Expose the duals of the JuMP path, boundary and box constraints, aligned with signs.md #430, nothing new here.

    Proposal

    • One PR for findings 1, 2 and 4: models and metadata, with the comparison tests and a convergence check of the problems touched.
    • Finding 6 goes with T8.
    • Findings 3 and 5 wait for the maintainer.

    🤖 Generated with Claude Code

  8. added a commit that references this issue on Nov 20, 2026
  9. ocots commented on Nov 20, 2026

    @ocots
    MemberAuthor

    T3, progress (ct-conventions v0.14.0, ct-agents v0.5.0)

  10. added 2 commits that reference this issue on Nov 20, 2026
  11. ocots commented on Nov 20, 2026

    @ocots
    MemberAuthor

    Progress, 2026-11-20 (ct-conventions v0.14.0, ct-agents v0.5.0)

  12. ocots commented on Nov 20, 2026

    @ocots
    MemberAuthor

    T4 — review of the test suite (2026-11-20, ct-conventions v0.14.0, ct-agents v0.5.0)

    Findings:

    1. Three tests solve in a modeling but report grid_size_data(problem), not the grid of the modeling grid_size_data(problem, backend) (feat(metadata): the grid of a problem by modeling, coarser for ModelingToolkit (#435) #473): the JuMP convergence cron, the JuMP and OptimalControl robustness. Same value today, wrong as soon as a problem has :grid_sizes. Decided: one public grid function, grid_size_data(problem, backend); the one-argument form goes (breaking, with the reference API of feat(references): the references by modeling, each from its own solves (#435) #474 in [Unreleased]).
    2. JuMP has its own test_smoke, test_convergence, test_robustness, and OptimalControl its own test_robustness, beside the shared common/modeling_tests.jl of the three modelings that return a Problem. Proposal: a JuMP adapter and a shared test_robustness: one place for the four modelings.
    3. What each environment tests is written nowhere: only JuMP tests the draft warning (test_draft), OptimalControlScalarized has no test_features nor test_reference_solution, robustness exists for JuMP and OptimalControl only. Proposal: a table modeling × kind of test in test/README.md, each gap with its reason, the forgotten ones added.
    4. test/extras/beam.jl is a dead script (Pkg.activate("test"), bare using, Plots, never run nor referenced): removed.
    5. test/README.md is stale: ModelingToolkit has references of its own since feat(references): the references by modeling, each from its own solves (#435) #474, a coarser grid (feat(metadata): the grid of a problem by modeling, coarser for ModelingToolkit (#435) #473) and a quasi-Newton Hessian (perf(test): ModelingToolkit solves with a quasi-Newton Hessian, warmed up on the smoke grid (#435) #472); the modelings are independent.
    6. common/status.jl (615 lines) does several things (rows, results, trajectories, reports, environment files); left as is for now.

    Already right: no fake type inside a function (TST3); every test file has its entry function test_<name>() (TST1).

    Plan: PR 1 = the grid function (b) + 1 + 4 + 5; PR 2 = 2 + 3.

  13. added 4 commits that reference this issue on Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions