gpuDevice — Query active GPU device metadata in MATLAB and RunMat.
info = gpuDevice() returns a struct describing the active GPU provider/device. Reported fields include identifiers, vendor/backend information, memory hints, and precision capability, following MATLAB-style metadata semantics in RunMat.
Syntax
info = gpuDevice()
info = gpuDevice(arg)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
arg | Any | Yes | — | Device index selector or reset-like argument. |
Returns
| Name | Type | Description |
|---|---|---|
info | Any | Struct describing active GPU provider/device metadata. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:gpuDevice:NoProvider | No acceleration provider is registered. | gpuDevice: no acceleration provider registered |
RunMat:gpuDevice:TooManyInputs | More than one input argument was supplied. | gpuDevice: too many input arguments |
RunMat:gpuDevice:UnsupportedArgument | Argument does not map to a valid device selector/reset operation. | gpuDevice: unsupported input argument |
RunMat:gpuDevice:ResetNotSupported | Reset was requested but active provider does not support reset. | gpuDevice: reset is not supported by the active provider |
RunMat:gpuDevice:InvalidIndex | Device index is not a positive integer scalar. | gpuDevice: device index must be a positive integer |
RunMat:gpuDevice:DeviceNotAvailable | Requested device index does not match the currently active provider index. | gpuDevice: requested device index is not available |
How gpuDevice works
- Requires an acceleration provider that implements RunMat Accelerate's
AccelProvidertrait. - Returns a struct so you can access fields with dot notation:
gpuDevice().name. - Does not mutate GPU state or enqueue kernels—it is safe to call frequently.
- Accepts a scalar device index;
gpuDevice(1)returns the active provider, while any other index raises the MATLAB-style errorgpuDevice: GPU device with index N not available. - Requests to reset the provider using
gpuDevice('reset')orgpuDevice([])currently raisegpuDevice: reset is not supported by the active provider. - Hooks into
gpuInfoso the string-form summary stays in sync with the struct fields.
GPU memory and residency
gpuDevice purely reports metadata and does not change residency. Arrays remain on the GPU or CPU exactly as they were prior to the call. Use gpuArray, gather, and the planner-controlled automatic residency features to move data as needed.
Examples
Inspecting the active GPU provider
info = gpuDevice();
disp(info.name)Expected output:
InProcessDisplaying vendor and backend metadata
info = gpuDevice();
fprintf("Vendor: %s (backend: %s)\n", info.vendor, info.backend)Expected output:
Vendor: RunMat (backend: inprocess)Checking whether double precision is supported
info = gpuDevice();
if info.supports_double
disp("Double precision kernels are available.");
else
disp("Provider only exposes single precision.");
endFormatting a user-facing status message
summary = gpuInfo();
disp("Active GPU summary:");
disp(summary)Expected output:
Active GPU summary:
GPU[device_id=0, index=1, name='InProcess', vendor='RunMat', backend='inprocess', precision='double', supports_double=true]Handling missing providers gracefully
try
info = gpuDevice();
catch ex
warning("GPU unavailable: %s", ex.message);
endUsing gpuDevice with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how gpuDevice changes the result.
Run a small gpuDevice example, explain the result, then change one input and compare the output.
FAQ
Do I need to call gpuDevice before using other GPU builtins?⌄
No. RunMat initialises the active provider during startup. gpuDevice is purely informational and can be called at any time to inspect the current provider.
Why are some fields missing from the struct?⌄
Providers only fill metadata they can reliably supply. For example, the in-process test provider does not report memory_bytes. Real GPU backends typically populate additional fields.
What happens if there is no GPU provider?⌄
RunMat raises gpuDevice: no acceleration provider registered. You can catch this error and fall back to CPU code, as shown in the examples above.
Does gpuDevice support selecting or resetting devices?⌄
RunMat currently exposes a single provider. gpuDevice(1) returns that provider, matching MATLAB's first-device semantics, while any other index raises gpuDevice: GPU device with index N not available. Reset requests (gpuDevice('reset') or gpuDevice([])) are not implemented yet and return gpuDevice: reset is not supported by the active provider.
How can I get a quick string summary instead of a struct?⌄
Use gpuInfo(). It internally calls gpuDevice and formats the struct fields into a concise status string that is convenient for logging or display.
Related Acceleration functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how gpuDevice is executed, line by line, in Rust.
- View the source for gpuDevice in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.