Joss review (#55)

* chore: make example in README solver agnostic

And add a note on how to use a specific solver

* docs: add comments to README code

* Update requirements.txt

* docs: update README to reflect swiglpk as a dep.

swiglpk is a hard dependency now, so that 'pip install optlang' works out of the box.

* docs: update install instructions

Swiglpk is now a hard dependency so the installation instructions are updated accordingly.

* docs: update dependency versions in readme

* docs: update contributing guidelines

And add CONTRIBUTIONS.md file

* docs: update readme, paper and documentation

Add target audience to paper and docs/index
Add solver problem capabilities to readme
Move installation issue from readme to docs/installation

* test: remove libglp from travis.yml

* docs: highlight 'modeling language'

* docs: change paper title

* Some minor writing fixes (#57)

I made some minor writing fixes, to be adopted before acceptance in JOSS (openjournals/joss-reviews#139)

Author: KristianJensen

CONTRIBUTING.md

@@ -0,0 +1,7 @@
+Contribute
+==========
+
+Contributions to optlang are very welcome. Fork optlang at `github
+<http://github.com/biosustain/optlang>`_, implement your feature and send us
+a pull request. Also, please use the GitHub `issue tracker <https://github.com/biosustain/optlang/issues>`_
+to let us know about bugs or feature requests, or if you have problems or questions regarding optlang.

README.rst

@@ -10,13 +10,16 @@ problems, i.e. maximizing or minimizing an objective function over a set
 of variables subject to a number of constraints. Optlang provides a
 common interface to a series of optimization tools, so different solver
 backends can be changed in a transparent way.
-Optlang takes advantage of the symbolic math library
+Optlang's object-oriented API takes advantage of the symbolic math library
 `sympy <http://sympy.org/en/index.html>`__ to allow objective functions
 and constraints to be easily formulated from symbolic expressions of
 variables (see examples).
 
 Show us some love by staring this repo if you find optlang useful!
 
+Also, please use the GitHub `issue tracker <https://github.com/biosustain/optlang/issues>`_
+to let us know about bugs or feature requests, or if you have problems or questions regarding optlang.
+
 Installation
 ~~~~~~~~~~~~
 
@@ -26,35 +29,51 @@ Install using pip
 
     pip install optlang
 
-Then you could install `swiglpk <https://github.com/biosustain/swiglpk>`_
+This will also install `swiglpk <https://github.com/biosustain/swiglpk>`_, an interface to the open source (mixed integer) LP solver `GLPK <https://www.gnu.org/software/glpk/>`_.
+Quadratic programming (and MIQP) is supported through additional optional solvers (see below).
 
-::
+Dependencies
+~~~~~~~~~~~~
+
+The following dependencies are needed.
+
+-  `sympy >= 1.0.0 <http://sympy.org/en/index.html>`__
+-  `six >= 1.9.0 <https://pypi.python.org/pypi/six>`__
+-  `swiglpk >= 1.3.0 <https://pypi.python.org/pypi/swiglpk>`__
+
+The following are optional dependencies that allow other solvers to be used.
+
+-  `cplex <https://www-01.ibm.com/software/commerce/optimization/cplex-optimizer/>`__ (LP, MILP, QP, MIQP)
+-  `gurobipy <http://www.gurobi.com>`__ (LP, MILP (QP and MIQP support will be added in the future))
+-  `scipy <http://www.scipy.org>`__ (LP)
 
-    pip install swiglpk
 
-to solve your optimization problems using `GLPK <https://www.gnu.org/software/glpk/>`_ (see below for further supported solvers).
 
 Example
 ~~~~~~~
 
 Formulating and solving the problem is straightforward (example taken
 from `GLPK documentation <http://www.gnu.org/software/glpk>`__):
 
-::
+.. code-block:: python
 
     from __future__ import print_function
-    from optlang.glpk_interface import Model, Variable, Constraint, Objective
+    from optlang import Model, Variable, Constraint, Objective
 
+    # All the (symbolic) variables are declared, with a name and optionally a lower and/or upper bound.
     x1 = Variable('x1', lb=0)
     x2 = Variable('x2', lb=0)
     x3 = Variable('x3', lb=0)
 
+    # A constraint is constructed from an expression of variables and a lower and/or upper bound (lb and ub).
     c1 = Constraint(x1 + x2 + x3, ub=100)
     c2 = Constraint(10 * x1 + 4 * x2 + 5 * x3, ub=600)
     c3 = Constraint(2 * x1 + 2 * x2 + 6 * x3, ub=300)
 
+    # An objective can be formulated
     obj = Objective(10 * x1 + 6 * x2 + 4 * x3, direction='max')
 
+    # Variables, constraints and objective are combined in a Model object, which can subsequently be optimized.
     model = Model(name='Simple model')
     model.objective = obj
     model.add([c1, c2, c3])
@@ -63,6 +82,7 @@ from `GLPK documentation <http://www.gnu.org/software/glpk>`__):
 
     print("status:", model.status)
     print("objective value:", model.objective.value)
+    print("----------")
     for var_name, var in model.variables.iteritems():
         print(var_name, "=", var.primal)
 
@@ -72,46 +92,22 @@ The example will produce the following output:
 
     status: optimal
     objective value: 733.333333333
+    ----------
     x2 = 66.6666666667
     x3 = 0.0
     x1 = 33.3333333333
 
+Using a particular solver
+-------------------------
+If you have more than one solver installed, it's also possible to specify which one to use, by importing directly from the
+respective solver interface, e.g. :code:`from optlang.glpk_interface import Model, Variable, Constraint, Objective`
+
 Documentation
 ~~~~~~~~~~~~~
 
 Documentation for optlang is provided at
 `readthedocs.org <http://optlang.readthedocs.org/en/latest/>`__.
 
-Development
-~~~~~~~~~~~
-
-The following dependencies are needed.
-
--  `sympy >= 0.7.5 <http://sympy.org/en/index.html>`__
--  `six >= 1.9.0 <https://pypi.python.org/pypi/six>`__
-
-And at least one of the following
-
--  `swiglpk >= 0.1.0 <https://pypi.python.org/pypi/swiglpk>`__
--  `cplex <https://www-01.ibm.com/software/commerce/optimization/cplex-optimizer/>`__
--  `gurobipy <http://www.gurobi.com>`__
--  `scipy <http://www.scipy.org>`__
-
-Local installations like
-
-::
-
-    python setup.py install
-
-
-might fail installing the dependencies (unresolved issue with
-``easy_install``). Running
-
-::
-
-    pip install -r requirements.txt
-
-beforehand should fix this issue.
 
 Future outlook
 ~~~~~~~~~~~~~~

docs/source/developers.rst

@@ -4,7 +4,7 @@ Contribute
 Contributions to optlang are very welcome. Fork optlang at `github
 <http://github.com/biosustain/optlang>`_, implement your feature and send us
 a pull request. Also, please use the GitHub `issue tracker <https://github.com/biosustain/optlang/issues>`_
-to let us know about bugs or feature requests.
+to let us know about bugs or feature requests, or if you have problems or questions regarding optlang.
 
 Add solver interface
 --------------------

docs/source/index.rst

@@ -1,12 +1,13 @@
 optlang
 *******
 
-Optlang is a Python package for solving mathematical optimization problems, i.e. maximizing or minimizing an objective function over a set of variables subject to a number of constraints.
+Optlang is a Python package implementing a modeling language for solving mathematical optimization problems, i.e. maximizing or minimizing an objective function over a set of variables subject to a number of constraints.
 Optlang provides a common interface to a series of optimization tools, so different solver backends can be changed in a transparent way.
 
 In constrast to e.g. the commonly used General Algebraic Modeling System (GAMS), optlang has a simple and intuitive interface using native Python algebra syntax, and is free and open-source.
 
 Optlang takes advantage of the symbolic math library `SymPy <http://sympy.org>`_ to allow objective functions and constraints to be easily formulated from symbolic expressions of variables (see examples).
+Scientists can thus use optlang to formulate their optimization problems using mathematical expressions derived from domain knowledge.
 
 Currently supported solvers are:
 
@@ -79,6 +80,12 @@ You should see the following output::
   x3 = 0.0
   x1 = 33.3333333333
 
+
+Using a particular solver
+----------
+If you have more than one solver installed, it's also possible to specify which one to use, by importing directly from the
+respective solver interface, e.g. :code:`from optlang.glpk_interface import Model, Variable, Constraint, Objective`
+
 Quadratic programming
 ----------
 A QP problem can be generated in the same way by creating an objective with a quadratic expression. In the above example

docs/source/installation.rst

@@ -5,7 +5,7 @@ Install optlang using pip::
 
   pip install optlang
 
-Or, or download the source distribution and run::
+Or download the source distribution and run::
 
   python setup.py install
 
@@ -16,15 +16,17 @@ You can run optlang's test suite like this (you need to install nose first thoug
   
 Solvers
 ----------
-In addition to optlang itself, it is necessary to install at least one solver. Optlang interfaces with the solvers
-through importable python modules. If the python module corresponding to the solver can be imported without errors
-the solver interface should be available as an optlang submodule (e.g. :code:`optlang.glpk_interface`).
+To solve optimization problems, at least one supported solver must be installed.
+Installing optlang using :code:`pip` will also automatically install GLPK. To use other solvers (e.g. commercial solvers) it is necessary
+to install them manually. Optlang interfaces with all solvers through importable python modules. If the python module corresponding
+to the solver can be imported without errors the solver interface should be available as an optlang submodule (e.g.
+:code:`optlang.glpk_interface`).
 
 The required python modules for the currently supported solvers are:
 
-- GLPK: :code:`swiglpk`
+- GLPK: :code:`swiglpk` (automatically installed by :code:`pip install optlang`) 
 
-  - GLPK is an open source Linear Programming library. Swiglpk can be installed from binary wheels or from source. Installing from source requires swig and GLPK
+  - GLPK is an open source Linear Programming library. Swiglpk can be installed from binary wheels or from source. Installing from source requires swig and GLPK.
 
 - Cplex: :code:`cplex`
 
@@ -39,3 +41,23 @@ The required python modules for the currently supported solvers are:
   - The SciPy linprog function is a very basic implementation of the simplex algorithm for solving linear optimization problems. Linprog is included in all recent versions of SciPy.
 
 After importing optlang you can check :code:`optlang.available_solvers` to verify that a solver is recognized.
+
+
+Issues
+------
+
+Local installations like
+
+::
+
+    python setup.py install
+
+
+might fail installing the dependencies (unresolved issue with
+``easy_install``). Running
+
+::
+
+    pip install -r requirements.txt
+
+beforehand should fix this issue.

paper/paper.md

@@ -1,5 +1,5 @@
 ---
-title: 'Optlang: A Python interface to common mathematical optimization solvers'
+title: 'Optlang: An algebraic modeling language for mathematical optimization'
 tags:
  - Mathematical optimization
  - Linear programming
@@ -23,16 +23,18 @@ bibliography: paper.bib
 
 # Summary
 
-Optlang is a Python package for solving mathematical optimization problems, i.e. maximizing or minimizing an
-objective function over a set of variables subject to a number of constraints. It provides a common native Python
-interface to a series of optimization tools, so different solver backends can used and changed in a transparent way.
+Optlang is a Python package implementing a modeling language for solving mathematical optimization problems, i.e., 
+maximizing or minimizing an objective function over a set of variables subject to a number of constraints. It provides
+a common native Python interface to a series of optimization tools, so different solver backends can be used and
+changed in a transparent way.
 
-Optlang takes advantage of the symbolic math library SymPy [@Sympy] to allow objective functions and constraints
-to be easily formulated algebraically from symbolic expressions of variables. With optlang the user can thus
-focus on the science of formulating a problem without worrying about how to solve it.
+Optlang's object-oriented API takes advantage of the symbolic math library SymPy [@Sympy] to allow objective functions
+and constraints to be easily formulated algebraically from symbolic expressions of variables. Optlang targets
+scientists who can thus focus on formulating optimization problems based on mathematical equations derived from domain
+knowledge.
 
-Solver interfaces can be added by subclassing the 4 main classes of the optlang API (Variable, Constraint, Objective
+Solver interfaces can be added by subclassing the four main classes of the optlang API (Variable, Constraint, Objective,
 and Model) and implementing the relevant API functions.
 
 
-# References
+# References

requirements.txt

@@ -1,2 +1,3 @@
 sympy>=1.0.0
 six>=1.9.0
+swiglpk>=1.3.0