Private API

Alias for CTModels.AbstractModel, the continuous-time OCP model type consumed by the discretizers.

mutable struct DOCP{D<:CTDirect.Scheme, O<:CTModels.Models.Model, S<:CTDirect.DOCPshape}

Struct representing a discretized optimal control problem (DOCP).

Fields

• discretization::D: The discretization scheme.
• ocp::O: The original OCP model.
• flags::DOCPFlags: Boolean flags describing problem structure.
• dims::DOCPdims: Problem dimensions.
• time::DOCPtime: Time discretization.
• bounds::DOCPbounds: Variable and constraint bounds.
• shape::S: Per-quantity coercions applied at user-function call boundaries.
• dim_NLP_variables::Int: Number of NLP variables.
• dim_NLP_constraints::Int: Number of NLP constraints.

Example

julia> DOCP(ocp, nlp_model_backend)
DOCP{...}(...)

struct DOCPCache{D<:CTDirect.DOCP} <: CTBase.Core.AbstractCache

Immutable discretize-time cache attached to a CTSolvers.DiscretizedModel.

Created by CTSolvers.discretize, it holds the precomputed DOCP reused across model/solution builds. It is never mutated: any build-time auxiliary (e.g. the ExaModels getter) is carried by the ExaBuildCache inside the CTSolvers.BuiltModel returned by CTSolvers.build_model.

Fields

• docp::D: The internal discretized OCP structure (bounds, dimensions, ...).

struct DOCPFlags

Internal struct holding boolean flags that characterize properties of the discretized optimal control problem (DOCP).

Fields

• freet0::Bool: Whether the OCP has a free initial time.
• freetf::Bool: Whether the OCP has a free final time.
• lagrange::Bool: Whether the OCP includes a Lagrange cost.
• mayer::Bool: Whether the OCP includes a Mayer cost.
• max::Bool: Whether the OCP is a maximization problem.

Example

julia> DOCPFlags(true, false, true, true, false)
DOCPFlags(true, false, true, true, false)

struct DOCPbounds

Internal struct holding variable and constraint bounds for a DOCP.

Fields

• var_l::Vector{Float64}: Lower bounds for NLP variables.
• var_u::Vector{Float64}: Upper bounds for NLP variables.
• con_l::Vector{Float64}: Lower bounds for NLP constraints.
• con_u::Vector{Float64}: Upper bounds for NLP constraints.

Example

julia> DOCPbounds([-1.0, -2.0], [1.0, 2.0], [0.0], [0.0])
DOCPbounds([-1.0, -2.0], [1.0, 2.0], [0.0], [0.0])

struct DOCPdims

Internal struct holding problem dimensions for a DOCP.

Fields

• NLP_x::Int: State dimension
• NLP_u::Int: Control dimension.
• NLP_v::Int: Variable dimension.
• path_cons::Int: Path constraints dimension.
• boundary_cons::Int: Boundary constraints dimension.

Example

julia> DOCPdims(4, 2, 1, 3, 2, 1)
DOCPdims(4, 2, 1, 3, 2, 1)

struct DOCPshape{CX, CU, CV}

Internal struct holding the per-quantity coercions (only or identity) applied at the boundary of every call into a user OCP function, driven by the declared dimension of state, control and optimization variable (never by the runtime type of the value).

Fields

• x: coercion for state / boundary states.
• u: coercion for control.
• v: coercion for the optimization variable.

struct DOCPtime

Internal struct holding time grid information for a DOCP.

Fields

• steps::Int: Number of time steps.
• normalized_grid::Vector{Float64}: Normalized time grid in [0,1].
• fixed_grid::Vector{Float64}: Fixed time grid in [t0, tf].

Example

julia> DOCPtime(10, collect(0:0.1:1), collect(0.0:0.1:1.0))
DOCPtime(10, [0.0, 0.1, …, 1.0], [0.0, 0.1, …, 1.0])

struct ExaBuildCache{G} <: CTBase.Core.AbstractCache

Immutable build-time cache produced by CTSolvers.build_model for the Exa backend.

Carries the getter produced together with the ExaModel so that CTSolvers.build_solution can reconstruct the OCP solution. Stored in the cache field of the CTSolvers.BuiltModel; never mutated.

Fields

• exa_getter::G: Getter produced by the ExaModels constructor.

abstract type Scheme

Abstract type representing a discretization scheme strategy for an optimal control problem.

Concrete subtypes of Scheme define specific schemes for transforming a continuous-time problem into a discrete-time representation suitable for numerical solution.

Example

julia> struct MyScheme <: Scheme end
MyScheme

__constraints!(c, xu, docp::CTDirect.DOCP) -> Any

Compute the nonlinear constraints of a DOCP.

The constraints are modeled as lb <= C(x) <= ub.

Arguments

• c: Preallocated constraint vector.
• xu: Vector of NLP decision variables.
• docp::DOCP: The discretized OCP.

Returns

• c: The filled constraint vector.

Example

julia> DOCP_constraints!(zeros(docp.dim_NLP_constraints), xu, docp)
[0.0, 0.1, …]

__constraints_bounds!(
    docp::CTDirect.DOCP
) -> Tuple{Vector{Float64}, Vector{Float64}}

Build lower and upper bounds vectors for the nonlinear constraints of a DOCP.

Arguments

• docp::DOCP: The discretized OCP.

Returns

• (lb, ub)::Tuple{Vector{Float64},Vector{Float64}}: Lower and upper bounds.

Example

julia> constraints_bounds!(docp)
([-1.0, …], [1.0, …])

__discretizer() -> CTDirect.Collocation

Default discretizer used when none is given: CTDirect.Collocation().

__objective(xu, docp::CTDirect.DOCP) -> Any

Compute the objective value of a discretized OCP.

Arguments

• xu: Vector of NLP decision variables.
• docp::DOCP: The discretized OCP.

Returns

• obj::Float64: Objective function value.

Example

julia> DOCP_objective(xu, docp)
12.34

_dim_coerce(
    dim::Int64
) -> Union{typeof(identity), typeof(only)}

Coercion to apply to a quantity of declared dimension dim before handing it to a user OCP function: only collapses a 1-D quantity to a scalar, identity leaves every other dimension untouched — including dim == 0 (control-free problems), for which only would throw on the empty view.

build_OCP_solution(
    docp::CTDirect.DOCP,
    nlp_solution::SolverCore.AbstractExecutionStats,
    T,
    objective,
    iterations,
    constraints_violation,
    message,
    status,
    successful;
    exa_getter
) -> CTModels.Solutions.Solution{TimeGridModelType, TimesModelType, StateModelType, ControlModelType, VariableModelType, ModelType, CostateModelType, Float64, DualModelType, CTModels.Solutions.SolverInfos{Any, Dict{Symbol, Any}}} where {TimeGridModelType<:CTModels.Solutions.AbstractTimeGridModel, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, ModelType<:CTModels.Models.AbstractModel, CostateModelType<:Function, DualModelType<:CTModels.Solutions.AbstractDualModel}

Build an OCP functional solution from a DOCP discrete solution given as a SolverCore.AbstractExecutionStats object.

Arguments

• docp: The discretized optimal control problem (DOCP).
• nlp_solution: A solver execution statistics object.

Returns

• solution::CTModels.Solution: A functional OCP solution containing trajectories, multipliers, and solver information.

Example

julia> build_OCP_solution(docp, nlp_solution)
CTModels.Solution(...)

build_bounds_block(
    dim_var,
    dim_box,
    box_triplet
) -> Tuple{Any, Any}

Build lower and upper bound vectors for state, control, or optimization variables.

Arguments

• dim_var::Int: Variable dimension.
• dim_box::Int: Number of box constraints.
• box_triplet: Triplet defining box constraints.

Returns

• (x_lb, x_ub)::Tuple{Vector{Float64},Vector{Float64}}: Lower and upper bounds.

Example

julia> build_bounds_block(3, 1, ([0.0], [2], [1.0]))
([-Inf, 0.0, -Inf], [Inf, 1.0, Inf])

coerce_control(docp::CTDirect.DOCP) -> Any

Coercion to apply to a control value before handing it to a user OCP function.

coerce_state(docp::CTDirect.DOCP) -> Any

Coercion to apply to a state value before handing it to a user OCP function.

coerce_variable(docp::CTDirect.DOCP) -> Any

Coercion to apply to the optimization variable before handing it to a user OCP function.

disc_model(docp::CTDirect.DOCP) -> CTDirect.Scheme

Return the discretization model associated with a given discretized optimal control problem (DOCP).

Arguments

• docp::DOCP: The discretized optimal control problem.

Returns

• discretization::Any: The discretization model stored in docp.

Example

julia> disc_model(docp)
DiscretizationModel(...)

get_docp(
    discretizer::CTSolvers.DOCP.AbstractDiscretizer,
    ocp::CTModels.Models.AbstractModel
) -> Union{CTDirect.DOCP{CTDirect.Euler, CTModels.Models.Model{TD, TimesModelType, StateModelType, ControlModelType, VariableModelType, DynamicsModelType, ObjectiveModelType, ConstraintsModelType, DefinitionType, BuildExaModelType}, CTDirect.DOCPshape{CX, CU, CV}} where {TD<:CTBase.Traits.TimeDependence, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.Components.AbstractObjectiveModel, ConstraintsModelType<:CTModels.Components.AbstractConstraintsModel, DefinitionType<:CTModels.Components.AbstractDefinition, BuildExaModelType<:Union{Nothing, Function}, CX<:Union{typeof(identity), typeof(only)}, CU<:Union{typeof(identity), typeof(only)}, CV<:Union{typeof(identity), typeof(only)}}, CTDirect.DOCP{CTDirect.Gauss_Legendre_2, CTModels.Models.Model{TD, TimesModelType, StateModelType, ControlModelType, VariableModelType, DynamicsModelType, ObjectiveModelType, ConstraintsModelType, DefinitionType, BuildExaModelType}, CTDirect.DOCPshape{CX, CU, CV}} where {TD<:CTBase.Traits.TimeDependence, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.Components.AbstractObjectiveModel, ConstraintsModelType<:CTModels.Components.AbstractConstraintsModel, DefinitionType<:CTModels.Components.AbstractDefinition, BuildExaModelType<:Union{Nothing, Function}, CX<:Union{typeof(identity), typeof(only)}, CU<:Union{typeof(identity), typeof(only)}, CV<:Union{typeof(identity), typeof(only)}}, CTDirect.DOCP{CTDirect.Gauss_Legendre_2_Stagewise, CTModels.Models.Model{TD, TimesModelType, StateModelType, ControlModelType, VariableModelType, DynamicsModelType, ObjectiveModelType, ConstraintsModelType, DefinitionType, BuildExaModelType}, CTDirect.DOCPshape{CX, CU, CV}} where {TD<:CTBase.Traits.TimeDependence, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.Components.AbstractObjectiveModel, ConstraintsModelType<:CTModels.Components.AbstractConstraintsModel, DefinitionType<:CTModels.Components.AbstractDefinition, BuildExaModelType<:Union{Nothing, Function}, CX<:Union{typeof(identity), typeof(only)}, CU<:Union{typeof(identity), typeof(only)}, CV<:Union{typeof(identity), typeof(only)}}, CTDirect.DOCP{CTDirect.Gauss_Legendre_3, CTModels.Models.Model{TD, TimesModelType, StateModelType, ControlModelType, VariableModelType, DynamicsModelType, ObjectiveModelType, ConstraintsModelType, DefinitionType, BuildExaModelType}, CTDirect.DOCPshape{CX, CU, CV}} where {TD<:CTBase.Traits.TimeDependence, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.Components.AbstractObjectiveModel, ConstraintsModelType<:CTModels.Components.AbstractConstraintsModel, DefinitionType<:CTModels.Components.AbstractDefinition, BuildExaModelType<:Union{Nothing, Function}, CX<:Union{typeof(identity), typeof(only)}, CU<:Union{typeof(identity), typeof(only)}, CV<:Union{typeof(identity), typeof(only)}}, CTDirect.DOCP{CTDirect.Gauss_Legendre_3_Stagewise, CTModels.Models.Model{TD, TimesModelType, StateModelType, ControlModelType, VariableModelType, DynamicsModelType, ObjectiveModelType, ConstraintsModelType, DefinitionType, BuildExaModelType}, CTDirect.DOCPshape{CX, CU, CV}} where {TD<:CTBase.Traits.TimeDependence, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.Components.AbstractObjectiveModel, ConstraintsModelType<:CTModels.Components.AbstractConstraintsModel, DefinitionType<:CTModels.Components.AbstractDefinition, BuildExaModelType<:Union{Nothing, Function}, CX<:Union{typeof(identity), typeof(only)}, CU<:Union{typeof(identity), typeof(only)}, CV<:Union{typeof(identity), typeof(only)}}, CTDirect.DOCP{CTDirect.Midpoint, CTModels.Models.Model{TD, TimesModelType, StateModelType, ControlModelType, VariableModelType, DynamicsModelType, ObjectiveModelType, ConstraintsModelType, DefinitionType, BuildExaModelType}, CTDirect.DOCPshape{CX, CU, CV}} where {TD<:CTBase.Traits.TimeDependence, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.Components.AbstractObjectiveModel, ConstraintsModelType<:CTModels.Components.AbstractConstraintsModel, DefinitionType<:CTModels.Components.AbstractDefinition, BuildExaModelType<:Union{Nothing, Function}, CX<:Union{typeof(identity), typeof(only)}, CU<:Union{typeof(identity), typeof(only)}, CV<:Union{typeof(identity), typeof(only)}}, CTDirect.DOCP{CTDirect.Trapeze, CTModels.Models.Model{TD, TimesModelType, StateModelType, ControlModelType, VariableModelType, DynamicsModelType, ObjectiveModelType, ConstraintsModelType, DefinitionType, BuildExaModelType}, CTDirect.DOCPshape{CX, CU, CV}} where {TD<:CTBase.Traits.TimeDependence, TimesModelType<:CTModels.Components.AbstractTimesModel, StateModelType<:CTModels.Components.AbstractStateModel, ControlModelType<:CTModels.Components.AbstractControlModel, VariableModelType<:CTModels.Components.AbstractVariableModel, DynamicsModelType<:Function, ObjectiveModelType<:CTModels.Components.AbstractObjectiveModel, ConstraintsModelType<:CTModels.Components.AbstractConstraintsModel, DefinitionType<:CTModels.Components.AbstractDefinition, BuildExaModelType<:Union{Nothing, Function}, CX<:Union{typeof(identity), typeof(only)}, CU<:Union{typeof(identity), typeof(only)}, CV<:Union{typeof(identity), typeof(only)}}}

Build the core DOCP structure from a discretizer and an OCP, setting variable and constraint bounds. Shared by all discretizer types.

get_time_grid(xu, docp::CTDirect.DOCP) -> Any

Return the time grid for problems with free initial or final times. Note that this function can be called during optimization, not just for postprocessing

Arguments

• xu: Vector of NLP decision variables.
• docp::DOCP: The discretized OCP.

Returns

• grid::Vector{Float64}: Time grid corresponding to current NLP variables.

Example

julia> get_time_grid(xu, docp)
[0.0, 0.1, …, 1.0]

get_time_grid_exa(
    nlp_solution::SolverCore.AbstractExecutionStats,
    docp::CTDirect.DOCP,
    exa_getter
) -> Vector{Float64}

Retrieve the time grid from the given DOCP solution.

Arguments

• nlp_solution: The DOCP solution.
• docp: The DOCP.

Returns

• ::Vector{Float64}: The time grid.

is_empty(t) -> Any

Check whether a collection t is empty or not defined.

Arguments

• t: Any object that may be nothing or support length.

Returns

• ::Bool: true if t is nothing or has length zero, otherwise false.

Example

julia> is_empty([])
true

julia> is_empty([1, 2, 3])
false

julia> is_empty(nothing)
true

ocp_model(docp::CTDirect.DOCP) -> CTModels.Models.Model

Return the continuous-time optimal control problem (OCP) model associated with a given discretized optimal control problem (DOCP).

Arguments

• docp::DOCP: The discretized optimal control problem.

Returns

• ocp::Any: The underlying OCP model stored in docp.

Example

julia> ocp_model(docp)
OCPModel(...)

stepPathConstraints!(docp, c, xu, v, time_grid, i)

Set path constraints at given time step