Distributed Data Library v. 2.1.2 (MPI) --------------------------------------- Tim Oliver Aug95 Upgrading from previous versions -------------------------------- *** THIS VERSION (2.1.2) IS INCOMPATIBLE WITH PREVIOUS VERSIONS *** Your existing user programs and DDL routines need to be modified slightly to work under this version of the DDL. See the INSTALL file for details. After making these modifications continue below. 0) Don't delete your old ddl directory until you're sure the new one is working properly! 1) Do a complete installation of the new version. This uses a new directory ddl2.1.2. 2) Copy your own DDL routines and associated files into the new ddl2.1.2/user directory. Hand-edit user/Makefile.in to compile and archive your own routines into libuser.a. Reconfigure and remake ddl2.1.2 (and make install if desired). Edit your DDL user Makefile to point to the new ddl2.1.2 if necessary and remake user programs. Programs should now be running with the new ddl2.1.2 library. 3) Report bugs, incompatibilities to me... New installation ---------------- 0) install MPI. 1) unpack the DDL tarfile. DDL v2.1.2 requires less than 4MB disk space to make, and even less afterwards if it is installed and the source tree deleted. Unpacking creates a directory structure as follows: ./ddl2.1.2 ./ddl2.1.2/base ./ddl2.1.2/blas ./ddl2.1.2/user ./ddl2.1.2/include ./ddl2.1.2/lib ./ddl2.1.2/examples ./ddl2.1.2/dev ./ddl2.1.2/doc plus some other directories. 2) Read ./ddl2.1.2/doc/INSTALL for more detailed notes on installation. 3) Change to the ddl2.1.2 directory. 4) Configure DDL for your system. The configure script generates Makefiles and some other files. Configure will check for some environment variables which allow you to alter the exact configuration of the DDL (see below for details) To run configure, first set the environment variables as required and then type configure For example to configure for rs6000 workstations using ksh: ARCH=rs6000 export ARCH configure The environment variables configure checks are as follows: ARCH: This is required. This environment variable specifies the architecture type you are compiling for, as used when configuring MPICH. Configure uses this value to help it choose compilers, and generate correct library paths. Currently supported architectures: rs6000, sun4, solaris, IRIX, meiko. Others may also work but have not been checked. MPIR_HOME: Optional. Configure looks for an installation of mpi. It checks for the directory mpi in the user's home directory and /usr/local. If you have installed mpi somewhere else or given the directory a different name (eg mpich) then you should set the environment variable MPIR_HOME to point to your mpi directory before running configure. All the other environment variables are optional. You should use them if the configure script does not generate the correct Makefiles when only the ARCH is set. So, try setting ARCH only and configuring and making. If this does not work, examine the Makefile in ./examples to see which variables are incorrect. Set the corresponding environment variables to the correct values, and rerun configure. Set environment variables override the values configure sets. COMM: Optional. This specifies the MPI communications device. If not specified the default is ch_p4. This is only used to generate correct library paths in the examples and dev Makefiles. All communications devices supported. OPTFLAGS: Optional. This specifies optional flags to be passed to the C and Fortran compilers, for example OPTFLAGS="-O" to generate optimised code. The default is OPTFLAGS="-g". Use OPTFLAGS=" " to remove all optional flags. TIME: Optional. This specifies whether the C cgettime and Fortran gettime functions return wall clock time (TIME="wall") or elapsed time (TIME="elapsed"). The default is TIME="wall". FF: Optional. This specifies optional flags to be passed to the Fortran compiler. CF: Optional. This specifies optional flags to be passed to the C compiler. LIB_LIST: Optional. This specifies the libraries to use at link time. LIB_PATH: Optional. This specifies the library paths to use to find the libraries given in LIB_LIST. CC, F77, AR, RANLIB: Optional. Specify the compilers and utilities. If the configure does not work get in touch with me and I will add your setup to the configure script. This will definitely cause problems on many systems! 5) Compile the system libraries and example programs: make 6) IMPORTANT. To run the demonstration programs you also need to install the PARSIM datasets into directory ddl2.1.2/parsim. If you already have these from an older DDL version then copy the old parsim directory structure: cp -r /parsim parsim Otherwise, you must obtain the datasets tarfile that comes with the ddl. Unpack the tarfile in the ddl2.1.2 directory giving a parsim subdirectory. 7) Check. Run the example C program (cdemo.c) to check the compilation was successful: cd examples p4run 1 cdemo Also run the simple FORTRAN program fdemo.f: p4run 1 fdemo The demonstration sparse linear equation solver is provided in tfqmrnc.f. To run it: p4run 1 tfqmrnc Two new programs demonstrate the use of permutation vectors. p4run 1 cmv and p4run 1 ctr The example programs are described in examples/README. (p4run is a simple script to run MPI p4-based programs on a single UNIX workstation. You could also use the scripts provided with MPI. Syntax: p4run eg. 'p4run 4 tfqmrnc' will run the solver program using 4 processes on one workstation.) 8) OPTIONAL. Install library files and include files into separate directory if desired so that you can delete the original sources. Specify the full path for the new directory with PREFIX, eg: make install PREFIX=/home/ssc/sa55/ddl This will create directories: /lib/ /include and install the compiled libraries and DDL include files there. Before deleting the whole ddl source directory tree, copy the examples directory as described in the next step. 9) To develop and run your own DDL programs. Make a copy of the examples directory and use the copy to create your own programs, editing the Makefile appropriately. Edit the paths to MPI and DDL in the Makefile. Some FORTRAN compilers do not support an include path. If this is the case with your compiler you must copy (or link) the FORTRAN include files ddlf.h (./include) and mpif.h (from MPI include directory) to your source directory. Note. To reduce the size of executables, which are generally large, use strip: strip 10) Documentation. Postscript versions of the DDL v2 User Guide and Technical Guide can be found where this software was ftped from. A buggy online version of the User Guide is also available on the World-Wide Web. Just point your Web browser to http://supr.scm.liv.ac.uk/~tim/parsim/parsim.html 11) Have fun! Optimizing code --------------- By default when you install the DDL it will be built with debugging options on. Performance can be improved considerably by removing the debug option and specifying optimization options instead. This is done by setting the environment variable OPTFLAGS (described in the Installation section) before making. On an rs6000 system with xlc, xlf use: -O3 -qarch=ppc In addition, use the strip command to reduce the size of the executables considerably.