Public API

abstract type AbstractDualModel

Abstract base type for dual variable models in optimal control solutions.

Subtypes store Lagrange multipliers (dual variables) associated with constraints.

See also: DualModel.

abstract type AbstractModel

Abstract base type for optimal control problem models.

Subtypes represent either a fully built immutable model (Model) or a mutable model under construction (PreModel).

See also: Model, PreModel.

abstract type AbstractSolution

Abstract base type for optimal control problem solutions.

Subtypes store the complete solution including primal trajectories, dual variables, and solver information.

See also: Solution.

abstract type AbstractSolverInfos

Abstract base type for solver information associated with an optimal control solution.

Subtypes store metadata about the numerical solution process.

See also: SolverInfos.

abstract type AbstractTimeGridModel

Abstract base type for time grid models used in optimal control solutions.

Subtypes store the discretised time points at which the solution is evaluated.

See also: TimeGridModel, EmptyTimeGridModel.

abstract type AbstractTimeModel

Abstract base type for time boundary models (initial or final time).

Subtypes represent either fixed or free time boundaries in an optimal control problem.

See also: FixedTimeModel, FreeTimeModel.

abstract type Autonomous <: CTModels.OCP.TimeDependence

Type tag indicating that the dynamics and other functions of an optimal control problem do not explicitly depend on time.

For autonomous systems, the dynamics have the form ẋ = f(x, u) rather than ẋ = f(t, x, u).

See also: TimeDependence, NonAutonomous.

struct BolzaObjectiveModel{TM<:Function, TL<:Function} <: CTModels.OCP.AbstractObjectiveModel

Objective model with both Mayer and Lagrange costs (Bolza form): g(x(t₀), x(tf), v) + ∫ f⁰(t, x, u, v) dt.

Fields

• mayer::TM: The Mayer cost function (x0, xf, v) -> g(x0, xf, v).
• lagrange::TL: The Lagrange integrand (t, x, u, v) -> f⁰(t, x, u, v).
• criterion::Symbol: Optimisation direction, either :min or :max.

Example

julia> using CTModels

julia> g = (x0, xf, v) -> xf[1]^2
julia> f0 = (t, x, u, v) -> u[1]^2
julia> obj = CTModels.BolzaObjectiveModel(g, f0, :min)

Type alias for a dictionary of constraints. This is used to store constraints before building the model.

julia> const TimesDisc = Union{Times, StepRangeLen}

See also: ConstraintsModel, PreModel and Model.

struct ConstraintsModel{TP<:Tuple, TB<:Tuple, TS<:Tuple, TC<:Tuple, TV<:Tuple} <: CTModels.OCP.AbstractConstraintsModel

Container for all constraints in an optimal control problem.

Fields

• path_nl::TP: Tuple of nonlinear path constraints (t, x, u, v) -> c(t, x, u, v).
• boundary_nl::TB: Tuple of nonlinear boundary constraints (x0, xf, v) -> b(x0, xf, v).
• state_box::TS: Tuple of box constraints on state variables (lower/upper bounds).
• control_box::TC: Tuple of box constraints on control variables (lower/upper bounds).
• variable_box::TV: Tuple of box constraints on optimisation variables (lower/upper bounds).

Example

julia> using CTModels

julia> # Typically constructed internally by the model builder
julia> cm = CTModels.ConstraintsModel((), (), (), (), ())

struct ControlModel <: CTModels.OCP.AbstractControlModel

Control model describing the structure of the control variable in an optimal control problem definition.

Fields

• name::String: Display name for the control variable (e.g., "u").
• components::Vector{String}: Names of individual control components (e.g., ["u₁", "u₂"]).

Example

julia> using CTModels

julia> cm = CTModels.ControlModel("u", ["thrust", "steering"])

Type alias for a dimension. This is used to define the dimension of the state space, the costate space, the control space, etc.

julia> const Dimension = Integer

struct DualModel{PC_Dual<:Union{Nothing, Function}, BC_Dual<:Union{Nothing, AbstractVector{<:Real}}, SC_LB_Dual<:Union{Nothing, Function}, SC_UB_Dual<:Union{Nothing, Function}, CC_LB_Dual<:Union{Nothing, Function}, CC_UB_Dual<:Union{Nothing, Function}, VC_LB_Dual<:Union{Nothing, AbstractVector{<:Real}}, VC_UB_Dual<:Union{Nothing, AbstractVector{<:Real}}} <: CTModels.OCP.AbstractDualModel

Dual variables (Lagrange multipliers) for all constraints in an optimal control solution.

Fields

• path_constraints_dual::PC_Dual: Multipliers for path constraints t -> μ(t), or nothing.
• boundary_constraints_dual::BC_Dual: Multipliers for boundary constraints (vector), or nothing.
• state_constraints_lb_dual::SC_LB_Dual: Multipliers for state lower bounds t -> ν⁻(t), or nothing.
• state_constraints_ub_dual::SC_UB_Dual: Multipliers for state upper bounds t -> ν⁺(t), or nothing.
• control_constraints_lb_dual::CC_LB_Dual: Multipliers for control lower bounds t -> ω⁻(t), or nothing.
• control_constraints_ub_dual::CC_UB_Dual: Multipliers for control upper bounds t -> ω⁺(t), or nothing.
• variable_constraints_lb_dual::VC_LB_Dual: Multipliers for variable lower bounds (vector), or nothing.
• variable_constraints_ub_dual::VC_UB_Dual: Multipliers for variable upper bounds (vector), or nothing.

Example

julia> using CTModels

julia> # Typically constructed internally by the solver
julia> dm = CTModels.DualModel(nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing)

struct EmptyControlModel <: CTModels.OCP.AbstractControlModel

Sentinel type representing the absence of a control input in an optimal control problem.

Used when the problem has no control variable (control dimension 0). An EmptyControlModel is the default value of the control field in PreModel: it is automatically substituted when the user does not call control! before build.

The methods name, components, and dimension are defined for this type and return "", String[], and 0 respectively.

Example

julia> using CTModels

julia> pre = CTModels.PreModel()
julia> CTModels.OCP.__is_control_set(pre)  # false — still EmptyControlModel
false

julia> CTModels.OCP.control_dimension(pre)  # 0
0

See also: ControlModel, PreModel, build.

struct EmptyTimeGridModel <: CTModels.OCP.AbstractTimeGridModel

Sentinel type representing an empty or uninitialised time grid.

Used when a solution does not yet have an associated time discretisation.

Example

julia> using CTModels

julia> etg = CTModels.EmptyTimeGridModel()

struct EmptyVariableModel <: CTModels.OCP.AbstractVariableModel

Sentinel type representing the absence of optimisation variables in an optimal control problem.

Used when the problem has no free parameters or free final time.

Example

julia> using CTModels

julia> evm = CTModels.EmptyVariableModel()

struct FixedTimeModel{T<:Real} <: CTModels.OCP.AbstractTimeModel

Time model representing a fixed (known) time boundary.

Fields

• time::T: The fixed time value.
• name::String: Display name for this time (e.g., "t₀" or "tf").

Example

julia> using CTModels

julia> t0 = CTModels.FixedTimeModel(0.0, "t₀")
julia> t0.time
0.0

struct FreeTimeModel <: CTModels.OCP.AbstractTimeModel

Time model representing a free (optimised) time boundary.

The actual time value is stored in the optimisation variable at the given index.

Fields

• index::Int: Index into the optimisation variable where this time is stored.
• name::String: Display name for this time (e.g., "tf").

Example

julia> using CTModels

julia> tf = CTModels.FreeTimeModel(1, "tf")
julia> tf.index
1

struct LagrangeObjectiveModel{TL<:Function} <: CTModels.OCP.AbstractObjectiveModel

Objective model with only a Lagrange (integral) cost: ∫ f⁰(t, x, u, v) dt.

Fields

• lagrange::TL: The Lagrange integrand (t, x, u, v) -> f⁰(t, x, u, v).
• criterion::Symbol: Optimisation direction, either :min or :max.

Example

julia> using CTModels

julia> f0 = (t, x, u, v) -> u[1]^2
julia> obj = CTModels.LagrangeObjectiveModel(f0, :min)

struct MayerObjectiveModel{TM<:Function} <: CTModels.OCP.AbstractObjectiveModel

Objective model with only a Mayer (terminal) cost: g(x(t₀), x(tf), v).

Fields

• mayer::TM: The Mayer cost function (x0, xf, v) -> g(x0, xf, v).
• criterion::Symbol: Optimisation direction, either :min or :max.

Example

julia> using CTModels

julia> g = (x0, xf, v) -> xf[1]^2
julia> obj = CTModels.MayerObjectiveModel(g, :min)

struct Model{TD<:CTModels.OCP.TimeDependence, TimesModelType<:CTModels.OCP.AbstractTimesModel, StateModelType<:CTModels.OCP.AbstractStateModel, ControlModelType<:CTModels.OCP.AbstractControlModel, VariableModelType<:CTModels.OCP.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.OCP.AbstractObjectiveModel, ConstraintsModelType<:CTModels.OCP.AbstractConstraintsModel, BuildExaModelType<:Union{Nothing, Function}} <: CTModels.OCP.AbstractModel

Immutable optimal control problem model containing all problem components.

A Model is created from a PreModel once all required fields have been set. It is parameterised by the time dependence type (Autonomous or NonAutonomous) and the types of all its components.

Fields

• times::TimesModelType: Initial and final time specification.
• state::StateModelType: State variable structure (name, components).
• control::ControlModelType: Control variable structure (name, components).
• variable::VariableModelType: Optimisation variable structure (may be empty).
• dynamics::DynamicsModelType: System dynamics function (t, x, u, v) -> ẋ.
• objective::ObjectiveModelType: Cost functional (Mayer, Lagrange, or Bolza).
• constraints::ConstraintsModelType: All problem constraints.
• definition::Expr: Original symbolic definition of the problem.
• build_examodel::BuildExaModelType: Optional ExaModels builder function.

Example

julia> using CTModels

julia> # Models are typically created via the @def macro or PreModel
julia> ocp = CTModels.Model  # Type reference

struct MultipleTimeGridModel <: CTModels.OCP.AbstractTimeGridModel

Multiple time grid model storing different time grids for each solution component.

Used when variables have different discretisations (e.g., different grid densities for state vs control).

Fields

• grids::NamedTuple: Named tuple with time grids for each component:
  • state::TimesDisc: Time grid for state and state box constraint duals
  • control::TimesDisc: Time grid for control and control box constraint duals
  • costate::TimesDisc: Time grid for costate
  • path::TimesDisc: Time grid for path constraints and their duals

Example

julia> using CTModels

julia> T_state = LinRange(0, 1, 101)
julia> T_control = LinRange(0, 1, 51)
julia> T_costate = LinRange(0, 1, 76)
julia> tg = CTModels.MultipleTimeGridModel(
    state=T_state, control=T_control, costate=T_costate, path=T_state
)
julia> length(tg.grids.state)
101

abstract type NonAutonomous <: CTModels.OCP.TimeDependence

Type tag indicating that the dynamics and other functions of an optimal control problem explicitly depend on time.

For non-autonomous systems, the dynamics have the form ẋ = f(t, x, u).

See also: TimeDependence, Autonomous.

mutable struct PreModel <: CTModels.OCP.AbstractModel

Mutable optimal control problem model under construction.

A PreModel is used to incrementally define an optimal control problem before building it into an immutable Model. Fields can be set in any order and the model is validated before building.

Fields

• times::Union{AbstractTimesModel,Nothing}: Initial and final time specification.
• state::Union{AbstractStateModel,Nothing}: State variable structure.
• control::AbstractControlModel: Control variable structure (defaults to EmptyControlModel(), i.e. no control).
• variable::AbstractVariableModel: Optimisation variable (defaults to empty).
• dynamics::Union{Function,Vector,Nothing}: System dynamics (function or component-wise).
• objective::Union{AbstractObjectiveModel,Nothing}: Cost functional.
• constraints::ConstraintsDictType: Dictionary of constraints being built.
• definition::Union{Expr,Nothing}: Symbolic definition expression.
• autonomous::Union{Bool,Nothing}: Whether the system is autonomous.

Example

julia> using CTModels

julia> pre = CTModels.PreModel()
julia> # Set fields incrementally...

struct Solution{TimeGridModelType<:CTModels.OCP.AbstractTimeGridModel, TimesModelType<:CTModels.OCP.AbstractTimesModel, StateModelType<:CTModels.OCP.AbstractStateModel, ControlModelType<:CTModels.OCP.AbstractControlModel, VariableModelType<:CTModels.OCP.AbstractVariableModel, ModelType<:CTModels.OCP.AbstractModel, CostateModelType<:Function, ObjectiveValueType<:Real, DualModelType<:CTModels.OCP.AbstractDualModel, SolverInfosType<:CTModels.OCP.AbstractSolverInfos} <: CTModels.OCP.AbstractSolution

Complete solution of an optimal control problem.

Stores the optimal state, control, and costate trajectories, the optimisation variable value, objective value, dual variables, and solver information.

Fields

• time_grid::TimeGridModelType: Discretised time points.
• times::TimesModelType: Initial and final time specification.
• state::StateModelType: State trajectory t -> x(t) with metadata.
• control::ControlModelType: Control trajectory t -> u(t) with metadata.
• variable::VariableModelType: Optimisation variable value with metadata.
• model::ModelType: Reference to the optimal control problem model.
• costate::CostateModelType: Costate (adjoint) trajectory t -> p(t).
• objective::ObjectiveValueType: Optimal objective value.
• dual::DualModelType: Dual variables for all constraints.
• solver_infos::SolverInfosType: Solver statistics and status.

Example

julia> using CTModels

julia> # Solutions are typically returned by solvers
julia> sol = solve(ocp, ...)  # Returns a Solution
julia> CTModels.objective(sol)

struct SolverInfos{V, TI<:Dict{Symbol, V}} <: CTModels.OCP.AbstractSolverInfos

Solver information and statistics from the numerical solution process.

Fields

• iterations::Int: Number of iterations performed by the solver.
• status::Symbol: Termination status (e.g., :first_order, :max_iter).
• message::String: Human-readable message describing the termination status.
• successful::Bool: Whether the solver converged successfully.
• constraints_violation::Float64: Maximum constraint violation at the solution.
• infos::TI: Dictionary of additional solver-specific information.

Example

julia> using CTModels

julia> si = CTModels.SolverInfos(100, :first_order, "Converged", true, 1e-8, Dict{Symbol,Any}())
julia> si.successful
true

struct StateModel <: CTModels.OCP.AbstractStateModel

State model describing the structure of the state variable in an optimal control problem definition.

Fields

• name::String: Display name for the state variable (e.g., "x").
• components::Vector{String}: Names of individual state components (e.g., ["x₁", "x₂"]).

Example

julia> using CTModels

julia> sm = CTModels.StateModel("x", ["position", "velocity"])

Type alias for a time.

julia> const Time = ctNumber

See also: ctNumber, Times, TimesDisc.

Type alias for a vector of times.

julia> const Times = AbstractVector{<:Time}

See also: Time, TimesDisc.

Type alias for a grid of times. This is used to define a discretization of time interval given to solvers.

julia> const TimesDisc = Union{Times, StepRangeLen}

See also: Time, Times.

struct TimesModel{TI<:CTModels.OCP.AbstractTimeModel, TF<:CTModels.OCP.AbstractTimeModel} <: CTModels.OCP.AbstractTimesModel

Combined model for initial and final times in an optimal control problem.

Fields

• initial::TI: The initial time model (fixed or free).
• final::TF: The final time model (fixed or free).
• time_name::String: Display name for the time variable (e.g., "t").

Example

julia> using CTModels

julia> t0 = CTModels.FixedTimeModel(0.0, "t₀")
julia> tf = CTModels.FixedTimeModel(1.0, "tf")
julia> times = CTModels.TimesModel(t0, tf, "t")

struct UnifiedTimeGridModel{T<:Union{StepRangeLen, AbstractVector{<:Real}}} <: CTModels.OCP.AbstractTimeGridModel

Unified time grid model storing a single discretised time grid for all solution components.

Used when all variables (state, control, costate, duals) share the same time grid.

Fields

• value::T: Vector or range of time points (e.g., LinRange(0, 1, 100)).

Example

julia> using CTModels

julia> tg = CTModels.UnifiedTimeGridModel(LinRange(0, 1, 101))
julia> length(tg.value)
101

struct VariableModel <: CTModels.OCP.AbstractVariableModel

Variable model describing the structure of the optimisation variable in an optimal control problem definition.

Fields

• name::String: Display name for the variable (e.g., "v").
• components::Vector{String}: Names of individual variable components (e.g., ["tf", "λ"]).

Example

julia> using CTModels

julia> vm = CTModels.VariableModel("v", ["final_time", "parameter"])

clean_component_symbols(
    description
) -> Tuple{Vararg{Symbol}}

Clean and standardize component symbols for time grid access.

Behavior

• Maps all component symbols to their canonical time grid: :state, :control, :costate, or :path.
• :costate, :costates map to :costate (costate has its own grid).
• :dual, :duals, :constraint, :constraints, :cons map to :path.
• :state_box_constraint(s) maps to :state.
• :control_box_constraint(s) maps to :control.
• Removes duplicate symbols.

Arguments

• description: A tuple of symbols passed by the user, typically from time grid access.

Returns

• A cleaned Tuple{Symbol...} of unique, standardized symbols.

Example

julia> clean_component_symbols((:states, :controls, :costate, :constraint, :duals))
# → (:state, :control, :costate, :path)

Type alias for a real number.

julia> const ctNumber = Real

Type alias for a vector of real numbers.

julia> const ctVector = AbstractVector{<:ctNumber}

See also: ctNumber.

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

Check if the time grid is empty from the solution.

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.

time_grid_model(
    sol::CTModels.OCP.Solution
) -> CTModels.OCP.AbstractTimeGridModel

Get the time grid model from a solution.

Returns

• AbstractTimeGridModel: The time grid model (UnifiedTimeGridModel or MultipleTimeGridModel)