Installation Guide

qsims is still under development, and as an "alpha" stage project, it still has quite a few rough edges. One of those is installation. While the actual C++ code for qsims is very portable, the Makefile is a horrible hard-coded hack. It seems to work fine on Mac OS X 10.3, FreeBSD 5.2.1, and at least some Linux distributions. It should work on any Unix-like system with little or no modification to the source, and minor changes to the Makefile. In particular, you may want to add platform-specific compiler optimization flags--these can often give a speed boost of about 10%.


FFTW--a Fast Fourier Transform library--is required. FFTW is a free, efficient, cross-platform FFT library. While it doesn't quite match the efficiency of some platform-specific vendor-supplied FFTs, it comes close. qsims was written to allow easy substitution of other FFT libraries, so don't give up if FFTW doesn't work for you. For a very slight speed-up when running qsims, you may want to create a system "wisdom" file for FFTW--see the FFTW documentation on how to do so (note that this can take a horribly long time--perhaps a day or so--and thus is likely not worth it unless you run an incredible number of simulations).

popt--a command-line option parsing library--is required. libpopt is probably already installed on most Linux and BSD systems. On Mac OS X, use Fink to get a working version--the standard libpopt source doesn't seem to compile correctly. It wouldn't be too hard to modify qsims to use a differnt command-line parsing package, although I currently have no reason to do so.

GNUPLOT--a graphing and plotting package--is recommended. It's the best way to plot the "grid" output files qsims produces. The tutorial discusses how to use GNUPLOT for this purpose. GNUPLOT is available for just about every platform. GNUPLOT 4 or later is required for surface plots of 2d grids. On Mac OS X, AquaTerm is also recommended as an accessory for GNUPLOT. Note: it may be helpful to install various image support libraries (e.g. libpng) before installing GNUPLOT.

ffmpeg--an image-to-movie conversion package--is recommended. ffmpeg can take the images produced by GNUPLOT and stitch them into mpegs or other video formats. Note: it may be helpful to install various image support libraries (e.g. libpng) before installing ffmpeg.


Once you get the required dependencies installed, download qsims from SourceForge. Then, unzip, and un-tar qsims:

% tar xvzf qsims-0.4.0.tgz

Change directories to the new qsims-0.4.0 directory, then use make to compile everything:

% cd qsims-0.4.0
% make all

If all goes well, qsims will be compiled, and you'll be left with a binary named "qsims" in the current directory. It's up to you to copy it by hand to your desired location (/usr/local/bin is a good choice). Refresh your shell's cached list of available executables (usually done by typing rehash, or just by logging out and back in), then you're ready to go.

Test qsims by running a benchmark:

% qsims -b 4

This causes qsims to run 4 time steps of a pre-defined benchmark simulation. The benchmark does not perform any correctness checks, but rather is purely for speed measurements. For reference, my 550 MHz PowerBook G4 takes about 24 s to run the benchmark command above if I compile with platform-specific optimizations, and 27 s otherwise.


Linking error: Did all the source files compile OK? Are FFTW and libpopt installed? Are you using the latest version of gcc?

Crashing on run: Try running a benchmark. If it still crashes, a bad or incorrectly-linked library is a possibility. Report the error via the project page on Sourceforge.

Exits immediately after simulation parameters are input: Check to make sure the target output directory exists, and can be written to.

Compilation problem: If you're not on OS X or BSD, I may not be able to help. If you do figure out a solution (or--even better--develop a makefile that doesn't suck), let me know.

Other problems: Contact me at trbeals at users d0t sourceforge d0t net.

qsims is hosted by Logo
Last updated 6 April 2005
by Travis Beals.