{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# The Transport Problem\n", "\n", "## Summary\n", "\n", "The goal of the Transport Problem is to select the quantities of an homogeneous good that has several production plants and several punctiform markets as to minimise the transportation costs.\n", "\n", "It is the default tutorial for the GAMS language, and GAMS equivalent code is inserted as single-dash comments. The original GAMS code needs slighly different ordering of the commands and it's available at http://www.gams.com/mccarl/trnsport.gms.\n", "\n", "## Problem Statement\n", "\n", "The Transport Problem can be formulated mathematically as a linear programming problem using the following model. \n", "\n", "### Sets\n", "\n", " $I$ = set of canning plants \n", " $J$ = set of markets\n", "\n", "### Parameters\n", "\n", " $a_i$ = capacity of plant $i$ in cases, $\\forall i \\in I$
\n", " $b_j$ = demand at market $j$ in cases, $\\forall j \\in J$
\n", " $d_{i,j}$ = distance in thousands of miles, $\\forall i \\in I, \\forall j \\in J$
\n", " $f$ = freight in dollars per case per thousand miles
\n", " $c_{i,j}$ = transport cost in thousands of dollars per case\n", " \n", " $c_{i,j}$ is obtained exougenously to the optimisation problem as $c_{i,j} = f \\cdot d_{i,j}$, $\\forall i \\in I, \\forall j \\in J$\n", " \n", "### Variables\n", " $x_{i,j}$ = shipment quantities in cases
\n", " z = total transportation costs in thousands of dollars\n", "\n", "### Objective\n", "\n", "Minimize the total cost of the shipments:
\n", "$\\min_{x} z = \\sum_{i \\in I} \\sum_{j \\in J} c_{i,j} x_{i,j}$\n", "\n", "### Constraints\n", "\n", "\n", "Observe supply limit at plant i:
\n", " $\\sum_{j \\in J} x_{i,j} \\leq a_{i}$, $\\forall i \\in I$\n", " \n", "Satisfy demand at market j:
\n", " $\\sum_{i \\in I} x_{i,j} \\geq b_{j}$, $\\forall j \\in J$\n", "\n", "Non-negative transportation quantities
\n", " $x_{i,j} \\geq 0$, $\\forall i \\in I, \\forall j \\in J$" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Pyomo Formulation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Creation of the Model\n", "\n", "In pyomo everything is an object. The various components of the model (sets, parameters, variables, constraints, objective..) are all attributes of the main model object while being objects themselves.\n", "\n", "There are two type of models in pyomo: A `ConcreteModel` is one where all the data is defined at the model creation. We are going to use this type of model in this tutorial. Pyomo however supports also an `AbstractModel`, where the model structure is firstly generated and then particular instances of the model are generated with a particular set of data.\n", "\n", "The first thing to do in the script is to load the pyomo library and create a new `ConcreteModel` object. We have little imagination here, and we call our model \"model\". You can give it whatever name you want. However, if you give your model an other name, you also need to create a `model` object at the end of your script:" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Import of the pyomo module\n", "from pyomo.environ import *\n", " \n", "# Creation of a Concrete Model\n", "model = ConcreteModel()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Set Definitions\n", "\n", "Sets are created as attributes object of the main model objects and all the information is given as parameter in the constructor function. Specifically, we are passing to the constructor the initial elements of the set and a documentation string to keep track on what our set represents: " ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "collapsed": true }, "outputs": [], "source": [ "## Define sets ##\n", "# Sets\n", "# i canning plants / seattle, san-diego /\n", "# j markets / new-york, chicago, topeka / ;\n", "model.i = Set(initialize=['seattle','san-diego'], doc='Canning plans')\n", "model.j = Set(initialize=['new-york','chicago', 'topeka'], doc='Markets')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Parameters\n", "\n", "Parameter objects are created specifying the sets over which they are defined and are initialised with either a python dictionary or a scalar: " ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "## Define parameters ##\n", "# Parameters\n", "# a(i) capacity of plant i in cases\n", "# / seattle 350\n", "# san-diego 600 /\n", "# b(j) demand at market j in cases\n", "# / new-york 325\n", "# chicago 300\n", "# topeka 275 / ;\n", "model.a = Param(model.i, initialize={'seattle':350,'san-diego':600}, doc='Capacity of plant i in cases')\n", "model.b = Param(model.j, initialize={'new-york':325,'chicago':300,'topeka':275}, doc='Demand at market j in cases')\n", "# Table d(i,j) distance in thousands of miles\n", "# new-york chicago topeka\n", "# seattle 2.5 1.7 1.8\n", "# san-diego 2.5 1.8 1.4 ;\n", "dtab = {\n", " ('seattle', 'new-york') : 2.5,\n", " ('seattle', 'chicago') : 1.7,\n", " ('seattle', 'topeka') : 1.8,\n", " ('san-diego','new-york') : 2.5,\n", " ('san-diego','chicago') : 1.8,\n", " ('san-diego','topeka') : 1.4,\n", " }\n", "model.d = Param(model.i, model.j, initialize=dtab, doc='Distance in thousands of miles')\n", "# Scalar f freight in dollars per case per thousand miles /90/ ;\n", "model.f = Param(initialize=90, doc='Freight in dollars per case per thousand miles')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "A third, powerful way to initialize a parameter is using a user-defined function.\n", "\n", "This function will be automatically called by pyomo with any possible (i,j) set. In this case pyomo will actually call `c_init()` six times in order to initialize the `model.c` parameter. " ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Parameter c(i,j) transport cost in thousands of dollars per case ;\n", "# c(i,j) = f * d(i,j) / 1000 ;\n", "def c_init(model, i, j):\n", " return model.f * model.d[i,j] / 1000\n", "model.c = Param(model.i, model.j, initialize=c_init, doc='Transport cost in thousands of dollar per case')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Variables\n", "\n", "Similar to parameters, variables are created specifying their domain(s). For variables we can also specify the upper/lower bounds in the constructor.\n", "\n", "Differently from GAMS, we don't need to define the variable that is on the left hand side of the objective function. " ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "collapsed": true }, "outputs": [], "source": [ "## Define variables ##\n", "# Variables\n", "# x(i,j) shipment quantities in cases\n", "# z total transportation costs in thousands of dollars ;\n", "# Positive Variable x ;\n", "model.x = Var(model.i, model.j, bounds=(0.0,None), doc='Shipment quantities in case')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Constrains\n", "\n", "At this point, it should not be a surprise that constrains are again defined as model objects with the required information passed as parameter in the constructor function. " ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "collapsed": true }, "outputs": [], "source": [ "## Define contrains ##\n", "# supply(i) observe supply limit at plant i\n", "# supply(i) .. sum (j, x(i,j)) =l= a(i)\n", "def supply_rule(model, i):\n", " return sum(model.x[i,j] for j in model.j) <= model.a[i]\n", "model.supply = Constraint(model.i, rule=supply_rule, doc='Observe supply limit at plant i')\n", "# demand(j) satisfy demand at market j ; \n", "# demand(j) .. sum(i, x(i,j)) =g= b(j);\n", "def demand_rule(model, j):\n", " return sum(model.x[i,j] for i in model.i) >= model.b[j] \n", "model.demand = Constraint(model.j, rule=demand_rule, doc='Satisfy demand at market j')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The above code take advantage of [list comprehensions](https://docs.python.org/2/tutorial/datastructures.html#list-comprehensions), a powerful feature of the python language that provides a concise way to loop over a list. If we take the supply_rule as example, this is actually called two times by pyomo (once for each of the elements of i). Without list comprehensions we would have had to write our function using a for loop, like: " ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "collapsed": true }, "outputs": [], "source": [ "def supply_rule(model, i):\n", " supply = 0.0\n", " for j in model.j:\n", " supply += model.x[i,j]\n", " return supply <= model.a[i]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Using list comprehension is however quicker to code and more readable. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Objective and Solving\n", "\n", "The definition of the objective is similar to those of the constrains, except that most solvers require a scalar objective function, hence a unique function, and we can specify the sense (direction) of the optimisation. " ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "collapsed": true }, "outputs": [], "source": [ "## Define Objective and solve ##\n", "# cost define objective function\n", "# cost .. z =e= sum((i,j), c(i,j)*x(i,j)) ;\n", "# Model transport /all/ ;\n", "# Solve transport using lp minimizing z ;\n", "def objective_rule(model):\n", " return sum(model.c[i,j]*model.x[i,j] for i in model.i for j in model.j)\n", "model.objective = Objective(rule=objective_rule, sense=minimize, doc='Define objective function')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As we are here looping over two distinct sets, we can see how list comprehension really simplifies the code. The objective function could have being written without list comprehension as: " ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "collapsed": true }, "outputs": [], "source": [ "def objective_rule(model):\n", " obj = 0.0 \n", " for ki in model.i:\n", " for kj in model.j:\n", " obj += model.c[ki,kj]*model.x[ki,kj]\n", " return obj" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Retrieving the Output\n", "\n", "We use the `pyomo_postprocess()` function to retrieve the output and do something with it. For example, we could display solution values (see below), plot a graph with [matplotlib](http://matplotlib.org/) or save it in a csv file.\n", "\n", "This function is called by pyomo after the solver has finished. " ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "collapsed": true }, "outputs": [], "source": [ "## Display of the output ##\n", "# Display x.l, x.m ;\n", "def pyomo_postprocess(options=None, instance=None, results=None):\n", " model.x.display()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can print model structure information with `model.pprint()` (“pprint” stand for “pretty print”).\n", "Results are also by default saved in a `results.json` file or, if PyYAML is installed in the system, in `results.yml`.\n", "\n", "### Editing and Running the Script\n", "\n", "Differently from GAMS, you can use whatever editor environment you wish to code a pyomo script. If you don't need debugging features, a simple text editor like Notepad++ (in windows), gedit or kate (in Linux) will suffice. They already have syntax highlight for python.\n", "\n", "If you want advanced features and debugging capabilities you can use a dedicated Python IDE, like e.g. Spyder.\n", "\n", "You will normally run the script as `pyomo solve –solver=glpk transport.py`. You can output solver specific output adding the option `–stream-output`. If you want to run the script as `python transport.py` add the following lines at the end:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "# ==========================================================\n", "# = Solver Results =\n", "# ==========================================================\n", "# ----------------------------------------------------------\n", "# Problem Information\n", "# ----------------------------------------------------------\n", "Problem: \n", "- Name: unknown\n", " Lower bound: 153.675\n", " Upper bound: 153.675\n", " Number of objectives: 1\n", " Number of constraints: 6\n", " Number of variables: 7\n", " Number of nonzeros: 13\n", " Sense: minimize\n", "# ----------------------------------------------------------\n", "# Solver Information\n", "# ----------------------------------------------------------\n", "Solver: \n", "- Status: ok\n", " Termination condition: optimal\n", " Statistics: \n", " Branch and bound: \n", " Number of bounded subproblems: 0\n", " Number of created subproblems: 0\n", " Error rc: 0\n", " Time: 0.03862881660461426\n", "# ----------------------------------------------------------\n", "# Solution Information\n", "# ----------------------------------------------------------\n", "Solution: \n", "- number of solutions: 0\n", " number of solutions displayed: 0\n", "\n", "Displaying Solution\n", "------------------------------------------------------------\n", "x : Shipment quantities in case\n", " Size=6, Index=x_index\n", " Key : Lower : Value : Upper : Fixed : Stale : Domain\n", " ('san-diego', 'chicago') : 0.0 : 0.0 : None : False : False : Reals\n", " ('san-diego', 'new-york') : 0.0 : 325.0 : None : False : False : Reals\n", " ('san-diego', 'topeka') : 0.0 : 275.0 : None : False : False : Reals\n", " ('seattle', 'chicago') : 0.0 : 300.0 : None : False : False : Reals\n", " ('seattle', 'new-york') : 0.0 : 0.0 : None : False : False : Reals\n", " ('seattle', 'topeka') : 0.0 : 0.0 : None : False : False : Reals\n" ] } ], "source": [ "# This is an optional code path that allows the script to be run outside of\n", "# pyomo command-line. For example: python transport.py\n", "if __name__ == '__main__':\n", " # This emulates what the pyomo command-line tools does\n", " from pyomo.opt import SolverFactory\n", " import pyomo.environ\n", " opt = SolverFactory(\"glpk\")\n", " results = opt.solve(model)\n", " #sends results to stdout\n", " results.write()\n", " print(\"\\nDisplaying Solution\\n\" + '-'*60)\n", " pyomo_postprocess(None, model, results)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Finally, if you are very lazy and want to run the script with just `./transport.py` (and you are in Linux) add the following lines at the top: " ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "collapsed": true }, "outputs": [], "source": [ "#!/usr/bin/env python\n", "# -*- coding: utf-8 -*-" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Complete script\n", "\n", "Here is the complete script: " ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "#!/usr/bin/env python\r\n", "# -*- coding: utf-8 -*-\r\n", "\r\n", "# Import\r\n", "from pyomo.environ import *\r\n", " \r\n", "# Creation of a Concrete Model\r\n", "model = ConcreteModel()\r\n", " \r\n", "## Define sets ##\r\n", "# Sets\r\n", "# i canning plants / seattle, san-diego /\r\n", "# j markets / new-york, chicago, topeka / ;\r\n", "model.i = Set(initialize=['seattle','san-diego'], doc='Canning plans')\r\n", "model.j = Set(initialize=['new-york','chicago', 'topeka'], doc='Markets')\r\n", " \r\n", "## Define parameters ##\r\n", "# Parameters\r\n", "# a(i) capacity of plant i in cases\r\n", "# / seattle 350\r\n", "# san-diego 600 /\r\n", "# b(j) demand at market j in cases\r\n", "# / new-york 325\r\n", "# chicago 300\r\n", "# topeka 275 / ;\r\n", "model.a = Param(model.i, initialize={'seattle':350,'san-diego':600}, doc='Capacity of plant i in cases')\r\n", "model.b = Param(model.j, initialize={'new-york':325,'chicago':300,'topeka':275}, doc='Demand at market j in cases')\r\n", "# Table d(i,j) distance in thousands of miles\r\n", "# new-york chicago topeka\r\n", "# seattle 2.5 1.7 1.8\r\n", "# san-diego 2.5 1.8 1.4 ;\r\n", "dtab = {\r\n", " ('seattle', 'new-york') : 2.5,\r\n", " ('seattle', 'chicago') : 1.7,\r\n", " ('seattle', 'topeka') : 1.8,\r\n", " ('san-diego','new-york') : 2.5,\r\n", " ('san-diego','chicago') : 1.8,\r\n", " ('san-diego','topeka') : 1.4,\r\n", " }\r\n", "model.d = Param(model.i, model.j, initialize=dtab, doc='Distance in thousands of miles')\r\n", "# Scalar f freight in dollars per case per thousand miles /90/ ;\r\n", "model.f = Param(initialize=90, doc='Freight in dollars per case per thousand miles')\r\n", "# Parameter c(i,j) transport cost in thousands of dollars per case ;\r\n", "# c(i,j) = f * d(i,j) / 1000 ;\r\n", "def c_init(model, i, j):\r\n", " return model.f * model.d[i,j] / 1000\r\n", "model.c = Param(model.i, model.j, initialize=c_init, doc='Transport cost in thousands of dollar per case')\r\n", " \r\n", "## Define variables ##\r\n", "# Variables\r\n", "# x(i,j) shipment quantities in cases\r\n", "# z total transportation costs in thousands of dollars ;\r\n", "# Positive Variable x ;\r\n", "model.x = Var(model.i, model.j, bounds=(0.0,None), doc='Shipment quantities in case')\r\n", " \r\n", "## Define contrains ##\r\n", "# supply(i) observe supply limit at plant i\r\n", "# supply(i) .. sum (j, x(i,j)) =l= a(i)\r\n", "def supply_rule(model, i):\r\n", " return sum(model.x[i,j] for j in model.j) <= model.a[i]\r\n", "model.supply = Constraint(model.i, rule=supply_rule, doc='Observe supply limit at plant i')\r\n", "# demand(j) satisfy demand at market j ; \r\n", "# demand(j) .. sum(i, x(i,j)) =g= b(j);\r\n", "def demand_rule(model, j):\r\n", " return sum(model.x[i,j] for i in model.i) >= model.b[j] \r\n", "model.demand = Constraint(model.j, rule=demand_rule, doc='Satisfy demand at market j')\r\n", " \r\n", "## Define Objective and solve ##\r\n", "# cost define objective function\r\n", "# cost .. z =e= sum((i,j), c(i,j)*x(i,j)) ;\r\n", "# Model transport /all/ ;\r\n", "# Solve transport using lp minimizing z ;\r\n", "def objective_rule(model):\r\n", " return sum(model.c[i,j]*model.x[i,j] for i in model.i for j in model.j)\r\n", "model.objective = Objective(rule=objective_rule, sense=minimize, doc='Define objective function')\r\n", " \r\n", " \r\n", "## Display of the output ##\r\n", "# Display x.l, x.m ;\r\n", "def pyomo_postprocess(options=None, instance=None, results=None):\r\n", " model.x.display()\r\n", " \r\n", "# This is an optional code path that allows the script to be run outside of\r\n", "# pyomo command-line. For example: python transport.py\r\n", "if __name__ == '__main__':\r\n", " # This emulates what the pyomo command-line tools does\r\n", " from pyomo.opt import SolverFactory\r\n", " import pyomo.environ\r\n", " opt = SolverFactory(\"glpk\")\r\n", " results = opt.solve(model)\r\n", " #sends results to stdout\r\n", " results.write()\r\n", " print(\"\\nDisplaying Solution\\n\" + '-'*60)\r\n", " pyomo_postprocess(None, model, results)\r\n", "\r\n" ] } ], "source": [ "!cat transport.py" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Solutions\n", "Running the model lead to the following output:" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[ 0.00] Setting up Pyomo environment\r\n", "[ 0.00] Applying Pyomo preprocessing actions\r\n", "[ 0.00] Creating model\r\n", "[ 0.00] Applying solver\r\n", "[ 0.04] Processing results\r\n", " Number of solutions: 1\r\n", " Solution Information\r\n", " Gap: 0.0\r\n", " Status: feasible\r\n", " Function Value: 153.67499999999998\r\n", " Solver results file: results.json\r\n", "[ 0.05] Applying Pyomo postprocessing actions\r\n", "x : Shipment quantities in case\r\n", " Size=6, Index=x_index\r\n", " Key : Lower : Value : Upper : Fixed : Stale : Domain\r\n", " ('san-diego', 'chicago') : 0.0 : 0.0 : None : False : False : Reals\r\n", " ('san-diego', 'new-york') : 0.0 : 325.0 : None : False : False : Reals\r\n", " ('san-diego', 'topeka') : 0.0 : 275.0 : None : False : False : Reals\r\n", " ('seattle', 'chicago') : 0.0 : 300.0 : None : False : False : Reals\r\n", " ('seattle', 'new-york') : 0.0 : 0.0 : None : False : False : Reals\r\n", " ('seattle', 'topeka') : 0.0 : 0.0 : None : False : False : Reals\r\n", "[ 0.05] Pyomo Finished\r\n" ] } ], "source": [ "!pyomo solve --solver=glpk transport.py" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "By default, the optimization results are stored in the file `results.yml`:" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "# ==========================================================\r\n", "# = Solver Results =\r\n", "# ==========================================================\r\n", "# ----------------------------------------------------------\r\n", "# Problem Information\r\n", "# ----------------------------------------------------------\r\n", "Problem: \r\n", "- Name: unknown\r\n", " Lower bound: 153.675\r\n", " Upper bound: 153.675\r\n", " Number of objectives: 1\r\n", " Number of constraints: 6\r\n", " Number of variables: 7\r\n", " Number of nonzeros: 13\r\n", " Sense: minimize\r\n", "# ----------------------------------------------------------\r\n", "# Solver Information\r\n", "# ----------------------------------------------------------\r\n", "Solver: \r\n", "- Status: ok\r\n", " Termination condition: optimal\r\n", " Statistics: \r\n", " Branch and bound: \r\n", " Number of bounded subproblems: 0\r\n", " Number of created subproblems: 0\r\n", " Error rc: 0\r\n", " Time: 0.008376121521\r\n", "# ----------------------------------------------------------\r\n", "# Solution Information\r\n", "# ----------------------------------------------------------\r\n", "Solution: \r\n", "- number of solutions: 1\r\n", " number of solutions displayed: 1\r\n", "- Gap: 0.0\r\n", " Status: feasible\r\n", " Message: None\r\n", " Objective:\r\n", " objective:\r\n", " Value: 153.675\r\n", " Variable:\r\n", " x[seattle,chicago]:\r\n", " Value: 300\r\n", " x[san-diego,topeka]:\r\n", " Value: 275\r\n", " x[san-diego,new-york]:\r\n", " Value: 325\r\n", " Constraint: No values\r\n" ] } ], "source": [ "!cat results.yml" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This solution shows that the minimum transport costs is attained when 300 cases are sent from the Seattle plant to the Chicago market, 50 cases from Seattle to New-York and 275 cases each are sent from San-Diego plant to New-York and Topeka markets.\n", "\n", "The total transport costs will be $153,675." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## References\n", "\n", "* Original problem formulation:\n", " - Dantzig, G B, Chapter 3.3. In Linear Programming and Extensions. Princeton University Press, Princeton, New Jersey, 1963.\n", "* GAMS implementation:\n", " - Rosenthal, R E, Chapter 2: A GAMS Tutorial. In GAMS: A User's Guide. The Scientific Press, Redwood City, California, 1988.\n", "* Pyomo translation: Antonello Lobianco" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.1" } }, "nbformat": 4, "nbformat_minor": 1 }