Main Content

batch

ワーカー上で MATLAB スクリプトまたは関数を実行する

ページ内をすべて折りたたむ

構文

j = batch(script)
j = batch(expression)
j = batch(myCluster,script)
j = batch(myCluster,expression)
j = batch(fcn,N,{x1,...,xn})
j = batch(myCluster,fcn,N,{x1,...,xn})
j = batch(___,Name,Value)

説明

j = batch(script) は既定のクラスター プロファイルによって指定されたクラスターのワーカー上で、スクリプト ファイル script を実行します (メモ: スクリプト名にファイル拡張子 .m を含めないでください)。この関数は、スクリプトを実行するジョブ オブジェクトのハンドル j を返します。スクリプト ファイル script はワーカーにコピーされます。

既定では、ワークスペース変数は batch(script) の実行時にクライアントからワーカーにコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。

例

j = batch(expression) は、既定のクラスター プロファイルによって指定されたクラスターのワーカー上で、expression を式として実行します。この関数は、式を実行するジョブ オブジェクトのハンドル j を返します。

既定では、ワークスペース変数は batch(expression) の実行時にクライアントからワーカーにコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。

j = batch(myCluster,script) は batch(script) とほぼ同じですが、myCluster クラスター オブジェクトで指定されたクラスターのワーカー上でスクリプトが実行される点が異なります。

j = batch(myCluster,expression) は batch(expression) とほぼ同じですが、myCluster クラスター オブジェクトで指定されたクラスターのワーカー上で式が実行される点が異なります。

j = batch(fcn,N,{x1,...,xn}) は既定のクラスター プロファイルによって指定されたクラスターのワーカー上で、関数 fcn を実行します。この関数は、それを実行するジョブ オブジェクトのハンドル j を返します。この関数は指定した引数 x1,...,xn を用いて評価され、N 個の出力引数を返します。fcn の関数ファイルはワーカーにコピーされます。(メモ: 関数名の引数にファイル拡張子 .m を含めないでください)。

例

j = batch(myCluster,fcn,N,{x1,...,xn}) は batch(fcn,N,{x1,...,xn}) とほぼ同じですが、myCluster クラスター オブジェクトで指定されたクラスターのワーカー上で実行される点が異なります。

例

j = batch(___,Name,Value) は、1 つ以上の名前と値の引数を使用して、ジョブの動作を変更するオプションを指定します。特に指定のない限り、これらのオプションは関数およびスクリプトのバッチをサポートします。この構文は、前述の構文にある任意の入力引数の組み合わせに加えて使用します。

例

例

すべて折りたたむ

ライブ スクリプトを開く

この例では、batch を使用して、バックグラウンドで実行される MATLAB® ワーカー セッションに作業をオフロードする方法を説明します。

計算の実行中も引き続き MATLAB を使用できます。

関数batchを使用して、スクリプトをバッチ ジョブとして実行します。既定で、batch は既定のクラスター プロファイルを使用します。既定のクラスター プロファイルは、MATLAB の [ホーム] タブの [環境] セクションの [並列]、[並列環境を選択] で確認します。または、名前と値のペアの引数 'Profile' を使用してクラスター プロファイルを指定することもできます。

job = batch('myScript');

batch は MATLAB をブロックしないため、計算の実行中に作業を続行できます。

ジョブが完了するまで MATLAB をブロックする場合は、ジョブ オブジェクトに対して関数 wait を使用します。

wait(job);

既定では、MATLAB はバッチ ジョブからのコマンド ウィンドウの出力をジョブのダイアリに保存します。これを取得するには、関数 diary を使用します。

diary(job)
--- Start Diary ---
n = 100

--- End Diary ---

ジョブの完了後、関数loadを使用して結果を取得します。

load(job,'x');
plot(x)

バッチ ジョブのすべての変数を読み込むには、代わりに load(job) を使用します。

必要な変数をすべて読み込んだら、ジョブ オブジェクトを削除してデータをクリーン アップし、不必要にリソースが消費されないようにします。

delete(job);
clear job

batch を使用してスクリプト ファイルを送信すると、MATLAB はスクリプトで使用しない場合でも、すべてのワークスペース変数をクラスターに転送します。大規模なワークスペースのデータ転送時間は長くなる場合があります。ベスト プラクティスとして、スクリプトを関数ファイルに変換することにより、この通信オーバーヘッドを回避します。関数を使用する例については、バッチ ジョブの実行とワーカーからのファイルへのアクセスを参照してください。

batch の高度なオプションについては、バッチ ジョブの実行とワーカーからのファイルへのアクセスを参照してください。

ライブ スクリプトを開く

batch を使用して、計算をオフロードしバックグラウンドで実行することができます。

コードでファイルへのアクセスが必要な場合は、'AttachedFiles' や 'AdditionalPaths' などの追加オプションを使用して、データをアクセス可能にできます。計算の実行中も MATLAB での作業を続行できます。計算をリモート クラスターに投入すると、MATLAB を閉じて、結果を後で復元できます。

例の準備

サポート関数 prepareSupportingFiles を使用して、この例に必要なデータを現在の作業フォルダーにコピーします。

prepareSupportingFiles;

これで、現在の作業フォルダーには、A.dat、B1.dat、B2.dat、B3.dat の 4 つのファイルが含まれています。

バッチ ジョブの実行

parclusterを使用してクラスター オブジェクトを作成します。既定で、parcluster は既定のクラスター プロファイルを使用します。既定のクラスター プロファイルは、MATLAB の [ホーム] タブの [環境] セクションの [並列]、[既定のクラスターの選択] で確認します。

c = parcluster();

関数内にコードを配置し、batchを使用してバッチ ジョブとして投入します。カスタム関数の例については、サポート関数 divideData を参照してください。必要な出力引数の数と、cell 配列を、関数の入力で指定します。

batch を使用してスクリプト ファイルを送信すると、MATLAB はスクリプトで使用しない場合でも、すべてのワークスペース変数をクラスターに転送します。ワークスペースが大きい場合、これはデータ転送時間に悪影響を及ぼします。ベスト プラクティスとして、スクリプトを関数ファイルに変換することにより、この通信オーバーヘッドを回避します。これを行うには、スクリプトの冒頭に関数の行を単純に追加します。この例では、オーバーヘッドを削減するために divideData がこのライブ スクリプト外のファイルで定義されています。

コードで並列プールが使用されている場合、名前と値のペアの引数 'Pool' を使用して、指定した数のワーカーがある並列プールを作成します。batch は追加のワーカーを使用して関数自体を実行します。

既定では、batch はワーカーの初期作業フォルダーを、MATLAB クライアントの現在のフォルダーに変更します。これは、ワーカーの初期作業フォルダーの制御に便利な場合があります。たとえば、クラスターの使用しているファイルシステムが異なり (Windows クライアント マシンから Linux クラスターに送信する場合など)、そのためにパスが異なる場合、この制御が必要となることがあります。

  • ワーカーの初期作業フォルダーを保持し、既定の設定を使用する場合は、'CurrentFolder' を '.' に設定します。

  • 初期作業フォルダーを変更するには、'CurrentFolder' を目的のフォルダーに設定します。

この例では、3 つのワーカーがある並列プールを使用して、初期作業フォルダーの一時的な場所を選択しています。batch を使用して、divideData 内の計算をオフロードします。

job = batch(c,@divideData,1,{}, ...
    'Pool',3, ...
    'CurrentFolder',tempdir);

batch は並列ワーカー上で divideData を実行するため、計算の実行中も MATLAB での作業を続行できます。

ジョブが完了するまで MATLAB をブロックする場合は、ジョブ オブジェクトに対して関数 wait を使用します。

wait(job);

結果を取得するには、ジョブ オブジェクトに対して fetchOutputs を使用します。divideData はワーカーが検出できないファイルに依存しているため、fetchOutputs はエラーをスローします。エラー情報にアクセスするには、ジョブの Task オブジェクトの Error プロパティに対して getReport を使用します。この例では、コードはワーカーが検出できないファイルに依存しています。

getReport(job.Tasks(1).Error)
ans = 
    'Error using divideData (line 4)
     Unable to read file 'B2.dat'. No such file or directory.'

ワーカーからのファイルへのアクセス

既定では、batch は自動的にコードを解析して必要なファイルをワーカーに転送します。場合によっては、これらのファイルを明示的に転送しなければなりません。たとえば、実行時にファイル名を決定する場合などです。

この例では、divideData はサポート ファイル A.dat にアクセスします。batch はこのファイルを自動的に検出および転送します。この関数は B1.dat にもアクセスしますが、ファイル名は実行時に解決されるため、依存関係の自動分析ではこのファイルは検出されません。

type divideData.m 
function X = divideData()
    A = load("A.dat"); 
    X = zeros(flip(size(A)));
    parfor i = 1:3
        B = load("B" + i + ".dat");
        X = X + A\B;
    end
end

ワーカーがアクセスできる場所にデータが存在する場合、名前と値のペアの引数 'AdditionalPaths' を使用してその場所を指定できます。'AdditionalPaths' によりこのパスがワーカーの MATLAB 検索パスに追加され、ワーカーがデータを認識できるようになります。

pathToData = pwd;
job(2) = batch(c,@divideData,1,{}, ...
    'Pool',3, ...
    'CurrentFolder',tempdir, ...
    'AdditionalPaths',pathToData);
wait(job(2));

ワーカーがアクセスできない場所にデータが存在する場合、名前と値のペアの引数 'AttachedFiles' を使用してファイルをワーカーに転送することができます。クライアントとワーカーが同じファイル システムを共有していない場合や、クラスターで汎用スケジューラ インターフェイスが非共有モードで使用されている場合は、ファイルを転送する必要があります。詳細については、汎用スケジューラ インターフェイスを使用した構成 (MATLAB Parallel Server)を参照してください。

filenames = "B" + string(1:3) + ".dat";
job(3) = batch(c,@divideData,1,{}, ...
    'Pool',3, ...
    'CurrentFolder',tempdir, ...
    'AttachedFiles',filenames);

既存のジョブの検索

ジョブをリモート クラスターに投入すると、ジョブの投入後に MATLAB を閉じて、結果を後で取得できます。MATLAB を閉じる前に、ジョブ ID をメモしておいてください。

job3ID = job(3).ID
job3ID = 25

もう一度 MATLAB を開いたときに、関数 findJob を使用してこのジョブを検索できます。

job(3) = findJob(c,'ID',job3ID);
wait(job(3));

あるいは、ジョブ モニターを使用してジョブを追跡することもできます。これを開くには、MATLAB の [ホーム] タブの [環境] セクションで [並列]、[ジョブの監視] を選択します。

結果の取得とデータのクリーン アップ

バッチ ジョブの結果を取得するには、関数 fetchOutputs を使用します。fetchOutputs は、batch で実行された関数の出力が含まれる cell 配列を返します。

X = fetchOutputs(job(3))
X = 1×1 cell array
    {40×207 double}

必要な出力がすべて取得され、ジョブ オブジェクトがこれ以上必要ではない場合は、ジョブ オブジェクトを削除してデータをクリーン アップし、リソースを不必要に消費しないようにします。

delete(job)
clear job

入力引数

すべて折りたたむ

MATLAB スクリプト。文字ベクトルまたは string スカラーとして指定します。

既定では、ワークスペース変数はこの引数を指定するときにクライアントからワーカーにコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。

例: batch('aScript');

データ型: char | string

評価式。文字ベクトルまたは string スカラーとして指定します。

既定では、ワークスペース変数はこの引数を指定するときにクライアントからワーカーにコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。

例: batch('y = magic(3)');

データ型: char | string

クラスター。クラスター計算リソースを表す parallel.Cluster オブジェクトとして指定します。オブジェクトを作成するには、関数parclusterを使用します。

例: cluster = parcluster; batch(cluster,'aScript');

データ型: parallel.Cluster

ワーカーで評価される関数。関数ハンドルまたは関数名として指定します。

例: batch(@myFunction,1,{x,y});

データ型: char | string | function_handle

評価された関数 fcn から返される出力数。非負の整数として指定します。

例: batch(@myFunction,1,{x,y});

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

関数 fcn の入力引数。cell 配列として指定します。

例: batch(@myFunction,1,{x,y});

データ型: cell

名前と値の引数

オプションの引数ペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

R2021a 以前は、名前と値をそれぞれコンマを使って区切り、Name を引用符で囲みました。

例: j = batch(@myFunction,1,{x,y},'Pool',3);

ワーカーにコピーする変数。'Workspace' と構造体スカラーからなるコンマ区切りのペアとして指定します。

既定値は、クライアント ワークスペースの変数に対応するフィールドをもつ構造体スカラーです。変数をこの構造体スカラーのフィールドとして指定します。

script または expression を指定した場合、ワークスペース変数はクライアントからワーカーにのみコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。

例: workspace.myVar = 5; j = batch('aScript','Workspace',workspace);

データ型: struct

クラスターの識別に使用するクラスター プロファイル。'Profile' と文字ベクトルまたは string で構成されるコンマ区切りのペアとして指定します。このオプションを省略した場合は、既定のプロファイルがクラスターの特定に使用され、ジョブおよびタスクのプロパティに適用されます。

例: j = batch('aScript','Profile','Processes');

データ型: char | string

スクリプトまたは関数を実行する前に MATLAB 検索パスに追加するワーカーのパス。'AdditionalPaths' と、文字ベクトル、string 配列、または文字ベクトルの cell 配列で構成されるコンマ区切りのペアとして指定します。

既定の検索パスは、ワーカー上とクライアント上で異なる場合があります。パスが異なる原因は、現在の作業フォルダー (cwd)、プラットフォームまたはネットワーク ファイル システムへのアクセスが異なるためである可能性があります。名前と値の引数 'AdditionalPaths' を指定すると、ワーカーがコード ファイル、データ ファイル、モデル ファイルなどのファイルを正しい場所で検索するようになります。

'AdditionalPaths' を使用すると、共有ファイル システムのファイルにアクセスできます。パスの表現は、ターゲット マシンによって異なります。'AdditionalPaths' は、クラスター内のマシンから見たパスでなければなりません。たとえば、ローカルの Windows® マシンの Z:\data が、Linux® クラスターでは /network/data と認識されている場合、'AdditionalPaths' には後者を追加します。データ ストアを使用している場合は、代わりに 'AlternateFileSystemRoots' を使用して、他の表現を処理します。詳細については、異なるマシンまたはクラスターで処理するためのデータストアの設定を参照してください。

AdditionalPaths は、相対パスまたはファイル名を使用してファイルを参照するためにファイルを検索する場合に使用します。絶対パスを使用する場合は使用しません。

例: j = batch(@myFunction,1,{x,y},'AdditionalPaths','/network/data/');

データ型: char | string | cell

ワーカーに転送するファイルまたはフォルダー。'AttachedFiles' と、文字ベクトル、string 配列または文字ベクトルの cell 配列で構成されるコンマ区切りのペアとして指定します。

例: j = batch(@myFunction,1,{x,y},'AttachedFiles','myData.dat');

データ型: char | string | cell

クライアントのパスでユーザーが追加したエントリをワーカーのパスに追加するフラグ。'AutoAddClientPath' と logical 値で構成されるコンマ区切りのペアとして指定します。

例: j = batch(@myFunction,1,{x,y},'AutoAddClientPath',false);

データ型: logical

依存関係の分析を有効にするかどうか、およびコード ファイルをジョブに自動付加するかどうかのフラグ。'AutoAttachFiles' と logical 値で構成されるコンマ区切りのペアとして指定します。この値を true に設定した場合、バッチ スクリプトまたは関数が解析され、依存するコード ファイルが自動的にワーカーに転送されます。

例: j = batch(@myFunction,1,{x,y},'AutoAttachFiles',true);

データ型: logical

スクリプトまたは関数を実行するフォルダー。'CurrentFolder' と文字ベクトルまたは string で構成されるコンマ区切りのペアとして指定します。このフォルダーがワーカーに存在するという保証はありません。このプロパティの既定値は、batch コマンドを実行するときの MATLAB の現在のディレクトリです。引数が '.' の場合、バッチの実行前にフォルダーの変更はありません。

例: j = batch(@myFunction,1,{x,y},'CurrentFolder','.');

データ型: char | string

関数の呼び出しからダイアリを収集するフラグ。'CaptureDiary' と logical 値で構成されるコンマ区切りのペアとして指定します。収集されたデータの詳細については、diary を参照してください。

例: j = batch('aScript','CaptureDiary',false);

データ型: logical

クライアント セッションからワーカーにコピーする環境変数。'EnvironmentVariables' と、文字ベクトル、string 配列、または文字ベクトルの cell 配列で構成されるコンマ区切りのペアとして指定します。ここで指定した名前は、該当する並列プロファイルで指定された EnvironmentVariables プロパティに追加され、環境変数の完全なリストが生成されます。リストにあっても設定されていない変数はワーカーにコピーされません。これらの環境変数は、バッチ ジョブの存在期間にわたってワーカーで設定されています。

例: j = batch('aScript','EnvironmentVariables',"MY_ENV_VAR");

データ型: char | string | cell

並列プールに加えられるワーカーの数。'Pool' と次のいずれかで構成されるコンマ区切りのペアとして指定します。

  • 非負の整数。

  • 非負の整数の 2 要素ベクトル。これは範囲として解釈されます。この結果生成される並列プールのサイズは、要求された範囲内で最大のサイズとなります。

さらに、batch は別のワーカーを使用してバッチ ジョブ自体を実行します。

このスクリプトまたは関数では、バッチ コード内にある parfor や spmd などのステートメントの実行にこのプールを使用します。このプールではバッチを実行するワーカーに加えて N 個のワーカーが必要となるため、クラスターでは少なくとも N+1 個のワーカーが使用可能でなければなりません。batch を実行するために並列プールを事前に実行しておく必要はありません。また、バッチにより作成される新しいプールは、既に開いている並列プールとは無関係です。詳細については、並列プールでのバッチ ジョブの実行を参照してください。

既定値の 0 を使用する場合、このスクリプトまたは関数は単一のワーカーでのみ実行され、並列プールでは実行されません。

batch は、最大 2000 個のワーカーをもつプールをサポートします。 (R2024a 以降)

例: j = batch(@myFunction,1,{x,y},'Pool',4);

例: j = batch(@myFunction,1,{x,y},'Pool',[2,6]);

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

R2024a 以降

バッチ ジョブの並列プールに対し spmd のサポートを有効にするかどうかを指定するフラグ。logical 値として指定します。サポートは、ローカル クラスターまたは MATLAB ジョブ スケジューラ クラスター上でのみ無効にできます。

parfor の反復にワーカー間の通信は関与しません。したがって、'SpmdEnabled' が false の場合、1 つ以上のワーカーが parfor ループの実行中に中止となってもループは続行します。

データ型: logical

出力引数

すべて折りたたむ

ジョブ。parallel.Job オブジェクトとして返されます。

例: j = batch('aScript');

データ型: parallel.Job

ヒント

  • バッチ ジョブのステータスの表示や、進行状況の追跡を行うには、ジョブ モニターの説明に従って、ジョブ モニターを使用します。また、ジョブ モニターを使用すると、別のセッションで作成されたバッチ ジョブのジョブ オブジェクトや、batch の呼び出しからジョブ オブジェクトを返さずに作成されたバッチ ジョブのジョブ オブジェクトを取得することもできます。

  • クラスターのストレージ リソースを不必要に消費しないようにするため、不要なバッチ ジョブがあれば削除してください。

  • コードの開発とテストを行うには、クライアント マシン上のローカル クラスターでバッチ ジョブを実行します。MATLAB セッションを閉じると、ローカル クラスターを使用するバッチ ジョブもすべてただちに停止します。

  • 作業をリモート クラスターにオフロードすると、ジョブの処理中に MATLAB クライアント セッションを閉じ、後から、あるいは新しいクライアント セッションでバッチ ジョブから情報を取得できます。

バージョン履歴

R2008a で導入

すべて展開する

参考

| | | | |

トピック