Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Streamline the README #1072

Merged
merged 5 commits into from
Jul 19, 2017
Merged

Streamline the README #1072

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d6378b0
Streamline the README.
drvinceknight Jun 19, 2017
729e99a
Add some plots.
drvinceknight Jun 19, 2017
e5d367d
Include quick start.
drvinceknight Jul 16, 2017
72e3d6b
Address Marc's comments
drvinceknight Jul 17, 2017
f907123
Improve size and alignement of images.
drvinceknight Jul 17, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 60 additions & 93 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
Axelrod
=======

Goals
-----

A Python library with the following principles and goals:

1. Enabling the reproduction of previous Iterated Prisoner's Dilemma research
Expand All @@ -26,66 +29,67 @@ A Python library with the following principles and goals:
4. Emphasizing readability along with an open and welcoming community that
is accommodating for developers and researchers of a variety of skill levels.

Currently the library contains well over 150 strategies including classics such
as Tit-For-Tat (TFT) and Win-Stay-Lose-Shift (WSLS), recent variants including
zero-determinant strategies, and a variety of novel strategies including several
machine-learning based strategies. Many strategies are parameterized, allowing
for infinitely-many variations. We welcome new strategies and additions from the
literature: see `#379 <https://github.com/Axelrod-Python/Axelrod/issues/379>`_
for a list of known strategies and sources.

With these strategies the library and can perform head-to-head Matches, a
variety of tournament types (RoundRobin, Noisy, Spatially-distributed, and
probabilistically ending) and population dynamics including the Moran process
on graphs, while taking advantage of multi-core processors.

The library emphasizes reproducibility and validity. The current test suite
covers more than 99% of all code in the library, with many portions covered many
times over, including `randomly generated tests
<https://github.com/HypothesisWorks/hypothesis-python>`_ that are created and
run regularly.

**Please contribute via pull request (or just get in touch with us).**

For an overview of how to use and contribute to this repository, see the
documentation: http://axelrod.readthedocs.org/

If you do use this library for your personal research we would love to hear
about it: please do add a link at the bottom of this README file (PR's welcome
or again, just let us know) :) If there is something that is missing in this
library and that you would like implemented so as to be able to carry out a
project please open an issue and let us know!
Features
--------

With Axelrod you:

- have access `to over 200 strategies
<http://axelrod.readthedocs.io/en/stable/reference/all_strategies.html>`_, including original and classics like Tit
For Tat and Win Stay Lose Shift. These are extendable through parametrization
and a collection of strategy transformers.
- can create `head to head matches
<http://axelrod.readthedocs.io/en/stable/tutorials/getting_started/match.html>`_ between pairs of strategies.
- can create `tournaments
<http://axelrod.readthedocs.io/en/stable/tutorials/getting_started/tournament.html>`_ over a number of strategies.
- can study population dynamics through `Moran processes
<http://axelrod.readthedocs.io/en/stable/tutorials/getting_started/moran.html>`_ and an `infinite
population model
<http://axelrod.readthedocs.io/en/stable/tutorials/further_topics/ecological_variant.html>`_.
- can analyse detailed `results of tournaments
<http://axelrod.readthedocs.io/en/stable/tutorials/getting_started/summarising_tournaments.html>`_ and matches.
- can `visualise results
<http://axelrod.readthedocs.io/en/stable/tutorials/getting_started/visualising_results.html>`_ of tournaments.

.. image:: http://axelrod.readthedocs.io/en/stable/_images/demo_strategies_boxplot.svg
:height: 300 px
:align: center

- can reproduce a number of contemporary research topics such as `fingerprinting <http://axelrod.readthedocs.io/en/stable/tutorials/further_topics/fingerprinting.html>`_ of
strategies and `morality metrics
<http://axelrod.readthedocs.io/en/stable/tutorials/further_topics/morality_metrics.html>`_.

.. image:: https://github.com/Axelrod-Python/Axelrod-fingerprint/raw/master/assets/Tricky_Defector.png
:height: 300 px
:align: center

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

`An open reproducible framework for the study of the iterated prisoner's
dilemma <http://openresearchsoftware.metajnl.com/article/10.5334/jors.125/>`_:
a peer reviewed paper introducing the library (22 authors).

Installation
============
------------

The library requires Python 3.4 or greater. It will not run on Python 2.

The simplest way to install is::

$ pip install axelrod

Otherwise::
To install from source::

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

Note that on Ubuntu `some
users <https://github.com/Axelrod-Python/Axelrod/issues/309>`_ have had problems
installing matplotlib. This seems to help with that::
Quick Start
-----------

sudo apt-get install libfreetype6-dev
sudo apt-get install libpng12-0-dev

Usage
-----

The full documentation can be found here:
`axelrod.readthedocs.org/ <http://axelrod.readthedocs.org/>`__.

The documentation includes details of how to setup a tournament but here is a
brief example showing how to get a simple tournament::
The following runs a basic tournament::

>>> import axelrod as axl
>>> axl.seed(0) # Set a seed
Expand All @@ -96,66 +100,29 @@ brief example showing how to get a simple tournament::
['Defector', 'Grudger', 'Tit For Tat', 'Cooperator', 'Random: 0.5']


There is also a `notebooks repository
<https://github.com/Axelrod-Python/Axelrod-notebooks>`_ which shows further
examples of using the library.

Results
=======

A tournament with the full set of strategies from the library can be found at
https://github.com/Axelrod-Python/tournament. These results can be easily viewed
at http://axelrod-tournament.readthedocs.org.
Examples
--------

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

Contributing
============
------------

All contributions are welcome!

You can find helpful instructions about contributing in the
documentation:
http://axelrod.readthedocs.org/en/latest/tutorials/contributing/index.html

Example notebooks
=================

https://github.com/Axelrod-Python/Axelrod-notebooks contains a set of example
Jupyter notebooks.

Projects that use this library
==============================

If you happen to use this library for anything from a blog post to a research
paper please list it here:

- `A 2015 pedagogic paper on active learning
<https://github.com/drvinceknight/Playing-games-a-case-study-in-active-learning>`_
by `drvinceknight <https://github.com/drvinceknight>`_ published in `MSOR
Connections <https://journals.gre.ac.uk/index.php/msor/about>`_: the library
is mentioned briefly as a way of demonstrating repeated games.
- `A repository with various example tournaments and visualizations of strategies
<https://github.com/marcharper/AxelrodExamples>`_
by `marcharper <https://github.com/marcharper>`_.
- `Axelrod-Python related blog articles
<http://www.thomascampbell.me.uk/category/axelrod.html>`_
by `Uglyfruitcake <https://github.com/uglyfruitcake>`_.
- `Evolving strategies for an Iterated Prisoner's Dilemma tournament
<http://mojones.net/evolving-strategies-for-an-iterated-prisoners-dilemma-tournament.html>`_
by `mojones <https://github.com/mojones>`_.
- `An Exploratory Data Analysis of the Iterated Prisoner's Dilemma, Part I
<http://marcharper.codes/2015-11-16/ipd.html>`_ and `Part II <http://marcharper.codes/2015-11-17/ipd2.html>`_
by `marcharper <https://github.com/marcharper>`_.
- `Survival of the fittest: Experimenting with a high performing strategy in
other environments
<http://vknight.org/unpeudemath/gametheory/2015/11/28/Experimenting-with-a-high-performing-evolved-strategy-in-other-environments.html>`_
by `drvinceknight <https://github.com/drvinceknight>`_
- `An open reproducible framework for the study of the iterated prisoner's
dilemma <https://arxiv.org/abs/1604.00896>`_: a pre print of a paper describing this
library (20 authors).

Contributors
============
------------

The library has had many awesome contributions from many `great
contributors <https://github.com/Axelrod-Python/Axelrod/graphs/contributors>`_.
Expand Down