Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

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
dcg
to compute the solution of a system of linear algebraic equations. The
Intel® oneAPI Math Kernel Library
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

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 the
dcg_init
/
dcgmrhs_init
routine. All the other routines use the
ipar
[0]
parameter instead. Note that the coefficient matrix
A
is a square matrix of size
n
*
n
.
x
double
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
MKL_INT
, this parameter sets the number of right-hand sides for MRHS routines.
b
double
array containing a single right-hand side vector, or matrix of size
n
*
nrhs
containing right-hand side vectors.
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 by
tmp
[0:
n
- 1)
, put the result in
tmp
[
n
:2*
n
- 1)
, 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
[2*
n
:3*
n
- 1]
, put the result in
tmp
[3*
n
:4*
n
- 1]
, and return the control to the
dcg
routine;
for MRHS: apply the preconditioner to
tmp
[2+
ipar
[2]*
n
:(3 +
ipar
[2])*
n
- 1]
, put the result in
tmp
[3*
n
:4*
n
- 1]
, 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
MKL_INT
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
[0]
specifies the size of the problem. The
dcg_init
/
dcgmrhs_init
routine assigns
ipar
[0]
=
n
. All the other routines use this parameter instead of
n
. 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 files
dcg_errors.txt
and
dcg_check_warnings.txt
, respectively. Note that if
ipar
[5]
and
ipar
[6]
parameters are set to 0, error and warning messages are not generated at all.
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 is
min(150,
n
)
.
ipar
[5]
if the value is not equal to 0, the routines output error messages in accordance with the parameter
ipar
[1]
. 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
[6]
if the value is not equal to 0, the routines output warning messages in accordance with the parameter
ipar
[1]
. 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
[7]
if the value is not equal to 0, the
dcg
/
dcgmrhs
routine performs the stopping test for the maximum number of iterations:
ipar
[3]
ipar
[4]
. 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
[8]
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
[9]
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.
At least one of the parameters
ipar
[7]
-
ipar
[9]
must be set to 1.
ipar
[10]
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
[11:127]
are reserved and not used in the current RCI CG SRHS and MRHS routines.
For future compatibility, you must declare the array
ipar
with 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 array
ipar
with length 128+2*
nrhs
for multiple right-hand sides.
dpar
double
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
[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 the
dcg
/
dcgmrhs
routine). The initial value is 0.0.
dpar
[3]
service variable equal to
dpar
[0]
*
dpar
[2]
+
dpar
[1]
(if it is computed in the
dcg
/
dcgmrhs
routine). 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 the
alpha
parameter 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 array
dpar
with 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 array
dpar
with length 128+2*
nrhs
for multiple right-hand sides.
tmp
double
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
[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 as
double
tmp
[3*
n
]
if you run only non-preconditioned CG iterations.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804