This topic provides information on how MATLAB^{®} allocates memory when working with arrays and variables. The purpose
is to help you use memory more efficiently when writing code. Most of the time,
however, you should not need to be concerned with these internal operations as
MATLAB handles data storage for you automatically.

**Note**

Any information on how the MATLAB software handles data internally is subject to change in future releases.

When you assign a numeric or character array to a variable, MATLAB allocates a contiguous virtual block of memory and stores the array data in that block. MATLAB also stores information about the array data, such as its class and dimensions, in a separate, small block of memory called a *header*.

If you add new elements to an existing array, MATLAB expands the existing array in memory in a way that keeps its storage contiguous. This usually requires finding a new block of memory large enough to hold the expanded array. MATLAB then copies the contents of the array from its original location to this new block in memory, adds the new elements to the array in this block, and frees up the original array location in memory.

If you remove elements from an existing array, MATLAB keeps the memory storage contiguous by removing the deleted elements, and then compacting its storage in the original memory location.

**Working with Large Data Sets. **If you are working with large data sets, you need to be careful when increasing the size of an array to avoid getting errors caused by insufficient memory. If you expand the array beyond the available contiguous memory of its original location, MATLAB must make a copy of the array and set this copy to the new value. During this operation, there are two copies of the original array in memory. This temporarily doubles the amount of memory required for the array and increases the risk of your program running out of memory during execution. It is better to preallocate sufficient memory for the largest potential size of the array at the start. See Preallocation.

Internally, multiple variables can point to the same block of data, thus sharing that array's value. When you copy a variable to another variable (e.g., `B = A`

), MATLAB makes a copy of the array reference, but not the array itself. As long as you do not modify the contents of the array, there is no need to store more than one copy of it. If you do modify any elements of the array, MATLAB makes a copy of the array and then modifies that copy.

This example uses the `memory`

function to demonstrate how MATLAB handles copying arrays. `memory`

is available only on Windows^{®} systems.

Start by creating a simple script `memUsed.m`

to display how much memory is being used by your MATLAB process. Put these two lines of code in the script.

[usr, sys] = memory; usr.MemUsedMATLAB

Get an initial reading of how much memory is being used by your MATLAB process:

format short eng; memUsed ans = 295.4977e+006

Create a 2000-by-2000 numeric array A. This uses about 32MB of memory:

```
A = magic(2000);
memUsed
ans =
327.6349e+006
```

Make a copy of array `A`

in `B`

. As there is no need to have two copies of the array data, MATLAB only makes a copy of the array reference. This requires no significant additional memory:

```
B = A;
memUsed
ans =
327.6349e+006
```

Now modify `B`

by making it one half its original size (that is, set 1000 rows to empty). This requires that MATLAB make a copy of at least the first 1000 rows of the `A`

array, and assign that copy to `B`

:

B(1001:2000,:) = []; format short; size(B) ans = 1000 2000

Check the memory used again. Even though `B`

is significantly smaller than it was originally, the amount of memory used by the MATLAB process has increased by about 16 MB (1/2 of the 32 MB originally required for `A`

) because `B`

could no longer remain as just a reference to `A`

:

format short eng; memUsed ans = 343.6421e+006

When you assign an array to a variable, MATLAB also stores information about the array (such as class and dimensions) in a separate piece of memory called a header. For most arrays, the memory required to store the header is insignificant. There is a small advantage to storing large data sets in a small number of large arrays as opposed to a large number of small arrays. This is because the former configuration requires fewer array headers.

**Structure and Cell Arrays. **For structures and cell arrays, MATLAB creates a header not only for each array, but also for each field of the structure and for each cell of a cell array. Because of this, 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.

For example, take a scalar structure array `S1`

having fields `R`

, `G`

, and `B`

. Each field of size 100-by-50 requires one array header to describe the overall structure, one header for each unique field name, and one header per field for the 1-by-1 structure array. This makes a total of seven array headers for the entire data structure:

S1.R(1:100,1:50) S1.G(1:100,1:50) S1.B(1:100,1:50)

On the other hand, take a 100-by-50 structure array `S2`

in which each element has scalar fields `R`

, `G`

, and `B`

. In this case, you need one array header to describe the overall structure, one for each unique field name, and one per field for each of the 5,000 elements of the structure, making a total of 15,004 array headers for the entire data structure:

S2(1:100,1:50).R S2(1:100,1:50).G S2(1:100,1:50).B

Even though `S1`

and `S2`

contain the same amount of data, `S1`

uses significantly less space in memory. Not only is less memory required, but there is a corresponding speed benefit to using the `S1`

format, as well.

See “Cell Arrays” and “Structures” under Data Structures and Memory.

**Memory Usage Reported By the whos Function. **The `whos`

function displays the amount of memory consumed by any variable. For reasons of simplicity, `whos`

reports only the memory used to store the actual data. It does not report storage for the array header, for example.

MATLAB handles arguments passed in function calls in a similar way. When you pass a variable to a function, you are actually passing a reference to the data that the variable represents. As long as the input data is not modified by the function being called, the variable in the calling function and the variable in the called function point to the same location in memory. If the called function modifies the value of the input data, then MATLAB makes a copy of the original array in a new location in memory, updates that copy with the modified value, and points the input variable in the called function to this new array.

In the example below, function `myfun`

modifies the value of the array passed into it. MATLAB makes a copy in memory of the array pointed to by `A`

, sets variable `X`

as a reference to this new array, and then sets one row of `X`

to zero. The array referenced by `A`

remains unchanged:

A = magic(500); myfun(A); function myfun(X) X(400,:) = 0;

If the calling function needs the modified value of the array it passed to `myfun`

, you need to return the updated array as an output of the called function, as shown here for variable `A`

:

A = magic(500); A = myfun(A); sprintf('The new value of A is %d', A) function Y = myfun(X) X(400,:) = 0; Y = X;

Memory requirements differ for the various types of MATLAB data structures. You might be able to reduce the amount of memory used for these structures by considering how MATLAB stores them.

MATLAB requires 1, 2, 4, or 8 bytes to store 8-bit, 16-bit, 32-bit, and 64-bit signed and unsigned integers, respectively. For floating-point numbers, MATLAB uses 4 or 8 bytes for `single`

and `double`

types. To conserve memory when working with numeric arrays, MathWorks^{®} recommends that you use the smallest integer or floating-point type that contains your data without overflowing. For more information, see Numeric Types.

MATLAB uses an interleaved storage representation of complex numbers, where the real and imaginary parts are stored together in a contiguous virtual block of memory. If you make a copy of a complex array, and then modify only the real or imaginary part of the array, MATLAB creates an array containing both real and imaginary parts. For more information, see MATLAB Support for Interleaved Complex API in MEX Functions.

It is best to store matrices with values that are mostly zero in sparse format. Sparse matrices can use less memory and might also be faster to manipulate than full matrices. You can convert a full matrix to sparse format using the `sparse`

function.

Compare two 1000-by-1000 matrices: `X`

, a matrix of doubles with 2/3 of its elements equal to zero; and `Y`

, a sparse copy of `X`

. The following example shows that the sparse matrix requires approximately half as much memory:

whos Name Size Bytes Class X 1000x1000 8000000 double array Y 1000x1000 4004000 double array (sparse)

In addition to data storage, cell arrays require additional memory to store
information describing each cell. This information is recorded in a
*header*, and there is one header for each cell of the
array. You can determine the amount of memory required for a cell array header
by finding the number of bytes consumed by a 1-by-1 cell that contains no data,
as shown below for a 64-bit system:

C = {[]}; % Empty cell array whos C Name Size Bytes Class Attributes C 1x1 104 cell

To predict the size of an entire cell array, multiply the header size by the total number of cells in the array, and then add to that the number of bytes required for the data you intend to store in the array:

(header_size x number_of_cells) + data

For example, a 10-by-20 cell array that contains 400 bytes of data would require 21,200 bytes of memory on a 64-bit system:

(104 x 200) + 400 = 21200

**Note**

While numeric arrays must be stored in contiguous memory, structures and cell arrays do not.

**Example – Memory Allocation for a Cell Array. **This 4-by-1 cell array records the brand name, screen size, price, and
on-sale status for three laptop computers:

Laptops = {['SuperrrFast 89X', 'ReliablePlus G5', ... 'UCanA4dIt 140L6']; ... [single(17), single(15.4), single(14.1)]; ... [2499.99, 1199.99, 499.99]; ... [true, true, false]};

On a 64-bit system, the cell array header alone requires 104 bytes per cell:

4 cells * 104 bytes per cell = 416 bytes for the cell array

Calculate the memory required to contain the data in each of the four cells:

45 characters * 2 bytes per char = 90 bytes 3 singles * 4 bytes per single = 12 bytes 3 doubles * 8 bytes per double = 24 bytes 3 logicals * 1 byte per logical = 3 bytes 90 + 12 + 24 + 3 = 129 bytes for the data

Add the two, and then compare your result with the size returned by MATLAB:

416 + 129 = 545 bytes total whos Laptops Name Size Bytes Class Attributes Laptops 4x1 545 cell

On a 64-bit system, each field of a structure array requires a 104-byte header. In addition, each unique field name requires a 64-byte header. For example, a structure with one empty field consumes 168 bytes (104 bytes for the field and 64 bytes for the field name):

S.A = []; whos S Name Size Bytes Class Attributes S 1x1 168 struct

To predict the size of an entire structure array, calculate the total number of header bytes, and then add to that the number of bytes required for the data you intend to store in the array:

number_of_fields x ((number_of_array_elements x field_header_size) + fieldname_header_size) + data

For example, a 4-by-5 structure `Clients`

with fields
`Address`

and `Phone`

uses 4,288 bytes
just for the headers:

2 x ((20 x 104) + 64) = 4288 bytes

To that sum, you must add the memory required to hold the data assigned to
each field. If you assign a 25-character vector to `Address`

and a 12-character vector to `Phone`

in each element of the
4-by-5 `Clients`

array, you need 1,480 bytes for data:

(25+12) characters * 2 bytes per char * 20 elements = 1480 bytes

Add the two and you see that the entire structure consumes 5,768 bytes of memory.

**Example – Memory Allocation for a Structure Array. **Calculate the amount of memory required on a 64-bit system to store a
6-by-5 structure array with these field values:

A: 5-by-8-by-6 signed 8-bit integer array B: 1-by-500 single array C: 30-by-30 unsigned 16-bit integer array D: 1-by-23 character array

Construct the array:

A = int8(ones(5,8,6)); B = single(1:500); C = uint16(magic(30)); D = 'Company Name: MathWorks'; S = struct('f1',A,'f2',B,'f3',C,'f4',D); for m = 1:6 for n = 1:5 S(m,n) = S(1,1); end end

Calculate the amount of memory required for the structure itself, and then for the data it contains:

structure = fields x ((array elements x 104) + 64) = 4 x ((30 x 104) + 64) = 12,736 bytes data = (field1 + field2 + field3 + field4) x array elements = (240 + 2000 + 1800 + 46) x 30 = 122,580 bytes

Add the two, and then compare your result with the size returned by MATLAB:

Total bytes calculated for structure S: 12,736 + 122,580 = 135,316 whos S Name Size Bytes Class Attributes S 6x5 135316 struct