17.1.2. mpirun / mpiexec

mpirun, mpiexec — 在Open MPI中执行串行和并行作业。

注意

mpirun 和 mpiexec 是彼此的同义词。 实际上，它们是指向同一个可执行文件的符号链接。 使用其中任何一个名称都会产生完全相同的行为。

17.1.2.1. 概述

单进程多数据(SPMD)模型：

mpirun [ options ] <program> [ <args> ]

多指令多数据 (MIMD) 模型：

mpirun [ global_options ]
       [ local_options1 ] <program1> [ <args1> ] :
       [ local_options2 ] <program2> [ <args2> ] :
       ... :
       [ local_optionsN ] <programN> [ <argsN> ]

请注意，在这两种模型中，通过绝对路径名调用mpirun等同于指定--prefix选项，其

值等于mpirun所在目录（减去最后一个子目录）。例如：

shell$ /usr/local/bin/mpirun ...

等同于

shell$ mpirun --prefix /usr/local

17.1.2.2. 快速概览

如果您只是想了解如何运行MPI应用程序，您可能需要使用以下形式的命令行：

shell$ mpirun [ -n X ] [ --hostfile <filename> ]  <program>

这将在您当前的运行时环境中运行X份程序（如果在支持的资源管理器下运行，Open MPI的mpirun通常会自动使用对应的资源管理器进程启动器，而不是像ssh那样需要借助主机文件，或者默认在本地主机上运行所有X份副本），默认情况下会按CPU槽位以轮询方式进行调度。更多详情请参阅本文档其余部分。

请注意，mpirun会自动将进程绑定到硬件资源。在没有任何进一步指令的情况下，会使用三种绑定模式（详见map/rank/bind defaults）：

• 绑定到核心: 当进程数小于等于2时

• 绑定到包: 当进程数量大于2时

• 不绑定任何核心: 当资源超额订阅时

如果你的应用程序使用多线程，那么你可能需要确保要么完全不进行绑定（通过指定--bind-to none），要么使用适当的绑定级别或每个应用进程特定的处理元素数量绑定到多个核心。

17.1.2.3. OPEN MPI对PRRTE的使用

Open MPI 使用 PMIx 参考运行时环境 (PRRTE) 作为启动、监控和终止 MPI 进程的核心引擎。

以下大部分文档内容直接引自PRRTE。因此，文中频繁提及PRRTE相关概念与命令行选项。除非特别说明，这些概念和命令行参数同样适用于Open MPI。Open MPI在PRRTE原有命令行选项基础上进行了扩展，并在某些情况下对PRRTE的默认行为做了细微调整。这些差异将在下文中具体说明。

17.1.2.4. 命令行选项

Open MPI的mpirun处理核心是通过PRRTE实现的。具体来说：mpirun本质上是prterun的封装器，但mpirun的命令行选项与PRRTE的命令行指令略有不同。

17.1.2.4.1. 通用命令行选项

以下是可用的通用命令行选项。

• -h | --help: 显示帮助信息

• -v | --verbose: 启用额外详细输出

• -V | --version: 打印版本信息并退出

17.1.2.4.2. 启动选项

• --default-hostfile : 提供一个默认的主机文件。

• -H | --host : 逗号分隔的主机列表，用于在这些主机上启动进程。 See below for details。

• --hostfile : 提供一个主机文件。 详情见下文。

• --machinefile : --hostfile的同义词。

• --mca : 传递特定上下文的MCA参数；如果未使用--gmca且仅指定了一个上下文，则这些参数被视为全局参数（是参数名称；是参数值）。

• --path : 用于查找可执行文件以启动进程的路径。

• --pmixmca : 传递上下文特定的PMIx MCA参数；如果只指定了一个上下文，这些参数将被视为全局参数（>是参数名称；是参数值）。 See below for details。

• --preload-files : 在启动远程进程之前，将逗号分隔的文件列表预加载到远程机器的当前工作目录中。

• --prtemca : 向DVM传递特定上下文的PRTE MCA参数。 See below for details。

• --pset : 为用户指定应用程序中进程的名称。

• --rankfile : 指定显式任务映射的文件名。

• --runtime-options : 传递给启动器的选项列表。 See below for details。

• -s | --preload-binary: 在启动远程进程前，先在远程机器上预加载二进制文件。

• --set-cwd-to-session-dir: 将启动进程的工作目录设置为其会话目录。

• --show-progress: 输出关于启动进度的简短定期报告。

• --wd

  : --wdir的同义词。

• --wdir

  : 设置启动进程的工作目录。

• -x : 导出环境变量，可选择指定其值。 See below for details。

• --unset-env : 取消设置环境变量。 See below for details。

• --prepend-env : 将值前置添加到环境变量中 See below for details。

• --append-env : 将值添加到环境变量的开头 See below for details。

• --gpu-support : 直接控制是否启用(true)或禁用(false)其内部库的GPU支持功能

• --app-pmix-prefix : 应用程序在远程节点上查找其PMIx安装时使用的前缀。

• --no-app-prefix: 不为此应用程序提供前缀指令。

17.1.2.4.3. 映射、排名与绑定选项

• --map-by : 控制进程在主机内的分布方式。详见下文。

• --rank-by : 控制进程在MPI_COMM_WORLD中的排序方式。See below for details。

• --bind-to : 控制进程在主机内的资源绑定。详见下文。

17.1.2.4.4. 输出选项

• --output : 控制输出生成方式的逗号分隔选项列表。详见下文。

• --report-child-jobs-separately: 仅返回主作业的退出状态。

• --stream-buffering : 控制输出缓冲方式。 详见下文。

• --xterm : 创建一个新的xterm窗口并在其中显示指定进程等级的输出。

17.1.2.4.5. 输入选项

• --stdin : 指定接收标准输入的进程；中允许的值为：逗号分隔的整数排名列表、all、none。默认为0，表示排名0。

17.1.2.4.6. 特定选项

• --allow-run-as-root: 允许以root用户身份执行(强烈不建议)。详情请见下文。

• --daemonize: 将DVM守护进程转为后台运行。

• --forward-signals : 以逗号分隔的额外信号列表（名称或整数值），这些信号将被转发到应用程序进程。 See below for details。

• --launch-agent : 用于在远程节点上启动进程的守护进程可执行文件名称（默认：prted）。

• --max-vm-size : 要启动的守护进程数量。

• --noprefix: 禁用自动--prefix行为。 See below for details。

• --prefix : 用于查找RTE可执行文件的前缀。

• --pmix-prefix : PRRTE可执行文件在远程节点上查找其PMIx安装时使用的前缀。

• --set-sid: 指示DVM守护进程从当前会话中分离。

• --singleton : 启动我们的单例进程的ID。

• --tmpdir

  : 设置会话目录树的根路径。

• --tune : 包含用于调优DVM操作的MCA参数的文件。 See below for details.

• --hetero-nodes: 分配的节点应被视为具有不同的拓扑结构

17.1.2.4.7. MPI选项

• --initial-errhandler: 指定在首次MPI调用期间附加到预定义通信器的初始错误处理程序。

• --memory-alloc-kinds: 值为逗号分隔的

  内存分配类型列表。

• --display-comm: 在MPI_Init期间显示MPI_COMM_WORLD各进程间通信方法的表格

• --display-comm-finalize: 在MPI_Finalize期间显示各进程间通信方法的表格

• --soft: 此选项无实际作用，但根据MPI标准要求保留

• --arch : 此选项无实际功能，但根据MPI标准必须保留

• --file : 此选项无实际功能，但MPI标准要求保留

17.1.2.4.8. 调试器/工具选项

• --keepalive : 监控指定的命名管道文件名 —— 当管道关闭时DVM将终止

• --report-pid : 在标准输出(-)、标准错误(+)或文件名(其他值)上打印PID

• --report-uri : 在标准输出(-)、标准错误(+)或文件名(其他值)上打印URI

• --stop-on-exec : 如果支持，在每个指定进程开始执行时停止

• --stop-in-init : 指示指定进程在MPI初始化函数中停止

• --stop-in-app : 指示指定进程在应用程序控制的位置停止

17.1.2.4.9. 调试选项

• --debug-daemons: 调试守护进程 — 如果未设置，"verbose"（详细）模式将仅限于DVM控制器以减少杂乱信息。See below for details。

• --debug-daemons-file: 启用对此应用程序使用的任何PRTE守护进程的调试功能，将其详细输出存储到文件中。详情请见下文。

• --display : 用于显示分配和作业信息的逗号分隔选项列表。允许的取值包括：allocation, bind, map, map-devel, topo。 详情请见下文。

• --get-stack-traces: 如果发生超时，获取所有应用程序进程的堆栈跟踪。

• --leave-session-attached: 不丢弃远程PRTE守护进程的标准输出/标准错误。 See below for details。

• --report-state-on-timeout: 超时时报告所有作业和进程状态。

• --spawn-timeout : 如果生成过程超过指定的秒数，则任务超时。

• --test-suicide : 在延迟后执行自杀式终止而非正常中止。

• --timeout : 在指定的秒数后使作业超时。

• --output-proctable : 在启动后将完整的进程表打印到标准输出；允许的值为+、-或文件名。

17.1.2.4.10. 容错选项

这些选项仅在Open MPI / PRRTE编译时启用了容错功能的情况下可用。

• --enable-recovery: 启用进程故障恢复功能（默认 = 禁用）

• --max-restarts: 失败进程的最大重启次数

• --disable-recovery: 禁用恢复功能（将所有恢复选项重置为关闭状态）

• --continuous: 作业将持续运行，直到被显式终止

• --with-ft: 指定应用程序将使用的错误处理类型。

17.1.2.4.11. 单个命令行选项的详细说明

以下章节提供了比上方缩略列表更详细的内容。

17.1.2.4.11.1. --allow-run-as-root 选项

允许以root身份执行(强烈不建议)。

以root身份运行会使用户面临潜在灾难性的文件系统损坏和破坏风险——例如，如果用户误将会话目录的根路径指向系统关键位置，该目录及其所有子内容将在作业完成后被删除，从而导致系统无法运行。

我们认识到某些环境（例如容器）可能需要以root身份运行，并且用户在这些场景下接受相关风险。因此，可以通过提供以下选项之一来覆盖PRRTE的以root身份运行保护机制：

• 命令行指令 --allow-run-as-root

• 添加以下两个环境参数：

  • PRTE_ALLOW_RUN_AS_ROOT=1

  • PRTE_ALLOW_RUN_AS_ROOT_CONFIRM=1

再次强调，我们建议仅在绝对必要时才进行此操作。

17.1.2.4.11.2. --bind-to 选项

默认情况下，进程会被绑定到独立的CPU（可能是核心或硬件线程，具体取决于作业的默认设置或用户指定）。在资源超额分配（即进程数超过分配的槽位数）的节点上，默认行为是不绑定进程。

注意

当新的作业映射导致节点资源超额分配时，先前已在节点上运行的作业进程不会被"解除绑定"。

绑定操作会在进程映射的对象内，针对第一个可用的指定对象类型执行。换句话说，绑定只能作用于已映射的对象或位于该对象下方的资源。

当一个对象上绑定的进程数等于其内部的CPU数量时，该对象被视为完全消耗。未绑定的进程不参与此计算。除非通过--bind-to命令行选项提供OVERLOAD限定符，否则无法将额外进程映射到已消耗的对象上。

请注意，指令和限定符不区分大小写，并且可以缩短为能唯一标识它们的最小字符数。因此，L1CACHE可以写成l1cache或简写为L1。

支持的绑定指令包括：

• NONE 不绑定进程

• HWTHREAD 将每个进程绑定到单个硬件线程/这要求将硬件线程视为独立的CPU（即需要为map-by选项提供HWTCPUS限定符，或者默认情况下将hwthreads指定为CPU）。

• CORE 将每个进程绑定到单个核心。无论将hwthreads还是cores视为独立CPU，只要在核心或更高级别执行映射，都可以实现此操作。

• L1CACHE 将每个进程绑定到L1缓存中的所有CPU核心。

• L2CACHE 将每个进程绑定到L2缓存中的所有CPU

• L3CACHE 将每个进程绑定到 L3 缓存中的所有 CPU

• NUMA 将每个进程绑定到 NUMA 区域内的所有 CPU

• PACKAGE 将每个进程绑定到 PACKAGE 中的所有CPU

任何指令都可以通过添加冒号(:)和一个或多个以下限定符组合到--bind-to选项中来包含限定条件：

• OVERLOAD 表示对象可以绑定比其内部CPU数量更多的进程

• IF-SUPPORTED 表示即使无法按请求执行绑定操作，作业也应继续启动并执行。

注意

指令和限定符不区分大小写。 OVERLOAD 等同于 overload。

17.1.2.4.11.3. --debug-daemons 选项

已启用调试守护进程输出。这通常是一个有限的信息流，仅用于确认守护进程已启动。包括保持输出流处于打开状态。

17.1.2.4.11.4. --debug-daemons-file 选项

已启用调试守护进程输出，所有来自守护进程的输出均被重定向至以下格式命名的文件中：

output-prted-<daemon-nspace>-<nodename>.log

这些名称避免了在共享文件系统上的冲突。文件位于分配给DVM的顶级会话目录中。

17.1.2.4.11.5. --display选项

display 命令行指令必须附带一个以逗号分隔、不区分大小写的选项列表，用于指定要显示的作业和/或分配信息。无需提供完整的指令名称——只需输入足够唯一标识该指令的字符即可。例如，ALL 足以表示 ALLOCATION 指令，而 MAP 不能用来表示 MAP-DEVEL（不过 MAP-D 可以满足要求）。

支持的取值包括：

• ALLOCATION 显示此作业检测到的主机和槽位分配情况

• BINDINGS 显示应用于本作业中进程的最终绑定结果

• MAP 显示此作业中分配给进程的结果位置

• MAP-DEVEL 显示关于此作业中分配给进程的位置的更详细报告，包括本地和节点等级、分配的绑定以及其他数据

• TOPO=LIST 显示分配给作业的以分号分隔的列表中每个节点的拓扑结构

• CPUS[=LIST] 显示指定分号分隔节点列表上的可用CPU（默认为所有节点）

显示命令行指令可以通过添加冒号(:)来包含限定符，后接以下一个或多个组合(用冒号分隔)：

• PARSEABLE 指示输出应采用易于机器解析的格式。请注意，PARSABLE 作为该限定符的常见拼写形式同样被接受。

提供的限定符将应用于所有显示指令。

17.1.2.4.11.6. --forward-signals 选项

以逗号分隔的额外信号列表（名称或整数值），这些信号将被转发到应用程序进程（none表示不转发任何信号）。默认提供的信号包括SIGTSTP、SIGUSR1、SIGUSR2、SIGABRT、SIGALRM和SIGCONT。

17.1.2.4.11.7. --host选项

主机语法由逗号分隔的节点名称列表组成，每个条目可选择包含一个:N扩展，用于指定分配给该条目的插槽数量：

--host node01:5,node02

在没有插槽扩展的情况下，将为节点分配一个插槽。重复的条目会被汇总，并且分配给该节点的插槽数量会相加。

注意

“slot”是PRRTE术语，指可分配的计算单元，用于启动进程。因此，slot数量等同于PRRTE在不超额订阅的情况下可在该节点上启动的最大进程数。

17.1.2.4.11.8. --hostfile 选项

PRRTE支持基于既定优先级顺序的多层次用户指定主机列表。用户可以指定一个默认主机文件，其中包含供DVM使用的节点列表。每个DVM只能提供一个默认主机文件。此外，用户还可以为DVM指定包含节点列表的主机文件，或通过--host命令行选项提供以逗号分隔的节点列表供该DVM使用。

这些不同选项的优先级顺序在一定程度上取决于本地环境。下表展示了在没有资源管理器(RM)的情况下，主机和主机文件指令如何共同定义DVM执行的主机集合：

默认主机文件	主机	主机文件	结果
未设置	未设置	未设置	DVN将仅包含 启动DVM的 本地主机。
未设置	已设置	未设置	主机选项定义了DVM的资源列表。
unset	unset	set	Hostfile选项定义了DVM的资源列表。
未设置	已设置	已设置	Hostfile选项定义了DVM的资源列表， 然后主机筛选该列表以定义最终 将被DVM使用的节点集合
set	unset	unset	默认主机文件定义了DVM的资源列表
set	set	unset	默认主机文件定义了DVM的资源列表， 然后主机过滤器会筛选该列表以确定 DVM最终使用的节点集合
set	set	set	默认主机文件定义了DVM的资源列表， 然后主机文件过滤该列表，接着主机过滤 该列表以定义最终将被DVM使用的 节点集合

在有资源管理器(RM)的情况下，这会有所变化，因为该实体指定了节点的初始分配。在这种情况下，默认主机文件、主机文件和主机指令都用于过滤资源管理器的规范，以便用户可以为不同的分布式虚拟机管理器(DVMs)利用分配的不同部分。这是按照与先前表格相同的优先级顺序完成的，资源管理器提供节点的初始池。

主机文件（有时称为“机器文件”）是以下两部分的组合：

1. 列出要启动进程的主机列表。

2. 可选地，限制每个主机上可以启动的进程数量。

主机文件语法规定每行包含一个节点名称，可选择性地指定“槽位”数量：

# This is a comment line, and will be ignored
node01  slots=10
node13  slots=5

node15
node16
node17  slots=3
...

空行和以#开头的行将被忽略。

“slot”是PRRTE术语，指可分配的计算单元，用于启动进程。有关slot的详细定义，请参阅slot术语说明章节。

如果未指定slot参数，PRRTE将根据节点检测到的CPU数量自动分配槽位数量；若在资源管理器环境下运行，则采用资源管理器分配的值。

重要

如果使用资源管理器，用户指定的槽位数将受限于资源管理器分配的值。

17.1.2.4.11.9. --leave-session-attached 选项

不要丢弃远程PRRTE守护进程的标准输出/标准错误流。此选项的主要用途是确保守护进程的输出流（即标准输出和标准错误）在启动后保持开放，从而让用户能够查看任何由守护进程生成的错误信息。否则，守护进程在启动时会自行"守护化"，从而关闭其输出流。

17.1.2.4.11.10. --map-by 选项

进程映射基于以下在作业级别应用的指令之一：

• SLOT 在分配过程中，会先将处理器分配给每个节点，直到达到该节点可用槽位的数量，然后再继续分配给分配列表中的下一个节点

• HWTHREAD 以轮询方式将处理器分配给节点上的每个硬件线程，直到该节点上的可用槽位用完，然后继续分配下一个节点

• CORE (默认) 以轮询方式为节点上的每个核心分配一个进程，直到该节点上的可用槽位用完，然后才会分配到下一个节点

• L1CACHE 以轮询方式将进程分配给节点上的每个L1缓存，直到该节点上的可用槽位用完，然后继续分配下一个节点

• L2CACHE 以轮询方式将进程分配给节点上的每个L2缓存，直到该节点上的可用槽位用完，然后继续分配下一个节点

• L3CACHE 以轮询方式将进程分配到节点上的每个L3缓存，直到该节点上的可用槽位用完，然后才会分配到分配中的下一个节点

• NUMA 以轮询方式为节点上的每个NUMA区域分配一个进程，直到该节点上的可用槽位用完，然后才会分配到分配中的下一个节点

• PACKAGE 以轮询方式为节点上的每个处理器包分配一个进程，直到该节点上的可用槽位用完，然后才会分配到下一个节点

• NODE 以轮询方式将进程分配给分配中的所有节点，每个节点分配的进程数不超过该节点上可用的槽位数

• SEQ（通常附带file=<路径>限定符）会为文件中指定的每个节点分配一个进程。该顺序文件应包含每个所需进程的条目，每行一个进程。

• PPR:N: 资源映射将N个进程分配到分配中指定资源类型的每个实例

• RANKFILE（通常配合file=<路径>限定符使用）会根据文件中每行的条目，将每个进程分配到指定的节点/资源上，文件每行对应一个进程。

• PE-LIST=a,b 根据ORDERED限定符将进程分配到分配中的每个节点。该列表由逗号分隔的CPU范围组成，用于此作业。如果未提供ORDERED限定符，则每个节点将被分配进程，数量不超过可用插槽数，并受指定CPU可用性的限制。如果指定了ORDERED，则将每个指定CPU分配一个进程（如果可用），受每个节点插槽数和指定进程总数的限制。在这两种情况下，向"bind-to"选项提供OVERLOAD限定符将移除对CPU可用性的检查。

任何指令都可以通过添加冒号(:)和一个或多个以下限定符(用冒号分隔)来包含限定条件，这些限定符可以添加到--map-by选项中(除非另有说明)：

• PE=n 为每个进程绑定n个CPU（不能与rankfile或pe-list指令同时使用）

• SPAN 通过将分配视为单个"超级节点"来在分配中均衡进程负载（不能与 slot、node、seq、ppr、rankfile 或 pe-list 指令组合使用）

• OVERSUBSCRIBE 允许在节点上运行比处理器核心数量更多的进程

• NOOVERSUBSCRIBE 表示 !OVERSUBSCRIBE

• NOLOCAL 不在与prun相同的节点上启动进程

• HWTCPUS 将硬件线程作为CPU插槽使用

• CORECPUS 将核心作为CPU槽位使用（默认）

• INHERIT 表示子作业（即从应用程序内部生成的作业）应继承生成它的父作业的放置策略。

• NOINHERIT 表示 `!INHERIT

• FILE= (包含顺序或rankfile条目的文件路径).

• ORDERED 仅适用于 PE-LIST 选项，用于指示进程将按照分配顺序绑定到每个指定的CPU上（即节点上的第一个进程将绑定到列表中的第一个CPU，第二个进程将绑定到第二个CPU，依此类推）。

注意

指令和限定符不区分大小写，可以缩写为能唯一标识它们的最小字符数。因此，L1CACHE可以写成l1cache或简写为L1。

映射算法中使用的CPU类型（核心 vs 硬件线程）按以下方式确定：

• 通过用户在命令行中使用HWTCPUS限定符对--map-by指令进行指定

• 通过设置rmaps_default_mapping_policy MCA参数包含HWTCPUS限定符。该参数为PRRTE DVM设置默认值——除非被用户命令行覆盖，否则限定符会传递到通过prun启动的DVM作业中

• 在定义了核心CPU的拓扑结构中默认为CORE，否则默认为hwthreads。

如果您的应用程序使用线程，那么您可能需要确保要么完全不绑定（通过指定--bind-to none），要么通过--map-by命令行指令的PE=#限定符，使用适当的绑定级别或每个应用程序进程的特定处理元素数量绑定到多个核心。

有关映射、排名和绑定过程的更详细描述，可以通过--help placement选项获取。

17.1.2.4.11.11. --output选项

output命令行指令必须附带一个不区分大小写的逗号分隔选项列表，用于控制输出生成方式。无需提供完整指令——只需输入足够唯一标识该指令的字符即可。例如，MERGE足以代表MERGE-STDERR-TO-STDOUT指令——而TAG不能代表TAG-DETAILED（但TAG-D可以满足要求）。

支持的取值包括：

• TAG 会在每行输出前标记生成该行的进程的 [job,rank]: 信息

• TAG-DETAILED 为每行输出标记详细的注释，包含生成该行输出的进程的[namespace,rank][hostname:pid]:信息

• TAG-FULLNAME 会在每条输出行前标记生成该行的进程的 [namespace,rank]: 信息

• TAG-FULLNAME 在每行输出前标记生成该行的进程的 [namespace,rank]: 信息

• TIMESTAMP 会在每条输出行前添加 [datetime]: 时间戳标记。请注意，该时间戳是DVM输出该行时的时间，而非原始输出产生的时间

• XML 以伪XML格式提供所有输出 MERGE-STDERR-TO-STDOUT 将标准错误合并到标准输出

• DIR=DIRNAME 将应用程序进程的输出重定向到 DIRNAME/job/rank/std[out,err,diag]。提供的名称将被 转换为绝对路径

• FILE=FILENAME 将应用程序进程的输出重定向到 filename.rank. 提供的名称将被转换为绝对路径

支持的限定符包括 NOCOPY（不将输出复制到标准输出/错误流），以及 RAW（不将输出缓冲为完整行，而是按接收到的原始格式输出）。

17.1.2.4.11.12. --pmixmca选项

传递一个PMIx MCA参数

语法：--pmixmca ，其中key表示参数名称，value表示参数值。

17.1.2.4.11.13. --prefix选项

用于查找PRRTE可执行文件的前缀。如果PRRTE配置了--enable-prte-prefix-by-default选项，或者prte命令本身是以绝对路径执行的，PRRTE会自动为远程守护进程设置前缀。此选项会覆盖现有设置（如果存在），并强制使用提供的路径。

17.1.2.4.11.14. --pmix-prefix选项

PRRTE可执行文件在远程节点上查找其PMIx安装时使用的前缀。这是安装顶级目录的位置。如果安装未被移动，它将是配置安装时提供给“--prefix”的值。

请注意，PRRTE无法确定该位置下库子目录的确切名称。例如，某些系统会将其称为“lib”，而其他系统则称为“lib64”。因此，PRRTE将使用用于构建PRRTE的PMIx安装中的库子目录名称。

17.1.2.4.11.15. --app-prefix 选项

应用程序用于在远程节点上查找其PMIx安装的前缀路径。这是安装顶级目录的位置。如果安装未被移动，它将是配置安装时传递给“--prefix”参数的值。

请注意，PRRTE无法确定该位置下库子目录的确切名称。例如，某些系统会将其称为“lib”，而其他系统则称为“lib64”。因此，PRRTE将使用构建PRRTE时所采用的PMIx安装的库子目录名称。

如果没有提供应用特定的前缀，除非给出“--no-app-prefix”指令，否则将应用PRRTE自身可执行文件所使用的PMIx前缀（如果已指定）。

17.1.2.4.11.16. --no-app-prefix 选项

不要对此应用程序应用任何前缀。当PRRTE已指定默认的PMIx前缀，但应用程序链接的PMIx库满足以下条件时需要此设置：(a) 该库与PRRTE使用的版本不同，(b) 未被迁移。否则PRRTE会对其应用默认前缀。

17.1.2.4.11.17. --prtemca选项

传递一个PRRTE MCA参数。

语法：--prtemca ，其中key表示参数名称，value表示参数值。

17.1.2.4.11.18. --noprefix选项

禁用自动--prefix行为。如果PRRTE配置了--enable-prte-prefix-by-default选项，或者prte本身是以绝对路径执行的，PRRTE会自动为远程守护进程设置前缀。此选项将禁用该行为。

17.1.2.4.11.19. --rank-by选项

PRRTE会自动为每个作业中的进程从零开始分配排名。 无论使用何种算法，排名分配在同一作业内的应用程序之间是连续的——例如，命令行如下所示：

-n 3 app1 : -n 2 app2

将导致 app1 拥有三个进程（排名0-2），而 app2 拥有两个进程（排名3-4）。

默认情况下，进程排名会根据映射指令进行分配——例如，按节点映射的作业将以轮询方式在每个节点基础上分配进程排名。不过，用户可以通过--rank-by命令行选项指定以下任意指令来覆盖默认设置：

• SLOT 按照映射器分配的先后顺序，为节点上的每个进程分配等级。这是默认行为，但作为显式选项提供，允许用户覆盖环境中指定的任何替代默认值。当映射到特定资源类型时，分配给节点上该资源特定实例的进程将在该节点上按资源基础进行等级分配，然后再转移到下一个节点。

• NODE 以节点为单位循环分配排名

• FILL 将进程分配给映射到每个节点上特定资源类型的处理器，在转移到该节点的下一个资源之前，会先填满该资源上的所有进程。例如，通过L1cache映射的进程会在转移到节点上的第二个L1cache之前，先将第一个L1cache上的所有进程按顺序排列。一旦节点上的所有进程都排列完毕，排列将继续在下一个节点上进行。

• SPAN 采用轮询方式为映射到特定资源类型的进程分配等级，将跨越整个分配的资源实例集合视为一个"超级节点"，然后循环进行下一轮分配。因此，等级分配会从第一个节点上的第一个L1cache上的第一个进程开始，接着将下一个等级分配给该节点上第二个L1cache上的第一个进程，依此类推，直到为作业使用的所有L1cache上的第一个进程分配完等级后，再循环回来为每个对象上的第二个进程分配等级。

rank-by 命令行选项没有限定符。

注意

指令不区分大小写。SPAN与span相同。

有关映射、排名和绑定过程的更详细描述，可以通过--help placement选项获取。

17.1.2.4.11.20. --runtime-options 选项

--runtime-options 命令行指令必须附带一个以逗号分隔、不区分大小写的选项列表，这些选项用于控制作业的运行时行为。无需提供完整指令——只需输入足够唯一标识该指令的字符即可。

运行时选项通常是true或false，不过这对开发者并非强制要求。由于每个选项的值可能需要设置（例如覆盖MCA参数设置的默认值），命令行指令的语法包含使用=字符来允许为选项指定值。例如，可以通过指定ABORT-NONZERO-STATUS=1将ABORT-NONZERO-STATUS选项设为true。请注意，布尔选项可以通过非零整数或不区分大小写的字符串true设为true。对于后一种表示方式，用户只需至少提供T字符即可。同样的规则也适用于将布尔选项设为false。

请注意，布尔选项如果未提供值，则默认为true。因此，--runtime-options abort-nonzero足以将ABORT-NONZERO-STATUS选项设置为true。

支持的取值包括：

• ERROR-NONZERO-STATUS[=(bool)]: 如果设置为false，这将指示运行时将以非零状态退出的进程视为正常终止。如果设置为true，运行时将把这种情况视为错误终止并采取适当措施——即除非运行时选项另有指示，否则作业将被终止。如果该选项未指定值，则默认为true。

• DONOTLAUNCH: 指示运行时仅映射但不启动指定的作业。该选项用于在实际开始执行前探索可能的进程布局模式。由于这不是PRRTE中可默认设置的选项，因此无需传递值。

• SHOW-PROGRESS[=(bool)]: 要求运行时提供其启动过程的进度报告——即支持作业的守护进程的启动。这通常用于在大型系统上调试DVM启动。如果该选项未指定值，则默认为true。

• NOTIFYERRORS[=(bool)]：如果设置为true，则要求运行时在作业遇到错误（例如进程失败）时提供PMIx事件。该事件将传递给作业中每个剩余的进程。如果该选项未指定值，则默认为true。有关可捕获故障事件的PMIx事件代码的更多详细信息，请参见--help notifications。

• RECOVERABLE[=(bool)]: 如果设置为true，表示应用程序希望将该作业视为可恢复的——即应用程序承担从任何进程故障中恢复的责任。这可能包括应用程序驱动的替代进程生成或对缺失进程的内部补偿。如果该选项未指定值，则默认为true。

• AUTORESTART[=(bool)]: 如果设置为true，表示请求运行时自动重启失败的进程，最多重启"max restarts"次。如果该选项不带值给出，则默认值为true。

• CONTINUOUS[=(bool)]：如果设置为true，这将通知运行时该作业中的进程将持续运行直到被显式终止。失败的进程将自动重启，最多"max restarts"次。进程失败的通知将发送给应用程序中的所有进程。这相当于指定了RECOVERABLE、NOTIFYERRORS和AUTORESTART选项，区别在于运行时（而非应用程序）承担进程恢复的责任。如果该选项不带值，则默认为true。

• MAX-RESTARTS=: 指定某个进程的最大重启次数。该参数可在应用级别或作业级别设置（在作业级别设置时将应用于该作业中的所有应用）。

• EXEC-AGENT= 指定用于启动应用程序进程的可执行文件路径。启动应用程序进程的最终命令将为 app 。该路径可以包含自身的命令行参数。

• DEFAULT-EXEC-AGENT: 指示运行时使用系统默认的执行智能体来启动应用程序进程。由于这不是PRRTE中可默认设置的选项，因此无需传递任何值。

• OUTPUT-PROCTABLE[(=channel)]: 指示运行时报告常规调试器进程表（包含应用程序中每个进程的PID和主机位置）。如果通道为-则输出到stdout，为+则输出到stderr，否则输出到指定文件。如果未指定通道，输出将默认定向到stdout。

• STOP-ON-EXEC: 指示运行时在应用程序进程执行后立即停止它们。该指令将应用于作业中的所有进程。

• STOP-IN-INIT: 表示运行时环境应指示应用程序进程在PMIx_Init()中停止。该指令将应用于作业中的所有进程。

• STOP-IN-APP: 表示运行时环境应指示应用程序进程在某个应用定义的位置停止，并通知它们已准备好进行调试。该指令将应用于作业中的所有进程。

• TIMEOUT=: 指示运行时在作业执行达到指定时间后终止。时间采用冒号分隔格式指定——例如，01:20:13:05 表示1天20小时13分钟5秒。未使用冒号分隔的时间将被视为以秒为单位。

• SPAWN-TIMEOUT=: 指示运行时在作业启动未能在指定时间内完成时终止作业。时间采用冒号分隔格式指定——例如，01:20:13:05表示1天20小时13分钟5秒。未使用冒号分隔的时间将被视为以秒为单位。

• REPORT-STATE-ON-TIMEOUT[(=bool)]: 指示运行时在作业超时时提供关于作业和应用进程状态的详细报告。如果该选项未指定值，则默认值为true。

• GET-STACK-TRACES[(=bool)]: 请求运行时在超时后仍执行的所有应用程序进程上提供堆栈跟踪。如果该选项未指定值，则默认值为true。

• REPORT-CHILD-JOBS-SEPARATELY[(=bool)]：指示运行时将主作业生成的任何子作业的退出状态单独报告。如果为false，则当主作业和所有子作业正常退出时，最终报告的退出状态为零；如果主作业或子作业返回非零状态，则报告第一个非零状态。如果该选项未指定值，则默认为true。

• AGGREGATE-HELP-MESSAGES[(=bool)]：指示运行时聚合帮助消息，每个独特的帮助消息仅报告一次，并附带报告该消息的进程数量。如果该选项未指定值，则默认为true。

• FWD-ENVIRONMENT[(=bool)]: 指示运行时转发整个本地环境以支持应用程序。如果该选项未指定值，则默认为true。

--runtime-options 命令行选项没有限定符。

注意

指令不区分大小写。FWD-ENVIRONMENT与fwd-environment相同。

17.1.2.4.11.21. --stream-buffering 选项

调整标准输出/标准错误的缓冲设置。允许的取值：

• 0: 无缓冲

• 1: 行缓冲

• 2: 完全缓冲

17.1.2.4.11.22. --tune 调优选项

逗号分隔的一个或多个文件列表，包含用于调优DVM和/或应用程序操作的PRRTE和PMIx MCA参数。文件中的参数将被视为通用参数，并遵循转换规则/不确定性。更多信息请参见--help mca。

文件中的语法为：

param = value

每行包含一个参数及其对应的值。空行和以#字符开头的行将被忽略。

17.1.2.4.11.23. -x选项

导出一个环境变量，可选择性地指定其值。例如：

• -x foo 导出环境变量 foo 并从当前环境中获取其值。

• -x foo=bar 导出环境变量名 foo 并在启动的进程中将其值设置为 bar。

• -x foo* 导出所有当前以foo开头的环境变量。

17.1.2.4.11.24. --unset-env选项

取消设置指定的环境变量。注意 --unset-env foo* 会取消所有当前以"foo"开头的环境变量

17.1.2.4.11.25. --prepend-env 选项

将指定的环境变量名前添加给定值。必须在名称后附加“[c]”以指定在追加值时使用的分隔符。

示例：--prepend-envar LD_LIBRARY_PATH[:] foo/lib 将产生以下结果：

LD_LIBRARY_PATH=foo/lib:$LD_LIBRARY_PATH

17.1.2.4.11.26. --append-env 选项

将指定的环境变量追加给定的值。必须在名称后附加“[c]”以指定在追加值时使用的分隔符。

示例：--append-envar LD_LIBRARY_PATH[:] foo/lib 将产生以下结果：

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:foo/lib

17.1.2.4.12. 已弃用的命令行选项

以下命令行选项已被弃用，通常不应使用。它们可能会在Open MPI的未来版本中被移除。

17.1.2.4.12.1. --bind-to-core 选项

将每个进程绑定到其专属核心。

已弃用

此选项已弃用。请使用 --bind-to core。

17.1.2.4.12.2. --display-allocation选项

显示此作业正在使用的分配情况。

已弃用

此选项已弃用。请改用--display alloc。

17.1.2.4.12.3. --display-devel-allocation 选项

显示此作业所使用的分配的详细列表（主要面向开发人员）。

已弃用

此选项已弃用。请改用--display alloc-devel。

17.1.2.4.12.4. --display-devel-map 选项

在启动前显示详细进程映射图（主要面向开发者）。

已弃用

此选项已弃用。请使用--display map-devel。

17.1.2.4.12.5. --display-map 选项

在启动前显示进程映射图。

已弃用

此选项已弃用。请改用--display map。

17.1.2.4.12.6. --display-topo 选项

在启动前将拓扑结构显示为进程映射的一部分（主要面向开发者）。

已弃用

该选项已弃用。请使用--display topo。

17.1.2.4.12.7. --gmca 选项

语法：--gmca ，其中key表示参数名称， value表示参数值。g前缀表明 该参数是"全局"的，将应用于所有应用上下文——而不仅限于出现该指令的上下文。

传递通用的MCA参数——即参数的项目归属必须由PRRTE根据参数名称与PRRTE已知各项目中定义值的匹配情况来确定。

已弃用

This translation can be incomplete (e.g., if known project adds or changes parameters) — thus, it is strongly recommended that users use project-specific parameters such as --gprtemca or --gpmixmca.

17.1.2.4.12.8. --mca选项

语法：--mca ，其中key是参数名称， value是参数值。

传递通用的MCA参数——即参数的项目归属必须由PRRTE根据参数名称与PRRTE已知各项目定义值的匹配情况来确定。

已弃用

This translation can be incomplete (e.g., if a project adds or changes parameters) — thus, it is strongly recommended that users use project-specific parameters such as --prtemca or --pmixmca.

17.1.2.4.12.9. --merge-stderr-to-stdout 选项

将每个进程的标准错误输出合并到标准输出。

已弃用

此选项已弃用。请使用 --output merge

17.1.2.4.12.10. --output-directory 选项

将应用程序进程的输出重定向到filename/job/rank/std[out,err,diag]。相对路径值将被转换为绝对路径。目录名可以包含冒号后跟一个逗号分隔的可选不区分大小写的指令列表。当前支持的指令包括NOJOBID（不包含作业ID目录层级）和NOCOPY（不将输出复制到stdout/err流）。

已弃用

此选项已弃用。请使用 --output dir=。

17.1.2.4.12.11. --output-filename 选项

将应用程序进程的输出重定向到filename.rank文件中。相对路径值将被转换为绝对路径。目录名可以包含冒号后跟一个逗号分隔的可选指令列表（不区分大小写）。当前支持的指令包括NOCOPY（不将输出复制到stdout/err流）。

已弃用

此选项已弃用。请使用 --output file=

17.1.2.4.12.12. --report-bindings 选项

将进程绑定显示到标准错误输出。

已弃用

此选项已弃用。请改用--display bindings。

17.1.2.4.12.13. --tag-output 选项

使用[job,rank]标记所有输出。

已弃用

此选项已弃用。请改用--output。

17.1.2.4.12.14. --timestamp-output选项

为所有应用程序进程输出添加时间戳。

已弃用

此选项已弃用。请改用--output timestamp。

17.1.2.4.12.15. --xml 选项

以XML格式提供所有输出。

已弃用

此选项已弃用。请改用--output。

17.1.2.5. 选项（旧版/硬编码内容 - 待审核）

这是旧内容

这是手动硬编码内容的旧部分。可能需要阅读/审核，看看我们想保留哪些内容，以及想舍弃哪些内容。

请随时参考https://docs.prrte.org/，而无需在此重复内容（例如，关于槽位定义及其他事项的说明）。

mpirun会将本地节点上调用时所在的目录名称发送到每个远程节点，并尝试切换到该目录。更多详情请参阅下方的"当前工作目录"部分。

• : 程序可执行文件。这是作为mpirun的第一个未被识别的参数来确定的。

• : 将这些运行时参数传递给每个新进程。这些参数必须是mpirun的最后参数。如果使用了应用上下文文件，将被忽略。

• -h, --help: 显示此命令的帮助信息

• -q, --quiet: 在应用程序执行期间抑制来自orterun的信息性消息。

• -v, --verbose:` 显示详细输出信息

• -V, --version: 打印版本号。如果没有提供其他参数，这将导致orterun退出。

• -N : 在所有分配的节点上每个节点启动num个进程 (等同于 --npernode)。

• --display-map: 在启动前显示每个进程映射位置的表格。

• --display-allocation: 显示检测到的资源分配情况。

• --output-proctable: 启动后输出调试器进程表。

• --dvm: 创建一个持久化的分布式虚拟机(DVM)。

• --max-vm-size <size>: 要启动的守护进程数量。

使用以下选项之一来指定集群中要运行的主机（节点）。请注意，从v1.8版本开始，mpirun会在执行的最初阶段向分配中的每台主机（根据以下选项修改）启动一个守护进程，无论最终是否会将应用程序进程映射到该节点执行。这样做的目的是允许从远程节点收集硬件拓扑信息，从而使我们能够根据已知拓扑映射进程。然而，这与之前版本的行为有所不同，在早期版本中，守护进程仅在映射完成后启动，因此只出现在实际执行应用程序进程的节点上。

• -H, --host : 要在其上调用进程的主机列表。

• --hostfile : 提供一个要使用的主机文件。

• --default-hostfile : 提供一个默认的主机文件。

• --machinefile : --hostfile的同义词。

• --cpu-set : 将启动的进程限制在每个节点指定的逻辑CPU上（逗号分隔的列表）。请注意绑定选项仍会在指定的范围内生效——例如，您可以选择将每个进程仅绑定到指定CPU集合中的一个CPU。

以下选项用于指定要启动的进程数量。请注意，这些选项均不隐含特定的绑定策略——例如，请求每个处理器封装运行N个进程，并不意味着这些进程将被绑定到该处理器封装。

• -n, --n, -c, -np <#>: 在指定节点上运行指定数量的程序副本。此选项表明指定的文件是可执行程序而非应用上下文。若未提供要执行的副本数量（即命令行中未指定-n或其同义词），Open MPI将自动在每个进程槽上执行程序副本（关于"进程槽"的定义请参阅PRRTE的defintion of "slot"）。但此功能仅适用于SPMD模型，否则将返回错误（且不会开始执行应用程序）。

  注意

  -n选项是指定要执行的程序副本数量的首选选项，但其他替代选项也可接受。

• --map-by ppr:N:: 在每个节点上启动指定类型对象数量的N倍。

• --npersocket <#persocket>: 在每个节点上，启动的进程数为该节点处理器插槽数量乘以这个参数值。 -npersocket选项还会自动启用--bind-to-socket选项。（已弃用，建议改用--map-by ppr:n:package）

• --npernode <#pernode>: 在每个节点上启动指定数量的进程。 (已弃用，建议使用 --map-by ppr:n:node)。

• --pernode: 在每个节点上启动一个进程 —— 等同于 --npernode 1。（已弃用，建议改用 --map-by ppr:1:node）

映射进程：

• --map-by : 映射到指定对象，默认为 package。支持的选项包括 slot, hwthread, core, L1cache, L2cache, L3cache, package, numa, node, seq, rankfile, pe-list=#, 和 ppr。 任何对象都可以通过添加 : 和以下任意组合来包含修饰符：

  • pe=n: 将 n 个处理元素绑定到每个进程

  • span: 在分配中平衡进程负载

  • oversubscribe: 允许在单个节点上运行超过处理器核心数的进程

  • nooversubscribe: 不允许在节点上运行超过处理器核心数的进程（默认设置）

  • nolocal: 不将进程放置在与mpirun进程相同的主机上

  • hwtcpus: 将硬件线程作为CPU插槽用于映射

  • corecpus: 将处理器核心作为CPU插槽进行映射（默认）

  • file=filename: 与rankfile配合使用；通过filename指定要使用的文件

  • ordered: 与pe-list配合使用，将每个进程绑定到指定的处理元素之一

  注意

  socket 也可作为 package 的别名使用。

• --bycore: 按核心映射进程（已弃用，建议改用 --map-by core）。

• --byslot: 按插槽轮询方式映射和分配进程排名（已弃用，建议使用--map-by slot替代）。

• --nolocal: 不在orterun运行的同一节点上启动任何应用程序副本。此选项将覆盖通过--host或其他主机指定机制列出的localhost。等同于--map-by :nolocal的别名。

• --nooversubscribe: 禁止超额订阅任何节点；如果请求的进程数会导致超额订阅，则报错（且不启动任何进程）。此选项会隐式将每个节点的"max_slots"设置为与"slots"值相等。（默认启用）。--map-by :nooversubscribe的别名。

• --oversubscribe: 允许节点超额订阅，即使在受管系统上也可使用，并允许处理单元过载。这是--map-by :oversubscribe的别名。

• --bynode: 以轮询方式按节点启动进程，每个节点一个进程。这会将进程均匀分布在各个节点上，并以轮询、"按节点"的方式分配MPI_COMM_WORLD的排名。(已弃用，推荐使用--map-by node)

• --cpu-list : 指定进程绑定到的处理器ID逗号分隔列表[默认=``NULL``]。处理器ID将被解释为hwloc逻辑核心ID。

  注意

  您可以运行hwloc的lstopo(1)命令查看可用核心及其逻辑ID列表。

对MPI_COMM_WORLD中的进程等级进行排序：

• --rank-by : 按照指定模式以轮询方式进行排名，默认为slot。支持的选项包括 slot, node, fill, 和 span。

进程绑定：

• --bind-to : 将进程绑定到指定对象，默认为core。支持的选项包括slot、hwthread、core、l1cache、l2cache、l3cache、package、numa和none。

• --cpus-per-proc <#perproc>: 将每个进程绑定到指定数量的CPU核心上。(已弃用，建议改用--map-by :PE=n)

• --cpus-per-rank <#perrank>: --cpus-per-proc的别名。 (已弃用，推荐使用--map-by :PE=n)

• --bind-to-core 将进程绑定到CPU核心（已弃用，建议改用 --bind-to core）

• --bind-to-socket: 将进程绑定到处理器插槽 (已弃用，推荐使用 --bind-to package)

• --report-bindings: 报告已启动进程的任何绑定情况。

对于rankfiles：

• --rankfile : 提供一个rankfile文件。 (已弃用，推荐使用 --map-by rankfile:file=FILE)

管理标准输入/输出：

• --output-filename : 将所有进程的标准输出、标准错误和标准诊断重定向到指定文件名的进程唯一版本。文件名中的任何目录将自动创建。每个输出文件将由filename.id组成，其中id是进程在MPI_COMM_WORLD中的排名，左侧填充零以确保在列表中的正确排序。相对路径值将基于执行mpirun时的当前工作目录转换为绝对路径。请注意，这在计算节点文件系统与执行mpirun(1)所在环境不同的情况下将无法工作。

• --stdin : 指定接收标准输入(stdin)的进程在MPI_COMM_WORLD中的排名。默认情况下会将stdin转发给MPI_COMM_WORLD中排名为0的进程，但该选项可用于将stdin转发给任意进程。也可以指定为none，表示没有进程会接收stdin。

• --merge-stderr-to-stdout: 将每个进程的标准错误输出合并到标准输出。

• --tag-output: 为stdout、stderr和stddiag的每行输出添加标签，格式为[jobid, MCW_rank]，其中包含生成该输出的进程的jobid和MPI_COMM_WORLD排名，以及生成该输出的通道。

• --timestamp-output: 为输出到stdout、stderr和stddiag的每一行添加时间戳。

• --xml: 以XML格式向标准输出(stdout)、标准错误(stderr)和标准诊断(stddiag)提供所有输出。

• --xml-file 将所有输出以XML格式提供到指定文件。

• --xterm : 在独立的xterm窗口中显示由MPI_COMM_WORLD标识的进程输出。ranks参数需指定为逗号分隔的范围列表，其中-1表示全部。系统将为每个指定进程创建独立窗口。

  注意

  xterm通常会在内部运行的进程终止时关闭窗口。但如果在ranks列表末尾添加!字符，系统将提供相应选项确保xterm在进程终止后保持窗口开启，以便查看进程输出。每个xterm窗口后续需要手动关闭。 注意：在某些环境中，xterm可能要求可执行文件位于用户路径中，或以绝对/相对路径指定。因此可能需要将本地可执行文件指定为./my_mpi_app而非简单的my_mpi_app。若xterm无法找到可执行文件，mpirun会挂起但仍能正确响应ctrl-C中断。如遇此情况，请检查可执行文件路径是否正确并重试。

管理文件与运行时环境：

• --path : 指定在查找请求的可执行文件时使用的路径。该路径会在使用本地PATH环境变量设置之前被使用。

• --prefix

  : 用于在远程节点上调用Open MPI或目标进程之前设置PATH和LD_LIBRARY_PATH的前缀目录。请参阅下方的远程执行章节。

• --noprefix: 禁用自动的--prefix行为

• --preload-binary: 在启动远程进程前，将指定的可执行文件复制到远程机器。这些可执行文件会被复制到Open MPI会话目录中，并在任务完成后删除。

• --preload-files : 在启动远程机器上的进程之前，将逗号分隔的文件列表预加载到这些进程将要运行的远程机器当前工作目录中。

• --set-cwd-to-session-dir: 将启动进程的工作目录设置为其会话目录。

• --wd

  : -wdir的同义词。

• --wdir

  : 在用户程序执行前切换到目录 。关于相对路径的注意事项，请参阅当前工作目录部分。注意：如果--wdir选项同时出现在命令行和应用上下文中，上下文将优先于命令行。因此，如果所需wdir路径在后端节点上不同，则必须指定为适用于后端节点的绝对路径。

• -x : 在执行程序前将指定的环境变量导出到远程节点。每个-x选项只能指定一个环境变量。可以指定已存在的环境变量，也可以通过对应值指定新变量名。例如：

  shell$ mpirun -x DISPLAY -x OFILE=/tmp/out ...
  

  -x选项的解析器功能较为简单；它甚至无法识别带引号的值。建议用户在环境中设置变量，然后使用-x来导出（而非定义）这些变量。

设置MCA参数：

• --gmca : 传递适用于所有上下文的全局MCA参数。是参数名称；是参数值。

• --mca : 向各种MCA模块传递参数。详情请参阅设置MCA参数章节。

  注意

  Open MPI会尝试识别通过--mca传递的PMIx和PRRTE MCA参数并正确处理，但可能无法总是准确识别。建议在向PMIx和PRRTE传递MCA参数时分别使用--pmixmca和--prtemca。

• --pmixmca : 向PMIx子系统中的MCA模块传递参数。更多详情请参阅Setting MCA Parameters章节。

• --prtemca : 向PMIx参考运行时环境(PRRTE)子系统中的MCA模块传递参数。详情请参阅Setting MCA Parameters章节。

• --tune : 指定一个调优文件来为各种MCA模块和环境变量设置参数。参见:ref:` 从文件设置MCA参数和环境变量 `。--am 是 --tune 的别名。

用于调试：

• --get-stack-traces: 当与--timeout选项配合使用时， mpirun将在超时到期时获取并打印所有仍在运行的启动进程的堆栈跟踪信息。请注意， 获取堆栈跟踪可能需要一些时间并产生大量输出，特别是对于进程数较多的作业。

• --timeout : mpirun运行的最大秒数。超过这个时间后，mpirun将中止启动的作业并以非零退出状态退出。当与--get-stack-traces选项结合使用时，--timeout也很有用。

还有其他选项：

• --allow-run-as-root: 允许mpirun在root用户下运行（默认情况下当以root用户启动时mpirun会中止）。更多详情请参阅Running as root章节。

• --app : 提供一个appfile文件，忽略所有其他命令行选项。

• --continuous: 任务将持续运行，直到被显式终止。

• --disable-recovery: 禁用恢复功能（将所有恢复选项重置为关闭状态）。

• --do-not-launch: 执行所有必要的操作来准备启动应用程序，但实际上不进行启动。

• --enable-recovery: 启用进程故障恢复功能（默认：禁用）

• --leave-session-attached: 不分离此应用程序使用的后端守护进程。这样可以将守护进程的错误信息以及底层环境（例如，当启动守护进程失败时）输出。

• --max-restarts : 失败进程的最大重启次数。

• --personality : 以逗号分隔的编程模型、语言和容器列表（默认值为``ompi``）。

• --ppr : 给定资源类型上进程数量的逗号分隔列表（默认：无）。--map-by ppr:N:OBJ的别名。

• --report-child-jobs-separately: 仅返回主作业的退出状态。

• --report-events : 将事件报告给监听在指定URI的工具。

• --report-pid : 在启动时打印出mpirun的进程ID。通道参数必须为以下之一：-表示将PID输出到标准输出(stdout)，+表示将PID输出到标准错误(stderr)，或者指定一个文件名将PID写入该文件。

• --report-uri : 在启动时打印出mpirun的URI。通道参数必须为以下之一：-表示URI输出到标准输出(stdout)，+表示URI输出到标准错误(stderr)，或者指定一个文件名将URI写入该文件。

• --show-progress: 输出关于启动进度的简短定期报告。

• --terminate: 终止DVM。

• --use-hwthread-cpus: 将硬件线程视为独立的CPU。

  请注意，如果未向Open MPI提供插槽数量（例如通过主机文件中的slots关键字或来自Slurm等资源管理器），使用此选项会改变节点上默认的插槽数量计算方式。详情请参阅PRRTE的“插槽”定义。

  还需注意，使用此选项会将Open MPI中“处理器单元”的定义从处理器核心更改为硬件线程。详情请参阅PRRTE的“处理器单元”定义。

以下选项对开发者很有用；它们对大多数Open MPI用户通常没有实际用途：

• --debug-daemons: 启用对此应用程序使用的运行时守护进程的调试功能。

• --debug-daemons-file: 启用对该应用程序使用的运行时守护进程的调试功能，将输出内容存储到文件中。

• --display-devel-map: 在启动前显示更详细的表格，展示每个进程的映射位置。

• --display-topo: 在启动前将拓扑结构作为进程映射的一部分显示。

• --launch-agent: 用于在远程节点上启动进程的可执行文件名称。默认为prted。该选项可用于测试新的守护进程概念，或在无需mpirun本身处理的情况下向守护进程传递参数。例如，指定启动代理为prted --prtemca odls_base_verbose 5可以让开发者获取prted的调试输出，而不会受到mpirun本身的干扰。

• --report-state-on-timeout: 当与命令行选项--timeout配合使用时，在超时到期时报告每个进程的运行时子系统状态。

使用 mpirun --help 可能会列出其他选项。

17.1.2.5.1. 环境变量

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

• MPIEXEC_TIMEOUT: --timeout命令行选项的同义词。

17.1.2.6. 描述

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

一次mpirun调用会启动一个在Open MPI下运行的MPI应用程序。如果该应用程序是单进程多数据(SPMD)模式，可以在mpirun命令行中指定该应用程序。

如果应用程序是多指令多数据（MIMD）类型，由多个程序组成，那么可以通过以下两种方式之一来指定程序集及其参数：扩展命令行参数和应用上下文。

应用程序上下文描述了MIMD程序集，包括单独文件中的所有参数。该文件本质上包含多个mpirun命令行（不含命令名称本身）。能够为程序的不同实例指定不同选项，是使用应用程序上下文的另一个原因。

扩展命令行参数允许使用冒号(:)在命令行上描述应用程序布局，用于分隔程序和参数的规范。某些选项在所有指定程序中全局设置(例如--hostfile)，而其他选项则特定于单个程序(例如-n)。

17.1.2.6.1. 指定主机节点

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

主机节点可以通过mpirun命令行中的--host选项或在主机文件中进行标识。

例如：

shell$ mpirun -H aa,aa,bb ./a.out

在节点 aa 上启动两个进程，在 bb 上启动一个进程。

或者，考虑以下主机文件：

shell$ cat myhostfile
aa slots=2
bb slots=2
cc slots=2

这里，我们不仅列出了主机名（aa、bb和cc），还列出了每个主机的插槽数量。

shell$ mpirun --hostfile myhostfile ./a.out

将在三个节点中的每个节点上启动两个进程。

shell$ mpirun --hostfile myhostfile --host aa ./a.out

将在节点 aa 上启动两个进程。

shell$ mpirun --hostfile myhostfile --host dd ./a.out

将找不到可运行的主机，并以错误中止。也就是说，指定的主机dd不在指定的主机文件中。

在资源管理器（如Slurm、Torque等）下运行时，OpenMPI将直接从资源管理器获取主机名和插槽数量。

17.1.2.6.2. 指定进程数量

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

正如我们刚才所见，可以通过主机文件设置要运行的进程数量。此外，还存在其他设置机制。

启动的进程数量可以指定为可用节点或处理器封装数量的倍数。例如，

shell$ mpirun -H aa,bb --map-by ppr:2:package ./a.out

在节点aa上启动进程0-3，在节点bb上启动进程4-7 （假设aa和bb每个节点都包含4个插槽）。

shell$ mpirun -H aa,bb --map-by ppr:2:node ./a.out

在节点 aa 上启动进程 0-1，在节点 bb 上启动进程 2-3。

shell$ mpirun -H aa,bb --map-by ppr:1:node ./a.out

每个主机节点启动一个进程。

mpirun -H aa,bb --pernode ./a.out

等同于 --map-by ppr:1:node 和 --npernode 1。

另一种选择是使用-n选项指定进程数量。现在考虑以下主机文件：

shell$ cat myhostfile
aa slots=4
bb slots=4
cc slots=4

现在使用 myhostfile 运行：

shell$ mpirun --hostfile myhostfile -n 6 ./a.out

将在节点aa上启动进程0-3，在节点bb上启动进程4-5。由于-n选项指定只启动6个进程，主机文件中剩余的槽位将不会被使用。

17.1.2.6.3. 将进程映射到节点：使用策略

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

上述示例展示了进程到节点的默认映射关系。这种映射也可以通过描述映射策略的各种mpirun选项来控制。

考虑与上述相同的主机文件，同样使用-n 6参数。下表列出了几种mpirun的变体用法，并展示了哪些MPI_COMM_WORLD等级最终运行在哪些节点上：

命令	节点 aa	节点 bb	节点 cc
mpirun	0 1 2 3	4 5
mpirun --map-by node	0 3	1 4	2 5
mpirun --nolocal		0 1 2 3	4 5

--map-by node选项将在可用节点间均衡分配进程，以轮询方式为每个进程编号。

--nolocal选项可以防止任何进程被映射到本地主机（在本例中为节点aa）。虽然mpirun通常消耗的系统资源很少，但在启动非常大的作业时，--nolocal可能会很有帮助，因为mpirun实际上可能需要使用相当数量的内存和/或处理时间。

正如-n可以指定比可用槽位更少的进程数一样，它也可以超额分配槽位。例如，使用相同的主机文件时：

shell$ mpirun --hostfile myhostfile -n 14 ./a.out

将在节点aa上启动进程0-3，在bb上启动4-7，在cc上启动8-11。然后会将剩余的两个进程分配到它选择的任意节点上。

还可以指定超额订阅的限制。例如，使用相同的主机文件：

shell$ mpirun --hostfile myhostfile -n 14 --nooversubscribe ./a.out

会产生错误，因为--nooversubscribe会阻止超额订阅。

主机文件中也可以指定超额订阅的限制：

shell$ cat myhostfile
aa slots=4 max_slots=4
bb         max_slots=4
cc slots=4

max_slots字段用于指定此类限制。当设置该值时，slots默认值将采用此限制值。现在：

shell$ mpirun --hostfile myhostfile -n 14 ./a.out

前12个进程会像之前一样启动，但剩下的两个进程将被强制分配到节点cc上。另外两个节点通过hostfile保护，防止被此作业超额占用。

使用--nooversubscribe选项会很有帮助，因为Open MPI 目前无法从资源管理器获取max_slots值。

当然，-n也可以与-H或-host选项一起使用。例如：

shell$ mpirun -H aa,bb -n 8 ./a.out

启动8个进程。由于仅指定了两个主机，在前两个进程分别映射到aa和bb后，剩余进程将超额占用已指定的主机资源。

这是一个MIMD的示例：

shell$ mpirun -H aa -n 1 hostname : -H bb,cc -n 2 uptime

将在节点aa上运行hostname启动进程0，并分别在节点bb和cc上运行uptime启动进程1和2。

17.1.2.6.4. 映射、排名与绑定：哦天哪！

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

Open MPI采用三阶段流程来分配进程位置和排名：

1. 映射: 为每个进程分配默认位置

2. 排名: 为每个进程分配一个MPI_COMM_WORLD排名值

3. 绑定: 限制每个进程在特定处理器上运行

映射步骤用于根据所采用的映射器为每个进程分配默认位置。按插槽、节点和顺序映射会将进程分配到节点级别。相比之下，按对象映射则允许映射器将进程分配到每个节点上的实际对象。

请注意，分配给进程的位置与其实际绑定位置无关——该分配仅作为绑定算法的输入使用。

进程到节点的映射不仅可以通过通用策略定义，必要时还可以使用无法通过简单策略描述的任意映射。可以使用“顺序映射器”，它会逐行读取主机文件，按照主机文件指定的顺序将进程分配到节点。使用---map-by seq选项。例如，使用之前相同的主机文件：

shell$ mpirun -hostfile myhostfile --map-by seq ./a.out

将在三个节点上分别启动三个进程，每个节点对应一个：aa、bb和cc。槽位计数无关紧要；每行列出的节点上都会启动一个进程。

另一种指定任意映射的方法是使用rankfile，它还能让你对进程绑定进行精细控制。关于rankfile的讨论请见下方。

第二阶段专注于进程在作业MPI_COMM_WORLD中的排名。Open MPI将此与映射过程分离，以便在MPI进程的相对布局上提供更大的灵活性。通过考虑以下使用--np 8 --map-by ppr:2:package --host aa:4,bb:4选项的案例，可以最清楚地说明这一点：

选项	节点 aa	节点 bb
--rank-by fill (即密集填充) 默认值	0 1 | 2 3	4 5 | 6 7
--rank-by span (即稀疏或负载均衡打包)	0 4 | 1 5	2 6 | 3 7
--rank-by node	0 2 | 4 6	1 3 | 5 7

按fill排序会在每个节点上以简单递增的方式分配MCW等级。按span和slot排序会产生相同的结果——在所有节点间以轮询方式递增分配包，直到返回第一个节点的第一个包。按node排序会先跨节点迭代分配MCW等级，然后再按包分配。

绑定阶段实际上是将每个进程绑定到一组特定的处理器上。如果操作系统对进程的放置不够优化，这种绑定可以提高性能。例如，操作系统可能会过度订阅某些多核处理器封装，导致其他封装闲置；这会使进程不必要地争夺共享资源。或者，它可能将进程分布得过于分散；如果应用程序性能对进程间通信成本敏感，这种分布可能不够优化。绑定还可以防止操作系统过度迁移进程，无论这些进程最初的放置有多优化。

用于绑定的处理器可以通过拓扑分组来识别——例如，绑定到l3cache将使每个进程绑定到其分配位置内单个L3缓存范围内的所有处理器。因此，如果映射器将某个进程分配到特定封装内，那么--bind-to l3cache指令将导致该进程被绑定到该封装内共享单个L3缓存的处理器上。

或者，也可以使用--map-by pe-list=选项将进程映射并绑定到指定的核心。例如，--map-by pe-list=0,2,5会映射三个进程，这三个进程都将绑定到逻辑核心0,2,5。如果您希望将这三个进程分别绑定到不同的核心，则可以使用:ordered限定符，如--map-by pe-list=0,2,5:ordered。在这个例子中，节点上的第一个进程将绑定到CPU 0，节点上的第二个进程将绑定到CPU 2，节点上的第三个进程将绑定到CPU 5。

最后，可以使用--report-bindings来报告绑定情况。

例如，考虑一个具有两个处理器封装的节点，每个封装包含四个核心，每个核心又包含一个硬件线程。--report-bindings选项会以描述性方式显示每个进程的绑定情况。以下是一些示例。

shell$ mpirun --np 4 --report-bindings --map-by core --bind-to core
[...] Rank 0 bound to package[0][core:0]
[...] Rank 1 bound to package[0][core:1]
[...] Rank 2 bound to package[0][core:2]
[...] Rank 3 bound to package[0][core:3]

在上述情况下，进程会绑定到连续的处理器核心上。

shell$ mpirun --np 4 --report-bindings --map-by package --bind-to package
[...] Rank 0 bound to package[0][core:0-3]
[...] Rank 1 bound to package[0][core:0-3]
[...] Rank 2 bound to package[1][core:4-7]
[...] Rank 3 bound to package[1][core:4-7]

在上述情况下，进程会绑定到连续处理器封装上的所有核心。进程会以轮询方式循环遍历所需的处理器封装次数。默认情况下，进程会按照fill方式进行排名。

shell$ mpirun --np 4 --report-bindings --map-by package --bind-to package --rank-by span
[...] Rank 0 bound to package[0][core:0-3]
[...] Rank 1 bound to package[1][core:4-7]
[...] Rank 2 bound to package[0][core:0-3]
[...] Rank 3 bound to package[1][core:4-7]

上述案例展示了当使用span限定符而非默认值时在排名上的差异。

shell$ mpirun --np 4 --report-bindings --map-by slot:PE=2 --bind-to core
[...] Rank 0 bound to package[0][core:0-1]
[...] Rank 1 bound to package[0][core:2-3]
[...] Rank 2 bound to package[0][core:4-5]
[...] Rank 3 bound to package[0][core:6-7]

在上述示例中，输出显示每个进程已绑定2个核心。具体而言，带有PE=2限定符的slot映射表明每个槽位（即进程）应占用两个处理器单元。默认情况下，Open MPI将"处理器单元"定义为"核心"，因此--bind-to core参数使每个进程被绑定到其所映射的两个核心上。

shell$ mpirun --np 4 --report-bindings --map-by slot:PE=2 --use-hwthread-cpus
[...]] Rank 0 bound to package[0][hwt:0-1]
[...]] Rank 1 bound to package[0][hwt:2-3]
[...]] Rank 2 bound to package[0][hwt:4-5]
[...]] Rank 3 bound to package[0][hwt:6-7]

在上述情况下，我们将--bind-to core替换为 --use-hwthread-cpus。--use-hwthread-cpus会被转换为 --bind-to hwthread，并指示--report-bindings输出显示 进程所绑定的硬件线程。在此情况下，每个进程会绑定到2个硬件线程。

shell$ mpirun --np 4 --report-bindings --bind-to none
[...] Rank 0 is not bound (or bound to all available processors)
[...] Rank 1 is not bound (or bound to all available processors)
[...] Rank 2 is not bound (or bound to all available processors)
[...] Rank 3 is not bound (or bound to all available processors)

在上述情况下，绑定功能已关闭并如此报告。

Open MPI对进程绑定的支持取决于底层操作系统。因此，某些进程绑定选项可能并非在所有系统上都可用。

进程绑定也可以通过MCA参数进行设置。虽然它们的使用不如mpirun选项方便，但MCA参数不仅可以在mpirun命令行中设置，还可以在系统或用户的mca-params.conf文件中配置，或者作为环境变量，具体方法如设置MCA参数所述。这些是PRRTE运行时的MCA参数，因此必须使用命令行参数--prtemca（注意：是prte带一个r，而不是两个r）来传递MCA参数的键值对。或者，也可以通过为键添加前缀PRTE_MCA_（再次强调：这不是拼写错误，是PRTE而非PRRTE）在命令行中指定MCA参数键值对。示例如下：

选项	PRRTE MCA参数键	值
--map-by core	rmaps_default_mapping_policy	core
--map-by package	rmaps_default_mapping_policy	package
--rank-by fill	rmaps_default_ranking_policy	fill
--bind-to core	hwloc_default_binding_policy	core
--bind-to package	hwloc_default_binding_policy	package
--bind-to none	hwloc_default_binding_policy	none

17.1.2.6.5. 映射、排序与绑定的默认设置

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

如果用户未指定--map-by、--rank-by和--bind-to选项中的每一个，则默认值如下：

• 如果未指定任何选项，则

  • 如果进程数量小于或等于2，则：

    • --map-by 设置为 core

    • --bind-to 是 core

    • --rank-by 是 span

    • 结果: --map-by core --bind-to core --rank-by span

  • 否则：

    • --map-by 设置为 package

    • --bind-to 设置为 package

    • --rank-by 是 fill

    • 结果: --map-by package --bind-to package --rank-by fill

• 如果仅指定了--map-by OBJ（其中OBJ类似于core），那么：

  • --map-by 指定了 OBJ

  • --bind-to 使用与 --map-by 相同的 OBJ

  • --rank-by 默认为 fill

  • 结果: --map-by OBJ --bind-to OBJ --rank-by fill

• 如果仅指定了--bind-to OBJ（其中OBJ类似于core），那么：

  • --map-by 根据进程数量可以是 core 或 package

  • --bind-to 指定了 OBJ

  • --rank-by 默认为 fill

  • 结果: --map-by OBJ --bind-to OBJ --rank-by fill

• 如果 --map-by OBJ1 --bind-to OBJ2，那么：

  • --map-by 指定了 OBJ1

  • --bind-to 指定了 OBJ2

  • --rank-by 默认为 fill

  • 结果: --map-by OBJ2 --bind-to OBJ2 --rank-by fill

考虑两台相同的主机（hostA 和 hostB），每台主机有2个处理器包（用 [] 表示），每个包有8个核心（用 /../ 表示），每个核心有2个硬件线程（用 . 表示）。

当进程数量小于或等于2时，默认使用--map-by core --bind-to core --rank-by span参数配置。

shell$ mpirun --np 2 --host hostA:4,hostB:2 ./a.out
R0  hostA  [BB/../../../../../../..][../../../../../../../..]
R1  hostA  [../BB/../../../../../..][../../../../../../../..]

当进程数大于2时，默认使用--map-by package --bind-to package --rank-by fill。

shell$ mpirun --np 4 --host hostA:4,hostB:2 ./a.out
R0  hostA  [BB/BB/BB/BB/BB/BB/BB/BB][../../../../../../../..]
R1  hostA  [BB/BB/BB/BB/BB/BB/BB/BB][../../../../../../../..]
R2  hostA  [../../../../../../../..][BB/BB/BB/BB/BB/BB/BB/BB]
R3  hostA  [../../../../../../../..][BB/BB/BB/BB/BB/BB/BB/BB]

如果仅指定--map-by OBJ，则隐含--bind-to OBJ --rank-by fill。下面的示例将生成--map-by hwthread --bind-to hwthread --rank-by fill

shell$ mpirun --np 4 --map-by hwthread --host hostA:4,hostB:2 ./a.out
R0  hostA  [B./../../../../../../..][../../../../../../../..]
R1  hostA  [.B/../../../../../../..][../../../../../../../..]
R0  hostA  [../B./../../../../../..][../../../../../../../..]
R1  hostA  [../.B/../../../../../..][../../../../../../../..]

如果仅指定了--bind-to OBJ，那么--map-by将由进程数量和--rank-by fill决定。下面的示例结果是--map-by package --bind-to core --rank-by fill

shell$ mpirun --np 4 --bind-to core --host hostA:4,hostB:2 ./a.out
R0  hostA  [BB/../../../../../../..][../../../../../../../..]
R1  hostA  [../BB/../../../../../..][../../../../../../../..]
R2  hostA  [../../../../../../../..][BB/../../../../../../..]
R3  hostA  [../../../../../../../..][../BB/../../../../../..]

如果我们把默认的--rank-by从fill改为span，可能会更清楚地看到映射模式。首先，进程通过包进行映射，在两个标记之间迭代，每次标记一个核心。接着，进程以跨度的方式进行排名，使它们在映射对象上实现负载均衡。最后，进程被绑定到它们所映射的核心上。

shell$ mpirun --np 4 --bind-to core --rank-by span --host hostA:4,hostB:2 ./a.out
R0  hostA  [BB/../../../../../../..][../../../../../../../..]
R1  hostA  [../../../../../../../..][BB/../../../../../../..]
R2  hostA  [../BB/../../../../../..][../../../../../../../..]
R3  hostA  [../../../../../../../..][../BB/../../../../../..]

17.1.2.6.6. 排名文件

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

Rankfiles是文本文件，用于指定关于如何将各个进程映射到节点以及应绑定到哪些处理器的详细信息。rankfile的每一行指定一个进程的位置（对于MPI作业，进程的"rank"指的是它在MPI_COMM_WORLD中的排名）。rankfile中每行的通用格式为：

rank <N>=<hostname> slot=<slot list>

例如：

shell$ cat myrankfile
rank 0=aa slot=1:0-2
rank 1=bb slot=0:0,1
rank 2=cc slot=2-3
shell$ mpirun -H aa,bb,cc,dd --map-by rankfile:file=myrankfile ./a.out

意思是：

• Rank 0 运行在节点 aa 上，绑定到逻辑包 1，核心 0-2。

• Rank 1运行在节点bb上，绑定到逻辑包0，核心0和1。

• Rank 2 运行在节点 cc 上，绑定到逻辑核心 2 和 3。

请注意，仅支持逻辑处理器位置。默认情况下，指定的值被视为核心。如果您打算指定特定的硬件线程，则必须向--map-by命令行选项添加:hwtcpus限定符（例如：--map-by rankfile:file=myrankfile:hwtcpus）。

如果任何两个rank之间的绑定规范重叠，则会发生错误。如果您希望允许进程共享相同的逻辑处理单元，则必须传递--bind-to :overload-allowed命令行选项，以告知运行时忽略此检查。

上述列出的主机名是"绝对"的，意味着指定的是实际可解析的主机名。然而，主机名也可以被指定为"相对"的，这意味着它们是相对于外部指定的主机名列表（例如通过mpirun的--host参数、主机文件或作业调度器）来指定的。

"relative"（相对）规范的格式为+n，其中X是一个整数，用于指定在所有可用主机名集合中按索引排序的第X个主机名（索引从0开始）。例如：

shell$ cat myrankfile
rank 0=+n0 slot=1:0-2
rank 1=+n1 slot=0:0,1
rank 2=+n2 slot=2-3
shell$ mpirun -H aa,bb,cc,dd --map-by rankfile:file=myrankfile ./a.out

所有包/核心插槽位置均以逻辑索引形式指定。

注意

Open MPI v1.6系列使用物理索引。从Open MPI v5.0开始，仅支持逻辑索引，且不再识别rmaps_rank_file_physical MCA参数。

您可以使用诸如Hwloc的lstopo(1)等工具来查找处理器封装和内核的逻辑索引。

17.1.2.6.7. 应用上下文还是可执行程序？

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

为了区分这两种不同的形式，mpirun会在命令行中查找--app选项。如果指定了该选项，则假定命令行中命名的文件是应用程序上下文。如果未指定，则假定该文件是可执行程序。

17.1.2.6.8. 文件定位

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

如果未为文件指定相对路径或绝对路径，Open MPI将首先通过搜索--path选项指定的目录来查找文件。如果未设置--path选项或在--path位置未找到文件，则Open MPI将搜索源节点上定义的用户PATH环境变量。

如果指定的是相对目录，它必须相对于所使用的特定启动器确定的初始工作目录。例如，当使用ssh启动器时，默认初始目录是$HOME。其他启动器可能会将初始目录设置为调用mpirun时的当前工作目录。

17.1.2.6.9. 当前工作目录

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

--wdir mpirun选项（及其同义词--wd）允许用户在程序调用前切换到任意目录。该选项也可用于应用程序上下文文件中，以指定特定节点和/或特定应用程序的工作目录。

如果--wdir选项同时出现在上下文文件和命令行中，上下文文件中的目录将覆盖命令行指定的值。

如果指定了-wdir选项，Open MPI将尝试在所有远程节点上切换到指定目录。如果失败，mpirun将中止执行。

如果未指定-wdir选项，Open MPI会将调用mpirun的目录名称发送到每个远程节点。远程节点将尝试切换到该目录。如果切换失败（例如，该节点上不存在该目录），则Open MPI将使用启动器确定的默认目录。

所有目录变更操作都在用户程序调用前完成；它不会等待直到MPI_INIT(3)被调用。

17.1.2.6.10. 标准输入/输出

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

Open MPI 将所有进程的UNIX标准输入重定向到/dev/null，除了MPI_COMM_WORLD中rank为0的进程。MPI_COMM_WORLD中rank为0的进程会从mpirun继承标准输入。

注意

调用mpirun的节点不必与MPI_COMM_WORLD中rank 0进程所在的节点相同。OpenMPI会处理将mpirun的标准输入重定向到rank 0进程的操作。

Open MPI 将远程节点的UNIX标准输出和错误信息重定向到调用mpirun的节点，并在mpirun的标准输出/错误中打印。本地进程会继承mpirun的标准输出/错误，并直接传输到其中。

因此，可以通过在mpirun上使用典型的shell重定向程序来重定向Open MPI应用程序的标准I/O。例如：

shell$ mpirun -n 2 my_app < my_input > my_output

请注意，在此示例中，只有MPI_COMM_WORLD的rank 0进程会从my_input接收标准输入流。所有其他节点的标准输入将被绑定到/dev/null。不过，所有节点的标准输出将被收集到my_output文件中。

17.1.2.6.11. 信号传播

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

当mpirun接收到SIGTERM和SIGINT信号时，它会尝试通过向作业中的所有进程发送SIGTERM信号来终止整个作业，等待几秒钟后，再向作业中的所有进程发送SIGKILL信号。

由mpirun接收到的SIGUSR1和SIGUSR2信号会被传播到作业中的所有进程。

向mpirun发送SIGTSTOP信号会导致向所有由mpirun启动的程序发送SIGSTOP信号，同样地，向mpirun发送SIGCONT信号也会触发SIGCONT信号的传递。

目前mpirun不会传播其他信号。

17.1.2.6.12. 进程终止/信号处理

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

在MPI应用程序运行期间，如果任何进程异常终止（无论是未调用MPI_FINALIZE(3)就退出，还是因信号而终止），mpirun将打印错误信息并终止其余MPI应用程序。

用户信号处理程序应尽量避免尝试清理MPI状态（Open MPI目前不具备异步信号安全性；有关MPI_THREAD_MULTIPLE和线程安全性的详细信息，请参阅MPI_INIT_THREAD(3)）。例如，如果在MPI_SEND(3)中发生段错误（可能是由于传入了错误缓冲区）并调用了用户信号处理程序，若该处理程序尝试调用MPI_FINALIZE(3)，则可能引发严重问题，因为错误发生时Open MPI已处于MPI上下文中。由于mpirun会检测到进程因信号终止，用户只需清理非MPI状态可能是最安全且不必要的做法。

17.1.2.6.13. 进程环境

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

MPI应用程序中的进程从其运行节点上的PRRTE守护进程继承环境变量。这些环境变量通常继承自用户的shell。在远程节点上，具体环境由所使用的启动MCA模块决定。例如，rsh启动模块通过rsh/ssh在远程节点上启动PRRTE守护进程，通常在启动PRRTE守护进程前会执行一个或多个用户的shell初始化文件。当运行需要设置LD_LIBRARY_PATH环境变量的动态链接应用程序时，必须注意确保在启动Open MPI时正确设置该变量。

更多详情请参阅远程执行章节。

17.1.2.6.14. 远程执行

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

Open MPI要求设置PATH环境变量以便在远程节点上查找可执行文件（通常仅在基于rsh或ssh的环境中需要——批处理/调度环境通常会将当前环境复制到远程作业执行中，因此如果当前环境已正确设置PATH和/或LD_LIBRARY_PATH，远程节点也会正确设置这些变量）。如果Open MPI编译时启用了共享库支持，可能还需要在远程节点上设置LD_LIBRARY_PATH环境变量（特别是为了找到运行用户MPI应用程序所需的共享库）。

然而，并不总是可取或能够通过编辑shell启动文件来设置PATH和/或LD_LIBRARY_PATH。为此，--prefix选项为某些无法修改配置文件的简单场景提供了解决方案。

--prefix 选项接受一个参数：远程节点上安装 Open MPI 的基础目录。Open MPI 将在执行任何 Open MPI 或用户应用程序之前，使用此目录设置远程节点的 PATH 和 LD_LIBRARY_PATH。这样可以在无需预先配置远程节点上的 PATH 和 LD_LIBRARY_PATH 的情况下运行 Open MPI 作业。

Open MPI会将当前节点$bindir（安装Open MPI可执行文件的目录）的基名添加到前缀中，并用于设置远程节点上的PATH。类似地，Open MPI会将当前节点$libdir（安装Open MPI库文件的目录）的基名添加到前缀中，并用于设置远程节点上的LD_LIBRARY_PATH。例如：

• 本地绑定目录: /local/node/directory/bin

• 本地库目录: /local/node/directory/lib64

如果使用以下命令行：

shell$ mpirun --prefix /remote/node/directory

Open MPI 将在尝试执行任何操作之前，将 /remote/node/directory/bin 添加到远程节点的 PATH 中，并将 /remote/node/directory/lib64 添加到 LD_LIBRARY_PATH 中。

如果远程节点上的安装路径与本地节点不同（例如，本地节点使用/lib而远程节点使用/lib64），或者安装路径不是公共前缀下的子目录，那么仅使用--prefix选项是不够的。

请注意，通过绝对路径执行mpirun等同于在mpirun的绝对路径中指定--prefix但不包含最后一个子目录。例如：

shell$ /usr/local/bin/mpirun ...

等同于

shell$ mpirun --prefix /usr/local

17.1.2.6.15. 导出的环境变量

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

所有以OMPI_*形式命名的环境变量将自动导出到本地和远程节点的新进程中。环境参数也可以通过MCA参数mca_base_env_list设置/转发到新进程。mpirun的-x选项已被弃用，但MCA参数的语法遵循之前的示例。虽然-x选项和MCA参数的语法允许定义新变量，但请注意这些选项的解析器目前并不十分复杂——它甚至无法理解带引号的值。建议用户在环境中设置变量并使用选项导出它们，而不是直接定义它们。

17.1.2.6.16. 设置MCA参数

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

--mca 开关允许向各种 MCA（模块化组件架构）模块传递参数。MCA 模块直接影响 MPI 程序的运行，因为它们允许在运行时设置可调参数（例如使用哪个 BTL 通信设备驱动程序、向该 BTL 传递哪些参数等）。

--mca 开关接受两个参数： 和 。 参数通常指定哪个MCA模块将接收该值。例如， btl 用于选择传输MPI消息时使用的BTL。 参数则是传递的具体值。例如：

shell$ mpirun --mca btl tcp,self -n 1 my_mpi_app

这表示Open MPI将使用tcp和self BTLs，并在分配的节点上运行my_mpi_app的单个实例。

shell$ mpirun --mca btl self -n 1 my_mpi_app

指示Open MPI使用self BTL，并在分配的节点上运行my_mpi_app的单个实例。

--mca 开关可以多次使用来指定不同的和/或参数。如果同一个被多次指定，则``s 会被用逗号 (,``)连接起来。

请注意，--mca开关只是设置环境变量的快捷方式。通过在运行mpirun之前设置相应的环境变量，可以达到相同的效果。Open MPI设置的环境变量格式为：

OMPI_MCA_<key>=<value>

因此，--mca开关会覆盖任何先前设置的环境变量。--mca设置同样会覆盖在$OPAL_PREFIX/etc/openmpi-mca-params.conf或$HOME/.openmpi/mca-params.conf文件中设置的MCA参数。

未知的参数仍会被设置为环境变量——mpirun不会检查这些参数的正确性。非法或错误的参数可能会被报告，也可能不会——这取决于具体的MCA模块。

要查找MCA架构下可用的组件类型，或查找特定组件的可用参数，请使用ompi_info命令。有关此命令的详细信息，请参阅ompi_info(1)手册页。

17.1.2.6.17. 从文件设置MCA参数和环境变量

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

--tune 命令行选项及其同义词 --mca mca_base_envar_file_prefix 允许用户按照以下描述的语法设置 MCA 参数和环境变量。此选项后面需要跟随单个文件或以“,”分隔的文件列表。

文件中的有效行可以包含零个或多个-x或 --mca。支持以下模式：

• --mca var val

• --mca var "val"

• -x var=val

• -x var

如果文件中存在重复参数，将使用最后读取的值。

在命令行中指定的MCA参数和环境变量优先级高于文件中指定的变量。

17.1.2.6.18. 以root身份运行

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

警告

Open MPI团队强烈建议不要以root用户身份执行mpirun。MPI应用程序应作为普通(非root)用户运行。

mpirun 默认会拒绝以root身份运行。

要覆盖此默认设置，您可以在mpirun命令行中添加--allow-run-as-root选项，或者设置环境参数OMPI_ALLOW_RUN_AS_ROOT=1和OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1。请注意，需要设置两个环境变量才能实现与--allow-run-as-root相同的效果，这是为了强调Open MPI团队强烈建议不要以root用户身份运行。

在与使用容器（默认以root用户运行）的社区进行深入讨论后，人们持续希望能够通过环境控制（而非现有的--allow-run-as-root命令行参数）来启用mpirun的root权限执行。最终达成使用两个环境变量的折衷方案：既允许通过环境控制实现root执行，同时也传达了Open MPI团队强烈不建议这种行为的立场。

17.1.2.6.19. 退出状态

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

对于mpirun应返回何种退出状态，目前尚无标准定义。经过大量讨论后，我们确定了以下方法来分配mpirun的退出状态（注意：在以下描述中，"primary"作业指由mpirun启动的初始应用程序——由该作业派生的所有作业均称为"secondary"作业）：

• 如果主作业中的所有进程正常终止且退出状态为0，mpirun将返回0。

• 如果主作业中的一个或多个进程通常以非零退出状态终止，mpirun将返回具有非零状态的进程中MPI_COMM_WORLD等级最低的那个进程的退出状态。

• 如果主作业中的所有进程正常终止且退出状态为0，而一个或多个次级作业中的进程正常终止但退出状态非零，mpirun：

  1. 返回具有最低jobid中最低MPI_COMM_WORLD等级且状态非零的进程的退出状态，并且

  2. 输出一条消息，汇总主作业和所有辅助作业的退出状态。

• 如果设置了命令行选项--report-child-jobs-separately， 我们将仅返回主作业的退出状态。任何 次级作业中的非零退出状态将仅在 摘要打印语句中报告。

默认情况下，当任何进程以非零状态终止时，作业将中止。可以通过将MCA参数--prtemca state_base_error_non_zero_exit设置为"false"（或"0"）来使Open MPI在一个或多个进程返回非零状态时不中止作业。在这种情况下，Open MPI会记录并标记进程以非零终止状态退出，以便根据上述要点报告mpirun的适当退出状态。

17.1.2.7. 示例

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

请务必也查看上面各节中的示例。

shell$ mpirun -n 4 --mca btl tcp,sm,self prog1

运行4份prog1程序副本，使用tcp、sm（共享内存）和self（进程回环）BTL作为MPI消息传输方式。

17.1.2.8. 返回值

这是旧的硬编码内容

此内容是否仍然准确/最新？应该更新保留还是移除？

mpirun 如果所有由mpirun启动的进程在调用MPI_FINALIZE(3)后退出，则返回0。如果mpirun内部发生错误，或有一个或多个进程在调用MPI_FINALIZE(3)前退出，则返回非零值。如果mpirun内部发生错误，将返回相应的错误代码。若有一个或多个进程在调用MPI_FINALIZE(3)前退出，则返回mpirun首先检测到的未调用MPI_FINALIZE(3)就退出的进程在MPI_COMM_WORLD中的秩值。请注意，通常情况下这会是第一个退出的进程，但并不保证总是如此。

如果使用了--timeout命令行选项，并且在作业完成前超时（从而强制mpirun终止作业），mpirun将返回等同于ETIMEDOUT值的退出状态（在Linux和OS X系统上通常为110）。

另请参阅

MPI_INIT(3), MPI_INIT_THREAD(3), MPI_FINALIZE(3), ompi_info(1)