DVM-system of parallel program development
Installation guide
* September, 2003 *

1 DVM-system installation under Windows

1.1 System installation
1.2 Installation of binary version of DVM-system
1.3 Problems arising during DVM-system installation

2 DVM-system installation under UNIX
3 DVM-system verification
4 Demonstration program run

DVM-system is delivered in two variants: as source files (file dvmNNN.tar.gz) and as binary version - executable programs and libraries (file dvmNNN_win.zip). NNN in file name is a number of DVM-system version. In the first case during installation all the components of the system are compiled, but in the second case only tuning on a computer configuration is performed. Different available versions of DVM-system are on the site www.keldysh.ru/dvm.

DVM-system requirements:

• operation system Windows95/NT and later;
• Microsoft Visual C++ 5.0 version and later (4.0 version can be used with some restrictions, see below);
• Microsoft Fortran PS 4.0 or Digital Fortran 5.0 and later. (For programs in Fortran-DVM language);
• Implementation of MPI standard for Windows95/NT (for DVM-system in source files only);
• WINZIP - standard Windows utility to unpack files. It is recommended as it supports conversion of text files to Windows format.

To install DVM-system the following steps should be done:

1. Install one of the implementations of MPI standard. If you intend to work with DVM-system on single computer (development and debugging of DVM-programs), you can use implementation MPICHWIN (file mpichwin.zip) from our site (www.keldysh.ru/dvm). For parallel job on several nodes network version of MPI is required. DVM-system was tested on MP-MPICH 1.3.0a for Windows (http://www.lfbs.rwth-aachen.de/mp-mpich/download/) and HPVM1.9.

To install MPICHWIN create a directory (for example, C:\MPICHWIN) and copy file mpichwin.zip to the directory and unpack it.

As a result the following folders and files will be created:

include\	- include-files;
lib\	- MPI library;
copyright*	- copyright information.

For the installation of new versions of DVM-system this step can be skipped (if not stated otherwise in the instruction).

2. Create a directory for the version of DVM-system (for example, DVM_NNN, where NNN - the number of selected version);
   

3. Copy to the directory required files from the following list
   

dvmNNN.tar.gz	- DVM-system as source files;
dvmUSRrhtm.tar.gz	- user documentation in Russian;
dvmSYSrhtm.tar.gz	- system documentation in Russian;
dvmUSRehtm.tar.gz	- user documentation in English;
dvmSYSehtm.tar.gz	- system documentation in English.

4. Unpack dvmNNN.tar.gz file.

As a result the following folders and files will be created:

dvm_sys\
		cdvm\		- C-DVM converter;
		driver\		- DVM-system service tools;
		examples\		- demonstration programs;
		fdvm\		- Fortran-DVM converter;
		platforms\		- parameter sets for the platforms;
		pppa\		- DVM-program performance analyzer;
		predictor\		- DVM-program performance predictor;
		rts\		- DVM-program support system;
		copyright		- copyright information;
		dvmclean*		- programs to clear directories of DVM-system;
		dvmcleanall*		- DVM-system uninstall programs;
		dvminstall*		- DVM-system install programs;
		makefile*		- system files of installation and uninstallation support;
		win_size_5.txt		- check file for unpacking.

Unpack program must support representation of text files in Windows format. This is checked by the file win_size_5.txt. Its size in Windows environment after unpacking must be equal to 5 bytes. Otherwise use other tools to unpack.

5. Unpack one or several documentation files; and as result, additional directory dvm_sys\doc will appear.

6. Perform tuning on compilers and MPI-library, installed on your computer. This step can be skipped, if you use MPI-library MPICHWIN, located on C:\MPICHWIN and compilers, known to installation program. The list and standard location of these compilers are defined in dvminstall.bat file as lines-comments, setting variables SETVARSVC (for C-compiler) and SETVARSFTN (for Fortran-compiler).

• Uncomment one of the lines, defining SETVARSVC variable and correct its value. The variable defines the full name of the program setting environment variables for C (C++) compiler;
• To work with Fortran-DVM programs uncomment one of the lines with SETVARSFTN variable setting and correct its value, which defines the full name of the program, setting environment variables for Fortran-compiler;
• If above programs require the parameters they can be defined in ARGSETVARSVC and ARGSETVARSFTN variables respectively;
• Correct (if it is necessary) the variables specifying the options of compilers (variables C (OPTCC), C++ (OPTCXX), Fortran (OPTFORT), linkers of C and Fortran programs (OPTLINKER and OPTFLINKER).
• Correct (if it is necessary) parameters, specifying version of MPICH library (variables MPI_HOME, MPI_LIB, MPI_INC).

7. In the directory dvm_sys run the command of DVM-system installation:

dvminstall.bat

On successful execution the message:
'DVM-system is successfully installed'
will be t displayed and the following folders (besides listed above) will be created in dvm_sys directory:

bin\	-	DVM-system executable files;
demo\	-	copy of demonstration programs to verify DVM-system;
lib\	-	support system library;
par\	-	support system parameters;
user\	-	files should be copied into user directories.

On errors examine logfile.txt files appeared in \src subdirectories of rts, cdvm, fdvm, driver, pppa, predictor directories.

8. DVM-system is ready for use!

1. Copy dvmNNN_win.zip file to the directory DVM_NNN, created by you, and unpack it. As a result the following folders and files will be created:
   

dvm_bin\
	bin\	- executable files of DVM-system;
	examples\	- demonstration files of DVM-system;
	include\	- include-files of DVM-system;
	lib\	- system support library;
	par\	- support system parameters;
	dvminstall.bat	- DVM-system install program.

2. Perform tuning on compilers, installed on your computer (see step 6 from section 1.1).

3. In the directory dvm_bin run the command of DVM-system installation:

1.3.1 Device is not ready

If during installation after the message:

you will see the message:

it means that Microsoft Visual C++ attempts to read CD_ROM. To turn off CD_ROM in the file:

user should comment out or delete the string:

and start up DVM-system installation once more.

It is possible that during the first installation or while executing DVM-program you will see the following message:

In this case you should increase the memory by one of the three ways (3072 is minimal memory size for DVM-system environment variables):

• in file config.sys you can specify the string:
  Shell=command.com /E:3072 /P
  and then restart your computer;
• when you run your programs previously change properties of corresponding object in MS-DOS Prompt or Far Manager window (select MS-DOS Prompt or Far Manager icon and click right button of a mouse) as follows

  Properties

  ->

  Memory

  ->

  Initial environment

  = 3072

• if you run any bat-file from Explorer, previously change the object (bat-file) properties as follows:

  Properties

  ->

  Memory

  ->

  Initial environment

  = 3072

The first two ways are preferable as it is sufficient to do only once.

DVM-system supposes the presence of two computers - instrumental (host-computer) and parallel one. One of the nodes of the parallel computer can be used as instrumental computer. The preparation and startup of parallel programs, an analysis and prediction of parallel program execution are performed on the instrumental computer.

DVM-system installation is performed on instrumental computer in the selected DVM-directory and consists of the preparing

• DVM-library for parallel computer,
• Fortran-DVM and C-DVM compilers,
• DVM-driver,
• performance analyzer,
• predictor

DVM-system requirements:

• UNIX^TM operating system;
• csh shell or its analogue;
• C and C++ compilers on host-computer;
• C and Fortran compilers on parallel computer;
• MPICH library;
• make utility;
• ar utility for host-computer and parallel computer;
• gunzip, tar utilities to unpack files.

To install DVM-system the following steps should be done.

1. Select or create a directory for given (NNN-th) version of DVM-system (for example, DVM_NNN).

2. Copy to it required files from the following list
   

dvmNNN.tar.gz	- DVM-system;
dvmUSRrhtm.tar.gz	- user documentation in Russian;
dvmSYSrhtm.tar.gz	- system documentation in Russian;
dvmUSRehtm.tar.gz	- user documentation in English;
dvmSYSehtm.tar.gz	- system documentation in English.

3. Unpack dvmNNN.tar.gz file. For example run:

gunzip -c dvmNNN.tar | tar xf -

As a result the following folders and files will be created:

dvm_sys/
	cdvm/	- C-DVM converter;
	driver/	- DVM-system service tools;
	examples/	- demonstration programs;
	fdvm/	- Fortran-DVM converter;
	platforms/	- parameter sets for the platforms;
	pppa/	- DVM-program performance analyzer;
	predictor/	- DVM-program performance predictor;
	rts/	- DVM-program support system;
	copyright	- copyright information;
	dvmclean*	- programs to delete intermediate files;
	dvmcleanall*	- DVM-system uninstall programs;
	dvminstall*	- DVM-system install programs;
	makefile*	- installation and uninstallation support system files.

4. Similarly unpack one or several documentation files; and as result, additional directory dvm_sys/doc will appear.

5. In dvminstall file correct the parameters specifying invocation of required tools and compilers for host-computer and parallel computer:

CC - C compiler for host-computer;
CXX - C ++ compiler for host-computer;
LINKER - linker for host-computer;
MPI_BIN - a directory containing commands of invoking of the compilers and startup of the programs for parallel computer;
PCC - C compiler for parallel computer;
PFORT - Fortran compiler for parallel computer;
PLINKER - linker of C-programs for parallel computer;
PFLINKER - linker of Fortran-programs for parallel computer;
lm - linking of mathematical libraries;
Par - utility for creation of libraries for parallel computer;
dvmrun - command (or a script) for startup of DVM-programs (see below Note 3);
MPI_INC - directory with include-files of MPI-library;
MPI_LIB - MPI library files.

Note 1.
Parameters are specified in the command format
setenv <PARAMETR> <value>
If the value consists of the several words, divided by spaces total value should be enclosed in quotes.

Note 2.
If compilers and linkers for parallel computer (PCC, PFORT, PLINKER, PFLINKER variables) is invoked by standard scripts or the programs providing tuning on the necessary version of the MPI-library (for example mpicc, mpif77) MPI_LIB, MPI_INC variables are not needed in correction. MPI_BIN variable can be used as a prefix when specifying PCC, PFORT, PLINKER, PFLINKER variables, and also in a script of DVM-program startup.

Note 3.
After compilation DVM-program is an usual MPI-program, but requiring some input information for its operating. DVM-program startup by dvm run : command consists of two steps. At the first step the input information necessary for execution DVM-program is prepared. At the second step the command (or the script), specified in dvmrun variable is performed. The amount of the processors necessary for execution is passed to the command (or to the script) as the first parameter. Thus, if at the first step the actions necessary for execution DVM-program on any platform is performed (input information is prepared) on the second step specificity of program startup on concrete computer should be taken into account.

DVM-system provides the scripts taking into account such features of program startup systems for concrete platforms, as

• startup command format (for example parsytec.run);
• presence of the scheduler of tasks queue and the features of its operating (for example runmpi.all);
• features of working with distributed file system (NFS) (for example soliton.run);
• implementations of MPI (mpich, lam) (for example runmpich, runlam);
• necessity to create a file describing the job for execution (for example run1000.mpi).

These scripts are in dvm_sys/driver/src directory. Their names are specified in parameter files for appropriative platforms (see Note 4), as values of dvmrun variable. During installation process the script specified in dvmrun variable is copied in dvm_sys/bin directory, whence will be executed at DVM-program startup.

When installing DVM-system on the new platform the following variants of organization of DVM-program startup are possible:

1. dvmrun variable is assigned by empty value (setenv dvmrun). In this case to start DVM-program it is required at first to perform dvm run <grid> command to create necessary files and then to start DVM-program as MPI-program on the given computer. (Here <grid> - a virtual grid of processors DVM-program should be executed on). It is necessary to take into account, that in the current directory (where the program will be executed) there should be the files generated by dvm run <grid> command.

2. In dvmrun variable the command of MPI-program start on the given computer with required options is specified. In this case, if the value of dvmrun variable is specified as
   setenv dvmrun 'mpirun [mpi_options] -np '
   then if jac2d program is started by the command
   dvm run 4 2 [cur_options] jac2d [args]
   the following command will be performed
   mpirun [mpi_options] -np 8 [cur_options] jac2d [args]
   
3. In dvmrun variable one of the scripts (probably corrected), provided by DVM-system and/or placed in dvm_sys/driver/src directory is specified.

4. The new script is written (taking into account all above stated). In this case it is necessary in dvmrun variable to specify its full name or its idle name, but to put it to the place accessible for execution (the directory should be present in path).

In 2, 3, 4 cases DVM-programs are started by standard way as it is described in appropriate DVM-system documents.

6. In the dvm_sys directory run the command:

dvminstall

On successful execution the message:
'DVM-system is successfully installed'
will be output and the following additional subdirectories will be created in dvm_sys directory:

bin/	-	DVM-system executable files;
demo/	-	copies of demonstration programs to verify DVM-system;
lib/	-	support system library;
par/	-	support system parameters;
user/	-	files that should be copied in user directories.

On errors examine logfile.txt files appeared in /src subdirectories of rts, cdvm, fdvm, driver, pppa, predictor directories.

7. DVM-system is ready for use!

To verify correctness of DVM-system installation it is recommended to run standard test procedure. You should run

in demo directory.

The command performs the following steps:

• starts up standard testing procedure which executes the testcdvm.cdv and testfdvm.fdv programs in different debug modes;
• compares execution results of each of the program with reference ones supplied with the system in files testcdvm_res, testfdvm_res;
• starts predictor (predictor of DVM-program performance) for jac1d.cdv and compares the predicted results with standard results supplied with the system in file pred_res;

Step names and results of comparison are displayed for the user at the screen. If the results are compared at all the steps the message

is displayed. It means that DVM-system has been installed correctly.

If some step is finished with an error a prompt is displayed and the user can either interrupt (Ctrl+C) or continue (any key) the test execution.

If results are not identical at any step it is necessary to check correctness of performing all steps of the instruction. Detailed information about DVM-program startup modes, used by test procedure and about all diagnostics messages of DVM-system is presented in the following documents:

• "Debugging DVM-program. User guide";
• 'C-DVM compiler. User guide';
• 'Fortran-DVM compiler. User guide'.

The directory demo contains the set of C-DVM and Fortran-DVM programs which show capabilities of DVM-system to realize different algorithms:

gauss_c.cdv, gausf.fdv, gaus_wb.cdv, gauswh.fdv - algorithm of Gaussian Elimination method;
jac1d.cdv, jac.fdv, jac2d.cdv, jacas.fdv, jacross.cdv, sor.fdv - Jacobi algorithm;
mgrid.cdv - multigrid task.
redb.cdv, redbf.fdv - red-black successive over-relaxation;
tskcdv, tsk_lp.cdv, tsk_ra.cdv, task2j.fdv, tasks.fdv, taskst.fdv - multi-block tasks.

(see Fortran-DVM. Language description. Annex 2. Code examples.
C-DVM. Language description. Appendix 1. Examples of C-DVM programs.)

In demo directory you can run any from listed above programs. For example, to run jac1d.cdv and jac.fdv you should perform

dvm c jac1d.cdv - compilation of jac1d.cdv (C-DVM);
dvm run 2 2 jac1d - execution of jac1d at 2x2 processor matrix;
dvm f jac.fdv - compilation of jac.fdv (Fortran-DVM);
dvm run 4 1 jac - execution of jac1d at 4x1 processor matrix.

The alldemo command sequentially executes all demonstration programs in different debug modes.