# CG Interface Description

All types in this documentation refer to the common Fortran types, INTEGER, and DOUBLE PRECISION.

C and C++ programmers should refer to the section Calling Sparse Solver and Preconditioner Routines From C/C++ for information on mapping Fortran types to C/C++ types.

Each routine for the RCI CG solver is implemented in two versions: for a system of equations with asingle 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` .

### Note

The routines for a system with MRHS can be used with the names without the suffix mrhs. To do this, the user must switch on the compiler preprocessor and include the files mkl_solver.h for C/C++, or mkl_solver.f77 for FORTRAN.

## Routines Options

All of the RCI CG routines have parameters for passing various options to the routines. The values for these parameters should be specified very carefully (see CG 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 CG routines take arrays of user data as input. For example, user arrays are passed to the routine dcg to compute the solution of a system of linear algebraic equations. The Intel MKL RCI CG routines do not make copies of the user input arrays to minimize storage requirements and improve overall run-time efficiency.

## CG Common Parameters

### Note

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

n

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

x

  - DOUBLE PRECISION array of size n for SRHS, or matrix of size n-by-nrhs for MRHS. This parameter contains the current approximation to the solution. Before the first call to the dcg/dcgmrhs routine, it contains the initial approximation to the solution.

nrhs

  - INTEGER, this parameter sets the number of right-hand sides for MRHS routines.

b

  - DOUBLE PRECISION array containing a single right-hand side vector, or matrix `(nrhs, n)` containing right-hand side vectors.

RCI_request

  - INTEGER, this parameter informs about the result of work of the RCI CG 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

    - to multiply the matrix by `tmp (1:n,1)`, put the result in tmp`(1:n,2)`, and return the control to the dcg/dcgmrhs routine;

  RCI_request= 2

    - to perform the stopping tests. If they fail, return the control to the dcg/dcgmrhs routine. Otherwise, the solution is found and stored in the x array;

  RCI_request= 3

    - for SRHS: to apply the preconditioner to tmp`(1:n,3)`, put the result in tmp`(1:n,4)`, and return the control to the dcg routine;

    - for MRHS: to apply the preconditioner to tmp`(:,3+ipar(3))`, put the result in tmp`(:,3)`, and return the control to the dcgmrhs routine.

  Note that the dcg_get/dcgmrhs_get routine does not change the parameter RCI_request. This enables to use this routine inside the Reverse Communication computations.

ipar

  - INTEGER array, of size 128 for SRHS, and of size `(128+2*nrhs)` for MRHS; this parameter specifies the integer set of data for the RCI CG computations:

  ipar(1)

    - specifies the size of the problem. The dcg_init/dcgmrhs_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 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 files dcg_errors.txt and dcg_check_warnings.txt respectively. Note that if ipar(6) and ipar(7) parameters are set to 0, error and warning messages are not generated at all.

  ipar(3)

    - for SRHS: contains the current stage of the RCI CG computations, the initial value is 1;

    - for MRHS: contains the right-hand side for which the calculations are currently performed.

    ### 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 dcg/dcgmrhs 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 routine does not perform this stopping test. The default value is 1.

  ipar(9)

    - if the value is not equal to 0, the dcg/dcgmrhs routine performs the residual stopping test, namely, `dpar(5)≤dpar(4)=dpar(1)*dpar(3)+dpar(2)`. Otherwise, the method is stopped and corresponding value is assigned to the RCI_request. If the value is 0, the routine does not perform this stopping test. The default value is 0.

  ipar(10)

    - if the value is not equal to 0, the dcg/dcgmrhs routine requests a user-defined stopping test by setting the output parameter RCI_request=2. If the value is 0, the 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 dcg/dcgmrhs routine runs the non-preconditioned version of the corresponding Conjugate Gradient method. Otherwise, the routine runs the preconditioned version of the Conjugate Gradient method, and requests the user to perform the preconditioning step by setting the output parameter RCI_request=3. The default value is 0.

  ipar(11:128), ipar(11:128+2*nrhs)

    are reserved and not used in the current RCI CG SRHS and MRHS routines respectively.

    ### Note

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

dpar

  - DOUBLE PRECISION array, for SRHS of size 128, for MRHS of size `(128+2*nrhs)`; this parameter is used to specify 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 square norm of the initial residual (if it is computed in the dcg/dcgmrhs routine). The initial value is 0.

  dpar(4)

    - service variable equal to `dpar(1)*dpar(3)+dpar(2)` (if it is computed in the dcg/dcgmrhs routine). The initial value is 0.

  dpar(5)

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

  dpar(6)

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

  dpar(7)

    - contains the alpha parameter of the CG method. The initial value is 0.0.

  dpar(8)

    - contains the beta parameter of the CG method, it is equal to `dpar(5)/dpar(6)` The initial value is 0.0.

  dpar(9:128), dpar(9:128+2*nrhs)

    are reserved and not used in the current RCI CG SRHS and MRHS routines respectively.

    ### Note

    Advanced users can define this array in the code using RCI CG SRHS as 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 (n,4)for SRHS, and (n,3+nrhs)for MRHS. This parameter is used to supply the double precision temporary space for the RCI CG computations, specifically:

  tmp(:,1)

    - specifies the current search direction. The initial value is 0.0.

  tmp(:,2)

    - contains the matrix multiplied by the current search direction. The initial value is 0.0.

  tmp(:,3)

    - contains the current residual. The initial value is 0.0.

  tmp(:,4)

    - contains the inverse of the preconditioner applied to the current residual. There is no initial value for this parameter.

    ### Note

    Advanced users can define this array in the code using RCI CG SRHS as DOUBLE PRECISION tmp(n,3) if they run only non-preconditioned CG iterations.

Parent topic: Iterative Sparse Solvers based on Reverse Communication Interface (RCI ISS)