Merge pull request #771 from control-toolbox/macro-free-def

Macro free documentation

Author: ocots

docs/make.jl

@@ -193,6 +193,9 @@ with_api_reference(src_dir, ext_dir) do api_pages
         format=Documenter.HTML(;
             repolink="https://" * repo_url,
             prettyurls=false,
+            example_size_threshold=2_000_000,
+            size_threshold_warn=2_000_000,
+            size_threshold=2_000_000,
             assets=[
                 asset("https://control-toolbox.org/assets/css/documentation.css"),
                 asset("https://control-toolbox.org/assets/js/documentation.js"),
@@ -213,7 +216,10 @@ with_api_reference(src_dir, ext_dir) do api_pages
                 "State constraint" => "example-state-constraint.md",
             ],
             "Manual" => [
-                "Define a problem" => "manual-abstract.md",
+                "Define a problem" => [
+                    "Abstract syntax (@def)" => "manual-abstract.md",
+                    "Functional API (macro-free)" => "manual-macro-free.md",
+                ],
                 "Use AI" => "manual-ai-llm.md",
                 "Problem characteristics" => "manual-model.md",
                 "Set an initial guess" => "manual-initial-guess.md",

docs/src/api/public.md

@@ -41,7 +41,7 @@ boundary_constraints_dual
 boundary_constraints_nl
 bypass
 components
-constraint
+CTModels.OCP.constraint
 constraints
 constraints_violation
 control
@@ -66,7 +66,7 @@ dim_path_constraints_nl
 dim_state_constraints_box
 dim_variable_constraints_box
 dimension
-discretize
+CTDirect.discretize
 dual
 dynamics
 export_ocp_solution
@@ -112,11 +112,11 @@ lagrange
 mayer
 message
 metadata
-methods
+methods()
 model
 name
 nlp_model
-objective
+CTModels.OCP.objective
 ocp_model
 ocp_solution
 option_default
@@ -149,7 +149,7 @@ time
 time_grid
 time_name
 times
-variable
+CTModels.OCP.variable
 variable_components
 variable_constraints_box
 variable_constraints_lb_dual

docs/src/assets/custom.css

@@ -33,4 +33,43 @@
     .responsive-columns-left-priority > div:first-child {
         flex: 1 1 100%;
     }
+}
+
+/* 30% / 70% two-column layout */
+.responsive-columns-30-70 {
+    display: flex;
+    gap: 1rem;
+    align-items: flex-start;
+    margin-bottom: 1em;
+}
+
+.responsive-columns-30-70 > div:first-child {
+    flex: 3;
+    min-width: 0;
+    transition: opacity 0.5s ease-in-out, flex 0.5s ease-in-out, max-width 0.5s ease-in-out, max-height 0.5s ease-in-out;
+}
+
+.responsive-columns-30-70 > div:last-child {
+    flex: 7;
+    min-width: 0;
+    opacity: 1;
+    max-width: 100%;
+    max-height: none;
+    transition: opacity 0.5s ease-in-out, flex 0.5s ease-in-out, max-width 0.5s ease-in-out, max-height 0.5s ease-in-out;
+}
+
+@media (max-width: 700px) {
+    .responsive-columns-30-70 > div:last-child {
+        opacity: 0;
+        max-width: 0;
+        max-height: 0;
+        flex: 0 0 0;
+        overflow: hidden;
+        margin: 0;
+        padding: 0;
+    }
+
+    .responsive-columns-30-70 > div:first-child {
+        flex: 1 1 100%;
+    }
 }

docs/src/index.md

@@ -43,6 +43,57 @@ plot(sol)
 - The [`solve`](@ref) function has many options. See the [solve tutorial](@ref manual-solve).  
 - The [`plot`](@ref) function is flexible. See the [plot tutorial](@ref manual-plot).
 
+## [Mathematical formulation](@id math-formulation)
+
+An optimal control problem (OCP) with fixed initial and final times can be described as minimising the cost functional (in Bolza form)
+
+```math
+J(x, u) = g(x(t_0), x(t_f)) + \int_{t_0}^{t_f} f^{0}(t, x(t), u(t))\,\mathrm{d}t
+```
+
+where the state $x$ and the control $u$ are functions of time $t$, subject for $t \in [t_0, t_f]$ to the differential constraint
+
+```math
+\dot{x}(t) = f(t, x(t), u(t))
+```
+
+and other constraints such as
+
+```math
+\begin{array}{llcll}
+x_{\mathrm{lower}} & \le & x(t)              & \le & x_{\mathrm{upper}}, \\
+u_{\mathrm{lower}} & \le & u(t)              & \le & u_{\mathrm{upper}}, \\
+c_{\mathrm{lower}} & \le & c(t, x(t), u(t))  & \le & c_{\mathrm{upper}}, \\
+b_{\mathrm{lower}} & \le & b(x(t_0), x(t_f)) & \le & b_{\mathrm{upper}}.
+\end{array}
+```
+
+If $g = 0$, the cost is said to be in **Lagrange form**; if $f^0 = 0$, it is in **Mayer form**.
+
+### Free times and extra variables
+
+The initial time $t_0$ and the final time $t_f$ may also be free, that is part of the optimisation variables:
+
+```math
+J(x, u, t_0, t_f) \to \min.
+```
+
+More generally, a vector $v \in \mathbb{R}^k$ of $k$ additional variables can be introduced (it may contain $t_0$, $t_f$, or any other free parameter). The cost, dynamics, and constraints then all depend on $v$:
+
+```math
+J(x, u, v) = g(x(t_0), x(t_f), v) + \int_{t_0}^{t_f} f^{0}(t, x(t), u(t), v)\,\mathrm{d}t \to \min,
+```
+
+```math
+\dot{x}(t) = f(t, x(t), u(t), v),
+```
+
+with, in addition, box constraints on $v$:
+
+```math
+v_{\mathrm{lower}} \le v \le v_{\mathrm{upper}}.
+```
+
 ## Citing us
 
 If you use OptimalControl.jl in your work, please cite us:

docs/src/manual-initial-guess.md

@@ -565,7 +565,7 @@ nothing # hide
 
 !!! tip "Interactions with an optimal control solution"
 
-    Please check [`state`](@ref), [`costate`](@ref), [`control`](@ref) and [`variable`](@ref variable(::Solution)) to get data from the solution. The functions `state`, `costate` and `control` return functions of time and `variable` returns a vector.
+    Please check [`state`](@ref), [`costate`](@ref), [`control`](@ref) and [`variable`](@ref CTModels.OCP.variable) to get data from the solution. The functions `state`, `costate` and `control` return functions of time and `variable` returns a vector.
 
 ## Costate / multipliers