BoolLib
-------

Revision History: see ChangeLog.
----------------

Author:	Alex Lancaster <alex@santafe.edu>
------

Synopsis
--------

This library provides an implementation of an autonomous, synchronous
random-Kauffman Boolean network in Swarm.

Prerequisites:
--------------
	GraphLib-1.1 or higher 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.

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@santafe.edu>

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.santafe.edu/~alex
	e-mail: <alex@santafe.edu>.
