"Out of memory" errors occur when MATLAB® requests more memory from the operating system than is available. For example on a 32-bit platform, the following command results in an error:
>> a=rand(1e9,1); % Requires approximately 8GB of memory
??? Error using ==> rand
Out of memory. Type HELP MEMORY for your options.
A single desktop computer has a finite amount of memory available to satisfy the needs of the applications running on it to store and process their data as well as to accommodate the code and internal state of the application itself. Memory is provided by the system in different forms (e.g., RAM, disk, virtual) and there are a number of limits associated with these due to the software and hardware characteristics of the computer.
Solutions to "Out of Memory" problems fall into two main categories:
- Maximizing the memory available to MATLAB (i.e., removing or increasing limits) on your system via operating system selection and system configuration. These usually have the greatest overall applicability but are potentially the most disruptive (e.g. using a different operating system). These techniques are covered in the first two sections of this document.
- Minimizing the memory used by MATLAB by making your code more memory efficient. These are all algorithm and application specific and therefore are less broadly applicable. These techniques are covered in later sections of this document.
Which of these solutions is the most appropriate for you depends on your particular system configuration and application. The techniques are mainly independent and can be tried in any order.
The last section of this document contains a list of tools that give information about used and available memory and also a list of resources to get further information.
These techniques are all designed to increase available memory or reduce consumed memory. See the Jun 2007 News and Notes article Maximizing Code Performance by Optimizing Memory Access for techniques designed to increase performance related to memory access.
Contents
- Maximizing memory available to MATLAB
- Maximizing size of largest contiguous block of memory (32-bit Windows only)
- Minimizing the memory used by avoiding common coding mistakes
- Minimizing the memory used during data import or creation
- Minimizing the memory used when selecting a variable data type
- Minimizing the memory used while your code is running
- Minimizing the memory used when plotting data
- Tools to measure used and available memory in your system and by MATLAB
- Other Resources
Maximizing memory available to MATLAB
The techniques in the next two sections involve computer system selection and configuration and are most appropriate to consider when you are frequently experiencing "Out of Memory" errors and you are looking at a long term solution. Where system configuration change is not possible or you wish to solve a problem related to just one MATLAB M file or application, see the subsequent sections for techniques involving minimizing memory usage.
The memory availability measurements listed in the following section were carried with MATLAB 7.4, part of release 2007a. Other versions of MATLAB may give slightly different results.
Be aware of the memory limitations of different operating systems
The platforms and operating systems that MATLAB supports have different memory characteristics and limitations. In particular, the processor limit is the maximum amount of virtual memory a single process (application) can address. On 32-bit systems this is the most important factor limiting data set size. The process limit must be large enough for MATLAB to store all the data it is to process, plus M code, the MATLAB executable itself and other state. Where possible, choose an operating system that maximizes this number, i.e. a 64-bit operating system. The following is a list of MATLAB supported operating systems and their process limits.
Operating system | Process Limit |
32-bit Windows XP, Vista and Windows 2000 (default) | 2GB |
32-bit Windows XP with 3GB boot.ini switch or 32-bit Vista with increaseuserva set (see later) | 3GB |
32-bit Linux | ~3GB |
64-bit Windows XP, MAC OSX, Linux or Solaris running 32-bit MATLAB | ≤4GB |
64-bit Windows XP, Vista, Linux or Solaris running 64-bit MATLAB | 8TB |
To verify the current process limit of MATLAB on Windows, run the ‘feature memstats’ command:
>> feature memstats
<snip>
Virtual Memory (Address Space):
In Use: 314 MB (13a7a000)
Free: 1733 MB (6c566000)
Total: 2047 MB (7ffe0000)
View the value against the Total entry in the Virtual Memory section, 2GB here, which is the default on Windows XP. On Unix see the ulimit command to view and set user limits including virtual memory.
Set the 3GB switch on 32-bit Windows XP (32-bit Windows XP only)
Microsoft Windows XP can allocate 3GB instead of the default 2GB to processes if you set an appropriate switch in the boot.ini file of the system. (Note that, although XP isnot one of the operating systems listed on the web page linked to in the previous sentence, it does support this capability). It is recommended that you only do this with Windows XP SP2 and later. This gives an extra 1GB of virtual memory to MATLAB, not contiguous with the rest of the memory. This enables you to store more data but not larger arrays, as these are limited by contiguous space (Contiguous memory is discussed later in this document). This is mostly beneficial if you have enough RAM e.g. 3 or 4 GB to use it. After setting the switch, confirm the new value of the virtual memory after restarting your computer and running the ‘feature memstats’ command.
>> feature memstats
…
Virtual Memory (Address Space):
In Use: 314 MB (13a7a000)
Free: 1733 MB (6c566000)
Total: 3047 MB (7ffe0000)
Here, the value is now 3GB.
For 32-bit Windows Vista use: BCDEdit /set increaseuserva 3072
Maximize total system memory - RAM and page/swap file
A basic knowledge of how virtual memory works is important to understand much of this material but is not covered here in detail. The Memory Management Guide contains an introduction to this.
The total memory available to the applications on your computer is comprised of physical memory (RAM) plus the page or swap file on disk. RAM is more expensive, but accessing data stored in RAM is orders of magnitude faster than accessing data stored on disk. The operating system allocates the virtual memory of each process to either physical RAM or a swap file on disk, depending on its needs and those of other processes.
Your operating system normally uses a page file (which is usually larger than your physical RAM) for extra memory. This file can be very large, even on 32-bit systems (e.g. 16TB on 32-bit windows, 512TB on 64-bit Windows).
The amount of RAM in a system primarily affects its speed rather than the chance of "Out of Memory" errors. For maximum MATLAB execution performance ensure that you memory usage does not surpass your physical RAM. You can monitor total used and available memory with appropriate operating system tools (the task manager in Windows or with the top command in Unix). You should normally add as much RAM as your budget can accommodate. On 32-bit machines the most RAM you can have is 4GB.
Be aware of the total workspace size limit
Assuming that the system MATLAB is running on has enough available total system memory, the MATLAB workspace size limit is the process limit minus any memory required by MATLAB itself. The workspace size limit determines the upper limit on the amount of data MATLAB can handle at one time. Estimate the availableworkspace size by viewing the Free entry in the Virtual Memory section of ‘feature memstats’:
>> feature memstats
<snip>
Virtual Memory (Address Space):
In Use: 314 MB (13a7a000)
Free: 1733 MB (6c566000)
Total: 2047 MB (7ffe0000)
This will be approximately 1.7 GB for 32-bit Windows XP, or 2.7 GB for 32-bit Windows XP with the 3gb switch set. On Unix, this depends on the limit set by the system administrator, but is typically more than this. On 64-bit systems, this is limited by total system memory (RAM + SWAP) and is rarely reached (Total available workspace size for all supported platforms is shown in later section. See separate technical note Maximum Matrix Size by Platform for more information).
Be aware of the number of elements limit (issue on 64-bit systems only)
In MATLAB 7.4, part of release 2007a, and earlier, there is a limit on the number of elements in an array of 231-2, or approximately 2x109. If you try to create an array with more elements than this, MATLAB throws an error. For example,
>> a=zeros(2^31-2,1,'int8'); % Possible with MATLAB on 64-bit platform
>> clear
>> a=zeros(2^31-1,1,'int8'); % Not possible in MATLAB 7.3 and earlier
??? Error using ==> zeros
Maximum variable size allowed by the program is exceeded.
The largest real double array you can store is therefore approximately 16GB in size (8 bytes per element) or 32GB for complex data.
Note that in MATLAB Version 7.4 and later you can create arrays with more than 231-1 elements but this was not officially supported until MATLAB 7.5.
In MATLAB 7.5, part of release 2007b and later, this limit was increased to 248 -1 and is therefore practically removed.
Other techniques
You can increase the workspace size by approximately 150 MB (5-9 %) on 32-bit Windows XP if you start MATLAB without Java using the command line option (–nojvm). However, this does not increase the size of the largest contiguous block and therefore largest matrix. On MAC OSX, Solaris, and 32-bit Linux, the –nojvm option gives you approximately 400MB more memory. It also increases the size of the largest contiguous block by about the same. This comes with a severe penalty in that you will lose many features that rely on Java, including the entire development environment.
Starting MATLAB with the -nodesktop option does not save any substantial amount of memory.
Shutting down other applications and services (e.g., using msconfig on Windows) can help if total system memory is the limiting factor, but usually process limit (on 32-bit machines) is the main limiting factor.
Consider distributed computing
For very large data set problems that process perhaps terabytes of data, multiple computers are needed to perform the required calculations in a reasonable time. N computers can store and process N times as much data. Only a subset of all applications, however, can be distributed across multiple machines. See the product information on Parallel Computing Toolbox™ and MATLAB® Distributed Computing Server™ to see if this is right for you.
Maximizing size of largest contiguous block of memory (32-bit Windows only)
Numeric arrays stored in MATLAB workspaces require contiguous virtual memory or address space. On Windows, the virtual memory of MATLAB, and therefore the memory used to store data in the workspace, is fragmented into a number of blocks, thus limiting the size of arrays that can be created. During usage, the virtual memory can become further fragmented, which limits the size of arrays further.
The size of the largest block determines the size of the largest numeric array you can create at any one time. You can view the size of the largest block in MATLAB on Windows XP using ‘feature memstats’ (see below). An equivalent function is not available on Linux and Unix, but memory fragmentation problems are less of a problem on these platforms.
>> feature memstats
<snip>
Largest Contiguous Free Blocks:
1. [at 10810000] 1189 MB (4a560000)
2. [at 63014000] 159 MB ( 9fec000)
3. [at 6d7c5000] 66 MB ( 42db000)
…
======= ==========
1642 MB (66a4f000)
After starting MATLAB, the largest contiguous block can be no greater than 1500 MB on Windows XP. If the first block listed is less than 1500 MB (such as in this case), consider using the following three techniques to address this issue. These techniques are applied by the chkmem utility on MATLAB central.
Fix workspace fragmentation caused by Windows XP DLLs (32-bit Windows XP SP2, MATLAB 7.3 part of Release 2006b and before)
System DLLs in Windows XP SP2 get loaded at suboptimal locations in the address space of MATLAB. We can see this by viewing the contents of the virtual memory of MATLAB with ‘feature dumpmem’:
>> feature dumpmem
Module Base In Use Free
============================ ============ ======== ========
…
<anonymous> 003e0000 00010000 00000000
<anonymous> 003f0000 00010000 00000000
<MATLABroot>/bin/win32/MATLAB.exe 04000000 00106000* 0000a000
…
<anonymous> 10010000 00800000* 4a560000***
c:/winnt/system32/uxtheme.dll 5ad70000 00038000 00ab8000*
C:/WINNT/system32/NETAPI32.dll 5b860000 00054000 017dc000**
C:/WINNT/system32/COMCTL32.dll 5d090000 00097000 034a9000**
C:/WINNT/system32/mslbui.dll 605d0000 00009000 02a27000**
C:/WINNT/system32/SynTPFcs.dll 63000000 00014000 09fec000**
<anonymous> 7ffe0000 0001f000 00001000
========== ==========
Totals 13b4b000 6c4b5000
Largest available memory block is 1247150080 bytes (1189.38 MB) located at address 10810000
The above listing is an abridged output of the feature dumpmem command. It lists all the modules (such as DLLs) and free space in the MATLAB address space named in the ‘Module’ column, the address of the module (in hex) in the ‘Base’ column, the memory in use in the module in the ‘In Use’ column, and the memory that is free in the ‘Free’ column. Observe the address (in hex) given for the largest block (here 10810000) shown at the very end of the output, and inspect the list of modules near that address (looking at the ‘Base’ column). Here you can see that the Windows DLL uxtheme.dll is probably limiting its size. This DLL can be rebased with the utility described in solution 1-1HE4G5. Note that this utility does not work in MATLAB version 7.4. Rebasing DLLs, especially system ones, does have side effects which should be considered before applying. See the solution for more information. After using this, check the size of the largest block again:
>> feature memstats
…
Largest Contiguous Free Blocks:
1. [at 10cc0000] 1549 MB (60de0000)
2. [at 7d1d6000] 37 MB ( 251a000)
… ======= ==========
1706 MB (6aa49000)
Fix workspace fragmentation caused by third party DLLs (32-bit Windows only)
Windows architecture results in DLLs from other applications sometimes becoming loaded into the process space of MATLAB and fragmenting the available memory. To diagnose such problems, use feature dumpmem:
>> feature dumpmem
Module Base In Use Free
============================ ============ ======== ========
…
<anonmous> 003e0000 00010000 00000000
<anonymous> 003f0000 00010000 00000000
<MATLABroot>/bin/win32/MATLAB.exe 04000000 00106000* 0000a000
…
<anonymous> 10410000 00800000* 143f0000***
C:/WINNT/System32/.../fpinter5.dll 25000000 0005b000 0afa5000**
C:/WINNT/System32/.../fpres532.dll 30000000 00028000 305a8000***
C:/WINNT/system32/mslbui.dll 605d0000 00009000 114c7000***
<anonymous> 7ffe0000 0001f000 00001000
========== ==========
Totals 13b4b000 6c4b5000
Largest available memory block is 811237376 bytes (773.66 MB) located at address 30028000
The above listing is an abridged output of the feature dumpmem command. It lists all the modules (such as DLLs) and free space in the MATLAB address space. Observe the hex address given for the largest block (here 30028000) and inspect the listing in the output near that address. This listing shows a DLL that does not belong to MATLAB or Windows, fpinter5.dll (a print driver) fragmenting the memory space. Uninstalling such applications, if they are not essential, is one solution to this problem. After doing this and restarting MATLAB check the size of the largest block again with feature memstats to see if you have achieved 1.5GB.
>> feature memstats
…
Largest Contiguous Free Blocks:
1. [at 10cc0000] 1549 MB (60de0000)
2. [at 7d1d6000] 37 MB ( 251a000)
… ======= ==========
1706 MB (6aa49000)
Consider reducing memory used by graphics card
Often, a large amount of virtual address space (up to the amount of RAM used by the video card) is reserved by the graphics driver. After restarting MATLAB, the effect of the graphics card can be assessed by comparing the size of available memory and the largest block before and after typing:
>> opengl info
On Windows operating systems, it is possible to disable your graphics card hardware acceleration, which will also eliminate the use of this buffer. To disable graphics acceleration on Windows, please follow the following steps:
- Right-click on the Windows desktop and select Properties
- Select the Settings tab
- Click Advanced
- Select the Troubleshooting or Performance tab
- Use the Hardware acceleration slider to decrease and turn off hardware acceleration.
Fix workspace fragmentation caused by Web Render DLL (MATLAB 7.3 and 32-bit Windows only)
When you open the Help Browser in the MATLAB Version 7.3, a DLL that is used by MATLAB fragments the memory space. This reduces the largest contiguous block to less than 700 MB. A workaround for this is found in bug report Bug Report 334120.
Manage workspace fragmentation as a result of long term MATLAB usage (32-bit Windows only)
On 32-bit Windows, the workspace of MATLAB can become fragmented over time due to the fact that the Windows memory manager does not return blocks of certain types and sizes to the operating system. Clearing the MATLAB workspace does not fix this problem. The problem can be minimized by allocating the largest variables you need first. This can not address, however, the eventual fragmentation of the workspace that can occur over continual usage of MATLAB (over many days and weeks for example). The only solution to this is to save your work and restart MATLAB.
The pack command, which saves all variables to disk and loads them back, does not help with this situation.
Be aware of the maximum matrix size on each platform
See separate technical note Maximum Matrix Size by Platform for more information.
Estimating how much memory you will need
When you intend to access (or create) many MBs of data, it is useful to estimate how much memory you will need to perform the operation and make sure it is less than your available memory (described earlier). You will need memory to store the data, plus additional memory for storing a few copies to be used in creating results andtemporary variables. For example, the following code performs an Singular Value Decomposition (SVD) of a 6000x6000 double array.
>> A=rand(6e3,6e3); % Requires 6000*6000*8 Bytes=288MB
>> B=svd(A); % Requires 48K for B and 288MB temporary
Although, the result requires only 48k, the SVD operation requires an additional ~288MB temporary, resulting in a peak of ~560MB. See below for techniques to avoid creating large temporaries while calling some functions.
If you are loading a file, note that the size of a file on disk is often not the same as in memory. Binary files generally take the same amount of disk space to be stored as in memory (as long as you read them all), but text files do not. They could be larger or smaller, depending on how the data is formatted in the file (e.g., how many characters are used per number and size of delimiter).
If you are not sure of the limit of the size of data your algorithm can handle, test it with small arrays and gradually increase the size.
Minimizing the memory used by avoiding common coding mistakes
Be careful not to make coding mistakes that result in large memory requirements. For example,
1) Calling zeros with not enough arguments (e.g. creating a million point column vector of zeros):
Wrong:
>> a=zeros(1e6);
??? Error using ==> zeros
Maximum variable size allowed by the program is exceeded.
Right:
>> a=zeros(1e6,1);
2) Confusing rows and columns (e.g. expanding a Nx1 column vector to a Nx2):
Wrong:
N=1e6;
Maximum variable size allowed by the program is exceeded.
Right:
N=1e6;
Minimizing the memory used during data import or creation
The source of many "out of memory" problems often involves analyzing or processing an existing large set of data such as in a file or a database. The user must first access this data set and bring all or part of it into MATLAB. The following techniques deal with minimizing the required memory during this stage. These techniques are also applicable if the problem requires synthesizing a large set of data.
Load only the data that you need for your calculation
Only input to MATLAB (or create) the as much of a large data set as you need for the problem you are trying to solve. This is not usually a problem when inputting data from sources such as a database (using the Database Toolbox) where you can explicitly search for elements matching a query. But this is a common problem with loading large flat text or binary files. Many users are tempted to try and load the entire file first then process it with MATLAB. To load parts of files, use the appropriate MATLAB function:
Text files
Use the textscan function to access parts of a large text file by reading just selected columns and rows. Don’t use the load command if you have a very large text file. When load starts to read a file, it does not know how big it is and has to periodically allocate memory, for the incoming data. As a result, it can allocate too much memory resulting in an "out of memory error". If you use textscan and specify the number of rows or a repeat format number, MATLAB calculates the exact amount of memory required beforehand.
Binary files
You can use low-level binary file I/O functions to access parts of any file with a known format. For binary files of a known format, try using memory mapping with memmapfile.
MAT files
You can load individual variables from a MAT file but currently not parts of a variable (as of release 2007a). There are workarounds to this limitation such as found in this MAT file utility on MATLAB Central.
HDF files
You can load parts of HDF files using the hdfread and hdf5read functions.
Image, audio and video files
You cannot read parts of these files. The only current solution is to use low-level file I/O routines (e.g., fread).
Consider loading and processing data in blocks
Consider block processing, i.e., processing a large data set one section at a time in a loop. Reducing the size of the largest object in a data set reduces the size of any copies or temporaries needed and thus increases the chance of it fitting into available memory. This can only be used for a subset of applications that can be broken into separate chunks and processed independently (or for applications that only rely on the state of a previous block, e.g., filtering).
Clear large data sets before loading or creating new ones
When you are accessing or synthesizing a very large data set repeatedly or interactively, clear the old variable first to make space for the new variable. Otherwise, MATLAB will need temporary storage of equal size before overriding the variable. For example,
>>a=rand(100e6,1) % 800MB array
>>a=rand(100e6,1) % New 800 MB array
??? Error using ==> rand
Out of memory. Type HELP MEMORY for your options.
>>clear a
>>a=rand(100e6,1) % New 800 MB array
Be aware of the MAT-file size limitation (before MATLAB 7.3)
Before MATLAB 7.3, the size of a MAT file was limited to 2GB. See this External Bug Report for a workaround using hdf5write. From MATLAB 7.3 on, the save command has an option to allow files greater than 2GB.
Minimizing the memory used when selecting a variable data type
All data that you wish to process with MATLAB must be stored as a variable or a set of variables. There are a number of data types and data structures to choose from in MATLAB and all have different memory characteristics. The following techniques deal with choosing the data type that minimizes memory while still meeting your information storage requirements.
Use a numeric data type requiring the least memory to suit your needs
The numeric data type you should use in MATLAB depends on your intended actions. The default data type double gives best precision, but requires 8 bytes per element of memory to store. If you intend to perform complicated math such as linear algebra, you must use a floating-point data type such as a double or single. Singles only require 4 bytes. Single precision math was introduced in MATLAB 7.0. There are some limitations on what you can do with singles, but most of MATLAB Math is supported.
If you just need to carry out simple arithmetic and the original data are represented as integers, you can use the integer data types in MATLAB. Integer math was introduced in MATLAB 7.0. The following is a list of numeric data types, memory requirements (in bytes), and the supported operations.
Data type | Number of Bytes | Supported Operations |
double | 8 | All math |
single | 4 | Most math |
int32, uint32 | 4 | Arithmetic and some simple functions |
int16, uint16 | 2 | Arithmetic and some simple functions |
int8, uint8 | 1 | Arithmetic and some simple functions |
int64 | 8 | No arithmetic supported |
logical | 1 | Logical/conditional operations |
For example, switching from doubles to singles can halve your memory requirements; changing from double to uint8 reduces memory requirements by a factor of eight.
If you are synthesizing a very large data set and storing it in a nondouble data type, avoid creating a temporary array of doubles. For example when creating a large array of zeros avoid this:
>> A=zeros(1e6,1);
>> As=single(A);
Instead use:
>> A=zeros(1e6,1,'single');
Also repmat, preallocation, and for loops are other ways to synthesize nondouble data without creating a temporary double data set.
If your data contains many zeros, consider using sparse arrays, which store only nonzero elements. The example below compares the space required for storage of an array of mainly zeros:
>> A=diag(1e3,1e3); % Full matrix with ones on the diagonal
>> As=sparse(A) % Sparse matrix storing only non-zero elements
>> whos
Name Size Bytes Class
A 1001x1001 8016008 double array
As 1001x1001 4020 double array (sparse)
You can see that this array requires only approximately 4k to be stored as sparse, but approximately 8MB as a full matrix. In general, for a sparse double array with nnz nonzero elements and ncol columns, the memory required is
- 16*nnz + 8*ncol + 8 bytes (on a 64 bit machine)
- 12*nnz + 4*ncol + 4 bytes (on a 32 bit machine)
Note that not all mathematical operations are supported on sparse arrays.
Choose an appropriate data structure
MATLAB arrays (implemented internally as mxArrays) require room to store meta information about the data, such as type, dimensions and attributes. This takes about 80 bytes per array. This overhead only becomes an issue when you have a large number (e.g., hundreds or thousands) of small mxArrays (e.g., scalars). The whos command lists the memory used by variables but does not include this overhead.
Simple numeric arrays (comprising one mxArray) have the least overhead, and so should be used where possible. When data is too complex to be stored in a simple array (or matrix), other data structures can be used.
Cell arrays are comprised of separate mxArrays for each element. As a result, cell arrays with many small elements have a large overhead.
In a similar way, structures require a similar amount of overhead per field (see Array Headers). So structures with many fields and small contents have a large overheadand should be avoided. A large array of structures with numeric scalar fields requires much more memory than a structure with fields containing large numeric arrays.
Also note that while numeric arrays must be stored in contiguous memory, structures and cell arrays do not and so can be larger (on 32-bit platforms).
Be aware of the data type specified when using fread
When reading data from a binary file with fread, it is a common error to specify only the type of the data in the file, and not the type of the data MATLAB uses once it is in the workspace. As a result, the default double is used even if you are reading only 8-bit values. For example,
>> fid=fopen('large_file_of_uint8s.bin','r');
>> a=fread(fid,1e3,'uint8'); % Requires 8k
>> whos a
Name Size Bytes Class Attributes
a 1000x1 8000 double
>> a=fread(fid,1e3,'uint8=>uint8'); % Requires just 1k
>> whos a
Name Size Bytes Class Attributes
a 1000x1 1000 uint8
Minimizing the memory used while your code is running
Calculate only the results that you need
If memory is limited, remember to calculate or generate only those results that you really need to calculate.
Preallocate arrays
One very powerful feature of MATLAB is that it does not insist that you declare the types and sizes of variables before you use them. It allows arrays to increase in size merely by indexing into them at a point larger than the currently size. This is convenient for quick prototyping of code but it has serious penalties with regards to performance and memory usage.
To avoid this, preallocate arrays before using them. The M-lint code checker in the MATLAB Editor or M-Lint Code Check Report gives a warning if it finds such a case. M-Lint generates a message such as: "Array 'a' might be grown using indexing. Consider preallocating for speed."
Avoid temporary memory copies
During processing, sometimes additional temporary storage is required by a function, or expression. Many MATLAB M-files, for example, create temporary data. In general, these temporaries make MATLAB safer to use than traditional programming language such as C, but can be a problem when handling large data sets.
MATLAB also creates temporary arrays during indexing. For example, an expression of the form:
>> y=x(1:n);
requires a temporary uint32 array of length n on 32-bit platforms, or a uint64 array of length n on 64-bit platforms. This temporary storage can be large if you have very many indices to select.
See the following sections for techniques on avoiding temporary memory copies (e.g., in-place operations, nested functions, de-vectorization).
Be aware of the function argument passing model of MATLAB
When you pass arguments to a function in MATLAB, the data is passed by value and not passed by reference (as can be done in C). (See Function Arguments in the MATLAB documentation). However, MATLAB only makes a copy of the data if it is modified by the function. This is called the "copy on write" behavior of MATLAB. This means you can safely pass any large arrays as arguments as long as they are not modified in the function. This is true even for assignment (copying of variables). For example,
>> A=rand(100e6,1) % 800MB array
>> B=A % No more memory is required for B at this stage
>> B(1)=3 % B is copied from A (requiring memory) and B(1) is modified
Use in-place operations (MATLAB 7.3 and after)
You can eliminate temporary memory copies when calling M-file functions and some built-in functions if you call them in an in-place fashion. For example,
>> x=myfunction(x)
If myfunction modifies the input variable x and returns it in an appropriate way, the operation will be carried out in-place and no additional temporary copy is required. This provides the large data set handling benefits of pointers or references without the debugging and indirection problems. For MATLAB versions before 7.3, see this workaround.
Use nested functions
An alternative to passing variables to functions as arguments is to share data between functions using nested functions. These let you control the scope of variables and minimize side effects, and is safer to use than global variables.
Be aware of differences in memory usage between command line and M-file execution
Code executed at the MATLAB command window can have different memory usage characteristics than code executed in an M-file. This is because the JIT/Accelerator technology (which is not enabled at the command line) is able to achieve more in-place operations (like x=x+1). As a result, it is possible that an operation fails with an "out of memory" error if called at the command line, but works when called in an M-file.
Consider removing vectorization
Vectorized code is faster in general than unvectorized code and usually easier to read. It does however often require more temporary memory storage. When processing very large data sets, the additional memory copies may be prohibitive.Instead, consider processing large arrays a block at a time or worst case an element at time in a for loop.
This reduces the size of any temporary copies, but also often reduces performance as well. (With the JIT/Accelerator technology in recent versions of MATLAB, this is much less than with older versions of MATLAB.) If it is necessary to use a loop, try to perform operations on MATLAB arrays down columns, as this is how they are stored in memory and can help cache access. For example, if you wanted to find the number of positive elements in a 600 MB int8 array A, you could code this operation in an M-file as:
found = A>0; % But found is a 600MB logical array
total = sum(found);
This doubles your memory requirements and can cause an "Out of Memory" error for such a large data set. Instead, you can do this with the slower and less elegant but more memory efficient code:
found=0;
for k=1:numel(A)
found=found + A(k)>0;
end
If it was expected that not many elements would meet this condition, you could consider using find instead. In general, for very large array processing, find is often more appropriate than logical indexing.
Clear variables when they are no longer required
The clear command can be used to remove variables from the base workspace or function workspaces. There are also other options to the clear command to remove other resource usage (e.g., MEX files).
Minimizing the memory used when plotting data
Be aware of memory needs for plotting
Monitors have limited resolution of perhaps 1000-2000 pixels square. As a result, there is a limit to how much information they can display and hence the size of the data set that can be plotted.
MATLAB needs additional memory to perform plotting (e.g., to store the pixel values to be sent to the graphics card). For example, if x and y are 1 million element double arrays (8MB storage), plotting requirements would be
>> plot(x,y) % Makes a copy of x and y (16MB extra).
>> plot (y) % Makes a copy of y as well as creating the indices from 1:size(y) (16MB extra)
Copies of data are always stored in doubles which can increase the memory requirements by up to eight times in the case of integers. There is currently no workaround to this memory usage. Try down sampling data, or if there are aliasing problems, consider replacing sections of data with their averages or min/max values. Low-pass filtering the data before down sample would solve this problem but the number of computations required usually makes this prohibitive.
Tools to measure used and available memory in your system and by MATLAB
Memory terms used by different tools
There are a number of operating system and MATLAB tools that report on memory availability and usage. Unfortunately, they use different terminology. The following table summarizes the terms used in different tools to designate the different aspects of memory.
System Memory Information
Tool | Total physical memory (RAM) | Total SWAP (file size) | Total system memory(RAM+SWAP) | Used physical memory (RAM) | Used System Total | Used SWAP |
Task Manager (performance panel) | Physical Memory: Total | N/A | Commit Charge: Limit | N/A (Total-Available) | PF Usage or Commit Charge: Total | N/A |
Process Explorer (System Information pane) | Physical Memory: Total | N/A | Commit Charge: Limit | N/A (Total-Available) | Commit Charge: Current | N/A |
Top command | Mem: Total | Swap: Total | Mem: Total + SWAP: Total | Mem: Used | Mem: Used + SWAP: Usedl | SWAP: Used |
feature memstats | Physical Memory: Total | N/A | Page File: Total | Physical Memory: In Use | Page File: In Use | N/A |
Individual Process Memory Information e.g. MATLAB
Term | Used physical memory (RAM) | Private bytes (what a process owns) | Used Virtual (Private bytes plus shared resources e.g. dlls, Max is 2 – 3GB on Windows XP) | Used Swap |
Task Manager (processes pane) | ‘Mem Usage’ | VM size | N/A | N/A |
Process Explorer (main process window) | ‘Working Set’ | ‘Private Bytes’ | ‘Virtual Size’ | N/A |
top command | ‘RES’ | N/A | ‘VIRT’ | ‘SWAP’ |
feature memstats | N/A | N/A | Virtual Memory – In Use (Max is 2 – 3GB on windows XP) | N/A |
feature processmem | Memory Usage | VM Size | N/A | N/A |
Windows Task Manager
On Windows, the Windows Task Manager can display useful memory information.
In the Performance tab, total system memory used (RAM plus page file) and maximum available are shown in the Commit Charge panel, listed as Total and Limit respectively. Total and available RAM is listed in the Physical Memory panel. The PF Usage panel displays the total commit charge graphically as a bar graph and, over time, as Page File Usage History. Note that for the Task Manager, Page File Usage does not mean just Page File or SWAP file; it means total system memory used (RAM plus page file). Note that some numbers are listed in KB which will look slightly different from the other numbers listed in MB.
Under the processes tab, the value listed in the memory column is RAM only and not total memory used by MATLAB. This is easier to ascertain with the Process Explorer utility (next).
Process Explorer (Windows Only)
Process Explorer is a free utility that can show, among other things, the total memory used by an application in a way that is more understandable than the Windows Task Manager. In the columns of information listed against processes, working set is the term to describe the RAM usage of MATLAB. Private bytes is the Memory that a process owns. This number, plus any shared memory such as libraries make up the virtual memory size.
Linux system tools
Linux system tools (like KDE Info Center below), show available and free total, physical, and swap file memory.
Unix top command
The Unix top command provides a display of the top CPU using processes. An example output is given below.
In the summary section at the start, it shows physical memory (used and free) and swap space (used and free). For an individual process listed in the command column, such as MATLAB, you can view total memory used (SIZE) and resident in physical memory (RES).
MATLAB monitoring tool (Windows only)
The MATLAB Monitoring Tool on MATLAB Central provides a continuously updating graph of MATLAB used memory.
The whos command
The whos command can give you an idea of the memory used by MATLAB variables.
>> A=ones(10,10);
>> whos
Name Size Bytes Class Attributes
A 10x10 800 double
Note that whos does not include information about:
- Memory used by MATLAB (e.g. Java and plots)
- Memory used for data structure overhead (i.e., the header for the mxArray)
- Memory used for most objects (e.g., time series, custom)
- Memory for variables not in the calling workspace
- Shared data copies (e.g., memory for B in >>B=A;) will still have bytes used listed against it even when it does not use any memory (see the "Be aware of the Function Argument Passing Model" section earlier)
Undocumented Command Option: Memory in the profiler
This undocumented option to the MATLAB profiler shows memory allocated, freed and peak per line when the Profiler report is viewed.
>> profile –memory on
Undocumented Command: feature memstats (Windows Only)
This undocumented command displays information about memory. All memory values are given in MB. This is shown in decimal, which is then followed by hexadecimal in parenthesis. Each section of the output of the command is described below.
>> feature memstats
This first section lists the used, free and total physical memory (RAM) of the system:
Physical Memory (RAM):
In Use: 711 MB (2c7be000)
Free: 1334 MB (536ad000)
Total: 2046 MB (7fe6b000)
This second section lists the used, free, and total memory of the system (RAM plus swap/page file):
Page File (Swap space):
In Use: 650 MB (28a45000)
Free: 2306 MB (90233000)
Total: 2956 MB (b8c78000)
The next section lists the used, free, and total virtual memory of the MATLAB process:
Virtual Memory (Address Space):
In Use: 336 MB (150e7000)
Free: 2734 MB (aaef9000)
Total: 3071 MB (bffe0000)
The final section lists the largest 10 blocks of contiguous free memory available to the memory of the MATLAB process. Note that there are some other smaller blocks not listed here.
Largest Contiguous Free Blocks:
1. [at 7ffe1000] 1023 MB (3ffc5000)
2. [at 20017000] 941 MB (3ad59000)
3. [at 12300000] 221 MB ( dd00000)
4. [at 63014000] 159 MB ( 9fec000)
5. [at 6d7c5000] 57 MB ( 39db000)
6. [at 605d9000] 42 MB ( 2a27000)
7. [at 7d1d5000] 37 MB ( 251b000)
8. [at 5e75d000] 30 MB ( 1e73000)
9. [at 7476b000] 28 MB ( 1c25000)
10. [at 5b8b4000] 23 MB ( 17dc000)
======= ==========
2565 MB (a059b000)
The value listed at the end is the size of the largest contiguous free block. This value can be assigned to an output argument. However the above display cannot be suppressed:
ans =
1.073500160000000e+009
For instructions on doing this with MATLAB 6.5 (R13), see Solution 1-19IT9.
Undocumented Command: feature dumpmem (Windows Only)
This undocumented feature command shows the location of software modules and free memory blocks in the address space of MATLAB. Its also shows the address of the largest block and is useful in diagnosing fragmentation problems.
>> feature dumpmem
Module Base In Use Free
============================ ============ ======== ========
…
<anonymous> 003e0000 00010000 00000000
<anonymous> 003f0000 00010000 00000000
<matlabroot>/bin/win32/MATLAB.exe 04000000 00106000* 0000a000
…
<anonymous> 10010000 00800000* 4a560000***
c:/winnt/system32/uxtheme.dll 5ad70000 00038000 00ab8000*
C:/WINNT/system32/NETAPI32.dll 5b860000 00054000 017dc000**
C:/WINNT/system32/COMCTL32.dll 5d090000 00097000 034a9000**
C:/WINNT/system32/mslbui.dll 605d0000 00009000 02a27000**
C:/WINNT/system32/SynTPFcs.dll 63000000 00014000 09fec000**
…
<anonymous> 7ffe0000 0001f000 00001000
========== ==========
Totals 13b4b000 6c4b5000
Largest available memory block is 1247150080 bytes (1189.38 MB) located at address 10810000
Undocumented Command: feature processmem (Windows Only)
This undocumented command shows the total and peak physical memory used, and virtual address space used by MATLAB itself. Note that these values are in bytes andnot KB or MB, and, as a result can look often slightly greater than the values shown in the Task Manager.
>> feature processmem
Memory usage : 141053952
Memory usage peak : 141053952
VM Size : 148049920
Note that this command uses a DLL which fragments the memory space the first time it is called (as of MATLAB 7.4, part of release 2007a. This may reduce the largest contiguous block.
Undocumented Command: system_dependent(‘CheckMallocMemoryUsage’) (Windows Only)
This undocumented command shows the total memory allocated by MATLAB, including data and graphics (but not Java).
>> system_dependent(‘CheckMallocMemoryUsage’);
ans =
6820440
Note that it shows results in bytes, not MB. To use this command, you must set the environmental variable ‘MATLAB_MEM_MGR’ to the value ‘debug’.
Other Resources
Handling Large Data Set Efficiently in MATLAB Presentation
Most of the techniques mentioned here are covered in a 1 hour 15min recorded presentation. If you intend to work with large amounts of data regularly, particularly on 32-bit systems, it is recommend that you watch this. The slides used in the webinar and some demonstration files are included in the Handling Large Data Sets Efficiently in MATLAB submission on MATLAB Central.
Move DLLS Utility (32-bit Windows XP SP2 only, MATLAB 7.3 and before)
The movedlls.exe utility is used to rebase some Windows XP SP2 system DLLs that fragment the MATLAB memory space.
Product support Memory Management Guide
The Memory Management Guide in Tech Note 1106 provides a number of techniques to understand and optimize memory usage in MATLAB.
MATLAB documentation on managing memory
See the MATLAB documentation on Using Memory Efficiently and Resolving "Out of Memory" Errors.