updated contribution file and docs. (#316)

* updated contribution file and docs.

* added more docstrings to documentation.

.github/CONTRIBUTING.md

@@ -2,6 +2,11 @@
 
 When contributing to this repository, please first discuss the change you wish to make with the owners of this repository by creating an issue before making a change. 
 
+## Contributor License Agreement
+
+This project belongs to the [COIN-OR](coinor) community and thus follows its guidelines, listed [here](coinor_guidelines). 
+In order to sign the contribution agreement, we use [cla-assistant](_cla_assistant). When a new PR is created, a link will appear that asks the submitter to sign it virtually, in case the github user has not done so already. The only requisite is to have a github account. The link to pulp's CLA is [here](cla).
+
 ## Pull Request Process
 
 1. Create a Fork of the project to your own repository.
@@ -16,7 +21,7 @@ When contributing to this repository, please first discuss the change you wish t
 
 ## Want to contribute but do not know where to start?
 
-Check the [Roadmap][roadmap] for the project to see what you can help with. We're always looking for more examples and better documentation.
+Check the [Roadmap][roadmap] for the project to see what you can help with. We're always looking for more examples and better documentation. Or check the issues that have the "help wanted" or "bug" tag.
 
 ### Attribution
 
@@ -26,3 +31,7 @@ available at [http://contributor-covenant.org/version/1/4][version]
 [homepage]: http://contributor-covenant.org
 [version]: http://contributor-covenant.org/version/1/4/
 [roadmap]: https://github.com/coin-or/pulp/projects/1
+[coinor]: https://www.coin-or.org/
+[coinor_guidelines]: https://www.coin-or.org/contributing/code/
+[cla]: https://cla-assistant.io/coin-or/pulp
+[_cla_assistant]: https://github.com/cla-assistant/cla-assistant

INSTALL

@@ -4,40 +4,36 @@ Installation
 Note that to install PuLP you must first have a working python installation as
 described in `installing python`_.
 
-PuLP requires Python >= 2.7.
+PuLP requires Python >= 2.7 or Python >= 3.4.
 
 The latest version of PuLP can be freely obtained from github_.
-Please note that this version of PuLP has not been tested with operating systems
-other than Microsoft Windows and Ubuntu Linux.
 
 Pip and pypi installation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By far the easiest way to install pulp is through the use of pip_ and
-CheeseShop_.
+By far the easiest way to install pulp is through the use of pip_.
 
-* Install pip
-    * In  windows (please make sure pip is on your path)::
+* In  windows (please make sure pip is on your path)::
 
-        c:\Python34\Scripts\> pip install pulp
+    c:\Python34\Scripts\> pip install pulp
 
-    * In Linux::
+* In Linux::
 
-        $ sudo pip install pulp
-        $ sudo pulptest             #needed to get the default solver to work
+    $ sudo pip install pulp
+    $ sudo pulptest             #needed to get the default solver to work
 
 * Then follow the instructions below to test your installation
 
-To access the examples and pulp source code use the instructions below
-to install from source
+To access the examples and pulp source code use the instructions below to install from source.
 
 
 Windows installation from source
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * Install python (`installing python`_)
 * Download the `PuLP zipfile`_
-* Extract the zipfile to a suitable location (such as the desktop - the folder will be no longer required after installation)
+* Extract the zipfile to a suitable location (such as the desktop: the folder will be no longer required after installation)
+
    * Open a command prompt by clicking "Run" in the Start Menu, and type 'cmd' in the window and push enter.
    * Navigate to the extracted folder with the setup file in it. [Do this by typing 'cd foldername' at the prompt, where 'cd' stands for current directory and the 'foldername' is the name of the folder to open in the path already listed to the left of the prompt. To return back to a root drive, type 'cd C:\']
    * Type 'setup.py install' at the command prompt. This will install all the PuLP functions into Python's site-packages directory.
@@ -46,9 +42,7 @@ The PuLP function library is now able to be imported from any python command lin
 
 >>> from pulp import *
 
-to load in the functions. (You need to re-import the functions each time after
-you close the GUI) PuLP is written in a programming language called Python, and
-to use PuLP you must write Python code to describe your optimization problem.
+to load in the functions. (You need to re-import the functions each time after you close the GUI) PuLP is written in a programming language called Python, and to use PuLP you must write Python code to describe your optimization problem.
 
 Linux Installation
 ~~~~~~~~~~~~~~~~~~
@@ -62,6 +56,7 @@ Linux Installation
     $ sudo python setup.py install
 
 * install a solver for pulp to use either
+
     * use the included 64 or 32-bit binaries cbc-32 and cbc-64
     * install glpk_  debain based distributions may use the following
 
@@ -123,8 +118,7 @@ Solver pulp.solvers.PYGLPK unavailable
 Solver pulp.solvers.YAPOSIB unavailable
 
 .. _`installing python`: http://www.diveintopython.org/installing_python/index.html
-.. _github: https://github.com/stumitchell/pulp-or
+.. _github: https://github.com/coin-or/pulp-or
 .. _pip: https://pypi.python.org/pypi/pip
-.. _CheeseShop: http://pypi.python.org
-.. _`PuLP zipfile`: https://github.com/stumitchell/pulp-or/archive/master.zip
+.. _`PuLP zipfile`: https://github.com/coi-nor/pulp-or/archive/master.zip
 

README.rst

@@ -4,7 +4,7 @@ pulp
     :target: https://travis-ci.org/coin-or/pulp
 
 PuLP is an LP modeler written in Python. PuLP can generate MPS or LP files
-and call GLPK[1], COIN-OR CLP/CBC[2], CPLEX[3], and GUROBI[4] to solve linear
+and call GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_, CHOCO_, MIPCL_, SCIP_ to solve linear
 problems.
 
 Installation
@@ -17,6 +17,13 @@ If pip is available on your system::
      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::
+
+    pip install -U git+https://github.com/coin-or/pulp
+
+
 On Linux and OSX systems the tests must be run to make the default
 solver executable.
 
@@ -81,19 +88,19 @@ 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
+* `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
+*  `LpConstraintVar` -- Used to construct a 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, 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
+* `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
 
 Comments, bug reports, patches and suggestions are welcome.
 pulp-or-discuss@googlegroups.com
@@ -102,10 +109,14 @@ pulp-or-discuss@googlegroups.com
      Copyright Stuart A. Mitchell (stu@stuartmitchell.com)
      See the LICENSE file for copyright information.
 
-References:
-
-[1] http://www.gnu.org/software/glpk/glpk.html
-[2] https://github.com/coin-or/Cbc
-[3] http://www.cplex.com/
-[4] http://www.gurobi.com/
-
+.. _Python: http://www.python.org/
+
+.. _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/

doc/source/CaseStudies/a_transportation_problem.rst

@@ -140,12 +140,12 @@ problem is found in the examples directory BeerDistributionProblem.py
 First, start your Python file with a heading and the import PuLP statement:
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 1:8
+    :lines: 1-8
 
 The start of the formulation is a simple definition of the nodes and their limits/capacities. The node names are put into lists, and their associated capacities are put into dictionaries with the node names as the reference keys:
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 10:25
+    :lines: 10-25
 
 The cost data is then inputted into a list, with two sub lists: the first 
 containing the costs of shipping from Warehouse A, and the second containing the 
@@ -160,18 +160,18 @@ warehouse A to bar 1, 2. If `costs["C"]["2"]` is called, it will return 0, since
 this is the defined default.
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 27:35
+    :lines: 27-35
 
 The `prob` variable is created using the `LpProblem` function, with the usual 
 input parameters.
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 37:38
+    :lines: 37-38
 
 A list of tuples is created containing all the arcs.
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 40:41
+    :lines: 40-41
 
 A dictionary called `route_var` is created which contains the LP variables. The 
 reference keys to the dictionary are the warehouse name, then the bar 
@@ -180,7 +180,7 @@ Route_A_2). The lower limit of zero is set, the upper limit of `None` is set,
 and the variables are defined to be Integers.
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 43:44
+    :lines: 43-44
 
 The objective function is added to the variable `prob` using a list 
 comprehension. Since `route_vars` and `costs` are now dictionaries (with further 
@@ -189,7 +189,7 @@ in Routes` will cycle through all the combinations/arcs. Note that `i` and `j`
 could have been used, but `w` and `b` are more meaningful.
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 46:47
+    :lines: 46-47
 
 The supply and demand constraints are added using a normal `for` loop and a list 
 comprehension. Supply Constraints: For each warehouse in turn, the values of the 
@@ -200,7 +200,7 @@ variables (number on arc) from each of the warehouses is summed, and then
 constrained to being greater than or equal to the demand minimum.
 
 .. literalinclude:: ../../../examples/BeerDistributionProblem.py
-    :lines: 49:55
+    :lines: 49-55
 
 Following this is the `prob.writeLP` line, and the rest as explained in previous 
 examples.
@@ -242,7 +242,7 @@ constraints all operated on the original supply, demand and cost
 lists/dictionaries, the only changes that must be made to include another demand node are:
 
 .. literalinclude:: ../../../examples/BeerDistributionProblemWarehouseExtension.py
-    :lines: 11:31
+    :lines: 11-31
 
 
 The `Bars` list is expanded and the `Demand` dictionary is expanded to make the 
@@ -271,7 +271,7 @@ list, `Supply` dictionary, and `costs` list. The Supply value is chosen to
 balance the problem, and cost of transport is zero to all demand nodes.
 
 .. literalinclude:: ../../../examples/BeerDistributionProblemCompetitorExtension.py
-    :lines:8:32
+    :lines: 8-32
 
 The code for this example is found in  `BeerDistributionProblemCompetitorExtension.py <https://projects.coin-or.org/PuLP/browser/trunk/examples/BeerDistributionProblemCompetitorExtension.py?format=txt>`_
 

doc/source/conf.py

@@ -104,14 +104,19 @@
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
 # html_theme = 'default'
-html_theme = 'alabaster'
+# html_theme = 'sphinx-glpi-theme'
+import sphinx_glpi_theme
 
+html_theme = "glpi"
+
+html_theme_path = sphinx_glpi_theme.get_html_themes_path()
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 html_theme_options = {
     'fixed_sidebar': True, 
+    'stickysidebar': True,
     'github_banner': True,
     'show_powered_by': False,
     'github_user': 'coin-or',

doc/source/guides/how_to_configure_solvers.rst

@@ -3,6 +3,33 @@ How to configure a solver in PuLP
 
 A typical problem PuLP users have is trying to connect to a solver that is installed in their pc. Here, we show the main concepts and ways to be sure PuLP can talk to the solver in question.
 
+Checking which solvers PuLP has acces to
+------------------------------------------------
+
+PuLP has some helper functions that permit a user to query which solvers are available and initialize a solver from its name.
+
+.. code-block:: python
+
+    import pulp as pl
+    solver_list = pl.list_solvers()
+    # ['GLPK_CMD', 'PYGLPK', 'CPLEX_CMD', 'CPLEX_PY', 'CPLEX_DLL', 'GUROBI', 'GUROBI_CMD', 'MOSEK', 'XPRESS', 'PULP_CBC_CMD', 'COIN_CMD', 'COINMP_DLL', 'CHOCO_CMD', 'PULP_CHOCO_CMD', 'MIPCL_CMD', 'SCIP_CMD']
+
+If passed the `only_available=True` argument, PuLP lists the solvers that are currently available::
+
+    import pulp as pl
+    solver_list = pl.list_solvers(available_only=True)
+    # ['GLPK_CMD', 'CPLEX_CMD', 'CPLEX_PY', 'GUROBI', 'GUROBI_CMD', 'PULP_CBC_CMD', 'COIN_CMD', 'PULP_CHOCO_CMD']
+
+Also, it's possible to get a solver object by using the name of the solver. Any arguments passes to this function are passed to the constructor:
+
+.. code-block:: python
+
+    import pulp as pl
+    solver = pl.get_solver('CPLEX_CMD')
+    solver = pl.get_solver('CPLEX_CMD', timeLimite=10)
+
+In the next sections, we will explain how to configure a solver to be accesible by pulp.
+
 What is an environment variable
 --------------------------------------
 
@@ -208,3 +235,40 @@ Also, you can access the python api object before solving by using the lower-lev
 
 For more information on how to use the `solverModel`, one needs to check the official documentation depending on the solver.
 
+
+Importing and exporting a solver
+-----------------------------------
+
+Exporting a solver can be useful to backup the configuration that was used to solve a model.
+
+In order to export it one needs can export it to a dictionary or a json file::
+
+    import pulp
+    solver = pulp.PULP_CBC_CMD()
+    solver_dict = solver.to_dict()
+
+The structure of the produce dictionary is quite simple::
+
+    {'keepFiles': 0,
+     'mip': True,
+     'msg': True,
+     'options': [],
+     'solver': 'PULP_CBC_CMD',
+     'timeLimit': None,
+     'warmStart': False}
+
+It's also possible to export it directly to a json file::
+
+    solver.to_json("some_file_name.json")
+
+In order to import it, one needs to do::
+
+    import pulp
+    solver = pulp.get_solver_from_dict(solver_dict)
+
+Or from a file::
+
+    import pulp
+    solver = pulp.get_solver_from_json("some_file_name.json")
+
+For json, we use the base `json` package. But if `ujson` is available, we use that so the import / export can be really fast.