Added player assumption classification

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+   configuration: docs/conf.py
+
+python:
+   install:
+   - requirements: docs/requirements.txt

axelrod/classifier.py

@@ -72,6 +72,7 @@ def classify_player(self, player: Type[Player]) -> T:
 manipulates_state = Classifier[Optional[bool]](
     "manipulates_state", lambda _: None
 )
+assumptions = Classifier[Optional[dict]]("assumptions", lambda _: {'actions_size': 2})
 
 # Should list all known classifiers.
 all_classifiers = [
@@ -82,6 +83,7 @@ def classify_player(self, player: Type[Player]) -> T:
     inspects_source,
     manipulates_source,
     manipulates_state,
+    assumptions,
 ]
 
 all_classifiers_map = {c.name: c.classify_player for c in all_classifiers}

axelrod/game.py

@@ -17,10 +17,13 @@ class AsymmetricGame(object):
     ----------
     scores: dict
         The numerical score attribute to all combinations of action pairs.
+    attributes: dict
+        A dictionary of attributes of the game. Used to ensure strategies
+        used with the game are valid.
     """
 
     # pylint: disable=invalid-name
-    def __init__(self, A: np.array, B: np.array) -> None:
+    def __init__(self, A: np.array, B: np.array, **characteristics) -> None:
         """
         Creates an asymmetric game from two matrices.
 
@@ -30,6 +33,9 @@ def __init__(self, A: np.array, B: np.array) -> None:
             the payoff matrix for player A.
         B: np.array
             the payoff matrix for player B.
+        **characteristics
+            optional characteristics detailing features of the game. Used
+            to ensure strategies used with the game are valid.
         """
 
         if A.shape != B.transpose().shape:
@@ -41,6 +47,8 @@ def __init__(self, A: np.array, B: np.array) -> None:
         self.A = A
         self.B = B
 
+        self.characteristics = characteristics
+
         self.scores = {
             pair: self.score(pair) for pair in ((C, C), (D, D), (C, D), (D, C))
         }
@@ -75,6 +83,27 @@ def get_value(x):
 
         return (self.A[row][col], self.B[row][col])
 
+    @property
+    def characteristics(self):
+        return self._characteristics
+
+    @characteristics.setter
+    def characteristics(self, characteristics):
+        """
+        Adds or changes game characteristics.
+
+        Parameters
+        ----------
+        characteristics: dict
+            characteristics to add to the game. If the added
+            characteristic already exists, it will overwrite the
+            previous value.
+        """
+        try:
+            self._characteristics = {**self._characteristics, **characteristics}
+        except AttributeError:
+            self._characteristics = characteristics
+
     def __repr__(self) -> str:
         return "Axelrod game with matrices: {}".format((self.A, self.B))
 
@@ -97,7 +126,7 @@ class Game(AsymmetricGame):
         The numerical score attribute to all combinations of action pairs.
     """
 
-    def __init__(self, r: Score = 3, s: Score = 0, t: Score = 5, p: Score = 1) -> None:
+    def __init__(self, r: Score = 3, s: Score = 0, t: Score = 5, p: Score = 1, **characteristics) -> None:
         """Create a new game object.
 
         Parameters
@@ -110,10 +139,14 @@ def __init__(self, r: Score = 3, s: Score = 0, t: Score = 5, p: Score = 1) -> No
             Score obtained by a player for defecting against a cooperator.
         p: int or float
             Score obtained by both player for mutual defection.
+        **attributes
+            optional attributes for the game. Used
+            to ensure strategies used with the game are valid.
+
         """
         A = np.array([[r, s], [t, p]])
 
-        super().__init__(A, A.transpose())
+        super().__init__(A, A.transpose(), **characteristics)
 
     def RPST(self) -> Tuple[Score, Score, Score, Score]:
         """Returns game matrix values in Press and Dyson notation."""
@@ -132,4 +165,4 @@ def __eq__(self, other):
         return self.RPST() == other.RPST()
 
 
-DefaultGame = Game()
+DefaultGame = Game(3, 0, 5, 1, game_type='prisoners_dilemma')

axelrod/match.py

@@ -30,6 +30,7 @@ def __init__(
         match_attributes=None,
         reset=True,
         seed=None,
+        strict_player_checking=True
     ):
         """
         Parameters
@@ -54,6 +55,9 @@ def __init__(
             Whether to reset players or not
         seed : int
             Random seed for reproducibility
+        strict_player_checking: bool, default True
+            If True, throws an error if strategies make assumptions which aren't
+            compatible with the game. if False, just produces warnings instead.
         """
 
         defaults = {
@@ -89,6 +93,7 @@ def __init__(
         else:
             self.match_attributes = match_attributes
 
+        self.strict_player_checking = strict_player_checking
         self.players = list(players)
         self.reset = reset
 
@@ -111,6 +116,14 @@ def players(self):
     def players(self, players):
         """Ensure that players are passed the match attributes"""
         newplayers = []
+        # ensure the game satisfies the player assumptions
+        # note the game size characteristic is added here because the player
+        # and coplayer may have different game sizes if the game is asymmetric!
+        players[0].check_assumptions({**self.game.characteristics, 'actions_size': self.game.A.shape[0]},
+                                      raise_error=self.strict_player_checking)
+        players[1].check_assumptions({**self.game.characteristics, 'actions_size': self.game.B.shape[0]},
+                                      raise_error=self.strict_player_checking)
+
         for player in players:
             player.set_match_attributes(**self.match_attributes)
             newplayers.append(player)

axelrod/mock_player.py

@@ -8,18 +8,31 @@
 
 
 class MockPlayer(Player):
-    """Creates a mock player that plays a given sequence of actions. If
-    no actions are given, plays like Cooperator. Used for testing.
+    """Creates a mock player that cycles through a given 
+    sequence of actions. If no actions are given, 
+    plays like Cooperator. Used for testing.
+
+    Parameters
+    ----------
+    actions: List[Action], default []
+        The sequence of actions played by the mock player.
+    attributes: dict, default {}
+        A dictionary of player attributes.
     """
 
     name = "Mock Player"
 
-    def __init__(self, actions: List[Action] = None) -> None:
+    def __init__(self, actions: List[Action] = None, classifier: dict = None) -> None:
         super().__init__()
         if not actions:
             actions = []
         self.actions = cycle(actions)
 
+        if not classifier:
+            self.classifier = {}
+        else:
+            self.classifier = classifier
+
     def strategy(self, opponent: Player) -> Action:
         # Return the next saved action, if present.
         try:

axelrod/player.py

@@ -258,6 +258,64 @@ def reset(self):
     def update_history(self, play, coplay):
         self.history.append(play, coplay)
 
+    def check_assumptions(self, game_characteristics: dict, raise_error: bool=True):
+        """
+        Compares the player assumptions to a dictionary of game characteristics.
+        Generates a warning or error if an assumption is not fulfilled.
+
+        Parameters:
+        -----------
+        game_characteristics: dict
+            The dictionary of game characteristics to compare the player's assumptions to.
+        raise_error: bool, default True
+            If True, raises an error if the assumption is violated. Else,
+            just generate a warning.
+        """
+
+        for key, value in self.classifier.get('assumptions', {}).items():
+            msg = None
+            if key not in game_characteristics.keys():
+                msg = ("Player {} assumes that "
+                       "the game has the attribute {}, "
+                       "but the game does not declare this attribute."
+                       "".format(self.name, key))
+            elif value != game_characteristics[key]:
+                msg = ("Player {} assumes that the game attribute "
+                       "{} is set to {}, but it is actually set to {}."
+                       "".format(self.name, key, value, game_characteristics[key]))
+
+            if msg is not None:
+                if raise_error:
+                    raise RuntimeError(msg)
+                warnings.warn(msg + " The strategy may not behave as expected.")
+
+    def assumptions_satisfy(self, game_characteristics: dict) -> bool:
+        """
+        Compares the player assumptions to a dictionary of game characteristics.
+        Returns True if the player assumptions are all satisfied by
+        these characteristics, and False otherwise.
+
+        Parameters:
+        -----------
+        game_characteristics: dict
+            The dictionary of game characteristics to compare the player's assumptions to.
+
+        Returns
+        -------
+        bool
+            A boolean of whether or not the game characteristics satisfy the player's
+            assumptions.
+        """
+
+        # we use check_assumptions as our 'base' rather than the other way
+        # around as check_assumptions needs finer grained understanding of
+        # the assumptions to produce useful error messages
+        try:
+            self.check_assumptions(game_characteristics, raise_error=True)
+        except RuntimeError:
+            return False
+        return True
+
     @property
     def history(self):
         return self._history

axelrod/tests/strategies/test_player.py

@@ -347,6 +347,42 @@ def test_init_kwargs(self):
             TypeError, ParameterisedTestPlayer, "other", "other", "other"
         )
 
+    def test_assumption_checking(self):
+        """
+        Checks that assumptions are checked, and warnings
+        or errors are raised when they're unfulfilled.
+        """
+        player = axl.MockPlayer(classifier={'assumptions': {'foo': True, 'bar': 3}})
+
+        # these should pass without errors/warnings
+        player.check_assumptions({'foo': True, 'bar': 3})  # correct characteristics
+        player.check_assumptions({'foo': True, 'bar': 3, 'baz': []})  # extraneous characteristic
+
+        with self.assertRaises(RuntimeError):
+            player.check_assumptions({'foo': True})  # missing characteristic
+        with self.assertRaises(RuntimeError):
+            player.check_assumptions({'foo': True, 'bar': 5})  # invalid charateristic value
+
+        with self.assertWarns(UserWarning):
+            player.check_assumptions({'foo': True}, raise_error=False)  # missing characteristic
+        with self.assertWarns(UserWarning):
+            player.check_assumptions({'foo': True, 'bar': 5}, raise_error=False)  # invalid charateristic value
+
+    def test_assumptions_satisfy(self):
+        """
+        Tests that the assumptions_satisfy() method works as intended.
+        It is a wrapper around check_assumptions() so the actual assumption
+        testing logic is checked more thoroughly there.
+        """
+        player = axl.MockPlayer(classifier={'assumptions': {'foo': True, 'bar': 3}})
+
+        self.assertEqual(player.assumptions_satisfy({'foo': True, 'bar': 3}), True)  # correct characteristics
+        self.assertEqual(player.assumptions_satisfy({'foo': True, 'bar': 3, 'baz': []}), True)  # extraneous characteristic
+        self.assertEqual(player.assumptions_satisfy({'foo': True}), False)  # missing characteristic
+        self.assertEqual(player.assumptions_satisfy({'foo': True, 'bar': 5}), False)  # invalid charateristic value
+
+
+
 
 class TestOpponent(axl.Player):
     """A player who only exists so we have something to test against"""

axelrod/tests/unit/test_match.py

@@ -3,9 +3,10 @@
 
 import axelrod as axl
 from axelrod.deterministic_cache import DeterministicCache
+from axelrod.mock_player import MockPlayer
 from axelrod.random_ import RandomGenerator
-from axelrod.tests.property import games
-from hypothesis import example, given
+from axelrod.tests.property import games, asymmetric_games
+from hypothesis import example, given, settings
 from hypothesis.strategies import floats, integers
 
 C, D = axl.Action.C, axl.Action.D
@@ -354,6 +355,18 @@ def test_sparklines(self):
         expected_sparklines = "XXXX\nXYXY"
         self.assertEqual(match.sparklines("X", "Y"), expected_sparklines)
 
+    @given(game=asymmetric_games(), n1=integers(min_value=2), n2=integers(min_value=2))
+    @settings(max_examples=5)
+    def test_game_size_checking(self, game, n1, n2):
+        """Tests warnings, errors or normal flow agrees with player action size."""
+        player1 = MockPlayer(classifier={'assumptions': {'actions_size': n1}})
+        player2 = MockPlayer(classifier={'assumptions': {'actions_size': n2}})
+
+        if (n1 != game.A.shape[0] or n2 != game.B.shape[0]):
+            with self.assertRaises(RuntimeError):
+                match = axl.Match((player1, player2), game=game)
+        else:
+            match = axl.Match((player1, player2), game=game)
 
 class TestSampleLength(unittest.TestCase):
     def test_sample_length(self):

docs/requirements.txt

@@ -1 +1,2 @@
 docutils <= 0.17  # Added this for a problem with sphinx https://github.com/sphinx-doc/sphinx/commit/13803a79e7179f40a27f46d5a5a05f1eebbcbb63
+numpy==1.24.3  # numpy isn't mocked due to complex use in doctests

docs/tutorials/implement_new_games/index.rst

@@ -124,6 +124,7 @@ an initialisation parameter for which move they start with::
     ...         "inspects_source": False,
     ...         "manipulates_source": False,
     ...         "manipulates_state": False,
+    ...         "assumptions": {"actions_size": 3},
     ...     }
     ...     
     ...     def __init__(self, starting_move=S):
@@ -153,6 +154,7 @@ an initialisation parameter for which move they start with::
     ...         "inspects_source": False,
     ...         "manipulates_source": False,
     ...         "manipulates_state": False,
+    ...         "assumptions": {"actions_size": 3},
     ...     }
     ...     
     ...     def __init__(self, starting_move=S):
@@ -165,6 +167,11 @@ an initialisation parameter for which move they start with::
     ...             return self.starting_move
     ...         return self.history[-1].rotate()
 
+Note that in the classifier for each strategy we set 'actions_size' to `3`. This
+is how we let Axelrod know that this strategy is expecting to have 3 possible actions,
+and when a match is created, it will check to make sure that this assumption is
+satisfied by the game.
+
 We are now all set to run some matches and tournaments in our new game!
 Let's start with a match between our two new players::