Iterated Prisoner's Dilemma Tournament
Python
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
ipdt
.gitignore
LICENSE
README
README.md
setup.py

README.md

ipdt : Iterated Prisoner's dilemma tournament

ipdt (Iterated Prisoner's Dilemma Tournament) is a simple software to organize iterated prisoner's dilemma competition between different strategies.

It has been written for the "Mathematics and Biology Workgroup" in the École normale supérieure (Paris, France) and it gives this kind of output.

How to

Play around

To test it, if you have python2.7 and pip available the installation is quite simple:

# Global install (for all users):
$ sudo pip install -U https://github.com/geeklhem/ipdt/zipball/master 
# Local install (for the current user only, do not need root privileges):
$ pip install --user -U https://github.com/geeklhem/ipdt/zipball/master
# To uninstall 
$ sudo pip uninstall ipdt

Then you can run a tournament between all defined strategies:

$ ipdt tournament 

You can restrict the tournament to a subset of strategies:

# list all available strategies:
$ ipdt list
# A tournament with only three strategies:
$ ipdt tournament --players naivecoop defector randomplayer
# A tournament with all strategies but the simpletons:
$ ipdt tournament --exclude naivecoop defector 

We have implemented a small model of population dynamics:

  • The payoffs are computed by a simple tournament.
  • Each strategies start with an equal proportion in the population.
  • Each generation, the geometric growth of their relative abundance is given by their payoffs weighted by the encounter probability (product of abundances).
# Run a population dynamics model for 10 generations with a null mutation level.
$ ipdt popdyn --generations 10 --mu 0

Finally, you can also run a single match between two strategies:

$ ipdt match -p naivecoop randomplayer

If you want more detailed info on the output, you can use the options (from the less to the more detailed output) -v: warnings (default), -vv info or -vvv debug.

You can have a nice HTML5 export (and for population dynamics) by using the --html filename option: it will create a filename.html file in your current folder.

Write a strategy

Get the code

In order to write a strategy, you should install the module in "develop mode", this way the modifications you do in the code will be immediately available.

## 1. Download it.
# Using git (useful if you want to submit your code):  
$ git clone https://github.com/geeklhem/ipdt/
# Or without git:
$ wget https://github.com/geeklhem/ipdt/archive/master.zip; unzip master.zip ; mv ipdt-master ipdt  

## 2. Install it
$ cd ipdt
$ sudo python setup.py develop ## Globally (all user) 
$ python setup.py develop --user ## Locally (just for you, if you do not want/cannot execute it as root).

Create your module

In ipdt, each strategies is stored as a python module (codename.py) in the players/ folder. Several strategies are bundled with the code, it is a good idea to go and check them.

A strategy module to be valid must:

  • Have a different name than the other modules,
  • Contain a Player class inheriting from ipdt.player.Player,
  • This object must have a method play(self,last_move) that take the opponent last move (as a boolean, True for cooperation, False for defection and None in the first round) and return a boolean for your move (same convention).

You can also:

  • Write an __init__(self,param) function, that will be ran before the beginning of the match, to set up some attributes. You can also use it to read the dictionary param containing the match parameters: param["T"] contains the number of successive rounds, param["cd"], param["cc"], param["dc"], param["dd"], contains the payoff matrix (the first character is the move: c or d of the focal player);
  • Define the Player.name and Player.author class variable to characterize your strategy;
  • Write a docstring for the class to describe your strategy (it is used in the HTML output).

Here is an example code for the naive cooperator strategy:

import ipdt.player

class Player(ipdt.player.Player):
    """ Naive cooperator, a strategy that think everyone is nice. """
    name = "Naive cooperator"
	author = "Robert Axelrod"
	
	def __init__(self, param):
        """
        Use this function to set up match wise attributes.

        Args:
            param (dict): the match parameters.
		"""
		pass 

    def play(self, last_move):
	    """
        Use this function to choose your action each turn.
    
        Args:
            last_move (boolean): Your oponent last move `True` for cooperation,
                `False` for defection and `None` in the first round.
        Return: 
            (boolean): Your move (same convention).
        """  
        return True 

Submit a strategy

You can either do a github pull request or send us your module (the *.py file) at gt-mathsbio.contact(AT)lists.ens.fr.

License

This program is distributed under the term of the GNU General Public License v3 (or later) with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it.