From 8fcef335aacfe553db7d2d2b4bbe178cc0f9e7d1 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 16 Sep 2015 21:44:08 +0100 Subject: [PATCH 01/82] New release --- CHANGES.txt | 1 + setup.py | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGES.txt b/CHANGES.txt index 2e2bf7188..847345b31 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -10,3 +10,4 @@ v0.0.9, 2015-06-14 -- Various improvements including noisy tournaments v0.0.10, 2015-08-17 -- Python 3 support and behaviour metrics v0.0.11, 2015-08-17 -- Updating Core team v0.0.12, 2015-09-02 -- Further behaviour and more info being passed to players. +v0.0.13, 2015-09-16 -- Adding classifier dictionary and dynamic strategy list. diff --git a/setup.py b/setup.py index b447ea178..595eb4a08 100644 --- a/setup.py +++ b/setup.py @@ -2,7 +2,7 @@ setup( name='Axelrod', - version='0.0.12', + version='0.0.13', author='Vince Knight, Owen Campbell, Karol Langner, Marc Harper', author_email=('axelrod-python@googlegroups.com'), packages=['axelrod', 'axelrod.strategies', 'axelrod.tests'], From 9612c061ee7fa6f1a9d7193c586083c8b22673e4 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 21:58:44 +0100 Subject: [PATCH 02/82] Inputting some basic tutorials. --- docs/index.rst | 18 ++--------- docs/tutorials/getting_started.rst | 49 ++++++++++++++++++++++++++++++ docs/tutorials/index.rst | 25 +++++++++++++++ 3 files changed, 77 insertions(+), 15 deletions(-) create mode 100644 docs/tutorials/getting_started.rst create mode 100644 docs/tutorials/index.rst diff --git a/docs/index.rst b/docs/index.rst index ca4209416..e6e9c2ed5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,25 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to the documentation for an implementation of Axelrod's tournament in Python -==================================================================================== - -This project is both: - -* A python library that reproduces Axelrod's tournament. -* A github experiment allowing anyone to contribute a strategy. - - -Contents: +Welcome to the documentation for the Axelrod Python library +=========================================================== .. toctree:: :maxdepth: 2 - background - usage - overview_of_strategies - index_of_strategies - contributing + tutorials/index.rst Indices and tables diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst new file mode 100644 index 000000000..28816e4f5 --- /dev/null +++ b/docs/tutorials/getting_started.rst @@ -0,0 +1,49 @@ +Getting started +=============== + +lipsum + + +Installation +------------ + +The simplest way to install the package is to obtain it from the PyPi +repository:: + + $ pip install axelrod + + +You can also build it from source if you would like to:: + + $ git clone https://github.com/Axelrod-Python/Axelrod.git + $ cd Axelrod + $ python setup.py install + + +Creating and running a simple tournament +---------------------------------------- + +The following lines of code create a simple list of strategies:: + + >>> import axelrod + >>> strategies = [s() for s in axelrod.demo_strategies] + >>> strategies + [Cooperator, Defector, Tit For Tat, Grudger, Random: 0.5] + +We can now create a tournament, play it, saving the results and viewing the +ranks of each player:: + + >>> tournament = axelrod.Tournament(strategies) + >>> results = tournament.play() + >>> results.ranked_names + ['Defector', 'Grudger', 'Tit For Tat', 'Cooperator', 'Random: 0.5'] + +We can also plot these results (which helps visualise the stochastic effects):: + + >>> plot = axelrod.Plot(results) + >>> p = plot.boxplot() + >>> p.show() + +.. image:: _static/usage/demo_strategies_boxplot.svg + :width: 50% + :align: center diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 000000000..57857faec --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,25 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Tutorials +========= + +This section contains a variety of tutorials related to the Axelrod library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + getting_started.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + From 2a7224cd841f8dc241e889348165c06e96122cb4 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 22:08:47 +0100 Subject: [PATCH 03/82] Deleting this as didn't seem to have an effect --- docs/auto_generate_strategies_list.py | 42 --------------------------- 1 file changed, 42 deletions(-) delete mode 100644 docs/auto_generate_strategies_list.py diff --git a/docs/auto_generate_strategies_list.py b/docs/auto_generate_strategies_list.py deleted file mode 100644 index f8b4da374..000000000 --- a/docs/auto_generate_strategies_list.py +++ /dev/null @@ -1,42 +0,0 @@ -""" -A script to generate the file needed for the strategy documentation. - -Run: - - python strategies.py > strategies.rst -""" -import os -import sys - -sys.path.insert(0, os.path.abspath("../")) -from axelrod import basic_strategies -from axelrod import ordinary_strategies -from axelrod import cheating_strategies - - -def print_header(string, character): - print string - print character * len(string) - print "" - - -if __name__ == "__main__": - - print ".. currentmodule:: axelrod.strategies" - print_header("Index of strategies", '=') - - print_header("Basic strategies", '-') - for strategy in basic_strategies: - print ".. autoclass:: %s" % strategy.__name__ - - print "" - - print_header("Further (honest) Strategies", '-') - for strategy in ordinary_strategies: - print ".. autoclass:: %s" % strategy.__name__ - - print "" - - print_header("Cheating strategies", '-') - for strategy in cheating_strategies: - print ".. autoclass:: %s" % strategy.__name__ From 29da9e9e3e11da7abefc804c076498f308b521b6 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 22:09:43 +0100 Subject: [PATCH 04/82] Writing test scripts --- .travis.yml | 1 + doctest | 2 ++ test | 3 +++ 3 files changed, 6 insertions(+) create mode 100755 doctest create mode 100755 test diff --git a/.travis.yml b/.travis.yml index 9354afcf2..846ba96db 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,5 +12,6 @@ install: - pip install coveralls script: - coverage run --source=axelrod -m unittest discover + - sh doctest after_success: - coveralls diff --git a/doctest b/doctest new file mode 100755 index 000000000..f263a59a6 --- /dev/null +++ b/doctest @@ -0,0 +1,2 @@ +#!/usr/bin/env bash +python -m doctest docs/tutorials/*rst diff --git a/test b/test new file mode 100755 index 000000000..ed49bd58a --- /dev/null +++ b/test @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +python -m unittest discover axelrod/tests/ +./doctest From 77e5c2878f1789eb930aa2561d382bdbce5eae69 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 22:10:11 +0100 Subject: [PATCH 05/82] Reorganising files. --- docs/{ => background}/background.rst | 0 docs/description.rst | 4 ---- docs/index.rst | 2 ++ docs/{ => reference}/index_of_strategies.rst | 0 docs/{ => reference}/overview_of_strategies.rst | 0 .../_static/getting_started}/demo_strategies_boxplot.svg | 0 docs/{contributing.rst => tutorials/contributing.old} | 0 docs/tutorials/getting_started.rst | 2 +- docs/{usage.rst => tutorials/usage.old} | 0 9 files changed, 3 insertions(+), 5 deletions(-) rename docs/{ => background}/background.rst (100%) delete mode 100644 docs/description.rst rename docs/{ => reference}/index_of_strategies.rst (100%) rename docs/{ => reference}/overview_of_strategies.rst (100%) rename docs/{_static/usage => tutorials/_static/getting_started}/demo_strategies_boxplot.svg (100%) rename docs/{contributing.rst => tutorials/contributing.old} (100%) rename docs/{usage.rst => tutorials/usage.old} (100%) diff --git a/docs/background.rst b/docs/background/background.rst similarity index 100% rename from docs/background.rst rename to docs/background/background.rst diff --git a/docs/description.rst b/docs/description.rst deleted file mode 100644 index b7387825f..000000000 --- a/docs/description.rst +++ /dev/null @@ -1,4 +0,0 @@ -Description -=========== - -Describe the available strategies. diff --git a/docs/index.rst b/docs/index.rst index e6e9c2ed5..b68edb3ec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,8 @@ Welcome to the documentation for the Axelrod Python library =========================================================== +lipsum + .. toctree:: :maxdepth: 2 diff --git a/docs/index_of_strategies.rst b/docs/reference/index_of_strategies.rst similarity index 100% rename from docs/index_of_strategies.rst rename to docs/reference/index_of_strategies.rst diff --git a/docs/overview_of_strategies.rst b/docs/reference/overview_of_strategies.rst similarity index 100% rename from docs/overview_of_strategies.rst rename to docs/reference/overview_of_strategies.rst diff --git a/docs/_static/usage/demo_strategies_boxplot.svg b/docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg similarity index 100% rename from docs/_static/usage/demo_strategies_boxplot.svg rename to docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg diff --git a/docs/contributing.rst b/docs/tutorials/contributing.old similarity index 100% rename from docs/contributing.rst rename to docs/tutorials/contributing.old diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst index 28816e4f5..27968da90 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/tutorials/getting_started.rst @@ -44,6 +44,6 @@ We can also plot these results (which helps visualise the stochastic effects):: >>> p = plot.boxplot() >>> p.show() -.. image:: _static/usage/demo_strategies_boxplot.svg +.. image:: _static/getting_started/demo_strategies_boxplot.svg :width: 50% :align: center diff --git a/docs/usage.rst b/docs/tutorials/usage.old similarity index 100% rename from docs/usage.rst rename to docs/tutorials/usage.old From 0cea46a38f9e9b36c32d1c1ef29da86899a10dee Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 22:48:40 +0100 Subject: [PATCH 06/82] Removing stochastic strategies from early tutorials --- .../demo_strategies_boxplot.svg | 0 .../demo_strategies_payoff.svg | 0 docs/tutorials/getting_started.rst | 15 +++---- docs/tutorials/index.rst | 2 + docs/tutorials/payoff_matrix.rst | 34 ++++++++++++++++ docs/tutorials/visualising_results.rst | 40 +++++++++++++++++++ 6 files changed, 84 insertions(+), 7 deletions(-) rename docs/tutorials/_static/{getting_started => visualising_results}/demo_strategies_boxplot.svg (100%) rename docs/{_static/usage => tutorials/_static/visualising_results}/demo_strategies_payoff.svg (100%) create mode 100644 docs/tutorials/payoff_matrix.rst create mode 100644 docs/tutorials/visualising_results.rst diff --git a/docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg similarity index 100% rename from docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg rename to docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg diff --git a/docs/_static/usage/demo_strategies_payoff.svg b/docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg similarity index 100% rename from docs/_static/usage/demo_strategies_payoff.svg rename to docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst index 27968da90..62bd7b2c1 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/tutorials/getting_started.rst @@ -25,25 +25,26 @@ Creating and running a simple tournament The following lines of code create a simple list of strategies:: - >>> import axelrod - >>> strategies = [s() for s in axelrod.demo_strategies] + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] >>> strategies - [Cooperator, Defector, Tit For Tat, Grudger, Random: 0.5] + [Cooperator, Defector, Tit For Tat, Grudger] We can now create a tournament, play it, saving the results and viewing the ranks of each player:: - >>> tournament = axelrod.Tournament(strategies) + >>> tournament = axl.Tournament(strategies) >>> results = tournament.play() >>> results.ranked_names - ['Defector', 'Grudger', 'Tit For Tat', 'Cooperator', 'Random: 0.5'] + ['Defector', 'Tit For Tat', 'Grudger', 'Cooperator'] We can also plot these results (which helps visualise the stochastic effects):: - >>> plot = axelrod.Plot(results) + >>> plot = axl.Plot(results) >>> p = plot.boxplot() >>> p.show() -.. image:: _static/getting_started/demo_strategies_boxplot.svg +.. image:: _static/getting_started/demo_deterministic_strategies_boxplot.svg :width: 50% :align: center diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 57857faec..74f9d1dbb 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -14,6 +14,8 @@ Contents: :maxdepth: 2 getting_started.rst + payoff_matrix.rst + visualising_results.rst Indices and tables diff --git a/docs/tutorials/payoff_matrix.rst b/docs/tutorials/payoff_matrix.rst new file mode 100644 index 000000000..8dbddb03a --- /dev/null +++ b/docs/tutorials/payoff_matrix.rst @@ -0,0 +1,34 @@ +Accessing the payoff matrix +=========================== + +lipsum + +This tutorial will show you briefly how to access the payoff matrix +corresponding to the tournament. + +Accessing the payoff matrix +--------------------------- + +As shown in `Getting_started`_ let us create a tournament:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + +We can view the payoff matrix of our tournament showing the score of the row-th +strategy when played against the column-th strategy:: + + >>> m = results.payoff_matrix + >>> for row in m: + ... print [round(ele, 1) for ele in row] # Rounding output + [3.0, 0.0, 3.0, 3.0] + [5.0, 1.0, 1.0, 1.0] + [3.0, 1.0, 3.0, 3.0] + [3.0, 1.0, 3.0, 3.0] + +Here we see that the second strategy (:code:`Defector`) obtains an average +utility per game of :code:`5.0` against the first strategy (:code:`Cooperator`) +as expected. + diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/visualising_results.rst new file mode 100644 index 000000000..e43fd414a --- /dev/null +++ b/docs/tutorials/visualising_results.rst @@ -0,0 +1,40 @@ +Visualising results +=================== + +lipsum + +This tutorial will show you briefly how to visualise some basic results + +Creating an axelrod plot instance +--------------------------------- + +As shown in `Getting_started`_ let us create a tournament, but this time we will +include a strategy that acts randomly:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> strategies.append(axl.Random()) + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + +We can view these results (which helps visualise the stochastic effects):: + + >>> plot = axl.Plot(results) + >>> p = plot.boxplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_boxplot.svg + :width: 50% + :align: center + +We can also easily view the payoff matrix described in `Payoff_matrix`_, this +becomes particularly useful when viewing the outputs of tournaments with a large +number of strategies:: + + >>> p = plot.payoff() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_payoff.svg + :width: 50% + :align: center From 5689be3e70cf99440aed8f0f342b03b053d6bccf Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 23:04:40 +0100 Subject: [PATCH 07/82] Making docs python 3 compatible. --- docs/tutorials/payoff_matrix.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/tutorials/payoff_matrix.rst b/docs/tutorials/payoff_matrix.rst index 8dbddb03a..20ba841c1 100644 --- a/docs/tutorials/payoff_matrix.rst +++ b/docs/tutorials/payoff_matrix.rst @@ -6,9 +6,6 @@ lipsum This tutorial will show you briefly how to access the payoff matrix corresponding to the tournament. -Accessing the payoff matrix ---------------------------- - As shown in `Getting_started`_ let us create a tournament:: >>> import axelrod as axl @@ -22,7 +19,7 @@ strategy when played against the column-th strategy:: >>> m = results.payoff_matrix >>> for row in m: - ... print [round(ele, 1) for ele in row] # Rounding output + ... print([round(ele, 1) for ele in row]) # Rounding output [3.0, 0.0, 3.0, 3.0] [5.0, 1.0, 1.0, 1.0] [3.0, 1.0, 3.0, 3.0] From a65d78fd0ff5fd28b165839675ec7288c5ed8771 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 23:04:56 +0100 Subject: [PATCH 08/82] Compartementalising documentation. --- docs/tutorials/visualising_results.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/visualising_results.rst index e43fd414a..d480af46b 100644 --- a/docs/tutorials/visualising_results.rst +++ b/docs/tutorials/visualising_results.rst @@ -5,8 +5,8 @@ lipsum This tutorial will show you briefly how to visualise some basic results -Creating an axelrod plot instance ---------------------------------- +Visualising the results of the tournament +----------------------------------------- As shown in `Getting_started`_ let us create a tournament, but this time we will include a strategy that acts randomly:: @@ -28,6 +28,9 @@ We can view these results (which helps visualise the stochastic effects):: :width: 50% :align: center +Visualising the payoff matrix +----------------------------- + We can also easily view the payoff matrix described in `Payoff_matrix`_, this becomes particularly useful when viewing the outputs of tournaments with a large number of strategies:: From 60d3200b37182c402d83bcce451b296a9187e320 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 17:35:56 +0100 Subject: [PATCH 09/82] Adding requirements.txt instructions. --- docs/tutorials/getting_started.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst index 62bd7b2c1..1ee21a446 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/tutorials/getting_started.rst @@ -19,6 +19,9 @@ You can also build it from source if you would like to:: $ cd Axelrod $ python setup.py install +If you do this you will need to also install the dependencies:: + + $ pip install -r requirements.txt Creating and running a simple tournament ---------------------------------------- From 6d2458336e80580ce6de7b77baa35ea8ab7c5d4e Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 17:57:00 +0100 Subject: [PATCH 10/82] Merge conflict. --- setup.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/setup.py b/setup.py index ed83f5ebb..2541c1e22 100644 --- a/setup.py +++ b/setup.py @@ -3,11 +3,7 @@ setup( name='Axelrod', -<<<<<<< HEAD - version='0.0.13', -======= version='0.0.15', ->>>>>>> master author='Vince Knight, Owen Campbell, Karol Langner, Marc Harper', author_email=('axelrod-python@googlegroups.com'), packages=['axelrod', 'axelrod.strategies', 'axelrod.tests'], From 4edbedc59cf8db542da1ed10663688cea5269f5d Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 18:00:09 +0100 Subject: [PATCH 11/82] Adding distribution of wins section to visualisation. --- .../demo_strategies_winplot.svg | 1284 +++++++++++++++++ docs/tutorials/index.rst | 1 + docs/tutorials/visualising_results.rst | 12 + 3 files changed, 1297 insertions(+) create mode 100644 docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg new file mode 100644 index 000000000..04ab787a7 --- /dev/null +++ b/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg @@ -0,0 +1,1284 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 74f9d1dbb..e4412fbc6 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -16,6 +16,7 @@ Contents: getting_started.rst payoff_matrix.rst visualising_results.rst + noisy_tournaments.rst Indices and tables diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/visualising_results.rst index d480af46b..afa194a09 100644 --- a/docs/tutorials/visualising_results.rst +++ b/docs/tutorials/visualising_results.rst @@ -28,6 +28,18 @@ We can view these results (which helps visualise the stochastic effects):: :width: 50% :align: center +Visualising the distributions of wins +------------------------------------- + +We can view the distributions of wins for each player:: + + >>> p = plot.winplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_winplot.svg + :width: 50% + :align: center + Visualising the payoff matrix ----------------------------- From 47f2b86c70d94d34c9686b736ec3eeeba357ef5c Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 18:00:41 +0100 Subject: [PATCH 12/82] Adding egg to gitignore For when use python setup.py develop. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index af448dbd4..3bfad54a1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ _build/ *.log dist/ MANIFEST +Axelrod.egg-info From 340d9617ebe299f44bbe6e6e79316688fa581b41 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 18:08:21 +0100 Subject: [PATCH 13/82] Adding noisy tournaments section. --- .../demo_strategies_noisy_boxplot.svg | 1968 +++++++++++++++++ .../demo_strategies_noisy_winplot.svg | 1223 ++++++++++ docs/tutorials/noisy_tournaments.rst | 46 + 3 files changed, 3237 insertions(+) create mode 100644 docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg create mode 100644 docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg create mode 100644 docs/tutorials/noisy_tournaments.rst diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg new file mode 100644 index 000000000..677a3aa8d --- /dev/null +++ b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg @@ -0,0 +1,1968 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg new file mode 100644 index 000000000..e8292e132 --- /dev/null +++ b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg @@ -0,0 +1,1223 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/noisy_tournaments.rst b/docs/tutorials/noisy_tournaments.rst new file mode 100644 index 000000000..a55234bce --- /dev/null +++ b/docs/tutorials/noisy_tournaments.rst @@ -0,0 +1,46 @@ +Noisy tournaments +================= + +A common variation on iterated prisoner’s dilemma tournaments is to add +stochasticity in the choice of plays, simply called noise. This noise is +introduced by flipping plays between ‘C’ and ‘D’ with some probability that is +applied to all plays after they are delivered by the player. + +The presence of this persistant bakground noise causes some strategies to +behave substantially differently. For example, TitForTat can fall into +defection loops with itself when there is noise. While TitForTat would usually +cooperate well with itself:: + + C C C C C ... + C C C C C ... + +Noise can cause a C to flip to a D (or vice versa), disrupting the cooperative +chain:: + + C C C D C D C D D D ... + C C C C D C D D D D ... + +To create a noisy tournament you simply need to add the `noise` argument:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> noise = 0.1 + >>> tournament = axl.Tournament(strategies, noise=noise) + >>> results = tournament.play() + >>> plot = axl.Plot(results) + >>> p = plot.boxplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_noisy_boxplot.svg + :width: 50% + :align: center + +Here is how the distribution of wins now looks:: + + >>> p = plot.winplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_noisy_winplot.svg + :width: 50% + :align: center From b8c315aa6945c2a9042fa575974b8023d6f8bc0e Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:36:02 +0100 Subject: [PATCH 14/82] Reorganisation of tutorials. --- .../demo_strategies_boxplot.svg | 0 .../demo_strategies_noisy_boxplot.svg | 0 .../demo_strategies_noisy_winplot.svg | 0 .../demo_strategies_payoff.svg | 0 .../demo_strategies_stackplot.svg | 2293 +++++++++++++++++ .../demo_strategies_winplot.svg | 0 .../{ => getting_started}/contributing.old | 0 .../getting_started/ecological_variant.rst | 24 + .../{ => getting_started}/getting_started.rst | 0 docs/tutorials/getting_started/index.rst | 20 + .../noisy_tournaments.rst | 0 .../{ => getting_started}/payoff_matrix.rst | 0 .../tutorials/{ => getting_started}/usage.old | 0 .../visualising_results.rst | 0 docs/tutorials/index.rst | 7 +- 15 files changed, 2339 insertions(+), 5 deletions(-) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_boxplot.svg (100%) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_noisy_boxplot.svg (100%) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_noisy_winplot.svg (100%) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_payoff.svg (100%) create mode 100644 docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_winplot.svg (100%) rename docs/tutorials/{ => getting_started}/contributing.old (100%) create mode 100644 docs/tutorials/getting_started/ecological_variant.rst rename docs/tutorials/{ => getting_started}/getting_started.rst (100%) create mode 100644 docs/tutorials/getting_started/index.rst rename docs/tutorials/{ => getting_started}/noisy_tournaments.rst (100%) rename docs/tutorials/{ => getting_started}/payoff_matrix.rst (100%) rename docs/tutorials/{ => getting_started}/usage.old (100%) rename docs/tutorials/{ => getting_started}/visualising_results.rst (100%) diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_boxplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_boxplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_winplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_winplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_payoff.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_payoff.svg diff --git a/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg new file mode 100644 index 000000000..21876e775 --- /dev/null +++ b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg @@ -0,0 +1,2293 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_winplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_winplot.svg diff --git a/docs/tutorials/contributing.old b/docs/tutorials/getting_started/contributing.old similarity index 100% rename from docs/tutorials/contributing.old rename to docs/tutorials/getting_started/contributing.old diff --git a/docs/tutorials/getting_started/ecological_variant.rst b/docs/tutorials/getting_started/ecological_variant.rst new file mode 100644 index 000000000..a51b4c62b --- /dev/null +++ b/docs/tutorials/getting_started/ecological_variant.rst @@ -0,0 +1,24 @@ +Ecological Variant +================== + +To study the evolutionary stability of each strategy it is possible to create an +ecosystem based on the payoff matrix of a tournament:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger(), + ... axl.Random()] + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + >>> eco = axl.Ecosystem(results) + >>> eco.reproduce(100) # Evolve the population over 100 time steps + +Here is how we obtain a nice stackplot of the system evolving over time:: + + >>> plot = axl.Plot(results) + >>> p = plot.stackplot(eco.population_sizes) + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_stackplot.svg + :width: 50% + :align: center diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started/getting_started.rst similarity index 100% rename from docs/tutorials/getting_started.rst rename to docs/tutorials/getting_started/getting_started.rst diff --git a/docs/tutorials/getting_started/index.rst b/docs/tutorials/getting_started/index.rst new file mode 100644 index 000000000..615d030ef --- /dev/null +++ b/docs/tutorials/getting_started/index.rst @@ -0,0 +1,20 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Getting Started +=============== + +This section contains a variety of tutorials related to the Axelrod library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + getting_started.rst + payoff_matrix.rst + visualising_results.rst + noisy_tournaments.rst + ecological_variant.rst diff --git a/docs/tutorials/noisy_tournaments.rst b/docs/tutorials/getting_started/noisy_tournaments.rst similarity index 100% rename from docs/tutorials/noisy_tournaments.rst rename to docs/tutorials/getting_started/noisy_tournaments.rst diff --git a/docs/tutorials/payoff_matrix.rst b/docs/tutorials/getting_started/payoff_matrix.rst similarity index 100% rename from docs/tutorials/payoff_matrix.rst rename to docs/tutorials/getting_started/payoff_matrix.rst diff --git a/docs/tutorials/usage.old b/docs/tutorials/getting_started/usage.old similarity index 100% rename from docs/tutorials/usage.old rename to docs/tutorials/getting_started/usage.old diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/getting_started/visualising_results.rst similarity index 100% rename from docs/tutorials/visualising_results.rst rename to docs/tutorials/getting_started/visualising_results.rst diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index e4412fbc6..c0e7993a5 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -13,11 +13,8 @@ Contents: .. toctree:: :maxdepth: 2 - getting_started.rst - payoff_matrix.rst - visualising_results.rst - noisy_tournaments.rst - + getting_started/index.rst + further_topics/index.rst Indices and tables ================== From 8ec0e357f1703232276c54e6e8b37177a142e3ce Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:36:15 +0100 Subject: [PATCH 15/82] First further topics tutorials. --- docs/tutorials/further_topics/index.rst | 17 +++++++ .../further_topics/morality_metrics.rst | 44 +++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/tutorials/further_topics/index.rst create mode 100644 docs/tutorials/further_topics/morality_metrics.rst diff --git a/docs/tutorials/further_topics/index.rst b/docs/tutorials/further_topics/index.rst new file mode 100644 index 000000000..ed5ee3b78 --- /dev/null +++ b/docs/tutorials/further_topics/index.rst @@ -0,0 +1,17 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Further Topics +============== + +This section contains a variety of tutorials that show some more in depth +capabilities of the axelrod library + +Contents: + +.. toctree:: + :maxdepth: 2 + + morality_metrics.rst diff --git a/docs/tutorials/further_topics/morality_metrics.rst b/docs/tutorials/further_topics/morality_metrics.rst new file mode 100644 index 000000000..5e0dfb965 --- /dev/null +++ b/docs/tutorials/further_topics/morality_metrics.rst @@ -0,0 +1,44 @@ +Morality Metrics +================ + +Tyler Singer-Clark's June 2014 paper, "Morality Metrics On Iterated Prisoner’s +Dilemma Players," describes several interesting metrics which may be used to +analyse IPD tournaments all of which are available within the ResultSet class. +(Tyler's paper is available here: http://www.scottaaronson.com/morality.pdf). + +Each metric depends upon the cooperation rate of the players, defined by Tyler +Singer-Clark as: + +.. math:: + + CR(b) = \frac{C(b)}{TT} + +where C(b) is the total number of turns where a player chose to cooperate and TT +is the total number of turns played. + +A matrix of cooperation rates is available within a tournament's ResultSet:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + >>> results.normalised_cooperation + [[1.0, 1.0, 1.0, 1.0], [0.0, 0.0, 0.0, 0.0], [1.0, 0.005, 1.0, 1.0], [1.0, 0.005, 1.0, 1.0]] + +There is also a 'good partner' matrix showing how often a player cooperated at +least as much as its opponent:: + + >>> results.good_partner_matrix + [[0, 10, 10, 10], [0, 0, 0, 0], [10, 10, 0, 10], [10, 10, 10, 0]] + +Each of the metrics described in Tyler's paper is available as follows (here they are rounded to 2 digits):: + + >>> [round(ele, 2) for ele in results.cooperating_rating] + [1.0, 0.0, 0.75, 0.75] + >>> [round(ele, 2) for ele in results.good_partner_rating] + [1.0, 0.0, 1.0, 1.0] + >>> [round(ele, 2) for ele in results.eigenjesus_rating] + [0.58, 0.0, 0.58, 0.58] + >>> [round(ele, 2) for ele in results.eigenmoses_rating] + [0.37, -0.37, 0.6, 0.6] From 2a667828c83dbbd1286e91841d9cd71d5f6dd7f3 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:36:32 +0100 Subject: [PATCH 16/82] Modifying the doctests. --- doctest | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doctest b/doctest index f263a59a6..30142ba09 100755 --- a/doctest +++ b/doctest @@ -1,2 +1,3 @@ #!/usr/bin/env bash -python -m doctest docs/tutorials/*rst +python -m doctest docs/tutorials/getting_started/*rst +python -m doctest docs/tutorials/further_topics/*rst From 02d7fd7a0b5d0f9be3f00e12c1f296c5a5637f62 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:38:05 +0100 Subject: [PATCH 17/82] Some minor rewording. --- docs/index.rst | 2 -- docs/tutorials/getting_started/index.rst | 3 ++- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index b68edb3ec..e6e9c2ed5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,6 @@ Welcome to the documentation for the Axelrod Python library =========================================================== -lipsum - .. toctree:: :maxdepth: 2 diff --git a/docs/tutorials/getting_started/index.rst b/docs/tutorials/getting_started/index.rst index 615d030ef..b02ad4e02 100644 --- a/docs/tutorials/getting_started/index.rst +++ b/docs/tutorials/getting_started/index.rst @@ -6,7 +6,8 @@ Getting Started =============== -This section contains a variety of tutorials related to the Axelrod library. +This section contains a variety of tutorials that should help get you started +with the Axelrod library. Contents: From 9c252db023b350a7c44a9874519966804cd86b98 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:50:07 +0100 Subject: [PATCH 18/82] Starting work on contributions. --- docs/tutorials/contributing/guidelines.rst | 27 +++++++++++ docs/tutorials/contributing/index.rst | 18 +++++++ docs/tutorials/contributing/instructions.rst | 49 ++++++++++++++++++++ 3 files changed, 94 insertions(+) create mode 100644 docs/tutorials/contributing/guidelines.rst create mode 100644 docs/tutorials/contributing/index.rst create mode 100644 docs/tutorials/contributing/instructions.rst diff --git a/docs/tutorials/contributing/guidelines.rst b/docs/tutorials/contributing/guidelines.rst new file mode 100644 index 000000000..02aa6b84b --- /dev/null +++ b/docs/tutorials/contributing/guidelines.rst @@ -0,0 +1,27 @@ +Guidelines +========== + +All contributions to this repository are welcome via pull request on the `github repository `_. + +The project follows the following guidelines: + +1. Use the base Python library unless completely necessary. A few external + libraries (such as numpy) have been included in requirements.txt -- feel free + to use these as needed. +2. If a non base Python library is deemed necessary, it should not hinder the + running or contribution of the package when using the base Python library. For + example, the `matplotlib library `_ is used in a + variety of classes to be able to show results, such as this one: This has been + done carefully with tests that are skipped if the library is not installed and + also without any crashes if something using the library was run. +3. Try as best as possible to follow `PEP8 + `_ which includes **using + descriptive variable names**. +4. Testing: the project uses the `unittest + `_ library and has a nice + testing suite that makes some things very easy to write tests for. Please try + to increase the test coverage on pull requests. +5. Merging pull-requests: We require two of the (currently four) core-team + maintainers to merge (and preferably not the submitted). Opening a PR for early + feedback or to check test coverage is OK, just indicate that the PR is not ready + to merge (and update when it is). diff --git a/docs/tutorials/contributing/index.rst b/docs/tutorials/contributing/index.rst new file mode 100644 index 000000000..603a8d37a --- /dev/null +++ b/docs/tutorials/contributing/index.rst @@ -0,0 +1,18 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Contributing +============ + +This section contains a variety of tutorials that should help you contribute to +the library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + guidelines.rst + instructions.rst diff --git a/docs/tutorials/contributing/instructions.rst b/docs/tutorials/contributing/instructions.rst new file mode 100644 index 000000000..6209befa1 --- /dev/null +++ b/docs/tutorials/contributing/instructions.rst @@ -0,0 +1,49 @@ +Instructions +============ + +Here is the file structure for the Axelrod repository:: + + . + ├── axelrod + │ └── __init__.py + │ └── ecosystem.py + │ └── game.py + │ └── player.py + │ └── plot.py + │ └── result_set.py + │ └── round_robin.py + │ └── tournament.py + │ └── /strategies/ + │ └── __init__.py + │ └── _strategies.py + │ └── cooperator.py + │ └── defector.py + │ └── grudger.py + │ └── titfortat.py + │ └── gobymajority.py + │ └── ... + │ └── /tests/ + │ └── functional + │ └── unit + │ └── test_*.py + └── README.md + +To contribute a strategy you need to follow as many of the following steps as possible: + +1. Fork the `github repository `_. +2. Add a :code:`.py` file to the strategies directory. (Take a look + at the others in there: you need to write code for the strategy and one other + simple thing.) +3. Update the :code:`./axelrod/strategies/_strategies.py` file (you need to + write the import statement and add the strategy to the relevant python list). +4. Update :code:`./axelrod/docs/overview_of_strategies.rst` with a description + of what the strategy does and include an example of it working. If relevant + please also add a source for the strategy (if it is not an original one). +5. This one is optional: write some unit tests in the ./axelrod/tests/ directory. +6. This one is also optional: ping us a message and we'll add you to the + Contributors team. This would add an Axelrod-Python organisation badge to + your profile. +7. Send us a pull request. + +**If you would like a hand with any of the above please do get in touch: we're +always delight to have new strategies.** From 01550301c1931438faf7a0ff515ff28b84c84b0f Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:50:30 +0100 Subject: [PATCH 19/82] Creating empty advanced topics. --- docs/tutorials/advanced/index.rst | 10 ++++++++++ docs/tutorials/index.rst | 2 ++ 2 files changed, 12 insertions(+) create mode 100644 docs/tutorials/advanced/index.rst diff --git a/docs/tutorials/advanced/index.rst b/docs/tutorials/advanced/index.rst new file mode 100644 index 000000000..ddfd52de6 --- /dev/null +++ b/docs/tutorials/advanced/index.rst @@ -0,0 +1,10 @@ +Advanced +======== + +This is a section aiming to showcase some problems solved and/or insights gained +using the Axelrod library. Please be the first to submit such a tutorial! + +Contents: + +.. toctree:: + :maxdepth: 2 diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index c0e7993a5..30c72c8c5 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -15,6 +15,8 @@ Contents: getting_started/index.rst further_topics/index.rst + advanced/index.rst + contributing/index.rst Indices and tables ================== From 488ee8d23cfa5b4ee404d9f206419d8593b63598 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 22:25:14 +0100 Subject: [PATCH 20/82] Refresh of overview of strategies: now doctested. --- docs/index.rst | 1 + docs/reference/index.rst | 19 + docs/reference/index_of_strategies.rst | 90 ---- docs/reference/overview_of_strategies.rst | 543 +++++++++------------- doctest | 1 + 5 files changed, 235 insertions(+), 419 deletions(-) create mode 100644 docs/reference/index.rst delete mode 100644 docs/reference/index_of_strategies.rst diff --git a/docs/index.rst b/docs/index.rst index e6e9c2ed5..58698af74 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ Welcome to the documentation for the Axelrod Python library :maxdepth: 2 tutorials/index.rst + reference/index.rst Indices and tables diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 000000000..d7b408eb8 --- /dev/null +++ b/docs/reference/index.rst @@ -0,0 +1,19 @@ +Reference +========= + +This section is the reference guide for the various components of the library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + overview_of_strategies.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/reference/index_of_strategies.rst b/docs/reference/index_of_strategies.rst deleted file mode 100644 index 68e2d855f..000000000 --- a/docs/reference/index_of_strategies.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. currentmodule:: axelrod.strategies -Index of strategies -=================== - -Basic strategies ----------------- - -.. autoclass:: Alternator -.. autoclass:: Cooperator -.. autoclass:: Defector -.. autoclass:: Random -.. autoclass:: TitForTat - -Further (honest) Strategies ---------------------------- - -.. autoclass:: AlternatorHunter -.. autoclass:: Appeaser -.. autoclass:: AntiTitForTat -.. autoclass:: ArrogantQLearner -.. autoclass:: AverageCopier -.. autoclass:: Bully -.. autoclass:: CautiousQLearner -.. autoclass:: CooperatorHunter -.. autoclass:: Davis -.. autoclass:: DefectorHunter -.. autoclass:: e -.. autoclass:: Feld -.. autoclass:: FoolMeOnce -.. autoclass:: ForgetfulFoolMeOnce -.. autoclass:: ForgetfulGrudger -.. autoclass:: Forgiver -.. autoclass:: ForgivingTitForTat -.. autoclass:: GTFT -.. autoclass:: GoByMajority -.. autoclass:: GoByMajority10 -.. autoclass:: GoByMajority20 -.. autoclass:: GoByMajority40 -.. autoclass:: GoByMajority5 -.. autoclass:: Golden -.. autoclass:: Grofman -.. autoclass:: Grudger -.. autoclass:: Grumpy -.. autoclass:: HesitantQLearner -.. autoclass:: Inverse -.. autoclass:: InversePunisher -.. autoclass:: Joss -.. autoclass:: LimitedRetaliate -.. autoclass:: LimitedRetaliate2 -.. autoclass:: LimitedRetaliate3 -.. autoclass:: MathConstantHunter -.. autoclass:: MetaHunter -.. autoclass:: MetaMajority -.. autoclass:: MetaMinority -.. autoclass:: MetaWinner -.. autoclass:: NiceAverageCopier -.. autoclass:: OnceBitten -.. autoclass:: OppositeGrudger -.. autoclass:: Pi -.. autoclass:: Punisher -.. autoclass:: RandomHunter -.. autoclass:: Retaliate -.. autoclass:: Retaliate2 -.. autoclass:: Retaliate3 -.. autoclass:: RiskyQLearner -.. autoclass:: Shubik -.. autoclass:: SneakyTitForTat -.. autoclass:: StochasticWSLS -.. autoclass:: SuspiciousTitForTat -.. autoclass:: TitFor2Tats -.. autoclass:: TrickyCooperator -.. autoclass:: TrickyDefector -.. autoclass:: Tullock -.. autoclass:: TwoTitsForTat -.. autoclass:: WinStayLoseShift -.. autoclass:: ZDExtort2 -.. autoclass:: ZDGTFT2 - -Cheating strategies -------------------- - -.. autoclass:: Darwin -.. autoclass:: Geller -.. autoclass:: GellerCooperator -.. autoclass:: GellerDefector -.. autoclass:: MindBender -.. autoclass:: MindController -.. autoclass:: MindReader -.. autoclass:: MindWarper -.. autoclass:: ProtectedMindReader diff --git a/docs/reference/overview_of_strategies.rst b/docs/reference/overview_of_strategies.rst index 9d3a4fb10..539026208 100644 --- a/docs/reference/overview_of_strategies.rst +++ b/docs/reference/overview_of_strategies.rst @@ -64,29 +64,22 @@ Implementation Here is a quick implementation of this in the library:: - import axelrod - p1 = axelrod.TitForTat() # Create a player that plays tit for tat - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.TitForTat() # Create a player that plays tit for tat + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['C', 'C', 'C', 'C', 'C'] We see that Tit for Tat cooperated every time, let us see how things change when it plays against a player that always defects:: - p1 = axelrod.TitForTat() # Create a player that plays tit for tat - p3 = axelrod.Defector() # Create a player that always defects - for round in range(5): - p1.play(p3) - print p1.history - -which gives:: - + >>> p1 = axelrod.TitForTat() # Create a player that plays tit for tat + >>> p3 = axelrod.Defector() # Create a player that always defects + >>> for round in range(5): + ... p1.play(p3) + >>> p1.history ['C', 'D', 'D', 'D', 'D'] We see that after cooperating once, Tit For Tat defects at every step. @@ -151,8 +144,10 @@ Finally this strategy defects if and only if: Grofman ^^^^^^^ -This is a pretty simple strategy: it cooperates with probability :math:`\frac{2}{7}`. In contemporary terminology, this is a memory-one player -with all four conditional probabilities of cooperation equal to :math:`\frac{2}{7}`. +This is a pretty simple strategy: it cooperates with probability +:math:`\frac{2}{7}`. In contemporary terminology, this is a memory-one player +with all four conditional probabilities of cooperation equal to +:math:`\frac{2}{7}`. *This strategy came 4th in Axelrod's original tournament.* @@ -161,34 +156,14 @@ Implementation Here is how Grofman is implemented in the library:: - import axelrod - p1 = axelrod.Grofman() # Create a Grofman player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Grofman() # Create a Grofman player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'D', 'D'] -Over a longer number of rounds:: - - from collections import Counter - for round in range(5): - p1.play(p2) - counter = Counter(p1.history) - print(counter) - Counter({'D': 367, 'C': 138}) - print float(counter['C']) / (counter['C'] + counter['D']) - print 2./7 - -We have that Grofman cooperates roughly in :math:`\frac{2}{7}`-ths of the rounds:: - - 0.2732673267326733 # Grofman - 0.2857142857142857 # 2./7 - Shubik ^^^^^^ @@ -203,18 +178,14 @@ Implementation Here is how Shubik is implemented in the library:: - import axelrod - p1 = axelrod.Shubik() # Create a Shubik player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(13): - p1.play(p2) - - print p1.history - print p2.history - -This yields the following history of play:: - + >>> import axelrod + >>> p1 = axelrod.Shubik() # Create a Shubik player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(13): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'D', 'C', 'D', 'D', 'D', 'C', 'C', 'C', 'D', 'D', 'D', 'C'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'C', 'D', 'C', 'C', 'C', 'D', 'C', 'C', 'C', 'D'] The increasing retaliation periods are visible in the output. Note that @@ -248,19 +219,15 @@ Implementation Here is how this is implemented in the library:: - import axelrod - p1 = axelrod.Grudger() # Create a player that grudger - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for the random seed used):: - - ['C', 'C', 'D', 'D', 'D'] - ['C', 'D', 'C', 'D', 'D'] + >>> import axelrod + >>> p1 = axelrod.Grudger() # Create a player that grudger + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP + ['C', 'C', 'D', 'D', 'D'] + >>> p2.history # doctest: +SKIP + ['C', 'D', 'C', 'D', 'D'] We see that as soon as :code:`p2` defected :code:`p1` defected for the rest of the play. @@ -278,19 +245,14 @@ Implementation Davis is implemented as follows:: - import axelrod - p1 = axelrod.Davis() # Create a Davis player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(15): - p1.play(p2) - - print p1.history - print p2.history - -This always produces (at least) 10 rounds of attempted cooperation followed by -Grudger:: - + >>> import axelrod + >>> p1 = axelrod.Davis() # Create a Davis player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(15): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'D', 'D', 'D', 'D', 'D'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'D', 'C', 'D', 'D', 'C', 'D', 'C', 'D', 'D', 'C', 'C', 'D'] Graaskamp @@ -341,18 +303,14 @@ Implementation Feld is implemented in the library as follows:: - import axelrod - p1 = axelrod.Feld() # Create a Feld player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(10): - p1.play(p2) - - print p1.history - print p2.history - -We can see from the output that Feld defects when its opponent does:: - + >>> import axelrod + >>> p1 = axelrod.Feld() # Create a Feld player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(10): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'D', 'C', 'D', 'D', 'D', 'D', 'C', 'D', 'D'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'D', 'D', 'D', 'C', 'D', 'D', 'D'] The defection times lengthen each time the opponent defects when Feld @@ -372,18 +330,14 @@ Implementation This is a memory-one strategy with four-vector :math:`(0.9, 0, 1, 0)`. Here is how Joss is implemented in the library:: - import axelrod - p1 = axelrod.Joss() # Create a Joss player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(10): - p1.play(p2) - - print p1.history - print p2.history - -This gives:: - + >>> import axelrod + >>> p1 = axelrod.Joss() # Create a Joss player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(10): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'D', 'C', 'D', 'C', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP ['C', 'C', 'D', 'C', 'D', 'C', 'C', 'C', 'C', 'D'] Which is the same as Tit-For-Tat for these 10 rounds. @@ -401,18 +355,14 @@ Implementation Tullock is implemented in the library as follows:: - import axelrod - p1 = axelrod.Tullock() # Create a Tullock player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(15): - p1.play(p2) - - print p1.history - print p2.history - -This gives:: - + >>> import axelrod + >>> p1 = axelrod.Tullock() # Create a Tullock player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(15): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'D', 'D', 'C', 'D'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'C', 'D', 'D', 'C', 'C', 'D', 'D', 'D', 'C', 'D', 'C', 'D', 'C'] We have 10 rounds of cooperation and some apparently random plays afterward. @@ -445,19 +395,15 @@ Implementation Here is how this is implemented in the library:: - import axelrod - p1 = axelrod.Random() # Create a player that plays randomly - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for the random seed used):: - - ['D', 'D', 'C', 'C', 'C'] - ['D', 'C', 'D', 'D', 'C'] + >>> import axelrod + >>> p1 = axelrod.Random() # Create a player that plays randomly + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP + ['D', 'D', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP + ['D', 'C', 'D', 'D', 'C'] Axelrod's second tournament --------------------------- @@ -479,21 +425,17 @@ Implementation Here is how Eatherley is implemented in the library:: - import axelrod - p1 = axelrod.Eatherley() # Create a Eatherley player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for a particular random seed):: + >>> import axelrod + >>> p1 = axelrod.Eatherley() # Create a Eatherley player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'D', 'C'] + >>> p2.history # doctest: +SKIP ['C', 'D', 'D', 'C', 'C'] - CHAMPION ^^^^^^^^ @@ -511,21 +453,16 @@ Implementation Here is how Champion is implemented in the library:: - import axelrod - p1 = axelrod.Champion() # Create a Champion player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for a particular random seed):: - + >>> import axelrod + >>> p1 = axelrod.Champion() # Create a Champion player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'D', 'C'] - TESTER ^^^^^^ @@ -541,22 +478,16 @@ Implementation Here is how this is implemented in the library:: - import axelrod - p1 = axelrod.Tester() # Create a Tester player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for a particular random seed):: - + >>> import axelrod + >>> p1 = axelrod.Tester() # Create a Tester player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['D', 'C', 'C', 'D', 'D'] + >>> p2.history # doctest: +SKIP ['C', 'D', 'D', 'D', 'C'] - - Stewart and Plotkin's Tournament (2012) --------------------------------------- @@ -650,17 +581,13 @@ Implementation Here is a quick implementation of this in the library:: - import axelrod - p1 = axelrod.GTFT() # Create a player that plays GTFT - p2 = axelrod.Defector() # Create a player that always defects - for round in range(10): - p1.play(p2) - - print p1.history - -this gives (for the random seed used):: - - ['C', 'D', 'D', 'C', 'D', 'D', 'D', 'D', 'D', 'D'] + >>> import axelrod + >>> p1 = axelrod.GTFT() # Create a player that plays GTFT + >>> p2 = axelrod.Defector() # Create a player that always defects + >>> for round in range(10): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP + ['C', 'D', 'D', 'C', 'D', 'D', 'D', 'D', 'D', 'D'] which shows that :code:`GTFT` tried to forgive :code:`Defector`. @@ -677,17 +604,13 @@ Implementation Here is the implementation of this in the library:: - import axelrod - p1 = axelrod.TitFor2Tats() # Create a player that plays TF2T - p2 = axelrod.Defector() # Create a player that always defects - for round in range(3): - p1.play(p2) - - print p1.history - -which gives:: - - ['C', 'C', 'D'] + >>> import axelrod + >>> p1 = axelrod.TitFor2Tats() # Create a player that plays TF2T + >>> p2 = axelrod.Defector() # Create a player that always defects + >>> for round in range(3): + ... p1.play(p2) + >>> p1.history + ['C', 'C', 'D'] we see that it takes 2 defections to trigger a defection by :code:`TitFor2Tats`. @@ -710,17 +633,13 @@ Implementation Here is a quick implementation of this in the library:: - import axelrod - p1 = axelrod.WinStayLoseShift() # Create a player that plays WSLS - p2 = axelrod.Alternator() # Create a player that alternates - for round in range(5): - p1.play(p2) - - print p1.history - -this gives:: - - ['C', 'C', 'D', 'D', 'C'] + >>> import axelrod + >>> p1 = axelrod.WinStayLoseShift() # Create a player that plays WSLS + >>> p2 = axelrod.Alternator() # Create a player that alternates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history + ['C', 'C', 'D', 'D', 'C'] which shows that :code:`WSLS` will choose the strategy that was a best response in the previous round. @@ -755,18 +674,14 @@ Implementation Here is how ZDGTFT-2 is implemented in the library:: - import axelrod - p1 = axelrod.ZDGTFT2() # Create a ZDGTFT-2 player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for the particular random seed used):: - + >>> import axelrod + >>> p1 = axelrod.ZDGTFT2() # Create a ZDGTFT-2 player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'D', 'D', 'C', 'C', 'D', 'C', 'D', 'D', 'D'] + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'D', 'C', 'C', 'D', 'C', 'D', 'D'] looking closely (and repeating the above) will show that the above @@ -790,18 +705,14 @@ Implementation Here is how EXTORT-2 is implemented in the library:: - import axelrod - p1 = axelrod.ZDExtort2() # Create a EXTORT-2 player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(10): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for the particular seed used):: - + >>> import axelrod + >>> p1 = axelrod.ZDExtort2() # Create a EXTORT-2 player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(10): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'C', 'C', 'C', 'D', 'D', 'D', 'D', 'C', 'D'] + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'C', 'C', 'D', 'D', 'D', 'D', 'D'] you can see that :code:`ZDExtort2` never cooperates after both strategies defect. @@ -821,16 +732,12 @@ Implementation Here is how GRIM is implemented in the library:: - import axelrod - p1 = axelrod.Grudger() # Create a GRIM player - p2 = axelrod.Defector() # Create a player that always defects - for round in range(5): - p1.play(p2) - - print p1.history - -this gives:: - + >>> import axelrod + >>> p1 = axelrod.Grudger() # Create a GRIM player + >>> p2 = axelrod.Defector() # Create a player that always defects + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['C', 'D', 'D', 'D', 'D'] HARD_JOSS @@ -867,22 +774,18 @@ Implementation HARD_MAJO is implemented in the library:: - import axelrod - p1 = axelrod.GoByMajority() # Create a HARD_TFT player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for this seed):: - - + >>> import axelrod + >>> p1 = axelrod.GoByMajority() # Create a HARD_TFT player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'C', 'C', 'D', 'D'] + >>> p1.history # doctest: +SKIP ['C', 'D', 'C', 'C', 'C'] -we see that following the third round (at which point the opponent has cooperated a lot), :code:`GoByMajority` cooperates. +we see that following the third round (at which point the opponent has +cooperated a lot), :code:`GoByMajority` cooperates. HARD_TFT ^^^^^^^^ @@ -900,20 +803,16 @@ Implementation HARD_TFT is implemented in the library:: - import axelrod - p1 = axelrod.HardTitForTat() # Create a HARD_TFT player - p2 = axelrod.Alternator() # Create a player that alternates - for round in range(5): - p1.play(p2) - - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.HardTitForTat() # Create a HARD_TFT player + >>> p2 = axelrod.Alternator() # Create a player that alternates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['C', 'C', 'D', 'D', 'D'] we see that :code:`HardTitForTat` cooperates for the first two moves but then -constantly defetcts as there is always a defection in it's opponent's recent +constantly defects as there is always a defection in it's opponent's recent history. HARD_TF2T @@ -931,18 +830,15 @@ Implementation HARD_TF2T is implemented in the library:: - import axelrod - p1 = axelrod.HardTitFor2Tats() # Create a HARD_TF2T player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for this particular seed):: + >>> import axelrod + >>> p1 = axelrod.HardTitFor2Tats() # Create a HARD_TF2T player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'D', 'C', 'D', 'C'] + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'D', 'C'] we see that :code:`HardTitFor2Tats` waited for 2 defects before defecting, but @@ -958,20 +854,16 @@ Calculator attempts to detect a cycle in the opponents history, and defects unconditionally thereafter if a cycle is found. Otherwise Calculator plays like TFT for the remaining rounds. -Calculator is implemented in the library as follows: - - import axelrod - p1 = axelrod.Calculator() # Create a HARD_TF2T player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -This returns (for a particular random seed):: +Calculator is implemented in the library as follows:: + >>> import axelrod + >>> p1 = axelrod.Calculator() # Create a HARD_TF2T player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C'] Prober @@ -989,18 +881,14 @@ Implementation Prober is implemented in the library:: - import axelrod - p1 = axelrod.Prober() # Create a Prober player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Prober() # Create a Prober player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'C', 'C', 'D', 'D'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] Prober2 @@ -1018,18 +906,14 @@ Implementation Prober2 is implemented in the library:: - import axelrod - p1 = axelrod.Prober2() # Create a Prober2 player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Prober2() # Create a Prober2 player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'C', 'C', 'C', 'C'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] Prober3 @@ -1047,18 +931,14 @@ Implementation Prober3 is implemented in the library:: - import axelrod - p1 = axelrod.Prober3() # Create a Prober3 player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Prober3() # Create a Prober3 player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'C', 'D', 'D', 'D'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] HardProber @@ -1076,58 +956,63 @@ Implementation HardProber is implemented in the library:: - import axelrod - p1 = axelrod.HardProber() # Create a Prober3 player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: + >>> import axelrod + >>> p1 = axelrod.HardProber() # Create a Prober3 player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'D', 'C', 'C', 'D'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] Strategies implemented in the module ------------------------------------ -There are several original strategies which have been created as part of this project and have never (to our knowledge) appeared in previous tournaments. +There are several original strategies which have been created as part of this +project and have never (to our knowledge) appeared in previous tournaments. Fool Me Once -^^^^^^^^^^^ +^^^^^^^^^^^^ -This strategy begins by cooperating but will defect if at any point the opponent has defected more than once. +This strategy begins by cooperating but will defect if at any point the opponent +has defected more than once. Forgetful Fool Me Once ^^^^^^^^^^^^^^^^^^^^^^ -Like Fool Me Once, this strategy defects if the opponent ever defects, but sometimes -forgets that the opponent had defected, cooperating again until another defection. +Like Fool Me Once, this strategy defects if the opponent ever defects, but +sometimes forgets that the opponent had defected, cooperating again until +another defection. Fool Me Forever ^^^^^^^^^^^^^^^ -This strategy defects until the opponent defects, and then cooperates there after. -Note that this strategy is different than opposite grudger, which cooperates -indefinitely after an opponent cooperation. +This strategy defects until the opponent defects, and then cooperates there +after. Note that this strategy is different than opposite grudger, which +cooperates indefinitely after an opponent cooperation. Backstabber ^^^^^^^^^^^ -Forgives the first 3 defections but on the fourth will defect forever. Defects after the 198th round unconditionally. +Forgives the first 3 defections but on the fourth will defect forever. Defects +after the 198th round unconditionally. DoubleCrosser ^^^^^^^^^^^^^ -Forgives the first 3 defections but on the fourth will defect forever. If the opponent did not defect in the first 6 rounds the player will cooperate until the 180th round. Defects after the 198th round unconditionally. +Forgives the first 3 defections but on the fourth will defect forever. If the +opponent did not defect in the first 6 rounds the player will cooperate until +the 180th round. Defects after the 198th round unconditionally. Aggravater ^^^^^^^^^^ -This strategy begins by defecting 3 times and then will cooperate until the opponent defects. After the opponent defects it will defect unconditionally. Essentially Grudger, but begins by defecting 3 times. +This strategy begins by defecting 3 times and then will cooperate until the +opponent defects. After the opponent defects it will defect unconditionally. +Essentially Grudger, but begins by defecting 3 times. Alternator ^^^^^^^^^^ diff --git a/doctest b/doctest index 30142ba09..7def29b5f 100755 --- a/doctest +++ b/doctest @@ -1,3 +1,4 @@ #!/usr/bin/env bash python -m doctest docs/tutorials/getting_started/*rst python -m doctest docs/tutorials/further_topics/*rst +python -m doctest docs/reference/*rst From 737d5f37c70dd1bb34dc7b5d35ea79cc503f5cf1 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 22:40:20 +0100 Subject: [PATCH 21/82] Adding tutorial on classification --- .../classification_of_strategies.rst | 42 +++++++++++++++++++ docs/tutorials/further_topics/index.rst | 6 +-- 2 files changed, 43 insertions(+), 5 deletions(-) create mode 100644 docs/tutorials/further_topics/classification_of_strategies.rst diff --git a/docs/tutorials/further_topics/classification_of_strategies.rst b/docs/tutorials/further_topics/classification_of_strategies.rst new file mode 100644 index 000000000..741eb14c7 --- /dev/null +++ b/docs/tutorials/further_topics/classification_of_strategies.rst @@ -0,0 +1,42 @@ +Classification of strategies +============================ + +Due to the large number of strategies, every class and instance of the class has +a :code:`classifier` attribute which classifies that strategy according to +various dimensions. + +Here is the :code:`classifier` for the :code:`Cooperator` strategy:: + + >>> import axelrod as axl + >>> expected_dictionary = {'manipulates_state': False, 'stochastic': False, 'manipulates_source': False, 'inspects_source': False, 'memory_depth': 0} # Order of this dictionary might be different on your machine + >>> axl.Cooperator.classifier == expected_dictionary + True + +Note that instances of the class also have this classifier:: + + >>> s = axl.Cooperator() + >>> s.classifier == expected_dictionary + True + +This allows us to, for example, quickly identify all the stochastic +strategies:: + + >>> len([s for s in axl.strategies if s().classifier['stochastic']]) + 31 + +Or indeed find out how many strategy have only use 1 turn worth of memory to +make a decision: + + >>> len([s for s in axl.strategies if s().classifier['memory_depth']==1]) + 15 + +Similarly, strategies that :code:`manipulate_source`, :code:`manipulate_state` +and/or :code:`inspect_source` return :code:`False` for the :code:`obey_axelrod` +function:: + + >>> s = axl.MindBender() + >>> axl.obey_axelrod(s) + False + >>> s = axl.TitForTat() + >>> axl.obey_axelrod(s) + True diff --git a/docs/tutorials/further_topics/index.rst b/docs/tutorials/further_topics/index.rst index ed5ee3b78..e60957f58 100644 --- a/docs/tutorials/further_topics/index.rst +++ b/docs/tutorials/further_topics/index.rst @@ -1,8 +1,3 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Further Topics ============== @@ -14,4 +9,5 @@ Contents: .. toctree:: :maxdepth: 2 + classification_of_strategies.rst morality_metrics.rst From 46fbb7b4078a21e229f2d072bf36c960fb736146 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 22:42:24 +0100 Subject: [PATCH 22/82] Removing indices. --- docs/reference/index.rst | 8 -------- docs/tutorials/index.rst | 8 -------- 2 files changed, 16 deletions(-) diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d7b408eb8..d8a3ff51b 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,11 +9,3 @@ Contents: :maxdepth: 2 overview_of_strategies.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 30c72c8c5..7dce1e7b2 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -17,11 +17,3 @@ Contents: further_topics/index.rst advanced/index.rst contributing/index.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - From ab32b890a562c03dbc668f0206b7c4dff1b96d3a Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 22:51:53 +0100 Subject: [PATCH 23/82] Removing merge conflict tag from travis file. --- .travis.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 5f6d79d81..c648d74d0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -22,6 +22,5 @@ script: - coverage report -m # Run the doctests - sh doctest ->>>>>>> master after_success: - coveralls From 570c236ab87c25b0af010134c9263dc7b0477393 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Mon, 19 Oct 2015 08:35:22 +0100 Subject: [PATCH 24/82] Adding glossary. --- docs/reference/glossary.rst | 56 +++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 2 files changed, 57 insertions(+) create mode 100644 docs/reference/glossary.rst diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst new file mode 100644 index 000000000..78f51e783 --- /dev/null +++ b/docs/reference/glossary.rst @@ -0,0 +1,56 @@ +Glossary +======== + +There are a variety of terms used in the documentation and throughout the +library. Here is an overview: + +An action +--------- + +An **action** is either :code:`C` or :code:`D`. +You can access these actions as follows but should not really have a reason to:: + + >>> import axelrod as axl + >>> axl.Actions.C + 'C' + >>> axl.Actions.D + 'D' + +A play +------ + +A **play** is a single player choosing an **action**. +In terms of code this is equivalent to:: + + >>> p1, p2 = axl.Cooperator(), axl.Defector() + >>> p1.play(p2) # This constitues two 'plays' (p1 plays and p2 plays). + +A turn +------ + +A **turn** is a 1 shot interaction between two players. It is in effect a +composition of two **plays**. + +A match +------- + +A **match** is a consecutive number of **turns**. The default number of turns +used in the tournament is 200. Here is a single match between two players over +10 turns:: + + >>> p1, p2 = axl.Cooperator(), axl.Defector() + >>> for turn in range(10): + ... p1.play(p2) + >>> p1.history, p2.history + (['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C'], ['D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D']) + +A round robin +------------- + +A **round robin** is the set of all potential (order invariant) matches between +a given collection of players. + +A tournament +------------ + +A **tournament** is a repetition of round robins so as to smooth out stochastic effects. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d8a3ff51b..a67deacd3 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,3 +9,4 @@ Contents: :maxdepth: 2 overview_of_strategies.rst + glossary.rst From b2196cbf721e527197b79276f575966a56de3444 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 20:07:06 +0100 Subject: [PATCH 25/82] Adding the suggestions from Marc - play(p1) equivalent to play(p2) - Outcomes of a turn --- docs/reference/glossary.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 78f51e783..3c0231bff 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -25,12 +25,18 @@ In terms of code this is equivalent to:: >>> p1, p2 = axl.Cooperator(), axl.Defector() >>> p1.play(p2) # This constitues two 'plays' (p1 plays and p2 plays). +This is equivalent to :code:`p2.play(p1)`. Either function invokes both +:code:`p1.strategy(p2)` and :code:`p2.strategy(p1)`. + A turn ------ A **turn** is a 1 shot interaction between two players. It is in effect a composition of two **plays**. +Each turn has four possible outcomes of a play: :code:`(C, C)`, :code:`(C, D)`, +:code:`(D, C)`, or :code:`(D, D)`. + A match ------- From 86f72a41d4767cb025fb77d8210caff28a9573d0 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 22:00:24 +0100 Subject: [PATCH 26/82] Adding section about the command line tool. Also minor tidying of other files. --- .../getting_started/command_line.rst | 45 +++++++++++++++++++ docs/tutorials/getting_started/index.rst | 6 +-- .../getting_started/visualising_results.rst | 2 - 3 files changed, 46 insertions(+), 7 deletions(-) create mode 100644 docs/tutorials/getting_started/command_line.rst diff --git a/docs/tutorials/getting_started/command_line.rst b/docs/tutorials/getting_started/command_line.rst new file mode 100644 index 000000000..a068cc6eb --- /dev/null +++ b/docs/tutorials/getting_started/command_line.rst @@ -0,0 +1,45 @@ +Using the command line tool +=========================== + +Once :code:`axelrod` is installed you have access to a `run_axelrod` script that +can help run some of the tournaments, include the tournament that involves all +of the strategies from the library. You can view them on this repository: +`https://github.com/Axelrod-Python/tournament/`_ + +To view the help for the :code:`run_axelrod` file run:: + + $ run_axelrod.py -h + +Note that if you have not installed the package you can still used this script +directly from the repository:: + + $ python run_axelrod -h + +There are a variety of options that include: + +- Excluding certain strategy sets. +- Not running the ecological variant. +- Running the rounds of the tournament in parallel. +- Include background noise + +Particular parameters can also be changed: + +- The output directory for the plot and csv files. +- The number of turns and repetitions for the tournament. + +Here is a command that will run the whole tournament, excluding the strategies +that do not obey Axelrod's original rules and using all available CPUS (this can +take quite a while!):: + + $ run_axelrod --xc -p 0 + +Here are some of the plots that are output when running with the latest total number of strategies: + +The results from the tournament itself (ordered by median score): + +.. image:: http://axelrod-python.github.io/tournament/assets/strategies_boxplot.svg + :width: 50% + :align: center + +This is just a brief overview of what the tool can do, take a look at the help +to see all the options. diff --git a/docs/tutorials/getting_started/index.rst b/docs/tutorials/getting_started/index.rst index b02ad4e02..99cffd34c 100644 --- a/docs/tutorials/getting_started/index.rst +++ b/docs/tutorials/getting_started/index.rst @@ -1,8 +1,3 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Getting Started =============== @@ -19,3 +14,4 @@ Contents: visualising_results.rst noisy_tournaments.rst ecological_variant.rst + command_line.rst diff --git a/docs/tutorials/getting_started/visualising_results.rst b/docs/tutorials/getting_started/visualising_results.rst index afa194a09..26c26629c 100644 --- a/docs/tutorials/getting_started/visualising_results.rst +++ b/docs/tutorials/getting_started/visualising_results.rst @@ -1,8 +1,6 @@ Visualising results =================== -lipsum - This tutorial will show you briefly how to visualise some basic results Visualising the results of the tournament From d165b6706cf67a009dc97cc61095913819c57ecb Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 22:21:17 +0100 Subject: [PATCH 27/82] Tidying of the tutorials structure. --- docs/tutorials/contributing/index.rst | 3 ++- docs/tutorials/contributing/library/index.rst | 15 +++++++++++++++ docs/tutorials/contributing/strategy/index.rst | 17 +++++++++++++++++ .../{ => strategy}/instructions.rst | 2 +- 4 files changed, 35 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/contributing/library/index.rst create mode 100644 docs/tutorials/contributing/strategy/index.rst rename docs/tutorials/contributing/{ => strategy}/instructions.rst (97%) diff --git a/docs/tutorials/contributing/index.rst b/docs/tutorials/contributing/index.rst index 603a8d37a..c7d845a84 100644 --- a/docs/tutorials/contributing/index.rst +++ b/docs/tutorials/contributing/index.rst @@ -15,4 +15,5 @@ Contents: :maxdepth: 2 guidelines.rst - instructions.rst + strategy/index.rst + library/index.rst diff --git a/docs/tutorials/contributing/library/index.rst b/docs/tutorials/contributing/library/index.rst new file mode 100644 index 000000000..d71dcbe6a --- /dev/null +++ b/docs/tutorials/contributing/library/index.rst @@ -0,0 +1,15 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Contributing to the library +=========================== + +This section contains a variety of tutorials that should help you contribute to +the library. + +Contents: + +.. toctree:: + :maxdepth: 2 diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst new file mode 100644 index 000000000..ad697e519 --- /dev/null +++ b/docs/tutorials/contributing/strategy/index.rst @@ -0,0 +1,17 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Contributing a strategy +======================= + +This section contains a variety of tutorials that should help you contribute to +the library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + instructions.rst diff --git a/docs/tutorials/contributing/instructions.rst b/docs/tutorials/contributing/strategy/instructions.rst similarity index 97% rename from docs/tutorials/contributing/instructions.rst rename to docs/tutorials/contributing/strategy/instructions.rst index 6209befa1..a7a4d8c3f 100644 --- a/docs/tutorials/contributing/instructions.rst +++ b/docs/tutorials/contributing/strategy/instructions.rst @@ -46,4 +46,4 @@ To contribute a strategy you need to follow as many of the following steps as po 7. Send us a pull request. **If you would like a hand with any of the above please do get in touch: we're -always delight to have new strategies.** +always delighted to have new strategies.** From 92d3bf99de7008d7ede1c8d777bbc14e0293a1f9 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 22:23:52 +0100 Subject: [PATCH 28/82] Removing comment about matplotlib from guidelines. --- docs/tutorials/contributing/guidelines.rst | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/tutorials/contributing/guidelines.rst b/docs/tutorials/contributing/guidelines.rst index 02aa6b84b..30bf7ce79 100644 --- a/docs/tutorials/contributing/guidelines.rst +++ b/docs/tutorials/contributing/guidelines.rst @@ -8,20 +8,14 @@ The project follows the following guidelines: 1. Use the base Python library unless completely necessary. A few external libraries (such as numpy) have been included in requirements.txt -- feel free to use these as needed. -2. If a non base Python library is deemed necessary, it should not hinder the - running or contribution of the package when using the base Python library. For - example, the `matplotlib library `_ is used in a - variety of classes to be able to show results, such as this one: This has been - done carefully with tests that are skipped if the library is not installed and - also without any crashes if something using the library was run. -3. Try as best as possible to follow `PEP8 +2. Try as best as possible to follow `PEP8 `_ which includes **using descriptive variable names**. -4. Testing: the project uses the `unittest +3. Testing: the project uses the `unittest `_ library and has a nice testing suite that makes some things very easy to write tests for. Please try to increase the test coverage on pull requests. -5. Merging pull-requests: We require two of the (currently four) core-team +4. Merging pull-requests: We require two of the (currently four) core-team maintainers to merge (and preferably not the submitted). Opening a PR for early feedback or to check test coverage is OK, just indicate that the PR is not ready to merge (and update when it is). From 19e4f0cb297bd155bf3f85a478423f8d3f87479b Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 08:30:37 +0100 Subject: [PATCH 29/82] Code highlight for directory. --- docs/tutorials/contributing/strategy/instructions.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/contributing/strategy/instructions.rst b/docs/tutorials/contributing/strategy/instructions.rst index a7a4d8c3f..27a11ed17 100644 --- a/docs/tutorials/contributing/strategy/instructions.rst +++ b/docs/tutorials/contributing/strategy/instructions.rst @@ -39,7 +39,8 @@ To contribute a strategy you need to follow as many of the following steps as po 4. Update :code:`./axelrod/docs/overview_of_strategies.rst` with a description of what the strategy does and include an example of it working. If relevant please also add a source for the strategy (if it is not an original one). -5. This one is optional: write some unit tests in the ./axelrod/tests/ directory. +5. This one is optional: write some unit tests in the :code:`./axelrod/tests/` + directory. 6. This one is also optional: ping us a message and we'll add you to the Contributors team. This would add an Axelrod-Python organisation badge to your profile. From 8def6fbdd5bdd59b0d39fbf0b574708b2c20e503 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 14:58:36 +0100 Subject: [PATCH 30/82] Section on writing strategies - Including a label in classification file. --- .../tutorials/contributing/strategy/index.rst | 1 + .../strategy/writing_the_new_strategy.rst | 112 ++++++++++++++++++ .../classification_of_strategies.rst | 2 + 3 files changed, 115 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/writing_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index ad697e519..2312d4578 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -15,3 +15,4 @@ Contents: :maxdepth: 2 instructions.rst + writing_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst new file mode 100644 index 000000000..131968b1c --- /dev/null +++ b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst @@ -0,0 +1,112 @@ +Writing the new strategy +======================== + +There are a couple of things that need to be created in a strategy.py file. Let +us take a look at the :code:`TitForTat` class (located in the +:code:`axelrod/strategies/titfortat.py` file):: + + class TitForTat(Player): + """ + A player starts by cooperating and then mimics previous move by + opponent. + + Note that the code for this strategy is written in a fairly verbose + way. This is done so that it can serve as an example strategy for + those who might be new to Python. + """ + + # These are various properties for the strategy + name = 'Tit For Tat' + classifier = { + 'memory_depth': 1, # Four-Vector = (1.,0.,1.,0.) + 'stochastic': False, + 'inspects_source': False, + 'manipulates_source': False, + 'manipulates_state': False + } + + def strategy(opponent): + """This is the actual strategy""" + # First move + if len(self.history) == 0: + return C + # React to the opponent's last move + if opponent.history[-1] == D: + return D + return C + +The first thing that is needed is a docstring that explains what the strategy +does:: + + """A player starts by cooperating and then mimics previous move by opponent.""" + +After that simply add in the string that will appear as the name of the +strategy:: + + name = 'Tit For Tat' + +Note that this is mainly used in plots by :code:`matplotlib` so you can use +LaTeX if you want to. For example there is strategy with :math:`\pi` as a +name:: + + name = '$\pi$' + +Following that you can add in the :code:`classifier` dictionary:: + + classifier = { + 'memory_depth': 1, # Four-Vector = (1.,0.,1.,0.) + 'stochastic': False, + 'inspects_source': False, + 'manipulates_source': False, + 'manipulates_state': False + } + +This helps classify the strategy as described in +:ref:`classification-of-strategies`. + +After that the only thing required is to write the :code:`strategy` method +which takes an opponent as an argument. In the case of :code:`TitForTat` the +strategy checks if it has any history (:code:`if len(self.history) == 0`). If +it does not (ie this is the first play of the match) then it returns :code:`C`. +If not, the strategy simply repeats the opponent's last move (:code:`return +opponent.history[-1]`):: + + def strategy(opponent): + """This is the actual strategy""" + # First move + if len(self.history) == 0: + return C + # Repeat the opponent's last move + return opponent.history[-1] + +The variables :code:`C` and :code:`D` represent the cooperate and defect actions respectively. + +If your strategy creates any particular attribute along the way you need to make +sure that there is a :code:`reset` method that takes account of it. An example +of this is the :code:`ForgetfulGrudger` strategy. + +You can also modify the name of the strategy with the `__repr__` method, which +is invoked when `str` is applied to a player instance. For example, the player +`Random` takes a parameter `p` for how often it cooperates, and the `__repr__` +method adds the value of this parameter to the name:: + + def __repr__(self): + return "%s: %s" % (self.name, round(self.p, 2)) + +Now we have separate names for different instantiations:: + + >>> import axelrod + >>> player1 = axelrod.Random(p=0.5) + >>> player2 = axelrod.Random(p=0.1) + >>> player1 + Random: 0.5 + >>> player2 + Random: 0.1 + +This helps distinguish players in tournaments that have multiple instances of the +same strategy. If you modify the `__repr__` method of player, be sure to add an +appropriate test. + +There are various examples of helpful functions and properties that make +writing strategies easier. Do not hesitate to get in touch with the +Axelrod-Python team for guidance. diff --git a/docs/tutorials/further_topics/classification_of_strategies.rst b/docs/tutorials/further_topics/classification_of_strategies.rst index 741eb14c7..b1f11aeca 100644 --- a/docs/tutorials/further_topics/classification_of_strategies.rst +++ b/docs/tutorials/further_topics/classification_of_strategies.rst @@ -1,3 +1,5 @@ +.. _classification-of-strategies: + Classification of strategies ============================ From 4e9c953325124b7f8d5515214843204459399503 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 15:12:44 +0100 Subject: [PATCH 31/82] Section on adding the strategy _strategies.py --- .../strategy/adding_the_new_strategy.rst | 22 +++++++++++++++++++ .../tutorials/contributing/strategy/index.rst | 1 + 2 files changed, 23 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/adding_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/adding_the_new_strategy.rst b/docs/tutorials/contributing/strategy/adding_the_new_strategy.rst new file mode 100644 index 000000000..782ed7556 --- /dev/null +++ b/docs/tutorials/contributing/strategy/adding_the_new_strategy.rst @@ -0,0 +1,22 @@ +Adding the new strategy +======================= + +To get the strategy to be recognised by the library we need to add it to the +files that initialise when someone types :code:`import axelrod`. This is done +in the :code:`axelrod/strategies/_strategies.py` file. + +If you have added your strategy to a file that already existed (perhaps you +added a new variant of :code:`titfortat` to the :code:`titfortat.py` file), +add a line similar to:: + + from import * + +Where :code:`file_name.py` is the name of the file you created. So for the +:code:`TitForTat` strategy which is written in the :code:`titfortat.py` file we +have:: + + from titfortat import * + +Once you have done that (**and you need to do this even if you have added a +strategy to an already existing file**), you need to add the class itself to +the :code:`strategies` list. diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index 2312d4578..e5d43149a 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -16,3 +16,4 @@ Contents: instructions.rst writing_the_new_strategy.rst + adding_the_new_strategy.rst From 8c72309398eaddde172218c02064777ad1257d2e Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 16:36:16 +0100 Subject: [PATCH 32/82] Section on classification. --- .../strategy/classifying_the_new_strategy.rst | 44 +++++++++++++++++++ .../tutorials/contributing/strategy/index.rst | 1 + 2 files changed, 45 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst new file mode 100644 index 000000000..87f86f691 --- /dev/null +++ b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst @@ -0,0 +1,44 @@ +Classifying the new strategy +============================ + +Every class has a classifier dictionary that gives some classification of the +strategy according to certain dimensions:: + +Let us take a look at :code:`TitForTat`:: + + >>> classifier = axelrod.TitForTat.classifier + >>> for key in classifier: + .... print key, classifier[key] + manipulates_state False + stochastic False + manipulates_source False + inspects_source False + memory_depth 1 + +You can read more about this in the :ref:`classification-of-strategies` section +but here are some tips about fill this part in correctly. + +Note that when an instance of a class is created it gets it's own copy of the +default classifier dictionary from the class. This might sometimes be modified by +the initialisation depending on input parameters. A good example of this is the +:code:`Joss` strategy:: + + >>> joss = axelrod.Joss() + >>> boring_joss = axelrod.Joss(1) + >>> joss.classifier['stochastic'], boring_joss.classifier['stochastic'] + (True, False) + +Dimensions that are not classified have value `None` in the dictionary. + +There are currently three important dimensions that help identify if a strategy +obeys axelrod's original tournament rules. + +1. :code:`inspects_source` - does the strategy 'read' any source code that + it would not normally have access to. An example of this is :code:`Geller`. +2. :code:`manipulates_source` - does the strategy 'write' any source code that + it would not normally be able to. An example of this is :code:`Mind Bender`. +3. :code:`manipulates_state` - does the strategy 'change' any attributes that + it would not normally be able to. An example of this is :code:`Mind Reader`. + +These dimensions are currently relevant to the `obey_axelrod` strategy which +checks if a strategy obeys Axelrod's original rules. diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index e5d43149a..4663c0f84 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -17,3 +17,4 @@ Contents: instructions.rst writing_the_new_strategy.rst adding_the_new_strategy.rst + classifying_the_new_strategy.rst From 2adcc5a7dc66af9e0c4d3687e63ff8ae8b15285c Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:19:25 +0100 Subject: [PATCH 33/82] Section on testing. --- .../tutorials/contributing/strategy/index.rst | 6 +- .../writing_test_for_the_new_strategy.rst | 131 ++++++++++++++++++ 2 files changed, 132 insertions(+), 5 deletions(-) create mode 100644 docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index 4663c0f84..f40bd3909 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -1,8 +1,3 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Contributing a strategy ======================= @@ -18,3 +13,4 @@ Contents: writing_the_new_strategy.rst adding_the_new_strategy.rst classifying_the_new_strategy.rst + writing_test_for_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst b/docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst new file mode 100644 index 000000000..93a14da8a --- /dev/null +++ b/docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst @@ -0,0 +1,131 @@ +Writing tests for the new strategy +================================== + +To write tests you either need to create a file called :code:`test_.py` +where :code:`.py` is the name of the file you have created or similarly +add tests to the test file that is already present in the +:code:`axelrod/tests/unit/` directory. + +As an example, the tests for Tit-For-Tat are as follows:: + + import axelrod + + from test_player import TestPlayer + + C, D = axelrod.Actions.C, axelrod.Actions.D + + class TestTitForTat(TestPlayer): + + name = "Tit For Tat" + player = axelrod.TitForTat + expected_classifier = { + 'memory_depth': 1, + 'stochastic': False, + 'inspects_source': False, + 'manipulates_source': False, + 'manipulates_state': False + } + + def test_strategy(self): + """Starts by cooperating.""" + P1 = axelrod.TitForTat() + P2 = axelrod.Player() + self.assertEqual(P1.strategy(P2), C) + + def test_effect_of_strategy(self): + """ + Repeats last action of opponent history + """ + P1 = axelrod.TitForTat() + P2 = axelrod.Player() + P2.history = [C, C, C, C] + self.assertEqual(P1.strategy(P2), C) + P2.history = [C, C, C, C, D] + self.assertEqual(P1.strategy(P2), D) + +The :code:`test_effect_of_strategy` method mainly checks that the +:code:`strategy` method in the :code:`TitForTat` class works as expected: + +1. If the opponent's last strategy was :code:`C`: then :code:`TitForTat` should + cooperate:: + + P2.history = ['C', 'C', 'C', 'C'] + self.assertEqual(P1.strategy(P2), 'C') + +2. If the opponent's last strategy was :code:`D`: then :code:`TitForTat` should + defect:: + + P2.history = ['C', 'C', 'C', 'C', 'D'] + self.assertEqual(P1.strategy(P2), 'D') + +We have added some convenience member functions to the :code:`TestPlayer` class. +All three of these functions can take an optional keyword argument +:code:`random_seed` (useful for stochastic strategies). + +1. The member function :code:`first_play_test` tests the first strategy, e.g.:: + + def test_strategy(self): + self.first_play_test('C') + + This is equivalent to:: + + def test_effect_of_strategy(self): + P1 = axelrod.TitForTat() # Or whatever player is in your test class + P2 = axelrod.Player() + P2.history = [] + P2.history = [] + self.assertEqual(P1.strategy(P2), 'C') + +2. The member function :code:`markov_test` takes a list of four plays, each + following one round of CC, CD, DC, and DD respectively:: + + def test_effect_of_strategy(self): + self.markov_test(['C', 'D', 'D', 'C']) + + This is equivalent to:: + + def test_effect_of_strategy(self): + P1 = axelrod.TitForTat() # Or whatever player is in your test class + P2 = axelrod.Player() + P2.history = ['C'] + P2.history = ['C'] + self.assertEqual(P1.strategy(P2), 'C') + P2.history = ['C'] + P2.history = ['D'] + self.assertEqual(P1.strategy(P2), 'D') + P2.history = ['D'] + P2.history = ['C'] + self.assertEqual(P1.strategy(P2), 'D') + P2.history = ['D'] + P2.history = ['D'] + self.assertEqual(P1.strategy(P2), 'C') + +3. The member function :code:`responses_test` takes arbitrary histories for each + player and tests a list of expected next responses:: + + def test_effect_of_strategy(self): + self.responses_test([C], [C], [D, C, C, C], random_seed=15) + + In this case each player has their history set to :code:`[C]` and the + expected responses are D, C, C, C. Note that the histories will elongate as + the responses accumulated. + +Finally, there is a :code:`TestHeadsUp` class that streamlines the testing of +two strategies playing each other using a test function :code:`versus_test`. For +example, to test several rounds of play of Tit-For-Two-Tats versus Bully:: + + class TestTF2TvsBully(TestHeadsUp): + """Test Tit for Two Tats vs Bully""" + def test_rounds(self): + outcomes = [[C, D], [C, D], [D, D], [D, C], [C, C], [C, D], [C, D], [D, D]] + self.versus_test(axelrod.TitFor2Tats, axelrod.Bully, outcomes) + +The function :code:`versus_test` also accepts a :code:`random_seed` keyword, and +like :code:`responses_test` the history is accumulated. + +The :code:`expected_classifier` dictionary tests that the classification of the +strategy is as expected (the tests for this is inherited in the :code:`init` +method). Please be sure to classify new strategies according to the already +present dimensions but if you create a new dimension you do not **need** to re +classify all the other strategies (but feel free to! :)), but please do add it +to the :code:`default_classifier` in the :code:`axelrod/player.py` parent class. From f4e0de50e7be55c451d05e065cda247a77f9c8eb Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:53:25 +0100 Subject: [PATCH 34/82] Adding section about identify new strategies. --- .../strategy/writing_the_new_strategy.rst | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst index 131968b1c..b525aece4 100644 --- a/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst +++ b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst @@ -1,6 +1,30 @@ Writing the new strategy ======================== +Identify a new strategy +----------------------- + +The library has a large number of strategies:: + + >>> import axelrod as axl + >>> len(axl.strategies) + 103 + +If you're not sure if you have a strategy that has already been implemented +please get in touch: `via the gitter room +`_ or `open an issue +`_. + +Several strategies are special cases of other strategies. For example, both +`Cooperator` and `Defector` are special cases of `Random`, `Random(1)` and +`Random(0)` respectively. While we could eliminate `Cooperator` in its current +form, these strategies are intentionally left as is as simple examples for new +users and contributors. Nevertheless, please feel free to update the docstrings +of strategies like `Random` to point out such cases. + +The code +-------- + There are a couple of things that need to be created in a strategy.py file. Let us take a look at the :code:`TitForTat` class (located in the :code:`axelrod/strategies/titfortat.py` file):: From a1ec90c872fb0ef2d134637790846e2843136e09 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:53:48 +0100 Subject: [PATCH 35/82] Adding section on tests. --- .../tutorials/contributing/strategy/index.rst | 1 + .../contributing/strategy/running_tests.rst | 30 +++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/running_tests.rst diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index f40bd3909..266097f18 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -14,3 +14,4 @@ Contents: adding_the_new_strategy.rst classifying_the_new_strategy.rst writing_test_for_the_new_strategy.rst + running_tests.rst diff --git a/docs/tutorials/contributing/strategy/running_tests.rst b/docs/tutorials/contributing/strategy/running_tests.rst new file mode 100644 index 000000000..936cb9e24 --- /dev/null +++ b/docs/tutorials/contributing/strategy/running_tests.rst @@ -0,0 +1,30 @@ +Running tests +============= + +The project has an extensive test suite which is run each time a new +contribution is made to the repository. If you want to check that all the tests +pass before you submit a pull request you can run the tests yourself:: + + $ python -m unittest discover + +If you are developing new tests for the suite, it is useful to run a single test +file so that you don't have to wait for the entire suite each time. For +example, to run only the tests for the Grudger strategy:: + + $ python -m unittest axelrod.tests.unit.test_grudger + +The test suite is divided into two categories: unit tests and integration tests. +Each can be run individually:: + + $ python -m unittest discover -s axelrod.tests.unit + $ python -m unittest discover -s axelrod.tests.integration + +Furthermore the documentation is also doctested, to run those tests you can run +the script:: + + $ sh doctest + +Note that this project is being taken care off by `travis-ci +`_, so all tests will be run automatically when opening +a pull request. You can see the latest build status `here +`_. From 1f1bfbd343769ab90f63bae91f0cc4fce44aa4b9 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:54:15 +0100 Subject: [PATCH 36/82] Fixing broken doctest. --- .../contributing/strategy/classifying_the_new_strategy.rst | 3 ++- doctest | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst index 87f86f691..10d4cba53 100644 --- a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst +++ b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst @@ -6,9 +6,10 @@ strategy according to certain dimensions:: Let us take a look at :code:`TitForTat`:: + >>> import axelrod >>> classifier = axelrod.TitForTat.classifier >>> for key in classifier: - .... print key, classifier[key] + ... print key, classifier[key] manipulates_state False stochastic False manipulates_source False diff --git a/doctest b/doctest index 7def29b5f..daea869e5 100755 --- a/doctest +++ b/doctest @@ -2,3 +2,4 @@ python -m doctest docs/tutorials/getting_started/*rst python -m doctest docs/tutorials/further_topics/*rst python -m doctest docs/reference/*rst +python -m doctest docs/tutorials/contributing/strategy/*rst From e06af3f1ad1b4329434e8a355c9ee00a2396a257 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:58:04 +0100 Subject: [PATCH 37/82] Writing small section about general contributions. --- docs/tutorials/contributing/library/index.rst | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/tutorials/contributing/library/index.rst b/docs/tutorials/contributing/library/index.rst index d71dcbe6a..797691ea8 100644 --- a/docs/tutorials/contributing/library/index.rst +++ b/docs/tutorials/contributing/library/index.rst @@ -1,15 +1,9 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Contributing to the library =========================== -This section contains a variety of tutorials that should help you contribute to -the library. - -Contents: +All contributions (docs, tests, etc) are very welcome, if there is a specific +functionality that you would like to add the please open an issue (or indeed +take a look at the ones already there and jump in the conversation!). -.. toctree:: - :maxdepth: 2 +If you want to work on documentation please keep in mind that doctests are +encouraged to help keep the documentation up to date. From 3e16aa08ec721c343be5c5b376eaa8c2393d7354 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 21:58:44 +0100 Subject: [PATCH 38/82] Inputting some basic tutorials. --- docs/index.rst | 18 ++--------- docs/tutorials/getting_started.rst | 49 ++++++++++++++++++++++++++++++ docs/tutorials/index.rst | 25 +++++++++++++++ 3 files changed, 77 insertions(+), 15 deletions(-) create mode 100644 docs/tutorials/getting_started.rst create mode 100644 docs/tutorials/index.rst diff --git a/docs/index.rst b/docs/index.rst index ca4209416..e6e9c2ed5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,25 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to the documentation for an implementation of Axelrod's tournament in Python -==================================================================================== - -This project is both: - -* A python library that reproduces Axelrod's tournament. -* A github experiment allowing anyone to contribute a strategy. - - -Contents: +Welcome to the documentation for the Axelrod Python library +=========================================================== .. toctree:: :maxdepth: 2 - background - usage - overview_of_strategies - index_of_strategies - contributing + tutorials/index.rst Indices and tables diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst new file mode 100644 index 000000000..28816e4f5 --- /dev/null +++ b/docs/tutorials/getting_started.rst @@ -0,0 +1,49 @@ +Getting started +=============== + +lipsum + + +Installation +------------ + +The simplest way to install the package is to obtain it from the PyPi +repository:: + + $ pip install axelrod + + +You can also build it from source if you would like to:: + + $ git clone https://github.com/Axelrod-Python/Axelrod.git + $ cd Axelrod + $ python setup.py install + + +Creating and running a simple tournament +---------------------------------------- + +The following lines of code create a simple list of strategies:: + + >>> import axelrod + >>> strategies = [s() for s in axelrod.demo_strategies] + >>> strategies + [Cooperator, Defector, Tit For Tat, Grudger, Random: 0.5] + +We can now create a tournament, play it, saving the results and viewing the +ranks of each player:: + + >>> tournament = axelrod.Tournament(strategies) + >>> results = tournament.play() + >>> results.ranked_names + ['Defector', 'Grudger', 'Tit For Tat', 'Cooperator', 'Random: 0.5'] + +We can also plot these results (which helps visualise the stochastic effects):: + + >>> plot = axelrod.Plot(results) + >>> p = plot.boxplot() + >>> p.show() + +.. image:: _static/usage/demo_strategies_boxplot.svg + :width: 50% + :align: center diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 000000000..57857faec --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,25 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Tutorials +========= + +This section contains a variety of tutorials related to the Axelrod library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + getting_started.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + From b9801465ac08224f3dbd2d303a47a10bda171404 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 22:08:47 +0100 Subject: [PATCH 39/82] Deleting this as didn't seem to have an effect --- docs/auto_generate_strategies_list.py | 42 --------------------------- 1 file changed, 42 deletions(-) delete mode 100644 docs/auto_generate_strategies_list.py diff --git a/docs/auto_generate_strategies_list.py b/docs/auto_generate_strategies_list.py deleted file mode 100644 index f8b4da374..000000000 --- a/docs/auto_generate_strategies_list.py +++ /dev/null @@ -1,42 +0,0 @@ -""" -A script to generate the file needed for the strategy documentation. - -Run: - - python strategies.py > strategies.rst -""" -import os -import sys - -sys.path.insert(0, os.path.abspath("../")) -from axelrod import basic_strategies -from axelrod import ordinary_strategies -from axelrod import cheating_strategies - - -def print_header(string, character): - print string - print character * len(string) - print "" - - -if __name__ == "__main__": - - print ".. currentmodule:: axelrod.strategies" - print_header("Index of strategies", '=') - - print_header("Basic strategies", '-') - for strategy in basic_strategies: - print ".. autoclass:: %s" % strategy.__name__ - - print "" - - print_header("Further (honest) Strategies", '-') - for strategy in ordinary_strategies: - print ".. autoclass:: %s" % strategy.__name__ - - print "" - - print_header("Cheating strategies", '-') - for strategy in cheating_strategies: - print ".. autoclass:: %s" % strategy.__name__ From aa5678e9ae6891a7ab873bbca43f249abe6d1541 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 22:04:12 +0100 Subject: [PATCH 40/82] Merge conflict --- .travis.yml | 1 + doctest | 2 ++ test | 3 +++ 3 files changed, 6 insertions(+) create mode 100755 doctest create mode 100755 test diff --git a/.travis.yml b/.travis.yml index ce9d30bcc..46f0fac0f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -20,5 +20,6 @@ script: - cd .. - coverage run --source=axelrod -m unittest discover - coverage report -m + - sh doctest after_success: - coveralls diff --git a/doctest b/doctest new file mode 100755 index 000000000..f263a59a6 --- /dev/null +++ b/doctest @@ -0,0 +1,2 @@ +#!/usr/bin/env bash +python -m doctest docs/tutorials/*rst diff --git a/test b/test new file mode 100755 index 000000000..ed49bd58a --- /dev/null +++ b/test @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +python -m unittest discover axelrod/tests/ +./doctest From 1fac8afa3b651b41f4d029d876f42c67be74c5d8 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 22:10:11 +0100 Subject: [PATCH 41/82] Reorganising files. --- docs/{ => background}/background.rst | 0 docs/description.rst | 4 ---- docs/index.rst | 2 ++ docs/{ => reference}/index_of_strategies.rst | 0 docs/{ => reference}/overview_of_strategies.rst | 0 .../_static/getting_started}/demo_strategies_boxplot.svg | 0 docs/{contributing.rst => tutorials/contributing.old} | 0 docs/tutorials/getting_started.rst | 2 +- docs/{usage.rst => tutorials/usage.old} | 0 9 files changed, 3 insertions(+), 5 deletions(-) rename docs/{ => background}/background.rst (100%) delete mode 100644 docs/description.rst rename docs/{ => reference}/index_of_strategies.rst (100%) rename docs/{ => reference}/overview_of_strategies.rst (100%) rename docs/{_static/usage => tutorials/_static/getting_started}/demo_strategies_boxplot.svg (100%) rename docs/{contributing.rst => tutorials/contributing.old} (100%) rename docs/{usage.rst => tutorials/usage.old} (100%) diff --git a/docs/background.rst b/docs/background/background.rst similarity index 100% rename from docs/background.rst rename to docs/background/background.rst diff --git a/docs/description.rst b/docs/description.rst deleted file mode 100644 index b7387825f..000000000 --- a/docs/description.rst +++ /dev/null @@ -1,4 +0,0 @@ -Description -=========== - -Describe the available strategies. diff --git a/docs/index.rst b/docs/index.rst index e6e9c2ed5..b68edb3ec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,8 @@ Welcome to the documentation for the Axelrod Python library =========================================================== +lipsum + .. toctree:: :maxdepth: 2 diff --git a/docs/index_of_strategies.rst b/docs/reference/index_of_strategies.rst similarity index 100% rename from docs/index_of_strategies.rst rename to docs/reference/index_of_strategies.rst diff --git a/docs/overview_of_strategies.rst b/docs/reference/overview_of_strategies.rst similarity index 100% rename from docs/overview_of_strategies.rst rename to docs/reference/overview_of_strategies.rst diff --git a/docs/_static/usage/demo_strategies_boxplot.svg b/docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg similarity index 100% rename from docs/_static/usage/demo_strategies_boxplot.svg rename to docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg diff --git a/docs/contributing.rst b/docs/tutorials/contributing.old similarity index 100% rename from docs/contributing.rst rename to docs/tutorials/contributing.old diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst index 28816e4f5..27968da90 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/tutorials/getting_started.rst @@ -44,6 +44,6 @@ We can also plot these results (which helps visualise the stochastic effects):: >>> p = plot.boxplot() >>> p.show() -.. image:: _static/usage/demo_strategies_boxplot.svg +.. image:: _static/getting_started/demo_strategies_boxplot.svg :width: 50% :align: center diff --git a/docs/usage.rst b/docs/tutorials/usage.old similarity index 100% rename from docs/usage.rst rename to docs/tutorials/usage.old From eff95292f03c60c87c2a8b6f54c9d6e9a26f7042 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 22:48:40 +0100 Subject: [PATCH 42/82] Removing stochastic strategies from early tutorials --- .../demo_strategies_boxplot.svg | 0 .../demo_strategies_payoff.svg | 0 docs/tutorials/getting_started.rst | 15 +++---- docs/tutorials/index.rst | 2 + docs/tutorials/payoff_matrix.rst | 34 ++++++++++++++++ docs/tutorials/visualising_results.rst | 40 +++++++++++++++++++ 6 files changed, 84 insertions(+), 7 deletions(-) rename docs/tutorials/_static/{getting_started => visualising_results}/demo_strategies_boxplot.svg (100%) rename docs/{_static/usage => tutorials/_static/visualising_results}/demo_strategies_payoff.svg (100%) create mode 100644 docs/tutorials/payoff_matrix.rst create mode 100644 docs/tutorials/visualising_results.rst diff --git a/docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg similarity index 100% rename from docs/tutorials/_static/getting_started/demo_strategies_boxplot.svg rename to docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg diff --git a/docs/_static/usage/demo_strategies_payoff.svg b/docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg similarity index 100% rename from docs/_static/usage/demo_strategies_payoff.svg rename to docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst index 27968da90..62bd7b2c1 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/tutorials/getting_started.rst @@ -25,25 +25,26 @@ Creating and running a simple tournament The following lines of code create a simple list of strategies:: - >>> import axelrod - >>> strategies = [s() for s in axelrod.demo_strategies] + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] >>> strategies - [Cooperator, Defector, Tit For Tat, Grudger, Random: 0.5] + [Cooperator, Defector, Tit For Tat, Grudger] We can now create a tournament, play it, saving the results and viewing the ranks of each player:: - >>> tournament = axelrod.Tournament(strategies) + >>> tournament = axl.Tournament(strategies) >>> results = tournament.play() >>> results.ranked_names - ['Defector', 'Grudger', 'Tit For Tat', 'Cooperator', 'Random: 0.5'] + ['Defector', 'Tit For Tat', 'Grudger', 'Cooperator'] We can also plot these results (which helps visualise the stochastic effects):: - >>> plot = axelrod.Plot(results) + >>> plot = axl.Plot(results) >>> p = plot.boxplot() >>> p.show() -.. image:: _static/getting_started/demo_strategies_boxplot.svg +.. image:: _static/getting_started/demo_deterministic_strategies_boxplot.svg :width: 50% :align: center diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 57857faec..74f9d1dbb 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -14,6 +14,8 @@ Contents: :maxdepth: 2 getting_started.rst + payoff_matrix.rst + visualising_results.rst Indices and tables diff --git a/docs/tutorials/payoff_matrix.rst b/docs/tutorials/payoff_matrix.rst new file mode 100644 index 000000000..8dbddb03a --- /dev/null +++ b/docs/tutorials/payoff_matrix.rst @@ -0,0 +1,34 @@ +Accessing the payoff matrix +=========================== + +lipsum + +This tutorial will show you briefly how to access the payoff matrix +corresponding to the tournament. + +Accessing the payoff matrix +--------------------------- + +As shown in `Getting_started`_ let us create a tournament:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + +We can view the payoff matrix of our tournament showing the score of the row-th +strategy when played against the column-th strategy:: + + >>> m = results.payoff_matrix + >>> for row in m: + ... print [round(ele, 1) for ele in row] # Rounding output + [3.0, 0.0, 3.0, 3.0] + [5.0, 1.0, 1.0, 1.0] + [3.0, 1.0, 3.0, 3.0] + [3.0, 1.0, 3.0, 3.0] + +Here we see that the second strategy (:code:`Defector`) obtains an average +utility per game of :code:`5.0` against the first strategy (:code:`Cooperator`) +as expected. + diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/visualising_results.rst new file mode 100644 index 000000000..e43fd414a --- /dev/null +++ b/docs/tutorials/visualising_results.rst @@ -0,0 +1,40 @@ +Visualising results +=================== + +lipsum + +This tutorial will show you briefly how to visualise some basic results + +Creating an axelrod plot instance +--------------------------------- + +As shown in `Getting_started`_ let us create a tournament, but this time we will +include a strategy that acts randomly:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> strategies.append(axl.Random()) + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + +We can view these results (which helps visualise the stochastic effects):: + + >>> plot = axl.Plot(results) + >>> p = plot.boxplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_boxplot.svg + :width: 50% + :align: center + +We can also easily view the payoff matrix described in `Payoff_matrix`_, this +becomes particularly useful when viewing the outputs of tournaments with a large +number of strategies:: + + >>> p = plot.payoff() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_payoff.svg + :width: 50% + :align: center From 41adada653ae04dafff809b5e73f6965c5b9bc24 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 23:04:40 +0100 Subject: [PATCH 43/82] Making docs python 3 compatible. --- docs/tutorials/payoff_matrix.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/tutorials/payoff_matrix.rst b/docs/tutorials/payoff_matrix.rst index 8dbddb03a..20ba841c1 100644 --- a/docs/tutorials/payoff_matrix.rst +++ b/docs/tutorials/payoff_matrix.rst @@ -6,9 +6,6 @@ lipsum This tutorial will show you briefly how to access the payoff matrix corresponding to the tournament. -Accessing the payoff matrix ---------------------------- - As shown in `Getting_started`_ let us create a tournament:: >>> import axelrod as axl @@ -22,7 +19,7 @@ strategy when played against the column-th strategy:: >>> m = results.payoff_matrix >>> for row in m: - ... print [round(ele, 1) for ele in row] # Rounding output + ... print([round(ele, 1) for ele in row]) # Rounding output [3.0, 0.0, 3.0, 3.0] [5.0, 1.0, 1.0, 1.0] [3.0, 1.0, 3.0, 3.0] From 67c1659812787f39031bcae9de5673372d81a0fa Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 18 Sep 2015 23:04:56 +0100 Subject: [PATCH 44/82] Compartementalising documentation. --- docs/tutorials/visualising_results.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/visualising_results.rst index e43fd414a..d480af46b 100644 --- a/docs/tutorials/visualising_results.rst +++ b/docs/tutorials/visualising_results.rst @@ -5,8 +5,8 @@ lipsum This tutorial will show you briefly how to visualise some basic results -Creating an axelrod plot instance ---------------------------------- +Visualising the results of the tournament +----------------------------------------- As shown in `Getting_started`_ let us create a tournament, but this time we will include a strategy that acts randomly:: @@ -28,6 +28,9 @@ We can view these results (which helps visualise the stochastic effects):: :width: 50% :align: center +Visualising the payoff matrix +----------------------------- + We can also easily view the payoff matrix described in `Payoff_matrix`_, this becomes particularly useful when viewing the outputs of tournaments with a large number of strategies:: From 0514fdf5b7dfb412a042e364200c92ddab1fe1db Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 17:35:56 +0100 Subject: [PATCH 45/82] Adding requirements.txt instructions. --- docs/tutorials/getting_started.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst index 62bd7b2c1..1ee21a446 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/tutorials/getting_started.rst @@ -19,6 +19,9 @@ You can also build it from source if you would like to:: $ cd Axelrod $ python setup.py install +If you do this you will need to also install the dependencies:: + + $ pip install -r requirements.txt Creating and running a simple tournament ---------------------------------------- From c449c85904382295d3cfbae4c7e18382c1cdc8e2 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 18:00:09 +0100 Subject: [PATCH 46/82] Adding distribution of wins section to visualisation. --- .../demo_strategies_winplot.svg | 1284 +++++++++++++++++ docs/tutorials/index.rst | 1 + docs/tutorials/visualising_results.rst | 12 + 3 files changed, 1297 insertions(+) create mode 100644 docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg new file mode 100644 index 000000000..04ab787a7 --- /dev/null +++ b/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg @@ -0,0 +1,1284 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 74f9d1dbb..e4412fbc6 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -16,6 +16,7 @@ Contents: getting_started.rst payoff_matrix.rst visualising_results.rst + noisy_tournaments.rst Indices and tables diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/visualising_results.rst index d480af46b..afa194a09 100644 --- a/docs/tutorials/visualising_results.rst +++ b/docs/tutorials/visualising_results.rst @@ -28,6 +28,18 @@ We can view these results (which helps visualise the stochastic effects):: :width: 50% :align: center +Visualising the distributions of wins +------------------------------------- + +We can view the distributions of wins for each player:: + + >>> p = plot.winplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_winplot.svg + :width: 50% + :align: center + Visualising the payoff matrix ----------------------------- From 10a31e485ddae1f3a2d2a0d5828f45c972e37531 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 18:00:41 +0100 Subject: [PATCH 47/82] Adding egg to gitignore For when use python setup.py develop. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index af448dbd4..3bfad54a1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ _build/ *.log dist/ MANIFEST +Axelrod.egg-info From 8e72d47b51aa9c3686259b2f1be3658cbcdaaf33 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 18:08:21 +0100 Subject: [PATCH 48/82] Adding noisy tournaments section. --- .../demo_strategies_noisy_boxplot.svg | 1968 +++++++++++++++++ .../demo_strategies_noisy_winplot.svg | 1223 ++++++++++ docs/tutorials/noisy_tournaments.rst | 46 + 3 files changed, 3237 insertions(+) create mode 100644 docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg create mode 100644 docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg create mode 100644 docs/tutorials/noisy_tournaments.rst diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg new file mode 100644 index 000000000..677a3aa8d --- /dev/null +++ b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg @@ -0,0 +1,1968 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg new file mode 100644 index 000000000..e8292e132 --- /dev/null +++ b/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg @@ -0,0 +1,1223 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/noisy_tournaments.rst b/docs/tutorials/noisy_tournaments.rst new file mode 100644 index 000000000..a55234bce --- /dev/null +++ b/docs/tutorials/noisy_tournaments.rst @@ -0,0 +1,46 @@ +Noisy tournaments +================= + +A common variation on iterated prisoner’s dilemma tournaments is to add +stochasticity in the choice of plays, simply called noise. This noise is +introduced by flipping plays between ‘C’ and ‘D’ with some probability that is +applied to all plays after they are delivered by the player. + +The presence of this persistant bakground noise causes some strategies to +behave substantially differently. For example, TitForTat can fall into +defection loops with itself when there is noise. While TitForTat would usually +cooperate well with itself:: + + C C C C C ... + C C C C C ... + +Noise can cause a C to flip to a D (or vice versa), disrupting the cooperative +chain:: + + C C C D C D C D D D ... + C C C C D C D D D D ... + +To create a noisy tournament you simply need to add the `noise` argument:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> noise = 0.1 + >>> tournament = axl.Tournament(strategies, noise=noise) + >>> results = tournament.play() + >>> plot = axl.Plot(results) + >>> p = plot.boxplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_noisy_boxplot.svg + :width: 50% + :align: center + +Here is how the distribution of wins now looks:: + + >>> p = plot.winplot() + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_noisy_winplot.svg + :width: 50% + :align: center From f38ef4ea8f86fc79079510f249c84cb098525cc0 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:36:02 +0100 Subject: [PATCH 49/82] Reorganisation of tutorials. --- .../demo_strategies_boxplot.svg | 0 .../demo_strategies_noisy_boxplot.svg | 0 .../demo_strategies_noisy_winplot.svg | 0 .../demo_strategies_payoff.svg | 0 .../demo_strategies_stackplot.svg | 2293 +++++++++++++++++ .../demo_strategies_winplot.svg | 0 .../{ => getting_started}/contributing.old | 0 .../getting_started/ecological_variant.rst | 24 + .../{ => getting_started}/getting_started.rst | 0 docs/tutorials/getting_started/index.rst | 20 + .../noisy_tournaments.rst | 0 .../{ => getting_started}/payoff_matrix.rst | 0 .../tutorials/{ => getting_started}/usage.old | 0 .../visualising_results.rst | 0 docs/tutorials/index.rst | 7 +- 15 files changed, 2339 insertions(+), 5 deletions(-) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_boxplot.svg (100%) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_noisy_boxplot.svg (100%) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_noisy_winplot.svg (100%) rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_payoff.svg (100%) create mode 100644 docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg rename docs/tutorials/{ => getting_started}/_static/visualising_results/demo_strategies_winplot.svg (100%) rename docs/tutorials/{ => getting_started}/contributing.old (100%) create mode 100644 docs/tutorials/getting_started/ecological_variant.rst rename docs/tutorials/{ => getting_started}/getting_started.rst (100%) create mode 100644 docs/tutorials/getting_started/index.rst rename docs/tutorials/{ => getting_started}/noisy_tournaments.rst (100%) rename docs/tutorials/{ => getting_started}/payoff_matrix.rst (100%) rename docs/tutorials/{ => getting_started}/usage.old (100%) rename docs/tutorials/{ => getting_started}/visualising_results.rst (100%) diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_boxplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_boxplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_noisy_boxplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_boxplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_winplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_noisy_winplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_noisy_winplot.svg diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_payoff.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_payoff.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_payoff.svg diff --git a/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg new file mode 100644 index 000000000..21876e775 --- /dev/null +++ b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_stackplot.svg @@ -0,0 +1,2293 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_winplot.svg similarity index 100% rename from docs/tutorials/_static/visualising_results/demo_strategies_winplot.svg rename to docs/tutorials/getting_started/_static/visualising_results/demo_strategies_winplot.svg diff --git a/docs/tutorials/contributing.old b/docs/tutorials/getting_started/contributing.old similarity index 100% rename from docs/tutorials/contributing.old rename to docs/tutorials/getting_started/contributing.old diff --git a/docs/tutorials/getting_started/ecological_variant.rst b/docs/tutorials/getting_started/ecological_variant.rst new file mode 100644 index 000000000..a51b4c62b --- /dev/null +++ b/docs/tutorials/getting_started/ecological_variant.rst @@ -0,0 +1,24 @@ +Ecological Variant +================== + +To study the evolutionary stability of each strategy it is possible to create an +ecosystem based on the payoff matrix of a tournament:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger(), + ... axl.Random()] + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + >>> eco = axl.Ecosystem(results) + >>> eco.reproduce(100) # Evolve the population over 100 time steps + +Here is how we obtain a nice stackplot of the system evolving over time:: + + >>> plot = axl.Plot(results) + >>> p = plot.stackplot(eco.population_sizes) + >>> p.show() + +.. image:: _static/visualising_results/demo_strategies_stackplot.svg + :width: 50% + :align: center diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started/getting_started.rst similarity index 100% rename from docs/tutorials/getting_started.rst rename to docs/tutorials/getting_started/getting_started.rst diff --git a/docs/tutorials/getting_started/index.rst b/docs/tutorials/getting_started/index.rst new file mode 100644 index 000000000..615d030ef --- /dev/null +++ b/docs/tutorials/getting_started/index.rst @@ -0,0 +1,20 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Getting Started +=============== + +This section contains a variety of tutorials related to the Axelrod library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + getting_started.rst + payoff_matrix.rst + visualising_results.rst + noisy_tournaments.rst + ecological_variant.rst diff --git a/docs/tutorials/noisy_tournaments.rst b/docs/tutorials/getting_started/noisy_tournaments.rst similarity index 100% rename from docs/tutorials/noisy_tournaments.rst rename to docs/tutorials/getting_started/noisy_tournaments.rst diff --git a/docs/tutorials/payoff_matrix.rst b/docs/tutorials/getting_started/payoff_matrix.rst similarity index 100% rename from docs/tutorials/payoff_matrix.rst rename to docs/tutorials/getting_started/payoff_matrix.rst diff --git a/docs/tutorials/usage.old b/docs/tutorials/getting_started/usage.old similarity index 100% rename from docs/tutorials/usage.old rename to docs/tutorials/getting_started/usage.old diff --git a/docs/tutorials/visualising_results.rst b/docs/tutorials/getting_started/visualising_results.rst similarity index 100% rename from docs/tutorials/visualising_results.rst rename to docs/tutorials/getting_started/visualising_results.rst diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index e4412fbc6..c0e7993a5 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -13,11 +13,8 @@ Contents: .. toctree:: :maxdepth: 2 - getting_started.rst - payoff_matrix.rst - visualising_results.rst - noisy_tournaments.rst - + getting_started/index.rst + further_topics/index.rst Indices and tables ================== From e932e6016940db8fbfd147a058665752c3ec894f Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:36:15 +0100 Subject: [PATCH 50/82] First further topics tutorials. --- docs/tutorials/further_topics/index.rst | 17 +++++++ .../further_topics/morality_metrics.rst | 44 +++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/tutorials/further_topics/index.rst create mode 100644 docs/tutorials/further_topics/morality_metrics.rst diff --git a/docs/tutorials/further_topics/index.rst b/docs/tutorials/further_topics/index.rst new file mode 100644 index 000000000..ed5ee3b78 --- /dev/null +++ b/docs/tutorials/further_topics/index.rst @@ -0,0 +1,17 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Further Topics +============== + +This section contains a variety of tutorials that show some more in depth +capabilities of the axelrod library + +Contents: + +.. toctree:: + :maxdepth: 2 + + morality_metrics.rst diff --git a/docs/tutorials/further_topics/morality_metrics.rst b/docs/tutorials/further_topics/morality_metrics.rst new file mode 100644 index 000000000..5e0dfb965 --- /dev/null +++ b/docs/tutorials/further_topics/morality_metrics.rst @@ -0,0 +1,44 @@ +Morality Metrics +================ + +Tyler Singer-Clark's June 2014 paper, "Morality Metrics On Iterated Prisoner’s +Dilemma Players," describes several interesting metrics which may be used to +analyse IPD tournaments all of which are available within the ResultSet class. +(Tyler's paper is available here: http://www.scottaaronson.com/morality.pdf). + +Each metric depends upon the cooperation rate of the players, defined by Tyler +Singer-Clark as: + +.. math:: + + CR(b) = \frac{C(b)}{TT} + +where C(b) is the total number of turns where a player chose to cooperate and TT +is the total number of turns played. + +A matrix of cooperation rates is available within a tournament's ResultSet:: + + >>> import axelrod as axl + >>> strategies = [axl.Cooperator(), axl.Defector(), + ... axl.TitForTat(), axl.Grudger()] + >>> tournament = axl.Tournament(strategies) + >>> results = tournament.play() + >>> results.normalised_cooperation + [[1.0, 1.0, 1.0, 1.0], [0.0, 0.0, 0.0, 0.0], [1.0, 0.005, 1.0, 1.0], [1.0, 0.005, 1.0, 1.0]] + +There is also a 'good partner' matrix showing how often a player cooperated at +least as much as its opponent:: + + >>> results.good_partner_matrix + [[0, 10, 10, 10], [0, 0, 0, 0], [10, 10, 0, 10], [10, 10, 10, 0]] + +Each of the metrics described in Tyler's paper is available as follows (here they are rounded to 2 digits):: + + >>> [round(ele, 2) for ele in results.cooperating_rating] + [1.0, 0.0, 0.75, 0.75] + >>> [round(ele, 2) for ele in results.good_partner_rating] + [1.0, 0.0, 1.0, 1.0] + >>> [round(ele, 2) for ele in results.eigenjesus_rating] + [0.58, 0.0, 0.58, 0.58] + >>> [round(ele, 2) for ele in results.eigenmoses_rating] + [0.37, -0.37, 0.6, 0.6] From fd228a24dabaf97dfb7ab9c60d00eeafc1a8a193 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:36:32 +0100 Subject: [PATCH 51/82] Modifying the doctests. --- doctest | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doctest b/doctest index f263a59a6..30142ba09 100755 --- a/doctest +++ b/doctest @@ -1,2 +1,3 @@ #!/usr/bin/env bash -python -m doctest docs/tutorials/*rst +python -m doctest docs/tutorials/getting_started/*rst +python -m doctest docs/tutorials/further_topics/*rst From 1b5a1880de97533b7a5b6f89dba3aad9fdc855a9 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:38:05 +0100 Subject: [PATCH 52/82] Some minor rewording. --- docs/index.rst | 2 -- docs/tutorials/getting_started/index.rst | 3 ++- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index b68edb3ec..e6e9c2ed5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,6 @@ Welcome to the documentation for the Axelrod Python library =========================================================== -lipsum - .. toctree:: :maxdepth: 2 diff --git a/docs/tutorials/getting_started/index.rst b/docs/tutorials/getting_started/index.rst index 615d030ef..b02ad4e02 100644 --- a/docs/tutorials/getting_started/index.rst +++ b/docs/tutorials/getting_started/index.rst @@ -6,7 +6,8 @@ Getting Started =============== -This section contains a variety of tutorials related to the Axelrod library. +This section contains a variety of tutorials that should help get you started +with the Axelrod library. Contents: From 5024ba12888f54a1352e1aec48818f28ad18bf32 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:50:07 +0100 Subject: [PATCH 53/82] Starting work on contributions. --- docs/tutorials/contributing/guidelines.rst | 27 +++++++++++ docs/tutorials/contributing/index.rst | 18 +++++++ docs/tutorials/contributing/instructions.rst | 49 ++++++++++++++++++++ 3 files changed, 94 insertions(+) create mode 100644 docs/tutorials/contributing/guidelines.rst create mode 100644 docs/tutorials/contributing/index.rst create mode 100644 docs/tutorials/contributing/instructions.rst diff --git a/docs/tutorials/contributing/guidelines.rst b/docs/tutorials/contributing/guidelines.rst new file mode 100644 index 000000000..02aa6b84b --- /dev/null +++ b/docs/tutorials/contributing/guidelines.rst @@ -0,0 +1,27 @@ +Guidelines +========== + +All contributions to this repository are welcome via pull request on the `github repository `_. + +The project follows the following guidelines: + +1. Use the base Python library unless completely necessary. A few external + libraries (such as numpy) have been included in requirements.txt -- feel free + to use these as needed. +2. If a non base Python library is deemed necessary, it should not hinder the + running or contribution of the package when using the base Python library. For + example, the `matplotlib library `_ is used in a + variety of classes to be able to show results, such as this one: This has been + done carefully with tests that are skipped if the library is not installed and + also without any crashes if something using the library was run. +3. Try as best as possible to follow `PEP8 + `_ which includes **using + descriptive variable names**. +4. Testing: the project uses the `unittest + `_ library and has a nice + testing suite that makes some things very easy to write tests for. Please try + to increase the test coverage on pull requests. +5. Merging pull-requests: We require two of the (currently four) core-team + maintainers to merge (and preferably not the submitted). Opening a PR for early + feedback or to check test coverage is OK, just indicate that the PR is not ready + to merge (and update when it is). diff --git a/docs/tutorials/contributing/index.rst b/docs/tutorials/contributing/index.rst new file mode 100644 index 000000000..603a8d37a --- /dev/null +++ b/docs/tutorials/contributing/index.rst @@ -0,0 +1,18 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Contributing +============ + +This section contains a variety of tutorials that should help you contribute to +the library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + guidelines.rst + instructions.rst diff --git a/docs/tutorials/contributing/instructions.rst b/docs/tutorials/contributing/instructions.rst new file mode 100644 index 000000000..6209befa1 --- /dev/null +++ b/docs/tutorials/contributing/instructions.rst @@ -0,0 +1,49 @@ +Instructions +============ + +Here is the file structure for the Axelrod repository:: + + . + ├── axelrod + │ └── __init__.py + │ └── ecosystem.py + │ └── game.py + │ └── player.py + │ └── plot.py + │ └── result_set.py + │ └── round_robin.py + │ └── tournament.py + │ └── /strategies/ + │ └── __init__.py + │ └── _strategies.py + │ └── cooperator.py + │ └── defector.py + │ └── grudger.py + │ └── titfortat.py + │ └── gobymajority.py + │ └── ... + │ └── /tests/ + │ └── functional + │ └── unit + │ └── test_*.py + └── README.md + +To contribute a strategy you need to follow as many of the following steps as possible: + +1. Fork the `github repository `_. +2. Add a :code:`.py` file to the strategies directory. (Take a look + at the others in there: you need to write code for the strategy and one other + simple thing.) +3. Update the :code:`./axelrod/strategies/_strategies.py` file (you need to + write the import statement and add the strategy to the relevant python list). +4. Update :code:`./axelrod/docs/overview_of_strategies.rst` with a description + of what the strategy does and include an example of it working. If relevant + please also add a source for the strategy (if it is not an original one). +5. This one is optional: write some unit tests in the ./axelrod/tests/ directory. +6. This one is also optional: ping us a message and we'll add you to the + Contributors team. This would add an Axelrod-Python organisation badge to + your profile. +7. Send us a pull request. + +**If you would like a hand with any of the above please do get in touch: we're +always delight to have new strategies.** From 0d1e1ace6d927f0f0ced13669a1bc8ea52eaa07f Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 21:50:30 +0100 Subject: [PATCH 54/82] Creating empty advanced topics. --- docs/tutorials/advanced/index.rst | 10 ++++++++++ docs/tutorials/index.rst | 2 ++ 2 files changed, 12 insertions(+) create mode 100644 docs/tutorials/advanced/index.rst diff --git a/docs/tutorials/advanced/index.rst b/docs/tutorials/advanced/index.rst new file mode 100644 index 000000000..ddfd52de6 --- /dev/null +++ b/docs/tutorials/advanced/index.rst @@ -0,0 +1,10 @@ +Advanced +======== + +This is a section aiming to showcase some problems solved and/or insights gained +using the Axelrod library. Please be the first to submit such a tutorial! + +Contents: + +.. toctree:: + :maxdepth: 2 diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index c0e7993a5..30c72c8c5 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -15,6 +15,8 @@ Contents: getting_started/index.rst further_topics/index.rst + advanced/index.rst + contributing/index.rst Indices and tables ================== From 99ad48de0a167b647765d175bb2abae72f7ab75a Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 22:25:14 +0100 Subject: [PATCH 55/82] Refresh of overview of strategies: now doctested. --- docs/index.rst | 1 + docs/reference/index.rst | 19 + docs/reference/index_of_strategies.rst | 90 ---- docs/reference/overview_of_strategies.rst | 543 +++++++++------------- doctest | 1 + 5 files changed, 235 insertions(+), 419 deletions(-) create mode 100644 docs/reference/index.rst delete mode 100644 docs/reference/index_of_strategies.rst diff --git a/docs/index.rst b/docs/index.rst index e6e9c2ed5..58698af74 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ Welcome to the documentation for the Axelrod Python library :maxdepth: 2 tutorials/index.rst + reference/index.rst Indices and tables diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 000000000..d7b408eb8 --- /dev/null +++ b/docs/reference/index.rst @@ -0,0 +1,19 @@ +Reference +========= + +This section is the reference guide for the various components of the library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + overview_of_strategies.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/reference/index_of_strategies.rst b/docs/reference/index_of_strategies.rst deleted file mode 100644 index 68e2d855f..000000000 --- a/docs/reference/index_of_strategies.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. currentmodule:: axelrod.strategies -Index of strategies -=================== - -Basic strategies ----------------- - -.. autoclass:: Alternator -.. autoclass:: Cooperator -.. autoclass:: Defector -.. autoclass:: Random -.. autoclass:: TitForTat - -Further (honest) Strategies ---------------------------- - -.. autoclass:: AlternatorHunter -.. autoclass:: Appeaser -.. autoclass:: AntiTitForTat -.. autoclass:: ArrogantQLearner -.. autoclass:: AverageCopier -.. autoclass:: Bully -.. autoclass:: CautiousQLearner -.. autoclass:: CooperatorHunter -.. autoclass:: Davis -.. autoclass:: DefectorHunter -.. autoclass:: e -.. autoclass:: Feld -.. autoclass:: FoolMeOnce -.. autoclass:: ForgetfulFoolMeOnce -.. autoclass:: ForgetfulGrudger -.. autoclass:: Forgiver -.. autoclass:: ForgivingTitForTat -.. autoclass:: GTFT -.. autoclass:: GoByMajority -.. autoclass:: GoByMajority10 -.. autoclass:: GoByMajority20 -.. autoclass:: GoByMajority40 -.. autoclass:: GoByMajority5 -.. autoclass:: Golden -.. autoclass:: Grofman -.. autoclass:: Grudger -.. autoclass:: Grumpy -.. autoclass:: HesitantQLearner -.. autoclass:: Inverse -.. autoclass:: InversePunisher -.. autoclass:: Joss -.. autoclass:: LimitedRetaliate -.. autoclass:: LimitedRetaliate2 -.. autoclass:: LimitedRetaliate3 -.. autoclass:: MathConstantHunter -.. autoclass:: MetaHunter -.. autoclass:: MetaMajority -.. autoclass:: MetaMinority -.. autoclass:: MetaWinner -.. autoclass:: NiceAverageCopier -.. autoclass:: OnceBitten -.. autoclass:: OppositeGrudger -.. autoclass:: Pi -.. autoclass:: Punisher -.. autoclass:: RandomHunter -.. autoclass:: Retaliate -.. autoclass:: Retaliate2 -.. autoclass:: Retaliate3 -.. autoclass:: RiskyQLearner -.. autoclass:: Shubik -.. autoclass:: SneakyTitForTat -.. autoclass:: StochasticWSLS -.. autoclass:: SuspiciousTitForTat -.. autoclass:: TitFor2Tats -.. autoclass:: TrickyCooperator -.. autoclass:: TrickyDefector -.. autoclass:: Tullock -.. autoclass:: TwoTitsForTat -.. autoclass:: WinStayLoseShift -.. autoclass:: ZDExtort2 -.. autoclass:: ZDGTFT2 - -Cheating strategies -------------------- - -.. autoclass:: Darwin -.. autoclass:: Geller -.. autoclass:: GellerCooperator -.. autoclass:: GellerDefector -.. autoclass:: MindBender -.. autoclass:: MindController -.. autoclass:: MindReader -.. autoclass:: MindWarper -.. autoclass:: ProtectedMindReader diff --git a/docs/reference/overview_of_strategies.rst b/docs/reference/overview_of_strategies.rst index 9d3a4fb10..539026208 100644 --- a/docs/reference/overview_of_strategies.rst +++ b/docs/reference/overview_of_strategies.rst @@ -64,29 +64,22 @@ Implementation Here is a quick implementation of this in the library:: - import axelrod - p1 = axelrod.TitForTat() # Create a player that plays tit for tat - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.TitForTat() # Create a player that plays tit for tat + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['C', 'C', 'C', 'C', 'C'] We see that Tit for Tat cooperated every time, let us see how things change when it plays against a player that always defects:: - p1 = axelrod.TitForTat() # Create a player that plays tit for tat - p3 = axelrod.Defector() # Create a player that always defects - for round in range(5): - p1.play(p3) - print p1.history - -which gives:: - + >>> p1 = axelrod.TitForTat() # Create a player that plays tit for tat + >>> p3 = axelrod.Defector() # Create a player that always defects + >>> for round in range(5): + ... p1.play(p3) + >>> p1.history ['C', 'D', 'D', 'D', 'D'] We see that after cooperating once, Tit For Tat defects at every step. @@ -151,8 +144,10 @@ Finally this strategy defects if and only if: Grofman ^^^^^^^ -This is a pretty simple strategy: it cooperates with probability :math:`\frac{2}{7}`. In contemporary terminology, this is a memory-one player -with all four conditional probabilities of cooperation equal to :math:`\frac{2}{7}`. +This is a pretty simple strategy: it cooperates with probability +:math:`\frac{2}{7}`. In contemporary terminology, this is a memory-one player +with all four conditional probabilities of cooperation equal to +:math:`\frac{2}{7}`. *This strategy came 4th in Axelrod's original tournament.* @@ -161,34 +156,14 @@ Implementation Here is how Grofman is implemented in the library:: - import axelrod - p1 = axelrod.Grofman() # Create a Grofman player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Grofman() # Create a Grofman player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'D', 'D'] -Over a longer number of rounds:: - - from collections import Counter - for round in range(5): - p1.play(p2) - counter = Counter(p1.history) - print(counter) - Counter({'D': 367, 'C': 138}) - print float(counter['C']) / (counter['C'] + counter['D']) - print 2./7 - -We have that Grofman cooperates roughly in :math:`\frac{2}{7}`-ths of the rounds:: - - 0.2732673267326733 # Grofman - 0.2857142857142857 # 2./7 - Shubik ^^^^^^ @@ -203,18 +178,14 @@ Implementation Here is how Shubik is implemented in the library:: - import axelrod - p1 = axelrod.Shubik() # Create a Shubik player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(13): - p1.play(p2) - - print p1.history - print p2.history - -This yields the following history of play:: - + >>> import axelrod + >>> p1 = axelrod.Shubik() # Create a Shubik player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(13): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'D', 'C', 'D', 'D', 'D', 'C', 'C', 'C', 'D', 'D', 'D', 'C'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'C', 'D', 'C', 'C', 'C', 'D', 'C', 'C', 'C', 'D'] The increasing retaliation periods are visible in the output. Note that @@ -248,19 +219,15 @@ Implementation Here is how this is implemented in the library:: - import axelrod - p1 = axelrod.Grudger() # Create a player that grudger - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for the random seed used):: - - ['C', 'C', 'D', 'D', 'D'] - ['C', 'D', 'C', 'D', 'D'] + >>> import axelrod + >>> p1 = axelrod.Grudger() # Create a player that grudger + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP + ['C', 'C', 'D', 'D', 'D'] + >>> p2.history # doctest: +SKIP + ['C', 'D', 'C', 'D', 'D'] We see that as soon as :code:`p2` defected :code:`p1` defected for the rest of the play. @@ -278,19 +245,14 @@ Implementation Davis is implemented as follows:: - import axelrod - p1 = axelrod.Davis() # Create a Davis player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(15): - p1.play(p2) - - print p1.history - print p2.history - -This always produces (at least) 10 rounds of attempted cooperation followed by -Grudger:: - + >>> import axelrod + >>> p1 = axelrod.Davis() # Create a Davis player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(15): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'D', 'D', 'D', 'D', 'D'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'D', 'C', 'D', 'D', 'C', 'D', 'C', 'D', 'D', 'C', 'C', 'D'] Graaskamp @@ -341,18 +303,14 @@ Implementation Feld is implemented in the library as follows:: - import axelrod - p1 = axelrod.Feld() # Create a Feld player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(10): - p1.play(p2) - - print p1.history - print p2.history - -We can see from the output that Feld defects when its opponent does:: - + >>> import axelrod + >>> p1 = axelrod.Feld() # Create a Feld player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(10): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'D', 'C', 'D', 'D', 'D', 'D', 'C', 'D', 'D'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'D', 'D', 'D', 'C', 'D', 'D', 'D'] The defection times lengthen each time the opponent defects when Feld @@ -372,18 +330,14 @@ Implementation This is a memory-one strategy with four-vector :math:`(0.9, 0, 1, 0)`. Here is how Joss is implemented in the library:: - import axelrod - p1 = axelrod.Joss() # Create a Joss player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(10): - p1.play(p2) - - print p1.history - print p2.history - -This gives:: - + >>> import axelrod + >>> p1 = axelrod.Joss() # Create a Joss player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(10): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'D', 'C', 'D', 'C', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP ['C', 'C', 'D', 'C', 'D', 'C', 'C', 'C', 'C', 'D'] Which is the same as Tit-For-Tat for these 10 rounds. @@ -401,18 +355,14 @@ Implementation Tullock is implemented in the library as follows:: - import axelrod - p1 = axelrod.Tullock() # Create a Tullock player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(15): - p1.play(p2) - - print p1.history - print p2.history - -This gives:: - + >>> import axelrod + >>> p1 = axelrod.Tullock() # Create a Tullock player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(15): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'D', 'D', 'C', 'D'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'C', 'D', 'D', 'C', 'C', 'D', 'D', 'D', 'C', 'D', 'C', 'D', 'C'] We have 10 rounds of cooperation and some apparently random plays afterward. @@ -445,19 +395,15 @@ Implementation Here is how this is implemented in the library:: - import axelrod - p1 = axelrod.Random() # Create a player that plays randomly - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for the random seed used):: - - ['D', 'D', 'C', 'C', 'C'] - ['D', 'C', 'D', 'D', 'C'] + >>> import axelrod + >>> p1 = axelrod.Random() # Create a player that plays randomly + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP + ['D', 'D', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP + ['D', 'C', 'D', 'D', 'C'] Axelrod's second tournament --------------------------- @@ -479,21 +425,17 @@ Implementation Here is how Eatherley is implemented in the library:: - import axelrod - p1 = axelrod.Eatherley() # Create a Eatherley player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for a particular random seed):: + >>> import axelrod + >>> p1 = axelrod.Eatherley() # Create a Eatherley player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'D', 'C'] + >>> p2.history # doctest: +SKIP ['C', 'D', 'D', 'C', 'C'] - CHAMPION ^^^^^^^^ @@ -511,21 +453,16 @@ Implementation Here is how Champion is implemented in the library:: - import axelrod - p1 = axelrod.Champion() # Create a Champion player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for a particular random seed):: - + >>> import axelrod + >>> p1 = axelrod.Champion() # Create a Champion player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP ['D', 'C', 'D', 'D', 'C'] - TESTER ^^^^^^ @@ -541,22 +478,16 @@ Implementation Here is how this is implemented in the library:: - import axelrod - p1 = axelrod.Tester() # Create a Tester player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -which gives (for a particular random seed):: - + >>> import axelrod + >>> p1 = axelrod.Tester() # Create a Tester player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['D', 'C', 'C', 'D', 'D'] + >>> p2.history # doctest: +SKIP ['C', 'D', 'D', 'D', 'C'] - - Stewart and Plotkin's Tournament (2012) --------------------------------------- @@ -650,17 +581,13 @@ Implementation Here is a quick implementation of this in the library:: - import axelrod - p1 = axelrod.GTFT() # Create a player that plays GTFT - p2 = axelrod.Defector() # Create a player that always defects - for round in range(10): - p1.play(p2) - - print p1.history - -this gives (for the random seed used):: - - ['C', 'D', 'D', 'C', 'D', 'D', 'D', 'D', 'D', 'D'] + >>> import axelrod + >>> p1 = axelrod.GTFT() # Create a player that plays GTFT + >>> p2 = axelrod.Defector() # Create a player that always defects + >>> for round in range(10): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP + ['C', 'D', 'D', 'C', 'D', 'D', 'D', 'D', 'D', 'D'] which shows that :code:`GTFT` tried to forgive :code:`Defector`. @@ -677,17 +604,13 @@ Implementation Here is the implementation of this in the library:: - import axelrod - p1 = axelrod.TitFor2Tats() # Create a player that plays TF2T - p2 = axelrod.Defector() # Create a player that always defects - for round in range(3): - p1.play(p2) - - print p1.history - -which gives:: - - ['C', 'C', 'D'] + >>> import axelrod + >>> p1 = axelrod.TitFor2Tats() # Create a player that plays TF2T + >>> p2 = axelrod.Defector() # Create a player that always defects + >>> for round in range(3): + ... p1.play(p2) + >>> p1.history + ['C', 'C', 'D'] we see that it takes 2 defections to trigger a defection by :code:`TitFor2Tats`. @@ -710,17 +633,13 @@ Implementation Here is a quick implementation of this in the library:: - import axelrod - p1 = axelrod.WinStayLoseShift() # Create a player that plays WSLS - p2 = axelrod.Alternator() # Create a player that alternates - for round in range(5): - p1.play(p2) - - print p1.history - -this gives:: - - ['C', 'C', 'D', 'D', 'C'] + >>> import axelrod + >>> p1 = axelrod.WinStayLoseShift() # Create a player that plays WSLS + >>> p2 = axelrod.Alternator() # Create a player that alternates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history + ['C', 'C', 'D', 'D', 'C'] which shows that :code:`WSLS` will choose the strategy that was a best response in the previous round. @@ -755,18 +674,14 @@ Implementation Here is how ZDGTFT-2 is implemented in the library:: - import axelrod - p1 = axelrod.ZDGTFT2() # Create a ZDGTFT-2 player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for the particular random seed used):: - + >>> import axelrod + >>> p1 = axelrod.ZDGTFT2() # Create a ZDGTFT-2 player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'D', 'D', 'C', 'C', 'D', 'C', 'D', 'D', 'D'] + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'D', 'C', 'C', 'D', 'C', 'D', 'D'] looking closely (and repeating the above) will show that the above @@ -790,18 +705,14 @@ Implementation Here is how EXTORT-2 is implemented in the library:: - import axelrod - p1 = axelrod.ZDExtort2() # Create a EXTORT-2 player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(10): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for the particular seed used):: - + >>> import axelrod + >>> p1 = axelrod.ZDExtort2() # Create a EXTORT-2 player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(10): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'C', 'C', 'C', 'D', 'D', 'D', 'D', 'C', 'D'] + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'C', 'C', 'D', 'D', 'D', 'D', 'D'] you can see that :code:`ZDExtort2` never cooperates after both strategies defect. @@ -821,16 +732,12 @@ Implementation Here is how GRIM is implemented in the library:: - import axelrod - p1 = axelrod.Grudger() # Create a GRIM player - p2 = axelrod.Defector() # Create a player that always defects - for round in range(5): - p1.play(p2) - - print p1.history - -this gives:: - + >>> import axelrod + >>> p1 = axelrod.Grudger() # Create a GRIM player + >>> p2 = axelrod.Defector() # Create a player that always defects + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['C', 'D', 'D', 'D', 'D'] HARD_JOSS @@ -867,22 +774,18 @@ Implementation HARD_MAJO is implemented in the library:: - import axelrod - p1 = axelrod.GoByMajority() # Create a HARD_TFT player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for this seed):: - - + >>> import axelrod + >>> p1 = axelrod.GoByMajority() # Create a HARD_TFT player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'C', 'C', 'D', 'D'] + >>> p1.history # doctest: +SKIP ['C', 'D', 'C', 'C', 'C'] -we see that following the third round (at which point the opponent has cooperated a lot), :code:`GoByMajority` cooperates. +we see that following the third round (at which point the opponent has +cooperated a lot), :code:`GoByMajority` cooperates. HARD_TFT ^^^^^^^^ @@ -900,20 +803,16 @@ Implementation HARD_TFT is implemented in the library:: - import axelrod - p1 = axelrod.HardTitForTat() # Create a HARD_TFT player - p2 = axelrod.Alternator() # Create a player that alternates - for round in range(5): - p1.play(p2) - - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.HardTitForTat() # Create a HARD_TFT player + >>> p2 = axelrod.Alternator() # Create a player that alternates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['C', 'C', 'D', 'D', 'D'] we see that :code:`HardTitForTat` cooperates for the first two moves but then -constantly defetcts as there is always a defection in it's opponent's recent +constantly defects as there is always a defection in it's opponent's recent history. HARD_TF2T @@ -931,18 +830,15 @@ Implementation HARD_TF2T is implemented in the library:: - import axelrod - p1 = axelrod.HardTitFor2Tats() # Create a HARD_TF2T player - p2 = axelrod.Random() # Create a player that plays randomly - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives (for this particular seed):: + >>> import axelrod + >>> p1 = axelrod.HardTitFor2Tats() # Create a HARD_TF2T player + >>> p2 = axelrod.Random() # Create a player that plays randomly + >>> for round in range(5): + ... p1.play(p2) + >>> p2.history # doctest: +SKIP ['D', 'D', 'C', 'D', 'C'] + >>> p1.history # doctest: +SKIP ['C', 'C', 'D', 'D', 'C'] we see that :code:`HardTitFor2Tats` waited for 2 defects before defecting, but @@ -958,20 +854,16 @@ Calculator attempts to detect a cycle in the opponents history, and defects unconditionally thereafter if a cycle is found. Otherwise Calculator plays like TFT for the remaining rounds. -Calculator is implemented in the library as follows: - - import axelrod - p1 = axelrod.Calculator() # Create a HARD_TF2T player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p1.history - print p2.history - -This returns (for a particular random seed):: +Calculator is implemented in the library as follows:: + >>> import axelrod + >>> p1 = axelrod.Calculator() # Create a HARD_TF2T player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C'] + >>> p2.history # doctest: +SKIP ['C', 'C', 'C', 'C', 'C'] Prober @@ -989,18 +881,14 @@ Implementation Prober is implemented in the library:: - import axelrod - p1 = axelrod.Prober() # Create a Prober player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Prober() # Create a Prober player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'C', 'C', 'D', 'D'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] Prober2 @@ -1018,18 +906,14 @@ Implementation Prober2 is implemented in the library:: - import axelrod - p1 = axelrod.Prober2() # Create a Prober2 player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Prober2() # Create a Prober2 player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'C', 'C', 'C', 'C'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] Prober3 @@ -1047,18 +931,14 @@ Implementation Prober3 is implemented in the library:: - import axelrod - p1 = axelrod.Prober3() # Create a Prober3 player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: - + >>> import axelrod + >>> p1 = axelrod.Prober3() # Create a Prober3 player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'C', 'D', 'D', 'D'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] HardProber @@ -1076,58 +956,63 @@ Implementation HardProber is implemented in the library:: - import axelrod - p1 = axelrod.HardProber() # Create a Prober3 player - p2 = axelrod.Cooperator() # Create a player that always cooperates - for round in range(5): - p1.play(p2) - - print p2.history - print p1.history - -which gives:: + >>> import axelrod + >>> p1 = axelrod.HardProber() # Create a Prober3 player + >>> p2 = axelrod.Cooperator() # Create a player that always cooperates + >>> for round in range(5): + ... p1.play(p2) + >>> p1.history ['D', 'D', 'C', 'C', 'D'] + >>> p2.history ['C', 'C', 'C', 'C', 'C'] Strategies implemented in the module ------------------------------------ -There are several original strategies which have been created as part of this project and have never (to our knowledge) appeared in previous tournaments. +There are several original strategies which have been created as part of this +project and have never (to our knowledge) appeared in previous tournaments. Fool Me Once -^^^^^^^^^^^ +^^^^^^^^^^^^ -This strategy begins by cooperating but will defect if at any point the opponent has defected more than once. +This strategy begins by cooperating but will defect if at any point the opponent +has defected more than once. Forgetful Fool Me Once ^^^^^^^^^^^^^^^^^^^^^^ -Like Fool Me Once, this strategy defects if the opponent ever defects, but sometimes -forgets that the opponent had defected, cooperating again until another defection. +Like Fool Me Once, this strategy defects if the opponent ever defects, but +sometimes forgets that the opponent had defected, cooperating again until +another defection. Fool Me Forever ^^^^^^^^^^^^^^^ -This strategy defects until the opponent defects, and then cooperates there after. -Note that this strategy is different than opposite grudger, which cooperates -indefinitely after an opponent cooperation. +This strategy defects until the opponent defects, and then cooperates there +after. Note that this strategy is different than opposite grudger, which +cooperates indefinitely after an opponent cooperation. Backstabber ^^^^^^^^^^^ -Forgives the first 3 defections but on the fourth will defect forever. Defects after the 198th round unconditionally. +Forgives the first 3 defections but on the fourth will defect forever. Defects +after the 198th round unconditionally. DoubleCrosser ^^^^^^^^^^^^^ -Forgives the first 3 defections but on the fourth will defect forever. If the opponent did not defect in the first 6 rounds the player will cooperate until the 180th round. Defects after the 198th round unconditionally. +Forgives the first 3 defections but on the fourth will defect forever. If the +opponent did not defect in the first 6 rounds the player will cooperate until +the 180th round. Defects after the 198th round unconditionally. Aggravater ^^^^^^^^^^ -This strategy begins by defecting 3 times and then will cooperate until the opponent defects. After the opponent defects it will defect unconditionally. Essentially Grudger, but begins by defecting 3 times. +This strategy begins by defecting 3 times and then will cooperate until the +opponent defects. After the opponent defects it will defect unconditionally. +Essentially Grudger, but begins by defecting 3 times. Alternator ^^^^^^^^^^ diff --git a/doctest b/doctest index 30142ba09..7def29b5f 100755 --- a/doctest +++ b/doctest @@ -1,3 +1,4 @@ #!/usr/bin/env bash python -m doctest docs/tutorials/getting_started/*rst python -m doctest docs/tutorials/further_topics/*rst +python -m doctest docs/reference/*rst From 63432f75c40db6391676d62e74672bef3bee99b7 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 22:40:20 +0100 Subject: [PATCH 56/82] Adding tutorial on classification --- .../classification_of_strategies.rst | 42 +++++++++++++++++++ docs/tutorials/further_topics/index.rst | 6 +-- 2 files changed, 43 insertions(+), 5 deletions(-) create mode 100644 docs/tutorials/further_topics/classification_of_strategies.rst diff --git a/docs/tutorials/further_topics/classification_of_strategies.rst b/docs/tutorials/further_topics/classification_of_strategies.rst new file mode 100644 index 000000000..741eb14c7 --- /dev/null +++ b/docs/tutorials/further_topics/classification_of_strategies.rst @@ -0,0 +1,42 @@ +Classification of strategies +============================ + +Due to the large number of strategies, every class and instance of the class has +a :code:`classifier` attribute which classifies that strategy according to +various dimensions. + +Here is the :code:`classifier` for the :code:`Cooperator` strategy:: + + >>> import axelrod as axl + >>> expected_dictionary = {'manipulates_state': False, 'stochastic': False, 'manipulates_source': False, 'inspects_source': False, 'memory_depth': 0} # Order of this dictionary might be different on your machine + >>> axl.Cooperator.classifier == expected_dictionary + True + +Note that instances of the class also have this classifier:: + + >>> s = axl.Cooperator() + >>> s.classifier == expected_dictionary + True + +This allows us to, for example, quickly identify all the stochastic +strategies:: + + >>> len([s for s in axl.strategies if s().classifier['stochastic']]) + 31 + +Or indeed find out how many strategy have only use 1 turn worth of memory to +make a decision: + + >>> len([s for s in axl.strategies if s().classifier['memory_depth']==1]) + 15 + +Similarly, strategies that :code:`manipulate_source`, :code:`manipulate_state` +and/or :code:`inspect_source` return :code:`False` for the :code:`obey_axelrod` +function:: + + >>> s = axl.MindBender() + >>> axl.obey_axelrod(s) + False + >>> s = axl.TitForTat() + >>> axl.obey_axelrod(s) + True diff --git a/docs/tutorials/further_topics/index.rst b/docs/tutorials/further_topics/index.rst index ed5ee3b78..e60957f58 100644 --- a/docs/tutorials/further_topics/index.rst +++ b/docs/tutorials/further_topics/index.rst @@ -1,8 +1,3 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Further Topics ============== @@ -14,4 +9,5 @@ Contents: .. toctree:: :maxdepth: 2 + classification_of_strategies.rst morality_metrics.rst From 15d7cc22cecfa4b3e5c3ee15526c5a0b7e65e616 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Sun, 18 Oct 2015 22:42:24 +0100 Subject: [PATCH 57/82] Removing indices. --- docs/reference/index.rst | 8 -------- docs/tutorials/index.rst | 8 -------- 2 files changed, 16 deletions(-) diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d7b408eb8..d8a3ff51b 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,11 +9,3 @@ Contents: :maxdepth: 2 overview_of_strategies.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 30c72c8c5..7dce1e7b2 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -17,11 +17,3 @@ Contents: further_topics/index.rst advanced/index.rst contributing/index.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - From 5996fd9c3a6e9d08e49aad3f02e84623ba875ff7 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Mon, 19 Oct 2015 08:35:22 +0100 Subject: [PATCH 58/82] Adding glossary. --- docs/reference/glossary.rst | 56 +++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 2 files changed, 57 insertions(+) create mode 100644 docs/reference/glossary.rst diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst new file mode 100644 index 000000000..78f51e783 --- /dev/null +++ b/docs/reference/glossary.rst @@ -0,0 +1,56 @@ +Glossary +======== + +There are a variety of terms used in the documentation and throughout the +library. Here is an overview: + +An action +--------- + +An **action** is either :code:`C` or :code:`D`. +You can access these actions as follows but should not really have a reason to:: + + >>> import axelrod as axl + >>> axl.Actions.C + 'C' + >>> axl.Actions.D + 'D' + +A play +------ + +A **play** is a single player choosing an **action**. +In terms of code this is equivalent to:: + + >>> p1, p2 = axl.Cooperator(), axl.Defector() + >>> p1.play(p2) # This constitues two 'plays' (p1 plays and p2 plays). + +A turn +------ + +A **turn** is a 1 shot interaction between two players. It is in effect a +composition of two **plays**. + +A match +------- + +A **match** is a consecutive number of **turns**. The default number of turns +used in the tournament is 200. Here is a single match between two players over +10 turns:: + + >>> p1, p2 = axl.Cooperator(), axl.Defector() + >>> for turn in range(10): + ... p1.play(p2) + >>> p1.history, p2.history + (['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C'], ['D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D']) + +A round robin +------------- + +A **round robin** is the set of all potential (order invariant) matches between +a given collection of players. + +A tournament +------------ + +A **tournament** is a repetition of round robins so as to smooth out stochastic effects. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d8a3ff51b..a67deacd3 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,3 +9,4 @@ Contents: :maxdepth: 2 overview_of_strategies.rst + glossary.rst From f242d4381b7ed94c20ad164369027279ae8d5bd1 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 20:07:06 +0100 Subject: [PATCH 59/82] Adding the suggestions from Marc - play(p1) equivalent to play(p2) - Outcomes of a turn --- docs/reference/glossary.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 78f51e783..3c0231bff 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -25,12 +25,18 @@ In terms of code this is equivalent to:: >>> p1, p2 = axl.Cooperator(), axl.Defector() >>> p1.play(p2) # This constitues two 'plays' (p1 plays and p2 plays). +This is equivalent to :code:`p2.play(p1)`. Either function invokes both +:code:`p1.strategy(p2)` and :code:`p2.strategy(p1)`. + A turn ------ A **turn** is a 1 shot interaction between two players. It is in effect a composition of two **plays**. +Each turn has four possible outcomes of a play: :code:`(C, C)`, :code:`(C, D)`, +:code:`(D, C)`, or :code:`(D, D)`. + A match ------- From 5b2afeadcd0df917234b25e1597cecf1162d42fb Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 22:00:24 +0100 Subject: [PATCH 60/82] Adding section about the command line tool. Also minor tidying of other files. --- .../getting_started/command_line.rst | 45 +++++++++++++++++++ docs/tutorials/getting_started/index.rst | 6 +-- .../getting_started/visualising_results.rst | 2 - 3 files changed, 46 insertions(+), 7 deletions(-) create mode 100644 docs/tutorials/getting_started/command_line.rst diff --git a/docs/tutorials/getting_started/command_line.rst b/docs/tutorials/getting_started/command_line.rst new file mode 100644 index 000000000..a068cc6eb --- /dev/null +++ b/docs/tutorials/getting_started/command_line.rst @@ -0,0 +1,45 @@ +Using the command line tool +=========================== + +Once :code:`axelrod` is installed you have access to a `run_axelrod` script that +can help run some of the tournaments, include the tournament that involves all +of the strategies from the library. You can view them on this repository: +`https://github.com/Axelrod-Python/tournament/`_ + +To view the help for the :code:`run_axelrod` file run:: + + $ run_axelrod.py -h + +Note that if you have not installed the package you can still used this script +directly from the repository:: + + $ python run_axelrod -h + +There are a variety of options that include: + +- Excluding certain strategy sets. +- Not running the ecological variant. +- Running the rounds of the tournament in parallel. +- Include background noise + +Particular parameters can also be changed: + +- The output directory for the plot and csv files. +- The number of turns and repetitions for the tournament. + +Here is a command that will run the whole tournament, excluding the strategies +that do not obey Axelrod's original rules and using all available CPUS (this can +take quite a while!):: + + $ run_axelrod --xc -p 0 + +Here are some of the plots that are output when running with the latest total number of strategies: + +The results from the tournament itself (ordered by median score): + +.. image:: http://axelrod-python.github.io/tournament/assets/strategies_boxplot.svg + :width: 50% + :align: center + +This is just a brief overview of what the tool can do, take a look at the help +to see all the options. diff --git a/docs/tutorials/getting_started/index.rst b/docs/tutorials/getting_started/index.rst index b02ad4e02..99cffd34c 100644 --- a/docs/tutorials/getting_started/index.rst +++ b/docs/tutorials/getting_started/index.rst @@ -1,8 +1,3 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Getting Started =============== @@ -19,3 +14,4 @@ Contents: visualising_results.rst noisy_tournaments.rst ecological_variant.rst + command_line.rst diff --git a/docs/tutorials/getting_started/visualising_results.rst b/docs/tutorials/getting_started/visualising_results.rst index afa194a09..26c26629c 100644 --- a/docs/tutorials/getting_started/visualising_results.rst +++ b/docs/tutorials/getting_started/visualising_results.rst @@ -1,8 +1,6 @@ Visualising results =================== -lipsum - This tutorial will show you briefly how to visualise some basic results Visualising the results of the tournament From 07fd6ea836939a56463cf13a451b9a6c8cc38560 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 22:21:17 +0100 Subject: [PATCH 61/82] Tidying of the tutorials structure. --- docs/tutorials/contributing/index.rst | 3 ++- docs/tutorials/contributing/library/index.rst | 15 +++++++++++++++ docs/tutorials/contributing/strategy/index.rst | 17 +++++++++++++++++ .../{ => strategy}/instructions.rst | 2 +- 4 files changed, 35 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/contributing/library/index.rst create mode 100644 docs/tutorials/contributing/strategy/index.rst rename docs/tutorials/contributing/{ => strategy}/instructions.rst (97%) diff --git a/docs/tutorials/contributing/index.rst b/docs/tutorials/contributing/index.rst index 603a8d37a..c7d845a84 100644 --- a/docs/tutorials/contributing/index.rst +++ b/docs/tutorials/contributing/index.rst @@ -15,4 +15,5 @@ Contents: :maxdepth: 2 guidelines.rst - instructions.rst + strategy/index.rst + library/index.rst diff --git a/docs/tutorials/contributing/library/index.rst b/docs/tutorials/contributing/library/index.rst new file mode 100644 index 000000000..d71dcbe6a --- /dev/null +++ b/docs/tutorials/contributing/library/index.rst @@ -0,0 +1,15 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Contributing to the library +=========================== + +This section contains a variety of tutorials that should help you contribute to +the library. + +Contents: + +.. toctree:: + :maxdepth: 2 diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst new file mode 100644 index 000000000..ad697e519 --- /dev/null +++ b/docs/tutorials/contributing/strategy/index.rst @@ -0,0 +1,17 @@ +.. Axelrod documentation master file, created by + sphinx-quickstart on Sat Mar 7 07:05:57 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Contributing a strategy +======================= + +This section contains a variety of tutorials that should help you contribute to +the library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + instructions.rst diff --git a/docs/tutorials/contributing/instructions.rst b/docs/tutorials/contributing/strategy/instructions.rst similarity index 97% rename from docs/tutorials/contributing/instructions.rst rename to docs/tutorials/contributing/strategy/instructions.rst index 6209befa1..a7a4d8c3f 100644 --- a/docs/tutorials/contributing/instructions.rst +++ b/docs/tutorials/contributing/strategy/instructions.rst @@ -46,4 +46,4 @@ To contribute a strategy you need to follow as many of the following steps as po 7. Send us a pull request. **If you would like a hand with any of the above please do get in touch: we're -always delight to have new strategies.** +always delighted to have new strategies.** From afaf49c6bc17927d59abfbf7c724d015c4ca93a6 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Tue, 20 Oct 2015 22:23:52 +0100 Subject: [PATCH 62/82] Removing comment about matplotlib from guidelines. --- docs/tutorials/contributing/guidelines.rst | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/tutorials/contributing/guidelines.rst b/docs/tutorials/contributing/guidelines.rst index 02aa6b84b..30bf7ce79 100644 --- a/docs/tutorials/contributing/guidelines.rst +++ b/docs/tutorials/contributing/guidelines.rst @@ -8,20 +8,14 @@ The project follows the following guidelines: 1. Use the base Python library unless completely necessary. A few external libraries (such as numpy) have been included in requirements.txt -- feel free to use these as needed. -2. If a non base Python library is deemed necessary, it should not hinder the - running or contribution of the package when using the base Python library. For - example, the `matplotlib library `_ is used in a - variety of classes to be able to show results, such as this one: This has been - done carefully with tests that are skipped if the library is not installed and - also without any crashes if something using the library was run. -3. Try as best as possible to follow `PEP8 +2. Try as best as possible to follow `PEP8 `_ which includes **using descriptive variable names**. -4. Testing: the project uses the `unittest +3. Testing: the project uses the `unittest `_ library and has a nice testing suite that makes some things very easy to write tests for. Please try to increase the test coverage on pull requests. -5. Merging pull-requests: We require two of the (currently four) core-team +4. Merging pull-requests: We require two of the (currently four) core-team maintainers to merge (and preferably not the submitted). Opening a PR for early feedback or to check test coverage is OK, just indicate that the PR is not ready to merge (and update when it is). From dc0b98d66bbb204b4df816d89ad4c1ebaba476f0 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 08:30:37 +0100 Subject: [PATCH 63/82] Code highlight for directory. --- docs/tutorials/contributing/strategy/instructions.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/contributing/strategy/instructions.rst b/docs/tutorials/contributing/strategy/instructions.rst index a7a4d8c3f..27a11ed17 100644 --- a/docs/tutorials/contributing/strategy/instructions.rst +++ b/docs/tutorials/contributing/strategy/instructions.rst @@ -39,7 +39,8 @@ To contribute a strategy you need to follow as many of the following steps as po 4. Update :code:`./axelrod/docs/overview_of_strategies.rst` with a description of what the strategy does and include an example of it working. If relevant please also add a source for the strategy (if it is not an original one). -5. This one is optional: write some unit tests in the ./axelrod/tests/ directory. +5. This one is optional: write some unit tests in the :code:`./axelrod/tests/` + directory. 6. This one is also optional: ping us a message and we'll add you to the Contributors team. This would add an Axelrod-Python organisation badge to your profile. From 7ece707c246c081eb7ec4c17bd9de5f88da34398 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 14:58:36 +0100 Subject: [PATCH 64/82] Section on writing strategies - Including a label in classification file. --- .../tutorials/contributing/strategy/index.rst | 1 + .../strategy/writing_the_new_strategy.rst | 112 ++++++++++++++++++ .../classification_of_strategies.rst | 2 + 3 files changed, 115 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/writing_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index ad697e519..2312d4578 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -15,3 +15,4 @@ Contents: :maxdepth: 2 instructions.rst + writing_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst new file mode 100644 index 000000000..131968b1c --- /dev/null +++ b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst @@ -0,0 +1,112 @@ +Writing the new strategy +======================== + +There are a couple of things that need to be created in a strategy.py file. Let +us take a look at the :code:`TitForTat` class (located in the +:code:`axelrod/strategies/titfortat.py` file):: + + class TitForTat(Player): + """ + A player starts by cooperating and then mimics previous move by + opponent. + + Note that the code for this strategy is written in a fairly verbose + way. This is done so that it can serve as an example strategy for + those who might be new to Python. + """ + + # These are various properties for the strategy + name = 'Tit For Tat' + classifier = { + 'memory_depth': 1, # Four-Vector = (1.,0.,1.,0.) + 'stochastic': False, + 'inspects_source': False, + 'manipulates_source': False, + 'manipulates_state': False + } + + def strategy(opponent): + """This is the actual strategy""" + # First move + if len(self.history) == 0: + return C + # React to the opponent's last move + if opponent.history[-1] == D: + return D + return C + +The first thing that is needed is a docstring that explains what the strategy +does:: + + """A player starts by cooperating and then mimics previous move by opponent.""" + +After that simply add in the string that will appear as the name of the +strategy:: + + name = 'Tit For Tat' + +Note that this is mainly used in plots by :code:`matplotlib` so you can use +LaTeX if you want to. For example there is strategy with :math:`\pi` as a +name:: + + name = '$\pi$' + +Following that you can add in the :code:`classifier` dictionary:: + + classifier = { + 'memory_depth': 1, # Four-Vector = (1.,0.,1.,0.) + 'stochastic': False, + 'inspects_source': False, + 'manipulates_source': False, + 'manipulates_state': False + } + +This helps classify the strategy as described in +:ref:`classification-of-strategies`. + +After that the only thing required is to write the :code:`strategy` method +which takes an opponent as an argument. In the case of :code:`TitForTat` the +strategy checks if it has any history (:code:`if len(self.history) == 0`). If +it does not (ie this is the first play of the match) then it returns :code:`C`. +If not, the strategy simply repeats the opponent's last move (:code:`return +opponent.history[-1]`):: + + def strategy(opponent): + """This is the actual strategy""" + # First move + if len(self.history) == 0: + return C + # Repeat the opponent's last move + return opponent.history[-1] + +The variables :code:`C` and :code:`D` represent the cooperate and defect actions respectively. + +If your strategy creates any particular attribute along the way you need to make +sure that there is a :code:`reset` method that takes account of it. An example +of this is the :code:`ForgetfulGrudger` strategy. + +You can also modify the name of the strategy with the `__repr__` method, which +is invoked when `str` is applied to a player instance. For example, the player +`Random` takes a parameter `p` for how often it cooperates, and the `__repr__` +method adds the value of this parameter to the name:: + + def __repr__(self): + return "%s: %s" % (self.name, round(self.p, 2)) + +Now we have separate names for different instantiations:: + + >>> import axelrod + >>> player1 = axelrod.Random(p=0.5) + >>> player2 = axelrod.Random(p=0.1) + >>> player1 + Random: 0.5 + >>> player2 + Random: 0.1 + +This helps distinguish players in tournaments that have multiple instances of the +same strategy. If you modify the `__repr__` method of player, be sure to add an +appropriate test. + +There are various examples of helpful functions and properties that make +writing strategies easier. Do not hesitate to get in touch with the +Axelrod-Python team for guidance. diff --git a/docs/tutorials/further_topics/classification_of_strategies.rst b/docs/tutorials/further_topics/classification_of_strategies.rst index 741eb14c7..b1f11aeca 100644 --- a/docs/tutorials/further_topics/classification_of_strategies.rst +++ b/docs/tutorials/further_topics/classification_of_strategies.rst @@ -1,3 +1,5 @@ +.. _classification-of-strategies: + Classification of strategies ============================ From 410d193ae89d4a1337616dfbcbe2420ce1b08836 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 15:12:44 +0100 Subject: [PATCH 65/82] Section on adding the strategy _strategies.py --- .../strategy/adding_the_new_strategy.rst | 22 +++++++++++++++++++ .../tutorials/contributing/strategy/index.rst | 1 + 2 files changed, 23 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/adding_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/adding_the_new_strategy.rst b/docs/tutorials/contributing/strategy/adding_the_new_strategy.rst new file mode 100644 index 000000000..782ed7556 --- /dev/null +++ b/docs/tutorials/contributing/strategy/adding_the_new_strategy.rst @@ -0,0 +1,22 @@ +Adding the new strategy +======================= + +To get the strategy to be recognised by the library we need to add it to the +files that initialise when someone types :code:`import axelrod`. This is done +in the :code:`axelrod/strategies/_strategies.py` file. + +If you have added your strategy to a file that already existed (perhaps you +added a new variant of :code:`titfortat` to the :code:`titfortat.py` file), +add a line similar to:: + + from import * + +Where :code:`file_name.py` is the name of the file you created. So for the +:code:`TitForTat` strategy which is written in the :code:`titfortat.py` file we +have:: + + from titfortat import * + +Once you have done that (**and you need to do this even if you have added a +strategy to an already existing file**), you need to add the class itself to +the :code:`strategies` list. diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index 2312d4578..e5d43149a 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -16,3 +16,4 @@ Contents: instructions.rst writing_the_new_strategy.rst + adding_the_new_strategy.rst From b1d814f828b04bc5c4231a74434190fcacdc7502 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 16:36:16 +0100 Subject: [PATCH 66/82] Section on classification. --- .../strategy/classifying_the_new_strategy.rst | 44 +++++++++++++++++++ .../tutorials/contributing/strategy/index.rst | 1 + 2 files changed, 45 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst new file mode 100644 index 000000000..87f86f691 --- /dev/null +++ b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst @@ -0,0 +1,44 @@ +Classifying the new strategy +============================ + +Every class has a classifier dictionary that gives some classification of the +strategy according to certain dimensions:: + +Let us take a look at :code:`TitForTat`:: + + >>> classifier = axelrod.TitForTat.classifier + >>> for key in classifier: + .... print key, classifier[key] + manipulates_state False + stochastic False + manipulates_source False + inspects_source False + memory_depth 1 + +You can read more about this in the :ref:`classification-of-strategies` section +but here are some tips about fill this part in correctly. + +Note that when an instance of a class is created it gets it's own copy of the +default classifier dictionary from the class. This might sometimes be modified by +the initialisation depending on input parameters. A good example of this is the +:code:`Joss` strategy:: + + >>> joss = axelrod.Joss() + >>> boring_joss = axelrod.Joss(1) + >>> joss.classifier['stochastic'], boring_joss.classifier['stochastic'] + (True, False) + +Dimensions that are not classified have value `None` in the dictionary. + +There are currently three important dimensions that help identify if a strategy +obeys axelrod's original tournament rules. + +1. :code:`inspects_source` - does the strategy 'read' any source code that + it would not normally have access to. An example of this is :code:`Geller`. +2. :code:`manipulates_source` - does the strategy 'write' any source code that + it would not normally be able to. An example of this is :code:`Mind Bender`. +3. :code:`manipulates_state` - does the strategy 'change' any attributes that + it would not normally be able to. An example of this is :code:`Mind Reader`. + +These dimensions are currently relevant to the `obey_axelrod` strategy which +checks if a strategy obeys Axelrod's original rules. diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index e5d43149a..4663c0f84 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -17,3 +17,4 @@ Contents: instructions.rst writing_the_new_strategy.rst adding_the_new_strategy.rst + classifying_the_new_strategy.rst From 099e48bc36fc39c7555aea3219504eb6feade25e Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:19:25 +0100 Subject: [PATCH 67/82] Section on testing. --- .../tutorials/contributing/strategy/index.rst | 6 +- .../writing_test_for_the_new_strategy.rst | 131 ++++++++++++++++++ 2 files changed, 132 insertions(+), 5 deletions(-) create mode 100644 docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index 4663c0f84..f40bd3909 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -1,8 +1,3 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Contributing a strategy ======================= @@ -18,3 +13,4 @@ Contents: writing_the_new_strategy.rst adding_the_new_strategy.rst classifying_the_new_strategy.rst + writing_test_for_the_new_strategy.rst diff --git a/docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst b/docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst new file mode 100644 index 000000000..93a14da8a --- /dev/null +++ b/docs/tutorials/contributing/strategy/writing_test_for_the_new_strategy.rst @@ -0,0 +1,131 @@ +Writing tests for the new strategy +================================== + +To write tests you either need to create a file called :code:`test_.py` +where :code:`.py` is the name of the file you have created or similarly +add tests to the test file that is already present in the +:code:`axelrod/tests/unit/` directory. + +As an example, the tests for Tit-For-Tat are as follows:: + + import axelrod + + from test_player import TestPlayer + + C, D = axelrod.Actions.C, axelrod.Actions.D + + class TestTitForTat(TestPlayer): + + name = "Tit For Tat" + player = axelrod.TitForTat + expected_classifier = { + 'memory_depth': 1, + 'stochastic': False, + 'inspects_source': False, + 'manipulates_source': False, + 'manipulates_state': False + } + + def test_strategy(self): + """Starts by cooperating.""" + P1 = axelrod.TitForTat() + P2 = axelrod.Player() + self.assertEqual(P1.strategy(P2), C) + + def test_effect_of_strategy(self): + """ + Repeats last action of opponent history + """ + P1 = axelrod.TitForTat() + P2 = axelrod.Player() + P2.history = [C, C, C, C] + self.assertEqual(P1.strategy(P2), C) + P2.history = [C, C, C, C, D] + self.assertEqual(P1.strategy(P2), D) + +The :code:`test_effect_of_strategy` method mainly checks that the +:code:`strategy` method in the :code:`TitForTat` class works as expected: + +1. If the opponent's last strategy was :code:`C`: then :code:`TitForTat` should + cooperate:: + + P2.history = ['C', 'C', 'C', 'C'] + self.assertEqual(P1.strategy(P2), 'C') + +2. If the opponent's last strategy was :code:`D`: then :code:`TitForTat` should + defect:: + + P2.history = ['C', 'C', 'C', 'C', 'D'] + self.assertEqual(P1.strategy(P2), 'D') + +We have added some convenience member functions to the :code:`TestPlayer` class. +All three of these functions can take an optional keyword argument +:code:`random_seed` (useful for stochastic strategies). + +1. The member function :code:`first_play_test` tests the first strategy, e.g.:: + + def test_strategy(self): + self.first_play_test('C') + + This is equivalent to:: + + def test_effect_of_strategy(self): + P1 = axelrod.TitForTat() # Or whatever player is in your test class + P2 = axelrod.Player() + P2.history = [] + P2.history = [] + self.assertEqual(P1.strategy(P2), 'C') + +2. The member function :code:`markov_test` takes a list of four plays, each + following one round of CC, CD, DC, and DD respectively:: + + def test_effect_of_strategy(self): + self.markov_test(['C', 'D', 'D', 'C']) + + This is equivalent to:: + + def test_effect_of_strategy(self): + P1 = axelrod.TitForTat() # Or whatever player is in your test class + P2 = axelrod.Player() + P2.history = ['C'] + P2.history = ['C'] + self.assertEqual(P1.strategy(P2), 'C') + P2.history = ['C'] + P2.history = ['D'] + self.assertEqual(P1.strategy(P2), 'D') + P2.history = ['D'] + P2.history = ['C'] + self.assertEqual(P1.strategy(P2), 'D') + P2.history = ['D'] + P2.history = ['D'] + self.assertEqual(P1.strategy(P2), 'C') + +3. The member function :code:`responses_test` takes arbitrary histories for each + player and tests a list of expected next responses:: + + def test_effect_of_strategy(self): + self.responses_test([C], [C], [D, C, C, C], random_seed=15) + + In this case each player has their history set to :code:`[C]` and the + expected responses are D, C, C, C. Note that the histories will elongate as + the responses accumulated. + +Finally, there is a :code:`TestHeadsUp` class that streamlines the testing of +two strategies playing each other using a test function :code:`versus_test`. For +example, to test several rounds of play of Tit-For-Two-Tats versus Bully:: + + class TestTF2TvsBully(TestHeadsUp): + """Test Tit for Two Tats vs Bully""" + def test_rounds(self): + outcomes = [[C, D], [C, D], [D, D], [D, C], [C, C], [C, D], [C, D], [D, D]] + self.versus_test(axelrod.TitFor2Tats, axelrod.Bully, outcomes) + +The function :code:`versus_test` also accepts a :code:`random_seed` keyword, and +like :code:`responses_test` the history is accumulated. + +The :code:`expected_classifier` dictionary tests that the classification of the +strategy is as expected (the tests for this is inherited in the :code:`init` +method). Please be sure to classify new strategies according to the already +present dimensions but if you create a new dimension you do not **need** to re +classify all the other strategies (but feel free to! :)), but please do add it +to the :code:`default_classifier` in the :code:`axelrod/player.py` parent class. From 23c1e830ab82dc0d8061828d2533d7601367b55f Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:53:25 +0100 Subject: [PATCH 68/82] Adding section about identify new strategies. --- .../strategy/writing_the_new_strategy.rst | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst index 131968b1c..b525aece4 100644 --- a/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst +++ b/docs/tutorials/contributing/strategy/writing_the_new_strategy.rst @@ -1,6 +1,30 @@ Writing the new strategy ======================== +Identify a new strategy +----------------------- + +The library has a large number of strategies:: + + >>> import axelrod as axl + >>> len(axl.strategies) + 103 + +If you're not sure if you have a strategy that has already been implemented +please get in touch: `via the gitter room +`_ or `open an issue +`_. + +Several strategies are special cases of other strategies. For example, both +`Cooperator` and `Defector` are special cases of `Random`, `Random(1)` and +`Random(0)` respectively. While we could eliminate `Cooperator` in its current +form, these strategies are intentionally left as is as simple examples for new +users and contributors. Nevertheless, please feel free to update the docstrings +of strategies like `Random` to point out such cases. + +The code +-------- + There are a couple of things that need to be created in a strategy.py file. Let us take a look at the :code:`TitForTat` class (located in the :code:`axelrod/strategies/titfortat.py` file):: From bad60728162247bf894a00285b3a5b263313b6ec Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:53:48 +0100 Subject: [PATCH 69/82] Adding section on tests. --- .../tutorials/contributing/strategy/index.rst | 1 + .../contributing/strategy/running_tests.rst | 30 +++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/running_tests.rst diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index f40bd3909..266097f18 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -14,3 +14,4 @@ Contents: adding_the_new_strategy.rst classifying_the_new_strategy.rst writing_test_for_the_new_strategy.rst + running_tests.rst diff --git a/docs/tutorials/contributing/strategy/running_tests.rst b/docs/tutorials/contributing/strategy/running_tests.rst new file mode 100644 index 000000000..936cb9e24 --- /dev/null +++ b/docs/tutorials/contributing/strategy/running_tests.rst @@ -0,0 +1,30 @@ +Running tests +============= + +The project has an extensive test suite which is run each time a new +contribution is made to the repository. If you want to check that all the tests +pass before you submit a pull request you can run the tests yourself:: + + $ python -m unittest discover + +If you are developing new tests for the suite, it is useful to run a single test +file so that you don't have to wait for the entire suite each time. For +example, to run only the tests for the Grudger strategy:: + + $ python -m unittest axelrod.tests.unit.test_grudger + +The test suite is divided into two categories: unit tests and integration tests. +Each can be run individually:: + + $ python -m unittest discover -s axelrod.tests.unit + $ python -m unittest discover -s axelrod.tests.integration + +Furthermore the documentation is also doctested, to run those tests you can run +the script:: + + $ sh doctest + +Note that this project is being taken care off by `travis-ci +`_, so all tests will be run automatically when opening +a pull request. You can see the latest build status `here +`_. From ff436a896e4a47722a81fe8630c8aeeb2965bb85 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:54:15 +0100 Subject: [PATCH 70/82] Fixing broken doctest. --- .../contributing/strategy/classifying_the_new_strategy.rst | 3 ++- doctest | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst index 87f86f691..10d4cba53 100644 --- a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst +++ b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst @@ -6,9 +6,10 @@ strategy according to certain dimensions:: Let us take a look at :code:`TitForTat`:: + >>> import axelrod >>> classifier = axelrod.TitForTat.classifier >>> for key in classifier: - .... print key, classifier[key] + ... print key, classifier[key] manipulates_state False stochastic False manipulates_source False diff --git a/doctest b/doctest index 7def29b5f..daea869e5 100755 --- a/doctest +++ b/doctest @@ -2,3 +2,4 @@ python -m doctest docs/tutorials/getting_started/*rst python -m doctest docs/tutorials/further_topics/*rst python -m doctest docs/reference/*rst +python -m doctest docs/tutorials/contributing/strategy/*rst From a00afc5376141a4ba09c4bc4072e2ff7d5620e91 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 21:58:04 +0100 Subject: [PATCH 71/82] Writing small section about general contributions. --- docs/tutorials/contributing/library/index.rst | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/tutorials/contributing/library/index.rst b/docs/tutorials/contributing/library/index.rst index d71dcbe6a..797691ea8 100644 --- a/docs/tutorials/contributing/library/index.rst +++ b/docs/tutorials/contributing/library/index.rst @@ -1,15 +1,9 @@ -.. Axelrod documentation master file, created by - sphinx-quickstart on Sat Mar 7 07:05:57 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Contributing to the library =========================== -This section contains a variety of tutorials that should help you contribute to -the library. - -Contents: +All contributions (docs, tests, etc) are very welcome, if there is a specific +functionality that you would like to add the please open an issue (or indeed +take a look at the ones already there and jump in the conversation!). -.. toctree:: - :maxdepth: 2 +If you want to work on documentation please keep in mind that doctests are +encouraged to help keep the documentation up to date. From b589c3544f599ceb697761e5121bcea4b5b14031 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 22:04:49 +0100 Subject: [PATCH 72/82] Removing test script. --- test | 3 --- 1 file changed, 3 deletions(-) delete mode 100755 test diff --git a/test b/test deleted file mode 100755 index ed49bd58a..000000000 --- a/test +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env bash -python -m unittest discover axelrod/tests/ -./doctest From 33f1d4942d30708777e7086764fa0287855652ea Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 22:08:48 +0100 Subject: [PATCH 73/82] Fixing broken doctests. --- .../tutorials/further_topics/classification_of_strategies.rst | 4 ++-- docs/tutorials/getting_started/ecological_variant.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/further_topics/classification_of_strategies.rst b/docs/tutorials/further_topics/classification_of_strategies.rst index b1f11aeca..42ffe2d94 100644 --- a/docs/tutorials/further_topics/classification_of_strategies.rst +++ b/docs/tutorials/further_topics/classification_of_strategies.rst @@ -27,10 +27,10 @@ strategies:: 31 Or indeed find out how many strategy have only use 1 turn worth of memory to -make a decision: +make a decision:: >>> len([s for s in axl.strategies if s().classifier['memory_depth']==1]) - 15 + 13 Similarly, strategies that :code:`manipulate_source`, :code:`manipulate_state` and/or :code:`inspect_source` return :code:`False` for the :code:`obey_axelrod` diff --git a/docs/tutorials/getting_started/ecological_variant.rst b/docs/tutorials/getting_started/ecological_variant.rst index a51b4c62b..df8f2900f 100644 --- a/docs/tutorials/getting_started/ecological_variant.rst +++ b/docs/tutorials/getting_started/ecological_variant.rst @@ -16,7 +16,7 @@ ecosystem based on the payoff matrix of a tournament:: Here is how we obtain a nice stackplot of the system evolving over time:: >>> plot = axl.Plot(results) - >>> p = plot.stackplot(eco.population_sizes) + >>> p = plot.stackplot(eco) >>> p.show() .. image:: _static/visualising_results/demo_strategies_stackplot.svg From 976224a6d9b451ae817f015ff65ef462a41d12e4 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Wed, 21 Oct 2015 22:31:53 +0100 Subject: [PATCH 74/82] Fixing doctest for py3. --- .../strategy/classifying_the_new_strategy.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst index 10d4cba53..79d5ae41e 100644 --- a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst +++ b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst @@ -9,12 +9,12 @@ Let us take a look at :code:`TitForTat`:: >>> import axelrod >>> classifier = axelrod.TitForTat.classifier >>> for key in classifier: - ... print key, classifier[key] - manipulates_state False - stochastic False - manipulates_source False - inspects_source False - memory_depth 1 + ... print(key, classifier[key]) + ('manipulates_state', False) + ('stochastic', False) + ('manipulates_source', False) + ('inspects_source', False) + ('memory_depth', 1) You can read more about this in the :ref:`classification-of-strategies` section but here are some tips about fill this part in correctly. From b594dad394c1dff388d155b28b93e90d5e92fffa Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Thu, 22 Oct 2015 08:55:55 +0100 Subject: [PATCH 75/82] Fixing the test again. Ordering keys so won't have a problem with order of hash. --- .../strategy/classifying_the_new_strategy.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst index 79d5ae41e..c831db87d 100644 --- a/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst +++ b/docs/tutorials/contributing/strategy/classifying_the_new_strategy.rst @@ -8,13 +8,13 @@ Let us take a look at :code:`TitForTat`:: >>> import axelrod >>> classifier = axelrod.TitForTat.classifier - >>> for key in classifier: - ... print(key, classifier[key]) - ('manipulates_state', False) - ('stochastic', False) - ('manipulates_source', False) - ('inspects_source', False) - ('memory_depth', 1) + >>> for key in sorted(classifier.keys()): + ... print("{}: {}".format(key, classifier[key])) + inspects_source: False + manipulates_source: False + manipulates_state: False + memory_depth: 1 + stochastic: False You can read more about this in the :ref:`classification-of-strategies` section but here are some tips about fill this part in correctly. From a3a5b2831f4347c270e9e9ca7b786cfca56ed8e8 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Thu, 22 Oct 2015 21:08:43 +0100 Subject: [PATCH 76/82] Various fixes pointed out by Owen - Adding '2 round from end' for Backstabber and Doublecrosser. - Correct tense in getting started. - Correct spelling of persistent. - Fix include to including. - Spelling of used to use. --- docs/reference/overview_of_strategies.rst | 5 +++-- docs/tutorials/getting_started/command_line.rst | 4 ++-- docs/tutorials/getting_started/getting_started.rst | 4 ++-- docs/tutorials/getting_started/noisy_tournaments.rst | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/reference/overview_of_strategies.rst b/docs/reference/overview_of_strategies.rst index 539026208..533e90c9e 100644 --- a/docs/reference/overview_of_strategies.rst +++ b/docs/reference/overview_of_strategies.rst @@ -998,14 +998,15 @@ Backstabber ^^^^^^^^^^^ Forgives the first 3 defections but on the fourth will defect forever. Defects -after the 198th round unconditionally. +unconditionally on the last 2 rounds (depending on the tournament length). DoubleCrosser ^^^^^^^^^^^^^ Forgives the first 3 defections but on the fourth will defect forever. If the opponent did not defect in the first 6 rounds the player will cooperate until -the 180th round. Defects after the 198th round unconditionally. +the 180th round. Defects unconditionally on the last 2 rounds (depending on the +tournament length). Aggravater ^^^^^^^^^^ diff --git a/docs/tutorials/getting_started/command_line.rst b/docs/tutorials/getting_started/command_line.rst index a068cc6eb..c5db2b629 100644 --- a/docs/tutorials/getting_started/command_line.rst +++ b/docs/tutorials/getting_started/command_line.rst @@ -2,7 +2,7 @@ Using the command line tool =========================== Once :code:`axelrod` is installed you have access to a `run_axelrod` script that -can help run some of the tournaments, include the tournament that involves all +can help run some of the tournaments, including the tournament that involves all of the strategies from the library. You can view them on this repository: `https://github.com/Axelrod-Python/tournament/`_ @@ -10,7 +10,7 @@ To view the help for the :code:`run_axelrod` file run:: $ run_axelrod.py -h -Note that if you have not installed the package you can still used this script +Note that if you have not installed the package you can still use this script directly from the repository:: $ python run_axelrod -h diff --git a/docs/tutorials/getting_started/getting_started.rst b/docs/tutorials/getting_started/getting_started.rst index 1ee21a446..8f8a40dc6 100644 --- a/docs/tutorials/getting_started/getting_started.rst +++ b/docs/tutorials/getting_started/getting_started.rst @@ -34,8 +34,8 @@ The following lines of code create a simple list of strategies:: >>> strategies [Cooperator, Defector, Tit For Tat, Grudger] -We can now create a tournament, play it, saving the results and viewing the -ranks of each player:: +We can now create a tournament, play it, save the results and view the rank of +each player:: >>> tournament = axl.Tournament(strategies) >>> results = tournament.play() diff --git a/docs/tutorials/getting_started/noisy_tournaments.rst b/docs/tutorials/getting_started/noisy_tournaments.rst index a55234bce..0fa59ec39 100644 --- a/docs/tutorials/getting_started/noisy_tournaments.rst +++ b/docs/tutorials/getting_started/noisy_tournaments.rst @@ -6,7 +6,7 @@ stochasticity in the choice of plays, simply called noise. This noise is introduced by flipping plays between ‘C’ and ‘D’ with some probability that is applied to all plays after they are delivered by the player. -The presence of this persistant bakground noise causes some strategies to +The presence of this persistent background noise causes some strategies to behave substantially differently. For example, TitForTat can fall into defection loops with itself when there is noise. While TitForTat would usually cooperate well with itself:: From 68cbbedbca9625f2143dcdb74d35bf664d2cc8d1 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Thu, 22 Oct 2015 21:21:51 +0100 Subject: [PATCH 77/82] Going with is variety. --- docs/tutorials/getting_started/command_line.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/getting_started/command_line.rst b/docs/tutorials/getting_started/command_line.rst index c5db2b629..fe08e3c5e 100644 --- a/docs/tutorials/getting_started/command_line.rst +++ b/docs/tutorials/getting_started/command_line.rst @@ -15,7 +15,7 @@ directly from the repository:: $ python run_axelrod -h -There are a variety of options that include: +There is a variety of options that include: - Excluding certain strategy sets. - Not running the ecological variant. From 70c7461ee1cf83041339c68025f4cb879ad74a69 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Thu, 22 Oct 2015 21:46:04 +0100 Subject: [PATCH 78/82] Adding missing graphs and violin plots as required. --- .../demo_deterministic_strategies_boxplot.svg | 1218 +++++++++++ .../demo_strategies_boxplot.svg | 1860 ++++++++++++----- 2 files changed, 2596 insertions(+), 482 deletions(-) create mode 100644 docs/tutorials/getting_started/_static/getting_started/demo_deterministic_strategies_boxplot.svg diff --git a/docs/tutorials/getting_started/_static/getting_started/demo_deterministic_strategies_boxplot.svg b/docs/tutorials/getting_started/_static/getting_started/demo_deterministic_strategies_boxplot.svg new file mode 100644 index 000000000..a42d8a023 --- /dev/null +++ b/docs/tutorials/getting_started/_static/getting_started/demo_deterministic_strategies_boxplot.svg @@ -0,0 +1,1218 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg index 3b2d4a97b..6e0f144d4 100644 --- a/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg +++ b/docs/tutorials/getting_started/_static/visualising_results/demo_strategies_boxplot.svg @@ -2,7 +2,7 @@ - + - + @@ -638,14 +1547,14 @@ z - + - + - + - + @@ -696,7 +1605,7 @@ Q26.2656 6.10938 33.4062 6.10938 Q40.5312 6.10938 44.6094 11.75 Q48.6875 17.3906 48.6875 27.2969" id="BitstreamVeraSans-Roman-70"/> - + @@ -711,14 +1620,14 @@ Q48.6875 17.3906 48.6875 27.2969" id="BitstreamVeraSans-Roman-70"/> - + - + - + - + @@ -863,7 +1772,7 @@ L10.6875 0 z " id="BitstreamVeraSans-Roman-2e"/> - + @@ -878,39 +1787,27 @@ z - - - - - - - - - - - - - + - + - + - + @@ -941,7 +1838,7 @@ L8.20312 64.5938 z " id="BitstreamVeraSans-Roman-37"/> - + @@ -949,14 +1846,14 @@ z - + - + - + - + @@ -999,7 +1896,7 @@ Q38.1406 66.4062 31.7812 66.4062 Q25.3906 66.4062 21.8438 63.2344 Q18.3125 60.0625 18.3125 54.3906" id="BitstreamVeraSans-Roman-38"/> - + @@ -1007,14 +1904,14 @@ Q18.3125 60.0625 18.3125 54.3906" id="BitstreamVeraSans-Roman-38"/> - + - + - + - + @@ -1049,7 +1946,7 @@ Q16.2188 57.2812 16.2188 49.4219 Q16.2188 41.5 20.0938 36.9531 Q23.9688 32.4219 30.6094 32.4219" id="BitstreamVeraSans-Roman-39"/> - + @@ -1057,14 +1954,14 @@ Q23.9688 32.4219 30.6094 32.4219" id="BitstreamVeraSans-Roman-39"/> - + - + - + - + @@ -1094,7 +1991,7 @@ Q49.8594 40.875 45.4062 35.4062 Q44.1875 33.9844 37.6406 27.2188 Q31.1094 20.4531 19.1875 8.29688" id="BitstreamVeraSans-Roman-32"/> - + @@ -1102,19 +1999,19 @@ Q31.1094 20.4531 19.1875 8.29688" id="BitstreamVeraSans-Roman-32"/> - + - + - + - + - + @@ -1122,19 +2019,19 @@ Q31.1094 20.4531 19.1875 8.29688" id="BitstreamVeraSans-Roman-32"/> - + - + - + - + - + @@ -1142,14 +2039,14 @@ Q31.1094 20.4531 19.1875 8.29688" id="BitstreamVeraSans-Roman-32"/> - + - + - + - + @@ -1187,7 +2084,7 @@ Q53.9062 64.0156 53.9062 55.3281 Q53.9062 49.2656 50.4375 45.0938 Q46.9688 40.9219 40.5781 39.3125" id="BitstreamVeraSans-Roman-33"/> - + @@ -1195,14 +2092,14 @@ Q46.9688 40.9219 40.5781 39.3125" id="BitstreamVeraSans-Roman-33"/> - + - + - + - + @@ -1228,7 +2125,7 @@ L4.89062 26.7031 z " id="BitstreamVeraSans-Roman-34"/> - + @@ -1236,19 +2133,19 @@ z - + - + - + - + - + @@ -1256,14 +2153,14 @@ z - + - + - + - + @@ -1298,7 +2195,7 @@ Q23.3906 74.2188 37.2031 74.2188 Q40.9219 74.2188 44.7031 73.4844 Q48.4844 72.75 52.5938 71.2969" id="BitstreamVeraSans-Roman-36"/> - + @@ -1307,7 +2204,7 @@ Q48.4844 72.75 52.5938 71.2969" id="BitstreamVeraSans-Roman-36"/> - + - + @@ -1427,52 +2324,51 @@ Q40.5781 54.5469 44.2812 53.0781" id="BitstreamVeraSans-Roman-73"/> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + From 04a1fdd12019ef427c3af6f465a2ec61366da3f8 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Thu, 22 Oct 2015 21:47:06 +0100 Subject: [PATCH 79/82] Removing lipsum. --- docs/tutorials/getting_started/getting_started.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/tutorials/getting_started/getting_started.rst b/docs/tutorials/getting_started/getting_started.rst index 8f8a40dc6..25af0e135 100644 --- a/docs/tutorials/getting_started/getting_started.rst +++ b/docs/tutorials/getting_started/getting_started.rst @@ -1,9 +1,6 @@ Getting started =============== -lipsum - - Installation ------------ From 32b74f88ab6ae29f92b97486a03091453967d493 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Thu, 22 Oct 2015 21:49:19 +0100 Subject: [PATCH 80/82] Adding seentence about no stochastic effect. --- docs/tutorials/getting_started/getting_started.rst | 6 +++++- docs/tutorials/getting_started/visualising_results.rst | 2 ++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/getting_started/getting_started.rst b/docs/tutorials/getting_started/getting_started.rst index 25af0e135..587b746db 100644 --- a/docs/tutorials/getting_started/getting_started.rst +++ b/docs/tutorials/getting_started/getting_started.rst @@ -39,7 +39,7 @@ each player:: >>> results.ranked_names ['Defector', 'Tit For Tat', 'Grudger', 'Cooperator'] -We can also plot these results (which helps visualise the stochastic effects):: +We can also plot these results:: >>> plot = axl.Plot(results) >>> p = plot.boxplot() @@ -48,3 +48,7 @@ We can also plot these results (which helps visualise the stochastic effects):: .. image:: _static/getting_started/demo_deterministic_strategies_boxplot.svg :width: 50% :align: center + +Note that in this case none of our strategies are stochastic so the boxplot +shows that there is no variation. Take a look at the :ref:`visualising-results` +section to see plots showing a stochastic effect. diff --git a/docs/tutorials/getting_started/visualising_results.rst b/docs/tutorials/getting_started/visualising_results.rst index 26c26629c..0a3e4328e 100644 --- a/docs/tutorials/getting_started/visualising_results.rst +++ b/docs/tutorials/getting_started/visualising_results.rst @@ -1,3 +1,5 @@ +.. _visualising-results: + Visualising results =================== From 39865141164dfdb49c83b1aa8507a405ebccc810 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 23 Oct 2015 17:25:29 +0100 Subject: [PATCH 81/82] Adding definition of a win to glossary. --- docs/reference/glossary.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 3c0231bff..1726c003a 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -50,6 +50,12 @@ used in the tournament is 200. Here is a single match between two players over >>> p1.history, p2.history (['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C'], ['D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D']) +A win +----- + +A **win** is the positive outcome of a match. For the example above, +:code:`Defector` would win that match. + A round robin ------------- From ad5c4c444d3681ca15f7a5cebbab679fb2935698 Mon Sep 17 00:00:00 2001 From: Vince Knight Date: Fri, 23 Oct 2015 17:58:05 +0100 Subject: [PATCH 82/82] Better definition of win --- docs/reference/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 1726c003a..9ba02e7c4 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -53,8 +53,8 @@ used in the tournament is 200. Here is a single match between two players over A win ----- -A **win** is the positive outcome of a match. For the example above, -:code:`Defector` would win that match. +A **win** is attributed to the player who has the higher total score at the end +of a match. For the example above, :code:`Defector` would win that match. A round robin -------------