Documentation

arrayfun

Apply function to each element of array on GPU

Syntax

A = arrayfun(FUN, B)
A = arrayfun(FUN,B,C,...)
[A,B,...] = arrayfun(FUN,C,...)

Description

This method of a gpuArray object is very similar in behavior to the MATLAB®functionarrayfun, except that the actual evaluation of the function happens on the GPU, not on the CPU. Thus, any required data not already on the GPU is moved to GPU memory, the MATLAB function passed in for evaluation is compiled for the GPU, and then executed on the GPU. All the output arguments return as gpuArray objects, whose data you can retrieve with thegathermethod.

A = arrayfun(FUN, B)applies the function specified byFUNto each element of the gpuArrayB, and returns the results in gpuArrayA.Ais the same size asB, andA(i,j,...)is equal toFUN(B(i,j,...)).FUNis a function handle to a function that takes one input argument and returns a scalar value.FUNmust return values of the same class each time it is called. The input data must be an array of one of the following types: numeric, logical, or gpuArray. The order in whicharrayfuncomputes elements ofAis not specified and should not be relied on.

FUNmust be a handle to a function that is written in the MATLAB language (i.e., not a MEX-function).

For more detailed information, seeRun Element-wise MATLAB Code on GPU. For the subset of the MATLAB language that is currently supported byarrayfunon the GPU, seeSupported MATLAB Code.

A = arrayfun(FUN,B,C,...)评估FUNusing elements of arraysB,C, ... as input arguments with singleton expansion enabled. The resulting gpuArray elementA(i,j,...)is equal toFUN(B(i,j,...),C(i,j,...),...). The inputsB,C, ... must all have the same size or be scalar. Any scalar inputs are scalar expanded before being input to the functionFUN.

One or more of the inputsB,C, ... must be a gpuArray; any of the others can reside in CPU memory. Each array that is held in CPU memory is converted to a gpuArray before calling the function on the GPU. If you plan to use an array in several differentarrayfuncalls, it is more efficient to convert that array to a gpuArray before making the series of calls toarrayfun.

[A,B,...] = arrayfun(FUN,C,...), whereFUNis a function handle to a function that returns multiple outputs, returns gpuArraysA,B, ..., each corresponding to one of the output arguments ofFUN.arrayfuncallsFUNeach time with as many outputs as there are in the call toarrayfun.FUNcan return output arguments having different classes, but the class of each output must be the same each timeFUNis called. This means that all elements ofAmust be the same class;Bcan be a different class fromA, but all elements ofBmust be of the same class, etc.

Although the MATLABarrayfunfunction allows you to specify optional parameter name/value pairs, the gpuArrayarrayfunmethod does not support these options.

Tips

  • The first time you callarrayfunto run a particular function on the GPU, there is some overhead time to set up the function for GPU execution. Subsequent calls ofarrayfunwith the same function can run significantly faster.

  • Nonsingleton dimensions of input arrays must match each other. In other words, the corresponding dimensions of argumentsB,C, etc., must be equal to each other, or equal to one. Whenever a dimension of an input array is singleton (equal to 1),arrayfunuses singleton expansion to virtually replicate the array along that dimension to match the largest of the other arrays in that dimension. In the case where a dimension of an input array is singleton and the corresponding dimension in another argument array is zero,arrayfunvirtually diminishes the singleton dimension to 0.

    输出数组的大小Ais such that each dimension is the largest of the input arrays in that dimension for nonzero size, or zero otherwise. Notice in the following code how dimensions of size 1 are scaled up or down to match the size of the corresponding dimension in the other argument:

    R1 = rand(2,5,4,'gpuArray'); R2 = rand(2,1,4,3,'gpuArray'); R3 = rand(1,5,4,3,'gpuArray'); R = arrayfun(@(x,y,z)(x+y.*z),R1,R2,R3); size(R)
    2 5 4 3
    R1 = rand(2,2,0,4,'gpuArray'); R2 = rand(2,1,1,4,'gpuArray'); R = arrayfun(@plus,R1,R2); size(R)
    2 2 0 4

  • Because the operations supported byarrayfunare strictly element-wise, and each element’s computation is performed independently of the others, certain restrictions are imposed:

    • Input and output arrays cannot change shape or size.

    • Functions likeranddo not support size specifications. Arrays of random numbers have independent streams for each element.

    For more limitations and details, seeTips and Restrictions.

Examples

If you define a MATLAB function as follows:

function[o1,o2] = aGpuFunction(a,b,c) o1 = a + b; o2 = o1 .* c + 2;

You can evaluate this on the GPU.

s1 = gpuArray(rand(400)); s2 = gpuArray(rand(400)); s3 = gpuArray(rand(400)); [o1,o2] = arrayfun(@aGpuFunction,s1,s2,s3); whos
Name Size Bytes Class o1 400x400 108 gpuArray o2 400x400 108 gpuArray s1 400x400 108 gpuArray s2 400x400 108 gpuArray s3 400x400 108 gpuArray

使用gatherto retrieve the data from the GPU to the MATLAB workspace.

d = gather(o2);

See Also

|||

Introduced in R2010b

Was this topic helpful?
Parallel Computing Toolbox Documentation
万博1manbetx

Try MATLAB, Simulink, and Other Products

Get trial now