matlab-solve-optimization

# MATLAB Optimization Workflow

Guide the full optimization lifecycle: classify the problem, formulate it, select and configure a solver, and validate the results.

## When to Use

- User is defining an optimization problem in MATLAB (variables, objectives, constraints)
- User asks about `optimproblem`, `optimvar`, `optimconstr`, `optimexpr`, or `fcn2optimexpr`
- User is selecting or configuring a solver (`optimoptions`, algorithm choice, tuning)
- User is interpreting results, debugging convergence, or checking exitflags
- User is deciding between problem-based and solver-based approaches
- User is writing optimization code with for-loops over decision variables or constraints

## When NOT to Use

- User is asking to solve a problem that doesn't require numerical optimization solvers (e.g., finding the minimum value in an array or table)
- User is working with non-optimization MATLAB code (data analysis, plotting, signal processing)
- User is using a third-party optimization toolbox (not MathWorks)
- User is solving symbolic equations with `solve(eqns, vars)`, ODE systems, or linear system solves (`A\b`)

---

## Stage 1: Classify & Formulate

### 1.1 Classify the Problem

Before formulating, identify the problem class — it determines which solver to use, what guarantee you can promise (global vs local), and whether a domain-specific tool should replace the generic path.

See [references/classify.md](references/classify.md) for the class→solver→guarantee table, convexity quick-checks, and "hidden easier class" heuristics. Key actions:
- Check if a purpose-built domain tool exists before falling back to `optimproblem`
- Watch for hidden easier classes (sum-of-squares disguised as NLP, linear structure missed)
- For QPs, check `eig(H)` — nonconvex QPs cannot use `quadprog` reliably
- Watch for hidden nonsmoothness: `max`, `min`, `abs`, `sort`, `if`/branching, or norms other than squared-2-norm

### 1.2 Choose Approach

**Use problem-based by default** for readable definitions, N-D modeling, and every LP, QP, conic, and mixed-integer problem (unless coefficients are already in matrix-vector form). Problem-based provides automatic differentiation and is less error-prone.

Even when AD is blocked (e.g., `ode45` in the objective), `fcn2optimexpr` can still wrap the function as a black-box — problem-based remains useful.

Only fall back to solver-based when one of these applies:

| Use solver-based when... | Reason |
|---|---|
| Trivial mapping to solver API — one vector `x`, pre-coded objective with exact gradients/Hessian | No benefit from abstraction; solver-based is direct |
| Overhead of building problem-based expressions dominates computation | Avoid tracing/transformation overhead |
| Need a solver feature problem-based doesn't expose (`CheckpointFile`, exact Hessians, custom `OutputFcn`) | Only available via solver-based calls |
| C code generation for embedded deployment is required | Problem-based does not support codegen |

**Converting between approaches:** `prob2struct(prob)` converts problem-based to solver-based form for deployment or performance.

**References:**
- Problem-based: [references/problem-based-guide.md](references/problem-based-guide.md)
- Solver-based (class→solver mapping): [references/classify.md](references/classify.md)

### 1.3 Formulate the Problem

**Problem-based canonical template:**

```matlab
% 1. Define decision variables
x = optimvar("x", N, LowerBound=lb, UpperBound=ub);

% 2. Create problem
prob = optimproblem("Objective", sum(x,"all"));

% 3. Add constraints
prob.Constraints.linear = A*x <= b;
prob.Constraints.nonlinear = fcn2optimexpr(@myNonlinFcn, x) <= rhs;

% 4. Set initial guess (must be struct with field names matching optimvar names)
x0.x = initialValues;

% 5. Solve
[sol, fval, exitflag, output] = solve(prob, x0);
```

**Solver-based key differences:**
- Initial guess is a **numeric vector**, not a struct
- You manage variable indexing manually (flat vector `x`)
- Supply gradients manually for best performance (`SpecifyObjectiveGradient=true`)
- Linear/quadratic solvers require explicit coefficient matrices

### 1.4 Validate at the Start Point

Before calling any solver, evaluate the objective and constraints at `x0` to catch sign/size/NaN errors early:

```matlab
% Problem-based
fval0 = evaluate(prob.Objective, x0);
assert(isfinite(fval0), 'Objective is not finite at x0');
infeas0 = infeasibility(prob.Constraints, x0);
fprintf('Max infeasibility at x0: %.3e\n', max(infeas0));
```

For solver-based, call `fun(x0)` and `nonlcon(x0)` directly and confirm finite, correctly-sized outputs. If gradients are supplied, run `checkGradients` at this point.

---

## Stage 2: Select & Configure Solver

### 2.1 Select the Narrowest Solver

Choose the **narrowest solver that matches the problem structure.** Do not default to `fmincon` or heuristic global solvers when a more specific solver applies.

Key selection rules:
- Always prefer: `linprog` > `quadprog` > `coneprog` > `lsqlin` > `lsqnonlin` > `fmincon` > global solvers
- Always prefer `fminunc` over `fminsearch` when Optimization Toolbox is installed
- Always prefer `lsqnonlin`/`lsqcurvefit` over `fmincon` for least-squares problems
- Always prefer `lsqlin` over `lsqnonlin` for linear least-squares with bounds or linear constraints
- Use `patternsearch` when gradients are unavailable/unreliable AND the problem is not extremely expensive
- Use `surrogateopt` when each evaluation takes >15-20 seconds
- For nearly linear MIPs, linearize and use `intlinprog` rather than calling Global Optimization solvers
- For unit commitment / binary operating modes, keep mixed-integer with `intlinprog`

See [references/classify.md](references/classify.md) for the full class→solver table.

### 2.2 Verify Options — Never Guess

**ALWAYS verify that solver options are valid before using them.** Options change across MATLAB releases and hallucinated options cause runtime errors.

```matlab
% Verify options for a solver
o