Query or select a GPU device
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
GPUDevice object, use the
You can also select or deselect your GPU device using the
function. If you have access to multiple GPUs, use the
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.
D = gpuDevice
D = gpuDevice(IDX)
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.
D = gpuDevice returns a
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.
D = gpuDevice( 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
CUDAKernel variables are now invalid
and must be cleared from the workspace or redefined.
gpuDevice(), with an empty argument (as opposed to no
argument), deselects the GPU device and clears its memory of
CUDAKernel variables. This syntax leaves no GPU device selected as
the current device.
Name— Name of the GPU device
Name of the GPU device, specified as a character array. The name assigned to the device is derived from the GPU device model.
Index— Index of the GPU device
Index of the GPU device, specified as an integer in the range
gpuDeviceCount. Use this index to select a particular GPU
ComputeCapability— Computational capability of the 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.
SupportsDouble— Support for double precision
Support for double precision operations, specified as the logical values
DriverVersion— Driver version
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.
ToolkitVersion— CUDA toolkit version
CUDA toolkit version used by the current release of MATLAB, specified as a scalar value.
MaxThreadsPerBlock— Maximum supported number of threads per block
Maximum supported number of threads per block during CUDAKernel execution, specified as a scalar value.
MaxShmemPerBlock— Maximum supported amount of shared memory
Maximum supported amount of shared memory that a thread block can use during CUDAKernel execution, specified as a scalar value.
MaxThreadBlockSize— Maximum size in each dimension for thread block
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
MaxGridSize— Maximum size of grid of thread blocks
Maximum size of grid of thread blocks, specified as a vector.
SIMDWidth— Number of simultaneously executing threads
Number of simultaneously executing threads, specified as a scalar value.
TotalMemory— Total memory
Total memory (in bytes) on the device, specified as a scalar value.
AvailableMemory— Total memory available for data
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.
MultiprocessorCount— Number of streaming multiprocessors
The number of streaming multiprocessors present on the device, specified as a scalar value.
ClockRateKHz— Peak clock rate
Peak clock rate of the GPU in kHz, specified as a scalar value.
ComputeMode— Compute mode
The compute mode of the device, specified as one of the following values.
|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.|
|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.|
|The device cannot be used.|
GPUOverlapsTransfers— Support for overlapped transfers
Support for overlapped transfers, specified as the logical values
KernelExecutionTimeout— Timeout for long-running kernels
Timeout for long-running kernels, specified as the logical values
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.
CanMapHostMemory— Support for mapping host memory
Support for mapping host memory into the CUDA address space, specified as the
DeviceSupported— Supported device
Supported device, specified by the logical values
1. Not all devices are supported; for example, devices with
DeviceSelected— Currently selected device
Currently selected device, specified by the logical values
You can identify, select, reset, or wait for a GPU device using the following functions:
The following functions are also available:
|Returns true if the GPU specified by index |
|Returns a |
For a complete list of functions, use the
methods function on the
You can get help on any of the object functions with the following command:
functionname is the name of the function. For example, to
get help on
To determine how many GPU devices are available in your computer, use the
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
To use another device, call
gpuDevice with the index of the other
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
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.
To identify which GPU each worker is using, call
spmd block. The
spmd block runs
gpuDevice on every worker.
spmd gpuDevice end
Use parallel language features, such as
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
gcp function to obtain the current
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
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.