X-Git-Url: http://git.tremily.us/?a=blobdiff_plain;f=README;h=414faca2858872cf9148c17d7435974efd98d0e2;hb=c09d9fac4eb565a30820feab2e7e6691bea6b679;hp=98d61ab89948da8c017607c7be6cbc13a1f7baf5;hpb=da768c0b62664dccb0b8560529e9da274d716396;p=sawsim.git diff --git a/README b/README index 98d61ab..414faca 100644 --- a/README +++ b/README @@ -1,11 +1,160 @@ -Warning: also my noweb-training program. +Compiling +--------- -Extract Makefile and compile with: - $ notangle -Rmakefile sawsim.nw | sed 's/ /\t/' > Makefile - $ make -Run the unit tests with - $ make check +Check out the source: -Depends on the GSL (GNU Scientific Library) development package. - http://www.gnu.org/software/gsl/ -This package is libgsl0-dev in Debian-based distributions. + $ git clone http://www.physics.drexel.edu/~wking/code/git/sawsim.git sawsim + $ 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]_ [2]_ +============ ===================== ================= ===================== + +.. _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 + setuputils` (Debian: python-setuptools) via: + + easy_install --user mpi4py + +.. [2] pbs-python has no Debian or Gentoo packages, but you can + install it from source. See the `pbs-python homepage`_. + +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/ --help + +for more details. + + +License +------- + +Saswim is released under the GNU GPLv3+. See `COPYING` for details.