axelrod-python / axelrod

A research tool for the Iterated Prisoner's Dilemma

Axelrod

Goals

A Python library with the following principles and goals:

1. Enabling the reproduction of previous Iterated Prisoner's Dilemma research as easily as possible.
2. Creating the de-facto tool for future Iterated Prisoner's Dilemma research.
3. Providing as simple a means as possible for anyone to define and contribute new and original Iterated Prisoner's Dilemma strategies.
4. Emphasizing readability along with an open and welcoming community that is accommodating for developers and researchers of a variety of skill levels.

Features

With Axelrod you:

• have access to over 200 strategies, including original and classics like Tit For Tat and Win Stay Lose Shift. These are extendable through parametrization and a collection of strategy transformers.
• can create head to head matches between pairs of strategies.
• can create tournaments over a number of strategies.
• can study population dynamics through Moran processes and an infinite population model.
• can analyse detailed results of tournaments and matches.

• can visualise results of tournaments.

  

• can reproduce a number of contemporary research topics such as fingerprinting of strategies and morality metrics.

  

The library has 100% test coverage and is extensively documented. See the documentation for details and examples of all the features: http://axelrod.readthedocs.org/

An open reproducible framework for the study of the iterated prisoner's dilemma: a peer reviewed paper introducing the library (22 authors).

Installation

The library is tested on Python versions 3.8, 3.9, and 3.10.

The simplest way to install is:

$ pip install axelrod

To install from source:

$ git clone https://github.com/Axelrod-Python/Axelrod.git
$ cd Axelrod
$ python setup.py install

Quick Start

The following runs a basic tournament:

>>> import axelrod as axl
>>> players = [s() for s in axl.demo_strategies]  # Create players
>>> tournament = axl.Tournament(players, seed=1)  # Create a tournament
>>> results = tournament.play()  # Play the tournament
>>> results.ranked_names
['Defector', 'Grudger', 'Tit For Tat', 'Cooperator', 'Random: 0.5']

Examples

• https://github.com/Axelrod-Python/tournament is a tournament pitting all the strategies in the repository against each other. These results can be easily viewed at http://axelrod-tournament.readthedocs.org.
• https://github.com/Axelrod-Python/Axelrod-notebooks contains a set of example Jupyter notebooks.
• https://github.com/Axelrod-Python/Axelrod-fingerprint contains fingerprints (data and plots) of all strategies in the library.

Contributing

All contributions are welcome!

You can find helpful instructions about contributing in the documentation: https://axelrod.readthedocs.io/en/latest/how-to/contributing/index.html

Publications

You can find a list of publications that make use of or cite the library on the citations page.

Contributors

The library has had many awesome contributions from many great contributors. The Core developers of the project are:

• drvinceknight
• gaffney2010
• marcharper
• meatballs
• nikoleta-v3

axelrod's Issues

Stop mind control strategy from spoiling all tournaments...

Implement the logging package

Replace the current bespoke logging solution with the standard logging package: https://docs.python.org/2/library/logging.html

Run the tournament itself on travis?

Is this something that you can even do?

Get results graph to plot but sort strategies by median score

Simple to do: will make plots look nicer.

Re-write README.md in rest

Based on hitchhikers guide this is apparently needed for Pypi.

Write nice overview of Axelrod's tournament for docs

Note that read the docs can render mathjax etc...

(Here's the currently rendered documentation: http://axelrod.readthedocs.org/en/latest/)

All files are written using sphinx in rst and can be found in the docs directory.

Write section about contributing

This is currently an empty rst file. Would be nice to come up with a nice guide (similar but improved version of what is currently in the README) and also include guidelines about convention (similar to discussion had at #85.

(Here's the currently rendered documentation: http://axelrod.readthedocs.org/en/latest/)

All files are written using sphinx in rst and can be found in the docs directory.

Move all outputs of the `run_tournment` script to an `assets` directory

This really should have been in place from the start: tidies things up nicely.

Very easy PR:

• tweak run_tournament.py script
• mv files.

Packaging, versioning, tagging etc...

So I've just written what I feel is an ok first draft of the documentation: http://axelrod.readthedocs.org/en/latest/ (by the way, what is the favicon for you on that? It seems to not at all be what I had hoped...).

I really want to get it so that this package can be installed as so:

pip install axelrod

To do this I need to write a setup.py file (working on #94 as we speak, using: https://the-hitchhikers-guide-to-packaging.readthedocs.org/en/latest/).

Does anyone know anything about this sort of thing/had an experience with it (so I'd like to tag this as a 0.1 version for example)? If you do, any tips/pointers etc would be awesome :)

Django Application

This could be turned into a Django application, hosted on Heroku or similar, with the tournament(s) results serialised to JSON via the Django Rest Framework and therefore available publicly for analysis by anyone.

There could be an admin backend for configuring and initialising tournaments and some work in AngularJS and D3 should enable all sorts of visualisiation.

Depends on: #45

Just have to find someone to fund my time to do this rather than the day job!!

Remove Numpy throughout

After discussion #98, I've decided that it'll be nice to have this written in as pure Python as possible.

@langner seems to already be working on this here #96 (Thanks!)

Write a manage.py script

As the number of strategies grows: the mathces (or just the random repetitions) can be parallelised (possibly even making use of caching for non stochastic strategies...).

Add docs

Could use this as an opportunity to try out readthedocs...

Rename and extend Boxplot class

Rename and extend the BoxPlot class so that it also processes the payoff plots thus:

• Simplifying run_tournament
• Allowing the elements of the payoff plot, currently in run_tournament, to become individual methods which can be included in the test suite
• Only checking for matplotlib installation once - in the class

Give players different classes

This will then determine which tournament they should be run in (Cheating class, All class etc)

Fix reset method (again): now does not reset score

See this branch/commit: 63eaa85

@geraintpalmer @JasYoung314

Improve how docstrings for strategies appear/are generated?

It must be possible to automate the generation of a sub header etc for each strategy?

Currently in the strategies.rst file I have manually listed all of them. I can't seem to be able to find how to automate this...

(Here's the currently rendered documentation: http://axelrod.readthedocs.org/en/latest/)

All files are written using sphinx in rst and can be found in the docs directory.

Parallelisation hangs

As far as I can tell this is something to do with #122 but I have no idea.

It hangs at this stage:

➜ Axelrod git:(master) ✗ python run_tournament.py -p 3
Starting basic_strategies tournament with 10 round robins of 200 turns per pair.
Passing cache with 0 entries to basic_strategies tournament
Running repetitions with 3 parallel processes
Finished basic_strategies tournament in 0.0s
Starting ecological variant of basic_strategies
Finished ecological variant of basic_strategies in 0.0s
Cache now has 10 entries
Finished all basic_strategies tasks in 1.3s

Starting strategies tournament with 10 round robins of 200 turns per pair.
Passing cache with 10 entries to strategies tournament
Running repetitions with 3 parallel processes

Infinite recursion

What happens when a geller encounters another geller?

Questions regarding tournament

Not sure if this is the right place for this, if not, please say!

I've been reading a bit around the history of this, and found a document which claims that the original tournament had 14 entries (15 including random) and the follow up had 62 entries (63 including random). These 62/63 strategies then went into the ecological tournament.

So whilst the number of strategies is not yet close to the number in the second iteration of the original tournament, we have nearly double the number used in the first iteration.

My questions:

• Is the intention to ultimately run the tournament and declare a winner?
• If so, will there be a prize? 🏆
• Any thoughts on why Tit for Tat isn't winning yet? Is it really just that more strategies are required?
• I've not yet found anything that describes what hardware/software was used to run the original tournament. Anyone know?

Create a BoxPlot class

This class should handle the production of a matlibplot boxplot based on a ResultSet instance passed to its init method.

The functions to generate the boxes/whiskers, xticks, and title should be separate methods with tests for each.

The method which would return an instance of matlibplot.Figure probably cannot be tested as Travis does not have matlibplot installed.

run_tournament.py would handle the creation of .png files based on the Figure object returned from this class.

Add list of contributors to README

and invite people to add their name/url when they contribute...

Add probabilistic ending variant

Add a variant where each round ends the match with given probability.

Write contribution guidelines

I'd suggest:

• Follow PEP guidelines
• No use of external library unless really necessary (matplotlib for example is deemed necessary but has exception handling so that code can be run without it).
• 100% test coverage (a very nice test suite has been written that automates a lot of the testing)

Ecological tournament variant

I'm not sure if it was organized by Axelrod, but there was a subsequent "ecological" tournament where each strategy was represented by some number of copies. The tournament consisted of ~1000 generations, and at the beginning of each generation the population of a strategy was set based on its score in the previous round.

This interesting variant could be easily built on top of the current code.

Strategy Design Pattern

Implement the strategy design pattern described here: https://en.wikipedia.org/wiki/Strategy_pattern

This would:

• Separate the behaviour of a Player from its instantiation and/or participation in a Tournament
• Simplify the definition of Strategies
• Allow multiple Players in a Tournament to use the same Strategy
• Enable dynamic allocation of Strategy to Player at Tournament runtime
• Enable the Django model layer (#44) to represent Players and Tournaments as simple objects with properties

Both a function and a class based example of how the pattern might be implemented in Python are described here: http://codereview.stackexchange.com/questions/20718/strategy-design-pattern-with-various-duck-type-classes

Make each test runable as standalone

Need to add code to bottom of every test script... (Why did I not do this to start?)

if __name__ == '__main__':
    unittest.main()

Add test for running of tournament

Possibly write a full tournament method.

Simply need to check that the tournament runs.

Should this be a 'pure Python' package?

In other words should we try to avoid numpy in the couple of places that we use it (it would be relatively straightforward to remove it as a dependancy)?

(matplotlib is another kettle of fish as there is no alternative)

Include exception catching for matplotlib

Following discussion here #98 I'd like to include a try... except for the use of matplotlib.

I think that this might be able to be incorporated in to the work being done by @meatballs on #88 (Owen, I'd be happy to accept a PR without the error handling and put that in myself).

Include the two missing memoryone strategies (already written: just commented out - need tests etc...)

@marcharper wrote a big pull request that took me a little while to merge as it needed tests etc...

I ended up commenting out two of the strategies: fa57959

It would be great to get them in, it just needs some tests and a PR that clarifies a couple of things.

Get mind reader back in

mindreader and geller are 2 'cheater' strategies but they cannot actually play against each other.

Would be cool to figure it out (even if perhaps we do this with error handling...)

@JasYoung314

Fool Me Once and Grudger

My apologies if I'm missing something, but aren't the 'Fool Me Once' and 'Grudger' strategies the same strategy with different implementations in code?

Random strategy gets mean score greater than 5

Looking at the boxplot it seems the the random strategy gets a score higher than it should be able to.

Figure out good way to sync gh-pages and master...

Improve the quality of ResultsSet testing

By including games with non zero scores

Rewrite how the reset method work

Have players have a reset method and just replace the relevant reset methods in the tournament.

Go through all strategies and write more tests

I'd like every strategy to be extensively tested. Some don't have tests for basic methods (repr etc...), whilst this might seem like overkill, I would prefer this project to be over tested than under tested.

Add a requirements.txt file

They results objects make use of numpy and matplotlib.

Refactor deterministic cache mechanism

• Ensure that the mechanism is used consistently across all Classes which utilise it
• Write some tests to ensure it works correctly
• Share it across multiple tournaments within the TournamentManager Class

Depends on #116

Come up with a nice favicon and image?

The documentation could perhaps use a nice favicon and image?

If anyone's good with design etc... Perhaps throw some images in this issue?

(Here's the currently rendered documentation: http://axelrod.readthedocs.org/en/latest/)

All files are written using sphinx in rst and can be found in the docs directory.

Write a setup.py script

Make running the cheating strategies optional (as some of them take time)

If we use docopt we should grab the script directly and not require it to be installed, because this is so simple though we could just use the base python argv or there is some python inbuilt library also...

A couple more tests for reflex.

Need to build up documentation about all the strategies.

Perhaps there is a way to script pulling the description of the strategy out of docstring... I know that sage does this, that could work in conjunction with readthedocs...

I set this up last weekend: http://axelrod.readthedocs.org/en/docs/ it is reading off the docs branch which has nothing in it.

Test (and improve) the packaging

So there is now a packaged version of axelrod available via pip. This is all from the packaging branch and this issue is to discuss any issues before merging in to master and making things 'official' :)

To test, I suggest creating a virtualenv as this will install 'system wide':

virtualenv tmp-axelrod2 # I had about 7 of these going as I as testing and am just about to tear them down
cd tmp-axelrod2 # Go to that directory
source bin/activate  # (depending on your shell this might need a tweak)

Type the following just to make sure that you have got a virtualenv:

which pip

Install through the magics of the internetz:

pip install axelrod

Note that that pulls down matplotlib also (which if you're in the virtualenv you will notice).

Now to run the tournament I have made some tweaks (see the packaging branch).
Firstly I've renamed the run_tournament.py script to run_axelrod as pip now installs this as an executable file system wide.

So below will run the very basic tournament:

run_axelrod --xs --xc --xa --ne

One thing that will need work on this branch before pulling in to master will be updating the documentation.

Colouring cheaters in plot with all

@JasYoung314

Make sure each and every method etc has a line of docstring

Even if it's just a simple one liner that basically repeats the name of the function itself.

Parallelise the tournament

To speed up the running of the tournament it would be nice to add the option to parallelise the various matches (or indeed more simply the repetitions).

This could then be run by using a command line argument...

I'm pretty sure I've never parallelised anything 'in the right way' so I'm throwing the help wanted label on this one... If you'd like to pick it up: let's chat :)

Add fact that using travis for automated tests in README

This commit: 427c4fe

See https://travis-ci.org/drvinceknight/Axelrod