This package works only under UNIX.  The most recent version of this
package can always be found in ftp://ftp.ccs.neu.edu/pub/people/gene/gapmpi/.
Hopefully, you will also find it among the share packages of the GAP
distribution.  It has been tested on Linux (ELF), Solaris 2.6 and OSF 1 (alpha).
To unpack:
  cd .../gap4b5/pkg/
  gunzip gapmpi-beta.tar.gz
  tar xvf gapmpi-beta.tar

It can be installed as described for a generic GAP share package:
  cd .../pkg/gapmpi
  ./configure ../..
  make

Verify that .../pkg/gapmpi/bin/gapmpi.sh
   and .../pkg/gapmpi/bin/procgroup have correct paths.

Then try it out:
  cd .../pkg/gapmpi/bin
  ./gapmpi.sh
[ALTERNATIVE:  PATH/gapmpi.sh -p4pg PATH/procgroup]
gap>  # This assumes your procgroup file includes two slave processes.
gap>  PingSlave(1);
gap>  SendMsg( "Print(3+4)" );
gap>  SendMsg( "Print(3+4,\"\\n\")" );
gap>  SendMsg( "3+4", 2);
gap>  RecvMsg( 2 );
gap>  FlushAllMsgs();
gap>  SendRecvMsg( "Exec(\"pwd\")" );
gap>  SendMsg("for i in [1..1000000] do for j in [1..1000000] do od; od");
gap>  SendMsg("Print(\"WAKE UP\\n\")");
gap>  ProbeMsgNonBlocking();
gap>  ParReset();
gap>  FlushAllMsgs();
gap>  SendRecvMsg( "a:=45; 3+4", 1 );
gap>  SendMsg( "a", 2 );   # Note "a" defined only on slave 1, not slave 2
gap>  RecvMsg( 2 );
gap>  SendMsg( "a", 1 );
gap>  RecvMsg( 1 );
gap>  myfnc := function() return 42; end;
gap>  BroadcastMsg( PrintToString( "myfnc := ", myfnc ) );
gap>  SendRecvMsg( "myfnc()", 1 );
gap>  FlushAllMsgs();
gap>  squares := ParList( [1..100], x->x^2 );
gap>  MSexample();
gap>  BroadcastMsg( PrintToString("MSList := ", MSList) );
gap>  ParEval( "MSList( [10..20], x->x^2 )" );
gap>  ParRead( "/home/gene/.gaprc" );

If you still have problems, here is a checklist:
  0. Check .../gap4b5/src/gap.c  for the following:
	#ifdef GAPMPI
	    /* GAPMPI module                                               */
	    InitInfoGapmpi,
	#endif
     [ An interim version of GAP was missing the line:  InitInfoGapmpi,
       If you're missing it, add it and re-compile. ]
  1. Do you have enough swap space to support multiple GAP processes?
  2. Did you check for correct settings in .../pkg/gapmpi/bin/gapmpi.sh?
  3. Is "gapmpi" listed in .../pkg/ALLPKG ? [ It's needed to autostart slaves.]
  4. Did gapmpi find your procgroup?
     [ It looks in the current directory, or for:
          ... -p4pg PATH/procgroup
       on the command line. ]
  5. Is the procgroup file in your current directory set correctly?
     Test it.  If you are calling it on a remote host, manually type:
       rsh <HOSTNAME> <BINARY>
     For example:  rsh denali.ccs.neu.edu /usr/local/gap4b5/bin/gapmpi.sh
     where <HOSTNAME> and <BINARY> appear exactly as in procgroup.
     In some cases, 'exec' is used to save process overhead.  Also try:
       rsh <HOSTNAME> exec <BINARY>
     If you plan to call it on localhost, try just:   <BINARY>
     If your site uses "ssh" instead, try modifying gapmpi/mpinu/cmd.c
     However, mpinu cannot work if your site requires passwords
       for a login by rsh or ssh.  In that case, consider using
       rhosts.equiv, shosts.equiv, .rhosts, .shosts, .ssh, etc.
       as described in the man page.
  6. Has MPI been successfully initialized?  Try:  MPI_Initialized();
  7. A remote gapmpi starts in your home directory and tries to
	cd to a directory of the same name as your local directory.
     Check your assumptions about the remote machine.  Try:
       SendRecvMsg("Exec(pwd)"); SendRecvMsg("GAPMPI_Hostname()");
       SendRecvMsg("GAPMPI_Getpid()");
  8. Read the documentation for further possible problems.

Note that this package modifies the GAP src and bin files, and creates
a new GAP kernel.  This new GAP kernel can be shared by traditional users
of the old, sequential GAP kernel, and by those doing parallel processing.

The GAP kernel will have identical behavior to the
old GAP kernel when invoked through the gap.sh script or the
bin/@GAParch@/gap binary.  The new GAPMPI variables will appear to the
end user _ONLY_ if the GAP binary was invoked as gapmpi:  a symbolic
link to the actual GAP binary.  The script, gapmpi.sh, does this.

So, in a multi-user environment, traditional users can continue to use
gap.sh without noticing any difference.  Only an invocation as gapmpi.sh
will add the new features.

Comments and contributions to a GAPMPI user library, or any other type
of assistance, are gratefully accepted.
							Gene Cooperman
							gene@ccs.neu.edu
