Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

## Purpose

nag_matop_complex_addsub (f01cw) adds two complex matrices, each one optionally transposed and multiplied by a scalar.

## Syntax

[c, ifail] = f01cw(transa, transb, m, n, alpha, a, beta, b)
[c, ifail] = nag_matop_complex_addsub(transa, transb, m, n, alpha, a, beta, b)

## Description

nag_matop_complex_addsub (f01cw) performs one of the operations
• $C:=\alpha A+\beta B$,
• $C:=\alpha {A}^{\mathrm{T}}+\beta B$,
• $C:=\alpha {A}^{\mathrm{H}}+\beta B$,
• $C:=\alpha A+\beta {B}^{\mathrm{T}}$,
• $C:=\alpha {A}^{\mathrm{T}}+\beta {B}^{\mathrm{T}}$,
• $C:=\alpha {A}^{\mathrm{H}}+\beta {B}^{\mathrm{T}}$,
• $C:=\alpha A+\beta {B}^{\mathrm{H}}$,
• $C:=\alpha {A}^{\mathrm{T}}+\beta {B}^{\mathrm{H}}$ or
• $C:=\alpha {A}^{\mathrm{H}}+\beta {B}^{\mathrm{H}}$,
where $A$, $B$ and $C$ are matrices, $\alpha$ and $\beta$ are scalars, $T$ denotes transposition and $H$ denotes conjugate transposition. For efficiency, the function contains special code for the cases when one or both of $\alpha$, $\beta$ is equal to zero, unity or minus unity. The matrices, or their transposes, must be compatible for addition. $A$ and $B$ are either $m$ by $n$ or $n$ by $m$ matrices, depending on whether they are to be transposed before addition. $C$ is an $m$ by $n$ matrix.

None.

## 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 \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• otherwise $\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{alpha}}\ne 0$ and ${\mathbf{transa}}=\text{'N'}$, $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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 \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• otherwise $\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{beta}}\ne 0$ and ${\mathbf{transb}}=\text{'N'}$, $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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.

None.

### Output Parameters

1:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – complex array
The first dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The second dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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

Errors or warnings detected by the function:
${\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}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The results returned by nag_matop_complex_addsub (f01cw) are accurate to machine precision.

The time taken for a call of nag_matop_complex_addsub (f01cw) varies with m, n and the values of $\alpha$ and $\beta$. The function is quickest if either or both of $\alpha$ and $\beta$ are equal to zero, or plus or minus unity.

## Example

The following program reads in a pair of matrices $A$ and ${\mathbf{b}}$, along with values for transa, transb, alpha and beta, and adds them together, printing the result matrix $C$. The process is continued until the end of the input stream is reached.
```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

```