Main Content

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.

example

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.

[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

This example shows how to use pagefun to apply the mtimes function to each page of two GPU arrays, B and C.

Create the two GPU arrays, B and C.

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
A = rand(M,K,P1,1,P3,'gpuArray');
B = rand(K,N,1,P2,P3,P4,'gpuArray');

Call pagefun to apply the mtimes function to each page of these two arrays.

C = pagefun(@mtimes,A,B);
s = size(C)    % M-by-N-by-P1-by-P2-by-P3-by-P4
s =
    3     2    10    17     4    12

This code shows another similar use-case of the pagefun function.

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');
C = pagefun(@mtimes,A,B);
s = size(C)    % returns M-by-N-by-P 
s =
    300        1000         200

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

Version History

Introduced in R2013b

See Also

| |