Establish Arrays on a GPU

A gpuArray in MATLAB^® represents an array that is stored in GPU memory. For more information about functions that support arrays on the GPU, see Run MATLAB Functions on a GPU.

Create GPU Arrays from Existing Data

Send Arrays to the GPU

You can create GPU arrays by transferring existing arrays from host memory to the GPU. Transfer an array from host memory to the GPU using the gpuArray function.

The gpuArray function supports only numeric input arguments, for example, single, double, int8, or logical input arguments. The gpuArray function supports complex-valued inputs. For more information, see Work with Complex Numbers on a GPU.

N = 6;
M = magic(N);
G = gpuArray(M);

Retrieve Arrays from the GPU

To transfer arrays from the GPU to host memory, use the gather function. This function returns a regular MATLAB array that is stored in host memory. Verify that the gather function returns the correct value by using isequal.

Transferring data to and from the GPU can be costly. Calling gather is generally not necessary unless you need to use your result with functions that do not support gpuArray.

G = gpuArray(ones(100,"uint32"));
D = gather(G);
OK = isequal(D,ones(100,"uint32"))

Transfer Array to the GPU

Create a 1000-by-1000 random matrix and then transfer it to the GPU. For more information about generating random numbers on the GPU, see Random Number Streams on a GPU.

X = rand(1000);
G = gpuArray(X);

For more information on generating random numbers of the GPU, see Random Number Streams on a GPU.

Transfer Array of a Specified Precision

Create a matrix of double-precision random values and transfer the matrix in single-precision format to the GPU.

X = rand(1000);
G = gpuArray(single(X));

Create GPU Arrays Directly

You can directly create arrays on the GPU by specifying the gpuArray type as an input argument for some functions. These functions require only array size and data class information, so they can construct an array without having to transfer any elements from host memory. For more information, see gpuArray.

You can also create arrays on the GPU by mirroring the data type of an existing gpuArray using the like syntax. You can use some functions to construct arrays with the same data type as a prototype array p by providing like=p as an input argument. Functions that support the like syntax include zeros, ones, createArray (since R2024a), eye, true, false, rand, randi, randn, cast, and eps.

Create Identity Matrix on the GPU

Create a 1024-by-1024 identity matrix of type int32 on the GPU.

II = eye(1024,"int32","gpuArray");
size(II)

        1024        1024

Create Multidimensional Array on the GPU

Create a three-dimensional array of ones with the single data type on the GPU.

G = ones(100,100,50,"single","gpuArray");
size(G)

   100   100    50

underlyingType(G)

    'single'

Create Vector on the GPU

Create a 8192-element column vector of zeros with the double data type on the GPU.

Z = zeros(8192,1,"gpuArray");
size(Z)

        8192           1

Create Array on the GPU Based on Prototype Array

Create a 100-by-100 array of pi with the same data type as a prototype array.

G = gpuArray(single(2));
X = createArray(100,like=G,FillValue=pi);
size(X)

   100   100

underlyingType(X)

    'single'

X(1:5)

    3.1416    3.1416    3.1416    3.1416    3.1416

Examine `gpuArray` Characteristics

Use these functions to examine the characteristics of a gpuArray object.

Function	Description
`underlyingType`	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
`isUnderlyingType`	Determine if underlying array data is of specified class, such as `double`
`isequal`	Determine if two or more arrays are equal
`isnumeric`	Determine if an array is of a numeric data type
`issparse`	Determine if an array is sparse
`length`	Length of vector or largest array dimension
`mustBeUnderlyingType`	Validate that array has specified underlying type, such as double
`ndims`	Number of dimensions in the array
`size`	Size of array dimensions

Examine the size of the gpuArray object G.

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

    100   100

Save and Load `gpuArray` Objects

You can save gpuArray variables as MAT files. When you save a gpuArray, MATLAB saves the data as a gpuArray variable in a MAT file. When you load a MAT file containing a gpuArray variable, MATLAB loads the data onto the GPU as a gpuArray.

Note

You can load MAT files containing gpuArray data as in-memory arrays when a GPU is not available. A gpuArray loaded without a GPU is limited and you cannot use it for computations. To use a gpuArray loaded without a GPU, retrieve the contents using gather.

For more information about how to save and load variables in the MATLAB workspace, see Save and Load Workspace Variables.