Documentation for nonlinear least squares (NLS) problems#411
Documentation for nonlinear least squares (NLS) problems#411arnavk23 wants to merge 3 commits intoJuliaSmoothOptimizers:mainfrom
Conversation
…ssification, implementation, and usage for contributors and users.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #411 +/- ##
===========================================
- Coverage 99.80% 54.34% -45.47%
===========================================
Files 1084 1138 +54
Lines 12319 13371 +1052
===========================================
- Hits 12295 7266 -5029
- Misses 24 6105 +6081 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
| end | ||
| ``` | ||
|
|
||
| ### Nonlinear Least Squares (NLS) Problems |
There was a problem hiding this comment.
Can we do this in the other PR ? so that we have one PR modifying contributing and we will able to merge this one quickly
| - See [`arglina`](https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/ADNLPProblems/arglina.jl) for a concrete example of this pattern. | ||
|
|
||
| To obtain the least-squares model (`ADNLSModel`), use the `use_nls=true` keyword argument when constructing the problem: | ||
| ```julia |
| ```julia | ||
| # Standard nonlinear model (ADNLPModel) | ||
| lanczos1_nlp = lanczos1() | ||
| # Least-squares model (ADNLSModel) |
There was a problem hiding this comment.
it's better to illustrate than add a comment. Maybe show the type or a residual call.
docs/src/tutorial.md
Outdated
| obj(nlp16_12, zeros(Float16, 12)) | ||
| ``` | ||
|
|
||
| ### Nonlinear Least Squares (NLS) Problems |
There was a problem hiding this comment.
We should have a sentence somewhere that explains why it would be better to have ADNLSModel than ADNLPModel.
Co-authored-by: Tangi Migot <tangi.migot@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation to better explain how nonlinear least squares (NLS) problems are represented and accessed in OptimizationProblems.jl, and fixes a couple of tutorial typos.
Changes:
- Add NLS user-facing documentation to the tutorial and metadata pages (including how to filter NLS problems and query
*_nls_nequ). - Add contributor guidelines for implementing NLS problems.
- Fix minor wording/typos in existing docs.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/src/tutorial.md | Adds a new NLS section describing use_nls=true usage and discovery via meta. |
| docs/src/meta.md | Documents the :objtype == :least_squares classification and get_*_nls_nequ() getters; adds filtering example. |
| docs/src/contributing.md | Adds contributor guidance for adding NLS problems (metadata + getters + construction pattern). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * 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`. | ||
| * In the `PureJuMP` file, clearly document that the problem is a nonlinear least squares (NLS) problem and explain how users can construct both the standard and NLS variants. | ||
| * Explicitly state that the NLS variant can be accessed by passing the keyword argument `use_nls=true` when constructing the problem, e.g.: | ||
| ```julia | ||
| # Standard model (ADNLPModel) | ||
| myprob_nlp = myprob() | ||
| # Least-squares model (ADNLSModel) |
There was a problem hiding this comment.
The NLS contributor guideline currently says to use ADNLSModels and links to ADNLPModels.jl, but this repository’s NLS implementations construct NLS models via ADNLPModels.ADNLSModel! (there is no ADNLSModels dependency in the project). Please update this bullet to reference ADNLPModels (and the ADNLSModel!/ADNLSModel API) to avoid sending contributors to a non-existent/unused package.
| * 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`. | |
| * In the `PureJuMP` file, clearly document that the problem is a nonlinear least squares (NLS) problem and explain how users can construct both the standard and NLS variants. | |
| * Explicitly state that the NLS variant can be accessed by passing the keyword argument `use_nls=true` when constructing the problem, e.g.: | |
| ```julia | |
| # Standard model (ADNLPModel) | |
| myprob_nlp = myprob() | |
| # Least-squares model (ADNLSModel) | |
| * Use the NLS constructors from `ADNLPModels` (e.g., `ADNLPModels.ADNLSModel!` / `ADNLPModels.ADNLSModel`) 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`. | |
| * In the `PureJuMP` file, clearly document that the problem is a nonlinear least squares (NLS) problem and explain how users can construct both the standard and NLS variants. | |
| * Explicitly state that the NLS variant can be accessed by passing the keyword argument `use_nls=true` when constructing the problem, e.g.: | |
| ```julia | |
| # Standard model (ADNLPModels.ADNLPModel) | |
| myprob_nlp = myprob() | |
| # Least-squares model (ADNLPModels.ADNLSModel) |
| 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. | ||
|
|
||
| To obtain the least squares model (`ADNLSModel`), use the `use_nls=true` keyword argument when constructing the problem: | ||
| ```julia | ||
| # Standard nonlinear model (ADNLPModel) | ||
| lanczos1_nlp = lanczos1() | ||
| # Least-squares model (ADNLSModel) | ||
| lanczos1_nls = lanczos1(use_nls=true) | ||
| ``` |
There was a problem hiding this comment.
In this tutorial page, all earlier snippets use @example ex2 so they are executed and kept in sync with the API. The new NLS snippets use plain ```julia fences, which won’t be executed during docs build and can silently drift. Consider switching these blocks to ``@example ex2 (or explicitly note they are non-executable).
| ``` | ||
| To filter all NLS problems in the metadata DataFrame: | ||
| ```@example 1 | ||
| nls_problems = OptimizationProblems.meta[OptimizationProblems.meta.objtype .== :least_squares, :name] |
There was a problem hiding this comment.
This @example ends with an assignment to nls_problems, so Documenter will print the full vector of NLS problem names in the rendered docs. That output is likely very long and noisy; consider suppressing output (trailing ;) or making the last expression something concise like length(nls_problems) / first(nls_problems, 10).
| nls_problems = OptimizationProblems.meta[OptimizationProblems.meta.objtype .== :least_squares, :name] | |
| nls_problems = OptimizationProblems.meta[OptimizationProblems.meta.objtype .== :least_squares, :name]; | |
| first(nls_problems, 10) |
| ) | ||
| ``` | ||
|
|
||
| ### Nonlinear Least Squares Problems (NLS) |
There was a problem hiding this comment.
There is trailing whitespace at the end of this Markdown heading. It’s harmless but tends to create noisy diffs and can violate whitespace linting in some setups; please remove the extra space.
| ### Nonlinear Least Squares Problems (NLS) | |
| ### Nonlinear Least Squares Problems (NLS) |
Connected to #162
@dpo @tmigot