pysawsim 0.10

Python framework for the sawsim force spectroscopy simulator.

Sawsim is a force-spectroscopy simulator. See the manual for more details.

Packages

Gentoo

I’ve packaged sawsim for Gentoo as sci-physics/sawsim in my wtk overlay. To install, run:

# emerge -av app-portage/layman
# layman --add wtk
# emerge -av sci-physics/sawsim

To stay current, follow the sawsim Atom or RSS feed, and re-emerge when there are interesting changes.

You can skip the Compiling and Upgrading sections of this README ;).

Compiling

Check out the source:

$ git clone git://tremily.us/sawsim.git
$ 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]	sys-cluster/pbs-python

[1]

mpi4py has no Debian package, but you can install it with distribute (a setuptools fork) (Debian: python-distribute, Gentoo: setuptools/setuptools) via:

$ easy_install --user mpi4py

For systems with earlier versions of distribute/setuptools, which lack the –user option, try something along the lines of:

$ easy_install --user mpi4py
$ easy_install --prefix $HOME/.local/ mpi4py

[2]

pbs-python has no Debian package, 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/<whatever> --help

for more details.

License

Saswim is released under the GNU GPLv3+. See COPYING for details.