gpuArray
Array stored on GPU
Description
A gpuArray
object represents an array stored in GPU memory. A
large number of functions in MATLAB^{®} and in other toolboxes support gpuArray
objects, allowing you to run your code on GPUs
with minimal changes to the code. To work with gpuArray
objects, use any
gpuArray
enabled MATLAB function such as fft
, mtimes
or
mldivide
. To find a full list of gpuArray
enabled functions in
MATLAB and in other toolboxes, see GPUsupported functions. For more information, see Run MATLAB Functions on a GPU.
If you want to retrieve the array from the GPU, for example when using a function that
does not support gpuArray
objects, use the gather
function.
Note
You can load MAT files containing gpuArray
data as inmemory arrays when a GPU is not
available. A gpuArray
object loaded without a GPU is limited and you cannot use it for
computations. To use a gpuArray
object loaded without a GPU, retrieve the contents using gather
.
Creation
Use gpuArray
to convert an array in the MATLAB workspace into a gpuArray
object. Some MATLAB functions also allow you to create gpuArray
objects directly.
For more information, see Establish Arrays on a GPU.
Syntax
Input Arguments
Object Functions
There are several methods for examining the characteristics of a
gpuArray
object. Most behave like the MATLAB functions of the same name.
isgpuarray  Determine whether input is gpuArray

existsOnGPU  Determine if gpuArray or CUDAKernel is available on GPU 
isUnderlyingType  Determine whether input has specified underlying data type 
ndims  Number of array dimensions 
size  Array size 
underlyingType  Type of underlying data determining array behavior 
Several MATLAB toolboxes include functions with gpuArray
support. To view
lists of all functions in these toolboxes that support gpuArray
objects, use
the links in the following table. Functions in the lists with information indicators have
limitations or usage notes specific to running the function on a GPU. You can check the usage
notes and limitations in the Extended Capabilities section of the function reference page. For
information about updates to individual gpuArray
enabled functions, see the
release notes.
Toolbox Name  List of Functions with gpuArray Support  GPUSpecific Documentation 

MATLAB  Functions with
gpuArray support  
Statistics and Machine Learning Toolbox™  Functions with
gpuArray support (Statistics and Machine Learning Toolbox)  Analyze and Model Data on GPU (Statistics and Machine Learning Toolbox) 
Image Processing Toolbox™  Functions with
gpuArray support (Image Processing Toolbox)  GPU Computing (Image Processing Toolbox) 
Deep Learning Toolbox™  Functions with
*(see also Deep Learning with GPUs)  Scale Up Deep Learning in Parallel, on GPUs, and in the Cloud (Deep Learning Toolbox) Deep Learning with MATLAB on Multiple GPUs (Deep Learning Toolbox) 
Computer Vision Toolbox™  Functions with
gpuArray support (Computer Vision Toolbox)  GPU Code Generation and Acceleration (Computer Vision Toolbox) 
Communications Toolbox™  Functions with
gpuArray support (Communications Toolbox)  Code Generation and Acceleration Support (Communications Toolbox) 
Signal Processing Toolbox™  Functions with
gpuArray support (Signal Processing Toolbox)  Code Generation and GPU Support (Signal Processing Toolbox) 
Audio Toolbox™  Functions with
gpuArray support (Audio Toolbox)  Code Generation and GPU Support (Audio Toolbox) 
Wavelet Toolbox™  Functions with
gpuArray support (Wavelet Toolbox)  Code Generation and GPU Support (Wavelet Toolbox) 
Curve Fitting Toolbox™  Functions with
gpuArray support (Curve Fitting Toolbox) 
For a list of functions with gpuArray
support in all
MathWorks^{®} products, see gpuArray
supported functions. Alternatively, you can
filter by product. On the Help bar, click Functions.
In the function list, browse the left pane to select a product, for example, MATLAB. At the bottom of the left pane, select GPU Arrays. If you
select a product that does not have gpuArray
enabled functions, then the
GPU Arrays filter is not available.
Examples
Limitations
None of the following can exceed
intmax("int32")
:The number of elements of a dense array.
The number of nonzero elements of a sparse array.
The size in any given dimension. For example,
zeros(0,3e9,"gpuArray")
is not allowed.
Distributing a
gpuArray
among workers in a parallel pool using thedistributed
orcodistributed
functions is not supported. If you have multiple GPUs and each worker in your parallel pool has access to a unique GPU, you can instead manually split or initially generate your data as multiplegpuArray
objects on different workers. For examples showing how to usegpuArray
data in a parallel pool, see Run MATLAB Functions on Multiple GPUs.
Tips
If you need better performance, or if a function is not available on the GPU,
gpuArray
supports the following options:To precompile and run purely elementwise code on
gpuArray
objects, use thearrayfun
function.To run C++ code containing CUDA^{®} device code or library calls, use a MEX function. For more information, see Run MEX Functions Containing CUDA Code.
To run existing GPU kernels written in CUDA C++, use the MATLAB
CUDAKernel
interface. For more information, see Run CUDA or PTX Code on GPU.To generate CUDA code from MATLAB code, use GPU Coder™. For more information, see Get Started with GPU Coder (GPU Coder).
To control the random number stream on the GPU, use the
gpurng
function.
Alternatives
You can also create a gpuArray
object using some MATLAB functions by specifying a gpuArray
output. The following
table lists the MATLAB functions that enable you to create gpuArray
objects
directly. For more information, see the Extended Capabilities section of the function
reference page.
Extended Capabilities
Version History
Introduced in R2010b