gpuArray — Move numeric or logical data to an acceleration provider.
gpuArray(X) uploads data to the active provider and returns an explicitly resident value. RunMat mode also provides class selection, reshape-at-upload, and prototype-based construction.
Syntax
G = gpuArray(X)
G = gpuArray(X, dim, ...)
G = gpuArray(X, dtype)
G = gpuArray(X, "like", prototype)
G = gpuArray(X, dim, ..., option, ...)Inputs
X- Type
Any- Required
- Yes
- Description
- Input value to upload or recast on GPU.
dim- Type
SizeArg- Required
- Variadic
- Description
- Reshape dimensions (scalar dims or a single size vector tensor).
dtype- Type
StringScalar- Required
- Yes
- Default
"double"- Description
- Class tag such as `single`, `int32`, `uint8`, `logical`, or `double`.
like- Type
StringScalar- Required
- Yes
- Description
- Literal keyword `"like"`.
prototype- Type
LikePrototype- Required
- Yes
- Description
- Prototype value whose class drives output conversion.
option- Type
Any- Required
- Variadic
- Description
- Class tags and/or `"like", prototype` qualifiers.
Returns
G- Type
Any- Description
- GPU-resident handle containing uploaded/converted data.
Errors
RunMat:gpuArray:NoProvider- When
- No acceleration provider is registered for host/device transfers.
- Message
gpuArray: no acceleration provider registered
RunMat:gpuArray:OptionArgument- When
- Option tail contains non-text values where class tags/keywords are expected.
- Message
gpuArray: invalid option argument
RunMat:gpuArray:LikeMissingPrototype- When
- Keyword `like` is supplied without a following prototype value.
- Message
gpuArray: expected a prototype value after 'like'
Behavior
G = gpuArray(X) uploads a numeric or logical value to the active acceleration provider. The resulting handle records its owner, physical element type, shape, layout, and explicit device-placement origin. Calling gpuArray on an existing gpuArray without conversion returns the same resident value.
RunMat compatibility mode also accepts explicit class selectors, reshape dimensions, and "like", prototype. Class conversion creates a new resident buffer and leaves an existing source handle valid. Reshaping follows column-major order and must preserve the element count.
Real and supported complex values retain their native class during transfer. Character and string uploads are RunMat extensions. A provider must support the requested physical storage; unsupported storage and transfer failures return an error instead of silently widening the value.
GPU execution
gpuArray is an explicit host-to-device boundary. Later provider-capable operations can consume the returned handle without gathering it first. Call gather when host data is required.
RunMat can also place eligible values on an accelerator automatically. Explicit gpuArray placement is retained as user intent: unsupported operations do not silently discard that placement by moving the value to the host.
Examples
Upload a matrix for elementwise GPU work
A = [1 2 3; 4 5 6];
G = gpuArray(A);
out = gather(sin(G))Expected output:
out is sin(A) with the same 2-by-3 shapeConvert to single precision while uploading
pi_single = gpuArray(pi, "single");
host = gather(pi_single)Expected output:
host is the single-precision value nearest piCreate logical storage during upload
mask = gpuArray([0 2 -5 0], "logical");
host = gather(mask)Expected output:
host = logical([0 1 1 0])Match a resident prototype's class
template = gpuArray(true(2, 2));
values = gpuArray([10 20; 30 40], "like", template);
host = gather(values)Expected output:
host = logical([1 1; 1 1])Reshape in column-major order during upload
flat = 1:6;
G = gpuArray(flat, 2, 3);
host = gather(G)Expected output:
host = [1 3 5; 2 4 6]Keep an existing gpuArray resident
G = gpuArray([1 2 3]);
H = gpuArray(G);
host = gather(H)Expected output:
host = [1 2 3]Convert a resident value without consuming its source
G = gpuArray(uint16([1 2; 3 4]));
H = gpuArray(G, "single");
original = gather(G);
converted = gather(H)Expected output:
original remains uint16; converted is singleUsing gpuArray with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how gpuArray changes the result.
Run a small gpuArray example, explain the result, then change one input and compare the output.
FAQ
What can gpuArray upload?⌄
The MATLAB-compatible form accepts real or complex numeric arrays and logical arrays. RunMat mode additionally supports character and string values where the active provider can represent the resulting storage.
What happens when the input is already a gpuArray?⌄
gpuArray(G) returns the existing resident value unchanged. A requested class conversion creates a new buffer and leaves G valid.
Do class selectors, size arguments, and like work in MATLAB compatibility mode?⌄
No. Those gpuArray constructor forms are RunMat extensions. Use gpuArray(X) with an explicitly converted or reshaped X for portable source.
Does upload preserve fixed-width integers?⌄
Yes. All eight fixed-width integer classes use native typed storage and retain their exact values and shape when the provider supports that physical element type.
Does gpuArray choose a GPU automatically?⌄
It uses the active acceleration provider and its selected device. If no provider is registered, the call returns a gpuArray provider error.
When should I call gather?⌄
Gather when host code or an unsupported operation needs the data. Keeping intermediate values resident avoids unnecessary transfers.
Can a requested reshape change the number of elements?⌄
No. RunMat's reshape-at-upload extension requires the requested dimensions to contain exactly the input element count.
Related Acceleration functions
Source you can read
Every RunMat function's source is public. Read exactly how gpuArray is executed, line by line, in Rust.
- View the source for gpuArray 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.