FGMRES Interface Description
Routine Options
All of the RCI FGMRES routines have common parameters for passing various options to the routines (see
FGMRES Common Parameters). The values for these parameters can be changed during computations.
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
RCI FGMRES routines do not make copies of the user input arrays.
dfgmres
to compute the solution of a system of linear algebraic equations. To minimize storage requirements and improve overall run-time efficiency, the Intel® oneAPI Math Kernel Library
FGMRES Common Parameters
The default and initial values listed below are assigned to the parameters by calling the
dfgmres_init
routine.
- n
- MKL_INT, this parameter sets the size of the problem in thedfgmres_initroutine. All the other routines use theipar[0]parameter instead. Note that the coefficient matrixAis a square matrix of sizen*n.
- x
- doublearray, this parameter contains the current approximation to the solution vector. Before the first call to thedfgmresroutine, it contains the initial approximation to the solution vector.
- b
- doublearray, this parameter contains the right-hand side vector. Depending on user requests (see the parameteripar[12]), it might contain the approximate solution after execution.
- RCI_request
- MKL_INT, this parameter gives information about the result of work of the RCI FGMRES routines. Negative values of the parameter indicate that the routine completed with errors or warnings. The 0 value indicates successful completion of the task. Positive values mean that you must perform specific actions:
- RCI_request= 1
- multiply the matrix by, put the result intmp[ipar[21] - 1:ipar[21] +n- 2], and return the control to thetmp[ipar[22] - 1:ipar[22] +n- 2]dfgmresroutine;
- RCI_request= 2
- perform the stopping tests. If they fail, return the control to thedfgresroutine. Otherwise, the solution can be updated by a subsequent call todfgmres_getroutine;
- RCI_request= 3
- apply the preconditioner to, put the result intmp[ipar[21] - 1:ipar[21] +n- 2], and return the control to thetmp[ipar[22] - 1:ipar[22] +n- 2]dfgmresroutine.
- RCI_request= 4
- check if the norm of the current orthogonal vector is zero, within the rounding or computational errors. Return the control to thedfgmresroutine if it is not zero, otherwise complete the solution process by callingdfgmres_getroutine.
- ipar[128]
- MKL_INTarray, this parameter specifies the integer set of data for the RCI FGMRES computations:
- ipar[0]
- specifies the size of the problem. Thedfgmres_initroutine assignsipar[0]=n. All the other routines uses this parameter instead ofn. There is no default value for this parameter.
- ipar[1]
- specifies the type of output for error and warning messages that are generated by the RCI FGMRES routines. The default value6means that all messages are displayed on the screen. Otherwise the error and warning messages are written to the newly created fileMKL_RCI_FGMRES_Log.txt. Note that ifipar[5]andipar[6]parameters are set to 0, error and warning messages are not generated at all.
- ipar[2]
- contains the current stage of the RCI FGMRES computations. The initial value is 1.Avoid altering this variable during computations.
- ipar[3]
- contains the current iteration number. The initial value is 0.
- ipar[4]
- specifies the maximum number of iterations. The default value ismin(150,n).
- ipar[5]
- if the value is not 0, the routines output error messages in accordance with the parameteripar[1]. If it is 0, the routines do not output error messages at all, but return a negative value of the parameterRCI_request. The default value is 1.
- ipar[6]
- if the value is not 0, the routines output warning messages in accordance with the parameteripar[1]. Otherwise, the routines do not output warning messages at all, but they return a negative value of the parameterRCI_request. The default value is 1.
- ipar[7]
- if the value is not equal to 0, thedfgmresroutine performs the stopping test for the maximum number of iterations:ipar[3]≤ipar[4]. If the value is 0, thedfgmresroutine does not perform this stopping test. The default value is 1.
- ipar[8]
- if the value is not 0, thedfgmresroutine performs the residual stopping test:dpar[4]≤dpar[3].If the value is 0, thedfgmresroutine does not perform this stopping test. The default value is 0.
- ipar[9]
- if the value is not 0, thedfgmresroutine indicates that the user-defined stopping test should be performed by settingRCI_request=2. If the value is 0, thedfgmresroutine does not perform the user-defined stopping test. The default value is 1.At least one of the parametersipar[7]-ipar[9]must be set to 1.
- ipar[10]
- if the value is 0, thedfgmresroutine runs the non-preconditioned version of the FGMRES method. Otherwise, the routine runs the preconditioned version of the FGMRES method, and requests that you perform the preconditioning step by setting the output parameterRCI_request=3. The default value is 0.
- ipar[11]
- if the value is not equal to 0, thedfgmresroutine performs the automatic test for zero norm of the currently generated vector:dpar[6]≤dpar[7], wheredpar[7]contains the tolerance value. Otherwise, the routine indicates that you must perform this check by setting the output parameterRCI_request=4. The default value is 0.
- ipar[12]
- if the value is equal to 0, thedfgmres_getroutine updates the solution to the vectorxaccording to the computations done by thedfgmresroutine. If the value is positive, the routine writes the solution to the right-hand side vectorb. 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.It is possible to call thedfgmres_getroutine at any place in the code, but you must pay special attention to the parameteripar[12]. The RCI FGMRES iterations can be continued after the call todfgmres_getroutine only if the parameteripar[12]is not equal to zero. Ifipar[12]is positive, then the updated solution overwrites the right-hand side in the vectorb. If you want 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 thedfgmres_getroutine with positiveipar[12].
- ipar[13]
- contains the internal iteration counter that counts the number of iterations before the restart takes place. The initial value is 0.Do not alter this variable during computations.
- ipar[14]
- specifies the number of the non-restarted FGMRES iterations. To run the restarted version of the FGMRES method, assign the number of iterations toipar[14]before the restart. The default value ismin(150,n), which means that by default the non-restarted version of FGMRES method is used.
- ipar[15]
- service variable specifying 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 thetmparray.
- ipar[16]
- service variable specifying the location of the rotation cosines from which the vector of cosines is started in thetmparray.
- ipar[17]
- service variable specifying the location of the rotation sines from which the vector of sines is started in thetmparray.
- ipar[18]
- service variable specifying the location of the rotated residual vector from which the vector is started in thetmparray.
- ipar[19]
- service variable, specifies the location of the least squares solution vector from which the vector is started in thetmparray.
- ipar[20]
- service variable specifying the location of the set of preconditioned vectors from which the set is started in thetmparray. The memory locations in thetmparray starting fromipar[20]are used only for the preconditioned FGMRES method.
- ipar[21]
- specifies the memory location from which the first vector (source) used in operations requested viaRCI_requestis started in thetmparray.
- ipar[22]
- specifies the memory location from which the second vector (output) used in operations requested viaRCI_requestis started in thetmparray.
- ipar[23:127]
- are reserved and not used in the current RCI FGMRES routines.You must declare the arrayiparwith length 128. While defining the array in the code asworks, there is no guarantee of future compatibility withipar[23].Intel® oneAPI Math Kernel Library
- dpar(128)
- doublearray, this parameter specifies the double precision set of data for the RCI CG computations, specifically:
- dpar[0]
- specifies the relative tolerance. The default value is 1.0e-6.
- dpar[1]
- specifies the absolute tolerance. The default value is 0.0e-0.
- dpar[2]
- specifies the Euclidean norm of the initial residual (if it is computed in thedfgmresroutine). The initial value is 0.0.
- dpar[3]
- service variable equal todpar[0]*dpar[2]+dpar[1](if it is computed in thedfgmresroutine). The initial value is 0.0.
- dpar[4]
- specifies the Euclidean norm of the current residual. The initial value is 0.0.
- dpar[5]
- specifies the Euclidean norm of residual from the previous iteration step (if available). The initial value is 0.0.
- dpar[6]
- contains the norm of the generated vector. The initial value is 0.0.
- dpar[7]
- contains the tolerance for the zero norm of the currently generated vector. The default value is 1.0e-12.
- dpar[8:127]
- are reserved and not used in the current RCI FGMRES routines.You must declare the arraydparwith length 128. While defining the array in the code asworks, there is no guarantee of future compatibility withdoubledpar[8].Intel® oneAPI Math Kernel Library
- tmp
- doublearray of size((2*used to supply the double precision temporary space for the RCI FGMRES computations, specifically:ipar[14] + 1)*n+ipar[14]*(ipar[14] + 9)/2 + 1))
- tmp[0:ipar[15] - 2]
- contains the sequence of vectors generated by the FGMRES method. The initial value is 0.0.
- tmp[ipar[15] - 1:ipar[16] - 2]
- 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 oftmparray.
- tmp[ipar[16] - 1:ipar[17] - 2]
- contains the rotation cosines vector generated by the FGMRES method. There is no initial value for this part oftmparray.
- tmp[ipar[17] - 1:ipar[18] - 2]
- contains the rotation sines vector generated by the FGMRES method. There is no initial value for this part oftmparray.
- tmp[ipar[18] - 1:ipar[19] - 2]
- contains the rotated residual vector generated by the FGMRES method. There is no initial value for this part oftmparray.
- tmp[ipar[19] - 1:ipar[20] - 2]
- contains the solution vector to the least squares problem generated by the FGMRES method. There is no initial value for this part oftmparray.
- tmp[ipar[20] - 1:*]
- contains the set of preconditioned vectors generated for the FGMRES method by the user. This part oftmparray is not used if the non-preconditioned version of FGMRES method is called. There is no initial value for this part oftmparray.You can define this array in the code asif you run only non-preconditioned FGMRES iterations.doubletmp[(2*ipar[14] + 1)*n+ipar[14]*(ipar[14] + 9)/2 + 1)]