What does the pagefun function do in MATLAB / RunMat?

pagefun(func, A, B, …) applies the MATLAB operator referenced by func to every page of the supplied arrays. Pages are the two leading dimensions of the inputs; the third and higher dimensions index the individual pages. The inputs must agree in all trailing dimensions, allowing singleton expansion.

How does the pagefun function behave in MATLAB / RunMat?

• 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.

pagefun GPU Execution Behaviour

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.

Examples of using the pagefun function in MATLAB / RunMat

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

GPU residency in RunMat (Do I need gpuArray?)

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.

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.

See Also

gpuArray, arrayfun, gather