Checkpoint adding back the host and remaining placement detail

Signed-off-by: Ralph Castain <[email protected]>

docs/hosts/cli.rst

@@ -1,36 +1 @@
-.. _hosts-cli-label:
-
-Listing Hosts on the Command Line
-=================================
-
-Many PRRTE commands accept the ``--host`` CLI parameter.
-``--host`` accepts a comma-delimited list of tokens of the form:
-
-.. code::
-
-   host[:slots]
-
-The ``host`` token can be either:
-
-* A name that resolves to an IP address, or
-* An IP address
-
-.. note:: The names and/or IP addresses of hosts are *only* used for
-          identifying the target host on which to launch.  They are
-          *not* used for determining which network interfaces are used
-          by applications (e.g., MPI or other network-based
-          applications).
-
-          For network-based applications, consult their documentation
-          for how to specify which network interfaces are used.
-
-The optional integer ``:slots`` parameter tells PRRTE the maximum
-number of slots to use on that host (:ref:`see this section
-<placement-definition-of-slot-label>` for a description of what a
-"slot" is).
-
-For example:
-
-.. code::
-
-   prterun --host node1:10,node2,node3:5 ...
+.. include:: /prrte-rst-content/detail-hosts-cli.rst

docs/hosts/hostfiles.rst

@@ -1,41 +1 @@
-Hostfiles
-=========
-
-Hostfiles (sometimes called "machine files") are a combination of two
-things:
-
-#. A listing of hosts on which to launch processes.
-#. Optionally, limit the number of processes which can be launched on
-   each host.
-
-Syntax
-------
-
-Hostfile syntax consists of one node name on each line, optionally
-including a designated number of "slots":
-
-.. code:: sh
-
-   # 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.  :ref:`See this section
-<placement-definition-of-slot-label>` 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.
+.. include:: /prrte-rst-content/detail-hostfiles.rst

docs/hosts/relative-indexing.rst

@@ -1,113 +1 @@
-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:
-
-.. code::
-
-   --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 |mdash| 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 |mdash| 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:
-
-.. code::
-
-   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:
-
-.. code::
-
-   +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:
-
-.. code::
-
-   <launcher> --hostfile dummyhosts --hostfile mylayout --prtemca rmaps seq ./my_app
-
-which will result in:
-
-.. code::
-
-   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.
+.. include:: /prrte-rst-content/detail-hosts-relative-indexing.rst

docs/hosts/rm.rst

@@ -1,9 +1 @@
-Resource Manager-Provided Hosts
-===============================
-
-When launching under a Resource Manager (RM), the RM usually
-picks which hosts |mdash| and how many processes can be launched on
-each host |mdash| on a per-job basis.
-
-The RM will communicate this information to PRRTE directly; users can
-simply omit specifying hosts or numbers of processes.
+.. include:: /prrte-rst-content/detail-hosts-rm.rst

docs/placement/deprecated.rst

@@ -1,141 +1 @@
-Deprecated options
-==================
-
-These deprecated options will be removed in a future release.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 20 20 30
-
-   * - Deprecated Option
-     - Replacement
-     - Description
-
-   * - ``--bind-to-core``
-     - ``--bind-to core``
-     - Bind processes to cores
-
-
-   * - ``--bind-to-socket``
-     - ``--bind-to package``
-     - Bind processes to processor sockets
-
-   * - ``--bycore``
-     - ``--map-by core``
-     - Map processes by core
-
-   * - ``--bynode``
-     - ``--map-by node``
-     - Launch processes one per node, cycling by node in a round-robin
-       fashion. This spreads processes evenly among nodes and assigns
-       ranks in a round-robin, "by node" manner.
-
-   * - ``--byslot``
-     - ``--map-by slot``
-     - Map and rank processes round-robin by slot
-
-   * - ``--cpus-per-proc <#perproc>``
-     - `--map-by <obj>:PE=<#perproc>``
-     - Bind each process to the specified number of CPUs
-
-   * - ``--cpus-per-rank <#perrank>``
-     - ``--map-by <obj>:PE=<#perrank>``
-     - Alias for ``--cpus-per-proc``
-
-   * - ``--display-allocation``
-     - ``--display ALLOC``
-     - Display the detected resource allocation
-
-   * - ``-display-devel-map``
-     - ``--display MAP-DEVEL``
-     - Display a detailed process map (mostly intended for developers)
-       just before launch.
-
-   * - ``--display-map``
-     - ``--display MAP``
-     - Display a table showing the mapped location of each process
-       prior to launch.
-
-   * - ``--display-topo``
-     - ``--display TOPO``
-     - Display the topology as part of the process map (mostly
-       intended for developers) just before launch.
-
-   * - ``--do-not-launch``
-     - ``--map-by :DONOTLAUNCH``
-     - Perform all necessary operations to prepare to launch the
-       application, but do not actually launch it (usually used to
-       test mapping patterns).
-
-   * - ``--do-not-resolve``
-     - ``--map-by :DONOTRESOLVE``
-     - Do not attempt to resolve interfaces |mdash| usually used to
-       determine proposed process placement/binding prior to obtaining
-       an allocation.
-
-   * - ``-N <num>``
-     - ``--map-by prr:<num>:node``
-     - Launch ``num`` processes per node on all allocated nodes
-
-   * - ``--nolocal``
-     - ``--map-by :NOLOCAL``
-     - Do not run any copies of the launched application on the same
-       node as ``prun`` is running. This option will override listing
-       the ``localhost`` with ``--host`` or any other host-specifying
-       mechanism.
-
-   * - ``--nooversubscribe``
-     - ``--map-by :NOOVERSUBSCRIBE``
-     - Do not oversubscribe any nodes; error (without starting any
-       processes) if the requested number of processes would cause
-       oversubscription. This option implicitly sets "max_slots" equal
-       to the "slots" value for each node. (Enabled by default).
-
-   * - ``--npernode <#pernode>``
-     - ``--map-by ppr:<#pernode>:node``
-     - On each node, launch this many processes
-
-   * - ``--npersocket <#persocket>``
-     - ``--map-by ppr:<#perpackage>:package``
-     - On each node, launch this many processes times the number of
-       processor sockets on the node. The ``--npersocket`` option also
-       turns on the ``--bind-to socket`` option. The term ``socket``
-       has been globally replaced with ``package``.
-
-   * - ``--oversubscribe``
-     - ``--map-by :OVERSUBSCRIBE``
-     - Nodes are allowed to be oversubscribed, even on a managed
-       system, and overloading of processing elements.
-
-   * - ``--pernode``
-     - ``--map-by ppr:1:node``
-     - On each node, launch one process
-
-   * - ``--ppr``
-     - `--map-by ppr:<list>``
-     - Comma-separated list of number of processes on a given resource type
-       [default: ``none``].
-
-   * - ``--rankfile <FILENAME>``
-     - ``--map-by rankfile:FILE=<FILENAME>``
-     - Use a rankfile for mapping/ranking/binding
-
-   * - ``--report-bindings``
-     - ``--display BINDINGS``
-     - Report any bindings for launched processes
-
-   * - ``--tag-output``
-     - ``--output TAG``
-     - Tag all output with ``[job,rank]``
-
-   * - ``--timestamp-output``
-     - ``--output TIMESTAMP``
-     - Timestamp all application process output
-
-   * - ``--use-hwthread-cpus``
-     - ``--map-by :HWTCPUS``
-     - Use hardware threads as independent CPUs
-
-   * - ``--xml``
-     - ``--output XML``
-     - Provide all output in XML format
+.. include:: /prrte-rst-content/detail-placement-deprecated.rst