BoolLib
-------
Release Notes
-------------

Date: 	10/071997
Author:	Alex Lancaster <alex@real.net.au>

This library provides an implemention of an autonomous, synchronous Kauffman 
Boolean network in Swarm.

Revision History:
-----------------
	10/07/1997  First release  Beta 0.2

Prerequisites:
--------------
	GraphLib-0.1 provided by Manor Askenazi.

The library inherits from the DiGraphLink, DiGraph and DiGraphNode classes in 
GraphLib. The user is still responsible for assigning the connections and 
states randomly but the library handles the display, updates and assignment of 
periodicity to each of the elements.

User notes:
-----------
The library permits the independent assignment of boolean function, input 
connections and states to each of the nodes in the network. Each node is 
unaware of the global (N, K) value of the network it is embedded in, it is the 
responsibility of the user to assign the appropriate number of connections - 
the node will always check all connected nodes when stepping to its new state. 
I have not stored the (N, K) value as a parameter in each node, to allow for a 
greater flexibility in modifying an existing network. If this proves to be a 
hindrance in practice, please let me know <alex@real.net.au>.

If N is the number of nodes in the network and K the exact number of input 
connections to each node then:

* A Boolean function is specified as an integer in the range (0 .. 2^(2^K) - 1)
it is the user's responsibility to ensure that a Boolean function is consistent
with K, set using:
 -setBoolFunc: (int) boolFunc

* State assignment is straightforward (0 = false, 1 = true), set using:
 -setBoolState: (BOOL) boolState

* Connections can be in two ways using
 -makeInputLink: aNode
 -makeInputLinkWithInt: (int) aNumber

The former is useful when stepping through an array of nodes, with a modelSwarm,
the latter is useful when, a node is "probed" interactively and a link can be 
formed by giving the node id (an int). For example one could run a net with 
N = 3 and K = 0 and specify the connections manually. 

If you use the latter method, it is necessary to set which Boolean network the 
node is part of using the

 -setBoolNet

method. (I may make this mandatory at some stage...)


* Each node maintains a state "history", which is used internally classify the 
periodicity of its Boolean activity. The length of the history is set to be 
twice the variable MAX_PERIODICITY which is a #define in "BoolNode.h". 
MAX_PERIODICITY is set to be the highest period one is interested in 
classifying, by default it is 7. To change this you will obviously need to 
re-compile the library.

* The periodicity is displayed by calling the function (called internally by 
the -update method)
 -displayNodeState

This function classifies nodes according to the following scheme:

   7  yellow
   6  pink
   5  grey
   4  orange
   3  brown
   2  purple
   1  red
   0  white

I have been mainly interested in using this colouring scheme for nets where the
overall network behaviour is of low periodicity, in particular when K = 2, for 
higher K where the state cycles are of much longer length, such colouring is 
debatable, the user could override these method in a derived class. I may 
eventually remove this altogther, but I included it to give users the choice of
colouring nodes if they want.

"ON" nodes are represented by a blue ring on the outside of the node, "OFF" is 
black.

* the -stepRule method will set the new Boolean state, before a synchronous 
update is made.

* the -update method actually performs the update. The demo application 
(BoolNet-0.2) included with this library demonstrates how all the library calls
work in practice.

To do:
------
* Create a -getRandomBoolNet function, that given arbitrary N and K, will 
return a randomly assigned Boolean network (connections, functions and states).
* Periodicity assignment is still done rather crudely - need to work on this.
* Representation self-connected nodes (although this is probably more of a 
GraphLib issue).
* Allowing for a non-synchronous networks.

Usual caveats:
--------------
I have developed this library mainly for my own rather idiosyncratic purposes, 
however I have attempted to keep it as general-purpose as possible, so it can 
spread throughout the meme pool of the Swarm hive. So apologies in advance if 
it doesn't work exactly as you expect. Drop me an e-mail and I'll see what I 
can do... <alex@real.net.au>

There is no warranty, either express or implied, of course.

This library is distributed under the terms of the GNU Library General Public 
Licence (attached in this directory) and was contributed by:

	Alex Lancaster 
	web:    http://www.real.net.au/~alex
	e-mail: <alex@real.net.au>.
