NAG Toolbox: nag_lapack_zgbequ (f07bt)

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)$ – complex 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_zgbsv (f07bn) 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: f07bt_example

function f07bt_example


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

m  = int64(4);
kl = int64(1);
ku = int64(2);
abr = [ 0     0         0.97     0.59   ;
        0    -2.05e-10 -2.99     3.33e10;
       -1.65 -1.48e-10 -1.06e10 -0.46;   
        0    -0.77      4.48     0];      
abi = [ 0     0        -2.84    -0.48;
        0    -8.50e-11  3.01    -1.04e10;
        2.26 -1.75e-10  1.94e10 -1.72;
        6.3   2.83     -1.09     0      ];
ab = abr + i*abi;

[r, c, rowcnd, colcnd, amax, info] = ...
  f07bt( m, kl, ku, ab);

fprintf('rowcnd = %8.1e colcnd = %8.1e amax = %8.1e\n\n', ...
        rowcnd, colcnd, amax);
fprintf('Row scale factors:\n');
fprintf('%12.2e',r)
fprintf('\nColumn scale factors:\n');
fprintf('%12.2e',c)
fprintf('\n\n');

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

% Convert ab to full representation a
[a, ab, ifail] = f01zd( ...
                        'u', kl, ku, complex(zeros(m, m)), ab);

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

mtitle = 'Scaled Matrix RAC:';
[ifail] = x04da( ...
                 'G', 'N', as, mtitle);

f07bt example results

rowcnd =  8.9e-11 colcnd =  8.2e-11 amax =  4.4e+10

Row scale factors:
    2.56e-01    1.59e-01    2.29e-11    1.80e-01
Column scale factors:
    1.00e+00    1.21e+10    1.00e+00    1.00e+00

 Scaled Matrix RAC:
          1       2       3       4
 1  -0.4220 -0.6364  0.2481  0.0000
     0.5780 -0.2639 -0.7263  0.0000

 2   0.0000 -0.2852 -0.4746  0.0937
     1.0000 -0.3372  0.4778 -0.0762

 3   0.0000 -0.2139 -0.2426  0.7620
     0.0000  0.7861  0.4439 -0.2380

 4   0.0000  0.0000  0.8043 -0.0826
     0.0000  0.0000 -0.1957 -0.3088