                     Evolutionary Prisoner's Dilemma v2.1.1
(c) James Marshall 1998-2002. Freely distributable under the GNU General Public Licence
                     contact- James.A.Marshall@imperial.ac.uk

Introduction
------------
The Objective C source included in this archive is for a Swarm simulation called the
"Evolutionary Prisoner's Dilemma" or "EPD". The EPD is a model of a multi-agent spatialised
system in which agents move locally, interacting by playing the Prisoner's Dilemma or any
other 2x2 game with, and mating with, agents they meet in their local neighbourhood. In
particular it is possible to change the "population viscosity" by varying the probability with
which agents move at each time step. Tools are provided to observe global characteristics,
including: cooperation level, relatedness level, and frequency of alleles in the gene pool.
Visualisation tools are also provided to observe local cooperation and relatedness levels, and
local population densities. Statistic collection tools are provided to log results from
systematic experimental variation of parameters.

This implementation is for Swarm 2.1.1. Swarm is a set of Objective C libraries for producing
simulation software, and is freely available from the Swarm Development Group at:

http://www.swarm.org

Publications
------------
This software has been used to provide the results presented in:

* Marshall, J. A. R. & J. E. Rowe (2003) Kin Selection May Inhibit the Evolution of Reciprocation.
To appear in Journal of Theoretical Biology.
* Marshall, J. A. R. & J. E. Rowe (2000) Investigating the Mechanisms Underlying Cooperation in
Viscous Population Multi-Agent Systems. Artificial Life VII: Proceedings of the Seventh
International Conference, edited by Mark A. Bedau, John S. McCaskill, Norman H. Packard,
and Steen Rasmussen (MIT Press, 2000).

Usage
-----
The Objective C source is fully commented throughout, to facilitate understanding and modification
of the model's operation, and extension of the model's functionality.
The EPD can be compiled in two forms, "observe" and "experiment". The observe form includes analysis
and visualisation tools for observing the model in real-time. The experiment form includes
statistic collection tools for logging the results of systematic experimental variation of model
parameters.

To compile the EPD at all it is first necessary to ensure that Swarm home is correctly defined in the
file "Makefile" to point to the location where Swarm 2.1.1 is installed on your system.

To compile the EPD in observer form (assuming correct installation and use of Swarm 2.1.1):
* edit the file "EPDDefines.h" and ensure that the line "#define observe" is uncommented.
* run the makefile by typing "make".

To compile the EPD in experiment form (again assuming correct installation and use of Swarm 2.1.1):
* edit the file "EPDDefines.h" and ensure that the line "#define observe" is commented out.
* run the makefile by typing "make".

Once you have an executable, run it as normal. Use the control panel buttons "Start", "Next" and "Stop"
to control simulation flow. Prior to starting the simulation you can modify the parameters as required.
The parameters are taken from a file called "world.setup". The experiment form of EPD takes its initial
parameter values from a file called "experiment.setup" and stores its results in a file called "log.file".
The game payoffs are taken from a file called "payoffs.setup" with, for example, ABPayoff giving the
payoff to a player making choice "A" against an opponent making choice "B".

Limitations
-----------
Anything you can think of... if you find you are limited, modify the source and recompile! If you think
your modification is useful, please let me know about it.

Documentation
-------------
If you feel the need for more comprehensive documentation, contact the author at the above
email address.
