Step-by-Step Guide to Debugging Out-of-Memory Errors in MATLAB

Out-of-memory (OOM) errors occur when MATLAB exceeds available RAM. These errors often arise when working with large datasets, matrices, or inefficient code. Below is a structured approach to diagnose and resolve these issues.

1. Diagnose the Source of the Error

Error Message Example:

Error using rand
Out of memory. Type HELP MEMORY for your options.

Tools to Investigate:

• memory Command:
  matlab

  Copy

  [user, sys] = memory;  
  disp(user);   % Shows available memory for MATLAB  
  disp(sys);    % Shows total system memory  

• whos Command:
  matlab

  Copy

  whos          % Lists variables in workspace and their memory usage  

• Memory Profiler:
  matlab

  Copy

  profile -memory on;  
  % Run your code  
  profile viewer;

2. Common Causes & Solutions

A. Large Variables or Arrays

Issue: Creating massive matrices (e.g., rand(1e4, 1e4) requires ~800 MB).
Solutions:

• Use Sparse Matrices for data with many zeros.
  matlab

  Copy

  S = sparse(1e4, 1e4); % Allocates memory only for non-zero elements  

• Downcast Data Types:
  matlab

  Copy

  % Replace double with single (halves memory usage)  
  data = single(rand(1000));

• Avoid Unnecessary Copies:
  matlab

  Copy

  A = A .* 2;   % In-place operation (avoids creating a new matrix)  

B. Memory Fragmentation

Issue: Repeated allocation/deallocation fragments memory.
Solutions:

• Preallocate Arrays:
  matlab

  Copy

  result = zeros(1e6, 1); % Preallocate instead of dynamically expanding  

• Clear Unused Variables:
  matlab

  Copy

  clear var1 var2;

• Use pack Command (defragments memory):
  matlab

  Copy

  pack;

C. System Limitations

Issue: 32-bit MATLAB or insufficient RAM.
Solutions:

• Switch to 64-bit MATLAB (supports larger memory allocation).
• Upgrade Physical RAM or use a system with more memory.
• Increase Virtual Memory (Pagefile):
  • Windows: Adjust via System Properties > Advanced > Performance Settings.

D. Memory Leaks

Issue: Unreleased memory due to persistent variables or handle objects.
Solutions:

• Use clear all to reset the workspace (caution: deletes all variables).
• Avoid Global/Persistent Variables unless necessary.
• Close Figures/Objects:
  matlab

  Copy

  close all;     % Close figures  
  delete(gcf);   % Delete graphics objects  

3. Advanced Workarounds

A. Process Data in Chunks

Load/process subsets of large datasets sequentially.
Example:

for i = 1:numChunks  
    chunk = read(dataSource, i);  
    process(chunk);  
end

B. Use Memory-Mapped Files

Access disk-stored data as if it’s in memory.

m = memmapfile('largeFile.bin', 'Format', 'double', 'Writable', true);  
data = m.Data; % Access without loading entire file into RAM  

C. Optimize Code for Memory

• Replace Loops with Vectorization (reduces temporary variables).
• Use repmat Alternatives:
  matlab

  Copy

  % Instead of repmat(A, 100, 100), use:  
  B = A(ones(100,1), ones(100,1));

D. Leverage GPU or Distributed Computing

Offload computations to GPU or cluster.

if gpuDeviceCount > 0  
    gpuArrayData = gpuArray(largeData);  
    result = gather(processOnGPU(gpuArrayData));  
end

4. Example Workflow

Scenario: Loading a 10 GB CSV file causes OOM.
Solution:

1. Check System Memory:
   matlab

   Copy

   [~, sys] = memory;  
   if sys.PhysicalMemory.Available < 10e9  
       error("Insufficient RAM.");  
   end

2. Load in Chunks:
   matlab

   Copy

   opts = detectImportOptions('largeFile.csv');  
   opts.DataRange = '1:1000';  
   chunk1 = readtable('largeFile.csv', opts);

3. Use datastore for Large Files:
   matlab

   Copy

   ds = datastore('largeFile.csv');  
   while hasdata(ds)  
      chunk = read(ds);  
      process(chunk);  
   end

5. Prevention Best Practices

• Monitor Memory with memory or whos during code development.
• Test Code with Small Data before scaling up.
• Use Efficient Data Structures:
  • Replace cell arrays with matrices where possible.
  • Use categorical for string data.

Debugging Checklist

1. Check system and MATLAB memory limits.
2. Profile memory usage with profile -memory on.
3. Downcast data types (e.g., single instead of double).
4. Clear unused variables and preallocate arrays.
5. Use disk-based storage (e.g., memmapfile, datastore).

By systematically addressing memory allocation, optimizing data structures, and leveraging disk resources, you can resolve most OOM errors in MATLAB.