docs: add discretization schemes documentation

- Add list of available integration schemes for collocation discretizer
- Document ADNLP-specific Gauss-Legendre schemes (2-point and 3-point)
- Remove Draft=false meta blocks from example files
- Update Manifest.toml

Author: ocots

docs/src/assets/Manifest.toml

@@ -242,9 +242,9 @@ weakdeps = ["OrdinaryDiffEq"]
 
 [[deps.CTModels]]
 deps = ["CTBase", "DocStringExtensions", "LinearAlgebra", "MLStyle", "MacroTools", "OrderedCollections", "Parameters", "RecipesBase"]
-git-tree-sha1 = "c878ed38da4040f618a459c30cec8e53286ddc26"
+git-tree-sha1 = "3e9df6b6cb96ccb05051ded9a5d4f76f649f6d0c"
 uuid = "34c4fa32-2049-4079-8329-de33c2a22e2d"
-version = "0.9.11"
+version = "0.9.12-beta"
 weakdeps = ["JLD2", "JSON3", "Plots"]
 
     [deps.CTModels.extensions]

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

@@ -135,8 +135,10 @@ We are now ready to solve the shooting equations.
 # auxiliary in-place NLE function
 nle!(s, p0, _) = s[:] = S(p0)
 
-# initial guess for the Newton solver
-p0_guess = [1, 1]
+# initial guess for the Newton solver from the direct solution
+t = time_grid(direct_sol) # the time grid as a vector
+p = costate(direct_sol)   # the costate as a function of time
+p0_guess = p(t0)          # initial costate
 
 # NLE problem with initial guess
 prob = NonlinearProblem(nle!, p0_guess)

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

@@ -90,14 +90,14 @@ nothing # hide
 Let us solve it with a direct method (we set the number of time steps to 200):
 
 ```@example main
-sol = solve(ocp; grid_size=200)
+direct_sol = solve(ocp; grid_size=200)
 nothing # hide
 ```
 
 and plot the solution:
 
 ```@example main
-plt = plot(sol; label="Direct", size=(800, 600))
+plt = plot(direct_sol; label="Direct", size=(800, 600))
 ```
 
 !!! note "Nota bene"
@@ -161,15 +161,24 @@ We are now ready to solve the shooting equations:
 # in-place shooting function
 nle!(s, ξ, λ) = shoot!(s, ξ[1:2], ξ[3], ξ[4]) 
 
-# initial guess: costate and final time
-ξ_guess = [0.1, 0.1, 0.5, 1]
+# initial guess for the Newton solver from direct method
+t = time_grid(direct_sol) # the time grid as a vector
+p = costate(direct_sol)   # the costate as a function of time
+p0_guess = p(t0)          # initial costate
+tf_guess = variable(direct_sol) # final time
+
+# find switching time t1 where p2(t) changes sign
+p2_values = [p(ti)[2] for ti in t]
+t1_guess = t[findfirst(i -> i > 1 && p2_values[i] * p2_values[i-1] < 0, 2:length(p2_values))]
+
+ξ_guess = [p0_guess[1], p0_guess[2], t1_guess, tf_guess]
 
 # NLE problem
 prob = NonlinearProblem(nle!, ξ_guess)
 
 # resolution of the shooting equations
-sol = solve(prob; show_trace=Val(true))
-p0, t1, tf = sol.u[1:2], sol.u[3], sol.u[4]
+shoot_sol = solve(prob; show_trace=Val(true))
+p0, t1, tf = shoot_sol.u[1:2], shoot_sol.u[3], shoot_sol.u[4]
 
 # print the solution
 println("\np0 = ", p0, "\nt1 = ", t1, "\ntf = ", tf)
@@ -182,10 +191,10 @@ Finally, we reconstruct and plot the solution obtained by the indirect method:
 φ = f_max * (t1, f_min)
 
 # compute the solution: state, costate, control...
-flow_sol = φ((t0, tf), x0, p0; saveat=range(t0, tf, 200))
+indirect_sol = φ((t0, tf), x0, p0; saveat=range(t0, tf, 200))
 
 # plot the solution on the previous plot
-plot!(plt, flow_sol; label="Indirect", color=2, linestyle=:dash)
+plot!(plt, indirect_sol; label="Indirect", color=2, linestyle=:dash)
 ```
 
 !!! note

docs/src/example-singular-control.md

@@ -77,7 +77,7 @@ Let's plot the solution:
 
 ```@example main
 opt = (state_bounds_style=:none, control_bounds_style=:none)
-plt = plot(direct_sol; label="direct", size=(800, 800), opt...)
+plt = plot(direct_sol; label="Direct", size=(800, 800), opt...)
 ```
 
 ## Singular control by hand
@@ -340,7 +340,7 @@ nothing # hide
 Plot the indirect solution alongside the direct solution:
 
 ```@example main
-plot!(plt, indirect_sol; label="indirect", color=2, linestyle=:dash, opt...)
+plot!(plt, indirect_sol; label="Indirect", color=2, linestyle=:dash, opt...)
 ```
 
 The indirect and direct solutions match very well, confirming that our singular control computation is correct.

docs/src/manual-solve.md

@@ -230,6 +230,22 @@ Each strategy declares its available options. You can inspect them using `descri
 
 ### Discretizer options
 
+The collocation discretizer supports multiple integration schemes:
+
+- `:trapeze` - Trapezoidal rule (second-order accurate)
+- `:midpoint` - Midpoint rule (second-order accurate)  
+- `:euler` or `:euler_explicit` or `:euler_forward` - Explicit Euler method (first-order accurate)
+- `:euler_implicit` or `:euler_backward` - Implicit Euler method (first-order accurate, more stable for stiff problems)
+
+!!! note "Additional schemes with ADNLP modeler"
+
+    When using the `:adnlp` modeler, two additional high-order collocation schemes are available:
+
+    - `:gauss_legendre_2` - 2-point Gauss-Legendre collocation (fourth-order accurate)
+    - `:gauss_legendre_3` - 3-point Gauss-Legendre collocation (sixth-order accurate)
+
+    These schemes provide higher accuracy but require more computational effort.
+
 ```@example main
 describe(:collocation)
 ```