|On this page…|
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 nonsparse, and either 'single', 'double', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64', 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 makes it available in 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'))
X = rand(1000); G = gpuArray(X);
X = rand(1000); G = gpuArray(single(X));
G = gpuArray(ones(100, 'uint32'));
A number of static methods on the gpuArray class allow you to directly construct arrays on the GPU without having to transfer them from the MATLAB workspace. These constructors require only array size and data class information, so they can construct an array without any element data 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
The static constructors appear at the bottom of the output from this command.
For help on any one of the constructors, type
For example, to see the help on the colon constructor, type
To create a 1024-by-1024 identity matrix of type int32 on the GPU, type
II = gpuArray.eye(1024,'int32'); size(II) 1024 1024
With one numerical argument, you create a 2-dimensional matrix.
To create a 3-dimensional array of ones with data class double on the GPU, type
G = gpuArray.ones(100, 100, 50); 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 8192-element column vector of zeros on the GPU, type
Z = gpuArray.zeros(8192, 1); 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:
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
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 = gpuArray.rand(n); % 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.
There are several functions available for examining the characteristics of a gpuArray object:
|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 = gpuArray.rand(100); s = size(G) 100 100