README

   1 Sawsim is a force-spectroscopy simulator.  See the manual for more
   2 details.
   3
   4
   5 Packages
   6 --------
   7
   8 Gentoo
   9 ~~~~~~
  10
  11 I've packaged sawsim for Gentoo_ as sci-physics/sawsim in my `wtk
  12 overlay`_.  To install, run::
  13
  14   # emerge -av app-portage/layman
  15   # layman --add wtk
  16   # emerge -av sci-physics/sawsim
  17
  18 To stay current, follow the sawsim `Atom`_ or `RSS`_ feed, and
  19 re-emerge when there are interesting changes.
  20
  21 You can skip the Compiling_ and Upgrading_ sections of this README ;).
  22
  23 .. _Gentoo: http://www.gentoo.org/
  24 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
  25 .. _Layman: http://www.gentoo.org/proj/en/overlays/userguide.xml
  26 .. _Atom: http://git.tremily.us/?p=sawsim.git;a=atom
  27 .. _RSS: http://git.tremily.us/?p=sawsim.git;a=rss
  28
  29
  30 Compiling
  31 ---------
  32
  33 Check out the source::
  34
  35   $ git clone git://tremily.us/sawsim.git
  36   $ cd sawsim
  37
  38 Sawsim is written in noweb_.  Extract the `Makefile` and compile with::
  39
  40   $ notangle -Rmakefile src/sawsim.nw | sed 's/        /\t/' > Makefile
  41   $ make
  42
  43 Run the unit tests with::
  44
  45   $ make check
  46
  47 If you're using the Python bindings (`pysawsim` or `bin/*.py`), you
  48 should run the `pysawsim` unit tests with::
  49
  50   $ ./misc/hooks/pre-commit-pysawsim-check
  51
  52
  53 Upgrading
  54 ~~~~~~~~~
  55
  56 Upgrade to the most recent version::
  57
  58   sawsim$ git pull
  59   sawsim$ make && make check && ./misc/hooks/pre-commit-pysawsim-check
  60
  61
  62 Dependencies
  63 ------------
  64
  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 ============  =====================  =================  ======================
  80
  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
  93
  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::
  97
  98      $ easy_install --user mpi4py
  99
 100    For systems with earlier versions of `distribute`/`setuptools`,
 101    which lack the `--user` option, try something along the lines of::
 102
 103      $ easy_install --user mpi4py
 104      $ easy_install --prefix $HOME/.local/ mpi4py
 105
 106 .. [2] pbs-python has no Debian package, but you can install it from
 107    source.  See the `pbs-python homepage`_.
 108
 109 .. _distribute: http://pypi.python.org/pypi/distribute
 110
 111
 112 PYTHONPATH
 113 ~~~~~~~~~~
 114
 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
 118 along the lines of::
 119
 120     export PYTHONPATH=".:$HOME/.local/lib/python2.6/site-packages"
 121
 122 to your `~/.bashrc` file to ensure that the new `PYTHONPATH` is setup
 123 for all future logins.
 124
 125
 126 Python wrapper
 127 --------------
 128
 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`.
 133
 134 Ensure that . is in your PYTHONPATH_, and run the pysawsim tests::
 135
 136   sawsim$ ./misc/hooks/pre-commit-pysawsim-check
 137
 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.
 142
 143
 144 Job managers
 145 ~~~~~~~~~~~~
 146
 147 For the `--manager` option, use whatever job scheduling system is most
 148 appropriate for your host.  For example:
 149
 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 ========================================================  =======
 158
 159
 160 Caching
 161 ~~~~~~~
 162
 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::
 169
 170   $ bin/sawsim_hist.py -s bin/sawsim -N 200 --use-cache
 171
 172 And then generate another histogram with the same `sawsim` parameters::
 173
 174   $ bin/sawsim_hist.py -s bin/sawsim -N 300 --use-cache
 175
 176 The second call will only execute an additional 100 `sawsim` runs.
 177
 178 If you ask for *fewer* runs than are contained in the cache, e.g.::
 179
 180   $ bin/sawsim_hist.py -s bin/sawsim -N 100 --use-cache
 181
 182 You will not run *any* new `sawsim` runs.  All 100 runs will be drawn
 183 at random from the cache.
 184
 185
 186 Help
 187 ----
 188
 189 As always, run::
 190
 191   sawim$ bin/<whatever> --help
 192
 193 for more details.
 194
 195
 196 Testing
 197 -------
 198
 199 You can run the internal unit tests with nose_::
 200
 201   $ nosetest --with-doctest --doctest-tests pysawsim
 202
 203
 204 License
 205 -------
 206
 207 Saswim is released under the GNU GPLv3+.  See `COPYING` for details.