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_file_print_matrix_real_gen (x04ca)

Purpose

nag_file_print_matrix_real_gen (x04ca) is an easy-to-use function to print a real matrix stored in a two-dimensional array.

Syntax

[ifail] = x04ca(matrix, diag, a, title, 'm', m, 'n', n)
[ifail] = nag_file_print_matrix_real_gen(matrix, diag, a, title, 'm', m, 'n', n)

Description

nag_file_print_matrix_real_gen (x04ca) prints a double matrix. It is an easy-to-use driver for nag_file_print_matrix_real_gen_comp (x04cb). The function uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length.
nag_file_print_matrix_real_gen (x04ca) will choose a format code such that numbers will be printed with an $\mathrm{F}8.4$, an $\mathrm{F}11.4$ or a $1\mathrm{PE}13.4$ format. The $\mathrm{F}8.4$ code is chosen if the sizes of all the matrix elements to be printed lie between $0.001$ and $1.0$. The $\mathrm{F}11.4$ code is chosen if the sizes of all the matrix elements to be printed lie between $0.001$ and $9999.9999$. Otherwise the $1\mathrm{PE}13.4$ code is chosen.
The matrix is printed with integer row and column labels, and with a maximum record length of $80$.
The matrix is output to the unit defined by nag_file_set_unit_advisory (x04ab).

None.

Parameters

Compulsory Input Parameters

1:     $\mathrm{matrix}$ – string (length ≥ 1)
Indicates the part of the matrix to be printed.
${\mathbf{matrix}}=\text{'G'}$
The whole of the rectangular matrix.
${\mathbf{matrix}}=\text{'L'}$
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
${\mathbf{matrix}}=\text{'U'}$
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: ${\mathbf{matrix}}=\text{'G'}$, $\text{'L'}$ or $\text{'U'}$.
2:     $\mathrm{diag}$ – string (length ≥ 1)
Unless ${\mathbf{matrix}}=\text{'G'}$, diag must specify whether the diagonal elements of the matrix are to be printed.
${\mathbf{diag}}=\text{'B'}$
The diagonal elements of the matrix are not referenced and not printed.
${\mathbf{diag}}=\text{'U'}$
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
${\mathbf{diag}}=\text{'N'}$
The diagonal elements of the matrix are referenced and printed.
If ${\mathbf{matrix}}=\text{'G'}$, then diag need not be set.
Constraint: if ${\mathbf{matrix}}\ne \text{'G'}$, ${\mathbf{diag}}=\text{'B'}$, $\text{'U'}$ or $\text{'N'}$.
3:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The matrix to be printed. Only the elements that will be referred to, as specified by arguments matrix and diag, need be set.
4:     $\mathrm{title}$ – string
A title to be printed above the matrix.
If , no title (and no blank line) will be printed.
If title contains more than $80$ characters, the contents of title will be wrapped onto more than one line, with the break after $80$ characters.
Any trailing blank characters in title are ignored.

Optional Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
2:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array a and the second dimension of the array a.
The number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than $1$, nag_file_print_matrix_real_gen (x04ca) will exit immediately after printing title; no row or column labels are printed.

Output Parameters

1:     $\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, ${\mathbf{matrix}}\ne \text{'G'}$, $\text{'L'}$ or $\text{'U'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{matrix}}=\text{'L'}$ or $\text{'U'}$, but ${\mathbf{diag}}\ne \text{'N'}$, $\text{'U'}$ or $\text{'B'}$.
${\mathbf{ifail}}=3$
 On entry, $\mathit{lda}<{\mathbf{m}}$.
${\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

Not applicable.

A call to nag_file_print_matrix_real_gen (x04ca) is equivalent to a call to nag_file_print_matrix_real_gen_comp (x04cb) with the following argument values:
```
ncols = 80
indent = 0
labrow = 'I'
labcol = 'I'
form = ' '```

Example

This example program calls nag_file_print_matrix_real_gen (x04ca) twice, first to print a $3$ by $5$ rectangular matrix, and then to print a $5$ by $5$ lower triangular matrix.
```function x04ca_example

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

nmax = 5;
a = zeros(nmax,nmax);

for i = 1:nmax
a(i,:) = [1:nmax] + 10*i;
end

% First matrix : 3x5 general matrix
mtitle = 'Example 1:';
matrix = 'General';
diag   = ' ';

[ifail] = x04ca( ...
matrix, diag, a(1:3,:), mtitle);

fprintf('\n');
% Second matrix : 5x5 non-unit lower triangular
mtitle = 'Example 2:';
matrix = 'Lower';
diag   = 'Non-unit';

[ifail] = x04ca( ...
matrix, diag, a, mtitle);

```
```x04ca example results

Example 1:
1          2          3          4          5
1     11.0000    12.0000    13.0000    14.0000    15.0000
2     21.0000    22.0000    23.0000    24.0000    25.0000
3     31.0000    32.0000    33.0000    34.0000    35.0000

Example 2:
1          2          3          4          5
1     11.0000
2     21.0000    22.0000
3     31.0000    32.0000    33.0000
4     41.0000    42.0000    43.0000    44.0000
5     51.0000    52.0000    53.0000    54.0000    55.0000
```