A gpuArray
in MATLAB^{®} represents
an array that is stored on the GPU. Use the gpuArray
function
to transfer an array from MATLAB to the GPU:
N = 6; M = magic(N); G = gpuArray(M);
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 Considerations for Complex Numbers.)
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'))
Transfer Array to the GPU. Create a 1000by1000 random matrix in MATLAB, and then transfer it to the GPU:
X = rand(1000); G = gpuArray(X);
Transfer Array of a Specified Precision. Create a matrix of doubleprecision random values in MATLAB, and then transfer the matrix as singleprecision from MATLAB to the GPU:
X = rand(1000); G = gpuArray(single(X));
Construct an Array for Storing on the GPU. Construct a 100by100 matrix of uint32
ones
and transfer it to the GPU. You can accomplish this with a single
line of code:
G = gpuArray(ones(100,'uint32'));
A number of methods on the gpuArray class allow you to directly construct arrays on the GPU without having to transfer arrays from the MATLAB workspace. These constructors require only array size and data class information, so they can construct an array without any elements from the workspace. Use any of the following to directly create an array on the GPU:






 gpuArray. 
 gpuArray. 
 gpuArray. 
 gpuArray. 
For a complete list of available static methods in any release, type
methods('gpuArray')
The constructors appear at the bottom of the output from this command.
For help on any one of the constructors, type
help gpuArray/functionname
For example, to see the help on the colon
constructor,
type
help gpuArray/colon
To create a 1024by1024 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 2dimensional matrix.
To create a 3dimensional array of ones with data class double
on
the GPU, type
G = ones(100,100,50,'gpuArray');
size(G)
100 100 50
classUnderlying(G)
double
The default class of the data is double
,
so you do not have to specify it.
To create a 8192element 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.
The following functions control the random number stream on the GPU:
parallel.gpu.rng 
parallel.gpu.RandStream 
These functions perform in the same way as rng
and RandStream
in MATLAB,
but with certain limitations on the GPU. For more information on the
use and limits of these functions, type
help parallel.gpu.rng help parallel.gpu.RandStream
The GPU uses the combined multiplicative recursive generator by default to create uniform random values, and uses inversion for creating normal values. This is not the default stream in a client MATLAB session on the CPU, but is the equivalent of
RandStream('CombRecursive','NormalTransform','Inversion');
However, a MATLAB worker session has the same default stream as its GPU, even if it is a worker in a local cluster on the same machine. That is, a MATLAB client and workers do not have the same default stream.
In most cases, it does not matter that the default random stream on the GPU is not the same as the default stream in MATLAB on the CPU. But if you need to reproduce the same stream on both GPU and CPU, you can set the CPU random stream accordingly, and use the same seed to set both streams:
seed=0; n=4; cpu_stream = RandStream('CombRecursive','Seed',seed,'NormalTransform','Inversion'); RandStream.setGlobalStream(cpu_stream); gpu_stream = parallel.gpu.RandStream('CombRecursive','Seed',seed); parallel.gpu.RandStream.setGlobalStream(gpu_stream); r = rand(n); % On CPU R = rand(n,'gpuArray'); % On GPU OK = isequal(r,R)
1
There are three supported random generators on the GPU. The combined multiplicative recursive generator (MRG32K3A) is the default because it is a popular and reliable industry standard generator for parallel computing. You can choose the GPU random generator with any of the following commands:
parallel.gpu.RandStream('combRecursive') parallel.gpu.RandStream('Philox4x3210') parallel.gpu.RandStream('Threefry4x6420')
For more information about generating random numbers on a GPU, and a comparison between GPU and CPU generation, see Control Random Number Streams. For an example that shows performance comparisons for different random generators, see Generating Random Numbers on a GPU.
There are several functions available for examining the characteristics of a gpuArray object:
Function  Description 

classUnderlying  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 
length  Length of vector or largest array dimension 
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