Documentation: multi-phase solutions (phase labels, switching structure, jump plotting) #992

Context

Indirect methods fix the structure of a solution: phases separated by switching times, with possible jumps of the state, the costate or the control. Until now this structure was lost: the Solution of a multi-phase flow repeated each switching time in the grid, and the plot joined the phases with oblique lines. The work on CTFlows#443 (draft PRs CTBase#613, CTSolvers#269, CTModels#463, CTFlows#473) keeps this structure and makes it visible.

Once these PRs are released, the OptimalControl documentation should present the new possibilities. This issue tracks that work so it is not forgotten.

What to document

Phase labels (CTFlows)

• Flow(...; label="bang") names the phase a flow integrates. It works for every Flow constructor, the SciML ones included.
• Concatenation keeps the labels in order: f1 * (t1, f2) * (t2, f3).
• The labels show in the display of a flow, of a multi-phase flow (labels: bang → singular) and of a trajectory or Solution (Phases : bang → · → singular, with · for an unlabelled phase).
• label is an action option of the constructor, like hamiltonian_type: it is never passed to the integrator.

Switching structure of the solution (CTModels, CTFlows)

• The Solution of a multi-phase Flow(ocp, law) keeps:

  • its switching times;
  • its phase labels;
  • the left and right limits of the state, costate and control at every switching time (a SwitchingModel).

• Accessors: switching_times, phase_labels, has_switching, left_limit(sol, :state, i), right_limit(sol, :control, i).

• The trajectories are left-continuous: sol(tᵢ) gives the value before the jump.

• Where the limits come from:

  • left: the end of the phase that finishes at tᵢ;
  • right: the start of the next phase, after the jump (x + Δx, p + Δp);
  • control: the law of each phase, evaluated at these values.

  They are not read from the next point of the grid.

• The time grid holds each switching time once. A repeated time in build_solution is now an error.

• The structure is saved and loaded with the solution (JLD2 and JSON).

Plotting (Plots and Makie)

• A jump of the state, costate or control is drawn as a vertical segment from the left to the right limit (jumps = :segment, the default). This makes jumps easy to see, and to compare with a direct method whose jump is smoothed.
• jumps = :none breaks the curve between the two limits instead, so that no segment suggests values the trajectory does not take.
• Vertical lines mark the switching times (switching_style; by default they look like the initial and final time markers; :none hides them).
• The phase labels are written on the control cell (phase_labels = :control | :all | :none, phase_labels_style). A phase with an empty label gets no text.
• The whole trajectory keeps one color: the phases are parts of the same curve.
• The same keywords apply to the raw trajectories of CTFlows (plot(traj)) and to plot(sol).

Pages to update (suggestion)

• flows/multi-phase.md: labels, the switching structure, the limits and where they come from, and plots of a multi-phase flow with the new keywords.
• results/plot.md and results/plot-makie.md: the switching_style, phase_labels, phase_labels_style and jumps keywords.
• results/solution.md: the switching accessors and the new display rows.
• results/save-load.md: the switching structure is saved.
• Examples with a fixed structure (examples/singular-control.md, examples/state-constraint.md, geometry/):
  • label the arcs (bang, singular, boundary);
  • show the plot, and possibly a comparison with the direct solution, using jumps = :segment to see the convergence.

Dependencies

To do after the releases of CTBase (0.30.11), CTSolvers (0.6.2), CTModels (0.20.0) and CTFlows. Related: CTFlows#443 (plan and review), CTFlows#472 (duals, follow-up), OptimalControl#968 (documentation issues to settle before the stable release).