Modify the documentation.

Author: drvinceknight

docs/how-to/index.rst

@@ -24,6 +24,7 @@ with the Axelrod library.
    use_parallel_processing.rst
    use_a_cache.rst
    use_different_stage_games.rst
+   use_custom_matches.rst
    set_a_seed.rst
    set_player_information.rst
    check_player_equality.rst

docs/how-to/use_custom_matches.rst

@@ -0,0 +1,22 @@
+.. _use-custom-matches:
+
+Use custom matches
+==================
+
+At present it is possible to use a custom match class in a Moran process. Below
+creates a new class of a match where both players end with a score of 2::
+
+
+    >>> import axelrod as axl
+    >>> class MassBaseMatch(axl.Match):
+    ...     """Axelrod Match object with a modified final score function to enable mass to influence the final score as a multiplier"""
+    ...     def final_score_per_turn(self):
+    ...         return 2, 2
+
+We can now create a Moran process like we normally would and pass our custom :code:`MassBaseMatch` to the moran process with the :code:`match_class` keyword argument::
+
+    >>> players = [axl.Cooperator(), axl.Defector(), axl.TitForTat(), axl.Grudger()]
+    >>> mp = axl.MoranProcess(players=players, match_class=MassBaseMatch, seed=0)
+    >>> population = mp.play()
+    >>> print(mp.winning_strategy_name)
+    Defector

docs/tutorials/creating_heterogenous_player_moran_process/index.rst

@@ -0,0 +1,65 @@
+.. _create-heterogeneous-moran-processes:
+
+Create heterogeneous Moran Processes
+====================================
+
+Axelrod Matches are homogeneous by nature but can be extended to utilize
+additional attributes of heterogeneous players. This tutorial indicates how the
+Axelrod :code:`Match` class can be manipulated in order to play heterogeneous
+tournaments and Moran processes using mass as a score modifier similarly to the
+work of [Krapohl2020]_.
+
+The following lines of code creates a list of players from the available demo
+strategies along with an ascending list of masses we will use for the players.
+This is equivalent in principle to the country masses discussed in
+[Krapohl2020]_::
+
+    >>> import axelrod as axl
+    >>> players = [player() for player in axl.demo_strategies]
+    >>> masses = [1 * i for i in range(len(players))]
+    >>> players
+    [Cooperator, Defector, Tit For Tat, Grudger, Random: 0.5]
+
+Using the :code:`setattr()` function, additional attributes can be passed to
+players to enable access during matches and tournaments without manual
+modification of individual strategies::
+
+    >>> def set_player_mass(players, masses):
+    ...     """Add mass attribute to player strategy classes to be accessable via self.mass"""
+    ...     for player, mass in zip(players, masses):
+    ...         setattr(player, "mass", mass)
+    ...
+    >>> set_player_mass(players, masses)
+
+The :code:`Match` class can be partially altered to enable different behaviour
+(see :ref:`use-custom-matches`_).
+Here we extend :code:`axl.Match` and overwrite its
+:code:`final_score_per_turn()` function to utilize the player mass attribute as
+a multiplier for the final score::
+
+    >>> class MassBaseMatch(axl.Match):
+    ...     """Axelrod Match object with a modified final score function to enable mass to influence the final score as a multiplier"""
+    ...     def final_score_per_turn(self):
+    ...         base_scores = axl.Match.final_score_per_turn(self)
+    ...         return [player.mass * score for player, score in zip(self.players, base_scores)] 
+
+In [Krapohl2020]_ a non standard Moran process is used where the mass of
+individuals is not reproduced so we will use inheritance to create a new Moran
+process that keeps the mass of the individuals constant::
+
+    >>> class MassBasedMoranProcess(axl.MoranProcess):
+    ...     """Axelrod MoranProcess class """
+    ...     def __next__(self):
+    ...         set_player_mass(self.players, masses)
+    ...         super().__next__()
+    ...         return self
+
+    >>> mp = MassBasedMoranProcess(players, match_class=MassBaseMatch, seed=0)
+    >>> populations = mp.play()
+    >>> print(mp.winning_strategy_name)
+    Random: 0.5
+
+Note that the snippets here only influence the final score of matches. The
+behavior of matches,  and moran processes can be more heavily influenced by
+partially overwriting other :code:`match` functions or :code:`birth` and
+:code:`death` functions within :code:`MoranProcess`.

docs/tutorials/index.rst

@@ -12,3 +12,4 @@ Contents:
 
    new_to_game_theory_and_or_python/index.rst
    running_axelrods_first_tournament/index.rst
+   creating_heterogenous_player_moran_process/index.rst