Add maintainer-friendly workflow documentation

Author: arnavk23

DEMBO_WORKFLOW.md

@@ -0,0 +1,152 @@
+# Dembo GP Problem Rebuild Workflow
+
+## Overview
+Rebuilt Dembo geometric programming problems 2-7 from original 1976 paper source to replace incorrect implementations.
+
+**Reference:** Dembo, R.S. (1976). *A set of geometric programming test problems and their solutions.* Mathematical Programming, 10(1), 192-213.
+
+## What Was Implemented
+- **GP2**: Colville's problem #3 (5 vars, 6 constraints)
+- **GP3**: Alkylation process (7 vars, 14 constraints)
+- **GP4A/4B**: Reactor design (8 vars, 4 constraints)
+- **GP5**: Heat exchanger (8 vars, 6 constraints)
+- **GP6**: 3-stage membrane (13 vars, 13 constraints)
+- **GP7**: 5-stage membrane (16 vars, 19 constraints)
+
+**Excluded** (due to OCR corruption in PDF):
+- GP1A, GP1B, GP8A: Unreadable exponents in source
+
+## Files Modified
+```
+src/ADNLPProblems/dembo_gp{2,3,4a,4b,5,6,7}.jl    (6 files)
+src/PureJuMP/dembo_gp{2,3,4a,4b,5,6,7}.jl         (6 files)
+src/Meta/dembo_gp{2,3,4a,4b,5,6,7}.jl             (6 files)
+```
+
+## Implementation Steps
+
+### 1. Extract from PDF
+Extract coefficient tables from Dembo (1976) Tables 2.1–7.2:
+- Coefficients → arrays `c[1]`, `c[2]`, ...
+- Bounds (lower/upper) → from table footnotes
+- Starting points → from table rows
+- Constraint structure → from problem description
+
+**Tools:** pdftotext, manual verification
+
+### 2. ADNLP Implementation
+Template in `src/ADNLPProblems/dembo_gp<N>.jl`:
+
+```julia
+function dembo_gp<N>(; n=default_nvar, kwargs...)
+    c = [...coefficients...]
+    
+    f(x) = objective_formula(c, x)
+    
+    function cons!(nlp, x)
+        nlp.cons[1] = constraint_1(c, x)
+        ...
+    end
+    
+    return ADNLPModel!(f, x0, lvar, uvar, cons!, 
+                      lcon=-Inf*ones(m), ucon=zeros(m), ...)
+end
+
+export dembo_gp<N>
+```
+
+**Key:** Constraints as `g(x) ≤ 0` form.
+
+### 3. PureJuMP Implementation
+Template in `src/PureJuMP/dembo_gp<N>.jl`:
+
+```julia
+function dembo_gp<N>(; n=default_nvar, kwargs...)
+    model = Model()
+    @variable(model, lvar[i] <= x[i=1:n] <= uvar[i], start=x0[i])
+    @objective(model, Min, objective_expr(c, x))
+    @constraint(model, constraint_exprs(c, x))
+    return model
+end
+
+export dembo_gp<N>
+```
+
+### 4. Metadata Registry
+Template in `src/Meta/dembo_gp<N>.jl`:
+
+```julia
+dembo_gp<N>_meta = Dict(
+    :nvar => <n>,
+    :ncon => <m>,
+    :minimize => true,
+    :name => "dembo_gp<N>",
+    :objtype => :other,
+    :contype => :general,
+    :origin => :academic,
+)
+
+get_dembo_gp<N>_nvar(; kwargs...) = <n>
+get_dembo_gp<N>_ncon(; kwargs...) = <m>
+```
+
+Auto-loaded by [src/OptimizationProblems.jl](src/OptimizationProblems.jl#L67).
+
+## Reproducible via API
+
+**Input format (JSON):**
+```json
+{
+  "name": "dembo_gp2",
+  "nvar": 5,
+  "ncon": 6,
+  "coefficients": [c1, c2, ...],
+  "bounds": {"lower": [...], "upper": [...]},
+  "start_point": [...],
+  "objective_terms": [
+    {"coeff_idx": 1, "vars": [2]},
+    {"coeff_idx": 2, "vars": [1, 5]}
+  ],
+  "constraints": [
+    {"type": "rational", "numerator_coeff": 11, 
+     "denominator_vars": [2, 5], "rhs": 1.0}
+  ]
+}
+```
+
+**Process:**
+1. Parse spec JSON
+2. Generate ADNLP boilerplate with `Template(ADNLPProblems/dembo_template.jl)`
+3. Generate PureJuMP boilerplate with `Template(PureJuMP/dembo_template.jl)`
+4. Generate metadata with `Template(Meta/dembo_template.jl)`
+5. Validate syntax with `get_errors(filenames)`
+
+## Testing Notes
+
+**Current limitation:** `Pkg.test()` distributed worker precompile cache may show false negatives (arrays display identically but comparison fails). Workaround:
+```bash
+rm -rf ~/.julia/compiled/v1.12/OptimizationProblems
+julia --project=. -e 'using Pkg; Pkg.precompile()'
+```
+
+**Simple validation (no distributed workers):**
+```bash
+julia --project=. verify_dembo.jl
+```
+
+## Adding New Problems
+
+1. Create problem spec (coefficients, bounds, constraints)
+2. Run code generator for each backend → 3 files
+3. Validate syntax
+4. Add to benchmark suite if needed
+
+## Verification Checklist
+
+- [ ] All coefficients match paper tables
+- [ ] Bounds are tight by design (not arbitrary)
+- [ ] Constraint form is `g(x) ≤ 0`
+- [ ] `export <function>` present in each backend file
+- [ ] Metadata `<name>_meta` Dict and getter functions present
+- [ ] No syntax errors: `get_errors()`
+- [ ] Problem instantiates: `nlp = dembo_gp<N>()`