Update the README with more information about the pysawsim wrappers.

diff --git a/README b/README
index 46340b8a4f398245d0efb77e446816943a1485ca..414faca2858872cf9148c17d7435974efd98d0e2 100644 (file)
--- a/README
+++ b/README
@@ -1,8 +1,12 @@
 Compiling
 ---------
 
-Sawsim is written in noweb_ (`noweb` in Debian-based distributions).
-Extract Makefile and compile with:
+Check out the source:
+
+  $ git clone http://www.physics.drexel.edu/~wking/code/git/sawsim.git sawsim
+  $ cd sawsim
+
+Sawsim is written in noweb_.  Extract the `Makefile` and compile with:
 
   $ notangle -Rmakefile src/sawsim.nw | sed 's/        /\t/' > Makefile
   $ make
@@ -11,20 +15,73 @@ Run the unit tests with:
 
   $ make check
 
-.. _noweb: http://www.eecs.harvard.edu/~nr/noweb/
+If you're using the Python bindings (`pysawsim` or `bin/*.py`), you
+should run the `pysawsim` unit tests with:
 
+  $ ./misc/hooks/pre-commit-pysawsim-check
 
-Dependencies
-------------
 
-Sawsim depends on the GSL_ (GNU Scientific Library) development
-package (`libgsl0-dev` in Debian-based distributions).
+Upgrading
+~~~~~~~~~
 
-The unit test programs `check_*` depend on the check_ package (`check`
-in Debian-based distributions).
+Upgrade to the most recent version:
+
+  sawsim$ git pull
+  sawsim$ make && make check && ./misc/hooks/pre-commit-pysawsim-check
+
+
+Dependencies
+------------
 
+============  =====================  =================  =====================
+Package       Purpose                Debian             Gentoo
+============  =====================  =================  =====================
+git_          version control        git-core           dev-vcs/git
+noweb_        source code framework  noweb              app-text/noweb
+GSL_          sawsim dependency      libgsl0-dev        sci-libs/gsl
+check_        sawsim unit tests      check              dev-libs/check
+python_ 2.5+  pysawsim execution     python             dev-lang/python
+nose_         pysawsim testing       python-nose        dev-python/nose
+matplotlib_   pysawsim execution     python-matplotlib  dev-python/matplotlib
+numpy_        pysawsim execution     python-numpy       dev-python/numpy
+scipy_        pysawsim execution     python-scipy       sci-libs/scipy
+mpi4py_       pysawsim mpi manager   [1]_               dev-python/mpi4py
+pbs-python_   pysawsim pbs manager   [2]_               [2]_
+============  =====================  =================  =====================
+
+.. _git: http://git-scm.com/
+.. _noweb: http://www.eecs.harvard.edu/~nr/noweb/
 .. _GSL: http://www.gnu.org/software/gsl/
 .. _check: http://check.sourceforge.net/
+.. _python: http://www.python.org/
+.. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.2/
+.. _matplotlib: http://matplotlib.sourceforge.net/
+.. _numpy: http://numpy.scipy.org/
+.. _scipy: http://www.scipy.org/
+.. _mpi4py: http://mpi4py.scipy.org/
+.. _pbs-python homepage:
+.. _pbs-python: http://subtrac.sara.nl/oss/pbs_python
+
+.. [1] mpi4py has no Debian package, but you can install it with
+   setuputils` (Debian: python-setuptools) via:
+
+     easy_install --user mpi4py
+
+.. [2] pbs-python has no Debian or Gentoo packages, but you can
+   install it from source.  See the `pbs-python homepage`_.
+
+PYTHONPATH
+~~~~~~~~~~
+
+If you install Python packages at the user level (vs. system-wide
+installs) you may need to setup a `PYTHONPATH` environmental variable
+so Python can find the packages.  You'll probably want to add a line
+along the lines of::
+
+    export PYTHONPATH=".:$HOME/.local/lib/python2.6/site-packages"
+
+to your `~/.bashrc` file to ensure that the new `PYTHONPATH` is setup
+for all future logins.
 
 
 Python wrapper
@@ -35,6 +92,67 @@ to run many repetitions to generate enough data for significant
 statistical analysis.  To facilitate this, we provide the `pysawsim`
 module which provides a higher level interface to `sawsim`.
 
+Ensure that . is in your PYTHONPATH_, and run the pysawsim tests:
+
+  sawsim$ ./misc/hooks/pre-commit-pysawsim-check
+
+Several `pysawsim` submodules have scripts (`bin/*.py`) providing
+command-line access to their functionality.  Many users will probably
+only need a single call to `bin/sawsim_hist_scan.py` to fit their
+unfolding force histograms to a particular model.
+
+
+Job managers
+~~~~~~~~~~~~
+
+For the `--manager` option, use whatever job scheduling system is most
+appropriate for your host.  For example:
+
+========================================================  =======
+Host description                                          Manager
+========================================================  =======
+SMP machine with many processors                          subproc
+Cluster with the Torque/Maui portable batch queue system  pbs
+Bunch of machines which can host message-passing daemons  mpi
+My wimpy single-processor, single-core netbook            thread
+========================================================  =======
+
+
+Caching
+~~~~~~~
+
+By default, the python wrappers do not cache the results of previous
+runs.  However, if you are repeatedly running sawsim with the same
+parameters, you probably want to enable caching (`-C/--use-cache`).
+The output of each `sawsim` run will be stored in your cache directory
+(`-d/--cache-dir`) and recycled for future runs with the same sawsim
+parameters.  For example, if you place 200 runs in the cache:
+
+  $ bin/sawsim_hist.py -s bin/sawsim -N 200 --use-cache
+
+And then generate another histogram with the same `sawsim` parameters:
+
+  $ bin/sawsim_hist.py -s bin/sawsim -N 300 --use-cache
+
+The second call will only execute an additional 100 `sawsim` runs.
+
+If you ask for *fewer* runs than are contained in the cache, e.g.:
+
+  $ bin/sawsim_hist.py -s bin/sawsim -N 100 --use-cache
+
+You will not run *any* new `sawsim` runs.  All 100 runs will be drawn
+at random from the cache.
+
+
+Help
+----
+
+As always, run
+
+  sawim$ bin/<whatever> --help
+
+for more details.
+
 
 License
 -------