Abstract syntax documentation

[jbcaillau]

Must add in the documentation a comprehensive description of the abstract syntax.

• @jbcaillau must cover whatever is in the grammar below (see onepass.jl)

        :( $v ∈ R^$q, variable       ) => p_variable!(p, ocp, v, q; log)
        :( $v ∈ R   , variable       ) => p_variable!(p, ocp, v   ; log)
        :( $v       , variable       ) => p_variable!(p, ocp, v   ; log) # todo: remove
        :( $t ∈ [ $t0, $tf ], time   ) => p_time!(p, ocp, t, t0, tf; log)
        :( $x ∈ R^$n, state          ) => p_state!(p, ocp, x, n; log)
        :( $x ∈ R   , state          ) => p_state!(p, ocp, x   ; log)
        :( $x       , state          ) => p_state!(p, ocp, x   ; log) # todo: remove
        :( $u ∈ R^$m, control        ) => p_control!(p, ocp, u, m; log)
        :( $u ∈ R   , control        ) => p_control!(p, ocp, u   ; log)
        :( $u       , control        ) => p_control!(p, ocp, u   ; log) # todo: remove
        :( $a = $e1                  ) => p_alias!(p, ocp, a, e1; log)
        :( ∂($x)($t) == $e1          ) => p_dynamics!(p, ocp, x, t, e1       ; log)
        :( ∂($x)($t) == $e1, $label  ) => p_dynamics!(p, ocp, x, t, e1, label; log)
        :( $e1 == $e2                ) => p_constraint!(p, ocp, e2     , e1, e2       ; log)
        :( $e1 == $e2, $label        ) => p_constraint!(p, ocp, e2     , e1, e2, label; log)
        :( $e1 ≤  $e2 ≤  $e3         ) => p_constraint!(p, ocp, e1     , e2, e3            ; log)
        :( $e1 ≤  $e2 ≤  $e3, $label ) => p_constraint!(p, ocp, e1     , e2, e3     , label; log)
        :(        $e2 ≤  $e3         ) => p_constraint!(p, ocp, nothing, e2, e3            ; log)
        :(        $e2 ≤  $e3, $label ) => p_constraint!(p, ocp, nothing, e2, e3     , label; log)
        :( $e3 ≥  $e2 ≥  $e1         ) => p_constraint!(p, ocp, e1     , e2, e3            ; log)
        :( $e3 ≥  $e2 ≥  $e1, $label ) => p_constraint!(p, ocp, e1     , e2, e3     , label; log)
        :( $e2 ≥  $e1                ) => p_constraint!(p, ocp, e1     , e2, nothing       ; log)
        :( $e2 ≥  $e1,        $label ) => p_constraint!(p, ocp, e1     , e2, nothing, label; log)
        :(       ∫($e1) → min        ) => p_lagrange!(p, ocp, e1, :min; log)
        :(       ∫($e1) → max        ) => p_lagrange!(p, ocp, e1, :max; log)
        :( $e1 + ∫($e2) → min        ) => p_bolza!(p, ocp,      e1,      e2  , :min; log)
        :( $e1 - ∫($e2) → min        ) => p_bolza!(p, ocp,      e1, :( -$e2 ), :min; log)
        :( $e1 + ∫($e2) → max        ) => p_bolza!(p, ocp,      e1,      e2  , :max; log)
        :( $e1 - ∫($e2) → max        ) => p_bolza!(p, ocp,      e1, :( -$e2 ), :max; log)
        :( ∫($e2) + $e1 → min        ) => p_bolza!(p, ocp,      e1,      e2  , :min; log)
        :( ∫($e2) - $e1 → min        ) => p_bolza!(p, ocp, :( -$e1 ),    e2  , :min; log)
        :( ∫($e2) + $e1 → max        ) => p_bolza!(p, ocp,      e1,      e2  , :max; log)
        :( ∫($e2) - $e1 → max        ) => p_bolza!(p, ocp, :( -$e1 ),    e2  , :max; log)
        :( $e1          → min        ) => p_mayer!(p, ocp, e1, :min; log)
        :( $e1          → max        ) => p_mayer!(p, ocp, e1, :max; log)

[ocots]

Ping @jbcaillau.

[jbcaillau]

pong @ocots

[ocots]

Things to mention in the doc:

• one-sided inequalities
• Bolza cost: parenthesis around the Mayer cots

[ocots]

@0Yassine0 You have used OptimalControl.jl to modelise some optimal control problems. Can you give some feedbacks just about modelisation? Have you encountered some difficulties? For instance, you have seen problems with constraints on the derivative of the control. This is not possible with our package. Have you other comments?

[0Yassine0]

@ocots. Overall, modeling with OptimalControl.jl is smooth and easy. Once we have the mathematical model, it takes only a few minutes to set it up with OptimalControl.jl.
For me, other than dealing with constraints on the control (its derivative or initial and final conditions), I didn't face any major complications.
Also we don't have a hand on manipulating the time step. The time grid is set as uniform and for some problems we need to optimize Δt.
However, I have a remark concerning the latest release, specifically about boundary constraints in the functional version. To define a fixed final or initial value, we now need to use constraint!(ocp, :final, rg =X, lb=Val, ub=Val), which is less practical compared to the previous versions where we had the option to simply use constraint!(ocp, :final, rg =X, Val).

[ocots]

You are right we have removed this possibility. We consider that the abstract form is the standard and we have reduced the number of different signatures for the functional form. However, we could have a keyword val replacing the lb and ub keywords.