Cricketsim is a computational simulation written in java. It relies on perl for data analysis and gnuplot for its graphing capabilities. It should be able to run on OS X, most versions of Linux and UNIX, and Windows 2000/XP. It was designed on Solaris (a flavor of UNIX), but later ported to Windows 2000 and then to XP. As such, the current version only directly supports execution on Windows XP. It will probably run on Windows 2000 with little or no modification. It should be able to run on UNIX and most versions of Linux provided that the proper programs (java, perl, gnuplot) are installed and the cricketsim.setup file is set properly to indicate those programs' locations.
What follows will be a guide for setting cricketsim up on Windows XP. The most important thing is to install java, which will allow cricketsim to run. After that, perl and gnuplot should be installed in the default locations chosen by the particular installers (if any). You may need to tell cricketsim the path where the perl and gnuplot executables are installed. This can be done in cricketsim's Data Analysis window (under the Output menu) or more permanently in its cricketsim.setup file. See later sections for performing this setup. Installation and setup are best performed by a person reasonably familiar with the operating system that cricketsim will be installed on.
The following steps are necessary in order to install cricketsim properly:
Cricketsim relies on the use of several software packages in order to run. You must install these before you install and run cricketsim.
The packages are:
Install the latest version of java (at least version 1.4, though the current vesrion is 1.6 (often called, simply, "version 6"). Sun's site can be very confusing. Look for the "Downloads" tab or link. It may be called "Java SE" (avoid "Java EE" - this is more java content than you need), "Java SDK" or even just the "Java JRE - java runtime environment" download. Version 6 is the current version as of this writing. There is typically an update or revision number, such as "JDK 6 Update 3" or "JRE 6 Update 3". That's usually what you want. Pick the right version for the operating system you are using.
download java (will leave this page)
Java version 1.4, 5, or 6 should all work.
Get ActiveState's perl package (you only need the free version - you just need the language itself):
download perl (will leave this page)
Install this in the default location for Windows or /usr/local/bin for Unix, Linux, or OS X (or wherever your sysadmin lets you). You'll tell cricketsim where perl is installed in Initial Setup below.
Default location on windows is:
c:\Perl\bin
download gnuplot (will leave this page)
On Windows, install gnuplot directly on the c: drive, in a folder called "gnuplot". See Initial Setup for further cricketsim setup instructions.
The best location for the gnuplot executable on windows is:
c:\gnuplot\bin\pgnuplot.exe
On Unix/Linux/OS X, install gnuplot in /usr/local/bin, or any desired location (but see Initial Setup for configuration of cricketsim - you'll need to tell cricketsim where gnuplot is. Gnuplot is often part of a UNIX installation, especially on academic campuses.
A possible source for gnuplot on OS X:
http://www.versiontracker.com/dyn/moreinfo/macosx/1849
Sadly, gnuplot does not exist in a simple-to-install form for OS X (as of this writing). To get instructions on compiling the source download for gnuplot (for OS X):
http://sourceforge.net/forum/forum.php?forum_id=729403
Further information on gnuplot, particularly with regard to installation on linux/unix/os x:
http://www.duke.edu/~hpgavin/gnuplot.html
Download the cricketsim program. This is a zip file. Unzip it. Place the cricketsim folder right at the root of the C: drive on Windows (e.g., "C:\cricketsim\"). On Unix, Linux or OS X, place the cricketsim folder in your home directory. In most cases, you'll need to configure cricketsim to tell it where its data analysis tools (cricketsim's perl and gnuplot scripts) are located. See Initial Setup below.
The best location to place the cricketsim folder on Windows is right at the root of the C: drive:
c:\cricketsim
Cricketsim is run by invoking java and telling java to run cricketsim.
The simplest way to run the program from a command line (if under Windows, this is the cmd.exe program run from Start->Run). First, you must change your current directory to be the cricketsim directory (folder). When in this directory, you should see a folder called "org". That is where the code is stored.
java -cp . org.elyk.cricketsim.CricketSimGUI
If a certain memory size is desired, java can be told to use that memory (for example, for experiments with large populations). The "-Xmx300m" indicates usage of 300MB of RAM for cricketsim. Your machine must, of course, have this amount of memory available (in addition to memory allotted for the operating system and any other programs you are running simultaneously with cricketsim).
java -Xmx300m -cp . org.elyk.cricketsim.CricketSimGUI
There are several scripts to make running the program simpler (and they must remain in the cricketsim folder, which is where they will be upon unzipping the program):
These scripts can run with an alias/shortcut, but a custom script to run the program can also be written. The cs-runit.pl is a perl script which can be modified to run specific sets of parameters, see that file for an idea of what can be done (familiarity with perl is a must, however).
java -cp . org.elyk.cricketsim.CricketSimConsole file my-experiment.prm
Cricketsim will write data files to folders inside the CSData1.2 folder (where it stores all experiment results). Each run specifies a subfolder for that experiment's results. That subfolder will be named according to the "Experimental condition subdirectory/folder" found in the parameter file (or the setting in the General parameters). Inside of that experiment subfolder will be another subfolder named with a unique name (based on time and date that the run began). See the user manual for more details.
After a cricketsim run has concluded, the data can be "analyzed" and graphed using a number of perl and gnuplot scripts to analyze and plot the data. These data will sit in the experiement's run's subfolder (the one with the "cs2008-..." name - the one based on year/month/day/hh/mm/ss). Just inside the experiment subfolder will be an html file. Double-clicking this will open up a browser file (firefox, IE, whatever is your default) - this will display a few links for each run - click on them to see various plots (some show few plots for an overview, other links are more in-depth).
All of this output is due to the perl scripts written in the Tools directory. They may of course be modified by a competent perl programmer to produce any html layout desired, to run any other gnuplot graphs desired, or to perform/display/format any other data or calculations which are needed. Cricketsim produces a great quantity of data for each run; there are many possible ways to interpret these data.
To reproduce the two-population experiments that we performed, the analysis (really, data collation) and graphing routines we used are included. If you are using many populations or have runs that last longer or shorter than 5000 time steps, these analysis and graphing routines will probably require modification. These scripts can provide the foundation for developing specialized experiments using cricketsim to test hypotheses other than the ones we have tested in our work.
Since Windows 2000/XP have caused problems with automated analysis, and since variations in gnuplot and perl can contribute to unusual behavior, cricketsim's automated analysis has been disabled. If running under Unix, it could be re-enabled (in the CricketSimGUI.java file, followed by a recompile). But the following perl script makes this largely unncessary, even though it is a brute-force approach - it will analyze everything in the data directory given as the first command-line argument (CSData1.2 in the example below).
From the cricketsim directory, under a DOS/command shell, run the following:
perl Tools\cs-analyze-all.pl CSData1.2 c:\cricketsim\Tools c:\gnuplot\bin\pgnuplot.exe
This should analyze all contents of the CSData1.2 directory - all runs of all experiments found there. The results of each experiment can be browsed by going into the experiment's directory and clicking on "csdata.html" (opening up your firefox/opera/ie/etc. browser). Results are displayed in several forms.
cs-analyze-all.bat
A batch file to run this analysis script is also provided in the cricketsim main directory. You can double-click that (assuming your installation of cricketsim and gnuplot matches the expected defaults, which are c:\cricketsim\Tools and c:\gnuplot\bin\pgnuplot.exe). This will execute the perl script on the CSData1.2 directory (everything inside will be analyzed/graphed). For more control, use the perl script command-line above, altered as needed. For even more control, write or modify your own analysis scripts to perform statistical or other analyses, etc.
If you have a number of experiments which have already been analyzed and you don't want to wait for them to be reanalyzed when you add a few new experimental runs, take the old experiments out of the CSData1.2 folder (or rename this folder and run your experiments in a new CSData1.2 dir, or set the data directory name in the General parameters). Any of these techniques mean that your data are now separated into different folders, each of which can be analyzed individually by the cs-analyze-all.pl script.
The following instructions are generally only needed if cricketsim does not produce plots or data analysis files at the end of an experimental run. Usually, the reason that cricketsim may fail to produce plots (and html files to link to many of those plots) is that perl or gnuplot cannot be found by the program.
Cricketsim must know where its Tools folder is, as well as the location of perl and gnuplot. These are specified in a file called "cricketsim.setup", which is just inside the main cricketsim folder. This file may be edited directly so that the settings can be maintained across runs, but the double-quotes around the paths must remain intact. Also, double-backslashes are required in this file instead of the standard single-backslash normally found in a windows path (UNIX, etc.: use single slashes, no need for double-slashes).
The default settings in cricketsim.setup are:
toolDir "c:\\cricketsim\\Tools" gnuplotCmd "c:\\gnuplot\\bin\\wgnuplot.exe" perlDir "c:\\Perl\\bin"
These settings assume you have moved the cricketsim code and the gnuplot folder (directly from their unzipped .zip files) right onto the C: drive. The default location for perl is what the ActiveState installer will give you: c:\Perl\bin.
You may also edit the cricketsim.setup information from within cricketsim itself, though the settings will only last as long as cricketsim is running.
From the main window, select the Output menu, then choose Data Analysis:
The data tools directory is a full path (including the drive designator, usually C:\ on a typical windows installation). The cricketsim tools consist of several perl and gnuplot scripts. "cs-analysis.pl" is one of these tools. Browse to whatever folder holds these tools. It is usually "C:\\cricketsim\\Tools".
Perl and Gnuplot are used by cricketsim to create graphs (gnuplot does this with perl's help) and to analyze some of the raw data files to produce more readable ones. The gnuplot command and perl directory must be full paths to these other software components. The perl directory must be the location of the "perl.exe" program. The gnuplot command must be the location of the gnuplot program ("wgnupl32.exe" or "wgnuplot.exe" or "pgnuplot.exe"). This command must include the program's name as well (will be "wgnupl32.exe" with an older version of windows-based gnuplot, "wgnuplot.exe" for the 4.x versions). If these are not set correctly, data analysis (plots, tables) will not be performed and the program will hang. The raw data will always be, but they must be analyzed manually if perl and gnuplot cannot be found. Use the "browse" button to set these values if needed.