Skip to content

Commit

Permalink
added mps to docs
Browse files Browse the repository at this point in the history
  • Loading branch information
pchtsp committed Dec 16, 2020
1 parent 81cd3d4 commit fbc3198
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 17 deletions.
12 changes: 8 additions & 4 deletions HISTORY
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,23 @@
# Copyright S.A.Mitchell ([email protected]), 2007-
# Copyright F.Peschiera ([email protected]), 2019-
# See the LICENSE file for copyright information.
2.4 2020-12-22
added mps reading support
updated docs
fix bug with no objective in prob.toDict()
2.3.1 2020-10-22
change naming of solver utility functions to camelcase.
fixed gurobi license detection.
change naming of solver utility functions to camelcase
fixed gurobi license detection
fixed scip options and added timeLimit argument
changed docs.
changed docs
2.3 2020-08-04
Added plugin page in docs
Standardize arguments of solvers to appear in docs
Fixes to import and export of LpProblem and solver
Added warm start to GUROBI
2.2 2020-04-06
Contribution files
Standard arguments: logPath, gapRel, gapAbs.
Standard arguments: logPath, gapRel, gapAbs
Import and export solver objects
Import and export LpProblem
Took out amply to its own package
Expand Down
74 changes: 63 additions & 11 deletions doc/source/guides/how_to_export_models.rst
Original file line number Diff line number Diff line change
@@ -1,29 +1,36 @@
How to export models in PuLP
======================================
How to import and export models in PuLP
==========================================

Exporting a model can be useful when the building time takes too long or when the model needs to be passed to another computer to solve. Or many other reason.
PuLP offers a way to export a model into a dictionary of a json file. The json file saves enough data to be able to rebuild a new model on reading it.
Exporting a model can be useful when the building time takes too long or when the model needs to be passed to another computer to solve. Or any other reason.
PuLP offers two ways to export a model: to an mps file or to a dictionary /json file. Each offers advantages over the other.

**The mps format** is an industry standard. But it is not very flexible so some information cannot be stored. It stores only variables and constraints. It does not store the values of variables.

**The dictionary/ json format** is made to fit how pulp stores the information and so it does not lose information: this format file saves enough data to be able to restore a complete pulp model on reading it.

The interface to import and export for both formats is similar as can be seen in the Example 1 below.

Considerations
------------------

The following considerations need to be taken into account:

#. Variable names need to be unique. PuLP permits having variable names because it uses an internal code for each one. But we do not export that code. So we identify variables by their name only.
#. Variables are not exported in a grouped way. This means that if you had several `dictionaries of many variables each` you will end up with a very long list of variables. This can be seen in the Example 2.
#. Output information is also written. This means that the status, solution status, the values of variables and shadow prices / reduced costs are exported too. This means that it is possible to export a model that has been solved and then read it again only to see the values of the variables.
#. Variables are not exported in a grouped way. This means that if you have several `dictionaries of many variables each` you will end up with a very long list of variables. This can be seen in the Example 2.
#. Output information is also written to the json format. This means that the status, solution status, the values of variables and shadow prices / reduced costs are exported too. This means that it is possible to export a model that has been solved and then read it again only to see the values of the variables.
#. For json, we use the base `json` package. But if `ujson` is available, we use that so the import / export can be really fast.

Example 1
Example 1: json
----------------

A very simple example taken from the internal tests. Imagine the following problem::

from pulp import *
prob = LpProblem("test_export_dict_MIP", const.LpMinimize)

prob = LpProblem("test_export_dict_MIP", LpMinimize)
x = LpVariable("x", 0, 4)
y = LpVariable("y", -1, 1)
z = LpVariable("z", 0, None, const.LpInteger)
z = LpVariable("z", 0, None, LpInteger)
prob += x + 4 * y + 9 * z, "obj"
prob += x + y <= 5, "c1"
prob += x + z >= 10, "c2"
Expand Down Expand Up @@ -82,7 +89,6 @@ We now have a dictionary with a lot of data::
'upBound': None,
'varValue': None}]}


We can now import this dictionary::

var1, prob1 = LpProblem.from_dict(data)
Expand Down Expand Up @@ -111,9 +117,48 @@ And the result will be available in our *new* variables::
# 3.0


Example 2
Example 1: mps
----------------

The same model::

from pulp import *
prob = LpProblem("test_export_dict_MIP", LpMinimize)
x = LpVariable("x", 0, 4)
y = LpVariable("y", -1, 1)
z = LpVariable("z", 0, None, LpInteger)
prob += x + 4 * y + 9 * z, "obj"
prob += x + y <= 5, "c1"
prob += x + z >= 10, "c2"
prob += -y + z == 7.5, "c3"

We can now export the problem into an mps file::

prob.writeMPS("test.mps")

We can now import this file::

var1, prob1 = LpProblem.fromMPS("test.mps")
var1
# {'x': x, 'y': y, 'z': z}
prob1
# test_export_dict_MIP:
# MINIMIZE
# 1*x + 4*y + 9*z + 0
# SUBJECT TO
# c1: x + y <= 5
# c2: x + z >= 10
# c3: - y + z = 7.5
# VARIABLES
# x <= 4 Continuous
# -1 <= y <= 1 Continuous
# 0 <= z Integer

The resulting tuple is exactly the same format as the previous one.

Example 2: json
------------------

We will use as example the model in :ref:`set-partitioning-problem`::

import pulp
Expand Down Expand Up @@ -179,3 +224,10 @@ And inspect some of the values::

wedding_vars["table_('M',_'N')"].value()
# 1.0


Grouping variables
------------------------------------

As the "Considerations" section mentions, the grouping of variables is not restored automatically. Nevertheless, by using some strict naming convention on variable names and clever parsing, one can reconstruct the original structure of the variables.

2 changes: 1 addition & 1 deletion pulp/apis/coin_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ def getOptions(self):
)

return [v.format(self.optionsDict[k]) for k, v in params_eq.items()
if k in self.optionsDict]
if self.optionsDict.get(k) is not None]

def readsol_MPS(self, filename, lp, vs, variablesNames, constraintsNames, objectiveName=None):
"""
Expand Down
2 changes: 1 addition & 1 deletion pulp/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
This file contains the constant definitions for PuLP
Note that hopefully these will be changed into something more pythonic
"""
VERSION = '2.3.1'
VERSION = '2.4'
EPS = 1e-7

# variable categories
Expand Down

0 comments on commit fbc3198

Please sign in to comment.