# -*- text -*-
#
# Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
#                         University Research and Technology
#                         Corporation.  All rights reserved.
# Copyright (c) 2004-2005 The University of Tennessee and The University
#                         of Tennessee Research Foundation.  All rights
#                         reserved.
# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
#                         University of Stuttgart.  All rights reserved.
# Copyright (c) 2004-2005 The Regents of the University of California.
#                         All rights reserved.
# Copyright (c) 2011-2020 Cisco Systems, Inc.  All rights reserved
# Copyright (c) 2011      Los Alamos National Security, LLC.
#                         All rights reserved.
# Copyright (c) 2014-2020 Intel, Inc.  All rights reserved.
# Copyright (c) 2021-2026 Nanook Consulting  All rights reserved.
# $COPYRIGHT$
#
# Additional copyrights may follow
#
# $HEADER$
#
# This is the US/English general help file for PRRTE's prun.
#
[bind-to]

By default, processes are bound to individual CPUs (either COREs or
HWTHREADs, as defined by default or by user specification for the
job). On nodes that are OVERSUBSCRIBEd (i.e., where the number of
procs exceeds the number of assigned slots), the default is to not
bind the processes.

Note:

  Processes from prior jobs that are already executing on a node are
  not "unbound" when a new job mapping results in the node becoming
  oversubscribed.

Binding is performed to the first available specified object type
within the object where the process was mapped. In other words,
binding can only be done to the mapped object or to a resource located
beneath that object.

An object is considered completely consumed when the number of
processes bound to it equals the number of CPUs within it. Unbound
processes are not considered in this computation. Additional processes
cannot be mapped to consumed objects unless the "OVERLOAD" qualifier
is provided via the "--bind-to" command line option.

Note that directives and qualifiers are case-insensitive and can be
shortened to the minimum number of characters to uniquely identify
them. Thus, "L1CACHE" can be given as "l1cache" or simply as "L1".

Supported binding directives include:

* "NONE" does not bind the processes

* "HWTHREAD" binds each process to a single hardware thread/ This
  requires that hwthreads be treated as independent CPUs (i.e., that
  either the "HWTCPUS" qualifier be provided to the "map-by" option or
  that "hwthreads" be designated as CPUs by default).

* "CORE" binds each process to a single core. This can be done whether
  "hwthreads" or "cores" are being treated as independent CPUs
  provided that mapping is performed at the core or higher level.

* "L1CACHE" binds each process to all the CPUs in an "L1" cache.

* "L2CACHE" binds each process to all the CPUs in an "L2" cache

* "L3CACHE" binds each process to all the CPUs in an "L3" cache

* "NUMA" binds each process to all the CPUs in a "NUMA" region

* "PACKAGE" binds each process to all the CPUs in a "PACKAGE"

Any directive can include qualifiers by adding a colon (:) and any
combination of one or more of the following to the "--bind-to" option:

* "OVERLOAD" indicates that objects can have more processes bound to
  them than CPUs within them

* "IF-SUPPORTED" indicates that the job should continue to be launched
  and executed even if binding cannot be performed as requested.

* "LIMIT=n" limits the number of processes bound to each eligible
  representative of the specified type to the given number. For
  example, speifying "--bind-to l3:limit=2" would direct PRRTE
  to bind ranks to the L3caches, limiting the number of processes
  bound to each l3cache to two - i.e., bind 2 processes to a
  given l3cache, and then move on to the next.

Note:

  Directives and qualifiers are case-insensitive. "OVERLOAD" is the
  same as "overload".

A more detailed description of the mapping, ranking, and binding
procedure can be obtained via the "--help placement" option.
