通用通用程序的插件脚本

下载示例插件脚本

为了支持通用调度器接口的使用，MathWorks^® 为几个第三方调度器提供了附加功能或插件。这些插件可从 GitHub^® 存储库或附加功能资源管理器获取，您可以下载并编辑它们以满足您的要求。

如果您的调度器有可用的插件，请下载并使用该插件。否则，请下载与您的设置最匹配的示例插件脚本之一。

使用这些工作流之一为您的调度器下载适当的插件脚本。

如果 MATLAB 客户端无法直接向调度器提交作业，MATLAB 支持使用 SSH 协议向远程集群提交命令。

如果客户端和集群节点之间没有共享文件系统，MATLAB 支持使用 SFTP 在您的计算机与集群之间复制作业和任务文件。

修改示例脚本

您可以设置其他属性来自定义客户端与集群的交互方式，而无需修改插件脚本。有关详细信息，请参阅自定义示例插件脚本的行为。

如果您的调度器或集群配置未完全由某个存储库支持，您可以修改其中一个包的脚本以满足您的要求。有关如何为通用调度器编写一组插件脚本的更多信息，请参阅编写自定义插件脚本。

包装器脚本

示例插件脚本使用包装器脚本来简化 independentSubmitFcn.m 和 communicatingSubmitFcn.m 的实现。这些脚本不是必需的，但是使用它们是一种很好的做法，可以使您的代码更具可读性。下表描述了这些脚本：

independentSubmitFcn

当您向通用集群提交独立作业时，independentSubmitFcn.m 函数会在 MATLAB 客户端会话中执行。

该函数的声明行必须是：

function independentSubmitFcn(cluster,job,environmentProperties)

MATLAB 独立作业中的每个任务都对应于调度器上的单个作业。该函数的作用是向您的第三方调度器提交 N 个作业，其中 N 是独立作业中的任务数。每项作业必须：

配置工作单元环境.  下表列出了运行单个任务时必须在工作单元 MATLAB 上设置的五个环境变量和值：

许多调度器支持将客户端环境复制作为提交命令的一部分。如果是这样，您可以在客户端中设置先前的环境变量，以便调度器可以将它们复制到工作单元环境中。如果没有，您必须修改您的提交命令以转发这些变量。

提交调度器作业以运行 MATLAB 工作单元.  一旦在工作单元上定义了给定作业和任务的五个必需参量，就可以通过调用带有适当参量的 MATLAB 可执行文件来运行该任务。要调用的 MATLAB 可执行文件在 environmentProperties.MatlabExecutable 中定义。要传递的参量在 environmentProperties.MatlabArguments 中定义。

SLURM 调度器的示例脚本.  该脚本展示了具有共享文件系统的 SLURM 调度器的基本提交函数。有关更完整的示例，请参阅 示例插件脚本。

function independentSubmitFcn(cluster,job,environmentProperties)
    % Specify the required environment variables.
    setenv('PARALLEL_SERVER_DECODE_FUNCTION', 'parallel.cluster.generic.independentDecodeFcn');
    setenv('PARALLEL_SERVER_STORAGE_CONSTRUCTOR', environmentProperties.StorageConstructor);
    setenv('PARALLEL_SERVER_STORAGE_LOCATION', environmentProperties.StorageLocation);
    setenv('PARALLEL_SERVER_JOB_LOCATION', environmentProperties.JobLocation);
    
    % Specify the MATLAB executable and arguments to run on the worker.
    % These are used in the independentJobWrapper.sh script.
    setenv('PARALLEL_SERVER_MATLAB_EXE', environmentProperties.MatlabExecutable);
    setenv('PARALLEL_SERVER_MATLAB_ARGS', environmentProperties.MatlabArguments);
    
    for ii = 1:environmentProperties.NumberOfTasks
        % Specify the environment variable required to identify which task to run.
        setenv('PARALLEL_SERVER_TASK_LOCATION', environmentProperties.TaskLocations{ii});
        % Specify the command to submit the job to the SLURM scheduler.
        % SLURM will automatically copy environment variables to workers.
        commandToRun = 'sbatch --ntasks=1 independentJobWrapper.sh';
        [cmdFailed, cmdOut] = system(commandToRun);
    end
end
 

前面的示例向调度器提交了一个简单的 bash 脚本 independentJobWrapper.sh。independentJobWrapper.sh 脚本使用环境变量嵌入 MATLAB 可执行文件和参量：

#!/bin/sh
# PARALLEL_SERVER_MATLAB_EXE - the MATLAB executable to use
# PARALLEL_SERVER_MATLAB_ARGS - the MATLAB args to use
exec "${PARALLEL_SERVER_MATLAB_EXE}" ${PARALLEL_SERVER_MATLAB_ARGS}

communicatingSubmitFcn

当您向通用集群提交通信作业时，communicatingSubmitFcn.m 函数将在 MATLAB 客户端会话中执行。

该函数的声明行必须是：

function communicatingSubmitFcn(cluster,job,environmentProperties)

此函数的目的是向您的调度器提交单个作业。此作业必须：

配置工作单元环境.  下表列出了在工作单元 MATLAB 上运行通信作业的任务时必须设置的四个环境变量和值：

许多调度器支持将客户端环境复制作为提交命令的一部分。如果是这样，您可以在客户端中设置先前的环境变量，以便调度器可以将它们复制到工作单元环境中。如果没有，您必须修改您的提交命令以转发这些变量。

提交调度器作业以启动 MPI 进程.  在为给定作业定义四个必需的参数后，通过使用 N 启动 mpiexec 工作单元 MATLAB 来运行您的作业。mpiexec 是随 Parallel Computing Toolbox 一起提供的软件，它实现了消息传递接口 (MPI) 标准，以允许在工作单元的 MATLAB 进程之间进行通信。有关 mpiexec 的更多信息，请参阅 MPICH 主页。

要运行您的作业，您必须向您的调度器提交一份作业，调度器将执行以下步骤。请注意，matlabroot 指的是工作单元节点上的 MATLAB 安装位置。

SLURM 调度器的示例脚本.  以下脚本展示了具有共享文件系统的 SLURM 调度器的基本提交函数。

提交的作业包含在 bash 脚本 communicatingJobWrapper.sh 中。该脚本实现了提交调度器作业以启动 MPI 进程中 SLURM 调度器的相关步骤。有关更完整的示例，请参阅 示例插件脚本。

function communicatingSubmitFcn(cluster,job,environmentProperties)
    % Specify the four required environment variables.
    setenv('PARALLEL_SERVER_DECODE_FUNCTION', 'parallel.cluster.generic.communicatingDecodeFcn');
    setenv('PARALLEL_SERVER_STORAGE_CONSTRUCTOR', environmentProperties.StorageConstructor);
    setenv('PARALLEL_SERVER_STORAGE_LOCATION', environmentProperties.StorageLocation);
    setenv('PARALLEL_SERVER_JOB_LOCATION', environmentProperties.JobLocation);
    
    % Specify the MATLAB executable and arguments to run on the worker.
    % Specify the location of the MATLAB install on the cluster nodes.
    % These are used in the communicatingJobWrapper.sh script.
    setenv('PARALLEL_SERVER_MATLAB_EXE', environmentProperties.MatlabExecutable);
    setenv('PARALLEL_SERVER_MATLAB_ARGS', environmentProperties.MatlabArguments);
    setenv('PARALLEL_SERVER_CMR', cluster.ClusterMatlabRoot);
    
    numberOfTasks = environmentProperties.NumberOfTasks;
    
    % Specify the command to submit a job to the SLURM scheduler which
    % requests as many processes as tasks in the job.
    % SLURM will automatically copy environment variables to workers.
    commandToRun = sprintf('sbatch --ntasks=%d communicatingJobWrapper.sh', numberOfTasks);
    [cmdFailed, cmdOut] = system(commandToRun);
end

getJobStateFcn

当您查询使用通用集群创建的作业的状态时，getJobStateFcn.m 函数会在 MATLAB 客户端会话中执行。该函数的声明行必须是：

function state = getJobStateFcn(cluster,job,state)

当使用第三方调度器时，调度器可能会拥有比工具箱从本地作业存储位置可用的更多有关您的作业的最新信息。如果您的集群不与客户端计算机共享文件系统，则这种情况尤其如此，远程文件系统在将大型数据文件传播回本地数据位置时可能会很慢。

要从调度器中检索该信息，请将名为 getJobStateFcn.m 的函数添加到集群的 PluginScriptsLocation 中。

传递到此函数的状态是从本地作业存储派生的状态。然后，此函数的主体可以查询调度器以确定作业的更准确状态，并将其返回以代替存储的状态。为此目的编写的函数必须返回作业对象状态的有效值。允许的值为 ‘pending'、‘queued'、‘running'、‘finished' 或 ‘failed'。

有关将 MATLAB 任务与其对应的调度器作业 ID 配对的说明，请参阅 使用通用调度器管理作业。

cancelJobFcn

当您取消使用通用集群创建的作业时，cancelJobFcn.m 函数将在 MATLAB 客户端会话中执行。该函数的声明行必须是：

function OK = cancelJobFcn(cluster,job)

当您取消使用通用调度器接口创建的作业时，默认情况下此操作只会影响存储中的作业数据。要取消调度器上的相应作业，您必须向调度器提供要做什么以及何时执行的指令。为了实现这一点，请将一个名为 cancelJobFcn.m 的函数添加到集群的 PluginScriptsLocation 中。

然后，该函数主体可以向调度器发送命令，例如，从队列中删除相应的作业。该函数必须返回一个逻辑标量，表明取消调度器上的作业是成功还是失败。

有关将 MATLAB 任务与其对应的调度器作业 ID 配对的说明，请参阅 使用通用调度器管理作业。

cancelTaskFcn

当您取消使用通用集群创建的任务时，cancelTaskFcn.m 函数将在 MATLAB 客户端会话中执行。该函数的声明行必须是：

function OK = cancelTaskFcn(cluster,task)

当您取消使用通用调度器接口创建的任务时，默认情况下，这只会影响存储中的任务数据。要取消调度器上的相应作业，您必须向调度器提供要做什么以及何时执行的指令。为了实现这一点，请将一个名为 cancelTaskFcn.m 的函数添加到集群的 PluginScriptsLocation 中。

然后，该函数的主体可以向调度器发送命令，例如，从调度器队列中删除相应的作业。该函数必须返回一个逻辑标量，表明取消调度器上的作业是成功还是失败。

有关将 MATLAB 任务与其对应的调度器作业 ID 配对的说明，请参阅 使用通用调度器管理作业。

deleteJobFcn

当您删除使用通用集群创建的作业时，deleteJobFcn.m 函数将在 MATLAB 客户端会话中执行。该函数的声明行必须是：

function deleteTaskFcn(cluster,task)

当您删除使用通用调度器接口创建的作业时，默认情况下，这只会影响存储中的作业数据。要删除调度器上的相应作业，您必须向调度器提供要做什么以及何时执行的指令。为了实现这一点，请将一个名为 deleteJobFcn.m 的函数添加到集群的 PluginScriptsLocation 中。

然后，该函数的主体可以向调度器发送命令，例如，从调度器队列中删除相应的作业。

有关将 MATLAB 任务与其对应的调度器作业 ID 配对的说明，请参阅 使用通用调度器管理作业。

deleteTaskFcn

当您删除使用通用集群创建的任务时，deleteTaskFcn.m 函数将在 MATLAB 客户端会话中执行。该函数的声明行必须是：

function deleteTaskFcn(cluster,task)

当您删除使用通用调度器接口创建的任务时，默认情况下，这只会影响存储中的任务数据。要删除调度器上的相应作业，您必须向调度器提供要做什么以及何时执行的指令。为了实现这一点，请将一个名为 deleteTaskFcn.m 的函数添加到集群的 PluginScriptsLocation 中。

然后，该函数的主体可以向调度器发送命令，例如，从调度器队列中删除相应的作业。

有关将 MATLAB 任务与其对应的调度器作业 ID 配对的说明，请参阅 使用通用调度器管理作业。

postConstructFcn

在 MATLAB 中创建集群实例后，postConstructFcn.m 函数将在 MATLAB 客户端会话中执行。例如，以下代码行创建集群的一个实例并运行与 postConstructFcn 集群配置文件关联的 ‘myProfile' 函数：

c = parcluster('myProfile');

postConstructFcn 函数的声明行必须是：

function postConstructFcn(cluster)

如果您需要在使用集群之前对其进行自定义配置，请在集群的 postConstructFcn.m 中添加一个名为 PluginScriptsLocation 的函数。此函数的主体可以包含您需要的任何额外设置步骤。

创建集群配置文件并验证插件脚本

为了验证您的自定义插件脚本是否运行良好以及并行计算产品是否在您的集群上正确安装和配置，您必须使用通用调度器接口在 MATLAB 客户端端上设置集群配置文件。有关详细说明，请参阅创建通用集群配置文件。

从集群配置文件管理器设置其他属性

通过修改以上示例中的脚本，您可以向通用集群配置文件中添加 AdditionalProperties 条目来指定要使用的节点列表。这为与您共享集群配置文件的任何人提供了一种记录添加到插件脚本中的自定义内容的方法。

要将 NodeList 属性添加到您的集群配置文件：

从 MATLAB 命令行设置附加属性

通过修改添加用户自定义中的脚本，您可以在提交作业之前通过设置集群对象的相应属性从 MATLAB 命令行编辑节点列表：

c = parcluster;
c.AdditionalProperties.NodeList = 'gpuNodeName';
j = c.batch('myScript'); 

显示 AdditionalProperties 对象以查看所有当前定义的属性及其值：

>> c.AdditionalProperties
ans = 
  AdditionalProperties with properties:
                 ClusterHost: 'myClusterHost'
                    NodeList: 'gpuNodeName'
    RemoteJobStorageLocation: '/tmp/jobs'

保存作业调度器数据

此示例显示如何修改 independentSubmitFcn.m 函数来解析提交给 SLURM 调度器的每个命令的输出。您可以使用正则表达式提取每个任务的调度器作业 ID，然后将其存储起来。

% Pattern to extract scheduler job ID from SLURM sbatch output
searchPattern = '.*Submitted batch job ([0-9]+).*';
 
jobIDs = cell(numberOfTasks, 1);
for ii = 1:numberOfTasks
    setenv('PARALLEL_SERVER_TASK_LOCATION', environmentProperties.TaskLocations{ii});
    commandToRun = 'sbatch --ntasks=1 independentJobWrapper.sh';
    [cmdFailed, cmdOut] = system(commandToRun);
    jobIDs{ii} = regexp(cmdOut, searchPattern, 'tokens', 'once');
end
 
% set the job IDs on the job cluster data
cluster.setJobClusterData(job, struct('ClusterJobIDs', {jobIDs}));

检索作业调度器数据

此示例修改 cancelJobFcn.m 以取消 SLURM 调度器上的相应作业。该示例使用 getJobClusterData (Parallel Computing Toolbox) 来检索作业调度器数据。

function OK = cancelJobFcn(cluster, job)

% Get the scheduler information for this job
data = cluster.getJobClusterData(job);
jobIDs = data.ClusterJobIDs;

for ii = 1:length(jobIDs)
    % Tell the SLURM scheduler to cancel the job
    commandToRun = sprintf('scancel ''%s''', jobIDs{ii});
    [cmdFailed, cmdOut] = system(commandToRun);
end

OK = true;