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

Aberta
  • Algo errado?
#439 0 comentários 0 reações 1 responsável Ver no GitHub

Mantenedores costumam responder em até 1 dia

@ocots já está trabalhando nisso.

Desde 8/11/2026.

Avaliação

Esta issue ainda não foi avaliada.

Descrição

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

Linguagem predominante
Julia
Estrelas
13
Forks
1
Merge médio
3h 33min
PRs com merge (30d)
55

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de control-toolbox/OptimalControlProblems.jl

Todas as issues de control-toolbox/OptimalControlProblems.jl

Issues semelhantes

Mais issues de Julia

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.