Public API

Display

Display and formatting module for CTModels.

This module provides functions for displaying and formatting optimal control problems and solutions in human-readable formats.

Public API

The following functions are exported and accessible via Base.show:

• Base.show(io::IO, ::MIME"text/plain", ocp::Model): Display an optimal control problem
• Base.show(io::IO, ::MIME"text/plain", sol::Solution): Display a solution

Private API

The following are internal utilities (accessible via Display.function_name):

• __print: Internal printing helper
• __print_abstract_definition: Print abstract OCP definition
• __print_mathematical_definition: Print mathematical OCP formulation

See also: CTModels

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

Extract a subplot from an existing plot.

Examples

julia> p1, p2 = plot(1:2), plot(10:20)
julia> pl = plot(p1, p2)  # plot containing 2 subplots

julia> plot(pl.subplots[1])  # extract 1st subplot as a standalone plot
julia> plot(pl.subplots[2])  # extract 2nd subplot as a standalone plot

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.