gather

将分布式数组、Composite 对象或 gpuArray 对象传输到本地工作区

全页折叠

语法

X = gather(A)

[X1,X2,...,Xn] = gather(A1,A2,...,An)

X = gather(Cd,destination)

[X1,X2,...,Xn] = gather(Cd1,Cd2,...,Cdn,destination)

X = gather(Cp)

[X1,X2,...,Xn] = gather(Cp1,Cp2,...,Cpn)

说明

示例

X = gather(A) 可以对以下数组数据进行操作：

在 gpuArray 上：将 A 的元素从 GPU 传输到本地工作区并将它们分配给 X。
在分布式数组上，spmd 语句之外：将来自多个工作进程的 A 元素收集到本地工作区并将它们分配给 X。
在协同分布数组中，在 spmd 语句或通信作业内：将 A 的元素聚集在一起并将它们复制到每个工作进程上的 X 中。

您可以在其他数据类型上调用 gather，例如 tall 数组（参见 gather (tall)）。如果数据类型不支持收集，则 gather 没有效果。

收集 GPU 数组或分布式数组的成本可能很高，而且通常没有必要，除非您需要将结果与不支持这些类型数组的函数一起使用。有关函数支持的更多信息，请参阅在 GPU 上运行 MATLAB 函数或使用分布式数组运行 MATLAB 函数。

X = gather(gpuArray(X))、X = gather(distributed(X)) 或 X = gather(codistributed(X)) 返回原始数组 X。

[X1,X2,...,Xn] = gather(A1,A2,...,An) 将多个数组 A1,A2,...,An 收集到相应的输出 X1,X2,...,Xn 中。输入参量和输出参量的数量必须匹配。

示例

X = gather(Cd,destination) 将协同分布数组 Cd 转换为变体数组 X，使得所有元素都包含在 destination 指定的工作进程上，而 X 在所有其他工作进程上都是一个 0×0 的空双精度数。

[X1,X2,...,Xn] = gather(Cd1,Cd2,...,Cdn,destination) 将协同分布数组 Cd1,Cd2,...,Cdn 收集到相应的输出 X1,X2,...,Xn 中，其中所有元素均位于由 destination 指定的工作进程上。输入参量和输出参量的数量必须匹配。

示例

X = gather(Cp) 将来自多个工作进程的复合数组 Cp 的所有元素收集到本地工作区并将它们分配给单元数组 X。X 中的单元格数量取决于 Cp 引用的工作进程数量。 (自 R2023a 起)

[X1,X2,...,Xn] = gather(Cp1,Cp2,...,Cpn) 将复合数组 Cp1,Cp2,...,Cpn 收集到相应的单元格数组 X1,X2,...,Xn 中。输入参量和输出参量的数量必须匹配。 (自 R2023a 起)

示例

全部折叠

收集 gpuArray

将 GPU 操作的结果收集到 MATLAB^® 工作区。

G = gpuArray(rand(1024,1));
F = sqrt(G);   % Input and output are both gpuArray
W = gather(G); % Return array to workspace
whos

  Name         Size            Bytes  Class       Attributes

  F         1024x1              8192  gpuArray              
  G         1024x1              8192  gpuArray              
  W         1024x1              8192  double

收集分布式数组

将分布式数组 D 的所有元素收集到客户端。

n = 10;
parpool('Processes',4);
D = distributed(magic(n)); % Distribute array to workers
M = gather(D)              % Return array to client

收集协同分布数组

将幻方分布在您的工作进程中，然后将整个矩阵收集到每个工作进程身上，然后再收集到客户端上。此代码在所有工作进程和客户端上产生与 M = magic(n) 等效的结果。

n = 10;
parpool('Processes',4);
spmd
  Cd = codistributed(magic(n));
  M = gather(Cd); % Gather all elements to all workers
end
S = gather(Cd)   % Gather elements to client

将 Cd 的所有元素聚集到工作进程 1 上，以执行无法跨分布式数组执行的操作。

n = 10;
spmd
  Cd = codistributed(magic(n));
  out = gather(Cd,1);
  if spmdIndex == 1
    % Characteristic sum for this magic square:
    characteristicSum = sum(1:n^2)/n;
    % Ensure that the diagonal sums are equal to the 
    % characteristic sum:
    areDiagonalsEqual = isequal ...
      (trace(out),trace(flipud(out)),characteristicSum)
  end
end

Worker 1: 
  
  areDiagonalsEqual =
  
    logical
  
     1

收集复合数组

自 R2023a 起

将并行工作进程上存储的复合数组 Cp 的所有元素收集到客户端上。

使用 spmd 语句在您的工作进程上创建一个幻方，并在客户端上创建一个 Composite 数组 Cp。

n = 10
p = parpool('Processes',4);
spmd
    Cp = magic(n);
end

将存储在您的工作进程身上的结果收集到客户端上。

results = gather(Cp)

results =

  1×4 cell array

    {10×10 double}    {10×10 double}    {10×10 double}    {10×10 double}

输入参数

全部折叠

`A` — 要收集的数组
gpuArray | 分布式数组 | 协同分布数组

要收集的数组，指定为 gpuArray、distributed 数组或 codistributed 数组。

`Cd` — 协同分布数组收集
协同分布数组

要收集的协同分布数组，指定为 codistributed 数组。

`Cp` — 复合数组收集
复合数组

自 R2023a 起

要收集的复合数组，指定为 Composite 数组。

提示

请注意，gather 分别在其执行的所有工作进程的工作区中或 MATLAB 客户端上组装共分布或分布式数组，但不会同时在两者中组装。如果在 spmd 语句中使用 gather，则可通过其对应的 Composite 对象在客户端访问收集的数组；请参阅使用复合材料访问工作进程变量。如果您在通信作业中运行 gather，则可以将收集的数组作为任务的输出参量返回到客户端。

由于 gather 函数需要所有工作进程之间的通信，因此您无法通过将该函数放在条件语句（例如 if spmdIndex == 1）内来将所有工作进程的数据收集到单个工作进程上。