RunMat
GitHub

View all functions

CategoryAcceleration: Gpu
GPUYes

gpuArray — Move MATLAB values onto the active GPU with optional size, dtype, and prototype controls.

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.

GPU behavior

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

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 gpuArray 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

See also

gather, gpuDevice, gpuInfo, arrayfun, zeros, sum

Source & Feedback