From 86f06a7515271a1d25e6e9a4e3c7e74f2079bfb6 Mon Sep 17 00:00:00 2001
From: Olivier Cots <66357348+ocots@users.noreply.github.com>
Date: Thu, 20 Jul 2023 22:36:45 +0200
Subject: [PATCH] update doc

---
 docs/Project.toml   |  1 +
 docs/make.jl        |  3 +-
 docs/src/api.md     | 10 ++-----
 docs/src/dev-api.md | 11 +++++++
 docs/src/index.md   | 70 +++++++++++++++++++++++++++++++++++++++++++--
 5 files changed, 84 insertions(+), 11 deletions(-)
 create mode 100644 docs/src/dev-api.md

diff --git a/docs/Project.toml b/docs/Project.toml
index dfa65cd1..013d2924 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -1,2 +1,3 @@
 [deps]
+CTDirect = "790bbbee-bee9-49ee-8912-a9de031322d5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
diff --git a/docs/make.jl b/docs/make.jl
index e79e6522..1dd6566c 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -6,7 +6,8 @@ makedocs(
     format = Documenter.HTML(prettyurls = false),
     pages = [
         "Introduction" => "index.md",
-        "API" => "api.md"
+        "API" => "api.md",
+        "Developers" => "dev-api.md",
     ]
 )
 
diff --git a/docs/src/api.md b/docs/src/api.md
index bf1508ea..ee69ca48 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -1,15 +1,11 @@
+# API
+
 ```@meta
 CurrentModule = CTDirect 
 ```
 
-```@contents
-Pages = ["api.md"]
-```
-
-# API
-This page is a dump of all the docstrings found in the code. 
-
 ```@autodocs
 Modules = [CTDirect]
 Order = [:module, :type, :function, :macro]
+Private = false
 ```
\ No newline at end of file
diff --git a/docs/src/dev-api.md b/docs/src/dev-api.md
new file mode 100644
index 00000000..de9f0ab2
--- /dev/null
+++ b/docs/src/dev-api.md
@@ -0,0 +1,11 @@
+# Internal functions
+
+```@meta
+CurrentModule = CTDirect 
+```
+
+```@autodocs
+Modules = [CTDirect]
+Order = [:module, :type, :function, :macro]
+Public = false
+```
diff --git a/docs/src/index.md b/docs/src/index.md
index 63bd1c2b..b60321e8 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,4 +1,68 @@
-# CTDirect.jl 
+# CTDirect.jl
 
-## Overview
-This package is ...
\ No newline at end of file
+```@meta
+CurrentModule =  CTDirect
+```
+
+The `CTDirect.jl` package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
+
+!!! note "Install"
+
+    To install a package from the control-toolbox ecosystem, 
+    please visit the [installation page](https://github.com/control-toolbox#installation).
+
+An optimal control problem with fixed initial and final times, denoted (OCP), can be described as minimising the cost functional
+
+```math
+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, 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}
+\psi_l &\le& \psi(t, x(t), u(t)) &\le& \psi_u, \\
+\phi_l &\le& \phi(x(t_0), x(t_f)) &\le& \phi_u.
+\end{array}
+```
+
+The so-called direct approach transforms the infinite dimensional optimal control problem (OCP) into a finite dimensional optimization problem (NLP). This is done by a discretization in time applied to the state and control variables, as well as the dynamics equation. These methods are usually less precise than indirect methods based on [Pontryagin’s Maximum Principle](https://en.wikipedia.org/w/index.php?title=Pontryagin's_maximum_principle&oldid=1160355192), but more robust with respect to the initialization. Also, they are more straightforward to apply, hence their wide use in industrial applications. We refer the reader to for instance[^1] and [^2] for more details on direct transcription methods and NLP algorithms.
+
+[^1]: J. T. Betts. Practical methods for optimal control using nonlinear programming. Society for Industrial and Applied Mathematics (SIAM), Philadelphia, PA, 2001.
+
+[^2]: J. Nocedal and S.J. Wright. Numerical optimization. Springer-Verlag, New York, 1999.****
+
+Summary of the time discretization:
+
+```math
+\begin{array}{lcl}
+t \in [t_0,t_f]   & \to & \{t_0, \ldots, t_N=t_f\}\\[0.2em]
+x(\cdot),\, u(\cdot) & \to & X=\{x_0, \ldots, x_N, u_0, \ldots, u_N\} \\[1em]
+\hline
+\\
+\text{criterion} & \to & \min\ g(x_0, x_N) \\[0.2em]
+\text{dynamics}  & \to & x_{i+i} = x_i + (t_{i+i} - t_i)\, f(t_i, x_i, u_i) ~~ \text{(Euler)}\\[0.2em]
+\text{path constraints} &\to& \psi_l \le \psi(t_i, x_i, u_i) \le \psi_u \\[0.2em]
+\text{limit conditions} &\to& \phi_l \le \phi(x_0, x_N) \le \phi_u
+\end{array}
+```
+
+We therefore obtain a nonlinear programming problem on the discretized state and control variables of the general form:
+
+```math
+(NLP)\quad \left\{
+\begin{array}{lr}
+\min \ F(X) \\
+LB \le C(X) \le UB
+\end{array}
+\right.
+```
+
+We use packages from [JuliaSmoothOptimizers](https://github.com/JuliaSmoothOptimizers) to solve the (NLP) problem.
\ No newline at end of file