Public API

This page lists exported symbols of CTModels.Building.

From `CTModels.Building`

`PreModel` [Struct]

CTModels.Building.PreModel — Type

mutable struct PreModel <: CTModels.Models.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 CTModels.Models.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::AbstractDefinition: Symbolic definition; defaults to CTModels.Components.EmptyDefinition and becomes a CTModels.Components.Definition when definition! is called with a real expression.
autonomous::Union{Bool,Nothing}: Whether the system is autonomous.

Example

julia> using CTModels

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

`append_box_constraints!` [Function]

CTModels.Building.append_box_constraints! — Function

append_box_constraints!(
    inds,
    lbs,
    ubs,
    labels,
    rg,
    lb,
    ub,
    label
)

Append box constraint data to the provided flat vectors.

This is an internal helper used by CTModels.Building.build. It simply accumulates declarations. Deduplication (one entry per component with intersection semantics) and associated warnings are handled later by CTModels.Building._dedup_box_constraints!.

Arguments

inds::Vector{Int}: Vector of component indices to append to.
lbs::Vector{<:Real}: Vector of lower bounds to append to.
ubs::Vector{<:Real}: Vector of upper bounds to append to.
labels::Vector{Symbol}: Vector of labels (one entry per declared component).
rg::AbstractVector{Int}: Component indices declared by the new constraint.
lb::AbstractVector{<:Real}: Lower bounds associated with rg.
ub::AbstractVector{<:Real}: Upper bounds associated with rg.
label::Symbol: Label describing the declaration.

Notes

Modifies inds, lbs, ubs, labels in-place.
No deduplication or warning emitted here; see CTModels.Building._dedup_box_constraints!.

Returns

Nothing

`build` [Function]

CTModels.Building.build — Function

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

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

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<:CTModels.Components.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.Models.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.

Example without control

using CTModels.Building

pre_ocp = PreModel()
times!(pre_ocp, 0.0, 1.0, 100)
state!(pre_ocp, 2, "x", ["x1", "x2"])
dynamics!(pre_ocp, (t, x, u) -> [-x[2], x[1]])
objective!(pre_ocp, :min, mayer=(x0, xf) -> xf[1]^2)
model = build(pre_ocp)
CTModels.Models.control_dimension(model)  # 0

Example with control

using CTModels.Building

pre_ocp = PreModel()
times!(pre_ocp, 0.0, 1.0, 100)
state!(pre_ocp, 2, "x", ["x1", "x2"])
control!(pre_ocp, 1, "u", ["u1"])
dynamics!(pre_ocp, (dx, t, x, u, v) -> dx .= x + u)
model = build(pre_ocp)

Throws

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

`build_model` [Function]

CTModels.Building.build_model — Function

build_model(
    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<:CTModels.Components.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}}}

Build a complete optimal control problem model from a pre-model.

This function is an alias for CTModels.Building.build and constructs a fully validated CTModels.Models.Model from a CTModels.Building.PreModel by extracting and organizing all components (times, state, control, variable, dynamics, objective, constraints).

Arguments

pre_ocp::CTModels.Building.PreModel: The pre-model containing all problem components
build_examodel=nothing: Optional ExaModel builder function for GPU acceleration

Returns

CTModels.Models.Model: A complete, validated optimal control problem model

Throws

CTBase.Exceptions.PreconditionError: If time dependence has not been set via CTModels.Building.time_dependence!

Example

using CTModels.Building

# Create and configure a pre-model
pre_ocp = PreModel()
time_dependence!(pre_ocp, autonomous=true)
state!(pre_ocp, 2)
control!(pre_ocp, 1)
dynamics!(pre_ocp, (x, u) -> [x[2], u[1]])
objective!(pre_ocp, :mayer, (x0, xf) -> xf[1]^2)

# Build the model
ocp = build_model(pre_ocp)

`constraint!` [Function]

CTModels.Building.constraint! — Function

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.

Example

julia> using CTModels

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

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

`control!` [Function]

CTModels.Building.control! — Function

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> using CTModels

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

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

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

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

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

Returns

Nothing

`definition!` [Function]

CTModels.Building.definition! — Function

definition!(
    ocp::CTModels.Building.PreModel,
    definition::Expr
)

Set the model definition of the optimal control problem from a raw Expr.

The expression is wrapped in a CTModels.Components.Definition and stored on the pre-model.

Arguments

ocp::PreModel: The pre-model to modify.
definition::Expr: The symbolic expression defining the problem.

Returns

Nothing

definition!(
    ocp::CTModels.Building.PreModel,
    definition::CTModels.Components.AbstractDefinition
)

Set the model definition of the optimal control problem from an existing CTModels.Components.AbstractDefinition value (either a CTModels.Components.Definition or an CTModels.Components.EmptyDefinition).

Arguments

ocp::PreModel: The pre-model to modify.
definition::AbstractDefinition: The definition value to store.

Returns

Nothing

`dynamics!` [Function]

CTModels.Building.dynamics! — Function

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

Throws

Exceptions.PreconditionError: If called out of order or in an invalid state.

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

Throws

Exceptions.PreconditionError: If the state or times are not yet set
Exceptions.PreconditionError: If the dynamics are already defined completely
Exceptions.PreconditionError: If any index in rg overlaps with an existing dynamics range
Exceptions.IncorrectArgument: If an index in rg is out of bounds

Returns

Nothing

Example

julia> using CTModels

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

Throws

Exceptions.PreconditionError: If the model is not properly initialized
Exceptions.PreconditionError: If the index i overlaps with existing dynamics
Exceptions.PreconditionError: If a full dynamics function is already defined
Exceptions.IncorrectArgument: If the index i is out of bounds

Example

julia> using CTModels

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

Returns

Nothing

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

`objective!` [Function]

CTModels.Building.objective! — Function

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> using CTModels

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

`state!` [Function]

CTModels.Building.state! — Function

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> using CTModels

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

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

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

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

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

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

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

julia> state_dimension(ocp), 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

`time!` [Function]

CTModels.Building.time! — Function

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> using CTModels

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

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

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

julia> ocp = PreModel(); time!(ocp; ind0=2, indf=3) # Free  t0 and free  tf

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

julia> using CTModels

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

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

`time_dependence!` [Function]

CTModels.Building.time_dependence! — Function

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

Set the time dependence of the optimal control problem ocp.

Arguments

ocp::PreModel: The optimal control problem being defined.
autonomous::Bool: Indicates whether the system is autonomous (true) or time-dependent (false).

Preconditions

The time dependence must not have been set previously.

Behavior

This function sets the autonomous field of the model to indicate whether the system's dynamics explicitly depend on time. It can only be called once.

Throws

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

Example

julia> using CTModels

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

Returns

Nothing

`variable!` [Function]

CTModels.Building.variable! — Function

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> using CTModels

julia> ocp = PreModel(); variable!(ocp, 1, "v")
julia> ocp = PreModel(); 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