Skip to content

docs: modelling — describe an optimal control problem - #865

Merged
ocots merged 9 commits into
mainfrom
docs/modelling
Aug 23, 2026
Merged

docs: modelling — describe an optimal control problem#865
ocots merged 9 commits into
mainfrom
docs/modelling

Conversation

@ocots

@ocots ocots commented Aug 20, 2026

Copy link
Copy Markdown
Member

Summary

  • Writes the six "Modelling" pages (docs/src/modelling/), replacing the PR-2 stubs wholesale: formulation.md, abstract-syntax.md, functional-api.md, without-control.md (new page), inspect.md, with-ai.md.
  • All content re-verified against current source (CTModels.jl, CTBase, CTFlows.jl, CTParser.jl) and live builds, not just ported from docs/attic/ — several factual errors in the old docs were caught and fixed rather than carried forward:
    • functional-api.md: removed the "callbacks always receive vectors" claim (contradicts the tested "1-D is a scalar" contract, test/suite/shape/test_shape_contract.jl), fixed the indexing (u[1] → u) across the worked example, and replaced it with an explicit ## Shapes in callbacks section stating the real rule (the in-place output buffer is the one exception). Also dropped the spec's own example count down from the attic's six to the one the 03-modelling.md outline actually calls for, deferring the rest to the future examples gallery (PR 10).
    • abstract-syntax.md: removed a self-contradictory !!! compat "Upcoming feature" note claiming control-free problems aren't supported yet, immediately after two working examples showing they are — confirmed live against CTModels.jl/src/Building/control.jl and the test suite.
    • without-control.md (new): assembled from docs/attic/example-control-free.md, with the indirect-method (shooting) code fixed to the current CTFlows.jl call signature (variable=, variable_costate=) — the attic version used a stale augment=true/positional-variable API that no longer exists. Verified end-to-end against both real test fixtures (ExponentialGrowth: recovered p≈0.5; HarmonicOscillator: recovered ω≈π/2).
    • inspect.md: dropped the docstring-wrapper section (now covered by PR 4's generated API reference), kept and relocated the richer running example.
    • with-ai.md: fixed six stale URLs pointing at the old manual-abstract.html page.
    • formulation.md: moved from index.md, which is trimmed to a short pointer. The old @id math-formulation anchor is dropped rather than kept alive — Documenter only recognizes @id as the sole child of a heading, so a same-page dual anchor isn't achievable; no live page referenced it.
  • Filed CTModels.jl#392: plot(sol) throws IncorrectArgument("a VBox needs at least one child") on a plain direct-solved solution whenever the default description (which includes :costate) is used with layout=:split — found while executing these pages for real (Draft = false). Worked around in-content with explicit description args; not fixed upstream in this PR since CTModels isn't owned by this repo.
  • Also includes an unrelated small cosmetic fix: tighter margin-top/margin-bottom on the <summary> of index.md's three collapsible sections (Version info / Package status / Complete manifest).

Test plan

  • julia --project=docs docs/make.jl — full rebuild, from scratch, three iterations until clean: 0 undefined-binding/no-docs/duplicate-docs warnings, 0 errors, all six pages' @example blocks execute (Draft = false), 0 unresolved @refs from them.
  • npx vitepress build on the Documenter output — site builds; spot-checked the with-ai.md provider-button URLs and the rocket-example asset path resolve in the built HTML.
  • Re-ran test/problems/control_free.jl, test/suite/problems/test_forms_equivalent.jl, test/suite/shape/test_shape_contract.jl — the three fixtures this PR's prose leans on are still green.
  • typos on all new/changed files — clean.
  • docs/reports/03-modelling.md acceptance criteria re-checked against the real build (5/6 ticked; the @id math-formulation criterion left unticked with the Documenter-limitation reasoning recorded inline).

Depends on #854 (merged). Follows the same PR-per-section pattern as #854/#855/#856.

🤖 Generated with Claude Code

ocots and others added 8 commits August 16, 2026 10:05
@ocots
docs(modelling): write Formulation page, trim index.md
b94536b 
Move the "Mathematical formulation" section from index.md to its own
page under the sitemap's Modelling node, per docs/reports/03-modelling.md.
index.md keeps a two-line pointer.

The old math-formulation anchor is not preserved: Documenter only
recognises @id on a link that is the sole child of a heading node, so
a standalone [](@id math-formulation) is not valid syntax (confirmed
against a full rebuild — it silently produced a broken-link warning
instead of an anchor). No currently-built page references it.
@ocots
docs(modelling): write Abstract syntax page
de6a481 
Ported from docs/attic/manual-abstract.md, with one factual fix: the
"control-free is upcoming, use a dummy control as a workaround" compat
note directly contradicted the two working examples right above it.
Confirmed against CTModels.jl/src/Building/control.jl and
test/problems/control_free.jl that omitting the control declaration
entirely is, and has been, the correct and only syntax — control!(pre, 0)
is rejected. Replaced the stale note with a forward-link to the new
Problems without a control page.
@ocots
docs(modelling): write Functional API page
33ef85f 
Rewritten, not ported, from docs/attic/manual-macro-free.md (899
lines -> 267). Two changes beyond trimming to one worked example (per
the spec's own outline, rather than all 6 comparison examples the
attic file accumulated):

- Deleted the "Scalar vs vector: a subtlety of the functional API"
  section, which claimed callbacks always receive vectors even for
  1-D components. That's false and contradicts the ecosystem's tested
  "1-D is a scalar" rule (test/suite/shape/test_shape_contract.jl).
  Replaced with a correct "Shapes in callbacks" section: scalars
  everywhere except the in-place output buffer, which is always a
  vector. Fixed the same wrong indexing in the one remaining example's
  callbacks and in the Canvas template's doc comments.
- Deleted the closing inline @docs block (PR 4's generated API
  reference already covers it).

Also worked around a real CTModels bug found while executing this
page for the first time under Draft=false: plot(sol) throws on the
default call for a plain direct solution once costate is in the
default description with layout=:split. Filed as CTModels.jl#392;
worked around here with an explicit plot(sol, :state, :control).
@ocots
docs(modelling): write Problems without a control page (new)
c87e383 
Assembled from docs/attic/example-control-free.md's two worked
problems (exponential growth rate estimation, harmonic oscillator
pulsation) plus new framing sections (how to declare it, how the
package knows, adding a control back), matching
docs/reports/03-modelling.md's outline. This page didn't exist before.

The source's indirect-method shooting code used augment=true and a
positional variable argument — both gone from current CTFlows. Fixed
to the current signature after verifying it end-to-end (both examples,
direct and indirect, recovering p=0.5 and omega=pi/2 as expected):
variable is now a keyword, augment=true is variable_costate=true, and
the trajectory call no longer takes saveat (removed call-time
integrator-option override, see BREAKING.md).

Same plot(sol) bug as functional-api.md (CTModels.jl#392) hit here
too, for both direct solutions; same explicit-description workaround.
@ocots
docs(modelling): write Inspect a problem page
25fb577 
Ported from docs/attic/manual-model.md, which was already accurate.
Dropped the "Model struct" section's docstring/getter-list wrapper
(PR 4's generated API reference covers it) but kept and relocated the
richer running-example OCP definition it also contained, since every
later accessor example depends on it being in scope.

Trimmed the opening "Main functionalities" teaser (a full solve +
Flow/PMP mini-example) down to a couple of pointers to the solve and
flows pages — this page is about reading a model back, not solving
it; my own editorial call, not explicit in the spec.
@ocots
docs(modelling): write With AI page
e364847 
Ported from docs/attic/manual-ai-llm.md, near-verbatim. Fixed all 6
occurrences of the stale target URL (the internal @ref, the prompt
text, and 4 provider button hrefs) from manual-abstract.html to the
new page's route, confirmed against the actual built output
(/modelling/abstract-syntax, DocumenterVitepress clean URLs).
@ocots
docs: verify PR 5 acceptance criteria against a real build, update wo…
6958905 
…rk board

Verified against an independent full rebuild (docs/make.jl +
vitepress build), not just the diff: zero undefined-binding/no-docs/
duplicate-docs (regression check on PR 4), zero build errors, zero
failed or un-expanded @example blocks on the six modelling pages, zero
unresolved @refs from them. One criterion dropped by decision (the
math-formulation anchor) with the reasoning recorded inline.
@ocots @claude
docs: tighten summary margins in collapsible index.md sections
f7abe92 
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ocots @claude
docs(reports): link PR 5 to #865 on the work board
9e22777 
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This was referenced Aug 20, 2026
Merged
Merged
Merged
@ocots
ocots merged commit a359a6e into main Aug 23, 2026
6 checks passed
@ocots
ocots deleted the docs/modelling branch August 23, 2026 08:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@ocots ocots

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ocots