fix merge

control-toolbox · Aug 24, 2024 · d00bcc7 · d00bcc7
2 parents 8e4435b + 411f3a4
commit d00bcc7
Show file tree

Hide file tree

Showing 13 changed files with 275 additions and 211 deletions.
diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@
 # Solution data files
 *.jld2
 *.json
+!.zenodo.json
 
 # System-specific files and directories generated by the BinaryProvider and BinDeps packages
 # They contain absolute paths specific to the host computer, and so should not be committed

diff --git a/.zenodo.json b/.zenodo.json
@@ -0,0 +1,48 @@
+{
+    "description": "<p>The&nbsp;<a href=\"https://juliahub.com/ui/Packages/General/OptimalControl\" rel=\"nofollow\">OptimalControl.jl</a>&nbsp;package is the root package of the&nbsp;<a href=\"https://github.com/control-toolbox\">control-toolbox ecosystem</a>. The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods.</p>",
+    "title": "OptimalControl.jl: a Julia package to modelise and solve optimal control problems with ODE's",
+    "upload_type": "software",
+    "doi": "10.5281/zenodo.13336652",
+    "keywords": [
+      "optimal control",
+      "control of ODE's",
+      "optimization",
+      "direct transcription",
+      "shooting"
+    ],
+     "creators": [
+      {
+        "affiliation": "Université Côte d’Azur, CNRS, Inria, LJAD",
+        "name": "Caillau, Jean-Baptiste",
+        "orcid": "0000-0002-1719-2016"
+      },
+      {
+        "affiliation": "Université Toulouse, CNRS, ENSEEIHT-IRIT",
+        "name": "Cots, Olivier",
+        "orcid": "0000-0002-4703-4369"
+      },
+      {
+        "affiliation": "Université Toulouse, CNRS, ENSEEIHT-IRIT",
+        "name": "Gergaud, Joseph",
+        "orcid": "0009-0005-9825-8652"
+      },
+      {
+        "affiliation": "CAGE team, Inria Paris",
+        "name": "Martinon, Pierre",
+        "orcid": "0000-0003-0571-2376"
+      },
+      {
+        "affiliation": "Inria Sophia Antipolis Méditerranée",
+        "name": "Sed, Sophia"
+      }
+    ],
+    "access_right": "open",
+    "related_identifiers": [
+      {
+        "scheme": "url",
+        "identifier": "https://github.com/control-toolbox/OptimalControl.jl/releases/latest",
+        "relation": "isSupplementTo"
+      }
+    ],
+    "license": "MIT"
+  }
diff --git a/CITATION.bib b/CITATION.bib
@@ -0,0 +1,7 @@
+@software{Caillau_OptimalControl_jl_a_Julia,
+author = {Caillau, Jean-Baptiste and Cots, Olivier and Gergaud, Joseph and Martinon, Pierre and Sed, Sophia},
+doi = {10.5281/zenodo.13336563},
+license = {["MIT"]},
+title = {{OptimalControl.jl: a Julia package to modelise and solve optimal control problems with ODE's}},
+url = {https://control-toolbox.org/OptimalControl.jl}
+}
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,19 +1,39 @@
-cff-version: 1.2.0
-message: "If you use this software, please cite it as below."
+abstract: <p>The&nbsp;<a href="https://juliahub.com/ui/Packages/General/OptimalControl"
+  rel="nofollow">OptimalControl.jl</a>&nbsp;package is the root package of the&nbsp;<a
+  href="https://github.com/control-toolbox">control-toolbox ecosystem</a>. The control-toolbox
+  ecosystem gathers Julia packages for mathematical control and applications. It aims
+  to provide tools to model and solve optimal control problems with ordinary differential
+  equations by direct and indirect methods.</p>
+title: "OptimalControl.jl: a Julia package to modelise and solve optimal control problems with ODE's"
 authors:
-- family-names: "Caillau"
-  given-names: "Jean-Baptiste"
-  orcid: "https://orcid.org/0000-0002-1719-2016"
-- family-names: "Cots"
-  given-names: "Olivier"
-  orcid: "https://orcid.org/0000-0002-4703-4369"
-- family-names: "Gergaud"
-  given-names: "Joseph"
-- family-names: "Martinon"
-  given-names: "Pierre"
-  orcid: "https://orcid.org/0000-0003-0571-2376"
-title: "OptimalControl.jl"
-version: 0.11.2
+- affiliation: "Universit\xE9 C\xF4te d'Azur, CNRS, Inria, LJAD"
+  family-names: Caillau
+  given-names: Jean-Baptiste
+  orcid: 0000-0002-1719-2016
+- affiliation: "Universit\xE9 Toulouse, CNRS, ENSEEIHT-IRIT"
+  family-names: Cots
+  given-names: Olivier
+  orcid: 0000-0002-4703-4369
+- affiliation: "Universit\xE9 Toulouse, CNRS, ENSEEIHT-IRIT"
+  family-names: Gergaud
+  given-names: Joseph
+  orcid: 0009-0005-9825-8652
+- affiliation: CAGE team, Inria Paris
+  family-names: Martinon
+  given-names: Pierre
+  orcid: 0000-0003-0571-2376
+- affiliation: "Inria Sophia Antipolis M\xE9diterran\xE9e"
+  family-names: Sed
+  given-names: Sophia
+cff-version: 1.2.0
 doi: 10.5281/zenodo.13336563
-date-released: 2024-08-17
-url: "https://github.com/control-toolbox/OptimalControl.jl"
+keywords:
+- optimal control
+- control of ODE's
+- optimization
+- direct transcription
+- shooting
+license:
+- MIT
+url: "https://control-toolbox.org/OptimalControl.jl"
+type: software
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "OptimalControl"
 uuid = "5f98b655-cc9a-415a-b60e-744165666948"
 authors = ["Olivier Cots <[email protected]>"]
-version = "0.11.2"
+version = "0.11.3"
 
 [deps]
 CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# OptimalControl
+# OptimalControl.jl
 
 [ci-img]: https://github.com/control-toolbox/OptimalControl.jl/actions/workflows/CI.yml/badge.svg?branch=main
 [ci-url]: https://github.com/control-toolbox/OptimalControl.jl/actions/workflows/CI.yml?query=branch%3Amain
@@ -12,26 +12,101 @@
 [doc-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
 [doc-stable-url]: https://control-toolbox.org/OptimalControl.jl/stable/
 
-[release-img]: https://img.shields.io/github/v/release/control-toolbox/OptimalControl.jl.svg?style=round-square
+[release-img]: https://juliahub.com/docs/General/OptimalControl/stable/version.svg
 [release-url]: https://github.com/control-toolbox/OptimalControl.jl/releases
 
-The [OptimalControl.jl](https://juliahub.com/ui/Packages/General/OptimalControl) package is the root package of the [control-toolbox ecosystem](https://github.com/control-toolbox).
-The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems by direct and indirect methods.
+[pkg-eval-img]: https://juliahub.com/docs/General/OptimalControl/stable/pkgeval.svg
+[pkg-eval-url]: https://juliahub.com/ui/Packages/General/OptimalControl
 
-| **Documentation**  | **Code Status**  | **Release**  | **Citation** |
-|:-------------------|:-----------------|:-------------|:-------------|
-| [![Documentation][doc-stable-img]][doc-stable-url] [![Documentation][doc-dev-img]][doc-dev-url] | [![Build Status][ci-img]][ci-url] [![Covering Status][co-img]][co-url] | [![Release][release-img]][release-url] | [![DOI](https://zenodo.org/badge/541187171.svg)](https://zenodo.org/doi/10.5281/zenodo.13336563) |
+[citation-img]: https://zenodo.org/badge/541187171.svg
+[citation-url]: https://zenodo.org/doi/10.5281/zenodo.13336563
+
+[licence-img]: https://img.shields.io/badge/License-MIT-yellow.svg
+[licence-url]: https://github.com/control-toolbox/OptimalControl.jl/blob/master/LICENSE
+
+The OptimalControl.jl package is the root package of the [control-toolbox ecosystem](https://github.com/control-toolbox).
+The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods.
+
+| **Name**          | **Badge**         |
+:-------------------|:------------------|
+| Documentation     | [![Documentation][doc-stable-img]][doc-stable-url] [![Documentation][doc-dev-img]][doc-dev-url]                   | 
+| Code Status       | [![Build Status][ci-img]][ci-url] [![Covering Status][co-img]][co-url] [![pkgeval][pkg-eval-img]][pkg-eval-url]   |
+| Licence           | [![License: MIT][licence-img]][licence-url]   |
+| Release           | [![Release][release-img]][release-url]        |
+| Citation          | [![DOI][citation-img]][citation-url]          |
 
 ## Installation
 
-To install a package from the control-toolbox ecosystem, please visit the [installation page](https://github.com/control-toolbox#installation). To install [OptimalControl.jl](https://github.com/control-toolbox/OptimalControl.jl) please <a href="https://docs.julialang.org/en/v1/manual/getting-started/">open
-Julia's interactive session (known as REPL)</a> and press <kbd>]</kbd> key in the REPL to use the package mode, then add the package:
+To install OptimalControl.jl please 
+<a href="https://docs.julialang.org/en/v1/manual/getting-started/">open Julia's interactive session (known as REPL)</a> 
+and press <kbd>]</kbd> key in the REPL to use the package mode, then add the package:
 
 ```julia
 julia> ]
 pkg> add OptimalControl
 ```
 
+## Basic usage
+
+Let us modelise, solve and plot a simple optimal control problem.
+
+```julia
+using OptimalControl
+using NLPModelsIpopt
+using Plots
+
+ocp = @def begin
+    t ∈ [0, 1], time
+    x ∈ R², state
+    u ∈ R, control
+    x(0) == [ -1, 0 ]
+    x(1) == [ 0, 0 ]
+    ẋ(t) == [ x₂(t), u(t) ]
+    ∫( 0.5u(t)^2 ) → min
+end
+
+sol = solve(ocp)
+
+plot(sol)
+```
+
+For more details about this problem, please check the
+[basic example tutorial](https://control-toolbox.org/OptimalControl.jl/stable/tutorial-basic-example.html). 
+For a comprehensive introduction to the syntax used above to describe the optimal control problem, check the
+[abstract syntax tutorial](https://control-toolbox.org/OptimalControl.jl/stable/tutorial-abstract.html#abstract).
+
+## How to cite
+
+If you use OptimalControl.jl in your work, please cite us:
+
+> Caillau, J., Cots, O., Gergaud, J., Martinon, P., & Sed, S. *OptimalControl.jl: a Julia package to modelise and solve optimal control problems with ODE's* [Computer software]. https://doi.org/10.5281/zenodo.13336563
+
+or in bibtex format:
+
+```bibtex
+@software{Caillau_OptimalControl_jl_a_Julia,
+author = {Caillau, Jean-Baptiste and Cots, Olivier and Gergaud, Joseph and Martinon, Pierre and Sed, Sophia},
+doi = {10.5281/zenodo.13336563},
+license = {["MIT"]},
+title = {{OptimalControl.jl: a Julia package to modelise and solve optimal control problems with ODE's}},
+url = {https://control-toolbox.org/OptimalControl.jl}
+}
+```
+
+## Contributing
+
+[issue-url]: https://github.com/control-toolbox/OptimalControl.jl/issues
+[first-good-issue-url]: https://github.com/control-toolbox/OptimalControl.jl/contribute
+
+If you think you found a bug or if you have a feature request or suggestion, feel free to open an [issue][issue-url].
+Before opening a pull request, start an issue or a discussion on the topic, please. 
+
+Any contributions are welcomed, check out [how to contribute to a Github project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project). 
+If it is your first contribution, you can also check [this first contribution tutorial](https://github.com/firstcontributions/first-contributions).
+You can find first good issues, if any, at the [first good issues page][first-good-issue-url]. You may find other packages to contribute to at the [control-toolbox organization](https://github.com/control-toolbox).
+
+If you want to ask a question, feel free to start a discussion [here](https://github.com/orgs/control-toolbox/discussions). This forum is for general discussion about this repository and the [control-toolbox organization](https://github.com/control-toolbox), so questions about any of our packages are welcome.
+
 ## See also
 
 We acknowledge support of colleagues from [ADNLPModels](https://jso.dev/ADNLPModels.jl/stable) @[Julia Smooth Optimizers](https://jso.dev).
diff --git a/docs/make.jl b/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",
+            "Solve"                 => "tutorial-solve.md",
             "Plot a solution"       => "tutorial-plot.md",
             "Flow"                  => "tutorial-flow.md",
+            "Functional syntax"     => "tutorial-functional.md",
             "Control-toolbox REPL"  => "tutorial-repl.md",
         ],
         "Tutorials" => [
@@ -61,9 +60,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",

diff --git a/docs/src/tutorial-abstract.md b/docs/src/tutorial-abstract.md
@@ -22,7 +22,7 @@ using OptimalControl #hide
 end
 ```
 
-Aliases `v₁`, `v₂` (and `v1`, v2`) are automatically defined and can be used in subsequent expressions instead of `v[1]` and `v[2]`. The user can also define her own aliases for the components (one alias per dimension):
+Aliases `v₁`, `v₂` (and `v1`, `v2`) are automatically defined and can be used in subsequent expressions instead of `v[1]` and `v[2]`. The user can also define her own aliases for the components (one alias per dimension):
 
 ```@example main
 @def begin

diff --git a/docs/src/tutorial-basic-example-f.md b/docs/src/tutorial-basic-example-f.md