Private API

DOCP_Hessian_pattern(
    docp::CTDirect.DOCP{D<:CTDirect.Scheme}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Hessian of Lagrangian (to be implemented for each discretization scheme)

DOCP_Hessian_pattern(
    docp::CTDirect.DOCP{CTDirect.Euler}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Hessian of Lagrangian

DOCP_Hessian_pattern(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRK}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Hessian of Lagrangian

DOCP_Hessian_pattern(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRKStagewise}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Hessian of Lagrangian

DOCP_Hessian_pattern(
    docp::CTDirect.DOCP{CTDirect.Midpoint}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Hessian of Lagrangian

DOCP_Hessian_pattern(
    docp::CTDirect.DOCP{CTDirect.Trapeze}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Hessian of Lagrangian

DOCP_Jacobian_pattern(
    docp::CTDirect.DOCP{D<:CTDirect.Scheme}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Jacobian of constraints (to be implemented for each discretization scheme)

DOCP_Jacobian_pattern(
    docp::CTDirect.DOCP{CTDirect.Euler}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Jacobian of constraints

DOCP_Jacobian_pattern(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRK}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Jacobian of constraints

DOCP_Jacobian_pattern(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRKStagewise}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Jacobian of constraints

DOCP_Jacobian_pattern(
    docp::CTDirect.DOCP{CTDirect.Midpoint}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Jacobian of constraints

DOCP_Jacobian_pattern(
    docp::CTDirect.DOCP{CTDirect.Trapeze}
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Build sparsity pattern for Jacobian of constraints

struct Euler <: CTDirect.Scheme

First-order Euler discretization scheme, explicit or implicit.

Selected with scheme = :euler (explicit; aliases :euler_explicit, :euler_forward) or scheme = :euler_implicit (aliases :euler_backward). Both variants share the NLP variable layout [X_1, U_1, …, X_N, U_N, X_N+1, V].

Fields

• info::String: human-readable scheme description.
• _step_variables_block::Int: number of NLP variables per time step (state + controls).
• _state_stage_eqs_block::Int: number of state/stage equality constraints per step.
• _step_pathcons_block::Int: number of path constraints per step.
• _final_control::Bool: whether a distinct control is stored at the final time.
• _explicit::Bool: true for explicit Euler, false for implicit.

See also: CTDirect.Scheme, CTDirect.Midpoint, CTDirect.Trapeze.

Implicit Midpoint discretization, formulated as a generic IRK (ie Gauss Legendre 1) For testing purpose only, use :midpoint instead (cf midpoint.jl) !

Gauss Legendre 2 discretization, formulated as a generic IRK

Implicit Gauss-Legendre collocation for s=2 with stagewise controls.

Gauss Legendre 3 discretization, formulated as a generic IRK

Implicit Gauss-Legendre collocation for s=3 with stagewise controls.

abstract type GenericIRK <: CTDirect.Scheme

Abstract supertype for implicit Runge–Kutta collocation schemes with a single control per time step (non-stagewise), parametrized by a Butcher tableau. Stage derivatives K_i^j are extra NLP variables; layout [X_0, U_0, K_0^1…K_0^s, …, X_N-1, U_N-1, K_N-1^1…K_N-1^s, X_N, V].

Interface Requirements

Concrete subtypes are built from (dims::DOCPdims, time::DOCPtime) (via CTDirect.IRK_dims), carry the Butcher fields stage, butcher_a, butcher_b, butcher_c, and rely on the shared DOCP{<:GenericIRK} methods setWorkArray, integral, stepStateConstraints!, DOCP_Jacobian_pattern and DOCP_Hessian_pattern defined in src/ode/irk.jl.

See also: CTDirect.Scheme, CTDirect.GenericIRKStagewise, CTDirect.Gauss_Legendre_2, CTDirect.Gauss_Legendre_3.

abstract type GenericIRKStagewise <: CTDirect.Scheme

Abstract supertype for implicit Runge–Kutta collocation schemes with stagewise controls (one control per stage per step), parametrized by a Butcher tableau. Both the stage derivatives K_i^j and the stage controls U_i^j are NLP variables; layout [X_0, U_0^1…U_0^s, K_0^1…K_0^s, …, X_N, V] (full layout in the header of src/ode/irk_stagewise.jl).

Interface Requirements

Concrete subtypes are built from (dims::DOCPdims, time::DOCPtime) (via CTDirect.IRK_stagewise_dims), carry the Butcher fields stage, butcher_a, butcher_b, butcher_c, and rely on the DOCP{<:GenericIRKStagewise} methods in src/ode/irk_stagewise.jl (setWorkArray, integral, stepStateConstraints!, __variables_bounds!, __initial_guess, DOCP_Jacobian_pattern, DOCP_Hessian_pattern, and the stagewise control/variable getters).

See also: CTDirect.Scheme, CTDirect.GenericIRK, CTDirect.Gauss_Legendre_2_Stagewise, CTDirect.Gauss_Legendre_3_Stagewise.

IRK_dims(
    dims::CTDirect.DOCPdims,
    time::CTDirect.DOCPtime,
    stage::Int64
) -> NTuple{5, Int64}

Return the dimension of the NLP variables and constraints for a generic IRK discretizion, with the control taken constant per step (ie not distinct controls at time stages)

Dimensions for the specialized IRK stagewise scheme. reminder: dims.NLPx : number of state variables dims.NLPu : number of control variables time.controlsteps : not fully clear yet, assumed to be 1 here dims.NLPv : number of additional optimization variables (free final or initial time for example)

returns:
step_variables_block : number of variables stored for a single time step
state_stage_eqs_block : how many state-vector-sized blocks are stored for the equations, i.e. the state equation and the stages
dim_NLP_variables : total number of optimization variables in the problem, all steps plus the final step
dim_NLP_constraints : for each time step, ((state + stage constraints) + path constraints) + path constraints at final time + boundary constraints

struct Midpoint <: CTDirect.Scheme

Second-order implicit midpoint discretization scheme (the default).

Selected with scheme = :midpoint. Control is piecewise constant, u([t_i, t_i+1[) = U_i and u(tf) = U_N; NLP variable layout [X_1, U_1, …, X_N, U_N, X_N+1, V]. This is the direct formulation (no stage variables), faster than the equivalent CTDirect.Gauss_Legendre_1 IRK form.

Fields

• info::String: human-readable scheme description.
• _step_variables_block::Int: number of NLP variables per time step (state + controls).
• _state_stage_eqs_block::Int: number of state/stage equality constraints per step.
• _step_pathcons_block::Int: number of path constraints per step.
• _final_control::Bool: whether a distinct control is stored at the final time.

See also: CTDirect.Scheme, CTDirect.Euler, CTDirect.Trapeze.

struct Trapeze <: CTDirect.Scheme

Second-order trapezoidal (Crank–Nicolson) discretization scheme.

Selected with scheme = :trapeze. Unlike the other one-step schemes it stores a control at every time step including the final one, hence the NLP variable layout [X_1, U_1, …, X_N+1, U_N+1, V].

Fields

• info::String: human-readable scheme description.
• _step_variables_block::Int: number of NLP variables per time step (state + controls).
• _state_stage_eqs_block::Int: number of state/stage equality constraints per step.
• _step_pathcons_block::Int: number of path constraints per step.
• _final_control::Bool: whether a distinct control is stored at the final time (true).

See also: CTDirect.Scheme, CTDirect.Euler, CTDirect.Midpoint.

__initial_guess(
    docp::CTDirect.DOCP,
    init::CTModels.Init.InitialGuess
) -> Vector{Float64}

Build an initial guess vector for the discretized OCP.

Arguments

• docp::DOCP: The discretized OCP.
• init::CTModels.Init: Initialization settings (default: CTModels.Init()).

Returns

• NLP_X::Vector{Float64}: Initial guess vector.

Example

julia> DOCP_initial_guess(docp)
[0.1, 0.1, …]

__initial_guess(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRKStagewise},
    init::CTModels.Init.InitialGuess
) -> Vector{Float64}

Build the NLP initial-guess vector for a stagewise-IRK–discretized OCP.

Specialises the generic CTDirect.__initial_guess: all entries default to 0.1 (including the stage derivatives and stagewise controls), then the user init.variable / init.state / init.control values are placed at their layout positions.

Arguments

• docp::DOCP{<:GenericIRKStagewise}: the discretized OCP.
• init::CTModels.InitialGuess: user initialization data.

Returns

• NLP_X::Vector{Float64}: initial guess vector.

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

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

Arguments

• docp::DOCP: The discretized OCP.

Returns

• (var_l, var_u)::Tuple{Vector{Float64},Vector{Float64}}: Lower and upper bounds for variables.

Example

julia> variables_bounds!(docp)
([-Inf, …], [Inf, …])

Give the bounds for each NLP variable. varl <= xu <= varu varl and varu have the same structure as xu, so we can reuse the same functions to access the correct location.

add_nonzero_block!(M, i_start, i_end, j_start, j_end; sym)

Mark the rows i_start:i_end × columns j_start:j_end of the boolean sparsity matrix M as nonzero; sym=true also marks the transposed block (for Hessian patterns). Independent from the discretization scheme.

Companion methods: add_nonzero_block!(M, i, j; sym) for a single element, and the add_nonzero_block!(Is, Js, ...) forms that push (row, col) pairs into index vectors instead of writing a matrix.

add_nonzero_block!(M, i, j; sym)

Single-element form: mark M[i, j] (and M[j, i] if sym=true) nonzero.

add_nonzero_block!(
    Is,
    Js,
    i_start,
    i_end,
    j_start,
    j_end;
    sym
)

Index-vector form: push every (row, col) of the block i_start:i_end × j_start:j_end onto (Is, Js) (and the transposed pairs if sym=true).

add_nonzero_block!(Is, Js, i, j; sym)

Single-element index-vector form: push (i, j) onto (Is, Js) (and (j, i) if sym=true).

get_OCP_control_at_time_step(
    xu,
    docp::CTDirect.DOCP,
    i
) -> Any
get_OCP_control_at_time_step(
    xu,
    docp::CTDirect.DOCP,
    i,
    j
) -> Any

Retrieve control variables at given time step from the NLP variables. Convention: 1 <= i <= dimNLPsteps(+1), with convention u(tf) = U_N Extension to the case of multiple controls per time step: index j Vector output

get_OCP_control_at_time_step(
    xu,
    docp::CTDirect.DOCP{CTDirect.Euler},
    i;
    j
) -> Any

Retrieve control variables at given time step from the NLP variables. Convention: see above for explicit / implicit versions Vector output

Compatibility accessor: return an averaged control at time step. Note that j is here ignored. See generic control getter in common.jl:90 +++ update: return actual stage controls for solution ? +++ nb incompatibility between control.steps ans stage for j... +++ would require a new getter for control block ?

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

Retrieve state variables at given time step from the NLP variables. Convention: 1 <= i <= dimNLPsteps+1 Vector output

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

Retrieve optimization variables from the NLP variables. Convention: stored at the end, hence not dependent on the discretization method Vector output

Return control at stage j on time step i. Convention: 1 <= i <= time.steps, j in {1,...,s}.

get_stagevars_at_time_step(
    xu,
    docp::CTDirect.DOCP,
    i,
    j
) -> Any

Retrieve stage variables at given time step/stage from the NLP variables. Convention: 1 <= i <= dimNLPsteps(+1), 1 <= j <= s Vector output Note that passing correct indices is up to the caller, no checks are made here.

Return stage variables Ki^j on time step i. Convention: 1 <= i <= time.steps, j in {1,...,s}. We extract Ki^j.

getter(nlp_solution, docp::CTDirect.DOCP; val)

Extract a named quantity from an NLP solution, reshaped to the OCP layout.

Generic post-optimization getter for the ADNLP path, written to match the ExaModels getter signature. Dispatches on val: dual quantities (:costate, :mult_path_constraints, :mult_boundary_constraints) are read from nlp_solution.multipliers; primal quantities (:variable, :state, :control) from nlp_solution.solution, with _l / _u suffixes selecting the lower / upper box multipliers (multipliers_L / multipliers_U) using the same layout.

Arguments

• nlp_solution: the NLP solver result (fields solution, multipliers, multipliers_L, multipliers_U).
• docp::DOCP: the discretized OCP giving dimensions and layout.
• val::Symbol: the quantity to extract (see above).

Returns

• Array{Float64}: the requested quantity, shaped (dim, n_time_points) for time-indexed quantities, a vector for :variable / :mult_boundary_constraints.

Throws

• CTBase.Exceptions.IncorrectArgument: if val is not a supported symbol.

integral(
    docp::CTDirect.DOCP{CTDirect.Euler},
    xu,
    v,
    time_grid,
    f
) -> Any

Compute the running cost

integral(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRK},
    xu,
    v,
    time_grid,
    f
) -> Any

Compute the running cost

Compute running cost using Gauss quadrature and stagewise controls.

integral(
    docp::CTDirect.DOCP{CTDirect.Midpoint},
    xu,
    v,
    time_grid,
    f
) -> Any

Compute the running cost

integral(
    docp::CTDirect.DOCP{CTDirect.Trapeze},
    xu,
    v,
    time_grid,
    f
) -> Any

Compute the running cost

runningCost(
    docp::CTDirect.DOCP{D<:CTDirect.Scheme},
    xu,
    v,
    time_grid
) -> Any

Compute the running cost (must be implemented for each discretization scheme)

setWorkArray(docp::CTDirect.DOCP, xu, time_grid, v) -> Any

Set work array for all dynamics evaluations

setWorkArray(
    docp::CTDirect.DOCP{CTDirect.Euler},
    xu,
    time_grid,
    v
) -> Any

Set work array for all dynamics and lagrange cost evaluations

setWorkArray(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRK},
    xu,
    time_grid,
    v
) -> Any

Set work array for all dynamics and lagrange cost evaluations

Set work array for dynamics and lagrange cost evaluations. Layout:

• [xi^j ; sumbk]

setWorkArray(
    docp::CTDirect.DOCP{CTDirect.Midpoint},
    xu,
    time_grid,
    v
) -> Any

Set work array for all dynamics cost evaluations

setWorkArray(
    docp::CTDirect.DOCP{CTDirect.Trapeze},
    xu,
    time_grid,
    v
) -> Any

Set work array for all dynamics evaluations

set_control_at_time_step!(
    xu,
    u_init,
    docp::CTDirect.DOCP,
    i;
    j
)

Set initial guess for control variables at given time step Convention: 1 <= i <= dimNLPsteps(+1)

set_optim_variable!(xu, v_init, docp) -> Any

Set optimization variables in the NLP variables (for initial guess)

set_state_at_time_step!(xu, x_init, docp::CTDirect.DOCP, i)

Set initial guess for state variables at given time step Convention: 1 <= i <= dimNLPsteps+1

stepStateConstraints!(
    docp::CTDirect.DOCP{CTDirect.Euler},
    c,
    xu,
    v,
    time_grid,
    i,
    work
) -> Any

Set the constraints corresponding to the state equation Convention: 1 <= i <= dimNLPsteps+1

stepStateConstraints!(
    docp::CTDirect.DOCP{<:CTDirect.GenericIRK},
    c,
    xu,
    v,
    time_grid,
    i,
    work
) -> Any

Set the constraints corresponding to the state equation Convention: 1 <= i <= dimNLPsteps (+1)

Set state and stage constraints. Convention: 1 <= i <= docp.time.steps

stepStateConstraints!(
    docp::CTDirect.DOCP{CTDirect.Midpoint},
    c,
    xu,
    v,
    time_grid,
    i,
    work
)

Set the constraints corresponding to the state equation Convention: 1 <= i <= dimNLPsteps+1

stepStateConstraints!(
    docp::CTDirect.DOCP{CTDirect.Trapeze},
    c,
    xu,
    v,
    time_grid,
    i,
    work
) -> Any

Set the constraints corresponding to the state equation Convention: 1 <= i <= dimNLPsteps+1