NAG Library ManualKeyword Search:

NAG Library Routine Document

f11gsf (complex_herm_basic_solver)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

1

Purpose

f11gsf is an iterative solver for a complex Hermitian system of simultaneous linear equations; f11gsf is the second in a suite of three routines, where the first routine, f11grf, must be called prior to f11gsf to set up the suite, and the third routine in the suite, f11gtf, can be used to return additional information about the computation.

These three routines are suitable for the solution of large sparse complex Hermitian systems of equations.

2

Specification

Fortran Interface

Subroutine f11gsf (

irevcm, u, v, wgt, work, lwork, ifail)

Integer, Intent (In)	::	lwork
Integer, Intent (Inout)	::	irevcm, ifail
Real (Kind=nag_wp), Intent (In)	::	wgt(*)
Complex (Kind=nag_wp), Intent (Inout)	::	u(), v(), work(lwork)

C Header Interface

#include nagmk26.h

void	f11gsf_ ( Integer irevcm, Complex u[], Complex v[], const double wgt[], Complex work[], const Integer lwork, Integer *ifail)

3

Description

f11gsf solves the complex Hermitian system of linear simultaneous equations

A x = b

using either the preconditioned conjugate gradient method (see Hestenes and Stiefel (1952), Golub and Van Loan (1996), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)) or a preconditioned Lanczos method based upon the algorithm SYMMLQ (see Paige and Saunders (1975) and Barrett et al. (1994)).

For a general description of the methods employed you are referred to Section 3 in f11grf.

f11gsf can solve the system after the first routine in the suite, f11grf, has been called to initialize the computation and specify the method of solution. The third routine in the suite, f11gtf, can be used to return additional information generated by the computation during monitoring steps and after f11gsf has completed its tasks.

f11gsf uses reverse communication, i.e., f11gsf returns repeatedly to the calling program with the argument irevcm (see Section 5) set to specified values which require the calling program to carry out a specific task: either to compute the matrix-vector product

v = A u

; to solve the preconditioning equation

M v = u

; to notify the completion of the computation; or, to allow the calling program to monitor the solution. Through the argument irevcm the calling program can cause immediate or tidy termination of the execution. On final exit, the last iterates of the solution and of the residual vectors of the original system of equations are returned.

Reverse communication has the following advantages.

1.	Maximum flexibility in the representation and storage of sparse matrices. All matrix operations are performed outside the solver routine, thereby avoiding the need for a complicated interface with enough flexibility to cope with all types of storage schemes and sparsity patterns. This applies also to preconditioners.
2.	Enhanced user interaction: you can closely monitor the progress of the solution and tidy or immediate termination can be requested. This is useful, for example, when alternative termination criteria are to be employed or in case of failure of the external routines used to perform matrix operations.

4

References

Barrett R, Berry M, Chan T F, Demmel J, Donato J, Dongarra J, Eijkhout V, Pozo R, Romine C and Van der Vorst H (1994) Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods SIAM, Philadelphia

Dias da Cunha R and Hopkins T (1994) PIM 1.1 — the parallel iterative method package for systems of linear equations user's guide — Fortran 77 version Technical Report Computing Laboratory, University of Kent at Canterbury, Kent, UK

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Hestenes M and Stiefel E (1952) Methods of conjugate gradients for solving linear systems J. Res. Nat. Bur. Stand. 49 409–436

Higham N J (1988) FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation ACM Trans. Math. Software 14 381–396

Paige C C and Saunders M A (1975) Solution of sparse indefinite systems of linear equations SIAM J. Numer. Anal. 12 617–629

5

Arguments

Note: this routine uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument irevcm. Between intermediate exits and re-entries, all arguments other than irevcm and v must remain unchanged.

1: $irevcm$ – IntegerInput/Output

On initial entry:

irevcm = 0

, otherwise an error condition will be raised.

On intermediate re-entry: irevcm must either be unchanged from its previous exit value, or can have one of the following values.

$irevcm = 5$: Tidy termination: the computation will terminate at the end of the current iteration. Further reverse communication exits may occur depending on when the termination request is issued. f11gsf will then return with the termination code $irevcm = 4$ . Note that before calling f11gsf with $irevcm = 5$ the calling program must have performed the tasks required by the value of irevcm returned by the previous call to f11gsf, otherwise subsequently returned values may be invalid.
$irevcm = 6$: Immediate termination: f11gsf will return immediately with termination code $irevcm = 4$ and with any useful information available. This includes the last iterate of the solution and, for conjugate gradient only, the last iterate of the residual vector. The residual vector is generally not available when the Lanczos method (SYMMLQ) is used. f11gsf will then return with the termination code $irevcm = 4$ .
Immediate termination may be useful, for example, when errors are detected during matrix-vector multiplication or during the solution of the preconditioning equation.

Changing irevcm to any other value between calls will result in an error.

On intermediate exit: has the following meanings.

$irevcm = 1$: The calling program must compute the matrix-vector product $v = A u$ , where $u$ and $v$ are stored in u and v, respectively.
$irevcm = 2$: The calling program must solve the preconditioning equation $M v = u$ , where $u$ and $v$ are stored in u and v, respectively.
$irevcm = 3$: Monitoring step: the solution and residual at the current iteration are returned in the arrays u and v, respectively. No action by the calling program is required. To return additional information f11gtf can be called at this step.

On final exit: if

irevcm = 4

, f11gsf has completed its tasks. The value of ifail determines whether the iteration has been successfully completed, errors have been detected or the calling program has requested termination.

Constraint: on initial entry,

irevcm = 0

; on re-entry, either irevcm must remain unchanged or be reset to

irevcm = 5

6

Note: any values you return to f11gsf as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by f11gsf. If your code inadvertently does return any NaNs or infinities, f11gsf is likely to produce unexpected results.

2: $u (*)$ – Complex (Kind=nag_wp) arrayInput/Output

Note: the dimension of the array u must be at least

n

On initial entry: an initial estimate,

x_{0}

, of the solution of the system of equations

A x = b

On intermediate re-entry: must remain unchanged.

On intermediate exit: the returned value of irevcm determines the contents of u in the following way.

irevcm = 1

2

, u holds the vector

u

on which the operation specified by irevcm is to be carried out.

irevcm = 3

, u holds the current iterate of the solution vector.

On final exit: if

ifail = 3

- i

, the array u is unchanged from the initial entry to f11gsf. If

ifail = 1

, the array u is unchanged from the last entry to f11gsf. Otherwise, u holds the last iterate of the solution of the system of equations, for all returned values of ifail.

3: $v (*)$ – Complex (Kind=nag_wp) arrayInput/Output

Note: the dimension of the array v must be at least

n

On initial entry: the right-hand side

b

of the system of equations

A x = b

On intermediate re-entry: the returned value of irevcm determines the contents of v in the following way.

irevcm = 1

2

, v must store the vector

v

, the result of the operation specified by the value of irevcm returned by the previous call to f11gsf

irevcm = 3

, v must remain unchanged.

On intermediate exit: if

irevcm = 3

, v holds the current iterate of the residual vector. Note that this is an approximation to the true residual vector. Otherwise, it does not contain any useful information.

On final exit: if

ifail = 3

0

, the array v is unchanged from the last entry to f11gsf. If

ifail = 1

, the array v is unchanged from the initial entry to f11gsf. If

ifail = 0

2

, the array v contains the true residual vector of the system of equations (see also Section 6). Otherwise, v stores the last iterate of the residual vector unless the Lanczos method (SYMMLQ) was used and

ifail \geq 5

, in which case v is set to

0.0

4: $wgt (*)$ – Real (Kind=nag_wp) arrayInput

Note: the dimension of the array wgt must be at least

\max (1, n)

On entry: the user-supplied weights, if these are to be used in the computation of the vector norms in the termination criterion (see Sections 3 and 5 in f11grf).

Constraint: if weights are to be used, at least one element of wgt must be nonzero.

5: $work (lwork)$ – Complex (Kind=nag_wp) arrayCommunication Array

On initial entry: the array work as returned by f11grf (see also Section 5 in f11grf).

On intermediate re-entry: must remain unchanged.

6: $lwork$ – IntegerInput

On initial entry: the dimension of the array work as declared in the (sub)program from which f11gsf is called (see also Section 3 in f11grf). The required amount of workspace is as follows:

Method	Requirements
CG	$lwork = 120 + 5 n + p$ .
SYMMLQ	$lwork = 120 + 6 n + p$ .

where

$p = 2 \times (maxits + 1)$ , when an estimate of $σ_{1} (A)$ (sigmax) is computed;
$p = 0$ , otherwise.

Constraint:

lwork \geq lwreq

, where lwreq is returned by f11grf.

7: $ifail$ – IntegerInput/Output

On initial entry: ifail must be set to

0

- 1 ​ or ​ 1

. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value

- 1 ​ or ​ 1

is recommended. If the output of error messages is undesirable, then the value

1

is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if

ifail \neq 0

on exit, the recommended value is

- 1

. When the value $- 1 or 1$ is used it is essential to test the value of ifail on exit.

On intermediate exit: the value of ifail is meaningless and should be ignored.

On final exit: (i.e., when

irevcm = 4

)

ifail = 0

, unless the routine detects an error or a warning has been flagged (see Section 6).

6

Error Indicators and Warnings

If on entry

ifail = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = - i$: On entry, the $i$ th argument had an illegal value.

$ifail = 1$: f11gsf has been called again after returning the termination code $irevcm = 4$ . No further computation has been carried out and all input data and data stored for access by f11gtf have remained unchanged.

$ifail = 2$: The required accuracy could not be obtained. However, f11gsf has terminated with reasonable accuracy: the last iterate of the residual satisfied the termination criterion but the exact residual $r = b - A x$ , did not. A small number of iterations have been carried out after the iterated residual satisfied the termination criterion, but were unable to improve on the accuracy. This error code usually implies that your problem has been fully and satisfactorily solved to within or close to the accuracy available on your system. Further iterations are unlikely to improve on this situation. You should call f11gtf to check the values of the left- and right-hand side of the termination condition.

$ifail = 3$: f11grf was either not called before calling f11gsf or it returned an error. The arrays u and v remain unchanged.

$ifail = 4$: The calling program requested a tidy termination before the solution had converged. The arrays u and v return the last iterates available of the solution and of the residual vector, respectively.

$ifail = 5$: The solution did not converge within the maximum number of iterations allowed. The arrays u and v return the last iterates available of the solution and of the residual vector, respectively.

$ifail = 6$: The preconditioner appears not to be positive definite. It is likely that your results are meaningless: both methods require a positive definite preconditioner (see also Section 3). However, the array u returns the last iterate of the solution, the array v returns the last iterate of the residual vector, for the conjugate gradient method only.

$ifail = 7$: The matrix of the coefficients appears not to be positive definite (conjugate gradient method only). The arrays u and v return the last iterates of the solution and residual vector, respectively. However, you should be warned that the results returned can be be in error.

$ifail = 8$: The calling program requested an immediate termination. However, the array u returns the last iterate of the solution, the array v returns the last iterate of the residual vector, for the conjugate gradient method only.

$ifail = 9$: The matrix appears to be singular.

$ifail = 10$: User-supplied weights are to be used, but all elements of the array wgt are zero.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

On completion, i.e.,

irevcm = 4

on exit, the arrays u and v will return the solution and residual vectors,

x_{k}

and

r_{k} = b - A x_{k}

, respectively, at the

k

th iteration, the last iteration performed, unless an immediate termination was requested and the Lanczos method (SYMMLQ) was used.

On successful completion, the termination criterion is satisfied to within the user-specified tolerance, as described in Section 3 in f11grf. The computed values of the left- and right-hand sides of the termination criterion selected can be obtained by a call to f11gtf.

8

Parallelism and Performance

f11gsf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.

f11gsf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9

Further Comments

The number of operations carried out by f11gsf for each iteration is likely to be principally determined by the computation of the matrix-vector products

v = A u

and by the solution of the preconditioning equation

M v = u

in the calling program. Each of these operations is carried out once every iteration.

The number of the remaining operations in f11gsf for each iteration is approximately proportional to

n

. Note that the Lanczos method (SYMMLQ) requires a slightly larger number of operations than the conjugate gradient method.

The number of iterations required to achieve a prescribed accuracy cannot be easily determined at the onset, as it can depend dramatically on the conditioning and spectrum of the preconditioned matrix of the coefficients

\bar{A} = E^{- 1} A E^{- H}

Additional matrix-vector products are required for the computation of

{‖A‖}_{1} = {‖A‖}_{\infty}

, when this has not been supplied to f11grf and is required by the termination criterion employed.

The number of operations required to compute

σ_{1} (\bar{A})

is negligible for reasonable values of sigtol and maxits (see Sections 5 and 9 in f11grf).

If the termination criterion

{‖r_{k}‖}_{p} \leq τ ({‖b‖}_{p} + {‖A‖}_{p} \times {‖x_{k}‖}_{p})

is used (see Section 3 in f11grf) and

‖x_{0}‖ ≫ ‖x_{k}‖

, so that because of loss of significant digits the required accuracy could not be obtained, the iteration is restarted automatically at some suitable point: f11gsf sets

x_{0} = x_{k}

and the computation begins again. For particularly badly scaled problems, more than one restart may be necessary. Naturally, restarting adds to computational costs: it is recommended that the iteration should start from a value

x_{0}

which is as close to the true solution

\tilde{x}

as can be estimated. Otherwise, the iteration should start from

x_{0} = 0

10

Example

See Section 10 in f11grf.

f11gsf (PDF version)

F11 (sparse) Chapter Contents

F11 (sparse) Chapter Introduction

NAG Library Manual

NAG Library Routine Document

f11gsf (complex_herm_basic_solver)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

6

Error Indicators and Warnings

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example