Passing Your Model Using Mathematical Programming System (MPS) Format


Using MPS Format


     Types of Records | Order of Records | Fixed Format | Free Format

If you are already familiar with MPS format, you may want to refer to "Optimization Library Compatibility with MPS Format" for additional information.  If you have never used MPS format and would like to use it with the Optimization Library, the following sections should help you understand it. These sections present MPS format as it is accepted by library modules. For more details on MPS format, see the Mathematical Programming System Extended/370 (MPSX/370) Program Reference Manual. Examples of MPS data files are located in "Sample MPS Input Files".

Notes:

In the following sections, a record or a card refers to a single line of input or output in an MPS file. The terms are used interchangeably. In all examples in this chapter, a header line is placed above the data to illustrate the positioning of the various fields. Although this header is a comment and may be part of an MPS file, it is not included in any sample data that is on the product tape or diskettes.

Types of Records

There are two principal types of records in an MPS file: indicator records and data records. Indicator records specify the type of data that follows. Generally, they consist of only one word. All indicator records must begin in column 1.

Data records contain the actual data values for the model. They are divided into the following fields:

Field 1: Indicator code
Field 2: Name
Field 3: Name
Field 4: Value
Field 5: Name
Field 6: Value

Not all fields will be used in a particular data record.

In data records:

You can insert a comment record, denoted by an asterisk (*) in column 1, anywhere in an MPS file. Also, if a dollar sign is the first character in field 3 or field 5 of any record, the information from that point to the end of the record is treated as a comment. All comment records are ignored.

Order of Records

The following is the order of records in an MPS file that defines the linear part of a model:

Also, the coefficients for the objective function and, if desired, the objective function change vector for LP parametrics, are defined in a similar manner.

A section is the indicator record followed by the associated data records. For example, the ROWS section consists of the ROWS indicator record followed by the data records that define the rows.

The RHS, RANGES, and BOUNDS sections are optional.

An MPS data file may contain information for several models. In this case, the NAME indicator record for another model should follow the ENDATA indicator record for the previous model.

The order of records in an MPS file that defines the quadratic part of a model is provided in "QSECTION Section". The order of records in an MPS file that defines a basis for a model is provided in "Optimization Library Compatibility with MPS Format".

Fixed Format Input

MPS files can be read and printed in both fixed and free format. In fixed format, each field of a data record must occur in a predefined position. If the integer control variable Inumchar is equal to the default value of 8, each field of a data record is in the following position:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Columns 2-3 

Columns 5-12 

Columns 15-22 

Columns 25-36 

Columns 40-47 

Columns 50-61 

 
If Inumchar is not equal to 8, each field of a data record is in the following position:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Starting column 

The third column after the last character of field 2 

The third column after the last character of field 3 

The third column after the last character of field 4 

The third column after the last character of field 5 

Ending column 

5 + Inumchar-1 

Starting column + Inumchar-1 

Starting column + 11 

Starting column + Inumchar-1 

Starting column + 11 

 
If Inumchar 12, only four fields may occur in a data record.

The names in fields 2, 3, and 5 should not contain embedded blanks. If they do, them will be removed. Regardless of the value of Inumchar, all numeric values appearing in fields 4 and 6 must be defined in a 12-character field. Columns outside the six fields must be blank, except for columns 72-80, whose contents are ignored.

Free Format Input

In free format, fields in data records have no predefined positions. They may be written anywhere except column 1, with each field separated from the next by one or more blanks. However, they must appear in the same sequence as in fixed format:


NAME and ENDATA Records

The following describes the format of NAME and ENDATA records and provides some examples.

NAME Indicator Record Format

The NAME indicator record has the following form:
 

Field 1 

Field 2 

Field 3 

Field 4 

NAME 

Blank 

Input model name 

BINARY, FREE, or blank 

 

Fixed Format

If you are using fixed format, you may use BINARY as a value for field 4 when the data values are written in binary format. Otherwise, this field should be blank.

Free Format

If you are using free format, you must use FREE as a value for field 4.

ENDATA Indicator Record Format

In fixed or free format, the ENDATA indicator record has the following form:
 

Columns 1-7 

ENDATA 

Examples

If Inumchar eq 8, the following is a sample NAME indicator record in fixed format:

*23456789012345678901234567890
NAME          EXAMPLE

The following is a sample NAME indicator record in fixed format, with Inumchar eq 8, for an input file that has values written in binary format:

*23456789012345678901234567890
NAME          EXAMPLE   BINARY

If Inumchar eq 7, the following are sample NAME indicator records in free format:

*23456789012345678901234567890
NAME          EXAMPLE FREE
*23456789012345678901234567890
NAME EXAMPLE             FREE


ROWS Section

Data records in the ROWS section specify the name to be assigned to each row of the model, as well as the type of constraint represented by the row. The name of the objective function is also defined in this section, even though it is not a row in the model.

Indicator Record

In fixed or free format, the ROWS indicator record has the following form:
 

Columns 1-4 

ROWS 

Data Record

The data records in the ROWS section have the following form:
 

Field 1 

Field 2 

Indicator code (see below) 

Name of row 

 
Field 1 must be in columns 2-3 for fixed and free format. Field 2 must be separated from field 1 by at least one blank.

Indicator Code

In a data record, the indicator code defines the type of row as follows, where b represents one blank character:

 

Note:

The indicator code Dx and the 'SCALE' marker are not supported. 

 
Normally, the first type-N row encountered will be used as the objective function and all other type-N rows will be discarded. You can explicitly designate an objective function by setting character control variable Cobjective to the name of the objective function before calling EKKMPS. Also, if you are using an objective function parametric change vector, you must set character control variable Cchangeobj before calling EKKMPS. The type-N row with field 2 equal to Cchangeobj will be used as the objective function parametric change vector.

Integer control variable Ioneobj will control the number of type-N rows that are discarded. This control variable does not affect the objective function parametric change row.

Example

If Inumchar 5, the following is a sample ROWS section in fixed format:

*23456789012345678901234567890
ROWS
 N  OBJ
 N  CHGOBJ
 G  ROW01
 L  ROW02
 E  ROW03
 G  ROW04
 L  ROW05

In this example, OBJ is the objective row, ROW01 and ROW04 are rows representing a greater than or equal to constraint, ROW02 and ROW05 are rows representing a less than or equal to constraint, and ROW03 represents an equality constraint. If LP parametrics are used and Cchangeobj is set to CHGOBJ, CHGOBJ is the name of the objective function change vector. 


COLUMNS Section

Data records in the COLUMNS section specify the names to be assigned to each column (structural variable) in the model and define, in column order, the coefficients of the model. The use of special markers in the COLUMNS section allows you to define sets of integer variables. See "Integer Data" for a description of these markers.

In addition, data records in this section define the coefficients of the objective function and, if desired, the values in the objective function change vector for LP parametrics.

Indicator Record

In fixed or free format, the COLUMNS indicator record has the following form:
 

Columns 1-7 

COLUMNS 

Data Record

The data record in the COLUMNS section has the following form:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Blank 

Column name 

First row name 

Matrix element in first row, this column 

Second row name 

Matrix element in second row, this column 

 

Because it is assumed that a coefficient that is not specified as described above is zero, there is no need to define zero coefficients. However, if a zero coefficient is defined, I/O processing continues normally.

Notes:

  1. The 'SCALE' marker in field 3 is not supported.
  2. If the absolute value of a coefficient is less than the real control variable Rtolmps, the coefficient is set to zero.
  3. Slacks or logical variables are automatically entered. You are not required to enter them with your model data. The variable is given the name of the row in which it appears.
  4. Although it is not recommended, any column may be given the same name as any row.

Examples

If Inumchar eq 8, the following is a sample COLUMNS section in fixed format:

*234567890123456789012345678901234567890123456789012345678901234567890
COLUMNS
    COL01     OBJ                1.0
    COL01     ROW01              3.0   ROW05              5.6
    COL01     CHGOBJ             0.9
    COL02     ROW01              1.0   ROW02              2.0
    COL02     CHGOBJ            -1.5
    COL03     ROW02              1.1   ROW03              1.0
    COL04     ROW01             -2.0   ROW04              2.8
    COL05     OBJ                2.0
    COL05     ROW01             -1.0   ROW05              1.0
    COL06     ROW03              1.0
    COL07     ROW04             -1.2
    COL08     OBJ               -1.0
    COL08     ROW01             -1.0   ROW05              1.9

In this example, the first column has the name COL01 and has the coefficient 1.0 in the objective function, coefficient 3.0 in the constraint with the name ROW01 and coefficient 5.6 in the constraint with the name ROW05. If LP parametrics are used, the objective function coefficient for the first column will have 0.9 times the value of Rslambda added to it during LP parametrics processing. The third record in this section may have had a blank second field and still be equivalent.

If Inumchar eq 5, the following is a sample COLUMNS section in fixed format:

*234567890123456789012345678901234567890123456789012345678901234567890
COLUMNS
    COL01 OBJ            1.0
    COL01 ROW01          3.0 ROW05          5.6
    COL02 ROW01          1.0 ROW02          2.0
    COL03 ROW02          1.1 ROW03          1.0
    COL04 ROW01         -2.0 ROW04          2.8
    COL05 OBJ            2.0
    COL05 ROW01         -1.0 ROW05          1.0
    COL06 ROW03          1.0
    COL07 ROW04         -1.2
    COL08 OBJ           -1.0
    COL08 ROW01         -1.0 ROW05          1.9


RHS Section

Data records in the RHS section specify the names and values of the right-hand side constraint vectors. You can specify multiple sets of right-hand side vectors in the MPS file, but only the one you designate will be used.

Indicator Record

In fixed or free format, the RHS indicator record has the following form:
 

Columns 1-3 

RHS 

 
or
 

Columns 1-4 

RHS' 

Data Record

The data record in the RHS section has the following form:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Blank 

RHS name 

First row name 

RHS value for first row 

Second row name 

RHS value for second row 

 

 

Note:

If the absolute value of an element of an RHS vector is less than or equal to the real control variable Rtolmps, that element is set to 0. If the absolute value of an element of an RHS vector is greater than 10 sup 31, the row for which it is defined is treated as unbounded. 

Example

If Inumchar eq 8, the following is a sample RHS section in fixed format:

*234567890123456789012345678901234567890123456789012345678901234567890
RHS
    RHS1      ROW01              2.5
    RHS1      ROW02              2.1
    CHGRHS    ROW04              2.0
    RHS1      ROW03              4.0
    RHS1      ROW04              1.8
    RHS1      ROW05             15.0

In this example, the RHS value for the row named ROW01 indicates that constraint row must have a value that is greater than or equal to 2.5, because ROW01 was defined as a type-G row in the ROWS section. If LP parametrics are used and Cchangerhs is set to CHGRHS, CHGRHS is the name of the right-hand side change vector. In this example, the RHS value for the row named ROW04 will have 2.0 times the value of Rslambda added to it during LP parametrics processing. 


RANGES Section

Data records in the RANGES section specify the names and values of range vectors. Range vectors allow rows to be constrained from above and below, thus allowing a single row to function as a type-L and a type-G row. You can specify multiple sets of range vectors in the MPS file, but uses only the one you designate will be used.

Indicator Record

In fixed or free format, the RANGES indicator record has the following form:
 

Columns 1-6 

RANGES 

Data Record

The data record in the RANGES section has the following form:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Blank 

RANGES name 

First row name 

Range for RHS of first row 

Second row name 

Range for RHS of second row 

 

Effect of Range Value on the RHS

If b(i) is the value given in the RHS section for a row, the range r(i) sets the following limits on the row activity:
 

Type of Row

Sign of r(i)

Resultant Upper Limit 

Resultant Lower Limit 

b(i) + r(i) 

b(i) 

b(i) 

b(i) - r(i) 

b(i) + r(i) 

b(i) 

b(i) 

b(i) + r(i) 

 
If r(i) is specified as a negative value for a G or an L row, the negative sign is ignored and the absolute value is used.
 

Note:

If the absolute value of a RANGES entry is less than or equal to real control variable Rtolmps, that entry is set to 0. If the absolute value of a RANGES entry is greater than 10 sup 31, the value is treated as unbounded. 

Example

If Inumchar eq 8, the following is a sample RANGES section in fixed format:

*234567890123456789012345678901234567890123456789012345678901234567890
RANGES
    RNG1      ROW04              3.2
    RNG1      ROW05             12.0
    CHGRNG    ROW04              2.5

In this example, the RANGE value for the row named ROW04 indicates that the constraint row must have a value that is greater than 1.8 and less than 5.0, because ROW04 was defined as a type-G row in the ROWS section and was given an RHS of 1.8 in the RHS section. If LP parametrics are used and Cchangerange is set to CHGRNG, CHGRNG is the name of the ranges change vector. In this example, the RANGE value for the row named ROW04 will have 2.5 times the value of Rslambda added to it during LP parametrics processing. 


BOUNDS Section

Data records in the BOUNDS section specify the names and values of the bound vectors, which impose limits on the values the columns (structural variables) may assume. You can specify multiple sets of bound vectors in the MPS file, but only the one you designate will be used.

Indicator Record

In fixed or free format, the BOUNDS indicator record has the following form:
 

Columns 1-6 

BOUNDS 

Data Record

The data record in the BOUNDS section has the following form:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Type of bound (see below) 

BOUNDS name 

First column name 

Bound for first column 

Blank 

Blank 

 

Bound Types

In a data record, field 1 defines the type of bound in the following manner:

Field 1 Value
Type of Bound
LO
Lower bound
UP
Upper bound
FX
Fixed value
FR
Free variable
MI
Lower bound
PL
Upper bound

Additional bound types are supported:

Field 1 Value
Type of Bound
UI
Upper integer

This allows you to specify an upper bound for a column that is equal to the value in field 4 rounded down to the nearest integer. The integer information is only written if the intunit parameter in the call to EKKMPS is nonzero.

BV
Binary variable

This allows you to specify the bounds for a column as 0 to 1. The integer information is only written if the intunit parameter in the call to EKKMPS is nonzero. You can specify both an upper and a lower bound, a lower bound only, or an upper bound only. When a single bound is specified, the other bound is set according to the rules below. If you want to name explicit upper and lower bounds on a single column, the bounds must be entered on separate records.

Default Bounds

For non-integer variables, the default bounds on columns are 0 and + . For integer variables, the default bounds on columns are 0 and 1. (WARNING, if you want a very large bound for an integer variable, explicitly set it to 1020. DO NOT specify a value larger than 1020, or leave the value unspecified, thinking that the result will be "unbounded.") For each column specified in the BOUNDS section, the bounds are set according the the bound type in field 1 as follows:

Field 1 Value        Bounds Set
LO
The lower bound is the value in field 4 and the upper bound is +, unless the variable is an integer variable, or unless an upper bound was explicitly set with a record that has UP, PL, or UI as the value in field 1.
UP
The upper bound is the value in field 4 and the lower bound is 0, unless a lower bound was explicitly set with a record that has LO or MI as the value in field 1.
FX
The column is fixed to the value in field 4; that is, the lower and upper bounds are set to the value in field 4.
FR
The lower bound is -, and the upper bound is +.
MI
The lower bound is -, and the upper bound is +, unless an upper bound was explicitly set with a record that has UP, PL, or UI as the value in field 1.
PL
The upper bound is +, and the lower bound is 0, unless a lower bound was explicitly set with a record that has LO or MI as the value in field 1.
UI
The upper bound is the value in field 4 rounded down to the nearest integer, and the lower bound is 0, unless a lower bound was explicitly set with a record that has LO or MI as the value in field 1.
BV
The lower bound is 0 and the upper bound is 1.

If an upper bound of zero is specified while no lower bound is specified, the bounds on the variable are set as if FX had been specified.
 

Note:

If the absolute value of a BOUNDS entry is less than or equal to real control variable Rtolmps, that entry is set to 0. If the absolute value of a BOUNDS entry is greater than 10 sup 31, it is treated as being unbounded. 

Example

If Inumchar eq 8, the following is a sample BOUNDS section in fixed format:

*234567890123456789012345678901234567890123456789012345678901234567890
BOUNDS
 LO BND1      COL01              2.5
 UP BND1      COL02              4.1
 LO BND1      COL05              0.5
 LO CHGBND    COL05             -0.5
 UP BND1      COL05              4.0
 UP CHGBND    COL05              0.5
 UP BND1      COL08              4.3

In this example, the value of the column named COL05 may go no lower than 0.5 and no higher than 4.0. If LP parametrics are used and Cchangebounds is set to CHGBND, CHGBND is the name of the bounds change vector. In this example, the lower bound for the column named COL05 will have -0.5 times the value of Rslambda added to it, and the the upper bound for the column named COL05 will have 0.5 times the value of Rslambda added to it during LP parametrics processing. 


Integer Data

Structural variables that are constrained to be integers can be defined in the COLUMNS section with the use of special marker records. The order of records in the COLUMNS section for a block of integer variables is as follows:

The blocks of integer variables may occur any number of times in the COLUMNS section.
 

Note:

The use of marker records in the ROWS section to designate sets of logical integer variables is not supported. 

Indicator Records

To designate the beginning or ending of a group of integer variables, an integer variable data record should be placed in the COLUMNS section with the following form:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Blank or SOS type (see below) 

Marker name 

'MARKER' (including the quotation marks) 

Blank 

Keyword indicating type of integer variables 

Blank 

General Integer Variables

For general integer variables, the following indicates the various values you may use for the fields:

Special Ordered Set (SOS)

A special ordered set (SOS) defines restrictions on the integer variables in the set. During branch-and-bound processing, branching on these sets consists of setting all variables before a certain point in the set to zero on one branch and setting all of them after a certain point to one on the alternative branch.

Three different types of special ordered sets are recognized:

SOSORG/SOSEND markers should not be included inside INTORG/INTEND marker pairs. If a SOSORG marker is encountered inside an INTORG/INTEND pair, the result is the implicit closing of the INTORG/INTEND pair. When this occurs, warning message EKK3005W is issued, but processing of the SOS variables continues. If more regular integer variables are defined later, they are not treated as integers unless a new INTORG marker is included.

For more information on special ordered sets, see Beale and Tomlin or "Mixed-Integer Programming (EKKMPRE and EKKMSLV)".

SOS Types 1 or 2

If you are defining an SOS of type 1 or type 2, field 1 must have the following value in the record that denotes the beginning or ending of an SOS:

Field 1 Value
SOS Type Defined
S1
Type 1
S2
Type 2

You can select any name for field 2 as long as it is different from the preceding and following column names. For the beginning record, field 5 must contain the value 'SOSORG'. For the ending record, field 5 must contain the value 'SOSEND'.

SOS Type 3

If you are defining an SOS of type 3, field 1 must be blank in the record that denotes the beginning or ending of an SOS. Field 2 contains the name of an existing equality row. For the beginning record, field 5 must contain the value 'SOSORG'. For the ending record, field 5 must contain the value 'SOSEND'. The 1.0 entries and an RHS of 1.0 are inserted by default.

Examples

The following is an example of defining general integer variables:

*234567890123456789012345678901234567890123456789012345678901234567890
COLUMNS
    COL01     OBJ                1.0
    COL01     ROW01              3.0   ROW05              5.6
    COL02     ROW01              1.0   ROW02              2.0
*
*  Mark COL03 and COL04 as integer
*
    INT1      'MARKER'                 'INTORG'
    COL03     ROW02              1.1   ROW03              1.0
    COL04     ROW01             -2.0   ROW04              2.8
    INT1END   'MARKER'                 'INTEND'
*
    COL05     OBJ                2.0
    COL05     ROW01             -1.0   ROW05              1.0
    COL06     ROW03              1.0
    COL07     ROW04             -1.2
    COL08     OBJ               -1.0
    COL08     ROW01             -1.0   ROW05              1.9

Here, the columns named COL03 and COL04 must take on integer values.

The following is an example of defining a special ordered set of integer variables:

*234567890123456789012345678901234567890123456789012345678901234567890
COLUMNS
    COL01     OBJ                1.0
    COL01     ROW01              3.0   ROW05              5.6
    COL02     ROW01              1.0   ROW02              2.0
*
*  Mark COL03 and COL04 as members of SOS type 1
*
 S1 INT1      'MARKER'                 'SOSORG'
    COL03     ROW02              1.1   ROW03              1.0
    COL04     ROW01             -2.0   ROW04              2.8
 S1 INT1END   'MARKER'                 'SOSEND'
*
    COL05     OBJ                2.0
    COL05     ROW01             -1.0   ROW05              1.0
    COL06     ROW03              1.0
    COL07     ROW04             -1.2
    COL08     OBJ               -1.0
    COL08     ROW01             -1.0   ROW05              1.9

Here, the columns named COL03 and COL04 are part of a type 1 SOS. 


QSECTION Section

Data records in the QSECTION section specify the quadratic part of a quadratic model. The format of the section is similar to the COLUMNS section.

Order of Records

The following is the order of records in an MPS file that defines the quadratic part of a model:

An MPS data file may contain information for several quadratic parts. In this case, the NAME indicator record for another model should follow the ENDATA indicator record for the previous model.

Indicator Records

The NAME and ENDATA indicator records are as defined previously. However, the value of the NAME indicator record in field 2 must be the same as the input file name for the linear part of the matrix. If you want to read in the quadratic matrix with a different name, use EKKCGET and EKKCSET to change the character control variable Cname before calling EKKQMPS.

In fixed or free format, the QSECTION indicator record has the following form:
 

Field 1 

QSECTION 

Data Record

The data record in the QSECTION section has the following form:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Blank 

Column name 

Column name 

Coefficient in objective function 

Ignored 

Ignored 

 

Example

If Inumchar eq 8, the following is a sample QSECTION section in fixed format:

*234567890123456789012345678901234567890123456789012345678901234567890
NAME     EXAMPLE
QSECTION
    COL01     COL01       1.0000D+00
    COL01     COL02      -0.5000D+00
    COL02     COL01      -0.5000D+00
    COL02     COL02       1.0000D+00
    COL02     COL03      -0.5000D+00
    COL03     COL02      -0.5000D+00
    COL03     COL03       1.0000D+00
    COL03     COL04      -0.5000D+00
    COL04     COL03      -0.5000D+00
    COL04     COL04       1.0000D+00
    COL04     COL05      -0.5000D+00
    COL05     COL04      -0.5000D+00
    COL05     COL05       1.0000D+00
    COL05     COL06      -0.5000D+00
    COL06     COL05      -0.5000D+00
    COL06     COL06       1.0000D+00
    COL06     COL07      -0.5000D+00
    COL07     COL06      -0.5000D+00
    COL07     COL07       1.0000D+00
    COL07     COL08      -0.5000D+00
    COL08     COL07      -0.5000D+00
    COL08     COL08       1.0000D+00
ENDATA

In this example, the COL02*COL01 term of the objective function has coefficient -0.25.
 

Note:

The QSECTION section may be on a different unit than the MPS file defining the linear part of model, or it may be on the same unit. If it is on the same unit, the NAME card for the quadratic part of the model should be after the ENDATA card for the linear part of the model. 


Optimization Library Compatibility with MPS Format

The Optimization Library is compatible with MPSX/370 because it accepts MPS format and may be called from an MPSX/370 Extended Control Language (ECL) PL/I program. Certain MPSX/370 procedures and macros related to the input and output of models in MPS format are analogous to certain subroutines, as summarized in the table below:
 

Library Subroutine 

MPSX/370 Function 

EKKBCDO 

BCDOUT 

EKKMPS 

CONVERT 

EKKBASI 

INSERT 

EKKBASO 

PUNCH 


Descriptions of all Optimization Library subroutines may be found in Optimization Library Subroutines. Explanations of how the MPSX/370 procedures identified above and the related library subroutines are compatible appear below. For more information on a particular MPSX/370 procedure, see the Mathematical Programming System Extended/370 (MPSX/370) Program Reference Manual.

EKKBCDO

The EKKBCDO subroutine writes a model in MPS format to a file in a form compatible with the MPSX/370 BCDOUT procedure. The subroutine EKKBCDO writes the sections in the same order as BCDOUT, as follows:

EKKBCDO also writes the matrix values as a character string or in binary format, which is functionally equivalent to specifying the 'BCD' or 'BINARY' parameters in the call to BCDOUT, respectively. The binary output option is only valid for VM or MVS. EKKBCDO also allows the selection of the number of row values associated with a given column to be output per record. This is functionally equivalent to the use of the 'ONE' parameter in BCDOUT. Like BCDOUT, the row and column selection lists will affect the output of EKKBCDO.

The BCDOUT parameters 'NOLIST' and 'LEAVE' have no equivalents when calling EKKBCDO. Matrix values are always listed, and EKKBCDO does not rewind or close the file to which the output is written. Also, the only type-N row that will be written to the file is the objective function, as defined by Cobjective. The only data records in the RHS, RANGES, and BOUNDS sections that will be written to the file are those associated with the names defined by Crhs, Crange, and Cbound.

EKKMPS

The EKKMPS subroutine accepts model input in MPS format from a file in a form compatible with the MPSX/370 CONVERT procedure. Model input is written into internal data structures, rather than writing the model on a problem file.

EKKMPS and CONVERT both require the following sections in the MPS input file:

While CONVERT requires an RHS section, it is not necessary for EKKMPS. Conversely, EKKMPS requires an ENDATA record to mark the end of the input file, while this is not necessary for CONVERT.

EKKMPS performs a check for duplicate row and column names throughout the entire matrix. This is an extension to the CONVERT parameter 'CHECK', which only performs a check of column names. EKKMPS also prints summary statistics about the input file, but not in the same manner as if the CONVERT parameter 'SUMMARY' were passed. Selection lists do not affect the action of EKKMPS.

EKKBASI


Order of Records | Indicator Records | Data Records | Indicator Code
 
The EKKBASI subroutine accepts basis input in MPS format from a file in a form compatible with the MPSX/370 INSERT procedure. As in INSERT, you may specify a partial basis or a complete basis with EKKBASI. You may also define a starting solution by the values of variables with EKKBASI.

Order of Records

The following is the order of records in a basis input file for EKKBASI:

Indicator Records

The NAME and ENDATA records have the same format as the NAME and ENDATA records for model input, except that an input file name is not necessary on the NAME record, and field 3 on the NAME record is ignored.

Data Records

The data records in a basis input file have the following format:
 

Field 1 

Field 2 

Field 3 

Field 4 

Field 5 

Field 6 

Indicator code (see below) 

Name 1 

Name 2 

Value 1 

Ignored 

Value 2 

 
Field 1 must be in columns 2-3 for fixed and free format. Field 2 must be separated from field 1 by at least one blank.

Fields 3, 4, and 6 are optional, depending on the value of field 1. If field 6 must be used, then field 5 should have a nonblank value, even though it is ignored.

Indicator Code

In a data record, the indicator code defines the status of rows and columns in the following way:

Field 1 Value   Type of Code
XL
Sets the variable in field 2 to basic with the activity in field 4. It also sets the logical variable in field 3 to an intermediate status. The activity computed for this logical variable depends on the value in field 6, which indicates the activity for the corresponding row. The outgoing variable is set at its lower bound.
XU
Does the same as XL, except the outgoing variable is set to its upper bound.
LL
Sets the structural variable in field 2 to nonbasic and sets the variable at its lower bound with the activity in field 4.
UL
Does the same as LL, except the variable is set at its upper bound.
BS
Sets the variable in field 2 to basic.

If the basis already contains as many variables as the model has rows, a request to set a new variable in the basis is not taken into account. The variable is then set to nonbasic with the value indicated in field 2.

EKKBASI initially sets up an all-logical basis by calling EKKNLBS, which is similar to the INSERT parameter 'LOGICAL'. The INSERT parameters 'UPPER' and 'VALUE' have no equivalents when calling EKKBASI.

EKKBASO

The EKKBASO subroutine writes a basis to a file in MPS format in a way that is compatible with the MPSX/370 PUNCH procedure. EKKBASO writes the sections in the same order as PUNCH:

EKKBASO also writes the matrix values as a character string or in binary format, which is functionally equivalent to not specifying the 'BINARY' parameter or specifying the 'BINARY' parameter in the call to PUNCH, respectively. The binary output option is only valid for VM or MVS. EKKBASO also allows the option of printing the activity levels of the rows and columns, which is equivalent to the use of the PUNCH parameter 'VALUE'. Like PUNCH, the row and column selection lists will affect the output of EKKBASO.

The PUNCH parameters 'NONAME' and 'NOEND' have no equivalents when calling EKKBASO. The NAME and ENDATA records will be written to the file. The PUNCH parameter 'LEAVE' also has no equivalent when calling EKKBASO. EKKBASO does not rewind or close the file to which the output is written. 


Optimization Library Extensions to MPS Format

The Optimization Library provides several extensions to MPS format. Explanations of some of these extensions may be found in previous sections of this chapter:


Optimization Library Restrictions to MPS Format

While Optimization Library I/O modules do accept most features of MPS format, there is some input that is not supported through EKKMPS or EKKBASI:

Although you cannot input scale factors, the scale factors used by OSL are available through the use of the index control variables Nrowscales and Ncolscales.


Compatibility with MPSX

The Optimization Library is compatible with MPSX/370, because it accepts the MPS input format and may be called from an MPSX/370 Extended Control Language PL/I program. MPSX/370 Version 2 Release 2 (5688-739) includes new procedure calls that allow an MPSX/370 user to access the advanced algorithms implemented in the Optimization Library. These algorithms may also be accessed interactively, allowing an MPSX/370 user to combine the best features of the Optimization Library and MPSX/370. 


Programming Examples

The following are examples of how to write a program that reads your model from MPS format for linear programming, mixed-integer programming, and quadratic programming models.

Linear and Mixed-Integer Programming

Refer to "Sample FORTRAN Program EXMPS" and "Sample FORTRAN Program EXMSLV" for examples of programs that uses EKKMPS to read in an MPS file for linear programming and mixed integer programming models. After each program is a reference to a data file that is included on the product tape or diskettes. This data file can be used to run the program.

Quadratic Programming

Refer to "Sample FORTRAN Program EXQSLV" for an example of a program that uses EKKMPS and EKKQMPS to read in MPS files for a quadratic programming model. After the program is a reference to data files that are included on the product tape or diskettes. These files can be used to run the program.

If the two data files are concatenated with the linear data preceding the quadratic data, the calls to EKKMPS and EKKQMPS in the "sample FORTRAN program EXQSLV" should use the same value for the unit parameter. Neither EKKMPS nor EKKQMPS rewind MPS input files after they have been read, so EKKQMPS will begin by reading the first record after the first ENDATA record, which represents the end of the linear part of the model.

If the name of the linear part of your model is different from the quadratic part of your model, you must insert the following code before a call to EKKQMPS. This makes sure the quadratic part of your model is read:

    INCLUDE (OSLC)
        .
        .
        .
    CALL EKKCGET(RTCOD,DSPACE,OSLC,OSLCLN)
    CNAME = CQNAME
    CALL EKKCSET(RTCOD,DSPACE,OSLC,OSLCLN)

CQNAME is the value in field 2 on the NAME card that appears at the beginning of the quadratic part of your model.

Related Control Variables

There are several control variables that control the processing of EKKMPS and EKKQMPS. As previously discussed, all the character control variables control the processing of an MPS file. In addition to the character control variables, the following integer control variables control the processing of an MPS file:

The use of Ioneobj is discussed in "ROWS Section". Inumchar indicates the number of characters in fields 2, 3, and 5 of the MPS input file. Because fixed amounts of space are reserved based on the value of Inumchar, and because the interpretation of the MPS input file is based on the value of Inumchar, you should set this control variable before calling EKKMPS and not alter it in the course of your program. To do so may cause unpredictable results.

Imaxrows and Imaxcols allow you to reserve extra room for spare rows and columns in the matrix. To reserve spare rows or columns, assign a negative value to these variables. The absolute value of the value you assign will be the number of spare rows or columns that is set aside for you. If you do not set these values before calling EKKMPS, Imaxrows and Imaxcols are set to the number of rows and columns, respectively, as defined by the input file.

If you want to use subroutines EKKCOL or EKKROW or to use subroutines EKKMPRE and EKKMSLV to their fullest potential, you should set the values of Imaxrows and Imaxcols as indicated above. You must call EKKDSCM before the calls to EKKIGET and EKKISET.

The real control variable Rtolmps also applies to MPS input. The use of this variable is explained in the sections of this chapter that discuss the COLUMNS, RHS, RANGES, BOUNDS, and QSECTION sections of the MPS input file.


[ Top of Page | Previous Page | Next Page | Table of Contents ]