Skip to content

[Cron/Doc] ModelingToolkit convergence cron, trajectories, and documentation (#308) #439

Closed

Description

@ocots

Agents: read the guide for agents in #310 first (order, difficulty, how to claim an issue, working method). Read AGENTS.md and clone .ct-conventions (v0.11.0) and .ct-agents (v0.4.0). Specification: this description and #308.

Sub-issue of #308, part 3 of 3. Depends on #438 (SolveModelingToolkit and test/suite/ModelingToolkit/).


Goal

Add the weekly ModelingToolkit convergence cron (test/cron/ModelingToolkit/test_convergence.jl) recording results and trajectories for the documentation results pipeline (#314), enable the Saturday cron schedule in .github/workflows/CronModelingToolkit.yml, and complete the documentation adapter and developer READMEs (docs/modelings.jl, docs/make.jl, docs/api_reference.jl, ext/README.md, test/README.md).

At the end of this issue, cron/ModelingToolkit runs end-to-end and generates its report and trajectory files, the documentation builds cleanly with the ModelingToolkit tab on bryson_denham's page, and all requirements of #308 are complete.


Technical Findings (from #308 preliminary checks)

  1. Convergence report (test/cron/ModelingToolkit/test_convergence.jl):
    • Convergence is reported, never tested as a binary failure ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360).
    • For a shooting method with piecewise-constant controls (scheme = :shooting_single or :shooting_multiple), reference_objective(problem; grid_size, scheme) has no trapezoidal entry in ext/MetaData/references/<problem>.toml, so TestStatus.result! naturally records ref_objective = nothing unless passed or matched, while the convergence script can also print both:
      • the gap to the analytic objective OptimalControlProblems.analytic_reference(problem).value ($J^* = 4.0$ for bryson_denham), and
      • the gap to the OptimalControl trapezoidal reference OptimalControlProblems.reference_objective(problem; grid_size, scheme=:trapezoid).
  2. Trajectories & ProblemPlot.vue ([Doc] Results pipeline for the documentation, and a gallery of problems #314):
    • docs/src/components/ProblemPlot.vue checks if (data[group][name]) for group in ['state', 'control', 'costate']. Since Corleone is a direct shooting solver without explicit costates, passing costate = Dict{String, Vector{Float64}}() in the trajectory returned by SolveModelingToolkit.trajectory causes ProblemPlot.vue to cleanly omit the Costate section and plot State and Control trajectories.
    • docs/make.jl does not run Corleone at build time (it only reads source files and precomputed JSONs from results), so docs/Project.toml only needs ModelingToolkit (to load ModelingToolkitModels for docs/api_reference.jl), not Corleone.
  3. Documentation problem page adapter (docs/modelings.jl):
    • Verify and polish the :ModelingToolkit => ModelingAdapter(...) entry in docs/modelings.jl so the ModelingToolkit tab on problems/bryson_denham.md shows:
      • how to retrieve the continuous ModelingToolkit.System (pb = bryson_denham(ModelingToolkitBackend()); sys = model(pb)),
      • how to discretize the path constraint on a constraint grid, build a CorleoneDynamicOptProblem with our shared initial_guess(pb), and solve it with Ipopt,
      • the note required by [Problems] Proof of concept: a ModelingToolkit modeling, solved with Corleone, with our own bryson_denham #308: "With direct shooting in Corleone, the state path constraint is enforced at the points of a constraint grid, and controls are piecewise constant on a control grid."

Mandatory Rules & Conventions (ct-conventions v0.11.0, #310)

  • Worktree per issue (#310 rule 3a): Never edit or switch branches in the main checkout. Use a dedicated worktree (git worktree add ../OptimalControlProblems-<issue> -b feat/<issue>-mtk-cron-docs main).
  • Qualified imports only (MOD3, MOD4): Always use using Pkg: Pkg, sym. Never use bare using Pkg or import.
  • No hand-written problem lists (test_no_handwritten_list in test/suite/core/test_consistency.jl): In test/cron/ModelingToolkit/test_convergence.jl, loop over problems using Main.TestStatus.for_each_problem(..., OptimalControlProblems.ModelingToolkitBackend()); never hardcode :bryson_denham.
  • Docstrings (DOC1–DOC8) & Site rules (SITE1–SITE18): Verify the documentation builds without warnings or errors.

Detailed Implementation Plan

Files to Create or Modify

File Action Details
test/cron/ModelingToolkit/test_convergence.jl Create Run every problem in ModelingToolkitBackend() across CONFIGS.ModelingToolkit on its default grid (max_iter=1000, tol=1e-6). Record Main.TestStatus.result! with trajectory = SolveModelingToolkit.trajectory(...) and log comparisons against analytic_reference(problem) and reference_objective(problem; grid_size, scheme=:trapezoid).
.github/workflows/CronModelingToolkit.yml Modify Uncomment the Saturday schedule (cron: "0 4 * * 6").
tools/cron/report.py Modify Update _CADENCE_NOTE so ModelingToolkit is listed among active weekly crons (Saturday 04:00 UTC).
docs/modelings.jl Modify Polish the :ModelingToolkit ModelingAdapter snippet and explanatory note on shooting with Corleone (piecewise-constant controls on control grid, path constraints sampled on constraint grid).
docs/Project.toml & docs/make.jl & docs/api_reference.jl Modify Add ModelingToolkit to docs/Project.toml, load using ModelingToolkit: ModelingToolkit in docs/make.jl, and include :ModelingToolkitModels in docs/api_reference.jl.
ext/README.md & test/README.md Modify Document ext/ModelingToolkitModels.jl, ext/ModelingToolkitModels/, test/suite/ModelingToolkit/, and test/cron/ModelingToolkit/.

Verification Commands

julia --project=. -e 'using Pkg; Pkg.test(test_args=["cron/ModelingToolkit"])'
julia --project=. -e 'using Pkg; Pkg.test(test_args=["suite/core"])'
julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=".")); Pkg.instantiate(); include("docs/make.jl")'

Done when

  • test/cron/ModelingToolkit/test_convergence.jl runs cleanly, writes test/reports/ModelingToolkit-cron.{md,json} and trajectory files, and prints gaps to both the analytic objective and the OptimalControl reference objective.
  • .github/workflows/CronModelingToolkit.yml has its Saturday cron enabled and tools/cron/report.py reflects it.
  • docs/make.jl builds cleanly; the bryson_denham page shows the ModelingToolkit tab (retrieve continuous System, then solve with Corleone) without problem-specific code in the page generator.
  • ext/README.md and test/README.md are updated.

Refs #308, #305, #307, #310, #314

Activity

  1. added
    documentationImprovements or additions to documentation
    featureNew feature or request
    on Nov 8, 2026
  2. ocots commented on Nov 11, 2026

    @ocots
    MemberAuthor

    Documentation, beyond the tab on the problem page: no page shows how to solve a ModelingToolkit problem with Corleone. Add a user-guide page "Solve with ModelingToolkit", next to "Solve with OptimalControl" and "Solve with JuMP" and built the same way. It should go from model(pb) to a Corleone solve with Ipopt, using initial_guess(pb) and the control, shooting and constraint grids, and link to the Corleone documentation for details. Tracked in the review #449 (T6).

  3. added a commit that references this issue on Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationfeatureNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions