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

Đang mở
  • Có gì không ổn?
#439 0 bình luận 0 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@ocots đang làm issue này rồi.

Từ ngày 8/11/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

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

Ngôn ngữ chính
Julia
Star
13
Fork
1
Merge trung bình
3 giờ 33 phút
Pull request đã merge (30 ngày)
55

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của control-toolbox/OptimalControlProblems.jl

Tất cả issue của control-toolbox/OptimalControlProblems.jl

Issue tương tự

Thêm issue về Julia

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.