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) 指定使用一个或多个名称-值参量修改作业行为的选项。除非另有说明，这些选项支持函数和脚本的批处理。除了以前语法中的任何输入参量组合之外，还可以使用此语法。

示例

全部折叠

将脚本作为批处理作业运行

打开实时脚本

此示例显示如何使用 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 中工作，然后稍后恢复结果。

准备示例

使用支持函数 prepareSupportingFiles 将此示例所需的数据复制到当前工作文件夹。

prepareSupportingFiles;

您当前的工作文件夹现在包含 4 个文件：A.dat、B1.dat、B2.dat 和 B3.dat。

运行批处理作业

使用 parcluster 创建一个集群对象。默认情况下，parcluster 使用您的默认集群配置文件。在 MATLAB 主页选项卡上的环境部分中的并行 > 选择默认集群中检查您的默认集群配置文件。

c = parcluster();

将您的代码放在函数内，并使用 batch 将其作为批处理作业提交。有关自定义函数的示例，请参阅支持函数 divideData。指定预期的输出参量数量以及包含函数输入的单元格数组。

请注意，如果您使用批处理发送脚本文件，MATLAB 会将所有工作区变量传输到集群，即使您的脚本不使用它们。如果您的工作空间较大，则会对数据传输时间产生负面影响。最佳实践是将脚本转换为函数文件以避免这种通信开销。您只需在脚本开头添加一个函数行即可完成此操作。为了减少此示例中的开销，divideData 在此实时脚本之外的文件中定义。

如果您的代码使用并行池，请使用 'Pool' 名称-值对参量来创建具有您指定工作进程数量的并行池。batch 使用额外的工作进程来运行函数本身。

默认情况下，batch 将工作进程的初始工作文件夹更改为 MATLAB 客户端的当前文件夹。控制工作进程中的初始工作文件夹会很有用。例如，如果您的集群使用不同的文件系统，您可能需要控制它，因此路径不同，例如当您从 Windows 客户端计算机提交到 Linux 集群时。

为了保留工作进程的初始工作文件夹并使用其默认值，请将 'CurrentFolder' 设置为 '.'。
要更改初始工作文件夹，请将 'CurrentFolder' 设置为您选择的文件夹。

此示例使用具有三个工作进程的并行池，并为初始工作文件夹选择一个临时位置。使用 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));

或者，您可以使用作业 Monitor 来跟踪您的作业。您可以从 MATLAB 主页选项卡的环境部分中的并行 > 监控作业中打开它。

检索结果并清理数据

要检索批处理作业的结果，请使用 fetchOutputs 函数。fetchOutputs 返回一个单元格数组，其中包含使用 batch 运行的函数的输出。

X = fetchOutputs(job(3))

X = 1×1 cell array
    {40×207 double}

当您检索到所有必需的输出并且不再需要该作业对象时，请删除它以清理其数据并避免不必要地消耗资源。

delete(job)
clear job

输入参数

全部折叠

`script` — MATLAB^® 脚本
字符向量 | 字符串标量

MATLAB 脚本，指定为字符向量或字符串标量。

默认情况下，当您指定此参量时，工作区变量将从客户端复制到工作进程。作业和任务对象不会被复制到工作进程手中。

示例: batch('aScript');

数据类型: char | string

`expression` — 要计算的表达式
字符向量 | 字符串标量

要计算的表达式，指定为字符向量或字符串标量。

默认情况下，当您指定此参量时，工作区变量将从客户端复制到工作进程。作业和任务对象不会被复制到工作进程手中。

示例: 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});

`{x1,...,xn}` — 输入参量
元胞数组

函数 fcn 的输入参量，指定为单元数组。

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

数据类型: 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` — 集群配置文件
字符向量 | 字符串

用于识别集群的聚类配置文件，指定为由 'Profile' 和字符向量或字符串组成的逗号分隔的对。如果省略此选项，则使用默认配置文件来识别集群并将其应用于作业和任务属性。

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

数据类型: char | string

`AdditionalPaths` — 添加到工作进程的路径
字符向量 | 字符串数组 | 字符向量元胞数组

在脚本或函数执行之前添加到工作进程的 MATLAB 搜索路径的路径，指定为以逗号分隔的对，由 'AdditionalPaths' 和字符向量、字符串数组或字符向量单元格数组组成。

工作进程器上的默认搜索路径可能与客户端上的不同；路径差异可能是由于当前工作文件夹 (cwd)、平台或网络文件系统访问不同造成的。指定 'AdditionalPaths' 名称-值参量有助于确保工作进程在正确的位置查找文件，例如代码文件、数据文件或模型文件。

您可以使用 'AdditionalPaths' 访问共享文件系统中的文件。请注意，路径表示可能因目标机器而异。'AdditionalPaths' 必须是集群中的机器所看到的路径。例如，如果您本地 Windows^® 机器上的 Z:\data 是您的 Linux^® 集群上的 /network/data，那么将后者添加到 'AdditionalPaths'。如果您使用数据存储，请使用 'AlternateFileSystemRoots' 来处理其他表示。有关详细信息，请参阅Set Up Datastore for Processing on Different Machines or Clusters。

请注意，AdditionalPaths 仅在您使用相对路径或文件名引用文件时才有助于查找文件，而使用绝对路径则不起作用。

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

数据类型: char | string | cell

`AttachedFiles` — 要传输的文件或文件夹
字符向量 | 字符串数组 | 字符向量元胞数组

要传输给工作进程的文件或文件夹，指定为以逗号分隔的对，由 'AttachedFiles' 和字符向量、字符串数组或字符向量单元格数组组成。

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

数据类型: char | string | cell

`AutoAddClientPath` — 标记以将客户端路径上的用户添加的条目添加到工作进程路径
`true` (默认) | `false`

标志用于将客户端路径上的用户添加的条目添加到工作进程路径，指定为由 'AutoAddClientPath' 和逻辑值组成的逗号分隔的对。

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

数据类型: logical

`AutoAttachFiles` — 启用依赖性分析的标志
`true` (默认) | `false`

标志以启用依赖性分析并自动将代码文件附加到作业，指定为由 'AutoAttachFiles' 和逻辑值组成的逗号分隔的对。如果将该值设置为 true，则会分析批处理脚本或函数并将其依赖的代码文件自动传输给工作进程。

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

数据类型: logical

`CurrentFolder` — 脚本或函数执行的文件夹
字符向量 | 字符串

脚本或函数执行的文件夹，指定为由 'CurrentFolder' 和字符向量或字符串组成的逗号分隔的对。无法保证此文件夹在工作进程程序上存在。该属性的默认值是执行 batch 命令时 MATLAB 的当前目录。如果参量是 '.'，则批处理执行之前文件夹中没有变化。

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

数据类型: char | string

`CaptureDiary` — 标记以收集日记
`true` (默认) | `false`

标志用于从函数调用中收集日记，指定为由 'CaptureDiary' 和逻辑值组成的逗号分隔的对。有关收集的数据的信息，请参阅 diary。

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

数据类型: logical

`EnvironmentVariables` — 要复制的环境变量
字符向量 | 字符串数组 | 字符向量元胞数组

要从客户端会话复制到工作进程客户端会话的环境变量，指定为由 'EnvironmentVariables' 和字符向量、字符串数组或字符数组单元格数组组成的逗号分隔的对。此处指定的名称附加到适用的并行配置文件中指定的 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]);

`SpmdEnabled` — 用于指定池批处理作业是否支持 `spmd` 的标志
`true` (默认) | `false`

自 R2024a 起

标志指定是否在批处理作业的并行池上启用了 spmd 支持，指定为逻辑值。您只能在本地或 MATLAB 作业调度器集群上禁用支持。

parfor 迭代不涉及工作进程之间的通信。因此，如果 'SpmdEnabled' 是 false，则即使在循环执行期间一个或多个工作进程中止，parfor 循环仍会继续。

数据类型: logical

输出参量

全部折叠

`j` — 作业
`parallel.Job` 对象

作业，以 parallel.Job 对象形式返回。

示例: j = batch('aScript');

数据类型: parallel.Job

提示

要查看批处理作业的状态或跟踪其进度，请使用作业监视器，如作业监控器中所述。您还可以使用作业监视器检索在不同会话中创建的批处理作业的作业对象，或者检索未从 batch 调用返回作业对象的批处理作业的作业对象。

删除不再需要的批处理作业，以避免不必要地消耗集群存储资源。

版本历史记录

在 R2008a 中推出

全部展开

R2024a: 支持最多有 2000 个工作进程的 `batch` 作业池。

从 R2024a 开始，batch 支持最多包含 2000 个工作进程的池。在 R2024a 之前，batch 支持最多 1000 个工作进程的池。

R2024a: 禁用批处理作业池中的工作进程之间的 spmd 通信

当您使用 'Pool' 名称-值参量创建并行池时，软件默认会创建一个启用 spmd 通信的池。要使用未启用 spmd 通信的池，请使用 'SpmdEnabled' 名称-值对参量来禁用 spmd 支持。

R2021a: `batch` 现在将单元数组输入参量 `{C1,...,Cn}` 评估为 `C1,...,Cn`

从 R2021a 开始，使用 batch 卸载的函数 fcn 将单元数组输入参量 {C1,...,Cn} 评估为 fcn(C1,...,Cn)。在以前的版本中，{C1,...,Cn} 引发了一个错误，并且 {{C1,...,Cn}} 被评估为 fcn(C1,...,Cn)。

从 R2021a 开始，使用以下代码将 fcn({a,b},{c,d}) 卸载到具有一个输出的集群 myCluster 上。

batch(myCluster,@fcn,1,{{a,b},{c,d}});

在以前的版本中，您应使用以下代码。

batch(myCluster,@fcn,1,{{{a,b},{c,d}}});

另请参阅

主题

设置工作进程的环境变量

batch

语法

说明

示例

将脚本作为批处理作业运行

运行批处理作业并从工作进程访问文件

输入参数

script — MATLAB® 脚本 字符向量 | 字符串标量

expression — 要计算的表达式 字符向量 | 字符串标量

myCluster — 集群 parallel.Cluster 对象

fcn — 工作进程要计算的函数 函数句柄 | 字符向量

N — 输出个数 非负整数

{x1,...,xn} — 输入参量 元胞数组

名称-值参数

Workspace — 复制到工作进程 的变量 结构体标量

Profile — 集群配置文件 字符向量 | 字符串

AdditionalPaths — 添加到工作进程的路径 字符向量 | 字符串数组 | 字符向量元胞数组

AttachedFiles — 要传输的文件或文件夹 字符向量 | 字符串数组 | 字符向量元胞数组

AutoAddClientPath — 标记以将客户端路径上的用户添加的条目添加到工作进程路径 true (默认) | false

AutoAttachFiles — 启用依赖性分析的标志 true (默认) | false

CurrentFolder — 脚本或函数执行的文件夹 字符向量 | 字符串

CaptureDiary — 标记以收集日记 true (默认) | false

EnvironmentVariables — 要复制的环境变量 字符向量 | 字符串数组 | 字符向量元胞数组

Pool — 组成并行池的工作进程数量 0 (默认) | 非负整数 | 非负整数的 2 元素向量

SpmdEnabled — 用于指定池批处理作业是否支持 spmd 的标志 true (默认) | false

输出参量

j — 作业 parallel.Job 对象

提示

版本历史记录

R2024a: 支持最多有 2000 个工作进程的 batch 作业池。

R2024a: 禁用批处理作业池中的工作进程之间的 spmd 通信

R2021a: batch 现在将单元数组输入参量 {C1,...,Cn} 评估为 C1,...,Cn

另请参阅

主题

WeChat

`script` — MATLAB^® 脚本
字符向量 | 字符串标量

`expression` — 要计算的表达式
字符向量 | 字符串标量

`myCluster` — 集群
`parallel.Cluster` 对象

`fcn` — 工作进程要计算的函数
函数句柄 | 字符向量

`N` — 输出个数
非负整数

`{x1,...,xn}` — 输入参量
元胞数组

`Workspace` — 复制到工作进程的变量
结构体标量

`Profile` — 集群配置文件
字符向量 | 字符串

`AdditionalPaths` — 添加到工作进程的路径
字符向量 | 字符串数组 | 字符向量元胞数组

`AttachedFiles` — 要传输的文件或文件夹
字符向量 | 字符串数组 | 字符向量元胞数组

`AutoAddClientPath` — 标记以将客户端路径上的用户添加的条目添加到工作进程路径
`true` (默认) | `false`

`AutoAttachFiles` — 启用依赖性分析的标志
`true` (默认) | `false`

`CurrentFolder` — 脚本或函数执行的文件夹
字符向量 | 字符串

`CaptureDiary` — 标记以收集日记
`true` (默认) | `false`

`EnvironmentVariables` — 要复制的环境变量
字符向量 | 字符串数组 | 字符向量元胞数组

`Pool` — 组成并行池的工作进程数量
`0` (默认) | 非负整数 | 非负整数的 2 元素向量

`SpmdEnabled` — 用于指定池批处理作业是否支持 `spmd` 的标志
`true` (默认) | `false`

`j` — 作业
`parallel.Job` 对象

R2024a: 支持最多有 2000 个工作进程的 `batch` 作业池。

R2021a: `batch` 现在将单元数组输入参量 `{C1,...,Cn}` 评估为 `C1,...,Cn`