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    distribute_ (a `setuptools` fork) (Debian: python-distribute,
  67    Gentoo: setuptools/setuptools) via::
  68
  69      $ easy_install --user mpi4py
  70
  71    For systems with earlier versions of `distribute`/`setuptools`,
  72    which lack the `--user` option, try something along the lines of::
  73
  74      $ easy_install --user mpi4py
  75      $ easy_install --prefix $HOME/.local/ mpi4py
  76
  77 .. [2] pbs-python has no Debian or Gentoo packages, but you can
  78    install it from source.  See the `pbs-python homepage`_.
  79
  80 .. _distribute: http://pypi.python.org/pypi/distribute
  81
  82
  83 PYTHONPATH
  84 ~~~~~~~~~~
  85
  86 If you install Python packages at the user level (vs. system-wide
  87 installs) you may need to setup a `PYTHONPATH` environmental variable
  88 so Python can find the packages.  You'll probably want to add a line
  89 along the lines of::
  90
  91     export PYTHONPATH=".:$HOME/.local/lib/python2.6/site-packages"
  92
  93 to your `~/.bashrc` file to ensure that the new `PYTHONPATH` is setup
  94 for all future logins.
  95
  96
  97 Python wrapper
  98 --------------
  99
 100 The `sawsim` binary only runs a single pull, but you'll probably want
 101 to run many repetitions to generate enough data for significant
 102 statistical analysis.  To facilitate this, we provide the `pysawsim`
 103 module which provides a higher level interface to `sawsim`.
 104
 105 Ensure that . is in your PYTHONPATH_, and run the pysawsim tests::
 106
 107   sawsim$ ./misc/hooks/pre-commit-pysawsim-check
 108
 109 Several `pysawsim` submodules have scripts (`bin/*.py`) providing
 110 command-line access to their functionality.  Many users will probably
 111 only need a single call to `bin/sawsim_hist_scan.py` to fit their
 112 unfolding force histograms to a particular model.
 113
 114
 115 Job managers
 116 ~~~~~~~~~~~~
 117
 118 For the `--manager` option, use whatever job scheduling system is most
 119 appropriate for your host.  For example:
 120
 121 ========================================================  =======
 122 Host description                                          Manager
 123 ========================================================  =======
 124 SMP machine with many processors                          subproc
 125 Cluster with the Torque/Maui portable batch queue system  pbs
 126 Bunch of machines which can host message-passing daemons  mpi
 127 My wimpy single-processor, single-core netbook            thread
 128 ========================================================  =======
 129
 130
 131 Caching
 132 ~~~~~~~
 133
 134 By default, the python wrappers do not cache the results of previous
 135 runs.  However, if you are repeatedly running sawsim with the same
 136 parameters, you probably want to enable caching (`-C/--use-cache`).
 137 The output of each `sawsim` run will be stored in your cache directory
 138 (`-d/--cache-dir`) and recycled for future runs with the same sawsim
 139 parameters.  For example, if you place 200 runs in the cache::
 140
 141   $ bin/sawsim_hist.py -s bin/sawsim -N 200 --use-cache
 142
 143 And then generate another histogram with the same `sawsim` parameters::
 144
 145   $ bin/sawsim_hist.py -s bin/sawsim -N 300 --use-cache
 146
 147 The second call will only execute an additional 100 `sawsim` runs.
 148
 149 If you ask for *fewer* runs than are contained in the cache, e.g.::
 150
 151   $ bin/sawsim_hist.py -s bin/sawsim -N 100 --use-cache
 152
 153 You will not run *any* new `sawsim` runs.  All 100 runs will be drawn
 154 at random from the cache.
 155
 156
 157 Help
 158 ----
 159
 160 As always, run::
 161
 162   sawim$ bin/<whatever> --help
 163
 164 for more details.
 165
 166
 167 License
 168 -------
 169
 170 Saswim is released under the GNU GPLv3+.  See `COPYING` for details.