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:

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 FICO Xpress 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:

The following sections are defined:

All section definitions start in column 1.

NAME section

ROWS section

followed by row definitions in the format:

The row types (Field 1) are:

COLUMNS section

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:

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:

or

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

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

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.

QCMATRIX section (Quadratic Constraint Programming only)

Quadratic constraints may be added using QCMATRIX sections.

Each constraint having quadratic terms should have it's own QCMATRIX section. The QCMATRIX section exactly follows the description of the QMATRIX section, i.e. for each quadratic term, we have:

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. All nonzero Q elements must be specified. The user must ensure that the Q matrix is symmetric. For instance a constraint of the form

is represented as:

NAME example
ROWS
 L qc1
COLUMNS
   x      qc1     1
   y      qc1     0
QCMATRIX qc1
   x      x       5
   x      y       3.5
   y      x       3.5
   y      y       9
RHS
 RHS1     qc1     2
END

The QCMATRIX 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. The defined matrices must be positive semi-definite. QCMATRICES must be defined only for rows of type L or G and must have no range value defined in the RANGE section..

NOTE: technically, there is one exception for the restriction on the row type being L or G. If the row is the first nonbinding row (type N) then the section is treated as a QMATRIX section instead. Please be aware, that this also means that the objective specific implied divider of 2 will be assumed (Q matrix has an implicit factors of 0.5 when included in the objective function, see the QMATRIX section). It's probably much better to use the QMATRIX or QUADOBJ sections to define quadratic objectives.

DELAYEDROWS section

This specifies a set of rows in the matrix that will be treated as delayed rows during a global search. These are rows that must be satisfied for any integer solution, but will not be loaded into the active set of constraints until required.

This section should be placed between the ROWS and COLUMNS sections. A delayed row may be of type L, G or E. Each row should appear either in the ROWS or the DELAYEDROWS section, not in both. Otherwise, the format used is the same as of the ROWS section.

followed by row definitions in the format:

NOTE: For compatibility reasons, section names DELAYEDROWS and LAZYCONS are treated as synonyms.

MODELCUTS section

This specifies a set of rows in the matrix that will be treated as model cuts during a global search. During presolve the model cuts are removed from the matrix. Following optimization, the violated model cuts are added back into the matrix and the matrix is re-optimized. This continues until no violated cuts remain. This section should be placed between the ROWS and COLUMNS sections. Model cuts may be of type L, G or E. The model cuts must be "true" model cuts, in the sense that they are redundant at the optimal MIP solution. The Optimizer does not guarantee to add all violated model cuts, so they must not be required to define the optimal MIP solution.

Each row should appear either in the ROWS, DELAYEDROWS or in the MODELCUTS section, not in any two or three of them. Otherwise, the format used is the same as of the ROWS section.

followed by row definitions in the format:

NOTE: A problem is not allowed to consists solely from model cuts. For compatibility reasons, section names MODELCUTS and USERCUTS are treated as synonyms.

INDICATORS section

This specifies that a set of rows in the matrix will be treated as indicator constraints during a global search. These are constraints that must be satisfied only when their associated controlling binary variables have specified values (either 0 or 1).

This section should be placed after any QUADOBJ, QMATRIX or QCMATRIX sections. The section format is as follows:

Subsequent records give the associations between rows and the controlling binary columns, with the following form:

which specifies that the row row_name must be satisfied only when column col_name has value value. Here type must always be IF and value can be either 0 or 1. Also referenced rows must be of type L or G only, and referenced columns must be binary.

SETS section (Integer Programming only)

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.

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:

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

followed by the right hand side as defined below:

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

followed by the right hand side ranges defined as follows:

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:

BOUNDS section

followed by the bounds acting on the variables:

The Linear Programming bound types are:

There are six additional bound types specific to Integer Programming:

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

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 FICO 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 FICO 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 given by the control LINELENGTH. 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.

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 LINELENGTH 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 FICO 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 FICO 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 LINELENGTH 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.

Delayed rows

Delayed rows are defined in the same way as general constraints, but after the "delayed rows" keyword. Note that delayed rows shall not include quadratic terms. The definition of constraints, delayed rows and model cuts should be sequentially after each other.

For example:

Minimize
obj: x1 + x2
subject to
x1 <= 10
x1 + x2 >= 1
delayed rows
x1 >= 2
end

For compatibility reasons, the term "lazy constraints" is used as a synonym to "delayed rows".

Model cuts

Model cuts are defined in the same way as general constraints, but after the "model cuts" keyword. Note that model cuts shall not include quadratic terms. The definition of constraints, delayed rows and model cuts should be sequentially after each other.

For example:

Minimize
obj: x1 + x2
subject to
x1 <= 10
x1 + x2 >= 1
model cuts
x1 >= 2
end

For compatibility reasons, the term "user cuts" is used as a synonym to "model cuts".

Indicator contraints

Indicator constraints are defined in the constraints section together with general constraints (that is, under the keyword "subject to"). The syntax is as follows:

constraint_name: col_name = value -> linear_inequality

which means that the constraint linear_inequality should be enforced only when the variable col_name has value value.

As for general constraints, the constraint_name: part is optional; col_name is the name of the controlling binary variable (it must be declared as binary in the binaries section); and value may be either 0 or 1. Finally the linear_inequality is defined in the same way as for general constraints.

For example:

Minimize
obj: x1 + x2
subject to
x1 + 2 x2 >= 2
x1 = 0 -> x2 >= 2
binary
x1
end

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 FICO 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 FICO Xpress Optimizer header files in your FICO Xpress Optimizer libraries package.

If a single bound is defined for a variable the FICO 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 FICO 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 FICO 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 FICO 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 FICO 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 FICO 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. The algebraic coefficients of the function x'Qx appearing in the objective for QP problems are specified inside square brackets []. 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.

Division by two of the QP objective is either implicit, or expressed by a /2 after the square brackets, thus [...] and [...]/2 are equivalent.

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 ] /2

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 FICO Xpress Optimizer is licensed for Quadratic Programming.

Quadratic Constraints

Quadratic terms in constraints are introduced using the same format and rules as for the quadratic objective, but without the implied or explicit /2 after the square brackets. Quadratic rows must be of type <= or >=, and the quadratic matrix should be positive semi-definite for <= rows and negative semi-definite for >= rows (do that the defined region is convex).

For example:

Minimize
obj: x1 + x2
s.t.
x1 + [ x1^2 + 4 x1 * x2 + 3 x2^2 ] <= 10
x1 >= 1
end

Please be aware of the differences of the default behaviour of the square brackets in the objective compared to the constraints. For example problem:

min y + [ x^2 ]
st.
 x >= 1
 y >= 1
end

Has an optimal objective function value of 1.5, while problem:

min t
 s.t.
 -t + y + [ x^2 ] <= 0
 x >= 1
 y >= 1
end

has an optimum of 2. The user is suggested to use the explicit /2 in the objective function like:

min y + [ x^2 ] / 2
st.
 x >= 1
 y >= 1
end

to make sure that the model represents what the modeller meant.

Extended naming convention

If the names in the problem do not comply with the LP file format, the optimizer will automatically check if uniqueness and reproducibility of the names could be preserved by prepending "x(" and appending ")" to all names, i.e. the parenthesis inside the original names are always presented in pairs. In these cases, the optimizer will create an LP file with the extended naming convention format. Use control FORCEOUTPUT to force the optimizer to write the names in the problem out as they are.

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:

• 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:

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:

• 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 FICO Xpress 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:

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:

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 Solution (.slx) Files

These files provide an easy to read format for storing solutions. An .slx file has a header NAME containing the name of the matrix the solution belongs to. Each line contains three fields as follows:

The variable type (field 1) is defined by:
C   structural column;
S   LP solution only: slack variables;
D   LP solution only: dual variables;
R   LP solution only: reduced costs.

The file is closed by ENDATA.

It is possible to store multiple solutions in the same .slx file by repeating the NAME field following by the additional solution information.

Example

NAME solution 1
 C	x1	0
 C	x2	1
NAME solution 2
 C	x1	1
 C	x2	0
ENDATA

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:

• 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:

type is one of:

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:

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.

IIS description file in CSV format

This file contains information on a single IIS of an infeasible LP.

Note that each IIS may contain a row or column with only on one of its possible senses. This also means that equality rows and columns with both lower and upper bounds, only one side of the restriction may be present. Range constraints in an IIS are converted to greater than or equal constraints.

An IIS often contains other columns than those listed in the IIS. Such columns are free, and have no associated conflicting bounds.

The information contained in these files is the same as returned by the XPRSgetiisdata function, or displayed by (IIS -p).

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.To change the objective coefficient of a column use the string **OBJ. For example, to change the lower bound (to 1.234), upper bound (to 5.678) and the objective (to 1234.0) of column x___0305 would look like:-

**LO
x___0305
1.234
**UP
x___0305
5.678
**OBJ
x___0305
1234.0

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:

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 Tuner Method (.xtm) File

The tuner method file is in a straightforward plain text format. For example, when the two controls MAXTIME and THREADS are set by the user on the current problem and then XPRStunerwritemethod is called, the generated xtm file will look as follows:

FIXED-CONTROLS
  MAXTIME              = 100
  THREADS              = 1
TUNABLE-CONTROLS
  SBEFFORT             = 0.25, 4
  HEURSEARCHEFFORT     = 0.5, 2
  CUTFACTOR            = 0.5, 1, 5
  SCALING              = 0
  PRESOLVE             = 0
  VARSELECTION         = 2, 7
  CUTFREQ              = 2
  SYMMETRY             = 0, 1, 2
  COVERCUTS            = 0, 2
  GOMCUTS              = 0, 2, 10
  TREECOVERCUTS        = 0
  TREEGOMCUTS          = 0
  HEURSTRATEGY         = 0
  SBESTIMATE           = 1, 2, 3, 4, 5, 6
  HEURSEARCHROOTSELECT = 0, 3, 5
  HEURSEARCHTREESELECT = 0, 3, 5
  ROOTPRESOLVE         = 1
  PREPROBING           = 3
  BRANCHDISJ           = 0

The tuner method file consists of a section of fixed controls and a section of tunable controls.

The fixed controls

The fixed controls section starts with FIXED-CONTROLS, followed by control setting lines in assignment form. Each control in this section can only be assigned to one value. If the same control appears several times in this section, its first appearance will be used.

When writting out the tuner method file, all the controls set for the current problem will be included in the fixed control section. When reading in the tuner method file using XPRStunerreadmethod, these controls won't be applied to the current problem immediately, they will only be applied to the worker problem used in the tuner.

This section can be empty.

The tunable controls

The tunable controls section starts with TUNABLE-CONTROLS, followed by control setting lines in assignment form. Each control in this section can be assigned to one value, or multiple values seperated by commas. A control may appear mutiple times in this section.

When reading in a tuner method file and writing it out again, the tunable controls may appear in a different order. If there is a control appearing multiple times in the original tuner method file, when written out, it will be combined into a single line with multiple values.

This section can be empty. When both the fixed and the tunable secitons are empty, the tuner will then use a pre-defined factory tuner method.

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:

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

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

The Barrier Log

The first line of the barrier log displays statistics about the Cholesky decomposition needed by the barrier algorithm. This line contains the following values:

During the barrier optimization, a summary log is displayed in every iteration. This summary log has the form:

After the barrier algorithm a crossover procedure may be applied. This process prints at most 3 log lines about the different phases of the crossover procedure. The structure of these lines follows The Simplex Log described in the section above.

If BAROUTPUT is set to 0, no log is displayed until the barrier algorithm finishes.

The Global Log

During the branch and bound tree search (see XPRSglobal (GLOBAL)), a summary log of nine columns of information is frequently printed. By default, the printing frequency increases over time. If MIPLOG is explicitly set to a negative value -n, a log line will be printed every n nodes. The nine columns consist of:

This log is also printed when an integer feasible solution is found. An asterisk (*) printed in front of the node number indicates that a solution has been found by an integral LP relaxation. Single characters indicate that a heuristic solution has been found. Lower case characters stand for different strategies of the Optimizer's diving heuristic: the letter a corresponds to strategy 1, the letter b to strategy 2, and so forth. Compare control HEURDIVESTRATEGY. By default, several strategies are applied. Upper case letters stand for special search heuristics. More precisely, R, L, M, C, U, and Z stand for the different modes of local search that can be selected by controls HEURSEARCHROOTSELECT and HEURSEARCHTREESELECT. For technical reasons, a U might also appear after a restart. The letter F represents the feasibility pump, T stands for a trivial heuristic. S, G, and B are reserved for special purpose heuristics for problems with set packing/partitioning constraints, GUBs, and branching on constraints, respectively. An I or an E indicate that a solution has been found while interdiction branching or the calculation of branching estimates.

During root node cutting, the column Node is replaced by two columns Its and Type, columns Active and Depth are replaced by Add and Del, respectively. These have the following meaning:

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

Not all the information described above is present for all nodes. If the LP relaxation is cut off, only Branch and Parent (and possibly Solution) are displayed. If the LP relaxation is infeasible, only Branch and Parent appear. The rest of the line will consist of a text message relaxation exceeds cutoff or relaxation infeasible. 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 1, the tree node logs are surpressed, but cutting loop logs will still be displayed. If MIPLOG is set to 0, neither cut nor node log wil be pritned. In any case, LP logs and intermediate status messages might still be printed.

The Tuner Log

While the tuner evaluates various control settings, it prints a summary log for each finished run. When tuning a MIP problem, the summary log consists of eight columns of information:

When tuning an LP problem, the summary log consists of five columns of information:

When the tuner finds an improving control setting, it will highlight the run with an asterisk (*) at the beginning of the log line. The tuner will also specify the control parameters and the log file name for the improving run.

If a control setting has been evaluated in previous tuner runs, its result can be reused. In this case, the tuner will print an extra H in the Stat column.