NAG Toolbox: nag_bnd_lin_lsq (e04pc)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Default: $\mathbf{itype}=1$

Provides the choice of returning a regularized solution if the matrix is not of full rank.

$\mathbf{itype}=0$

Specifies that a regularized solution is to be computed.

$\mathbf{itype}=1$

Specifies that no regularization is to take place.

Constraint: $\mathbf{itype}=0$ or $1$.

2:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array

The first dimension of the array a must be at least $\mathbf{m}$.

The second dimension of the array a must be at least $\mathbf{n}$.

The $m$ by $n$ matrix $A$.

3:     $\mathrm{b}\left(\mathbf{m}\right)$ – double array

The right-hand side vector $b$.

4:     $\mathrm{bl}\left(\mathbf{n}\right)$ – double array

5:     $\mathrm{bu}\left(\mathbf{n}\right)$ – double array

$\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_i$.

Constraint: $\mathbf{bl}\left(\mathit{i}\right)\le \mathbf{bu}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

Optional Input Parameters

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

Default: the first dimension of the array a and the dimension of the array b. (An error is raised if these dimensions are not equal.)

$m$, the number of linear equations.

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

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

Default: the second dimension of the array a and the dimension of the arrays bl, bu. (An error is raised if these dimensions are not equal.)

$n$, the number of variables.

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

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

Default: $\mathbf{tol}=0.0$

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. Increasing its value from $\sqrt{\mathit{machine precision}}$ will increase the likelihood of additional elements of $x$ being set to zero. It may be worth experimenting with increasing values of tol to determine whether the nature of the solution, $x$, changes significantly. In practice a value of $\sqrt{\mathit{machine precision}}$ is recommended (see nag_machine_precision (x02aj)).

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

Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array

The first dimension of the array a will be $\mathbf{m}$.

The second dimension of the array a will be $\mathbf{n}$.

If $\mathbf{itype}=1$, a contains the product matrix $QA$, where $Q$ is an $m$ by $m$ orthogonal matrix generated by nag_bnd_lin_lsq (e04pc); otherwise a is unchanged.

2:     $\mathrm{b}\left(\mathbf{m}\right)$ – double array

If $\mathbf{itype}=1$, the product of $Q$ times the original vector $b$, where $Q$ is as described in argument a; otherwise b is unchanged.

3:     $\mathrm{x}\left(\mathbf{n}\right)$ – double array

The solution vector $x$.

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

The Euclidean norm of the residual vector $b-Ax$.

5:     $\mathrm{nfree}$ – int64int32nag_int scalar

Indicates the number of components of the solution vector that are not at one of the constraints.

6:     $\mathrm{w}\left(\mathbf{n}\right)$ – double array

Contains the dual solution vector. The magnitude of $\mathbf{w}\left(i\right)$ gives a measure of the improvement in the objective value if the corresponding bound were to be relaxed so that $x_i$ could take different values.

A value of $\mathbf{w}\left(i\right)$ equal to the special value $-999.0$ 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.0$. If $\mathbf{itype}=1$ then the values contained in w (other than those set to $-999.0$) may be unreliable; the corresponding values in indx may likewise be unreliable. If you have any doubts set $\mathbf{itype}=0$. Otherwise the values of $\mathbf{w}\left(i\right)$ have the following meaning:

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

if $x_i$ is unconstrained.

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

if $x_i$ is constrained by its lower bound.

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

if $x_i$ is constrained by its upper bound.

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

may be any value if $l_i=u_i$.

7:     $\mathrm{indx}\left(\mathbf{n}\right)$ – int64int32nag_int array

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 of the solution 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 of the solution have been constrained by either the lower or upper bound.

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

These elements of the solution 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}$.)

8:     $\mathrm{ifail}$ – int64int32nag_int scalar

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

Error Indicators and Warnings

   $\mathbf{ifail}=1$

Constraint: $\mathbf{bl}\left(i\right)\le \mathbf{bu}\left(i\right)$.

Constraint: $\mathit{lda}\ge \mathbf{m}$.

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

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

   $\mathbf{ifail}=2$

The function failed to converge in $3\times n$ iterations. This is not expected. Please contact NAG.

   $\mathbf{ifail}=-99$

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

   $\mathbf{ifail}=-399$

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

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: e04pc_example

function e04pc_example


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

a = [0.05, 0.05, 0.25,-0.25;
     0.25, 0.25, 0.05,-0.05;
     0.35, 0.35, 1.75,-1.75;
     1.75, 1.75, 0.35,-0.35;
     0.30,-0.30, 0.30, 0.30;
     0.40,-0.40, 0.40, 0.40];
b = [1,  2,  3,  4,  5,  6,];
bl = [1, 1, 1, 1];
bu = [5, 5, 5, 5];
itype = int64(1);


[a, b, x, rnorm, nfree, w, indx, ifail] = e04pc(itype, a, b, bl, bu);
fprintf('\nSolution vector:\n');
disp(x');
fprintf('Dual Solution:\n');
disp(w');
fprintf('Residual: %9.4f\n', rnorm);

e04pc example results


Solution vector:
    1.8133    1.0000    5.0000    4.3467

Dual Solution:
         0   -2.7200    2.7200         0

Residual:    3.4246