README

   1 Compiling
   2 ---------
   3
   4 Check out the source:
   5
   6   $ git clone http://www.physics.drexel.edu/~wking/code/git/sawsim.git sawsim
   7   $ cd sawsim
   8
   9 Sawsim is written in noweb_.  Extract the `Makefile` and compile with:
  10
  11   $ notangle -Rmakefile src/sawsim.nw | sed 's/        /\t/' > Makefile
  12   $ make
  13
  14 Run the unit tests with:
  15
  16   $ make check
  17
  18 If you're using the Python bindings (`pysawsim` or `bin/*.py`), you
  19 should run the `pysawsim` unit tests with:
  20
  21   $ ./misc/hooks/pre-commit-pysawsim-check
  22
  23
  24 Upgrading
  25 ~~~~~~~~~
  26
  27 Upgrade to the most recent version:
  28
  29   sawsim$ git pull
  30   sawsim$ make && make check && ./misc/hooks/pre-commit-pysawsim-check
  31
  32
  33 Dependencies
  34 ------------
  35
  36 ============  =====================  =================  =====================
  37 Package       Purpose                Debian             Gentoo
  38 ============  =====================  =================  =====================
  39 git_          version control        git-core           dev-vcs/git
  40 noweb_        source code framework  noweb              app-text/noweb
  41 GSL_          sawsim dependency      libgsl0-dev        sci-libs/gsl
  42 check_        sawsim unit tests      check              dev-libs/check
  43 python_ 2.5+  pysawsim execution     python             dev-lang/python
  44 nose_         pysawsim testing       python-nose        dev-python/nose
  45 matplotlib_   pysawsim execution     python-matplotlib  dev-python/matplotlib
  46 numpy_        pysawsim execution     python-numpy       dev-python/numpy
  47 scipy_        pysawsim execution     python-scipy       sci-libs/scipy
  48 mpi4py_       pysawsim mpi manager   [1]_               dev-python/mpi4py
  49 pbs-python_   pysawsim pbs manager   [2]_               [2]_
  50 ============  =====================  =================  =====================
  51
  52 .. _git: http://git-scm.com/
  53 .. _noweb: http://www.eecs.harvard.edu/~nr/noweb/
  54 .. _GSL: http://www.gnu.org/software/gsl/
  55 .. _check: http://check.sourceforge.net/
  56 .. _python: http://www.python.org/
  57 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.2/
  58 .. _matplotlib: http://matplotlib.sourceforge.net/
  59 .. _numpy: http://numpy.scipy.org/
  60 .. _scipy: http://www.scipy.org/
  61 .. _mpi4py: http://mpi4py.scipy.org/
  62 .. _pbs-python homepage:
  63 .. _pbs-python: http://subtrac.sara.nl/oss/pbs_python
  64
  65 .. [1] mpi4py has no Debian package, but you can install it with
  66    setuputils` (Debian: python-setuptools) via:
  67
  68      easy_install --user mpi4py
  69
  70 .. [2] pbs-python has no Debian or Gentoo packages, but you can
  71    install it from source.  See the `pbs-python homepage`_.
  72
  73 PYTHONPATH
  74 ~~~~~~~~~~
  75
  76 If you install Python packages at the user level (vs. system-wide
  77 installs) you may need to setup a `PYTHONPATH` environmental variable
  78 so Python can find the packages.  You'll probably want to add a line
  79 along the lines of::
  80
  81     export PYTHONPATH=".:$HOME/.local/lib/python2.6/site-packages"
  82
  83 to your `~/.bashrc` file to ensure that the new `PYTHONPATH` is setup
  84 for all future logins.
  85
  86
  87 Python wrapper
  88 --------------
  89
  90 The `sawsim` binary only runs a single pull, but you'll probably want
  91 to run many repetitions to generate enough data for significant
  92 statistical analysis.  To facilitate this, we provide the `pysawsim`
  93 module which provides a higher level interface to `sawsim`.
  94
  95 Ensure that . is in your PYTHONPATH_, and run the pysawsim tests:
  96
  97   sawsim$ ./misc/hooks/pre-commit-pysawsim-check
  98
  99 Several `pysawsim` submodules have scripts (`bin/*.py`) providing
 100 command-line access to their functionality.  Many users will probably
 101 only need a single call to `bin/sawsim_hist_scan.py` to fit their
 102 unfolding force histograms to a particular model.
 103
 104
 105 Job managers
 106 ~~~~~~~~~~~~
 107
 108 For the `--manager` option, use whatever job scheduling system is most
 109 appropriate for your host.  For example:
 110
 111 ========================================================  =======
 112 Host description                                          Manager
 113 ========================================================  =======
 114 SMP machine with many processors                          subproc
 115 Cluster with the Torque/Maui portable batch queue system  pbs
 116 Bunch of machines which can host message-passing daemons  mpi
 117 My wimpy single-processor, single-core netbook            thread
 118 ========================================================  =======
 119
 120
 121 Caching
 122 ~~~~~~~
 123
 124 By default, the python wrappers do not cache the results of previous
 125 runs.  However, if you are repeatedly running sawsim with the same
 126 parameters, you probably want to enable caching (`-C/--use-cache`).
 127 The output of each `sawsim` run will be stored in your cache directory
 128 (`-d/--cache-dir`) and recycled for future runs with the same sawsim
 129 parameters.  For example, if you place 200 runs in the cache:
 130
 131   $ bin/sawsim_hist.py -s bin/sawsim -N 200 --use-cache
 132
 133 And then generate another histogram with the same `sawsim` parameters:
 134
 135   $ bin/sawsim_hist.py -s bin/sawsim -N 300 --use-cache
 136
 137 The second call will only execute an additional 100 `sawsim` runs.
 138
 139 If you ask for *fewer* runs than are contained in the cache, e.g.:
 140
 141   $ bin/sawsim_hist.py -s bin/sawsim -N 100 --use-cache
 142
 143 You will not run *any* new `sawsim` runs.  All 100 runs will be drawn
 144 at random from the cache.
 145
 146
 147 Help
 148 ----
 149
 150 As always, run
 151
 152   sawim$ bin/<whatever> --help
 153
 154 for more details.
 155
 156
 157 License
 158 -------
 159
 160 Saswim is released under the GNU GPLv3+.  See `COPYING` for details.