Title: TOC
Last saved by: M
Company: Indiana University

Developing a CC3d simulation--overview.

We intend CompuCell to be a user-friendly tool.  Once you have CompuCell installed, you will be able to design, run and post-process your own simulations of biological systems.  Here we give a brief outline of the steps involved.  Currently, all CompuCell simulations are based on a configuration file which the player reads and executes.  This configuration file contains the basic parameters that define the cells and their interactions and directs CompuCell to other user-defined text files containing initial configurations of cells and chemical fields.

So the first step in a CC3d simulation is to design the cells and their interactions.  Some examples of properties that you can give cells are preference for a particular volume or shape, response to chemical gradients, secretion of chemicals, adhesion, etc.  Since the Monte Carlo method is based on fluctuations, you can also specify, for instance, how much the volume will fluctuate around the preferred volume.

CC3d includes some stock initializers that create an initial configuration of cells, but you will probably want to create your own.  You specify the initial configuration in a data file with a simple format.  You can create this file with a scripting language or just type it in by hand if you wish, working from a diagram on some graph paper.  In the future, CC3d will have graphical tools to help with this process.

Once you have written your configuration file, running CC3d is as simple as playing a movie.  You simply open the player, select the configuration file you want to use (from the file:open menu) and click the "play" button.  You can select visualization options and customize the output you wish.  In addion to visualizing (and saving) the cell fields, you can look at chemical fields, pressure fields, velocity fields, etc.

Finally, you can analyze your data with any standard techniques for analyzing and visualizing spatial data.  We are currently developing some basic tools to add to the CC3d player.

Writing Your Own Configuration files
IV.A.  XML Structure and Syntax
XML, which stands for "eXtensible Markup Language" is an extension (or superclass) of html.  If you are familliar with html then you should find using xml easy enough.  If not, it will take some getting used to.  We use xml for the configuration file because it is easy for a computer to "parse", i.e. find and interpret meaningful information.  In the xml configuration file you will specify the general parameters of your simulation such as what types of cells, their properties, etc.  The actual outcome is random, but based on the specifications in the xml configuration file.

A typical block of xml you will use in CompuCell3d looks like this:

<SectionName Attribute1="attribute" Attribute2="attribute">
	<Variable1 VarAttribute1="attribute" VarAttribute2="attribute">
		ValueOfVariable
	</Variable1>
	<Subsection>
		<VarA>ValueA</VarA>
	</Subsection>
</SectionName>

If that looks like a lot of gobledeegook, don't worry.  I'll explain it.  The first thing to notice is that in xml you specify where each statement begins and ends like this
	<begin>
		...
	</begin>
As a matter of style, defining characteristics, or properties, of a section are specified with the syntac PropertyValue="property", while specific values of variables are usually placed  between a "begin" and "end" for that variable.  An example where a variable might have an attribute could be
	<Age Style="numeric">38</Age>
			or
	<Age Style="InWords">"Thirty-Eight"</Age>
			or
	<Age Style="Roman">"XXXVIII"</Age>.
I say it's a matter of style, because one could just as well opt for the syntax possibilities:
	<Age>
		<Style>"Roman"</Style>
		<Number>XXXVIII</Number>
	</Age>
or
	<Age Style="Roman" Value="XXXVIII"/>.
In the last example, both field are attributes.  In the second to last they are both values.  In most parts of the configuration file a mixture is used.  In the reference section of the manual you will find the proper syntax laid out explicitly.

XML is hierarchical and nested.  That means that sections can contain sub-sections, and the properties of sub-sections apply only to the parent sections that they are "nested" in.  The section called "Subsection" in the example is nested within the section "SectionName".  So VarA only takes the value "ValueA" within "Subsection".

Configurtaion File Contents
The configuration file will contain two main types of blocks, called plugin's and steppables.  Here's the difference.  A plugin is a routine that sets the global properties of your simulation such as cell properties. Plugin is also called every spin flip attempt. A steppable is a routine that operates on the CompuCell3d lattice each Monte Carlo Step (MCS). It is important to first list plugins and after all the plugins for a given simulation have been listed, one lists steppables. If you do otherwise, or mix plugin and stoppable declaration in the configuration file you will get cryptic runtime error.

Important: It is crucial to understand the difference between spin flip and Monte Carlo Step (MCS). Monte Carlo Step consists of many spin flip attempts. Typically the number of spin flip attempts is equal to the number of lattice sites, but this is not a requirement and can be changed in the configuration file. Failure to differentiate between MCS and spin flip attempts is a common misconception among people who try to use CPM.

Your first CompuCell  simulation. 

I will keep things as simple as possible and instead of starting with introduction, motivation, overview etc. I will show you complete configuration file for the cellsorting simulation. I found that looking at the example is the best way to grasp the idea of how to write CompuCell configuration file. Plus there is really not magic to it, so let’s start: