Modelling

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

julia

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

CTParser.@init Macro

julia

@init ocp begin
    ...
end

Build an initial guess object for an optimal control problem from a small initialisation DSL.

The block following @init is interpreted as a collection of assignment rules for the state, control and variable components of an optimal control problem, using a compact syntax of the form

julia

q(t) := sin(t)     # time-dependent function
x(T) := X          # time grid and associated samples
u := 0.1           # constant value
a = 1.0           # ordinary Julia alias (not part of the initial guess)
v(t) := a         # time-dependent function using the alias above

The macro itself only rewrites this DSL into a NamedTuple-based representation. All dimensional checks, interpretation of aliases and construction of the concrete initial guess object are delegated to the backend selected by init_prefix (by défaut :CTModels), via build_initial_guess and validate_initial_guess.

An optional keyword-like trailing argument controls logging:

julia

ig = @init ocp begin
    u(t) := t
end log = true

When log = true, the macro additionally prints a human-readable NamedTuple-like representation of the specification.

Arguments

ocp: symbolic optimal control problem built with @def.
begin ... end: block containing the initialisation DSL.
log: optional Boolean keyword (default false) enabling textual logging of the parsed specification.

Returns

AbstractInitialGuess: backend-specific initial guess object produced by the current backend (par défaut CTModels).

Example

julia

julia> using CTParser

julia> ocp = @def begin
           t ∈ [0, 1], time
           x ∈ R, state
           u ∈ R, control
           ẋ(t) == u(t)
           x(0) == 0
           x(1) == 0
           ∫(0.5u(t)^2) → min
       end

julia> ig = @init ocp begin
           u(t) := t
       end

julia> ig isa CTModels.AbstractInitialGuess
true

CTModels.Building.time! Function

julia

time!(
    ocp::CTModels.Building.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.

Note

You must use time! only once to set either the initial or the final time, or both.

Arguments

ocp::PreModel: The optimal control problem model.
t0::Union{Time,Nothing} (keyword): The initial time (fixed). Must not be provided with ind0.
tf::Union{Time,Nothing} (keyword): The final time (fixed). Must not be provided with indf.
ind0::Union{Int,Nothing} (keyword): The variable index for free initial time. Must not be provided with t0.
indf::Union{Int,Nothing} (keyword): The variable index for free final time. Must not be provided with tf.
time_name::Union{String,Symbol} (keyword): The name of the time variable (default: "t").

Examples

time! may be used only once per problem; each form below applies to a fresh ocp:

julia

julia> using CTModels

julia> ocp = CTModels.PreModel(); CTModels.variable!(ocp, 0); CTModels.time!(ocp; t0=0, tf=1)   # Fixed t0 and fixed tf

julia> ocp = CTModels.PreModel(); CTModels.variable!(ocp, 2); CTModels.time!(ocp; t0=0, indf=2) # Fixed t0 and free  tf

julia> ocp = CTModels.PreModel(); CTModels.variable!(ocp, 2); CTModels.time!(ocp; ind0=1, tf=1) # Free  t0 and fixed tf

When a solution is plotted, the name of the time variable appears ("t" by default). To name the time variable "s":

julia

julia> ocp = CTModels.PreModel(); CTModels.variable!(ocp, 0); CTModels.time!(ocp; t0=0, tf=1, time_name="s") # time_name as a String

julia> ocp = CTModels.PreModel(); CTModels.variable!(ocp, 0); CTModels.time!(ocp; t0=0, tf=1, time_name=:s)  # time_name as 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)

Returns

Nothing

CTModels.Building.state! Function

julia

state!(ocp::CTModels.Building.PreModel, n::Int64)
state!(
    ocp::CTModels.Building.PreModel,
    n::Int64,
    name::Union{String, Symbol}
)
state!(
    ocp::CTModels.Building.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.

Note

You must use state! only once to set the state dimension.

Arguments

ocp::PreModel: The optimal control problem model.
n::Dimension: The state dimension (number of state components).
name::Union{String,Symbol} (optional): The name of the state variable (default: "x").
components_names::Vector{<:Union{String,Symbol}} (optional): Names of the state components (default: automatically generated).

Examples

Each call below starts from a fresh PreModel (state! may be used only once per problem). The forms illustrate the default name, a custom name, and explicit component names:

julia

julia> using CTModels

julia> ocp = CTModels.PreModel(); CTModels.state!(ocp, 1);

julia> CTModels.state_dimension(ocp), CTModels.state_components(ocp)
(1, ["x"])

julia> ocp = CTModels.PreModel(); CTModels.state!(ocp, 2);

julia> CTModels.state_dimension(ocp), CTModels.state_components(ocp)
(2, ["x₁", "x₂"])

julia> ocp = CTModels.PreModel(); CTModels.state!(ocp, 2, "y");

julia> CTModels.state_dimension(ocp), CTModels.state_components(ocp)
(2, ["y₁", "y₂"])

julia> ocp = CTModels.PreModel(); CTModels.state!(ocp, 2, "y", ["u", "v"]);

julia> CTModels.state_dimension(ocp), CTModels.state_components(ocp)
(2, ["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

Returns

Nothing

CTModels.Building.control! Function

julia

control!(ocp::CTModels.Building.PreModel, m::Int64)
control!(
    ocp::CTModels.Building.PreModel,
    m::Int64,
    name::Union{String, Symbol}
)
control!(
    ocp::CTModels.Building.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.

Note

This function should be called only once per model. Calling it again will raise an error.

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

julia> using CTModels

julia> ocp = CTModels.PreModel(); CTModels.control!(ocp, 1);

julia> CTModels.control_dimension(ocp), CTModels.control_components(ocp)
(1, ["u"])

julia> ocp = CTModels.PreModel(); CTModels.control!(ocp, 1, "v");

julia> CTModels.control_components(ocp)
["v"]

julia> ocp = CTModels.PreModel(); CTModels.control!(ocp, 2);

julia> CTModels.control_components(ocp)
["u₁", "u₂"]

julia> ocp = CTModels.PreModel(); CTModels.control!(ocp, 2, "v", ["a", "b"]);

julia> CTModels.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

Returns

Nothing

CTModels.Building.variable! Function

julia

variable!(ocp::CTModels.Building.PreModel, q::Int64)
variable!(
    ocp::CTModels.Building.PreModel,
    q::Int64,
    name::Union{String, Symbol}
)
variable!(
    ocp::CTModels.Building.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.

Note

You can call variable! only once. It must be called before setting the objective or dynamics.

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

julia> using CTModels

julia> ocp = CTModels.PreModel(); CTModels.variable!(ocp, 1, "v");

julia> ocp = CTModels.PreModel(); CTModels.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)

Returns

Nothing

CTModels.Building.dynamics! Function

julia

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

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

The dynamics have the signature f!(r, t, x, u, v) where r is the output buffer (filled in-place), t is the time, x the state, u the control (or nothing for control-free problems), and v the optimisation variable.

Arguments

ocp::PreModel: The optimal control problem being defined.
f::Function: In-place function f!(r, t, x, u, v) defining the complete dynamics.

Returns

Nothing

Throws

Exceptions.PreconditionError: If state has not been set yet.
Exceptions.PreconditionError: If times have not been set yet.
Exceptions.PreconditionError: If dynamics have already been set.

julia

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

Add a partial dynamics function for a range of state indices in ocp.

The partial right-hand side fills r[1:length(rg)] (local buffer view). Ranges must tile 1:n without overlap; completeness is verified by CTModels.Building.build via CTModels.Building.__is_dynamics_complete.

Arguments

ocp::PreModel: The optimal control problem being defined.
rg::AbstractRange{<:Int}: State index range covered by f.
f::Function: In-place function f!(r, t, x, u, v) updating r[1:length(rg)].

Returns

Nothing

Throws

Exceptions.PreconditionError: If state or times have not been set yet.
Exceptions.PreconditionError: If complete dynamics have already been set.
Exceptions.PreconditionError: If rg overlaps with an existing dynamics range.
Exceptions.IncorrectArgument: If any index in rg is out of bounds.

julia

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

Convenience wrapper: add partial dynamics for a single state index i.

Equivalent to CTModels.Building.dynamics!(ocp, i:i, f).

Arguments

ocp::PreModel: The optimal control problem being defined.
i::Integer: State index covered by f.
f::Function: In-place function f!(r, t, x, u, v) updating r[1].

Returns

Nothing

Throws

Exceptions.PreconditionError: If state, times, or dynamics preconditions are violated.
Exceptions.IncorrectArgument: If i is out of bounds.

See also: CTModels.Building.dynamics! (range-based version).

CTModels.Building.objective! Function

julia

objective!(ocp::CTModels.Building.PreModel; ...)
objective!(
    ocp::CTModels.Building.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.

Note

The state and times must be set before the objective.
Control is optional: problems without control input (dimension 0) are fully supported.
The objective must not be set before.
At least one of the two functions must be given. Please provide a Mayer or a Lagrange function.

Examples

julia

julia> using CTModels

julia> ocp = CTModels.PreModel()

julia> CTModels.state!(ocp, 1); CTModels.control!(ocp, 1); CTModels.variable!(ocp, 1); CTModels.time!(ocp; t0=0, tf=1);

julia> mayer(x0, xf, v)    = x0[1] + xf[1] + v[1]
julia> lagrange(t, x, u, v) = x[1]  + u[1]  + v[1]

julia> CTModels.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

Returns

Nothing

CTModels.Building.constraint! Function

julia

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

Add a constraint to a pre-model. See CTModels.Building.__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.

Examples

julia

julia> using CTModels

julia> ocp = CTModels.PreModel(); CTModels.variable!(ocp, 0); CTModels.time!(ocp; t0=0, tf=1);

julia> CTModels.state!(ocp, 2); CTModels.control!(ocp, 2);

julia> CTModels.constraint!(ocp, :control; rg=1:2, lb=[-1.0, -1.0], ub=[1.0, 1.0], label=:u_box);

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

Returns

Nothing

Note

Control is only required for type == :control constraints. All other types (:state, :boundary, :path, :variable) are valid even when no control is defined (control dimension 0).

CTModels.Building.time_dependence! Function

julia

time_dependence!(
    ocp::CTModels.Building.PreModel;
    autonomous
)

Set the time dependence of the optimal control problem ocp.

Must be called exactly once, after declaring the spaces and dynamics but before calling CTModels.Building.build.

Arguments

ocp::PreModel: The optimal control problem being defined.
autonomous::Bool: true for an autonomous system , false for a non-autonomous system .

Returns

Nothing

Throws

Exceptions.PreconditionError: If time dependence has already been set.

Examples

julia

julia> using CTModels

julia> ocp = CTModels.PreModel(); CTModels.time_dependence!(ocp; autonomous=true);

CTModels.Building.build Function

julia

build(
    constraints::OrderedCollections.OrderedDict{Symbol, Tuple{Symbol, Union{Function, OrdinalRange{<:Int64}}, AbstractVector{<:Real}, AbstractVector{<:Real}}}
) -> CTModels.Components.ConstraintsModel{TP, TB, Tuple{Vector{Float64}, Vector{Int64}, Vector{Float64}, Vector{Symbol}, Vector{Vector{Symbol}}}, Tuple{Vector{Float64}, Vector{Int64}, Vector{Float64}, Vector{Symbol}, Vector{Vector{Symbol}}}, Tuple{Vector{Float64}, Vector{Int64}, Vector{Float64}, Vector{Symbol}, Vector{Vector{Symbol}}}} where {TP<:Tuple{Vector{Float64}, Function, Vector{Float64}, Vector{Symbol}}, TB<:Tuple{Vector{Float64}, Function, Vector{Float64}, Vector{Symbol}}}

Constructs a CTModels.Components.ConstraintsModel from a dictionary of constraints.

This function processes a dictionary where each entry defines a constraint with its type, function or index range, lower and upper bounds, and label. It categorizes constraints into path, boundary, state, control, and variable constraints, assembling them into a structured CTModels.Components.ConstraintsModel.

Arguments

constraints::CTModels.Components.ConstraintsDictType: A dictionary mapping constraint labels to tuples of the form (type, function_or_range, lower_bound, upper_bound).

Returns

CTModels.Components.ConstraintsModel: A structured model encapsulating all provided constraints.

Example

julia

using CTModels.Building
using OrderedCollections

f1(t, x, u, v) = x[1]
constraints = OrderedDict(
    :c1 => (:path, f1, [0.0], [1.0]),
    :c2 => (:state, 1:2, [-1.0, -1.0], [1.0, 1.0])
)
model = build(constraints)

Throws

CTBase.Exceptions.IncorrectArgument: If an unknown constraint type is encountered

julia

build(
    pre_ocp::CTModels.Building.PreModel;
    build_examodel
) -> CTModels.Models.Model{TD, var"#s179", var"#s1791", var"#s1792", var"#s1793", var"#s1794", var"#s1795", CTModels.Components.ConstraintsModel{TP, TB, Tuple{Vector{Float64}, Vector{Int64}, Vector{Float64}, Vector{Symbol}, Vector{Vector{Symbol}}}, Tuple{Vector{Float64}, Vector{Int64}, Vector{Float64}, Vector{Symbol}, Vector{Vector{Symbol}}}, Tuple{Vector{Float64}, Vector{Int64}, Vector{Float64}, Vector{Symbol}, Vector{Vector{Symbol}}}}, <:CTModels.Components.AbstractDefinition, Nothing} where {TD<:CTBase.Traits.TimeDependence, var"#s179"<:CTModels.Components.AbstractTimesModel, var"#s1791"<:CTModels.Components.AbstractStateModel, var"#s1792"<:CTModels.Components.AbstractControlModel, var"#s1793"<:CTModels.Components.AbstractVariableModel, var"#s1794"<:Function, var"#s1795"<:CTModels.Components.AbstractObjectiveModel, TP<:Tuple{Vector{Float64}, Function, Vector{Float64}, Vector{Symbol}}, TB<:Tuple{Vector{Float64}, Function, Vector{Float64}, Vector{Symbol}}}

Converts a mutable CTModels.Building.PreModel into an immutable CTModels.Models.Model.

This function finalizes a pre-defined optimal control problem (CTModels.Building.PreModel) by verifying that all necessary components (times, state, dynamics, objective) are set. It then constructs a CTModels.Models.Model instance, incorporating optional components like control, variable, and constraints.

Note

Control is optional: calling CTModels.Building.control! is not required. When omitted, the model is built with control_dimension == 0 (an CTModels.Components.EmptyControlModel). This is useful for problems where the dynamics depend only on the state, such as pure state-space systems.

Arguments

pre_ocp::CTModels.Building.PreModel: The pre-defined optimal control problem to be finalized.
build_examodel=nothing: Optional ExaModel builder function for GPU acceleration.

Returns

CTModels.Models.Model: A fully constructed model ready for solving.

Examples

Minimal Mayer problem (no control):

julia

using CTModels

pre = CTModels.PreModel()
CTModels.variable!(pre, 0)
CTModels.time!(pre; t0=0.0, tf=1.0)
CTModels.state!(pre, 2, "x", ["x1", "x2"])
CTModels.dynamics!(pre, (r, t, x, u, v) -> (r[1] = -x[2]; r[2] = x[1]; nothing))
CTModels.objective!(pre, :min; mayer=(x0, xf, v) -> xf[1]^2)
CTModels.time_dependence!(pre; autonomous=true)
model = CTModels.build(pre)
CTModels.control_dimension(model)  # 0

Bolza problem with control:

julia

using CTModels

pre = CTModels.PreModel()
CTModels.variable!(pre, 0)
CTModels.time!(pre; t0=0.0, tf=1.0)
CTModels.state!(pre, 2)
CTModels.control!(pre, 1)
CTModels.dynamics!(pre, (r, t, x, u, v) -> (r[1] = x[2]; r[2] = u[1]; nothing))
CTModels.objective!(pre, :min; lagrange=(t, x, u, v) -> u[1]^2)
CTModels.time_dependence!(pre; autonomous=true)
model = CTModels.build(pre)

Throws

CTBase.Exceptions.PreconditionError: If times, state, dynamics, objective, or time dependence are not set
CTBase.Exceptions.PreconditionError: If dynamics are incomplete

CTModels.Init.build_initial_guess Function

julia

build_initial_guess(
    ocp::CTModels.Models.AbstractModel,
    init_data
) -> CTModels.Init.AbstractInitialGuess

Build and validate an initial guess from various input formats.

Accepts multiple input types, converts them to an InitialGuess, and validates dimensions against the problem definition. This is the single entry point that guarantees a validated initial guess.

Supported input types:

nothing or (): Returns default initial guess.
AbstractInitialGuess: Validates and returns.
AbstractPreInitialGuess: Converts from pre-initialisation.
Solutions.AbstractSolution: Warm-starts from a previous solution.
NamedTuple: Parses named fields for state, control, and variable.

Arguments

ocp::Models.AbstractModel: The optimal control problem.
init_data: The initial guess data in one of the supported formats.

Returns

InitialGuess: A validated initial guess.

Throws

Exceptions.IncorrectArgument: If init_data has an unsupported type or if dimensions do not match the problem definition.

Example

julia

julia> using CTModels

julia> init = CTModels.build_initial_guess(ocp, (state=t -> [0.0], control=t -> [1.0]))

Modelling ​

Modelling