matlab-solve-optimization

name	matlab-solve-optimization
description	Use when writing, solving, or debugging MATLAB optimization code — formulating problems (optimproblem, optimvar, fcn2optimexpr), selecting and configuring solvers (fmincon, linprog, quadprog, intlinprog, lsqnonlin, ga, surrogateopt, optimoptions), or validating results (exitflag, convergence, constraint violations). Covers problem-based and solver-based approaches, solver tuning, and solution verification.
license	MathWorks BSD-3-Clause
metadata	{"author":"MathWorks","version":"1.0"}

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 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
• Solver-based (class→solver mapping): references/classify.md

1.3 Formulate the Problem

Problem-based canonical template:

% 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:

% 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 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.

% Verify options for a solver
opts = optimoptions('solvername')

Run optimoptions('solvername') to see all valid options for the user's installed version before writing options code.

2.3 Verify Gradients (if supplied)

If analytic gradients are supplied (SpecifyObjectiveGradient=true), verify them before solving:

[valid, err] = checkGradients(@myObjective, x0, Display="on");

For constraint gradients: checkGradients(@myConstraints, x0, IsConstraint=true).

2.4 Parallelize (if expensive)

If the solver supports UseParallel and Parallel Computing Toolbox is available:

ver('parallel')  % Check for PCT
options = optimoptions('solvername', UseParallel=true);

Solvers supporting UseParallel: fmincon, fminunc, lsqnonlin, lsqcurvefit, patternsearch, surrogateopt, ga, particleswarm, paretosearch, gamultiobj.

Do NOT suggest UseParallel for: quadprog, intlinprog, fminsearch, linprog, lsqlin.

2.5 Performance (after correctness)

If the solve is correct but too slow, see references/performance-levers.md. Key levers: analytic gradients, sparsity patterns, warm starting, code generation. Apply only after Stage 3 confirms correctness — re-validate after any performance change.

Reference: references/solver-tuning.md for per-solver algorithm and tuning guidance.

---

Stage 3: Validate Results

3.1 Basic Validation (Always Include)

Every time solver-calling code is written, add basic output validation:

[sol, fval, exitflag, output] = solve(prob, x0);

% Check convergence
if exitflag > 0
    fprintf('Optimization converged: %s\n', output.message);
else
    warning('Optimization did not converge (exitflag = %d): %s\n', exitflag, output.message);
end

% Report key metrics
fprintf('Objective value: %.6f\n', fval);
fprintf('Iterations: %d\n', output.iterations);
if isfield(output, 'constrviolation')
    fprintf('Constraint violation: %d\n', output.constrviolation);
end

See references/validation-checklist.md for detailed exitflag meanings per solver.

3.2 Extended Validation

Constraint violations (problem-based):

[allsat, sat] = issatisfied(prob, sol);
if ~allsat
    conNames = fieldnames(prob.Constraints);
    for i = 1:numel(conNames)
        infeas = infeasibility(prob.Constraints.(conNames{i}), sol);
        if any(infeas > 0)
            fprintf('Constraint "%s" violated by %.3e\n', conNames{i}, max(infeas));
        end
    end
end

Optimality conditions (gradient-based solvers only — skip for patternsearch, ga, particleswarm, surrogateopt):

if isfield(output, 'firstorderopt')
    fprintf('First-order optimality: %.6e\n', output.firstorderopt);
    if output.firstorderopt > 1e-3
        warning('First-order optimality measure is large — solution may not be optimal.\n');
    end
end

3.3 Debugging Failed or Poor Solutions

When exitflag <= 0 or convergence is poor, follow the improving-results checklist in references/improving-results.md:

1. Check formulation — constraints feasible? bounds consistent? objective well-defined at x0?
2. Check scaling — scale variables to O(1); rescale if objective/constraints differ by orders of magnitude; use FiniteDifferenceType='central' if finite-difference gradients are inaccurate
3. Try different algorithms — options.Algorithm, increase MaxIterations/MaxFunctionEvaluations, adjust tolerances, set HybridFcn for heuristic solvers
4. Try different initial points — MultiStart, GlobalSearch, or surrogateopt/ga for global optimization

Debug discipline:

• Smallest-first. Shrink to 2-3 variables. A bug in a toy problem is minutes; at full scale is hours.
• One change at a time, justified by a symptom.
• Stop-and-ask budget. Stop coding and talk to the user when: >3 rounds with no improvement, >2 option tweaks that don't move diagnostics, or you can't get a finite objective at x0 even on a toy problem.

3.4 Application-Specific Visualization

Problem Domain	Suggested Plots
Optimal control / navigation	State trajectories vs time, control input profiles, phase portraits
Scheduling / assignment	Gantt charts, resource utilization over time
Design optimization	Contour plots with optimum marked, sensitivity plots
Parameter estimation / fitting	Residual plots, fitted surface vs data
Portfolio / allocation	Bar charts of allocations, efficient frontier plots

---

Gotchas

Formulation

1. Initial guess must be a struct with field names matching optimvar names exactly. NOT a flat vector.
2. Do NOT set SpecifyObjectiveGradient or SpecifyConstraintGradient in options for problem-based — AD manages gradients internally.
3. Use N-D optimvar for multi-dimensional problems. Do NOT create scalar variables in a loop.
4. Preallocate constraint arrays with optimconstr(N). Do NOT concatenate in a loop.
5. Call fcn2optimexpr ONCE per function, not inside loops. See references/fcn2optimexpr-guide.md.
6. Use "like" for preallocation inside traced functions to preserve AD type: zeros(n,1,"like",x).

Solver Configuration

7. Never guess option names from memory. Always verify with optimoptions('solvername').
8. Do NOT tighten MeshTolerance for patternsearch too much.
9. Do NOT set AbsoluteGapTolerance/RelativeGapTolerance high for intlinprog for early stopping — use time/node limits.
10. Keep tolerances well above machine epsilon. Use 1e-6 to 1e-8 range unless specifically required.

Validation

11. output.constrviolation does not exist for unconstrained solvers. Always check with isfield.
12. Do NOT check output.firstorderopt for derivative-free solvers. Check solver-specific metrics instead (output.meshsize, output.stallgenerations).
13. infeasibility() operates on individual constraints, not entire problems. Use issatisfied(prob, sol) for overall checks.
14. For fmincon with exitflag <= 0, check output.bestfeasible. Use it as a starting point for a new solve.

Conventions

• Default to problem-based unless a specific blocker applies.
• When vectorization is possible, always prefer it over loops.
• When wrapping complex logic in fcn2optimexpr, encapsulate in a single helper function rather than calling inside a loop.
• Always show the initial guess setup.
• Mark code blocks as templates when they depend on user-supplied functions.
• When suggesting tuning options, explain the trade-off (speed vs accuracy).
• Do not over-tune: for simple or small problems, defaults are usually sufficient.
• Always include basic validation (exitflag check) when writing solver-calling code.
• When debugging, start with formulation and scaling before changing algorithms.

---

Copyright 2026 The MathWorks, Inc.