matlab/matlab-agentic-toolkit / skills-catalog/computational-finance/matlab-optimize-portfolio
matlab-optimize-portfolio
VerifiedFormulate and solve portfolio optimization problems in MATLAB. Routes to the Financial Toolbox Portfolio object for mean-variance (Markowitz), minimum- variance, target-return, maximum Sharpe ratio, and efficient frontier problems with bounds, budget, group, turnover, tracking-error, or cardinality constraints; or to the problem-based framework (optimproblem/optimvar/solve) when constraints exceed what Portfolio can express: integer round lots, whole shares, per-lot or fixed commissions, minimum trade sizes, semi-integer positions, wash-sale rules, realized capital-gains caps, tax-loss harvesting, asymmetric or bucketed transaction- cost caps, or a custom efficient frontier over such constraints. Use when users ask about portfolio optimization, when they attempt quadprog, fmincon, intlinprog, or ga for a portfolio problem, or when code rounds Portfolio weights to whole shares or lots.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| manifest.yaml | config | 762 B |
| references/portfolio-object.md | markdown | 6.3 KB |
| references/portfolio-object/examples.md | markdown | 8.8 KB |
| references/portfolio-object/formulation-max-sharpe.md | markdown | 3.6 KB |
| references/portfolio-object/formulation-mean-variance.md | markdown | 3.7 KB |
| references/portfolio-object/reference-core.md | markdown | 6.8 KB |
| references/problem-based.md | markdown | 19.2 KB |
| references/problem-based/custom-frontier.md | markdown | 9.3 KB |
| references/problem-based/disjunctive-big-m.md | markdown | 5.9 KB |
| references/problem-based/mip-recognition.md | markdown | 4.0 KB |
| references/problem-based/problem-based-framework.md | markdown | 6.1 KB |
| references/problem-based/problem-data-hygiene.md | markdown | 7.4 KB |
| references/problem-based/tax-aware-constraints.md | markdown | 5.0 KB |
| references/problem-based/trade-aux-variables.md | markdown | 5.7 KB |
references/problem-based/problem-based-framework.md
View on GitHub# Set Up and Solve a Problem-Based Model
## The default: problem-based
Formulate every portfolio problem with `optimproblem` + `optimvar` and call
`solve(prob)`. This is the default, not a preference — the problem-based
framework carries three advantages that matter for the failure modes below:
- **Constraint expressions read like the math.** `sum(sell.*(price - basis)) <= 500`
is a natural expression; `A*x <= b` in solver-based form obscures unit
errors like the cap-gains `$² / share` bug (see `problem-data-hygiene.md`).
- **`solve` picks the right solver from the problem structure.** LP, QP,
MILP, MIQP, NLP, MINLP are all dispatched automatically. No manual solver
choice, no `A/Aeq/b/beq` indices bookkeeping.
- **Integer variables use `optimvar(..., "Type", "integer")`.** This one
option turns a QP into a MIQP or an LP into a MILP without changing any of
the constraint expressions.
## When solver-based is legitimate
Only in these narrow cases:
- The user explicitly asks for solver-based (`linprog(f, A, b, ...)`,
`intlinprog(f, intcon, A, b, ...)`, `ga(fun, nvars, ...)`).
- Problem-based has a documented gap for the shape at hand.
- Legacy code the user is extending is already in solver-based form and they
want a minimal diff.
Otherwise: stay in problem-based. Three common drops to solver-based on
portfolio MIPs — `linprog` matrix form on a MILP, `intlinprog` matrix form
on a MILP, `ga` function-handle form on a MIQP — are all avoidable and all
lose readability plus the `solve` dispatch safety net.
## The nonlinear escape: `fcn2optimexpr`
For genuinely nonlinear pieces that cannot be linearized (a custom pricing
function, a nonlinear risk measure, a nonconvex objective), wrap the MATLAB
function so it composes with `optimproblem`:
```matlab
prob = optimproblem(ObjectiveSense="maximize");
w = optimvar("w", nAssets, LowerBound=0, UpperBound=1);
prob.Objective = fcn2optimexpr(@customUtility, w, muParams);
prob.Constraints.budget = sum(w) == 1;
x0.w = ones(nAssets, 1) / nAssets; % nonlinear (fmincon) needs a start point
sol = solve(prob, x0);
```
`fcn2optimexpr` keeps the formulation inside `optimproblem` so `solve` still
dispatches. Do **not** drop out to `ga(@objfun, nvars, ...)` function-handle
form for nonlinear pieces — you lose the ability to name and index
constraints and variables, and the code stops reading like the math.
## `solve` dispatch table
Read the problem structure off the formulation — objective form and variable
types together decide it:
| Objective form | All continuous vars | Any integer vars |
|------------------------------------|---------------------|------------------|
| Linear | LP | MILP |
| Quadratic | QP | MIQP |
| Nonlinear (via `fcn2optimexpr`) | NLP | MINLP |
Then `solve` picks the solver:
| Problem structure | Dispatched solver | Toolbox | Deterministic? |
|-------------------|-------------------|-----------------------|------------------------|
| LP | `linprog` | Optimization Toolbox | yes |
| QP | `quadprog` | Optimization Toolbox | yes |
| MILP | `intlinprog` | Optimization Toolbox | yes |
| MIQP | `ga` | Global Optimization | no (heuristic) |
| NLP | `fmincon` | Optimization Toolbox | local, depends on x0 |
| MINLP | `ga` | Global Optimization | no (heuristic) |
Dispatch is by **problem structure**, not by "has binaries." A MIQP has
integer variables and a quadratic objective — `solve` dispatches to `ga`,
not `intlinprog`, because `intlinprog` cannot handle quadratic objectives.
## Options must match the dispatched solver
`optimoptions(solverName, ...)` is bound to the solver name at construction.
If you pass options for a solver `solve` does not dispatch to, only the
options the dispatched solver also supports carry over.
Anti-pattern:
```matlab
opts = optimoptions("intlinprog", "Display", "iter", "MaxTime", 60, ...
"MaxNodes", 1e4);
[sol, fval, exitflag] = solve(prob, "Options", opts); % prob is MIQP
% -> solve dispatches to ga
% -> Display, MaxTime carry over
% -> MaxNodes (intlinprog-specific) is dropped with a warning
```
Correct: check the dispatch first, then if the user asks for options on a
MIQP/MINLP set options on the actual dispatched solver:
```matlab
% Correct: the objective is quadratic + integer vars are present => MIQP => ga
opts = optimoptions("ga", "Display", "iter", "MaxTime", 60);
[sol, fval, exitflag] = solve(prob, "Options", opts);
```
Rule of thumb — read the dispatch off the objective form and the variable
types, then pick the solver name for `optimoptions`. When in doubt, run
`solve` once and inspect the diagnostic output; it names the solver.
## Common mistakes
| Mistake | Why it's wrong | Correct approach |
|---------|----------------|------------------|
| `linprog(f, A, b, Aeq, beq, lb, ub)` on a portfolio LP | Manual row/column bookkeeping across `A`, `Aeq`, `b`, `beq`, `lb`, `ub` is error-prone; constraints stop reading like the math; unit errors (cap-gains, self-financing) get buried in coefficient matrices | `optimproblem` + `optimvar`; `solve(prob)` |
| `intlinprog(f, intcon, A, b, ...)` on a portfolio MILP | Same manual matrix bookkeeping — plus `intcon` is a separate list of integer column indices that must stay in sync with `A`'s column layout every time a variable is added or removed | `optimvar(..., "Type", "integer")` |
| `ga(@objfun, nvars, ...)` on a portfolio MIQP | Function-handle form breaks the `optimproblem` composition; nonlinear pieces cannot compose with other constraints cleanly | `optimproblem` + `optimvar` (integer type); `fcn2optimexpr` for nonlinear pieces |
| `optimoptions("intlinprog", ...)` passed to `solve` on a MIQP | `solve` dispatches to `ga`; `intlinprog`-specific options are dropped with a warning | Read dispatch first; `optimoptions("ga", ...)` on MIQP |
----
Copyright 2026 The MathWorks, Inc.
----
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |