Public API

This page lists exported symbols of CTFlows.Trajectories.

From `CTFlows.Trajectories`

`CTFlows.Trajectories` [Module]

CTFlows.Trajectories — Module

Trajectories

Trajectory types and trajectory building for CTFlows.

This module provides:

AbstractIntegrationResult: Abstraction for raw ODE integration results
VectorFieldTrajectory: Trajectory type wrapping integration results
build_trajectory: Trajectory building functions for different configuration types
final_state, times, evaluate_at: Semantic accessors for integration results
state, time_grid: Semantic accessors for VectorFieldTrajectory
plot: Plotting functionality for trajectories

`AbstractHamiltonianVectorFieldTrajectory` [Abstract Type]

CTFlows.Trajectories.AbstractHamiltonianVectorFieldTrajectory — Type

abstract type AbstractHamiltonianVectorFieldTrajectory

Abstract supertype for Hamiltonian vector field solution containers.

This type defines the interface for all solution types that wrap ODE integration results for Hamiltonian systems.

`AbstractVectorFieldTrajectory` [Abstract Type]

CTFlows.Trajectories.AbstractVectorFieldTrajectory — Type

abstract type AbstractVectorFieldTrajectory

Abstract supertype for vector field solution containers.

This type defines the interface for all solution types that wrap ODE integration results.

`CostateProjection` [Struct]

CTFlows.Trajectories.CostateProjection — Type

struct CostateProjection{S<:CTFlows.Trajectories.HamiltonianVectorFieldTrajectory} <: Function

Callable struct returning the costate component of a HamiltonianVectorFieldTrajectory.

CostateProjection(sol)(t) is equivalent to sol(t)[2], but avoids creating a closure each time costate(sol) is called. The solution reference is stored once at construction.

`HamiltonianVectorFieldTrajectory` [Struct]

CTFlows.Trajectories.HamiltonianVectorFieldTrajectory — Type

struct HamiltonianVectorFieldTrajectory{X0, R<:CTFlows.Integrators.AbstractIntegrationResult} <: CTFlows.Trajectories.AbstractHamiltonianVectorFieldTrajectory

Container for the integration result from a HamiltonianTrajectoryConfig integration.

This type wraps the integration result returned by integrators and provides semantic accessors for time grids, state functions, and costate functions.

Fields

result: The integration result object (subtype of AbstractIntegrationResult).

Accessors

times(sol): Get the time grid (alias: time_grid(sol))
state(sol): Get the solution as a callable state function x(t)
costate(sol): Get the solution as a callable costate function p(t)
sol(t): Evaluate the solution at time t, returning tuple (x(t), p(t))

Example

using CTFlows.Trajectories

sol = HamiltonianVectorFieldTrajectory(result)
ts = times(sol)           # or time_grid(sol)
x = state(sol)            # callable state function x(t)
p = costate(sol)          # callable costate function p(t)
x(0.5), p(0.5)           # evaluate at t = 0.5
x0, p0 = sol(0.0)        # returns tuple (x(0), p(0))

`StateProjection` [Struct]

CTFlows.Trajectories.StateProjection — Type

struct StateProjection{S<:CTFlows.Trajectories.HamiltonianVectorFieldTrajectory} <: Function

Callable struct returning the state component of a HamiltonianVectorFieldTrajectory.

StateProjection(sol)(t) is equivalent to sol(t)[1], but avoids creating a closure each time state(sol) is called. The solution reference is stored once at construction.

`VectorFieldTrajectory` [Struct]

CTFlows.Trajectories.VectorFieldTrajectory — Type

struct VectorFieldTrajectory{R<:CTFlows.Integrators.AbstractIntegrationResult} <: CTFlows.Trajectories.AbstractVectorFieldTrajectory

Container for the integration result from a StateTrajectoryConfig integration.

This type wraps the integration result returned by integrators and provides semantic accessors for time grids and state functions.

Fields

result: The integration result object (subtype of AbstractIntegrationResult).

Accessors

times(sol): Get the time grid (alias: time_grid(sol))
state(sol): Get the solution as a callable state function
sol(t): Evaluate the solution at time t (equivalent to state(sol)(t))

Example

using CTFlows.Trajectories

sol = VectorFieldTrajectory(result)
ts = times(sol)           # or time_grid(sol)
x = state(sol)            # callable state function
x(0.5)                    # evaluate at t = 0.5

`build_trajectory` [Function]

CTFlows.Trajectories.build_trajectory — Function

build_trajectory(
    _::Type{CTBase.Traits.EndPointMode},
    _::Type{CTBase.Traits.StateDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTFlows.Integrators.AbstractIntegrationResult
) -> Any

Default implementation for scalar point configs — return the final state.

For scalar configurations (initial_state <: Number), unwraps the length-1 vector that was introduced by scalar-promotion at ODE problem construction time.

This uses compile-time dispatch on the initial state type to avoid runtime type tests.

Arguments

::Type{Traits.EndPointMode}: The point mode trait type.
::Type{Traits.StateDynamics}: The state content trait type.
initial_state::Number: The scalar initial state.
result::Integrators.AbstractIntegrationResult: The integration result.

Returns

Number: The unwrapped scalar final state.

build_trajectory(
    _::Type{CTBase.Traits.TrajectoryMode},
    _::Type{CTBase.Traits.StateDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTFlows.Integrators.AbstractIntegrationResult
) -> CTFlows.Trajectories.VectorFieldTrajectory

Default implementation for trajectory configs — wrap the integration result in a VectorFieldTrajectory for future extensibility.

Arguments

::Type{Traits.TrajectoryMode}: The trajectory mode trait type.
::Type{Traits.StateDynamics}: The state content trait type.
initial_state: The initial state.
result::Integrators.AbstractIntegrationResult: The integration result.

Returns

VectorFieldTrajectory: The wrapped integration result.

build_trajectory(
    _::Type{CTBase.Traits.EndPointMode},
    _::Type{CTBase.Traits.HamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTFlows.Integrators.AbstractIntegrationResult
) -> Tuple{Any, Any}

Build a solution for Hamiltonian point configs.

Returns the final state and costate as a tuple (xf, pf), dispatching on the type of the initial state to handle scalar, vector, and matrix cases.

Arguments

::Type{Traits.EndPointMode}: The point mode trait type.
::Type{Traits.HamiltonianDynamics}: The Hamiltonian content trait type.
initial_state: The initial state (scalar, vector, or matrix).
result::Integrators.AbstractIntegrationResult: The integration result.

Returns

Tuple: The final state and costate. Type depends on initial_state:
- Tuple{Number, Number} for scalar inputs
- Tuple{AbstractVector, AbstractVector} for vector inputs
- Tuple{AbstractMatrix, AbstractMatrix} for matrix inputs

build_trajectory(
    _::Type{CTBase.Traits.TrajectoryMode},
    _::Type{CTBase.Traits.HamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTFlows.Integrators.AbstractIntegrationResult
) -> CTFlows.Trajectories.HamiltonianVectorFieldTrajectory

Build a solution for Hamiltonian trajectory configs.

Wraps the integration result in a HamiltonianVectorFieldTrajectory for future extensibility.

Arguments

::Type{Traits.TrajectoryMode}: The trajectory mode trait type.
::Type{Traits.HamiltonianDynamics}: The Hamiltonian content trait type.
initial_state: The initial state.
result::Integrators.AbstractIntegrationResult: The integration result.

Returns

HamiltonianVectorFieldTrajectory: The wrapped integration result.

build_trajectory(
    _::Type{CTBase.Traits.EndPointMode},
    _::Type{CTBase.Traits.AugmentedHamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTFlows.Integrators.AbstractIntegrationResult
) -> Tuple{Any, Any, Any}

Build a solution for augmented Hamiltonian point configs.

Returns the final state, costate, and variable costate as a tuple (xf, pf, pvf). For Hamiltonian systems, n_p = n_x always, so the augmented state [x; p; pv] splits using only the state dimension n = length(initial_state).

Arguments

::Type{Traits.EndPointMode}: The point mode trait type.
::Type{Traits.AugmentedHamiltonianDynamics}: The augmented Hamiltonian content trait type.
initial_state: The initial state (used to determine state dimension n).
result::Integrators.AbstractIntegrationResult: The integration result.

Returns

Tuple{AbstractVector, AbstractVector, AbstractVector}: Tuple (xf, pf, pvf).

Notes

Uses _aug_split_solution helper to split the augmented final state.
Assumes n_p = n_x invariant for Hamiltonian systems.

`costate` [Function]

CTFlows.Trajectories.costate — Function

costate(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> CTFlows.Trajectories.CostateProjection

Return the solution as a costate function of time p(t).

Returns a CostateProjection wrapping the solution, callable as p(t).

Arguments

sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

CostateProjection: A callable t -> p(t) that returns the costate at time t.

Example

using CTFlows.Trajectories

sol = HamiltonianVectorFieldTrajectory(result)
p = costate(sol)  # p is a callable CostateProjection
p(0.0)            # initial costate
p(0.5)            # interpolated costate at t = 0.5

`plot` [Function]

RecipesBase.plot — Function

plot(
    sol::CTFlows.Trajectories.AbstractVectorFieldTrajectory;
    kwargs...
) -> Any

Plot stub — throws error if Plots extension not loaded.

Arguments

sol::AbstractVectorFieldTrajectory: The vector field solution.
kwargs...: Additional plotting keyword arguments (ignored).

Throws

CTBase.Exceptions.ExtensionError: If Plots extension is not loaded.

plot(
    sol::CTFlows.Trajectories.AbstractHamiltonianVectorFieldTrajectory;
    kwargs...
) -> Any

Plot stub — throws error if Plots extension not loaded.

Arguments

sol::AbstractHamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.
kwargs...: Additional plotting keyword arguments (ignored).

Throws

CTBase.Exceptions.ExtensionError: If Plots extension is not loaded.

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.Solutions.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(
    sol::CTFlows.Trajectories.VectorFieldTrajectory;
    kwargs...
) -> Any

Plot a VectorFieldTrajectory by extracting time points and states.

Uses default xlabel="time" for the x-axis label and font size settings (10pt for labels and titles).

Arguments

sol::Trajectories.VectorFieldTrajectory: The solution to plot.
kwargs...: Additional keyword arguments passed to Plots.plot.

Returns

The plot object returned by Plots.plot.

plot(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory;
    kwargs...
) -> Any

Plot a HamiltonianVectorFieldTrajectory by extracting time points, states, and costates.

Uses a (1, 2) layout to show state and costate in separate subplots. Uses default xlabel=["time" "time"] for both subplots, title=["state" "costate"] for subplot titles, and font size settings (10pt for labels and titles).

Arguments

sol::Trajectories.HamiltonianVectorFieldTrajectory: The Hamiltonian solution to plot.
kwargs...: Additional keyword arguments passed to Plots.plot.

Returns

The plot object returned by Plots.plot.

`state` [Function]

CTFlows.Trajectories.state — Function

state(
    sol::CTFlows.Trajectories.VectorFieldTrajectory
) -> CTFlows.Trajectories.VectorFieldTrajectory

Return the solution itself as a state function of time.

This is a semantic accessor that returns sol itself (which is already callable), providing a clear, self-documenting way to obtain the trajectory function.

Arguments

sol::VectorFieldTrajectory: The vector field solution.

Returns

VectorFieldTrajectory: The solution itself, which is callable as a function of time.

Example

using CTFlows.Trajectories

sol = VectorFieldTrajectory(result)
x = state(sol)    # x is a function of time
x(0.0)            # initial state
x(0.5)            # interpolated state at t = 0.5
x.(0.0:0.1:1.0)   # broadcast over time grid

Notes

This accessor provides a foundation for uniform semantic accessors in optimal control: state(sol), costate(sol), control(sol) when extended to Hamiltonian systems.
No allocation occurs — returns sol directly.

state(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> CTFlows.Trajectories.StateProjection

Return the solution as a state function of time x(t).

Returns a StateProjection wrapping the solution, callable as x(t).

Arguments

sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

StateProjection: A callable t -> x(t) that returns the state at time t.

Example

using CTFlows.Trajectories

sol = HamiltonianVectorFieldTrajectory(result)
x = state(sol)    # x is a callable StateProjection
x(0.0)            # initial state
x(0.5)            # interpolated state at t = 0.5

`time_grid` [Function]

CTFlows.Trajectories.time_grid — Function

time_grid(
    sol::CTFlows.Trajectories.VectorFieldTrajectory
) -> Any

Alias for times(sol) — returns the time grid from the solution.

This is an alternative, more explicit name for times in numerical contexts where "time grid" is the standard terminology.

Arguments

sol::VectorFieldTrajectory: The vector field solution.

Returns

AbstractVector: The vector of time points.

Example

using CTFlows.Trajectories

sol = VectorFieldTrajectory(result)
tg = time_grid(sol)  # same as times(sol)

Notes

time_grid and times are two names for the same operation.
Use time_grid when "grid" terminology is clearer in context.
Use times for brevity in everyday use.

time_grid(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> Any

Alias for times(sol) — returns the time grid from the solution.

This is an alternative, more explicit name for times in numerical contexts where "time grid" is the standard terminology.

Arguments

sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

AbstractVector: The vector of time points.