# CDROM Guide to PGENESIS 2.1

    Nigel Goddard & Greg Hood
    Pittsburgh Supercomputing Center
    ngoddard@psc.edu
    ghood@psc.edu

NOTE: Before installing this software, please check that you have the latest version by checking the PGENESIS home page: `http://www.psc.edu/Packages/PGENESIS` We *strongly* advise you to download the latest version if you don't already have it. The following text applies to the old CDROM version of PGENESIS, which has become quite outdated, and may not even run without modification on modern machines and OS versions.

## Introduction

PGENESIS (Parallel GENESIS) can be run on a single workstation; the PVM software system is used to provide the illusion of a parallel computer. It is much easier to run on a network of workstations if they have a shared file system so that any workstation can access any file. If this is not the case, you will need to install PGENESIS independently on each workstation and you will need a copy of the files needed for your simulation (data files, script files, etc), preferably in an identically named directory path.

## Running PGENESIS

PGENESIS can be run directly off the CDROM with the command:

`/cdrom/pgenesis/bin/pgenesis`

You may wish to put `/cdrom/pgenesis/bin` in your path so that `pgenesis` is all that is required. For example, `cd` to `/cdrom/pgenesis/Scripts/orient2` and execute `pgenesis demo.g`. To see the documentation invoke `pgenesis -browse`. You can cd to your own script directory and run PGENESIS on those scripts. But beware: if you have a customized `.simrc` in the directory, PGENESIS will ignore it. The simple thing to do is invoke `pgenesis` without any script, quit at the prompt, then edit the file `.psimrc` to include whatever customizations you have.

There are several available options, which may be listed by typing `pgenesis -help`. The most commonly used of these are:

        -config <file> - where <file> is a file containing a list of
                       machines to be used (1 per line)
        -nox - run without Xodus
        -debug tty - create a window for each pgenesis node
        -browse - browse the pgenesis documentation using netscape

Read the Web pages (rooted at `/cdrom/pgenesis/Hyperdoc/welcome.html`) to take advantage of the new functionality provided by PGENESIS.

## Installing PGENESIS

PGENESIS can also be installed onto your disk by first installing serial GENESIS (see the regular GENESIS documentation for instructions) and then issuing the command:

`/cdrom/Install/PGENESIS_Install install_dir genesis_pathname`

where `install_dir` is the name of the directory in which `pgenesis` and `pvm3` subdirectories will be created, and `genesis_pathname` is the directory where the serial GENESIS directory is located. For example, "`/cdrom/Install/PGENESIS_Install /usr/local /usr/genesis`" will make subdirectories `/usr/local/pgenesis` and `/usr/local/pvm3` and reference the serial GENESIS located in `/usr/genesis`.

Each user should make sure that their PATH is set to include `install_dir/pgenesis/bin`. If the script files you wish to use are not in your home directory, the examples directory, or the directory you run parallel Genesis in, you will need to add their directory path to the SIMPATH variable in the .simrc file you use. By default this is .psimrc for PGENESIS worker nodes.

## Debugging PGENESIS Scripts

Normally the master node sends its output to your screen and the worker nodes send their output to the file `/tmp/pvml.????` on the machine they are running on, where `????` is your uid on that machine. Many script bugs can be tracked down by examining those /tmp/pvml.`????` files. Note that PVM appends to these files on every run, until PVM is halted and restarted. Also note that if a worker node exits without executing "paroff", some of its output to stdout/stderr which is buffered may not appear in the `/tmp/pvml.????` file.

Output from the workers can be redirected to a file by giving the paron command the `-output <filename>` option. `<filename>` can be `/dev/tty`, in which case the worker output appears on your screen mixed with the master's output.

If you are running X-Windows, you can have each worker create its own window and send its output there by using the `-debug tty` flag when invoking PGENESIS. This requires that your DISPLAY environment variable is set to "`hostname:0`" when you invoke the pgenesis script.

By default PGENESIS starts the workers using `-silent 3` which minimizes the messages printed by the workers (e.g., the banner). To see more worker status messages, give the `paron` command the `-silent 0` option.

Common errors include:

1. User impatience leads to interruption of PGENESIS before it has completed the initialization of the workers. The timeout is set to 120 seconds, for maximum information about the problem, let PGENESIS timeout if it fails to initialize workers properly (i.e., wait!).
2. PVM can't find the worker executable. This is specified with the `-executable <filename>` option of the paron command, the default is "pnxgenesis". This executable, or a link to it, should be in `~/pvm3/bin/$PVM_ARCH`. A symptom of this problem is that PGENESIS reports it failed to spawn workers and the `/tmp/pvml.???` files are empty apart from the header.
3. PVM aborts worker startup due to I/O in your .cshrc Symptoms of this are that PGENESIS reports workers failed to spawn and the `/tmp/pvml.???` files contain error messages about TTY or other strange things, and no Genesis startup banner. Modify your .cshrc as described in pvm-cshrc.stub.
4. The workers can't find the script containing the paron command. Symptoms of this are that PGENESIS reports workers failed to spawn and the `/tmp/pvml.???` files show the GENESIS prompt with no attempt to execute `paron`, or the startup banners show that the script file could not be found. Edit your `~/.psimrc` and `~/.pnxsimrc` so that SIMPATH lists the directories containing the scripts.
5. Incorrect use of barriers. Symptoms are that the master or some worker(s) hang and eventually timeout. Examine your use of barriers. Note that some commands contain implicit barriers, it is possible there is a bug in the source - if you suspect this mail ngoddard@psc.edu.

For more information on the finer points of using PVM, refer to the PVM user guide.

NOTE: For instructions on how to run the parallel Genesis beta test see the `README.beta` file. The file you are now reading tells you how to install parallel Genesis and run it with your scripts.

## User-Extended PGENESIS

Libraries are constructed just as for serial GENESIS, each in its own subdirectory in a canonical form. See the GENESIS documentation for descriptions of this form. In this section we describe how to link these libraries with PGENESIS components to create an extended PGENESIS.

Assuming your libraries are subdirectories of a root directory I'll call `MYPGEN`, these are the steps you follow to create and run extended PGENESIS.

1. Copy `install_dir/pgenesis/lib/Usermake` to `MYPGEN/Makefile`. Modify the `Makefile` for your platform type as described in the `Makefile`. You must set `PVM_ROOT` and `PVM_ARCH` in the `Makefile`, unless you have set them in your `.cshrc` as described in section 3.3 of the PVM manual. The default setting for `PVM_ARCH` should be correct in almost all cases. You will have to uncomment one of the machine/compiler dependent options for CC, CPP, CFLAGS, LIBS, SYSLIBS, etc. The `GENESIS` and `INST_DIR` macros should be set to, respectively, the full pathnames of the serial Genesis installation and the directory in which parallel Genesis should be installed (usually the PGENESIS root directory).
2. Now add the names of your libraries and their subdirectories to `USERLIB` and `USERDIR` and set the installation root for your extended PGENESIS in `USERINST`. Execute '`make nxextended`' to make extended PGENESIS without Xodus, '`make extended`' to make extended PGENESIS with Xodus.
3. This should create `USERINST/bin` and `USERINST/lib` containing various files. The only one you need to be aware of is `USERINST/bin/pgenesis`. To run your extended PGENESIS, set your path to include `USERINST/bin` early. Then invoke extended PGENESIS with '`pgenesis`' just as you would for vanilla PGENESIS.