6.1. Using SLES

Up: Contents Next: Solving Successive Linear Systems Previous: SLES: Linear Equations Solvers

To solve a linear system with SLES, one must first create a solver context with the command

   ierr = SLESCreate(MPI_Comm comm,SLES *sles);  
Here comm is the MPI communicator, and sles is the newly formed solver context. Before actually solving a linear system with SLES, the user must call the following routine to set the matrices associated with the linear system:
   ierr = SLESSetOperators(SLES sles,Mat Amat,Mat Pmat,MatStructure flag); 
The argument Amat, representing the matrix that defines the linear system, is a symbolic place holder for any kind of matrix. In particular, SLES does support matrix-free methods. The routine MatCreateShell() in Section Matrix-Free Matrices provides further information regarding matrix-free methods. Typically the preconditioning matrix (i.e., the matrix from which the preconditioner is to be constructed), Pmat, is the same as the matrix that defines the linear system, Amat; however, occasionally these matrices differ (for instance, when a preconditioning matrix obtained from a high order method with that from a low order method). The argument flag can be used to eliminate unnecessary work when repeatedly solving linear systems of the same size with the same preconditioning method; when solving just one linear system, this flag is ignored. The user can set flag as follows:
If in doubt about the structure of a matrix, one should use the flag DIFFERENT_NONZERO_PATTERN.

Much of the power of SLES can be accessed through the single routine

   ierr = SLESSetFromOptions(SLES sles); 
This routine accepts the options -h and -help as well as any of the KSP and PC options discussed below. To solve a linear system, one merely executes the command
   ierr = SLESSolve(SLES sles,Vec b,Vec x,int *its); 
where b and x respectively denote the right-hand-side and solution vectors. On return, the parameter its contains either the iteration number at which convergence was successfully reached, or the negative of the iteration at which divergence or breakdown was detected. Section Convergence Tests gives more details regarding convergence testing. Note that multiple linear solves can be performed by the same SLES context. Once the SLES context is no longer needed, it should be destroyed with the command
   ierr = SLESDestroy(SLES sles); 
The above procedure is sufficient for general use of the SLES package. One additional step is required for users who wish to customize certain preconditioners (e.g., see Section Block Jacobi and ) or to log certain performance data using the PETSc profiling facilities (as discussed in Chapter Profiling ). In this case, the user can optionally explicitly call
   ierr = SLESSetUp(SLES sles,Vec b,Vec x); 
before calling SLESSolve() to perform any setup required for the linear solvers. The explicit call of this routine enables the separate monitoring of any computations performed during the set up phase, such as incomplete factorization for the ILU preconditioner.

The default solver within SLES is restarted GMRES, preconditioned for the uniprocessor case with ILU(0), and for the multiprocessor case with the block Jacobi method (with one block per processor, each of which is solved with ILU(0)). A variety of other solvers and options are also available. To allow application programmers to set any of the preconditioner or Krylov subspace options directly within the code, we provide routines that extract the PC and KSP contexts,

   ierr = SLESGetPC(SLES sles,PC *pc); 
   ierr = SLESGetKSP(SLES sles,KSP *ksp); 
The application programmer can then directly call any of the PC or KSP routines to modify the corresponding default options.

To solve a linear system with a direct solver (currently supported only for sequential matrices) one may use the options -pc_type lu -ksp_type preonly (see below).

By default, if a direct solver is used, the factorization is not done in-place. This approach is to prevent the user from the unexpected surprise of having a corrupted matrix after a linear solve. The routine PCLUSetUseInPlace(), discussed below, causes factorization to be done in-place.


Up: Contents Next: Solving Successive Linear Systems Previous: SLES: Linear Equations Solvers