diff --git a/docs/src/meta.md b/docs/src/meta.md index f22909d4..2b4112af 100644 --- a/docs/src/meta.md +++ b/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,13 @@ adproblems = ( eval(Meta.parse("ADNLPProblems.$(pb[:name])()")) for pb in eachrow(names_pb_vars) ) ``` + +### Nonlinear Least Squares Problems (NLS) +Problems with `:objtype` set to `:least_squares` are nonlinear least squares problems (NLS). For these, you can access the number of NLS equations using a getter like `get_nameoftheproblem_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] +``` \ No newline at end of file diff --git a/docs/src/tutorial.md b/docs/src/tutorial.md index ab7ba9ce..49e1afdf 100644 --- a/docs/src/tutorial.md +++ b/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,31 @@ 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 Problems (NLS) + +Some problems are classified as nonlinear least squares (NLS). These problems may provide both an `ADNLPModel` and an `ADNLSModel` implementation, and dispatch to one or the other using the `use_nls` keyword argument, see [`arglina`](https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/ADNLPProblems/arglina.jl) for a concrete example of this pattern. + +Using `ADNLSModel` can be preferable when a solver exploits the least-squares structure directly (residual vector and Jacobian), which is often more efficient and numerically robust than treating the same problem as a generic nonlinear program (`ADNLPModel`). + +To obtain the least squares model (`ADNLSModel`), use the `use_nls=true` keyword argument when constructing the problem: +``` @example ex2 +lanczos1_nlp = lanczos1() +lanczos1_nls = lanczos1(use_nls=true) +typeof(lanczos1_nlp) +typeof(lanczos1_nls) +``` + +To list all NLS problems: +``` @example ex2 +nls_problems = OptimizationProblems.meta[OptimizationProblems.meta.objtype .== :least_squares, :name] +``` +To access the number of NLS equations for a problem: +``` @example ex2 +OptimizationProblems.get_lanczos1_nls_nequ() +``` \ No newline at end of file