This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Run MATLAB Functions on a GPU

MATLAB Functions with gpuArray Arguments

Hundreds of functions in MATLAB® and other toolboxes run automatically on GPU if you supply a gpuArray argument.

A = gpuArray([1 0 1; -1 -2 0; 0 1 -1]);
e = eig(A);

Whenever you call any of these functions with at least one gpuArray as a data input argument, the function executes on the GPU. The function generates a gpuArray as the result, unless returning MATLAB data is more appropriate (for example, size). You can mix inputs using both gpuArray and MATLAB arrays in the same function call. To learn more about when a function runs on GPU or CPU, see Special Conditions for gpuArray Inputs. GPU-enabled functions include the discrete Fourier transform (fft), matrix multiplication (mtimes), left matrix division (mldivide), and hundreds of others.

Check GPU Supported Functions

If a MATLAB function has GPU support, you can consult additional GPU usage information on its function page. See GPU Arrays in the Extended Capabilities section at the end of the function page.

You can also browse GPU support for functions, and filter by product. On the Help bar, click Functions and select a product. In the function list, at the bottom of the left pane, select GPU Arrays.

For information about updates to individual GPU-enabled functions, see the release notes.

Check or Select a GPU

If you have a GPU, then MATLAB automatically uses it for GPU computations. You can check your GPU using the gpuDevice function. If you have multiple GPUs, then you can use gpuDevice to select one of them, or use multiple GPUs with a parallel pool. For an example, see Identify and Select a GPU and Use Multiple GPUs in a Parallel Pool. To check if your GPU is supported, see GPU Support by Release.

For deep learning, MATLAB provides automatic parallel support for multiple GPUs. See Deep Learning with MATLAB on Multiple GPUs (Deep Learning Toolbox).

Use MATLAB Functions with a GPU

This example shows how to use GPU-enabled MATLAB functions to operate with gpuArrays. Check your GPU using the gpuDevice function.

Create a row vector. To transfer it to the GPU and create a gpuArray, use the gpuArray function.

range = [-15:15 0 -15:15 0 -15:15];
n = gpuArray(range);
whos n
  Name      Size            Bytes  Class       Attributes

  n         1x95                4  gpuArray              

To operate with gpuArrays, use any GPU-enabled MATLAB function. MATLAB automatically runs calculations on the GPU. For more information, see Run MATLAB Functions on a GPU. For example, use a combination of diag, expm, mod, abs, and fliplr.

E = expm(diag(n,-1)) * expm(diag(n,1));
M = mod(abs(E),2);
F = M + fliplr(M);

Then, plot the results.

imagesc(F);
colormap(flip(gray));

If you need to transfer the data back from the GPU, use gather. 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.

result = gather(F);
whos result
  Name         Size            Bytes  Class     Attributes

  result      96x96            73728  double              

Sharpen an Image Using the GPU

This example shows how to sharpen an image using gpuArrays and GPU-enabled functions.

Read the image and send it to the GPU using the gpuArray function.

image = gpuArray(imread('peppers.png'));

Convert the image to doubles, and apply convolutions to obtain the gradient image. Then, using the gradient image, sharpen the image by a factor of amount.

dimage = im2double(image); 
gradient = convn(dimage,ones(3)./9,'same') - convn(dimage,ones(5)./25,'same');
amount = 5;
sharpened = dimage + amount.*gradient;

Resize, plot and compare the original and sharpened images.

imshow(imresize([dimage, sharpened],0.7));
title('Original image (left) vs sharpened image (right)');

Compute the Mandelbrot Set using GPU-Enabled Functions

This example shows how to use GPU-enabled MATLAB functions to compute a well-known mathematical construction: the Mandelbrot Set. Check your GPU using the gpuDevice function.

Define the parameters. The Mandelbrot algorithm iterates over a grid of real and imaginary parts. The following code defines the number of iterations, grid size and grid limits.

maxIterations = 500;
gridSize = 1000;
xlim = [-0.748766713922161, -0.748766707771757];
ylim = [ 0.123640844894862,  0.123640851045266]; 

You can use the gpuArray function to transfer data to the GPU and create a gpuArray, or you can create an array directly on the GPU. gpuArray provides GPU versions of many functions that you can use to create data arrays, such as linspace. For more information, see Create GPU Arrays Directly.

x = gpuArray.linspace(xlim(1),xlim(2),gridSize);
y = gpuArray.linspace(ylim(1),ylim(2),gridSize);
whos a b

Many MATLAB functions support gpuArrays. When you supply a gpuArray argument to any GPU-enabled function, the function runs automatically on the GPU. For more information, see Run MATLAB Functions on a GPU. Create a complex grid for the algorithm, and create an array for the results, count. To create this array directly on the GPU, use the ones function, and specify 'gpuArray'.

[xGrid,yGrid] = meshgrid(x,y);
z0 = complex(xGrid,yGrid);
count = ones(size(z0),'gpuArray');

The following code implements the Mandelbrot algorithm using GPU-enabled functions. Because the code uses gpuArrays, the calculations happen in the GPU.

z = z0;
for n = 0:maxIterations
    z = z.*z + z0;
    inside = abs(z) <= 2;
    count = count + inside;
end
count = log(count);

When computations are done, plot the results.

imagesc(x,y,count)
colormap([jet();flipud(jet());0 0 0]);
axis off

Work with Sparse Arrays on a GPU

The following functions support sparse gpuArrays.

abs
angle
bicg
bicgstab
ceil
cgs
classUnderlying
conj
ctranspose
deg2rad
end
expm1
find
fix
floor
full
gmres
gpuArray.speye
imag
isaUnderlying
isdiag
isempty
isequal
isequaln
isfloat
isinteger
islogical
isnumeric
isreal
issparse
istril
istriu
length
log1p
lsqr
minus
mtimes
ndims
nextpow2
nnz
nonzeros
norm
numel
nzmax
pcg
plus
rad2deg
real
realsqrt
round
sign
size
sparse
spfun
spones
sprandsym
sqrt
sum
transpose
tril
triu
uminus
uplus  

You can create a sparse gpuArray either by calling sparse with a gpuArray input, or by calling gpuArray with a sparse input. For example,

x = [0 1 0 0 0; 0 0 0 0 1]
     0     1     0     0     0
     0     0     0     0     1
s = sparse(x)
   (1,2)        1
   (2,5)        1
g = gpuArray(s);   % g is a sparse gpuArray
gt = transpose(g); % gt is a sparse gpuArray
f = full(gt)       % f is a full gpuArray
     0     0
     1     0
     0     0
     0     0
     0     1

Work with Complex Numbers on a GPU

If the output of a function running on the GPU could potentially be complex, you must explicitly specify its input arguments as complex. This applies to gpuArray or to functions called in code run by arrayfun.

For example, if creating a gpuArray which might have negative elements, use G = gpuArray(complex(p)), then you can successfully execute sqrt(G).

Or, within a function passed to arrayfun, if x is a vector of real numbers, and some elements have negative values, sqrt(x) will generate an error; instead you should call sqrt(complex(x)).

If the result is a gpuArray of complex data and all the imaginary parts are zero, these parts are retained and the data remains complex. This could have an impact when using sort, isreal, etc.

The following table lists the functions that might return complex data, along with the input range over which the output remains real.

FunctionInput Range for Real Output
acos(x)abs(x) <= 1
acosh(x)x >= 1
acoth(x)abs(x) >= 1
acsc(x)abs(x) >= 1
asec(x)abs(x) >= 1
asech(x)0 <= x <= 1
asin(x)abs(x) <= 1
atanhabs(x) <= 1
log(x)x >= 0
log1p(x)x >= -1
log10(x)x >= 0
log2(x)x >= 0
power(x,y)x >= 0
reallog(x)x >= 0
realsqrt(x)x >= 0
sqrt(x)x >= 0

Special Conditions for gpuArray Inputs

GPU-enabled functions run on the GPU only when the data is on the GPU. For example, the following code runs on GPU because the data, the first input, is on the GPU:

>> sum(gpuArray(magic(10)),2);
However, this code does not run on GPU because the data, the first input, is not on the GPU:
>> sum(magic(10),gpuArray(2));
If your input argument gpuArrays contain items such as dimensions, scaling factors, or number of iterations, then the function gathers them and computes on the CPU. Functions only run on the GPU when the actual data arguments are gpuArrays.

Acknowledgments

MAGMA is a library of linear algebra routines that take advantage of GPU acceleration. Linear algebra functions implemented for gpuArrays in Parallel Computing Toolbox™ leverage MAGMA to achieve high performance and accuracy.

See Also

|

Related Examples

More About