## Resolve “Out of Memory” Errors

### Issue

When your code operates on large amounts of data or does not use memory
efficiently, MATLAB^{®} might produce an error in response to an unreasonable array size, or
it might run out of memory. MATLAB has built-in protection against creating arrays that are too large.
For example, this code results in an error, because MATLAB cannot create an array with the requested number of elements.

A = rand(1e9);

`Requested array exceeds the maximum possible variable size.`

By default, MATLAB can use up to 100% of the RAM (not including virtual memory) of your computer to allocate memory for arrays, and if an array size would exceed that threshold, then MATLAB produces an error. For example, this code attempts to create an array whose size exceeds the maximum array size limit.

B = rand(1e6);

```
Requested 1000000x1000000 (7450.6GB) array exceeds maximum array size preference (63.7GB). This might cause MATLAB to become
unresponsive.
```

If you turn off the array size limit in **MATLAB Workspace
Preferences**, attempting to create an unreasonably large array might
cause MATLAB to run out of memory, or it might make MATLAB or even your computer unresponsive due to excessive memory paging
(that is, moving memory pages between RAM and disk).

B = rand(1e6);

`Out of memory.`

### Possible Solutions

No matter how you run into memory limits, MATLAB provides several solutions depending on your situation and goals. For example, you can improve the way your code uses memory, leverage specialized data structures such as datastores and tall arrays, take advantage of pooled resources within a computing cluster, or make adjustments to your settings and preferences.

**Note**

The solutions presented here are specific to MATLAB. To optimize system-wide memory performance, consider adding more physical memory (RAM) to your computer or making adjustments at the operating system level.

**Clear Variables When No Longer Needed**

Make it a practice to clear variables when they are no longer needed. To clear
items from memory, use the `clear`

function.

Before | After |
---|---|

```
A = rand(1e4);
disp(max(A,[],"all"))
B = rand(1e4);
``` |
A = rand(1e4); disp(max(A,[],"all")) clear A B = rand(1e4); |

For more information, see Strategies for Efficient Use of Memory.

#### Use Appropriate Data Storage

Memory requirements differ for MATLAB data types. You might be able to reduce the amount of memory used by your code by using the appropriate data type and storage. For more information about the solutions in this section, see Strategies for Efficient Use of Memory.

**Use the Appropriate Numeric Class. **The numeric class you should use depends on your intended actions. In
MATLAB, `double`

is the default numeric data type
and provides sufficient precision for most computational tasks:

If you want to perform complicated math such as linear algebra, use floating-point numbers in either double-precision (

`double`

) or single-precision (`single`

) format. Numbers of type`single`

require less memory than numbers of type`double`

, but are also represented to less precision.If you just need to carry out simple arithmetic and you represent the original data as integers, use the integer classes in MATLAB.

Class (Data Type) | Bytes | Supported Operations |
---|---|---|

`single` | 4 | Most math |

`double` | 8 | All math |

`logical` | 1 | Logical/conditional operations |

`int8, uint8` | 1 | Arithmetic and some simple functions |

`int16, uint16` | 2 | Arithmetic and some simple functions |

`int32, uint32` | 4 | Arithmetic and some simple functions |

`int64, uint64` | 8 | Arithmetic and some simple functions |

**Reduce the Amount of Overhead When Storing Data. **When you create a numeric or character array, MATLAB allocates a block of memory to store the array data.
MATLAB also stores information about the array data, such as its
class and dimensions, in a small, separate block of memory called a
*header*. Because simple numeric and character arrays
have the least overhead, use them whenever possible. Use other data
structures only for data that is too complex to store in a simple
array.

For structures and cell arrays, MATLAB creates a header not only for the array, but also for each field of the structure or each cell of the cell array. Therefore, the amount of memory required to store a structure or cell array depends not only on how much data it holds, but also on how it is constructed. As a result, cell arrays with many small elements or structures with many fields containing little content have large overhead and should be avoided.

Before | After |
---|---|

% S has 15,000 fields (3 fields per array element) for i = 1:100 for j = 1:50 S(i,j).R = 0; % Each field contains a numeric scalar S(i,j).G = 0; S(i,j).B = 0; end end |
% S has 3 fields S.R = zeros(100,50); % Each field contains a numeric array S.G = zeros(100,50); S.B = zeros(100,50); |

**Make Arrays Sparse When Possible. **A good practice is to store matrices with few nonzero elements using
sparse storage. When a full matrix has a small number of nonzero elements,
converting the matrix to sparse storage typically improves memory usage and
code execution time. MATLAB has several functions that support sparse storage. For
example, you can use the `speye`

function to create a
sparse identity matrix.

Before | After |
---|---|

I = eye(1000); |
I = speye(1000); |

**Import Data Using the Appropriate MATLAB Class. **When reading data from a binary file with `fread`

, a common mistake is
to specify only the class of the data in the file and not the class of the
data MATLAB uses once it is in the workspace. If you do not specify the
class of the data in memory, MATLAB uses `double`

even if you read 8-bit
values.

Before | After |
---|---|

fileID = fopen("large_file_of_uint8s.bin","r"); A = fread(fileID,1e3,"uint8"); |
fileID = fopen("large_file_of_uint8s.bin","r"); A = fread(fileID,1e3,"uint8=>uint8"); |

#### Avoid Unnecessary Copies of Data

To improve memory usage and execution speed, make sure your code does not result in unnecessary copies of data. For more information about the solutions in this section, see Avoid Unnecessary Copies of Data and Strategies for Efficient Use of Memory.

**Avoid Creating Temporary Arrays. **Avoid creating temporary arrays when they are not necessary. For example,
instead of creating an array of zeros as a temporary variable and then
passing that variable to a function, use one command to do both
operations.

Before | After |
---|---|

A = zeros(1e6,1); As = single(A); |
```
As = zeros(1e6,1,"single");
``` |

**Preallocate Memory. **When you work with large data sets, repeatedly resizing arrays might cause
your program to run out of memory. If you expand an array beyond the
available contiguous memory of its original location, MATLAB must make a copy of the array and move the copy into a memory
block with sufficient space. During this process, two copies of the original
array exist in memory. You can improve the memory usage and code execution
time by preallocating the maximum amount of space required for the array.
For more information, see Preallocation.

Before | After |
---|---|

x = 0; for k = 2:1000000 x(k) = x(k-1) + 5; end |
x = zeros(1,1000000); for k = 2:1000000 x(k) = x(k-1) + 5; end |

**Use Nested Functions to Pass Fewer Arguments. **When calling a function, MATLAB typically makes a temporary copy of the variable in the
caller's workspace if the function modifies its value. MATLAB applies various techniques to avoid making unnecessary copies,
but avoiding a temporary copy of an input variable is not always
possible.

One way to avoid temporary copies in function calls is to use nested functions. A nested function shares the workspace of all outer functions, so you do not need to pass a copy of variables in the function call. For more information, see Nested Functions.

#### Load Only as Much Data as You Need

One way to fix memory issues is to import into MATLAB only as much of a large data set as you need for the problem you are trying to solve. Data set size is not usually a problem when importing from sources such as a database, where you can explicitly search for elements matching a query. But it is a common problem with loading large flat text or binary files.

The `datastore`

function lets you
work with large data sets incrementally. Datastores are useful any time you want
to load only some portions of a data set into memory at a time.

To create a datastore, provide the name of a file or a directory containing a collection of files with similar formatting. For example, with a single file, use the following.

`ds = datastore("path/to/file.csv");`

`ds = datastore("path/to/folder/");`

`*`

to select all files of
a specific
type.`ds = datastore("path/to/*.csv");`

Aside from datastores, MATLAB also has several other functions to load parts of files. This table summarizes the functions by the type of files they operate on.

File Type | Partial Loading |
---|---|

MAT-file | Load part of a variable by indexing into an object that
you create with the |

Text | Use the |

Binary | You can use low-level binary file I/O functions, such
as |

Image, Audio, Video, and HDF | Many of the MATLAB functions that support loading from these types of files allow you to select portions of the data to read. For details, see the function reference pages listed in Supported File Formats for Import and Export. |

#### Use Tall Arrays

Tall arrays help you work with data sets that are too large to fit in memory. MATLAB works with small blocks of the data at a time, automatically handling all of the data chunking and processing in the background. You can use tall arrays in two primary ways:

If you have a large array that fits in memory, but you run out of memory when you try to perform calculations, you can cast the array to a tall array.

This approach lets you work with large arrays that can fit in memory, but that consume too much memory to allow for copies of the data during calculations. For example, if you have 8 GB of RAM and a 5 GB matrix, casting the matrix to a tall array enables you to perform calculations on the matrix without running out of memory. For an example of this usage, seet = tall(A);

`tall`

.If you have file- or folder-based data, you can create a datastore and then create a tall array on top of the datastore.

This approach gives you the full power of tall arrays in MATLAB. The data can have any number of rows and MATLAB does not run out of memory. And because`ds = datastore("path/to/file.csv"); t = tall(ds);`

`datastore`

works with both local and remote data locations, the data you work with does not need to be on the computer you use to analyze it. See Work with Remote Data for more information.

To learn more about tall arrays, see Tall Arrays for Out-of-Memory Data.

#### Use Memory of Multiple Machines

If you have a cluster of computers, you can use distributed arrays (requires Parallel Computing Toolbox™) to perform calculations using the combined memory of all the machines in the cluster. Depending on how your data fits in memory, different ways to partition data among workers of a parallel pool exist. For more information, see Distributing Arrays to Parallel Workers (Parallel Computing Toolbox).

#### Adjust Settings and Preferences

Generally, rewriting code is the most effective way to improve memory performance. However, if you cannot make changes to your code, these solutions might provide it with the required amount of memory.

**Start MATLAB Without Java Virtual Machine or Decrease the Java Heap Size. **If you either start MATLAB without the Java^{®} Virtual Machine (JVM™) software or decrease the Java heap size, you can increase the available workspace memory. To
start MATLAB without JVM, use the command-line option `-nojvm`

. For
information on how to decrease the Java heap size, see Java Heap Memory Preferences.

Using `-nojvm`

comes with a penalty in that you lose
several features that rely on JVM, such as the desktop tools and graphics. Starting MATLAB with the `-nodesktop`

option does not save
any substantial amount of memory.

**Adjust the Array Size Limit. **If you face an error stating that the array size exceeds the maximum array
size preference, you can adjust this array size limit in MATLAB. For information on adjusting the array size limit, see Workspace and Variable Preferences. This solution is helpful only if the
array you want to create exceeds the current maximum array size limit but is
not too large to fit in memory. Even if you turn off the array size limit,
attempting to create an unreasonably large array might cause MATLAB to run out of memory, or it might make MATLAB or even your computer unresponsive due to excessive memory
paging.

## See Also

`memory`

| `whos`

| `datastore`

| `tall`