Merge pull request #687 from marcharper/docs

Docs and such

Author: meatballs

README.rst

@@ -15,15 +15,24 @@
 Axelrod
 =======
 
-A repository with the following goals:
+A library with the following principles and goals:
 
-1. To enable the reproduction of previous Iterated Prisoner's Dilemma research as easily as possible.
-2. To produce the de-facto tool for any future Iterated Prisoner's Dilemma research.
-3. To provide as simple a means as possible for anyone to define and contribute
+1. Enabling the reproduction of previous Iterated Prisoner's Dilemma research
+as easily as possible.
+2. Creating the de-facto tool for future Iterated Prisoner's Dilemma
+research.
+3. Providing as simple a means as possible for anyone to define and contribute
    new and original Iterated Prisoner's Dilemma strategies.
+4. Emphasizing readability along with an open and welcoming community that
+is accommodating for developers and researchers of a variety of skill levels
 
-**Please contribute strategies via pull request (or just get in touch
-with us).**
+Currently the library contains well over 100 strategies and can perform a
+variety of tournament types (RoundRobin, Noisy, Spatially-distributed, and
+probabilistically ending) and population dynamics while taking advantage
+of multi-core processors.
+
+
+**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/
@@ -91,8 +100,7 @@ at http://axelrod-tournament.readthedocs.org.
 Contributing
 ============
 
-All contributions are welcome, with a particular emphasis on
-contributing further strategies.
+All contributions are welcome!
 
 You can find helpful instructions about contributing in the
 documentation:

axelrod/_strategy_utils.py

@@ -15,7 +15,7 @@ def detect_cycle(history, min_size=1, offset=0):
     Mainly used by hunter strategies.
 
     Parameters
-
+    ----------
     history: sequence of C and D
         The sequence to look for cycles within
     min_size: int, 1
@@ -83,7 +83,7 @@ def look_ahead(player_1, player_2, game, rounds=10):
 
 
 class Memoized(object):
-    """Decorator. Caches a function's return value each time it is called.
+    """Decorator that caches a function's return value each time it is called.
     If called later with the same arguments, the cached value is returned
     (not reevaluated). From:
     https://wiki.python.org/moin/PythonDecoratorLibrary#Memoize

axelrod/actions.py

@@ -10,4 +10,4 @@ def flip_action(action):
     elif action == Actions.D:
         return Actions.C
     else:
-        raise ValueError("Encountered a invalid action")
+        raise ValueError("Encountered a invalid action.")

axelrod/deterministic_cache.py

@@ -144,5 +144,4 @@ def load(self, file_name):
         else:
             raise ValueError(
                 'Cache file exists but is not the correct format. Try deleting and re-building the cache file.')
-
         return True

axelrod/ecosystem.py

@@ -11,13 +11,13 @@ def __init__(self, results, fitness=None, population=None):
         self.payoff_matrix = self.results.payoff_matrix
         self.payoff_stddevs = self.results.payoff_stddevs
 
-        # Population sizes will be recorded in this nested list, with each internal
-        # list containing strategy populations for a given turn. The first list,
-        # representing the starting populations, will by default have all equal
-        # values, and all population lists will be normalized to one.
-        # An initial population vector can also be passed. This will be
-        # normalised, but must be of the correct size and have all
-        # non-negative values.
+        # Population sizes will be recorded in this nested list, with each
+        # internal list containing strategy populations for a given turn. The
+        # first list, representing the starting populations, will by default
+        # have all equal values, and all population lists will be normalized to
+        # one. An initial population vector can also be passed. This will be
+        # normalised, but must be of the correct size and have all non-negative
+        # values.
         if population:
             if min(population) < 0:
                 raise TypeError("Minimum value of population vector must be non-negative")
@@ -29,8 +29,8 @@ def __init__(self, results, fitness=None, population=None):
         else:
             self.population_sizes = [[1.0 / self.nplayers for i in range(self.nplayers)]]
 
-        # This function is quite arbitrary and probably only influences the kinetics
-        # for the current code.
+        # This function is quite arbitrary and probably only influences the
+        # kinetics for the current code.
         if fitness:
             self.fitness = fitness
         else:
@@ -43,11 +43,12 @@ def reproduce(self, turns):
             plist = list(range(self.nplayers))
             pops = self.population_sizes[-1]
 
-            # The unit payoff for each player in this turn is the sum of the payoffs
-            # obtained from playing with all other players, scaled by the size of the
-            # opponent's population. Note that we sample the normal distribution
-            # based on the payoff matrix and its standard deviations obtained from
-            # the iterated PD tournament run previously.
+            # The unit payoff for each player in this turn is the sum of the
+            # payoffs obtained from playing with all other players, scaled by
+            # the size of the opponent's population. Note that we sample the
+            # normal distribution based on the payoff matrix and its standard
+            # deviations obtained from the iterated PD tournament run
+            # previously.
             payoffs = [0 for ip in plist]
             for ip in plist:
                 for jp in plist:
@@ -56,9 +57,10 @@ def reproduce(self, turns):
                     p = random.normalvariate(avg, dev)
                     payoffs[ip] += p * pops[jp]
 
-            # The fitness should determine how well a strategy reproduces. The new populations
-            # should be multiplied by something that is proportional to the fitness, but we are
-            # normalizing anyway so just multiply times fitness.
+            # The fitness should determine how well a strategy reproduces. The
+            # new populations should be multiplied by something that is
+            # proportional to the fitness, but we are normalizing anyway so
+            # just multiply times fitness.
             fitness = [self.fitness(p) for p in payoffs]
             newpops = [p * f for p, f in zip(pops, fitness)]
 

axelrod/game.py

@@ -15,7 +15,8 @@ def __init__(self, r=3, s=0, t=5, p=1):
         }
 
     def RPST(self):
-        """Return the values in the game matrix in the Press and Dyson notation."""
+        """Return the values in the game matrix in the Press and Dyson
+        notation."""
         R = self.scores[(C, C)][0]
         P = self.scores[(D, D)][0]
         S = self.scores[(C, D)][0]

axelrod/match.py

@@ -26,14 +26,14 @@ def __init__(self, players, turns, game=None, deterministic_cache=None,
             The number of turns per match
         game : axelrod.Game
             The game object used to score the match
-        deterministic_cache : dictionary
+        deterministic_cache : axelrod.DeterministicCache
             A cache of resulting actions for deterministic matches
         noise : float
             The probability that a player's intended action should be flipped
         match_attributes : dict
             Mapping attribute names to values which should be passed to players.
             The default is to use the correct values for turns, game and noise
-            but these can be overidden if desired.
+            but these can be overridden if desired.
         """
         self.result = []
         self.turns = turns
@@ -78,7 +78,7 @@ def players(self, players):
     def _stochastic(self):
         """
         A boolean to show whether a match between two players would be
-        stochastic
+        stochastic.
         """
         return is_stochastic(self.players, self.noise)
 

axelrod/random_.py

@@ -24,7 +24,7 @@ def randrange(a, b):
     return a + int(r)
 
 
-def seed(seed):
+def seed(seed_):
     """Sets a seed"""
-    random.seed(seed)
-    numpy.random.seed(seed)
+    random.seed(seed_)
+    numpy.random.seed(seed_)

axelrod/result_set.py

@@ -296,8 +296,8 @@ def build_payoffs(self):
 
             [uij1, uij2, ..., uijk]
 
-            Where k is the number of repetitions and uijk is the list of utilities
-            obtained by player i against player j in each repetition.
+            Where k is the number of repetitions and uijk is the list of
+            utilities obtained by player i against player j in each repetition.
         """
         plist = list(range(self.nplayers))
         payoffs = [[[] for opponent in plist] for player in plist]

axelrod/strategy_transformers.py

@@ -66,13 +66,14 @@ def __call__(self, PlayerClass):
             Returns
             -------
             new_class, class object
-                A class object that can create instances of the modified PlayerClass
+                A class object that can create instances of the modified
+                PlayerClass
             """
 
             args = self.args
             kwargs = self.kwargs
             try:
-            #if "name_prefix" in kwargs remove as only want dec arguments
+                # if "name_prefix" in kwargs remove as only want dec arguments
                 del kwargs["name_prefix"]
             except KeyError:
                 pass