review-purejump

name	review-purejump
description	Review a src/PureJuMP/<name>.jl file for correctness, signature conventions, n-adjustment, start-value coverage, and cross-compatibility with the ADNLPProblems sibling. Reports findings as Errors (test-suite failures), Warnings (likely issues requiring judgment), and Info (notable but valid observations).
argument-hint	<problem-name>
allowed-tools	["Read","Glob","Grep","Bash"]

review-purejump

Audit a single src/PureJuMP/<name>.jl file against every rule enforced by the test suite, contributing guidelines, and module-loading conventions.

Arguments

The user invoked this skill with: $ARGUMENTS

This must be a problem name (e.g. hs100, arglina). Strip a leading src/PureJuMP/ prefix or trailing .jl suffix if present.

If $ARGUMENTS is empty after stripping, ask the user to provide a problem name (e.g. /review-purejump hs100) and stop — do not try to infer from the open file.

---

Instructions

Follow these steps in order.

Step 1 — Read the files

1. Read src/PureJuMP/<name>.jl in full.
2. Glob-check whether the sibling files exist:
   • src/ADNLPProblems/<name>.jl
   • src/Meta/<name>.jl

Step 2 — Detect problem characteristics from the file text

Before running checks, determine the following from the file content. Do NOT read the sibling files.

• Is scalable? — n is actually referenced in the function body beyond the signature (used to define variables, constraints, or expressions, not just forwarded).
• Has n-adjustment? — the body modifies n before using it (e.g. n = 4 * div(n, 4), n = max(2, n)).
• Uses old @warn pattern? — contains @warn(" (raw warn call) rather than @adjust_nvar_warn.
• Has nonlinear constraints? — any @constraint (or @NLconstraint) with a nonlinear expression involving variables.
• Has linear constraints? — any @constraint with a purely linear expression involving variables.
• Has variable bounds? — any @variable with lb ≤ x ≤ ub syntax or scalar bound.
• Multi-function file? — more than one function name appears in the export statement(s), e.g. export dixmaane, dixmaanf, ....
• Data-loading file? — calls _ensure_data! or include("../../data/...").
• Has NLS objective? — src/Meta/<name>.jl exists and contains :objtype => :least_squares.

Step 3 — Static analysis

Scan the text of src/PureJuMP/<name>.jl and collect findings under three severity levels.

Structural (→ Error)

• The file contains at least one export statement.
• At least one exported symbol matches the filename base <name>. This is how names(PureJuMP) resolves the problem, and the test @test setdiff(union(names(PureJuMP), ...), list_problems) == [:PureJuMP] depends on it.
• Every symbol listed in export is defined as a function in this file. Exporting names from other modules would pollute PureJuMP.
• A function named <name> is defined in the file.
• The file does NOT call ADNLPModel, ADNLPModel!, ADNLSModel, or ADNLSModel!. Those constructors belong exclusively in src/ADNLPProblems/.
• The function signature does NOT contain type::Type{T} or where {T}. Type-parametric dispatch is an ADNLP-only pattern; JuMP handles numeric types internally.
• kwargs... is present as the last keyword argument in every exported function's signature. Without it, callers that forward options will raise an error.
• The function body creates a Model() (or Model(optimizer)) and returns it. Returning nothing, an NLPModel, or any other type is wrong.
• The function body contains @objective. A JuMP model with no objective is not a valid NLP.

Start values (→ Error)

• Every @variable call specifies a start = ... value inline, OR the variables are initialized via set_start_value.(...) after the macro. Missing start values default to 0.0, which will disagree with the x0 vector in the ADNLPProblems sibling; the test nlp_jump.meta.x0 == nlp_ad.meta.x0 will then fail.

  Accepted patterns: @variable(nlp, x[i=1:n], start = 1.0), @variable(nlp, x[i=1:n], start = x0[i]), set_start_value.(x, x0).

Signature (→ Error)

• If the problem is scalable (n used in body): n::Int = default_nvar must appear as a keyword argument. The default must reference the module constant default_nvar, not a raw integer.

n-adjustment (→ Error when test is affected, → Warning for soft cases)

• Error — If n is adjusted internally such that get_<name>_nvar(n=50) ≠ 50 or get_<name>_nvar(n=100) ≠ 100, the file must use @adjust_nvar_warn("<name>", n_orig, n). The test test-defined-problems.jl matches exactly the message emitted by this macro ("number of variables adjusted from N to M"). Any other warning format causes the test to fail.
• Error — If @adjust_nvar_warn is used, the original requested n must be saved first (e.g. n_orig = n) before any modification. The first argument to the macro must be the string literal problem name; the second must be the un-modified n; the third must be the adjusted n.
• Warning — If the file uses the old raw @warn("name: ...") pattern for a minimum-size guard (e.g. n < 2 && @warn(...); n = max(2, n)): this should be replaced by n_orig = n; n = max(2, n); @adjust_nvar_warn("<name>", n_orig, n). It won't cause test failures for n ∈ {50, 100} but is inconsistent with the expected warning format for edge-case inputs.

Noteworthy (→ Info)

• Multi-function file: the export statement lists more than one symbol. This is an accepted legacy pattern for function families (dixmaan, genrose+rosenbrock, triangle variants) but new problems should not use it.
• n::Int = default_nvar is present in the signature but n is not used in the body. This is harmless but misleading — the keyword will be silently ignored.
• Data-loading file: calls _ensure_data! or include("../../data/..."). Correct pattern for mesh/tabular problems; means the problem is effectively non-scalable.
• src/ADNLPProblems/<name>.jl does not exist. This is a JuMP-only problem. Check that src/Meta/<name>.jl has :implementation => :jump. If it has :both or :adnlpmodels instead, flag as Error — the test suite consistency check will fail.
• src/Meta/<name>.jl does not exist. Without a meta file the problem is absent from OptimizationProblems.meta, and the test sort(list_problems) == sort(Symbol.(meta[!, :name])) will fail. This is an Error.

Step 4 — Dynamic analysis (run Julia)

Run the following Julia snippet via the Bash tool. Replace PROBLEM_NAME with the actual problem name.

Prerequisite: NLPModels, NLPModelsJuMP, and ADNLPModels must be available. If the snippet fails with a package-not-found error, install them first:

julia -e "import Pkg; Pkg.add([\"NLPModels\", \"NLPModelsJuMP\", \"ADNLPModels\"])"

julia --project -e "
using OptimizationProblems, NLPModels
import OptimizationProblems.PureJuMP, OptimizationProblems.ADNLPProblems
import NLPModelsJuMP, ADNLPModels

name = \"PROBLEM_NAME\"

if !(Symbol(name) in names(PureJuMP, all=false))
  println(\"FAIL export: \", name, \" not exported from PureJuMP\")
  exit(0)
end
ctor = PureJuMP.eval(Symbol(name))
println(\"OK export\")

# --- Instantiation ---
model = nothing
try
  global model = ctor()
  println(\"OK instantiate_model\")
catch e
  println(\"FAIL instantiate_model: \", e)
end
model === nothing && exit(0)

nlp = nothing
try
  global nlp = NLPModelsJuMP.MathOptNLPModel(model)
  println(\"OK wrap_nlpmodel\")
catch e
  println(\"FAIL wrap_nlpmodel: \", e)
end
nlp === nothing && exit(0)

# --- Objective at x0 ---
f0 = try obj(nlp, nlp.meta.x0) catch e; println(\"FAIL obj_at_x0: \", e); NaN end
if !isnan(f0)
  println(isfinite(f0) ? \"OK obj_at_x0: \$(f0)\" : \"WARN obj_at_x0: non-finite value \$(f0)\")
end

# --- Meta consistency ---
has_meta = isdefined(OptimizationProblems, Symbol(name, :_meta))
if !has_meta
  println(\"INFO no_meta: src/Meta/$(name).jl not loaded\")
else
  meta = OptimizationProblems.eval(Symbol(name, :_meta))
  get_pb_nvar  = OptimizationProblems.eval(Symbol(:get_, name, :_nvar))
  get_pb_ncon  = OptimizationProblems.eval(Symbol(:get_, name, :_ncon))
  get_pb_nlin  = OptimizationProblems.eval(Symbol(:get_, name, :_nlin))
  get_pb_nnln  = OptimizationProblems.eval(Symbol(:get_, name, :_nnln))
  get_pb_nequ  = OptimizationProblems.eval(Symbol(:get_, name, :_nequ))
  get_pb_nineq = OptimizationProblems.eval(Symbol(:get_, name, :_nineq))

  actual_nequ = length(get_jfix(nlp))

  checks = [
    (\"meta_nvar\",             meta[:nvar],                  nlp.meta.nvar,
      meta[:nvar] == nlp.meta.nvar || meta[:variable_nvar]),
    (\"meta_ncon\",             meta[:ncon],                  nlp.meta.ncon,
      meta[:ncon] == nlp.meta.ncon || meta[:variable_ncon]),
    (\"minimize\",              meta[:minimize],              get_minimize(nlp),
      meta[:minimize] == get_minimize(nlp)),
    (\"has_bounds\",            meta[:has_bounds],            length(get_ifree(nlp)) < get_nvar(nlp),
      meta[:has_bounds] == (length(get_ifree(nlp)) < get_nvar(nlp))),
    (\"has_fixed_variables\",   meta[:has_fixed_variables],   get_ifix(nlp) != [],
      meta[:has_fixed_variables] == (get_ifix(nlp) != [])),
    (\"has_equalities_only\",   meta[:has_equalities_only],   actual_nequ == get_ncon(nlp) > 0,
      meta[:has_equalities_only] == (actual_nequ == get_ncon(nlp) > 0)),
    (\"has_inequalities_only\", meta[:has_inequalities_only], get_ncon(nlp) > 0 && actual_nequ == 0,
      meta[:has_inequalities_only] == (get_ncon(nlp) > 0 && actual_nequ == 0)),
    (\"getter_nvar\",           get_pb_nvar(),                nlp.meta.nvar,
      get_pb_nvar()  == nlp.meta.nvar  || meta[:variable_nvar]),
    (\"getter_ncon\",           get_pb_ncon(),                nlp.meta.ncon,
      get_pb_ncon()  == nlp.meta.ncon  || meta[:variable_ncon]),
    (\"getter_nlin\",           get_pb_nlin(),                nlp.meta.nlin,
      get_pb_nlin()  == nlp.meta.nlin  || meta[:variable_ncon]),
    (\"getter_nnln\",           get_pb_nnln(),                nlp.meta.nnln,
      get_pb_nnln()  == nlp.meta.nnln  || meta[:variable_ncon]),
    (\"getter_nequ\",           get_pb_nequ(),                actual_nequ,
      get_pb_nequ()  == actual_nequ    || meta[:variable_ncon]),
    (\"getter_nineq\",          get_pb_nineq(),               nlp.meta.ncon - actual_nequ,
      get_pb_nineq() == (nlp.meta.ncon - actual_nequ) || meta[:variable_ncon]),
  ]

  for (label, meta_val, actual_val, ok) in checks
    println(ok ? \"OK\" : \"FAIL\", \" \", label, \": meta=\", meta_val, \" actual=\", actual_val)
  end

  println(\"DEFINED_EVERYWHERE_CHECK finite=\", isfinite(f0), \" meta=\", meta[:defined_everywhere])

  # --- Scalability check ---
  if meta[:variable_nvar]
    n_test = 5
    try
      model2 = ctor(n = n_test)
      nlp2 = NLPModelsJuMP.MathOptNLPModel(model2)
      n_expected = get_pb_nvar(n = n_test)
      ok = nlp2.meta.nvar == n_expected
      println(ok ? \"OK scalable_nvar: \$(nlp2.meta.nvar)\" : \"FAIL scalable_nvar: got \$(nlp2.meta.nvar) expected \$(n_expected)\")
      println(nlp2.meta.nvar != nlp.meta.nvar ? \"OK scalable_changes\" : \"WARN scalable_no_change: both n give nvar=\$(nlp.meta.nvar)\")
    catch e
      println(\"FAIL scalable_instantiate: \", e)
    end
  end
end

# --- Compatibility with ADNLPProblems ---
if Symbol(name) in names(ADNLPProblems, all=false)
  ad_ctor = ADNLPProblems.eval(Symbol(name))
  nlp_ad = nothing
  try
    global nlp_ad = ad_ctor()
    println(\"OK ad_instantiate\")
  catch e
    println(\"WARN ad_instantiate: \", e)
  end

  if nlp_ad !== nothing
    println(nlp.meta.nvar == nlp_ad.meta.nvar ? \"OK compat_nvar\" :
      \"FAIL compat_nvar: jump=\$(nlp.meta.nvar) ad=\$(nlp_ad.meta.nvar)\")
    println(nlp.meta.ncon == nlp_ad.meta.ncon ? \"OK compat_ncon\" :
      \"FAIL compat_ncon: jump=\$(nlp.meta.ncon) ad=\$(nlp_ad.meta.ncon)\")
    println(nlp.meta.x0 == nlp_ad.meta.x0 ? \"OK compat_x0\" :
      \"FAIL compat_x0: starting points differ\")
    println(nlp.meta.lvar == nlp_ad.meta.lvar ? \"OK compat_lvar\" :
      \"FAIL compat_lvar: lower bounds differ\")
    println(nlp.meta.uvar == nlp_ad.meta.uvar ? \"OK compat_uvar\" :
      \"FAIL compat_uvar: upper bounds differ\")

    x0 = nlp_ad.meta.x0
    x1 = x0 .+ 0.01
    f_jump = try obj(nlp, x0)    catch; NaN end
    f_ad   = try obj(nlp_ad, x0) catch; NaN end
    if !isnan(f_jump) && !isnan(f_ad)
      n0 = max(abs(f_ad), 1.0)
      println(isapprox(f_jump, f_ad, atol=1e-10*n0) ? \"OK compat_obj_x0\" :
        \"FAIL compat_obj_x0: jump=\$(f_jump) ad=\$(f_ad)\")
      f_jump1 = try obj(nlp, x1)    catch; NaN end
      f_ad1   = try obj(nlp_ad, x1) catch; NaN end
      if !isnan(f_jump1) && !isnan(f_ad1)
        n1 = max(abs(f_ad1), 1.0)
        println(isapprox(f_jump1, f_ad1, atol=1e-10*n1) ? \"OK compat_obj_x1\" :
          \"FAIL compat_obj_x1: jump=\$(f_jump1) ad=\$(f_ad1)\")
      end
    end

    if nlp_ad.meta.ncon > 0
      c_jump = try cons(nlp, x0)    catch; nothing end
      c_ad   = try cons(nlp_ad, x0) catch; nothing end
      if c_jump !== nothing && c_ad !== nothing
        n0 = max(maximum(abs.(c_ad .+ 1e-30)), 1.0)
        println(all(isapprox.(c_jump, c_ad, atol=1e-10*n0)) ? \"OK compat_cons_x0\" :
          \"FAIL compat_cons_x0: constraint values differ at x0\")
        c_jump1 = try cons(nlp, x1)    catch; nothing end
        c_ad1   = try cons(nlp_ad, x1) catch; nothing end
        if c_jump1 !== nothing && c_ad1 !== nothing
          n1 = max(maximum(abs.(c_ad1 .+ 1e-30)), 1.0)
          println(all(isapprox.(c_jump1, c_ad1, atol=1e-10*n1)) ? \"OK compat_cons_x1\" :
            \"FAIL compat_cons_x1: constraint values differ at x0+0.01\")
        end
        println(nlp.meta.lcon ≈ nlp_ad.meta.lcon ? \"OK compat_lcon\" :
          \"FAIL compat_lcon: lower constraint bounds differ\")
        println(nlp.meta.ucon ≈ nlp_ad.meta.ucon ? \"OK compat_ucon\" :
          \"FAIL compat_ucon: upper constraint bounds differ\")
        println(nlp.meta.lin == nlp_ad.meta.lin ? \"OK compat_lin\" :
          \"FAIL compat_lin: linear constraint index sets differ\")
      end
    end
  end
else
  println(\"INFO no_ad_sibling\")
end
"

Interpret the output as follows:

Line pattern	Action
OK export	No finding
FAIL export: ...	Error: function not exported from PureJuMP
OK instantiate_model	No finding
FAIL instantiate_model: ...	Error: JuMP model construction throws; all subsequent dynamic checks skipped
OK wrap_nlpmodel	No finding
FAIL wrap_nlpmodel: ...	Error: MathOptNLPModel wrapping fails
OK obj_at_x0: X	No finding
FAIL obj_at_x0: ...	Error: objective throws at starting point
WARN obj_at_x0: non-finite value X	Warning: objective is Inf or -Inf at x0
INFO no_meta: ...	Info: src/Meta/<name>.jl not present; meta-consistency checks skipped
OK <field>: meta=X actual=Y	No finding
FAIL <field>: meta=X actual=Y	Error: meta field <field> claims X but the JuMP model gives Y
DEFINED_EVERYWHERE_CHECK finite=false meta=true	Warning: objective is NaN/Inf at x0 but :defined_everywhere => true
DEFINED_EVERYWHERE_CHECK finite=false meta=missing	Warning: objective is NaN/Inf at x0; :defined_everywhere should probably be false
DEFINED_EVERYWHERE_CHECK finite=false meta=false	Info: consistent — domain is declared restricted and x0 confirms it
DEFINED_EVERYWHERE_CHECK finite=true ...	No finding
OK scalable_nvar: N	No finding
FAIL scalable_nvar: got N expected M	Error: nvar at n=5 does not match get_<name>_nvar(n=5)
OK scalable_changes	No finding
WARN scalable_no_change: ...	Warning: meta says variable_nvar=true but both n values give the same nvar
FAIL scalable_instantiate: ...	Error: model cannot be instantiated at small n
OK ad_instantiate	No finding; note in report that compatibility was tested
WARN ad_instantiate: ...	Warning: ADNLPProblems sibling exists but cannot be instantiated
OK compat_nvar / FAIL compat_nvar: ...	Match/mismatch in number of variables between JuMP and AD models
OK compat_ncon / FAIL compat_ncon: ...	Match/mismatch in number of constraints
OK compat_x0 / FAIL compat_x0: ...	Error: starting points disagree — x0 in @variable start=... differs from AD x0
OK compat_lvar / FAIL compat_lvar: ...	Error: variable lower bounds disagree
OK compat_uvar / FAIL compat_uvar: ...	Error: variable upper bounds disagree
OK compat_obj_x0 / FAIL compat_obj_x0: ...	Error: objective values at x0 disagree
OK compat_obj_x1 / FAIL compat_obj_x1: ...	Error: objective values at x0+0.01 disagree
OK compat_cons_x0 / FAIL compat_cons_x0: ...	Error: constraint values at x0 disagree
OK compat_cons_x1 / FAIL compat_cons_x1: ...	Error: constraint values at x0+0.01 disagree
OK compat_lcon / FAIL compat_lcon: ...	Error: constraint lower bounds disagree
OK compat_ucon / FAIL compat_ucon: ...	Error: constraint upper bounds disagree
OK compat_lin / FAIL compat_lin: ...	Error: linear constraint index sets disagree
INFO no_ad_sibling	Info: no ADNLPProblems sibling — JuMP-only problem; no compatibility checks run

Step 5 — Report

Output:

## review-purejump: <name>   [src/PureJuMP/<name>.jl]
Characteristics: <scalable|fixed-size>, <unconstrained|linear|nonlinear|mixed>, <with bounds|no bounds>
Dynamic checks: <passed | N failures | not available>
Compatibility: <tested against ADNLPProblems | JuMP-only problem | AD sibling not instantiatable>

### Errors (N)
- [E] <check>: <what was wrong and what was expected>

### Warnings (N)
- [W] <check>: <what is missing or suspicious>

### Info (N)
- [I] <observation>: <what was noted>

---
Summary: N error(s), N warning(s), N info.

If a tier has zero findings, omit that section header entirely. End with one sentence summarising the overall state.

---

Quick reference

Standard signature forms

Problem type	Signature
Scalable, unconstrained	function <name>(args...; n::Int = default_nvar, kwargs...)
Fixed-size	function <name>(args...; kwargs...)
Scalable with extra params	function <name>(args...; n::Int = default_nvar, α::Float64 = 1.0, kwargs...)

n-adjustment pattern (required form)

function <name>(args...; n::Int = default_nvar, kwargs...)
  n_orig = n
  n = 4 * max(1, div(n, 4))   # or whatever the adjustment is
  @adjust_nvar_warn("<name>", n_orig, n)
  ...
end

@variable start value patterns (all accepted)

@variable(nlp, x[i = 1:n], start = 1.0)          # scalar literal
@variable(nlp, x[i = 1:n], start = x0[i])         # per-element from array
@variable(nlp, 0 <= x[i = 1:n] <= 1, start = 0.5) # bounded with start
set_start_value.(x, x0)                            # post-hoc batch assignment

Reference examples

• Unconstrained scalable: src/PureJuMP/arwhead.jl
• Scalable with n-adjustment: src/PureJuMP/woods.jl, src/PureJuMP/elec.jl
• Scalable multi-parameter family: src/PureJuMP/dixmaan_efgh.jl
• Constrained scalable: src/PureJuMP/elec.jl, src/PureJuMP/catmix.jl
• Fixed-size constrained: src/PureJuMP/hs100.jl
• Data-loading with _ensure_data!: src/PureJuMP/triangle.jl