--------------------------------------------------------------------
RUNNING BIOLOGO


To run BIOLOGO, from this directory:

% cd BIOLOGO
% ./BIOLOGO <BIOLOGO file> <CompuCell3D root directory>

BIOLOGO will subsequently run on the specified BIOLOGO file, and
then generate new plugins for hamiltonians and automata in the 
following spot:

<CompuCell3D root directory>/src/CompuCell3D/plugins

A new config file in:

<CompuCell3D root directory>/examples/<BIOLOGO file name - .xml>/<BIOLOGO file name>

(The config file will share the same name as the BIOLOGO file, they
 are both XML files).

A new Makefile.am in:

<CompuCell3D root directory>/src/CompuCell3D/plugins

And finally a new configure.in in:

<CompuCell3D root directory>


In addition an intermediate file will be generated within the BIOLOGO/
directory, this is only a temporary helper file.


CompuCell3D can then be run using these new plugins and new 
configuration file, after reconfiguration and recompilation.  
This is done in the normal way from <CompuCell3D root directory>:

% ./autogen.sh
% ./configure --with-xercesc=<xerces root>
% make

Note that automake is now going to use the newly generated
configure.in and Makefile.am, adding all newly created plugins
to the compilation.


Also you need in the Makefile within BioLogoReader, to modify
the paths for all included libraries accordingly but the Makefile
is simple and short, it should be straightforward.


--------------------------------------------------------------------
SYNTAX OF BIOLOGO

All BIOLOGO files start and end with <CompuCell3D> and </CompuCell3D>
tags, respectively.

Aside from the hamiltonian and automata declarations, a BIOLOGO file 
and a CompuCell3D configuration file are no different.  That is, all
configuration file information that should appear in the configuration
file generated by BIOLOGO should be identical in the BIOLOGO file.

Example:

<Potts>
   <Dimensions x="50" y="50" z="50" />
   <Anneal>10</Anneal>
   <Steps>10000</Steps>
   <Temperature>5</Temperature>
   <Flip2DimRatio>1</Flip2DimRatio>
</Potts>

This example is from the basic cell sort.  This is how this segment
should appear in the configuration file, and so this is how it
should appear in the BIOLOGO file.

The difference is as mentioned, hamiltonians and automata.  These
are added to CompuCell3D as plugins, by the BIOLOGO compiler.




HAMILTONIANS
------------
Hamiltonians are functions that return values of type double. 
Their template is as follows:


<Hamiltonian name="<string>">
<Input name="<string>" type="<datatype>" params="<int>" />
<Input name="<string>" type="<datatype>" params="<int>" />
....
<Field name="<string>" type="<datatype>" x="<int>" y="<int>" z="<int>" />
<Field name="<string>" type="<datatype>" x="<int>" y="<int>" z="<int>"
....
<Step>
   ... BIOLOGO statements ...
</Step>
</Hamiltonian>



A hamiltonian thus has three sections:
1. Input variables
2. Field names
3. Step function (produces an energy deltaE for the Potts Model)

    
1. Input Variables
These are specified as variables that, when this Hamiltonian is
referenced as a plugin in XML (that plugin will have the same name
as this hamiltonian), these variables should be specified as inputs.
Attribute 'name' gives the name of the input, attribute 'type' the
datatype, and attribute 'params' (optional) gives a number of
cell types to expect as arguments.  Right now this can only be 1 or 2.

For example, the well known Contact hamiltonian's Input section would
look like this:

<Input name="Energy" type="double" params="2" />
<Input name="depth" type="int" />

There is also one unique type of Input that should be spoken of.
This is the 'file'-'field' relationship.  A good example is
in the Chemical hamiltonian, for ConcentrationFile:

<Input name="ConcentrationFile" type="file"
fieldname="reactiondiffusion" fieldtype="float" fieldx="71"
fieldy="36" fieldz="211" />

This tells BIOLOGO that an input of ConcentrationFile should be
used which accepts a string for a filename, and reads once at the
beginning to populate field reactiondiffusion, of type float and
dimensions 71x36x211.  If you want repeated reads at every given #
of timesteps, you can also add a frequency tag:

<Input name="ConcentrationFile" type="file"
fieldname="reactiondiffusion" fieldtype="float" fieldx="71"
fieldy="36" fieldz="211" frequency="steps" />

Which says the frequency provided by the user should be measured
in timesteps (right now it's the only option).  When this plugin
is subsequently referenced then in the configuration file,
the input <ConcentrationFile> will give the filename, and
<ConcentrationFileFreq> the frequency for reading.
An example of this is in dicty.

Either of these types of input also creates a field as described
below.


2. Field Names
These fields are declared as three-dimensional arrays of type
<datatype> with the specified x, y and z dimensions.  When referenced
in regular expressions, the syntax <name>[x][y][z] is used.  These
can be referenced within the hamiltonian to which they are declared, 
and also in any declared automata (that syntax is explained later).


3. Step function
This function returns a value of type double for the change in energy
assuming this is run at every flip attempt to help determine deltaE.
The function is implemented using normal BIOLOGO statements, which
are described in the next section.

Note, there are also some predefined variables that can be
referenced in each hamiltonian:

potts.cellfield: a 3D field of type cell.  Referenced with the []
operators like a normal field
pt: the current selected point for flipping (type pixel)
oldcell: the current cell that lies at the selected point (type cell)
newcell: the candidate cell that selected point may flip to (type cell)

A unique statement that can be used here is <return>.
<return value="<expression of type double>" />

If this statement is reached the expression is returned as the
change in this energy.



AUTOMATON

An automaton, or cell model, can be defined by the following
template:


<cellmodel name="<string>" />
<useplugin name="<string>" />
<useplugin name="<string>" />
... declare statements ...

<celltype name="<string>">
<creation>
.... BIOLOGO statements ....
</creation>
<updatevariables>
.... BIOLOGO statements ....
</updatevariables>
<updatecelltypes>
.... BIOLOGO statements ....
</updatecelltypes>
</celltype>

(Same above template for all celltypes)

</cellmodel>


The first section of the model contains the names of any plugins
that can be referenced within this model.  If plugin A is specified
as included using the <useplugin> tag, all of A's Inputs and Fields
could be referenced within this cell model using A.<inputname> or
A.<fieldname>.

The following section of the model can contain an unlimited number
of BIOLOGO 'declare' statements, each declaring a model variable
for all cells in this simulation to possess (these variables
can subsequently be referenced in all variables of type 'cell').

The <celltype> section should be repeated for all celltypes of this
model (i.e. the model chickenlimb had 2 celltypes, NonCondensing and
Condensing; model dicty had 3, Prespore, Prestalk and Autocycling).
A Medium type is automatically declared by default.  If the user
specifies a Medium celltype in BIOLOGO it is ignored.

<creation> section contains BIOLOGO statements that should be 
executed upon the creation of a cell of this type.  This also includes
the point where a cell transitions to this type.

<updatevariables> section contains BIOLOGO statements that should
be executed at a flip attempt of this cell 
(unless this cell changes type).

<updatecelltypes> section specifies the conditions for a cell to 
BECOME THIS TYPE.  Transitions are attempted for a cell whenever a
point inside that cell is chosen for flipping in the Potts Model.
If a cell does not change type, the code in <updatevariables> is
subsequently executed.  If a cell does change type, the code in the
<creation> section of the new cell type is executed.
A special statement in this section is the <changeif> statement:

<changeif currenttype="<string>" condition="<boolean expression>" />

This says that a cell should change type if its current type is
<currenttype> and <condition> is true.
You can have many <changeif> statements in an <updatecelltypes>
section.  You cannot use this statement anywhere else.
-------------------------------------------------------------------


BIOLOGO Statements (can be used in a Hamiltonian <step> section,
<creation> sections, <updatevariables> sections, or 
<updatecelltypes> sections:

1. <declare> : Use in coordination with one of the following to declare
a variable.  All variables (with the exception of those predefined)
must be declared before use.

<boolean>, Attributes: name(string), value(optional, string)
Declare a boolean variable <name> and initialize to <value>
<integer>, Same attributes, declare an integer
<float>, Same attributes, declare a single-precision floating point
number
<double>, Same attributes, declare a double-precision floating point
number
<char>, Same attributes, declare a character
<string>, Same attributes, declare a string
<pixel>, Same attributes, declare an object of type pixel.  You can
reference its coordinates using <name>.x, <name>.y and <name>.z
<cell>, Same attributes, declare a cell object.  This cell follows
whatever cellmodel was declared and contains whatever variables
were declared in this cellmodel.  By default all cells contain one
member variable, type, of type string - referenced using <name>.type.
This will contain one of the celltypes declared in the cellmodel.

Sample: <declare><boolean name="jack" value="false" /></declare>
        <declare><int name="gus" /></declare>


        
2. <copy>, Attributes: to(variable name), from(expression)
Copy the value of expression <from> into variable <to>.  <to> must
be a defined variable (either user-declared or pre-defined).

Sample: <copy name="gus" value="3*2" />



3. <if>, Attributes: condition(expression of type boolean)
   <elseif>, Attributes: condition(expression of type boolean)
   <else>, Attributes: none

Implements a conditional block. 


<if condition="<expression>">
  ... BIOLOGO statements ...
</if>
<elseif condition="<expression>">
  ... BIOLOGO statements ...
</elseif>
<elseif condition="<expression>">
  ... BIOLOGO statements ...
</elseif>
<else>
  ... BIOLOGO statements ...
</else>

Execute the BIOLOGO statements within the tag of whichever condition
passes first.  If all fail, execute the statements within the <else>
tags.  <elseif>s and <else>s are optional when using <if> clauses.


4. <do>, Attributes: condition(boolean expression)

Executes a set of statements (at least once) while <expression> 
is true.

<do condition="<expression>">
   ... BIOLOGO statements ...
</do>


5. <while>, Attributes: condition(boolean expression)

Executes a set of statements while <expression> is true 
(not at least once).

<while condition="<expression>">
   ... BIOLOGO statements ...
</while>


6. <for>, Attributes: variable(variable name), from(expression),
   to(optional, expression), downto(optional, expression),
   step(expression) <- Note: one of either to or downto is 
   necessary.

Counting for loop.  Executes a set of statements, starting variable
<variable> at <from>, going to either <to> or <downto>, by a count
of <step>.  When <variable> hits <to> (or <downto>), stop.

<for variable="<variable name>" from="<expression>" to="<expression>"
step="<expression>">
  ... BIOLOGO statements ...
</for>


7. <forneighbors>, Attributes: variable(variable name of type pixel),
    point(variable name of type pixel), grid(a three-dimensional 
    field), distance(double), depth(int), checkbounds(boolean)

This is a little unique, but useful.  At each iteration of this loop,
a neighboring pixel within depth <depth> to <point> within <grid> 
is calculated and stored in <variable>.  Distance between <point> 
and <variable> is subsequently stored in <distance>.  <checkbounds>
is turned on if CompuCell3D should implement bounds checking on
each point it finds.

------------------------------------------------------------------

BIOLOGO Expressions
The following symbols can be used:

+: Addition
-: Subtraction
*: Multiplication
/: Division
%: Mod
(: Parenthesis
greater: Greater than
less: Less than
greaterequal: Greater than or equal to
lessequal: Less than or equal to
equal: Equal to
notequal: Not equal to

Strings in expressions are surrounded by dollar signs ($).
Characters in expressions are surrounded by single quotes (').


In all other ways, expressions can be written in C/C++ notation.
In this way several predefined functions of these languages
can be referenced (drand48() for example).


Questions?
Trevor Cickovski
tcickovs@nd.edu