stanfish06 MATLAB Memory Optimization Workflow
Systematic 7-step workflow for finding and fixing memory bottlenecks in MATLAB code.
When to Use
- User gets out-of-memory errors running MATLAB code
- User wants to reduce memory usage of their MATLAB program
- User wants to process larger datasets without running out of memory
- User asks to profile or measure memory allocations
When NOT to Use
- The bottleneck is execution speed, not memory (use
matlab-optimize-performance) - The memory issue is in compiled C/MEX code that can't be changed at the M-code level
- Memory usage is dominated by I/O buffers (memory-mapped files, database connections)
The 7-Step Workflow
Step 1: Establish Memory Baseline
Measure current memory usage before making changes.
m0 = memory;
targetFunction(inputs);
m1 = memory;
deltaBytes = m1.MemUsedMATLAB - m0.MemUsedMATLAB;
fprintf('Memory delta: %.2f MB\n', deltaBytes / 1e6);
When memory errors (Linux/macOS), use whos for variable sizes or Java runtime for heap:
info = whos('result');
fprintf('Variable size: %.2f MB\n', info.bytes / 1e6);
Step 2: Profile Memory Allocations
Find where memory is being allocated.
profile('-memory', 'on');
for iter = 1:5
targetFunction(inputs);
end
profile off;
p = profile('info');
ft = p.FunctionTable;
[~, idx] = sort([ft.TotalMemAllocated], 'descend');
for i = 1:min(15, numel(idx))
f = ft(idx(i));
fprintf('%-40s %10.2f MB\n', f.FunctionName, f.TotalMemAllocated/1e6);
end
If TotalMemAllocated fields are zero, fall back to whos snapshots before/after each function call.
Key things to look for:
- Functions with high "Allocated" but low "Freed" — memory is retained
- Functions called many times with moderate allocations — total adds up
- Large gaps between Allocated and Freed — temporaries accumulating
Step 3: Identify Optimization Opportunities
Based on profiling, identify which patterns apply. See references/memory-patterns.md for code examples.
| Pattern | Typical Reduction | Look For |
|---|---|---|
Cell collection + vertcat |
O(N²) → O(N) | [arr; newRow] inside loops |
Implicit expansion over repmat |
Eliminates full copy | repmat(A, [1 1 K]) for broadcasting |
| Clear variables when done | Immediate reclamation | Large arrays used only in early steps |
| Break chained expressions | 1 fewer peak temporary | a.*b.*c./d all alive at once |
| Reuse variables (overwrite in-place) | Avoids output allocation | Separate variables for each step |
max/min instead of masking |
Eliminates logical temporary | x .* (x > 0) pattern |
zeros(...,'like',x) |
Eliminates temporaries | 0 * x to create zeros |
| Copy-on-write sharing | Shares backing memory | Same array assigned to multiple places |
| Dense → sparse | O(N²) → O(N·bw) | zeros(N,N) where N > 10000 |
Step 4: Implement Optimizations
Apply the identified patterns. Focus only on the hotspots identified in Step 2 — do not apply patterns everywhere.
Step 5: Measure Optimized Memory
Re-measure using the same method as Step 1:
m0 = memory;
optimizedFunction(inputs);
m1 = memory;
deltaOpt = m1.MemUsedMATLAB - m0.MemUsedMATLAB;
reduction = 1 - deltaOpt / deltaBytes;
fprintf('Optimized: %.2f MB (%.0f%% reduction)\n', deltaOpt/1e6, reduction*100);
Step 6: Verify Correctness
Every optimization must produce the same results:
original = originalFunction(inputs);
optimized = optimizedFunction(inputs);
maxErr = max(abs(original(:) - optimized(:)));
fprintf('Max error: %.2e\n', maxErr);
assert(maxErr < 1e-10, 'Results differ!');
Step 7: Report Results
Summarize the memory optimization with baseline, optimized, reduction percentage, correctness check, and patterns applied.
Key Rules
- Never propose optimizations based solely on reading source code — always measure and profile first
- Verify correctness — memory optimizations must produce identical results
- Clear variables early — free memory as soon as data is no longer needed
- Avoid growing arrays — preallocate or use cell collection
- Break chains — sequential assignment reduces peak memory vs chained expressions
- Watch for copies — MATLAB copies on write; reuse variables to avoid duplicates
Platform Notes
- Windows:
memorycommand returns full statistics (MemUsedMATLAB, etc.) - Linux/macOS:
memoryerrors ("not supported on this platform"). Usewhosfor variable sizes, JavaRuntime.getRuntimefor heap usage, or OS-level RSS viasystem('ps ...') profile -memory: Works on all platforms but is undocumented since R2016a. When unavailable, usewhossnapshots before/after function calls.
Copyright 2026 The MathWorks, Inc.