Plot

Index

Warning

In the examples in the documentation below, the methods are not prefixed by the module name even if they are private.

julia> using CTModels
julia> x = 1
julia> private_fun(x) # throw an error

must be replaced by

julia> using CTModels
julia> x = 1
julia> CTModels.private_fun(x)

However, if the method is reexported by another package, then, there is no need of prefixing.

julia> module OptimalControl
           import CTModels: private_fun
           export private_fun
       end
julia> using OptimalControl
julia> x = 1
julia> private_fun(x)

Simple example

using CTModels, Plots
import CTParser: @def

t0, tf, x0 = 0.0, 1.0, -1.0

ocp = @def begin
    t ∈ [t0, tf], time
    x ∈ R, state
    u ∈ R, control
    x(t0) == x0
    -Inf ≤ x(t) + u(t) ≤ 0, (mixed_con)
    ẋ(t) == u(t)
    ∫(0.5u(t)^2) → min
end

sol = CTModels.build_solution(
    ocp,
    collect(range(t0, tf; length=201)),
    t -> x0 * exp(-t),
    t -> -x0 * exp(-t),
    Float64[],
    t -> exp(t - tf) - 1;
    objective = exp(-1) - 1,
    iterations = 0,
    constraints_violation = 0.0,
    message = "",
    status = :optimal,
    successful = true,
)

plot(sol)

Documentation

CTModelsPlots.AbstractPlotTreeElement — Type

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.

CTModelsPlots.EmptyPlot — Type

struct EmptyPlot <: CTModelsPlots.AbstractPlotTreeElement

Represents an empty placeholder in the plot tree.

Used to maintain layout consistency when certain plots are omitted.

CTModelsPlots.PlotLeaf — Type

struct PlotLeaf <: CTModelsPlots.AbstractPlotTreeElement

Represents a leaf node in a plot tree.

Typically used as an individual plot element without any children.

CTModelsPlots.PlotNode — Type

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.

CTModelsPlots.__get_data_plot — Method

__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

CTModelsPlots.__initial_plot — Method

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

CTModelsPlots.__keep_series_attributes — Method

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

CTModelsPlots.__plot! — Method

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

CTModelsPlots.__plot — Method

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

CTModelsPlots.__plot_time! — Method

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

CTModelsPlots.__plot_time! — Method

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

CTModelsPlots.__plot_tree — Function

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

CTModelsPlots.__plot_tree — Method

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

Return an empty plot for a PlotLeaf.

Used as a placeholder in layout trees.

RecipesBase.apply_recipe — Function

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.

RecipesBase.plot! — Method

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,
    color,
    kwargs...
) -> Any

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

See plot for full behavior and keyword arguments.

RecipesBase.plot! — Method

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,
    color,
    kwargs...
) -> Plots.Plot

Modify Plot p with the optimal control solution sol.

See plot for full behavior and keyword arguments.

RecipesBase.plot — Method

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,
    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)

CTModelsPlots.clean — Method

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)

CTModelsPlots.do_decorate — Method

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

CTModelsPlots.do_plot — Method

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)

CTModelsPlots.__control_layout — Method

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

CTModelsPlots.__description — Method

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

CTModelsPlots.__plot_label_suffix — Method

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

CTModelsPlots.__plot_layout — Method

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

CTModelsPlots.__plot_style — Method

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

CTModelsPlots.__size_plot — Method

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

CTModelsPlots.__time_normalization — Method

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