NAG Toolbox: nag_matop_real_addsub (f01ct)

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'}$ 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 \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{transa}=\text{'N'}$, and at least $\max \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 \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{transb}=\text{'N'}$, and at least $\max \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$.

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double 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: f01ct_example

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