From 1ea00a7aca681374f453f746581cd2ed3d23c9c5 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 23 Oct 2010 10:48:16 -0400 Subject: [PATCH] Update the README with more information about the pysawsim wrappers. --- README | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 127 insertions(+), 9 deletions(-) diff --git a/README b/README index 46340b8..414faca 100644 --- 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/ --help + +for more details. + License ------- -- 2.26.2