Scyld ClusterWare HPC: Reference Guide
<< PreviousNext >>

beomap

Name

beomap -- Show a job map from the beomap scheduler.

Synopsis

beomap [-h, --help] [-V, --version] [--map node list] [--all-cpus] [--all-nodes] [--np processes] [--all-local]
[--no-local] [--exclude node list]

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, mpirun, 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.

Job Map Parameters

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, with their equivalent environment variables; note that the command line options take precedence over the environment variables.

All of the beomap job map parameters listed below can also be used directly with beorun, mpirun, and mpprun.

--map node list

Specify a process map consisting of a colon-delimited list of nodes. Each node in the list indicates where one process will be assigned. The number of entries in the job map implies the number of ranks in the job.

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 assign more processes to a node than it has processors or cores.

The --all-cpus, --all-nodes, --np processes, --all-local, --no-local, and --exclude parameters are not specified with the --map parameter.

The equivalent environment variable is BEOWULF_JOB_MAP=node list.

--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 specified with the --map parameter.

The equivalent environment variable is ALL_CPUS.

--all-nodes

Create a process map consisting of all "up" nodes, with 1 CPU mapped on each of the "up" nodes. This parameter is not specified with the --map parameter.

The equivalent environment variable is ALL_NODES.

NOTE: --all-nodes and ALL_NODES do not currently work as intended; this is a known issue in ClusterWare 4.1.0. Refer to the Release Notes for suggested workarounds.

--np processes

Specify the number of processes to run. The beomap command attempts to place one process per processor or core, but will assign multiple processes per processor or core if there are not enough individual processors or cores available. This parameter is not specified with the --map parameter.

The equivalent environment variable is NP=processes.

--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 for everything. This parameter is not specified with the --map parameter.

This option is a handy shortcut for troubleshooting connectivity problems or testing on an isolated head node before running a job on a "live" cluster.

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 -1 in the --exclude node list option. For MPI jobs, this option puts the "rank 0" job on a compute node instead of the master. This parameter is not specified with the --map parameter.

The equivalent environment variable is NO_LOCAL.

--exclude node list

Do not include the listed nodes in the process map; the nodes to be excluded are stated as a colon-delimited list. This parameter is not specified with the --map parameter.

The equivalent environment variable is EXCLUDE=node list.

Tip

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, the following priorities apply:

  • Three of the environment variables determine how many ranks to schedule in the map: ALL_CPUS (priority 1), ALL_NODES (priority 2), and NP (priority 3). If none of these are set explicitly by the user, then a usage of NP=1 is assumed.

  • Three of the environment variables determine what node numbers are candidates for being mapped: ALL_LOCAL (priority 1), NO_LOCAL (priority 2), and EXCLUDE (priority 3).

Caution

It is an error to use NO_LOCAL and ALL_LOCAL together. If both are used, ALL_LOCAL will take 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, 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.

See Also

beorun(1), bpsh(1), beostatus(1), beonpc(1), mpprun(1), and the User's Guide.

<< PreviousHomeNext >>
beoconfigUpbeonetconf