NAG FL Interface
f01hbf (complex_​gen_​matrix_​actexp_​rcomm)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{irevcm}$ – Integer Input/Output

On initial entry: must be set to $0$.

On intermediate exit: $\mathbf{irevcm}=1$, $2$, $3$, $4$ or $5$. The calling program must:

1. (a)if $\mathbf{irevcm}=1$: evaluate $B_2=AB$, where $B_2$ is an $n\times m$ matrix, and store the result in b2;
   if $\mathbf{irevcm}=2$: evaluate $Y=AX$, where $X$ and $Y$ are $n\times 2$ matrices, and store the result in y;
   if $\mathbf{irevcm}=3$: evaluate $X=A^{\mathrm{H}}Y$ and store the result in x;
   if $\mathbf{irevcm}=4$: evaluate $p=Az$ and store the result in p;
   if $\mathbf{irevcm}=5$: evaluate $r=A^{\mathrm{H}}z$ and store the result in r.
2. (b)call f01hbf again with all other parameters unchanged.

On final exit: $\mathbf{irevcm}=0$.

Note: any values you return to f01hbf 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 f01hbf. If your code does inadvertently return any NaNs or infinities, f01hbf is likely to produce unexpected results.

2: $\mathbf{n}$ – Integer Input

On entry: $n$, the order of the matrix $A$.

Constraint: $\mathbf{n}\ge 0$.

3: $\mathbf{m}$ – Integer Input

On entry: the number of columns of the matrix $B$.

Constraint: $\mathbf{m}\ge 0$.

4: $\mathbf{b}(\mathbf{ldb},*)$ – Complex (Kind=nag_wp) array Input/Output

Note: the second dimension of the array b must be at least $\mathbf{m}$.

On initial entry: the $n\times m$ matrix $B$.

On intermediate exit: if $\mathbf{irevcm}=1$, contains the $n\times m$ matrix $B$.

On intermediate re-entry: must not be changed.

On final exit: the $n\times m$ matrix $e^{tA}B$.

5: $\mathbf{ldb}$ – Integer Input

On entry: the first dimension of the array b as declared in the (sub)program from which f01hbf is called.

Constraint: $\mathbf{ldb}\ge \mathbf{n}$.

6: $\mathbf{t}$ – Complex (Kind=nag_wp) Input

On entry: the scalar $t$.

7: $\mathbf{tr}$ – Complex (Kind=nag_wp) Input

On entry: the trace of $A$. If this is not available then any number can be supplied ($0.0$ is a reasonable default); however, in the trivial case, $n=1$, the result $e^{\mathbf{tr}t}B$ is immediately returned in the first row of $B$. See Section 9.

8: $\mathbf{b2}(\mathbf{ldb2},*)$ – Complex (Kind=nag_wp) array Input/Output

Note: the second dimension of the array b2 must be at least $\mathbf{m}$.

On initial entry: need not be set.

On intermediate re-entry: if $\mathbf{irevcm}=1$, must contain $AB$.

On final exit: the array is undefined.

9: $\mathbf{ldb2}$ – Integer Input

On initial entry: the first dimension of the array b2 as declared in the (sub)program from which f01hbf is called.

Constraint: $\mathbf{ldb2}\ge \mathbf{n}$.

10: $\mathbf{x}(\mathbf{ldx},*)$ – Complex (Kind=nag_wp) array Input/Output

Note: the second dimension of the array x must be at least $2$.

On initial entry: need not be set.

On intermediate exit: if $\mathbf{irevcm}=2$, contains the current $n\times 2$ matrix $X$.

On intermediate re-entry: if $\mathbf{irevcm}=3$, must contain $A^{\mathrm{H}}Y$.

On final exit: the array is undefined.

11: $\mathbf{ldx}$ – Integer Input

On entry: the first dimension of the array x as declared in the (sub)program from which f01hbf is called.

Constraint: $\mathbf{ldx}\ge \mathbf{n}$.

12: $\mathbf{y}(\mathbf{ldy},*)$ – Complex (Kind=nag_wp) array Input/Output

Note: the second dimension of the array y must be at least $2$.

On initial entry: need not be set.

On intermediate exit: if $\mathbf{irevcm}=3$, contains the current $n\times 2$ matrix $Y$.

On intermediate re-entry: if $\mathbf{irevcm}=2$, must contain $AX$.

On final exit: the array is undefined.

13: $\mathbf{ldy}$ – Integer Input

On entry: the first dimension of the array y as declared in the (sub)program from which f01hbf is called.

Constraint: $\mathbf{ldy}\ge \mathbf{n}$.

14: $\mathbf{p}\left(\mathbf{n}\right)$ – Complex (Kind=nag_wp) array Input/Output

On initial entry: need not be set.

On intermediate re-entry: if $\mathbf{irevcm}=4$, must contain $Az$.

On final exit: the array is undefined.

15: $\mathbf{r}\left(\mathbf{n}\right)$ – Complex (Kind=nag_wp) array Input/Output

On initial entry: need not be set.

On intermediate re-entry: if $\mathbf{irevcm}=5$, must contain $A^{\mathrm{H}}z$.

On final exit: the array is undefined.

16: $\mathbf{z}\left(\mathbf{n}\right)$ – Complex (Kind=nag_wp) array Input/Output

On initial entry: need not be set.

On intermediate exit: if $\mathbf{irevcm}=4$ or $5$, contains the vector $z$.

On intermediate re-entry: must not be changed.

On final exit: the array is undefined.

17: $\mathbf{ccomm}\left(\mathbf{n}\times (\mathbf{m}+2)\right)$ – Complex (Kind=nag_wp) array Communication Array

18: $\mathbf{comm}\left(3\times \mathbf{n}+14\right)$ – Real (Kind=nag_wp) array Communication Array

19: $\mathbf{icomm}\left(2\times \mathbf{n}+40\right)$ – Integer array Communication Array

20: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $\mathrm{-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 $\mathrm{-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 $\mathrm{-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).

6 Error Indicators and Warnings

$\mathbf{ifail}=2$

$e^{tA}B$ has been computed using an IEEE double precision Taylor series, although the arithmetic precision is higher than IEEE double precision.

$\mathbf{ifail}=-1$

On initial entry, $\mathbf{irevcm}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{irevcm}=0$.

On intermediate re-entry, $\mathbf{irevcm}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{irevcm}=1$, $2$, $3$, $4$ or $5$.

$\mathbf{ifail}=-2$

On initial entry, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}\ge 0$.

$\mathbf{ifail}=-3$

On initial entry, $\mathbf{m}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{m}\ge 0$.

$\mathbf{ifail}=-5$

On initial entry, $\mathbf{ldb}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ldb}\ge \mathbf{n}$.

$\mathbf{ifail}=-9$

On initial entry, $\mathbf{ldb2}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ldb2}\ge \mathbf{n}$.

$\mathbf{ifail}=-11$

On initial entry, $\mathbf{ldx}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ldx}\ge \mathbf{n}$.

$\mathbf{ifail}=-13$

On initial entry, $\mathbf{ldy}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ldy}\ge \mathbf{n}$.

$\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.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

9.1 Use of $\mathit{T}\mathit{r}\left(\mathit{A}\right)$

9.2 When to use f01hbf

9.3 Use in Conjunction with NAG Library Routines

revcm: Do 
  Call f01hbf(irevcm,n,m,b,ldb,t,tr,b2,ldb2,x,ldx,y,ldx,p,r,z, &
             ccomm,comm,icomm,ifail)
  If (irevcm == 0) Then 
      Exit revcm 
  Else If (irevcm == 1) Then
      .. Code to compute b2=ab ..
  Else If (irevcm == 2) Then
      .. Code to compute y=ax ..
  Else If (irevcm == 3) Then
      .. Code to compute x=a^h y ..
  Else If (irevcm == 4) Then
      .. Code to compute p=az ..
  Else If (irevcm == 5) Then 
      .. Code to compute r=a^h z ..
  End If
End Do revcm

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results