HOW TO RUN THE WAVE EQUATION WITH LOADLEVER/POE (THE NCAR/BLUESKY ENVIRONMENT)

Running the wave equation example under a job scheduler such as LoadLever/POE 
requires setting up the user's environment beforehand, in particular, the
user's ssh configuration.

InterComm requires a PVM virtual machine to be setup as it functions as
the underlying its communication infra-structure. In a non-scheduled parallel
environment, it is easy to start PVM and add the hosts that will be part of the
virtual machine. In an environment controlled by a job-scheduler, a
complication arises because, although one can usually request a particular set
of nodes, in most cases a user will request for any nodes matching a particular
set of criteria. Thus, it is not a priori known the nodes that will become part
of the virtual machine.

To enable nodes to be dynamically added to the virtual machine usually the user
will have to write scripts that will detect where (i.e., the nodes) they are
being executed and those nodes will be automatically added to the virtual
machine configuration. Because this operation is accomplished by scripts and
because PVM needs ssh access to any node that is part of the virtual machine,
it is necessary that the user sets up her ssh configuration based on public
keys, without password authentication (see the end of this text for how that
can be done).

Once the user environment is configured, take a look at the README file to
understand about how the three pieces of the parallel run (i.e., waveeq-left,
waveeq-right, and vis) fit together.

The visualization code is sequential and should be run as follows:

poe vis.cmd -procs 1

waveq-left and waveeq-right are parallel programs and the number of processors
that each part will use is established in the configuration file waveeq.conf,
in particular, the following lines:

LeftNProcessors=m
RightNProcessors=n

where m and n are the number of processors for waveeq-left and waveeq-right
respectively. This way, in order to run them the following commands must
be issued:

poe wl.cmd -procs m
poe wl.cmd -procs n

The output result generated by the wave equation code is put in the user's
home directory in PBM files (that can be visualized with either xv or
ImageMagick's 'display' program) whose file names are of the form 
vis*-UnixUserid-SequenceNumber.pbm.

--------------------------------

A FEW WORDS ON THE SCRIPTS

The .cmd file are LoadLever scripts that POE uses. The .pl files are Perl
scripts that essentially allows the collection of hosts, the setup of
the PVM virtual machine, and signalling that the machine is functioning.

get_allcd_hosts.pl: is run by all .cmd scripts and it collects the list of
nodes that were allocated.

create_pvm_hostfile.pl: collects the info about the processors allocated for
each application (vis, waveeq-left, and waveeq-right), generates a machine
file, i.e., the list of nodes that were allocated by the independent poe
invokations, starts up PVM, and signals to the other application that the
virtual machine is up and running.

wait_host_file.pl: receives the signal that PVM is up and running and the
wave equation code and the visualization code can progress.

--------------------------------

SETTING UP SSH WITH PUBLIC KEY AUTHENTICATION

Generating Key Pairs

If you do not want to enter your password every time you use ssh, scp, or sftp
to connect to a remote machine, you can generate an authorization key pair.

Keys must be generated for each user. To generate keys for a user, follow the
following steps as the user who wants to connect to remote machines. If you
complete the following steps as root, only root will be able to use the keys.

Use the following steps to generate a DSA key pair for version 2 of the SSH
Protocol.

1. To generate a DSA key pair to work with version 2 of the protocol, type the
following command at a shell prompt:

ssh-keygen -t dsa

Accept the default file location of ~/.ssh/id_dsa. Enter a passphrase different
from your account password and confirm it by entering it again.

A passphrase is a string of words and characters used to authenticate a user.
Passphrases differ from passwords in that you can use spaces or tabs in the
passphrase. Passphrases are generally longer than passwords because they are
usually phrases instead of just a word.

The public key is written to ~/.ssh/id_dsa.pub. The private key is written to
~/.ssh/id_dsa. It is important never to give anyone the private key.


2. Change the permissions of your .ssh directory using the command chmod 755
~/.ssh.

3. Copy the contents of ~/.ssh/id_dsa.pub to ~/.ssh/authorized_keys on the
machine to which you want to connect. If the file ~/.ssh/authorized_keys does
not exist, you can copy the file ~/.ssh/id_dsa.pub to the file
~/.ssh/authorized_keys on the other machine.

4. If you are running GNOME, skip to the Section called Configuring ssh-agent
with GNOME. If you are not running the X Window System, skip to the Section
called Configuring ssh-agent. 

Generating an RSA Key Pair for Version 2

Use the following steps to generate a RSA key pair for version 2 of the SSH
protocol. This is the default starting with OpenSSH 2.9.

1. To generate a RSA key pair to work with version 2 of the protocol, type the
following command at a shell prompt:

ssh-keygen -t rsa

Accept the default file location of ~/.ssh/id_rsa. Enter a passphrase different
from your account password and confirm it by entering it again.

The public key is written to ~/.ssh/id_rsa.pub. The private key is written to
~/.ssh/id_rsa. Never distribute your private key to anyone.

2. Change the permissions of your .ssh directory using the command chmod 755
~/.ssh.  

3. Copy the contents of ~/.ssh/id_rsa.pub to ~/.ssh/authorized_keys on the
machine to which you want to connect. If the file ~/.ssh/authorized_keys does
not exist, you can copy the file ~/.ssh/id_rsa.pub to the file
~/.ssh/authorized_keys on the other machine.

4. If you are running GNOME, skip to the Section called Configuring ssh-agent
with GNOME. If you are not running the X Window System, skip to the Section
called Configuring ssh-agent. 

Generating an RSA Key Pair for Version 1.3 and 1.5

Use the following steps to generate an RSA key pair, which is used by version 1
of the SSH Protocol. If you are only connecting between Red Hat Linux 7.3
systems, you do not need an RSA version 1.3 or RSA version 1.5 key pair.

1. To generate an RSA (for version 1.3 and 1.5 protocol) key pair, type the
following command at a shell prompt:

ssh-keygen -t rsa1

Accept the default file location (~/.ssh/identity). Enter a passphrase
different from your account password. Confirm the passphrase by entering it
again.

The public key is written to ~/.ssh/identity.pub. The private key is written to
~/.ssh/identity. Do not give anyone the private key.

2. Change the permissions of your .ssh directory and your key with the commands
chmod 755 ~/.ssh and chmod 644 ~/.ssh/identity.pub.

3. Copy the contents of ~/.ssh/identity.pub to the file ~/.ssh/authorized_keys on the machine to which you wish to connect. If the file ~/.ssh/authorized_keys does not exist, you can copy the file ~/.ssh/identity.pub to the file ~/.ssh/authorized_keys on the remote machine.

4.  If you are running GNOME, skip to the Section called Configuring ssh-agent
with GNOME. If you are not running GNOME, skip to the Section called
Configuring ssh-agent. 
