Canine

一个模块化、高性能的计算解决方案，用于运行使用SLURM的工作

用法

Canine通过在SLURM集群上运行作业来运行。它设计用于使用Firecloud工作区中的数据或手动提供的输入来调度bash或WDL脚本。API用法在本节底部文档化。

Canine可以以下任何方式使用

• 运行pipeline yaml文件（例如：$ canine examples/example_pipeline.yaml）
• 在命令行中运行定义的pipeline（例如：$ canine --backend type:TransientGCP --backend name:my-cluster (等等...)）
• 在Python中构建和运行pipeline（例如：>>> canine.Orchestrator(pipeline_dict).run_pipeline()）
• 使用Canine API在Slurm中执行无法配置为pipeline对象的自定义工作流

pipeline的结构

Canine可以原生配置以适应各种设置。Canine被模块化为三个主要组件，可以根据需要混合匹配：适配器、后端和本地化器。pipeline指定要使用哪些适配器、后端和本地化器，以及每个的任何配置选项。

适配器

pipeline适配器负责将提供的输入列表转换为每个作业的输入规范。

选择适配器

这是一个可用适配器的列表。有关更多详细信息，请参阅pipeline_options.md

• 手动：（默认）这是主要的输入适配器，负责根据用户提供的原始输入确定作业数量和每个作业的输入。
  • 具有单个常量值的输入将在所有作业中具有相同的值。
  • 具有1维值列表的输入将在每个作业中具有这些值之一。默认情况下，所有列表输入必须具有相同的长度，并且将有一个作业对应每个元素。第n个作业将具有每个输入的第n个值。
  • 有一些额外的配置选项可以改变输入的组合方式或列表的解析方式。
• Firecloud/Terra：如果您正在使用FireCloud或Terra工作区中的数据，请选择此适配器。您的输入将被解释为实体表达式，类似于FireCloud和Terra工作流程解释输入的方式。您还可以配置此适配器将结果发布回您的工作区。警告：从工作区存储桶读取很方便，但如果您的Slurm集群未使用您的凭据登录，您可能会遇到问题。

后端

管道后端负责与Slurm控制器接口。根据SLURM的运行位置（或为您创建Slurm集群）有多种不同的后端可供选择。

选择后端

这是一个可用后端的列表。有关更多详细信息，请参阅pipeline_options.md

• Local：（默认）如果您将从Slurm控制器运行Canine并且您的集群已完全配置，请选择此后端。此后端将通过本地shell运行Slurm命令。
• Remote：如果您有一个完全配置的SLURM集群，但将在其他地方运行Canine，请选择此后端。此后端使用SSH和SFTP与Slurm控制器交互。
• GCPTransient：如果您没有Slurm集群，请选择此后端。此后端将在Google Cloud中根据您的规格创建集群，然后使用SSH和SFTP与控制器交互。Canine完成后，集群将被删除。
• ImageTransient：如果您没有Slurm集群，但想要比GCPTransient更多的控制，请选择此后端。此后端假定当前系统已安装Slurm并已设置NFS挂载。然后它使用您已设置和配置的Google Compute Image创建工作节点。
• DockerTransient：如果您想要与ImageTransient相同的控制，但不需要设置Google Compute Image，请选择此后端。Slurm守护进程在工作节点上的docker容器中运行。Slurm控制器守护进程在本地文件系统上的docker容器中运行。
• Dummy：选择此后端进行管道的开发或测试。此后端通过在本地系统上作为docker容器运行控制器和工作者来模拟Slurm集群。此后端不配置任何云资源。它完全通过本地docker守护进程运行。

本地化器

管道本地化器负责在SLURM控制器上安装管道，并在需要时传输输入/输出。有四种不同的本地化器来满足不同的需求。

选择本地化器

这是一个可用本地化器的列表。有关更多详细信息，请参阅pipeline_options.md

• Batched：（默认）此本地化器适用于大多数情况。它将Canine管道工作区在本地临时目录中，在广播工作区目录结构到Slurm控制器之前，将本地文件复制或符号链接到其中。存储在Google Cloud Storage中的文件将在最后下载到Slurm控制器（使用控制器上存储的凭据）。
• 本地化：如果您有存储在Google Cloud Storage中需要本地化的文件，但无法将合适的凭证保存到Slurm控制器，请选择此本地化器。这与批量本地化器非常相似，区别在于Google Cloud Storage文件在本地进行阶段化，并与管道中的其他文件一起广播到Slurm控制器。
• 远程：对于包含少量本地文件的短管道，请选择此本地化器。此本地化器使用SFTP直接在Slurm控制器上对管道目录进行阶段化。它通常不如批量和本地本地化器使用的批量目录复制效率高（特别是如果您为它们提供了transfer_bucket），但对于完全由Google Cloud Storage中的文件组成的短管道，可能优于其他本地化器。
• NFS：如果当前系统已有一个到Slurm控制器的活跃NFS挂载，请选择此后端。Canine管道将在NFS挂载点内的本地进行阶段化，允许NFS处理将管道目录传输到控制器。

示例

在examples/目录中有一些可以直接运行的示例。要运行这些管道之一，请遵循以下任何说明：

命令行

$ canine examples/example_pipeline.yaml

Python（使用文件路径）

import canine
orchestrator = canine.Orchestrator('examples/example_pipeline.yaml')
results = orchestrator.run_pipeline()

Python（使用字典）

import canine
import yaml

with open('examples/example_pipeline.yaml') as r:
  config = yaml.load(r)

orchestrator = canine.Orchestrator(config)
results = orchestrator.run_pipeline()

其他管道组件

希望您已经运行了一两个示例，并对管道的结构有了更好的理解。本节将描述管道配置的其他部分，这些部分尚未涉及

输入

输入描述了作业的数量以及每个作业的输入。管道的inputs部分应该是一个字典。每个键是一个字符串，将输入名称映射到字符串或字符串列表。如上所述，适配器负责将用户提供的原始输入解析为每个将运行的作业的输入集。

• 适配器将二维或多维的原始输入列表解释为用户希望为每个作业提供嵌套列表之一。数组被展平到二维，并解释为常规列表输入（每个作业传递一个元素）。这些数组的内容使用上述本地化规则处理
• 在覆盖中标记为common的任何维度的原始输入列表被展平到一维，整个列表作为每个作业的输入提供。数组的内容作为common文件处理（见下文）

脚本

管道脚本是管道的核心。这是将要运行的实际bash脚本。script键可以是运行bash脚本的文件路径，或者是一个字符串列表，其中每个字符串都是一个要运行的命令。无论哪种方式，脚本都将由管道的每个作业执行。

覆盖

在localization.overrides中定义的本地化覆盖允许用户更改本地化器对特定输入的默认处理。覆盖部分应是一个将输入名称映射到描述所需处理的字符串的字典，如下所示：

• 默认规则（无覆盖）
  • 作为本地文件路径存在的字符串被视为文件，并将本地化到Slurm控制器。
  • 以gs://开头的字符串被解释为Google Cloud Storage中的文件/目录，并将本地化到Slurm控制器。
  • 任何作为多个作业输入的文件或Google Storage对象都视为common，并将一次性本地化到公共目录，对所有作业可见。
  • 如果任何作业的任何任意输入是一个列表，则使用相同的规则解释列表的内容
• 通用：标记为通用的输入将被视为所有作业的通用，并一次性本地化到所有作业都可见的目录中。标记为通用且无法解释为文件路径或Google Cloud Storage对象的输入将被忽略，并作为字符串处理。
• 流：标记为流的输入将被流式传输到一个FIFO管道中，管道的路径将被导出到作业中。对于不是Google Cloud Storage对象的输入，流覆盖被忽略，这些输入将按照默认规则本地化。由于节点故障而重新排队的作业将始终重新启动流。
• 延迟：标记为延迟的输入将在作业启动时下载，而不是在本地化时立即下载。对于不是Google Cloud Storage对象的输入，延迟覆盖被忽略，这些输入将按照默认规则本地化。由于节点故障而重新排队的作业只有在作业在下载完成之前失败时才会重新下载延迟输入。
• 本地化：标记为本地化的输入将被视为文件，并本地化到特定作业的输入目录中。这可以用来强制将作为通用处理的文件为每个作业本地化。对于不是有效文件路径或Google Cloud Storage对象的输入，本地化覆盖被忽略，这些输入将被作为字符串处理。
• 空或无：以这种方式标记的输入被视为字符串，不会应用任何本地化。

输出

输出部分定义了输出名称到应抓取的文件模式的映射。文件模式可以是原始文件名或通配符，可以包括shell变量（包括作业输入）。这些模式始终相对于每个作业的初始工作目录（$CANINE_JOB_ROOT）。模式可能匹配工作空间目录之上的文件，但这不建议。默认情况下，stdout和stderr包含在输出中，这将抓取作业的stdout/err流。您可以通过提供自己的stdout或stderr模式来覆盖此行为。警告：输出stdout和stderr有特殊处理，期望它们的模式精确匹配一个文件。如果您为stdout或stderr提供了自定义模式且匹配多个文件，则输出数据框将只显示匹配的第一个文件名。

所有与提供的输出模式匹配的文件都将从Slurm控制器解本地化到当前系统的以下目录结构中

output_dir/
  {job id}/
    stdout
    stderr
    {other output names}/
      {matched files/directories}

资源

资源部分允许您定义要传递给sbatch的额外参数，以控制资源分配或其他调度参数。资源字典被转换为如下命令行参数

• 单字母键被转换为短选项（-x）。
• 多字母键被转换为长选项（--xx）。
• 值为True的键被转换为标志（无值）
• 具有任何其他值的键被转换为参数（--key=val）
• 键中的下划线被转换为连字符（foo_bar变为--foo-bar）