NAG Toolbox: nag_lapack_dgbequ (f07bf)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{m}$ – int64int32nag_int scalar

$m$, the number of rows of the matrix $A$.

Constraint: $\mathbf{m}\ge 0$.

2:     $\mathrm{kl}$ – int64int32nag_int scalar

$k_l$, the number of subdiagonals of the matrix $A$.

Constraint: $\mathbf{kl}\ge 0$.

3:     $\mathrm{ku}$ – int64int32nag_int scalar

$k_u$, the number of superdiagonals of the matrix $A$.

Constraint: $\mathbf{ku}\ge 0$.

4:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – double array

The first dimension of the array ab must be at least $\mathbf{kl}+\mathbf{ku}+1$.

The second dimension of the array ab must be at least $\max \left(1,\mathbf{n}\right)$.

The $m$ by $n$ band matrix $A$ whose scaling factors are to be computed.

The matrix is stored in rows $1$ to $k_l+k_u+1$, more precisely, the element $A_{ij}$ must be stored in

$$\mathbf{ab}\left(k_u+1+i-j,j\right)\text{\hspace{1em} for }\max \left(1,j-k_u\right)\le i\le \min \left(m,j+k_l\right)\text{.}$$

See Further Comments in nag_lapack_dgbsv (f07ba) for further details.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the second dimension of the array ab.

$n$, the number of columns of the matrix $A$.

Constraint: $\mathbf{n}\ge 0$.

Output Parameters

1:     $\mathrm{r}\left(\mathbf{m}\right)$ – double array

If $\mathbf{info}=\mathbf{0}$ or $\mathbf{info}>\mathbf{m}$, r contains the row scale factors, the diagonal elements of $D_R$. The elements of r will be positive.

2:     $\mathrm{c}\left(\mathbf{n}\right)$ – double array

If $\mathbf{info}=\mathbf{0}$, c contains the column scale factors, the diagonal elements of $D_C$. The elements of c will be positive.

3:     $\mathrm{rowcnd}$ – double scalar

If $\mathbf{info}=\mathbf{0}$ or $\mathbf{info}>\mathbf{m}$, rowcnd contains the ratio of the smallest value of $\mathbf{r}\left(i\right)$ to the largest value of $\mathbf{r}\left(i\right)$. If $\mathbf{rowcnd}\ge 0.1$ and amax is neither too large nor too small, it is not worth scaling by $D_R$.

4:     $\mathrm{colcnd}$ – double scalar

If $\mathbf{info}=\mathbf{0}$, colcnd contains the ratio of the smallest value of $\mathbf{c}\left(i\right)$ to the largest value of $\mathbf{c}\left(i\right)$.

If $\mathbf{colcnd}\ge 0.1$, it is not worth scaling by $D_C$.

5:     $\mathrm{amax}$ – double scalar

$\max \left|a_{ij}\right|$. If amax is very close to overflow or underflow, the matrix $A$ should be scaled.

6:     $\mathrm{info}$ – int64int32nag_int scalar

$\mathbf{info}=0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{info}<0$

If $\mathbf{info}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

W  $\mathbf{info}>0\hspace{0.17em}\text{and}\hspace{0.17em}\mathbf{info}\le \mathbf{m}$

Row $\_$ of $A$ is exactly zero.

W  $\mathbf{info}>\mathbf{m}$

Column $\_$ of $A$ is exactly zero.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f07bf_example

function f07bf_example


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

m  = int64(4);
kl = int64(1);
ku = int64(2);
a = [-2.30e-01,  2.54e+00, -3.66e-10,  0;
     -6.98e+10,  2.46e+10, -2.73e+00  -2.13e+10;
      0,         2.56e+00,  2.46e-10,  4.07e+00;
      0,         0,        -4.78e-10, -3.82e+00];

% Convert a to packed representation
[~, ab, ifail] = f01zc(...
                       'p', kl, ku, a, zeros(m, m));

% Compute row and column scaling factors
[r, c, rowcnd, colcnd, amax, info] = ...
  f07bf(m, kl, ku, ab);

format shorte;
fprintf('\nrowcnd = %8.1e colcnd = %8.1e amax = %8.1e\n\n', ...
        rowcnd, colcnd, amax);
fprintf('Row scale factors:\n');
disp(r');
fprintf('Column scale factors:\n');
disp(c');

% Compute values close to underflow and overflow
small = x02am/(x02aj*double(x02bh));
big = 1/small;
thresh = 0.1;

if (rowcnd >= thresh) && (amax >= small) && (amax <= big)
  if colcnd<thresh
    % Just column scale A
    as = a*diag(c);
  end
elseif colcnd>=thresh
  % Just row scale A
  as = diag(r)*a;
else
  % Row and column scale A
  as = diag(r)*a*diag(c);
end

format short;
fprintf('\nScaled Matrix:\n');
disp(as);

f07bf example results


rowcnd =  3.6e-11 colcnd =  1.4e-10 amax =  7.0e+10

Row scale factors:
   3.9370e-01   1.4327e-11   2.4570e-01   2.6178e-01

Column scale factors:
   1.0000e+00   1.0000e+00   6.9399e+09   1.0000e+00


Scaled Matrix:
   -0.0906    1.0000   -1.0000         0
   -1.0000    0.3524   -0.2714   -0.3052
         0    0.6290    0.4195    1.0000
         0         0   -0.8684   -1.0000