CG Interface Description

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 10/31/2024

Version

Public

Visible to Intel only — GUID: GUID-84B673F3-E221-4D25-A260-62D3398CA2F8

View Details

CG Interface Description

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

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 dcgto compute the solution of a system of linear algebraic equations. The Intel® oneAPI Math Kernel Library (oneMKL) 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 use the ipar(1) parameter instead. Note that the coefficient matrix A is a square matrix of size n*n.

x

DOUBLE PRECISION array of size n for SRHS, or matrix of size (n*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 of size n*nrhs containing right-hand side vectors.

RCI_request

INTEGER, 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 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. If the stopping tests succeed, it indicates that the solution is found and stored in the x array;

RCI_request= 3

for SRHS: 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: 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 use of 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 use 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 number of 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: 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: `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 CG method. Otherwise, the routine runs the preconditioned version of the CG method, and by setting the output parameter RCI_request=3, indicates that you must perform the preconditioning step. The default value is 0.
ipar`(12:128)`	are reserved and not used in the current RCI CG SRHS and MRHS routines. NOTE: For future compatibility, you must declare the array ipar with length 128 for a single right-hand side.
ipar(12:128+2*nrhs)	are reserved for internal use in the current RCI CG SRHS and MRHS routines. NOTE: For future compatibility, you must declare the array ipar with length 128+2*nrhs for multiple right-hand sides.

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.0X10^-6.
dpar`(2)`	specifies the absolute tolerance. The default value is 0.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.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.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)`	are reserved and not used in the current RCI CG SRHS and MRHS routines. NOTE: For future compatibility, you must declare the array dpar with length 128 for a single right-hand side.
dpar(9:128+2nrhs)`(9:128 + 2nrhs)`	are reserved for internal use in the current RCI CG SRHS and MRHS routines. NOTE: For future compatibility, you must declare the array dpar with length 128+2*nrhs for multiple right-hand sides.

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 for the SRHS version of CG. There is no initial value for this parameter.
tmp(:,4:3+nrhs)	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.

NOTE:

You can define this array in the code using RCI CG SRHS as DOUBLE PRECISIONtmp(n,3) if you run only non-preconditioned CG iterations.

Schemes of Using the RCI CG Routines

The following pseudocode shows the general schemes of using the RCI CG routines for the SRHS case. The MRHS is similar (see the example code for more details).

...

generate matrix A

generate preconditioner C (optional)

call dcg_init(n, x, b, RCI_request, ipar, dpar, tmp)

change parameters in ipar, dpar if necessary

call dcg_check(n, x, b, RCI_request, ipar, dpar, tmp)

1 call dcg(n, x, b, RCI_request, ipar, dpar, tmp)

if (RCI_request.eq.1) then

multiply the matrix A by tmp(1:n,1) and put the result in tmp(1:n,2)

It is possible to use MKL Sparse BLAS Level 2 subroutines for this operation

c proceed with CG iterations

goto 1

endif

if (RCI_request.eq.2)then

do the stopping test

if (test not passed) then

c proceed with CG iterations

go to 1

else

c stop CG iterations

goto 2

endif

if (RCI_request.eq.3) then (optional)

apply the preconditioner C inverse to tmp(1:n,3) and put the result in tmp(1:n,4)

c proceed with CG iterations

goto 1

end

2 calldcg_get(n, x, b, RCI_request, ipar, dpar, tmp, itercount)

current iteration number is in itercount

the computed approximation is in the array x

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

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

CG Interface Description

Routine Options

User Data Arrays

CG Common Parameters

Schemes of Using the RCI CG Routines