gather — Gather gpuArray data back to host memory in MATLAB and RunMat.

gather(X) copies GPU-resident data back to host memory. In RunMat, gpuArray handles become dense MATLAB values, while CPU-resident inputs pass through unchanged.

Syntax

X = gather(X)
[X1, X2, ...] = gather(X1, X2, ...)

Inputs

Returns

Returned values from gather depend on how many outputs the caller requests.

Errors

How gather works

• Accepts any MATLAB value. Non-GPU inputs (numbers, logicals, structs, strings, etc.) pass through untouched, so gather is safe to call unconditionally at API boundaries.
• Downloads gpuArray tensors via the active acceleration provider, producing dense double-precision matrices. Logical gpuArray inputs return logical arrays with MATLAB-compatible 0/1 encoding.
• Recursively descends into cells, structs, and objects, gathering every nested gpuArray handle. This mirrors MATLAB's behaviour when you gather composite data structures.
• Clears residency metadata so the auto-offload planner treats the gathered value as host-resident.
• Supports multiple inputs: in a single-output context it returns a 1×N cell array preserving the original order; in a multi-output assignment the number of inputs and outputs must match, mirroring MATLAB's requirement.
• Raises gather: no acceleration provider registered when you attempt to download gpuArray data without an active provider, and propagates provider-specific download errors verbatim.

Does RunMat run gather on the GPU?

gather itself runs on the CPU. When the input contains gpuArray handles, the builtin calls the provider's download hook to retrieve a HostTensorOwned view, converts the result into MATLAB data, and clears residency via runmat_accelerate_api::clear_residency. If the provider does not implement download, the builtin surfaces the provider error so you know the backend must be extended. When the input is already on the host, no provider work is required.

GPU memory and residency

RunMat's auto-offload planner keeps tensors on the GPU until a builtin marked as a sink (such as gather, plotting functions, or I/O) requests host access. You usually call gather at API boundaries, for example to log results or hand them to CPU-only libraries. If the upstream computation never leaves the GPU, you can omit gather and keep chaining gpu-aware builtins.

Examples

Converting a gpuArray back to host memory

G = gpuArray([1 2 3; 4 5 6]);
H = gather(G)

Expected output:

H =
     1     2     3
     4     5     6

Gathering data that is already on the CPU

x = [10 20 30];
y = gather(x)

Expected output:

y =
    10    20    30

Preserving logical values when gathering

mask = gpuArray(logical([1 0 1 0]));
hostMask = gather(mask)

Expected output:

hostMask =
  1×4 logical array
   1   0   1   0

Gathering gpuArray values stored inside a cell array

C = {gpuArray([1 2]), 42};
hostC = gather(C)

Expected output:

hostC =
  1×2 cell array
    {[1 2]}    {[42]}

Gathering struct fields that live on the GPU

S.data = gpuArray(magic(3));
S.label = "gpu result";
S_host = gather(S)

Expected output:

S_host =
  struct with fields:
     data: [3×3 double]
    label: "gpu result"

Gathering multiple gpuArrays into one cell result

A = gpuArray(eye(3));
B = gpuArray(ones(3));
cellOut = gather(A, B)

Expected output:

cellOut =
  1×2 cell array
    {[3×3 double]}    {[3×3 double]}

Gathering results at the end of a GPU pipeline

A = gpuArray(rand(1024, 1));
B = sin(A) .* 5;
result = gather(B)

Expected output:

result(1:3) =
    4.1377
    2.4884
    0.1003

Using gather with coding agents

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

FAQ

Related Acceleration functions

Open-source implementation

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

• View the source for gather 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