gpuDevice

Query or select a GPU device

expand all in page

Description

A GPUDevice object represents a graphic processing unit (GPU) in your computer. You can use the GPU to execute CUDA kernels or MATLAB code.

You can use a GPUDevice object to inspect the properties of your GPU device, reset the GPU device, or wait for your GPU to finish executing a computation. To obtain a GPUDevice object, use the gpuDevice function. You can also select or deselect your GPU device using the gpuDevice function. If you have access to multiple GPUs, use the gpuDevice function to choose a specific GPU device on which to execute your code.

You do not need to use a GPUDevice object to run functions on a GPU. For more information on how to use GPU-enabled functions, see Run MATLAB Functions on a GPU.

Creation

Syntax

gpuDevice
D = gpuDevice
D = gpuDevice(IDX)
gpuDevice([])

Description

gpuDevice displays the properties of the currently selected GPU device. If there is no currently selected device, gpuDevice selects the default device without clearing it. Use this syntax when you want to inspect the properties of your GPU device.

example

D = gpuDevice returns a GPUDevice object representing the currently selected device. If there is no currently selected device, gpuDevice selects the default device and returns a GPUDevice object representing that device without clearing it.

example

D = gpuDevice(IDX) selects the GPU device specified by index IDX. If the specified GPU device is not supported, an error occurs. This syntax resets the specified device and clears its memory, even if the device is already currently selected (equivalent to the reset function). All workspace variables representing gpuArray or CUDAKernel variables are now invalid and must be cleared from the workspace or redefined.

example

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

Input Arguments

expand all

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

Example: gpuDevice(1);

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

Properties

expand all

Name of the GPU device, specified as a character array. The name assigned to the device is derived from the GPU device model.

Index of the GPU device, specified as an integer in the range 1 to gpuDeviceCount. Use this index to select a particular GPU device.

Computational capability of the GPU device, specified as a character array. To use the selected GPU device in MATLAB®, ComputeCapability must meet the required specification in GPU Support by Release.

Support for double precision operations, specified as the logical values 0 for false or 1 for true.

GPU device driver version currently in use, specified as a scalar value. To use the selected GPU device in MATLAB, DriverVersion must meet the required specification in GPU Support by Release.

CUDA toolkit version used by the current release of MATLAB, specified as a scalar value.

Maximum supported number of threads per block during CUDAKernel execution, specified as a scalar value.

Example: 1024

Maximum supported amount of shared memory that a thread block can use during CUDAKernel execution, specified as a scalar value.

Example: 49152

Maximum size in each dimension for thread block, specified as a vector. Each dimension of a thread block must not exceed these dimensions. Also, the product of the thread block size must not exceed MaxThreadsPerBlock.

Maximum size of grid of thread blocks, specified as a vector.

Number of simultaneously executing threads, specified as a scalar value.

Total memory (in bytes) on the device, specified as a scalar value.

Total memory (in bytes) available for data, specified as a scalar value. This property is available only for the currently selected device. This value can differ from the value reported by the NVIDIA® System Management Interface due to memory caching.

The number of streaming multiprocessors present on the device, specified as a scalar value.

Peak clock rate of the GPU in kHz, specified as a scalar value.

The compute mode of the device, specified as one of the following values.

'Default'The device is not restricted, and multiple applications can use it simultaneously. MATLAB can share the device with other applications, including other MATLAB sessions or workers.
'Exclusive thread' or 'Exclusive process'Only one application at a time can use the device. While the device is selected in MATLAB, other applications cannot use it, including other MATLAB sessions or workers.
'Prohibited'The device cannot be used.

Support for overlapped transfers, specified as the logical values 0 or 1.

Timeout for long-running kernels, specified as the logical values 0 or 1. If 1, the operating system places an upper bound on the time allowed for the CUDA kernel to execute. After this time, the CUDA driver times out the kernel and returns an error.

Support for mapping host memory into the CUDA address space, specified as the logical values 0 or 1.

Supported device, specified by the logical values 0 or 1. Not all devices are supported; for example, devices with insufficient ComputeCapability.

Currently selected device, specified by the logical values 0 or 1.

Object Functions

You can identify, select, reset, or wait for a GPU device using the following functions:

gpuDeviceCountNumber of GPU devices present
resetReset GPU device and clear its memory
wait (GPUDevice)Wait for GPU calculation to complete

The following functions are also available:

parallel.gpu.GPUDevice.isAvailable(idx)Returns true if the GPU specified by index idx is supported and capable of being selected. idx can be an integer or a vector of integers; the default index is the current device.
parallel.gpu.GPUDevice.getDevice(idx)Returns a GPUDevice object without selecting it.

For a complete list of functions, use the methods function on the GPUDevice object:

methods('parallel.gpu.GPUDevice')

You can get help on any of the object functions with the following command:

help parallel.gpu.GPUDevice.functionname

where functionname is the name of the function. For example, to get help on isAvailable, type:

help parallel.gpu.GPUDevice.isAvailable

Examples

collapse all

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: 10
            ToolkitVersion: 10
        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 d 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)

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
Open Live Script

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('local',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, 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 the gcp function to obtain the current parallel pool.

delete(gcp('nocreate'));

If you want to use a different choice of GPUs, then 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.

See Also

| | | | |

Topics

External Websites

Introduced in R2010b

Parallel Computing Toolbox Documentation

Support