RunMat
  • Pricing
RunMat
GitHub
GitHub
Sign inTry in browser
DesktopRuntimePhysicsCADAdministrationAgent

Get RunMat updates

New releases, guides and examples.

Product+
  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download
Math+
  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting
Physics+
  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA
Industries+
  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance
Learn+
  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students
Compare+
  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons
Company+
  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms

Product

  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download

Math

  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting

Physics

  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA

Industries

  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance

Learn

  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students

Compare

  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons

Company

  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms
GitHubXLinkedIn

© Dystr, Inc. · RunMat v0.7.1, Nov 17, 2026

RunMat® is a registered trademark of Dystr, Inc. MATLAB® is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.

/
See all docs
Builtin Reference
    • arrayfun
    • gather
    • gpuArray
    • gpuDevice
    • gpuInfo
    • pagefun

gather — Copy provider-resident data back to host memory.

gather reconstructs host values from gpuArray storage while preserving class and shape. Host values pass through unchanged, and RunMat mode can gather gpuArray values nested in containers.

Syntax

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

Inputs

X
Type
Any
Required
Yes
Description
Input value to gather from GPU to host.
X1
Type
Any
Required
Yes
Description
First input value.
Xn
Type
Any
Required
Variadic
Description
Additional input values.
NameTypeRequiredDefaultDescription
XAnyYes—Input value to gather from GPU to host.
X1AnyYes—First input value.
XnAnyVariadic—Additional input values.

Returns

X
Type
Any
Description
Host-resident value gathered from input.
X
Type
Any
Description
Host-resident outputs matching each input.
NameTypeDescription
XAnyHost-resident value gathered from input.
XAnyHost-resident outputs matching each input.

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

Errors

RunMat:gather:NotEnoughInputs
When
No input arguments were provided.
Message
gather: not enough input arguments
RunMat:gather:TooManyOutputs
When
Requested outputs exceed one for single-input gather.
Message
gather: too many output arguments
RunMat:gather:OutputCountMismatch
When
Requested output count does not match number of inputs.
Message
gather: number of outputs must match number of inputs
RunMat:gather:InternalError
When
Internal output construction failed.
Message
gather: internal error
IdentifierWhenMessage
RunMat:gather:NotEnoughInputsNo input arguments were provided.gather: not enough input arguments
RunMat:gather:TooManyOutputsRequested outputs exceed one for single-input gather.gather: too many output arguments
RunMat:gather:OutputCountMismatchRequested output count does not match number of inputs.gather: number of outputs must match number of inputs
RunMat:gather:InternalErrorInternal output construction failed.gather: internal error

Behavior

X = gather(A) copies a provider-resident value to host memory. The result retains the source class, shape, and supported real or complex layout. Host-resident input passes through unchanged.

[X1, X2, ...] = gather(A1, A2, ...) gathers each input in call order. The number of requested outputs must match the number of inputs. RunMat mode also descends through cells, structs, and supported object values and replaces nested gpuArray handles with host values.

Gathering does not consume the source handle. It remains valid and resident until the program releases it. Provider download errors remain visible to the caller rather than changing the value's class or precision.

GPU execution

gather is an explicit device-to-host boundary and a fusion sink. Each gpuArray is resolved through its owning provider, so a later provider registration cannot redirect an existing handle to a different backend.

Transfers carry the physical element type and layout. Single and fixed-width integer values are reconstructed from native storage instead of passing through double precision.

Examples

Copy a gpuArray matrix to host memory

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

Expected output:

H = [1 2 3; 4 5 6]

Pass through data already in host memory

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

Expected output:

y = uint16([10 20 30])

Preserve logical class and shape

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

Expected output:

hostMask = logical([1 0 1 0])

Gather gpuArray values inside a cell array

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

Expected output:

hostC contains host values [1 2] and uint8(42)

Gather gpuArray values in struct fields

S = struct("data", gpuArray([8 1 6; 3 5 7; 4 9 2]), "label", "gpu result");
S_host = gather(S)

Expected output:

S_host.data is a host matrix and S_host.label is unchanged

Gather multiple inputs into matching outputs

A = gpuArray(eye(3));
B = gpuArray(ones(2, 2));
[hostA, hostB] = gather(A, B)

Expected output:

hostA is eye(3); hostB is ones(2, 2)

Gather at the end of a GPU pipeline

A = gpuArray([0 pi/6 pi/2]);
B = sin(A) .* 5;
result = gather(B)

Expected output:

result = [0 2.5 5]

Using gather with coding agents

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

Run a small gather example, explain the result, then change one input and compare the output.

FAQ

Does gather modify the original gpuArray?⌄

No. It returns a host value and leaves the source handle valid and resident.

What happens to input that is already on the host?⌄

It passes through unchanged, including its class and shape.

Are logical and integer classes preserved?⌄

Yes. Native download metadata reconstructs logical, single, double, and all eight fixed-width integer classes without widening through double.

Does gather recurse into containers?⌄

In RunMat compatibility mode, it gathers nested gpuArray values in cells, structs, and supported objects. This recursive container behavior is a RunMat extension.

How do multiple inputs work?⌄

Request one output for each input: [X1, X2] = gather(A1, A2). The input and output counts must match.

What happens if no provider owns a gpuArray handle?⌄

The call returns a provider error. Host-only inputs do not require an acceleration provider.

Does gather free device memory?⌄

No. Clear or release the source gpuArray when it is no longer needed.

Related Acceleration functions

arrayfun · gpuArray · gpuDevice · gpuInfo · pagefun

Source you can read

Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatOpen Sandbox
On this page
  • Syntax
  • Inputs
  • Returns
  • Errors
  • Behavior
  • GPU execution
  • Examples
  • Copy a gpuArray matrix to host memory
  • Pass through data already in host memory
  • Preserve logical class and shape
  • Gather gpuArray values inside a cell array
  • Gather gpuArray values in struct fields
  • Gather multiple inputs into matching outputs
  • Gather at the end of a GPU pipeline
  • Using gather with coding agents
  • FAQ
  • Related Acceleration functions
  • Source you can read
  • About RunMat