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 gpuArray works in 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.

How gpuArray runs 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. 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

Related functions to explore

These functions work well alongside gpuArray. Each page has runnable examples you can try in the browser.

gather, gpuDevice, gpuInfo, arrayfun, zeros, sum, pagefun

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how gpuArray works, line by line, in Rust.

• View gpuArray.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing