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

# NAG Toolbox: nag_sparse_direct_real_gen_matmul (f11mk)

## Purpose

nag_sparse_direct_real_gen_matmul (f11mk) computes a matrix-matrix or transposed matrix-matrix product involving a real, square, sparse nonsymmetric matrix stored in compressed column (Harwell–Boeing) format.

## Syntax

[c, ifail] = f11mk(trans, alpha, icolzp, irowix, a, b, beta, c, 'n', n, 'm', m)
[c, ifail] = nag_sparse_direct_real_gen_matmul(trans, alpha, icolzp, irowix, a, b, beta, c, 'n', n, 'm', m)

## Description

nag_sparse_direct_real_gen_matmul (f11mk) computes either the matrix-matrix product $C←\alpha AB+\beta C$, or the transposed matrix-matrix product $C←\alpha {A}^{\mathrm{T}}B+\beta C$, according to the value of the argument trans, where $A$ is a real $n$ by $n$ sparse nonsymmetric matrix, of arbitrary sparsity pattern with $\mathit{nnz}$ nonzero elements, $B$ and $C$ are $n$ by $m$ real dense matrices. The matrix $A$ is stored in compressed column (Harwell–Boeing) storage format. The array a stores all nonzero elements of $A$, while arrays icolzp and irowix store the compressed column indices and row indices of $A$ respectively.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{trans}$ – string (length ≥ 1)
Specifies whether or not the matrix $A$ is transposed.
${\mathbf{trans}}=\text{'N'}$
$\alpha AB+\beta C$ is computed.
${\mathbf{trans}}=\text{'T'}$
$\alpha {A}^{\mathrm{T}}B+\beta C$ is computed.
Constraint: ${\mathbf{trans}}=\text{'N'}$ or $\text{'T'}$.
2:     $\mathrm{alpha}$ – double scalar
$\alpha$, the scalar factor in the matrix multiplication.
3:     $\mathrm{icolzp}\left(:\right)$int64int32nag_int array
The dimension of the array icolzp must be at least ${\mathbf{n}}+1$
${\mathbf{icolzp}}\left(i\right)$ contains the index in $A$ of the start of a new column. See Compressed column storage (CCS) format in the F11 Chapter Introduction.
4:     $\mathrm{irowix}\left(:\right)$int64int32nag_int array
The dimension of the array irowix must be at least ${\mathbf{icolzp}}\left({\mathbf{n}}+1\right)-1$, the number of nonzeros of the sparse matrix $A$
The row index array of sparse matrix $A$.
5:     $\mathrm{a}\left(:\right)$ – double array
The dimension of the array a must be at least ${\mathbf{icolzp}}\left({\mathbf{n}}+1\right)-1$, the number of nonzeros of the sparse matrix $A$
The array of nonzero values in the sparse matrix $A$.
6:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array
The first dimension of the array b must be at least $\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{m}}\right)$.
The $n$ by $m$ matrix $B$.
7:     $\mathrm{beta}$ – double scalar
The scalar factor $\beta$.
8:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double array
The first dimension of the array c must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array c must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The $n$ by $m$ matrix $C$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the arrays b, c. (An error is raised if these dimensions are not equal.)
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\mathrm{m}$int64int32nag_int scalar
Default: the second dimension of the arrays b, c. (An error is raised if these dimensions are not equal.)
$m$, the number of columns of matrices $B$ and $C$.
Constraint: ${\mathbf{m}}\ge 0$.

### 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{n}}\right)$.
The second dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
$C$ stores $\alpha AB+\beta C$ or $\alpha {A}^{\mathrm{T}}B+\beta C$ depending on the value of trans.
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$
Constraint: $\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
Constraint: $\mathit{ldc}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
Constraint: ${\mathbf{m}}\ge 0$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{trans}}=_$.
Constraint: ${\mathbf{trans}}=\text{'N'}$ or $\text{'T'}$.
${\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.

Not applicable.

None.

## Example

This example reads in a sparse matrix $A$ and a dense matrix $B$. It then calls nag_sparse_direct_real_gen_matmul (f11mk) to compute the matrix-matrix product $C=AB$ and the transposed matrix-matrix product $C={A}^{\mathrm{T}}B$, where
 $A= 2.00 1.00 0 0 0 0 0 1.00 -1.00 0 4.00 0 1.00 0 1.00 0 0 0 1.00 2.00 0 -2.00 0 0 3.00 and B= 0.70 1.40 0.16 0.32 0.52 1.04 0.77 1.54 0.28 0.56 .$
```function f11mk_example

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

% Form C = AB and C = A^TB, for sparse A.

icolzp = [int64(1); 3; 5;  7; 9; 12];
irowix = [int64(1); 3; 1;  5; 2;  3;  2; 4; 3; 4; 5];
a      = [        2;  4; 1; -2; 1;  1; -1; 1; 1; 2; 3];
b = [0.70, 1.40;
0.16, 0.32;
0.52, 1.04;
0.77, 1.54;
0.28, 0.56];
c = [0, 0;
0, 0;
0, 0;
0, 0;
0, 0];

alpha = 1;
beta  = 0;

% Calculate matrix-matrix product
trans = 'N';
[c, ifail] = f11mk( ...
trans, alpha, icolzp, irowix, a, b, beta, c);
fprintf('Matrix-matrix product:\n');
disp(c);

% Calculate transposed matrix-matrix product
trans = 'T';
[c, ifail] = f11mk( ...
trans, alpha, icolzp, irowix, a, b, beta, c);
fprintf('\nTransposed matrix-matrix product:\n');
disp(c);

```
```f11mk example results

Matrix-matrix product:
1.5600    3.1200
-0.2500   -0.5000
3.6000    7.2000
1.3300    2.6600
0.5200    1.0400

Transposed matrix-matrix product:
3.4800    6.9600
0.1400    0.2800
0.6800    1.3600
0.6100    1.2200
2.9000    5.8000

```