CG Interface Description
Each routine for the RCI CG solver is implemented in two versions: for a system of equations with a single right-hand side (SRHS), and for a system of equations with multiple right-hand sides (MRHS). The names of routines for a system with MRHS contain the suffix
.
mrhs
Routine Options
All of the RCI CG routines have common parameters for passing various options to the routines (see
CG Common Parameters). The values for these parameters can be changed during computations.
User Data Arrays
Many of the RCI CG routines take arrays of user data as input. For example, user arrays are passed to the routine
RCI CG routines do not make copies of the user input arrays to minimize storage requirements and improve overall run-time efficiency.
dcg
to compute the solution of a system of linear algebraic equations. The Intel® oneAPI Math Kernel Library
CG Common Parameters
The default and initial values listed below are assigned to the parameters by calling the
dcg_init
/dcgmrhs_init
routine.
- n
- MKL_INT, this parameter sets the size of the problem in thedcg_init/dcgmrhs_initroutine. All the other routines use theparameter instead. Note that the coefficient matrixipar[0]Ais a square matrix of sizen*n.
- x
- doublearray of sizenfor SRHS, or matrix of size (n*nrhs) for MRHS. This parameter contains the current approximation to the solution. Before the first call to thedcg/dcgmrhsroutine, it contains the initial approximation to the solution.
- nrhs
- MKL_INT, this parameter sets the number of right-hand sides for MRHS routines.
- b
- doublearray containing a single right-hand side vector, or matrix of sizecontaining right-hand side vectors.n*nrhs
- RCI_request
- MKL_INT, this parameter gives information about the result of work of the RCI CG 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 bytmp[0:, put the result inn- 1)tmp[, and return the control to then:2*n- 1)dcg/dcgmrhsroutine;
- RCI_request= 2
- to perform the stopping tests. If they fail, return the control to thedcg/dcgmrhsroutine. If the stopping tests succeed, it indicates that the solution is found and stored in thexarray;
- RCI_request= 3
- for SRHS: apply the preconditioner totmp[2*, put the result inn:3*n- 1]tmp[3*, and return the control to then:4*n- 1]dcgroutine;for MRHS: apply the preconditioner totmp[2+, put the result inipar[2]*n:(3 +ipar[2])*n- 1]tmp[3*, and return the control to then:4*n- 1]dcgmrhsroutine.
Note that thedcg_get/dcgmrhs_getroutine does not change the parameterRCI_request. This enables use of this routine inside thereverse communicationcomputations. - ipar
- MKL_INTarray, of size128for SRHS, and of size(128+2*for MRHS. This parameter specifies the integer set of data for the RCI CG computations:nrhs)
- ipar[0]
- specifies the size of the problem. Thedcg_init/dcgmrhs_initroutine assigns=ipar[0]n. All the other routines use this parameter instead ofn. There is no default value for this parameter.
- ipar[1]
- specifies the type of output for error and warning messages generated by the RCI CG 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 filesdcg_errors.txtanddcg_check_warnings.txt, respectively. Note that ifandipar[5]parameters are set to 0, error and warning messages are not generated at all.ipar[6]
- ipar[2]
- for SRHS: contains the current stage of the RCI CG computations. The initial value is 1;for MRHS: contains the number of the right-hand side for which the calculations are currently performed.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 equal to 0, the routines output error messages in accordance with the parameter. Otherwise, the routines do not output error messages at all, but return a negative value of the parameteripar[1]RCI_request. The default value is 1.
- ipar[6]
- if the value is not equal to 0, the routines output warning messages in accordance with the parameter. Otherwise, the routines do not output warning messages at all, but they return a negative value of the parameteripar[1]RCI_request. The default value is 1.
- ipar[7]
- if the value is not equal to 0, thedcg/dcgmrhsroutine performs the stopping test for the maximum number of iterations:ipar[3]≤. Otherwise, the method is stopped and the corresponding value is assigned to theipar[4]RCI_request. If the value is 0, the routine does not perform this stopping test. The default value is 1.
- ipar[8]
- if the value is not equal to 0, thedcg/dcgmrhsroutine performs the residual stopping test:. Otherwise, the method is stopped and corresponding value is assigned to thedpar(5)≤dpar(4)=dpar(1)*dpar(3)+dpar(2)RCI_request. If the value is 0, the routine does not perform this stopping test. The default value is 0.
- ipar[9]
- if the value is not equal to 0, thedcg/dcgmrhsroutine requests a user-defined stopping test by setting the output parameterRCI_request=2. If the value is 0, the routine does not perform the user defined stopping test. The default value is 1.At least one of the parameters-ipar[7]must be set to 1.ipar[9]
- ipar[10]
- if the value is equal to 0, thedcg/dcgmrhsroutine runs the non-preconditioned version of the corresponding CG method. Otherwise, the routine runs the preconditioned version of the CG method, and by setting the output parameterRCI_request=3, indicates that you must perform the preconditioning step. The default value is 0.
- ipar[11:127]
- are reserved and not used in the current RCI CG SRHS and MRHS routines.For future compatibility, you must declare the arrayiparwith length 128 for a single right-hand side.
- ipar[11:127 + 2*nrhs]
- are reserved for internal use in the current RCI CG SRHS and MRHS routines.For future compatibility, you must declare the arrayiparwith length 128+2*nrhsfor multiple right-hand sides.
- dpar
- doublearray, for SRHS of size128, for MRHS of size(128+2*; this parameter is used to specify the double precision set of data for the RCI CG computations, specifically:nrhs)
- dpar[0]
- specifies the relative tolerance. The default value is 1.0X10-6.
- dpar[1]
- specifies the absolute tolerance. The default value is 0.0.
- dpar[2]
- specifies the square norm of the initial residual (if it is computed in thedcg/dcgmrhsroutine). The initial value is 0.0.
- dpar[3]
- service variable equal to(if it is computed in the*dpar[0]+dpar[2]dpar[1]dcg/dcgmrhsroutine). The initial value is 0.0.
- dpar[4]
- specifies the square norm of the current residual. The initial value is 0.0.
- dpar[5]
- specifies the square norm of residual from the previous iteration step (if available). The initial value is 0.0.
- dpar[6]
- contains thealphaparameter of the CG method. The initial value is 0.0.
- dpar[7]
- dpar[8:127]
- are reserved and not used in the current RCI CG SRHS and MRHS routines.For future compatibility, you must declare the arraydparwith length 128 for a single right-hand side.
- dpar(9:128+2*nrhs)[8:127 + 2*nrhs]
- are reserved for internal use in the current RCI CG SRHS and MRHS routines.For future compatibility, you must declare the arraydparwith length 128+2*nrhsfor multiple right-hand sides.
- tmp
- doublearray of size(for SRHS, andn*4)(for MRHS. This parameter is used to supply the double precision temporary space for the RCI CG computations, specifically:n*(3+nrhs))
- tmp[0:n- 1]
- specifies the current search direction. The initial value is 0.0.
- tmp[n:2*n- 1]
- contains the matrix multiplied by the current search direction. The initial value is 0.0.
- tmp[2*n:3*n- 1]
- contains the current residual. The initial value is 0.0.
- tmp[3*n:4*n- 1]
- contains the inverse of the preconditioner applied to the current residual for the SRHS version of CG. There is no initial value for this parameter.
- tmp[4*n:(4 +nrhs)*n- 1]
- contains the inverse of the preconditioner applied to the current residual for the MRHS version of CG. There is no initial value for this parameter.
You can define this array in the code using RCI CG SRHS asdoubletmp[3*if you run only non-preconditioned CG iterations.n]