docs: add functional API documentation with mathematical formulation

Author: ocots

docs/make.jl

@@ -213,7 +213,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/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: