Log and File Formats

Topics covered in this chapter:

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
.csv	Output file, output by XPRSiiswrite.	ASCII
.dir	Directives file (MIP only), input by XPRSreaddirs (READDIRS).	ASCII
.glb	Tree file (MIP only), used by XPRSmipoptimize (MIPOPTIMIZE).	Binary
.hdr	Solution header file, output by XPRSwritesol (WRITESOL).	ASCII
.lp	LP format matrix file, input by XPRSreadprob (READPROB).	ASCII
.mps	MPS / XMPS format matrix file, input by XPRSreadprob (READPROB).	ASCII
.prt	Fixed format solution file, output by XPRSwriteprtsol (WRITEPRTSOL).	ASCII
.sol	Solution file created by XPRSwritebinsol (WRITEBINSOL).	Binary
.slx	Solution file created by XPRSwriteslxsol (WRITESLXSOL).	ASCII
.xtm	Tuner method created by XPRStunerwritemethod.	ASCII
.xtr	Tuner result created by XPRStune.	XML
.json	Remote Solving Configuration file	JSON

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

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

File Compression

Many Optimizer commands support reading and writing compressed files. Support for Gzip compression is built in, so commands like the following will work as expected:

readprob problem.mat.gz
writeprob problem.gz

The Optimizer can also support additional compression formats, as long as the necessary command-line tools are available in the PATH environment variable. The following table shows the supported compression formats along with the required tools:

Extension	Required Tool
gz	Built-in support
zip	zip / unzip
tar, tgz	tar
bz2, bzip2	bzip2
7z	7z / 7za / 7zr
xz	xz
lz4	lz4
Z	compress / decompress

In addition, the 7z tool can be used to read and write most of the formats listed above.

NB: compression using external tools is not supported in cloud environments due to security restrictions.

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:

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 / QMATRIX	introduces a quadratic objective function;
QCMATRIX	introduces the quadratic constraints;
DELAYEDROWS	introduces the delayed rows;
MODELCUTS	introduces the model cuts;
INDICATORS	introduces the indicator contraints;
SETS	introduces SOS definitions;
RHS	introduces the right hand side(s);
RANGES	introduces the row ranges;
BOUNDS	introduces the bounds;
GENCONS	introduces general constraints;
ENDATA	signals the end of the matrix.
compatibility	additional sections for extensions of the MPS format that can be read but not written.

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	Field 3	Field 4	Field 5	Field 6
type	row_name	priority	weight	abstol	reltol

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.

Fields 3-6 are used for multi-objective problems, and they may only be populated for neutral rows (objectives). In a multi-objective problem, you must specify either the weight and priority of every objective, or you must specify the weight, priority, absolute and relative tolerances for every objective. No other combination of fields is valid, in order to remain compatible with older MPS files. For more information about multi-objective problems, please refer to Multi-objective Optimization.

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 (i.e., the quadratic part of the objective) has an implicit factor of 0.5 when included in the objective function.
This means, for instance that an objective function of the form

\[ 5x^2 + 7xy + 9y^2 \]

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.

Format:	Cols 1-8	Field 3
	QCMATRIX	row_name

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:

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

\[ qc1: x + 5 x^2 + 7 xy + 9 y^2 \leq 2 \]

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

The FICO Xpress Optimizer can solve both convex and non-convex (MI)QPs and (MI)QCPs. For non-convex problems, some of the restrictions of FICO Xpress Global apply, e.g., callback usability is limited. A quadratic problem is convex, when the Q matrix of the objective is positive semi-definite for minimization and negative semi-definite for maximization. A quadratically constrained problem is convex, when all row Q matrices are positive semi-definite for \( \leq \) rows and negative semi-definite for \( \geq \) rows. For convex (MI)QCPs, equations must not contain a quadratic part.

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 tree 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.

Format:	Cols 1-11
	DELAYEDROWS

followed by row definitions in the format:

Field 1	Field 2
type	row_name

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 tree 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.

Format:	Cols 1-9
	MODELCUTS

followed by row definitions in the format:

Field 1	Field 2
type	row_name

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

Format:	Cols 1-10
	INDICATORS

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

Field 1	Field 2	Field 3	Field 4
type	row_name	col_name	value

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)

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.

GENCONS section

Format:	Cols 1-7
	GENCONS

This record introduces the section which specifies any general constraints, namely min, max, and, or, abs, pwl constraints. If present it must appear after the COLUMNS section. It is followed by a record which specifies the type and name of each general constraint, as defined below.

Field 1	Field 2
type	name

Where type is MAX for a maximum-constraint, MIN for a minimum-constraint, AND for an and-constraint, OR for an or-constraint, ABS for an absolute-value-constraint or PWL for a piecewise linear constraint and name is the name of the general constraint.

Subsequent records for min/max/and/or/abs give the elements for the constraint and are of the form:

Field 1	Field 2
blank	col/val

For all general constraints, the first given element (which needs to be the name of a column) will be the so-called "resultant". For the max- and min-constraints, the resultant is followed by an arbitrary number of further column names or values, and the resultant should be the maximum/minimum of the remaining columns and values. For the and- and or-constraints the resultant is followed by an arbitrary number of further column names, where all the columns (including the resultant) need to be binary, and the resultant will be one if and only if all (and) or at least one (or) of the remaining variables are one. For the abs-constraint, the resultant should be followed by exactly one futher column name, and the resultant will take the absolute value of the other column.

As an example, the constraint z = max {x, y, 5.0} could be written as

 GENCONS
 MAX m1
	z
	x
	y
	5.0

For piecewise linear constraints the format is slightly different, consisting of exactly one line of the form:

Field 1	Field 2
col1	col2

and at least three lines of the form:

Field 1	Field 2
val1	val2

The first line defines the two variables that should be restricted by a piecewise linear relationship and the points given in the remaining lines will define the piecewise linear function, which is extended beyond the first and last point according to the slope of the previous ones. For instance the piecewise linear constraint

y = 0, if x < 0
y = x, if 0 <= x <= 5
y = 2x - 5, if 5 < x <= 10
y = 15, if x > 10

could be represented as:

 GENCONS
 PWL p1
    x  y
	-1 0
	0  0
	5  5
	10 15
	11 15

ENDATA section

Format:	Cols 1-6
	ENDATA

is the last record of the file.

Compatibility

The optimizer is also able to read in some further sections defined by extensions of the LP format. This includes the SOS section, which is a different way of writing down special ordered sets, and the following sections that offer different ways of formulating piecewise linear constraints and objectives:

PWLOBJ section

Piecewise linear objective functions may be added using PWLOBJ sections.

Format:	Cols 1-6
	PWLOBJ

The piecewise linear objective function is defined via its extreme points, i.e., the function itself is given by all convex combinations of neighboring extreme points as well as the infinite rays defined by the first two and last two points. Each row of the PWLOBJ section defines one extreme point for one column.

Field 1	Field 2	Field 3	Field 4
blank	col	value1	value2

where col is the variable whose objective contribution is defined through the piecewise linear function and value2 is the objective contribution if the variable takes value1. For instance the piecewise linear objective function

0, if x < 0
x, if 0 <= x <= 5
2x - 5, if 5 < x <= 10
15, if x > 10

could be represented as:

PWLOBJ
   x         -1 0
   x         0  0
   x         5  5
   x         10 15
   x         11 15

If there are piecewise linear objective functions for multiple variables, these should be given consecutively (i.e., first all extreme points for x, then all for y). Furthermore, for each variable, the extreme points should be sorted according to non-decreasing value1. The piecewise linear functions do not necessarily need to be continuous, in this case two extreme points with identical value1 and different value2 can be given and the first one will be used as the lefthand-limit and the second one as the righthand-limit. Note that for value1 itself, both value2 can appear in the solution due to tolerances.

PWLNAM section

PWLNAM is the first of the two sections defining piecewise linear constraints.

Format:	Cols 1-6
	PWLNAM

Similar to the piecewise linear objective, the piecewise linear constraints will mainly be defined through its extreme points, which happens in the PWLCON section. In addition to that, however, the two variables involved in the restriction y = f(x), with piecewise linear function f, need to be specified, and additionally a pre- and postslope are given, defining the slope of the piecewise linear function before the first and after the last extreme point. Each piecewise linear function needs to be named, to later refer to it in the PWLCON section when specifying the extreme points.

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

where col1 is the resulting variable (y above), col2 is the input variable (x above), value1 is the preslope defining the piecewise linear function up to the first extreme point and value1 is the postslope defining it after the last extreme point.

PWLCON section

PWLCON is the second of the two sections defining piecewise linear constraints.

Format:	Cols 1-6
	PWLCON

Each piecewise linear constraint introduced in the PWLNAM section needs to be further specified through its extreme points, defining the behaviour between the pre- and postlope. Each line consists of the name of a piecewise linear constraint introduced in the PWLNAM followed by a list of extreme points. Similar to the PWLOBJ section, the functions can be discontinuous, in which case the extreme points have to be given in the correct order.

Field 1	Field 2	Field 3	Field 4
blank	name	value1	value2

where name is the name of a piecewise linear function introduced in the PWLNAM section and value1 and value2 define an extreme point, where value1 is the value of the input variable and value1 is the corresponding output value. For instance the piecewise linear constraint

y = 0, if x < 0
y = x, if 0 <= x <= 5
y = 2x - 5, if 5 < x <= 10
y = 15, if x > 10

could be represented as:

PWLNAM
 pwc1	 y		   x1			  0			0
PWLCON
 pwc1		  0			0
 pwc1		  5			5
 pwc1		  10		15

LP File Format

Matrices can be represented in text files using either the MPS file format (.mps or .mat 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. There is no maximum on the length names of on the length of input 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_PLUSINFINITY].
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 integers	s.i.	A list of semi-integer bound expressions for variables.
partial integer	p.i.	A list of variable names of partial integer variables.
general constraints	general constraint gencons g.c.	A list of min/max/and/or/abs and piecewise linear constraints.
ranges	range	A list of constraint ranges.

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.

Names

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

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

A name can not begin with a number, a period, a comma, a slash or parenthesis and should not be the same as any of the section or subsection names. Care should be taken using the characters E or e since these may be interpreted as exponential notation for numbers.

Curly braces ({ and }) cannot be used in Xpress LP files since these are used as delimiters in non-linear formulas.

The @ (at) character has a special meaning in Xpress: it is used to escape characters that are otherwise invalid in LP files. See also the ESCAPENAMES control.

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

No line continuation character is required to break the objective function across multiple lines and it can be broken wherever you may use white space.

The objective function can be named in the same way as for constraints (see later).

Multiple objectives

For multi-objective problems, the priority, weight, absolute and relative tolerances can be specified before the objective expression, for example:

Minimize
Obj1: Priority=3
x1 + x2
Obj2: Priority=2 Weight=-1
x3 - x4
Obj3: Priority=1 AbsTol=1 RelTol=0.01
x5 + 2 x6

For more information about multi-objective problems, please refer to Multi-objective Optimization.

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 <=.

No line continuation character is required when breaking a constraint across multiple lines, 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 and variables declared in the generals section, the interval defined by the default bounds is [0, XPRS_PLUSINFINITY], while for variables declared in the integers section (see later) the relaxation interval defined by the default bounds is [0, 1]. Note that the constant XPRS_PLUSINFINITY is 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 the objective section or in the constraint section is ignored.

If multiple lower bounds or multiple upper bounds are defined for the same variable, only the last definition is applied. For example, if the bounds section contains the following bound definitions on a variable x

-1 <= x <= 1
x <= 2

then the first upper bound of x <= 1 will be ignored due to the second definition of x <= 2. The resulting bounds will be -1 <= x <= 2.

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_PLUSINFINITY. 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 the objective section or in a constraint in the constraint section is ignored.

Semi-continuous and semi-integer

The semi-continuous and semi integers 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 integers) 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 integers) section are a list of white space or carriage return delimited entries that are variable name-number pair. For the semi-continuous secion it is also possible to provide a variable name only. 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 integers
x7 >= 3
x9 > 5

Note that it is possible to use either the >= token or the > token. The resulting threshold will be identical for both cases. It is not possible to use 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.

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.

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

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 + [ x1^2 + 4 x1 * x2 + 3 x2^2 ] /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.

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.

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.

The FICO Xpress Optimizer can solve both convex and non-convex (MI)QCPs. For non-convex problems, some of the restrictions of FICO Xpress Global apply, e.g., callback usability is limited. A quadratically constrained problem is convex, when all quadratic row matrices are positive semi-definite for \( \leq \) rows and negative semi-definite for \( \geq \) rows. For convex (MI)QCPs, equations must not contain a quadratic part.

General Constraints

The general constraints section started by the record General Constraints specifies min, max, and, or, abs and piecewise linear constraints. Each line defines one such constraint, beginning with a name, followed by a colon, a resultant variable, a sign, a keyword and further variables (or breakpoints for the piecewise linear constraints) in brackets with spaces and commas. The keywords are MAX for a maximum-constraint, MIN for a minimum-constraint, AND for an and-constraint, OR for an or-constraint, ABS for an absolute-value-constraint and PWL for a piecewise linear constraint. For the max- and min-constraints, the resultant is followed by an arbitrary number of further column names or values, and the resultant should be the maximum/minimum of the remaining columns and values. For the and- and or-constraints the resultant is followed by an arbitrary number of further column names, where all the columns (including the resultant) need to be binary, and the resultant will be one if and only if all (and) or at least one (or) of the remaining variables are one. For the abs-constraint, the resultant should be followed by exactly one further column name, and the resultant will take the absolute value of the other column. For the piecewise linear constraints, there needs to be exactly one input variable, followed by a colon and a list of breakpoints. Note that general constraints may only introduce new variables if they are placed immediately after the subject to (or delayed rows, model cuts or pwl) sections. An example for a max-constraint would be

 myCons: m = MAX ( x , y , 0.0 )

An example for a piecewise linear constraint would be

 myPwl: y = PWL ( x ): (-1,-1) (0,0) (10,20) (10,0) (11,0)

defining that y = f(x), where f is a piecewise linear function with value x if x is negative, y = 2x if 0 <= x <= 10 and y = 0 if x is larger than 10.

Constraint ranges

Constraint ranges may be defined in a section beginning with the keyword ranges. Each range definition must be on a separate line, and must specify an upper and lower range for a named constraint that has previously been defined in the constraints section.

For example:

Minimize
x1 + x2
subject to
c1: x + y <= 10
ranges
1 <= c1 <= 10
end

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.

Compatibility to other extensions

The FICO Xpress Optimizer is also able to read (but not write) further sections defined by extensions of the LP format. These include the SOS section, as a different way of defining special orderred sets, and the PWLObj and PWL sections for piecewise linear objective and constraints.

The piecewise linear objective section is started by the PWLObj line. It is followed by lines consisting of one variable name and a list of extreme points defining the piecewise linear objective function for this variable. For example the line

 x: (-1,-1) (0,0) (10,20) (10,0) (11,0)

defines that if x is negative, the objective contribution is x. If x is between 0 and 10, then the objective contribution is 2x and if x is larger than 10, then the objective contribution is 0. For each variable, the extreme points should be sorted according to non-decreasing variable value. The piecewise linear functions do not necessarily need to be continuous, in this case two extreme points with identical variable values and different function values can be given and the first one will be used as the lefthand-limit and the second one as the righthand-limit. Note that for the point where the discontinuity appears, both function values can appear in the solution due to tolerances.

The piecewise linear constraint section is started by the PWL keyword. Each piecewise linear constraint defines a restriction y = f(x), where f is a piecewise linear function. The lines in the input format consist of a name, the input variable, a preslope, the extreme points and a postslope. The preslope defines the function before the first extreme point and the postslope defines it after the last one. Discontinuities are possible as for the objective function. Note that pwl sections may only introduce new variables if they are placed immediately after the subject to (or delayed rows, model cuts or general constraints) sections. Above example would look as follows, assuming that instead of the objective it now defines the value of a variable y :

 pwlc1: y = x 1 (0,0) (10,20) (10,0) 0

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:

C	optimization interrupted (like ctrl-c);
O	optimal;
N	infeasible;
S	stability problems;
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) name;
3	string	3	variable type (C=column; N, L, G, E for rows);
4	string	4	variable status (LL, **, BS, UL, EQ, SB 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 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:

**	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.

In case there is a basis available, sensitivity analysis values may be included in the output by passing the s flag.

The rows section is extended with two new columns, presenting the range of the RHS in which it can be changed before it affects the optimality or feasibiltiy of the current basis.

Rows Section
                                                                                       RHS Sensitivity
   Number    Row     At      Value      Slack Value   Dual Value        RHS       Lower Range   Upper Range
 G      1  third     LL     15.000000       .000000     10.571428     15.000000     10.199999     25.000002

For the columns section, objective ranges are added.

Columns Section
                                                                      Objective Sensitivity
   Number   Column   At      Value      Input Cost   Reduced Cost   Lower Range   Upper Range
 C     58  c         BS      2.742857      5.849999       .000000       .999998      8.350002

A third section presents the sensitivity values for the column bounds.

Bound sensitivity
                                  Lower Bound Sensitivity                   Upper Bound Sensitivity
   Number   Column   At   Lower Range      Bound      Upper Range   Lower Range      Bound      Upper Range
 C     58  d         BS  -1.00000E+20       .000000      2.742857      2.742857     10.000000   1.00000E+20

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:

Field	Type	Width	Description
1	char	1	variable type;
2	string	variable	name of variable;
3	real	variable	value of activity.

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

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

name

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)
DR	a delayed row entry (value is not used)
BR	force the optimizer to branch on the entity even if it is satisfied. If a node solution is MIP feasible, the Optimizer will first branch on any branchable entity flagged with BR before returning the solution.

name is the name of a MIP entity (column or special ordered set), a row (for types MC and DR), 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. Note that a whitespace character encountered within the name field will signal the end of the name field and the start of the value field. To match an entity or row whose name contains whitespace characters, convert the name into a mask by replacing each whitespace character with by a ?.

value is the value to accompany the type.

For example:

PR x1* 2

gives MIP 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.

Field	Description
Name	Name of a row or column in conflict.
Type	Type of conflicting variable (row or column).
Sense	Sense of conflicting variable: (LE or GE) to indicate or rows. (LO or UP) to indicate lower or upper bounds for columns.
Bound	Value associated with the variable, i.e. RHS for rows and bound values for columns.
Dual value	The dual multipliers corresponding to the contradiction deducible from the IIS. Summing up all the rows and columns in the IIS multiplied by these values yields a contradicting constraint. This value is negative for <= rows and upper bounds, and positive for >= rows and lower bounds.
In iso	Indicates if the row or column is in isolation.

Note that each IIS may contain a row or column with only one of its possible senses. This also means that for 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:

N	for the new row type to be unconstrained;
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.
R	for the new row type to be a range row.

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).

When turning a row to ranged row, a third entry, the range, is expected to be defined following **NTR. The rules for changing a row to a ranged row follow that of XPRSchgrhsrange.

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 similar to the following:

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
  HEUREMPHASIS         = 0,1
  SBESTIMATE           = 1, 2, 3, 4, 5, 6
  HEURSEARCHROOTCUTFREQ= 2, 5
  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 multiple 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.

For bit vector controls, such as PRESOLVEOPS, SCALING, or HEURSEARCHROOTSELECT, it is possible to either specify concrete assignments to the control or to specify individual bits that should be used for tuning. In the latter case, one has to use a colon instead of an equals sign. For example, "SCALING = 24, 675" will tune using the two given concrete values 24 and 675, while "SCALING : 3, 4, 9" will individually toggle bits 3, 4, and 9 of the default value for SCALING and potentially also try combinations of those later during tuning.

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 at regular time intervals, determined by an internal deterministic timer. 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 LPLOGSTYLE to 0 and 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 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:

Dense cols	The number of dense columns identified in the factorization.
NZ(L)	The number of nonzero elements in the Cholesky factorization.
Flops	The number of floating point operations needed to perform one factorization.

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

Its	The number of iterations taken so far.
P.inf	Maximal violation of primal constraints.
D.inf	Maximal violation of dual constraints.
U.inf	Maximal violation of upper bounds.
Primal obj	Value of the primal objective function.
Dual obj	Value of the dual objective function.
Compl	Value of the average complementarity.

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 Hybrid Gradient Log

The content and format of the log messages of the Hybrid Gradient method are identical to those of the Newton Barrier method, with a few minor differences. Since there is no Cholesky factorization that table is not printed. Upper bound infeasibility is always 0, simply by the design of the algorithm.

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

The MIP Log

During the branch and bound tree search (see XPRSmipoptimize (MIPOPTIMIZE)), 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:

Node	A sequential node number.
BestSoln	The value of the best integer solution found so far.
BestBound	A bound on the value of the optimal integer solution.
Sols	The number of integer solutions that have been found.
Active	The number of active (unsolved) 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 MIP infeasibilities at the current node.
Time	The time taken.

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 E indicates that a solution has been found during the calculation of branching estimates. P stands for heuristics that run in parallel to the MIP root node. A stands for the Shift-and-propagate heuristic. When solving with Xpress Global, an N indicates that an integer feasible node solution has been extended to a MINLP solution using a local solver.

Note that heuristic solutions found before the tree search (and thereby the MIP log) starts, are reported with a special log line of the form:

 *** Solution found:     <SolVal>   Time:   <Time>    Heuristic: <DispChar> ***

Here <SolVal> and <Time> are numeric values indicating the solution value of the found heuristic solution and the run time after which it was found, respectively. The single <DispChar> character indicates which heuristic found the solution.

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:

Its	A counter for the number of cutting plane separation loops.
Type	The type of cuts that have been generated this round: G -- Gomory cuts, M -- model cuts, O -- outer approximation cuts (only for nonlinear problems), N -- network-based cuts, K -- any other type of cuts
Add	Number of cuts added to the LP relaxation in this iteration
Del	Number of cuts deleted from the LP relaxation in this iteration

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

Branch	A sequential node number.
Parent	The node number of the parent of the current node. A D or a U marks whether the current node is the down child or the up child, respectively, of its parent.
Solution	The optimal value of the LP relaxation at the current node.
Entity	The MIP entity on which the Optimizer will branch after this node.
Value	The current value of the entity chosen for branching.
Active	The number of active nodes in the tree search.
GInf	The number of violated MIP entities
Time	The time taken.

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 IIS Log

While the IIS procedure is searching for a minimal set of restrictions that cause the infeasibility of the instance it prints a summary log periodically. The IIS log consists of three columns of information. This is repeated for each restriction type (rows, columns, discrete entities). The restriction type is printed before the log.

Remaining	The number of restrictions of the given type that still need to be checked by the deletion filter.
In IIS	The number of restrictions of the given type that are verified to be necessary for the IIS.
Time (s)	The total time spent in the IIS procedure (in seconds).

The printing of the IIS log can be disabled using the IISLOG control. A similar log is printed while searching for isolations.

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:

RunID	A sequential tuner run number.
Stat	Status of a finished run: S - Solved, T - Timeout, U - Unsolved and C - Cancelled.
Solution	The best integer solution.
Bound	The best bound.
Integral	The primal dual integral.
Gap	The relative MIP gap.
RunTime	The time spent for solving with this control setting.
TotTime	The total time spent for the tuner.

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

RunID	A sequential tuner run number.
Stat	Status of a finished run: S - Solved, T - Timeout, U - Unsolved and C - Cancelled.
Solution	The LP objective.
RunTime	The time spent for solving with this control setting.
TotTime	The total time spent for the tuner.

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.

The Remote Solving Configuration file

This configuration file allows the user to control some of the ways the Xpress solver interacts with the remote Insight Compute Interface. It contains advanced configuration settings; it is expected that most users will not need to use these configuration options.

To use the configuration file, set the environment variable XPRESS_COMPUTE_CONFIG to the full path of the file including the file name itself; you must also set the XPRESS_COMPUTE and XPRESS_COMPUTE_URL environment variables to activate remote solving in the usual way. Changes to the configuration are only read when the Optimizer is first initialized with XPRSinit.

The configuration file must be a valid JSON document, containing a single object with key-value pairs. All keys are optional and Xpress will use sensible defaults for anything you do not specify. For example:

{
  "logLevel": 101,
  "caCertsPath": "C:/xpressmp/ssl/ca-bundle.crt"
}

The remainder of this section details the individual keys that can be set.

caCertsPath

This field can be set to the absolute path of the certificate bundle file to use for authenticating SSL certificates when communicating with a remote server using HTTPS. If unspecified, Xpress will look for a file ca-bundle.crt in the path specified by the MOSEL_SSL environment variable (if set), or the .mmssl folder of the user's home directory (if not). If this file does not exist, it can be created in the default location by executing the command mmssl setup

For example:

{
  "caCertsPath": "C:/xpressmp/ssl/ca-bundle.crt"
}

cleanupJobs

This field controls whether Xpress should delete a compute job from the remote server when it successfully completes or is interrupted. The default is false. Set to true to automatically delete successfully completed jobs from the Insight Compute Interface.

For example:

{
  "cleanupJobs": true
}

executionService

This field contains the name of the Insight execution service that will be used for jobs. If unset, the Insight server's default execution service is used. Where the execution service name is set in the configuration file and the COMPUTEEXECSERVICE control, the value from the control will be used.

For example:

{
  "executionService": "SECONDARY"
}

logLevel

This field controls additional lines written to the problem's log that describe communication between the local Xpress application and the remote Insight Compute Interface. (Note it doesn't affect lines written by the remote Insight Compute Interface itself.) Supported levels are:

• 0 - write no extra log lines
• 1 - write error and warning messages only
• 2 - write error, warning and notification messages (the default)
• 101 - as 2, but also write lines for every HTTP request made and event message received from the server
• 102 - as 101, but include extra debugging output. Should be set on the advice of FICO product support only.

For example:

{
  "logLevel": 0
}

maxRetries

This field controls how many times a failed request to the remote server will be retried before we show an error to the user. There will be an exponentially increasing delay before each retry (0ms, 200ms, 400ms, 800ms, etc) - the default setting of 9 means we try each request for about 51 seconds before the user is informed of an error. Set to a lower value if you want to see errors quicker, or 0 to disable retries entirely.

For example:

{
  "maxRetries": 2
}

priority

This field controls the default priority of compute jobs created on the Xpress Insight Compute Interface. It should be a number between -100 and 100, with priority 0 used if not specified. If the priority is set to a nonzero value in both the configuration file and the COMPUTEJOBPRIORITY control, the value from the control will be used.

For example:

{
  "priority": 90
}

trustSrv

This field controls whether Xpress should trust the remote server without checking its certificate, when an HTTPS URL is used. If set to false, the authenticity of the remote server is checked using the list of trusted certification authorities and the operation will be aborted if the verification fails. Set to true if you want to use a server that has a known invalid or self-signed certificate, and acknowledge the security risks this brings. Default is false.

For example:

{
  "trustSrv": true
}