pagefun

Apply function to each page of distributed or GPU array

collapse all in page

Syntax

A = pagefun(FUN,B)
A = pagefun(FUN,B1,...,Bn)
[A1,...,Am] = pagefun(FUN,___)

Description

A = pagefun(FUN,B) applies the function specified by FUN to each page of the distributed or GPU array B. The result A contains each page of results such that A(:,:,I,J,...) = FUN(B(:,:,I,J,...)). A is a distributed or GPU array, depending on the array type of B. FUN is a handle to a function that takes a two-dimensional input argument.

A = pagefun(FUN,B1,...,Bn) evaluates FUN using pages of the arrays B1,...,Bn as input arguments with scalar expansion enabled. Any of the input page dimensions that are scalar are virtually replicated to match the size of the other arrays in that dimension so that A(:,:,I,J,...) = FUN(B1(:,:,I,J,...),...,Bn(:,:,I,J,...)). The input pages B(:,:,I,J,...),...,Bn(:,:,I,J,...), must satisfy all of the input requirements of FUN.

If you plan to make several calls to pagefun, it is more efficient to first convert that array to a distributed or GPU array.

example

[A1,...,Am] = pagefun(FUN,___) returns multiple output arrays A1,...,Am when the function FUN returns m output values. pagefun calls FUN each time with as many outputs as there are in the call to pagefun, that is, m times. If you call pagefun with more output arguments than supported by FUN, MATLAB® generates an error. FUN can return output arguments having different data types, but the data type of each output must be the same each time FUN is called.

Examples

collapse all

Open Live Script

Create two GPU arrays, A and B. A is a two-dimensional array (a matrix) and B is a three-dimensional array, where the first two dimensions are just like a matrix, but the third dimension represents pages of elements.

M = 300;       % output number of rows
K = 500;       % matrix multiply inner dimension
N = 1000;      % output number of columns
P = 200;       % number of pages
A = rand(M,K,"gpuArray");
B = rand(K,N,P,"gpuArray");

Apply a matrix multiplication (mtimes) to each page of arrays A and B using pagefun.

C = pagefun(@mtimes,A,B);
s = size(C)    % returns M-by-N-by-P 
s = 1×3

         300        1000         200

Create two higher-dimensional arrays, D and E. D is an array with five dimensions and E is an array with six dimensions.

M = 3;         % output number of rows
K = 6;         % matrix multiply inner dimension
N = 2;         % output number of columns
P1 = 10;       % size of first array dimension (row size)
P2 = 17;       % size of second array dimension (column size)
P3 = 4;        % size of third array dimension (page size)
P4 = 12;       % size of fourth array dimension
D = rand(M,K,P1,1,P3,"gpuArray");
E = rand(K,N,1,P2,P3,P4,"gpuArray");

Apply a matrix multiplication (mtimes) to each page of arrays D and E using pagefun. The dimensions with size 1 are implicitly expanded to match the size of the other array in that dimension.

F = pagefun(@mtimes,D,E);
s = size(F)    % M-by-N-by-P1-by-P2-by-P3-by-P4
s = 1×6

     3     2    10    17     4    12

Input Arguments

collapse all

Function applied to each page of the inputs, specified as a function handle. For each output argument, FUN must return values of the same class each time it is called.

The supported values for FUN include:

  • Most element-wise distributed array and GPU array functions

  • @conv

  • @conv2

  • @ctranspose

  • @fliplr

  • @flipud

  • @inv

  • @mldivide

  • @mrdivide

  • @mtimes

  • @norm

  • @qr — For GPU arrays, the syntax [__] = pagefun(@qr,__) only supports one input array and does not support returning the permutation matrix

  • @rot90

  • @svd — For GPU arrays, the row and column sizes of each page must not be larger than 32-by-32

  • @transpose

  • @tril

  • @triu

If the inputs are distributed arrays, the supported values for FUN also include:

  • @lu

Input array, specified as a distributed or GPU array.

Input arrays, specified as distributed arrays, GPU arrays, or arrays. At least one of the inputs B1,...,Bn, must be a distributed or GPU array. Using both distributed and GPU array as inputs is not supported. Each array that is stored in CPU memory is converted to a distributed or GPU array before the function is evaluated. If you plan to make several calls to pagefun with the same array, it is more efficient to first convert that array to a distributed or GPU array.

Output Arguments

collapse all

Output array, returned as a distributed or GPU array.

Extended Capabilities

expand all

Version History

Introduced in R2013b

See Also

| |