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

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).