DISCRETE DYNAMICS LAB
=====================
Cellular Automata - Random Boolean Networks.
July 1995 (copyright (c) Andrew Wuensche 1993)

Santa Fe Institute
and The University of Sussex (COGS)
wuensch@santafe.edu
andywu@cogs.susx.ac.uk

-----------------------------------------------------------------------
Note:
This text file includes the first sections of the DDLab reference manual, 
namely the index, overview and quick start instructions.  The full
manual (but without illustrations) is a Word for Windows  file "ddlabop.doc"
contained in "ddlab.zip". For the fully illustrated hard copy of the manual
contact the author. DDLab is undergoing continuous development. Check
 for the latest update at Alife Online at the Santa Fe Institute and  follow 
the download instructions described in #1.1. 
   Any comments on DDLab or feedback on your applications  is welcome.

Suggestion:
Try running DDLab straight away by following the quick start examples.

-----------------------------------------------------------------------
Index.
-----------------------------------------------------------------------
Overview.
-----------------------------------------------------------------------
A1.  Introduction
A3.  Presentation options
A4.  Filing and Printing
A5.  Mutations
A6.  Statistical measures and data
A7.  Reverse algorithms
A8.  Sculpting attractor basins
A9.  Hardware and software requirements
A10. References
-----------------------------------------------------------------------
Quick Start Instructions
-----------------------------------------------------------------------
1. Unzipping and running.
   1.1. Updates to DDLab.
-----------------------------------------------------------------------
2. The user interface.
   2.1, Input.
   2.2. Backtrack.
   2.3. Changing the graphics set-up.
-----------------------------------------------------------------------
3. Quick start examples
   3.1 Basin of attraction fields.
   3.2. "Backwards" space-time patterns, and state-space matrix
   3.3. Basins of attraction fields for a range of network sizes
   3.4 A single basin of attraction.
   3.6. A subtree.
   3.7. Space-time pattern only, 1d
   3.8. Space-time pattern only, 2d (game of life).
   3.9. "Screen-saver" demo.
-----------------------------------------------------------------------
Reference Manual
-----------------------------------------------------------------------
4. Starting DDLab, memory, and the user interface.
      4.1. Title bar.
      4.2. DDLAb version, graphics and mouse status.
      4.3. Memory available.
      4.4. Virtual Memory.
      4.5. Prompts.
-----------------------------------------------------------------------
5. The first prompt (and graphics setup).
   5.1. Field, or a run requiring a seed.
   5.2. Graphics set-up.
   5.2.1. VGA and SVGA.
      5.2.2. Black or white background.
   5.3. Options.   
   5.4. Random number seed.
   5.5. Exit DDLab.
-----------------------------------------------------------------------
6. Network size, 1d.
   6.1. Setting range of sizes.
   6.2. Setting one network size.
   6.3. Network size limitations.
-----------------------------------------------------------------------
7. Cell scale.
-----------------------------------------------------------------------
8. Neighbourhood.
   8.1. Setting neighbourhood size or mix.
   8.2. Setting the neighbourhood mix.
   8.3. Loading a neighbourhood mix file.
   8.4. Setting the neighbourhood mix by hand.
   8.5. Setting the neighbourhood mix at random.
   8.6. Reviewing the neighbourhood mix.
      8.6.1. Reviewing the neighbourhood mix in large networks.
      8.6.2. Jumping to a new cell index.
      8.6.3. Saving the neighbourhood mix.
      8.6.4. Other options to review and alter the neighbourhood mix.
-----------------------------------------------------------------------
9. Wiring.
   9.1. Network geometry
   9.2. The pseudo-neighbourhood.
   9.3. Setting the wiring.
-----------------------------------------------------------------------
10. Quick wiring settings.
   10.1. Loading the wiring scheme.
   10.2. Regular 1d wiring.
   10.3. Regular 2d wiring
      10.3.1. Conserving wiring memory in regular 2d networks
      10.3.2. Setting 2d network size.
   10.4. Random 1d wiring.
-----------------------------------------------------------------------
11. Special wiring.
   11.1. Set network geometry.
   11.2. Set special wiring.
   11.3. Special wiring, regular 1d (treat as random).
   11.4. Special wiring, regular 2d.
   11.5. Special wiring, random.      
      11.5.1. Confining random wiring to a set zone.
      11.5.2. Self wiring.
      11.5.3. Distinct wiring.
   11.6. Wiring by hand.
      11.6.1. Wiring by hand in large networks.
-----------------------------------------------------------------------
12. Reviewing Wiring.
   12.1. The wiring matrix, and 1d or 2d wiring graphic.
   12.2. The wiring matrix.
      12.2.2 Revise wiring, wiring matrix.
      12.2.3 Revise by hand.
      12.2.4 Randomly rewire.
      12.2.5 Reset wiring options.
-----------------------------------------------------------------------
13. Rules.
   13.1. The rule-table.
      13.1.2. The totalistic code table
      13.1.3. Totalistic rules.
   13.2. Rule table matrix.
   13.3. Single rule or rule mix.
      13.3.1. A rule mix with just one rule.
   13.4. Rule mix.
   13.5. Rule mix options.
      13.5.1. Rule mix with no limit.
      13.5.2. By hand.
      13.5.3. Majority.
      13.5.4. Majority + end bits flipped.      
      13.5.5. Random.
      13.5.6. Random + canalyzing.
      13.5.7. Setting a limited sub-set of rules for random selection.
   13.6. Setting the selection method for a singe rule (by hand).
      13.6.1. Methods for setting a rule.
      13.6.2. The rule window.
   13.7. Seting the majority rule.
   13.8. Setting the "game of life" rule.
   13.9. Setting the rule in decimal.
   13.10. Setting the rule at Random.
   13.11. Setting the rule as bits.
      13.11.1. Setting bits with the mouse.
      13.11.2. Setting bits from the keyboard.
   13.12. Setting the rule in hex.
   13.13. Repeating the last rule.
   13.14. Loading Rules.
      13.14.1. Single rule file encoding.
      13.14.2. Conflicts in neighbourhood size between network and file.
   13.15. Rule mix selection by hand.
      13.15.1. Changing the cell index or selection method.
      13.15.2. Changing the cell index.
      13.15.3. Changing the rule selection method..
   13.16. Automatic saving of last rule.
   13.17. Transforming the rule, and setting canalyzing inputs.
      13.17.1.Complimentary transformation.
      13.17.2. Equivalent rule by negative transformation.
      13.17.3. Equivalent rule by reflection transformation.
      13.17.4. Equivalent rules with a greater neighbourhood, size, k.
      13.17.5. Setting canalyzing inputs.
   13.17.6. Saving the transformed rule.
-----------------------------------------------------------------------
14. Reviewing wiring/rules.
   14.1. 1d or 2d wiring graphic and rule scheme.
   14.2. Wiring graphic, 1d.
      14.2.1. Moving or jumping between cells, 1d wiring graphic.
   14.3. Wiring graphic, 2d.
      14.3.1. Moving or jumping between cells, 2d wiring graphic.
   14.4. Options, 1d and 2d wiring graphic.
      14.4.1. Revising the wiring.
      14.4.2. Revising the rule.
      14.4.3. Computing the (weighted) average lambda and Z parameters.
      14.4.4. Learning pre-images without attractor basins.
      14.4.5. Printing the wiring graphic window.
      14.4.6. Options.
   14.5. Revise wiring with the 1d or 2d wiring graphic.
      14.5.1 Changing the  neighbourhood size.
      14.5.2 Hand rewiring.
      14.5.3. Random wiring.
      14.5.4. Random special wiring.
      14.5.5. Regular 1d wiring.
      14.5.6. Regular 2d wiring.
   14.6. Revise rules with the 1d or 2d wiring graphic.
   14.7. Rule/wiring scheme: saving, loading, or printing (to a printer or
         file).
      14.7.1. Save/load/print selection.
      14.7.2. Mixed rules and non-local wiring.
      14.7.3. One rule and non-local wiring.
      14.7.4. Mixed rules and local wiring.
      14.7.5. Printing to a printer or file.
      14.7.6. Wiring/rulemix file names.
      14.7.7. Wiring/rulemix encoding..
      14.7.8. Wiring/rulemix file loading conventions.
      14.7.9. Neighbourhood mix loading conventions.
-----------------------------------------------------------------------
15. Seed.
   15.1. Setting the selection method for the seed.
   15.2. Seed bit pattern display.
   15.3. Rotating the seed.
   15.4. Setting the seed in decimal.
   15.5. Setting the seed at random.
   15.6. Setting the seed in hex.
   15.7. Setting the seed set as bits, drawing with the mouse.
      15.7.1. 1d networks (shown as 1d).
      15.7.2. 1d networks (shown as 2d).
      15.7.3. 2d networks.
      15.7.4. Setting/deleting bits with the mouse or keyboard.
   15.8. Repeating the seed..
   15.9. Loading a seed.
      15.9.1. Seed file encoding and loading conventions.
      15.9.2. Seed file, 1d.
      15.9.3. Seed file, 2d.
   15.10. Saving a seed.
-----------------------------------------------------------------------
16. Output parameters
   16.1. The first output parameter prompt.
      16.1.1. Accept all output parameter defaults.
      16.1.2. Space-time patters only.
      16.1.3. Restore all output parameter defaults, or just layout defaults.
      16.1.4. Jump to layout of attractor basins.
      16.1.5. Jump to display of attractor basins, and data
      16.1.6. Jump to mutation.
-----------------------------------------------------------------------
17. Set various output parameter options.
   17.1. State-space matrix scatter-plot.
      17.1.1. Display all states.
      17.1.2. Display attractor states only.
      17.1.3. Change matrix size.
      17.1.4. Change start colour.
   17.2. In-degree frequency histogram.
      17.2.1. In-degree frequency cut-off.
      17.2.2. In-degree frequency window.
      17.2.3. Data shown.
      17.2.4. Options.
      17.2.5. Re-scaling the x-axis.
      17.2.6. Re-scaling the y-axis.
   17.3. States with majority of 1s or 0s.
   17.4. "Screen save" demo.
   17.5. Graphs: G-density, Z and lambda ratio.
   17.5.1. G-density against Z and/or lambda ratio.
      17.5.2. Z against lambda ratio.
   17.6. "Backwards" space-time patterns.
   17.7. Scroll space-time patterns.
-----------------------------------------------------------------------
18. Graphic conventions for attractor basins.
   18.1. Network states, nodes.
   18.2. Attractor cycles.
   18.3. Transient trees.
   18.4. Transient tree colors.
   18.5. Transient trees for the states all 0s or all 1s.
   18.6. Subtree only.
-----------------------------------------------------------------------
19. Layout of attractor basins.
   19.1. The layout preview.
   19.2. The first layout prompt.
      19.2.1 Reset all layout defaults.
      19.2.2 Reset layout for learning.
      19.2.3. Basin scale, attractor radius.
   19.3. Basin start position.
   19.4. Show the field as successive basins.
   19.5. Basin spacing for fields.
   19.6. Select mimimum right border width.
   19.7. Amend the layout after each basin or tree.
      19.7.1. Amend the spacing and right border after each basin.
      19.7.2. Amending the next position (and spacing) after each basin.
   19.8. Amend the spacing increace for sucessive fields.
   19.10. Revise layout parameters.
-----------------------------------------------------------------------
20. Display of attractor basins, and data.
   20.1. Compression of equivalent CA dynamics.
      20.1.1. Supress compression.
      20.1.2. Supress copies of trees (and subtrees)..
   20.2. Node display.
      20.2.1. Show bit pattern nodes for 1d networks in 2d.
      20.2.2. Alter node label size, decimal or hex.
      20.2.3. Alter node size, bits.
   20.3. Highlight one state in each attractor.
   20.4. Pause, and data.
      20.4.1. Data on sub-trees.
      20.4.2. Data on a subtree from a uniform state.
      20.4.3. Data on trees.
      20.4.4. Data on basins.
      20.4.5. Pause after each field:
      20.4.6. Pause after each basin or tree:
   20.5. Print data to printer.
   20.6. Save data to file.
   20.7. Format of printed or saved data.
      20.7.1. Network data.
      20.7.2. Basin field data (no tree data).
      20.7.3. Basin field data, including tree and subtree data.
      20.7.4. Single basin data file.
      20.7.5. Subtree data file.
-----------------------------------------------------------------------
21. Mutation.
   21.1. The first mutation prompt.
   21.2. Flip bits.
      21.2.1. Alter the number of bits to flip.
      21.2.2. Alter the percentage of bits to flip.
   21.3. Special rule mutation.
      21.3.1. Mutate by the rule or code number.
      21.3.2. Assign a random rule or code number.
      21.3.3. Mutate by bitflip.
   21.4. Mutate wiring.
      21.4.1. Alter the number of wires to move.
      21.4.2. Alter the percentage of wires to move.
   21.5. No pause before next mutant.
-----------------------------------------------------------------------
22. Run backwards for subtree, or forwards for a single basin.
   22.1. Subtree:Run forwards before running bakwards.
   22.2. Single basin repeat check limit.
      22.2.1. Alter repeat check limit, or forwards only.
-----------------------------------------------------------------------
23. Final options: subtree, single basin or basin of attraction field.
   23.1. Local wiring.
   23.2. Non-local wiring.
   23.3. Partial preimage stack, local wiring.
   23.4. Partial preimage histogram, non-local wiring.
   23.5. The exhaustive testing reverse algorithm.
   23.5.1. Load exhaustive pairs.
   23.5.2. Computing exhaustive pairs.
   23.5.3. Saving exhaustive pairs.
-----------------------------------------------------------------------
24. Final options for space-time patterns (forwards only).
   24.1. Color cells by value or neighborhood.
   24.2. Pause when screen full.
   24.3. Frozen generation size.
   24.4. Analysis.
      24.4.1. Pattern density.
      24.4.2. Lookup frequency and entropy.
   24.5. Analysis generation size.
   24.6. State-space matrix scatter-plot (forwards only).
-----------------------------------------------------------------------
25. Changing settings "on the fly" (attractor basins).
   25.1. Interrupting attractor basins.
      25.1.1. Backtrack through prompts.
      25.1.2. Abandoning a tree and continuing with the next tree.
      25.1.3. Other options.
   25.2. Key hit attractor basin options.
   25.3. Attractor basin complete options.
   25.4. Further attractor basin complete options.
   25.4.1. Rule options.
   25.4.2. Seed options.
-----------------------------------------------------------------------
26. Changing settings "on the fly" (space-time patterns only).
   26.1. The "Interrupt Key Index" (space-time patterns only).
      26.2.1. change rule table
      26.1.2.change wiring
      26.1.3. change seed/size
      26.1.4. presentation
      26.1.5. 2d space-time pattern
      26.1.6. highlight frozen cells
      26.1.7. analysis
      26.1.8. state-space matrix
      26.1.9. index, pause, quit
   26.2. The "Interrupt Key Index", some further details 
      26.2.1. change rule table
      26.2.2. change wiring
      26.2.3. 2d space-time pattern	
      26.2.4. highlight frozen cells
      26.2.5. analysis
   26.3. Pause space-time pattern.
   26.4. Rule details (space-time patterns only).
   26.5. Further space-time pattern options .
      26.5.1. Screen options.
      26.5.2. Rule options.
      26.5.3. Seed options.
      26.5.4. Other options.
      26.5.5. Further options, first backtrack.
-----------------------------------------------------------------------
27. Learning, forgetting, and highlighting.
   27.1. Highlighting states.
   27.2. Default attractor basin layout for learning.
   27.3. Selecting the wiring graphic.
   27.4. Selecting the learn/highlight window.
   27.5. Select the "target" state.
   27.6. Select a set of states as pre-images.
      27.6.1. An arbitrary list of aspiring pre-images.
      27.6.2. Pre-images according to Hamming distance.
      27.6.4. Odd or even parity.
      27.6.5. Repeat previous selection.
   27.7. Review target state and aspiring pre-images.
    27.8. Learn, forget, or highlight only.
   27.9. Learning/forgetting by wire moves or bit-flips.
      27.9.1. Learning/forgetting by bit-flips.
      27.9.2. Learning/forgetting by wire-moves.
   27.10. Highlighting options.
   27.11. Learning complete.
-----------------------------------------------------------------------
28. Filing
   28.2. Saving and Loading
   28.3. Changing the directory
   28.4. List files
   28.5. File encoding
      28.5.1. SCREEN (image)
      28.5.2. N'HOOD MIX
      28.5.3. WIRING ONLY, RULE SCHEME ONLY, WIRING-RULE SCHEME
      28.5.4. SINGLE RULE
      28.5.5. SEED
      28.5.6. DATA
      28.5.7. EXHAUSTIVE (pairs)

-----------------------------------------------------------------------
Overview.
-----------------------------------------------------------------------
A1. Introduction
----------------
DDLab is an interactive graphics program for research into the dynamics of 
finite binary networks, from Cellular Automata (CA) to random Boolean 
networks, including their attractor basins (for a DOS-PC platform). The 
program is relevant to the study of complexity, emergent phenomena, neural 
computation and theoretical biology, and implements the investigations 
presented in (Wuensche 1992-1995).
   Using a flexible user interface, a network can be set up for any 
architecture between regular CA (1d or 2d with periodic boundary conditions) 
on the one hand, and random Boolean networks (disordered CA) on the other. 
The latter have arbitrary connections, and rules which may be different at 
each site. The neighbourhood (or pseudo-neighbourhood) size may be set from 1 
to 9, and the network may have a mix of neighbourhood sizes.
   The program iterates the network forward to display space-time patterns 
(mutations are possible "on the fly"), and also runs the network "backwards" 
to generate a pattern's (or state's) predecessors and reconstruct its 
branching sub-tree of all ancestor patterns until all the "garden of Eden" 
states, the leaves of the sub-tree, have been reached. Sub-trees, basins of 
attraction or the whole basin of attraction field (referred to collectively 
as "attractor basins") can be displayed as a directed graph or set of graphs 
in real time, with many presentation options. Attractor basins may be 
"sculpted" towards a desired configuration. Various statistical and 
analytical measures and numerical data are made available.
   Whereas large systems sizes may be run forward to look at space-time 
patterns, or backwards to look at subtrees, much smaller sizes (say less than 
18) are appropriate for the basin of attraction field given that  state-space 
grows exponentially with system size. The program's upper limit for basin of 
attraction fields is 32; there is no limit for single basins or sub-trees. 
Larger sizes may be tried, but may impose unacceptable time, memory and 
display constraints. Sub-trees may be generated for much larger systems for 
rules having a low in-degree.
   The network's parameters, and the graphics display and presentation 
options, can be very flexibly set, reviewed and altered. Changes can be made 
"on the fly", including mutations to rules, connections or current state. 2d 
networks (including the "game of life" (Conway 1982) or any mutation thereof) 
can be displayed as a space-time pattern in a 3d isometric projection.
   Statistical measures and data (mostly presented graphically) include: 
lambda and Z parameters, the frequency of canalyzing "genes" and inputs, 
rule-table lookup frequency and entropy, pattern density, detailed data on 
sub-trees, basins and fields, garden-of-Eden density, in-degree frequency and 
a scatter-plot of state-space.  Network parameters, states, data, and the 
screen image can be saved and loaded in a variety of tailor-made file 
formats.
   Learning/forgetting algorithms allow attaching/detaching sets of states as 
predecessors of a given state by automatically mutating rules or changing 
connections. This allows "sculpting" the basin of attraction field to 
approach a desired scheme of hierarchical categorisation.
   #A1-10 gives a overview of the program. #1-3 give some "quick start" 
examples. These should be tried initially to get the flavour of the DDLab. 
#4-28 is a detailed reference manual. For further background on the attractor 
basins of CA and random Boolean networks, and their implications, refer to 
Wuensche (1992-1995), Kauffman (1993) and other references listed in #A10.
-----------------------------------------------------------------------
A2. Network parameters
----------------------
DDLab has a flexible user interface for setting, viewing and amending network 
parameters. Parameters are set by responding to a main sequence of screen 
prompts, and various context dependent prompt windows, all of which allow 
default choices and backtracking. A flashing cursor indicates the prompt. 
"Return" (or the left mouse button) steps forward through the prompts, "q" 
(or the right mouse button) backtracks, or interrupts a run.
   CA rules (or totalistic codes) are set in decimal, hex, as a lookup table 
bit pattern (using the mouse), at random or loaded from a file. The "game of 
life" and the "majority" rule can also be selected. Rules may be changed into 
their equivalents (by reflection and negative transformations), and 
transformed into equivalent rules with larger neighbourhoods. The latter is 
useful to achieve finer mutations of interesting rules. The frequency of 
canalyzing "genes" or inputs in a network can be set to any arbitrary 
proportion, useful in modelling gene regulatory networks.
   Wiring is set as regular 1d or 2d for the given neighbourhood size, at 
random, with a "spread sheet" to set or alter individual couplings by hand, 
or a wiring scheme may be loaded from a file. In most cases regular 2d wiring 
defines a square grid on the torus, and includes the von Neumann and Moore 
neighbourhoods of 5 and 9 cells. However the 7 cell regular 2d neighbourhood 
is wired to define a triangular grid. Non standard wiring can be constrained 
in various ways, including confinement to a local patch of cells with a given 
radius.
   The network parameters can be scrutinised and amended in a 1d or 2d 
graphic display format, or a "spread sheet" format, showing each cell's 
particular wiring and rule, using the arrow keys to move between cells.
   An initial network state is required as a seed for a forwards or backward 
run (to seed a sub-tree or single basin). A basin of attraction field does 
not require a seed. The seed is set in 1d or 2d, in decimal, hex, as a bit 
pattern (using the mouse), at random, or loaded from a file. The bit pattern 
method is a mini drawing program, using the mouse (or keyboard) to set cell 
values (0,1). It is particularly useful for 2d patterns.
-----------------------------------------------------------------------
A3. Presentation options
------------------------
Many options are provided for the presentation of attractor basins and space-
time patterns. Again, many of these settings can be changed "on the fly", 
including the scale and colour of space-time patterns. Cells in space-time 
patterns are coloured according to their value (0,1) or alternatively 
according to their neighbourhood at the previous time step (the entry in the 
look-up table that determined the cell's value). A key press will toggle 
between the two. Alternatively, the colour presentation can be set to 
highlight cells that have not changed in the previous x generations, where x 
can be set to any value. The development of such frozen clusters, which may 
link up into percolating walls, is associated with canalyzing "genes", and 
underlies Kauffman's "random Boolean network " model of gene regulatory 
networks (Kauffman 1993).
   A space-time pattern is presented in successive vertical sweeps, or may be 
scrolled, which is slower. 2d networks (including the "game of life" or any 
mutation thereof) can be displayed as a space-time pattern in a 3d isometric 
projection (as if looking up at a glass lift shaft). The projection can be 
toggled between 3d, 2d and 1d (which shows a series of slices).
   For attractor basins, options allow the selection of the basin of 
attraction field, a single basin (from a selected seed), or a sub-tree (also 
trees, an option is therefore offered to run the network forward a given 
number of steps to a new seed before running backward. This guarantees a sub-
tree with at least that number of levels.
   Options (and defaults) are provided for the layout of attractor basins, 
their size, position, spacing, and type of node display (as a spot, in 
decimal, hex or a (1d or 2d) bit pattern). Regular 1d and 2d CA produce 
attractor basins where sub-trees and basins are equivalent by rotational 
symmetry. This allows "compression" of basins (by default) into non-
equivalent prototypes, though compression can be suppressed. Attractor basins 
can be generated for a given system size, or automatically for a range of 
sizes. As attractor basins are generating, a reverse space-time pattern plot, 
showing each state in black and its predecessors (if any) in red can be 
displayed (and toggled on and of).
   An attractor basin run can be set to pause to see data on each transient 
tree, each basin, or each field. Normally the run will pause before the next 
"mutant" attractor basin, but this pause may be turned off to create a 
continuous demo of new attractor basins. A "screensave" demo option shows new 
basins continually growing in random positions
   At any time, a space-time pattern or attractor basin run can be 
interrupted to pause, save or print the screen image, or backtrack through 
options. The graphics can be set up for VGA (640x480) or SVGA (1024x768) (in 
the SVGA mode there is a problem with the mouse). The colour setting in both 
modes can be set for either a white or black background. The default setting 
is VGA with a white background.
-----------------------------------------------------------------------
A4. Filing and Printing
-----------------------
Network parameters and states can be saved and loaded with default file 
extensions (and default file names) for the following: rules, rule-schemes, 
wiring-schemes, wiring/rule schemes, neighbourhood mix, and network state.
   The screen image is saved and loaded using a home made compressed format. 
To save the image in a standard format (and print to any printer), use a 
"stay resident screen grabber". A number a specialist screen grabbers are 
available, and others are part of "paint" programs. Alternatively run DDLab 
as a DOS application in Microsoft Windows and use their "paint" screen 
grabber. The screen image can be printed at any time directly from DDLab, but 
reliably only to the Epson MX-82 dot matrix printer. Printing to other 
printers is worth a try but is unpredictable (these shortcomings will be 
dealt with in time).
   Detailed data on attractor basins can be automatically saved (also 
printed). A file of "exhaustive pairs", made up of each state and its 
successor, can be created for very fast generation of a basin of attraction 
field of a random Boolean network.
-----------------------------------------------------------------------
A5. Mutations
-------------
Network parameters (as well as graphics presentation) can altered "on the 
fly". For example during forward iteration various key presses allow 
mutations to rules, wiring or current state; the network size can be 
increased or decreased, and the graphical display of analytical data can be 
changed. About 60 1d complex 5-neighbour rules (with glider interactions) are 
provided in a file and can be set with a button press, and also a few 6 and 7 
neighbour complex rules. Examples of these are presented in (Wuensche 
1994b,1995).
   When attractor basins are complete, a key press will regenerate the 
attractor basin of a mutant network. Various mutation options can be pre-set 
including random bit flips in rule tables, or random moves of a given number 
of wires. Sets of states can be specified and highlighted in the attractor 
basin to see how mutations affect their distribution.
-----------------------------------------------------------------------
A6. Statistical measures and data
---------------------------------
Numerical, statistical and analytical data, mostly presented graphically, 
includes the following: A rule-table lookup frequency histogram, which can be 
toggled between 2d and 3d to include a time dimension. An alternative plot of 
the lookup frequency histogram and its entropy. A plot of pattern density. 
(these may be spread over a number of generations). The lambda and Z 
parameters. The proportion of canalyzing rules and inputs. Detailed data on 
attractor basins including garden-of-Eden density (this data may be 
automatically saved). A histogram of in-degree frequency. A scatter-plot of 
state space (plotting the left half against the right half of each state bit 
string), using colour to identify different basins, or attractor cycle 
states. A plot of garden-of Eden density against the Z parameter. Most of 
these topics are explained in (Wuensche 1994b,1995).
-----------------------------------------------------------------------
A7. Reverse algorithms
----------------------
There are three different reverse algorithms for generating the pre-images of 
a network state. The first is specifically for "local" 1d wiring with a 
homogeneous neighbourhood, such as 1d CA, though the rules may be 
heterogeneous. This is the most efficient thus fastest algorithm, described 
in (Wuensche 1992). Furthermore, compression of 1d CA attractor basins by 
rotation symmetry (see #20.1) speeds up the process.
   Any other network architecture, with non-local wiring, will be dealt with 
by a slower general reverse algorithm described in (Wuensche 1994a). A 
histogram revealing the inner workings of this algorithm can be displayed. 
Regular 2d CA will use this general reverse algorithm; however compression 
algorithms will come into play to take advantage of the many rotation 
symmetries on the torus (unless suppressed, and not for a neighbourhood of 7 
as yet, because the symmetries of a triangular grid on the torus have yet to 
be resolved).
   Both these reverse algorithms generate the pre-images of a state directly; 
their speed is sensitive to neighbourhood size as well as system size. A 
neighbourhood of 9, such as the game of life, is slowest. A third reverse 
algorithm first sets up a list of "exhaustive pairs" of each state in state-
space and its successor (this can be saved). The pre-images of states are 
generated by reference to this list. This method is efficient for basin of 
attraction fields, or large basins that use up a good proportion of state-
space, and additionally is not sensitive to neighbourhood size (the basin of 
attraction field of the 4x4 "game of life" by this method takes about 30 
minuets on my 66MHz 486 ).
   The method used to generate pre-images will be chosen by default, which 
can be overridden. For example, a regular 1d CA can be made to use either of 
the two other algorithms for benchmark purposes. The time taken to generate 
attractor basins is displayed, and for the basin of attraction field, a 
progress bar indicates the proportion of states in state-space used up so 
far.
-----------------------------------------------------------------------
A8. Sculpting attractor basins
------------------------------
Learning and forgetting algorithms allow attaching and detaching sets of 
states as predecessors of a given state by automatically mutating rules or 
wiring couplings. This allows "sculpting" the attractor basin to approach a 
desired scheme of hierarchical categorisation. When an attractor basin run is 
complete, various "learning" windows allow a "target" state to be set, 
together with a number of "aspiring pre-images" (predecessors). These may be 
selected in various ways including by Hamming distance. Learning/forgetting 
algorithms will attempt to attach the aspiring pre-images to the target 
state, and can be set for either rule-table bit-flips or wire moves. In fact 
the bit-flip method cannot fail. In this way, new point and cyclic attractors 
can be created and sub-trees transplanted. The result of learning/forgetting, 
including side effects, will be apparent in the new attractor basins. The 
algorithms, and their implications are described in (Wuensche 1994a).
-----------------------------------------------------------------------
A9. Hardware and software requirements
--------------------------------------
Platform: PC-DOS 386 or higher, with VGA or SVGA graphics; maths co-
processor, mouse (optional). (ideally a fast 486 with 8MB ram). The code is 
written in C and developed with BorlandC, but compiled with the Watcom C32 
compiler (and the Rational Systems DOS extender) giving access to extended 
memory. The supplied Watcom file "dos4gw.exe" must be in the same directory 
as "ddlab.exe".
-----------------------------------------------------------------------
A10. References
---------------
Conway,J.H., (1982) "What is Life?" in "Winning ways for your mathematical
   plays", Berlekamp,E, J.H.Conway and R.Guy,  Vol.2, chap.25, Academic
   Press, New York.
Gutowitz,H.A., ed., (1991) "Cellular Automata, Theory and Experiment", MIT
   press. Hopfield,J.J. (1982) "Neural networks and physical systems with
   emergent collective computational abilities", Proceedings of the National
   Academy of Sciences 79:2554-2558.
Kauffman,S.A., (1993) The Origins of Order, Self-Organization and Selection
   in Evolution, Oxford University Press.
Langton,C.G., (1986) "Studying Artificial Life with Cellular Automata",
    Physica D, 22, 120-149.
Langton,C.G., (1990) "Computation at the Edge of Chaos: Phase Transitions and
   Emergent Computation", Physica D, 42, 12-37.
Wolfram,S., ed. (1986) "Theory and Application of Cellular Automata", World
    Scientific, 1986.
Wuensche,A., and M.J.Lesser. (1992) “The Global Dynamics of Cellular
   Automata; An Atlas of Basin of Attraction Fields of One-Dimensional
   Cellular Automata”, Santa Fe Institute Studies in the Sciences of
   Complexity, Addison-Wesley.
Wuensche,A., (1994a) "The Ghost in the Machine; Basin of Attraction Fields of
   Random Boolean Networks", in Artificial Life III, ed C.G.Langton, Santa Fe
   Institute Studies in the Sciences of Complexity, Addison-Wesley.
Wuensche,A., (1994b) "Complexity in One-D Cellular Automata; Gliders, Basins
   of Attraction and the Z Parameter", Santa Fe Institute Working Paper 
   94-04-025.
Wuensche,A., (1994c) “The Emergence of Memory", Cognitive Science Research
   Paper 346, Univ. of Sussex, to appear in "Towards a Scientific Basis for
   Consciousness", eds. S.R.Hameroff, A.W.Kaszniak, A.C.Scott, MIT Press.
Wuensche,A., (1995) "Gliders in One-D Cellular Automata; some new measures of
   dynamical behaviour", to appear in Complexity.

-----------------------------------------------------------------------
Quick Start Instructions
-----------------------------------------------------------------------
1. Unzipping and running.
-------------------------
"ddlab.zip" will unzip to give the following files:

"ddlab.exe"       the program
"dos4gw.exe"   the DOS extender, giving access to extended memory.
 "smalle.fon",  "sserife.fon"   2 text fonts.
                             Files with "complex" 1d CA rules which feature
                             interacting gliders.
 "glider5.r_s"    about 60 complex 5-neighbour rules.
 "glider6.r_s"    about 5 complex 6-neighbour rules.
 "glider7.r_s"    about 10 complex 7-neighbour rules.
 "pento.eed"      the "rpentomeno" 2d pattern, which seeds interesting
                             "game-of-life" dynamics.
 "readme.txt"     a text file (Index, Introduction and Quick Start  Instructions only).
 "ddlabop.doc"  a word for Windows file with the full  (un-illustrated) reference manual

   Make a new directory, say "ddlab", and copy these files into it. To run 
the program, from this directory enter "ddlab". The "DOS extender" banner 
will briefly appear, and the program will start. Section 2 and 3 give brief 
"quick start" examples. You are encouraged to try these examples first to get 
the flavour of DDLab. Section 4 onwards is the detailed program reference, 
listing all the various options and prompts with explanatory notes.
   Note that DDLab may also be set up and run as a non-Windows application 
under Microsoft Windows.

1.1. Updates to DDLab.
----------------------
Check for the latest version of DDLab available at Alife Online at the Santa Fe Institute. 
Download "ddlab.zip"  by ftp or www as described below. 

World Wide Web	           http://alife.santafe.edu/alife/software/ddlab.html
ftp download instructions        ftp://alife.santafe.edu/pub/SOFTWARE/ddlab

Download just the file "ddlab.txt" (48k) for details about DDLab, or the 
complete set of files (including the un-illustrated reference manual) contained 
in the binary file "ddlab.zip" (545k). Unzip the file with "pkunzip".

%             ftp alife.santafe.edu
name:         anonymous
password:     your complete email address
ftp>          cd pub/SOFTWARE/ddlab   (note "SOFTWARE" is upper case)
ftp>          binary
ftp>          get ddlab.zip 
ftp>          close
-----------------------------------------------------------------------
2. The user interface.
----------------------
When DDLab is run, the user interface (white background) appears, with a 
title bar across the bottom of the screen. A series of prompts are presented 
to set up the network and presentation parameters. These prompts appear 
either in a main sequence for the most commonly needed settings, or in 
various windows that automatically open up. If a mouse is detected, a mouse 
cursor will also appear. It is used to set bits in rule-tables and network 
states, and for "drawing" bit patterns in 2d networks. Otherwise it is just a 
pointer.

2.1. Input.
-----------
The green flashing cursor prompts for input. Enter appropriate input from the 
keyboard (backspace or press the left mouse button to revise) and "return" 
(or press the left mouse button) to accept and move on to the next prompt or 
routine. Just entering "return" (or left mouse button) will automatically 
select a default.

2.2. Backtrack.
---------------
To backtrack through the prompts (or interrupt a running routine) press the 
"q" key (or right mouse button). When a routine is running, such as space-
time patterns or attractor basins, the mouse disappears, To interrupt the 
running routine enter "q" (mouse presses only work when the green flashing 
cursor is visible, not during the running of a routine). Then backtrack to 
any stage in the prompt sequence with "q" (or right mouse button), eventually 
to exit the program and return to DOS.

2.3. Changing the graphics set-up.
----------------------------------
The graphics set-up can be changed between a white and black background, and 
VGA (640 x 480 pixels) and Super VGA (1024 x 768 pixels), given the necessary 
graphics card and monitor. At the first prompt on the main sequence (and at 
other points in the program) select "g" for graphics. The "Change graphics 
setup" screen will appear showing screen colours. Enter "b" to toggle the 
background, "g" to toggle VGA and SVGA. Note that at present the mouse cursor 
is invisible in SVGA, though the left and right button presses work.
-----------------------------------------------------------------------

3 Quick start examples
==============================
The following examples will give the flavour of the program. Accept defaults 
with "return" (or left mouse button) or experiment with other settings.

3.1 Basin of attraction fields.
---------------------------------
From the first prompt keep accepting defaults with "return" (or left mouse 
button) until "OUTPUT PARAMETERS" appears at the top centre of the screen, 
and a window with various options in the top right. Enter "d" (to accept all 
output defaults).
   A new prompt window appears top right. Enter "return".
   The basin of attraction field will be generated for a 1d 3-neighbour rule, 
system size 10. The rule (chosen at random by default) appears in a window at 
bottom of the screen A window in the top right shows brief data on the field 
once it is generated. A progress bar below this window shows the proportion 
of state-space as it is used up. Vertical lines on this bar indicate the 
states used to seed the basins. 
   A prompt window appears top left. Enter "return".
   Another basin of attraction field is generated, a one bit mutant of the 
previous rule, with corresponding information. This process can continue 
indefinitely (it can be set on automatic).
   Enter "q" to interrupt (and backtrack).

3.2. "Backwards" space-time patterns, and state-space matrix
-----------------------------------------------------------------
While the attractor basins are generating, various display settings can be 
changed "on the fly". These are indicated on the right of the bottom title 
bar. (If the attractor basin generates to fast, backtrack to slightly 
increase the network or neighbourhood size settings).
   Enter "s" to toggle the "backwards" space-time pattern on-off, and see 
predecessors (pre-images) being generated (on the left of the screen) as a 
space-time pattern. Initially the attractor states will be displayed, then 
each state (black) and its set of pre-images (red). Expand or contract the 
scale of the space-time pattern with "e" and "c".
   Enter "m" to toggle the display of the state-space matrix (or scatter-
plot) in the lower right corner. This reveals interesting symmetries. 
Different colours represent states in different basins.
   Enter "q" to interrupt (and backtrack).

3.3. Basins of attraction fields for a range of network sizes.
--------------------------------------------------------------
Backtrack with "q" (or right mouse button) to the start of the program. At 
the second prompt, select "r" for a range of network sizes. 
   Enter "return" repeatedly until OUTPUT PARAMETERS, then "a" to restore all 
defaults, then "d" to accept all defaults.
   Enter "return" to start a range of CA basin of attraction fields (same 
rule), for network size 5 to 12.
   Enter "return" for the next mutant.
   Toggle the display of the "backwards" space-time pattern and the state-
space matrix as described in 3.2. Enter "q" to interrupt (and backtrack).

3.4 A single basin of attraction.
----------------------------- ---
Backtrack with "q" (or right mouse button) to the start of the program. 
   At the very first prompt enter "s" for single basin or sub-tree.
   At the "Neighbourhood size..." prompt select 4.
   Keep entering "return" to accept defaults for the rule, seed etc. (The 
last seed and rule selected are automatically saved). 
   At the OUTPUT PARAMETERS prompt enter "a" to restore all defaults, then 
"d" to accept all attractor basin defaults.
   A prompt window appears "run network backwards-b, forwards (default):", 
enter "return". (generating a single basin requires running forward first to 
uncover the attractor cycle).
   Enter "return" in response to further options.
   A singe basin for network size 14 is generated.
   Enter "return" for the next mutant.
   Toggle the display of the "backwards" space-time pattern and the state-
space matrix as described in 3.2. Enter "q" to interrupt (and backtrack).

3.6. A subtree.
---------------
Backtrack with "q" (or right mouse button) to the start of the program. 
   At the very first prompt enter "s" for forwards only.
   At the "network size... " prompt select 25.
   At the "Neighbourhood size..." prompt select 5.
   Keep entering "return" to accept defaults for the rule, seed etc. 
   At the OUTPUT PARAMETERS prompt enter "s" for "space-time pattern only".
   Keep entering "return" to accept space-time pattern defaults.
   The space-time pattern is generated on the left of the screen. Alongside 
is a plot of the lookup frequency of each entry in the 5-neighbour lookup-
table, and the entropy of this frequency distribution. A histogram of the 
lookup frequency changing at each time step is shown alongside. An "interrupt 
key index" on the right of the screen gives a list of key presses to change 
settings "on the fly".
   Enter "g" a few times to change the rule to different complex "glider" 
rules. Try other key presses to change the rule, wiring, seed, colour, 
analysis, scale and size.
   Enter "q" to interrupt (and backtrack).

3.8 Space-time pattern only, 2d (game of life).
-----------------------------------------------
Backtrack with "q" (or right mouse button) to the start of the program. 
   At the very first prompt enter "s" for forwards only.
   Enter "return" until a "wiring:..." prompt window appears top right. Enter "2" (for regular 2d).
   At the next prompt window enter "return".
   The next prompt window sets the size of the 2d lattice. Accept the default size 36x36 (for a faster computer increase the size to say 50x50).
   At the next prompt window enter 9 (the neighbourhood size).
   At the "Select n=9 rule,..." in the main sequence of prompts, enter "f" for the "game of life" (the lookup-table of this rule will be displayed as a bit pattern..
   Keep entering "return" to accept defaults for the seed etc. 
   At the OUTPUT PARAMETERS prompt enter "s" for "space-time pattern only".
   Enter "d" to accept all space-time pattern defaults.
   The 2d space-time pattern is generated in the top left of the screen. An "interrupt key index" on the right of the screen gives a list of key presses to change settings "on the fly".
   Enter "t" to toggle between the 2d display and a 3d isometric projection. (imagine looking up at the ceiling of a transparent lift shaft). The "game of life" may soon settle to a stable or null state. To re-seed the network enter "k" for a new (random) central block. With luck gliders will emerge. Note that colours represent the cell's rule-table lookup rather than its value, making the 3d graphics clearer (key "3" toggles this colour setting). Other key pressed include changes to the rule, wiring, seed and scale.
   Enter "q" to interrupt (and backtrack).

3.9 "Screen-saver" demo.
------------------------
For a continuous show of attractor basins "boiling" on the screen.
   Backtrack with "q" (or right mouse button) to the start of the program. 
   At the very first prompt enter "s" for single basin or sub-tree.
   At the "Network size..." prompt select 10. (for a faster computer select 
11 or 12).
   At the "Neighbourhood size..." prompt select 4.
   Keep entering "return" to accept defaults for the rule, seed etc.
   At the OUTPUT PARAMETERS prompt enter "a" to restore all defaults, then 
"return" until the "savescreen demo.." window appears and enter "s" to accept 
the option. Then enter "d" to accept all further defaults.
   Enter "return" until the show starts (the rule picked at random will be 
shown in the bottom rule-window).
   Toggle the display of the "backwards" space-time pattern and the state-
space matrix as described in 3.2. Enter "q" to interrupt (and backtrack).
   Try the screen saver with a black background (see #2.3).
------------------------------------------------------------------------