From f40614798f514f5a476dd791e5fe29c1a220db9d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alonso=20Mart=C3=ADnez=20Cisneros?= <alonso.mtz99@gmail.com>
Date: Thu, 15 Aug 2024 18:34:34 +0200
Subject: [PATCH] Documented translation layer

---
 docs/pages.jl                               |  3 +-
 docs/src/optimization_packages/nlpmodels.md | 58 +++++++++++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/optimization_packages/nlpmodels.md

diff --git a/docs/pages.jl b/docs/pages.jl
index cc69fa3cb..07a3ebf63 100644
--- a/docs/pages.jl
+++ b/docs/pages.jl
@@ -36,6 +36,7 @@ pages = ["index.md",
         "PRIMA.jl" => "optimization_packages/prima.md",
         "Polyalgorithms.jl" => "optimization_packages/polyopt.md",
         "QuadDIRECT.jl" => "optimization_packages/quaddirect.md",
-        "SpeedMapping.jl" => "optimization_packages/speedmapping.md"
+        "SpeedMapping.jl" => "optimization_packages/speedmapping.md",
+        "NLPModels.jl" => "optimization_packages/nlpmodels.md"
     ]
 ]
diff --git a/docs/src/optimization_packages/nlpmodels.md b/docs/src/optimization_packages/nlpmodels.md
new file mode 100644
index 000000000..f9b8f0a5c
--- /dev/null
+++ b/docs/src/optimization_packages/nlpmodels.md
@@ -0,0 +1,58 @@
+# NLPModels.jl
+
+[NLPModels](https://jso.dev/NLPModels.jl/latest/), similarly to Optimization.jl itself,
+provides a standardized modeling interface for representing Non-Linear Programs that
+facilitates using different solvers on the same problem. The Optimization.jl extension of
+NLPModels aims to provide a thin translation layer to make `NLPModel`s, the main export of
+the package, compatible with the optimizers in the Optimization.jl ecosystem.
+
+## Installation: NLPModels.jl
+
+To translate an `NLPModel`, install the OptimizationNLPModels package:
+
+```julia
+import Pkg;
+Pkg.add("OptimizationNLPModels")
+```
+
+The package NLPModels.jl itself containts no optimizers or models. Several packages
+provide optimization problem ([CUTEst.jl](https://jso.dev/CUTEst.jl/stable/),
+[NLPModelsTest.jl](https://jso.dev/NLPModelsTest.jl/dev/)) which can then be solved with
+any optimizer supported by Optimization.jl
+
+## Usage
+
+For example, solving a problem defined in `NLPModelsTest` with
+[`Ipopt.jl`](https://github.com/jump-dev/Ipopt.jl). First, install the packages like so:
+
+```julia
+import Pkg;
+Pkg.add("NLPModelsTest", "Ipopt")
+```
+
+We instantiate [problem
+10](https://jso.dev/NLPModelsTest.jl/dev/reference/#NLPModelsTest.HS10) in the
+Hock--Schittkowski optimization suite available from `NLPModelsTest` as `HS10`, then
+translate it to an `OptimizationProblem`.
+
+```@example NLPModels
+using OptimizationNLPModels, Optimization, NLPModelsTest, Ipopt 
+nlpmodel = NLPModelsTest.HS10()
+prob = OptimizationProblem(nlpmodel, AutoForwardDiff())
+```
+
+which can now be solved like any other `OptimizationProblem`:
+
+```@example NLPModels
+sol = solve(prob, Ipopt.Optimizer())
+```
+
+## API
+
+Problems represented as `NLPModel`s can be used to create `OptimizationProblem`s and
+`OptimizationFunction`.
+
+```@docs
+SciMLBase.OptimizationFunction(::AbstractNLPModel, ::ADTypes.AbstractADType)
+SciMLBase.OptimizationProblem(::AbstractNLPModel, ::ADTypes.AbstractADType)
+```
\ No newline at end of file