Routine Options

User Data Arrays

CG Common Parameters

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.