gpuDevice

Query or select GPU device

Syntax

D = gpuDevice

D = gpuDevice()

D = gpuDevice(IDX)

gpuDevice([])

Description

D = gpuDevice or D = gpuDevice(), if no device is already selected, selects the default GPU device and returns a GPUDevice object representing that device. If a GPU device is already selected, this returns an object representing that device without clearing it.

D = gpuDevice(IDX) selects the GPU device specified by index IDX. A warning or error might occur if the specified GPU device is not supported. This form of the command with a specified index resets the device and clears its memory (even if this device is already currently selected, equivalent to reset); so all workspace variables representing gpuArray or CUDAKernel variables are now invalid, and you should clear them from the workspace or redefine them.

gpuDevice([]), with an empty argument (as opposed to no argument), deselects the GPU device and clears its memory of gpuArray and CUDAKernel variables. This leaves no GPU device selected as the current device.

Examples

Identify and Select a GPU

This example shows how to identify and select a GPU for your computations.

To determine how many GPU devices are available in your computer, use the gpuDeviceCount function.

gpuDeviceCount

    2

When there are multiple devices, the first is the default. You can examine its properties with the gpuDevice function to determine if that is the one you want to use.

d = gpuDevice

d =

  CUDADevice with properties:

                      Name: 'GeForce GTX 1080'
                     Index: 1
         ComputeCapability: '6.1'
            SupportsDouble: 1
             DriverVersion: 9.2000
            ToolkitVersion: 9
        MaxThreadsPerBlock: 1024
          MaxShmemPerBlock: 49152
        MaxThreadBlockSize: [1024 1024 64]
               MaxGridSize: [2.1475e+09 65535 65535]
                 SIMDWidth: 32
               TotalMemory: 8.5899e+09
           AvailableMemory: 7.0053e+09
       MultiprocessorCount: 20
              ClockRateKHz: 1733500
               ComputeMode: 'Default'
      GPUOverlapsTransfers: 1
    KernelExecutionTimeout: 1
          CanMapHostMemory: 1
           DeviceSupported: 1
            DeviceSelected: 1

If this is the device you want to use, you can proceed. To run computations on the GPU, use gpuArray enabled functions. For more information, see Run MATLAB Functions on a GPU.

To use another device, call gpuDevice with the index of the other device.

gpuDevice(2)

Query Compute Capabilities

Create an object representing the default GPU device.

g = gpuDevice;

Query the compute capabilities of all available GPU devices.

for ii = 1:gpuDeviceCount
    g = gpuDevice(ii);
    fprintf(1,'Device %i has ComputeCapability %s \n', ...
            g.Index,g.ComputeCapability)
end

Device 1 has ComputeCapability 3.5
Device 2 has ComputeCapability 2.0

Use Multiple GPUs in a Parallel Pool

This example shows how to identify and select a GPU for the workers in a parallel pool. If you have access to several GPUs, you can perform your calculations on multiple GPUs in parallel using a parallel pool.

Start a parallel pool with as many workers as GPUs. To determine the number of GPUs available, use the gpuDeviceCount function. By default, MATLAB^® assigns a different GPU to each worker for best performance.

parpool(gpuDeviceCount);

To identify which GPU each worker is using, call gpuDevice inside an spmd block. The spmd block runs gpuDevice on every worker.

spmd
    gpuDevice
end

Use parallel language features, such as parfor or parfeval, to distribute your computations to workers in the parallel pool. If you use gpuArray enabled functions in your computations, then these functions run on the GPU of the worker. For more information, see Run MATLAB Functions on a GPU. For an example, see Run MATLAB Functions on Multiple GPUs.

When you are done with your computations, shut down the parallel pool. You can use use the gcp function to obtain the current parallel pool.

delete(gcp);

If you want to use a different choice of GPUs, then you can use gpuDevice to select a particular GPU on each worker. Define an array, for example gpuIndices, that contains the indices of the GPUs to activate on each worker. Then, start a parallel pool with as many workers as GPUs to select, and use an spmd block to run gpuDevice on each worker. The labindex function identifies each worker. Use this function to associate a worker with a GPU index.

gpuIndices = [1 3];
parpool(numel(gpuIndices));
spmd
    gpuDevice(gpuIndices(labindex));
end

As a best practice, and for best performance, assign a different GPU to each worker.

Input Arguments

IDX — Index of the GPU device

integer

Index of the GPU device, specified as an integer in the range 1 to gpuDeviceCount.

Example: gpuDevice(1);

Data Types: int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64