Main Content

このページの翻訳は最新ではありません。ここをクリックして、英語の最新版を参照してください。

batch

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

説明

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

j = batch(myCluster,script)batch(script) とほぼ同じですが、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 を引数なしで使用します。

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

delete(job);
clear job

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

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

batch を使用して、計算をオフロードしバックグラウンドで実行することができます。コードでファイルへのアクセスが必要な場合は、'AttachedFiles''AdditionalPaths' などの追加オプションを使用して、データをアクセス可能にできます。計算の実行中に MATLAB での作業を終了または続行し、結果を後で復元することができます。

例の準備

次のコマンドを使用して、この例のサポート ファイルを準備してコピーします。

prepareSupportingFiles;

バッチ ジョブの実行

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

c = parcluster();

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

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

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

  • ワーカーの初期作業ディレクトリを保持し、既定の設定を使用する場合は、'CurrentFolder''.' に設定します。

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

この例では、3 つのワーカーがある並列プールを使用して、初期作業ディレクトリの一時的な場所を選択しています。

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

batch は関数内の計算を並列ワーカーにオフロードします。これにより、計算の実行中も MATLAB での作業を続行できます。

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

wait(job);

結果を取得するには、ジョブ オブジェクトに対して fetchOutputs を使用します。

コードにエラーがある場合、fetchOutputs はエラーをスローします。エラー情報にアクセスするには、ジョブの Task オブジェクトの Error プロパティを確認します。この例では、コードはワーカーが検出できないファイルに依存しています。

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

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

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

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

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

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

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

ワーカーがアクセスできない場所にデータが存在する場合、名前と値のペアの引数 'AttachedFiles' を使用してファイルをワーカーに転送することができます。

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

既存のジョブの検索

ジョブの投入後に MATLAB を閉じて、結果を後で取得することができます。MATLAB を閉じる前に、ジョブ ID をメモしておいてください。

job3ID = job(3).ID
job3ID = 19

もう一度 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

クラスター。クラスター計算リソースを表す 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

名前と値のペアの引数

オプションの Name,Value の引数ペアをコンマ区切りで指定します。Name は引数名で、Value は対応する値です。Name は引用符で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順序で指定できます。

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

スクリプトまたは関数を呼び出す直前のワーカーのワークスペース。'Workspace' と 1 行 1 列の struct で構成されるコンマ区切りのペアとして指定します。この構造体のフィールド名は変数名を定義し、フィールド値はワークスペース変数に割り当てられます。既定では、このパラメーターには、batch が実行される現在のワークスペース内の全変数用のフィールドが設定されます。このパラメーターではスクリプトの実行のみがサポートされます。

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

データ型: struct

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

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

データ型: 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 は別のワーカーを使用してバッチ ジョブ自体を実行します。

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

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

例: 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

出力引数

すべて折りたたむ

スクリプトまたは関数を実行するジョブ。parallel.Job オブジェクトとして返されます。

例: j = batch('aScript');

データ型: parallel.Job

ヒント

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

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

R2008a で導入