Try our new documentation site (beta).
MPS format
MPS format is the oldest and most widely used format for storing math programming models. There are actually two variants of this format in wide use. In fixed format, the various fields must always start at fixed columns in the file. Free format is very similar, but the fields are separated by whitespace characters instead of appearing in specific columns. One important practical difference between the two formats is in name length. In fixed format, row and column names are exactly 8 characters, and spaces are part of the name. In free format, names can be arbitrarily long (although the Gurobi reader places a 255 character limit on name length), and names may not contain spaces. The Gurobi MPS reader reads both MPS types, and recognizes the format automatically.
Note that any line that begins with the *
character is a
comment. The contents of that line are ignored.
NAME section
The first section in an MPS format file is the NAME
section.
It gives the name of the model:
NAME AFIROIn fixed format, the model name starts in column 15.
OBJSENSE section
The OBJSENSE
section is an optional section for maximizing the objective
function. By default, Gurobi assumes the objective function of an MPS file
should be minimized, in which case the OBJSENSE
section can be omitted.
To instruct Gurobi to maximize the objective function, add the line
OBJSENSE MAXafter the
NAME
section.
ROWS section
The next section is the ROWS
section. It begins with the word
ROWS
on its own line, and continues with one line for each row
in the model. These lines indicate the constraint type (E
for
equality, L
for less-than-or-equal, or G
for
greater-than-or-equal), and the constraint name. In fixed format, the
type appears in column 2 and the row name starts in column 5. Here's
a simple example:
ROWS E R09 E R10 L X05 N COSTNote that an
N
in the type field indicates that the row is a
free row. The first free row is used as the objective
function.
If the file includes multiple N
rows, each including a
priority, weight, relative, and absolute tolerance field, then each
such row is treated as an objective in a multi-objective model. The
additional fields must appear after the name, separated by spaces.
For example, the following would capture a pair of objectives, where
the first has priority 2 and the second has priority 1 (and both have
identical weights, and relative and absolute tolerances):
N OBJ0 2 1 0 0 N OBJ1 1 1 0 0Please refer to the multi-objective, ObjNPriority, ObjNWeight, ObjNAbsTol, and ObjNRelTol sections for information on the meanings of these fields. Note that all objectives of a multi-objective optimization problem have to be linear.
LAZYCONS section
The next section is the LAZY CONSTRAINTS
section. It begins with the
line LAZYCONS
, optionally followed by a space and a laziness level 1-3
(if no laziness level is specified 1 is assumed), and continues with one
line for each lazy constraint. The format is the same as that of the
ROWS
section: each line indicates the constraint type (E
for
equality, L
for less-than-or-equal, or G
for
greater-than-or-equal), and the constraint name. In fixed format, the type
appears in column 2 and the row name starts in column 5. For example:
LAZYCONS E R01 G R07 L S01 LAZYCONS 2 E R02 G R03 L S11
Lazy constraints are linear constraints, and they are semantically
equivalent to standard linear constraints (i.e., entries in the ROWS
section). 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.
USERCUTS section
The next section is the USER CUTS
section. It begins with the
line USERCUTS
, on its own line, and continues with one
line for each user cut. The format is the same as that of the
ROWS
section: each line indicates the constraint type (E
for
equality, L
for less-than-or-equal, or G
for
greater-than-or-equal), and the constraint name. In fixed format, the type
appears in column 2 and the row name starts in column 5. For example:
USERCUTS E R01 G R07 L S01
User cuts are linear constraints, and they are semantically
equivalent to standard linear constraints (i.e., entries in the ROWS
section). Please refer to the description of the
Lazy attribute for details.
This section is optional.
COLUMNS section
The next and typically largest section of an MPS file is the
COLUMNS
section, which lists the columns in the model and the
non-zero coefficients associated with each. Each line in the columns
section provides a column name, followed by either zero, one, or two
non-zero coefficients from that column. Coefficients are specified
using a row name first, followed by a floating-point value. Consider
the following example:
COLUMNS X01 X48 .301 R09 -1. X01 R10 -1.06 X05 1. X02 X21 -1. R09 1. X02 COST -4.The first line indicates that column
X01
has a non-zero in row
X48
with coefficient .301
, and a non-zero in row
R09
with coefficient -1.0
. Note that multiple lines
associated with the same column must be contiguous in the file.
In fixed format, the column name starts in column 5, the row name for the first non-zero starts in column 15, and the value for the first non-zero starts in column 25. If a second non-zero is present, the row name starts in column 40 and the value starts in column 50.
Integrality markers
The COLUMNS
section can optionally include integrality markers. The
variables introduced between a pair of markers must take integer values.
All variables within markers will have a default lower bound of 0 and a
default upper bound of 1 (other bounds can be specified in the
BOUNDS
section). The beginning of an integer section is marked by
an INTORG
marker:
MARK0000 'MARKER' 'INTORG'The end of the section is marked by an
INTEND
marker:
MARK0000 'MARKER' 'INTEND'The first field (beginning in column 5 in fixed format) is the name of the marker (which is ignored). The second field (in column 15 in fixed format) must be equal to the string
'MARKER'
(including the single quotes).
The third field (in column 40 in fixed format) is 'INTORG'
at the
start and 'INTEND'
at the end of the integer section.
The COLUMNS
section can contain an arbitrary number of such
marker pairs.
RHS section
The next section of an MPS file is the RHS
section, which
specifies right-hand side values. Each line in this section may
contain one or two right-hand side values.
RHS B X50 310. X51 300. B X05 80. X17 80.The first line above indicates that row
X50
has a right-hand
side value of 310
, and X51
has a right-hand side value
of 300
. In fixed format, the variable name for the first
bound starts in column 15, and the first bound value starts in column
25. For the second bound, the variable name starts in column 40 and
the value starts in column 50. The name of the RHS is specified in
the first field (column 5 in fixed format), but this name is ignored
by the Gurobi reader. If a row is not mentioned anywhere in the
RHS
section, that row takes a right-hand side value of
0
. You may define an objective offset by setting the negative
offset as right-hand side of the objective row. For example, if the
linear objective row in the problem is called COST
and you
want to add an offset of 1000 to your objective function, you can
add the following to the RHS
section:
RHS RHS1 COST -1000
BOUNDS section
The next section in an MPS file is the optional BOUNDS
section. By default, each variable takes a lower bound of 0 and an
infinite upper bound. Each line in this section can modify the lower
bound of a variable, the upper bound, or both. Each line indicates a
bound type (in column 2 in fixed format), a bound name (ignored), a
variable name (in column 15 in fixed format), and a bound value (in
columns 25 in fixed format). The different bound types, and the
meaning of the associate bound value, are as follows:
LO | lower bound |
UP | upper bound |
FX | variable is fixed at the specified value |
FR | free variable (no lower or upper bound) |
MI | infinite lower bound |
PL | infinite upper bound |
BV | variable is binary (equal 0 or 1) |
LI | lower bound for integer variable |
UI | upper bound for integer variable |
SC | upper bound for semi-continuous variable |
SI | upper bound for semi-integer variable |
Consider the following example:
BOUNDS FR BND X49 UP BND X50 80. LO BND X51 20. FX BND X52 30.In this
BOUNDS
section, variable X49
gets a lower bound of
-infinity
(infinite upper bound is unchanged), variable X50
gets a
upper bound of 80
(lower bound is unchanged at 0
, X51
gets a lower bound of 20
(infinite upper bound is unchanged), and
X52
is fixed at 30
.
QUADOBJ section
The next section in an MPS file is the optional QUADOBJ
section, which contains quadratic objective terms. Each line in this
section represents a single non-zero value in the lower triangle of
the Q matrix. The names of the two variable that participate in the
quadratic term are found first (starting in columns 5 and 15 in fixed
format), followed by the numerical value of the coefficient (in column
25 in fixed format). By convention, the Q matrix has an implicit
one-half multiplier associated with it. Here's an example containing
three quadratic terms:
QUADOBJ X01 X01 10.0 X01 X02 2.0 X02 X02 2.0These three terms would represent the quadratic function (recall that the single off-diagonal term actually represents a pair of non-zero values in the symmetric Q matrix).
QCMATRIX section
The next section in an MPS file contains zero or more QCMATRIX
blocks. These blocks contain the quadratic terms associated with the
quadratic constraints. There should be one block for each quadratic
constraint in the model.
Each QCMATRIX
block starts with a line that indicates the name
of the associated quadratic constraint (starting in column 12 in fixed
format). This is followed by one of more quadratic terms. Each term
is described on one line, which gives the names of the two
involved variables (starting in columns 5 and 15 in fixed format),
followed by the coefficient (in column 25 in fixed format).
For example:
QCMATRIX QC0 X01 X01 10.0 X01 X02 2.0 X02 X01 2.0 X02 X02 2.0These four lines describe three quadratic terms: quadratic constraint
QC0
contains terms , , and .
Note that a QCMATRIX
block must contain a symmetric matrix, so
for example an X01*X02
term must be accompanied by a matching
X02*X01
term.
Linear terms for quadratic constraint QC0
appear in the
COLUMNS
section. The sense and right-hand side value appear in
the ROWS
and RHS
sections, respectively.
PWLOBJ section
The next section in an MPS file is the optional PWLOBJ
section,
which contains piecewise-linear objective functions. Each line in
this section represents a single point in a piecewise-linear objective
function. The name of the associated variable appears first (starting
in column 4), followed by the x and y coordinates of the point
(starting in columns 14 and 17). Here's an example containing two
piecewise-linear expressions, for variables X01
and X02
,
each with three points:
X01 1 1 X01 2 2 X01 3 4 X02 1 1 X02 3 5 X02 7 10
SOS section
The next section in an MPS file is the optional SOS
section.
The representation for a single SOS constraint contains one line that
provides the type of the SOS set (S1
for SOS type 1 or
S2
for SOS type 2, found in column 2 in fixed format) and the
name of the SOS set (column 5 in fixed format) of the SOS set. This
is followed by one line for each SOS member. The member line gives
the name of the member (column 5 in fixed format) and the associated
weight (column 15 in fixed format). Here's an example containing two
SOS2 sets.
SOS S2 sos1 x1 1 x2 2 x3 3 S2 sos2 x3 1 x4 2 x5 3
Indicator Constraint section
The indicator constraint section is optional in the MPS format. It
starts with the keyword INDICATORS
. Each subsequent line of the
indicator section starts with the keyword IF
(placed at column
2 in fixed format) followed by a space and a row name (the row must
have already been defined in the ROWS
section). The line
continues with a binary variable (placed at column 15 in fixed format)
and finally a value 0
or 1
(placed at column 25 in fixed
format).
Here a simple example:
INDICATORS IF row1 x1 0 IF row2 y1 1
The first indicator constraint in this example states that row1
has to be fulfilled if the x1
takes a value of 0
.
General Constraint section
An MPS file may contain an optional section that captures general
constraints. This section starts with the keyword GENCONS
.
General constraints can be of two basic types: simple general constraints - MIN, MAX, OR, AND, NORM, ABS or PWL, or function constraints - polynomial (POLY), power (POW), exponential ( EXP or EXPA), logarithmic (LOG, LOGA), or logistic (LOGISTIC), and trigonometric functions (SIN, COS, or TAN).
Each general constraint starts with a general constraint type specifier (MIN, MAX, OR, AND, NORM, ABS, PWL, POLY, POW, EXP, EXPA, LOG, LOGA, LOGISTIC, SIN, COS, or TAN), found in column 2 in fixed format. Optionally a space and a constraint name may follow. For a NORM constraint, the norm type (0, 1, 2, or INF) follows the type specifier (and is optionally followed by a constraint name).
For function constraints, the next line defines a few attributes used
to perform the piecewise-linear approximation. The line starts with
the keyword Options (found in column 5 in fixed format),
followed by two spaces, followed by four values (separated by two
spaces) that define the FuncPieces
, FuncPieceLength
,
FuncPieceError
, and FuncPieceRatio
attribute values
(in that order).
What follows depends on the general constraint type. Simple general constraints start with the name of the so-called resultant variable, placed on it's own line (starting at column 5 in fixed format). For MIN or MAX constraints, a non empty list of variables or values follows (with each variable name on its own line). For OR, AND, and NORM constraints, a list of variables follows (each on its own line). The variables must be binary for OR and AND constraints. For ABS constraints, only one additional variable follows (on its own line). In fixed format, all of these variables or values begin in column 5.
Piecewise-linear constraints start with the name of the so-called operand variable (starting at column 5 in fixed format), followed by the so-called resultant variable. The next lines contain the piecewise-linear function breakpoints, each represented as pair of x and y values. The x values must be non-decreasing.
Function constraints also start with the name of the operand variable (starting at column 5 in fixed format), followed by two spaces, followed by the name of the resultant variable. This is sufficient to define EXP LOG, LOGISTIC, SIN, COS, and TAN functions. The POW, EXPA and LOGA functions require an exponent or base, respectively, which is defined on the next line (starting in column 5 in fixed format). For the polynomial function, the following lines contain a coefficient (at column 5 in fixed format), followed by two spaces, followed by the associated power (natural numbers only). Note that powers must be decreasing.
The other general constraint type, the INDICATOR constraint,
appears in a separate Indicator
section, which is described
above.
The following shows an example of a general constraint section:
GENCONS MAX gc0 r1 x1 x2 x10 0.7 MIN gencons1 r2 y0 10 y1 r1 AND and1 r b1 b2 OR or1 r b3 b4 NORM 2 norm2 r3 x1 y1 z1 ABS GC14 xabs x PWL GC0 x[0] y[0] -1 2 0 1 0 0 0 1 1 2 POLY GC2 Options 0 0.01 0.001 -1 x y 4 7 2 3 SIN gc1 Options 0 0.01 1e-05 0.5 y z LOGA gc6 Options 0 0.01 0.001 -1 x y 10 EXPA gc4 Options 0 0.01 0.001 -1 y z 3
For more information, consult the general constraint discussion.
Scenario section
An MPS 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 keyword SCENARIOS
, followed by the
number of scenarios. 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).
Each scenario starts with the keyword NAME
(starting at column
2 in fixed format), followed by a scenario name.
Changes to the objective function are defined in the COLUMNS
subsection (starting at column 2 in fixed format). Each objective
change is on its own line; that line contains the variable name
(starting at column 5 in fixed format), the objective name (starting
at column 15 in fixed format), and the modified objective value
(starting at column 25 in fixed format). The format is similar to the
columns section above.
Changes to the right-hand sides of linear constraints are defined in
the RHS
subsection (starting at column 2 in fixed format).
Each right-hand side change is on its own line; that line contains
a right-hand side specifier (starting at column 5 in fixed format),
the constraint name (starting at column 15 in fixed format), and the
right-hand side value (starting at column 25 in fixed format). The
format is similar to the right-hand side section above.
Changes to variable bounds are defined in the BOUNDS
subsection. Each changed variable bound is on its own line. The
format is similar to the bounds section above (with a small difference
that the first and second column in fixed format are 5 and 8,
respectively).
The following example shows three scenarios in MPS format:
SCENARIOS 3 NAME scenario0 NAME scenario1 COLUMNS x1 OBJ 0 x2 OBJ 1 RHS RHS1 c1 2 RHS1 c2 2 BOUNDS FR BND1 x1 LO BND1 x3 0.5 UP BND1 x3 1.5 FX BND1 x2 0 NAME scenario2 BOUNDS FX BND1 x3 3
For more information, consult the multiple scenario discussion.
ENDATA
The final line in an MPS file must be an ENDATA
statement.
Additional notes
Note that in the Gurobi optimizer, MPS models are always written in full precision. That means that if you write a model and then read it back, the data associated with the resulting model will be bit-for-bit identical to the original data.