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.

gpuArray

Create array on GPU

Syntax

G = gpuArray(X)

Description

example

G = gpuArray(X) copies the array X to the GPU, and returns a gpuArray object. To work with gpuArrays, use any GPU-enabled MATLAB® function. For more information, see Run MATLAB Functions on a GPU. If you need to retrieve the array back from the GPU, for example when using a function that does not support GPU, use the gather function.

To avoid transferring data from the CPU, you can create arrays directly on the GPU. For more information, see Create GPU Arrays Directly.

If you need increased performance, or if a function is not available for GPU, gpuArrays support the following options:

  1. To precompile and run purely element-wise code on gpuArrays, use the arrayfun function. For more information, see Run Element-wise MATLAB Code on GPU.

  2. To run existing GPU kernels written in CUDA® C++, use the MATLAB CUDAKernel interface. For more information, see Run CUDA or PTX Code on GPU.

  3. To run C++ code containing CUDA device code or library calls, use a MEX-function. For more information, see Run MEX-Functions Containing CUDA Code.

  4. To generate CUDA code from MATLAB code, use GPU Coder™. For more information, see Getting Started with GPU Coder (GPU Coder).

Examples

collapse all

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              

This example shows how to use MATLAB functions and operators with gpuArrays to compute the integral of a function, using the Monte Carlo integration method. Check your GPU using the gpuDevice function.

Define the number of points to sample. Sample points in the domain of the function, the interval [-1,1] in both x and y coordinates, by creating random points with the rand function. To create random arrays directly in the GPU, specify 'gpuArray' as the type of array argument. For more information, see Establish Arrays on a GPU.

n = 1e6;
x = 2*rand(n,1,'gpuArray')-1;
y = 2*rand(n,1,'gpuArray')-1;

Define the function to integrate, and use the Monte Carlo integration formula on it. Because the code uses GPU-enabled functions and operators on gpuArrays, the computations automatically run on the GPU. To learn more about GPU-enabled functions, see Run MATLAB Functions on a GPU.

f = x.^2 + y.^2 <= 1;
result = 4*1/n*f'*ones(n,1,'gpuArray')
result =

    3.1444

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

Input Arguments

collapse all

Array, specified as a numeric or logical array, to transfer to the GPU. The GPU device must have sufficient free memory to store the data. If X is already a gpuArray, gpuArray outputs X unchanged.

Example: G = gpuArray(rand(3));

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical
Complex Number Support: Yes

Output Arguments

collapse all

GPU array, returned as a gpuArray object, that represents an array stored in the GPU. Use gpuArray objects in hundreds of GPU-enabled MATLAB functions. For more information, see Run MATLAB Functions on a GPU. To retrieve the array back from the GPU, use the gather function.

The maximum number of elements of a gpuArray is limited to intmax('int32').

Example: G = gpuArray([1 2; 2 4]);

Data Types: gpuArray

Introduced in R2010b