NAG Library Routine Document
h02buf
(ilp_mpsx_convert)
1
Purpose
h02buf reads data for a linear or integer programming problem from an external file which is in standard or compatible MPSX input format.
2
Specification
Fortran Interface
Subroutine h02buf ( 
infile,
maxn,
maxm,
optim,
xbldef,
xbudef,
nmobj,
nmrhs,
nmrng,
nmbnd,
mpslst,
n,
m,
a,
bl,
bu,
cvec,
x,
intvar,
crname,
nmprob,
iwork,
ifail) 
Integer, Intent (In)  :: 
infile,
maxn,
maxm  Integer, Intent (Inout)  :: 
ifail  Integer, Intent (Out)  :: 
n,
m,
intvar(maxn),
iwork(maxn+maxm)  Real (Kind=nag_wp), Intent (In)  :: 
xbldef,
xbudef  Real (Kind=nag_wp), Intent (Out)  :: 
a(maxm,maxn),
bl(maxn+maxm),
bu(maxn+maxm),
cvec(maxn),
x(maxn)  Logical, Intent (In)  :: 
mpslst  Character (3), Intent (In)  :: 
optim  Character (8), Intent (Inout)  :: 
nmobj,
nmrhs,
nmrng,
nmbnd  Character (8), Intent (Out)  :: 
crname(maxn+maxm),
nmprob 

C Header Interface
#include nagmk26.h
void 
h02buf_ (
const Integer *infile,
const Integer *maxn,
const Integer *maxm,
const char *optim,
const double *xbldef,
const double *xbudef,
char *nmobj,
char *nmrhs,
char *nmrng,
char *nmbnd,
const logical *mpslst,
Integer *n,
Integer *m,
double a[],
double bl[],
double bu[],
double cvec[],
double x[],
Integer intvar[],
char crname[],
char *nmprob,
Integer iwork[],
Integer *ifail,
const Charlen length_optim,
const Charlen length_nmobj,
const Charlen length_nmrhs,
const Charlen length_nmrng,
const Charlen length_nmbnd,
const Charlen length_crname,
const Charlen length_nmprob) 

3
Description
h02buf reads linear programming (LP) or integer programming (IP) problem data from an external file which is prepared in standard or compatible MPSX (see
IBM (1971)) input format and then initializes
$n$ (the number of variables),
$m$ (the number of general linear constraints), the vectors
$c$,
$l$ and
$u$ and the
$m$ by
$n$ matrix
$A$ for use with
e04mff/e04mfa or
h02bbf, which are designed to solve problems of the form
h02buf may be followed by calls to either
e04mff/e04mfa (to solve an LP problem) or
h02bbf and
h02bzf (to solve an IP problem), possibly followed by a call to
h02bvf (to print the solution using MPSX names).
Note that
h02buf uses an ‘infinite’ bound size of
${10}^{20}$ in the definition of
$l$ and
$u$. In other words, any element of
$u$ greater than or equal to
${10}^{20}$ will be regarded as
$+\infty $ (and similarly any element of
$l$ less than or equal to
${10}^{20}$ will be regarded as
$\infty $). If this value is deemed to be ‘inappropriate’, you are recommended to reset the value of either the optional parameter
Infinite Bound Size (if an LP problem is being solved) or the argument BIGBND (if an IP problem is being solved) and make any necessary changes to
bl and/or
bu prior to calling
e04mff/e04mfa or
h02bbf (as appropriate).
The documents for
e04mff/e04mfa,
h02bvf and/or
h02bbf and
h02bzf should be consulted for further details.
MPSX input format
The input file of data may only contain two types of lines.
1. 
Indicator lines (specifying the type of data which is to follow). 
2. 
Data lines (specifying the actual data). 
The input file must not contain any blank lines. Any characters beyond column 80 are ignored. Indicator lines must not contain leading blank characters (in other words they must begin in column 1). The following displays the order in which the indicator lines must appear in the file:
NAME 
usergiven name 
ROWS 
data line(s) 
COLUMNS 
data line(s) 
RHS 
data line(s) 
RANGES (optional) 
data line(s) 
BOUNDS (optional) 
data line(s) 
ENDATA 

The ‘usergiven name’ specifies a name for the problem and must occupy columns 15–22. The name can either be blank or up to a maximum of $8$ characters.
A data line follows the same fixed format made up of fields defined below. The contents of the fields may have different significance depending upon the section of data in which they appear.


Field 1 
Field 2 
Field 3 
Field 4 
Field 5 
Field 6 
Columns 
$2\u20133$ 
$5\u201312$ 
$15\u201322$ 
$25\u201336$ 
$40\u201347$ 
$50\u201361$ 
Contents 
Code 
Name 
Name 
Value 
Name 
Value 
The names and codes consist of ‘alphanumeric’ characters (i.e., a–z, A–Z,
$0$–9,
$+$,
$$, asterisk (*), blank ( ), colon (:), dollar sign ($) or fullstop (.) only) and the names must not contain leading blank characters. Values are read using Fortran format E12.0. This allows values to be entered in several equivalent forms. For example,
$1.2345678$,
$1.2345678E+0$,
$\text{123.45678E\u22122}$ and
$\text{12345678E\u221207}$ all represent the same number. It is safest to include an explicit decimal point.
Note that in order to ensure numeric values are interpreted as intended, they should be
rightjustified in the
$12$character field, with no trailing blanks. This is because in some situations trailing blanks may be interpreted as zeros and this can dramatically affect the interpretation of the value. This is relevant if the value contains an exponent, or if it contains neither an exponent nor an explicit decimal point. For example, the fields
%%%%1.23E2%
%%%%%%%123%%
may be interpreted as
$\text{1.23E\u221220}$ and
$12300$ respectively (where
% is used to denote a blank). The actual behaviour is systemdependent.
Comment lines are allowed in the data file. These must have an asterisk (*) in column 1 and any characters in columns 2–80. In any data line, a dollar sign ($) as the first character in Field 3 or 5 indicates that the information from that point through column 80 consists of comments.
Columns outside the six fields must be blank, except for columns 72–80, whose contents are ignored by the routine. These columns may be used to enter a sequence number. A nonblank character outside the predefined six fields and columns 72–80 is considered to be a major error (
${\mathbf{ifail}}={\mathbf{11}}$; see
Section 6), unless it is part of a comment.
ROWS data line(s)
These lines specify row (constraint) names and their inequality types (i.e.,
$=$,
$\ge $ or
$\le $).
Field 1: 
defines the constraint type. It may be in column 2 or column 3. 
N 
free row, that is no constraint. It may be used to define the objective row. 
G 
greater than or equal to (i.e., $\ge $). 
L 
less than or equal to (i.e., $\le $). 
E 
exactly equal to (i.e., $=$). 
Field 2: 
defines the row name. 
Row type
N stands for ‘Not binding’, also known as ‘Free’. It can be used to define the objective row. The objective row is a free row that specifies the vector
$c$ in the objective function. It is taken to be the first free row, unless some other free row name is specified by the argument
nmobj (see
Section 5). Note that the objective function must be included in the MPSX data file. Thus the maximum number of constraints (
maxm; see
Section 5) in the problem must be
$m+1$.
COLUMNS data line(s)
These lines specify the names to be assigned to the variables (columns) in the constraint matrix
$A$, and define, in terms of column vectors, the actual values of the corresponding matrix elements.

Field 1: blank (ignored) 

Field 2: gives the name of the column associated with the elements specified in the following fields. 

Field 3: contains the name of a row. 

Field 4: used in conjunction with Field 3 contains the value of the matrix element. 

Field 5: is optional (may be used like Field 3). 

Field 6: is optional (may be used like Field 4). 
Note that only nonzero elements of $A$ need to be specified in the COLUMNS section, as any unspecified elements are assumed to be zero.
RHS data line(s)
This section specifies the righthand side values of the constraint matrix $A$. The lines specify the name of the RHS (righthand side) vector given to the problem, the numerical values of the elements of the vector are also defined by the data lines and may appear in any order. The data lines have exactly the same format as the COLUMNS data lines, except that the column name is replaced by the RHS name. Note that any unspecified elements are assumed to be zero.
RANGES data line(s) (optional)
Ranges are used for constraints of the form $l\le Ax\le u$, where $l$ and $u$ are finite. The range of the constraint is $r=ul$. Either $l$ or $u$ must be specified in the RHS section and $r$ must be defined in this section.
The data lines have exactly the same format as the COLUMNS data lines, except that the column name is replaced by the RANGES name.
BOUNDS data line(s) (optional)
These lines specify limits on the values of the variables (
$l$ and
$u$ in
$l\le x\le u$). If the variable is not specified in the bound set then it is automatically assumed to lie between default lower and upper bounds (usually
$0$ and
$+\infty $). Like an RHS column which is given a name, the set of variables in one bound set is also given a name.
Field 1: 
specifies the type of bound or defines the variable type. 
LO 
lower bound 
UP 
upper bound 
FX 
fixed variable 
FR 
free variable ($\infty $ to $+\infty $) 
MI 
lower bound is $\infty $ 
PL 
upper bound is $+\infty $. This is the default variable type. 
Field 2: 
identifies a name for the bound set. 
Field 3: 
identifies the column name of the variable belonging to this set. 
Field 4: 
identifies the value of the bound; this has a numerical value only in association with LO, UP, FX in Field 1, otherwise it is blank. 
Field 5: 
is blank and ignored. 
Field 6: 
is blank and ignored. 
Note that if RANGES and BOUNDS sections are both present, the RANGES section must appear first.
Integer Problems
In IP problems there are two common integer variable types.
1. 
$0$–1 integer variables which represent ‘on’ or ‘off’ situations and 
2. 
General integer variables which are forced to take an integer value, in a specified range, at the optimal integer solution. 
Integer variables can be defined in the following compatible and standard MPSX forms.
In the compatible MPSX format, the type of integer variables is defined in Field 1 of the BOUNDS section, that is:
Field 1: 
specifies the type of the integer variable. 
BV 
$0\u20131$ integer variable (bound value is $1.0$). 
UI 
general integer variable (bound value is in Field 4). 
In the standard MPSX format, the integer variables are treated the same as the ‘ordinary’ bounded variables, in the BOUNDS section. Integer markers are, however, introduced in the COLUMNS section to specify the integer variables. The indicator lines for these markers are:


Field 1 
Field 2 
Field 3 
Field 4 
Field 5 
Field 6 
Columns 
$2\u20133$ 
$5\u201312$ 
$15\u201322$ 
$25\u201336$ 
$40\u201347$ 
$50\u201361$ 
Contents 

INTEGER 
‘MARKER’ 

‘INTORG’ 

to mark the beginning of the integer variables and


Field 1 
Field 2 
Field 3 
Field 4 
Field 5 
Field 6 
Columns 
$2\u20133$ 
$5\u201312$ 
$15\u201322$ 
$25\u201336$ 
$40\u201347$ 
$50\u201361$ 
Contents 

INTEGER 
‘MARKER’ 

‘INTEND’ 

to mark the end. That is, any variables between these markers are treated as integer variables. Note that if the (INTEND) indicator line is not specified in the file then all the variables between the (INTORG) indicator line and the end of the COLUMNS section are assumed to be integer variables. The routine accepts both standard and/or compatible MPSX format as a means of specifying integer variables. This is illustrated in
Section 10.2 in
h02bff.
4
References
IBM (1971) MPSX – Mathematical programming system Program Number 5734 XM4 IBM Trade Corporation, New York
5
Arguments
 1: $\mathbf{infile}$ – IntegerInput

On entry: the unit number associated with the MPSX data file.
Constraint:
$0\le {\mathbf{infile}}\le 99$.
 2: $\mathbf{maxn}$ – IntegerInput

On entry: an upper limit for the number of variables in the problem.
Constraint:
${\mathbf{maxn}}\ge 1$.
 3: $\mathbf{maxm}$ – IntegerInput

On entry: an upper limit for the number of constraints (including the objective) in the problem.
Constraint:
${\mathbf{maxm}}\ge 1$.
 4: $\mathbf{optim}$ – Character(3)Input

On entry: specifies the direction of the optimization.
optim must be set to 'MIN' for minimization and to 'MAX' for maximization.
Constraint:
${\mathbf{optim}}=\text{'MIN'}$ or $\text{'MAX'}$.
 5: $\mathbf{xbldef}$ – Real (Kind=nag_wp)Input

On entry: the default lower bound to be used for the variables in the problem when none is specified in the BOUNDS section of the MPSX data file. For a standard LP or IP problem
xbldef would normally be set to zero.
 6: $\mathbf{xbudef}$ – Real (Kind=nag_wp)Input

On entry: the default upper bound to be used for the variables in the problem when none is specified in the BOUNDS section of the MPSX data file. For a standard LP or IP problem
xbudef would normally be set to ‘infinity’ (i.e.,
${\mathbf{xbudef}}\ge {10}^{20}$).
Constraint:
${\mathbf{xbudef}}\ge {\mathbf{xbldef}}$.
 7: $\mathbf{nmobj}$ – Character(8)Input/Output

On entry: either the name of the objective function to be used for the optimization, or blank (in which case the first objective (free) row in the file is used).
On exit: the name of the objective row as defined in the MPSX data file.
 8: $\mathbf{nmrhs}$ – Character(8)Input/Output

On entry: either the name of the RHS set to be used for the optimization, or blank (in which case the first RHS set is used).
On exit: the name of the RHS set read in the MPSX data file.
 9: $\mathbf{nmrng}$ – Character(8)Input/Output

On entry: either the name of the RANGE set to be used for the optimization, or blank (in which case the first RANGE set (if any) is used).
On exit: the name of the RANGE set read in the MPSX data file. This is blank if the MPSX data file does not have a RANGE set.
 10: $\mathbf{nmbnd}$ – Character(8)Input/Output

On entry: either the name of the BOUNDS set to be used for the optimization, or blank (in which case the first BOUNDS set (if any) is used).
On exit: the name of the BOUNDS set read in the MPSX data file. This is blank if the MPSX data file does not have a BOUNDS set.
 11: $\mathbf{mpslst}$ – LogicalInput

On entry: if
${\mathbf{mpslst}}=\mathrm{.TRUE.}$, then a listing of the input data is sent to the current advisory message unit (as defined by
x04abf). This can be useful for debugging the MPSX data file.
 12: $\mathbf{n}$ – IntegerOutput

On exit: $n$, the actual number of variables in the problem.
 13: $\mathbf{m}$ – IntegerOutput

On exit: $m$, the actual number of general linear constraints in the problem.
 14: $\mathbf{a}\left({\mathbf{maxm}},{\mathbf{maxn}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: $A$, the matrix of general linear constraints.
 15: $\mathbf{bl}\left({\mathbf{maxn}}+{\mathbf{maxm}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit:
$l$, the lower bounds for all the variables and constraints in the following order. The first
n elements of
bl contain the bounds on the variables and the next
m elements contain the bounds for the general linear constraints (if any). Note that an ‘infinite’ lower bound is indicated by
${\mathbf{bl}}\left(j\right)=\text{1.0E+20}$ and an equality constraint by
${\mathbf{bl}}\left(j\right)={\mathbf{bu}}\left(j\right)$.
 16: $\mathbf{bu}\left({\mathbf{maxn}}+{\mathbf{maxm}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit:
$u$, the upper bounds for all the variables and constraints in the following order. The first
n elements of
bu contain the bounds on the variables and the next
m elements contain the bounds for the general linear constraints (if any). Note that an ‘infinite’ upper bound is indicated by
${\mathbf{bu}}\left(j\right)=\text{1.0E+20}$ and an equality constraint by
${\mathbf{bu}}\left(j\right)={\mathbf{bl}}\left(j\right)$.
 17: $\mathbf{cvec}\left({\mathbf{maxn}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit:
$c$, the coefficients of the objective function. The signs of these coefficients are determined by the problem (either LP or IP) and the direction of the optimization (see
optim above).
 18: $\mathbf{x}\left({\mathbf{maxn}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: an initial estimate of the solution to the problem. More precisely,
${\mathbf{x}}\left(\mathit{j}\right)=1.0$ if $\mathit{j}$ is odd and $0.0$ otherwise, for $\mathit{j}=1,2,\dots ,{\mathbf{n}}$.
 19: $\mathbf{intvar}\left({\mathbf{maxn}}\right)$ – Integer arrayOutput

On exit: indicates which are the integer variables in the problem. More precisely,
${\mathbf{intvar}}\left(\mathit{k}\right)=1$ if ${x}_{\mathit{k}}$ is an integer variable, and $0$ otherwise, for $\mathit{k}=1,2,\dots ,{\mathbf{n}}$.
 20: $\mathbf{crname}\left({\mathbf{maxn}}+{\mathbf{maxm}}\right)$ – Character(8) arrayOutput

On exit: the MPSX names of all the variables and constraints in the problem in the following order. The first
n elements contain the MPSX names for the variables and the next
m elements contain the MPSX names for the general linear constraints (if any).
 21: $\mathbf{nmprob}$ – Character(8)Output

On exit: the name of the problem as defined in the MPSX data file.
 22: $\mathbf{iwork}\left({\mathbf{maxn}}+{\mathbf{maxm}}\right)$ – Integer arrayWorkspace

 23: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation 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, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{ 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
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}={\mathbf{3}}$ to
${\mathbf{ifail}}={\mathbf{15}}$ (apart from
${\mathbf{ifail}}={\mathbf{14}}$) are caused by having either a corrupt or a nonstandard MPSX data file. Refer to
Section 3 for a detailed description of the MPSX format which can be read by
h02buf. If
${\mathbf{mpslst}}=\mathrm{.TRUE.}$, the last line of printed output refers to the line in the MPSX data file which contains the reported error.
 ${\mathbf{ifail}}=1$

There are too many rows present in the data file. Increase
maxm by at least (
${\mathbf{m}}{\mathbf{maxm}}$) and rerun
h02buf.
 ${\mathbf{ifail}}=2$

There are too many columns present in the data file. Increase
maxn by at least (
${\mathbf{n}}{\mathbf{maxn}}$) and rerun
h02buf.
 ${\mathbf{ifail}}=3$

The objective function row was not found. There must be at least one row in the ROWS section with row type
n for the objective row.
 ${\mathbf{ifail}}=4$

There are no rows specified in the ROWS section.
 ${\mathbf{ifail}}=5$

An illegal constraint type was detected in the ROWS section. The constraint type must be one of N, L, G or E.
 ${\mathbf{ifail}}=6$

An illegal row name was detected in the ROWS section. Names must be made up of alphanumeric characters with no leading blanks.
 ${\mathbf{ifail}}=7$

An illegal column name was detected in the COLUMNS section. Names must be made up of alphanumeric characters with no leading blanks.
 ${\mathbf{ifail}}=8$

An illegal bound type was detected in the BOUNDS section. The bound type must be one of LO, UP, FX, FR, MI, PL, BV or UI.
 ${\mathbf{ifail}}=9$

An unknown column name was detected in the BOUNDS section. All the column names must be specified in the COLUMNS section.
 ${\mathbf{ifail}}=10$

The last line in the file does not contain the ENDATA line indicator.
 ${\mathbf{ifail}}=11$

An illegal data line was detected in the file. This line is neither a comment line nor a valid data line.
 ${\mathbf{ifail}}=12$

An unknown row name was detected in COLUMNS or RHS or RANGES section. All the row names must be specified in the ROWS section.
 ${\mathbf{ifail}}=13$

There were no columns specified in the COLUMNS section.
 ${\mathbf{ifail}}=14$

An input argument is invalid.
 ${\mathbf{ifail}}=15$

Incorrect integer marker. In standard MPSX data format, integer variables should be defined between INTORG and INTEND markers.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
Not applicable.
8
Parallelism and Performance
h02buf is not threaded in any implementation.
None.
10
Example
This example solves the same problem as the example for
h02bff, except that it treats it as an LP problem.
One of the applications of linear programming is to the socalled diet problem. Given the nutritional content of a selection of foods, the cost of each food, the amount available of each food and the consumer's minimum daily nutritonal requirements, the problem is to find the cheapest combination. This gives rise to the following problem:
minimize
subject to
where
and
The rows of $A$ correspond to energy, protein and calcium and the columns of $A$ correspond to oatmeal, chicken, eggs, milk, pie and bacon respectively.
The MPSX representation of the problem is given in
Section 10.2.
10.1
Program Text
Program Text (h02bufe.f90)
10.2
Program Data
Program Options (h02bufe.opt)
10.3
Program Results
Program Results (h02bufe.r)