id       = "open-mpi"
name     = "Open MPI"
homepage = "https://www.open-mpi.org"
description = "A high performance message passing library."
executables   = ["mpirun", "mpiexec", "ompi_info"]

[dotfiles]

# Open MPI's official MCA documentation (https://docs.open-mpi.org/en/main/
# mca.html) names $HOME/.openmpi/mca-params.conf as the highest-precedence
# user-supplied parameter file. The installation-prefix file is system-level
# and is deliberately not included.
paths = ["~/.openmpi/mca-params.conf"]

exclude = []
secret = []
side_effect = false

[commands]
format = 1
label = "Run an MPI program"
description = "Launch copies of a program with mpirun, choosing process count, hosts, mapping and binding. MCA parameters, PMIx/PRRTE tuning, debugging and fault-tolerance options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "posix", long_equals = false, short_attached = false, short_bundles = false }

[[commands.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/openmpi-bin/mpirun.1.en.html"
revision = "Open MPI mpirun(1), Debian unstable"
evidence = """
-n, --n, -c, -np <#>: Run this many copies of the program on the given nodes.
mpirun --np 4 --report-bindings --map-by core --bind-to core
-H | --host <list>: Comma-delimited list of hosts on which to to invoke processes.
--hostfile <filename>: Provide a hostfile. See below for details.
--map-by <value>: Controls how processes are distributed within a host.
--rank-by <value>: Controls how processes are ordered in MPI_COMM_WORLD.
--bind-to <value>: Controls the resources to which processes are bound within a host.
--oversubscribe: Nodes are allowed to be oversubscribed, even on a managed system
--report-bindings: Report any bindings for launched processes.
--wdir <dir>: Set the working directory of the started processes.
-x <var>: Export an environment variable, optionally specifying a value.
--timeout <seconds>: Timeout the job after the specified number of seconds.
--output <list>: Comma-delimited list of options that control how output is generated.
-v | --verbose: Enable extra verbose output
"""

[[commands.field]]
id = "np"
label = "Number of processes"
type = "integer"
option = ["--np", "-n"]
validation = { min = 1 }
sources = ["man"]

[[commands.field]]
id = "host"
label = "Hosts"
description = "Comma-delimited host list, optionally with slot counts, e.g. hostA:4,hostB:2."
type = "string"
option = ["--host", "-H"]
sources = ["man"]

[[commands.field]]
id = "hostfile"
label = "Hostfile"
type = "path"
option = ["--hostfile"]
path = { kind = "file", role = "input" }
sources = ["man"]

[[commands.field]]
id = "map_by"
label = "Map by"
description = "How processes are distributed within a host, e.g. core, package, slot:PE=2."
type = "string"
option = ["--map-by"]
sources = ["man"]

[[commands.field]]
id = "rank_by"
label = "Rank by"
type = "string"
option = ["--rank-by"]
sources = ["man"]

[[commands.field]]
id = "bind_to"
label = "Bind to"
type = "string"
option = ["--bind-to"]
suggestions = [{ value = "core", label = "Core" }, { value = "package", label = "Package" }, { value = "none", label = "None" }]
sources = ["man"]

[[commands.field]]
id = "report_bindings"
label = "Report bindings"
type = "boolean"
option = ["--report-bindings"]
sources = ["man"]

[[commands.field]]
id = "oversubscribe"
label = "Allow oversubscription"
type = "boolean"
option = ["--oversubscribe"]
sources = ["man"]

[[commands.field]]
id = "wdir"
label = "Working directory"
type = "path"
option = ["--wdir"]
path = { kind = "directory", role = "input" }
sources = ["man"]

[[commands.field]]
id = "export_env"
label = "Export environment variable"
description = "Variable name, or NAME=value."
type = "string"
option = ["-x"]
multiple = true
sources = ["man"]

[[commands.field]]
id = "timeout"
label = "Timeout (seconds)"
type = "integer"
option = ["--timeout"]
validation = { min = 1 }
sources = ["man"]

[[commands.field]]
id = "verbose"
label = "Verbose"
type = "boolean"
option = ["--verbose"]
sources = ["man"]

[[commands.field]]
id = "program"
label = "Program"
type = "string"
position = 0
sources = ["man"]

[[commands.field]]
id = "program_args"
label = "Program arguments"
type = "string"
position = 1
multiple = true
sources = ["man"]

[[commands.task]]
id = "run"
label = "Run on this machine"
fields = ["np", "program", "program_args"]
required = ["np", "program"]

[[commands.task]]
id = "cluster"
label = "Run across hosts"
fields = ["np", "host", "hostfile", "program", "program_args"]
required = ["np", "program"]

[[commands.task]]
id = "bindings"
label = "Check process placement"
fields = ["np", "map_by", "bind_to", "report_bindings", "program", "program_args"]
required = ["np", "program"]
set = { report_bindings = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["np", "host", "hostfile", "program", "program_args"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["map_by", "rank_by", "bind_to", "report_bindings", "oversubscribe", "wdir", "export_env", "timeout", "verbose"]