DVM-system of parallel program development
Installation guide
* March, 2010 *

1 DVM-system installation under Windows

       1.1 System installation

       1.2 Problems arising during DVM-system installation

             1.2.1 Not enough memory for environment variables

2  DVM-system installation under UNIX

3  DVM-system verification

4  Demonstration program run

DVM-system is delivered  as source files (file dvmNNN.tgz). NNN in file name is a number of DVM-system version. During installation all the components of the system are compiled and 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 Windows XP, Windows Vista, Windows7
• C/C++ Microsoft Visual Studio .NET 2003 and later;
• Intel Fortran 9.0 and later.  (For programs in Fortran-DVM language);
• Implementation of MPI standard ;
• 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.  DVM-system was tested on MPICH2 32-bits realization of MPI-2, implemented in Aragone National Laboratory (USA) (http://www.mcs.anl.gov/research/projects/mpich2/).

   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.tgz	- 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.tgz 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 one of MPI realizations (for example, MPICH2) located on “standard” place 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 MPI_HOME (for MPI library), 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 MPI 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 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.2.1 Not enough memory for environment variables

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

  PropetiesèMemoryèInitial environment = 3072

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

  Propetiesè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.tgz	- 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:

   tar -xzf dvmNNN.tgz

   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.