FGMRES Interface Description

Routines Options

All of the RCI FGMRES routines have parameters for passing various options to the routines. The values for these parameters should be specified very carefully (see FGMRES Common Parameters), and they can be changed during computations according to the user's needs.

Note

Provide correct and consistent parameters to the subroutines to avoid fails or wrong results.

User Data Arrays

Many of the RCI FGMRES routines take arrays of user data as input. For example, user arrays are passed to the routine dfgmres to compute the solution of a system of linear algebraic equations. To minimize storage requirements and improve overall run-time efficiency, the Intel MKL RCI FGMRES routines do not make copies of the user input arrays.

FGMRES Common Parameters

Note

The default and initial values listed below are assigned to the parameters by calling the dfgmres_init routine.

n

- INTEGER, this parameter sets the size of the problem in the dfgmres_init routine. All the other routines uses ipar(1) parameter instead.

x

- DOUBLE PRECISION array, this parameter contains the current approximation to the solution vector. Before the first call to the dfgmres routine, it contains the initial approximation to the solution vector.

b

- DOUBLE PRECISION array, this parameter contains the right-hand side vector. Depending on user requests, it may later contain the approximate solution.

RCI_request

- INTEGER, this parameter informs about the result of work of the RCI FGMRES routines. The negative values of the parameter indicate that the routine is completed with errors or warnings. The 0 value indicates the successful completion of the task. The positive values mean that the user must perform certain actions, specifically:

RCI_request= 1

- multiply the matrix by tmp(ipar(22)), put the result in tmp(ipar(23)), and return the control to the dfgmres routine;

RCI_request= 2

- perform the stopping tests. If they fail, return the control to the dfgres routine. Otherwise, the solution can be updated by a subsequent call to dfgmres_get routine;

RCI_request= 3

- apply the preconditioner to tmp(ipar(22)), put the result in tmp(ipar(23)), and return the control to the dfgmres routine.

RCI_request= 4

- check if the norm of the current orthogonal vector is not zero within the rounding/computational errors. Return the control to the dfgmres routine if it is not zero, otherwise complete the solution process by calling dfgmres_get routine.

ipar(128)

- INTEGER array, this parameter specifies the integer set of data for the RCI FGMRES computations:

ipar(1)

- specifies the size of the problem. The dfgmres_init routine assigns ipar(1)=n. All the other routines uses this parameter instead of n. There is no default value for this parameter.

ipar(2)

- specifies the type of output for error and warning messages that are generated by the RCI FGMRES routines. The default value 6 means that all messages are displayed on the screen. Otherwise the error and warning messages are written to the newly created file MKL_RCI_FGMRES_Log.txt. Note that if ipar(6) and ipar(7) parameters are set to 0, error and warning messages are not generated at all.

ipar(3)

- contains the current stage of the RCI FGMRES computations, the initial value is 1.

Warning

Avoid altering this variable during computations.

ipar(4)

- contains the current iteration number. The initial value is 0.

ipar(5)

- specifies the maximum number of iterations. The default value is min {150,n}.

ipar(6)

- if the value is not equal to 0, the routines output error messages in accordance with the parameter ipar(2). Otherwise, the routines do not output error messages at all, but return a negative value of the parameter RCI_request. The default value is 1.

ipar(7)

- if the value is not equal to 0, the routines output warning messages in accordance with the parameter ipar(2). Otherwise, the routines do not output warning messages at all, but they return a negative value of the parameter RCI_request. The default value is 1.

ipar(8)

- if the value is not equal to 0, the dfmres routine performs the stopping test for the maximum number of iterations, namely, ipar(4)≤ipar(5). Otherwise, the method is stopped and the corresponding value is assigned to the RCI_request. If the value is 0, the dfgmres routine does not perform this stopping test. The default value is 1.

ipar(9)

- if the value is not equal to 0, the dfgmres routine performs the residual stopping test, namely, dpar(5)≤dpar(4) = dpar(1)·dpar(3)+dpar(2). If the criterion is met, the method is stopped and corresponding value is assigned to the output parameter RCI_request. If the value is 0, the dfgmres routine does not perform this stopping test. The default value is 0.

ipar(10)

- if the value is not equal to 0, the dfgmres routine requests for the user defined stopping test by setting RCI_request=2. If the value is 0, the dfgmres routine does not perform the user defined stopping test. The default value is 1.

Note

At least one of the parameters ipar(8)-ipar(10) must be set to 1.

ipar(11)

- if the value is equal to 0, the dfgmres routine runs the non-preconditioned version of the FGMRES method. Otherwise, the routine runs the preconditioned version of the FGMRES method, and requests the user to perform the preconditioning step by setting the output parameter RCI_request=3. The default value is 0.

ipar(12)

- if the value is not equal to 0, the dfgmres routine performs the automatic test for zero norm of the currently generated vector, namely, dpar(7)≤dpar(8), where dpar(8) contains the tolerance value. Otherwise, the routine requests the user to perform this check by setting the output parameter RCI_request=4. The default value is 0.

ipar(13)

- if the value is equal to 0, the dfgmres_get routine updates the solution to the vector x according to the computations done by the dfgmres routine. If the value is positive, the routine writes the solution to the right hand side vector b. If the value is negative, the routine returns only the number of the current iteration, and does not update the solution. The default value is 0

Note

Advanced users may use the dfgmres_get routine at any place in the code. In this case special attention should be paid to the parameter ipar(13). The RCI FGMRES iterations can be continued after the call to dfgmres_get routine only if the parameter ipar(13) is not equal to zero. If ipar(13) is positive, then the updated solution overwrites the right hand side in the vector b. If the user wants to run the restarted version of FGMRES with the same right hand side, then it must be saved in a different memory location before the first call to the dfgmres_get routine with positive ipar(13).

ipar(14)

- contains the internal iteration counter that counts the number of iterations before the restart takes place. The initial value is 0.

Warning

Avoid altering this variable during computations.

ipar(15)

- specifies the length of the non-restarted FGMRES iterations. To run the restarted version of the FGMRES method, the user must assign the number of iterations to ipar(15) before the restart. The default value is min {150, n}, that is, by default the non-restarted version of FGMRES method is used.

ipar(16)

- service variable, specifies the location of the rotated Hessenberg matrix from which the matrix stored in the packed format (see Matrix Arguments in the Appendix B for details) is started in the tmp array.

ipar(17)

- service variable, specifies the location of the rotation cosines from which the vector of cosines is started in the tmp array.

ipar(18)

- service variable, specifies the location of the rotation sines from which the vector of sines is started in the tmp array.

ipar(19)

- service variable, specifies the location of the rotated residual vector from which the vector is started in the tmp array.

ipar(20)

- service variable, specifies the location of the least squares solution vector from which the vector is started in the tmp array.

ipar(21)

- service variable, specifies the location of the set of preconditioned vectors from which the set is started in the tmp array. The memory locations in the tmp array starting from ipar(21) are used only for the preconditioned FGMRES method.

ipar(22)

- specifies the memory location from which the first vector (source) used in operations requested via RCI_request is started in the tmp array.

ipar(23)

- specifies the memory location from which the second vector (source) used in operations requested via RCI_request is started in the tmp array.

ipar(24:128)

are reserved and not used in the current RCI FGMRES routines.

Note

Advanced users can define the array in the code as INTEGER ipar(23). However, to guarantee compatibility with the future releases of Intel MKL, declaring the array ipar with length 128 is highly recommended.

dpar(128)

- DOUBLE PRECISION array, this parameter specifies the double precision set of data for the RCI CG computations, specifically:

dpar(1)

- specifies the relative tolerance. The default value is 1.0D-6.

dpar(2)

- specifies the absolute tolerance. The default value is 0.0D-0.

dpar(3)

- specifies the Euclidean norm of the initial residual (if it is computed in the dfgmres routine). The initial value is 0.0.

dpar(4)

- service variable equal to dpar(1)*dpar(3)+dpar(2) (if it is computed in the dfgmres routine). The initial value is 0.0.

dpar(5)

- specifies the Euclidean norm of the current residual. The initial value is 0.0.

dpar(6)

- specifies the Euclidean norm of residual from the previous iteration step (if available). The initial value is 0.0.

dpar(7)

- contains the norm of the generated vector. The initial value is 0.0.

Note

For reference only: in terms of [Saad03] this parameter is the coefficient h_k+1,k of the Hessenberg matrix.

dpar(8)

- contains the tolerance for the zero norm of the currently generated vector. The default value is 1.0D-12.

dpar(9:128)

are reserved and not used in the current RCI FGMRES routines.

Note

Advanced users can define this array in the code as follows: DOUBLE PRECISION dpar(8). However, to guarantee compatibility with the future releases of Intel MKL, declaring the array dpar with length 128 is highly recommended.

tmp

-DOUBLE PRECISION array of size ((2*ipar(15)+1)*n + ipar(15)*(ipar(15)+9)/2 + 1)), this parameter is used to supply the double precision temporary space for the RCI FGMRES computations, specifically:

tmp(1:ipar(16)-1)

- contains the sequence of generated by the FGMRES method vectors. The initial value is 0.0 for the first part of this memory of length n;

tmp(ipar(16):ipar(17)-1)

contains the rotated Hessenberg matrix generated by the FGMRES method; the matrix is stored in the packed format. There is no initial value for this part of tmp array.

tmp(ipar(17):ipar(18)-1)

- contains the rotation cosines vector generated by the FGMRES method. There is no initial value for this part of tmp array.

tmp(ipar(18):ipar(19)-1)

contains the rotation sines vector generated by the FGMRES method. There is no initial value for this part of tmp array.

tmp(ipar(19):ipar(20)-1)

contains the rotated residual vector generated by the FGMRES method. There is no initial value for this part of tmp array.

tmp(ipar(20):ipar(21)-1)

contains the solution vector to the least squares problem generated by the FGMRES method. There is no initial value for this part of tmp array.

tmp(ipar(21):)

contains the set of preconditioned vectors generated for the FGMRES method by the user. This part of tmp array is not used if non-preconditioned version of FGMRES method is called. There is no initial value for this part of tmp array.

Note

Advanced users can define this array in the code as DOUBLE PRECISION tmp((2*ipar(15)+1)*n + ipar(15)*(ipar(15)+9)/2 + 1)) if they run only non-preconditioned FGMRES iterations.