Establish Arrays on a GPU
A gpuArray
in MATLAB® represents an array that is stored on the GPU. For a complete list of
functions that support arrays on the GPU, see Run MATLAB Functions on a GPU.
Create GPU Arrays from Existing Data
Send Arrays to the GPU
GPU arrays can be created by transferring existing arrays from the workspace
to the GPU. Use the gpuArray
function to transfer
an array from MATLAB to the GPU:
N = 6; M = magic(N); G = gpuArray(M);
You can accomplish this in a single line of code:
G = gpuArray(magic(N));
G
is now a MATLAB
gpuArray
object that represents the magic square stored on
the GPU. The input provided to gpuArray
must be numeric (for
example: single
, double
,
int8
, etc.) or logical. (See also Work with Complex Numbers on a GPU.)
Retrieve Arrays from the GPU
Use the gather
function to retrieve
arrays from the GPU to the MATLAB workspace. This takes an array that is on the
GPU represented by a gpuArray
object, and transfers it to the
MATLAB workspace as a regular MATLAB array. You can use isequal
to verify that you
get the correct values back:
G = gpuArray(ones(100,'uint32')); D = gather(G); OK = isequal(D,ones(100,'uint32'))
Gathering back to the CPU can be costly, and is generally not necessary unless
you need to use your result with functions that do not support
gpuArray
.
Example: Transfer Array to the GPU
Create a 1000-by-1000 random matrix in MATLAB, and then transfer it to the GPU:
X = rand(1000); G = gpuArray(X);
Example: Transfer Array of a Specified Precision
Create a matrix of double-precision random values in MATLAB, and then transfer the matrix as single-precision from MATLAB to the GPU:
X = rand(1000); G = gpuArray(single(X));
Create GPU Arrays Directly
A number of functions allow you to directly construct arrays on the GPU by
specifying the 'gpuArray'
type as an input argument. These
functions require only array size and data class information, so they can construct
an array without having to transfer any elements from the MATLAB workspace. For more information, see gpuArray
.
Example: Construct an Identity Matrix on the GPU
To create a 1024-by-1024 identity matrix of type int32
on
the GPU, type
II = eye(1024,'int32','gpuArray'); size(II)
1024 1024
With one numerical argument, you create a 2-dimensional matrix.
Example: Construct a Multidimensional Array on the GPU
To create a 3-dimensional array of ones with data class
double
on the GPU, type
G = ones(100,100,50,'gpuArray');
size(G)
100 100 50
underlyingType(G)
double
The default class of the data is double
, so you do not have
to specify it.
Example: Construct a Vector on the GPU
To create a 8192-element column vector of zeros on the GPU, type
Z = zeros(8192,1,'gpuArray');
size(Z)
8192 1
For a column vector, the size of the second dimension is 1.
Examine gpuArray
Characteristics
There are several functions available for examining the characteristics of a
gpuArray
object:
Function | Description |
---|---|
underlyingType | Class of the underlying data in the array |
existsOnGPU | Indication if array exists on the GPU and is accessible |
isreal | Indication if array data is real |
isUnderlyingType | Determine if underlying array data is of specified class,
such as |
isequal | Determine if two or more arrays are equal |
isnumeric | Determine if an array is of a numeric data type |
issparse | Determine if an array is sparse |
length | Length of vector or largest array dimension |
mustBeUnderlyingType | Validate that array has specified underlying type, such as double |
ndims | Number of dimensions in the array |
size | Size of array dimensions |
For example, to examine the size of the gpuArray
object
G
, type:
G = rand(100,'gpuArray');
s = size(G)
100 100
Save and Load gpuArray
Objects
You can save gpuArray
variables as MAT files for later use.
When you save a gpuArray
from the MATLAB workspace, the data is saved as a gpuArray
variable in a MAT file.
When you load a MAT file containing a gpuArray
variable, the data is loaded onto the
GPU as a gpuArray
.
Note
You can load MAT files containing gpuArray
data as in-memory arrays when a GPU
is not available. A gpuArray
loaded without a GPU is limited and you cannot use
it for computations. To use a gpuArray
loaded without a GPU, retrieve the
contents using gather
.
For more information about how to save and load variables in the MATLAB workspace, see Save and Load Workspace Variables.