Scalar Ruge-Stuben AMG stand-alone and preconditioned GMRES
solver
A. T. Papadopoulos, Oxford University Computing Laboratory
June 2004

Algorithms mainly following Stuben's GMD report 70, also found as 
an appendix to the Multigrid book by Trottenberg, Oosterlee 
and Schuller. 
GMRES routine from Saad's SPARSKIT, with obvious changes.

See also relevant parts of my thesis ;) 

This is purely a research code. Please don't expect it to 
run smoothly in all situations and for matrices departing 
from the classes described in Stuben's work.  

Known cases of strange behaviour: 
1. negative main diagonals, 
2. too many strong positive off-diagonals,
3. scaling by main diagonal might be necessary 
in some cases for smoothers to work.

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

Compiling: unzip into a directory, and then f90 *.f90

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

Changes to solver parameters and options listed below 
must be performed manually in appropriate parts of the code 
and then recompile. 

Options requiring manual change in code:
 
Parameters on line 2 of main.f90 controlling max. system size (maxn),
max. number of nonzeros in any single operator (maxnza), 
max. total number of nonzeros in all coarse operators or 
inter-grid transfer operators (maxsize), 
max. number of levels allowed (maxlevs),
max. total number of unknowns at all levels incl. finest (maxsize2).

Adjust as required. 
Under normal conditions, maxsize < 3 maxnza, maxsize2 < 5 maxn.

main.f90, line 138: Stand-alone convergence tolerance oldres, set at 1e-9
main.f90, line 187: GMRES convergence tolearnce eps, set at 1e-10
main.f90, line 188: GMRES max. allowed iterations for conv. maxits, set at 400
main.f90, line 191: GMRES restart value im, set at 50
setup.f90, line 82: max. size of coarse grid before assuming it is the 
coarsest one wn, set at 40

The maximum allowed size of the coarsest grid operator is now 100 
(so wn above should be set <= 100).
To make it larger change size of array fullA in line 23 of setup.f90, 
line 13 of main.f90, line 15 of amgmres.f90, line 16 of bicgstab1.f90, 
line 18 of vcycle.f90, line 21 of wcycle.f90.

Bi-CGSTAB can be enabled by commenting out lines 87 and 218 of main.f90 
and removing comment (!) from lines 85 and 86.

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

Required input: the system's coefficient matrix in simple coordinate format 
ordered by columns, with header row, in file fort.9 - see example in this 
zip file.
Optional input: the right-hand-side vector in file fort.7 

The user is also asked to input the following for each run of the code:

> 1. rhs available in fort.7 , 2. rhsv of ones 
 
choice of right-hand-side vector, 1 or 2

>  1 for V-cycle, 2 for W-cycle, 3 for V^* cycle

choose cycle type 

> enter max number of cycles in stand-alone iteration

say 20-30

> enter 2 for GS-CF, 3 for SPAI(0), o/w simple line GS
> 3 n/a for W

cycle smoother; 1 for point GS, 2 for GS-CF, 3 for SPAI(0)
SPAI(0) not available for W-cycles.

> enter number of smoother iterations as pre-smoother

pre-smoothing iterations at each level

> enter number of smoother iterations as post-smoother

post-smoothing iterations at each level

> enter alpha. suggested value = 0.25

strength-of-connections value for negative off-diagonals

> enter beta. suggested value=0.50
 
Strength-of-connections value for positive off-diagonals.
Only meaningful if interpolation type 4 used below. 

> 0 for standard interp. with recoloring,
> 3 for add-positives-to-diagonal,
> 4 for all couplings, 5 for Stuben direct interp

Interpolation types. If matrix has no strong positive couplings 
then options 3, 4 should default to direct interp. (5).

> gmres: enter # cycles as preconditioner

1, rarely 2...

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

Initial guess/approximation vector for all iterations: 0

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

Output: 

Setup phase: Some on-screen output, including 
dimension of each coarse level,
timging of individual setup components, etc. 

Stand-alone cyclic iteration: current residual Euclidean norm 
and iteration contraction rate at each cycle.

Right-Preconditioned GMRES: iterations required for convergence is outputed.
Iteration data stored in fort.4, solution vector in fort.17

Final output: a variety of data, including operator complexities 
(nnz of coarse grid operators compared to nnz of finest), 
timings and C/F splittings at each level. 

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

Important note: 
In this code the set of transpose strong dependencies 
is generated by simply taking the columns of the 
matrix of strong dependencies (the set of strong 
dependencies is of course given by the rows of the 
same matrix).

This could potentially create problems for systems 
with large differences in column scalings.

This can be solved by adding a couple of lines of code
in the appropriate subroutine to compute the column-wise
strong dependencies via the usual RS rule.

The interested user is encouraged to look at and 
change the source code as required. 

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

Have fun using this code,

Andreas