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 : = αA + βB$C:=\alpha A+\beta B$,
• C : = αAT + βB$C:=\alpha {A}^{\mathrm{T}}+\beta B$,
• C : = αAH + βB$C:=\alpha {A}^{\mathrm{H}}+\beta B$,
• C : = αA + βBT$C:=\alpha A+\beta {B}^{\mathrm{T}}$,
• C : = αAT + βBT$C:=\alpha {A}^{\mathrm{T}}+\beta {B}^{\mathrm{T}}$,
• C : = αAH + βBT$C:=\alpha {A}^{\mathrm{H}}+\beta {B}^{\mathrm{T}}$,
• C : = αA + βBH$C:=\alpha A+\beta {B}^{\mathrm{H}}$,
• C : = αAT + βBH$C:=\alpha {A}^{\mathrm{T}}+\beta {B}^{\mathrm{H}}$ or
• C : = αAH + βBH$C:=\alpha {A}^{\mathrm{H}}+\beta {B}^{\mathrm{H}}$,
where A$A$, B$B$ and C$C$ are matrices, α$\alpha$ and β$\beta$ are scalars, T$T$ denotes transposition and H$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$A$ and B$B$ are either m$m$ by n$n$ or n$n$ by m$m$ matrices, depending on whether they are to be transposed before addition. C$C$ is an m$m$ by n$n$ matrix.

None.

## Parameters

### Compulsory Input Parameters

1:     transa – string (length ≥ 1)
2:     transb – string (length ≥ 1)
transa and transb must specify whether or not the matrix A$A$ and the matrix B$B$, respectively, are to be transposed before addition.
transa or transb = 'N'${\mathbf{transb}}=\text{'N'}$
The matrix will not be transposed.
transa or transb = 'T'${\mathbf{transb}}=\text{'T'}$
The matrix will be transposed.
transa or transb = 'C'${\mathbf{transb}}=\text{'C'}$
The matrix will be transposed and conjugated.
Constraint: transa​ or ​transb = 'N'${\mathbf{transa}}\text{​ or ​}{\mathbf{transb}}=\text{'N'}$, 'T'$\text{'T'}$ or 'C'$\text{'C'}$.
3:     m – int64int32nag_int scalar
m$m$, the number of rows of the matrices A$A$ and B$B$ or their transposes. Also the number of rows of the matrix C$C$.
Constraint: m0${\mathbf{m}}\ge 0$.
4:     n – int64int32nag_int scalar
n$n$, the number of columns of the matrices A$A$ and B$B$ or their transposes. Also the number of columns of the matrix C$C$.
Constraint: n0${\mathbf{n}}\ge 0$.
5:     alpha – complex scalar
The scalar α$\alpha$, by which matrix A$A$ is multiplied before addition.
6:     a(lda, : $:$) – complex array
The first dimension, lda, of the array a must satisfy
• if transa = 'N'${\mathbf{transa}}=\text{'N'}$, ldamax (1,m)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• otherwise ldamax (1,n)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if alpha0${\mathbf{alpha}}\ne 0$ and transa = 'N'${\mathbf{transa}}=\text{'N'}$, max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ if alpha0${\mathbf{alpha}}\ne 0$ and transa = 'T'${\mathbf{transa}}=\text{'T'}$ or 'C'$\text{'C'}$ and at least 1$1$ if alpha = 0${\mathbf{alpha}}=0$
The matrix A$A$. If α = 0$\alpha =0$, the array a is not referenced.
7:     beta – complex scalar
The scalar β$\beta$, by which matrix B$B$ is multiplied before addition.
8:     b(ldb, : $:$) – complex array
The first dimension, ldb, of the array b must satisfy
• if transb = 'N'${\mathbf{transb}}=\text{'N'}$, ldbmax (1,m)$\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• otherwise ldbmax (1,n)$\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if beta0${\mathbf{beta}}\ne 0$ and transb = 'N'${\mathbf{transb}}=\text{'N'}$, max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ if beta0${\mathbf{beta}}\ne 0$ and transb = 'T'${\mathbf{transb}}=\text{'T'}$ or 'C'$\text{'C'}$ and at least 1$1$ if beta = 0${\mathbf{beta}}=0$
The matrix B$B$. If β = 0$\beta =0$, the array b is not referenced.

None.

lda ldb ldc

### Output Parameters

1:     c(ldc, : $:$) – complex array
The first dimension of the array c will be max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
ldcmax (1,m)$\mathit{ldc}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The elements of the m$m$ by n$n$ matrix C$C$.
2:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, one or both of transa or transb is not equal to 'N', 'T' or 'C'.
ifail = 2${\mathbf{ifail}}=2$
 On entry, one or both of m or n is less than 0$0$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, lda < max (1,P)$\mathit{lda}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,P\right)$, where P = m$\mathrm{P}={\mathbf{m}}$ if transa = 'N'${\mathbf{transa}}=\text{'N'}$, and P = n$\mathrm{P}={\mathbf{n}}$ otherwise.
ifail = 4${\mathbf{ifail}}=4$
 On entry, ldb < max (1,P)$\mathit{ldb}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,P\right)$, where P = m$\mathrm{P}={\mathbf{m}}$ if transb = 'N'${\mathbf{transb}}=\text{'N'}$, and P = n$\mathrm{P}={\mathbf{n}}$ otherwise.
ifail = 5${\mathbf{ifail}}=5$
 On entry, ldc < max (1,m)$\mathit{ldc}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.

## 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

```function nag_matop_complex_addsub_example
transa = 'N';
transb = 'N';
m = int64(4);
n = int64(3);
alpha = complex(1);
a = [ 1 + 2i,  2.5 - 1.5i,  2.5 - 1i;
-2 - 2i,  2 - 1i,  -1.5 - 1i;
3.5 - 1.5i,  2 + 1.5i,  2 + 3i;
-2.5 + 0i,  -3 + 2.5i,  -2 + 2i];
beta = complex(1);
b = [ 2 + 1i,  -2.5 + 3i,  -0.5 + 0i;
1 + 0i,  1 - 1.5i,  1.5 - 1.5i;
-1.5 - 0.5i,  2.5 - 2i,  -0.5 + 1i;
2.5 - 1.5i,  -1 + 1.5i,  2 + 3i];
[c, ifail] = nag_matop_complex_addsub(transa, transb, m, n, alpha, a, beta, b)
```
```

c =

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

ifail =

0

```
```function f01cw_example
transa = 'N';
transb = 'N';
m = int64(4);
n = int64(3);
alpha = complex(1);
a = [ 1 + 2i,  2.5 - 1.5i,  2.5 - 1i;
-2 - 2i,  2 - 1i,  -1.5 - 1i;
3.5 - 1.5i,  2 + 1.5i,  2 + 3i;
-2.5 + 0i,  -3 + 2.5i,  -2 + 2i];
beta = complex(1);
b = [ 2 + 1i,  -2.5 + 3i,  -0.5 + 0i;
1 + 0i,  1 - 1.5i,  1.5 - 1.5i;
-1.5 - 0.5i,  2.5 - 2i,  -0.5 + 1i;
2.5 - 1.5i,  -1 + 1.5i,  2 + 3i];
[c, ifail] = f01cw(transa, transb, m, n, alpha, a, beta, b)
```
```

c =

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

ifail =

0

```