Examples

The code reported in Figure  shows how to set and apply the default multi-level preconditioner available in the real double precision version of MLD2P4 (see Table ). This preconditioner is chosen by simply specifying 'ML' as second argument of mld_precinit (a call to mld_precset is not needed) and is applied with the BiCGSTAB solver provided by PSBLAS. As previously observed, the modules psb_base_mod, mld_prec_mod and psb_krylov_mod must be used by the example program.

The part of the code concerning the reading and assembling of the sparse matrix and the right-hand side vector, performed through the PSBLAS routines for sparse matrix and vector management, is not reported here for brevity; the statements concerning the deallocation of the PSBLAS data structure are neglected too. The complete code can be found in the example program file mld_dexample_ml.f90, in the directory examples/fileread of the MLD2P4 tree (see Section ). For details on the use of the PSBLAS routines, see the PSBLAS User's Guide [11].

The setup and application of the default multi-level preconditioners for the real single precision and the complex, single and double precision, versions are obtained with straightforward modifications of the previous example (see Section  for details). If these versions are installed, the corresponding Fortran 95 codes are available in examples/fileread/.

Figure: Setup and application of the default multi-level Schwarz preconditioner.

  use psb_base_mod
  use mld_prec_mod
  use psb_krylov_mod
... ...
!
! sparse matrix
  type(psb_dspmat_type) :: A
! sparse matrix descriptor
  type(psb_desc_type)   :: desc_A
! preconditioner
  type(mld_dprec_type)  :: P
! right-hand side and solution vectors
  real(kind(1.d0))      :: b(:), x(:)
... ...
!
! initialize the parallel environment
  call psb_init(ictxt)
  call psb_info(ictxt,iam,np)
... ...
!
! read and assemble the matrix A and the right-hand side b 
! using PSBLAS routines for sparse matrix / vector management 
... ...
!
! initialize the default multi-level preconditioner, i.e. hybrid
! Schwarz, using RAS (with overlap 1 and ILU(0) on the blocks) 
! as post-smoother and 4 block-Jacobi sweeps (with UMFPACK LU
! on the blocks) as distributed coarse-level solver
  call mld_precinit(P,'ML',info)
!
! build the preconditioner
  call mld_precbld(A,desc_A,P,info)
!
! set the solver parameters and the initial guess
  ... ...
!
! solve Ax=b with preconditioned BiCGSTAB
  call psb_krylov('BICGSTAB',A,P,b,x,tol,desc_A,info)
  ... ...
!
! deallocate the preconditioner
  call mld_precfree(P,info)
!
! deallocate other data structures
  ... ...
!
! exit the parallel environment
  call psb_exit(ictxt)
  stop

Different versions of multi-level preconditioners can be obtained by changing the default values of the preconditioner parameters. The code reported in Figure  shows how to set a three-level hybrid Schwarz preconditioner, which uses block Jacobi with ILU(0) on the local blocks as post-smoother, has a coarsest matrix replicated on the processors, and solves the coarsest-level system with the LU factorization from UMFPACK [8]. The number of levels is specified by using mld_precinit; the other preconditioner parameters are set by calling mld_precset. Note that the type of multilevel framework (i.e. multiplicative among the levels with post-smoothing only) is not specified since it is the default set by mld_precinit.

Figure  shows how to set a three-level additive Schwarz preconditioner, which uses RAS, with overlap 1 and ILU(0) on the blocks, as pre- and post-smoother, and applies five block-Jacobi sweeps, with the UMFPACK LU factorization on the blocks, as distributed coarsest-level solver. Again, mld_precset is used only to set non-default values of the parameters (see Tables -). In both cases, the construction and the application of the preconditioner are carried out as for the default multi-level preconditioner. The code fragments shown in in Figures - are included in the example program file mld_dexample_ml.f90 too.

Finally, Figure  shows the setup of a one-level additive Schwarz preconditioner, i.e. RAS with overlap 2. The corresponding example program is available in mld_dexample_1lev.f90.

For all the previous preconditioners, example programs where the sparse matrix and the right-hand side are generated by discretizing a PDE with Dirichlet boundary conditions are also available in the directory examples/pdegen.

Figure: Setup of a hybrid three-level Schwarz preconditioner.

... ...
! set a three-level hybrid Schwarz preconditioner, which uses 
! block Jacobi (with ILU(0) on the blocks) as post-smoother,
! a coarsest matrix replicated on the processors, and the 
! LU factorization from UMFPACK as coarse-level solver
  call mld_precinit(P,'ML',info,nlev=3)
  call_mld_precset(P,mld_smoother_type_,'BJAC',info)
  call mld_precset(P,mld_coarse_mat_,'REPL',info)
  call mld_precset(P,mld_coarse_solve_,'UMF',info)
... ...

Figure: Setup of an additive three-level Schwarz preconditioner.

... ...
! set a three-level additive Schwarz preconditioner, which uses 
! RAS (with overlap 1 and ILU(0) on the blocks) as pre- and 
! post-smoother, and 5 block-Jacobi sweeps (with UMFPACK LU
! on the blocks) as distributed coarsest-level solver
  call mld_precinit(P,'ML',info,nlev=3)
  call mld_precset(P,mld_ml_type_,'ADD',info)
  call_mld_precset(P,mld_smoother_pos_,'TWOSIDE',info)
  call mld_precset(P,mld_coarse_sweeps_,5,info)
... ...

Figure: Setup of a one-level Schwarz preconditioner.

... ...
! set RAS with overlap 2 and ILU(0) on the local blocks
  call mld_precinit(P,'AS',info)
  call mld_precset(P,mld_sub_ovr_,2,info)
... ...

Remark 3. Any PSBLAS-based program using the basic preconditioners implemented in PSBLAS 2.0, i.e. the diagonal and block-Jacobi ones, can use the diagonal and block-Jacobi preconditioners implemented in MLD2P4 without any change in the code. The PSBLAS-based program must be only recompiled and linked to the MLD2P4 library.