[Previous chapter]

Log and File Formats

---

File Types

The Optimizer generates or inputs a number of files of various types as part of the solution process. By default these all take file names governed by the problem name (problem_name), but distinguished by their three letter extension. The file types associated with the Optimizer are as follows:

Extension	Description	File Type
.alt	Matrix alteration file, input by XPRSalter (ALTER).	ASCII
.asc	CSV format solution file, output by XPRSwritesol (WRITESOL).	ASCII
.bss	Basis file, output by XPRSwritebasis (WRITEBASIS), input by XPRSreadbasis (READBASIS).	ASCII
.dir	Directives file (MIP only), input by XPRSreaddirs (READDIRS).	ASCII
.glb	Global file (MIP only), used by XPRSglobal (GLOBAL).	Binary
.gol	Goal programming input file, input byXPRSgoal (GOAL).	ASCII
.grp	Goal programming output file, output byXPRSgoal (GOAL).	ASCII
.hdr	Solution header file, output by XPRSwritesol (WRITESOL) and XPRSwriterange (WRITERANGE).	ASCII
.iis	IIS output file, output by XPRSiis (IIS).	ASCII
.lp	LP format matrix file, input by XPRSreadprob (READPROB).	ASCII
.mat	MPS / XMPS format matrix file, input by XPRSreadprob (READPROB).	ASCII
.prt	Fixed format solution file, output by XPRSwriteprtsol (WRITEPRTSOL).	ASCII
.rng	Range file, output by XPRSrange (RANGE).	Binary
.rrt	Fixed format range file, output by XPRSwriteprtrange (WRITEPRTRANGE).	ASCII
.rsc	CSV format range file, output by XPRSwriterange (WRITERANGE).	ASCII
.sol	Solution file created by XPRSwritebinsol (WRITEBINSOL).	Binary
.svf	Optimizer state file, output by XPRSsave (SAVE), input by XPRSrestore (RESTORE).	Binary

In the following sections we describe the formats for a number of these.

Note that CSV stands for comma-separated-values text file format.

XMPS Matrix Files

The Xpress‑MP Optimizer accepts matrix files in LP or MPS format, and an extension of this, XMPS format. In that the latter represents a slight modification of the industry-standard, we provide details of it here.

XMPS format defines the following fields:

Field	1	2	3	4	5	6
Columns	2-3	5-12	15-22	25-36	40-47	50-61

The following sections are defined:

NAME	the matrix name;
ROWS	introduces the rows;
COLUMNS	introduces the columns;
QUADOBJ	introduces a quadratic objective function;
SETS	introduces SOS definitions;
RHS	introduces the right hand side(s);
RANGES	introduces the row ranges;
BOUNDS	introduces the bounds;
ENDATA	signals the end of the matrix.

All section definitions start in column 1.

NAME section

Format:	Cols 1-4	Field 3
	NAME	model_name

ROWS section

Format:	Cols 1-4
	ROWS

followed by row definitions in the format:

Field 1	Field 2
type	row_name

The row types (Field 1) are:

N	unconstrained (for objective functions);
L	less than or equal to;
G	greater than or equal to;
E	equality.

COLUMNS section

Format:	Cols 1-7
	COLUMNS

followed by columns in the matrix in column order, i.e. all entries for one column must finish before those for another column start, where:

Field 1	Field 2	Field 3	Field 4	Field 5	Field 6
blank	col	row1	value1	row2	value2

specifies an entry of value1 in column col and row row1 (and value2 in col and row row2). The Field 5/Field 6 pair is optional.

QUADOBJ / QMATRIX section (Quadratic Programming only)

A quadratic objective function can be specified in an MPS file by including a QUADOBJ or QMATRIX section. For fixed format XMPS files, the section format is as follows:

Format:	Cols 1-7
	QUADOBJ

or

Format:	Cols 1-7
	QMATRIX

followed by a description of the quadratic terms. For each quadratic term, we have:

Field 1	Field 2	Field 3	Field 4
blank	col1	col2	value

where col1 is the first variable in the quadratic term, col2 is the second variable and value is the associated coefficient from the Q matrix. In the QMATRIX section all nonzero Q elements must be specified. In the QUADOBJ section only the nonzero elements in the upper (or lower) triangular part of Q should be specified. In the QMATRIX section the user must ensure that the Q matrix is symmetric, whereas in the QUADOBJ section the symmetry of Q is assumed and the missing part is generated automatically.

Note that the Q matrix has an implicit factors of 0.5 when included in the objective function.
This means, for instance that an objective function of the form

5x² + 7xy + 9y²

is represented in a QUADOBJ section as:

QUADOBJ
x      x      10
x      y       7
y      y      18

(The additional term 'y x 7' is assumed which is why the coefficient is not doubled); and in a QMATRIX section as:

QMATRIX
x      x      10
x      y       7
y      x       7
y      y      18

The QUADOBJ and QMATRIX sections must appear somewhere after the COLUMNS section and must only contain columns previously defined in the columns section. Columns with no elements in the problem matrix must be defined in the COLUMNS section by specifying a (possibly zero) cost coefficient.

SETS section (Integer Programming only)

Format:	Cols 1-4
	SETS

This record introduces the section which specifies any Special Ordered Sets. If present it must appear after the COLUMNS section and before the RHS section. It is followed by a record which specifies the type and name of each set, as defined below.

Field 1	Field 2
type	set

Where type is S1 for a Special Ordered Set of type 1 or S2 for a Special Ordered Set of type 2 and set is the name of the set.

Subsequent records give the set members for the set and are of the form:

Field 1	Field 2	Field 3	Field 4	Field 5	Field 6
blank	set	col1	value1	col2	value2

which specifies a set member col1 with reference value value1 (and col2 with reference value value2). The Field 5/Field 6 pair is optional.

RHS section

Format:	Col 1-3
	RHS

followed by the right hand side as defined below:

Field 1	Field 2	Field 3	Field 4	Field 5	Field 6
blank	rhs	row1	value1	row2	value2

specifies that the right hand side column is called rhs and has a value of value1 in row row1 (and a value of value2 in row row2). The Field 5/Field 6 pair is optional.

RANGES section

Format:	Cols 1-6
	RANGES

followed by the right hand side ranges defined as follows:

Field 1	Field 2	Field 3	Field 4	Field 5	Field 6
blank	rng	row1	value1	row2	value2

specifies that the right hand side range column is called rng and has a value of value1 in row row1 (and a value of value2 in row row2). The Field 5/Field 6 pair is optional.

For any row, if b is the value given in the RHS section and r the value given in the RANGES section, then the activity limits below are applied:

Row Type	Sign of r	Upper Limit	Lower Limit
G	+	b+r	b
L	+	b	b-r
E	+	b+r	b
E	-	b	b+r

BOUNDS section

Format:	Cols 1-6
	BOUNDS

followed by the bounds acting on the variables:

Field 1	Field 2	Field 3	Field 4
type	blank	col	value

The Linear Programming bound types are:

UP	for an upper bound;
LO	for a lower bound;
FX	for a fixed value of the variable;
FR	for a free variable;
MI	for a non-positive ('minus') variable;
PL	for a non-negative ('plus') variable (the default).

There are six additional bound types specific to Integer Programming:

UI	for an upper bounded general integer variable;
LI	for a lower bounded general integer variable;
BV	for a binary variable;
SC	for a semi-continuous variable;
SI	for a semi-continuous integer variable;
PI	for a partial integer variable.

The value specified is an upper bound on the largest value the variable can take for types UP, FR, UI, SC and SI; a lower bound for types LO and LI; a fixed value for type FX; and ignored for types BV, MI and PL. For type PI it is the switching value: below which the variable must be integer, and above which the variable is continuous. If a non-integer value is given with a UI or LI type, only the integer part of the value is used.

Integer variables may only take integer values between 0 and the upper bound. Integer variables with an upper bound of unity are treated as binary variables.
Binary variables may only take the values 0 and 1. Sometimes called 0/1 variables.
Partial integer variables must be integral when they lie below the stated value, above that value they are treated as continuous variables.
Semi-continuous variables may take the value zero or any value between a lower bound and some finite upper bound. By default, this lower bound is 1.0. Other positive values can be specified as an explicit lower bound. For example

BOUNDS
LO x 0.8
SC x 12.3

means that x can take the value zero or any value between 0.8 and 12.3.
Semi-continuous integer variables may take the value zero or any integer value between a lower bound and some finite upper bound.

ENDATA section

Format:	Cols 1-6
	ENDATA

is the last record of the file.

LP File Format

Matrices can be represented in text files using either the MPS file format (.mat or .mps files) or the LP file format (.lp files). The LP file format represents matrices more intuitively than the MPS format in that it expresses the constraints in a row-oriented, algebraic way. For this reason, matrices are often written to LP files to be examined and edited manually in a text editor. Note that because the variables are 'declared' as they appear in the constraints during file parsing the variables may not be stored in the Xpress‑Optimizer memory in the way you would expect from your enumeration of the variable names. For example, the following file:

Minimize
obj: - 2 x3

Subject To
c1: x2 - x1 <= 10
c2: x1 + x2 + x3 <= 20

Bounds
x1 <= 30

End

after being read and rewritten to file would be:

\Problem name:
Minimize
 - 2 x3

Subject To
c1: x2 - x1 <= 10
c2: x3 + x2 + x1 <= 20

Bounds
x1 <= 30

End

Note that the last constraint in the output .lp file has the variables in reverse order to those in the input .lp file. The ordering of variables in the last constraint of the rewritten file is the order that the variables were encountered during file reading. Also note that although the optimal solution is unique for this particular problem in other problems with many equal optimal solutions the path taken by the solver may depend on the variable ordering and therefore by changing the ordering of your constraints in the .lp file may lead to different solution values for the variables.

Rules for the LP file format

The following rules can be used when you are writing your own .lp files to be read by the Xpress‑Optimizer.

Comments and blank lines

Text following a backslash (\) and up to the subsequent carriage return is treated as a comment. Blank lines are ignored. Blank lines and comments may be inserted anywhere in an .lp file. For example, a common comment to put in LP files is the name of the problem:

\Problem name:  prob01

File lines, white space and identifiers

White space and carriage returns delimit variable names and keywords from other identifiers. Keywords are case insensitive. Variable names are case sensitive. Although it is not strictly necessary, for clarity of your LP files it is perhaps best to put your section keywords on their own lines starting at the first character position on the line. The maximum length for any name is 64. The maximum length of any line of input is 512. Lines can be continued if required. No line continuation character is needed when expressions are required to span multiple lines. Lines may be broken for continuation wherever you may use white space.

Sections

The LP file is broken up into sections separated by section keywords. The following are a list of section keywords you can use in your LP files. A section started by a keyword is terminated with another section keyword indicating the start of the subsequent section.

Section keywords	Synonyms	Section contents
maximize or minimize	maximum max minimum min	One linear expression describing the objective function.
subject to	subject to: such that st s.t. st. subjectto suchthat subject such	A list of constraint expressions.
bounds	bound	A list of bounds expressions for variables.
integers	integer ints int	A list of variable names of integer variables. Unless otherwise specified in the bounds section, the default relaxation interval of the variables is [0, 1].
generals	general gens gen	A list of variable names of integer variables. Unless otherwise specified in the bounds section, the default relaxation interval of the variables is [0, XPRS_MAXINT].
binaries	binary bins bin	A list of variable names of binary variables.
semi-continuous	semi continuous semis semi s.c.	A list of variable names of semi-continuous variables.
semi integer	s.i.	A list of variable names of semi-integer variables.
partial integer	p.i.	A list of variable names of partial integer variables.

Variables that do not appear in any of the variable type registration sections (i.e., integers, generals, binaries, semi-continuous, semi integer, partial integer) are defined to be continuous variables by default. That is, there is no section defining variables to be continuous variables.

With the exception of the objective function section (maximize or minimize) and the constraints section (subject to), which must appear as the first and second sections respectively, the sections may appear in any order in the file. The only mandatory section is the objective function section. Note that you can define the objective function to be a constant in which case the problem is a so-called constraint satisfaction problem. The following two examples of LP file contents express empty problems with constant objective functions and no variables or constraints.

Empty problem 1:

Minimize

End

Empty problem 2:

Minimize

0

End

The end of a matrix description in an LP file can be indicated with the keyword end entered on a line by itself. This can be useful for allowing the remainder of the file for storage of comments, unused matrix definition information or other data that may be of interest to be kept together with the LP file.

Variable names

Variable names can use any of the alphanumeric characters (a-z, A-Z, 0-9) and any of the following symbols:

!"#$%&/,.;?@_`'{}()|~'

A variable name can not begin with a number or a period. Care should be taken using the characters E or e since these may be interpreted as exponential notation for numbers.

Linear expressions

Linear expressions are used to define the objective function and constraints. Terms in a linear expression must be separated by either a + or a - indicating addition or subtraction of the following term in the expression. A term in a linear expression is either a variable name or a numerical coefficient followed by a variable name. It is not necessary to separate the coefficient and its variable with white space or a carriage return although it is advisable to do so since this can lead to confusion. For example, the string " 2e3x" in an LP file is interpreted using exponential notation as 2000 multiplied by variable x rather than 2 multiplied by variable e3x. Coefficients must precede their associated variable names. If a coefficient is omitted it is assumed to be 1.

Objective function

The objective function section can be written in a similar way to the following examples using either of the keywords maximize or minimize. Note that the keywords maximize and minimize are not used for anything other than to indicate the following linear expression to be the objective function. Note the following two examples of an LP file objective definition:

Maximize
 - 1 x1 + 2 x2 + 3x + 4y

or

Minimize
- 1 x1 + 2 x2 + 3x + 4y

Generally objective functions are defined using many terms and since the maximum length of any line of file input is 512 characters the objective function definitions are typically always broken with line continuations. No line continuation character is required and lines may be broken for continuation wherever you may use white space.

Note that the sense of objective is defined only after the problem is loaded and when it is optimized by the Xpress‑Optimizer when the user calls either the minim or maxim operations. The objective function can be named in the same way as for constraints (see later) although this name is ignored internally by the Xpress‑Optimizer. Internally the objective function is always named __OBJ___.

Constraints

The section of the LP file defining the constraints is preceded by the keyword subject to. Each constraint definition must begin on a new line. A constraint may be named with an identifier followed by a colon before the constraint expression. Constraint names must follow the same rules as variable names. If no constraint name is specified for a constraint then a default name is assigned of the form C0000001, C0000002, C0000003, etc. Constraint names are trimmed of white space before being stored.

The constraints are defined as a linear expression in the variables followed by an indicator of the constraint's sense and a numerical right-hand side coefficient. The constraint sense is indicated intuitively using one of the tokens: >=, <=, or =. For example, here is a named constraint:

depot01: - x1 + 1.6 x2 - 1.7 x3 <;= 40

Note that tokens > and < can be used, respectively, in place of the tokens >= and <=.

Generally, constraints are defined using many terms and since the maximum length of any line of file input is 512 characters the constraint definitions are typically always broken with line continuations. No line continuation character is required and lines may be broken for continuation wherever you may use white space.

Bounds

The list of bounds in the bounds section are preceded by the keyword bounds. Each bound definition must begin on a new line. Single or double bounds can be defined for variables. Double bounds can be defined on the same line as 10 <= x <= 15 or on separate lines in the following ways:

10 <= x
15 >= x

or

x >= 10
x <= 15

If no bounds are defined for a variable the Xpress‑Optimizer uses default lower and upper bounds. An important point to note is that the default bounds are different for different types of variables. For continuous variables the interval defined by the default bounds is [0, XPRS_PLUSINFINITY] while for variables declared in the integers and generals section (see later) the relaxation interval defined by the default bounds is [0, 1] and [0, XPRS_MAXINT], respectively. Note that the constants XPRS_PLUSINFINITY and XPRS_MAXINT are defined in the Xpress‑Optimizer header files in your Xpress‑Optimizer libraries package.

If a single bound is defined for a variable the Xpress‑Optimizer uses the appropriate default bound as the second bound. Note that negative upper bounds on variables must be declared together with an explicit definition of the lower bound for the variable. Also note that variables can not be declared in the bounds section. That is, a variable appearing in a bounds section that does not appear in a constraint in the constraint section is ignored.

Bounds that fix a variable can be entered as simple equalities. For example, x6 = 7.8 is equivalent to 7.8 <= x6 <= 7.8. The bounds + (positive infinity) and - (negative infinity) must be entered as strings (case insensitive):

+infinity, -infinity, +inf, -inf.

Note that the keywords infinity and inf may not be used as a right-hand side coefficient of a constraint.

A variable with a negative infinity lower bound and positive infinity upper bound may be entered as free (case insensitive). For example, x9 free in an LP file bounds section is equivalent to:

- infinity <= x9 <= + infinity

or

- infinity <= x9 

In the last example here, which uses a single bound is used for x9 (which is positive infinity for continuous example variable x9).

Generals, Integers and binaries

The generals, integers and binaries sections of an LP file is used to indicate the variables that must have integer values in a feasible solution. The difference between the variables registered in each of these sections is in the definition of the default bounds that the variables will have. For variables registered in the generals section the default bounds are 0 and XPRS_MAXINT. For variables registered in the integers section the default bounds are 0 and 1. The bounds for variables registered in the binaries section are 0 and 1.

The lines in the generals, integers and binaries sections are a list of white space or carriage return delimited variable names. Note that variables can not be declared in these sections. That is, a variable appearing in one of these sections that does not appear in a constraint in the constraint section is ignored.

It is important to note that you will only be able to use these sections if your Xpress‑Optimizer is licensed for Mix Integer Programming.

Semi-continuous and semi-integer

The semi-continuous and semi integer sections of an LP file relate to two similar classes of variables and so their details are documented here simultaneously.

The semi-continuous (or semi integer) section of an LP file are used to specify variables as semi-continuous (or semi-integer) variables, that is, as variables that may take either (a) value 0 or (b) real (or integer) values from specified thresholds and up to the variables' upper bounds.

The lines in a semi-continuous (or semi integer) section are a list of white space or carriage return delimited entries that are either (i) a variable name or (ii) a variable name-number pair. The following example shows the format of entries in the semi-continuous section.

Semi-continuous
x7 >= 2.3
x8
x9 >= 4.5

The following example shows the format of entries in the semi integer section.

Semi integer
x7 >= 3
x8
x9 >= 5

Note that you can not use the <= token in place of the >= token.

The threshold of the interval within which a variable may have real (or integer) values is defined in two ways depending on whether the entry for the variable is (i) a variable name or (ii) a variable name-number pair. If the entry is just a variable name, then the variable's threshold is the variable's lower bound, defined in the bounds section (see earlier). If the entry for a variable is a variable name-number pair, then the variable's threshold is the number value in the pair.

It is important to note that if (a) the threshold of a variable is defined by a variable name-number pair and (b) a lower bound on the variable is defined in the bounds section, then:

Case 1) If the lower bound is less then zero, then the lower bound is zero.

Case 2) If the lower bound is greater than zero but less than the threshold, then the value of zero is essentially cut off the domain of the semi-continuous (or semi-integer) variable and the variable becomes a simple bounded continuous (or integer) variable.

Case 3) If the lower bound is greater than the threshold, then the variable becomes a simple lower bounded continuous (or integer) variable.

If no upper bound is defined in the bounds section for a semi-continuous (or semi-integer) variable, then the default upper bound that is used is the same as for continuous variables, for semi-continuous variables, and generals section variables, for semi-integer variables.

It is important to note that you will only be able to use this section if your Xpress‑Optimizer is licensed for Mix Integer Programming.

Partial integers

The partial integers section of an LP file is used to specify variables as partial integer variables, that is, as variables that can only take integer values from their lower bounds up to specified thresholds and then take continuous values from the specified thresholds up to the variables' upper bounds.

The lines in a partial integers section are a list of white space or carriage return delimited variable name-integer pairs. The integer value in the pair is the threshold below which the variable must have integer values and above which the variable can have real values. Note that lower bounds and upper bounds can be defined in the bounds section (see earlier). If only one bound is defined in the bounds section for a variable or no bounds are defined then the default bounds that are used are the same as for continuous variables.

The following example shows the format of the variable name-integer pairs in the partial integers section.

Partial integers
x11 >= 8
x12 >= 9

Note that you can not use the <= token in place of the >= token.

It is important to note that you will only be able to use this section if your Xpress‑Optimizer is licensed for Mix Integer Programming.

Special ordered sets

Special ordered sets are defined as part of the constraints section of the LP file. The definition of each special ordered set looks the same as a constraint except that the sense is always = and the right hand side is either S1 or S2 (case sensitive) depending on whether the set is to be of type 1 or 2, respectively. Special ordered sets of type 1 require that, of the non-negative variables in the set, one at most may be non-zero. Special ordered sets of type 2 require that at most two variables in the set may be non-zero, and if there are two non-zeros, they must be adjacent. Adjacency is defined by the weights, which must be unique within a set given to the variables. The weights are defined as the coefficients on the variables in the set constraint. The sorted weights define the order of the special ordered set. It is perhaps best practice to keep the special order sets definitions together in the LP file to indicate (for your benefit) the start of the special ordered sets definition with the comment line \Special Ordered Sets as is done when a problem is written to an LP file by the Xpress‑Optimizer. The following example shows the definition of a type 1 and type 2 special ordered set.

Sos101: 1.2 x1 + 1.3 x2 + 1.4 x4 = S1
Sos201: 1.2 x5 + 1.3 x6 + 1.4 x7 = S2

It is important to note that you will only be able to use special ordered sets if your Xpress‑Optimizer is licensed for Mix Integer Programming.

Quadratic programming problems

Quadratic programming problems (QPs) with quadratic objective functions are defined using a special format within the objective function description. Note that quadratic terms may appear only in the objective function and not in any constraints. The algebraic coefficients of the function x'Qx appearing in the objective for QP problems are specified inside square brackets []. Division by two of the QP objective component in the square bracket is implicit. All quadratic coefficients must appear inside square brackets. Multiple square bracket sections may be used and quadratic terms in the same variable(s) may appear more than once in quadratic expressions.

Within a square bracket pair, a quadratic term in two different variables is indicated by the two variable names separated by an asterisk (*). A squared quadratic term is indicated with the variable name followed by a carat (^) and then a 2.

For example, the LP file objective function section:

Minimize
obj: x1 + x2 + [ x12 + 4 x1 * x2 + 3 x22 ]

Note that if in a solution the variables x1 and x2 both have value 1 then value of the objective function is 1 + 1 + (1*1 + 4*1*1 + 3*1*1) / 2 = 2 + (8) / 2 = 6.

It is important to note that you will only be able to use quadratic objective function components if your Xpress‑Optimizer is licensed for Quadratic Programming.

ASCII Solution Files

Solution information is available from the Optimizer in a number of different file formats depending on the intended use. The XPRSwritesol (WRITESOL) command produces two files, problem_name.hdr and problem_name.asc, whose output has comma separated fields and is primarily intended for input into another program. By contrast, the command XPRSwriteprtsol (WRITEPRTSOL ) produces fixed format output intended to be sent directly to a printer, the file problem_name.prt. All three of these files are described below.

Solution Header .hdr Files

This file only contains one line of characters comprising header information which may be used for controlling the reading of the .asc file (which contains data on each row and column in the problem). The single line is divided into fourteen fields, separated by commas, as follows:

Field	Type	Width	Description
1	string	10	matrix name;
2	integer	4	number of rows in problem;
3	integer	6	number of structural columns in problem;
4	integer	4	sequence number of the objective row;
5	string	3	problem status (see notes below);
6	integer	4	direction of optimization (0=none, 1=min, 2=max);
7	integer	6	number of iterations taken;
8	integer	4	final number of infeasibilities;
9	real	12	final object function value;
10	real	12	final sum of infeasibilities;
11	string	10	objective row name;
12	string	10	right hand side row name;
13	integer	1	flag: integer solution found (1), otherwise 0;
14	integer	4	matrix version number.

• Character fields contain character strings enclosed in double quotes.
• Integer fields contain right justified decimal digits.
• Fields of type real contain a decimal character representation of a real number, right justified, with six digits to the right of the decimal point.
• The status of the problem (field 5) is a single character as follows:

O	optimal;
N	infeasible;
U	unbounded;
Z	unfinished.

CSV Format Solution .asc Files

The bulk of the solution information is contained in this file. One line of characters is used for each row and column in the problem, starting with the rows, ordered according to input sequence number. Each line contains ten fields, separated by commas, as follows:

Field	Type	Width	Description
1	integer	6	input sequence number of variable;
2	string	10	variable (row or column vector) name;
3	string	3	variable type (C=column; N, L, G, E for rows);
4	string	4	variable status (LL, BS, UL, EQ or **);
5	real	12	value of activity;
6	real	12	slack activity (rows) or input cost (columns;)
7	real	12	lower bound (-1000000000 if none);
8	real	12	upper bound (1000000000 if none);
9	real	12	dual activity (rows) or reduced cost (columns);
10	real	12	right hand side value (rows) or blank (columns).

• The field Type is as for the .hdr file.
• The variable type (field 3) is defined by:
  C   structural column;
  N   N type row;
  L   L type row;
  G   G type row;
  E   E type row;
• The variable status (field 4) is defined by:
  LL   non-basic at lower bound;
  **   basic and infeasible;
  BS   basic and feasible;
  UL   non-basic at upper bound;
  EQ   equality row;
  SB   variable is super-basic;
  ??   unknown.

Fixed Format Solution (.prt) Files

This file is the output of the XPRSwriteprtsol (WRITEPRTSOL) command and has the same format as is displayed to the console by PRINTSOL. The format of the display is described below by way of an example, for which the simple example of the Xpress‑MP Getting Started manual will be used.

The first section contains summary statistics about the solution process and the optimal solution that has been found. It gives the matrix (problem) name (simple) and the names of the objective function and right hand sides that have been used. Then follows the number of rows and columns, the fact that it was a maximization problem, that it took two iterations (simplex pivots) to solve and that the best solution has a value of 171.428571.

Problem Statistics
Matrix simple
Objective *OBJ*
RHS *RHS*
Problem has      3 rows and      2 structural columns

Solution Statistics
Maximization performed
Optimal solution found after      3 iterations
Objective function value is     171.428571

Next, the Rows Section presents the solution for the rows, or constraints, of the problem.

Rows Section
Number Row    At    Value     Slack Value Dual Value  RHS
N   1    *OBJ*  BS  171.428571  -171.428571  .000000      .000000
L   2    second UL  200.000000      .000000  .571429   200.000000
L   3    first  UL  400.000000      .000000  .142857   400.000000

The first column shows the constraint type: L means a 'less than or equal to' constrain; E indicates an 'equality' constraint; G refers to a 'greater than or equal to' constraint; N means a 'nonbinding' constraint -- this is the objective function.

The sequence numbers are in the next column, followed by the name of the constraint. The At column displays the status of the constraint. A UL indicator shows that the row is at its upper limit. In this case a row is hard up against the right hand side that is constraining it. BS means that the constraint is not active and could be removed from the problem without changing the optimal value. If there were constraints then we might see LL indicators, meaning that the constraint was at its lower limit. Other possible values include:

**	basic and infeasible;
EQ	equality row;
??	unknown.

The RHS column is the right hand side of the original constraint and the Slack Value is the amount by which the constraint is away from its right hand side. If we are tight up against a constraint (the status is UL or LL) then the slack will be 0.

The Dual Value is a measure of how tightly a constraint is acting. If a row is hard up against a constraint then it might be expected that a greater profit would result if the constraint were relaxed a little. The dual value gives a precise numerical measure to this intuitive feeling. In general terms, if the right hand side of a row is increased by 1 then the profit will increase by the dual value of the row. More specifically, if the right hand side increases by a sufficiently small then the profit will increase by x dual value, since the dual value is a marginal concept. Dual values are sometimes known as shadow prices.

Finally, the Columns Section gives the solution for the columns, or variables.

Columns Section
Number Column At    Value    Input Cost   Reduced Cost
C   4     a     BS  114.285714    1.000000  .000000
C   5     b     BS   28.571429    2.000000  .000000

The first column contains a C meaning column (compare with the rows section above). The number is a sequence number. The name of the decision variable is given under the Column heading. Under At is the status of the column: BS means it is away from its lower or upper bound, LL means that it is at its lower bound and UL means that the column is limited by its upper bound. Other possible values include:

**	basic and infeasible;
EQ	equality row;
SB	variable is super-basic;
??	unknown.

The Value column gives the optimal value of the variable. For instance, the best value for the variable a is 114.285714 and for variable b it is 28.571429. The Input Cost column tells you the coefficient of the variable in the objective function.

The final column in the solution print gives the Reduced Cost of the variable, which is always zero for variables that are away from their bounds -- in this case, away from zero. For variables which are zero, it may be assumed that the per unit contribution is not high enough to make production viable. The reduced cost shows how much the per unit profitability of a variable would have to increase before it would become worthwhile to produce this product. Alternatively, and this is where the name reduced cost comes from, the cost of production would have to fall by this amount before any production could include this without reducing the best profit.

ASCII Range Files

Users can display range (sensitivity analysis) information produced by XPRSrange (RANGE) either directly, or by printing it to a file for use. Two functions exist for this purpose, namely XPRSwriteprtrange (WRITEPRTRANGE) and XPRSwriterange (WRITERANGE). The first of these, XPRSwriterange (WRITERANGE) produces two files, problem_name.hdr and problem_name.rsc, both of which have fixed fields and are intended for use as input to another program. By way of contrast, command XPRSwriteprtrange (WRITEPRTRANGE) outputs information in a format intended for sending directly to a printer (problem_name.rrt). The information provided by both functions is essentially the same and the difference lies purely in the intended purpose for the output. The formats of these files are described below.

Solution Header (.hdr) Files

This file contains only one line of characters comprising header information which may be used for controlling the reading of the .rsc file. Its format is identical to that produced by XPRSwritesol (WRITESOL) and is described in Solution Header (.hdr) Files above.

CSV Format Range (.rsc) Files

The bulk of the range information is contained in this file. One line of characters is used for each row and column in the problem, starting with the rows, ordered according to input sequence number. Each line contains 16 fields, separated by commas, as follows:

Field	Type	Width	Description
1	integer	6	input sequence number of variable;
2	string	*	variable (row or column vector) name;
3	string	3	variable type (C=column; N, L, G, E for rows);
4	string	4	variable status (LL, BS, UL, EQ or **);
5	real	12	value of activity;
6	real	12	slack activity (rows) or input cost (columns);
7	real	12	lower activity;
8	real	12	unit cost down;
9	real	12	lower profit;
10	string	*	limiting process;
11	string	4	status of limiting process at limit (LL, UL);
12	real	12	upper activity;
13	real	12	unit cost up;
14	real	12	upper profit;
15	string	*	limiting process;
16	string	4	status of limiting process at limit (LL, UL).
* these fields are variable length depending on the maximum name length

• The field Type is as for the .hdr file.
• The variable type (field 3) is defined by:
  C   structural column;
  N   N type row;
  L   L type row;
  G   G type row;
  E   E type row;
• The variable status (field 4) is defined by:
  LL   non-basic at lower bound;
  **   basic and infeasible;
  BS   basic and feasible;
  UL   non-basic at upper bound;
  EQ   equality row;
  ??   unknown.
• The status of limiting process at limit (fields 11 and 16) is defined by:
  LL   non-basic at lower bound;
  UL   non-basic at upper bound;
• A full description of all fields can be found below.

Fixed Format Range (.rrt) Files

This file is the output of the XPRSwriteprtrange (WRITEPRTRANGE ) command and has the same format as is displayed to the console by PRINTRANGE. This format is described below by way of an example.

Output is displayed in three sections, variously showing summary data, row data and column data. The first of these is the same information as displayed by the XPRSwriteprtsol (WRITEPRTSOL) command (see above), resembling the following:

Problem Statistics
Matrix PLAN
Objective C0______
RHS R0______
Problem has 7 rows and 5 structural columns

Solution Statistics
Minimization performed
Optimal solution found after 6 iterations
Objective function value is 15.000000

The next section presents data for the rows, or constraints, of the problem. For each constraint, data are displayed in two lines. In this example the data for just one row is shown:

Rows Section
Vector Activity Lower actvty Unit cost DN Upper cost Limiting AT
Number Slack    Upper actvty Unit cost UP            Process
G C1 10.000000    9.000000  -1.000000                x4       LL
LL 2 .000000     12.000000   1.000000                C6       UL

In the first of the two lines, the row type (N, G, L or E) appears before the row name. The value of the activity follows. Then comes Lower actvty, the level to which the activity may be decreased at a cost per unit of decrease given by the Unit cost DN column. At this level the unit cost changes. The Limiting Process is the name of the row or column that would change its status if the activity of this row were decreased beyond its lower activity. The AT column displays the status of the limiting process when the limit is reached. It is either LL, meaning that it leaves or enters the basis at its lower limit, or UL, meaning that it leaves or enters the basis at its upper limit. In calculating Lower actvty, the lower bound on the row as specified in the RHS section of the matrix is ignored.

The second line starts with the current status of the row and the sequence number. The value of the slack on the row is then shown. The next four pieces of data are exactly analogous to the data above them. Again, in calculating Upper actvty, the upper bound on that activity is ignored.

The columns, or variables, are similarly displayed in two lines. Here we show just two columns:

Columns Section
Vector Activity   Lower actvty Unit costDN Upper cost Limiting AT
Number Input cost Upper actvty Unit costUP Lower cost Process    
C x4   1.000000   -2.000000    5.000000    6.000000   C5       LL
BS 8   1.000000    3.000000    1.000000     .000000   C1       LL

C x5   2.000000   -1.000000    2.000000    6.000000   X3       LL
UL 9   4.000000    3.000000   -2.000000  -very large  X2       LL

The vector type is always C, denoting a column. The Activity is the optimal value. The Lower/Upper actvty is the activity level that would result from a cost coefficient increase/decrease from the Input cost to the Upper/Lower cost (assuming a minimization problem). The lower/upper bound on the column is ignored in this calculation. The Unit cost DN/UP is the change in the objective function per unit of change in the activity down/up to the Lower/Upper activity. The interpretation of the Limiting Processes and AT statuses is as for rows. The second line contains the column's status and sequence number.

Note that for non-basic columns, the Unit costs are always the (absolute) values of the reduced costs.

The Directives (.dir) File

This consists of an unordered sequence of records which specify branching priorities, forced branching directions and pseudo costs, read into the Optimizer using the XPRSreaddirs (READDIRS) command. By default its name is of the form problem_name.dir.

Directive file records have the format:

Col 2-3	Col 5-12	Col 25-36
type	entity	value

type is one of:

PR	implying a priority entry (the value gives the priority, which must be an integer between 0 and 1000. Values greater than 1000 are rejected, and real values are rounded down to the next integer. A low value means that the entity is more likely to be selected for branching.)
UP	the entity is to be forced up (value is not used)
DN	the entity is to be forced down (value is not used)
PU	an up pseudo cost entry (the value gives the cost)
PD	a down pseudo cost entry (the value gives the cost)
MC	a model cut entry (value is not used)

entity is the name of a global entity (vector or special ordered set), or a mask. A mask may comprise ordinary characters which match the given character: a ? which matches any single character, or a *, which matches any string or characters. A * can only appear at the end of a mask.

value is the value to accompany the type.

For example:

PR x1* 2

gives global entities (integer variables etc.) whose names start with x1 a priority of 2. Note that the use of a mask: a * matches all possible strings after the initial x1.

The Matrix Alteration (.alt) File

The Alter File is an ASCII file containing matrix revision statements, read in by use of the XPRSalter (ALTER) command, and should be named problem_name.alt by default. Each statement occupies a separate line of the file and the final line is always empty. The statements consist of identifiers specifying the object to be altered and actions to be applied to the specified object. Typically the identifier may specify just a row, for example R2, specifying the second row if that name has been assigned to row 2. If a coefficient is to be altered, the associated variable must also be specified. For example:

RRRRRRRR
CCRider
2.087

changes the coefficient of CCRider in row RRRRRRRR to 2.087. The action may be one of the following possibilities.

Changing Upper or Lower Bounds

An upper or lower bound of a column may be altered by specifying the special 'rows' **LO and **UP for lower and upper bounds respectively.

Changing Right Hand Side Coefficients

Right hand side coefficients of a row may be altered by changing values in the 'column' with the name of the right hand side.

Changing Constraint Types

The direction of a constraint may be altered. The row name is given first, followed by an action of **NTx, where x is one of:

N	for the new row type to be constrained;
L	for the new row type to be 'less than or equal to';
G	for the new row type to be 'greater than or equal to';
E	for the new row type to be an equality.

Note that N type rows will not be present in the matrix in memory if the control KEEPNROWS has been set to zero before XPRSreadprob (READPROB).

The Simplex Log

During the simplex optimization, a summary log is displayed every n iterations, where n is the value of LPLOG. This summary log has the form:

Its	The number of iterations or steps taken so far.
Obj Value	The objective function value.
S	The current solution method (p primal; d dual).
Ninf	The number of infeasibilities.
Nneg	The number of variables which may improve the current solution if assigned a value away from their current bounds.
Sum inf	The scaled sum of infeasibilities. For the dual algorithm this is the scaled sum of dual infeasibilities when the number of negative dj's is non-zero.
Time	The number of seconds spent iterating.

A more detailed log can be displayed every n iterations by setting LPLOG to -n. The detailed log has the form:

Its	The number of iterations or steps taken so far.
S	The current solution method (p primal; d dual).
Ninf	The number of infeasibilities.
Obj Value	If the solution is infeasible, the scaled sum of infeasibilities, otherwise: the objective value.
In	The sequence number of the variable entering the basis (negative if from upper bound).
Out	The sequence number of the variable leaving the basis (negative if to upper bound).
Nneg	The number of variables which may prove the current solution if assigned a value away from their current bounds.
Dj	The scaled rate at which the most promising variable would improve the solution if assigned a value away from its current bound (reduced cost).
Neta	A measure of the size of the inverse.
Nelem	Another measure of the size of the inverse.
Time	The number of seconds spent iterating.

If LPLOG is set to 0, no log is displayed until the optimization finishes.

The Global Log

During the Branch and Bound tree search (see XPRSglobal (GLOBAL)), a summary log of nine columns of information is printed every n nodes, where -n is the value of MIPLOG. These columns consist of:

Node	A sequential node number.
BestSoln	The value of the best integer feasible solution found.
BestBound	A bound on the value of the best integer feasible solution that can be found.
Sols	The number of integer feasible solutions that have been found.
Active	The number of active nodes in the Branch and Bound tree search.
Depth	The depth of the current node in the Branch and Bound tree.
Gap	The percentage gap between the best solution and the best bound.
GInf	The number of global infeasabilities at the current node.
Time	The time taken.

This log is also printed when an integer feasible solution is found. Stars (*) printed on both sides of the log indicate a solution has been found. Pluses (+) printed on both sides of the log indicate a heuristic solution has been found.

If MIPLOG is set to 3, a more detailed log of eight columns of information is printed for each node in the tree search:

Branch	A sequential node number.
Parent	The node number of the parent of this node.
Solution	The optimum value of the LP relaxation at the node.
Entity	If it is necessary to continue the search from this node, then this global entity will be separated upon.
Value / Bound	The current value of the entity chosen above for separation. A U or an L follows: If the letter is U (resp. L) then a new upper (lower) bound will first be applied to the entity. Thus the entity will be forced down (up) on the first branch from this node.
Active	The number of active nodes in the tree search.
GInf	The number of global infeasibilities.
Time	The time taken.

Not all the information described above is present for all nodes. If the LP relaxation is cut off, only the Branch and Parent (and possibly Solution) are displayed. If the LP relaxation is infeasible, only the Branch and Parent appear. If an integer solution is discovered, this is highlighted before the log line is printed.

If MIPLOG is set to 2, the detailed log is printed at integer feasible solutions only. When MIPLOG is set to 0 or 1, no log is displayed and status messages only are displayed at the end of the search. The LP iteration log is suppressed, but messages from the LP Optimizer may be seen if major numerical difficulties are encountered.

[Index]

---

If you have any comments or suggestions about these pages, please send mail to docs@dashoptimization.com.