NAG Library Routine Document

E04PCF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     ITYPE – INTEGERInput

On entry:

$\mathbf{ITYPE}=0$

Specifies that a regularized solution will be computed.

$\mathbf{ITYPE}=1$

Specifies that no regularization is to take place.

2:     M – INTEGERInput

On entry: $m$, the number of equations.

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

3:     N – INTEGERInput

On entry: $n$, the number of variables.

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

4:     A(LDA,$*$) – REAL (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array A must be at least $\mathbf{N}$.

On entry: the $m$ by $n$ matrix $A$.

On exit: if $\mathbf{ITYPE}=1$, A contains the product matrix, $QA$, where $Q$ is an $m$ by $m$ orthogonal matrix generated by E04PCF; otherwise A is unchanged.

5:     LDA – INTEGERInput

On entry: the first dimension of the array A as declared in the (sub)program from which E04PCF is called.

Constraint: $\mathbf{LDA}\ge \mathbf{M}$.

6:     B(M) – REAL (KIND=nag_wp) arrayInput/Output

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

On exit: if $\mathbf{ITYPE}=1$, the product of $Q$ times the original vector $B$; otherwise B is unchanged.

7:     BL(N) – REAL (KIND=nag_wp) arrayInput

8:     BU(N) – REAL (KIND=nag_wp) arrayInput

On entry: $\mathbf{BL}\left(\mathit{i}\right)$ and $\mathbf{BU}\left(\mathit{i}\right)$ must specify the lower and upper bounds, $l_i$ and $u_i$ respectively to be imposed on the solution vector $x\left(i\right)$.

Constraint: $\mathbf{BL}\left(\mathit{i}\right)\le \mathbf{BU}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{N}$.

9:     TOL – REAL (KIND=nag_wp)Input

On entry: TOL specifies a parameter used to determine the relative linear dependence of a column vector for a variable moved from its initial value. It determines the computational rank of the matrix.

If on entry $\mathbf{TOL}<\mathit{machine precision}$, then machine precision is used.

10:   X(N) – REAL (KIND=nag_wp) arrayOutput

On exit: the solution vector $x$.

11:   RNORM – REAL (KIND=nag_wp)Output

On exit: the Euclidean norm of the residual vector, $b-Ax$.

12:   NFREE – INTEGEROutput

On exit: indicates the number of components of the solution vector that are not at one of the constraints.

13:   W(N) – REAL (KIND=nag_wp) arrayOutput

On exit: contains the dual solution vector.

A value of $\mathbf{W}\left(i\right)$ equal to the special value $-999$ is indicative of the matrix $A$ not having full rank. It is only likely to occur when $\mathbf{ITYPE}=1$. However a matrix may have less than full rank without $\mathbf{W}\left(i\right)$ being set to $-999$. Under these circumstances the value of $\mathbf{W}\left(i\right)$, and hence $\mathbf{INDX}\left(i\right)$, may be unreliable. If you have any doubts set $\mathbf{ITYPE}=0$. Otherwise values have the following meaning:

$\mathbf{W}\left(i\right)=0$

If $x\left(i\right)$ is unconstrained.

$\mathbf{W}\left(i\right)<0$

If $x\left(i\right)$ is constrained by its lower bound.

$\mathbf{W}\left(i\right)>0$

If $x\left(i\right)$ is constrained by its upper bound.

$\mathbf{W}\left(i\right)$

May be any value if $l_i=u_i$.

14:   INDX(N) – INTEGER arrayOutput

On exit: the contents of this array describe the components of the solution vector as follows:

$\mathbf{INDX}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{NFREE}$

These elements have not hit a constraint i.e., $\mathbf{W}\left(i\right)=0$.

$\mathbf{INDX}\left(\mathit{i}\right)$, for $\mathit{i}=\mathbf{NFREE}+1,\dots ,k$

These elements have been constrained by either the lower or upper bound constraint.

$\mathbf{INDX}\left(\mathit{i}\right)$, for $\mathit{i}=k+1,\dots ,\mathbf{N}$

These elements are fixed by the bounds i.e., $\mathbf{BL}\left(i\right)=\mathbf{BU}\left(i\right)$.

Here $k$ is determined from NFREE and the number of fixed components. (Often the latter will be $0$, so $k$ will be $\mathbf{N}-\mathbf{NFREE}$.)

15:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if $\mathbf{IFAIL}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }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}}⟩$ and $\mathbf{LDA}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{LDA}\ge \mathbf{M}$.

On entry, $\mathbf{M}=⟨\mathit{\text{value}}⟩$ and $\mathbf{N}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{M}\ge 0$ and $\mathbf{N}\ge 0$.

On entry, when $i=⟨\mathit{\text{value}}⟩$, $\mathbf{BL}\left(i\right)=⟨\mathit{\text{value}}⟩$ and $\mathbf{BU}\left(i\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{BL}\left(i\right)\le \mathbf{BU}\left(i\right)$.

$\mathbf{IFAIL}=2$

Failed to converge in $⟨\mathit{\text{value}}⟩$ iterations.

$\mathbf{IFAIL}=-999$

Dynamic memory allocation failed.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (e04pcfe.f90)

9.2  Program Data

Program Data (e04pcfe.d)

9.3  Program Results

Program Results (e04pcfe.r)