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


- last edited 11.11.03 -


Contents

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

1.3.1 Device is not ready
1.3.2 Not enough memory for environment variables

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


 1 DVM-system installation under Windows

1.1  System installation

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:

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.
  2. 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).

  3. Create a directory for the version of DVM-system (for example, DVM_NNN, where NNN - the number of selected version);
  1. Copy to the directory required files from the following list
  2. 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.

  3. Unpack dvmNNN.tar.gz file.
  4. 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.
  1. 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).

If tuning on compilers and MPI-library is required, then in dvminstall.bat file:

Note 1. If neither SETVARSVC nor SETVARSFTN are defined, the installation program tries to find compilers (known to it) in standard locations (on C disk). Searching is started from compilers with maximal number of version. On success corresponding information is output. If Fortran-compiler is not found, corresponding message is output and the installation can be continued for operating without Fortran-DVM programs. If C-compiler is not found, corresponding message is output and the installation is interrupted.

Note 2. Compiling of predictor is possible only by compilers, satisfying to C++ standard (ISO/IEC14882 “Standard for the C++ programming language”), ratified in August 1998. For example it can be compilers Microsoft Visual C 5.0 and later, GNU C++ 2.8.1 version and later and etc. Predictor can not be used with Microsoft Visual 4.0 compiler, you should exclude predictor by commenting out three lines in dvm_sys\makefile.win:

@cd predictor
@$ (MAKE)
………….all
@cd ..

If predictor is required you should install binary version of DVM-system (see below).

  1. In the directory dvm_sys run the command of DVM-system installation:
  2. 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.

  3. DVM-system is ready for use!

Now the user can copy all files from directory dvm_sys\user to his own directory containing DVM-programs and work with DVM-system.

1.2  Installation of binary version of DVM-system
  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:
  2. 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.

  3. Perform tuning on compilers, installed on your computer (see step 6 from section 1.1).
  1. In the directory dvm_bin run the command of DVM-system installation:

dvminstall.bat

On successful execution the message:
“DVM-system is successfully installed”
will be displayed.

1.3  Problems arising during DVM-system installation

1.3.1 Device is not ready

If during installation after the message:

Setting environment for Micrsoft Visual C++ tools

you will see the message:

Device is not ready: disk <name of CD_ROM>

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

…\Program Files\DevStudio\VC\bin\vcvars32.bat

user should comment out or delete the string:

set vcsource=D:\DEVSTUDIO

and start up DVM-system installation once more.

1.3.2 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:

“Out of environment space”

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

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

2  DVM-system installation under UNIX

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-system requirements:

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).
  1. Copy to it required files from the following list
  2. 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:
  4. 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.

  5. Similarly unpack one or several documentation files; and as result, additional directory dvm_sys/doc will appear.
  1. 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

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.
  1. 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]
  2. In dvmrun variable one of the scripts (probably corrected), provided by DVM-system and/or placed in dvm_sys/driver/src directory is specified.
  1. 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.

Note 4. The platforms subdirectory contains the files with values of parameters for concrete platforms, DVM-system was installed or approved on. To install DVM-system on such platform it is enough in dvminstall file to specify a name of appropriate file with parameters in the command
setenv PLATFORM <file name>
(or uncomment correspondent line in dvminstall file). In this case all platform variables will be corrected in accordance with patterns from the file;

  1. In the dvm_sys directory run the command:
  2. 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.

  3. DVM-system is ready for use!

Now the user can copy all the files from directory dvm_sys/user to his own directory with DVM programs and works with system.

3. DVM-system verification

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

alltest

in demo directory.

The command performs the following steps:

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

… end of testing DVM …

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:

4. Demonstration program run

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.