diff --git a/README.rst b/README.rst index 7ed640d7..d3685d48 100644 --- a/README.rst +++ b/README.rst @@ -10,74 +10,53 @@ pulp :target: https://pypi.org/project/PuLP/ :alt: PyPI - Downloads -PuLP is an LP modeler written in Python. PuLP can generate MPS or LP files and call GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_, CHOCO_, MIPCL_, HiGHS_, SCIP_/FSCIP_ to solve linear problems. - -Installation -================ - -The easiest way to install pulp is via `PyPi `_ - -If pip is available on your system:: - - python -m pip install pulp - -Otherwise follow the download instructions on the PyPi page. - - -If you want to install the latest version from github you can run the following:: - - python -m pip install -U git+https://github.com/coin-or/pulp +PuLP is an linear and mixed integer programming modeler written in Python. With PuLP, it is simple to create MILP optimisation problems and solve them with the latest open-source (or proprietary) solvers. PuLP can generate MPS or LP files and call solvers such as GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_, CHOCO_, MIPCL_, HiGHS_, SCIP_/FSCIP_. +The documentation for PuLP can be `found here `_. -On Linux and OSX systems the tests must be run to make the default -solver executable. +PuLP is part of the `COIN-OR project `_. -:: - - sudo pulptest - -Examples +Installation ================ -See the examples directory for examples. - PuLP requires Python 3.7 or newer. -The examples use the default solver (CBC). To use other solvers they must be available (installed and accessible). For more information on how to do that, see the `guide on configuring solvers `_. +The easiest way to install PuLP is with ``pip``. If ``pip`` is available on your system, type:: -Documentation -================ + python -m pip install pulp -Documentation is found on https://coin-or.github.io/pulp/. +Otherwise follow the download instructions on the `PyPi page `_. -Use LpVariable() to create new variables. To create a variable 0 <= x <= 3:: +Quickstart +=============== +Use ``LpVariable`` to create new variables. To create a variable x with 0 ≤ x ≤ 3:: + + from pulp import * x = LpVariable("x", 0, 3) -To create a variable 0 <= y <= 1:: +To create a binary variable, y, with values either 0 or 1:: - y = LpVariable("y", 0, 1) + y = LpVariable("y", cat="Binary") -Use LpProblem() to create new problems. Create "myProblem":: +Use ``LpProblem`` to create new problems. Create a problem called "myProblem" like so:: prob = LpProblem("myProblem", LpMinimize) -Combine variables to create expressions and constraints, then add them to the -problem:: +Combine variables in order to create expressions and constraints, and then add them to the problem.:: prob += x + y <= 2 -If you add an expression (not a constraint), it will -become the objective:: +An expression is a constraint without a right-hand side (RHS) sense (one of ``=``, ``<=`` or ``>=``). If you add an expression to a problem, it will become the objective:: prob += -4*x + y -To solve with the default included solver:: +To solve the problem with the default included solver:: status = prob.solve() -To use another sovler to solve the problem:: +If you want to try another solver to solve the problem:: status = prob.solve(GLPK(msg = 0)) @@ -86,26 +65,53 @@ Display the status of the solution:: LpStatus[status] > 'Optimal' -You can get the value of the variables using value(). ex:: +You can get the value of the variables using ``value``. ex:: value(x) > 2.0 -Exported Classes: -* ``LpProblem`` -- Container class for a Linear programming problem -* ``LpVariable`` -- Variables that are added to constraints in the LP -* ``LpConstraint`` -- A constraint of the general form +Essential Classes +------------------ + + +* ``LpProblem`` -- Container class for a Linear or Integer programming problem +* ``LpVariable`` -- Variables that are added into constraints in the LP problem +* ``LpConstraint`` -- Constraints of the general form - a1x1+a2x2 ...anxn (<=, =, >=) b + a1x1 + a2x2 + ... + anxn (<=, =, >=) b -* ``LpConstraintVar`` -- Used to construct a column of the model in column-wise modelling +* ``LpConstraintVar`` -- A special type of constraint for constructing column of the model in column-wise modelling -Exported Functions: +Useful Functions +------------------ * ``value()`` -- Finds the value of a variable or expression -* ``lpSum()`` -- given a list of the form [a1*x1, a2x2, ..., anxn] will construct a linear expression to be used as a constraint or variable -* ``lpDot()`` --given two lists of the form [a1, a2, ..., an] and [ x1, x2, ..., xn] will construct a linear expression to be used as a constraint or variable +* ``lpSum()`` -- Given a list of the form [a1*x1, a2*x2, ..., an*xn] will construct a linear expression to be used as a constraint or variable +* ``lpDot()`` -- Given two lists of the form [a1, a2, ..., an] and [x1, x2, ..., xn] will construct a linear expression to be used as a constraint or variable + +More Examples +================ + +Several tutorial are given in `documentation `_ and pure code examples are available in `examples/ directory `_ . + +The examples use the default solver (CBC). To use other solvers they must be available (installed and accessible). For more information on how to do that, see the `guide on configuring solvers `_. + + +For Developers +================ + + +If you want to install the latest version from GitHub you can run:: + + python -m pip install -U git+https://github.com/coin-or/pulp + + +On Linux and MacOS systems, you must run the tests to make the default solver executable:: + + sudo pulptest + + Building the documentation @@ -126,17 +132,20 @@ To build, run the following in a terminal window, in the PuLP root directory A folder named html will be created inside the ``build/`` directory. The home page for the documentation is ``doc/build/html/index.html`` which can be opened in a browser. +Contributing to PuLP +----------------------- +Instructions for making your first contribution to PuLP are given `here `_. - - - - -**Comments, bug reports, patches and suggestions are welcome.** +**Comments, bug reports, patches and suggestions are very welcome!** * Comments and suggestions: https://github.com/coin-or/pulp/discussions * Bug reports: https://github.com/coin-or/pulp/issues * Patches: https://github.com/coin-or/pulp/pulls +Copyright and License +======================= +PuLP is distributed under an MIT license. + Copyright J.S. Roy, 2003-2005 Copyright Stuart A. Mitchell See the LICENSE file for copyright information. diff --git a/doc/source/CaseStudies/a_blending_problem.rst b/doc/source/CaseStudies/a_blending_problem.rst index 9b4371e4..5d526757 100644 --- a/doc/source/CaseStudies/a_blending_problem.rst +++ b/doc/source/CaseStudies/a_blending_problem.rst @@ -1,3 +1,5 @@ +.. _blending_problem: + A Blending Problem =================== diff --git a/doc/source/index.rst b/doc/source/index.rst index abeb2e4d..50156bd8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,14 +6,21 @@ Optimization with PuLP ---------------------- -You can begin learning Python and using PuLP -by looking at the content below. We recommend that you read The Optimisation Process, -Optimisation Concepts, and the Introduction to Python -before beginning the case-studies. For instructions for the installation of PuLP -see :ref:`installation`. - -The full PuLP function documentation is available, and useful functions -will be explained in the case studies. +PuLP is an linear and mixed integer programming modeler written in Python. + +With PuLP, it is simple to create MILP optimisation problems and solve them with the +latest open-source (or proprietary) solvers. PuLP can generate MPS or LP files and +call solvers such as GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_, +CHOCO_, MIPCL_, HiGHS_, SCIP_/FSCIP_. + +Here are some ways to get started using PuLP: + +* for instructions about installing PuLP see :ref:`installation`. +* If you're new to Python and optimisation we recommend that you read :ref:`optimisation_concepts`, :ref:`optimisation_process`, and the :ref:`getting_started_with_python`. +* If you want to jump right in then start reading the case studies starting with :ref:`blending_problem`. + +The full PuLP API documentation is available, and useful functions +are also explained in the case studies. The case studies are in order, so the later case studies will assume you have (at least) read the earlier case studies. However, we will provide links to any relevant information you will need. @@ -34,3 +41,16 @@ Authors The authors of this documentation (the pulp documentation team) include: .. include:: AUTHORS.txt + + +.. _GLPK: http://www.gnu.org/software/glpk/glpk.html +.. _CBC: https://github.com/coin-or/Cbc +.. _CPLEX: http://www.cplex.com/ +.. _GUROBI: http://www.gurobi.com/ +.. _MOSEK: https://www.mosek.com/ +.. _XPRESS: https://www.fico.com/es/products/fico-xpress-solver +.. _CHOCO: https://choco-solver.org/ +.. _MIPCL: http://mipcl-cpp.appspot.com/ +.. _SCIP: https://www.scipopt.org/ +.. _HiGHS: https://highs.dev +.. _FSCIP: https://ug.zib.de diff --git a/doc/source/main/basic_python_coding.rst b/doc/source/main/basic_python_coding.rst index 0b0f6cdf..35ea9597 100644 --- a/doc/source/main/basic_python_coding.rst +++ b/doc/source/main/basic_python_coding.rst @@ -1,3 +1,6 @@ +.. _getting_started_with_python: + + Basic Python Coding =================== diff --git a/doc/source/main/optimisation_concepts.rst b/doc/source/main/optimisation_concepts.rst index d7416612..5841d855 100644 --- a/doc/source/main/optimisation_concepts.rst +++ b/doc/source/main/optimisation_concepts.rst @@ -1,3 +1,5 @@ +.. _optimisation_concepts: + Optimisation Concepts ===================== diff --git a/doc/source/main/the_optimisation_process.rst b/doc/source/main/the_optimisation_process.rst index 67098ff9..a07df8d9 100644 --- a/doc/source/main/the_optimisation_process.rst +++ b/doc/source/main/the_optimisation_process.rst @@ -1,3 +1,6 @@ +.. _optimisation_process: + + The Optimisation Process ======================== diff --git a/pulp/pulp.py b/pulp/pulp.py index b186e6ed..79b473b1 100644 --- a/pulp/pulp.py +++ b/pulp/pulp.py @@ -26,70 +26,101 @@ # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ -PuLP is an LP modeler written in python. PuLP can generate MPS or LP files -and call GLPK[1], COIN CLP/CBC[2], CPLEX[3], GUROBI[4] and MOSEK[5] to solve linear -problems. +PuLP is an linear and mixed integer programming modeler written in Python. -See the examples directory for examples. +With PuLP, it is simple to create MILP optimisation problems and solve them with the +latest open-source (or proprietary) solvers. PuLP can generate MPS or LP files and +call solvers such as GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_, +CHOCO_, MIPCL_, HiGHS_, SCIP_/FSCIP_. +The documentation for PuLP can be `found here `_. + +Many examples are shown in the `documentation `_ +and pure code examples are available in `examples/ directory `_ . The examples require at least a solver in your PATH or a shared library file. -Documentation is found on https://www.coin-or.org/PuLP/. -A comprehensive wiki can be found at https://www.coin-or.org/PuLP/ +Quickstart +------------ +Use ``LpVariable`` to create new variables. To create a variable x with 0 ≤ x ≤ 3:: + + from pulp import * + x = LpVariable("x", 0, 3) + +To create a binary variable, y, with values either 0 or 1:: + + y = LpVariable("y", cat="Binary") + +Use ``LpProblem`` to create new problems. Create a problem called "myProblem" like so:: + + prob = LpProblem("myProblem", LpMinimize) + +Combine variables in order to create expressions and constraints, and then add them to +the problem.:: + + prob += x + y <= 2 + +An expression is a constraint without a right-hand side (RHS) sense (one of ``=``, +``<=`` or ``>=``). If you add an expression to a problem, it will become the +objective:: -Use LpVariable() to create new variables. To create a variable 0 <= x <= 3 ->>> x = LpVariable("x", 0, 3) + prob += -4*x + y -To create a variable 0 <= y <= 1 ->>> y = LpVariable("y", 0, 1) +To solve the problem with the default included solver:: -Use LpProblem() to create new problems. Create "myProblem" ->>> prob = LpProblem("myProblem", const.LpMinimize) + status = prob.solve() -Combine variables to create expressions and constraints and add them to the -problem. ->>> prob += x + y <= 2 +If you want to try another solver to solve the problem:: -If you add an expression (not a constraint), it will -become the objective. ->>> prob += -4 * x + y + status = prob.solve(GLPK(msg = 0)) -Choose a solver and solve the problem. ex: ->>> status = prob.solve(PULP_CBC_CMD(msg=0)) +Display the status of the solution:: -Display the status of the solution ->>> const.LpStatus[status] -'Optimal' + LpStatus[status] + > 'Optimal' -You can get the value of the variables using value(). ex: ->>> value(x) -2.0 +You can get the value of the variables using ``value``. ex:: -Exported Classes: - - LpProblem -- Container class for a Linear programming problem - - LpVariable -- Variables that are added to constraints in the LP - - LpConstraint -- A constraint of the general form - a1x1+a2x2 ...anxn (<=, =, >=) b - - LpConstraintVar -- Used to construct a column of the model in column-wise - modelling + value(x) + > 2.0 -Exported Functions: - - value() -- Finds the value of a variable or expression - - lpSum() -- given a list of the form [a1*x1, a2x2, ..., anxn] will construct - a linear expression to be used as a constraint or variable - - lpDot() --given two lists of the form [a1, a2, ..., an] and - [ x1, x2, ..., xn] will construct a linear epression to be used - as a constraint or variable +Useful Classes and Functions +----------------------------- -Comments, bug reports, patches and suggestions are welcome. -https://github.com/coin-or/pulp +Exported classes: -References: +* ``LpProblem`` -- Container class for a Linear or Integer programming problem +* ``LpVariable`` -- Variables that are added into constraints in the LP problem +* ``LpConstraint`` -- Constraints of the general form + + a1x1 + a2x2 + ... + anxn (<=, =, >=) b + +* ``LpConstraintVar`` -- A special type of constraint for constructing column of the model in column-wise modelling + +Exported functions: + +* ``value()`` -- Finds the value of a variable or expression +* ``lpSum()`` -- Given a list of the form [a1*x1, a2*x2, ..., an*xn] will construct a linear expression to be used as a constraint or variable +* ``lpDot()`` -- Given two lists of the form [a1, a2, ..., an] and [x1, x2, ..., xn] will construct a linear expression to be used as a constraint or variable + +Contributing to PuLP +----------------------- +Instructions for making your first contribution to PuLP are given +`here `_. + +**Comments, bug reports, patches and suggestions are very welcome!** + +* Comments and suggestions: https://github.com/coin-or/pulp/discussions +* Bug reports: https://github.com/coin-or/pulp/issues +* Patches: https://github.com/coin-or/pulp/pulls + +References +---------- [1] http://www.gnu.org/software/glpk/glpk.html [2] http://www.coin-or.org/ [3] http://www.cplex.com/ [4] http://www.gurobi.com/ [5] http://www.mosek.com/ + """ from collections import Counter