Documentation: issues to settle in the other packages before the final read and the stable release

Đang mở
  • Có gì không ổn?
#968 3 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 9/10/2026.

Đánh giá

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

Mô tả

documentation

Context

The page-by-page review of the documentation is merged (#953, 45 / 45 pages). Many pages point to issues of the other packages, either as a note ("see CTFlows#441"), or as a probe in docs/probes/ that checks the current behaviour and fails once the fix is released. Before a final read of the documentation, and the release of a new stable version, these issues must be settled, and the pages updated.

For each item: when the fix is released, bump the compat if needed, update the page and the probe (the probe fails on purpose, as a reminder), and tick the box.

Other packages: open issues

CTFlows
  • control-toolbox/CTFlows.jl#441: with saveat, the point call returns the state at the last saved time, not at tf (wrong result, no error). Pages: Flows overview, Constrained arcs, Plot.
  • control-toolbox/CTFlows.jl#440: constraint=:label uses the raw constraint function and ignores its bound and its side. Page: Constrained arcs.
  • control-toolbox/CTFlows.jl#439: the point call of a concatenated Hamiltonian flow returns a flat [x; p]. Page: Multi-phase flows (the code reads zf[1:2]).
  • control-toolbox/CTFlows.jl#438: errors of the accessors, and gradients that only take (t, x, p, v). Page: Accessors.
  • control-toolbox/CTFlows.jl#437: variable_costate=true on a trajectory call: raw MethodError. Page: From an OCP.
  • control-toolbox/CTFlows.jl#436: method=:gpu raises obscure MethodErrors. Page: Flows overview. Closed: once released, quote the new errors and update the section "CPU and GPU" (it says the error does not name the cause yet).
  • control-toolbox/CTFlows.jl#435: the Solution of a flow keeps only 5 points. Page: Plot.
  • control-toolbox/CTFlows.jl#446: default output grid, an adaptive grid of 250 points when the solver returns fewer (so that a flow Solution is not polygonal by default). If adopted, the wording on grid=n / AdaptiveGrid(n) in the Plot and Flows overview pages changes (opt-out with grid=nothing). Pages: Plot, Flows overview.

CTFlows#434 is closed (control-toolbox/CTFlows.jl#442), and control-toolbox/CTFlows.jl#435 too (control-toolbox/CTFlows.jl#444, which replaces the output-grid rule of #442). Once released: (1) dense=false can be dropped from the plots (pages Plot, Flows overview, and the examples; probe plot_flow_saveat.jl); (2) the Plot page (and Flows overview) should say what to do when an integrated trajectory looks polygonal: the default grid is the solver steps, so pass grid=n or grid=AdaptiveGrid(n) (curvature-based, denser where the curves bend) at the call, e.g. f((t0, tf), x0, p0; grid=200). A grid cannot be combined with saveat or with a list of times (IncorrectArgument). Check the wording against the released API. Same check for the closed issues control-toolbox/CTBase.jl#570 (OpenLoop, pages Simulation and Migration), control-toolbox/CTModels.jl#435 (import_ocp_solution, page Save & load), control-toolbox/CTSolvers.jl#234 and control-toolbox/CTBase.jl#565 (GPU errors, probe installation_gpu_errors.jl), control-toolbox/CTSolvers.jl#230 (probe installation_integrators.jl).

CTDirect
  • control-toolbox/CTDirect.jl#639: box multipliers are not divided by the time step, and their sign is the opposite of the path multipliers. Page: Solution object. Probe solution_duals.jl.
  • control-toolbox/CTDirect.jl#640: time stamps of the costate. Same page and probe.
  • control-toolbox/CTDirect.jl#405: dual variables of the path constraints, zeros with :exa. Same page and probe.
  • control-toolbox/CTDirect.jl#638: :exa with an explicit time_grid. Page: Choosing a method.
CTParser
  • control-toolbox/CTParser.jl#326 (PR): alignment with ExaModels 0.12, errors as CTExceptions. Pages that quote errors of @def need a re-read.
  • control-toolbox/CTParser.jl#352, #353, #354: messages of @def. Page: Abstract syntax.
  • control-toolbox/CTParser.jl#355: :exa and the scheme aliases. Page: Choosing a method.
  • control-toolbox/CTParser.jl#356: make @def hygienic (modules instead of names in the generated code).
CTLie
  • control-toolbox/CTLie.jl#40: make @Lie hygienic. Page: The @Lie macro (section "using OptimalControl is needed").
  • control-toolbox/CTLie.jl#41: the error of Lift on a HamiltonianVectorField names ad. Page: Lift.
CTBase
  • control-toolbox/CTBase.jl#569: title, xlabel and ylabel are ignored without a warning in plot. Page: Plot.

OptimalControl

  • #964: init and initial_guess together. Page: Initial guess.
  • #965: which initial-guess helpers of CTModels are re-exported.
  • #966: stop exporting the module name CTLie, after CTLie#40.
  • #967: remove the re-exports of CTModels and ExaModels (and review CTBase, CTFlows), after CTParser#356.
  • #481: constant component of the dynamics with :adnlp. Page: Abstract syntax. Probe abstract_syntax_constants_ad.jl.
  • #976: documentation of the GPU for the indirect method (flows and shooting). The direct method has a page; the indirect one has only a short section in the Flows overview.

To think about later

  • The Geometry pages: the section has 6 pages for 4 functions. The review suggested 3 pages (overview and lift, brackets with ad, Poisson, @Lie and ∂ₜ, and AD backend). They were kept as they are in #953. Decide the structure, once the macros are hygienic (the page on @Lie changes).

Then

  1. Update the pages and the probes for each released fix: julia --project=docs docs/probes/run.jl is the checklist, since a probe for a known bug fails when the bug is fixed.
  2. Final read of the documentation (the review notes and the per-page log are kept by the maintainers).
  3. Release of the new stable version, and switch back the links of "Chat with an AI" to stable/ (they point to dev/ meanwhile).
Ngôn ngữ chính
Julia
Star
135
Fork
11
Merge trung bình
7 giờ 51 phút
Pull request đã merge (30 ngày)
22

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/OptimalControl.jl

Tất cả issue của control-toolbox/OptimalControl.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.