Makeflow用户手册 一

Makeflow用户手册

概述

Makeflow是用于大规模分布式计算的工作流引擎。它接受要执行的大量工作的规范，并尽可能在远程计算机上并行运行。此外，Makeflow是容错的，因此您可以使用它来协调非常大的任务，这些任务可能在出现故障时运行数天或数周。Makeflow的设计与Make类似，因此如果可以编写Makefile，那么就可以编写Makeflow。
Makeflow使得将大量工作从一个设施移动到另一个设施变得很容易。在编写了一个工作流之后，您可以在本地笔记本电脑上进行测试，然后在您的大学计算中心运行它，将其转移到类似XSEDE这样的国家级计算设施，然后再转到商业云系统。使用（捆绑的）工作队列系统，您甚至可以同时跨多个系统运行。无论您在何处运行任务，工作流语言都保持不变。
Makeflow在生产中用于支持科学和工程中的大规模问题。生物信息学、生物特征学、地理学和高能物理等领域的研究人员都使用Makeflow从现有应用程序中组合工作流。
Makeflow可以将您的作业发送到各种各样的服务，例如批处理系统（HTCondor、SGE、PBS、Torque）、集群管理器（Mesos和Kubernetes）、云服务（amazonec2或Lambda）和容器环境（如Docker和Singularity）。批处理系统支持部分提供了每个系统的详细信息。

入门

安装

请参阅协作计算工具包的安装说明。然后，确保你的路径设置正确。

基本用途
Makeflow工作流由一组规则组成。每个规则都指定一组要创建的输出文件、一组创建它们所需的输入文件，以及一个从源文件生成目标文件的命令。
Makeflow尝试在工作流中生成所有输出文件。它检查所有规则并确定哪些规则必须在其他规则之前运行。在可能的情况下，它并行运行命令以减少执行时间。
Makeflow假设两种编写工作流的方法：经典Make和JX。经典Make非常容易学习和入门，但在编写大型工作流时可能会非常冗长。JX工作流语言稍微复杂一些，但是允许更可编程的工作流构造。
下面是一个用经典Make语言编写的工作流示例。它使用“转化”工具制作动画。它从网上下载图像，创建图像的四种变体，然后将它们组合成动画。第一个和最后一个任务被标记为本地任务，以强制它们在控制计算机上运行。

CURL=/usr/bin/curl
CONVERT=/usr/bin/convert
URL=“http://ccl.cse.nd.edu/images/capitol.jpg”

capitol.anim.gif: capitol.jpg capitol.90.jpg capitol.180.jpg capitol.270.jpg capitol.360.jpg
LOCAL $(CONVERT) -delay 10 -loop 0 capitol.jpg capitol.90.jpg capitol.180.jpg capitol.270.jpg capitol.360.jpg capitol.270.jpg capitol.180.jpg capitol.90.jpg capitol.anim.gif

capitol.90.jpg: capitol.jpg
$(CONVERT) -swirl 90 capitol.jpg capitol.90.jpg

capitol.180.jpg: capitol.jpg
$(CONVERT) -swirl 180 capitol.jpg capitol.180.jpg

capitol.270.jpg: capitol.jpg
$(CONVERT) -swirl 270 capitol.jpg capitol.270.jpg

capitol.360.jpg: capitol.jpg
$(CONVERT) -swirl 360 capitol.jpg capitol.360.jpg

capitol.jpg:
LOCAL $(CURL) -o capitol.jpg $(URL)

（请注意，Makeflow与Make有一些细微的不同，您可以在下面的语言参考中了解这些细节。）
要尝试上面的示例，请将其复制并粘贴到名为示例.makeflow. 要在本地计算机上运行它：
$ makeflow example.makeflow

请注意，如果您再次运行它，您将收到以下消息：
makeflow: nothing left to do
因为所有的文件都已经生成了。
在重试之前，请使用–clean选项清除所有内容：
$ makeflow --clean example.makeflow

如果您可以访问像Condor、SGE或Torque这样的批处理系统，或者访问像Amazon这样的云服务提供商，那么您可以使用-T选项来指示Makeflow在那里运行您的作业：
$ makeflow -T condor example.makeflow

$ makeflow -T sge example.makeflow

$ makeflow -T torque example.makeflow

$ makeflow -T amazon example.makeflow

要了解有关各种批处理系统选项的更多信息，请参阅批处理系统支持部分。

Warning
You may have to slightly adapt the makeflow workflow file to work across different batch systems. This is because different batch systems have different expectations on whether the underlying filesystem is shared (e.g., slurm and torque), or not (e.g., condor and work queue).

JX Language

经典的make语言易于学习，适合多种用途，但对于复杂的工作流，它可能会变得相当冗长。Makeflow还支持JX工作流语言，以更可编程的方式表达工作流。为了让您了解一下，下面是如何使用JX快速生成1000个模拟作业：
{
“rules”: [
{
“command”: “./simulate.py -n “+N+” > output.”+N+".txt",
“inputs”: [ “simulate.py” ], “outputs”: [ “output.”+N+".txt" ],
} for N in range(1,1000)
]
}

只需对任何调用使用–JX参数，就可以在Makeflow中使用JX语言。例如：makeflow --jx example.jx -T condor
在这里了解更多关于JX的信息。

资源

大多数批处理系统需要关于每个作业需要什么资源的信息，以便适当地安排它们。您可以通过在每个作业之前设置变量CORES、MEMORY（以MB为单位）和DISK（以MB为单位）来传达这一点。Makeflow将根据需要将这些信息转换到底层批处理系统。例如：

CORES=4
MEMORY=1024
DISK=4000

output.txt: input.dat
analyze input.dat > output.txt

监测

有多种工具可帮助您在工作流运行时监视其进度。Makeflow本身创建一个事务日志(example.makeflow.makeflowlog)它包含每个任务运行时的详细信息，跟踪有多少任务空闲、正在运行、已完成等等。这些工具可以读取事务日志并汇总工作流：

makeflow_monitor读取事务日志并生成连续显示，显示整个工作流的总时间和进度：
$ makeflow example.makeflow
$ makeflow_monitor example.makeflow.makeflowlog

makeflow_graph_log将读取事务日志，并生成一个时间轴图，显示一段时间内准备、运行和完成的作业数：
$ makeflow example.makeflow
$ makeflow_graph_log example.makeflow.makeflowlog example.png

makeflow_-viz将以图形形式显示工作流，这样您可以更容易地理解结构和依赖关系。阅读有关可视化的更多信息。
此外，如果使用-N选项为工作流指定一个“项目名称”，它将每分钟向目录服务器报告一次其状态。makeflow_status命令将查询目录并汇总当前运行的工作负载，如下所示：
OWNER PROJECT JOBS WAIT RUN COMP ABRT FAIL TYPE
alfred simulation 2263 2258 1 4 0 0 condor
betty analysis 2260 1 1 2258 0 0 wq

一般建议

一些关键的建议可以解决使用Makeflow时遇到的最常见问题：
首先，当Makeflow拥有关于您希望运行的每个任务的准确信息时，它的工作效果最好。请确保您小心地指出每个任务需要哪些输入文件，以及它生成哪些输出文件。
其次，如果Makeflow正在执行意外的操作，您可能会发现使用-dall选项打开调试流很有用。这将发出关于每个作业是如何构造并发送到底层批处理系统的各种详细信息。
调试失败的任务时，检查生成的任何输出通常很有用。Makeflow自动将这些文件保存在makeflow.failed每个失败规则的.$ruleno目录。只保存规则的指定输出。如果规则被重试，以后成功，失败的输出将被自动删除。
最后，Makeflow是由圣母大学的合作计算实验室创建的。我们很乐意了解更多关于Makeflow是如何使用的，如果您有任何问题或困难，我们会为您提供帮助。
有关Makeflow的最新信息，请访问我们的网站并订阅我们的邮件列表以获取更多信息。

批处理系统支持

Makeflow支持多种批处理系统。使用makeflow–help查看当前支持的列表。一般来说，只需使用-T选项运行Makeflow来选择所需的批处理系统。如果没有给出任何选项，则假定为-T local。
Warning
As mentioned before, different batch systems have different expectations on whether the underlying filesystem is shared. For example, one workflow may work with -Tslurm, but may fail with -Tcondor, etc. The most portable workflows read and write files from the working directory of each rule. If a rule depends on the creation of a directory, make this creation explicit, as the directory may not be present for the intermidate results on the site where the rule executes.

如果需要向批处理系统传递其他参数，例如指定特定队列或计算机类别，请使用-B选项生成流，或在Makeflow文件中设置batch_OPTIONS变量。如下文所述，对这些选项的解释因每个系统而异。
为了避免用大量空闲作业压倒批处理系统，Makeflow将限制一次发送到系统的作业数。可以在命令行上使用–max remote选项或MAKEFLOW_max_remote_JOBS环境变量来控制此操作。同样，本地执行可以通过–max local和MAKEFLOW_max_local_JOBS来限制。

本地执行

默认情况下，Makeflow在本地计算机上执行。它将测量本地计算机上可用的内核、内存和磁盘，然后运行尽可能多的作业，以满足这些资源的需要。（当然，您必须用内核、内存和磁盘适当地标记作业。您可以对用于Makeflow的–localcore、-localmemory和–local disk选项一起使用的资源设置上限。此外，本地运行的作业总数可以限制为–max local。

HTCondor

如果直接从命令行运行Makeflow，只需使用-T condor选项将作业提交到HTCondor批处理系统。
如果您有一个长期运行的工作流，我们建议您使用condor_submit_makeflow，如下所示：

$ condor_submit_makeflow example.mf

Submitting example.mf as a background job to HTCondor…
Submitting job(s). 1 job(s) submitted to cluster 364.
Makeflow Output : makeflow.364.output
Makeflow Error : makeflow.364.error
Condor Log : makeflow.364.condorlog

这将导致Makeflow本身作为批处理作业提交，以便HTCondor可以监视它，允许您注销并稍后返回以检查工作流的状态。您将看到Makeflow和它在HTCondor队列中运行的作业：
ID OWNER SUBMITTED RUN_TIME ST PRI SIZE CMD
10.0 dthain 7/17 13:03 0+00:00:05 R 0 1.7 makeflow -T condor
11.0 dthain 7/17 13:03 0+00:00:00 I 0 0.0 condor.sh myjob -p 1
…

Makeflow将为每个作业自动生成一个提交文件，因此您不需要编写一个提交文件。但是，如果要自定义Condor submit文件，请使用-B选项或BATCH_OPTIONS变量指定要添加到提交文件中的文本。
例如，如果要向Condor submit文件添加要求和排名行，请将以下内容添加到Makeflow中：
BATCH_OPTIONS=“Requirements = (Memory>1024)”

UGE - Univa Grid Engine / OGE - Open Grid Engine / SGE - Sun Grid Engine

Use the -T sge option to submit jobs to Sun Grid Engine or systems derived from it like Open Grid Scheduler or Univa Grid Engine.
如上所述，Makeflow将自动生成qsub命令。使用-B选项或BATCH_OPTIONS变量指定要添加到命令行的文本。例如，要指定作业应提交到devel队列，请执行以下操作：
BATCH_OPTIONS="-q devel"

便携式批处理系统

使用-T pbs选项将作业提交到便携式批处理系统或兼容系统。
这将添加核心、内存和磁盘的值。这些值将以以下格式添加到qsub中：
-l nodes=1:ppn=$CORES,mem=${MEMORY}mb,file=${DISK}mb`

要在提交时删除资源规范，请使用Makeflow选项–safe submit mode。

Torque Batch System
使用-T torque选项将作业提交到torque资源管理器批处理系统。
这将定义核心、内存、磁盘和墙时间的任何值。这些值将以以下格式添加到qsub中：
-l nodes=1:ppn=$CORES,mem=${MEMORY}mb,file=${DISK}mb

若要在提交时删除资源规范，请使用Makeflow选项–safe submit mode。