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_real_addsub (f01ct) adds two double matrices, each one optionally transposed and multiplied by a scalar.

## Syntax

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

## Description

nag_matop_real_addsub (f01ct) performs one of the operations
• $C:=\alpha A+\beta B$,
• $C:=\alpha {A}^{\mathrm{T}}+\beta B$,
• $C:=\alpha A+\beta {B}^{\mathrm{T}}$ or
• $C:=\alpha {A}^{\mathrm{T}}+\beta {B}^{\mathrm{T}}$,
where $A$, $B$ and $C$ are matrices, and $\alpha$ and $\beta$ are scalars. 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'}$ or $\text{'C'}$
The matrix will be transposed.
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}$ – double scalar
The scalar $\alpha$, by which matrix $A$ is multiplied before addition.
6:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double 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{transa}}=\text{'N'}$, and at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ otherwise.
If $\alpha =0.0$, the elements of array a need not be assigned. If $\alpha \ne 0.0$, then if ${\mathbf{transa}}=\text{'N'}$, the leading $m$ by $n$ part of a must contain the matrix $A$, otherwise the leading $n$ by $m$ part of a must contain the matrix $A$.
7:     $\mathrm{beta}$ – double scalar
The scalar $\beta$, by which matrix $B$ is multiplied before addition.
8:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double 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{transb}}=\text{'N'}$, and at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ otherwise.
If $\beta =0.0$, the elements of array b need not be assigned. If $\beta \ne 0.0$, then if ${\mathbf{transa}}=\text{'N'}$, the leading $m$ by $n$ part of b must contain the matrix $B$, otherwise the leading $n$ by $m$ part of b must contain the matrix $B$.

None.

### Output Parameters

1:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double 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_real_addsub (f01ct) are accurate to machine precision.

The time taken for a call of nag_matop_real_addsub (f01ct) 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 $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 f01ct_example

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

% Example 1: C = A + B
a = [ 1.0   2.5   3.0;
-2.0   2.0  -1.5;
3.5   2.0  -2.5;
1.5  -2.0   1.0];
b = [ 2.0  -2.5  -2.0;
1.0   1.0   1.0;
-1.5   2.5  -2.5;
2.0  -2.0   1.0];
[m,n] = size(a);
m = int64(m);
n = int64(n);

transa = 'N';
transb = 'N';
alpha  =  1;
beta   =  1;
[c1, ifail] = f01ct( ...
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   2.5   3.0   1.5   2.5;
-2.0   2.0  -1.5  -2.0  -1.0;
3.5   2.0  -2.5  -1.5   2.5];
b = [ 2.0  -2.5  -2.0;
1.0   1.0   1.0;
-1.5   2.5  -2.5;
2.0  -2.0   1.0;
1.0   1.0   2.5];
[m,n] = size(a);
m = int64(m);
n = int64(n);

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

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

```
```f01ct example results

Example 1: C = A + B
3.0000         0    1.0000
-1.0000    3.0000   -0.5000
2.0000    4.5000   -5.0000
3.5000   -4.0000    2.0000

Example 2: C = A - B'
-1.0000    1.5000    4.5000   -0.5000    1.5000
0.5000    1.0000   -4.0000         0   -2.0000
5.5000    1.0000         0   -2.5000         0

```