Matlab Optimize Performance

MATLAB Performance Optimization Workflow

Systematic 7-step workflow for finding and fixing performance bottlenecks in MATLAB code.

When to Use

• User asks to speed up MATLAB code, or to optimize it for execution time

• User wants to find why their MATLAB code is slow

• User has a function or script that takes too long to run

• User asks to benchmark or time MATLAB code in the current session (a one-off timing or an A/B of two versions)

• User wants to compare performance before and after a change

• User asks about MATLAB performance best practices

When NOT to Use

• Optimizing Simulink model simulation speed (use Simulink Profiler)

• Speeding code up by compiling it with MATLAB Coder (codegen, MEX), or tuning generated MEX (use the matlab-generate-code skill)

• The problem is memory, not speed: out-of-memory errors or peak memory (use the matlab-optimize-memory skill)

• The performance issue is purely I/O-bound (file reads, network, database)

• User wants to write performance tests, or track timings across builds or in CI (use the matlab-write-performance-tests skill)

• Note: for exact invocation counts, or a sub-10 ms / MEX / parallel workload, use the MATLAB profiler (profile) rather than the Sampling Profiler (Step 2) — that's a profiler choice, not a reason to skip the skill

The 7-Step Workflow

Step 1: Establish Baseline

Measure current performance so you have a number to improve against:

f = @() targetFunction(input1, input2);
baseline = timeit(f);   % handles warm-up and repeats; prefer it to tic/toc

For GPU code use gputimeit. For a script, run it once to warm up, then time a second run with tic/toc. Templates: assets/measurement-templates.md.

Step 2: Profile and Analyze

Find where the time actually goes — don't guess, profile.

Pick the profiler first: check, don't assume. In R2026b+ the Sampling Profiler is the default: a low-overhead statistical profiler that samples the execution thread at ~100 Hz. This skill's sampling_profiler helper drives it, and sampling_profiler('available') tells you whether this MATLAB has it. Use the MATLAB profiler (profile) only when available is false, when you need exact call counts, or for a one-shot call too short to loop, or MEX or parallel code.

% Sampling Profiler — use when sampling_profiler('available') is true (clean up after)
addpath(fullfile(skillRoot, "scripts"));   % skillRoot = directory containing this SKILL.md
assert(sampling_profiler('available'));     % false -> use the MATLAB profiler block below
nReps = 1;   % raise until the loop below runs several seconds (~10 s is ideal)
sampling_profiler('on');
sampling_profiler('pause');
targetFunction(input1, input2);            % warm-up: pays first-call cost, not collected
sampling_profiler('clear');
sampling_profiler('resume');
for r = 1:nReps, targetFunction(input1, input2); end
[~, stacks] = sampling_profiler('off');
sampling_profiler('destroy');              % mandatory cleanup: skipping it corrupts later runs

% MATLAB profiler — any release; use when the Sampling Profiler isn't available
profile on; targetFunction(input1, input2); profile off; profile viewer;

Reading the sampler:

• Run several seconds; ~10 s is ideal (~1000 samples; ~100 is the bare minimum). Loop a quick workload by raising nReps, and keep the warm-up call. If it can't be looped, use profile.

• The counts describe the profiled run (stacks.TotalSamples/100 is close to its wall clock) and include no invocation counts. For how many times something ran, use profile, and record "call_count_source": "builtin_profile_numcalls", "sampling_can_count_invocations": false and "sampling_profiler_samples" in perf_report.json.

• Neither profiler sees inside a builtin or P-coded frame: the time lands on the call site with no line detail. Confirm such a hotspot by removing it and re-timing (Step 5).

Work from the profile to a change:

• Rank functions by self time, then read the lines inside the top one. Per-line time includes callees, so a line that only makes a call can outrank the line doing the work.

• Before changing anything, say from the code why that line is slow: a real mechanism (a reallocation in a loop, a builtin on a large array), not just a big percentage.

• Step 5 is the proof: if re-timing doesn't move the clock, your explanation was wrong; profile again.

For the full Sampling Profiler API, results model, traps, and helpers, see references/sampling-profiler.md.

Step 3: Identify Optimization Opportunities

Based on profiling results, identify which patterns apply. Read references/optimization-patterns.md for the full catalog.

Before optimizing, verify the target is worth it:

• Is it called in a tight loop? High call count × small time = big total.

• Is it M-code or a built-in? You can't make a built-in faster, but you can often call it fewer times (e.g., pass a matrix to filtfilt/filter instead of looping over columns).

Step 4: Implement Optimizations

Apply the patterns from Step 3, starting with the highest-impact one. Before/after examples are in references/optimization-patterns.md.

• Move invariant work out of loops (object creation, option parsing, constant expressions)

• Replace element-wise loops with array operations where possible

• Use purpose-built functions (discretize, cumsum, hypot) instead of hand-written equivalents

• For large data, batch the vectorization to control memory (see Pattern 9 in catalog)

• Try each new variant on a small slice of the input first: a wrong orientation in implicit expansion can build a huge array

Step 5: Measure Optimized Performance

Quick check, while you are still iterating: re-time with timeit as in Step 1 and compare with the baseline. A speedup of 1.2x or more is considered significant; below that, measurement noise makes it hard to be confident the change helped.

Verified result — required whenever the user asks for a number to report, commit, or share, when they gave you a hypothesis about what is slow, or when two profilers disagree. Follow references/measurement-protocol.md in full:

1. Measure the ceiling before optimizing — delete or hoist the suspected work, re-time end-to-end, and compute what fraction of total time it actually accounted for; profiler attribution has been observed to overstate it by more than 10x. (This removal-and-re-time step is called ablation, and is recorded as adjudication_method: "removal_ablation".)

2. Correctness gate against the original in the same session, with a tolerance scaled to the output (100*eps(max(abs(original(:))))), plus an independent witness statistic of the output.

3. Mutation test — perturb the input; the output must change. Catches code that is fast because it stopped doing the work.

4. Interleaved paired timing, one session, N ≥ 5, median(tb ./ to). Never compare across sessions or in sequential blocks — machine drift lands entirely on one arm.

5. Write perf_report.json — every field from a variable a run of the current code computed, never a typed-in literal. Run each step in its own tool call and save its results to a .mat as it finishes, so a fix to the report re-writes it from those files instead of re-running the steps.

The headline speedup_median is always end-to-end. A sub-kernel number goes in kernel_speedup. A refuted hypothesis is a result: report it with the honest speedup, including 1.0.

Step 6: Verify Correctness

Every optimization must produce the same results as the original:

original = originalFunction(input1, input2);
fast = optimizedFunction(input1, input2);

% Scale the tolerance to the output — a fixed 1e-10 is wrong in both directions
tol = 100 * eps(max(abs(original(:))));
maxErr = max(abs(original(:) - fast(:)));
fprintf('Max error: %.2e (tol %.2e)\n', maxErr, tol);
assert(isequal(isnan(original), isnan(fast)) && maxErr <= tol, 'Results differ beyond tolerance!');   % max skips NaN

For non-numeric outputs:

assert(isequal(original, fast), 'Results differ!');

Error at or below eps(max(abs(original(:)))) is floating-point reordering noise — acceptable; document it. Error orders of magnitude above it is a bug, however clean the algebra looked. Watch for catastrophic cancellation: an algebraically exact shortcut (e.g. the running-sums variance formula) can be dramatically faster and still wrong on data with a large mean offset. Subtract the mean first, then check the result against the tolerance again.

An error of exactly 0 proves nothing on its own. Also record an independent statistic of the optimized output (min(fast(:)), a checksum) — see references/measurement-protocol.md.

Step 7: Report Results

Report the baseline, the optimized time, the speedup (for each change and end to end), the max error, and the pattern applied. If you followed the verified-result protocol in Step 5, perf_report.json is the deliverable and this is its human-readable summary.

Key Rules

1. Always profile before optimizing — never guess where the bottleneck is

2. Measure the ceiling before you optimize — remove or hoist the suspect and re-time end-to-end; that difference, not the profiler's % column, is the ceiling on what a rewrite can win (this step is ablation)

3. One change at a time — measure after each optimization to know what helped

4. Verify correctness — every optimization must produce equivalent output, with a tolerance scaled to the output

5. Report end-to-end — the headline number is the whole workload; a sub-kernel speedup is reported separately and labelled as such

6. Every reported number comes from a variable — computed by a run of the current code, never typed in from memory

7. 1.2x threshold — speedups below 1.2x are not reliably distinguishable from noise

8. GPU timing — always wait(gpuDevice) before and after timing GPU code

9. Use timeit — it handles warmup and averaging; avoid raw tic/toc for benchmarks

10. On R2026a, clear what you profiled before you time anything — code run under profile on R2026a stays ~100x slower for the rest of the session until you clear it, so a baseline taken after a profiled run flatters every "after" number. R2026a also has no Sampling Profiler.

Common Mistakes

Reference Files

• references/measurement-protocol.md — the verified-result protocol for Step 5 and every perf_report.json field

• references/sampling-profiler.md — Sampling Profiler (R2026b+): commands, results model, traps, and the scripts/ helper index

• references/optimization-patterns.md — the pattern catalog, with before/after code and measured speedups

• assets/measurement-templates.md — templates for a timeit baseline, GPU timing, and a scaling test

• scripts/ — MATLAB helpers for the Sampling Profiler; addpath this folder to use them

Copyright 2026 The MathWorks, Inc.