# Documentation

##

LP format

The LP format captures an optimization model in a way that is easier for humans to read than MPS format, and can often be more natural to produce. One limitation of the LP format is that it doesn't preserve several model properties. In particular, LP files do not preserve column order when read, and they typically don't preserve the exact numerical values of the coefficients (although this isn't inherent to the format).

Unlike MPS files, LP files do not rely on fixed field widths. Line breaks and whitespace characters are used to separate objects. Here is a simple example:

\ LP format example Maximize x + y + z Subject To c0: x + y = 1 c1: x + 5 y + 2 z <= 10 qc0: x + y + [ x ^ 2 - 2 x * y + 3 y ^ 2 ] <= 5 Bounds 0 <= x <= 5 z >= 2 Generals x y z End

The backslash symbol starts a comment; the remainder of that line is ignored.

Variable names play a major role in LP files. Each variable must have its
own unique name. A name should be no longer than 255 characters, and to
avoid confusing the LP parser, it should not begin with a number, or
contain any of the characters
`+, -, *, ^, <, >, =, (, ), [, ], ,, or :`

or whitespace. Also,
variable names should not be equal (case insensitive) to any of the LP file
format keywords, e.g., `st, bounds, min, max, binary, or end`

.

The same rules apply to any other type of names in the LP format, e.g., constraint names or the objective name.

Note that whitespace characters are not optional in the Gurobi LP format. Thus,
for example, the text `x+y+z`

would be treated as a single
variable name, while `x + y + z`

would be treated as a three
term expression.

LP files are structured as a list of sections, where each section captures a logical piece of the whole optimization model. Sections begin with particular keywords, and must generally come in a fixed order, although a few are allowed to be interchanged.

Objective Section

The first section in an LP file is the objective section. This section begins with one of the following six keywords: minimize, maximize, minimum, maximum, min, or max. Capitalization is ignored. This keyword may appear alone, or it may be immediately followed by multi-objectives, which indicates that the model contains multiple objective functions.

Single-Objective Case

Let us consider single-objective models first, where this header is followed by a single linear or quadratic expression that captures the objective function.

The objective optionally begins with a label. A label consists of a name, followed by a colon character, following by a space. A space is allowed between the name and the colon, but not required.

The objective then continues with a list of linear terms, separated by
the `+`

or `-`

operators. A term can contain a
coefficient and a variable (e.g., `4.5 x`

), or just a variable
(e.g., `x`

). The objective can be spread over many lines, or it
may be listed on a single line. Line breaks can come between tokens,
but never within tokens.

The objective may optionally continue with a list of quadratic terms.
The quadratic portion of the objective expression begins with a
`[`

symbol and ends with a `]`

symbol, followed by
`/ 2`

. These brackets should enclose one or more quadratic terms.
Either squared terms (e.g., `2 x ^ 2`

) or product terms
(e.g., `3 x * y`

) are accepted. Coefficients on the quadratic
terms are optional.

For variables with piecewise-linear objective functions, the objective
section will include a `__pwl(x)`

term, where `x`

is the
name of the variable. You should view these as comments; they are
ignored by the LP reader. The actual piecewise-linear expressions are
pulled from the later `PWLObj`

section.

The objective expression must always end with a line break.

An objective section might look like the following:

Minimize obj: 3.1 x + 4.5 y + 10 z + [ x ^ 2 + 2 x * y + 3 y ^ 2 ] / 2

Multi-Objective Case

In the multi-objective case, the header is followed by one or more
linear objective functions, where each starts with its own sub-header. The
sub-header gives the name of the objective, followed by a number of
fields that provide a Priority, Weight,
absolute tolerance (AbsTol) and relative tolerance
(RelTol) for that objective (see
ObjNPriority,
ObjNWeight,
ObjNAbsTol, and
ObjNRelTol for details on the meanings
of these fields).
The fields start with the field
name, followed by a `=`

, followed by the value. For
example:

OBJ0: Priority=2 Weight=1 AbsTol=0 RelTol=0Please refer to the multi-objective section for additional details.

Each sub-header is followed by a linear expression that captures that objective.

A complete multi-objective section might look like the following:

Minimize multi-objectives OBJ0: Priority=2 Weight=1 AbsTol=0 RelTol=0 3.1 x + 4.5 y + 10 z OBJ1: Priority=1 Weight=1 AbsTol=0 RelTol=0 10 x + 0.1 y

The objective section is optional. The objective is set to 0 when it is not present.

Constraints Section

The next section is the constraints section. It begins with one of the
following headers, on its own line: *subject to*,
*such that*, *st*, or *s.t.*.
Capitalization is ignored.

The constraint section can have an arbitrary number of constraints.
Each constraint starts with an optional label (constraint name,
followed by a colon, followed by a space), continues with a linear
expression, followed by an optional quadratic expression (enclosed
in square brackets), and ends with a comparison operator, followed by a
numerical value, followed by a line break. Valid comparison
operators are `=`

, `<=`

, `<`

, `>=`

, or
`>`

. Note that LP format does not distinguish between strict and
non-strict inequalities, so for example `<`

and `<=`

are
equivalent.

Note that the left-hand side of a constraint may not contain a constant term; the constant must appear on the right-hand side.

The following is a simple example of a valid linear constraint:

c0: 2.5 x + 2.3 y + 5.3 z <= 8.1The following is a valid quadratic constraint:

qc0: 3.1 x + 4.5 y + 10 z + [ x ^ 2 + 2 x * y + 3 y ^ 2 ] <= 10

The constraint section may also contain another constraint type: the
so-called indicator constraint. Indicator constraints start with an
optional label (constraint name, followed by a colon, followed by a
space), followed by a binary variable, a space, a `=`

, again a
space and a value, either `0`

or `1`

. They continue with a
space, followed by `->`

, and again a space and finally a linear
constraint (without a label).

For example:

c0: b1 = 1 -> 2.5 x + 2.3 y + 5.3 z <= 8.1

This example constraint requires the given linear constraint to be
satisfied if the variable `b1`

takes a value of `1`

.

Every LP format file must have a constraints section.

Lazy Constraints Section

The next section is the lazy constraints section. It begins with the line
`Lazy Constraints`

, optional followed by a space and a laziness level
1-3 (if no laziness level is specified 1 is assumed), and continues with a
list of linear constraints in the exact same format as the linear
constraints in the constraints section. For example:

Lazy Constraints c0: 2.5 x + 2.3 y + 5.3 z <= 8.1 Lazy Constraints 2 c1: 1.5 x + 3.3 y + 4.3 z <= 8.1

Lazy constraints are linear constraints, and they are semantically equivalent to standard linear constraints. Depending on their laziness level they are enforced differently by the MIP solver. Please refer to the description of the Lazy attribute for details.

This section is optional.

Bounds Section

The next section is the bounds section. It begins with the word
`Bounds`

, on its own line, and is followed by a list of variable
bounds. Each line specifies the lower bound, the upper bound, or both
for a single variable. The keywords `inf`

or `infinity`

can be used in the bounds section to specify infinite bounds. A bound
line can also indicate that a variable is `free`

, meaning that
it is unbounded in either direction.

Here are examples of valid bound lines:

0 <= x0 <= 1 x1 <= 1.2 x2 >= 3 x3 free x2 >= -Inf

It is not necessary to specify bounds for all variables; by default, each variable has a lower bound of 0 and an infinite upper bound. In fact, the entire bounds section is optional.

Variable Type Section

The next section is the variable types section. Variables can be designated as being either binary, general integer, or semi-continuous. In all cases, the designation is applied by first providing the appropriate header (on its own line), and then listing the variables that have the associated type. For example:

Binary x y zVariable type designations don't need to appear in any particular order (e.g., general integers can either precede or follow binaries). If a variable is included in multiple sections, the last one determines the variable type.

Valid keywords for variable type headers are: *binary*, * binaries*, *bin*, *general*, *generals*, * gen*, *semi-continuous*, *semis*, or *semi*.

The variable types section is optional. By default, variables are assumed to be continuous.

SOS Section

An LP file can contain a section that captures SOS constraints of type
1 or type 2. The SOS section begins with the `SOS`

header on
its own line (capitalization isn't important). An arbitrary number of
SOS constraints can follow. An SOS constraint starts with a name,
followed by a colon (unlike linear constraints, the name is not
optional here). Next comes the SOS type, which can be either
`S1`

or `S2`

. The type is followed by a pair of colons.

Next come the members of the SOS set, along with their weights. Each member is captured using the variable name, followed by a colon, followed by the associated weight. Spaces can optionally be placed before and after the colon. An SOS constraint must end with a line break.

Here's an example of an SOS section containing two SOS constraints:

SOS sos1: S1 :: x1 : 1 x2 : 2 x3 : 3 sos2: S2 :: x4:8.5 x5:10.2 x6:18.3

The SOS section is optional.

PWLObj Section

An LP file can contain a section that captures piecewise-linear
objective functions. The PWL section begins with the `PWLObj`

header on its own line (capitalization isn't important). Each
piecewise-linear objective function is associated with a model
variable. A PWL function starts with the corresponding variable name,
followed immediately by a colon (the name is not optional). Next come
the points that define the piecewise-linear function. These points
are represented as `(x, y)`

pairs, with parenthesis surrounding
the two values and a comma separating them. A PWL function must end
with a line break.

Here's an example of a PWLObj section containing two simple piecewise-linear functions:

PWLObj x1: (1, 1) (2, 2) (3, 4) x2: (1, 3) (3, 5) (100, 300)

The PWLObj section is optional.

General Constraint Section

An LP file may contain an optional section that captures *general
constraints*. This section starts with one of the
following keywords *general constraints*, *general constraint*,
*gencons*, or *g.c.* (capitalization is ignored).

General constraints can be of two basic types: *simple* general
constraints - *MIN*, *MAX*, *OR*, *AND*,
*ABS*, or *PWL*, or *function* constraints -
polynomial (`POLY`

), power (`POW`

), exponential (`EXP`

or `EXPA`

), logarithmic (`LOG`

or `LOGA`

), or
trigonometric (`SIN`

, `COS`

, or `TAN`

).

A simple general constraint starts with an optional label (constraint
name, followed by a colon), followed by a variable name (the so-called
*resultant*), then an equals sign `=`

. The line continues
with a general constraint type specifier (*MIN*, *MAX*,
*OR*, *AND*, or *ABS*), then a `(`

. All tokens
must be separated using spaces. Capitalization is ignored.

What follows depends on the general constraint type. *MIN* or
*MAX* constraints expect a non-empty, comma-separated list of
variables or values. *OR* and *AND* constraints expect a
comma-separated list of binary variables. *ABS* constraints only
expect one variable name. Again, all tokens (including commas) must
be separated using spaces.

All of these general constraints end with a `)`

and a line break.

Here are a few examples:

gc0: r1 = MAX ( x1 , x2 , x10 , 0.7 ) gencons1: r2 = MIN ( y0 , 10 , y1 , r1 ) and1: r = AND ( b1 , b2 ) or1: r = OR ( b3 , b4 ) GC14: xabs = ABS ( x )

Piecewise-linear constraints also start with an optional label (constraint
name, followed by a colon). The line continues with a variable name (the
so-called *resultant*) and an equal sign `=`

. Next comes the
keyword *PWL* that indicates that the constraint is of type
piecewise-linear. This is followed by a `(`

, and then by a variable
name (the so-called *operand*) followed by a `)`

. The line
continues with a `:`

and then the list of piecewise-linear breakpoints
in parentheses (e.g., (x0, y0) (x1, y1)) with non-decreasing values on x.
Recall that spaces are required between tokens.

Here an example:

GC0: y[0] = PWL ( x[0] ) : (-1, 2) (0, 1) (0, 0) (0, 1) (1, 2)

There is one other type of simple constraint, the
*INDICATOR* constraint. Those appear in the regular
constraints section (described above), not in the general
constraint section.

Function constraints also start with an optional label (constraint
name, followed by a colon). An optional list of attribute assignments
follows. These start with a `(`

, then a space-separate list of
`Name=Value`

strings (no spaces before or after the `=`

),
closed with a `)`

. An example is shown below. Default values
are used if no attributes are specified.

The line continues with a variable name (the so-called *resultant*)
and an equal sign `=`

. Next comes a keyword that indicates the type
of function being defined (*POLY*, *POW*, *EXP*, * EXPA*, *LOG*, *LOG_A*, *SIN*, *COS*, or * TAN*). For a *LOG*, use *LOG_A* if it isn't a natural
log, where is the base. This is followed by a `(`

, and then by
the expression that defines the actual function. The line closes with a
`)`

. Recall that spaces are required between tokens.

Polynomials and powers are described in what is hopefully the natural
way, with exponents preceded by the `^`

symbol.

The following give examples of a few function constraints:

gc1: ( PieceError=1e-05 PieceRatio=0.5 ) z = SIN ( y ) GC2: ( PieceLength=0.001 ) y = POLY ( 5 x ^ 3 + 2 x + 5 ) gc3: z = EXPA ( 3.5 ^ y ) gc4: z = LOG_10 ( y ) logytoz: z = LOG ( y )

For more information, consult the general constraint discussion.

Scenario Section

An LP file may contain an optional section that captures scenario data. A model can have multiple scenarios, where each defines a set of changes to the original model (which we refer to as the base model).

This section starts with the *Scenario* keyword (capitalization
is ignored), followed by a scenario name. Scenarios are described as a
set of changes to the objective function, the right-hand sides of
linear constraints, and the bounds of variables. Objective changes
are stated first, followed by right-hand side changes, then bound
changes. A scenario can be empty (i.e., identical to the base model).

Changes to the objective function start with one of the allowed
objective keywords (`Minimize`

, `Maximize`

, etc.; see
objective section above for additional information). Note that the
keyword needs to match the objective sense of the base model. This is
followed by a line for each changed objective coefficient that
contains the variable name and its modified value (separated by a
space).

Changes to the right-hand sides of linear constraints start with one
of the allowed constraint section keywords (`Subject To`

, etc.;
see the constraints section above for additional information). This
is followed by a line for each changed right-hand side value that
contains the constraint name followed by a colon, then a space, the
constraint sense, a space, and the scenario right-hand side value.

Changes to variable bounds start with the `Bounds`

keyword. This
is followed by a line for each variable with changed scenario bounds;
the format of each such line is the same as in the bounds section above.

The following example shows three scenarios in LP format:

Scenario scenario0 Scenario scenario1 Maximize x1 0 x2 1 Subject To c1: <= 2 c2: >= 2 Bounds x3 <= 1.5 x1 free 0 <= x2 <= 0 x3 >= 0.5 Scenario scenario2 Bounds x3 = 3

For more information, consult the multiple scenario discussion.

End statement

The last line in an LP format file should be an `End`

statement.