-stats.status</code></pre><h3 id="Nonlinear-Least-Squares-(NLS)-Problems"><a class="docs-heading-anchor" href="#Nonlinear-Least-Squares-(NLS)-Problems">Nonlinear Least Squares (NLS) Problems</a><a id="Nonlinear-Least-Squares-(NLS)-Problems-1"></a><a class="docs-heading-anchor-permalink" href="#Nonlinear-Least-Squares-(NLS)-Problems" title="Permalink"></a></h3><p>If your problem is a nonlinear least squares (NLS), please follow these guidelines:</p><ul><li>Set the <code>:objtype</code> entry in the meta file to <code>:least_squares</code>.</li><li>Add a getter for the number of NLS equations, named <code>get_problemname_nls_nequ</code>.</li><li>Support the <code>use_nls=true/false</code> keyword to allow both <code>ADNLPModel</code> and <code>ADNLSModel</code> instantiation from the same problem.</li><li>Instantiate both <code>ADNLPModel</code> and <code>ADNLSModel</code>, ensure <code>residual!(nls, x, Fx)</code> is allocation-free, and check that objectives agree (or differ by a factor of 2 for LS).</li><li>In the <code>PureJuMP</code> 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.</li><li>Explicitly state that the NLS variant can be accessed by passing the keyword argument <code>use_nls=true</code> when constructing the problem.</li><li>Make sure this information is also reflected in the meta file, so users and tools can easily discover the NLS capability.</li><li>In validation, also run the local solver sanity check with <code>problem_name(use_nls=true)</code>.</li></ul><p>See existing NLS problems (e.g., <a href="https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/ADNLPProblems/lanczos1.jl"><code>lanczos1</code></a>, <a href="https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/ADNLPProblems/lanczos2.jl"><code>lanczos2</code></a>, <a href="https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/ADNLPProblems/brownal.jl"><code>brownal</code></a>) for templates.</p><h2 id="Reviewer-Checklist-for-New-Problems"><a class="docs-heading-anchor" href="#Reviewer-Checklist-for-New-Problems">Reviewer Checklist for New Problems</a><a id="Reviewer-Checklist-for-New-Problems-1"></a><a class="docs-heading-anchor-permalink" href="#Reviewer-Checklist-for-New-Problems" title="Permalink"></a></h2><ul><li>[ ] First check: the problem is added in exactly these three files with the same base name: <code>src/ADNLPProblems/problem_name.jl</code>, <code>src/PureJuMP/problem_name.jl</code>, and <code>src/Meta/problem_name.jl</code>. Example: <a href="https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/ADNLPProblems/arglina.jl"><code>arglina</code> in ADNLPProblems</a>, <a href="https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/PureJuMP/arglina.jl"><code>arglina</code> in PureJuMP</a>, and <a href="https://github.com/JuliaSmoothOptimizers/OptimizationProblems.jl/blob/main/src/Meta/arglina.jl"><code>arglina</code> in Meta</a>.</li></ul><p><strong>Meta</strong></p><ul><li>[ ] The corresponding meta file exists (<code>src/Meta/problem_name.jl</code>), the problem name matches the AD and JuMP files, and <code>OptimizationProblems.meta</code> contains the problem entry.</li><li>[ ] All meta fields (origin, objtype, contype, bounds, best-known, etc.) are filled correctly.</li><li>[ ] The problem origin/provenance is clearly documented and consistent between the <code>PureJuMP</code> problem documentation and the <code>:origin</code> meta entry.</li><li>[ ] Meta formulas for variable sizes match actual model behavior.</li></ul><p><strong>Definition</strong></p><ul><li>[ ] No extra or spurious exports are introduced.</li><li>[ ] The problem function is exported in <code>src/ADNLPProblems/problem_name.jl</code> and <code>src/PureJuMP/problem_name.jl</code>, and not exported in <code>src/Meta/problem_name.jl</code>.</li><li>[ ] Model name matches the file and function name.</li><li>[ ] The implemented objective, constraints, and bounds match the mathematical problem definition from the cited reference/documentation.</li></ul><p><strong>Implementation</strong></p><ul><li>[ ] Objective and constraint values agree (ADNLPProblems vs PureJuMP) within tolerance at test points.</li><li>[ ] Number of variables and constraints match.</li><li>[ ] For <code>type::Type{T}</code>, <code>x0 isa Vector{T}</code> and objective values are of type <code>T</code>.</li><li>[ ] <code>ADNLPModel</code>/<code>ADNLSModel</code> constructors receive a meaningful <code>name</code> keyword.</li></ul><p><strong>Sanity</strong></p><ul><li>[ ] Objective is callable at the starting point and does not return NaN (unless documented).</li><li>[ ] Model instantiates without error for different types, e.g. Float32 and Float64.</li><li>[ ] For scalable problems, changing <code>n</code> updates <code>nvar</code> and all related meta fields, and the effective number of variables remains as close as possible to the requested <code>n</code> when internal adjustments are required.</li></ul><p><strong>Zero-Allocation</strong></p><ul><li>[ ] All in-place APIs (constraints, residuals) are allocation-free.</li><li>[ ] No unnecessary allocations in tight loops or callbacks.</li><li>[ ] Objective evaluation has minimal allocations (ideally allocation-free in performance-critical paths).</li></ul><p><strong>Least-Squares & In-Place APIs</strong></p><ul><li>[ ] If least squares, ADNLP constructor supports <code>nls=true/false</code> for both ADNLPModel and ADNLSModel.</li><li>[ ] In-place nonlinear constraint evaluations (<code>cons_nln!(nlp, x, cx)</code>) and least squares residuals (<code>residual!</code>) are allocation-free.</li><li>[ ] For least squares problems, objectives for NLP and NLS must agree (or differ by a factor of 2, as appropriate).</li></ul></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../reference/">« Reference</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.17.0 on <span class="colophon-date" title="Friday 15 May 2026 16:40">Friday 15 May 2026</span>. Using Julia version 1.12.6.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
0 commit comments