batch
ワーカー上で MATLAB スクリプトまたは関数を実行する
構文
説明
は、既定のクラスター プロファイルによって指定されたクラスターのワーカー上で、j
= batch(expression
)expression
を式として実行します。この関数は、式を実行するジョブ オブジェクトのハンドル j
を返します。
既定では、ワークスペース変数は batch(expression)
の実行時にクライアントからワーカーにコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。
は 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
クラスター オブジェクトで指定されたクラスターのワーカー上で実行される点が異なります。
は、1 つ以上の名前と値の引数を使用して、ジョブの動作を変更するオプションを指定します。特に指定のない限り、これらのオプションは関数およびスクリプトのバッチをサポートします。この構文は、前述の構文にある任意の入力引数の組み合わせに加えて使用します。j
= batch(___,Name,Value
)
例
バッチ ジョブとしてスクリプトを実行
この例では、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
入力引数
script
— MATLAB® スクリプト
文字ベクトル | string スカラー
MATLAB スクリプト。文字ベクトルまたは string スカラーとして指定します。
既定では、ワークスペース変数はこの引数を指定するときにクライアントからワーカーにコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。
例: batch('aScript');
データ型: char
| string
expression
— 評価式
文字ベクトル | string スカラー
評価式。文字ベクトルまたは string スカラーとして指定します。
既定では、ワークスペース変数はこの引数を指定するときにクライアントからワーカーにコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。
例: batch('y = magic(3)');
データ型: char
| string
myCluster
— クラスター
parallel.Cluster
オブジェクト
クラスター。クラスター計算リソースを表す parallel.Cluster
オブジェクトとして指定します。オブジェクトを作成するには、関数parcluster
を使用します。
例: cluster = parcluster; batch(cluster,'aScript');
データ型: parallel.Cluster
fcn
— ワーカーで評価される関数
関数ハンドル | 文字ベクトル
ワーカーで評価される関数。関数ハンドルまたは関数名として指定します。
例: batch(@myFunction,1,{x,y});
データ型: char
| string
| function_handle
N
— 出力数
非負の整数
評価された関数 fcn
から返される出力数。非負の整数として指定します。
例: batch(@myFunction,1,{x,y});
データ型: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
{x1,...,xn}
— 入力引数
cell 配列
名前と値の引数
オプションの引数ペアを Name1=Value1,...,NameN=ValueN
として指定します。ここで、Name
は引数名で、Value
は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。
R2021a 以前は、名前と値をそれぞれコンマを使って区切り、Name
を引用符で囲みました。
例: j = batch(@myFunction,1,{x,y},'Pool',3);
Workspace
— ワーカーにコピーする変数
構造体スカラー
ワーカーにコピーする変数。'Workspace'
と構造体スカラーからなるコンマ区切りのペアとして指定します。
既定値は、クライアント ワークスペースの変数に対応するフィールドをもつ構造体スカラーです。変数をこの構造体スカラーのフィールドとして指定します。
script
または expression
を指定した場合、ワークスペース変数はクライアントからワーカーにのみコピーされます。ジョブおよびタスク オブジェクトはワーカーにコピーされません。
例: workspace.myVar = 5; j = batch('aScript','Workspace',workspace);
データ型: struct
Profile
— クラスター プロファイル
文字ベクトル | string
クラスターの識別に使用するクラスター プロファイル。'Profile'
と文字ベクトルまたは string で構成されるコンマ区切りのペアとして指定します。このオプションを省略した場合は、既定のプロファイルがクラスターの特定に使用され、ジョブおよびタスクのプロパティに適用されます。
例: j = batch('aScript','Profile','Processes');
データ型: char
| string
AdditionalPaths
— ワーカーに追加するパス
文字ベクトル | string 配列 | 文字ベクトルの cell 配列
スクリプトまたは関数を実行する前に 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 配列
ワーカーに転送するファイルまたはフォルダー。'AttachedFiles'
と、文字ベクトル、string 配列または文字ベクトルの cell 配列で構成されるコンマ区切りのペアとして指定します。
例: j = batch(@myFunction,1,{x,y},'AttachedFiles','myData.dat');
データ型: char
| string
| cell
AutoAddClientPath
— クライアントのパスでユーザーが追加したエントリをワーカーのパスに追加するフラグ
true
(既定値) | false
クライアントのパスでユーザーが追加したエントリをワーカーのパスに追加するフラグ。'AutoAddClientPath'
と logical 値で構成されるコンマ区切りのペアとして指定します。
例: j = batch(@myFunction,1,{x,y},'AutoAddClientPath',false);
データ型: logical
AutoAttachFiles
— 依存関係の分析を有効にするかどうかのフラグ
true
(既定値) | false
依存関係の分析を有効にするかどうか、およびコード ファイルをジョブに自動付加するかどうかのフラグ。'AutoAttachFiles'
と logical 値で構成されるコンマ区切りのペアとして指定します。この値を true
に設定した場合、バッチ スクリプトまたは関数が解析され、依存するコード ファイルが自動的にワーカーに転送されます。
例: j = batch(@myFunction,1,{x,y},'AutoAttachFiles',true);
データ型: logical
CurrentFolder
— スクリプトまたは関数を実行するフォルダー
文字ベクトル | string
スクリプトまたは関数を実行するフォルダー。'CurrentFolder'
と文字ベクトルまたは string で構成されるコンマ区切りのペアとして指定します。このフォルダーがワーカーに存在するという保証はありません。このプロパティの既定値は、batch
コマンドを実行するときの MATLAB の現在のディレクトリです。引数が '.'
の場合、バッチの実行前にフォルダーの変更はありません。
例: j = batch(@myFunction,1,{x,y},'CurrentFolder','.');
データ型: char
| string
CaptureDiary
— ダイアリを収集するフラグ
true
(既定値) | false
関数の呼び出しからダイアリを収集するフラグ。'CaptureDiary'
と logical 値で構成されるコンマ区切りのペアとして指定します。収集されたデータの詳細については、diary
を参照してください。
例: j = batch('aScript','CaptureDiary',false);
データ型: logical
EnvironmentVariables
— コピーする環境変数
文字ベクトル | string 配列 | 文字ベクトルの cell 配列
クライアント セッションからワーカーにコピーする環境変数。'EnvironmentVariables'
と、文字ベクトル、string 配列、または文字ベクトルの cell 配列で構成されるコンマ区切りのペアとして指定します。ここで指定した名前は、該当する並列プロファイルで指定された EnvironmentVariables
プロパティに追加され、環境変数の完全なリストが生成されます。リストにあっても設定されていない変数はワーカーにコピーされません。これらの環境変数は、バッチ ジョブの存在期間にわたってワーカーで設定されています。
例: j = batch('aScript','EnvironmentVariables',"MY_ENV_VAR");
データ型: char
| string
| cell
Pool
— 並列プールに加えられるワーカーの数
0
(既定値) | 非負の整数 | 非負の整数の 2 要素ベクトル
並列プールに加えられるワーカーの数。'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
SpmdEnabled
— spmd
がプールでのバッチ ジョブでサポートされるかどうかを指定するフラグ
true
(既定値) | false
R2024a 以降
バッチ ジョブの並列プールに対し spmd
のサポートを有効にするかどうかを指定するフラグ。logical 値として指定します。サポートは、ローカル クラスターまたは MATLAB ジョブ スケジューラ クラスター上でのみ無効にできます。
parfor
の反復にワーカー間の通信は関与しません。したがって、'SpmdEnabled'
が false
の場合、1 つ以上のワーカーが parfor
ループの実行中に中止となってもループは続行します。
データ型: logical
出力引数
j
— ジョブ
parallel.Job
オブジェクト
ヒント
バッチ ジョブのステータスの表示や、進行状況の追跡を行うには、ジョブ モニターの説明に従って、ジョブ モニターを使用します。また、ジョブ モニターを使用すると、別のセッションで作成されたバッチ ジョブのジョブ オブジェクトや、
batch
の呼び出しからジョブ オブジェクトを返さずに作成されたバッチ ジョブのジョブ オブジェクトを取得することもできます。クラスターのストレージ リソースを不必要に消費しないようにするため、不要なバッチ ジョブがあれば削除してください。
コードの開発とテストを行うには、クライアント マシン上のローカル クラスターでバッチ ジョブを実行します。MATLAB セッションを閉じると、ローカル クラスターを使用するバッチ ジョブもすべてただちに停止します。
作業をリモート クラスターにオフロードすると、ジョブの処理中に MATLAB クライアント セッションを閉じ、後から、あるいは新しいクライアント セッションでバッチ ジョブから情報を取得できます。
バージョン履歴
R2008a で導入R2024a: 最大 2000 個のワーカーをもつ batch
ジョブのプールのサポート
R2024a 以降では、batch
は最大 2000 個のワーカーをもつプールをサポートします。R2024a より前では、batch
は最大 1000 個のワーカーをもつプールをサポートします。
R2024a: バッチ ジョブのプールのワーカー間の spmd 通信を無効化
名前と値の引数 'Pool'
を使用して並列プールを作成すると、spmd 通信が既定で有効になっているプールが作成されます。spmd 通信が有効でないプールを使用するには、名前と値の引数 'SpmdEnabled'
を使用して spmd サポートを無効にします。
R2021a: batch
が cell 配列の入力引数 {C1,...,Cn}
を C1,...,Cn
として評価
R2021a 以降、batch
を使用してオフロードされた関数 fcn
は cell 配列の入力引数 {C1,...,Cn}
を fcn(C1,...,Cn)
として評価するようになりました。以前のリリースでは、{C1,...,Cn}
はエラーをスローし、{{C1,...,Cn}}
が fcn(C1,...,Cn)
として評価されていました。
R2021a 以降は、fcn({a,b},{c,d})
をクラスター myCluster
に 1 つの出力でオフロードするには、次のコードを使用します。
batch(myCluster,@fcn,1,{{a,b},{c,d}});
batch(myCluster,@fcn,1,{{{a,b},{c,d}}});
MATLAB コマンド
次の MATLAB コマンドに対応するリンクがクリックされました。
コマンドを MATLAB コマンド ウィンドウに入力して実行してください。Web ブラウザーは MATLAB コマンドをサポートしていません。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)