fix merge

.github/workflows/CompatHelper.yml

@@ -0,0 +1,46 @@
+# CompatHelper v3.5.0
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if Julia is already available in the PATH
+        id: julia_in_path
+        run: which julia
+        continue-on-error: true
+      - name: Install Julia, but only if it is not already available in the PATH
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+          arch: ${{ runner.arch }}
+        if: steps.julia_in_path.outcome != 'success'
+      - name: "Add the General registry via Git"
+        run: |
+          import Pkg
+          ENV["JULIA_PKG_SERVER"] = ""
+          Pkg.Registry.add("General")
+        shell: julia --color=yes {0}
+      - name: "Install CompatHelper"
+        run: |
+          import Pkg
+          name = "CompatHelper"
+          uuid = "aa819f21-2bde-4658-8897-bab36330d9b7"
+          version = "3"
+          Pkg.add(; name, uuid, version)
+        shell: julia --color=yes {0}
+      - name: "Run CompatHelper"
+        run: |
+          import CompatHelper
+          CompatHelper.main()
+        shell: julia --color=yes {0}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+          # COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV }}

docs/make.jl

@@ -30,17 +30,16 @@ makedocs(
     pages = [
         "Introduction" => "index.md",
         "Basic examples" => [
-            "Energy min (abstract syntax)"   => "tutorial-basic-example.md", 
-            "Energy min (functional syntax)" => "tutorial-basic-example-f.md",
-            "Time min (abstract syntax)"     => "tutorial-double-integrator.md",
-            "Time min (functional syntax)"     => "tutorial-double-integrator-f.md",
+            "Energy minimisation" => "tutorial-basic-example.md", 
+            "Time mininimisation" => "tutorial-double-integrator.md",
         ],
         "Manual" => [
-            "Abstract syntax" => "tutorial-abstract.md",
-            "Solve"           => "tutorial-solve.md",
-            "Initial guess"   => "tutorial-initial-guess.md",
-            "Plot a solution" => "tutorial-plot.md",
-            "Flow"            => "tutorial-flow.md",
+            "Abstract syntax"   => "tutorial-abstract.md",
+            "Initial guess"     => "tutorial-initial-guess.md",
+            "Solve"             => "tutorial-solve.md",
+            "Plot a solution"   => "tutorial-plot.md",
+            "Flow"              => "tutorial-flow.md",
+            "Functional syntax" => "tutorial-functional.md",
         ],
         "Tutorials" => [
             "tutorial-continuation.md",
@@ -60,9 +59,9 @@ makedocs(
         "Developers" => [
             "OptimalControl.jl" => "dev-optimalcontrol.md",
             "Subpackages" => [
-                "CTBase.jl" => "dev-ctbase.md",
+                "CTBase.jl"   => "dev-ctbase.md",
                 "CTDirect.jl" => "dev-ctdirect.md",
-                "CTFlows.jl" => "dev-ctflows.md",
+                "CTFlows.jl"  => "dev-ctflows.md",
             ],
         ],
         "JuliaCon 2024"=> "juliacon2024.md",

docs/src/tutorial-basic-example.md

@@ -49,6 +49,10 @@ end
 nothing # hide
 ```
 
+!!! note "Nota bene"
+
+    For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.* There is also a non-standard but more classical functional syntax, check [this tutorial](@ref functional).
+
 ## [Solve and plot](@id basic-solve-plot)
 
 We can solve it simply with:
@@ -64,10 +68,6 @@ And plot the solution with:
 plot(sol)
 ```
 
-!!! note "Nota bene"
-
-    For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.*
-
 ## State constraint
 
 We add the path constraint

docs/src/tutorial-double-integrator.md

@@ -70,7 +70,7 @@ nothing # hide
 
 !!! note "Nota bene"
 
-    For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this tutorial](@ref abstract).
+    For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.* There is also a non-standard but more classical functional syntax, check [this tutorial](@ref functional).
 
 ## Solve and plot
 

docs/src/tutorial-functional.md

@@ -0,0 +1,85 @@
+# [The functional syntax to define an optimal control problem](@id functional)
+
+There are two syntaxes to define an optimal control problem with OptimalControl.jl:
+
+- the standard way is to use the abstract syntax. See for instance [basic example](@ref basic) for a start or for a comprehensive introduction to the abstract syntax, check [this tutorial](@ref abstract).
+- the old-fashioned functional syntax. In this tutorial with give two examples defined with the functional syntax. For more details please check the [`Model` documentation](@ref api-ctbase-model).
+
+## Double integrator: energy minimisation
+
+Let us consider a wagon moving along a rail, whom acceleration can be controlled by a force $u$.
+We denote by $x = (x_1, x_2)$ the state of the wagon, that is its position $x_1$ and its velocity $x_2$.
+
+```@raw html
+<img src="./assets/chariot.png" style="display: block; margin: 0 auto 20px auto;" width="300px">
+```
+
+We assume that the mass is constant and unitary and that there is no friction. The dynamics we consider is given by
+
+```math
+    \dot x_1(t) = x_2(t), \quad \dot x_2(t) = u(t), \quad u(t) \in \R,
+```
+
+which is simply the [double integrator](https://en.wikipedia.org/w/index.php?title=Double_integrator&oldid=1071399674) system.
+Les us consider a transfer starting at time $t_0 = 0$ and ending at time $t_f = 1$, for which we want to minimise the transfer energy
+
+```math
+    \frac{1}{2}\int_{0}^{1} u^2(t) \, \mathrm{d}t
+```
+
+starting from the condition $x(0) = (-1, 0)$ and with the goal to reach the target $x(1) = (0, 0)$.
+
+
+Let us define the problem with the functional syntax.
+
+```@example main
+using OptimalControl
+
+ocp = Model()                                   # empty optimal control problem
+
+time!(ocp, t0=0, tf=1)                          # initial and final times
+state!(ocp, 2)                                  # dimension of the state
+control!(ocp, 1)                                # dimension of the control
+
+constraint!(ocp, :initial; val=[ -1, 0 ])       # initial condition
+constraint!(ocp, :final;   val=[  0, 0 ])       # final condition
+
+dynamics!(ocp, (x, u) -> [ x[2], u ])           # dynamics of the double integrator
+
+objective!(ocp, :lagrange, (x, u) -> 0.5u^2)    # cost in Lagrange form
+nothing # hide
+```
+
+!!! note "Nota bene"
+
+    This problem is defined with the abstract syntax [here](@ref basic).
+
+## Double integrator: time minimisation    
+
+We consider the same optimal control problem where we replace the cost. Instead of minimisation the L2-norm of the control, we consider the time minimisation problem, that is we minimise the final time $t_f$.
+
+```@example main
+ocp = Model(variable=true)                       # variable is true since tf is free
+
+variable!(ocp, 1, :tf)                           # dimension and name of the variable
+time!(ocp, t0=0, indf=1)                         # initial time fixed to 0
+                                                 # final time free and corresponds to the
+                                                 # first component of the variable
+state!(ocp, 2, :x, [:q, :v])                     # dimension of the state with names
+control!(ocp, 1)                                 # dimension of the control
+
+constraint!(ocp, :variable; lb=0)                # tf ≥ 0
+constraint!(ocp, :control; lb=-1, ub=1)          # -1 ≤ u(t) ≤ 1
+constraint!(ocp, :initial; val=[ 1, 2 ])         # initial condition
+constraint!(ocp, :final;   val=[ 0, 0 ])         # final condition
+constraint!(ocp, :state; lb=[-5, -3], ub=[5, 3]) # -5 ≤ q(t) ≤ 5, -3 ≤ v(t) ≤ 3
+
+dynamics!(ocp, (x, u, tf) -> [ x[2], u ])        # dynamics of the double integrator
+
+objective!(ocp, :mayer, (x0, xf, tf) -> tf)      # cost in Mayer form
+nothing # hide
+```
+
+!!! note "Nota bene"
+
+    This problem is defined with the abstract syntax [here](@ref double-int).