Plot

abstract type AbstractPlotTreeElement

Abstract supertype for nodes used in the plot tree structure. This serves as a base for elements like PlotLeaf, PlotNode, and EmptyPlot.

struct EmptyPlot <: CTModelsPlots.AbstractPlotTreeElement

Represents an empty placeholder in the plot tree.

Used to maintain layout consistency when certain plots are omitted.

struct PlotLeaf <: CTModelsPlots.AbstractPlotTreeElement

Represents a leaf node in a plot tree.

Typically used as an individual plot element without any children.

struct PlotNode{TL<:Union{Symbol, Matrix{Any}}, TC<:(Vector{<:CTModelsPlots.AbstractPlotTreeElement})} <: CTModelsPlots.AbstractPlotTreeElement

Represents a node with a layout and children in a plot tree.

Fields

• layout::Union{Symbol, Matrix{Any}}: Layout specification, e.g., :row, :column, or a custom layout matrix.
• children::Vector{<:AbstractPlotTreeElement}: Subplots or nested plot nodes.

__get_data_plot(
    sol::CTModels.Solution,
    model::Union{Nothing, CTModels.Model},
    xx::Union{Symbol, Tuple{Symbol, Int64}};
    time
) -> Any

Extract data for plotting from a Solution and optional Model.

Arguments

• xx: Symbol or (Symbol, Int) indicating the quantity and component.
• time: Whether to normalize the time grid.

Supported values for xx:

• :time, :state, :control, :costate, :control_norm
• :path_constraint, :dual_path_constraint

__height(r::Real) -> Expr

Return an expression a{r*h} to control relative plot height when using custom layouts.

Used for vertical space control in plot trees.

__initial_plot(
    sol::CTModels.Solution,
    description::Symbol...;
    layout,
    control,
    model,
    state_style,
    control_style,
    costate_style,
    path_style,
    dual_style,
    kwargs...
)

Initialize the layout and create an empty plot canvas according to layout and control parameters.

Keyword Arguments

• layout: Plot layout style (:group or :split).
• control: What to plot for controls (:components, :norm, :all).
• state_style, control_style, etc.: Plot styles for various signals.

__keep_series_attributes(; kwargs...) -> Vector{Any}

Filter keyword arguments to retain only those relevant for plotting series.

Returns a list of key-value pairs recognized by Plots.

__plot!(
    p::Plots.Plot,
    sol::CTModels.Solution,
    description::Symbol...;
    model,
    time,
    control,
    layout,
    time_style,
    state_style,
    state_bounds_style,
    control_style,
    control_bounds_style,
    costate_style,
    path_style,
    path_bounds_style,
    dual_style,
    kwargs...
)

Plot an optimal control Solution on a given plot p.

This updates an existing plot object with the trajectory of states, controls, costates, constraints, and duals based on the provided layout and description.

Keyword Arguments

Includes options such as:

• layout, control, time
• state_style, control_style, costate_style, etc.

__plot(
    sol::CTModels.Solution,
    description::Symbol...;
    model,
    time,
    control,
    layout,
    time_style,
    state_style,
    state_bounds_style,
    control_style,
    control_bounds_style,
    costate_style,
    path_style,
    path_bounds_style,
    dual_style,
    size,
    kwargs...
)

Construct and return a new plot for the provided Solution.

This is a wrapper that calls __initial_plot and then fills it using __plot!.

Use this to obtain a standalone plot.

__plot_time!(
    p::Union{Plots.Plot, Plots.Subplot},
    sol::CTModels.Solution,
    model::Union{Nothing, CTModels.Model},
    d::Int64,
    s::Symbol,
    time::Symbol;
    t_label,
    labels,
    title,
    kwargs...
)

Plot all components of a vector-valued signal over time.

Arguments

• d: Dimension of the signal (number of components).
• labels: Vector of string labels for each component.
• title: Title of the subplot.

Other arguments are the same as for the scalar version of __plot_time!.

__plot_time!(
    p::Union{Plots.Plot, Plots.Subplot},
    sol::CTModels.Solution,
    model::Union{Nothing, CTModels.Model},
    s::Symbol,
    i::Int64,
    time::Symbol;
    t_label,
    y_label,
    kwargs...
)

Plot a single component i of a time-dependent vector-valued quantity (:state, :control, :costate, etc.).

Arguments

• p: A Plots.Plot or Plots.Subplot object to update.
• sol: An optimal control Solution.
• model: The associated Model or nothing.
• s: Symbol indicating the signal type (:state, :control, :costate, :control_norm, etc.).
• i: Component index (use -1 for :control_norm).
• time: Time normalization option (:default, :normalize, :normalise).

Keyword Arguments

• t_label: Label for the time axis.
• y_label: Label for the vertical axis.
• kwargs...: Additional plotting options.

__plot_tree(node::CTModelsPlots.PlotNode; ...) -> Any
__plot_tree(
    node::CTModelsPlots.PlotNode,
    depth::Int64;
    kwargs...
) -> Any

Recursively assemble a hierarchical plot layout from a PlotNode.

Each node may represent a row, column, or custom layout and contain children (subplots or nested nodes).

Arguments

• node: The root of a plot subtree.
• depth: Current depth (used to control spacing/layout).

__plot_tree(
    leaf::CTModelsPlots.PlotLeaf,
    depth::Int64;
    kwargs...
) -> Plots.Plot

Return an empty plot for a PlotLeaf.

Used as a placeholder in layout trees.

apply_recipe(
    plotattributes::AbstractDict{Symbol, Any},
    sol::CTModels.Solution,
    model::Union{Nothing, CTModels.Model},
    xx::Union{Symbol, Tuple{Symbol, Int64}},
    yy::Union{Symbol, Tuple{Symbol, Int64}}
) -> Vector{RecipeData}
apply_recipe(
    plotattributes::AbstractDict{Symbol, Any},
    sol::CTModels.Solution,
    model::Union{Nothing, CTModels.Model},
    xx::Union{Symbol, Tuple{Symbol, Int64}},
    yy::Union{Symbol, Tuple{Symbol, Int64}},
    time::Symbol
) -> Vector{RecipeData}

A Plots.jl recipe for plotting Solution data.

Returns the (x, y) values based on symbolic references like :state, :control, :time, etc.

Arguments

• xx: Symbol or (Symbol, Int) indicating the x-axis.
• yy: Symbol or (Symbol, Int) indicating the y-axis.

plot!(
    sol::CTModels.Solution,
    description::Symbol...;
    layout,
    control,
    time,
    state_style,
    state_bounds_style,
    control_style,
    control_bounds_style,
    costate_style,
    time_style,
    path_style,
    path_bounds_style,
    dual_style,
    kwargs...
) -> Any

Modify Plot current() with the optimal control solution sol.

See plot for full behavior and keyword arguments.

plot!(
    p::Plots.Plot,
    sol::CTModels.Solution,
    description::Symbol...;
    layout,
    control,
    time,
    state_style,
    state_bounds_style,
    control_style,
    control_bounds_style,
    costate_style,
    time_style,
    path_style,
    path_bounds_style,
    dual_style,
    kwargs...
) -> Plots.Plot

Modify Plot p with the optimal control solution sol.

See plot for full behavior and keyword arguments.

plot(
    sol::CTModels.Solution,
    description::Symbol...;
    layout,
    control,
    time,
    state_style,
    state_bounds_style,
    control_style,
    control_bounds_style,
    costate_style,
    time_style,
    path_style,
    path_bounds_style,
    dual_style,
    size,
    kwargs...
) -> Plots.Plot

Plot the components of an optimal control solution.

This is the main user-facing function to visualise the solution of an optimal control problem solved with the control-toolbox ecosystem.

It generates a set of subplots showing the evolution of the state, control, costate, path constraints, and dual variables over time, depending on the problem and the user’s choices.

Arguments

• sol::CTModels.Solution: The optimal control solution to visualise.
• description::Symbol...: A variable number of symbols indicating which components to include in the plot. Common values include:
  • :state – plot the state.
  • :costate – plot the costate (adjoint).
  • :control – plot the control.
  • :path – plot the path constraints.
  • :dual – plot the dual variables (or Lagrange multipliers) associated with path constraints.

If no symbols are provided, a default set is used based on the problem and styles.

Keyword Arguments (Optional)

• layout::Symbol = :group: Specifies how to arrange plots.

  • :group: Fewer plots, grouping similar variables together (e.g., all states in one subplot).
  • :split: One plot per variable component, stacked in a layout.

• control::Symbol = :components: Defines how to represent control inputs.

  • :components: One curve per control component.
  • :norm: Single curve showing the Euclidean norm ‖u(t)‖.
  • :all: Plot both components and norm.

• time::Symbol = :default: Time normalisation for plots.

  • :default: Real time scale.
  • :normalize or :normalise: Normalised to the interval [0, 1].

Style Options (Optional)

All style-related keyword arguments can be either a NamedTuple of plotting attributes or the Symbol :none referring to not plot the associated element. These allow you to customise color, line style, markers, etc.

• time_style: Style for vertical lines at initial and final times.
• state_style: Style for state components.
• costate_style: Style for costate components.
• control_style: Style for control components.
• path_style: Style for path constraint values.
• dual_style: Style for dual variables.

Bounds Decorations (Optional)

Use these options to customise bounds on the plots if applicable and defined in the model. Set to :none to hide.

• state_bounds_style: Style for state bounds.
• control_bounds_style: Style for control bounds.
• path_bounds_style: Style for path constraint bounds.

Returns

• A Plots.Plot object, which can be displayed, saved, or further customised.

Example

# basic plot
julia> plot(sol)

# plot only the state and control
julia> plot(sol, :state, :control)

# customise layout and styles, no costate
julia> plot(sol;
       layout = :group,
       control = :all,
       state_style = (color=:blue, linestyle=:solid),
       control_style = (color=:red, linestyle=:dash),
       costate_style = :none)       

clean(description) -> Tuple

Clean and standardize the description tuple for plot selection.

Behavior

• Converts plural forms (:states, :costates, etc.) to their singular equivalents.
• Maps ambiguous terms (:constraint, :constraints, :cons) to :path.
• Removes duplicate symbols.

Arguments

• description: A tuple of symbols passed by the user, typically from plot arguments.

Returns

• A cleaned Tuple{Symbol...} of unique, standardized symbols.

Example

julia> clean((:states, :controls, :costate, :constraint, :duals))
# → (:state, :control, :costate, :path, :dual)

do_decorate(
;
    model,
    time_style,
    state_bounds_style,
    control_bounds_style,
    path_bounds_style
)

Determine whether to decorate plots with bounds or time annotations.

Keyword Arguments

• model: The associated OCP model. If nothing, decorations are skipped.
• time_style: Style used for vertical lines marking initial/final time.
• state_bounds_style: Style for state bounds lines.
• control_bounds_style: Style for control bounds lines.
• path_bounds_style: Style for path constraint bounds.

Returns

• A 4-tuple of booleans: (do_decorate_time, do_decorate_state_bounds, do_decorate_control_bounds, do_decorate_path_bounds)

Notes

Each decoration is applied only if:

• A non-:none style is provided, and
• A model is available (not nothing).

Example

julia> do_decorate(model=my_model, time_style=NamedTuple(), state_bounds_style=:none, ...)
# → (true, false, ...)

do_plot(
    sol::CTModels.Solution,
    description::Symbol...;
    state_style,
    control_style,
    costate_style,
    path_style,
    dual_style
)

Determine which components should be plotted based on the description and style settings.

Arguments

• sol: The optimal control solution.
• description: A cleaned tuple of plot description symbols (:state, :costate, :control, :path, :dual).

Keyword Arguments

• *_style: The plotting style (a NamedTuple or :none). If a style is :none, that component is skipped.

Returns

• A 5-tuple of booleans: (do_plot_state, do_plot_costate, do_plot_control, do_plot_path, do_plot_dual)

Notes

• Duals are only plotted if sol contains path constraint dual variables.
• A style must not be :none for the component to be included.

Example

julia> do_plot(sol, :state, :control, :path; state_style=NamedTuple(), control_style=:none, path_style=NamedTuple(), ...)
# → (true, false, false, true, false)

__control_layout() -> Symbol

Default layout for control input visualization.

Returns :components, which plots each control component individually.

Possible values:

• :components: One plot per control component (default).
• :norm: Single plot showing the control norm ‖u(t)‖.
• :all: Show both components and norm.

Used as the default for control in plot(sol; control=...).

__description() -> NTuple{12, Symbol}

Return the default list of description symbols to be plotted if the user does not specify any.

Includes aliases for backward compatibility.

Returns a tuple of symbols, such as:

• :state, :costate, :control, :path, :dual, ...

__plot_label_suffix() -> String

Default suffix used for the solution label in plots.

Returns an empty string "".

This label can be used to distinguish multiple solutions in comparative plots.

__plot_layout() -> Symbol

Default layout for the full plot.

Returns :split, which arranges each component (e.g. state, control) in separate subplots.

Possible values:

• :split: One subplot per component (default).
• :group: Combine components into shared subplots.

Used as the default for layout in plot(sol; layout=...).

__plot_style() -> @NamedTuple{}

Default plot style.

Returns an empty NamedTuple(), which means no style override is applied.

Used when no user-defined style is passed for plotting states, controls, etc.

__size_plot(
    sol::CTModels.Solution,
    model::Union{Nothing, CTModels.Model},
    control::Symbol,
    layout::Symbol,
    description::Symbol...;
    state_style,
    control_style,
    costate_style,
    path_style,
    dual_style
)

Compute a default size (width, height) for the plot figure.

This depends on the number of subplots, which is inferred from:

• The layout (:group or :split)
• The presence of state, control, costate, path constraint, or dual variable plots
• The number of state and control variables
• The control layout choice (:components, :norm, :all)

Used internally in the plot function to automatically size the output plot.

Example

julia> size = __size_plot(sol, model, :components, :split; ...)

__time_normalization() -> Symbol

Default time axis normalization.

Returns :default, which plots against real time.

Possible values:

• :default: Plot time in original units (default).
• :normalize: Normalize time to [0, 1].
• :normalise: Same as :normalize, British spelling.

Used as the default for time in plot(sol; time=...).