Manual (Quickstart)

Right now there's only a quick-start guide here, but I'm working on the full manual, so check back soon for a link. Before you start this guide you will need to know how to use a terminal or command line. A frontend is planned but it won't be around for a while, so read this guide on the Ubuntu Community Documentation website to learn how to use a terminal. It's fun!

Installation

Currently you must compile the program from source. It doesn't install to the system directories yet, but I'm working on it. Visit the obtaining it page for more information on installing. You can also email me (check out the team page) for help, and I promise I won't tell you to RTFM.

Running

Once you have the program compiled, go into the source directory with a terminal. You should see many files and a file called "bioc". Open a terminal and type "./bioc" to run the program. If it does not run type "chmod +x bioc", and then try again.

The program will then output something like this:

#bioCity: Welcome to bioCity Matrix 0.4 (staging branch)
#bioCity: The current byte-size of the world class is 44
#bioCity: Current World Parameters
#Population Size:    40
#Dimension X:        500
#Dimension Y:        500
#Time:               1000
#Graphics:           0
#Scenario:           scen_single_pop
#dist_life: gsl_cdf_exponential_P
Timestep        Population       First   Second
0       40      40      0
20      129     129     0
40      136     136     0
60      152     152     0
80      164     164     0
100     145     145     0
120     141     141     0
140     149     149     0
160     146     146     0
#The world has ended! Input anything to quit.

This is the data outputted by the program. The lines starting with a '#' are comment lines and contain some metadata about the current virtual simulation you are running. The line:

Timestep        Population       First   Second

Are column headers for the data below. "Timestep" is the timestep that the data is being sampled at. "Population" is the total population at "Timestep", and so on. The "First" just indicates the number of organisms of the first type. Currently there is only one type, and this display will be improved soon.

The output is structured in such a way so that it is easy to import into a statistical program such as R to analyse the data. Make sure in the program you use, that you specify the "#" character as the comment character (R has this by default).

If you would like the data to be written to a file instead, run the program like this:

./bioc >> data.txt

Eventually, outputting data to a file will be an option, but for now use this technique.

Configuring The Scenario

This is probably the most interesting and important part of the program. Each virtual organism follows rules at each timestep, and these can be configured to an extent.

In the program directory you will find a file called "bioc.conf", and it will look something like this:

# For boolean values, 0 = false, 1 = true

time: 1000
population: 40
dimx: 500
dimy: 500
graphics: 0
scenario: scen_single_pop

Each field specifies the initial values of the simulation. The fields are as follows:

• time: the total time in timesteps that the program will run for
• record_interval: print out data every "record_interval" timesteps. For instance, if you set this to "1" then data will be outputted at every timestep, which is the maximum resolution possible.
• population: the starting population
• dimx: the length of the habitat
• dimy: the width of the habitat
• graphics: whether the real-time map will be displayed
• scenario: what set of rules to use, which can be configured

After this you can configure the details of the scenario. For each scenario the configuration options are different, and these are detailed on the scenarios page.

The 32x32 icons here are from the Tango Desktop Project. The logo was made in Inkscape and the website in Vim.