The pgenesis shell script

The pgenesis shell script is used to invoke parallel genesis. It performs many checks and may set up necessary files and links in your directories. In addition to the usual flags available to the genesis executable, it takes the following additional flags:

-browse

Attempt to browse the PGENESIS documentation using netscape, which needs to be on the PATH for this to work.

-config filename

The specified file should contain a list of hosts to use to run the scripts (e.g., "axp0 axp1 axp2"). Names should be separated by blanks or newlines.

-debug mode

Run the workers and in some cases the master nodes in their own windows and in some cases under the control of a C code source level debugger. Valid modes are:

tty - run the in individual windows but not under any C debugger.

dbx - run the in individual windows under the control of dbx.

gdb - run the in individual windows under the control of gdb running inside emacs.

Not all modes are supported on all platforms. If you specify an unsupported mode the pgenesis shell script will select an alternative.

-nodes number

Specify the number of PGENESIS nodes (i.e., processes) to use. For MPI-based PGENESIS this option is required to used more than one node. For PVM-based PGENESIS it is not required since this number can be specified as an argument to the paron command within the script file.

-nohalt

Don't halt the PVM daemon after running the pgenesis executable. This allows you to use the -skip flag (below) on subsequent runs.

-skip

Do the minimal processing to start the pgenesis executable. Skip all checks and assume the PVM daemon is already running.

-nox

Run a version of the pgenesis executable which does not have the X libraries loaded - this is smaller and starts up faster and does not require you to be running X windows.

-v

Run in verbose mode

-help

Show and describe these flags.

Notes on script file command line parameters and the paron statement:

The invocation of PGENESIS and the spawning of PGENESIS nodes varies slightly depending on whether PGENESIS is using the PVM library or the MPI library for communication. With PVM, PGENESIS is first started on a single node, the master node, which in turn spawns a a number of child nodes when the paron statement is executed in its script. When spawning these child nodes, the master takes into account all parameters listed in the paron statement.

With MPI-based PGENESIS, however, no such spawning is done. Instead, the pgenesis script internally uses the mpirun command (or its local equivalent) to start the PGENESIS executable simultaneously on all processing elements requested. (The number of PEs to be used is typically defined by the -np argument to the mpirun command.) There is logically still a master node (the first node) and worker nodes. However, this master node does not spawn the worker nodes. Since the master node does not spawn, it has no direct control over the execution parameters of the worker nodes.

Because of this difference, many of the parameters of the paron statement are ignored in MPI-based PGENESIS. Instead, equivalent parameters must be specified as command-line arguments to the pgenesis script command.

These paron parameters should be replaced with the following command line equivalents for MPI-based PGENESIS:

  paron argument         MPI-based pgenesis command line equivalent
  --------------         ---------------------------------
  -simrc filename         -altsimrc filename
  -silent level           -silent level
  -nice level             -nice level
  -execdir directory      -execdir directory

These paron parameters are ignored by the MPI-based PGENESIS since they are already determined by the time the paron statement is interpreted:

  -executable filename
  -startup script

These paron parameters are read and interpreted by each node:

  -debug level
  -output filename

Troubleshooting PGENESIS Startup

The rest of this document discusses some issues to check through if you are having problems getting PGENESIS to run..

When PGENESIS was installed using the MPI message-passing library:

Make sure that the pgenesis script is invoking the proper command to start a set of MPI processes. This defaults to "mpirun" but can be set at installation time by modifying MPI_CMD in the top-level Makefile. After modifying the Makefile, it is always safest to do a "make clean" and then a complete rebuild.

When PGENESIS was installed using the PVM message-passing library:

Make sure your .cshrc (on each machine that you will use) sets the PVM_ROOT and PVM_ARCH environment variables correctly. See the "Setup to Use PVM" section in the PVM book for a description.
In your .cshrc file, your path should include the $PVM_ROOT/bin/$PVM_ARCH, $PVM_ROOT/lib/$PVM_ARCH and $PVM_ROOT/lib directories.
Ensure that your .cshrc file(s) do not do any I/O. If you wish to have I/O, see the section in the PVM book entitled "Common Startup Problems" for the ways you can do it.
Ensure your .cshrc sets the PVM_EXPORT environment variable appropriately (see the section in the PVM book entitled "Environment Variables"). For debugging the DISPLAY variable should be included:
```
   setenv PVM_EXPORT :DISPLAY
```
Make sure there is a soft link called pgenesis (or nxpgenesis for non-graphical PGENESIS) in the $PVM_ROOT/bin/$PVM_ARCH directory, which should point to the executable pgenesis (or nxpgenesis) in the pgenesis/bin/$PVM_ARCH directory. This must be true for each machine that you will use. Normally the pgenesis script will create these links, but this may not happen for heterogeneous architectures and/or non-shared filesystems.
If you wish to use PGENESIS in interactive or debugging style (each GENESIS node has its own command interpreter running in its own window, into which you can type commands), set up the file $PVM_ROOT/lib/debugger as described in the "Debugging" section of the PVM book.
Test that the pvm daemon starts when manually executing pvm. The daemon should be found on your path in $PVM_ROOT/lib/$PVM_ARCH. Make sure you can configure the PVM virtual machine you wish to use by adding other hosts with the "add" command. See the "Starting PVM" section of the PVM book. You do not necessarily need to add any machines to the virtual machine; you can run on a single workstation.