JuMP schemes
This page is for users and developers who want to know exactly which nonlinear program (NLP) a JuMP model of this package is, and how the model stores what is needed to read the state, the control and the costate back. It is not needed to use the package.
The OptimalControl modelings return the continuous problem; the discretization is chosen in solve and done by CTDirect. The JuMP modeling has no such layer: each JuMP model is an NLP. To compare JuMP and OptimalControl fairly, the JuMP models reproduce the NLP that CTDirect builds, scheme by scheme.
The continuous problem
Every problem is written in Bolza form, with state
The grid
With grid_size, the grid is uniform:
When
Indices start at x₁[0:N]). CTDirect counts from
Unknowns and number of controls
The state is discretized at the
| Scheme | scheme | Controls | Number of unknowns |
|---|---|---|---|
| Trapezoidal rule | :trapeze | ||
| Explicit Euler | :euler | ||
| Implicit Euler | :euler_implicit | ||
| Midpoint rule | :midpoint |
For the one-step schemes,
The scheme of a JuMP model is chosen when it is built, with the names of OptimalControl.Collocation; the default is the trapezoidal rule:
model = beam(JuMPBackend(); grid_size=100, scheme=:midpoint)
model[:scheme] # :midpointDynamics and cost, scheme by scheme
Write
| Scheme | Dynamics | Lagrange cost |
|---|---|---|
:trapeze | ||
:euler | ||
:euler_implicit | ||
:midpoint |
The Lagrange cost is added to the objective directly, by the quadrature of the scheme: no extra state is introduced. The Mayer term is
The schemes as Butcher tableaux
The four schemes are Runge–Kutta methods, each given by its Butcher tableau
and the Lagrange cost uses the same quadrature,
| Scheme | |||
|---|---|---|---|
:euler | |||
:euler_implicit | |||
:midpoint | |||
:trapeze |
The JuMP models have no stage unknowns: each stage is written with the nodes of its step,
Two properties of the tableau decide the rest:
stiffly accurate: the last row of
is and , so the last stage is; explicit first stage: the first row of
is zero and , so the first stage is.
A tableau with both is FSAL (First Same As Last): the last stage of a step is the first stage of the next one. Among the four schemes, only the trapezoidal rule is FSAL.
| Scheme | Stiffly accurate | Explicit first stage | FSAL |
|---|---|---|---|
:euler | no | yes | no |
:euler_implicit | yes | no | no |
:midpoint | no | no | no |
:trapeze | yes | yes | yes |
With FSAL, the dynamics and the Lagrange integrand are evaluated once per node,
These properties are computed from the tableau, not declared, in ext/JuMPModels/schemes/tableaux.jl; the names follow the roadmap of CTDirect (CTDirect.jl#610), where the same tableaux, traits and specializations are planned.
Constraints
Box constraints on the state, the control and the variable are bounds of the unknowns, not constraints:
Path constraints are imposed at the
| Scheme | Node |
|---|---|
:trapeze | |
:euler, :midpoint | |
:euler_implicit |
Boundary conditions
Exa and the number of controls
Under the :exa modeler of OptimalControl, the controls are declared at the :euler, :midpoint and :euler_implicit the Exa NLP therefore has
Order of the unknowns and of the constraints
The order of the unknowns and of the constraints changes the sparsity pattern seen by the linear solver. It is chosen when the model is built, with ordering:
:interleaved(default), CTDirect's order:unknowns: node by node, the state then the control while there is one,
(trapezoidal rule) or (one control per step), then ; constraints: for each step
, the dynamics of the step then the path constraints at node; then the path constraints at node ; then the boundary conditions.
:blocks, the same pieces grouped by kind:unknowns:
, then all the controls, then ; constraints: all the dynamics, then the path constraints at the nodes
, then the boundary conditions.
model = beam(JuMPBackend(); grid_size=100, ordering=:blocks)
model[:ordering] # :blocksThe NLP is the same in both orders, up to a permutation of the unknowns and of the constraints. The unknowns keep their names (x₁[3]), and model[:constraints] lists the constraints in CTDirect's order for both orderings, so the permutation can be computed from the model.
MOI groups the constraints by type
JuMP passes the constraints to the solver grouped by type: function (affine, quadratic, nonlinear) and set (equality, interval). The order of creation is kept only within a type. The dynamics, path constraints and boundary conditions of a problem are often of different types, so :blocks mostly changes the order of the unknowns.
In the code
A problem file declares data
A file of ext/JuMPModels/ fills a ProblemData and hands it to the scheme; it writes no discretization itself:
data = ProblemData(;
state=[Component("x₁"; lower=x₁_l, upper=x₁_u), Component("x₂")],
control=[Component("u")],
costate=["∂x₁", "∂x₂"],
times=v -> (t0, tf),
dynamics=(x, u, v, t) -> [x[2], u[1]],
lagrange=(x, u, v, t) -> u[1]^2,
boundary=[(x₁_t0, (x0, xf, v) -> x0[1], x₁_t0), (x₁_tf, (x0, xf, v) -> xf[1], x₁_tf)],
)
return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)| Field | Mathematical object |
|---|---|
state, control, variable | the components and their bounds (box constraints); the start values are those of the initial guess init of the metadata, at the nodes |
times(v) | |
dynamics(x, u, v, t) | |
lagrange(x, u, v, t) | nothing |
cost(I, x0, xf, v) | the objective given the discretized integral |
path | |
boundary |
The functions receive the vectors of JuMP variables of one node and return JuMP expressions: the scheme evaluates them at its stages (nodes or, for the midpoint rule,
Scaled models. A model written on scaled variables writes its dynamics on the scaled state, as the OptimalControl model does: for space_shuttle, with
What the model stores
Besides the NLP, build stores in the JuMP model what is needed to read a solution back:
| Key | Content | Used by |
|---|---|---|
model[:x₁], … (one per state component) | the unknowns of the component, a container indexed by 0:N | state |
model[:u], … (one per control component) | the unknowns of the component, indexed by 0:N (trapezoidal rule) or 0:N-1 (one control per step, | control |
model[:tf], … (one per variable component) | the unknown | variable, the time grid |
model[:∂x₁], … (one per costate name) | the dynamics constraints of the component, indexed by 1:N | costate (their duals) |
model[:scheme] | the scheme, :trapeze, :euler, :euler_implicit or :midpoint | control, solution |
model[:ordering] | the order of the unknowns and constraints, :interleaved or :blocks | the comparisons with CTDirect |
model[:constraints] | the constraints, in CTDirect's order whatever the ordering | the comparisons with CTDirect |
model[:time_grid] | a function returning | time_grid |
model[:state_components], model[:control_components], model[:variable_components], model[:costate_components] | the names above, in order | every accessor |
The accessors read these keys:
model = beam(JuMPBackend(); grid_size=100)
JuMP.set_optimizer(model, Ipopt.Optimizer)
JuMP.optimize!(model)
T = time_grid(model) # t_0, …, t_N
x = state(model) # function of t, interpolating X_0, …, X_N
u = control(model) # function of t: linear (trapeze) or piecewise constant
p = costate(model) # function of t, from the duals of the dynamics constraints
objective(model), iterations(model)The costate is read from the duals of the JuMP.dual returns the MOI ConstraintDual, a convention fixed by MathOptInterface, independent of the solver and of the objective sense; the accessors return -JuMP.dual, the multiplier convention of rules/signs.md (ct-conventions, SGN1–SGN3) and of OptimalControl (#326). When the problem also exists in OptimalControl, solution(model, pb) builds a full CTModels.Solution from these values, which can be plotted like an OptimalControl solution.
With one control per step, the control is reported as CTDirect reports it: