docs: minimal 1-D bang–singular–bang example (phase O)

[ocots]

What

New page docs/src/examples/turnpike.md — a minimal 1-D singular-control example, solved both directly and indirectly.

The scalar turnpike:

$$\dot x = u,\quad u\in[-1,1],\quad x(0)=1,\quad x(t_f)=1/2,\quad t_f=2,\quad \int_0^{2} x(t)^2,dt \to \min.$$

The pseudo-Hamiltonian $H = p,u - x^2$ is linear in $u$, so the control is bang except on a singular arc — and here the singular feedback drops straight out of the optimality conditions, $p\equiv 0 \Rightarrow \dot p = 2x = 0 \Rightarrow x = 0 \Rightarrow u_s = 0$, with no Poisson brackets. The optimal solution is bang ($-1$) on $[0,1]$, singular ($0$) on $[1,3/2]$, bang ($+1$) on $[3/2,2]$, with $p_0=-1$ and cost $3/8$.

Why

examples/singular-control.md is the only page showing a singular arc, and it is a 2-D Zermelo problem needing the full Lift/@Lie/H₀₀₁/H₁₀₁ chain. There was nowhere lighter for a reader who just wants to see a bang–singular–bang solution. This page is also the concrete case that flows/shooting.md §Switching times as unknowns describes in prose but never works (two unknown switching times).

Contents

• Direct — solve, one plot; the flat turnpike plateau at $x=0$ is the singular arc.
• The singular control — short, analytic, no @Lie.
• Indirect — three constant-control flows; shooting on [p0, t1, t2] (fixed horizon). The guess for the singular arc is read off the direct solution the way the Goddard tutorial does it — t12 = t[abs.(φ.(t)) .≤ η], where the switching function is just the costate here.
• Comparison — three-flow concatenation f₋ * (t1, f₀) * (t2, f₊), overlaid on the direct plot; objective $\approx 3/8$.
• See also — forward pointer to the Goddard problem as the harder instance (singular arc and a state-constraint boundary arc).

Wiring

• docs/make.jl and docs/src/examples/gallery.md — inserted directly before Singular control (the minimal singular case, then the bracket-heavy 2-D one). Happy to move it after Time minimisation (bang–bang) if you prefer the tighter bang-arc thread.
• Cross-linked from examples/singular-control.md (opening pointer) and flows/shooting.md (§ switching times as unknowns).
• geometry/overview.md left untouched — flagged as a maintainer call in the plan.

Verification

julia --project=. docs/make.jl on this branch:

• examples/turnpike.html renders; both its figures are SVG, no new .png.
• 6 cannot resolve errors — all pre-existing @extref noise (Plots.plot(::CTModels…) ×4, CTBase.Strategies.parameter ×2), unchanged from main; none from this page.
• All three new @ref examples-turnpike links resolve.
• Executed values: p0 = -1, t1 = 1, t2 = 3/2, direct cost 0.37495, shooting residual ~1e-16.

One note: this OCP is autonomous + fixed-time + no variable, so the Flow(ocp, u) control law is arity 2 — (x, p) -> …, not the arity-3 (x, p, v) -> … form used in double-integrator-time.md (which has tf ∈ R, variable).

Add the run documentation label to build the site in CI.

🤖 Generated with Claude Code