arrayfun

将函数应用于 GPU 上的数组的每个元素

语法

B = arrayfun(func,A)

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

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

说明

注意

该函数的行为与 MATLAB^® 函数 arrayfun 类似，只是该函数的评估发生在 GPU 上，而不是 CPU 上。任何尚未在 GPU 上的所需数据都将移动到 GPU 内存。传入评估的 MATLAB 函数经过编译，然后在 GPU 上执行。所有输出参量都作为 gpuArray 对象返回。

B = arrayfun(func,A) 将函数 func 应用于 gpuArray A 的每个元素，然后将 func 的输出连接到输出 gpuArray B。B 的大小与 A 和 B(i,j,...) = func(A(i,j,...)) 相同。输入参量 func 是 MATLAB 函数的函数句柄，该函数接受一个输入参量并返回一个标量。func 的调用次数与 A 的元素数量相同。

示例

B = arrayfun(func,A1,...,An) 将 func 应用于数组 A1,...,An 的元素，从而 B(i,j,...) = func(A1(i,j,...),...,An(i,j,...))。函数 func 必须接受 n 输入参量并返回一个标量。A1,...,An 的大小必须匹配或兼容。

示例

当函数 B1,...,Bm 返回 func 个输出值时，[B1,...,Bm] = arrayfun(func,___) 返回多个输出数组 m。func 可以返回具有不同数据类型的输出参量，但每次调用 func 时，每个输出的数据类型必须相同。

示例

全部折叠

在 GPU 上运行函数

打开实时脚本

定义一个函数，cal。函数 cal 对测量数据数组应用增益和偏移校正。当将 gain 因子和 offset 应用于 rawdata 数组的每个元素时，该函数仅执行逐元素操作。

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

创建测量数据数组。

meas = 1:4

meas = 1×4

     1     2     3     4

创建包含增益和偏移数据的数组。

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

在 GPU 上运行校准函数。该函数在 GPU 上运行，因为输入参量 gn 和 offs 已经是 GPU 数组，因此存储在 GPU 内存中。函数运行之前，它将输入数组 meas 转换为 gpuArray 对象。

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

corrected =

    1.0021    1.9889    2.9874    4.0129

在 GPU 上执行少量逐元素操作不太可能加快您的代码速度。有关展示 arrayfun 执行速度如何随输入数组大小变化的示例，请参阅使用 arrayfun 提高 GPU 上元素级 MATLAB 函数的性能。

使用具有多个输出的函数

打开实时脚本

定义一个函数，将逐元素操作应用于多个输入并返回多个输出。

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

创建 gpuArray 输入数据，并在 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

结合 `arrayfun` 使用随机数

打开实时脚本

定义一个创建并使用随机数 R 的函数。

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

在 GPU 上运行该函数。由于 G 是一个 4×4 的 gpuArray 对象，arrayfun 应用 myRandfun 函数 16 次，生成 16 个不同的随机标量值，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

输入参数

全部折叠

`func` — 要应用的函数
函数句柄

应用于输入数组元素的函数，指定为函数句柄。

func 必须返回标量值。
对于每个输出参量，func 每次调用时都必须返回同一类的值。
func 必须接受数值或逻辑输入数据。
func 必须是用 MATLAB 语言编写的函数的句柄。您不能将 func 指定为 MEX 函数的句柄。
您不能将 func 指定为静态方法或类构造函数方法。

func 可以包含以下内置 MATLAB 函数和运算符。

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

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

以下的标量扩展版本：

*
/
\
^

分支说明：

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

创建数组的函数（例如 Inf、NaN、ones、rand、randi、randn 和 zeros）不支持将大小规范作为输入参量。相反，生成的数组的大小由函数输入变量的大小决定。生成足够的数组元素来满足您的输入或输出变量的需求。您可以使用类和 like 语法指定数据类型。以下示例显示了数组创建函数支持的语法：

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

当您使用 rand、randi 和 randn 在 func 内生成随机数时，每个元素都是从不同的子流生成的。有关在 GPU 上生成随机数的更多信息，请参阅 GPU 上的随机数流。

当在 func 中使用 switch, case, otherwise 时，case 表达式仅支持数值和逻辑值。

`A` — 输入数组
标量 | 向量 | 矩阵 | 多维数组

输入数组，指定为标量、向量、矩阵或多维数组。至少一个输入数组参量必须是 gpuArray，arrayfun 才能在 GPU 上运行。在函数执行之前，存储在 CPU 内存中的每个数组都会转换为 gpuArray。如果您计划使用同一个数组多次调用 arrayfun，则将该数组转换为 gpuArray 会更有效率。

输出参量

全部折叠

`B` — 输出数组
`gpuArray`

输出数组，以 gpuArray 形式返回。

限制

A1,...,An 的大小必须匹配或兼容。输出数组 B 的大小取决于 A1,...,An 的大小。有关详细信息，请参阅基本运算的兼容数组大小。
由于 arrayfun 支持的操作是严格逐元素的，并且每个元素的计算都是独立于其他元素进行的，因此施加了某些限制：
- 输入和输出数组不能改变形状或大小。
- 数组创建函数（例如 rand）不支持大小规范。随机数数组的每个元素都有独立的流。
您无法指定 arrayfun 计算输出数组 B 元素的顺序，也无法依赖它们以任何特定顺序完成。
与 MATLAB 中的 arrayfun 类似，矩阵指数幂、乘法和除法（^、*、/、\）仅执行逐元素计算。
不支持改变输入或输出数组（cat、reshape 等）的大小或形状的操作。
支持只读索引 (subsref) 和从嵌套函数内部访问父（外部）函数工作区的变量。您可以在 GPU 上进行评估之前索引函数中存在的变量。不支持在嵌套函数内对这些变量进行赋值或 subsasgn 索引。有关支持的用法示例，请参阅 GPU 上的模板操作。
匿名函数无权访问其父函数工作区。
不允许重载支持的函数。
代码无法调用脚本。
没有 ans 变量来保存未分配的计算结果。确保将所有计算的结果明确分配给变量。
不支持以下语言功能：持久变量或全局变量、parfor、spmd 和 try/catch。

提示

第一次调用 arrayfun 在 GPU 上运行特定函数时，需要一些额外时间来设置该函数以供 GPU 执行。后续使用相同函数调用 arrayfun 可以运行得更快。

扩展功能

全部展开

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

该函数完全支持基于线程的环境。有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

arrayfun 函数完全支持 GPU 数组。要在 GPU 上运行该函数，请将输入数据指定为 gpuArray。有关详细信息，请参阅在 GPU 上运行 MATLAB 函数。

版本历史记录

在 R2010b 中推出

全部展开

R2025a: 支持 `intmin`、`intmax`、`realmin` 和 `realmax` 的 `like` 语法

现在，您可以在使用 arrayfun 应用函数时，使用 intmin、intmax、realmin 和 realmax 函数，并使用 like 语法指定原型数组。

例如，以下函数使用 intmin 和 intmax 来判断整数型 gpuArray x 的元素是否饱和。

function saturated = findSaturated(x)
saturated = (x == intmin(like=x)) | (x == intmax(like=x));
end

% Generate random integer gpuArray that includes saturated values.
x = randi([-200 200],1e6,1,"int8","gpuArray");

% Find saturated values.
saturated = arrayfun(@findSaturated,x);

R2025a: 支持在编译的独立应用程序中使用 P-code 文件

您现在可以在 P-代码文件中调用 arrayfun，或在使用 MATLAB Compiler™ 编译的独立应用程序中使用 arrayfun 来评估以 P-代码文件形式混淆的函数。

有关将 MATLAB 函数打包成独立应用程序的详细信息，请参阅从 MATLAB 创建独立应用程序 (MATLAB Compiler)。

R2024b: 支持类定义文件中定义的函数

现在，您可以在类方法中调用 arrayfun 来评估类定义文件（包含 .m 关键字的 classdef 扩展名的文件）中定义的函数。

例如，此类包含一个方法 output，它使用 arrayfun 来评估本地函数 localFun。

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

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

有关在 MATLAB 中定义类的更多信息，请参阅创建简单类。

R2024b: 支持 P-Code 文件

您现在可以将 P 代码文件与 arrayfun 一起使用。您可以：

使用 arrayfun 来评估混淆为 P 代码文件的函数。
在 P 代码文件中调用 arrayfun。
当所应用的函数包含对被混淆为 P 代码文件的函数的调用时，使用 arrayfun。

有关 P 代码文件的更多信息，请参阅 Create a Content-Obscured File with P-Code。

R2024a: 支持 `switch`、`case`、`otherwise` 中的元胞数组 case 表达式

使用元胞数组作为 case 表达式，将 switch 表达式与您使用 arrayfun 应用的函数中的多个值进行比较。例如，如果 switch 表达式至少匹配 case {x1,y1} 和 x1 中的一个，则可以使用 y1 来执行相应的代码。

R2023b: 支持 `switch`、`case` 和 `otherwise`

现在，您可以在使用 arrayfun 应用的函数中使用 switch 条件语句。此功能有以下限制：

Case 表达式仅支持数值和逻辑值。
不支持使用元胞数组作为 case 表达式来将 switch 表达式与多个值进行比较，例如 case {x1,y1}。

R2023b: 对嵌套函数中的变量进行索引和写入的更改

将数组从父工作区传递到嵌套函数并在嵌套函数中索引数组现在会出现错误

例如，在下面的代码中，在 parentWorkspaceVar 函数的父工作区中创建变量 foo。如果在 arrayfun 调用中使用 foo 并且输入为 gpuArray，并且 foo 函数将 parentWorkspaceVar 作为输入传递给 foo 内的嵌套函数，则代码会出现错误。

作为一种解决方法，不要将父工作区变量 (parentWorkspaceVar) 传递给嵌套函数 (bar)，而是直接使用父工作区变量，因为它已经在嵌套函数的范围内。

错误	解决方法
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

错误

解决方法

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

函数写入父函数中创建的变量现在会出错

在下面的代码中，在 workspaceVar 函数的工作区中创建了变量 bar。如果在 arrayfun 调用中使用 bar 并且输入 gpuArray，并且嵌套函数 foo 写入 workspaceVar，则代码会出错。

作为一种解决方法，不要在嵌套函数 (workspaceVar) 中写入变量 (foo)，而是向嵌套函数添加另一个输出并使用该输出写入变量。

错误	解决方法
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

错误

解决方法

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

另请参阅

gather | gpuArray | pagefun

arrayfun

语法

说明

示例

在 GPU 上运行函数

使用具有多个输出的函数

结合 arrayfun 使用随机数

输入参数

func — 要应用的函数 函数句柄

A — 输入数组 标量 | 向量 | 矩阵 | 多维数组

输出参量

B — 输出数组 gpuArray

限制

提示

扩展功能

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

GPU 数组 通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

版本历史记录

R2025a: 支持 intmin、intmax、realmin 和 realmax 的 like 语法

R2025a: 支持在编译的独立应用程序中使用 P-code 文件

R2024b: 支持类定义文件中定义的函数

R2024b: 支持 P-Code 文件

R2024a: 支持 switch、case、otherwise 中的元胞数组 case 表达式

R2023b: 支持 switch、case 和 otherwise

R2023b: 对嵌套函数中的变量进行索引和写入的更改

另请参阅

主题

结合 `arrayfun` 使用随机数

`func` — 要应用的函数
函数句柄

`A` — 输入数组
标量 | 向量 | 矩阵 | 多维数组

`B` — 输出数组
`gpuArray`

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

R2025a: 支持 `intmin`、`intmax`、`realmin` 和 `realmax` 的 `like` 语法

R2024a: 支持 `switch`、`case`、`otherwise` 中的元胞数组 case 表达式

R2023b: 支持 `switch`、`case` 和 `otherwise`