Solution: keep the switching structure (switching times, left/right limits, phase labels); reject duplicate grid times #460

Summary

An indirect method fixes the structure of the solution: switching times, jumps of the state
or costate, and changes of control law. That is what sets it apart from a direct method.
Today a Solution built from a multi-phase flow (CTFlows.Flow(ocp, law)) loses all of
it:

• x, p and u are functions of t, so they cannot return two values at tᵢ;
• the grid passed in contains duplicates, which issorted(T; lt=<) lets through without
  any warning;
• the plot draws a slanted segment instead of a vertical jump.

Part of the switching-structure work tracked in control-toolbox/CTFlows.jl#443 (detailed
plan there).

Proposal

abstract type AbstractSwitchingModel end
struct EmptySwitchingModel <: AbstractSwitchingModel end
struct SwitchingModel <: AbstractSwitchingModel     # built through a keyword constructor
    times::Vector{Float64}                 # strictly increasing, in (t0, tf); may be empty
    labels::Vector{String}                 # one per phase (length(times) + 1); "" = no label
    state::NTuple{2,Matrix{Float64}}       # (left, right), one row per tᵢ
    costate::NTuple{2,Matrix{Float64}}
    control::NTuple{2,Matrix{Float64}}
end

• Solution. New last field switching, which is also the last type parameter.
• build_solution. Gains the keyword
  switching::AbstractSwitchingModel=EmptySwitchingModel(), in both the matrix and the
  function variants. It is validated: tᵢ in (t0, tf) and strictly increasing, the
  number of labels, and the matrix dimensions.
• Left values are stored too. The grid T need not contain the tᵢ, and an imported
  solution can rebuild both limits.
• Keyword constructor. It lets fields be added later without breaking anything:
  constraint duals at tᵢ, see Flow(ocp, law) Solution: reconstruct the constraint duals from the multipliers CTFlows.jl#472.
• Getters.
  • switching_times(sol), empty if there are none;
  • phase_labels(sol);
  • has_switching(sol);
  • the left and right limits per component.
• Strict grid (breaking → 0.20.0). A duplicate time in a grid raises
  IncorrectArgument. A non-sorted grid keeps the current behaviour (sort + @warn).
  Check the CTDirect and OptimalControl suites before the release.
• Display.
  • New row: ├─ Switching times : [0.31, 0.72].
  • New row: ├─ Phases : bang → singular → bang, shown only if at least one label is
    non-empty.
• Plot (PlotCase, so Plots and Makie are both covered).
  • Jumps: after sampling on T, splice in the rows (tᵢ, left) then (tᵢ, right).
    This applies to the state, costate, control, control norm, and to the path
    constraints evaluated at the limits.
  • Vertical lines at tᵢ: new keyword switching_style.
    • Its default has the same look as the existing time lines, _TIME_STYLE, merged with
      the user's time_style.
    • A NamedTuple is merged on top; :none hides the lines.
    • The lines appear in every cell, including when time=:normalize.
  • Phase labels: phase_labels ∈ (:control, :all, :none) (default :control), plus
    phase_labels_style.
    • Each label is an Annotation (Plotting: text annotations in the IR (Annotation decoration) CTBase.jl#612) centred on its
      phase.
    • When the control is not drawn, :control falls back to the last panel.
• Serialization (JSON and JLD).
  • New keys: switching_times, phase_labels, switching_{state,costate,control}_{left,right}.
  • A file without these keys loads with EmptySwitchingModel, so old files still load.
  • Reconstruction interpolates phase by phase, starting each interval (tᵢ, tᵢ₊₁] from
    the right limit, so an imported solution keeps its jumps.

Tests

• Construction. Nominal cases with 0, 1 and n switching times, with and without
  labels. Each validation error with its exception type. Duplicate in a grid →
  IncorrectArgument. Unsorted grid → warning. Default EmptySwitchingModel.
  Getters, including the empty case. @inferred on the getters.
• Show. Reference strings with and without switching, with and without labels, and with
  some labels empty.
• Plot (Plots and Makie).
  • Panel data have the vertical rows; a tᵢ already in T is not duplicated.
  • VLines at tᵢ, including with time=:normalize.
  • switching_style: the default, :none, and a merged NamedTuple.
  • phase_labels set to :control, :all and :none, plus the fallback.
  • Path constraints at the limits.
• Serialization. JSON and JLD round trips with jumps and labels. Import of an old
  file. The reconstructed value just after tᵢ is close to the right limit.

Depends on / consumers

• Depends on Plotting: text annotations in the IR (Annotation decoration) CTBase.jl#612 (Annotation).
• Filled by Plot jumps at switching times as vertical segments (left and right limits) — raw trajectories, Solutions, multi-phase CTFlows.jl#443 (Flow(ocp, law)).
• Extended later by Flow(ocp, law) Solution: reconstruct the constraint duals from the multipliers CTFlows.jl#472 (constraint duals).