NAG Toolbox: nag_matop_complex_gen_matrix_actexp_rcomm (f01hb)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{irevcm}$ – int64int32nag_int scalar

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

2:     $\mathrm{m}$ – int64int32nag_int scalar

The number of columns of the matrix $B$.

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

3:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array

The first dimension of the array b must be at least $\mathbf{n}$.

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

On initial entry: the $n$ by $m$ matrix $B$.

On intermediate re-entry: must not be changed.

4:     $\mathrm{t}$ – complex scalar

The scalar $t$.

5:     $\mathrm{b2}\left(\mathit{ldb2},:\right)$ – complex array

The first dimension of the array b2 must be at least $\mathbf{n}$.

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

6:     $\mathrm{x}\left(\mathit{ldx},:\right)$ – complex array

The first dimension of the array x must be at least $\mathbf{n}$.

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

On initial entry: need not be set.

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

7:     $\mathrm{y}\left(\mathit{ldy},:\right)$ – complex array

The first dimension of the array y must be at least $\mathbf{n}$.

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

On initial entry: need not be set.

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

8:     $\mathrm{p}\left(\mathbf{n}\right)$ – complex array

On initial entry: need not be set.

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

9:     $\mathrm{r}\left(\mathbf{n}\right)$ – complex array

On initial entry: need not be set.

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

10:   $\mathrm{z}\left(\mathbf{n}\right)$ – complex array

On initial entry: need not be set.

On intermediate re-entry: must not be changed.

11:   $\mathrm{ccomm}\left(\mathbf{n}\times \left(\mathbf{m}+2\right)\right)$ – complex array

12:   $\mathrm{comm}\left(3\times \mathbf{n}+14\right)$ – double array

13:   $\mathrm{icomm}\left(2\times \mathbf{n}+40\right)$ – int64int32nag_int array

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the first dimension of the arrays b, b2, x, y, ccomm and the dimension of the arrays p, r, z. (An error is raised if these dimensions are not equal.)

$n$, the order of the matrix $A$.

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

2:     $\mathrm{tr}$ – complex scalar

Default: $0$

The trace of $A$. If this is not available then any number can be supplied ($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 Further Comments.

Output Parameters

1:     $\mathrm{irevcm}$ – int64int32nag_int scalar

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

(a)

if $\mathbf{irevcm}=1$: evaluate $B_2=AB$, where $B_2$ is an $n$ by $m$ matrix, and store the result in b2; if $\mathbf{irevcm}=2$: evaluate $Y=AX$, where $X$ and $Y$ are $n$ by $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.

(b)

call nag_matop_complex_gen_matrix_actexp_rcomm (f01hb) again with all other parameters unchanged.

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

2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array

The first dimension of the array b will be $\mathbf{n}$.

The second dimension of the array b will be $\mathbf{m}$.

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

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

3:     $\mathrm{b2}\left(\mathit{ldb2},:\right)$ – complex array

The first dimension of the array b2 will be $\mathbf{n}$.

The second dimension of the array b2 will be $\mathbf{m}$.

On final exit: the array is undefined.

4:     $\mathrm{x}\left(\mathit{ldx},:\right)$ – complex array

The first dimension of the array x will be $\mathbf{n}$.

The second dimension of the array x will be $2$.

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

On final exit: the array is undefined.

5:     $\mathrm{y}\left(\mathit{ldy},:\right)$ – complex array

The first dimension of the array y will be $\mathbf{n}$.

The second dimension of the array y will be $2$.

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

On final exit: the array is undefined.

6:     $\mathrm{p}\left(\mathbf{n}\right)$ – complex array

On final exit: the array is undefined.

7:     $\mathrm{r}\left(\mathbf{n}\right)$ – complex array

On final exit: the array is undefined.

8:     $\mathrm{z}\left(\mathbf{n}\right)$ – complex array

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

On final exit: the array is undefined.

9:     $\mathrm{ccomm}\left(\mathbf{n}\times \left(\mathbf{m}+2\right)\right)$ – complex array

10:   $\mathrm{comm}\left(3\times \mathbf{n}+14\right)$ – double array

11:   $\mathrm{icomm}\left(2\times \mathbf{n}+40\right)$ – int64int32nag_int array

12:   $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W  $\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}=\_$.
Constraint: $\mathbf{irevcm}=0$.

On intermediate re-entry, $\mathbf{irevcm}=\_$.
Constraint: $\mathbf{irevcm}=1$, $2$, $3$, $4$ or $5$.

   $\mathbf{ifail}=-2$

On initial entry, $\mathbf{n}=\_$.
Constraint: $\mathbf{n}\ge 0$.

   $\mathbf{ifail}=-3$

On initial entry, $\mathbf{m}=\_$.
Constraint: $\mathbf{m}\ge 0$.

   $\mathbf{ifail}=-5$

On initial entry, $\mathit{ldb}=\_$ and $\mathbf{n}=\_$.
Constraint: $\mathit{ldb}\ge \mathbf{n}$.

   $\mathbf{ifail}=-9$

On initial entry, $\mathit{ldb2}=\_$ and $\mathbf{n}=\_$.
Constraint: $\mathit{ldb2}\ge \mathbf{n}$.

   $\mathbf{ifail}=-11$

On initial entry, $\mathit{ldx}=\_$ and $\mathbf{n}=\_$.
Constraint: $\mathit{ldx}\ge \mathbf{n}$.

   $\mathbf{ifail}=-13$

On initial entry, $\mathit{ldy}=\_$ and $\mathbf{n}=\_$.
Constraint: $\mathit{ldy}\ge \mathbf{n}$.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Use of TrA

When to use nag_matop_complex_gen_matrix_actexp_rcomm (f01hb)

Use in Conjunction with NAG Toolbox Functions

while irevcm ~= 0
  switch irevcm
    case {1}
      % Compute ab and store in b2
    case {2}
      % Compute ax and store in y
    case {3}
      % Compute a^Hy and store in x
    case {4}
      % compute az and store in p
    case {5}
      % compute a^Hz and store in r
  end

Example

Open in the MATLAB editor: f01hb_example

function f01hb_example


fprintf('f01hb example results\n\n');

a = [0.7+0.8i, -0.2+0.0i, 1.0+0.0i, 0.6+0.5i;
     0.3+0.7i,  0.7+0.0i, 0.9+3.0i, 1.0+0.8i;
     0.3+3.0i, -7.0+0.0i, 0.2+0.6i, 0.7+0.5i;
     0.0+0.9i,  4.0+0.0i, 0.0+0.0i, 0.2+0.0i];
b = [0.1+0.0i,  1.2+0.1i;
     1.3+0.9i, -0.2+2.0i;
     4.0+0.6i, -1.0+0.8i;
     0.4+0.0i, -0.9+0.0i];
n = 4;
m = 2;

t = complex(1.1);
b2 = b; x = b; y = b;
p = complex(zeros(n, 1)); r = p; z = p;
comm =  zeros(3*n+14, 1);
icomm = zeros(2*n+40, 1, 'int64');
ccomm = complex(zeros(n*(m+2), 1));
tr = trace(a);

% Compute exp(ta)b by reverse communication
irevcm = int64(0);
done = false;

while ~done
  [irevcm, b, b2, x, y, p, r, z, ccomm, comm, icomm, ifail] = ...
  f01hb( ...
         irevcm, b, t, b2, x, y, p, r, z, ccomm, comm, icomm, 'tr', tr);
  switch irevcm
    case {0}
      done = true;
    case {1}
      % Compute ab and store in b2
      b2 = a*b;
    case {2}
      % Compute ax and store in y
      y = a*x;
    case {3}
      % Compute a^Hy and store in x
      x = a'*y;
    case {4}
      % compute az and store in p
      p = a*z;
    case {5}
      % compute a^Hz and store in r
      r = a'*z;
  end
end

fprintf('\n exp(tA)B\n');
disp(b);

f01hb example results


 exp(tA)B
 -15.3125 + 5.9123i  -4.5605 - 2.4288i
  12.3396 -50.6993i   9.2005 -10.3632i
 -65.4353 +34.3271i -17.6075 - 1.0019i
  45.6506 -28.3253i  11.3339 + 0.1127i