Private API

__print(e::Expr, io::IO, l::Int64)

Print an expression with indentation.

Arguments

• e::Expr: The expression to print.
• io::IO: The output stream.
• l::Int: The indentation level (number of spaces).

__print_abstract_definition(
    io::IO,
    ocp::Union{CTModels.OCP.PreModel, CTModels.OCP.Model}
) -> Bool

Print the abstract definition of an optimal control problem.

Arguments

• io::IO: The output stream.
• ocp::Union{Model,PreModel}: The optimal control problem.

Returns

• Bool: true if something was printed.

__print_mathematical_definition(
    io::IO,
    some_printing::Bool,
    x_dim::Int64,
    u_dim::Int64,
    v_dim::Int64,
    t_name::String,
    t0_name::String,
    tf_name::String,
    x_name::String,
    u_name::String,
    v_name::String,
    xi_names::Vector{String},
    ui_names::Vector{String},
    vi_names::Vector{String},
    is_variable_dependent::Bool,
    is_time_dependent::Bool,
    has_a_lagrange_cost::Bool,
    has_a_mayer_cost::Bool,
    dim_path_cons_nl::Int64,
    dim_boundary_cons_nl::Int64,
    dim_state_cons_box::Int64,
    dim_control_cons_box::Int64,
    dim_variable_cons_box::Int64
) -> Bool

Print the mathematical definition of an optimal control problem.

Displays the problem in standard mathematical notation with objective, dynamics, and constraints.

When u_dim == 0 (no control input), all control-dependent parts of the output are suppressed:

• The objective is rendered as J(x, v) instead of J(x, u, v).
• Dynamics arguments omit the control: f(t, x, v) instead of f(t, x, u, v).
• The "where" clause lists only x (and v if variable-dependent).
• Box constraints on control are not listed.

Returns

• Bool: true if something was printed.

The main plot command. Use plot to create a new plot object, and plot! to add to an existing one:

    plot(args...; kw...)                  # creates a new plot window, and sets it to be the current
    plot!(args...; kw...)                 # adds to the `current`
    plot!(plotobj, args...; kw...)        # adds to the plot `plotobj`

There are lots of ways to pass in data, and lots of keyword arguments... just try it and it will likely work as expected. When you pass in matrices, it splits by columns. To see the list of available attributes, use the plotattr(attr) function, where attr is the symbol :Series, :Subplot, :Plot, or :Axis. Pass any attribute to plotattr as a String to look up its docstring, e.g., plotattr("seriestype").

Extended help

Series attributes

• arrow
• bar_edges
• bar_position
• bar_width
• bins
• colorbar_entry
• connections
• contour_labels
• contours
• extra_kwargs
• fill
• fill_z
• fillalpha
• fillcolor
• fillrange
• fillstyle
• group
• hover
• label
• levels
• line
• line_z
• linealpha
• linecolor
• linestyle
• linewidth
• marker
• marker_z
• markeralpha
• markercolor
• markershape
• markersize
• markerstrokealpha
• markerstrokecolor
• markerstrokestyle
• markerstrokewidth
• normalize
• orientation
• permute
• primary
• quiver
• ribbon
• series_annotations
• seriesalpha
• seriescolor
• seriestype
• show_empty_bins
• smooth
• stride
• subplot
• weights
• x
• xerror
• y
• yerror
• z
• z_order
• zerror

Axis attributes

Prepend these with the axis letter (x, y or z)

• axis
• discrete_values
• draw_arrow
• flip
• foreground_color_axis
• foreground_color_border
• foreground_color_grid
• foreground_color_guide
• foreground_color_minor_grid
• foreground_color_text
• formatter
• grid
• gridalpha
• gridlinewidth
• gridstyle
• guide
• guide_position
• guidefont
• guidefontcolor
• guidefontfamily
• guidefonthalign
• guidefontrotation
• guidefontsize
• guidefontvalign
• lims
• link
• minorgrid
• minorgridalpha
• minorgridlinewidth
• minorgridstyle
• minorticks
• mirror
• rotation
• scale
• showaxis
• tick_direction
• tickfont
• tickfontcolor
• tickfontfamily
• tickfonthalign
• tickfontrotation
• tickfontsize
• tickfontvalign
• ticks
• unit
• unitformat
• widen

Subplot attributes

• annotationcolor
• annotationfontfamily
• annotationfontsize
• annotationhalign
• annotationrotation
• annotations
• annotationvalign
• aspect_ratio
• background_color_inside
• background_color_subplot
• bottom_margin
• camera
• clims
• color_palette
• colorbar
• colorbar_continuous_values
• colorbar_discrete_values
• colorbar_fontfamily
• colorbar_formatter
• colorbar_scale
• colorbar_tickfontcolor
• colorbar_tickfontfamily
• colorbar_tickfonthalign
• colorbar_tickfontrotation
• colorbar_tickfontsize
• colorbar_tickfontvalign
• colorbar_ticks
• colorbar_title
• colorbar_title_location
• colorbar_titlefont
• colorbar_titlefontcolor
• colorbar_titlefontfamily
• colorbar_titlefonthalign
• colorbar_titlefontrotation
• colorbar_titlefontsize
• colorbar_titlefontvalign
• extra_kwargs
• fontfamily_subplot
• foreground_color_subplot
• foreground_color_title
• framestyle
• left_margin
• legend_background_color
• legend_column
• legend_font
• legend_font_color
• legend_font_family
• legend_font_halign
• legend_font_pointsize
• legend_font_rotation
• legend_font_valign
• legend_foreground_color
• legend_position
• legend_title
• legend_title_font
• legend_title_font_color
• legend_title_font_family
• legend_title_font_halign
• legend_title_font_pointsize
• legend_title_font_rotation
• legend_title_font_valign
• margin
• plot_title_font
• projection
• projection_type
• right_margin
• subplot_index
• title
• title_font
• titlefontcolor
• titlefontfamily
• titlefonthalign
• titlefontrotation
• titlefontsize
• titlefontvalign
• titlelocation
• top_margin

Plot attributes

• background_color
• background_color_outside
• display_type
• dpi
• extra_kwargs
• extra_plot_kwargs
• fontfamily
• foreground_color
• html_output_format
• inset_subplots
• layout
• link
• overwrite_figure
• plot_title
• plot_titlefontcolor
• plot_titlefontfamily
• plot_titlefonthalign
• plot_titlefontrotation
• plot_titlefontsize
• plot_titlefontvalign
• plot_titleindex
• plot_titlelocation
• plot_titlevspan
• pos
• show
• size
• tex_output_standalone
• thickness_scaling
• warn_on_unsupported
• window_title

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.

__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, ...

__get_data_plot(
    sol::CTModels.OCP.Solution,
    model::Union{Nothing, CTModels.OCP.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

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

Extract data for plotting from a Solution and optional Model for a pair of axes.

This function handles the complexity of multi-time-grids by ensuring both axes use compatible grids for proper plotting.

Arguments

• xx: Symbol or (Symbol, Int) indicating the x-axis quantity and component.
• yy: Symbol or (Symbol, Int) indicating the y-axis quantity and component.
• time: Whether to normalize the time grid (only applies to time axes).

Returns

• (x_data, y_data): Data vectors for x and y axes

Cases Handled

• (t, x) or (x, t): Time-based plots with proper axis ordering
• (x, u): Variable-variable plots with common grid interpolation
• (t, t): Invalid - throws IncorrectArgument

__initial_plot(
    sol::CTModels.OCP.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(
    sol::CTModels.OCP.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,
    color,
    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!(
    p::Plots.Plot,
    sol::CTModels.OCP.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,
    color,
    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_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.

__plot_time!(
    p::Union{Plots.Plot, Plots.Subplot},
    sol::CTModels.OCP.Solution,
    model::Union{Nothing, CTModels.OCP.Model},
    s::Symbol,
    i::Int64,
    time::Symbol;
    t_label,
    y_label,
    color,
    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.
• color: color of the graph
• kwargs...: Additional plotting options.

__plot_time!(
    p::Union{Plots.Plot, Plots.Subplot},
    sol::CTModels.OCP.Solution,
    model::Union{Nothing, CTModels.OCP.Model},
    d::Int64,
    s::Symbol,
    time::Symbol;
    t_label,
    labels,
    title,
    color,
    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_tree(
    leaf::CTModelsPlots.PlotLeaf,
    depth::Int64;
    kwargs...
) -> Plots.Plot

Return an empty plot for a PlotLeaf.

Used as a placeholder in layout trees.

__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).

__size_plot(
    sol::CTModels.OCP.AbstractSolution,
    model::Union{Nothing, CTModels.OCP.AbstractModel},
    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=...).

Get variable values for a given symbol, index, and time grid

Handle time-based plots: (t, x) or (x, t)

Handle variable-variable plots: (x, u)

Handle variable-variable plots for unified time grid.

Handle variable-variable plots for multiple time grids.

Map plotting components to valid time grid components.

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.OCP.AbstractSolution,
    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.
• Control is never plotted when control_dimension(sol) == 0, even if :control is listed in description. This supports solutions of problems without a control input.

Example

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

plot(
    sol::CTModels.OCP.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,
    color,
    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].

• color: set the color of the all the graphs.

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)       

plot!(
    p::Plots.Plot,
    sol::CTModels.OCP.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,
    color,
    kwargs...
) -> Plots.Plot

Modify Plot p with the optimal control solution sol.

See plot for full behavior and keyword arguments.

plot!(
    sol::CTModels.OCP.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,
    color,
    kwargs...
) -> Any

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

See plot for full behavior and keyword arguments.