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

Abierto
  • ¿Algo no está bien?
#439 0 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@ocots ya está trabajando en esto.

Desde el 8/11/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

documentation feature

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 (#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 (#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 #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

Lenguaje dominante
Julia
Estrellas
13
Forks
1
Merge medio
3 h 33 min
PR fusionados (30 d)
55

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de control-toolbox/OptimalControlProblems.jl

Todos los issues de control-toolbox/OptimalControlProblems.jl

Issues similares

Más issues de Julia

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.