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

gpuArray — Move numeric or logical data to an acceleration provider.

gpuArray(X) uploads data to the active provider and returns an explicitly resident value. RunMat mode also provides class selection, reshape-at-upload, and prototype-based construction.

Syntax

G = gpuArray(X)
G = gpuArray(X, dim, ...)
G = gpuArray(X, dtype)
G = gpuArray(X, "like", prototype)
G = gpuArray(X, dim, ..., option, ...)

Inputs

X
Type
Any
Required
Yes
Description
Input value to upload or recast on GPU.
dim
Type
SizeArg
Required
Variadic
Description
Reshape dimensions (scalar dims or a single size vector tensor).
dtype
Type
StringScalar
Required
Yes
Default
"double"
Description
Class tag such as `single`, `int32`, `uint8`, `logical`, or `double`.
like
Type
StringScalar
Required
Yes
Description
Literal keyword `"like"`.
prototype
Type
LikePrototype
Required
Yes
Description
Prototype value whose class drives output conversion.
option
Type
Any
Required
Variadic
Description
Class tags and/or `"like", prototype` qualifiers.
NameTypeRequiredDefaultDescription
XAnyYes—Input value to upload or recast on GPU.
dimSizeArgVariadic—Reshape dimensions (scalar dims or a single size vector tensor).
dtypeStringScalarYes"double"Class tag such as `single`, `int32`, `uint8`, `logical`, or `double`.
likeStringScalarYes—Literal keyword `"like"`.
prototypeLikePrototypeYes—Prototype value whose class drives output conversion.
optionAnyVariadic—Class tags and/or `"like", prototype` qualifiers.

Returns

G
Type
Any
Description
GPU-resident handle containing uploaded/converted data.
NameTypeDescription
GAnyGPU-resident handle containing uploaded/converted data.

Errors

RunMat:gpuArray:NoProvider
When
No acceleration provider is registered for host/device transfers.
Message
gpuArray: no acceleration provider registered
RunMat:gpuArray:OptionArgument
When
Option tail contains non-text values where class tags/keywords are expected.
Message
gpuArray: invalid option argument
RunMat:gpuArray:LikeMissingPrototype
When
Keyword `like` is supplied without a following prototype value.
Message
gpuArray: expected a prototype value after 'like'
IdentifierWhenMessage
RunMat:gpuArray:NoProviderNo acceleration provider is registered for host/device transfers.gpuArray: no acceleration provider registered
RunMat:gpuArray:OptionArgumentOption tail contains non-text values where class tags/keywords are expected.gpuArray: invalid option argument
RunMat:gpuArray:LikeMissingPrototypeKeyword `like` is supplied without a following prototype value.gpuArray: expected a prototype value after 'like'
RunMat:gpuArray:LikeDuplicateKeyword `like` appears more than once.gpuArray: duplicate 'like' qualifier
RunMat:gpuArray:CodistributedUnsupportedDistributed/codistributed qualifiers are requested.gpuArray: codistributed arrays are not supported yet
RunMat:gpuArray:ConflictingTypeQualifiersMultiple incompatible class qualifiers are supplied.gpuArray: conflicting type qualifiers supplied
RunMat:gpuArray:UnknownOptionText option is not a recognized class/keyword token.gpuArray: unrecognised option
RunMat:gpuArray:InvalidSizeArgumentSize arguments are malformed (not finite integers, negative, or invalid combinations).gpuArray: invalid size argument
RunMat:gpuArray:InvalidLikePrototype`like` prototype is unsupported for type inference.gpuArray: invalid 'like' prototype
RunMat:gpuArray:UnsupportedInputTypeInput value type cannot be uploaded/coerced to supported gpuArray storage.gpuArray: unsupported input type
RunMat:gpuArray:TypedIntegerUnsupportedA native integer value or integer GPU class is requested without matching provider storage.gpuArray: native integer storage is not supported by the active acceleration provider
RunMat:gpuArray:ConversionFailedRequested dtype conversion cannot be performed (for example NaN->logical).gpuArray: conversion failed
RunMat:gpuArray:ReshapeMismatchRequested shape does not preserve the element count.gpuArray: cannot reshape gpuArray into requested size
RunMat:gpuArray:ProviderIOProvider upload/download interaction fails.gpuArray: provider I/O failed
RunMat:gpuArray:InternalErrorInternal tensor/container conversion fails.gpuArray: internal error

Behavior

G = gpuArray(X) uploads a numeric or logical value to the active acceleration provider. The resulting handle records its owner, physical element type, shape, layout, and explicit device-placement origin. Calling gpuArray on an existing gpuArray without conversion returns the same resident value.

RunMat compatibility mode also accepts explicit class selectors, reshape dimensions, and "like", prototype. Class conversion creates a new resident buffer and leaves an existing source handle valid. Reshaping follows column-major order and must preserve the element count.

Real and supported complex values retain their native class during transfer. Character and string uploads are RunMat extensions. A provider must support the requested physical storage; unsupported storage and transfer failures return an error instead of silently widening the value.

GPU execution

gpuArray is an explicit host-to-device boundary. Later provider-capable operations can consume the returned handle without gathering it first. Call gather when host data is required.

RunMat can also place eligible values on an accelerator automatically. Explicit gpuArray placement is retained as user intent: unsupported operations do not silently discard that placement by moving the value to the host.

Examples

Upload a matrix for elementwise GPU work

A = [1 2 3; 4 5 6];
G = gpuArray(A);
out = gather(sin(G))

Expected output:

out is sin(A) with the same 2-by-3 shape

Convert to single precision while uploading

pi_single = gpuArray(pi, "single");
host = gather(pi_single)

Expected output:

host is the single-precision value nearest pi

Create logical storage during upload

mask = gpuArray([0 2 -5 0], "logical");
host = gather(mask)

Expected output:

host = logical([0 1 1 0])

Match a resident prototype's class

template = gpuArray(true(2, 2));
values = gpuArray([10 20; 30 40], "like", template);
host = gather(values)

Expected output:

host = logical([1 1; 1 1])

Reshape in column-major order during upload

flat = 1:6;
G = gpuArray(flat, 2, 3);
host = gather(G)

Expected output:

host = [1 3 5; 2 4 6]

Keep an existing gpuArray resident

G = gpuArray([1 2 3]);
H = gpuArray(G);
host = gather(H)

Expected output:

host = [1 2 3]

Convert a resident value without consuming its source

G = gpuArray(uint16([1 2; 3 4]));
H = gpuArray(G, "single");
original = gather(G);
converted = gather(H)

Expected output:

original remains uint16; converted is single

Using gpuArray with coding agents

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

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

FAQ

What can gpuArray upload?⌄

The MATLAB-compatible form accepts real or complex numeric arrays and logical arrays. RunMat mode additionally supports character and string values where the active provider can represent the resulting storage.

What happens when the input is already a gpuArray?⌄

gpuArray(G) returns the existing resident value unchanged. A requested class conversion creates a new buffer and leaves G valid.

Do class selectors, size arguments, and like work in MATLAB compatibility mode?⌄

No. Those gpuArray constructor forms are RunMat extensions. Use gpuArray(X) with an explicitly converted or reshaped X for portable source.

Does upload preserve fixed-width integers?⌄

Yes. All eight fixed-width integer classes use native typed storage and retain their exact values and shape when the provider supports that physical element type.

Does gpuArray choose a GPU automatically?⌄

It uses the active acceleration provider and its selected device. If no provider is registered, the call returns a gpuArray provider error.

When should I call gather?⌄

Gather when host code or an unsupported operation needs the data. Keeping intermediate values resident avoids unnecessary transfers.

Can a requested reshape change the number of elements?⌄

No. RunMat's reshape-at-upload extension requires the requested dimensions to contain exactly the input element count.

Related Acceleration functions

arrayfun · gather · gpuDevice · gpuInfo · pagefun

Source you can read

Every RunMat function's source is public. Read exactly how gpuArray is executed, line by line, in Rust.

  • View the source for gpuArray 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
  • Upload a matrix for elementwise GPU work
  • Convert to single precision while uploading
  • Create logical storage during upload
  • Match a resident prototype's class
  • Reshape in column-major order during upload
  • Keep an existing gpuArray resident
  • Convert a resident value without consuming its source
  • Using gpuArray with coding agents
  • FAQ
  • Related Acceleration functions
  • Source you can read
  • About RunMat