
======================
examples/grids directory
======================

grids contains test drivers related  to simple 2-D and  3-D centered
finite difference  elliptic PDEs on rectangular  domains.  The drivers
call subroutines included in the  library to generate a linear systems
associated with  the 5-point (or  7-point) discretization of  a simple
elliptic operator  on a rectangular  region.  Each node  generates its
own part of the 5/7-point matrix using a simple regular partitioning.

-----------------------------------------------------------------------

IMPORTANT FEATURES:

-- all preconditioners/ accelerators in pARMS can be tested with the one
   drivers provided here by either changing the parameters of the input
   file.
   
-- Standard and Flexible GMRES (FGMRES) is used  as the accelerator by
   the driver dd-grid.c  (or fdd-grid.F for FORTRAN).

-- Only vertex based partitioning can be tested- [See the end of this
   file for a desciption]   	
   The driver dd-grid.c tests a vertex-based partitioner.
   The driver fdd-grid.F tests a vertex-based partitioner.

NOTES: 1. THE INPUT FILE FOR THESE TEST PROBLEMS SPECIFIES THE PROBLEM
SIZE  ON EACH PROCESSOR,  RATHER THAN  THE PROBLEM  SIZE OF  THE WHOLE
PROBLEM ON ALL PROCESSORS.  THE EXECUTION TIME WILL THEREFORE INCREASE
WITH  THE NUMBER OF  PROCESSORS SINCE  THE SIZE  OF THE  PROBLEM BEING
SOLVED  INCREASES.  IN  PERFECTLY  SCALABLE CASE,  THE EXECUTION  TIME
SHOULD BE CONSTANT.

2. The  inputs specify  mprocy and  mprocx  -- the  dimensions of  the
virtual processor grid  in each of the x and  y directions. The number
of processors in  the z direction is determined  by dividing the total
number of  processors by mprocx*mprocy --  If nproc/(mprocx*mprocy) is
not an integer the program will abort.

-----------------------------------------------------------------------

CONTENTS: 
========== 

The makefile provided will make the executable by invoking its name

* make dd-grid.ex  
  runs a vertex-based partitioned problem only. 
  Preconditioned (F)GMRES is used as a solver

To compile  the code in grids,  make sure that the  makefile.in in the
home directory  has  been configured properly and make sure to
have  the library  generated [make  all at  the top  directory  -- see
instructions on how to make the library]

The other files in this directory are:
	
- fdmat.f, a suite or routines adapted from SPARSKIT for generating
           5-point and 7-point finite difference matrices

- functs.f, functions for defining the PDE being solved on the unit
            square - needed by fdmat.f 
      
- aux.c,    reads input parameters for the run from a file

- inputs   : input file for various parameters 


NOTE: The functions defined in the above files handle both the real 
      and complex cases. See the driver for the preprocessor calls
      to the respective functions.
-----------------------------------------------------------------------

INPUT FILE 
===========

A sample of the input file follows

ras            parallel preconditioner (RAS, SCHUR, BJ)
arms           local preconditioner (ilu0, iluk, ilut, arms)
0.01           eps(tolerance for inner iteration)
1.0e-6         eps1(tolerance for outer iteration)
4              nlev(number of levels for ARMS)   
100             bsize(block size for block independent sets)
0.1            tolind(tolerance used in independent set)
60             im (krylov subspace size for outer iteration)
200            maxits (outer fgmres)
5              kim (krylov subspace size for inner iteration)
5              itsgmr(inner fgmres)
20             lfil0(ilut, iluk and arms for lfil[0-3])
20             lfil4(schur)
20             lfil5(ILUT L, ILUT U)
0.001          droptol0(droptol[0=3], L, U, L^{-1}F, EU^{-1}
0.001          droptol4(for schur complements at each level)
0.001          droptol5(for ILUT in last level Schur Complement)
2              mprocx (number of processors in the x direction)
2              mprocy (number of processors in the y direction)
100            xnmesh, nx = xnmesh*mprocx
100            ynmesh, ny = ynmesh*mprocy

-----------------------------------------------------------------------

===== 
USAGE
======

Once you have the driver dd-grid.ex, you can execute 

dd-grid.ex 

(for example on the sp:

>>   poe dd-grid.ex -hostfile host.file -procs 4 

will excecute on 4 processors) 

In this case, the driver will  use the input file "inputs" given above
and will write the results on standard output.

You can also specify different input and output files : 

dd-grid.ex infile outfile 

(for example on the sp:

poe dd-grid.ex inp ouot -hostfile host.file -procs 4 ) 

uses "inp" as input file and "out" for output. 

dd-grid.ex filename 

assumes that filename is an input file 

-----------------------------------------------------------------------

========================= 
PRECONDITIONERS AVAILABLE 
========================= 

The following preconditioner methods are available in PARMS:

BJ (Block Jacobi), RAS (Restricted Additive Schwarz), SCHUR(Schur
Complement based Preconditioner)

Local Preconditioners:

ILU0, ILUT, ILUK, ARMS

-----------------------------------------------------------------------

======= 
EXTRAS
======= 

The directory  "extras" contains script files and  sample input files.
*.pbs and *.cmd  are script files for submitting  jobs on SGI
Altix and IBM p690 machines respectively.  These need  to be edited
before being submitted to SGI Altix or IBM p690. They may also
correspond to the specific environment available at the University of
Minnesota... 

-----------------------------------------------------------------------

========================================== 
VERTEX-BASED PARTITIONING
========================================== 

VERTEX based:  

              subdomain 1                   subdomain 2 
        +--------------------------+--------------------------+
        |61   62    63    64    65 | 66    67   68   69   70  |
        |                          |                          |
        |51   52    53    54    55 | 56    57   58   59   60  |
        |                          |                          |
        |41   42    43    44    45 | 46    47   48   49   50  |
        +--------------------------+--------------------------| 
        |31   32    33    34    35 | 36    37   38   39   40  |
        |                          |                          |
        |21   22    23    24    25 | 26    27   28   29   30  |
        |                          |                          |
        |11   12    13    14    15 | 16    17   18   19   20  |
        |                          |                          |
        | 1    2     3     4     5 |  6     7    8    9   10  |
        +--------------------------+--------------------------+ 
                subdomain 3                subdomain 4 

YS 

======================================================================= 
