Documentation for nonlinear least squares (NLS) problems

docs/src/contributing.md

@@ -72,3 +72,12 @@ function function_name(; n::Int = default_nvar, type::Type{T} = Float64, kwargs.
   return nlp
 end
 ```
+
+### Nonlinear Least Squares (NLS) Problems
+
+If your problem is a nonlinear least squares (NLS), please follow these guidelines:
+* Use `ADNLSModels` for the ADNLPProblems implementation (see [ADNLPModels.jl](https://github.com/JuliaSmoothOptimizers/ADNLPModels.jl)).
+* Set the `:objtype` entry in the meta file to `:least_squares`.
+* Add a getter for the number of NLS equations, named `get_problemname_nls_nequ`.
+* Document the provenance and structure of the NLS problem in the `PureJuMP` file. Ensure the documentation and meta clarify that the problem is NLS and how to access it.
+* See existing NLS problems (e.g., `lanczos1`, `lanczos2`, `brownal`) for templates.

docs/src/meta.md

@@ -17,7 +17,7 @@ OptimizationProblems.AMPGO02_meta
 ```
 See `? OptimizationProblems.meta` for more documentation on the various entries and their default values.
 
-This structre is completed by getters to access the number of variables, `get_nameoftheproblem_nvar`,the number of constraints, `get_nameoftheproblem_ncon`, the number of linear constraints, `get_nameoftheproblem_nlin`, the number of nonlinear constraints, `get_nameoftheproblem_nnln`, the number of equality constraints, `get_nameoftheproblem_nequ`, and the number of inequality constraints, `get_nameoftheproblem_nineq`.
+This structure is completed by getters to access the number of variables, `get_nameoftheproblem_nvar`, the number of constraints, `get_nameoftheproblem_ncon`, the number of linear constraints, `get_nameoftheproblem_nlin`, the number of nonlinear constraints, `get_nameoftheproblem_nnln`, the number of equality constraints, `get_nameoftheproblem_nequ`, and the number of inequality constraints, `get_nameoftheproblem_nineq`.
 ```@example 1
 OptimizationProblems.get_AMPGO02_nvar()
 ```
@@ -50,3 +50,14 @@ adproblems = (
   eval(Meta.parse("ADNLPProblems.$(pb[:name])()")) for pb in eachrow(names_pb_vars)
 )
 ```
+
+### Nonlinear Least Squares (NLS) Problems
+
+Problems with `:objtype` set to `:least_squares` are nonlinear least squares (NLS) problems. For these, you can access the number of NLS equations using a getter like `get_problemname_nls_nequ()`.
+```@example 1
+OptimizationProblems.get_lanczos1_nls_nequ()
+```
+To filter all NLS problems in the metadata DataFrame:
+```@example 1
+nls_problems = OptimizationProblems.meta[OptimizationProblems.meta.objtype .== :least_squares, :name]
+```

docs/src/tutorial.md

@@ -47,7 +47,7 @@ using OptimizationProblems, OptimizationProblems.ADNLPProblems
 problems = OptimizationProblems.meta[!, :name]
 length(problems)
 ```
-Similarly, to the PureJuMP models, it suffices to select any of this problem to get the model.
+Similarly, to the PureJuMP models, it suffices to select any of these problems to get the model.
 ``` @example ex2
 nlp = zangwil3()
 ```
@@ -62,8 +62,25 @@ One of the advantages of these problems is that they are type-stable. Indeed, on
 ``` @example ex2
 nlp16_12 = woods(n=12, type=Float16)
 ```
-Then, all the API will be compatible with the precised type.
+Then, all the API will be compatible with the specified type.
 ``` @example ex2
 using NLPModels
 obj(nlp16_12, zeros(Float16, 12))
 ```
+
+### Nonlinear Least Squares (NLS) Problems
+
+Some problems are classified as nonlinear least squares (NLS). These problems:
+- Have `:objtype` set to `:least_squares` in their meta data.
+- Use `ADNLSModels` for the ADNLPProblems implementation.
+- Provide a getter for the number of NLS equations, e.g., `get_lanczos1_nls_nequ()`.
+
+To list all NLS problems:
+```julia
+nls_problems = OptimizationProblems.meta[OptimizationProblems.meta.objtype .== :least_squares, :name]
+```
+To access the number of NLS equations for a problem:
+```julia
+OptimizationProblems.get_lanczos1_nls_nequ()
+```
+See existing NLS problems (e.g., `lanczos1`, `lanczos2`, `brownal`) for templates.