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 ind)ind. 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
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(ind) | Returns logical 1 or true if the GPU
specified by index ind is supported and capable of being
selected. ind can be an integer or a vector of integers; the
default index is the current device. |
parallel.gpu.GPUDevice.getDevice(ind) | 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
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 false
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 verify that MATLAB® can use your GPU, use the canUseGPU function. The function returns 1 (true) if there is a GPU available for computation and 0 (false) otherwise.
canUseGPU
ans = logical
1
To diagnose an issue with your GPU setup, for example if canUseGPU returns 0 (false), use the validateGPU function. Validating your GPU is optional.
validateGPU
# Beginning GPU validation # Performing system validation # CUDA-supported platform .................................................PASSED # CUDA-enabled graphics driver exists .....................................PASSED # Version: 537.70 # CUDA-enabled graphics driver load .......................................PASSED # CUDA environment variables ..............................................PASSED # CUDA device count .......................................................PASSED # Found 2 devices. # GPU libraries load ......................................................PASSED # # Performing device validation for device index 1 # Device exists ...........................................................PASSED # NVIDIA RTX A5000 # Device supported ........................................................PASSED # Device available ........................................................PASSED # Device is in 'Default' compute mode. # Device selectable .......................................................PASSED # Device memory allocation ................................................PASSED # Device kernel launch ....................................................PASSED # # Finished GPU validation with no failures.
To use another device, call gpuDevice with the index of the other device.
gpuDevice(2)
ans =
CUDADevice with properties:
Name: 'Quadro P620'
Index: 2 (of 2)
ComputeCapability: '6.1'
DriverModel: 'WDDM'
TotalMemory: 2147352576 (2.15 GB)
AvailableMemory: 1596066816 (1.60 GB)
DeviceAvailable: true
DeviceSelected: true
Show all properties.
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.
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
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 (of 2)
ComputeCapability: '8.6'
DriverModel: 'TCC'
TotalMemory: 25544294400 (25.54 GB)
AvailableMemory: 25120866304 (25.12 GB)
DeviceAvailable: true
DeviceSelected: true
Show all properties.
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.
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"));Extended Capabilities
Version History
Introduced in R2010bSee Also
gpuArray | gpuDeviceTable | gpuDeviceCount | canUseGPU | validateGPU | arrayfun | reset | wait (GPUDevice) | GPUDeviceManager
