Description

Given a general square sparse matrix A and a right-hand side vector b, S3L_gen_iter_solve solves the linear system of equations Ax = b, using an iterative algorithm, with or without preconditioning.

The first three arguments to S3L_gen_iter_solve are S3L internal array handles that describe the global general sparse matrix A, the rank 1 global array b, and the rank 1 global array x.

The sparse matrix A is produced by a prior call to one of the following sparse routines:

• S3L_declare_sparse

• S3L_read_sparse

• S3L_rand_sparse

The global rank 1 arrays, b and x, have the same data type and precision as the sparse matrix A and both have a length equal to the order of A.

Two local rank 1 arrays, iparm and rparm, provide user control over various aspects of S3L_gen_iter_solve behavior, including:

• Choice of algorithm to be used.

• Type of preconditioner to use on A.

• Flags to select the initial guess to the solution.

• Maximum number of iterations to be taken by the solver.

• If restarted GMRES algorithm is chosen, selection of the size of the Krylov subspace.

• Tolerance values to be used by the stopping criterion.

• If the Richardson algorithm is chosen, selection of the scaling factor to be used.

iparm is an integer array and rparm is a real array. The options supported by these arguments are described in the subsections titled: "Algorithm," "Preconditioning," "Initial Guess," "Maximum Iterations," "Krylov Subspace," "Stopping Criterion Tolerance," and "Richardson Scaling Factor." The "Iteration Termination" subsection identifies the conditions under which S3L_gen_iter_solve will terminate anoperation.

iparm and rparm must be preallocated and initialized before S3L_gen_iter_solve is called. To enable the default condition for any parameter, set it to 0. Otherwise, initialize them with the appropriate parameter values, as described in the following subsections.

Algorithm

S3L_gen_iter_solve attempts to solve Ax = b using one of the following iterative solution algorithms. The choice of algorithm is determined by the value supplied for the parameter iparm[S3L_iter_solver]. The various options available for this parameter are listed and described in Table 8-12

Preconditioning

S3L_gen_iter_solve implements left preconditioning. That is, preconditioning is applied to the linear system Ax = b by

Example 8-81

Q-1 A = Q-1 b 

where Q is the preconditioner and Q^-1 denotes the inverse of Q. The supported preconditioners are listed in Table 8-13.

Convergence/Divergence Criteria

The iparm[S3L_iter_conv] parameter selects the criterion to be used for stopping computation. Currently, the single valid option for this parameter is S3L_r0, which selects the default criterion for both convergence and divergence. The convergence criterion is satisfied when:

err = ||rj||_2 / ||r0||_2 < epsilon

and the divergence criterion is met when

err = ||rj||_2 / ||r0||_2 > 10000.0

where:

• rj and r0 are the residuals obtained at iterations j and 0.

• ||.||_2 is the 2-norm.

• epsilon is the desired convergence tolerance stored in rparm[S3L_iter_tol].

• 10000.0 is the divergence tolerance, which is set internally in the solver.

Initial Guess

The parameter iparm[S3L_iter_init] determines the contents of the initial guess to the solution of the linear system as follows:

• 0 - Applies zero as the initial guess. This is the default.

• 1 - Applies the value contained in array x as the initial guess. For this case, the user must initialize x before calling S3L_gen_iter_solve.

Maximum Iterations

On input, the iparm[S3L_iter_maxiter] parameter specifies the maximum number of iterations to be taken by the solver. Set to 0 to select the default, which is 10000.

On output, iparm[S3L_iter_maxiter] contains the total number of iterations taken by the solver at the time of termination.

Krylov Subspace

If the restarted GMRES algorithm is selected, iparm[S3L_iter_kspace] specifies the size of the Krylov subspace to be used. The default is 30.

Stopping Criterion Tolerance

On input, rparm[S3L_iter_tol] specifies the tolerance values to be used by the stopping criterion. Its default is 10-8.

On output, rparm[S3L_iter_tol] contains the computed error, err, according to the convergence criteria. See the iparm[S3L_iter_conv] description for details.

Richardson Scaling Factor

If the Richardson method is selected, rparm[S3L_rich_scale] specifies the scaling factor to be used. The default value is 1.0.

Iteration Termination

S3L_gen_iter_solve terminates the iteration when one of the following conditions is met.

• The computation has satisfied the convergence criterion.

• The computation has diverged.

• An algorithmic breakdown has occurred.

• The number of iterations has exceeded the supplied value.