README

# 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](http://www.gt-mathsbio.biologie.ens.fr/)" in the
École normale supérieure (Paris, France) and it gives [this kind](http://www.eleves.ens.fr/home/doulcier/projects/math/ipdt.html) [of output](http://www.eleves.ens.fr/home/doulcier/projects/math/popdyn.html ).

## How to 
### Play around
To test it, if you have python2.7 and pip available the installation is quite simple:

```bash
# 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:
```bash
$ ipdt tournament 
``` 

You can restrict the tournament to a subset of strategies:
```bash
# 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).

```bash
# 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:

```bash
$ 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](http://www.eleves.ens.fr/home/doulcier/projects/math/ipdt.html) (and [for population dynamics](http://www.eleves.ens.fr/home/doulcier/projects/math/popdyn.html)) 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. 

```bash
## 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:

```python
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](https://guides.github.com/introduction/flow/index.html) 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.