Public API

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.

constraint(
    model::CTModels.OCP.Model,
    label::Symbol
) -> Tuple{Symbol, Any, Any, Any}

Get a labelled constraint from the model. Returns a tuple of the form (type, f, lb, ub) where type is the type of the constraint, f is the function, lb is the lower bound and ub is the upper bound.

The function returns an exception if the label is not found in the model.

Arguments

• model: The model from which to retrieve the constraint.
• label: The label of the constraint to retrieve.

Returns

• Tuple: A tuple containing the type, function, lower bound, and upper bound of the constraint.

constraint!(
    ocp::CTModels.OCP.PreModel,
    type::Symbol;
    rg,
    f,
    lb,
    ub,
    label,
    codim_f
)

Add a constraint to a pre-model. See __constraint! for more details.

Arguments

• ocp: The pre-model to which the constraint will be added.
• type: The type of the constraint. It can be :state, :control, :variable, :boundary, or :path.
• rg: The range of the constraint. It can be an integer or a range of integers.
• f: The function that defines the constraint. It must return a vector of the same dimension as the constraint.
• lb: The lower bound of the constraint. It can be a number or a vector.
• ub: The upper bound of the constraint. It can be a number or a vector.
• label: The label of the constraint. It must be unique in the pre-model.

Example

# Example of adding a control constraint to a pre-model
julia> ocp = PreModel()
julia> constraint!(ocp, :control, rg=1:2, lb=[0.0], ub=[1.0], label=:control_constraint)

Throws

• Exceptions.PreconditionError: If state has not been set
• Exceptions.PreconditionError: If times has not been set
• Exceptions.PreconditionError: If control has not been set and type == :control
• Exceptions.PreconditionError: If variable has not been set (when type=:variable)
• Exceptions.PreconditionError: If constraint with same label already exists
• Exceptions.PreconditionError: If both lb and ub are nothing
• Exceptions.IncorrectArgument: If lb and ub have different lengths
• Exceptions.IncorrectArgument: If lb > ub element-wise
• Exceptions.IncorrectArgument: If dimensions don't match expected sizes

control!(ocp::CTModels.OCP.PreModel, m::Int64)
control!(
    ocp::CTModels.OCP.PreModel,
    m::Int64,
    name::Union{String, Symbol}
)
control!(
    ocp::CTModels.OCP.PreModel,
    m::Int64,
    name::Union{String, Symbol},
    components_names::Array{T2<:Union{String, Symbol}, 1}
)

Define the control input for a given optimal control problem model.

This function sets the control dimension and optionally allows specifying the control name and the names of its components.

Arguments

• ocp::PreModel: The model to which the control will be added.
• m::Dimension: The control input dimension (must be greater than 0).
• name::Union{String,Symbol} (optional): The name of the control variable (default: "u").
• components_names::Vector{<:Union{String,Symbol}} (optional): Names of the control components (default: automatically generated).

Examples

julia> control!(ocp, 1)
julia> control_dimension(ocp)
1
julia> control_components(ocp)
["u"]

julia> control!(ocp, 1, "v")
julia> control_components(ocp)
["v"]

julia> control!(ocp, 2)
julia> control_components(ocp)
["u₁", "u₂"]

julia> control!(ocp, 2, :v)
julia> control_components(ocp)
["v₁", "v₂"]

julia> control!(ocp, 2, "v", ["a", "b"])
julia> control_components(ocp)
["a", "b"]

Throws

• Exceptions.PreconditionError: If control has already been set
• Exceptions.IncorrectArgument: If m ≤ 0
• Exceptions.IncorrectArgument: If number of component names ≠ m
• Exceptions.IncorrectArgument: If name is empty
• Exceptions.IncorrectArgument: If any component name is empty
• Exceptions.IncorrectArgument: If name is one of the component names
• Exceptions.IncorrectArgument: If component names contain duplicates
• Exceptions.IncorrectArgument: If name conflicts with existing names in other components
• Exceptions.IncorrectArgument: If any component name conflicts with existing names

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.

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

dimension(model::CTModels.OCP.StateModel) -> Int64

Get the dimension of the state from the state model.

dimension(model::CTModels.OCP.StateModelSolution) -> Int64

Get the dimension of the state from the state model solution.

dimension(model::CTModels.OCP.ControlModel) -> Int64

Get the control input dimension.

Arguments

• model::ControlModel: The control model.

Returns

• Dimension: The number of control components.

dimension(model::CTModels.OCP.ControlModelSolution) -> Int64

Get the control input dimension from the solution.

Arguments

• model::ControlModelSolution: The control model solution.

Returns

• Dimension: The number of control components.

dimension(_::CTModels.OCP.EmptyControlModel) -> Int64

Return 0 since no control is defined.

dimension(model::CTModels.OCP.VariableModel) -> Int64

Return the dimension (number of components) of the variable.

dimension(
    model::CTModels.OCP.VariableModelSolution
) -> Int64

Return the number of components in the variable solution.

dimension(_::CTModels.OCP.EmptyVariableModel) -> Int64

Return 0 since no variable is defined.

dynamics!(ocp::CTModels.OCP.PreModel, f::Function)

Set the full dynamics of the optimal control problem ocp using the function f.

Arguments

• ocp::PreModel: The optimal control problem being defined.
• f::Function: A function that defines the complete system dynamics.

Preconditions

• The state and times must be set before calling this function.
• Control is optional: problems without control input (dimension 0) are supported.
• No dynamics must have been set previously.

Behavior

This function assigns f as the complete dynamics of the system. It throws an error if the state or times are not yet set, or if dynamics have already been set.

Errors

Throws Exceptions.PreconditionError if called out of order or in an invalid state.

dynamics!(
    ocp::CTModels.OCP.PreModel,
    rg::AbstractRange{<:Int64},
    f::Function
)

Add a partial dynamics function f to the optimal control problem ocp, applying to the subset of state indices specified by the range rg.

Arguments

• ocp::PreModel: The optimal control problem being defined.
• rg::AbstractRange{<:Int}: Range of state indices to which f applies.
• f::Function: A function describing the dynamics over the specified state indices.

Preconditions

• The state and times must be set before calling this function.
• Control is optional: problems without control input (dimension 0) are supported.
• The full dynamics must not yet be complete.
• No overlap is allowed between rg and existing dynamics index ranges.

Behavior

This function appends the tuple (rg, f) to the list of partial dynamics. It ensures that the specified indices are not already covered and that the system is in a valid configuration for adding partial dynamics.

Errors

Throws Exceptions.PreconditionError if:

• The state or times are not yet set.
• The dynamics are already defined completely.
• Any index in rg overlaps with an existing dynamics range.

Example

julia> dynamics!(ocp, 1:2, (out, t, x, u, v) -> out .= x[1:2] .+ u[1:2])
julia> dynamics!(ocp, 3:3, (out, t, x, u, v) -> out .= x[3] * v[1])

dynamics!(
    ocp::CTModels.OCP.PreModel,
    i::Integer,
    f::Function
)

Define partial dynamics for a single state variable index in an optimal control problem.

This is a convenience method for defining dynamics affecting only one element of the state vector. It wraps the scalar index i into a range i:i and delegates to the general partial dynamics method.

Arguments

• ocp::PreModel: The optimal control problem being defined.
• i::Integer: The index of the state variable to which the function f applies.
• f::Function: A function of the form (out, t, x, u, v) -> ..., which updates the scalar output out[1] in-place.

Behavior

This is equivalent to calling:

julia> dynamics!(ocp, i:i, f)

Errors

Throws the same errors as the range-based method if:

• The model is not properly initialized.
• The index i overlaps with existing dynamics.
• A full dynamics function is already defined.

Example

julia> dynamics!(ocp, 3, (out, t, x, u, v) -> out[1] = x[3]^2 + u[1])

has_fixed_initial_time(
    times::CTModels.OCP.TimesModel{<:CTModels.OCP.FixedTimeModel{T<:Real}}
) -> Bool

Check if the initial time is fixed. Return true.

has_fixed_initial_time(
    times::CTModels.OCP.TimesModel{CTModels.OCP.FreeTimeModel}
) -> Bool

Check if the initial time is free. Return false.

has_fixed_initial_time(ocp::CTModels.OCP.Model) -> Bool

Check if the initial time is fixed.

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

Check if the initial time is fixed.

has_lagrange_cost(
    _::CTModels.OCP.MayerObjectiveModel
) -> Bool

Return false.

has_lagrange_cost(
    _::CTModels.OCP.LagrangeObjectiveModel
) -> Bool

Return true.

has_lagrange_cost(
    _::CTModels.OCP.BolzaObjectiveModel
) -> Bool

Return true.

has_lagrange_cost(ocp::CTModels.OCP.Model) -> Bool

Check if the model has a Lagrange cost.

has_mayer_cost(_::CTModels.OCP.MayerObjectiveModel) -> Bool

Return true.

has_mayer_cost(
    _::CTModels.OCP.LagrangeObjectiveModel
) -> Bool

Return false.

has_mayer_cost(_::CTModels.OCP.BolzaObjectiveModel) -> Bool

Return true.

has_mayer_cost(ocp::CTModels.OCP.Model) -> Bool

Check if the model has a Mayer cost.

index(model::CTModels.OCP.FreeTimeModel) -> Int64

Get the index of the time variable from the free time model.

initial_time(
    model::CTModels.OCP.TimesModel{<:CTModels.OCP.FixedTimeModel{T<:Real}}
) -> Real

Get the initial time from the times model, from a fixed initial time model.

initial_time(
    model::CTModels.OCP.TimesModel{CTModels.OCP.FreeTimeModel},
    variable::AbstractArray{T<:Real, 1}
) -> Any

Get the initial time from the times model, from a free initial time model.

initial_time(ocp::CTModels.OCP.AbstractModel) -> Any

Throw an error for unsupported initial time access.

initial_time(
    ocp::CTModels.OCP.AbstractModel,
    variable::AbstractVector
) -> Any

Throw an error for unsupported initial time access with variable.

initial_time(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel{CTModels.OCP.FixedTimeModel{T<:Real}}}
) -> Any

Return the initial time, for a fixed initial time.

initial_time(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel{CTModels.OCP.FreeTimeModel}},
    variable::AbstractArray{T<:Real, 1}
) -> Any

Return the initial time, for a free initial time.

initial_time(
    ocp::CTModels.OCP.Model{<:CTModels.OCP.TimeDependence, <:CTModels.OCP.TimesModel{CTModels.OCP.FreeTimeModel}},
    variable::Real
) -> Real

Return the initial time, for a free initial time.

initial_time(sol::CTModels.OCP.Solution) -> Real

Return the initial time of the solution.

Alias for has_fixed_final_time. Check if the final time is fixed.

Example

julia> is_final_time_fixed(times)  # equivalent to has_fixed_final_time(times)

See also: has_fixed_final_time, is_final_time_free.

Alias for has_free_final_time. Check if the final time is free.

Example

julia> is_final_time_free(times)  # equivalent to has_free_final_time(times)

See also: has_free_final_time, is_final_time_fixed.

Alias for has_fixed_initial_time. Check if the initial time is fixed.

Example

julia> is_initial_time_fixed(times)  # equivalent to has_fixed_initial_time(times)

See also: has_fixed_initial_time, is_initial_time_free.

Alias for has_free_initial_time. Check if the initial time is free.

Example

julia> is_initial_time_free(times)  # equivalent to has_free_initial_time(times)

See also: has_free_initial_time, is_initial_time_fixed.

Alias for has_lagrange_cost. Check if the objective has a Lagrange (integral) cost defined.

Example

julia> is_lagrange_cost_defined(obj)  # equivalent to has_lagrange_cost(obj)

See also: has_lagrange_cost, is_mayer_cost_defined.

Alias for has_mayer_cost. Check if the objective has a Mayer (terminal) cost defined.

Example

julia> is_mayer_cost_defined(obj)  # equivalent to has_mayer_cost(obj)

See also: has_mayer_cost, is_lagrange_cost_defined.

name(model::CTModels.OCP.StateModel) -> String

Get the name of the state from the state model.

name(model::CTModels.OCP.StateModelSolution) -> String

Get the name of the state from the state model solution.

name(model::CTModels.OCP.ControlModel) -> String

Get the name of the control variable.

Arguments

• model::ControlModel: The control model.

Returns

• String: The name of the control.

Example

julia> name(controlmodel)
"u"

name(model::CTModels.OCP.ControlModelSolution) -> String

Get the name of the control variable from the solution.

Arguments

• model::ControlModelSolution: The control model solution.

Returns

• String: The name of the control.

name(_::CTModels.OCP.EmptyControlModel) -> String

Return an empty string, since no control is defined.

name(model::CTModels.OCP.VariableModel) -> String

Return the name of the variable stored in the model.

name(model::CTModels.OCP.VariableModelSolution) -> String

Return the name of the variable stored in the model solution.

name(_::CTModels.OCP.EmptyVariableModel) -> String

Return an empty string, since no variable is defined.

name(model::CTModels.OCP.FixedTimeModel) -> String

Get the name of the time from the fixed time model.

name(model::CTModels.OCP.FreeTimeModel) -> String

Get the name of the time from the free time model.

objective!(ocp::CTModels.OCP.PreModel; ...)
objective!(
    ocp::CTModels.OCP.PreModel,
    criterion::Symbol;
    mayer,
    lagrange
)

Set the objective of the optimal control problem.

Arguments

• ocp::PreModel: the optimal control problem.
• criterion::Symbol: the type of criterion. Either :min, :max, :MIN, or :MAX (case-insensitive). Default is :min.
• mayer::Union{Function, Nothing}: the Mayer function (inplace). Default is nothing.
• lagrange::Union{Function, Nothing}: the Lagrange function (inplace). Default is nothing.

Examples

julia> function mayer(x0, xf, v)
           return x0[1] + xf[1] + v[1]
       end
julia> function lagrange(t, x, u, v)
           return x[1] + u[1] + v[1]
       end
julia> objective!(ocp, :min, mayer=mayer, lagrange=lagrange)

Throws

• Exceptions.PreconditionError: If state has not been set
• Exceptions.PreconditionError: If times has not been set
• Exceptions.PreconditionError: If objective has already been set
• Exceptions.IncorrectArgument: If criterion is not :min, :max, :MIN, or :MAX
• Exceptions.IncorrectArgument: If neither mayer nor lagrange function is provided

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.

state!(ocp::CTModels.OCP.PreModel, n::Int64)
state!(
    ocp::CTModels.OCP.PreModel,
    n::Int64,
    name::Union{String, Symbol}
)
state!(
    ocp::CTModels.OCP.PreModel,
    n::Int64,
    name::Union{String, Symbol},
    components_names::Array{T2<:Union{String, Symbol}, 1}
)

Define the state dimension and possibly the names of each component.

Examples

julia> state!(ocp, 1)
julia> state_dimension(ocp)
1
julia> state_components(ocp)
["x"]

julia> state!(ocp, 1, "y")
julia> state_dimension(ocp)
1
julia> state_components(ocp)
["y"]

julia> state!(ocp, 2)
julia> state_dimension(ocp)
2
julia> state_components(ocp)
["x₁", "x₂"]

julia> state!(ocp, 2, :y)
julia> state_dimension(ocp)
2
julia> state_components(ocp)
["y₁", "y₂"]

julia> state!(ocp, 2, "y")
julia> state_dimension(ocp)
2
julia> state_components(ocp)
["y₁", "y₂"]

julia> state!(ocp, 2, "y", ["u", "v"])
julia> state_dimension(ocp)
2
julia> state_components(ocp)
["u", "v"]

julia> state!(ocp, 2, "y", [:u, :v])
julia> state_dimension(ocp)
2
julia> state_components(ocp)
["u", "v"]

Throws

• Exceptions.PreconditionError: If state has already been set
• Exceptions.IncorrectArgument: If n ≤ 0
• Exceptions.IncorrectArgument: If number of component names ≠ n
• Exceptions.IncorrectArgument: If name is empty
• Exceptions.IncorrectArgument: If any component name is empty
• Exceptions.IncorrectArgument: If name is one of the component names
• Exceptions.IncorrectArgument: If component names contain duplicates
• Exceptions.IncorrectArgument: If name conflicts with existing names in other components
• Exceptions.IncorrectArgument: If any component name conflicts with existing names

time() -> Float64

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

See also time_ns.

time(t::TmStruct) -> Float64

Converts a TmStruct struct to a number of seconds since the epoch.

time(model::CTModels.OCP.FixedTimeModel{T<:Real}) -> Real

Get the time from the fixed time model.

time(
    model::CTModels.OCP.FreeTimeModel,
    variable::AbstractArray{T<:Real, 1}
) -> Any

Get the time from the free time model.

Exceptions

• If the index of the time variable is not in [1, length(variable)], throw an error.

time!(
    ocp::CTModels.OCP.PreModel;
    t0,
    tf,
    ind0,
    indf,
    time_name
)

Set the initial and final times. We denote by t0 the initial time and tf the final time. The optimal control problem is denoted ocp. When a time is free, then, one must provide the corresponding index of the ocp variable.

Examples

julia> time!(ocp, t0=0,   tf=1  ) # Fixed t0 and fixed tf
julia> time!(ocp, t0=0,   indf=2) # Fixed t0 and free  tf
julia> time!(ocp, ind0=2, tf=1  ) # Free  t0 and fixed tf
julia> time!(ocp, ind0=2, indf=3) # Free  t0 and free  tf

When you plot a solution of an optimal control problem, the name of the time variable appears. By default, the name is "t". Consider you want to set the name of the time variable to "s".

julia> time!(ocp, t0=0, tf=1, time_name="s") # time_name is a String
# or
julia> time!(ocp, t0=0, tf=1, time_name=:s ) # time_name is a Symbol  

Throws

• Exceptions.PreconditionError: If time has already been set
• Exceptions.PreconditionError: If variable must be set before (when t0 or tf is free)
• Exceptions.IncorrectArgument: If ind0 or indf is out of bounds
• Exceptions.IncorrectArgument: If both t0 and ind0 are provided
• Exceptions.IncorrectArgument: If neither t0 nor ind0 is provided
• Exceptions.IncorrectArgument: If both tf and indf are provided
• Exceptions.IncorrectArgument: If neither tf nor indf is provided
• Exceptions.IncorrectArgument: If time_name is empty
• Exceptions.IncorrectArgument: If time_name conflicts with existing names
• Exceptions.IncorrectArgument: If t0 ≥ tf (when both are fixed)

variable!(ocp::CTModels.OCP.PreModel, q::Int64)
variable!(
    ocp::CTModels.OCP.PreModel,
    q::Int64,
    name::Union{String, Symbol}
)
variable!(
    ocp::CTModels.OCP.PreModel,
    q::Int64,
    name::Union{String, Symbol},
    components_names::Array{T2<:Union{String, Symbol}, 1}
)

Define a new variable in the optimal control problem ocp with dimension q.

This function registers a named variable (e.g. "state", "control", or other) to be used in the problem definition. You may optionally specify a name and individual component names.

Arguments

• ocp: The PreModel where the variable is registered.
• q: The dimension of the variable (number of components).
• name: A name for the variable (default: auto-generated from q).
• components_names: A vector of strings or symbols for each component (default: ["v₁", "v₂", ...]).

Examples

julia> variable!(ocp, 1, "v")
julia> variable!(ocp, 2, "v", ["v₁", "v₂"])

Throws

• Exceptions.PreconditionError: If variable has already been set
• Exceptions.PreconditionError: If objective has already been set
• Exceptions.PreconditionError: If dynamics has already been set
• Exceptions.IncorrectArgument: If number of component names ≠ q (when q > 0)
• Exceptions.IncorrectArgument: If name is empty (when q > 0)
• Exceptions.IncorrectArgument: If any component name is empty (when q > 0)
• Exceptions.IncorrectArgument: If name is one of the component names (when q > 0)
• Exceptions.IncorrectArgument: If component names contain duplicates (when q > 0)
• Exceptions.IncorrectArgument: If name conflicts with existing names in other components (when q > 0)
• Exceptions.IncorrectArgument: If any component name conflicts with existing names (when q > 0)

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

Get the variable box constraints from the model.

Arguments

• model: The constraints model from which to retrieve the variable box constraints.

Returns

• The variable box constraints.

Example

# Example of retrieving variable box constraints
julia> model = ConstraintsModel(...)
julia> variable_constraints = variable_constraints_box(model)

variable_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, <:Tuple, TV<:Tuple}}
) -> Any

Return the box constraints on variable.