RunMat
  • Pricing
RunMat
GitHub
GitHub
Sign inTry in browser
DesktopRuntimePhysicsCADAdministrationAgent

Get RunMat updates

New releases, guides and examples.

Product+
  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download
Math+
  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting
Physics+
  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA
Industries+
  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance
Learn+
  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students
Compare+
  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons
Company+
  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms

Product

  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download

Math

  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting

Physics

  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA

Industries

  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance

Learn

  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students

Compare

  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons

Company

  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms
GitHubXLinkedIn

© Dystr, Inc. · RunMat v0.7.1, Nov 17, 2026

RunMat® is a registered trademark of Dystr, Inc. MATLAB® is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.

/
See all docs
Builtin Reference
    • arrayfun
    • gather
    • gpuArray
    • gpuDevice
    • gpuInfo
    • pagefun

gpuDevice — Inspect, select, synchronize and reset a session-owned GPUDevice.

device = gpuDevice() returns a parallel.gpu.GPUDevice handle for the current session. It selects an available device without resetting an already selected device. gpuDevice(ind) physically resets this session's device allocations before selecting the indexed owner, including when it was already selected. gpuDevice([]) resets and deselects. This is a typed object with read-only dependent properties, not the former provider metadata struct; use gpuInfo for a summary string.

Syntax

device = gpuDevice()
device = gpuDevice(arg)

Inputs

arg
Type
Any
Required
Yes
Description
Exact positive host device index or empty host array for physical reset and deselection.
NameTypeRequiredDefaultDescription
argAnyYes—Exact positive host device index or empty host array for physical reset and deselection.

Returns

device
Type
Any
Description
Session-owned parallel.gpu.GPUDevice handle, or empty host double result for deselection.
NameTypeDescription
deviceAnySession-owned parallel.gpu.GPUDevice handle, or empty host double result for deselection.

Errors

RunMat:gpuDevice:NoProvider
When
No acceleration provider is registered.
Message
gpuDevice: no acceleration provider registered
RunMat:gpuDevice:TooManyInputs
When
More than one input argument was supplied.
Message
gpuDevice: too many input arguments
RunMat:gpuDevice:UnsupportedArgument
When
Argument does not map to a valid device selector/reset operation.
Message
gpuDevice: unsupported input argument
IdentifierWhenMessage
RunMat:gpuDevice:NoProviderNo acceleration provider is registered.gpuDevice: no acceleration provider registered
RunMat:gpuDevice:TooManyInputsMore than one input argument was supplied.gpuDevice: too many input arguments
RunMat:gpuDevice:UnsupportedArgumentArgument does not map to a valid device selector/reset operation.gpuDevice: unsupported input argument
RunMat:gpuDevice:ResetNotSupportedReset was requested but active provider does not support reset.gpuDevice: reset is not supported by the active provider
RunMat:gpuDevice:InvalidIndexDevice index is not a positive integer scalar.gpuDevice: device index must be a positive integer
RunMat:gpuDevice:DeviceNotAvailableRequested device index does not match the currently active provider index.gpuDevice: requested device index is not available
RunMat:gpuDevice:LifecycleThe handle/session/lease is invalid, a backend fact or control capability is unsupported, or physical reset/wait fails.GPUDevice lifecycle or property access failed

Behavior and compatibility

A selected RuntimeContext and a registered provider with genuine device-control capability are required. Device indices are positive exact host integers, numbered in registered device-ID order among this invocation's authorized, control-capable providers. Provider-assigned physical IDs are not device indices. Numeric indices are not widened through double; logical selectors remain a separately gated RunMat extension.

Name is a UTF-16 character row; Index is a host double scalar. SupportsDouble reports the actual enabled device capability, not the current execution precision. DeviceAvailable reports backend availability, and DeviceSelected reads the requesting session's current selection. Public properties cannot be assigned; a handle from another session or a replaced class authority is rejected.

TotalMemory and AvailableMemory are queried only from actual backend facts. WGPU does not expose those measurements here and property access reports an explicit unsupported diagnostic. max_buffer_size is an allocation limit, not VRAM; total CUDA memory is not free memory. Missing metrics are never fabricated as zero, an allocation limit, or a successful reset.

wait(device) awaits the real queue-completion owner without retiring allocations. reset(device) and numeric selection await physical completion, fence ordinary session dispatch/publication, and retire this session's allocations through their existing owners. Previously inherited same-session allocations in other control-capable providers are included. Every relevant capability and execution lease is preflighted before the fence.

RunMat's WGPU provider may be shared by sessions. Reset invalidates the requesting session's prior allocation epochs and cached/pool resources without destroying peer-session allocations or clearing the provider registry. An old GPU array from the reset session is no longer usable; a peer's array remains valid. This scoped device lifecycle is not a process-wide adapter reset or a claim that every CUDA-specific GPUDevice property is implemented.

Reset is ordered retirement, not a transactional rollback. A later owner failure can follow earlier completed retirements; the session stays fenced with the retained original failure and epoch unchanged. The existing host task supervisor owns reset independently of its awaiting caller. Caller cancellation does not restore selection or discard GPU-completion claims; host shutdown before terminal disposition records a fenced failure. Native GPU waits run on the existing bounded device-progress worker, not the RuntimeContext/UI poll thread. Retirement yields between bounded batches.

Only providers that expose actual control and allocation ownership participate. Unsupported backends are not silently treated as reset-capable. The catalog remains incomplete while backend/property coverage and native/browser physical qualification remain outstanding.

Examples

Inspect the current device

device = gpuDevice();

disp(device.Name)

Read live device availability

device = gpuDevice();

assert(device.DeviceAvailable);

assert(device.DeviceSelected)

Branch on actual double capability

device = gpuDevice();

if device.SupportsDouble; disp('double supported'); else; disp('double unavailable'); end

Reset and select an indexed device

device = gpuDevice(uint32(1));

assert(device.Index == 1);

wait(device)

Keep the summary interface distinct

device = gpuDevice();

status = gpuInfo();

disp(status)

Residency and diagnostics

The selector and GPUDevice handle remain on the host. Querying properties does not gather array payloads. Selection/reset changes allocation validity only after actual synchronized owner retirement; ordinary array transfer still uses gpuArray and gather.

Invalid, nonpositive, fractional, out-of-range, nonscalar or resident selectors are rejected. An unavailable index, missing control/lease, unsupported measured property, foreign handle, and retained reset failure are explicit errors. Use reset(device), not the unsupported text selector gpuDevice('reset').

Examples

Inspect current device

device = gpuDevice();

Read authoritative availability

device = gpuDevice(); disp(device.Name); available = device.DeviceAvailable;

Inspect actual double capability

device = gpuDevice(); supports_double = device.SupportsDouble;

Reset and select an index

device = gpuDevice(uint32(1)); wait(device); reset(device);

Keep summary and object interfaces distinct

device = gpuDevice(); status = gpuInfo(); gpuDevice([]); selected_after = device.DeviceSelected;

Using 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

Must I call gpuDevice before GPU builtins?⌄

No. Existing inherited dispatch can use its admitted provider. Calling gpuDevice establishes explicit session selection; a deselected session does not fall back to the process default until it is explicitly selected again.

Why do memory properties report unsupported?⌄

A backend must supply actual measurements. WGPU buffer-size limits are not device memory, and total bytes are not free bytes.

Does reset destroy another session's arrays?⌄

No. WGPU retires the requesting session's prior epochs through their original allocation owners. It synchronizes shared queue work without globally clearing the device registry or invalidating peer scopes.

What happens when reset fails or its caller is cancelled?⌄

The host supervisor retains the reset task through caller cancellation. A physical/retirement failure leaves the session fenced with the original epoch and failure; completed earlier retirements are not rolled back or relabeled transactional.

How do I get a short summary?⌄

gpuInfo remains a separate metadata-summary string interface and does not manufacture a GPUDevice object.

Related Acceleration functions

arrayfun · gather · gpuArray · gpuInfo · pagefun

Source you can read

Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.

Getting started · Benchmarks · Pricing

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatOpen Sandbox
On this page
  • Syntax
  • Inputs
  • Returns
  • Errors
  • Behavior and compatibility
  • Examples
  • Residency and diagnostics
  • Examples
  • Inspect current device
  • Read authoritative availability
  • Inspect actual double capability
  • Reset and select an index
  • Keep summary and object interfaces distinct
  • Using gpuDevice with coding agents
  • FAQ
  • Related Acceleration functions
  • Source you can read
  • About RunMat