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 列の空の double 配列となるようにします。

例

[X1,X2,...,Xn] = gather(Cd1,Cd2,...,Cdn,destination) は対話型分散配列 Cd1,Cd2,...,Cdn を収集して、対応する出力 X1,X2,...,Xn を生成します。これには destination で指定されたワーカーのすべての要素が含まれます。入力引数の数と出力引数の数は一致しなければなりません。

X = gather(Cp) は、複数のワーカーの Composite 配列 Cp のすべての要素をローカル ワークスペースに収集し、cell 配列 X に割り当てます。X 内のセルの数は、Cp で参照されるワーカーの数に依存しています。 (R2023a 以降)

例

[X1,X2,...,Xn] = gather(Cp1,Cp2,...,Cpn) は Composite 配列 Cp1,Cp2,...,Cpn を対応する cell 配列 X1,X2,...,Xn に収集します。入力引数の数と出力引数の数は一致しなければなりません。 (R2023a 以降)

例

すべて折りたたむ

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 以降

並列ワーカーに保存されている Composite 配列 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}

入力引数

すべて折りたたむ

収集する配列。gpuArray 配列、distributed 配列、または codistributed 配列として指定します。

収集する対話型分散配列。codistributed 配列として指定します。

R2023a 以降

収集する Composite 配列。Composite 配列として指定します。

ヒント

  • gather は、実行される全ワーカーのワークスペースに対話型分散配列をまとめるか、または MATLAB クライアントに分散配列を集めますが、両方は行わないことに注意してください。spmd ステートメント内で gather を使用する場合、収集された配列にクライアント上でアクセスするには、それに対応する Composite オブジェクトを使用します。Composite を使用するワーカー変数へのアクセスを参照してください。gather を通信ジョブ内で実行する場合、収集された配列はタスクからの出力引数としてクライアントに返すことができます。

  • 分散配列または対話型分散配列の gather 関数にはすべてのワーカー間での通信が必要であるため、if spmdIndex == 1 などの条件付きステートメントの内部にこの関数を置いて、すべてのワーカーからのデータを単一のワーカーに収集することはできません。

  • ワークスペースで変数を右クリックして [GPU から収集] を選択すると gpuArray オブジェクトを収集できます。 (R2025a 以降)

バージョン履歴

R2006b で導入

すべて展開する

参考

| | | | |