Documentation

Transfer Arrays Between Workspace and GPU

Send Arrays to the GPU

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.)

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'))

Examples: Transfer Array

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);

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));

Construct an Array for Storing on the GPU.  Construct a 100-by-100 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'));

Create GPU Arrays Directly

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:

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

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

classUnderlying(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.

Control the Random Stream for gpuArray

The following functions control the random number stream on the GPU:

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('Philox4x32-10')
parallel.gpu.RandStream('Threefry4x64-20')

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.

Examine gpuArray Characteristics

There are several functions available for examining the characteristics of a gpuArray object:

For example, to examine the size of the gpuArray object G, type:

G = rand(100,'gpuArray');
s = size(G)

    100   100