# -*- text -*-
#
# Copyright (c) 2025-2026 Nanook Consulting  All rights reserved.
# $COPYRIGHT$
#
# Additional copyrights may follow
#
# $HEADER$
#
# This is the US/English general help file for PRTE's dash-host.
#
[hostfile]

PRRTE supports several levels of user-specified hostfiles based on an
established precedence order. Users can specify a hostfile that
contains a list of nodes to be used for the job, or can provide a
comma-delimited list of nodes to be used for that job via the "--host"
command line option.

The precedence order applied to these various options depends to some
extent on the local environment. The following table illustrates how
host and hostfile directives work together to define the set of hosts
upon which a DVM will execute the job in the absence of a resource
manager (RM):

+---------+------------+-----------------------------------------------+
| host    | hostfile   | Result                                        |
|=========|============|===============================================|
| unset   | unset      | The DVM will utilize all its available        |
|         |            | resources when mapping the job.               |
+---------+------------+-----------------------------------------------+
| set     | unset      | Host option defines resource list for the job |
+---------+------------+-----------------------------------------------+
| unset   | set        | Hostfile defines resource list for the job    |
+---------+------------+-----------------------------------------------+
| set     | set        | Hostfile defines resource list for the job,   |
|         |            | then host filters the list to define the      |
|         |            | final set of nodes to be used for the job     |
+---------+------------+-----------------------------------------------+

Hostfiles (sometimes called "machine files") are a combination of two
things:

1. A listing of hosts on which to launch processes.

2. Optionally, limit the number of processes which can be launched on
   each host.

Hostfile syntax consists of one node name on each line, optionally
including a designated number of "slots":

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

   node15
   node16
   node17  slots=3
   ...

Blank lines and lines beginning with a "#" are ignored.

A "slot" is the PRRTE term for an allocatable unit where we can launch
a process.  See the section on definition of the term "slot" for a
longer description of slots.

In the absence of the "slot" parameter, PRRTE will assign either the
number of slots to be the number of CPUs detected on the node or the
resource manager-assigned value if operating in the presence of an RM.

Important:

  If using a resource manager, the user-specified number of slots is
  capped by the RM-assigned value.


Relative host indexing
----------------------

Hostfile and "--host" specifications can also be made using relative
indexing. This allows a user to stipulate which hosts are to be used
for a given app context without specifying the particular host name,
but rather its relative position in the allocation.

This can probably best be understood through consideration of a few
examples. Consider the case where a DVM is comprised of a set of nodes
named "foo1", "foo2", "foo3", "foo4". The user wants the first app
context to have exclusive use of the first two nodes, and a second app
context to use the last two nodes. Of course, the user could printout
the allocation to find the names of the nodes allocated to them and
then use "--host" to specify this layout, but this is cumbersome and
would require hand-manipulation for every invocation.

A simpler method is to utilize PRRTE's relative indexing capability to
specify the desired layout. In this case, a command line containing:

   --host +n1,+n2 ./app1 : --host +n3,+n4 ./app2

would provide the desired pattern. The "+" syntax indicates that the
information is being provided as a relative index into the existing
allocation. Two methods of relative indexing are supported:

* "+n#": A relative index into the allocation referencing the "#"
  node. PRRTE will substitute the "#" node in the allocation

* "+e[:#]": A request for "#" empty nodes — i.e., PRRTE is to
  substitute this reference with nodes that have not yet been used by
  any other app_context. If the ":#" is not provided, PRRTE will
  substitute the reference with all empty nodes. Note that PRRTE does
  track the empty nodes that have been assigned in this manner, so
  multiple uses of this option will result in assignment of unique
  nodes up to the limit of the available empty nodes. Requests for
  more empty nodes than are available will generate an error.

Relative indexing can be combined with absolute naming of hosts in any
arbitrary manner, and can be used in hostfiles as well as with the "--
host" command line option. In addition, any slot specification
provided in hostfiles will be respected — thus, a user can specify
that only a certain number of slots from a relative indexed host are
to be used for a given app context.

Another example may help illustrate this point. Consider the case
where the user has a hostfile containing:

   dummy1 slots=4
   dummy2 slots=4
   dummy3 slots=4
   dummy4 slots=4
   dummy5 slots=4

This may, for example, be a hostfile that describes a set of commonly-
used resources that the user wishes to execute applications against.
For this particular application, the user plans to map byslot, and
wants the first two ranks to be on the second node of any allocation,
the next ranks to land on an empty node, have one rank specifically on
"dummy4", the next rank to be on the second node of the allocation
again, and finally any remaining ranks to be on whatever empty nodes
are left. To accomplish this, the user provides a hostfile of:

   +n2 slots=2
   +e:1
   dummy4 slots=1
   +n2
   +e

The user can now use this information in combination with PRRTE's
sequential mapper to obtain their specific layout:

   <launcher> --hostfile dummyhosts --hostfile mylayout --map-by seq ./my_app

which will result in:

   rank0 being mapped to dummy3
   rank1 to dummy1 as the first empty node
   rank2 to dummy4
   rank3 to dummy3
   rank4 to dummy2 and rank5 to dummy5 as the last remaining unused nodes

Note that the sequential mapper ignores the number of slots arguments
as it only maps one rank at a time to each node in the list.

If the default round-robin mapper had been used, then the mapping
would have resulted in:

* ranks 0 and 1 being mapped to dummy3 since two slots were specified

* ranks 2-5 on dummy1 as the first empty node, which has four slots

* rank6 on dummy4 since the hostfile specifies only a single slot from
  that node is to be used

* ranks 7 and 8 on dummy3 since only two slots remain available

* ranks 9-12 on dummy2 since it is the next available empty node and
  has four slots

* ranks 13-16 on dummy5 since it is the last remaining unused node and
  has four slots

Thus, the use of relative indexing can allow for complex mappings to
be ported across allocations, including those obtained from automated
resource managers, without the need for manual manipulation of scripts
and/or command lines.

See the "Host specification" HTML documentation for details about the
format and content of hostfiles.
#
[machinefile]

This option is a synonym for "--hostfile".

#include#help-hostfile.txt#hostfile

#
[host]

Host syntax consists of a comma-delimited list of node names, each
entry optionally containing a ":N" extension indicating the number of
slots to assign to that entry:

   --host node01:5,node02

In the absence of the slot extension, one slot will be assigned to the
node. Duplicate entries are aggregated and the number of slots
assigned to that node are summed together.

Note:

  A "slot" is the PRRTE term for an allocatable unit where we can
  launch a process. Thus, the number of slots equates to the maximum
  number of processes PRRTE may start on that node without
  oversubscribing it.
#
[add-hostfile]

PRRTE allows a user to expand an existing DVM prior to launching an
application.  Users can specify a hostfile that contains a list of
nodes to be added to the DVM using normal hostfile syntax.

The list can include nodes that are already part of the DVM — in this
case, the number of slots available on those nodes will be set to the
new specification, or adjusted as directed:

   node01  slots=5

would direct that node01 be set to 5 slots, while

   node01 slots+=5

would add 5 slots to the current value for node01, and

   node01  slots-=5

would subtract 5 slots from the current value.

Slot adjustments for existing nodes will have no impact on currently
executing jobs, but will be applied to any new spawn requests. Nodes
contained in the add-hostfile specification are available for
immediate use by the accompanying application.

Users desiring to constrain the accompanying application to the newly
added nodes should also include the "--hostfile" command line
directive, giving the same hostfile as its argument:

   --add-hostfile <filename> --hostfile <filename>
#
[no-hostfile]

PRTE was unable to open the hostfile:

   %s

Check to make sure the path and filename are correct.
#
[port]

PRTE detected a bad parameter in the hostfile:

   %s

The port parameter is less than 0:

   port=%d
#
[slots]

PRTE detected a bad parameter in the hostfile:

   %s

The slots parameter is less than 0:

   slots=%d
#
[max_slots]

PRTE detected a bad parameter in the hostfile:

   %s

The max_slots parameter is less than 0:

   max_slots=%d
#
[max_slots_lt]

PRTE detected a bad parameter in the hostfile:

   %s

The max_slots parameter is less than the slots parameter:

   slots=%d
   max_slots=%d
#
[parse_error_string]

PRTE detected a parse error in the hostfile:

   %s

It occured on line number %d on token %d:

   %s
#
[parse_error_int]

PRTE detected a parse error in the hostfile:

   %s

It occured on line number %d on token %d:

   %d
#
[parse_error]

PRTE detected a parse error in the hostfile:

   %s

It occured on line number %d on token %d.
#
[not-all-mapped-alloc]

Some of the requested hosts are not included in the current
allocation.

The requested hosts were in this hostfile:

      %s

Please verify that you have specified the allocated resources properly
in the provided hostfile.
#
[hostfile:relative-syntax]

A relative host was specified, but no prior allocation has been made.
Thus, there is no way to determine the proper host to be used.

   hostfile entry: %s

Re-run this command with "--help hosts" for further information.
#
[hostfile:relative-node-not-found]

A relative host was specified, but was not found. The requested host
was specified as:

   Index: %d
   Syntax given: %s

This is most likely due to the relative index being out of bounds. You
could obtain a larger allocation or reduce the relative host index.

Re-run this command with "--help hosts" for further information.

[hostfile:invalid-relative-node-syntax]

A relative host was improperly specified — the value provided was.

   hostfile entry: %s

You may have forgotten to preface a node with "N" or "n", or used the
"e" or "E" to indicate empty nodes.

Re-run this command with "--help hosts" for further information.
#
[hostfile:not-enough-empty]

The requested number of empty hosts was not available — the system was
short by %d hosts.  Please recheck your allocation.

Re-run this command with "--help hosts" for further information.
#
[hostfile:extra-node-not-found]

A hostfile was provided that contains at least one node not present in
the allocation:

   hostfile:  %s
   node:      %s

If you are operating in a resource-managed environment, then only
nodes that are in the allocation can be used in the hostfile. You may
find relative node syntax to be a useful alternative to specifying
absolute node names; re-run this command with "--help hosts" for
further information.
#
[slots-given]

A hostfile was provided that contains multiple definitions of the slot
count for at least one node:

   hostfile:  %s
   node:      %s

You can either list a node multiple times, once for each slot, or you
can provide a single line that contains "slot=N". Mixing the two
methods is not supported.

Please correct the hostfile and try again.
