Wednesday Apr 04, 2007

PE Tight Integration

While the topic of integration of parallel environments with Grid Engine is still fresh, there's one other topic I'd like to cover. What is a tight integration, and how is it different from a loose integration?

Let's start with how a parallel job is started.
Step 1, the scheduler sends the qmaster a set of orders, saying where to put the master task and where to put the slave tasks. The master task is the one that runs the job script. (I say script because in the vast majority of cases, a parallel job will be a script. It is, however, theoretically possible for it to be a binary.)
Step 2, the qmaster sends the master task to its destination execution daemon, just like with a non-parallel job, but it also reserves the jobs slots on the destination execution daemons for the slave tasks. Notice that I said "reserves slots," not "starts." The qmaster does not actually start any of the slave tasks. See step 3.3.
Step 3, the execution daemon starts the parallel job on the master node.
Step 3.1, the execution daemon on the master node runs the parallel environment startup script. This script prepares the parallel environment for running the master task. Among other things, this script creates a file that lists the job slots to be used for the slave tasks.
Step 3.2, the execution daemon runs the job script as the master task.
Step 3.3, the master task starts the parallel environment for the job. This step is different from step 3.1. Step 3.1 prepares the parallel environment, but it doesn't necessarily start any processes. Step 3.3 is where the parallel environment is actually run, such as running mpirun for an MPI integration.
Step 3.4, the parallel environment connects to the slave nodes and starts the slave tasks.
Step 4, after the job finishes, the execution daemon on the master node runs the parallel environment shutdown script.

The above process applies to both loosely and tightly integrated parallel environments. The difference between loose and tight integration is how the slave tasks gets started. In a loose integration, the parallel environment uses some out-of-band method to connect to the slave nodes and start the slave tasks. This method gives the parallel environment a great deal of freedom in how it starts the slave tasks, but it means that the slave tasks are running outside of the scope of Grid Engine. Because the slave tasks are run outside of Grid Engine, the qmaster has no way to track the resource usage of slave tasks in loosely integrated parallel environments. Only the resource usage of the master task can be tracked.

In a tightly integrated parallel environment, the slave tasks are started through qrsh -inherit. The -inherit switch is a special qrsh switch that is used only with slave tasks in tightly integrated parallel environments. A job submitted this way actually bypasses the scheduler completely and is sent directly to the target execution daemon. As a security precaution, execution daemons deny such job submissions by default. In step 2, when the qmaster reserves the slave nodes for a parallel job in a tightly integrated parallel environment, it tells the execution daemons to expect the qrsh -inherit jobs and not to deny them. Because the slave tasks are run through Grid Engine, the qmaster is able to track the tasks' resource usage, the same as with any other kind of job. A common trick to make the implementation of the integration easier is to provide an rsh wrapper that translates rsh calls into qrsh calls. That way, as long as the parallel environment naturally uses rsh to contact the slave nodes, the tight integration will work automatically.

Friday Mar 23, 2007

Configuring a New Parallel Environment

Since this seems to be a regular topic on the user mailing list, here's a quick guide to setting up a parallel environment on Grid Engine:

  1. First, create/borrow/steal the startup and shutdown scripts for the parallel environment you're using. You can find MPI and PVM scripts in the $SGE_ROOT/mpi and $SGE_ROOT/pvm directories, respectively. If you cannot find scripts for your parallel environment, you'll have to create them. The startup script must prepare the parallel environment for being used. With most MPI implementations, that's just a matter of creating a "machines" file that lists the machines which are to run the parallel job. The shutdown script must clean up after the parallel job's execution. The MPI shutdown script just deletes the "machines" file.

  2. Next, you have to tell Grid Engine about your parallel environment. You can do that interactively with qmon or qconf -ap <pe_name> or you can write the data to a file and use qconf -Ap <file_name>. For an example of what such a file would look like, see $SGE_ROOT/mpi/mpi.template or $SGE_ROOT/pvm/pvm.template.

    Let's look at what the parallel environment configuration contains.

    pe_name           template
    slots             0
    user_lists        NONE
    xuser_lists       NONE
    start_proc_args   /bin/true
    stop_proc_args    /bin/true
    allocation_rule   $pe_slots
    control_slaves    FALSE
    job_is_first_task FALSE
    urgency_slots     min

    • pe_name - the name by which the parallel environment will be known to Grid Engine

    • slots - the maximum number of job slots that the parallel environment is allowed to occupy at once

    • users_lists - an ACL specifying the users who are allowed to use the parallel environment. If set to NONE, it means any user can use it

    • xusers_list - an ACL specifying the users who are not allowed to use the parallel environment. Users in both the users_list and xusers_list are not allowed to use the parallel environment

    • start_proc_args - the path to the startup script for the parallel environment followed by any needed arguments. Grid Engine provides some inline variables that you can use as arguments:

      • $pe_hostfile - the path to a file written by Grid Engine which contains information about how and where the parallel job should be run
      • $host - the host on which the parallel environment is being started
      • $job_owner - the name of the user who owns the parallel job
      • $job_id - the id of the parellel job
      • $job_name - the name of the parallel job
      • $pe - the name of the parallel environment
      • $pe_slots - the number of job slots assigned to the job
      • $queue - the name of the queue in which the parallel job is running

      The value of this setting is the command that will be run to start the parallel environment for every parallel job.

    • stop_proc_args - the path to the shutdown script for the parallel environment followed by any needed arguments. The same inline variables are available as with start_proc_args.

    • allocation_rule - this setting controls how job slots are assigned to hosts. It can have four possible values:

      • a number - if set to a number, Grid Engine will assign that many slots to the parallel job on each host until the assigned number of job slots is met. Setting this attribute to 1, for example, would mean that the job gets a single job slot on each host where it is assigned. Grid Engine will not assign the job more job slots than the number of assigned hosts multiplied by this attribute's value.

      • $fill_up - use all of the job slots on a given host before moving to the next host

      • $round_robin - select one slot from each host in a round-robin fashion until all job slots are assigned. This setting can result in more than one job slot per host.

      • $pe_slots - place all the job slots on a single machine. Grid Engine will only schedule such a job to a machine that can host the maximum number of slots requested by the job. (See below.)

    • control_slaves - this setting tells Grid Engine whether the parallel environment integration is "tight" or "loose". See your parallel environment's documentation for more details.

    • job_is_first_task - this setting tells Grid Engine whether the first task of the parallel job is actually a job task or whether it's just there to kick off the rest of the jobs. This setting is also determined by your parallel environment integration.

    • urgency_slots - this setting affect how resource requests affect job priority for parallel jobs. The values can be "min," "max," "avg," or a number. For more information about resource-based job priorities, see this white paper

    For more information about these settings, see the sge_pe man page.

  3. The next step is to enable your parallel environment for the queues where it should be available. You can add the parallel environment to a queue interactively with qmon or qconf -mq <queue> or in a single action with qconf -aattr queue pe_list <pe_name> <queue>.

  4. Now you're ready to test your parallel environment. Run qsub -pe <pe_name> <slots>. Aside from the usual output and error files (<job_name>.o<job_id> and <job_name>.e<job_id>, respectively), you should also look for the parallel environment startup output and error files, <job_name>.po<job_id> and <job_name>.pe<job_id>.

That's all there is to it! Just to make sure we're clear on everything, let's do an example. Let's create a parallel environment that starts up an RMI registry and stores the port number in a file so that the job can find it.

First thing we have to do is write the startup and shudown scripts for the RMI parallel environment. Here's what they look like:
# $TMPDIR and $JOB_ID are set by Grid Engine automatically

# Borrowed from $SGE_ROOT/mpi/
   cat $1 | while read line; do
      host=`echo $line|cut -f1 -d" "|cut -f1 -d"."`
      nslots=`echo $line|cut -f2 -d" "`

      while [ $i -le $nslots ]; do
         echo $host
         i=`expr $i + 1`

# get arguments

# ensure pe_hostfile is readable
if [ ! -r $pe_hostfile ]; then
   echo "$me: can't read $pe_hostfile" >&2
   exit 1

# create machines file
PeHostfile2MachineFile $pe_hostfile >> $machines

# We use ports 40000-40999
port=`expr \\( $JOB_ID % 1000 \\) + 40000`

# Start the registry
/usr/java/bin/rmiregistry $port &

# Save the registry's PID so that we can stop it later
echo $! > $TMPDIR/pid

# Save the port number so the job can find it
echo $port > $TMPDIR/port
# $TMPDIR is set by Grid Engine automatically

# Get the registry's PID
pid=`cat $TMPDIR/pid`

# Kill the registry
kill $pid

# Clean up the files the startup script created
rm $TMPDIR/pid
rm $TMPDIR/port
rm $TMPDIR/machines

Next thing we have to do is add our parallel environment to Grid Engine. First we create a file, say /tmp/rmi_pe, with the following contents:

pe_name           rmi
slots             4
user_lists        NONE
xuser_lists       NONE
start_proc_args   /home/dant/ $pe_hostfile
stop_proc_args    /home/dant/
allocation_rule   $round_robin
control_slaves    TRUE
job_is_first_task FALSE
urgency_slots     min

Note that control_slaves is true and job_is_first_task is false. Because we're writing the integration scripts, the choice is somewhat arbitrary, but it affects how the job scripts must be written, as we'll see below. It also affect whether the qmaster is able to keep accounting records on the slave tasks. If control_slaves is false, the qmaster is have no records of how much resources the slaves tasks consumed.

Now we add the parallel environment with qconf -Ap /tmp/rmi_pe. We could have skipped a step by running qconf -ap rmi and entering the data in the editor that comes up, but they way we've done it here is scriptable.

The next step is to add our parallel environment to our queue with qconf -aattr queue pe_list rmi all.q. Again, we could have run qconf -mq all.q and edited the pe_list attribute in the editor, but the way we've done it is scriptable.

Last thing to do is test out our parellel environmemt. First we need a job script:

#$ -S /bin/sh

port=`cat $TMPDIR/port`

cat $TMPDIR/machines | while read host; do
   $qrsh -inherit $host /usr/bin/java -cp ~/rmi.jar RMIApp $port &

Let's look at this job script for a moment. The first thing to notice is the use of qrsh -inherit. The -inherit switch is specifically for kicking off slave tasks. It requires that the target host name be supplied. In order to get the target host name, we read the machines file that the startup script generated from the one Grid Engine supplied.

The second thing to notice is how ugly the use of qrsh -inherit is. RMI is not really a parallel environment. It's a communications framework. It doesn't do the work of kicking off remote processes for you. So, instead, we have to do it ourselves in the job script. With a true parallel environment, like any of the MPI flavors, the framework also takes care of starting the remote processes, often through rsh. In the MPI scripts included with Grid Engine, an rsh wrapper script is included, which transparently replaces calls to rsh with calls to qrsh -inherit. By using that wrapper script, the parallel environment's calls to rsh can be rerouted through the grid via qrsh without having to modify the parallel environment itself to work with Grid Engine.

The last thing to notice is how this script correlates to the control_slaves and job_is_first_task attributes of the parallel environment configuration. Let's start with first_job_is_task. In our configuration, we set it to false. That means that this master job script is not counted as a job and does no real work. That is why our script doesn't do anything but kick off sub-tasks. If job_is_first_task had been true, our job script would be expected to run one of the RMIApp instances itself.

Now let's talk about the control_slaves attribute. If control_slaves is true, we are allowed to use qrsh -inherit to kick off our sub-tasks. The qmaster will not, however, allow us to kick off more subtasks than the number of slots we've been assigned (minus 1 if job_is_first_task is true). The advantage of using qrsh -inherit is that the sub-tasks are tracked by Grid Engine like regular jobs. If control_slaves is false, we have to use some mechanism external to Grid Engine, such as rsh or ssh, to kick off our sub-tasks, meaning that Grid Engine cannot track them and is actually fully unaware of them. That's why job_is_first_task is meaningless when control_slaves is false.

In order to test our job we need a Java application called RMIApp. As that's outside the scope of the example, let's just pretend we have a parallel Java application that uses the RMI registry for intra-process communication. To submit our job we use qsub -pe rmi 2-4 The -pe rmi 2-4 argument tells the qmaster that we're using the rmi parallel environment and we want 4 job slots assigned to our job, but we will accept as few as 2. Because our job script starts a sub-task for every entry in to host file, it will start the right number of sub-tasks, no matter how many slots we are assigned. Had we written the job script to start exactly two sub-tasks, we would have to use -pe rmi 2 so that we could be sure we got exactly two job slots.

While the job is running, run qstat -f. You'll see output something like this:

% qstat -f
queuename                      qtype used/tot. load_avg arch          states
all.q@ultra20                  BIP   4/10      0.08     sol-amd64
    253 0.55500 dant         r     03/23/2007 11:46:51     4

From this output we can see that the job has been scheduled and has been assigned four job slots. Those four job slots only account for the four sub-tasks. The master job itself is not counted because the job_is_first_task attribute is false.

After our job completes, if we look in our home directory (which is where Grid Engine will put the output files since we didn't tell it otherwise), we will find four new files:,,, and, assuming, of course, that our job was number 253. The \*.o253 and \*.e253 files should be familiar. They're the output and error streams from the job script. The \*.po253 and \*.pe253 files are new. They're the output and error streams from the parallel environment startup and shutdown scripts.

So, there you have it. A complete, top-to-bottom example of creating, configuring, and running a parallel environment.




« July 2016