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


beomap [-h, --help] [-V, --version] [--np processes ] [--allcpus, --all-cpus] [--all-local] [--no-local, --nolocal]
[--exclude node list ] [--beowulf-job-map node list ] [--map node list ]


This program retrieves a Beowulf job map from the currently installed BeoMap scheduler. This is the same job map that would be used by an integrated application, for instance a BeoMPI application, started with the same scheduling parameter at that instant in time.

The beomap command may be used to generate a schedule for applications that do not have their own scheduler interface, in scripts, or to examine the current scheduling state of the system.

Both command-line options and environment variables influence the resulting job map. Command-line options take precedence over the environment variable settings.


The following options are available to the beomap program.


Print the command usage message and exit. If -h is in the option list, all other options will be ignored.


Print the command version number and exit. Any other options will be parsed and handled.

-np processes

Specify the number of processes to run. beomap attempts to place one process per processor or core, but will asign multiple processes per processor or core if there are not enough individual processors or cores available.

-no-local, --nolocal

Do not include the master in the process map. For MPI jobs, this puts the "rank 0" job on a compute node instead of the master. This parameter is not specified with the --map parameter.


Create a process map consisting entirely of master node entries. This parameter is not specified with the --map parameter.


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.

--exclude node list

Do not include the listed nodes in the process map. This parameter is not specified with the --map parameter.

--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. Note the following:

  • The number of items in the list must be equal to the number of processes requested in the -np parameter. For an MPI job, the first node in the list will be where the "rank 0" job runs.

  • Listing a node more than once in the list will assign multiple processes to that node. Typically, this is done to asign 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 -no-local, -all-local, -all-cpus and --exclude parameters are not specified with the --map parameter.


Find the set of machines available for use:

[user@cluster user]$ beomap --all-cpus

Create a process map for 10 processes on a cluster consisting of idle dual processor compute nodes:

[user@cluster user]$ beomap --np 10

Select an available machine to start up an application, while handling application termination or machine failure:

[user@cluster user]$ while true; do
	NODE=`beomap --no-local --np 1'
	bpsh $NODE application-to-run

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 nolocal, are true in the resulting job map.

See Also

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