
                    mpiJava - A Java Interface to MPI
                    ---------------------------------

                        Version 1.2, Sep 1999

          Sung Hoon Ko, Sang Lim, Xinying Li, Bryan Carpenter
                     NPAC, Syracuse University
                 email {shko,slim,xli,dbc}@npac.syr.edu

                             Mark Baker
                   CSM, University of Portsmouth
                      email mab@sis.port.ac.uk


This package provides an object-oriented Java interface to the Message
Passing Interface (MPI) standard, for use on parallel or distributed
computing platforms.  The release includes the Java Native Interface
(JNI) C stubs that binds the Java interface to an underlying native MPI
C interface (which must be obtained and installed independently).  The
release also includes a comprehensive test suite for the Java
interface, created by translating the IBM MPI test suite to Java, and
some simple examples and demos.

The Java API is defined in the document "mpiJava 1.2: API specification"
in the `doc' directory.


Significant changes from version 1.1
------------------------------------

1) Support for the `MPI.Object' basic type (note that this release
   uses default JDK serialization, which can be quite inefficient).
2) Support for Linux platforms.
3) Inclusion of new demo programs.
4) Inclusion of `javadoc' documentation.
5) Other minor changes to the API---see the spec in the `doc' directory.
6) Bug fixes.


Platforms
---------

We have tested the software using (select combinations of)

  1. Operating systems:

       Sun Machines running SunOS 5.4 (Solaris2.5.1)
       Linux-Mandrake 6.0
       Redhat Linux 6.0
       WinTel NT 4 (SP3)
       SGI Challange Machines running IRIX 6.2

  2. Java Development environments:

       Java JDK 1.2(solaris) 
       IBM JDK 1.1.6
       Java JDK 1.1.x(SGI)

  3. Native MPI installations:

       MPICH 1.1.2 
       SunHPC-MPI(3.0) 
       WMPI 1.1

Users have reported ports to other platforms (for Alpha processors, see
the message at the end of this file).

Updates and further information about mpiJava can be found on the home
page at http://www.npac.syr.edu/projects/pcrc/HPJava/mpiJava.html

If you find bugs, have comments, or want further information about
mpiJava or the team of developers email mpiJava@npac.syr.edu

Installation
------------

The following instructions apply to UNIX.  For instructions on
installation under Windows NT, see the file `NT_INSTALL.TXT'.


1. Install your preferred Java programming environment.

For Solaris, we strongly recommend to use JDK1.2 or later with the
``native'' thread option.  The older ``green threads'' implementation
in JDK leads to incompatibilites with current MPICH and SunHPC-MPI.

After Java JDK is installed successfully, you should add the Java JDK
`bin' directory to your path setting, so that the `mpiJava/configure'
script can find the `java', `javac', and `javah' commands.


2. Install your preferred MPI software.

Add the MPI `bin' directory to your path setting.


3. Now, you are ready to install the mpiJava interface.

   step 1.  Unpack the software, eg

              gunzip -c mpiJava-x.x.tar.gz | tar -xvf -

            A subdirectory `mpiJava' is created.

   step 2.  Go to the `mpiJava' directory.  Configure the software for
            your platform:

              configure

            You may specify various standard options to the configure
            process.
	    
            Try

                configure --help

            for various option.

            The default MPI is MPICH.  Use

                configure --with-MPI=sunhpc

            for SunHPC

            If you need to reconfigure for a different platform later
            you should remove `config.cache' before repeating `configure'.

   step 3.  Build (compile) the software:

                make


After successful compilation, the makefile will put the generated class 
library in dir `classes', which contains java classes for MPI, 
and a dynamic library in `lib'.

Add the directory <mpiJava-pathname>/src/scripts to your path.  
Add the directory <mpiJava-pathname>/lib/classes to your CLASSPATH.
Add the directory <mpiJava-pathname>/lib         to your LD_LIBRARY_PATH.


Using the software
------------------

If everything goes well, you can compile and run the test programs by
issuing the command

    make check

in the mpiJava installation directory.

An example of how to compile and run a program:

  javac Life.java
  prunjava 4 Life

The `prunjava' script is a wrapper for the MPICH `mpirun' script.  The
first argument is the number of processors on which the program will be
executed.  A list of available host computuers may be given in an
MPICH-style `machines' file in the local directory.

See the `doc' directory for further information.  The API definition is in

  mpiJava/doc/api/mpi/mpiJava-spec.ps

Javadoc documentation for the API is preinstalled at

  mpiJava/doc/api/mpi/package-summary.html

For questions and comments, email us.  


Known bugs and omissions in version 1.2
---------------------------------------

1) The subclasses of `MPIException' documented in the mpiJava spec are still
   not implemented (and in fact mpiJava methods never throw
   exceptions---they generally abort the program in case of error).

2) In general, sanity-checking method arguments is not as thorough as it
   should be.


mpiJava Directory Structure
---------------------------
  
     mpiJava/
         bin/
	      This directory contains binaries or installed scripts.
	      For NT releases, sub-directories contain Win32 Dynamic
	      Link Libraries (.dll).

              WMPI/
		   For NT releases, contains wmpi.dll created by
		   compiling the JNI C stubs. The directory where the
		   DLL resides needs to be added to the PATH
		   environment variable so that it can be found at
		   run-time by Java.

                   mpiJava.dll 

         config/

         doc/

         examples/
              metropolis/
              simple/
              pingpong/

         lib/
	      For UNIX releases this directory contains shared libraries.
              Class files are contained in a subdirectory.

              classes/
		   The mpiJava class files live here.  This directory
		   should be added to your CLASSPATH enviroment
		   variable.

                   mpiJava.zip

         src/
              C/
		   The JNI C stubs for mpiJava.  This directory
		   contains the JNI C wrappers and the header files for
		   mpiJava.  These files are compiled into a shared
		   (.so in UNIX) or dynamic-load-library (.dll in
		   Win32) that is loaded at runtime by the JVM
		   (loadlibary(mpiJava)) when the Java MPI interface is
		   used.

              Java/
		   The Java interface to MPI.  This directory includes
		   a sub-directory (mpi) holding the Java interface to
		   MPI.  These files need to be compiled using a Java
		   compiler, such as javac.  The resulting class files
		   are copied into the mpiJava/lib/classes directory.

                   mpi/

              scripts/
		   Various scripts for configuraing and testing mpiJava
		   under UNIX.

              wmpi_jni/
                   See notes in `NT_INSTALL.TXT'

                   release/

         tests/
              ccl/
              comm/
              dtyp/
              env/
              group/
              pt2pt/
              topo/



                           References
                           ==========

MPI Home Page:
    http://www.mcs.anl.gov/mpi/index.html

WMPI (an MPI for Windows NT):
    http://dsg.dei.uc.pt/w32mpi/


Contributions
-------------

From Hiromitsu Takagi:

I'd like to inform you that we have successfully built and run it on
Digital UNIX V4.0D (OSF JDK1.1.6) / MPICH but a few modifications are
required.

o add "-I$(JDK)/include/java -I$(JDK)/include/java/alpha" into 
  INCLUDE of mpiJava-1.1/src/C/Makefile
  (jni.h is placed on $(JDK)/include/java/ and jni_md.h is placed on
  $(JDK)/include/alpha/.)

o set LDFLAG of mpiJava-1.1/src/C/Makefile "-shared"

[...]
--
Hiromitsu Takagi
Computer Science Division, Electrotechnical Laboratory

Sep 1, 98

