cultaptation - Python Engine
----------------------------

von Eckhart Arnold, Uni Bayreuth (Philosophy & Economics)
    www.eckhartarnold.de; eckhart_arnold@hotmail.com
mit Strategien von Julia Lohmann, Philipp Schächtele,
                   Christoph Siemroth und Martin Neumann

Verison 0.3,   10. Dezemebr 2008

Versionsgeschichte:
Verison 0.3,   10. Dezemebr 2008
Verison 0.2,   28. Juni 2008
Version 0.1.1, 22. Februar 2008



English
-------

The program is a simulation environment that is meant to reproduce
the conditions of the "cultaptation" tournament. Information on
the cultaptation tournament and prize competition can be found here
(deadline was June 30th 2008):

http://www.intercult.su.se/cultaptation/tournament_details.php

The purpose of the engine is to develop new strategies, i.e. to test,
analyze and improve strategies. The engine does not only reproduce the
conditions of the tournament but it also collects all sorts of data
on the progress of the tournament and the "behavior" and performance 
of the strategies.

THIS IS NOT THE OFFICIAL CULTAPTATION ENGINE THAT IS USED IN THE
ACTUAL TOURNAMENT!

The program in its current state should suffice to implement and examine
strategies. This is, how you can do so:

1. Before you can use the cultaptation engine, you need to download
   and install the following software packages:
   a) Python
   b) numpy
   c) matplotlib
   
2. Unpack "cultaptation.zip" somewhere on your hard disk  

3. In order to run the engine type "python FrontEnd.py" in a 
   command shell or double click on "FrontEnd.py"
   
4. Select or deselect strategies on the left hand side and start
   a single "match", a series of matches ("contest") or a 
   full "tournament". If only two strategies are selected a pairwise 
   match or contest is started when either the "match" or the "contest"
   butten is pressed. With more than two strategies, melee matches are
   played.
   
5. When the match, contest or tournament is finished a web browser
   is opened that displays extensive information on the match, contest
   or tournament. (The web-pages are saved in the user's "home" 
   directory)
   
6. The following information is displayed:
   a) population share of the strategies
   b) (average) payoffs
   c) performance profiles of the strategies
   
7. Custom strategies should be added to the file "Strategy.py". They are
   automatically recognized when restarting the program. 
   
8. The easiest way to create a new strategy is to take an existing one, 
   rename it (!!!) and change it as you like.
   
9. To simplify programming a new strategy, there is a module "Toolkit.py"
   that contains many useful functions so that one can usually avoid 
   handling the matrices directly.       

   
Acknowledgements:
-----------------
Luke Rendell and the cultaptation team! (Thanks for making this 
tournament. It is great fun!)

Phlipp Schaechtele, Christoph Siemroth, Julia Lohmann, Martin Neumann
(Thanks for contributing some good strategies and giving feed-back!) 




Deutsch
-------

Bei dem Programm handelt es sich um eine Simulationsumgebung die die 
Bedingungen des "cultaptation" Turniers nachbilden soll. Informationen
zum Tunier und Preisausschreiben gibt es hier:

http://www.intercult.su.se/cultaptation/tournament_details.php

Die Engine soll dazu dienen, eigene Strategien zu entwickeln, d.h.
auszuprobieren, zu analysieren und zu verbessern. Dazu bildet die
Engine nicht nur das Turnier nach, sondern sammelt auch Informationen
zum Verlauf des Turniers und des Verhaltens der Strategien (zuminstest
ist das das Ziel ;) der "Engine").

Das Programm ist zwar bisher alles andere als fertig, aber ich glaube, 
dass es jetzt zumindest recht einfach ist, eigene Strategien auszuprobieren 
und auf ihre Leistung hin zu analysieren.

Und so kann jeder seine eigenen Strategien ausprobieren:

1. Python, numpy und matplotlib müssen installiert sein
   (Wer die Pakete nicht hat: Einfach bei Google eingeben
   und herunterlagen.)

2. "cultaptation.zip" irgendwo auf der Festplatte entpacken.

3. Zum Ausprobieren das Programm durch einen Doppelklick auf die
Datei "FrontEnd.py" (ja, es gibt eine, allerdings simple,
Benutzeroberfläche!) im cultaptation Verzeichnis starten.

4. Dann kann man die Strategien, die bereits im Programm vorhanden sind
per Mausklick auswählen und ein "Match" (bisher noch kein komplettes Turnier)
starten. Während das Match läuft, kann man dem "Live Plot" zu schauen.

5. Ist das Match beendet, dann speichert das Programm eine Zusammenfassung der
Ergebnisse auf der Festplatte (was eine Weile dauert, bitte Geduld) und
startet dann automatisch einen Internetbrowser, um die Zusammenfassung
anzuzeigen!

6. Folgende Informationen werden angezeigt:
  a) Verbreitung der Strategien in der Population
  b) Payoffs (für jede Runde und gemittelt)
  c) Besonders wichtig: Leistungsprofile jeder einzelnen Strategie, und zwar:
      (i) Die Durchschnittliche Leistung über alle (verstorbenen) Individuen
         der Stratergie gemittelt.
      (ii) drei Einzelbeispiele für typische Lebenszyklen eines
          Individuums mit dieser Strategie.

7. Neue eigene Strategien sollten in die Datei "Strategy.py" eingebaut werden,
das Programm erkennt sie dann beim nächsten Neustart.

8. Am einfachsten ist es erst einmal eine der vorhandenen Strategien zu
kopieren, sie abzuwandeln und - nicht vergessen!!! - mit einem neuen Namen zu
versehen.

9. Um das Programmieren der Strategien zu vereinfachen, enthält das
Modul "Toolkit.py" eine Reihe von nützlichen Funktionen, die
von "Strategy.py" importiert werden. So muss man sich nicht mit den Untiefen
von "numpy" herumschlagen. (siehe die Beispielstrategien im Modul "Strategy.py"

Wer Probleme beim Installieren oder mit der Programmierung von Strategien hat,
kann sich jederzeit an mich wenden. (Im Büro unter 4129 oder einfach vorbei
kommen, wenn ich da bin.)


Dankeschön an:
-----------------
Luke Rendell und die Leute, die das cultaptation Turnier veranstalten!

Phlipp Schaechtele, Christoph Siemroth, Julia Lohmann, Martin Neumann
(für Strategien und feed-back!) 



