Merge pull request #151 from kyleabeauchamp/readme

Updated README, removed cython dependency

README.md

@@ -8,144 +8,79 @@ pymbar
 
 Python implementation of the multistate Bennett acceptance ratio (MBAR) method for estimating expectations and free energy differences.  See our [Docs](http://pymbar.readthedocs.org/en/latest/).
 
-Authors
--------
-* John D. Chodera <choderaj@mskcc.org>
-* Michael R. Shirts <michael.shirts@virginia.edu>
-* Kyle A. Beauchamp <beauchak@mskcc.org>
-
-
-Manifest
---------
-
-This archive contains the following files:
-
-* `README.md` - this file
-* `LICENSE` - a copy of the GNU General Public License version 2 covering this code
-* `pymbar/` - Python MBAR package
-* `examples/` - examples of applications of MBAR to various types of calculations
-  See the README.md in that folder for more information
-* `tests/` - unit tests for the functionality
-* `docs/` - sphinx documetation
-* `devtools/` - travis CI and conda configuration files
-
-Prerequisites
--------------
-
-The pymbar module requires the following:
 
-* Python 2.7 or later: http://www.python.org/
-* the NumPy package: http://numpy.scipy.org/
-* the SciPy package: http://www.scipy.org/
-* NumExpr
-* six
-* cython
-* nose
-* Some optional graphing functionality in the tests requires the matplotlib library: http://matplotlib.sourceforge.net/
-
-Quickstart
-----------
+Installation
+------------
 
 The easiest way to install `pymbar` is via [conda](http://conda.pydata.org), a binary package installer that comes with the [Anaconda Scientific Python distribution](https://store.continuum.io/cshop/anaconda/):
 ```tcsh
 conda install -c https://conda.binstar.org/omnia pymbar
 ```
-If you don't have `conda` installed but do have `pip`, you can install it with:
-```tcsh
-pip install conda
-```
-
-Alternatives
-------------
-
-There are several other ways to install pymbar.
-
-You can grab the latest version from the [Python Package Index (PyPI)](https://pypi.python.org/pypi/pymbar) with `easy_install`:
-```tcsh
-easy_install pymbar
-```
-or using `pip install`:
-```tcsh
-pip install pymbar
-```
 
-Or, if you download the [GitHub version](http://github.com/choderalab/pymbar), you can use the provided `setup.py` to install.
+Besides conda, you can also install `pymbar` using `pip` (`pip install pymbar`) or directly from the source directory (`python setup.py install`).
 
-To install to your default Python site-packages location:
-```tcsh
-python setup.py install
-```
-Or to install to a different location (e.g. a local Python package repository):
-```tcsh
-python setup.py install --prefix=/path/to/my/site-packages/
-```
-The C++ helper code will automatically be built in both cases, if possible.
-
-To build pymbar in situ, without installing to site-packages, run
-```tcsh
-python setup.py build
-```
-and add the directory containing this file to your PYTHONPATH environment variable.
-```tcsh
-# For tcsh
-setenv PYTHONPATH "/path/to/pymbar:$PYTHONPATH"
-# For bash
-export PYTHONPATH="/path/to/pymbar:$PYTHONPATH"
-```
 
 Usage
 -----
 
-In Python 2.6 or later, you can view the docstrings with `help()`:
-```python
->>> from pymbar import MBAR
->>> help(MBAR)
-```
-See the example code in the docstrings, or find more elaborate examples in the `examples/` directory.
+Basic usage involves importing pymbar, loading data, and constructing an MBAR object from the reduced potential of simulation or experimental data:
 
-Basic usage involves first constructing a MBAR object, initializing it with the reduced potential from the simulation or experimental data:
 ```python
->>> mbar = MBAR(u_kln, N_k)
+>>> from pymbar import MBAR, testsystems
+>>> x_k, u_kn, N_k, s_n = testsystems.HarmonicOscillatorsTestCase().sample()
+>>> mbar = MBAR(u_kn, N_k)
 ```
+
 Next, we extract the dimensionless free energy differences and uncertainties:
+
 ```python
->>> (Deltaf_ij_estimated, dDeltaf_ij_estimated) = mbar.getFreeEnergyDifferences()
+>>> (Deltaf_ij_estimated, dDeltaf_ij_estimated, Theta_ij) = mbar.getFreeEnergyDifferences()
 ```
+
 or compute expectations of given observables A(x) for all states:
+
 ```python
->>> (A_k_estimated, dA_k_estimated) = mbar.computeExpectations(A_kn)
+>>> (A_k_estimated, dA_k_estimated) = mbar.computeExpectations(x_k)
 ```
-See the help for these individual methods for more information on exact usage.
+See the help for these individual methods for more information on exact usage; in Python or IPython, you can view the docstrings with `help()`.  
+Additional examples can be found in [pymbar-examples](http://github.com/choderalab/pymbar-examples/).
 
-Examples
---------
 
-Several examples of applications of `pymbar` to various types of simulation data can be found in [pymbar-examples](http://github.com/choderalab/pymbar-examples/).
+Prerequisites
+-------------
 
+To install and run pymbar requires the following:
 
-Optimizations and improvements
-------------------------------
+* Python 2.7 or later: http://www.python.org/
+* NumPy: http://numpy.scipy.org/
+* SciPy: http://www.scipy.org/
+* NumExpr: https://github.com/pydata/numexpr
+* six
+* nose
+* Some optional graphing functionality in the tests requires the matplotlib library: http://matplotlib.sourceforge.net/
 
-By default, the pymbar class uses an adaptive method which uses self-consistent iteration initially and switches to Newton-Raphson iteration (with N-R implemented as described in the Appendix of Ref. [1]) when the norm of the gradient of a Newton-Raphson step is lower than the norm of the gradient of a self-consistent step. Self-consistent iteration or Newton-Raphson can be selected instead if desired.  For example, to use the Newton-Raphson solver alone, add the optional argument:
-```python
-method = 'Newton-Raphson'
-```
-to the MBAR initialization, as in 
-```python
->>> mbar = MBAR.MBAR(u_kln, N_k, method = 'Newton-Raphson')
-```
-In very rare cases, the self-consistent iteration may still work when the adaptive method switches to Newton-Raphson prematurely.
 
-* C++ helper code
+Authors
+-------
+* John D. Chodera <choderaj@mskcc.org>
+* Michael R. Shirts <michael.shirts@virginia.edu>
+* Kyle A. Beauchamp <beauchak@mskcc.org>
+
 
-We have provided a C++ helper code (`_pymbar.c`) to speed up the most time-consuming operation in computing the dimensionless free energies (used by all methods).  For many applications, use of the compiled helper code results in a speedup of ~40x.  There should be no significant difference in the output (if any) between the pure-Python/Numpy results and those employing the helper routine.  
+Manifest
+--------
+
+This archive contains the following files:
+
+* `README.md` - this file
+* `LICENSE` - a copy of the GNU General Public License version 2 covering this code
+* `pymbar/` - Python MBAR package
+* `examples/` - examples of applications of MBAR to various types of calculations
+  See the README.md in that folder for more information
+* `docs/` - sphinx documetation
+* `devtools/` - travis CI and conda configuration files
 
-The routine should be installed correctly using the `setup.py` script, but if it fails, instructions on compilation for several platforms can be found in the header of `_pymbar.c`.
 
-pymbar.py will import and use the compiled dynamic library (`_pymbar.so`) provided it can be found in your `PYTHONPATH`.  An optional `use_optimized` flag passed to the MBAR constructor can be used to force or disable this behavior.  Passing the flag `use_optimized = False` to the MBAR initialization will disable use of the module.
-```python
->>> mbar = pymbar.MBAR(u_kln, N_k, use_optimized = False)
-```
 
 References
 ----------
@@ -159,16 +94,11 @@ References
   Chodera JD, Swope WC, Pitera JW, Seok C, and Dill KA. Use of the weighted histogram analysis method for the analysis of simulated and parallel tempering simulations. J. Chem. Theor. Comput. 3(1):26-41 (2007).  [DOI](http://dx.doi.org/10.1021/ct0502864)
 
 
-Copyright notice
-----------------
-
-Copyright (c) 2006-2012 The Regents of the University of California.  All Rights Reserved.  Portions of this software are Copyright (c) 2007-2008 Stanford University and Columbia University, (c) 2008-2014 University of Virginia, and (c) 2014 Memorial Sloan-Kettering Cancer Center.
-
-This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+License
+-------
 
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+Pymbar is free software and is licensed under the GPLv2 license.
 
-You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
 Thanks
 ------

devtools/conda-recipe/meta.yaml

@@ -6,15 +6,13 @@ package:
 requirements:
   build:
     - python
-    - cython
     - numpy
     - scipy
     - setuptools
     - numexpr   
     - six 
   run:
     - python
-    - cython
     - numpy
     - scipy
     - numexpr