Skip to content

Commit

Permalink
Merge pull request #1072 from Axelrod-Python/readme-revamp
Browse files Browse the repository at this point in the history 
Streamline the README
  • Loading branch information
@meatballs
meatballs authored Jul 19, 2017
2 parents 602c8e9 + f907123 commit f78e017
Showing 1 changed file with 60 additions and 93 deletions.
153 changes: 60 additions & 93 deletions README.rst
View file
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

0 comments on commit f78e017

Please sign in to comment.