-Warning: also my noweb-training program.
+Sawsim is a force-spectroscopy simulator. See the manual for more
+details.
-Extract Makefile and compile with:
- $ notangle -Rmakefile sawsim.nw | sed 's/ /\t/' > Makefile
- $ make
-Run the unit tests with
- $ make check
+Packages
+--------
+
+Gentoo
+~~~~~~
+
+I've packaged sawsim for Gentoo_ as sci-physics/sawsim in my `wtk
+overlay`_. To install, run::
+
+ # emerge -av app-portage/layman
+ # layman --add wtk
+ # emerge -av sci-physics/sawsim
+
+To stay current, follow the sawsim `Atom`_ or `RSS`_ feed, and
+re-emerge when there are interesting changes.
+
+You can skip the Compiling_ and Upgrading_ sections of this README ;).
+
+.. _Gentoo: http://www.gentoo.org/
+.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
+.. _Layman: http://www.gentoo.org/proj/en/overlays/userguide.xml
+.. _Atom: http://git.tremily.us/?p=sawsim.git;a=atom
+.. _RSS: http://git.tremily.us/?p=sawsim.git;a=rss
+
+
+Compiling
+---------
+
+Check out the source::
+
+ $ git clone git://tremily.us/sawsim.git
+ $ cd sawsim
+
+Sawsim is written in noweb_. Extract the `Makefile` and compile with::
+
+ $ notangle -Rmakefile src/sawsim.nw | sed 's/ /\t/' > Makefile
+ $ make
+
+Run the unit tests with::
+
+ $ make check
+
+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
+
+
+Upgrading
+~~~~~~~~~
+
+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]_ sys-cluster/pbs-python
+============ ===================== ================= ======================
+
+.. _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
+ distribute_ (a `setuptools` fork) (Debian: python-distribute,
+ Gentoo: setuptools/setuptools) via::
+
+ $ easy_install --user mpi4py
+
+ For systems with earlier versions of `distribute`/`setuptools`,
+ which lack the `--user` option, try something along the lines of::
+
+ $ easy_install --user mpi4py
+ $ easy_install --prefix $HOME/.local/ mpi4py
+
+.. [2] pbs-python has no Debian package, but you can install it from
+ source. See the `pbs-python homepage`_.
+
+.. _distribute: http://pypi.python.org/pypi/distribute
+
+
+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
+--------------
+
+The `sawsim` binary only runs a single pull, but you'll probably want
+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
+-------
+
+Saswim is released under the GNU GPLv3+. See `COPYING` for details.
projects / sawsim.git / blobdiff