OptimalControl.jl

OptimalControl.jl is the core package of the control-toolbox ecosystem. Below, we group together the documentation of all the functions and types exported by OptimalControl.

Beware!

Even if the following functions are prefixed by another package, such as CTFlows.Lift, they can all be used with OptimalControl. In fact, all functions prefixed with another package are simply reexported. For example, Lift is defined in CTFlows but accessible from OptimalControl.

julia> using OptimalControl
julia> F(x) = 2x
julia> H = Lift(F)
julia> x = 1
julia> p = 2
julia> H(x, p)
4

Exported functions and types

OptimalControl.OptimalControl — Module

OptimalControl

High-level interface for solving optimal control problems.

This package provides a unified, user-friendly API for defining and solving optimal control problems using various discretization methods, NLP modelers, and solvers. It orchestrates the complete workflow from problem definition to solution.

Main Features

Flexible solve interface: Descriptive (symbolic) or explicit (typed components) modes
Multiple discretization methods: Collocation and other schemes via CTDirect
Multiple NLP modelers: ADNLP, ExaModels with CPU/GPU support
Multiple solvers: Ipopt, MadNLP, MadNCL, Knitro with CPU/GPU support
Automatic component completion: Partial specifications are completed intelligently
Option routing: Strategy-specific options are routed to the appropriate components

Usage

using OptimalControl

# Define your optimal control problem
ocp = Model(...)
# ... problem definition ...

# Solve using descriptive mode (symbolic description)
sol = solve(ocp, :collocation, :adnlp, :ipopt)

# Or solve using explicit mode (typed components)
sol = solve(ocp; 
    discretizer=CTDirect.Collocation(),
    modeler=CTSolvers.ADNLP(),
    solver=CTSolvers.Ipopt()
)

Exported Names

See Also

solve: Main entry point for solving optimal control problems
methods: List available solving methods
CTBase: Core types and abstractions
CTDirect: Direct methods for discretization
CTSolvers: NLP solvers and orchestration

Documentation

Base.:* — Method

*(x, y...)

Multiplication operator.

Infix x*y*z*... calls this function with all arguments, i.e. *(x, y, z, ...), which by default then calls (x*y) * z * ... starting from the left.

Juxtaposition such as 2pi also calls *(2, pi). Note that this operation has higher precedence than a literal *. Note also that juxtaposition "0x..." (integer zero times a variable whose name starts with x) is forbidden as it clashes with unsigned integer literals: 0x01 isa UInt8.

Note that overflow is possible for most integer types, including the default Int, when multiplying large numbers.

Examples

julia> 2 * 7 * 8
112

julia> *(2, 7, 8)
112

julia> [2 0; 0 3] * [1, 10]  # matrix * vector
2-element Vector{Int64}:
  2
 30

julia> 1/2pi, 1/2*pi  # juxtaposition has higher precedence
(0.15915494309189535, 1.5707963267948966)

julia> x = [1, 2]; x'x  # adjoint vector * vector
5

*(
    F::CTFlowsODE.AbstractFlow,
    g::Tuple{Real, TF<:CTFlowsODE.AbstractFlow}
) -> Any

Shorthand for concatenate(F, g) when g is a tuple (t_switch, G).

Arguments

F::AbstractFlow: The first flow.
g::Tuple{ctNumber, AbstractFlow}: Tuple containing the switching time and second flow.

Returns

A new flow that switches from F to G at t_switch.

Example

julia> F * (1.0, G)

*(
    F::CTFlowsODE.AbstractFlow,
    g::Tuple{Real, Any, TF<:CTFlowsODE.AbstractFlow}
) -> Any

Shorthand for concatenate(F, g) when g is a tuple (t_switch, η_switch, G) including a jump.

Arguments

F::AbstractFlow: The first flow.
g::Tuple{ctNumber, Any, AbstractFlow}: Tuple with switching time, jump value, and second flow.

Returns

A flow with a jump at t_switch and a switch from F to G.

Example

julia> F * (1.0, η, G)

CTFlows.Flow — Function

Flow(
    vf::CTFlows.VectorField;
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> CTFlowsODE.VectorFieldFlow

Constructs a flow object for a classical (non-Hamiltonian) vector field.

This creates a VectorFieldFlow that integrates the ODE system dx/dt = vf(t, x, v) using DifferentialEquations.jl. It handles both fixed and parametric dynamics, as well as jump discontinuities and event stopping.

Keyword Arguments

alg, abstol, reltol, saveat, internalnorm: Solver options.
kwargs_Flow...: Additional arguments passed to the solver configuration.

Example

julia> vf(t, x, v) = -v * x
julia> flow = CTFlows.Flow(CTFlows.VectorField(vf))
julia> x1 = flow(0.0, 1.0, 1.0)

Flow(
    h::CTFlows.AbstractHamiltonian;
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> CTFlowsODE.HamiltonianFlow

Constructs a Hamiltonian flow from a scalar Hamiltonian.

This method builds a numerical integrator that simulates the evolution of a Hamiltonian system given a Hamiltonian function h(t, x, p, l) or h(x, p).

Internally, it computes the right-hand side of Hamilton’s equations via automatic differentiation and returns a HamiltonianFlow object.

Keyword Arguments

alg, abstol, reltol, saveat, internalnorm: solver options.
kwargs_Flow...: forwarded to the solver.

Example

julia> H(x, p) = dot(p, p) + dot(x, x)
julia> flow = CTFlows.Flow(CTFlows.Hamiltonian(H))
julia> xf, pf = flow(0.0, x0, p0, 1.0)

Flow(
    hv::CTFlows.HamiltonianVectorField;
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> CTFlowsODE.HamiltonianFlow

Constructs a Hamiltonian flow from a precomputed Hamiltonian vector field.

This method assumes you already provide the Hamiltonian vector field (dx/dt, dp/dt) instead of deriving it from a scalar Hamiltonian.

Returns a HamiltonianFlow object that integrates the given system.

Keyword Arguments

alg, abstol, reltol, saveat, internalnorm: solver options.
kwargs_Flow...: forwarded to the solver.

Example

julia> hv(t, x, p, l) = (∇ₚH, -∇ₓH)
julia> flow = CTFlows.Flow(CTFlows.HamiltonianVectorField(hv))
julia> xf, pf = flow(0.0, x0, p0, 1.0, l)

Flow(
    ocp::CTModels.OCP.Model,
    u::CTFlows.ControlLaw;
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> Union{CTFlowsODE.OptimalControlFlow{CTFlows.Fixed}, CTFlowsODE.OptimalControlFlow{CTFlows.NonFixed}}

Construct a flow for an optimal control problem using a given control law.

This method builds the Hamiltonian system associated with the optimal control problem (ocp) and integrates the corresponding state–costate dynamics using the specified control law u.

Arguments

ocp::CTModels.Model: An optimal control problem defined using CTModels.
u::CTFlows.ControlLaw: A feedback control law generated by ControlLaw(...) or similar.
alg: Integration algorithm (default inferred).
abstol: Absolute tolerance for the ODE solver.
reltol: Relative tolerance for the ODE solver.
saveat: Time points at which to save the solution.
internalnorm: Optional norm function used by the integrator.
kwargs_Flow: Additional keyword arguments passed to the solver.

Returns

A flow object f such that:

f(t0, x0, p0, tf) integrates the state and costate from t0 to tf.
f((t0, tf), x0, p0) returns the full trajectory over the interval.

Example

julia> u = (x, p) -> p
julia> f = Flow(ocp, ControlLaw(u))

Flow(
    ocp::CTModels.OCP.Model,
    u::Function;
    autonomous,
    variable,
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> Union{CTFlowsODE.OptimalControlFlow{CTFlows.Fixed}, CTFlowsODE.OptimalControlFlow{CTFlows.NonFixed}}

Construct a flow for an optimal control problem using a control function in feedback form.

This method constructs the Hamiltonian and integrates the associated state–costate dynamics using a raw function u. It automatically wraps u as a control law.

Arguments

ocp::CTModels.Model: The optimal control problem.
u::Function: A feedback control function:
- If ocp is autonomous: u(x, p)
- If non-autonomous: u(t, x, p)
autonomous::Bool: Whether the control law depends on time.
variable::Bool: Whether the OCP involves variable time (e.g., free final time).
alg, abstol, reltol, saveat, internalnorm: ODE solver parameters.
kwargs_Flow: Additional options.

Returns

A Flow object compatible with function call interfaces for state propagation.

Example

julia> u = (t, x, p) -> t + p
julia> f = Flow(ocp, u)

Flow(
    ocp::CTModels.OCP.Model,
    u::Union{CTFlows.ControlLaw{<:Function, T, V}, CTFlows.FeedbackControl{<:Function, T, V}},
    g::Union{CTFlows.MixedConstraint{<:Function, T, V}, CTFlows.StateConstraint{<:Function, T, V}},
    μ::CTFlows.Multiplier{<:Function, T, V};
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> Union{CTFlowsODE.OptimalControlFlow{CTFlows.Fixed}, CTFlowsODE.OptimalControlFlow{CTFlows.NonFixed}}

Construct a flow for an optimal control problem with control and constraint multipliers in feedback form.

This variant constructs a Hamiltonian system incorporating both the control law and a multiplier law (e.g., for enforcing state or mixed constraints). All inputs must be consistent in time dependence.

Arguments

ocp::CTModels.Model: The optimal control problem.
u::ControlLaw or FeedbackControl: Feedback control.
g::StateConstraint or MixedConstraint: Constraint function.
μ::Multiplier: Multiplier function.
alg, abstol, reltol, saveat, internalnorm: Solver settings.
kwargs_Flow: Additional options.

Returns

A Flow object that integrates the constrained Hamiltonian dynamics.

Example

julia> f = Flow(ocp, (x, p) -> p[1], (x, u) -> x[1] - 1, (x, p) -> x[1]+p[1])

For non-autonomous cases:

julia> f = Flow(ocp, (t, x, p) -> t + p, (t, x, u) -> x - 1, (t, x, p) -> x+p)

Warning

All input functions must match the autonomous/non-autonomous nature of the problem.

Flow(
    ocp::CTModels.OCP.Model,
    u::Function,
    g::Function,
    μ::Function;
    autonomous,
    variable,
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> Union{CTFlowsODE.OptimalControlFlow{CTFlows.Fixed}, CTFlowsODE.OptimalControlFlow{CTFlows.NonFixed}}

Construct a flow from a raw feedback control, constraint, and multiplier.

This version is for defining flows directly from user functions without wrapping them into ControlLaw, Constraint, or Multiplier types. Automatically wraps and adapts them based on time dependence.

Arguments

ocp::CTModels.Model: The optimal control problem.
u::Function: Control law.
g::Function: Constraint.
μ::Function: Multiplier.
autonomous::Bool: Whether the system is autonomous.
variable::Bool: Whether time is a free variable.
alg, abstol, reltol, saveat, internalnorm: Solver parameters.
kwargs_Flow: Additional options.

Returns

A Flow object ready for trajectory integration.

Flow(
    dyn::Function;
    autonomous,
    variable,
    alg,
    abstol,
    reltol,
    saveat,
    internalnorm,
    kwargs_Flow...
) -> CTFlowsODE.ODEFlow

Constructs a Flow from a user-defined dynamical system given as a Julia function.

This high-level interface handles:

autonomous and non-autonomous systems,
presence or absence of additional variables (v),
selection of ODE solvers and tolerances,
and integrates with the CTFlows event system (e.g., jumps, callbacks).

Arguments

dyn: A function defining the vector field. Its signature must match the values of autonomous and variable.
autonomous: Whether the dynamics are time-independent (false by default).
variable: Whether the dynamics depend on a control or parameter v.
alg, abstol, reltol, saveat, internalnorm: Solver settings passed to OrdinaryDiffEq.solve.
kwargs_Flow: Additional keyword arguments passed to the solver.

Returns

An ODEFlow object, wrapping both the full solver and its right-hand side (RHS).

Supported Function Signatures for dyn

Depending on the (autonomous, variable) flags:

(false, false): dyn(x)
(false, true): dyn(x, v)
(true, false): dyn(t, x)
(true, true): dyn(t, x, v)

Example

julia> dyn(t, x, v) = [-x[1] + v[1] * sin(t)]
julia> flow = CTFlows.Flow(dyn; autonomous=true, variable=true)
julia> xT = flow((0.0, 1.0), [1.0], [0.1])

CTFlows.@Lie — Macro

Compute Lie or Poisson brackets.

This macro provides a unified notation to define recursively nested Lie brackets (for vector fields) or Poisson brackets (for Hamiltonians).

Syntax

@Lie [F, G]: computes the Lie bracket [F, G] of two vector fields.
@Lie [[F, G], H]: supports arbitrarily nested Lie brackets.
@Lie {H, K}: computes the Poisson bracket {H, K} of two Hamiltonians.
@Lie {{H, K}, L}: supports arbitrarily nested Poisson brackets.
@Lie expr autonomous = false: specifies a non-autonomous system.
@Lie expr variable = true: indicates presence of an auxiliary variable v.

Keyword-like arguments can be provided to control the evaluation context for Poisson brackets with raw functions:

autonomous = Bool: whether the system is time-independent (default: true).
variable = Bool: whether the system depends on an extra variable v (default: false).

Bracket type detection

Square brackets [...] denote Lie brackets between VectorField objects.
Curly brackets {...} denote Poisson brackets between Hamiltonian objects or between raw functions.
The macro automatically dispatches to Lie or Poisson depending on the input pattern.

Return

A callable object representing the specified Lie or Poisson bracket expression. The returned function can be evaluated like any other vector field or Hamiltonian.

Examples

■ Lie brackets with VectorField (autonomous)

julia> F1 = VectorField(x -> [0, -x[3], x[2]])
julia> F2 = VectorField(x -> [x[3], 0, -x[1]])
julia> L = @Lie [F1, F2]
julia> L([1.0, 2.0, 3.0])
3-element Vector{Float64}:
  2.0
 -1.0
  0.0

■ Lie brackets with VectorField (non-autonomous, with auxiliary variable)

julia> F1 = VectorField((t, x, v) -> [0, -x[3], x[2]]; autonomous=false, variable=true)
julia> F2 = VectorField((t, x, v) -> [x[3], 0, -x[1]]; autonomous=false, variable=true)
julia> L = @Lie [F1, F2]
julia> L(0.0, [1.0, 2.0, 3.0], 1.0)
3-element Vector{Float64}:
  2.0
 -1.0
  0.0

■ Poisson brackets with Hamiltonian (autonomous)

julia> H1 = Hamiltonian((x, p) -> x[1]^2 + p[2]^2)
julia> H2 = Hamiltonian((x, p) -> x[2]^2 + p[1]^2)
julia> P = @Lie {H1, H2}
julia> P([1.0, 1.0], [3.0, 2.0])
-4.0

■ Poisson brackets with Hamiltonian (non-autonomous, with variable)

julia> H1 = Hamiltonian((t, x, p, v) -> x[1]^2 + p[2]^2 + v; autonomous=false, variable=true)
julia> H2 = Hamiltonian((t, x, p, v) -> x[2]^2 + p[1]^2 + v; autonomous=false, variable=true)
julia> P = @Lie {H1, H2}
julia> P(1.0, [1.0, 3.0], [4.0, 2.0], 3.0)
8.0

■ Poisson brackets from raw functions

julia> H1 = (x, p) -> x[1]^2 + p[2]^2
julia> H2 = (x, p) -> x[2]^2 + p[1]^2
julia> P = @Lie {H1, H2}
julia> P([1.0, 1.0], [3.0, 2.0])
-4.0

■ Poisson bracket with non-autonomous raw functions

julia> H1 = (t, x, p) -> x[1]^2 + p[2]^2 + t
julia> H2 = (t, x, p) -> x[2]^2 + p[1]^2 + t
julia> P = @Lie {H1, H2} autonomous = false
julia> P(3.0, [1.0, 2.0], [4.0, 1.0])
-8.0

■ Nested brackets

julia> F = VectorField(x -> [-x[1], x[2], x[3]])
julia> G = VectorField(x -> [x[3], -x[2], 0])
julia> H = VectorField(x -> [0, 0, -x[1]])
julia> nested = @Lie [[F, G], H]
julia> nested([1.0, 2.0, 3.0])
3-element Vector{Float64}:
  2.0
  0.0
 -6.0

julia> H1 = (x, p) -> x[2]*x[1]^2 + p[1]^2
julia> H2 = (x, p) -> x[1]*p[2]^2
julia> H3 = (x, p) -> x[1]*p[2] + x[2]*p[1]
julia> nested_poisson = @Lie {{H1, H2}, H3}
julia> nested_poisson([1.0, 2.0], [0.5, 1.0])
14.0

■ Mixed expressions with arithmetic

julia> F1 = VectorField(x -> [0, -x[3], x[2]])
julia> F2 = VectorField(x -> [x[3], 0, -x[1]])
julia> x = [1.0, 2.0, 3.0]
julia> @Lie [F1, F2](x) + 3 * [F1, F2](x)
3-element Vector{Float64}:
  8.0
 -4.0
  0.0

julia> H1 = (x, p) -> x[1]^2
julia> H2 = (x, p) -> p[1]^2
julia> H3 = (x, p) -> x[1]*p[1]
julia> x = [1.0, 2.0, 3.0]
julia> p = [3.0, 2.0, 1.0]
julia> @Lie {H1, H2}(x, p) + 2 * {H2, H3}(x, p)
24.0

CTFlows.Lie — Function

Lie derivative of a scalar function along a vector field.

Example:

julia> φ = x -> [x[2], -x[1]]
julia> X = VectorField(φ)
julia> f = x -> x[1]^2 + x[2]^2
julia> Lie(X,f)([1, 2])
0
julia> φ = (t, x, v) -> [t + x[2] + v[1], -x[1] + v[2]]
julia> X = VectorField(φ, NonAutonomous, NonFixed)
julia> f = (t, x, v) -> t + x[1]^2 + x[2]^2
julia> Lie(X, f)(1, [1, 2], [2, 1])
10

Lie derivative of a scalar function along a function with specified dependencies.

Example:

julia> φ = x -> [x[2], -x[1]]
julia> f = x -> x[1]^2 + x[2]^2
julia> Lie(φ,f)([1, 2])
0
julia> φ = (t, x, v) -> [t + x[2] + v[1], -x[1] + v[2]]
julia> f = (t, x, v) -> t + x[1]^2 + x[2]^2
julia> Lie(φ, f, autonomous=false, variable=true)(1, [1, 2], [2, 1])
10

Lie bracket of two vector fields in the autonomous case.

Example:

julia> f = x -> [x[2], 2x[1]]
julia> g = x -> [3x[2], -x[1]]
julia> X = VectorField(f)
julia> Y = VectorField(g)
julia> Lie(X, Y)([1, 2])
[7, -14]

Lie bracket of two vector fields in the nonautonomous case.

Example:

julia> f = (t, x, v) -> [t + x[2] + v, -2x[1] - v]
julia> g = (t, x, v) -> [t + 3x[2] + v, -x[1] - v]
julia> X = VectorField(f, NonAutonomous, NonFixed)
julia> Y = VectorField(g, NonAutonomous, NonFixed)
julia> Lie(X, Y)(1, [1, 2], 1)
[-7, 12]

CTFlows.Lift — Function

Lift(
    X::CTFlows.VectorField
) -> CTFlows.HamiltonianLift{CTFlows.VectorField{TF, TD, VD}} where {TF<:Function, TD<:CTFlows.TimeDependence, VD<:CTFlows.VariableDependence}

Construct the Hamiltonian lift of a VectorField.

Arguments

X::VectorField: The vector field to lift. Its signature determines if it is autonomous and/or variable.

Returns

A HamiltonianLift callable object representing the Hamiltonian lift of X.

Examples

julia> HL = Lift(VectorField(x -> [x[1]^2, x[2]^2], autonomous=true, variable=false))
julia> HL([1, 0], [0, 1])  # returns 0

julia> HL2 = Lift(VectorField((t, x, v) -> [t + x[1]^2, x[2]^2 + v], autonomous=false, variable=true))
julia> HL2(1, [1, 0], [0, 1], 1)  # returns 1

julia> H = Lift(x -> 2x)
julia> H(1, 1)  # returns 2

julia> H2 = Lift((t, x, v) -> 2x + t - v, autonomous=false, variable=true)
julia> H2(1, 1, 1, 1)  # returns 2

# Alternative syntax using symbols for autonomy and variability
julia> H3 = Lift((t, x, v) -> 2x + t - v, NonAutonomous, NonFixed)
julia> H3(1, 1, 1, 1)  # returns 2

Lift(
    X::Function;
    autonomous,
    variable
) -> CTFlows.var"#21#22"{<:Function}

Construct the Hamiltonian lift of a function.

Arguments

X::Function: The function representing the vector field.
autonomous::Bool=true: Whether the function is autonomous (time-independent).
variable::Bool=false: Whether the function depends on an additional variable argument.

Returns

A callable function computing the Hamiltonian lift,

(and variants depending on autonomous and variable).

Details

Depending on the autonomous and variable flags, the returned function has one of the following call signatures:

(x, p) if autonomous=true and variable=false
(x, p, v) if autonomous=true and variable=true
(t, x, p) if autonomous=false and variable=false
(t, x, p, v) if autonomous=false and variable=true

Examples

julia> H = Lift(x -> 2x)
julia> H(1, 1)  # returns 2

julia> H2 = Lift((t, x, v) -> 2x + t - v, autonomous=false, variable=true)
julia> H2(1, 1, 1, 1)  # returns 2

CTFlows.Poisson — Function

Poisson(
    f::CTFlows.AbstractHamiltonian{CTFlows.Autonomous, V<:CTFlows.VariableDependence},
    g::CTFlows.AbstractHamiltonian{CTFlows.Autonomous, V<:CTFlows.VariableDependence}
) -> Any

Poisson bracket of two Hamiltonian functions (subtype of AbstractHamiltonian). Autonomous case.

Returns a Hamiltonian representing the Poisson bracket {f, g} of two autonomous Hamiltonian functions f and g.

Example

julia> f = (x, p) -> x[2]^2 + 2x[1]^2 + p[1]^2
julia> g = (x, p) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1]
julia> F = Hamiltonian(f)
julia> G = Hamiltonian(g)
julia> Poisson(f, g)([1, 2], [2, 1])     # -20
julia> Poisson(f, G)([1, 2], [2, 1])     # -20
julia> Poisson(F, g)([1, 2], [2, 1])     # -20

Poisson(
    f::CTFlows.AbstractHamiltonian{CTFlows.NonAutonomous, V<:CTFlows.VariableDependence},
    g::CTFlows.AbstractHamiltonian{CTFlows.NonAutonomous, V<:CTFlows.VariableDependence}
) -> Any

Poisson bracket of two Hamiltonian functions. Non-autonomous case.

Returns a Hamiltonian representing {f, g} where f and g are time-dependent.

Example

julia> f = (t, x, p, v) -> t*v[1]*x[2]^2 + 2x[1]^2 + p[1]^2 + v[2]
julia> g = (t, x, p, v) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1] + t - v[2]
julia> F = Hamiltonian(f, autonomous=false, variable=true)
julia> G = Hamiltonian(g, autonomous=false, variable=true)
julia> Poisson(F, G)(2, [1, 2], [2, 1], [4, 4])     # -76
julia> Poisson(f, g, NonAutonomous, NonFixed)(2, [1, 2], [2, 1], [4, 4])     # -76

Poisson(
    f::CTFlows.HamiltonianLift{T<:CTFlows.TimeDependence, V<:CTFlows.VariableDependence},
    g::CTFlows.HamiltonianLift{T<:CTFlows.TimeDependence, V<:CTFlows.VariableDependence}
)

Poisson bracket of two HamiltonianLift vector fields.

Returns the HamiltonianLift corresponding to the Lie bracket of vector fields f.X and g.X.

Example

julia> f = x -> [x[1]^2 + x[2]^2, 2x[1]^2]
julia> g = x -> [3x[2]^2, x[2] - x[1]^2]
julia> F = Lift(f)
julia> G = Lift(g)
julia> Poisson(F, G)([1, 2], [2, 1])     # -64

julia> f = (t, x, v) -> [t*v[1]*x[2]^2, 2x[1]^2 + v[2]]
julia> g = (t, x, v) -> [3x[2]^2 - x[1]^2, t - v[2]]
julia> F = Lift(f, NonAutonomous, NonFixed)
julia> G = Lift(g, NonAutonomous, NonFixed)
julia> Poisson(F, G)(2, [1, 2], [2, 1], [4, 4])     # 100

Poisson(
    f::Function,
    g::Function;
    autonomous,
    variable
) -> CTFlows.Hamiltonian

Poisson bracket of two functions. The time and variable dependence are specified with keyword arguments.

Returns a Hamiltonian computed from the functions promoted as Hamiltonians.

Example

julia> f = (x, p) -> x[2]^2 + 2x[1]^2 + p[1]^2
julia> g = (x, p) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1]
julia> Poisson(f, g)([1, 2], [2, 1])     # -20

julia> f = (t, x, p, v) -> t*v[1]*x[2]^2 + 2x[1]^2 + p[1]^2 + v[2]
julia> g = (t, x, p, v) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1] + t - v[2]
julia> Poisson(f, g, autonomous=false, variable=true)(2, [1, 2], [2, 1], [4, 4])     # -76

Poisson(
    f::Function,
    g::CTFlows.AbstractHamiltonian{TD<:CTFlows.TimeDependence, VD<:CTFlows.VariableDependence}
) -> CTFlows.Hamiltonian

Poisson bracket of a function and a Hamiltonian.

Returns a Hamiltonian representing {f, g} where g is already a Hamiltonian.

Example

julia> f = (x, p) -> x[2]^2 + 2x[1]^2 + p[1]^2
julia> g = (x, p) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1]
julia> G = Hamiltonian(g)
julia> Poisson(f, G)([1, 2], [2, 1])     # -20

julia> f = (t, x, p, v) -> t*v[1]*x[2]^2 + 2x[1]^2 + p[1]^2 + v[2]
julia> g = (t, x, p, v) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1] + t - v[2]
julia> G = Hamiltonian(g, autonomous=false, variable=true)
julia> Poisson(f, G)(2, [1, 2], [2, 1], [4, 4])     # -76

Poisson(
    f::CTFlows.AbstractHamiltonian{TD<:CTFlows.TimeDependence, VD<:CTFlows.VariableDependence},
    g::Function
) -> CTFlows.Hamiltonian

Poisson bracket of a Hamiltonian and a function.

Returns a Hamiltonian representing {f, g} where f is already a Hamiltonian.

Example

julia> f = (x, p) -> x[2]^2 + 2x[1]^2 + p[1]^2
julia> g = (x, p) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1]
julia> F = Hamiltonian(f)
julia> Poisson(F, g)([1, 2], [2, 1])     # -20

julia> f = (t, x, p, v) -> t*v[1]*x[2]^2 + 2x[1]^2 + p[1]^2 + v[2]
julia> g = (t, x, p, v) -> 3x[2]^2 - x[1]^2 + p[2]^2 + p[1] + t - v[2]
julia> F = Hamiltonian(f, autonomous=false, variable=true)
julia> Poisson(F, g)(2, [1, 2], [2, 1], [4, 4])     # -76

CTModels.OCP.boundary_constraints_dual — Function

boundary_constraints_dual(
    model::CTModels.OCP.DualModel{<:Union{Nothing, Function}, BC_Dual<:Union{Nothing, AbstractVector{<:Real}}}
) -> Union{Nothing, AbstractVector{<:Real}}

Return the dual vector associated with the boundary constraints.

Arguments

model::DualModel: A model including dual variables for boundary constraints.

Returns

A vector of dual values, or nothing if not set.

boundary_constraints_dual(
    sol::CTModels.OCP.Solution
) -> Union{Nothing, AbstractVector{<:Real}}

Return the dual of the boundary constraints.

CTModels.OCP.boundary_constraints_nl — Function

boundary_constraints_nl(
    model::CTModels.OCP.ConstraintsModel{<:Tuple, TB}
) -> Any

Get the nonlinear boundary constraints from the model.

Arguments

model: The constraints model from which to retrieve the boundary constraints.

Returns

The nonlinear boundary constraints.

Example

# Example of retrieving nonlinear boundary constraints
julia> model = ConstraintsModel(...)
julia> boundary_constraints = boundary_constraints_nl(model)

boundary_constraints_nl(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel, <:CTModels.OCP.AbstractStateModel, <:CTModels.OCP.AbstractControlModel, <:CTModels.OCP.AbstractVariableModel, <:Function, <:CTModels.OCP.AbstractObjectiveModel, <:CTModels.OCP.ConstraintsModel{<:Tuple, TB<:Tuple}}
) -> Any

Return the nonlinear boundary constraints.

CTSolvers.Strategies.bypass — Function

bypass(val) -> CTSolvers.Strategies.BypassValue

Mark an option value to bypass validation.

This function creates a BypassValue wrapper around the provided value. When passed to a strategy constructor, this value will be accepted even if the option name is unknown (not in metadata) or if validation would otherwise fail.

This can be combined with route_to to bypass validation for specific strategies when routing ambiguous options.

Arguments

val: The option value to wrap

Returns

BypassValue: The wrapped value

Example

julia> using CTSolvers.Strategies

julia> # Pass an unknown option directly to strategy
julia> solver = Ipopt(
           max_iter=100, 
           custom_backend_option=bypass(42)  # Bypasses validation
       )
Ipopt(options=StrategyOptions{...})

julia> # Alternative syntax using force alias
julia> solver = Ipopt(
           max_iter=100, 
           custom_backend_option=force(42)  # Same as bypass(42)
       )
Ipopt(options=StrategyOptions{...})

julia> # Combine with routing for ambiguous options
julia> solve(ocp, method; 
           backend = route_to(ipopt=bypass(42))  # Route to ipopt AND bypass validation
       )

Notes

Use with caution! Bypassed options are passed directly to the backend.
Typos in option names will not be caught by validation.
Invalid values for the backend will cause backend-level errors.
Can be combined with route_to for strategy-specific bypassing
force is an alias for bypass - they are identical functions

See also: BypassValue, route_to, force

CTModels.OCP.components — Function

components(model::CTModels.OCP.StateModel) -> Vector{String}

Get the components names of the state from the state model.

components(
    model::CTModels.OCP.StateModelSolution
) -> Vector{String}

Get the components names of the state from the state model solution.

components(
    model::CTModels.OCP.ControlModel
) -> Vector{String}

Get the names of the control components.

Arguments

model::ControlModel: The control model.

Returns

Vector{String}: A list of control component names.

Example

julia> components(controlmodel)
["u₁", "u₂"]

components(
    model::CTModels.OCP.ControlModelSolution
) -> Vector{String}

Get the names of the control components from the solution.

Arguments

model::ControlModelSolution: The control model solution.

Returns

Vector{String}: A list of control component names.

components(
    _::CTModels.OCP.EmptyControlModel
) -> Vector{String}

Return an empty vector since there are no control components defined.

components(
    model::CTModels.OCP.VariableModel
) -> Vector{String}

Return the names of the components of the variable.

components(
    model::CTModels.OCP.VariableModelSolution
) -> Vector{String}

Return the names of the components from the variable solution.

components(
    _::CTModels.OCP.EmptyVariableModel
) -> Vector{String}

Return an empty vector since there are no variable components defined.

Missing docstring.

Missing docstring for constraint. Check Documenter's build log for details.

CTModels.OCP.constraints — Function

constraints(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.AbstractTimesModel, <:CTModels.OCP.AbstractStateModel, <:CTModels.OCP.AbstractControlModel, <:CTModels.OCP.AbstractVariableModel, <:Function, <:CTModels.OCP.AbstractObjectiveModel, C<:CTModels.OCP.AbstractConstraintsModel}
) -> CTModels.OCP.AbstractConstraintsModel

Return the constraints struct.

CTModels.OCP.constraints_violation — Function

constraints_violation(sol::CTModels.OCP.Solution) -> Float64

Return the constraints violation.

CTModels.OCP.control — Function

control(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel, <:CTModels.OCP.AbstractStateModel, T<:CTModels.OCP.AbstractControlModel}
) -> CTModels.OCP.AbstractControlModel

Return the control struct.

control(
    sol::CTModels.OCP.Solution{<:CTModels.OCP.AbstractTimeGridModel, <:CTModels.OCP.AbstractTimesModel, <:CTModels.OCP.AbstractStateModel, <:CTModels.OCP.ControlModelSolution{TS<:Function}}
) -> Function

Return the control as a function of time.

julia> u  = control(sol)
julia> t0 = time_grid(sol)[1]
julia> u0 = u(t0) # control at the initial time

control(init::CTModels.Init.AbstractInitialGuess) -> Any

Return the control trajectory from an initial guess.

control(sol::CTModels.OCP.AbstractSolution) -> Function

Return the control trajectory from a solution.

CTModels.OCP.control_components — Function

control_components(
    ocp::CTModels.OCP.Model
) -> Vector{String}

Return the names of the components of the control.

control_components(
    sol::CTModels.OCP.Solution
) -> Vector{String}

Return the names of the components of the control.

CTModels.OCP.control_constraints_box — Function

control_constraints_box(
    model::CTModels.OCP.ConstraintsModel{<:Tuple, <:Tuple, <:Tuple, TC}
) -> Any

Get the control box constraints from the model.

Arguments

model: The constraints model from which to retrieve the control box constraints.

Returns

The control box constraints.

Example

# Example of retrieving control box constraints
julia> model = ConstraintsModel(...)
julia> control_constraints = control_constraints_box(model)

control_constraints_box(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel, <:CTModels.OCP.AbstractStateModel, <:CTModels.OCP.AbstractControlModel, <:CTModels.OCP.AbstractVariableModel, <:Function, <:CTModels.OCP.AbstractObjectiveModel, <:CTModels.OCP.ConstraintsModel{<:Tuple, <:Tuple, <:Tuple, TC<:Tuple}}
) -> Any

Return the box constraints on control.

CTModels.OCP.control_constraints_lb_dual — Function

control_constraints_lb_dual(
    model::CTModels.OCP.DualModel{<:Union{Nothing, Function}, <:Union{Nothing, AbstractVector{<:Real}}, <:Union{Nothing, Function}, <:Union{Nothing, Function}, CC_LB_Dual<:Union{Nothing, Function}}
) -> Union{Nothing, Function}

Return the dual function associated with the lower bounds of control constraints.

Arguments

model::DualModel: A model including dual variables for control lower bounds.

Returns

A function mapping time t to a vector of dual values, or nothing if not set.

control_constraints_lb_dual(
    sol::CTModels.OCP.Solution
) -> Union{Nothing, Function}

Return the lower bound dual of the control constraints.

CTModels.OCP.control_constraints_ub_dual — Function

control_constraints_ub_dual(
    model::CTModels.OCP.DualModel{<:Union{Nothing, Function}, <:Union{Nothing, AbstractVector{<:Real}}, <:Union{Nothing, Function}, <:Union{Nothing, Function}, <:Union{Nothing, Function}, CC_UB_Dual<:Union{Nothing, Function}}
) -> Union{Nothing, Function}

Return the dual function associated with the upper bounds of control constraints.

Arguments

model::DualModel: A model including dual variables for control upper bounds.

Returns

A function mapping time t to a vector of dual values, or nothing if not set.

control_constraints_ub_dual(
    sol::CTModels.OCP.Solution
) -> Union{Nothing, Function}

Return the upper bound dual of the control constraints.

CTModels.OCP.control_dimension — Function

control_dimension(ocp::CTModels.OCP.Model) -> Int64

Return the control dimension.

control_dimension(sol::CTModels.OCP.Solution) -> Int64

Return the dimension of the control.

CTModels.OCP.control_name — Function

control_name(ocp::CTModels.OCP.Model) -> String

Return the name of the control.

control_name(sol::CTModels.OCP.Solution) -> String

Return the name of the control.

CTModels.OCP.costate — Function

costate(
    sol::CTModels.OCP.Solution{<:CTModels.OCP.AbstractTimeGridModel, <:CTModels.OCP.AbstractTimesModel, <:CTModels.OCP.AbstractStateModel, <:CTModels.OCP.AbstractControlModel, <:CTModels.OCP.AbstractVariableModel, <:CTModels.OCP.AbstractModel, Co<:Function}
) -> Function

Return the costate as a function of time.

julia> p  = costate(sol)
julia> t0 = time_grid(sol)[1]
julia> p0 = p(t0) # costate at the initial time

CTModels.OCP.criterion — Function

criterion(model::CTModels.OCP.MayerObjectiveModel) -> Symbol

Return the criterion (:min or :max).

criterion(
    model::CTModels.OCP.LagrangeObjectiveModel
) -> Symbol

Return the criterion (:min or :max).

criterion(model::CTModels.OCP.BolzaObjectiveModel) -> Symbol

Return the criterion (:min or :max).

criterion(ocp::CTModels.OCP.Model) -> Symbol

Return the type of criterion (:min or :max).

CTParser.@def — Macro

Define an optimal control problem. One pass parsing of the definition. Can be used writing either ocp = @def begin ... end or @def ocp begin ... end. In the second case, setting log to true will display the parsing steps.

Example

ocp = @def begin
    tf ∈ R, variable
    t ∈ [ 0, tf ], time
    x ∈ R², state
    u ∈ R, control
    tf ≥ 0
    -1 ≤ u(t) ≤ 1
    q = x₁
    v = x₂
    q(0) == 1
    v(0) == 2
    q(tf) == 0
    v(tf) == 0
    0 ≤ q(t) ≤ 5,       (1)
    -2 ≤ v(t) ≤ 3,      (2)
    ẋ(t) == [ v(t), u(t) ]
    tf → min
end

@def ocp begin
    tf ∈ R, variable
    t ∈ [ 0, tf ], time
    x ∈ R², state
    u ∈ R, control
    tf ≥ 0
    -1 ≤ u(t) ≤ 1
    q = x₁
    v = x₂
    q(0) == 1
    v(0) == 2
    q(tf) == 0
    v(tf) == 0
    0 ≤ q(t) ≤ 5,       (1)
    -2 ≤ v(t) ≤ 3,      (2)
    ẋ(t) == [ v(t), u(t) ]
    tf → min
end true # final boolean to show parsing log

CTModels.OCP.definition — Function

definition(ocp::CTModels.OCP.Model) -> Expr

Return the model definition of the optimal control problem.

Arguments

ocp::Model: The built optimal control problem model.

Returns

Expr: The symbolic expression defining the problem.

definition(
    ocp::CTModels.OCP.PreModel
) -> Union{Nothing, Expr}

Return the model definition of the optimal control problem or nothing.

Arguments

ocp::PreModel: The pre-model (may not have a definition set).

Returns

Union{Expr, Nothing}: The symbolic expression or nothing if not set.

CTSolvers.Strategies.describe — Function

Display detailed information about a strategy type, including its id, supertype, and full metadata with all available option definitions.

This function is useful for discovering what options a strategy accepts before constructing an instance.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type to describe

Example

julia> describe(Modelers.ADNLP)
Modelers.ADNLP (strategy type)
├─ id: :adnlp
├─ supertype: AbstractNLPModeler
└─ metadata: 4 options defined
   ├─ show_time :: Bool (default: false)
   │  description: Whether to show timing information
   ├─ backend :: Symbol (default: optimized)
   │  description: AD backend used by ADNLPModels
   └─ matrix_free :: Bool (default: false)
      description: Enable matrix-free mode

See also: option_source, options

CTSolvers.Strategies.options — Function

Return the current options of a strategy as a StrategyOptions.

Arguments

strategy::AbstractStrategy: The strategy instance

Returns

StrategyOptions: Current option values with provenance tracking

Example

# For a concrete strategy instance:
julia> strategy = MyStrategy(backend=:sparse)
julia> opts = options(strategy)
julia> opts
StrategyOptions with values=(backend=:sparse), sources=(backend=:user)

CTModels.OCP.path_constraints_dual — Function

path_constraints_dual(
    model::CTModels.OCP.DualModel{PC_Dual<:Union{Nothing, Function}}
) -> Union{Nothing, Function}

Return the dual function associated with the nonlinear path constraints.

Arguments

model::DualModel: A model including dual variables for path constraints.

Returns

A function mapping time t to the vector of dual values, or nothing if not set.

path_constraints_dual(
    sol::CTModels.OCP.Solution
) -> Union{Nothing, Function}

Return the dual of the path constraints.

CTModels.OCP.path_constraints_nl — Function

path_constraints_nl(
    model::CTModels.OCP.ConstraintsModel{TP}
) -> Any

Get the nonlinear path constraints from the model.

Arguments

model: The constraints model from which to retrieve the path constraints.

Returns

The nonlinear path constraints.

Example

# Example of retrieving nonlinear path constraints
julia> model = ConstraintsModel(...)
julia> path_constraints = path_constraints_nl(model)

path_constraints_nl(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel, <:CTModels.OCP.AbstractStateModel, <:CTModels.OCP.AbstractControlModel, <:CTModels.OCP.AbstractVariableModel, <:Function, <:CTModels.OCP.AbstractObjectiveModel, <:CTModels.OCP.ConstraintsModel{TP<:Tuple}}
) -> Any

Return the nonlinear path constraints.

RecipesBase.plot — Function

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)

RecipesBase.plot! — Function

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.

CTSolvers.Strategies.route_to — Function

route_to(; kwargs...)

Create a disambiguated option value by explicitly routing it to specific strategies.

This function resolves ambiguity when the same option name exists in multiple strategies (e.g., both modeler and solver have max_iter). It creates a RoutedOption that tells the orchestration layer exactly which strategy should receive which value.

Arguments

kwargs...: Named arguments where keys are strategy identifiers (:solver, :modeler, etc.) and values are the option values to route to those strategies

Returns

RoutedOption: A routed option containing the strategy => value mappings

Throws

Exceptions.PreconditionError: If no strategies are provided

Example

julia> using CTSolvers.Strategies

julia> # Single strategy
julia> route_to(solver=100)
RoutedOption((solver = 100,))

julia> # Multiple strategies with different values
julia> route_to(solver=100, modeler=50)
RoutedOption((solver = 100, modeler = 50))

Usage in solve()

# Without disambiguation - error if max_iter exists in multiple strategies
solve(ocp, method; max_iter=100)  # ❌ Ambiguous!

# With disambiguation - explicit routing
solve(ocp, method; 
    max_iter = route_to(solver=100)              # Only solver gets 100
)

solve(ocp, method; 
    max_iter = route_to(solver=100, modeler=50)  # Different values for each
)

Notes

Strategy identifiers must match the actual strategy IDs in your method tuple
You can route to one or multiple strategies in a single call
This is the recommended way to disambiguate options
The orchestration layer will validate that the strategy IDs exist

See also: RoutedOption, route_all_options

CommonSolve.solve — Method

solve(
    problem::CTSolvers.Optimization.AbstractOptimizationProblem,
    initial_guess,
    modeler::CTSolvers.Modelers.AbstractNLPModeler,
    solver::CTSolvers.Solvers.AbstractNLPSolver;
    display
) -> Any

High-level solve: Build NLP model, solve it, and build solution.

Arguments

problem::Optimization.AbstractOptimizationProblem: The optimization problem
initial_guess: Initial guess for the solution
modeler::Modelers.AbstractNLPModeler: Modeler to build NLP
solver::AbstractNLPSolver: Solver to use
display::Bool: Whether to show solver output (default: true)

Returns

Solution object from the optimization problem

Example

# Conceptual usage pattern
# problem = ...
# x0 = ...
# modeler = Modelers.ADNLP()
# solver = Solvers.Ipopt(max_iter=1000)
# solution = solve(problem, x0, modeler, solver, display=true)

See also: Optimization.build_model, Optimization.build_solution

CommonSolve.solve — Method

solve(
    ocp::CTModels.OCP.AbstractModel,
    description::Symbol...;
    kwargs...
) -> Union{CTModels.OCP.Solution{TimeGridModelType, TimesModelType, StateModelType, ControlModelType, VariableModelType, ModelType, CostateModelType, Float64, DualModelType, CTModels.OCP.SolverInfos{Any, Dict{Symbol, Any}}} where {TimeGridModelType<:Union{CTModels.OCP.MultipleTimeGridModel, CTModels.OCP.UnifiedTimeGridModel{Vector{Float64}}}, TimesModelType<:CTModels.OCP.TimesModel, StateModelType<:Union{CTModels.OCP.StateModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.StateModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, ControlModelType<:Union{CTModels.OCP.ControlModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.ControlModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, VariableModelType<:Union{CTModels.OCP.VariableModelSolution{Vector{Float64}}, CTModels.OCP.VariableModelSolution{Float64}}, ModelType<:(CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, T} where T<:CTModels.OCP.TimesModel), CostateModelType<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, DualModelType<:(CTModels.OCP.DualModel{PC_Dual, Nothing, SC_LB_Dual, SC_UB_Dual, CC_LB_Dual, CC_UB_Dual, Vector{Float64}, Vector{Float64}} where {PC_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, SC_LB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, SC_UB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, CC_LB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, CC_UB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}})}, CTModels.OCP.Solution{TimeGridModelType, TimesModelType, StateModelType, ControlModelType, VariableModelType, ModelType, CostateModelType, Float64, DualModelType, CTModels.OCP.SolverInfos{Any, Dict{Symbol, Any}}} where {TimeGridModelType<:Union{CTModels.OCP.MultipleTimeGridModel, CTModels.OCP.UnifiedTimeGridModel{Vector{Float64}}}, TimesModelType<:CTModels.OCP.TimesModel, StateModelType<:Union{CTModels.OCP.StateModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.StateModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, ControlModelType<:Union{CTModels.OCP.ControlModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.ControlModelSolution{TS} where TS<:CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, VariableModelType<:Union{CTModels.OCP.VariableModelSolution{Vector{Float64}}, CTModels.OCP.VariableModelSolution{Float64}}, ModelType<:(CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, T} where T<:CTModels.OCP.TimesModel), CostateModelType<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, DualModelType<:(CTModels.OCP.DualModel{PC_Dual, Vector{Float64}, SC_LB_Dual, SC_UB_Dual, CC_LB_Dual, CC_UB_Dual, Vector{Float64}, Vector{Float64}} where {PC_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, SC_LB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, SC_UB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, CC_LB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}, CC_UB_Dual<:Union{CTModels.OCP.var"#_wrap_scalar_and_deepcopy##0#_wrap_scalar_and_deepcopy##1", CTModels.OCP.var"#_wrap_scalar_and_deepcopy##2#_wrap_scalar_and_deepcopy##3"}})}}

Main entry point for optimal control problem resolution.

This function orchestrates the complete solve workflow by:

Detecting the resolution mode (explicit vs descriptive) from arguments
Extracting or creating the strategy registry for component completion
Dispatching to the appropriate Layer 2 solver based on the detected mode

Arguments

ocp::CTModels.AbstractModel: The optimal control problem to solve
description::Symbol...: Symbolic description tokens (e.g., :collocation, :adnlp, :ipopt)
kwargs...: All keyword arguments. Action options (initial_guess/init, display) are extracted by the appropriate Layer 2 function. Explicit components (discretizer, modeler, solver) are identified by abstract type. A registry keyword can be provided to override the default strategy registry.

Returns

CTModels.AbstractSolution: Solution to the optimal control problem

Examples

# Descriptive mode (symbolic description)
solve(ocp, :collocation, :adnlp, :ipopt)

# With initial guess alias
solve(ocp, :collocation; init=x0, display=false)

# Explicit mode (typed components)
solve(ocp; discretizer=CTDirect.Collocation(),
           modeler=CTSolvers.ADNLP(), solver=CTSolvers.Ipopt())

Throws

CTBase.Exceptions.IncorrectArgument: If explicit components and symbolic description are mixed

Notes

This is the main entry point (Layer 1) of the solve architecture
Mode detection determines whether to use explicit or descriptive resolution path
The registry can be injected for testing or customization purposes
Action options and strategy-specific options are handled by Layer 2 functions

CommonSolve.solve — Method

solve(
    ocp::CTModels.OCP.AbstractModel,
    initial_guess::CTModels.Init.AbstractInitialGuess,
    discretizer::CTDirect.AbstractDiscretizer,
    modeler::CTSolvers.Modelers.AbstractNLPModeler,
    solver::CTSolvers.Solvers.AbstractNLPSolver;
    display
)

Resolve an optimal control problem using fully specified, concrete components (Layer 3).

This is the lowest-level execution layer for solving an optimal control problem. It expects all components (initial guess, discretizer, modeler, and solver) to be fully instantiated and normalized. It discretizes the problem and passes it to the underlying solve pipeline.

Arguments

ocp::CTModels.AbstractModel: The optimal control problem to solve
initial_guess::CTModels.AbstractInitialGuess: Normalized initial guess for the solution
discretizer::CTDirect.AbstractDiscretizer: Concrete discretization strategy
modeler::CTSolvers.AbstractNLPModeler: Concrete NLP modeling strategy
solver::CTSolvers.AbstractNLPSolver: Concrete NLP solver strategy
display::Bool: Whether to display the OCP configuration before solving

Returns

CTModels.AbstractSolution: The solution to the optimal control problem

Example

# Conceptual usage pattern for Layer 3 solve
ocp = Model(time=:final)
# ... define OCP ...
init = CTModels.build_initial_guess(ocp, nothing)
disc = CTDirect.Collocation(grid_size=100)
mod  = CTSolvers.ADNLP()
sol  = CTSolvers.Ipopt()

solution = solve(ocp, init, disc, mod, sol; display=true)

Notes

This is Layer 3 of the solve architecture - all inputs must be concrete, fully specified types
No defaults, no normalization, no component completion occurs at this level
The function performs: (1) optional configuration display, (2) problem discretization, (3) NLP solving
This function is typically called by higher-level solvers (solve_explicit, solve_descriptive)

CTModels.OCP.state — Function

state(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel, T<:CTModels.OCP.AbstractStateModel}
) -> CTModels.OCP.AbstractStateModel

Return the state struct.

state(
    sol::CTModels.OCP.Solution{<:CTModels.OCP.AbstractTimeGridModel, <:CTModels.OCP.AbstractTimesModel, <:CTModels.OCP.StateModelSolution{TS<:Function}}
) -> Function

Return the state as a function of time.

julia> x  = state(sol)
julia> t0 = time_grid(sol)[1]
julia> x0 = x(t0) # state at the initial time

state(init::CTModels.Init.AbstractInitialGuess) -> Any

Return the state trajectory from an initial guess.

state(sol::CTModels.OCP.AbstractSolution) -> Function

Return the state trajectory from a solution.

CTModels.OCP.state_components — Function

state_components(ocp::CTModels.OCP.Model) -> Vector{String}

Return the names of the components of the state.

state_components(
    sol::CTModels.OCP.Solution
) -> Vector{String}

Return the names of the components of the state.

CTModels.OCP.state_constraints_box — Function

state_constraints_box(
    model::CTModels.OCP.ConstraintsModel{<:Tuple, <:Tuple, TS}
) -> Any

Get the state box constraints from the model.

Arguments

model: The constraints model from which to retrieve the state box constraints.

Returns

The state box constraints.

Example

# Example of retrieving state box constraints
julia> model = ConstraintsModel(...)
julia> state_constraints = state_constraints_box(model)

state_constraints_box(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel, <:CTModels.OCP.AbstractStateModel, <:CTModels.OCP.AbstractControlModel, <:CTModels.OCP.AbstractVariableModel, <:Function, <:CTModels.OCP.AbstractObjectiveModel, <:CTModels.OCP.ConstraintsModel{<:Tuple, <:Tuple, TS<:Tuple}}
) -> Any

Return the box constraints on state.

CTModels.OCP.state_constraints_lb_dual — Function

state_constraints_lb_dual(
    model::CTModels.OCP.DualModel{<:Union{Nothing, Function}, <:Union{Nothing, AbstractVector{<:Real}}, SC_LB_Dual<:Union{Nothing, Function}}
) -> Union{Nothing, Function}

Return the dual function associated with the lower bounds of state constraints.

Arguments

model::DualModel: A model including dual variables for state lower bounds.

Returns

A function mapping time t to a vector of dual values, or nothing if not set.

state_constraints_lb_dual(
    sol::CTModels.OCP.Solution
) -> Union{Nothing, Function}

Return the lower bound dual of the state constraints.

CTModels.OCP.state_constraints_ub_dual — Function

state_constraints_ub_dual(
    model::CTModels.OCP.DualModel{<:Union{Nothing, Function}, <:Union{Nothing, AbstractVector{<:Real}}, <:Union{Nothing, Function}, SC_UB_Dual<:Union{Nothing, Function}}
) -> Union{Nothing, Function}

Return the dual function associated with the upper bounds of state constraints.

Arguments

model::DualModel: A model including dual variables for state upper bounds.

Returns

A function mapping time t to a vector of dual values, or nothing if not set.

state_constraints_ub_dual(
    sol::CTModels.OCP.Solution
) -> Union{Nothing, Function}

Return the upper bound dual of the state constraints.

CTModels.OCP.state_dimension — Function

state_dimension(ocp::CTModels.OCP.PreModel) -> Int64

Return the state dimension of the PreModel.

Throws Exceptions.PreconditionError if state has not been set.

state_dimension(ocp::CTModels.OCP.Model) -> Int64

Return the state dimension.

state_dimension(sol::CTModels.OCP.Solution) -> Int64

Return the dimension of the state.

CTModels.OCP.state_name — Function

state_name(ocp::CTModels.OCP.Model) -> String

Return the name of the state.

state_name(sol::CTModels.OCP.Solution) -> String

Return the name of the state.

CTModels.OCP.status — Function

status(sol::CTModels.OCP.Solution) -> Symbol

Return the status criterion (a Symbol).

Base.success — Function

success(command)

Run a command object, constructed with backticks (see the Running External Programs section in the manual), and tell whether it was successful (exited with a code of 0). An exception is raised if the process cannot be started.

CTModels.OCP.successful — Function

successful(sol::CTModels.OCP.Solution) -> Bool

Return the successful status.

Base.Libc.time — Function

time() -> Float64

Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution.