=======================================================================
 --> Version 2.1  Latest changes made on: Fri Dec  1 19:14:59 CST 2006

====================== WELCOME to PARMS Version 3 ===================== 

GENERAL:

BEFORE INSTALLING PARMS READ FIRST THE COPYRIGHT  AGREEMENT. 

pARMS -- version 2 is a new version of pARMS which has been reimplemented
completely. This version includes 

-- The restrictive additive schwarz procedures (RAS) 

-- schur complement techniques with RAS. 

-- ddPQ ordering for local matrices.. [However, these will Schur
   complement techniques will not support ddPQ ordering] 

-- deflated gmres accelerator

pARMS has been written mainly by Zhongze Li.
-- various contributions to the code from 
   ** Yousef Saad 
   ** Masha Sosonkina
-- other contributors: Brian Suchomel, Matthias Bollhoefer, Na Li,
  
------------------------------------------------------------------------------ 

I. INSTALLING pARMS.

  a) Copy the appropriate conf/makefile.XX to makefile.in in this 
     directory

  b) Edit makefile.in to change the paths of PARMS_ROOT, BLAS and MPI.

  c) Type 'make' to build the library -- 

II. Running the examples 

  a) Now try running the  example with systems from Finite Difference
     matrices.  Enter directory grid and type 'make dd-grid.ex' 
     to build all the executable and run it. Recall however that there
     the number of processors is restricted to being a multiple of
     nprocx*nprocy [see input file and README for details] 

  b) Now try running some examples with general matrices. 
     Enter directory 'examples/general'. There are several options:
     -- if you want a simple run with the partitioner 'dse' available with
        parms type make dd-HB-dse.ex  and run the executable dd-HB-dse.ex
     -- if you want a run with the partitioner 'metis' you need to
        modify the makefile and change the flags XIFLAGS and XLIB 
        to give a path for the library and the include directory.. 
     -- there are fortran90 versions of the above two test programs too
     -- can also 'make allexe' to build both driver programs above 
    
  c) Enter directory petsc and type 'make BOPT=X dd-petsc.ex' to build
     the petsc version of driver program. X stands for compile option
     used for building PETSc library.

III Details on the test runs 
   There are three subdirectories: grid, general, and petsc.
   a). The file dd-grid.c, and fdd-grid.F on subdirectory grid 
       solve a poisson equation in parallel. The scale of problem 
     	 on each PE is fixed.
   b). The files dd-HB-dse.c, dd-HB-metis.c, fdd-HB-dse.F, and
       fdd-HB-metis.F in subdirectory 'general'
       show how to solve a system with a general matrix with pARMS.
   c). The file dd-petsc.c on subdirectory petsc shows how to use
       preconditioners in pARMS as add-ons to PETSc.

IV. Sequences in which routines are called.
  a). Partition the mesh or graph using a partitioner such as  Metis,
      or dse (included), or ParMetis, or zoltan, etc...  
  b). Create a map object based on the output from a mesh
      partitioning software. For example, based on the output from
      the Metis, you may create a map object by calling function
      parms_MapCreateFromGlobal(...). 
  c). Create matrix and vectors based on the map created
      above. parms_MatCreate(&mat, map); parms_VecCreate(&rhs,
      map); parms_VecCreate(&sol, map);
  d). Insert entries into the vectors and the matrix. Note that
      the indices of entries are in global labeling.  
  e). Set up the matrix and the vectors by calling
      parms_MatSetup(mat); parms_VecSetup(vec); After call above
      two functions, one cannot insert entries to the matrix and
      vector anymore.  
  f). Create a preconditioner based on the matrix created
      above. parms_PCCreate(&pc, mat); You can set the type of the
      preconditioner by parms_PCSetType. Currently, PCBJ(block
      Jacobi), PCSCHUR(Schur complement), PCRAS(restrctive
      additive Schwarz) are available. More robust preconditioner
      like SCHURRAS will be available soon-- 
  g). Call parms_PCSetup(pc) to create the preconditioning matrix. 
  h). Create a solver based on the matrix and the preconditioner
      created above. parms_SolverCreate(&solver, mat, pc); 
  i). Solve the linear equation. parms_SolverApply(solver, rhs, sol);
