NAG FL Interfacef04zdf (complex_​gen_​norm_​rcomm)

▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

1Purpose

f04zdf estimates the $1$-norm of a complex rectangular matrix without accessing the matrix explicitly. It uses reverse communication for evaluating matrix products. The routine may be used for estimating condition numbers of square matrices.

2Specification

Fortran Interface
 Subroutine f04zdf ( m, n, x, ldx, y, ldy, t, seed, work,
 Integer, Intent (In) :: m, n, ldx, ldy, t, seed Integer, Intent (Inout) :: irevcm, iwork(2*n+5*t+20), ifail Real (Kind=nag_wp), Intent (Inout) :: estnrm, rwork(2*n) Complex (Kind=nag_wp), Intent (Inout) :: x(ldx,*), y(ldy,*), work(m*t)
C Header Interface
#include <nag.h>
 void f04zdf_ (Integer *irevcm, const Integer *m, const Integer *n, Complex x[], const Integer *ldx, Complex y[], const Integer *ldy, double *estnrm, const Integer *t, const Integer *seed, Complex work[], double rwork[], Integer iwork[], Integer *ifail)
The routine may be called by the names f04zdf or nagf_linsys_complex_gen_norm_rcomm.

3Description

f04zdf computes an estimate (a lower bound) for the $1$-norm
 $‖A‖1 = max 1≤j≤n ∑ i=1 m |aij|$ (1)
of an $m×n$ complex matrix $A=\left({a}_{ij}\right)$. The routine regards the matrix $A$ as being defined by a user-supplied ‘Black Box’ which, given an $n×t$ matrix $X$ (with $t\ll n$) or an $m×t$ matrix $Y$, can return $AX$ or ${A}^{\mathrm{H}}Y$, where ${A}^{\mathrm{H}}$ is the complex conjugate transpose. A reverse communication interface is used; thus control is returned to the calling program whenever a matrix product is required.
Note:  this routine is not recommended for use when the elements of $A$ are known explicitly; it is then more efficient to compute the $1$-norm directly from the formula (1) above.
The main use of the routine is for estimating ${‖{B}^{-1}‖}_{1}$ for a square matrix $B$, and hence the condition number ${\kappa }_{1}\left(B\right)={‖B‖}_{1}{‖{B}^{-1}‖}_{1}$, without forming ${B}^{-1}$ explicitly ($A={B}^{-1}$ above).
If, for example, an $LU$ factorization of $B$ is available, the matrix products ${B}^{-1}X$ and ${B}^{-\mathrm{H}}Y$ required by f04zdf may be computed by back- and forward-substitutions, without computing ${B}^{-1}$.
The routine can also be used to estimate $1$-norms of matrix products such as ${A}^{-1}B$ and $ABC$, without forming the products explicitly. Further applications are described in Higham (1988).
Since ${‖A‖}_{\infty }={‖{A}^{\mathrm{H}}‖}_{1}$, f04zdf can be used to estimate the $\infty$-norm of $A$ by working with ${A}^{\mathrm{H}}$ instead of $A$.
The algorithm used is described in Higham and Tisseur (2000).

4References

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
Higham N J and Tisseur F (2000) A block algorithm for matrix $1$-norm estimation, with an application to $1$-norm pseudospectra SIAM J. Matrix. Anal. Appl. 21 1185–1201

5Arguments

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 x and y must remain unchanged.
1: $\mathbf{irevcm}$Integer Input/Output
On initial entry: must be set to $0$.
On intermediate exit: ${\mathbf{irevcm}}=1$ or $2$, and x contains the $n×t$ matrix $X$ and y contains the $m×t$ matrix $Y$. The calling program must
1. (a)if ${\mathbf{irevcm}}=1$, evaluate $AX$ and store the result in y
or
if ${\mathbf{irevcm}}=2$, evaluate ${A}^{\mathrm{H}}Y$ and store the result in x, where ${A}^{\mathrm{H}}$ is the complex conjugate transpose;
2. (b)call f04zdf once again, with all the arguments unchanged.
On intermediate re-entry: irevcm must be unchanged.
On final exit: ${\mathbf{irevcm}}=0$.
Note: any values you return to f04zdf 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 f04zdf. If your code does inadvertently return any NaNs or infinities, f04zdf is likely to produce unexpected results.
2: $\mathbf{m}$Integer Input
On entry: the number of rows of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
3: $\mathbf{n}$Integer Input
On initial entry: $n$, the number of columns of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
4: $\mathbf{x}\left({\mathbf{ldx}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array x must be at least ${\mathbf{t}}$.
On initial entry: need not be set.
On intermediate exit: if ${\mathbf{irevcm}}=1$, contains the current matrix $X$.
On intermediate re-entry: if ${\mathbf{irevcm}}=2$, must contain ${A}^{\mathrm{H}}Y$.
On final exit: the array is undefined.
5: $\mathbf{ldx}$Integer Input
On initial entry: the leading dimension of the array x as declared in the (sub)program from which f04zdf is called.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
6: $\mathbf{y}\left({\mathbf{ldy}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array y must be at least ${\mathbf{t}}$.
On initial entry: need not be set.
On intermediate exit: if ${\mathbf{irevcm}}=2$, contains the current matrix $Y$.
On intermediate re-entry: if ${\mathbf{irevcm}}=1$, must contain $AX$.
On final exit: the array is undefined.
7: $\mathbf{ldy}$Integer Input
On initial entry: the leading dimension of the array y as declared in the (sub)program from which f04zdf is called.
Constraint: ${\mathbf{ldy}}\ge {\mathbf{m}}$.
8: $\mathbf{estnrm}$Real (Kind=nag_wp) Input/Output
On initial entry: need not be set.
On intermediate re-entry: must not be changed.
On final exit: an estimate (a lower bound) for ${‖A‖}_{1}$.
9: $\mathbf{t}$Integer Input
On entry: the number of columns $t$ of the matrices $X$ and $Y$. This is an argument that can be used to control the accuracy and reliability of the estimate and corresponds roughly to the number of columns of $A$ that are visited during each iteration of the algorithm.
If ${\mathbf{t}}\ge 2$ then a partly random starting matrix is used in the algorithm.
Suggested value: ${\mathbf{t}}=2$.
Constraint: $1\le {\mathbf{t}}\le {\mathbf{m}}$.
10: $\mathbf{seed}$Integer Input
On entry: the seed used for random number generation.
If ${\mathbf{t}}=1$, seed is not used.
Constraint: if ${\mathbf{t}}>1$, ${\mathbf{seed}}\ge 1$.
11: $\mathbf{work}\left({\mathbf{m}}×{\mathbf{t}}\right)$Complex (Kind=nag_wp) array Communication Array
12: $\mathbf{rwork}\left(2×{\mathbf{n}}\right)$Real (Kind=nag_wp) array Communication Array
13: $\mathbf{iwork}\left(2×{\mathbf{n}}+5×{\mathbf{t}}+20\right)$Integer array Communication Array
On initial entry: need not be set.
On intermediate re-entry: must not be changed.
14: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
Internal error; please contact NAG.
${\mathbf{ifail}}=-1$
On entry, ${\mathbf{irevcm}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{irevcm}}=0$, $1$ or $2$.
On initial entry, ${\mathbf{irevcm}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{irevcm}}=0$.
${\mathbf{ifail}}=-2$
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\ge 0$.
${\mathbf{ifail}}=-3$
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 0$.
${\mathbf{ifail}}=-5$
On entry, ${\mathbf{ldx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-7$
On entry, ${\mathbf{ldy}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldy}}\ge {\mathbf{m}}$.
${\mathbf{ifail}}=-9$
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{t}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{t}}\le {\mathbf{m}}$.
${\mathbf{ifail}}=-10$
On entry, ${\mathbf{t}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{seed}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{t}}>1$, ${\mathbf{seed}}\ge 1$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7Accuracy

In extensive tests on random matrices of size up to $m=n=450$ the estimate estnrm has been found always to be within a factor two of ${‖A‖}_{1}$; often the estimate has many correct figures. However, matrices exist for which the estimate is smaller than ${‖A‖}_{1}$ by an arbitrary factor; such matrices are very unlikely to arise in practice. See Higham and Tisseur (2000) for further details.

8Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
f04zdf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
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.

9Further Comments

9.1Timing

For most problems the time taken during calls to f04zdf will be negligible compared with the time spent evaluating matrix products between calls to f04zdf.
The number of matrix products required depends on the matrix $A$. At most six products of the form $Y=AX$ and five products of the form $X={A}^{\mathrm{H}}Y$ will be required. The number of iterations is independent of the choice of $t$.

9.2Overflow

It is your responsibility to guard against potential overflows during evaluation of the matrix products. In particular, when estimating ${‖{B}^{-1}‖}_{1}$ using a triangular factorization of $B$, f04zdf should not be called if one of the factors is exactly singular – otherwise division by zero may occur in the substitutions.

9.3Choice of $\mathbit{t}$

The argument $t$ controls the accuracy and reliability of the estimate. For $t=1$, the algorithm behaves similarly to the LAPACK estimator xLACON. Increasing $t$ typically improves the estimate, without increasing the number of iterations required.
For $t\ge 2$, random matrices are used in the algorithm, so for repeatable results the same value of seed should be used each time.
A value of $t=2$ is recommended for new users.

9.4Use in Conjunction with NAG Library Routines

To estimate the $1$-norm of the inverse of a matrix $A$, the following skeleton code can normally be used:
```      ...  code to factorize A ...
If (A is not singular) Then
irevcm = 0
10       Call f04zdf (irevcm,m,n,x,ldx,y,ldy,estnrm,t,seed,work,  &
rwork,iwork,ifail)
If (irevcm.ne.0) Then
If (irevcm.eq.1) Then
...  code to compute y=inv(A)x ...
Else
...  code to compute x=inv(herm(A))y ...
End If
Go To 10
End If
End If```
To compute ${A}^{-1}X$ or ${A}^{-\mathrm{H}}Y$, solve the equation $AY=X$ or ${A}^{\mathrm{H}}X=Y$ storing the result in y or x respectively.
It is also straightforward to use f04zdf for Hermitian positive definite matrices, using f06tff, f07frf and f07fsf for factorization and solution.
For upper or lower triangular square matrices, no factorization routine is needed: $Y={A}^{-1}X$ and $X={A}^{-\mathrm{H}}Y$ may be computed by calls to f06sjf (or f06skf if the matrix is banded, or f06slf if the matrix is stored in packed form).

10Example

This example estimates the condition number ${‖A‖}_{1}{‖{A}^{-1}‖}_{1}$ of the matrix $A$ given by
 $A = ( 0.7+0.1i -0.2+0.0i 1.0+0.0i 0.0+0.0i 0.0+0.0i 0.1+0.0i 0.3+0.0i 0.7+0.0i 0.0+0.0i 1.0+0.2i 0.9+0.0i 0.2+0.0i 0.0+5.9i 0.0+0.0i 0.2+0.0i 0.7+0.0i 0.4+6.1i 1.1+0.4i 0.0+0.1i 0.0+0.1i -0.7+0.0i 0.2+0.0i 0.1+0.0i 0.1+0.0i 0.0+0.0i 4.0+0.0i 0.0+0.0i 1.0+0.0i 9.0+0.0i 0.0+0.1i 4.5+6.7i 0.1+0.4i 0.0+3.2i 1.2+0.0i 0.0+0.0i 7.8+0.2i ) .$

10.1Program Text

Program Text (f04zdfe.f90)

10.2Program Data

Program Data (f04zdfe.d)

10.3Program Results

Program Results (f04zdfe.r)