update documentation

README.rst

@@ -12,15 +12,49 @@ Should be an easy pip installation:
 
    pip install scikit-glpk
 
-GLPK must be installed in order to use the wrappers. Download the latest version from `here <http://ftp.gnu.org/gnu/glpk/>`_ and following the instructions for installation.  If you use Linux/Mac, you should be able to run the following (see docs for different configuration options):
+Usage
+-----
+
+There are a few things in this package:
+
+- `glpk()` : the wrappers over the solvers (basically acts like Pythonized `glpsol`)
+- `mpsread()` : convert an MPS file to some matrices
+
+
+
+.. code-block::
+
+   from glpk import glpk, GLPK
+
+   res = glpk(
+       c, A_ub, b_ub, A_eq, b_eq, bounds, solver, sense, maxit, timeout,
+       basis_fac, message_level, disp, simplex_options, ip_options,
+       mip_options, libpath)
+
+   c, A_ub, b_ub, A_eq, b_eq, bounds = mpsread(
+       filename, fmt=GLPK.GLP_MPS_FILE, ret_glp_prob=False, libpath=None)
+
+There's lots of information in the docstrings for these functions, please check there for a complete listing and explanation.
+
+Notice that `glpk` is the wrapper and `GLPK` acts as a namespace that holds constants.
+
+`bounds` is also behaves a little differently for both of these:
+
+- as an input to `glpk`, `bounds` is a list of triplets in the style of GLPK (probably should be converted to `linprog` conventions)
+- as an output of `mpsread`, `bounds` is a list of tuples in the style of `linprog`
+
+GLPK stuffs
+-----------
+
+GLPK must be installed in order to use the wrappers. Download the latest version from `here <http://ftp.gnu.org/gnu/glpk/>`_ and follow the instructions for installation.  If you use Linux/Mac, you should be able to run the following to compile from source (see docs for different configuration options):
 
 .. code-block::
 
    ./configure
    make -j
    make install
 
-For Windows you will need Visual Studio Build Tools.  Go to the correct subdirectory (w32 for 32-bit or w64 for 64-bit) and the run the batch script:
+For Windows you will need at least `Visual Studio Build Tools <https://visualstudio.microsoft.com/visual-cpp-build-tools/>`_.  Go to the correct subdirectory (w32 for 32-bit or w64 for 64-bit) and the run the batch script:
 
 .. code-block::
 
@@ -43,23 +77,29 @@ Note that there are several projects that aim for something like this, but which
 - `Pyomo <https://github.com/Pyomo/pyomo>`_ : Big, uses different conventions than that of `linprog`
 - `CVXOPT <https://cvxopt.org/>`_ : Big, GPL licensed
 - `Sage <https://git.sagemath.org/sage.git/tree/README.md>`_ : Big, GPL licensed
-- `pulp <https://launchpad.net/pulp-or>`_ : Calls `glpsol` from command line (writes problems, solutions to file instead of shared memory model)
-- `yaposib <https://github.com/coin-or/yaposib>`_ : seems dead? Bigger than I want
-- `ecyglpki <https://github.com/equaeghe/ecyglpki/tree/0.1.0>`_ : dead
+- `pulp <https://launchpad.net/pulp-or>`_ : Calls `glpsol` from command line (writes problems, solutions to file instead of shared memory model -- this is actually easy to do)
+- `yaposib <https://github.com/coin-or/yaposib>`_ : seems dead? OSI-centric
+- `ecyglpki <https://github.com/equaeghe/ecyglpki/tree/0.1.0>`_ : GPL licensed, dead?
 - `swiglpk <https://github.com/biosustain/swiglpk>`_ : GPL licensed, low level
+- `optlang <https://github.com/biosustain/optlang>`_ : sympy-like, cool project otherwise
 
 Most existing projects lean to GPL licenses.  Not a bad thing, but would hinder adoption into scipy.
 
 Why do we want this?
 --------------------
 
-GLPK has a lot of options that the current scipy solvers lack as well as robust MIP support (only basic in HiGHS).  It is also a standard, well known solver in the optimization community.  Easy access to GLPK as a backend to `linprog` would be very welcome (to me at least).
+GLPK has a lot of options that the current scipy solvers lack as well as robust MIP support (only basic in HiGHS).  It is also a standard, well known solver in the optimization community.  The only thing that I want that it lacks on an API level is robust support for column generation.  Easy access to GLPK as a backend to `linprog` would be very welcome (to me at least).
 
 Approach
 --------
 
-Since the underlying API is quite simple and written in C, `ctypes` is a good fit for this.
+Since the underlying API is quite simple and written in C and only C, `ctypes` is a good fit for this.
 
 GLPK will not be packaged with scipy due to licensing issues, so the strategy will be to specify where the installation is on a user's computer (i.e., path to the shared library).  `linprog` could then presumably route the problem to the GLPK backend instead of HiGHS or the existing native python solvers.
 
 The `ctypes` wrapper is required for integrating GLPK into the Python runtime.  Instead of using MPS files to communicate problems and reading solutions from files, `scipy.sparse.coo_matrix` and `numpy` arrays can be passed directly to the library.  More information can be extracted from GLPK this way as well (For example, there is no way to get iteration count except by reading directly from the underlying structs.  It is only ever printed to stdout, no other way to get it).
+
+TODO
+----
+
+- Several GLPK solver options (notably tolerances) not wrapped yet

setup.py

@@ -4,7 +4,7 @@
 
 setup(
     name='scikit-glpk',
-    version='0.0.4',
+    version='0.0.5',
     author='Nicholas McKibben',
     author_email='[email protected]',
     url='https://github.com/mckib2/scikit-glpk',