gpuArray — Move data to the GPU as gpuArray values in MATLAB and RunMat.

gpuArray(X) moves data to the active GPU and returns a gpuArray handle for accelerated execution. Type controls, size forms, and 'like' prototype behavior follow MATLAB semantics.

Syntax

G = gpuArray(X)
G = gpuArray(X, dim, ...)
G = gpuArray(X, dtype)
G = gpuArray(X, "like", prototype)
G = gpuArray(X, dim, ..., option, ...)

Inputs

Returns

Errors

How gpuArray works

• Accepts numeric tensors, complex tensors, logical arrays, booleans, character vectors, and existing gpuArray handles. Other input types raise descriptive errors so callers can gather or convert first.
• Optional leading size arguments (gpuArray(data, m, n, ...) or gpuArray(data, [m n ...])) reshape the uploaded value. The element count must match the requested size.
• Class strings such as 'single', 'double', 'int32', 'uint8', and 'logical' convert real data before upload, matching MATLAB casting semantics (round-to-nearest with saturation for integers, NaN→0 for integer classes, and errors when converting NaN to logical). Complex inputs can be uploaded as double or single precision.
• 'like', prototype infers the dtype (and logical state) from prototype. Explicit class strings override the inference when both are supplied.
• "gpuArray" strings are accepted as no-ops so call-sites that forward arguments from constructors such as zeros(..., 'gpuArray') remain compatible.
• Inputs that are already gpuArray handles pass through by default. When a class change is requested, RunMat gathers the data, performs the conversion, uploads a fresh buffer, and frees the old handle.
• When no acceleration provider is registered, the builtin raises gpuArray: no acceleration provider registered.

Does RunMat run gpuArray on the GPU?

gpuArray itself runs on the CPU. For host inputs it prepares a HostTensorView and forwards it to the provider’s upload hook. Complex tensors are uploaded as interleaved real/imaginary buffers and marked with complex storage metadata so gather reconstructs a host ComplexTensor. For gpuArray inputs that require dtype conversion, the builtin gathers the existing buffer, casts the result on the host, uploads a replacement, and frees the original handle. Providers that do not yet implement upload should report an informative error; the builtin surface mirrors MATLAB’s message by prefixing it with gpuArray:.

GPU memory and residency

RunMat’s auto-offload planner transparently moves and keeps tensors on the GPU when it predicts a benefit. You typically call gpuArray to honour MATLAB scripts that opt-in explicitly, to enforce residency before a long computation, or when you need MATLAB-style dtype conversion alongside the upload. The builtin never forces a host copy once the handle has been created.

Examples

Moving a matrix to the GPU for elementwise work

A = [1 2 3; 4 5 6];
G = gpuArray(A);
out = gather(sin(G))

Expected output:

out =
  2×3

    0.8415    0.9093    0.1411
   -0.7568   -0.9589   -0.2794

Uploading a scalar with dtype conversion

pi_single = gpuArray(pi, 'single');
isa(pi_single, 'gpuArray');
class(gather(pi_single))

Expected output:

ans =
  logical
     1

ans =
  single

Converting host data to a logical gpuArray

mask = gpuArray([0 2 -5 0], 'logical');
gather(mask)

Expected output:

ans =
  1×4 logical array

   0   1   1   0

Matching an existing prototype with 'like'

template = gpuArray(true(2, 2));
values = gpuArray([10 20 30 40], [2 2], 'like', template);
isequal(gather(values), logical([10 20; 30 40]))

Expected output:

ans =
  logical
     1

Reshaping during upload

flat = 1:6;
G = gpuArray(flat, 2, 3);
size(G)

Expected output:

ans =
     2     3

Calling gpuArray on an existing gpuArray handle

G = gpuArray([1 2 3]);
H = gpuArray(G, 'double');
isequal(G, H)

Expected output:

ans =
  logical
     1

Using gpuArray with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how gpuArray changes the result.

Related Acceleration functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. 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 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.

Getting started · Benchmarks · Pricing