What does the gpuArray function do in MATLAB / RunMat?

gpuArray(X) moves MATLAB values onto the active GPU and returns a handle that the rest of the runtime can execute on. RunMat mirrors MATLAB semantics, including MATLAB-style size arguments, explicit dtype toggles (such as 'single', 'int32', 'logical'), and the 'like' prototype syntax that matches the class of an existing array.

How does the gpuArray function behave in MATLAB / RunMat?

• Accepts numeric 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 the 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).
• '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.

gpuArray GPU Execution Behaviour

gpuArray itself runs on the CPU. For host inputs it prepares a HostTensorView and forwards it to the provider’s upload hook. 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 residency in RunMat (Do I need gpuArray?)

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 of using the gpuArray function in MATLAB / RunMat

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

FAQ

Can I reshape while uploading?
Yes. Provide either individual dimension arguments or a size vector. The element count must match.

What class strings are supported?
'double', 'single', 'logical', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64', and the compatibility no-op 'gpuArray'. Unknown strings raise an error.

How does 'like' interact with explicit class strings?
'like' sets the default dtype (for example, inferring logical arrays), but any subsequent class string overrides that inference.

Can I promote an existing gpuArray to another class?
Yes. When you pass a gpuArray as the first argument, gpuArray reuploads the buffer if a class change is requested. Without a change it simply updates metadata (for example clearing logical flags).

What happens when the provider is missing?
The builtin raises gpuArray: no acceleration provider registered. Register a provider (for example, the in-process test provider or the WGPU backend) before uploading values.

Does gpuArray support complex inputs, structs, or cell arrays?
Not yet. Gather or decompose the data first, mirroring MATLAB’s requirement to convert to supported numeric or logical types.

See Also

gather, gpuDevice, gpuInfo, arrayfun, zeros, sum

Source & Feedback

• Implementation: crates/runmat-runtime/src/builtins/acceleration/gpu/gpuarray.rs
• Found a bug or behavior mismatch? Please open an issue with a minimal reproduction.