`pagefun` — Apply matrix operators page-by-page across higher-dimensional arrays.

pagefun(func, A, B, ...) applies supported operators independently across pages indexed by third-and-higher dimensions, following MATLAB-compatible pagewise execution semantics.

Syntax

Y = pagefun(func, A, B)
Y = pagefun(func, A1, An...)

Inputs

Name	Type	Required	Default	Description
`func`	`Any`	Yes	—	Operator/function handle (currently `@mtimes`).
`A`	`Any`	Yes	—	First paged input array.
`B`	`Any`	Yes	—	Second paged input array.
`func`	`Any`	Yes	—	Operator/function handle.
`A1`	`Any`	Yes	—	First paged input array.
`An`	`Any`	Variadic	—	Additional paged input arrays.

Returns

Name	Type	Description
`Y`	`Any`	Result of applying the operator page-by-page.

Errors

Identifier	When	Message
`RunMat:pagefun:InvalidCallable`	Function selector is not a supported pagefun operator handle.	`pagefun: invalid function selector`
`RunMat:pagefun:UnsupportedOperation`	Operator is not implemented by pagefun.	`pagefun: unsupported operation`
`RunMat:pagefun:InvalidArity`	Provided operand count does not satisfy operator arity requirements.	`pagefun: invalid number of input arrays`
`RunMat:pagefun:InvalidInput`	Input values are not supported numeric/pageable arrays for the operation.	`pagefun: invalid input array`
`RunMat:pagefun:PageDimensionMismatch`	Trailing page dimensions cannot be broadcast across inputs.	`pagefun: page dimensions are not compatible`
`RunMat:pagefun:MatrixDimensionMismatch`	Matrix inner dimensions do not align for the selected operation.	`pagefun: inner matrix dimensions must agree`
`RunMat:pagefun:ResultShapeMismatch`	Per-page operator results produce inconsistent matrix shapes.	`pagefun: result matrix shape mismatch`
`RunMat:pagefun:ResultTypeMismatch`	Per-page operator result is not a supported matrix/scalar type.	`pagefun: operator returned unsupported result type`
`RunMat:pagefun:InternalError`	Internal pagefun execution/assembly failure occurred.	`pagefun: internal error`

How `pagefun` works

Accepts function handles, builtin names (character vectors or string scalars), and validates that the requested operator is supported.
The first two dimensions of each input form the matrix operated on by the builtin. Dimensions three and up identify individual pages. Inputs with fewer pages are broadcast so long as the page extent is 1.
Any combination of empty matrices and empty page extents produces empty results with MATLAB-compatible shapes.
When all operands are gpuArray values the builtin gathers data to the host if the registered acceleration provider cannot satisfy the request. Uniform numeric results are uploaded back to the GPU so later operations retain residency.

Does RunMat run `pagefun` on the GPU?

RunMat Accelerate exposes a custom pagefun provider hook. When the active provider implements it (the WGPU backend does for @mtimes), pages stay on the device and execute via a tiled compute shader. If the provider does not support the requested operator the runtime gathers the data to the host, evaluates using the CPU builtin, and re-uploads numeric outputs so subsequent GPU work can stay resident.

GPU memory and residency

No. RunMat's auto-offload planner migrates tensors to the GPU when beneficial. When you explicitly pass gpuArray inputs, pagefun keeps numeric results on the device whenever all operands were device-resident and the provider can accept uploads. Complex outputs remain host-resident until device buffers for complex doubles ship.

Examples

Batched matrix multiplication across pages

A = reshape(1:12, [2 2 3]);
B = reshape(13:24, [2 2 3]);
C = pagefun(@mtimes, A, B)

Expected output:

C(:,:,1) =
    55    63
    82    94

C(:,:,2) =
   211   235
   246   274

C(:,:,3) =
   431   471
   474   518

Broadcasting a single page against multiple pages

A = reshape(1:8, [2 2 2]);
B = eye(2);
C = pagefun(@mtimes, A, B);   % B broadcasts across the page dimension

Working with `gpuArray` inputs

G1 = gpuArray(rand(4, 4, 8));
G2 = gpuArray(rand(4, 4, 8));
H = pagefun(@mtimes, G1, G2);
firstPage = gather(H(:, :, 1));   % Inspect the first product page on the host

Handling empty page dimensions

Z = zeros(2, 2, 0);
R = pagefun(@mtimes, Z, Z);
size(R)

Expected output:

ans =
     2     2     0

Using `pagefun` with coding agents

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

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

FAQ

Which functions does pagefun support today?⌄

RunMat currently supports @mtimes page-wise. Additional MATLAB page-aware functions will be added over time as the GPU provider hooks land.

How are page dimensions inferred?⌄

The first two dimensions represent the matrix operated on by the builtin. Any remaining dimensions are treated as page indices. Inputs with fewer trailing dimensions receive implicit singleton expansion to match other operands.

What happens if the pages are incompatible?⌄

pagefun raises a MATLAB-compatible error describing the mismatched page dimension. Matrix dimension mismatches are forwarded from the underlying builtin (for example, Inner matrix dimensions must agree for @mtimes).

Are results always uploaded back to the GPU?⌄

Numeric results are uploaded when every operand started as a gpuArray and an acceleration provider is registered. Complex results remain on the host today, matching MATLAB's behaviour when complex GPU buffers are not available.

Does pagefun participate in fusion?⌄

No. Because pagefun can invoke arbitrary MATLAB builtins it forms a fusion barrier. Upstream expressions are evaluated before entering pagefun.

arrayfun · gather · gpuArray · gpuDevice · gpuInfo

Open-source implementation

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

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

pagefun — Apply matrix operators page-by-page across higher-dimensional arrays.