beomap¶
Name¶
beomap -- Show a job map from the beomap scheduler.
Synopsis¶
beomap [-h, --help] [-V, --version] [--all-cpus] [--all-nodes] [--all-local] [--no-local] [--map nodelist] [--exclude nodelist] [--np num-processes]
Description¶
This program retrieves a job map from the currently installed beomap
scheduler. This is the same job map that would be used by an integrated
application (such as beorun or mpprun) started with
the same scheduling parameters at that instant in time.
The beomap command may be used to generate a job map for applications that do not have their own scheduler interface, in scripts, or to examine the current scheduling state of the system.
You can influence the job map either by setting environment variables or by entering command line options. Note that command-line options take precedence over the environment variable settings.
Options¶
The following general command line options are available to beomap. Also see the next section, which describes the job map parameters.
-h, --help | Print the command usage message and exit. If -h is in the option
list, all other options will be ignored. |
-V, --version | Print the command version number and exit. Any other options will be parsed and handled. |
You can influence the beomap job map either by entering command line options or by setting environment variables. Following are the available command line options, together with their equivalent environment variables. Note that the command line options take precedence over the environment variables.
All the beomap job map parameters listed below can also be used directly with beorun and mpprun.
--all-cpus | Create a process map consisting of all "up" nodes, with each node number
repeated to represent the number of CPUs on that node. This parameter
is not allowed in conjunction with the --map parameter. |
--all-nodes | Create a process map consisting of all "up" nodes, with one CPU mapped on
each of the "up" nodes. This parameter is not allowed in conjunction with
the The equivalent environment variable is ALL_NODES. |
--all-local | Create a process map consisting entirely of master node entries. This option eliminates everything except node -1 from the pool of candidate node numbers, thus forcing the map to use node -1 (the master node) for everything. The equivalent environment variable is ALL_LOCAL. |
--no-local | Exclude the master in the process map. This option is essentially a
syntactic shortcut for including The equivalent environment variable is NO_LOCAL. |
--exclude nodelist | |
Build a process map that excludes listed nodes. The The equivalent environment variable is EXCLUDE=nodelist. | |
--map nodelist | Explicitly specify a process map consisting of a colon-delimited list of
nodes. Each node in Listing a node more than once in the list will assign multiple processes to that node. Typically, this is done to assign one process to each processor (or core) on a node, but this can also be used to "oversubscribe", i.e., to assign more processes to a node than it has processors (or cores). The equivalent environment variable is BEOWULF_JOB_MAP=nodelist. |
--np num-processes | |
Specify the number of processes to run. The beomap command attempts to
place one process per processor (or core), but will "oversubscribe" and
assign multiple processes per processor (or core) if there are not enough
individual processors or cores available. This parameter is not allowed in
conjunction with the The equivalent environment variable is NP=num-processes. |
The environment variables have an order of priority. The BEOWULF_JOB_MAP variable acts as a "master override" for the other environment variables. If BEOWULF_JOB_MAP is not set, then the following priorities apply:
Three of the environment variables determine how many ranks to schedule in the map: (1) ALL_CPUS, (2) ALL_NODES, and (3) NP. If none of these are set explicitly by the user, then NP=1 is the default.
Three of the environment variables determine what node numbers are candidates for being mapped: (1) ALL_LOCAL, (2) NO_LOCAL, and (3) EXCLUDE.
Note: it is improper to use NO_LOCAL and ALL_LOCAL together. If both are used, then ALL_LOCAL takes precedence.
Examples¶
Find the set of machines available for use:
[user@cluster ~] $ beomap --all-cpus
-1:0:1:2:3:4:5:6:7:8:9:10:11:12:13:14:15
Create a process map to run 20 processes on a cluster with 10 idle dual-processor compute nodes:
[user@cluster user] $ beomap --np 20
-1:0:0:1:1:2:2:3:3:4:4:5:5:6:6:7:7:8:8:9
Note: Since --no-local
was not specified, then the master node
(listed as "-1") is included in the map, and node 9 is listed only once.
Select an available machine to start up an application, while handling application termination or machine failure; note that the following works only for the sh family of shells (bash):
[user@cluster user] $ while :; do export NODE=`beomap --no-local -np 1`; bpsh $NODE application-to-run; done
Provide an explicit map to run 5 processes on node 0:
[user@cluster user] $ beomap --np 5 --map 0:0:0:0:0
Special Notes¶
The underlying beomap system calls pluggable schedulers, which may
use arbitrary scheduling inputs. The command line options replace and
delete environment variables used by the Scyld-provided default
schedulers/mappers, but other schedulers are free to ignore these
advisory settings. Specifically, the beomap command does not confirm
that the parameters, such as --no-local
, are true in the resulting
job map.