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
- MATLAB-compatible calls require a function handle. In
runmatcompatibility mode, builtin names supplied as character vectors or string scalars are accepted as a RunMat extension. - 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.
- MATLAB-compatible calls require at least one distributed or
gpuArrayinput. Inrunmatcompatibility mode, all-host operands are accepted as a RunMat extension and return host results. - When any operand is a
gpuArray, provider fallback gathers inputs through the provider that owns them and restores supported results to that same provider. Automatic residency remains transparent, while an explicitgpuArrayremains resident whenever its class can be represented by the owner. - Integer operands inherit the selected function's contract. For
@mtimes, one operand must be scalar when either operand is an integer class; each page uses exact native integer storage, applies the class-preserving saturation rules ofmtimes, and never passes through a floating copy.
Does RunMat run pagefun on the GPU?
RunMat Accelerate exposes a custom pagefun provider hook. When every operand is a floating gpuArray and the owning provider implements the operation (the WGPU backend does for @mtimes), pages stay on the device and execute via a tiled compute shader. Mixed host/GPU inputs, integer pages, and unsupported provider operations use owner-aware host fallback; exact native storage is retained and supported outputs are restored to the original provider.
GPU memory and residency
No. RunMat's auto-offload planner migrates tensors to the GPU when beneficial. When you explicitly pass any gpuArray input, pagefun returns supported real or complex numeric results on the device whenever the provider can accept the upload.
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 518Broadcasting 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 dimensionWorking 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 hostHandling empty page dimensions
Z = zeros(2, 2, 0);
R = pagefun(@mtimes, Z, Z);
size(R)Expected output:
ans =
2 2 0Using 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?⌄
When any operand is a gpuArray and an acceleration provider is registered, supported uniform real or complex numeric results are uploaded back to the device. An all-host RunMat-extension call returns a host result.
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.
Related Acceleration functions
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.