Merge pull request #480 from control-toolbox/478-dev-scalar-vs-dim-one

abstract doc update

Author: ocots

docs/src/tutorial-abstract.md

@@ -137,6 +137,9 @@ As before, there are automatic aliases (`u₁` and `u1` for `u[1]`, *etc.*) and
 end
 ```
 
+!!! note
+    One dimensional variable, state or control are treated as scalars (`Real`), not vectors (`Vector`). In Julia, for `x::Real`, it is possible to write `x[1]` (and `x[1][1]`...) so it is OK (though useless) to write `x₁`, `x1` or `x[1]` instead of simply `x` to access the corresponding value. Conversely it is *not* OK to use such an `x` as a vector, for instance as in `...f(x)...` where `f(x::Vector{T}) where {T <: Real}`.
+
 ## [Dynamics](@id tutorial-abstract-dynamics)
 
 ```julia
@@ -299,6 +302,38 @@ using OptimalControl
 end
 ```
 
+!!! caveat
+     Constraint bounds must be *effective*, that is must not depend on a variable. For instance, instead of
+```julia
+o = @def begin
+    v ∈ R, variable
+    t ∈ [0, 1], time
+    x ∈ R², state
+    u ∈ R, control
+    -1 ≤ v ≤ 1
+    x₁(0) == -1
+    x₂(0) == v # wrong: the bound is not effective (as it depends on the variable)
+    x(1) == [0, 0]
+    ẋ(t) == [x₂(t), u(t)]
+    ∫( 0.5u(t)^2 ) → min
+end
+```
+write
+```julia
+o = @def begin
+    v ∈ R, variable
+    t ∈ [0, 1], time
+    x ∈ R², state
+    u ∈ R, control
+    -1 ≤ v ≤ 1
+    x₁(0) == -1
+    x₂(0) - v == 0 # OK: the boundary contraint may involve the variable
+    x(1) == [0, 0]
+    ẋ(t) == [x₂(t), u(t)]
+    ∫( 0.5u(t)^2 ) → min
+end
+```
+
 ## [Mayer cost](@id tutorial-abstract-mayer)
 
 ```julia                                      
@@ -506,3 +541,7 @@ end
 
 - Parsing errors should be explicit enough (with line number in the `@def` `begin ... end` block indicated) 🤞🏾
 - Check tutorials and applications in the documentation for further use.
+
+## Known issues
+
+- [Constants and (reverse over forward) AD](https://github.com/JuliaSmoothOptimizers/ADNLPModels.jl/issues/346)

docs/src/tutorial-double-integrator-energy.md

@@ -41,9 +41,9 @@ ocp = @def begin
     t ∈ [0, 1], time
     x ∈ R², state
     u ∈ R, control
-    x(0) == [ -1, 0 ]
-    x(1) == [ 0, 0 ]
-    ẋ(t) == [ x₂(t), u(t) ]
+    x(0) == [-1, 0]
+    x(1) == [0, 0]
+    ẋ(t) == [x₂(t), u(t)]
     ∫( 0.5u(t)^2 ) → min
 end
 nothing # hide
@@ -91,10 +91,10 @@ ocp = @def begin
 
     x₂(t) ≤ 1.2
 
-    x(0) == [ -1, 0 ]
-    x(1) == [ 0, 0 ]
+    x(0) == [-1, 0]
+    x(1) == [0, 0]
 
-    ẋ(t) == [ x₂(t), u(t) ]
+    ẋ(t) == [x₂(t), u(t)]
 
     ∫( 0.5u(t)^2 ) → min
 

docs/src/tutorial-double-integrator-time.md

@@ -37,7 +37,7 @@ Let us define the problem
 ocp = @def begin
 
     tf ∈ R,          variable
-    t ∈ [ 0, tf ],   time
+    t ∈ [0, tf],   time
     x = (q, v) ∈ R², state
     u ∈ R,           control
 
@@ -52,7 +52,7 @@ ocp = @def begin
     -5 ≤ q(t) ≤ 5,          (1)
     -3 ≤ v(t) ≤ 3,          (2)
 
-    ẋ(t) == [ v(t), u(t) ]
+    ẋ(t) == [v(t), u(t)]
 
     tf → min
 
@@ -65,7 +65,7 @@ nothing # hide
     In order to ensure convergence of the direct solver, we have added the state constraints labelled (1) and (2):
 
     ```math
-    -5 \leq q(t) \leq 5,\quad -3 \leq v(t) \leq 3,\quad t \in [ 0, t_f ].
+    -5 \leq q(t) \leq 5,\quad -3 \leq v(t) \leq 3,\quad t \in [0, t_f].
     ```
 
 !!! note "Nota bene"