BUGSIM README FILE ================== This file is provided with the bugsim application and provides a quick startup guide to using the software. What is Bugsim? --------------- Bugsim is an application which allows you to explore animal interactions with resources using a random walk model. The random walk is described in detail in many sources (see thesis available at http://jimbarritt.com/academic/bugsim/download.html) Bugsim creates an environment in which you can place resources at any location and then allow random walkers to move around the "world" until they intersect with a resource. The original application for the software was to model oviposition (egg-laying) behaviour of butterflies (Pieris rapae) so when the foragers intersect a resource they "lay an egg" on the resource. The total number of eggs is then reported for each resource. "Eggs" could be viewed in more abstract terms simply as "number of visits" There are many parameters and the output is reasonably complex, this file intends to provide a simple overview to get you started, more complete documentation will hopefully arrive at some point but much can be learned from the thesis available from the location above. For more information or even a guided tour please email Jim Barritt, the software author at jim@planet-ix.com. Installation ------------ You should have either downloaded or been provided with a Zip file containing everything you need. Unzip this into a folder of your choice, maybe called "bugsim" There should now be a JAR (Java Archive) file, several script files (.cmd or .sh) and two sub directories, "lib" and "experiments" The "lib" directory contains some supporting files essential for bugsim to operate. The "experiments" directory is a place to store configurations for experiments you want to create and run with bugsim (see below). The script files allow you to start the software either under windows or linux (also see below). If you are running under unix you will need to make the .sh files executable by using the following command, eg. chmod +x editparameters.sh There are also zip files containing the complete Java Source code and script files for R (www.cran-r.org) to analyse the results but these latter are rather complex and totally undocumented! Finally there are some CSV files which contain layouts of resources in the directory "field-resource-layouts". Applications ------------ There are two executable applications included. The Experiment Editor is an application which allows you to specify the many parameters for the software, such as how many foragers to release, what the resource layout should be, what parameters to vary and so on. To start the experiment editor, execute the script called "editparameters.cmd" or "editparameters.sh" (on unix) The Experiment Executor then executes a particular set of parameters and reports the results. Initially you will see a view of the landscape showing the foragers moving around. This will slow down execution somewhat so you can simply close the landscape window and the experiment will run faster. To start the experiment executor, execute the script called "runinteractive.cmd" or "runinteractive.sh" (on unix) Step by step - Execution ------------------------ The most important concept in understanding how to use the software is the "Experiment". This is stored as an XML file and tells the experiment executor how to run the software. There is a simple experiment included in the Zip file in the "experiments" directory called "first-experiment.xml". You can see the software in action by simply typying "runinteractive.cmd" in a windows console (command window) in the directory in which you unzipped the application zip file. You will see a dialog that allows you to select an experiment file. Initially it may not be displaying anything in the list. Click the button with three dots (...) at the top to browse to a new location and navigate to the "experiments" sub directory created when you unzipped earlier. You will now see an entry in the list of experiment plans called "First Experiment". Select this and click "open" The application will start and you will see two windows, on the left a view of the "landscape" and on the right a control interface which allows you to run the experiment. The first experiment contains a simple random walker with both visual and olfactory senses and a very simple resource layout. You will see the visual field represented as a circular segment colored blue / purple. You can zoom in and centre on the butterfly agent to see what it looks like close up - two dots indicate the location of the olfactory sensors. There are quite a few options, unfortunately not yet documented, however a little exploration should show you how things work. It is possible to zoom in and out of the landscape view and "click and drag" on the view to move the landscape around in the viewer if you are zoomed right in. There is also a "centre on agent" option which is useful if you want to follow a particular agent when zoomed right in. When using a big landscape, the relative sizes of the resources are automatically exaggerated so that their locations are obvious at bigger scales, when soomed in everything will be to scale. The default scale is assumed to be 1 logical unit = 1 cm. The controller window allows you to execute a single step, or run the entire experiment until complete or run for a specified number of steps. There is a "delay" box (in milliseconds) which allows you to slow down the steps so that you can see whats going on in the viewer. The first experiment is set up with a very simple layout and will release 1000 foragers into the landscape. As more eggs are laid on the resources they change colour from green to yellow. When the experiment is complete you can look at the results in the output directory (by default "output" in the directory the application was unzipped to). Here you will find all kinds of CSV files with various results in them. Again at this point these are not fully documented but should be relatively obvious. Using the R package to load some of these files will probably help. Step by Step - Experiment Creation ---------------------------------- You may now want to try and adjust some of the parameters. Open the experiment editor using the editexperiments script. You initially see a rather complex dialog which allows all of the parameters to be adjusted. In order to edit the first experiment select the "..." button at the top and a browse dialog identical to that for running experiments will be shown. Choose the first experiment to open. There are many parameters, but the most immediately interesting ones are those in the "forager" tab. Here you can set the step length and turning angle concentration of the foragers. Navigate to this tab and try changing the turning angle concentration from 10 (highly directed) to 0.5 (very random). Then you need to provide a new name for this experiment - go to the "general" tab and change the "name" from "FIRST" to whatever you like, maybe "FIRST-A". Then click on the "Save As button" A save as dialog will appear which will already have a filename suggested so just click "ok". You can now run the experiment executor again and should see your new experiment. Select this and run it to see how the random walk has changed. Further Hints ------------- More documentation to follow! Hopefully this will give you a basic idea and at least allow you to see the software in action please contact us at jim@planet-ix.com for more help until we get the documentation complete! Enjoy Jim Barritt