NAG Toolbox: nag_opt_lp_solve (e04mf)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

The first dimension of the array a must be at least $\max \left(1,\mathbf{nclin}\right)$.

The second dimension of the array a must be at least $\mathbf{n}$ if $\mathbf{nclin}>0$ and at least $1$ if $\mathbf{nclin}=0$.

The $\mathit{i}$th row of a must contain the coefficients of the $\mathit{i}$th general linear constraint, for $\mathit{i}=1,2,\dots ,m_L$.

If $\mathbf{nclin}=0$, a is not referenced.

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

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

Must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first $n$ elements of each array must contain the bounds on the variables, and the next $m_L$ elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., $l_j=-\infty$), set $\mathbf{bl}\left(j\right)\le -\mathit{bigbnd}$, and to specify a nonexistent upper bound (i.e., $u_j=+\infty$), set $\mathbf{bu}\left(j\right)\ge \mathit{bigbnd}$; the default value of $\mathit{bigbnd}$ is ${10}^{20}$, but this may be changed by the optional parameter Infinite Bound Size. To specify the $j$th constraint as an equality, set $\mathbf{bl}\left(j\right)=\mathbf{bu}\left(j\right)=\beta$, say, where $\left|\beta \right|<\mathit{bigbnd}$.

Constraints:

• $\mathbf{bl}\left(\mathit{j}\right)\le \mathbf{bu}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}+\mathbf{nclin}$;
• if $\mathbf{bl}\left(\mathit{j}\right)=\mathbf{bu}\left(\mathit{j}\right)=\beta$, $\left|\beta \right|<\mathit{bigbnd}$.

4:     $\mathrm{cvec}\left(:\right)$ – double array

The dimension of the array cvec must be at least $\mathbf{n}$ if the problem is of type LP (the default), and at least $1$ otherwise

The coefficients of the objective function when the problem is of type LP.

If the problem is of type FP, cvec is not referenced.

5:     $\mathrm{istate}\left(\mathbf{n}+\mathbf{nclin}\right)$ – int64int32nag_int array

Need not be set if the (default) optional parameter Cold Start is used.

If the optional parameter Warm Start has been chosen, istate specifies the desired status of the constraints at the start of the feasibility phase. More precisely, the first $n$ elements of istate refer to the upper and lower bounds on the variables, and the next $m_L$ elements refer to the general linear constraints (if any). Possible values for $\mathbf{istate}\left(j\right)$ are as follows:

$\mathbf{istate}\left(j\right)$	Meaning
0	The corresponding constraint should not be in the initial working set.
1	The constraint should be in the initial working set at its lower bound.
2	The constraint should be in the initial working set at its upper bound.
3	The constraint should be in the initial working set as an equality. This value must not be specified unless $\mathbf{bl}\left(j\right)=\mathbf{bu}\left(j\right)$.

The values $-2$, $-1$ and $4$ are also acceptable but will be reset to zero by the function. If nag_opt_lp_solve (e04mf) has been called previously with the same values of n and nclin, istate already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The function also adjusts (if necessary) the values supplied in x to be consistent with istate.

Constraint: $-2\le \mathbf{istate}\left(\mathit{j}\right)\le 4$, for $\mathit{j}=1,2,\dots ,\mathbf{n}+\mathbf{nclin}$.

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

An initial estimate of the solution.

7:     $\mathrm{lwsav}\left(120\right)$ – logical array

8:     $\mathrm{iwsav}\left(610\right)$ – int64int32nag_int array

9:     $\mathrm{rwsav}\left(475\right)$ – double array

The arrays lwsav, iwsav and rwsav must not be altered between calls to any of the functions nag_opt_lp_solve (e04mf), nag_opt_lp_option_string (e04mh) or nag_opt_init (e04wb).

Optional Input Parameters

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

Default: the dimension of the array x.

$n$, the number of variables.

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

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

Default: the first dimension of the array a.

$m_L$, the number of general linear constraints.

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

Output Parameters

1:     $\mathrm{istate}\left(\mathbf{n}+\mathbf{nclin}\right)$ – int64int32nag_int array

The status of the constraints in the working set at the point returned in x. The significance of each possible value of $\mathbf{istate}\left(j\right)$ is as follows:

$\mathbf{istate}\left(j\right)$	Meaning
$-2$	The constraint violates its lower bound by more than the feasibility tolerance.
$-1$	The constraint violates its upper bound by more than the feasibility tolerance.
$\phantom{-}0$	The constraint is satisfied to within the feasibility tolerance, but is not in the working set.
$\phantom{-}1$	This inequality constraint is included in the working set at its lower bound.
$\phantom{-}2$	This inequality constraint is included in the working set at its upper bound.
$\phantom{-}3$	This constraint is included in the working set as an equality. This value of istate can occur only when $\mathbf{bl}\left(j\right)=\mathbf{bu}\left(j\right)$.
$\phantom{-}4$	This corresponds to optimality being declared with $\mathbf{x}\left(j\right)$ being temporarily fixed at its current value. This value of istate can occur only when $\mathbf{ifail}=\mathbf{1}$ on exit.

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

The point at which nag_opt_lp_solve (e04mf) terminated. If $\mathbf{ifail}=\mathbf{0}$, $\mathbf{1}$ or $\mathbf{4}$, x contains an estimate of the solution.

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

The total number of iterations performed.

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

The value of the objective function at $x$ if $x$ is feasible, or the sum of infeasibiliites at $x$ otherwise. If the problem is of type FP and $x$ is feasible, obj is set to zero.

5:     $\mathrm{ax}\left(\max \left(1,\mathbf{nclin}\right)\right)$ – double array

The final values of the linear constraints $Ax$.

If $\mathbf{nclin}=0$, ax is not referenced.

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

The values of the Lagrange multipliers for each constraint with respect to the current working set. The first $n$ elements contain the multipliers for the bound constraints on the variables, and the next $m_L$ elements contain the multipliers for the general linear constraints (if any). If $\mathbf{istate}\left(j\right)=0$ (i.e., constraint $j$ is not in the working set), $\mathbf{clamda}\left(j\right)$ is zero. If $x$ is optimal, $\mathbf{clamda}\left(j\right)$ should be non-negative if $\mathbf{istate}\left(j\right)=1$, non-positive if $\mathbf{istate}\left(j\right)=2$ and zero if $\mathbf{istate}\left(j\right)=4$.

7:     $\mathrm{lwsav}\left(120\right)$ – logical array

8:     $\mathrm{iwsav}\left(610\right)$ – int64int32nag_int array

9:     $\mathrm{rwsav}\left(475\right)$ – double array

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

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

nag_opt_lp_solve (e04mf) returns with $\mathbf{ifail}=\mathbf{0}$ if $x$ is a strong local minimizer, i.e., the reduced gradient (Norm Gz; see Printed Output) is negligible and the Lagrange multipliers (Lagr Mult; see Printed Output) are optimal.

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.

W  $\mathbf{ifail}=1$

$x$ is a weak local minimum (the projected gradient is negligible and the Lagrange multipliers are optimal but there is a small multiplier). This means that the solution is not unique.

W  $\mathbf{ifail}=2$

The solution appears to be unbounded, i.e., the objective function is not bounded below in the feasible region. This value of ifail occurs if a step larger than Infinite Step Size ($\text{default value}={10}^{20}$) would have to be taken in order to continue the algorithm, or the next step would result in an element of $x$ having magnitude larger than optional parameter Infinite Bound Size ($\text{default value}={10}^{20}$).

W  $\mathbf{ifail}=3$

No feasible point was found, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance. In this case, the constraint violations at the final $x$ will reveal a value of the tolerance for which a feasible point will exist – for example, when the feasibility tolerance for each violated constraint exceeds its Slack (see Printed Output) at the final point. The modified problem (with an altered feasibility tolerance) may then be solved using a Warm Start. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to the absolute precision $\sigma$, you should ensure that the value of the optional parameter Feasibility Tolerance ($\text{default value}=\sqrt{\epsilon }$, where $\epsilon$ is the machine precision) is greater than $\sigma$. For example, if all elements of $A$ are of order unity and are accurate only to three decimal places, the Feasibility Tolerance should be at least ${10}^{-3}$.

   $\mathbf{ifail}=4$

The limiting number of iterations was reached before normal termination occurred.

The value of the optional parameter Iteration Limit ($\text{default value}=\max \left(50,5\left(n+m_L\right)\right)$) may be too small. If the method appears to be making progress (e.g., the objective function is being satisfactorily reduced), either rerun nag_opt_lp_solve (e04mf) with a larger value of Iteration Limit or, alternatively, rerun nag_opt_lp_solve (e04mf) using the Warm Start facility to specify the initial working set.

   $\mathbf{ifail}=5$

Not used by this function.

   $\mathbf{ifail}=6$

An input argument is invalid.

   $\mathbf{ifail}=7$

The designated problem type was not FP or LP. Rerun nag_opt_lp_solve (e04mf) with the optional parameter Problem Type set to one of these values.

   $\mathbf{\text{Overflow}}$

If the printed output before the overflow error contains a warning about serious ill-conditioning in the working set when adding the $j$th constraint, it may be possible to avoid the difficulty by increasing the magnitude of the Feasibility Tolerance ($\text{default value}=\sqrt{\epsilon }$, where $\epsilon$ is the machine precision) and rerunning the program. If the message recurs even after this change, the offending linearly dependent constraint (with index ‘$j$’) must be removed from the problem.

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

Scaling

Description of the Printed Output

Example

Open in the MATLAB editor: e04mf_example

function e04mf_example


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

a = [1,    1,    1,    1,    1,    1,    1;
     0.15, 0.04, 0.02, 0.04, 0.02, 0.01, 0.03;
     0.03, 0.05, 0.08, 0.02, 0.06, 0.01, 0;
     0.02, 0.04, 0.01, 0.02, 0.02, 0,    0;
     0.02, 0.03, 0,    0,    0.01, 0,    0;
     0.7,  0.75, 0.8,  0.75, 0.8,  0.97, 0;
     0.02, 0.06, 0.08, 0.12, 0.02, 0.01, 0.97];
bl = [-0.01;-0.1;   -0.01;  -0.04;  -0.1;   -0.01;  -0.01;
      -0.13;-1e25;  -1e25;  -1e25;  -1e25;  -0.0992;-0.003];
bu = [ 0.01; 0.15;   0.03;   0.02;   0.05;   1e25;   1e25;
      -0.13;-0.0049;-0.0064;-0.0037;-0.0012; 1e25;   0.002];
cvec = [-0.02; -0.2;-0.2;   -0.2;   -0.2;    0.04;   0.04];
istate = zeros(14, 1, 'int64');

x  = [-0.01; -0.03;  0;     -0.01;  -0.1;    0.02;   0.01];

% Initialize and set options
[cwsav,lwsav,iwsav,rwsav,ifail] = e04wb('e04mf');
[lwsav, iwsav, rwsav, inform] = ...
    e04mh('Nolist', lwsav, iwsav, rwsav);
[lwsav, iwsav, rwsav, inform] = ...
    e04mh('Print Level = -1', lwsav, iwsav, rwsav);

[istate, x, iter, obj, ax, clamda, lwsav, iwsav, rwsav, ifail] = ...
    e04mf(...
          a, bl, bu, cvec, istate, x, lwsav, iwsav, rwsav);
fprintf('Minimum value     :  %9.4f\n\n',obj);
fprintf('Found after %3d iterations at x:\n   ',iter);
fprintf(' %9.4f',x);
fprintf('\nLinear contrained values Ax:\n   ');
fprintf(' %9.4f',ax);
fprintf('\n');

e04mf example results

Minimum value     :     0.0236

Found after   7 iterations at x:
      -0.0100   -0.1000    0.0300    0.0200   -0.0675   -0.0023   -0.0002
Linear contrained values Ax:
      -0.1300   -0.0055   -0.0066   -0.0048   -0.0039   -0.0992   -0.0030

Algorithmic Details

Overview

Definition of Search Direction

Main Iteration

Choosing the Initial Working Set

Optional Parameters

• Check Frequency
• Cold Start
• Crash Tolerance
• Defaults
• Expand Frequency
• Feasibility Tolerance
• Infinite Bound Size
• Infinite Step Size
• Iteration Limit
• Iters
• Itns
• List
• Minimum Sum of Infeasibilities
• Monitoring File
• Nolist
• Optimality Tolerance
• Print Level
• Problem Type
• Warm Start

[lwsav, iwsav, rwsav, inform] = e04mh('Print Level = 5', lwsav, iwsav, rwsav);

Description of the Optional Parameters

• the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
• a parameter value, where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
• the default value, where the symbol $\epsilon$ is a generic notation for machine precision (see nag_machine_precision (x02aj)).

Description of Monitoring Information