beorun

Name

beorun – Run a job on a Scyld cluster using dynamically selected nodes.

Synopsis

beorun [-h, –help] [-V, –version] [–all-cpus] [–all-nodes] [–all-local] [–no-local] [–map nodelist] [–exclude nodelist] [–np processes] command [command-args…]

Description

The beorun program runs the specified program on a dynamically selected set of cluster nodes. It generates a job map from the currently installed beomap scheduler, and starts the program on each node specified in the map. The scheduling parameters from the command line and environment are the same as for beomap, and the resulting job map is identical to the job map that beomap would if generate at that instant in time for that program name.

The beorun command may be used to start applications that are not cluster-aware or do not have their own scheduler interface.

Options

The following general command line options are available to beorun. Also see the next section, which describes the beomap job map parameters.

-h, --help, -u, --usage

Print the command usage message on stdout and exit. When one of these options is recognized in the option list, all following options will be ignored.

-V

Print the command version number on stdout and exit. Any following options will be ignored.

You can influence the beorun 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 beorun job map parameters listed below can also be used directly with beomap 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 --map parameter.

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

The equivalent environment variable is NO_LOCAL.

--exclude nodelist

Build a process map that excludes listed nodes. The nodelist consists of a colon-delimited list. This parameter is not allowed in conjunction with the --map parameter.

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 nodelist 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 “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 beorun 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 --map parameter.

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.

Unrecognized options and invalid option formats are reported on stderr and the command exits with exit status 1 (invalid option) or 2 (no command specified or invalid command).

NOTE: beorun does not pass information from stdin to applications. In cases where an application must read data from stdin, it is suggested that bpsh be used instead. Please see the bpsh man page for usage information; command line options for bpsh are similar to those for beorun, but not exactly the same.

Examples

Run uptime on any two available cluster compute nodes:

11:05am  up 2 days, 11:16,  0 users,  load average: 0.05, 0.24, 0.65
11:05am  up 2 days, 11:16,  0 users,  load average: 0.01, 0.07, 0.37