NAG Toolbox: nag_matop_complex_addsub (f01cw)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{transa}$ – string (length ≥ 1)

2:     $\mathrm{transb}$ – string (length ≥ 1)

transa and transb must specify whether or not the matrix $A$ and the matrix $B$, respectively, are to be transposed before addition.

transa or $\mathbf{transb}=\text{'N'}$

The matrix will not be transposed.

transa or $\mathbf{transb}=\text{'T'}$

The matrix will be transposed.

transa or $\mathbf{transb}=\text{'C'}$

The matrix will be transposed and conjugated.

Constraint: $\mathbf{transa}\text{ or }\mathbf{transb}=\text{'N'}$, $\text{'T'}$ or $\text{'C'}$.

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

$m$, the number of rows of the matrices $A$ and $B$ or their transposes. Also the number of rows of the matrix $C$.

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

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

$n$, the number of columns of the matrices $A$ and $B$ or their transposes. Also the number of columns of the matrix $C$.

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

5:     $\mathrm{alpha}$ – complex scalar

The scalar $\alpha$, by which matrix $A$ is multiplied before addition.

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

The first dimension, $\mathit{lda}$, of the array a must satisfy

• if $\mathbf{transa}=\text{'N'}$, $\mathit{lda}\ge \max \left(1,\mathbf{m}\right)$;
• otherwise $\mathit{lda}\ge \max \left(1,\mathbf{n}\right)$.

The second dimension of the array a must be at least $\max \left(1,\mathbf{n}\right)$ if $\mathbf{alpha}\ne 0$ and $\mathbf{transa}=\text{'N'}$, $\max \left(1,\mathbf{m}\right)$ if $\mathbf{alpha}\ne 0$ and $\mathbf{transa}=\text{'T'}$ or $\text{'C'}$ and at least $1$ if $\mathbf{alpha}=0$.

The matrix $A$. If $\alpha =0$, the array a is not referenced.

7:     $\mathrm{beta}$ – complex scalar

The scalar $\beta$, by which matrix $B$ is multiplied before addition.

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

The first dimension, $\mathit{ldb}$, of the array b must satisfy

• if $\mathbf{transb}=\text{'N'}$, $\mathit{ldb}\ge \max \left(1,\mathbf{m}\right)$;
• otherwise $\mathit{ldb}\ge \max \left(1,\mathbf{n}\right)$.

The second dimension of the array b must be at least $\max \left(1,\mathbf{n}\right)$ if $\mathbf{beta}\ne 0$ and $\mathbf{transb}=\text{'N'}$, $\max \left(1,\mathbf{m}\right)$ if $\mathbf{beta}\ne 0$ and $\mathbf{transb}=\text{'T'}$ or $\text{'C'}$ and at least $1$ if $\mathbf{beta}=0$.

The matrix $B$. If $\beta =0$, the array b is not referenced.

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – complex array

The first dimension of the array c will be $\max \left(1,\mathbf{m}\right)$.

The second dimension of the array c will be $\max \left(1,\mathbf{n}\right)$.

The elements of the $m$ by $n$ matrix $C$.

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

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

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,

one or both of transa or transb is not equal to 'N', 'T' or 'C'.

   $\mathbf{ifail}=2$

On entry,

one or both of m or n is less than $0$.

   $\mathbf{ifail}=3$

On entry,

$\mathit{lda}<\max \left(1,P\right)$, where $\mathrm{P}=\mathbf{m}$ if $\mathbf{transa}=\text{'N'}$, and $\mathrm{P}=\mathbf{n}$ otherwise.

   $\mathbf{ifail}=4$

On entry,

$\mathit{ldb}<\max \left(1,P\right)$, where $\mathrm{P}=\mathbf{m}$ if $\mathbf{transb}=\text{'N'}$, and $\mathrm{P}=\mathbf{n}$ otherwise.

   $\mathbf{ifail}=5$

On entry,

$\mathit{ldc}<\max \left(1,\mathbf{m}\right)$.

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

Example

Open in the MATLAB editor: f01cw_example

function f01cw_example


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

% Example 1: C = A + B
a = [ 1.0 + 2.0i   2.5 - 1.5i   2.5 - 1.0i;
     -2.0 - 2.0i   2.0 - 1.0i  -1.5 - 1.0i;
      3.5 - 1.5i   2.0 + 1.5i   2.0 + 3.0i;
     -2.5 + 0.0i  -3.0 + 2.5i  -2.0 + 2.0i];
b = [ 2.0 + 1.0i  -2.5 + 3.0i  -0.5 + 0.0i;
      1.0 + 0.0i   1.0 - 1.5i   1.5 - 1.5i;
     -1.5 - 0.5i   2.5 - 2.0i  -0.5 + 1.0i;
      2.5 - 1.5i  -1.0 + 1.5i   2.0 + 3.0i];

[m,n] = size(a);
m = int64(m);
n = int64(n);

transa = 'N';
transb = 'N';
alpha  = complex(1);
beta   = complex(1);
[c1, ifail] = f01cw( ...
                     transa, transb, m, n, alpha, a, beta, b);

disp('Example 1: C = A + B');
disp(c1);

% Example 2: C = A - B^T
a = [ 1.0 + 1.0i   2.5 - 1.5i   3.0 + 1.5i;
     -2.0 - 0.5i   2.0 + 1.5i  -1.5 - 2.5i];
b = [ 2.0 + 1.0i  -2.5 + 2.0i;
      1.0 + 0.0i   1.0 + 1.5i;
     -1.5 - 0.5i   2.5 - 1.0i]; 
[m,n] = size(a);
m = int64(m);
n = int64(n);

transa = 'N';
transb = 'T';
alpha  = complex(1);
beta   = complex(-1);
[c2, ifail] = f01cw( ...
                     transa, transb, m, n, alpha, a, beta, b);

disp('Example 2: C = A - B^T');
disp(c2);

f01cw example results

Example 1: C = A + B
   3.0000 + 3.0000i   0.0000 + 1.5000i   2.0000 - 1.0000i
  -1.0000 - 2.0000i   3.0000 - 2.5000i   0.0000 - 2.5000i
   2.0000 - 2.0000i   4.5000 - 0.5000i   1.5000 + 4.0000i
   0.0000 - 1.5000i  -4.0000 + 4.0000i   0.0000 + 5.0000i

Example 2: C = A - B^T
  -1.0000 + 0.0000i   1.5000 - 1.5000i   4.5000 + 2.0000i
   0.5000 - 2.5000i   1.0000 + 0.0000i  -4.0000 - 1.5000i