1 Sawsim is a force-spectroscopy simulator. See the manual for more
11 I've packaged sawsim for Gentoo_ as sci-physics/sawsim in my `wtk
12 overlay`_. To install, run::
14 # emerge -av app-portage/layman
16 # emerge -av sci-physics/sawsim
18 To stay current, follow the sawsim `Atom`_ or `RSS`_ feed, and
19 re-emerge when there are interesting changes.
21 You can skip the Compiling_ and Upgrading_ sections of this README ;).
23 .. _Gentoo: http://www.gentoo.org/
24 .. _wtk overlay: http://www.physics.drexel.edu/~wking/unfolding-disasters/posts/Gentoo_overlay/
25 .. _Layman: http://www.gentoo.org/proj/en/overlays/userguide.xml
26 .. _Atom: http://www.physics.drexel.edu/~wking/code/git/gitweb.cgi?p=sawsim.git;a=atom
27 .. _RSS: http://www.physics.drexel.edu/~wking/code/git/gitweb.cgi?p=sawsim.git;a=rss
33 Check out the source::
35 $ git clone http://www.physics.drexel.edu/~wking/code/git/sawsim.git sawsim
38 Sawsim is written in noweb_. Extract the `Makefile` and compile with::
40 $ notangle -Rmakefile src/sawsim.nw | sed 's/ /\t/' > Makefile
43 Run the unit tests with::
47 If you're using the Python bindings (`pysawsim` or `bin/*.py`), you
48 should run the `pysawsim` unit tests with::
50 $ ./misc/hooks/pre-commit-pysawsim-check
56 Upgrade to the most recent version::
59 sawsim$ make && make check && ./misc/hooks/pre-commit-pysawsim-check
65 ============ ===================== ================= ======================
66 Package Purpose Debian Gentoo
67 ============ ===================== ================= ======================
68 git_ version control git-core dev-vcs/git
69 noweb_ source code framework noweb app-text/noweb
70 GSL_ sawsim dependency libgsl0-dev sci-libs/gsl
71 check_ sawsim unit tests check dev-libs/check
72 python_ 2.5+ pysawsim execution python dev-lang/python
73 nose_ pysawsim testing python-nose dev-python/nose
74 matplotlib_ pysawsim execution python-matplotlib dev-python/matplotlib
75 numpy_ pysawsim execution python-numpy dev-python/numpy
76 scipy_ pysawsim execution python-scipy sci-libs/scipy
77 mpi4py_ pysawsim mpi manager [1]_ dev-python/mpi4py
78 pbs-python_ pysawsim pbs manager [2]_ sys-cluster/pbs-python
79 ============ ===================== ================= ======================
81 .. _git: http://git-scm.com/
82 .. _noweb: http://www.eecs.harvard.edu/~nr/noweb/
83 .. _GSL: http://www.gnu.org/software/gsl/
84 .. _check: http://check.sourceforge.net/
85 .. _python: http://www.python.org/
86 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.2/
87 .. _matplotlib: http://matplotlib.sourceforge.net/
88 .. _numpy: http://numpy.scipy.org/
89 .. _scipy: http://www.scipy.org/
90 .. _mpi4py: http://mpi4py.scipy.org/
91 .. _pbs-python homepage:
92 .. _pbs-python: http://subtrac.sara.nl/oss/pbs_python
94 .. [1] mpi4py has no Debian package, but you can install it with
95 distribute_ (a `setuptools` fork) (Debian: python-distribute,
96 Gentoo: setuptools/setuptools) via::
98 $ easy_install --user mpi4py
100 For systems with earlier versions of `distribute`/`setuptools`,
101 which lack the `--user` option, try something along the lines of::
103 $ easy_install --user mpi4py
104 $ easy_install --prefix $HOME/.local/ mpi4py
106 .. [2] pbs-python has no Debian package, but you can install it from
107 source. See the `pbs-python homepage`_.
109 .. _distribute: http://pypi.python.org/pypi/distribute
115 If you install Python packages at the user level (vs. system-wide
116 installs) you may need to setup a `PYTHONPATH` environmental variable
117 so Python can find the packages. You'll probably want to add a line
120 export PYTHONPATH=".:$HOME/.local/lib/python2.6/site-packages"
122 to your `~/.bashrc` file to ensure that the new `PYTHONPATH` is setup
123 for all future logins.
129 The `sawsim` binary only runs a single pull, but you'll probably want
130 to run many repetitions to generate enough data for significant
131 statistical analysis. To facilitate this, we provide the `pysawsim`
132 module which provides a higher level interface to `sawsim`.
134 Ensure that . is in your PYTHONPATH_, and run the pysawsim tests::
136 sawsim$ ./misc/hooks/pre-commit-pysawsim-check
138 Several `pysawsim` submodules have scripts (`bin/*.py`) providing
139 command-line access to their functionality. Many users will probably
140 only need a single call to `bin/sawsim_hist_scan.py` to fit their
141 unfolding force histograms to a particular model.
147 For the `--manager` option, use whatever job scheduling system is most
148 appropriate for your host. For example:
150 ======================================================== =======
151 Host description Manager
152 ======================================================== =======
153 SMP machine with many processors subproc
154 Cluster with the Torque/Maui portable batch queue system pbs
155 Bunch of machines which can host message-passing daemons mpi
156 My wimpy single-processor, single-core netbook thread
157 ======================================================== =======
163 By default, the python wrappers do not cache the results of previous
164 runs. However, if you are repeatedly running sawsim with the same
165 parameters, you probably want to enable caching (`-C/--use-cache`).
166 The output of each `sawsim` run will be stored in your cache directory
167 (`-d/--cache-dir`) and recycled for future runs with the same sawsim
168 parameters. For example, if you place 200 runs in the cache::
170 $ bin/sawsim_hist.py -s bin/sawsim -N 200 --use-cache
172 And then generate another histogram with the same `sawsim` parameters::
174 $ bin/sawsim_hist.py -s bin/sawsim -N 300 --use-cache
176 The second call will only execute an additional 100 `sawsim` runs.
178 If you ask for *fewer* runs than are contained in the cache, e.g.::
180 $ bin/sawsim_hist.py -s bin/sawsim -N 100 --use-cache
182 You will not run *any* new `sawsim` runs. All 100 runs will be drawn
183 at random from the cache.
191 sawim$ bin/<whatever> --help
199 Saswim is released under the GNU GPLv3+. See `COPYING` for details.