Private API

struct CompositeConstraint{Sig, CS} <: Function

In-place callable struct concatenating n nonlinear constraints into a single composite constraint. Sig = :path selects the call method (val, t, x, u, v); Sig = :boundary selects (val, x0, xf, v). Both the signature and the concrete tuple type CS are encoded in type parameters, so each call method is fully specialised with no runtime branch.

Storing n, dims, and funs as fields (Pattern 7) eliminates the capture-by-reference fragility present in the previous make_boundary_cons_nl closure (where constraints_number and constraints_dimensions were outside the let block).

Replaces the anonymous closures path_cons_nl! and boundary_cons_nl! produced inside CTModels.Building.build in build.jl.

Fields

• n::Int: Number of individual constraints.
• dims::Vector{Int}: Dimension of each individual constraint.
• funs::CS: Concrete tuple of the N constraint functions.

Examples

using CTModels.Building

f1!(r, t, x, u, v) = (r[1] = x[1] + u[1])
f2!(r, t, x, u, v) = (r[1] = x[2])
fc = CompositeConstraint{:path}(2, [1, 1], (f1!, f2!))
val = zeros(2)
fc(val, 0.0, [1.0, 2.0], [3.0], nothing)
# val == [4.0, 2.0]

__build_dynamics_from_parts(
    parts::Vector{<:Tuple{var"#s51", var"#s50"} where {var"#s51"<:(AbstractRange{<:Int64}), var"#s50"<:Function}}
) -> CTModels.Building.var"#dyn!#__build_dynamics_from_parts##0"{Vector{var"#s52"}} where var"#s52"<:(Tuple{var"#s51", var"#s50"} where {var"#s51"<:(AbstractRange{<:Int64}), var"#s50"<:Function})

Build a combined dynamics function from multiple parts.

This function constructs an in-place dynamics function dyn! by composing several sub-functions, each responsible for updating a specific segment of the output vector.

Arguments

• parts::Vector{<:Tuple{<:AbstractRange{<:Int}, <:Function}}: A vector of tuples, where each tuple contains:
  • A range specifying the indices in the output vector val that the corresponding function updates.
  • A function f with the signature (output_segment, t, x, u, v), which updates the slice of val indicated by the range.

Returns

• dyn!: A function with signature (val, t, x, u, v) that updates the full output vector val in-place by applying each part function to its assigned segment.

Details

• The returned dyn! function calls each part function with a view of val restricted to the assigned range. This avoids unnecessary copying and allows efficient updates of sub-vectors.
• Each part function is expected to modify its output segment in-place.

Example

# Define two sub-dynamics functions
julia> f1(out, t, x, u, v) = out .= x[1:2] .+ u[1:2]
julia> f2(out, t, x, u, v) = out .= x[3] * v

# Combine them into one dynamics function affecting different parts of the output vector
julia> parts = [(1:2, f1), (3:3, f2)]
julia> dyn! = __build_dynamics_from_parts(parts)

val = zeros(3)
julia> dyn!(val, 0.0, [1.0, 2.0, 3.0], [0.5, 0.5], 2.0)
julia> println(val)  # prints [1.5, 2.5, 6.0]

__collect_used_names(
    ocp::CTModels.Building.PreModel
) -> Vector{String}

Collect all names already used in the PreModel across all components.

Returns a vector containing:

• Time name (if set)
• State name and components (if set)
• Control name and components (if set)
• Variable name and components (if set and non-empty)

Example

julia> ocp = PreModel()
julia> state!(ocp, 2, "x", ["x₁", "x₂"])
julia> control!(ocp, 1, "u")
julia> __collect_used_names(ocp)
4-element Vector{String}:
 "x"
 "x₁"
 "x₂"
 "u"

See also: CTModels.Building.__has_name_conflict, CTModels.Building.__validate_name_uniqueness.

__constraint!(
    ocp_constraints::OrderedCollections.OrderedDict{Symbol, Tuple{Symbol, Union{Function, OrdinalRange{<:Int64}}, AbstractVector{<:Real}, AbstractVector{<:Real}}},
    type::Symbol,
    n::Int64,
    m::Int64,
    q::Int64;
    rg,
    f,
    lb,
    ub,
    label,
    codim_f
)

Add a constraint to a dictionary of constraints.

Arguments

• ocp_constraints: The dictionary of constraints to which the constraint will be added.
• type: The type of the constraint. It can be :state, :control, :variable, :boundary, or :path.
• n: The dimension of the state.
• m: The dimension of the control.
• q: The dimension of the variable.
• 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 dictionary of constraints.

Requirements

• The constraint must not be set before.
• The lower bound lb and the upper bound ub cannot be both nothing.
• The lower bound lb and the upper bound ub must have the same length, if both provided.

If rg and f are not provided then,

• type must be :state, :control, or :variable.
• lb and ub must be of dimension n, m, or q respectively, when provided.

If rg is provided, then:

• f must not be provided.
• type must be :state, :control, or :variable.
• rg must be a range of integers, and must be contained in 1:n, 1:m, or 1:q respectively.

If f is provided, then:

• rg must not be provided.
• type must be :boundary or :path.
• f must be a function that returns a vector of the same dimension as the constraint.
• lb and ub must be of the same dimension as the output of f, when provided.

Example

# Example of adding a state constraint
julia> ocp_constraints = Dict()
julia> __constraint!(ocp_constraints, :state, 3, 2, 1, lb=[0.0], ub=[1.0], label=:my_constraint)

__constraint_label() -> Symbol

Return a unique label for a constraint using gensym with prefix :unnamed.

Returns

• Symbol: A unique constraint label.

__constraints()

Return the default value for the constraints.

Returns

• Nothing

__control_components(
    m::Int64,
    name::String
) -> Vector{String}

Return the default component names for a control variable of dimension m.

Arguments

• m::Dimension: The control dimension.
• name::String: The base name for components.

Returns

• Vector{String}: Component names (single element for m=1, subscripted for m>1).

__control_interpolation() -> Symbol

Return the default control interpolation type.

Returns

• Symbol: The interpolation type (:constant for piecewise constant, :linear for piecewise linear).

__control_name() -> String

Return the default name of the control variable.

Returns

• String: The default control name ("u").

__criterion_type() -> Symbol

Return the default optimization criterion type.

Returns

• Symbol: The criterion type (:min for minimization).

__filename_export_import() -> String

Return the default filename (without extension) for exporting and importing solutions.

Returns

• String: The default filename ("solution").

__format() -> Symbol

Return the default format of the file to be used for export and import.

Returns

• Symbol: The format symbol (:JLD).

__has_name_conflict(
    ocp::CTModels.Building.PreModel,
    new_name::String
) -> Bool
__has_name_conflict(
    ocp::CTModels.Building.PreModel,
    new_name::String,
    exclude_component::Symbol
) -> Bool

Check if a name conflicts with existing names in the PreModel.

Arguments

• ocp::PreModel: The model to check against
• new_name::String: The new name to check
• exclude_component::Symbol: Component type to exclude from check (:state, :control, :variable, :time, :none)

The exclude_component parameter allows checking for conflicts while updating a component, excluding the component's own current names from the check.

Returns

• Bool: true if conflict exists, false otherwise

Example

julia> ocp = PreModel()
julia> state!(ocp, 2, "x", ["x₁", "x₂"])
julia> __has_name_conflict(ocp, "x", :none)
true

julia> __has_name_conflict(ocp, "y", :none)
false

See also: CTModels.Building.__collect_used_names, CTModels.Building.__validate_name_uniqueness.

__is_autonomous_set(ocp::CTModels.Building.PreModel) -> Bool

Return true if the autonomous flag has been set in the PreModel.

Returns

• Bool

__is_consistent(ocp::CTModels.Building.PreModel) -> Bool

Return true if all the required fields are set in the PreModel.

Arguments

• ocp::PreModel: The pre-model to check.

Returns

• Bool

__is_control_empty(c) -> Bool

Return true if c is an EmptyControlModel.

Returns

• Bool

__is_control_empty(ocp::CTModels.Building.PreModel) -> Bool

Return true if the control field of the PreModel is an EmptyControlModel.

Returns

• Bool

__is_definition_empty(d) -> Bool

Return true if d is an CTModels.Components.EmptyDefinition.

Returns

• Bool

__is_definition_empty(
    ocp::CTModels.Building.PreModel
) -> Bool

Return true if the definition field of the PreModel is an CTModels.Components.EmptyDefinition.

Returns

• Bool

__is_dynamics_complete(
    ocp::CTModels.Building.PreModel
) -> Bool

Return true if dynamics cover all state components in the PreModel.

For component-wise dynamics, checks that all state indices are covered.

Arguments

• ocp::PreModel: The pre-model to check.

Returns

• Bool

__is_dynamics_set(ocp::CTModels.Building.PreModel) -> Bool

Return true if dynamics have been set in the PreModel.

Returns

• Bool

__is_empty(ocp::CTModels.Building.PreModel) -> Bool

Return true if nothing has been set.

Arguments

• ocp::PreModel: The pre-model to check.

Returns

• Bool

__is_objective_set(ocp::CTModels.Building.PreModel) -> Bool

Return true if objective has been set in the PreModel.

Returns

• Bool

__is_set(x) -> Bool

Return true if x is not nothing.

Returns

• Bool

__is_state_set(ocp::CTModels.Building.PreModel) -> Bool

Return true if state has been set in the PreModel.

Returns

• Bool

__is_times_set(ocp::CTModels.Building.PreModel) -> Bool

Return true if times have been set in the PreModel.

Returns

• Bool

__is_variable_empty(v) -> Bool

Return true if v is an EmptyVariableModel.

Returns

• Bool

__is_variable_empty(ocp::CTModels.Building.PreModel) -> Bool

Return true if the variable field of the PreModel is an EmptyVariableModel.

Returns

• Bool

__state_components(n::Int64, name::String) -> Vector{String}

Return the default component names for a state variable of dimension n.

Arguments

• n::Dimension: The state dimension.
• name::String: The base name for components.

Returns

• Vector{String}: Component names (single element for n=1, subscripted for n>1).

__state_name() -> String

Return the default name of the state variable.

Returns

• String: The default state name ("x").

__time_grid_default_component() -> Symbol

Return the default component for time grid access in multiple time grid solutions.

Returns

• Symbol: The default component (:state).

__time_name() -> String

Return the default name of the time variable.

Returns

• String: The default time name ("t").

__validate_name_uniqueness(
    ocp::CTModels.Building.PreModel,
    name::String,
    components::Vector{String},
    component_type::Symbol
)

Validate that a name and its components don't conflict with existing names.

Performs comprehensive validation:

1. Name is not empty
2. Components are not empty
3. Name not in components (internal conflict)
4. No duplicates in components
5. No conflicts with existing names in other components (global uniqueness)

Arguments

• ocp::PreModel: The model to validate against
• name::String: The component name
• components::Vector{String}: The component names
• component_type::Symbol: Type of component (:state, :control, :variable, :time)

Throws

• Exceptions.IncorrectArgument: If any validation fails

Example

julia> ocp = PreModel()
julia> state!(ocp, 2, "x", ["x₁", "x₂"])
julia> __validate_name_uniqueness(ocp, "x", ["u"], :control)  # Would throw if "x" conflicts

See also: CTModels.Building.__has_name_conflict, CTModels.Building.__collect_used_names.

__variable_components(
    q::Int64,
    name::String
) -> Vector{String}

Return the default component names for a variable of dimension q.

Arguments

• q::Dimension: The variable dimension.
• name::String: The base name for components.

Returns

• Vector{String}: Component names (empty for q=0, single element for q=1, subscripted for q>1).

__variable_name(q::Int64) -> String

Return the default name for optimization variables.

Arguments

• q::Dimension: The variable dimension.

Returns

• String: The variable name ("v" for q>0, empty string for q=0).

_dedup_box_constraints!(
    inds::Vector{Int64},
    lbs::Array{T<:Real, 1},
    ubs::Array{T<:Real, 1},
    labels::Vector{Symbol},
    aliases::Vector{Vector{Symbol}},
    kind::String
)

Deduplicate box-constraint declarations by component, applying the intersection of all declared bounds for each repeated component. Produces an aliases vector recording every label that targeted each component.

After this function returns, the vectors satisfy the invariant:

• allunique(inds) — each component appears at most once.
• lbs[k] = max of all declared lower bounds for component inds[k].
• ubs[k] = min of all declared upper bounds for component inds[k].
• labels[k] = the first label that declared component inds[k] (stable order).
• aliases[k] = all distinct labels that declared component inds[k], in first-seen order (always starts with labels[k]).
• Vectors are sorted by inds.

A @warn is emitted once for each duplicated component, listing all contributing labels. If the intersection is empty (i.e. max(lbs_k) > min(ubs_k)), an CTBase.Exceptions.IncorrectArgument is thrown.

Arguments

• inds, lbs, ubs, labels: in-place flat vectors produced by successive calls to CTModels.Building.append_box_constraints!.
• aliases: in-place empty Vector{Vector{Symbol}} to be populated with the per-component list of all declaring labels.
• kind::String: human-readable descriptor (e.g. "state", "control", "variable") used in diagnostic messages.

Throws

• CTBase.Exceptions.IncorrectArgument if the intersection of declared bounds is empty for some component.

Returns

• Nothing

as_range(::Nothing) -> Nothing

Return nothing unchanged.

Returns

• Nothing

as_range(r::Int) -> UnitRange{Int}

Convert a scalar integer to a single-element range r:r.

Arguments

• r::Int: An integer index.

Returns

• UnitRange{Int}: A range containing only r.

Example

julia> as_range(3)
3:3

as_range(r::OrdinalRange{Int}) -> OrdinalRange{Int}

Return an ordinal range unchanged.

Arguments

• r::OrdinalRange{Int}: A range of integers.

Returns

• OrdinalRange{Int}: The input range unchanged.

Example

julia> as_range(1:5)
1:5

as_vector(::Nothing) -> Nothing

Return nothing unchanged.

Returns

• Nothing

as_vector(x::T) -> Vector{T} where {T<:ctNumber}

Wrap a scalar number into a single-element vector.

Arguments

• x::T: A scalar number.

Returns

• Vector{T}: A single-element vector containing x.

Example

julia> as_vector(1.0)
1-element Vector{Float64}:
 1.0

as_vector(x::AbstractVector{T}) -> AbstractVector{T} where {T<:ctNumber}

Return a vector unchanged.

Arguments

• x::AbstractVector{T}: A vector of numbers.

Returns

• AbstractVector{T}: The input vector unchanged.

Example

julia> as_vector([1.0, 2.0, 3.0])
3-element Vector{Float64}:
 1.0
 2.0
 3.0