	User guide for migration from Mark-4 VLBI Analysis System Calc/Solve 
        to Mark-5 VLBI Analysis System Calc/Solve


	I. Introduction.
        ~~~~~~~~~~~~~~~~


1) Mark-5 VLBI analysis System Calc/Solve has the following differences 
   with respect to the Mark-4 VLBI Analysis System:

   a) Mark-4 Calc/Solve was written in Fortran77 and assumed all integer
      constants and integer variables as Integer*2, except those which were
      explicitly declared as Integer*4. Mark-5 Calc/Solve is written in
      Fortran95 and assumes all integer constants as Integer*4. All integer
      variables are explicitly defined as Integer*2 or Integer*4.

   b) Mark-4 Calc/Solve could run only under HP-UX 9.0, 10.x and 11.x
      Mark-4 Calc/Solve is designed to run under both HP-UX 10.x, HP-UX 11.x
      and Linux operating systems. Caveat: as of 2003.07.25 not all programs 
      from Mark-5 Calc/Solve run under Linux.

   c) Mark-5 Calc/Solve uses advanced optimized block algorithms for matrix 
      multiplication and matrix inversion, while Mark-4 Calc/Solve used 
      LAPACK procedures of the level 2. 


2) This transition required gigantic work. Code of all Fortran programs, 
   without exception, was transformed several times. First, programs which 
   required implicit definitions of integer variables and constants as 
   Integer*2 (more than 90% of source code) were transformed to the form which 
   required implicit definition of integer constants as integer*4. All integer
   variables are explicitly defined as integer*2 or integer*4. It was done
   by a sophisticated program which analyzed listing of Fortran77 compiler,
   analyzed the type of constants or variables and inserted (or in some 
   cases deleted) wrappers for type conversion where it was needed. Second,
   all code was automatically converted to Fortran95 free style syntax.
   Handling of comments, line continuation, derived type, directives, 
   tabulations, include statements and many other things was changed in order 
   to conform Fortran95 specifications. In addition to that calls to some 
   HP-UX specific system functions was changed in such a manner that they
   can be compiled and executed under different platforms. Third, 711 source 
   code files were edited manually to fix the minor remaining problems which 
   software for automatic conversion did not fix. Fourth, all makefile were 
   written anew. Fifth, the support subsystem for flawless compilation/linking 
   under HP-UX and Linux was re-designed.
   

	II. Changes.
        ~~~~~~~~~~~~


1) Programs apriori, ut1pm and skeleton were removed from the distribution 
   kit. Dbedit and independently calc are able to do the functions which 
   apriori, ut1pm and skeleton did in the past.

2) sscat was removed. Its function was unclear.

3) CNPLT was replaced with REPA. CNPLT referred to the graphic libraries 
   of object modules for HP-UX which existed long time ago. Source code of
   these libraries was lost.

4) Block algorithms for matrix multiplication and matrix inversion were 
   implemented. It should significantly boost performance of Calc/Solve
   when it runs solutions of large dimensions. For example, inversion of
   matrix 1000x1000 runs faster by the factor of 4.5 on HP 9000/785 than
   the old Mark-4 software did.
   
5) matvec_test utility for tuning matvec library was added.

6) Handling local customization files was changed (see below).

7) No center_label is needed any more.


        III. Migration.
        ~~~~~~~~~~~~~~~


   Since source of Mark-5 Calc/Solve is incompatible with source code of
Mark-4 Calc/Solve. Mark-5 Calc/Solve should reside in a different directory
tree than the Mark-4 Calc/Solve. 

1)   Before compilation you should 

a) carefully read INSTALL.hpux or INSTALL.linux
   ( 
     They are accessible also as 
     http://gemini.gsfc.nasa.gov/solve_root/help/INSTALL.hpux
     http://gemini.gsfc.nasa.gov/solve_root/help/INSTALL.linux
   )

b) create Mark-5 Calc/Solve root directory
c) set environment variable MK5_ROOT with the name of this directory.
d) create $MK5_ROOT/local directory
e) Create $MK5_ROOT/local/solve.lcl file. This file keeps your local
   customization. It is recommended that you should print the old 
   $MK4_ROOT/local/<center_label>.lcl file.

   Or you can should edit it:
   i) Remove code after the line 
            ! === | ../src/solve/include/matvec.i      |

   ii) Append contents of the file $MK5_ROOT/example/matvec_hp_785.lcl 
       or $MK5_ROOT/example/matvec_celeron.lcl 
       to the end of the $MK5_ROOT/local/solve.lcl file
       ( You can find this file on the Web in
       http://gemini.gsfc.nasa.gov/solve_root/example/matvec_hp_785.lcl or
       http://gemini.gsfc.nasa.gov/solve_root/example/matvec_celeron.lcl 
       )

   iii) Replace all occurrences of the name MK4_ROOT with MK5_ROOT in the
        $MK5_ROOT/local/solve.lcl file.

   Alternatively you can browse solve.lcl which is currently used by
   Goddard from http://gemini.gsfc.nasa.gov/solve_root/local/solve.lcl
   copy it to $MK5_ROOT/local/solve.lcl, carefully inspect it and edit.

f) Copy file $MK4_ROOT/local/<center_label>.eops to $MK5_ROOT/local/eops
             $MK4_ROOT/local/<center_label>.eopi to $MK5_ROOT/local/eopi.lcl
             $MK4_ROOT/local/<center_label>.gae  to $MK5_ROOT/local/gae.lcl
             $MK4_ROOT/local/<center_label>.dbi  to $MK5_ROOT/local/dbi.lcl
             $MK4_ROOT/local/<center_label>.dbs  to $MK5_ROOT/local/dbs.lcl

   If you do not have one of these files, Calc/Solve installation will work,
   but you will see warning messages.

2) Download the latest distribution kit from
   http://gemini.gsfc.nasa.gov/solve

   Untar it. ( tar -xvf <distributive_kit_file> ). You can do it in any
   directory with 30Mb free space, but it is advisable to do it in directory
   $MK5_ROOT/archive/distr_xxxxxxx where xxxxxxxx is the date of
   the distribution kit, f.e. 20030725

3) cd to that directory and run ./solve_install

4) solve_install makes extensive checks before beginning of compilation.
   If configuration is failed it means that you system either does not have
   necessary software or badly configured. You need communicate with your
   system administrator. Only the system administrator, not folks in Goddard,
   can solve your problem!

   During installation Solve sources four C-shell programs:

   $MK5_ROOT/support/solve_bin
   $MK5_ROOT/support/solve_inc
   $MK5_ROOT/support/solve_lib
   $MK5_ROOT/support/compile_variable.csh

   These C-shell programs set environment variables used for compilation.
   At the end each these C-shell program it looks for 

   $MK5_ROOT/local/bin.lcl
   $MK5_ROOT/local/inc.lcl
   $MK5_ROOT/local/lib.lcl
   $MK5_ROOT/local/comp.lcl

   If such a file exists, it is sourced. These files can contain definitions
   which overwrite definitions of solve environment variables in standard 
   configuration files. For example, if you have blas library in a wrong 
   place and solve cannot find it, and your system administrator is not 
   available to fix this configuration error, you can add definition of the 
   environment variable SOLVE_LIB_BLAS  in $MK5_ROOT/local/lib.lcl:

   #!/bin/csh -f
   setenv SOLVE_LIB_BLAS     "/opt/non_standard_directory/libblas.a"

5) You need update your path. It should contain $MK5_ROOT/bin directory
   and should not contain $MK4_ROOT/bin directory.

6) You need update the user file with definitions of Solve related environment
   variables. It should contain definition of $MK5_ROOT, but not $MK5_ROOT
   If you are going to compile and link Calc/Solve you have to add 
   "source /lyra5/mk5/support/solve_var" in your strat-up file after 
   definition of $MK5_ROOT.

7) You may need to copy a command file for Solve ghostscript viewer and 
   Solve editor from $MK4_ROOT/bin to $MK5_ROOT/bin

8) If you run long Solve solutions you may be interested in tuning performance
   of matvec libraries. Refer to $MK5_ROOT/help/matvec_tune.txt for details. 
   Keep in mind that after changes in $MK5_ROOT/local/solve.lcl you have to 
   re-compile/re-link Calc/Solve in order these changes took effect.
   For re-compiling Calc/Solve you need
   a) stop all Solve processes or patiently wait for their completion;
   b) run C-shell program $MK5_ROOT/support/make_all_mk5

2003.07.25_20:02:52
