README FILE

Description of all the routines and modules provided in the DPMTA
distribution.

RCSID: $Id: README,v 1.1 1997/09/05 19:41:49 jim Exp $

================

Makefiles:

Makefile
   - generic makefile to build and install libraries and test 
     executables for a homogeneous cluster of workstations.

Makefile.cray
   - builds and installs libraries and test execuatbles for a
     Cray C90/T3D system.
   - use directly via the '-f' option to make

================

Include Files:

dpmta.h
   - contains type declarations and prototypes that should be used
     by applications calling DPMTA

dpmta_pvm.h 
   - contains definitions for PVM message passing

dpmta_cell.h
   - structure type definitions for cell table and other
     information structures.
   - requires constants defined in dpmta_pvm.h

dpmta_slave.h
   - global variable extern definitions used by slave process
   - globals allocated in dpmta_slave.c

dpmta_fft.h
   - contains the inline fft macros
   - replaces dpmta_slvmacros.h

dpmta_legendre.h
   - contains the inline legendre polynomial macros
   - replaces dpmta_slvmacros.h

dpmta_slvmkil.h
   - contains inline macros for translation of relative interaction
     list vectors

dpmta_timer.h
   - contains global declarations for internal timing meassurements.

dpmta_version.h
   - contains the definition of the release version number

================

Master Program Modules:

dpmta_mastiface.c
   - provides the interface routines that to the actual work of spawning
     slaves and passing particle data back and forth to them.

dpmta_mastinit.c
   - routine to send initialization data to slave processes.

dpmta_mastiter.c
   - routines to send and receive particle and force data to the slaves.
   - receives and prints out timing data if enabled


================

Slave Program Modules:

dpmta_slave.c
   - main slave routine.
   - calls other subroutines to handle transfer and calculation of data.
   - contains all global variable declarations.

dpmta_slvcompute.c
   - contains the main computation routine.
   - called (repetitively) after initialization to perform actual
     multipole processing.

dpmta_slvpcalc.c
   - routines to perform direct particle interactions.  routines are
     called directly from main().

dpmta_slvmcalc.c
   - routines to perform multipole interactions.  routines are
     called directly from main().

dpmta_slvcomm.c
   - routines to send and receive multipole information
     between slaves, send and receive particle information between 
     slaves and send and receive interaction and particle
     information to and from the master process.

dpmta_slvmisc.c
   - miscellenious routines to provide cell and pid indexing.

dpmta_slvmkcell.c
   - allocated and initializes cell table data structures

dpmta_slvmkhl.c
   - generates mpe transfer matrices corresponding to the 
     vector entries in the relative interaction list

dpmta_slvmkil.c
   - generates relative interaction lists

dpmta_slvmkiil.c
   - allocate and compute inverse interaction lists for each slave

dpmta_slvmultipole.c
   - the multipole library.
   - routines to perform all aspects of the multipole calculations
   - M2M, M2L, L2L, Part->MPE and MPE->Force
   - includes FFT enhancements

dpmta_slvfft.c
   - implements routines to perform the fft optimization for the fma code.

dpmta_slvclean.c
   - routines to free up particle information following each iteration.

================

Test Programs:

dpmta_test.c
   - master program, reads in command line arguments, spawns slaves,
     generates random particles, and calls PMTAforce to caluculate the 
     N-body forces.
   - runs multiple iterations

dpmta_test2.c
   - a version of "dpmta_test" that spawns a number of test slaves and
     interface to the DPMTA routines through these slaves, utilizing the
     distributed calling sequence.

dpmta_test2b.c
   - the slave part of "dpmta_test2" that actually calls the PMTAforce()
     routine, collect the results, and sends them back to dpmta_test2 to
     be collected and printed

dpmta_test3.c
   - SPMD test routine that spawns a number of copies of itself where
     each copy calls PMTAforce() to compute the results.

dpmta_direct.c
   - this is an SPMD application that will take the output particle
     list file generated by the above test applications and perform
     a naive direct force calculation on the test particles.
   - this is used for error computations and validation of correctness
     of the DPMTA application.

================

Other Modules and Programs:

dpmta_t3dlib.c
   - replacement routine for dpmta_slave.c and dpmta_mastiface.c that 
     provides a DPMTA library where the multipole routines are actually
     linked into the application program instead of a stand-alone
     process.  This is for support of the Cray T3D where you cannot
     have multiple processes exist ona single PE.
