arrayfun

Apply function to each element of array on GPU

Syntax

B = arrayfun(func,A)

B = arrayfun(func,A1,...,An)

[B1,...,Bm] = arrayfun(func,___)

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.

B = arrayfun(func,A) applies a function func to each element of a gpuArray A and then concatenates the outputs from func into output gpuArray B. B is the same size as A and B(i,j,...) = func(A(i,j,...)). The input argument func is a function handle to a MATLAB function that takes one input argument and returns a scalar. func is called as many times as there are elements of A.

example

B = arrayfun(func,A1,...,An) applies func to the elements of the arrays A1,...,An, so that B(i,j,...) = func(A1(i,j,...),...,An(i,j,...)). The function func must take n input arguments and return a scalar. The sizes of A1,...,An must match or be compatible.

example

[B1,...,Bm] = arrayfun(func,___) returns multiple output arrays B1,...,Bm when the function func returns m output values. func can return output arguments having different data types, but the data type of each output must be the same each time func is called.

example

Examples

collapse all

Run Function on GPU

Open Live Script

Define a function, cal. The function cal applies a gain and an offset correction to an array of measurement data. The function performs only element-wise operations when applying the gain factor and offset to each element of the rawdata array.

function c = cal(rawdata,gain,offset)
c = (rawdata.*gain) + offset;
end

Create an array of measurement data.

meas = 1:4

meas = 1×4

     1     2     3     4

Create arrays containing the gain and offset data.

gn   = rand([1 4],"gpuArray")/100 + 0.995

gn =

    0.9958    0.9967    0.9985    1.0032

offs = rand([1 4],"gpuArray")/50  - 0.01

offs =

    0.0063   -0.0045   -0.0081    0.0002

Run the calibration function on the GPU. The function runs on the GPU because the input arguments gn and offs are already GPU arrays, and are therefore stored in GPU memory. Before the function runs, it converts the input array meas to a gpuArray object.

corrected = arrayfun(@cal,meas,gn,offs)

corrected =

    1.0021    1.9889    2.9874    4.0129

Performing a small number of element-wise operations on a GPU is unlikely to speed up your code. For an example showing how arrayfun execution speed scales with input array size, see Improve Performance of Element-Wise MATLAB Functions on the GPU Using arrayfun.

Use Function with Multiple Outputs

Open Live Script

Define a function that applies element-wise operations to multiple inputs and returns multiple outputs.

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

Create gpuArray input data, and evaluate the function on the GPU.

s1 = rand(400,"gpuArray");
s2 = rand(400,"gpuArray");
s3 = rand(400,"gpuArray");
[o1,o2] = arrayfun(@myFun,s1,s2,s3);
whos

  Name        Size               Bytes  Class       Attributes

  o1        400x400            1280000  gpuArray              
  o2        400x400            1280000  gpuArray              
  s1        400x400            1280000  gpuArray              
  s2        400x400            1280000  gpuArray              
  s3        400x400            1280000  gpuArray

Use Random Numbers with `arrayfun`

Open Live Script

Define a function that creates and uses a random number, R.

function Y = myRandFun(X)
R = rand;
Y = R.*X;
end

Run the function on the GPU. As G is a 4-by-4 gpuArray object, arrayfun applies the myRandfun function 16 times, generating 16 different random scalar values, H.

G = ones(4,"gpuArray")*2;
H = arrayfun(@myRandFun,G)

H =

    1.0557    0.3599    1.5303    0.2745
    0.4268    1.1226    1.5261    1.7068
    0.0302    0.5814    0.2556    0.3902
    1.1210    1.5310    1.3665    0.8487

Input Arguments

collapse all

`func` — Function to apply
function handle

Function to apply to the elements of the input arrays, specified as a function handle.

func must return scalar values.
For each output argument, func must return values of the same class each time it is called.
func must accept numerical or logical input data.
func must be a handle to a function that is written in the MATLAB language. You cannot specify func as a handle to a MEX function.
You cannot specify func as a static method or a class constructor method.

func can contain the following built-in MATLAB functions and operators.

abs
and
acos
acosh
acot
acoth
acsc
acsch
asec
asech
asin
asinh
atan
atan2
atanh
beta
betaln
bitand
bitcmp
bitget
bitor
bitset
bitshift
bitxor
cast
ceil
complex
conj
cos
cosh
cot
coth
csc

csch
double
eps
eq
erf
erfc
erfcinv
erfcx
erfinv
exp
expm1
false
fix
floor
gamma
gammaln
ge
gt
hypot
imag
Inf
int8
int16
int32
int64
intmax
intmin
isfinite
isinf
isnan
ldivide
le
log

log2
log10
log1p
logical
lt
max
min
minus
mod
NaN
ne
not
ones
or
pi
plus
pow2
power
rand
randi
randn
rdivide
real
reallog
realmax
realmin
realpow
realsqrt
rem
round
sec
sech
sign

sin
single
sinh
sqrt
tan
tanh
times
true
uint8
uint16
uint32
uint64
xor
zeros

+
-
.*
./
.\
.^
==
~=
<
<=
>
>=
&
|
~
&&
||

Scalar expansion versions of the following:

*
/
\
^

Branching instructions:

break
continue
else, elseif, if
for
return
switch, case, otherwise
while

Functions that create arrays (such as Inf, NaN, ones, rand, randi, randn, and zeros) do not support size specifications as input arguments. Instead, the size of the generated array is determined by the size of the input variables to your functions. Enough array elements are generated to satisfy the needs of your input or output variables. You can specify the data type using both class and like syntaxes. The following examples show supported syntaxes for array-creation functions:

a = rand;
b = ones;
c = zeros(like=x);
d = Inf("single");
e = randi([0 9],"uint32");

When you use rand, randi, and randn to generate random numbers within func, each element is generated from a different substream. For more information about generating random numbers on the GPU, see Random Number Streams on a GPU.

When you use switch, case, otherwise within func, case expressions support only numeric and logical values.

`A` — Input array
scalars | vectors | matrices | multidimensional arrays

Input array, specified as scalars, vectors, matrices, or multidimensional arrays. At least one input array argument must be a gpuArray for arrayfun to run on the GPU. Each array that is stored in CPU memory is converted to a gpuArray before the function is evaluated. If you plan to make several calls to arrayfun with the same array, it is more efficient to convert that array to a gpuArray.

Output Arguments

collapse all

`B` — Output array
`gpuArray`

Output array, returned as a gpuArray.

Limitations

The sizes of A1,...,An must match or be compatible. The size of output array B depends on the sizes of A1,...,An. For more information, see Compatible Array Sizes for Basic Operations.
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.
You cannot specify the order in which arrayfun calculates the elements of output array B or rely on them being done in any particular order.
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.
Calls to arrayfun inside P-code files or using arrayfun to evaluate functions obfuscated as a P-code files are not supported in standalone functions compiled using MATLAB Compiler™.

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.

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The arrayfun function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray. For more information, see Run MATLAB Functions on a GPU.

Version History

Introduced in R2010b

expand all

R2024b: Support for functions defined in class definition files

You can now call arrayfun in a class method to evaluate functions defined in the class definition file (a file with a .m extension that contains the classdef keyword).

For example, this class contains a method, output, that uses arrayfun to evaluate a local function, localFun.

classdef TestClass
    methods
        function output = func(obj,x)
            output = arrayfun(@localFun,x);
        end
    end
end

function output = localFun(x)
output = x.*x;
end

For more information about defining classes in MATLAB, see Creating a Simple Class.

R2024b: Support for P-Code files

You can now use P-code files with arrayfun. You can:

Use arrayfun to evaluate a function obfuscated as a P-code file.
Call arrayfun inside a P-code file.
Use arrayfun when the function it applies contains a call to a function obfuscated as a P-code file.

For more information about P-code files, see Create a Content-Obscured File with P-Code.

R2024a: Support for cell array case expressions in `switch`, `case`, `otherwise`

Use a cell array as the case expression to compare the switch expression against multiple values within the function you apply using arrayfun. For example, you can use case {x1,y1} to execute the corresponding code if the switch expression matches at least one of x1 and y1.

R2023b: Support for `switch`, `case`, and `otherwise`

You can now use switch conditional statements in functions you apply using arrayfun. This functionality has these limitations:

Case expressions support only numeric and logical values.
Using a cell array as the case expression to compare the switch expression against multiple values, for example, case {x1,y1}, is not supported.

R2023b: Changes to indexing into and writing to variables in nested functions

Passing arrays from a parent workspace to a nested function and indexing into the array within the nested function now errors

For example, in the following code, the variable parentWorkspaceVar is created in the parent workspace of the foo function. If foo is used in an arrayfun call with gpuArray input, and if the foo function passes parentWorkspaceVar as input to a nested function within foo, the code errors.

As a workaround, instead of passing the parent workspace variable (parentWorkspaceVar) to the nested function (bar), use the parent workspace variable directly as it is already in the scope of the nested function.

Errors	Workaround
function y = exampleFunction parentWorkspaceVar = 1:9; x = ones(2,"gpuArray"); y = arrayfun(@foo,x); function y = foo(x) y = bar(parentWorkspaceVar); function y = bar(z) % ERRORS y = z(1); end end end	function y = exampleFunction parentWorkspaceVar = 1:9; x = ones(2,"gpuArray"); y = arrayfun(@foo,x); function y = foo(x) y = bar; function y = bar % Previously this variable was passed in, now it is used directly as it is in scope. y = parentWorkspaceVar(1); end end end

Errors

Workaround

function y = exampleFunction
    parentWorkspaceVar = 1:9;
    x = ones(2,"gpuArray");
    y = arrayfun(@foo,x);

    function y = foo(x)
        y = bar(parentWorkspaceVar);

        function y = bar(z) % ERRORS
            y = z(1);
        end

    end

end

function y = exampleFunction
    parentWorkspaceVar = 1:9;
    x = ones(2,"gpuArray");
    y = arrayfun(@foo,x);

    function y = foo(x)
        y = bar;

        function y = bar
 % Previously this variable was passed in, now it is used directly as it is in scope.
            y = parentWorkspaceVar(1);
        end

    end

end

Functions writing into variables created in a parent function now error

In the following code, the variable workspaceVar is created in the workspace of the bar function. If bar is used in an arrayfun call with gpuArray input, and if a nested function foo writes into workspaceVar, the code errors.

As a workaround, instead of writing to the variable (workspaceVar) within the nested function (foo), add another output to the nested function and use the output to write to the variable.

Errors	Workaround
function x = exampleFunction z = ones(2,"gpuArray"); x = arrayfun(@bar,z); function y = bar(z) workspaceVar = 2; foo(z); function x = foo(z) workspaceVar = 10; % ERRORS x = z; end y = workspaceVar; end end	function x = exampleFunction z = ones(2,"gpuArray"); x = arrayfun(@bar,z); function y = bar(z) workspaceVar = 2; [out,workspaceVar] = foo(z); % Write to workspaceVar outside foo. function [x,y] = foo(z) % Add another output y to the nested function. y = 10; x = z; end y = workspaceVar; end end

Errors

Workaround

function x = exampleFunction
    z = ones(2,"gpuArray");
    x = arrayfun(@bar,z);

    function y = bar(z)
        workspaceVar = 2;
        foo(z);

        function x = foo(z)
            workspaceVar = 10; % ERRORS
            x = z;
        end

        y = workspaceVar;
    end

end

function x = exampleFunction
    z = ones(2,"gpuArray");
    x = arrayfun(@bar,z);

    function y = bar(z)
        workspaceVar = 2;
        [out,workspaceVar] = foo(z); % Write to workspaceVar outside foo.

        function [x,y] = foo(z) % Add another output y to the nested function.
            y = 10; 
            x = z;
        end

        y = workspaceVar;
    end

end

arrayfun

Syntax

Description

Examples

Run Function on GPU

Use Function with Multiple Outputs

Use Random Numbers with `arrayfun`

Input Arguments

`func` — Function to apply
function handle

`A` — Input array
scalars | vectors | matrices | multidimensional arrays

Output Arguments

`B` — Output array
`gpuArray`

Limitations

Tips

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

R2024b: Support for functions defined in class definition files

R2024b: Support for P-Code files

R2024a: Support for cell array case expressions in `switch`, `case`, `otherwise`

R2023b: Support for `switch`, `case`, and `otherwise`

R2023b: Changes to indexing into and writing to variables in nested functions

See Also

Topics

arrayfun

Syntax

Description

Examples

Run Function on GPU

Use Function with Multiple Outputs

Use Random Numbers with arrayfun

Input Arguments

func — Function to apply function handle

A — Input array scalars | vectors | matrices | multidimensional arrays

Output Arguments

B — Output array gpuArray

Limitations

Tips

Extended Capabilities

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

R2024b: Support for functions defined in class definition files

R2024b: Support for P-Code files

R2024a: Support for cell array case expressions in switch, case, otherwise

R2023b: Support for switch, case, and otherwise

R2023b: Changes to indexing into and writing to variables in nested functions

See Also

Topics

Use Random Numbers with `arrayfun`

`func` — Function to apply
function handle

`A` — Input array
scalars | vectors | matrices | multidimensional arrays

`B` — Output array
`gpuArray`

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

R2024a: Support for cell array case expressions in `switch`, `case`, `otherwise`

R2023b: Support for `switch`, `case`, and `otherwise`