NAG FL Interface
f04qaf (real_​gen_​sparse_​lsqsol)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{m}$ – Integer Input

On entry: $m$, the number of rows of the matrix $A$.

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

2: $\mathbf{n}$ – Integer Input

On entry: $n$, the number of columns of the matrix $A$.

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

3: $\mathbf{b}\left(\mathbf{m}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the right-hand side vector $b$.

On exit: b is overwritten.

4: $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: the solution vector $x$.

5: $\mathbf{se}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: the estimates of the standard errors of the components of $x$. Thus $\mathbf{se}\left(i\right)$ contains an estimate of $\sqrt{{\nu }_{ii}}$, where ${\nu }_{ii}$ is the $i$th diagonal element of the estimated variance-covariance matrix $V$. The estimates returned in se will be the lower bounds on the actual estimated standard errors, but will usually be correct to at least one significant figure.

6: $\mathbf{aprod}$ – Subroutine, supplied by the user. External Procedure

aprod must perform the operations $y≔y+Ax$ and $x≔x+A^{\mathrm{T}}y$ for given vectors $x$ and $y$.

The specification of aprod is:

Fortran Interface copy

Subroutine aprod ( mode, m, n, x, y, ruser, lruser, iuser, liuser) Integer, Intent (In) :: m, n, lruser, liuser Integer, Intent (Inout) :: mode, iuser(liuser) Real (Kind=nag_wp), Intent (Inout) :: x(n), y(m), ruser(lruser)

C Header Interface copy

void  aprod (Integer *mode, const Integer *m, const Integer *n, double x[], double y[], double ruser[], const Integer *lruser, Integer iuser[], const Integer *liuser)

C++ Header Interface copy

#include <nag.h> extern "C" { void  aprod (Integer &mode, const Integer &m, const Integer &n, double x[], double y[], double ruser[], const Integer &lruser, Integer iuser[], const Integer &liuser) }

1: $\mathbf{mode}$ – Integer Input/Output

On entry: specifies which operation is to be performed.

$\mathbf{mode}=1$

aprod must compute $y+Ax$.

$\mathbf{mode}=2$

aprod must compute $x+A^{\mathrm{T}}y$.

On exit: may be used as a flag to indicate a failure in the computation of $y+Ax$ or $x+A^{\mathrm{T}}y$. If mode is negative on exit from aprod, f04qaf will exit immediately with ifail set to mode.

2: $\mathbf{m}$ – Integer Input

On entry: $m$, the number of rows of $A$.

3: $\mathbf{n}$ – Integer Input

On entry: $n$, the number of columns of $A$.

4: $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the vector $x$.

On exit: if $\mathbf{mode}=1$, x must be unchanged.

If $\mathbf{mode}=2$, x must contain $x+A^{\mathrm{T}}y$.

5: $\mathbf{y}\left(\mathbf{m}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the vector $y$.

On exit: if $\mathbf{mode}=1$, y must contain $y+Ax$.

If $\mathbf{mode}=2$, y must be unchanged.

6: $\mathbf{ruser}\left(\mathbf{lruser}\right)$ – Real (Kind=nag_wp) array User Workspace

7: $\mathbf{lruser}$ – Integer Input

8: $\mathbf{iuser}\left(\mathbf{liuser}\right)$ – Integer array User Workspace

9: $\mathbf{liuser}$ – Integer Input

aprod is called with the arguments ruser, lruser, iuser and liuser as supplied to f04qaf. You should use the arrays ruser, lruser, iuser and liuser to supply information to aprod.

aprod must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which f04qaf is called. Arguments denoted as Input must not be changed by this procedure.

Note: aprod should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by f04qaf. If your code inadvertently does return any NaNs or infinities, f04qaf is likely to produce unexpected results.

7: $\mathbf{damp}$ – Real (Kind=nag_wp) Input

On entry: the value $\lambda$. If either problem (1) or problem (2) is to be solved, damp must be supplied as zero.

8: $\mathbf{atol}$ – Real (Kind=nag_wp) Input

On entry: the tolerance, ${\mathit{tol}}_1$, of the convergence criteria (6) and (7); it should be an estimate of the largest relative error in the elements of $A$. For example, if the elements of $A$ are correct to about $4$ significant figures, then atol should be set to about $5\times {10}^{\mathrm{-4}}$. If atol is supplied as less than $\epsilon$, where $\epsilon$ is the machine precision, the value $\epsilon$ is used instead of atol.

9: $\mathbf{btol}$ – Real (Kind=nag_wp) Input

On entry: the tolerance, ${\mathit{tol}}_2$, of the convergence criterion (6); it should be an estimate of the largest relative error in the elements of $B$. For example, if the elements of $B$ are correct to about $4$ significant figures, then btol should be set to about $5\times {10}^{\mathrm{-4}}$. If btol is supplied as less than $\epsilon$, the value $\epsilon$ is used instead of btol.

10: $\mathbf{conlim}$ – Real (Kind=nag_wp) Input

On entry: the value $c_{\lim }$ of equation (8); it should be an upper limit on the condition number of $\overline{A}$. conlim should not normally be chosen much larger than $1.0/\mathbf{atol}$. If conlim is supplied as zero, the value $1.0/\epsilon$ is used instead of conlim.

11: $\mathbf{itnlim}$ – Integer Input/Output

On entry: an upper limit on the number of iterations. If $\mathbf{itnlim}\le 0$, the value n is used in place of itnlim, but for ill-conditioned problems a higher value of itnlim is likely to be necessary.

On exit: unchanged unless $\mathbf{itnlim}\le 0$ on entry, in which case it is set to n.

12: $\mathbf{msglvl}$ – Integer Input

On entry: the level of printing from f04qaf. If $\mathbf{msglvl}\le 0$, then no printing occurs, but otherwise messages will be output on the current advisory message unit (see x04abf). A description of the printed output is given in Section 9.1. The level of printing is determined as follows:

$\mathbf{msglvl}\le 0$

No printing.

$\mathbf{msglvl}=1$

A brief summary is printed just prior to return from f04qaf.

$\mathbf{msglvl}\ge 2$

A summary line is printed periodically to monitor the progress of f04qaf, together with a brief summary just prior to return from f04qaf.

13: $\mathbf{itn}$ – Integer Output

On exit: the number of iterations performed.

14: $\mathbf{anorm}$ – Real (Kind=nag_wp) Output

On exit: an estimate of $\Vert \overline{A}\Vert$ for the matrix $\overline{A}$ of (4).

15: $\mathbf{acond}$ – Real (Kind=nag_wp) Output

On exit: an estimate of $\mathrm{cond}\left(\overline{A}\right)$ which is a lower bound.

16: $\mathbf{rnorm}$ – Real (Kind=nag_wp) Output

On exit: an estimate of $\Vert \overline{r}\Vert$ for the residual, $\overline{r}$, of (5) corresponding to the solution $x$ returned in x. Note that $\Vert \overline{r}\Vert$ is the function being minimized.

17: $\mathbf{arnorm}$ – Real (Kind=nag_wp) Output

On exit: an estimate of the $\Vert {\overline{A}}^{\mathrm{T}}\overline{r}\Vert$ corresponding to the solution $x$ returned in x.

18: $\mathbf{xnorm}$ – Real (Kind=nag_wp) Output

On exit: an estimate of $\Vert x\Vert$ for the solution $x$ returned in x.

19: $\mathbf{work}(\mathbf{n},2)$ – Real (Kind=nag_wp) array Workspace

20: $\mathbf{ruser}\left(\mathbf{lruser}\right)$ – Real (Kind=nag_wp) array User Workspace

ruser is not used by f04qaf, but is passed directly to aprod and may be used to pass information to this routine.

21: $\mathbf{lruser}$ – Integer Input

On entry: the dimension of the array ruser as declared in the (sub)program from which f04qaf is called.

22: $\mathbf{iuser}\left(\mathbf{liuser}\right)$ – Integer array User Workspace

iuser is not used by f04qaf, but is passed directly to aprod and may be used to pass information to this routine.

23: $\mathbf{liuser}$ – Integer Input

On entry: the dimension of the array iuser as declared in the (sub)program from which f04qaf is called.

24: $\mathbf{inform}$ – Integer Output

On exit: the reason for termination of f04qaf.

$\mathbf{inform}=0$

The exact solution is $x=0$. No iterations are performed in this case.

$\mathbf{inform}=1$

The termination criterion of (6) has been satisfied with ${\mathit{tol}}_1$ and ${\mathit{tol}}_2$ as the values supplied in atol and btol respectively.

$\mathbf{inform}=2$

The termination criterion of (7) has been satisfied with ${\mathit{tol}}_1$ as the value supplied in atol.

$\mathbf{inform}=3$

The termination criterion of (6) has been satisfied with ${\mathit{tol}}_1$ and/or ${\mathit{tol}}_2$ as the value $\epsilon$, where $\epsilon$ is the machine precision. One or both of the values supplied in atol and btol must have been less than $\epsilon$ and was too small for this machine.

$\mathbf{inform}=4$

The termination criterion of (7) has been satisfied with ${\mathit{tol}}_1$ as the value $\epsilon$. The value supplied in atol must have been less than $\epsilon$ and was too small for this machine.

The values $\mathbf{inform}=5$, $6$ and $7$ correspond to failure with $\mathbf{ifail}=\mathbf{2}$, $\mathbf{3}$ and $\mathbf{4}$ respectively (see Section 6) and when ifail is negative inform will be set to the same negative value.

25: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $\mathrm{-1}$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $\mathrm{-1}$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $\mathrm{-1}$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, $\mathbf{m}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{m}\ge 1$.

On entry, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}\ge 1$.

$\mathbf{ifail}=2$

Termination criteria not satisfied, but the condition number bound supplied in conlim has been met.

The condition of (8) has been satisfied for the value of $c_{\lim }$ supplied in conlim. If this failure is unexpected you should check that aprod is working correctly. Although conditions (6) or (7) have not been satisfied, the values returned in rnorm, arnorm and xnorm may nevertheless indicate that an acceptable solution has been reached.

$\mathbf{ifail}=3$

Termination criteria not satisfied, but the condition number is bounded by $1$/x02ajf.

The condition of (8) has been satisfied for the value $c_{\lim }=1.0/\epsilon$, where $\epsilon$ is the machine precision. The matrix $\overline{A}$ is nearly singular or rank deficient and the problem is too ill-conditioned for this machine. If this failure is unexpected, you should check that aprod is working correctly.

$\mathbf{ifail}=4$

Maximum number of iterations reached.

The limit on the number of iterations has been reached. The number of iterations required by f04qaf and the condition of the matrix $\overline{A}$ can depend strongly on the scaling of the problem. Poor scaling of the rows and columns of $A$ should be avoided whenever possible.

$\mathbf{ifail}<0$

mode in aprod has been set to: $⟨\mathit{\text{value}}⟩$.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

9.1 Description of the Printed Output

10 Example

Figure 1

10.1 Program Text

10.2 Program Data

10.3 Program Results