pagefun

Apply function to each page of distributed array or gpuArray

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 array or gpuArray B. The result A contains each page of results such that A(:,:,I,J,...) = FUN(B(:,:,I,J,...)). A is a distributed array or a gpuArray, 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 array or gpuArray.

[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. 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 page dimension
P2 = 17;       % size of second page dimension
P3 = 4;        % size of third page dimension
P4 = 12;       % size of fourth page 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 gpuArray functions

  • @ctranspose

  • @fliplr

  • @flipud

  • @inv

  • @mldivide

  • @mrdivide

  • @mtimes

  • @rot90

  • @transpose

  • @tril

  • @triu

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

  • @lu

  • @qr

  • @norm

Input array, specified as a distributed array or gpuArray.

Input arrays, specified as distributed arrays, gpuArrays, or arrays. At least one of the inputs B1,...,Bn, must be a distributed array or gpuArray. Using both distributed array and gpuArray as inputs is not supported. Each array that is stored in CPU memory is converted to a distributed array or gpuArray 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 array or a gpuArray.

Output Arguments

collapse all

Output array, returned as a distributed array or gpuArray.

See Also

| | |

Introduced in R2013b

Parallel Computing Toolbox Documentation

Support