# arrayfun

Apply function to each element of array on GPU

## Description

**Note**

This function behaves similarly to the MATLAB^{®} function `arrayfun`

, except that the evaluation of the
function happens on the GPU, not on the CPU. Any required data not already on the GPU is
moved to GPU memory. The MATLAB function passed in for evaluation is compiled and then executed on the
GPU. All output arguments are returned as `gpuArray`

objects. You can retrieve `gpuArray`

data using
the `gather`

function.

applies the function `B`

= arrayfun(`FUN`

,`A`

)`FUN`

to each element of the
`gpuArray`

`A`

. `arrayfun`

then concatenates the outputs from
`FUN`

into output `gpuArray`

`B`

. `B`

is the same size as `A`

and
`B(i,j,...) = FUN(A(i,j,...))`

. The input argument `FUN`

is a function handle to a MATLAB function that takes one input argument and returns a scalar value.
`FUN`

is called as many times as there are elements of
`A`

.

You cannot specify the order in which `arrayfun`

calculates the
elements of `B`

or rely on them being done in any particular order.

applies `B`

= arrayfun(`FUN`

,A1,...,An)`FUN`

to the elements of the arrays `A1,...,An`

,
so that `B(i,j,...) = FUN(A1(i,j,...),...,An(i,j,...))`

. The function
`FUN`

must take `n`

input arguments and return a scalar.
The nonsingleton dimensions of the inputs `A1,...,An`

must all match, or
the inputs must be scalar. Any singleton dimensions or scalar inputs are virtually
replicated before being input to the function `FUN`

.

`[B1,...,Bm] = arrayfun(`

returns multiple output arrays `FUN`

,___)`B1,...,Bm`

when the function
`FUN`

returns `m`

output values.
`arrayfun`

calls `FUN`

each time with as many outputs as
there are in the call to `arrayfun`

, that is, `m`

times.
If you call `arrayfun`

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

## Input Arguments

## Output Arguments

## Tips

The first time you call

`arrayfun`

to run a particular function on the GPU, there is some overhead time to set up the function for GPU execution. Subsequent calls of`arrayfun`

with the same function can run faster.Nonsingleton dimensions of input arrays must match each other. In other words, the corresponding dimensions of arguments

`A1,...,An`

, must be equal to each other, or equal to one. Whenever a dimension of an input array is singleton (equal to`1`

),`arrayfun`

uses singleton expansion. The array is virtually replicated along the singleton dimension to match the largest of the other arrays in that dimension. When a dimension of an input array is singleton and the corresponding dimension in another argument array is zero,`arrayfun`

virtually diminishes the singleton dimension to`0`

.Each dimension of the output array

`B`

is the same size as the largest of the input arrays in that dimension for nonzero size, or zero otherwise. The following code shows how dimensions of size`1`

are scaled up or down to match the size of the corresponding dimension in other arguments.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 by

`arrayfun`

are strictly element-wise, and each computation of each element is performed independently of the others, certain restrictions are imposed:Input and output arrays cannot change shape or size.

Array-creation functions such as

`rand`

do not support size specifications. Arrays of random numbers have independent streams for each element.

Like

`arrayfun`

in MATLAB, matrix exponential power, multiplication, and division (`^`

,`*`

,`/`

,`\`

) perform element-wise calculations only.Operations that change the size or shape of the input or output arrays (

`cat`

,`reshape`

, and so on) are not supported.Read-only indexing (

`subsref`

) and access to variables of the parent (outer) function workspace from within nested functions is supported. You can index variables that exist in the function before the evaluation on the GPU. Assignment or`subsasgn`

indexing of these variables from within the nested function is not supported. For an example of the supported usage, see Stencil Operations on a GPU.Anonymous functions do not have access to their parent function workspace.

Overloading the supported functions is not allowed.

The code cannot call scripts.

There is no

`ans`

variable to hold unassigned computation results. Make sure to explicitly assign to variables the results of all calculations.The following language features are not supported: persistent or global variables,

`parfor`

,`spmd`

, and`try`

/`catch`

.P-code files cannot contain a call to

`arrayfun`

with`gpuArray`

data.

## Version History

**Introduced in R2010b**