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

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

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

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.

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.

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

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.

It is important to note that you will only be able to use this section if your FICO Xpress Optimizer is licensed for Mixed 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 Mixed 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 Mixed 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.

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.

Note that the FICO Xpress Optimizer can only solve convex (MI)QPs. Thus quadratic rows must be of type <= or >=, and the quadratic matrix should be positive semi-definite for <= rows and negative semi-definite for >= rows so that the defined region is convex. Otherwise the problem will need to be solved by the nonlinear solver.

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.

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