gpuDevice
Query or select a GPU device
Description
A GPUDevice object represents a graphic processing unit (GPU)
in your computer. You can use the GPU to run MATLAB® code that supports gpuArray variables or execute CUDA kernels using
CUDAKernel objects.
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
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.
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.
D = gpuDevice( selects the GPU device
specified by index indx)indx. 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.
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
Properties
Object Functions
You can identify, select, reset, or wait for a GPU device using the following functions:
gpuDeviceCount | Number of GPU devices present |
reset | Reset GPU device and clear its memory |
wait (GPUDevice) | Wait for GPU calculation to complete |
The following functions are also available:
parallel.gpu.GPUDevice.isAvailable(indx) | Returns logical 1 or true if the GPU
specified by index indx is supported and capable of being
selected. indx can be an integer or a vector of integers; the
default index is the current device. |
parallel.gpu.GPUDevice.getDevice(indx) | 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
Identify and Select a GPU Device
This example shows how to use gpuDevice to identify and select which device you want to use.
To determine how many GPU devices are available in your computer, use the gpuDeviceCount function.
gpuDeviceCount("available")ans = 2
When there are multiple devices, the first is the default. You can examine its properties with the gpuDeviceTable function to determine if that is the one you want to use.
gpuDeviceTable
ans=2×5 table
Index Name ComputeCapability DeviceAvailable DeviceSelected
_____ __________________ _________________ _______________ ______________
1 "NVIDIA RTX A5000" "8.6" true false
2 "Quadro P620" "6.1" true true
If the first device 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)
ans =
CUDADevice with properties:
Name: 'Quadro P620'
Index: 2
ComputeCapability: '6.1'
SupportsDouble: 1
GraphicsDriverVersion: '511.79'
DriverModel: 'WDDM'
ToolkitVersion: 11.2000
MaxThreadsPerBlock: 1024
MaxShmemPerBlock: 49152 (49.15 KB)
MaxThreadBlockSize: [1024 1024 64]
MaxGridSize: [2.1475e+09 65535 65535]
SIMDWidth: 32
TotalMemory: 2147287040 (2.15 GB)
AvailableMemory: 1615209678 (1.62 GB)
CachePolicy: 'balanced'
MultiprocessorCount: 4
ClockRateKHz: 0
ComputeMode: 'Default'
GPUOverlapsTransfers: 1
KernelExecutionTimeout: 1
CanMapHostMemory: 1
DeviceSupported: 1
DeviceAvailable: 1
DeviceSelected: 1
Alternatively, you can determine how many GPU devices are available, inspect some of their properties, and select a device to use from the MATLAB® desktop. On the Home tab, in the Environment area, select Parallel > Select GPU Environment.
Query Compute Capabilities
Create an object representing the default GPU device and query its compute capability.
D = gpuDevice; D.ComputeCapability
ans = '8.6'
Query the compute capabilities of all available GPU devices.
for idx = 1:gpuDeviceCount D = gpuDevice(idx); fprintf(1,"Device %i has ComputeCapability %s \n", ... D.Index,D.ComputeCapability) end
Device 1 has ComputeCapability 8.6 Device 2 has ComputeCapability 6.1
Compare the compute capabilities and availability of the GPU devices in your system using gpuDeviceTable.
gpuDeviceTable
ans=2×5 table
Index Name ComputeCapability DeviceAvailable DeviceSelected
_____ __________________ _________________ _______________ ______________
1 "NVIDIA RTX A5000" "8.6" true false
2 "Quadro P620" "6.1" true true
Query and Change Caching Policy
Change the caching policy of your GPU.
Create an object representing the default GPU device.
D = gpuDevice
D =
CUDADevice with properties:
Name: 'NVIDIA RTX A5000'
Index: 1
ComputeCapability: '8.6'
SupportsDouble: 1
GraphicsDriverVersion: '511.79'
DriverModel: 'TCC'
ToolkitVersion: 11.2000
MaxThreadsPerBlock: 1024
MaxShmemPerBlock: 49152 (49.15 KB)
MaxThreadBlockSize: [1024 1024 64]
MaxGridSize: [2.1475e+09 65535 65535]
SIMDWidth: 32
TotalMemory: 25553076224 (25.55 GB)
AvailableMemory: 25145376768 (25.15 GB)
CachePolicy: 'balanced'
MultiprocessorCount: 64
ClockRateKHz: 0
ComputeMode: 'Default'
GPUOverlapsTransfers: 1
KernelExecutionTimeout: 0
CanMapHostMemory: 1
DeviceSupported: 1
DeviceAvailable: 1
DeviceSelected: 1
Access the CachePolicy property of the GPU device.
D.CachePolicy
ans = 'balanced'
Change the caching policy to allow the GPU to cache the maximum amount of memory for accelerating computation.
D.CachePolicy = "maximum";
D.CachePolicyans = 'maximum'
Reset the caching policy to the default policy by setting the property to [].
D.CachePolicy = [];
Calling reset(D) or selecting another device with gpuDevice also resets the caching policy to its default value.
Use Multiple GPUs in Parallel Pool
If you have access to several GPUs, you can perform your calculations on multiple GPUs in parallel using a parallel pool.
To determine the number of GPUs that are available for use in MATLAB, use the gpuDeviceCount function.
availableGPUs = gpuDeviceCount("available")availableGPUs = 3
Start a parallel pool with as many workers as available GPUs. For best performance, MATLAB assigns a different GPU to each worker by default.
parpool('Processes',availableGPUs);Starting parallel pool (parpool) using the 'Processes' profile ... Connected to the parallel pool (number of workers: 3).
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 you can use gpuDevice to select a particular GPU on each worker, using the GPU device index. You can obtain the index of each GPU device in your system using the gpuDeviceCount function.
Suppose you have three GPUs available in your system, but you want to use only two for a computation. Obtain the indices of the devices.
[availableGPUs,gpuIndx] = gpuDeviceCount("available")availableGPUs = 3
gpuIndx = 1×3
1 2 3
Define the indices of the devices you want to use.
useGPUs = [1 3];
Start your parallel pool. Use an spmd block and gpuDevice to associate each worker with one of the GPUs you want to use, using the device index. The spmdIndex function identifies the index of each worker.
parpool('Processes',numel(useGPUs));Starting parallel pool (parpool) using the 'Processes' profile ... Connected to the parallel pool (number of workers: 2).
spmd gpuDevice(useGPUs(spmdIndex)); end
As a best practice, and for best performance, assign a different GPU to each worker.
When you are done with your computations, shut down the parallel pool.
delete(gcp('nocreate'));Version History
Introduced in R2010b
You can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)