ENH: Add GamPayoffVector

oyamad · oyamad · commit d5cd93bc83ae · 2026-02-19T16:34:34.000+09:00
diff --git a/quantecon/game_theory/game_converters.py b/quantecon/game_theory/game_converters.py
@@ -4,7 +4,7 @@
 Examples
 --------
 
-Create a QuantEcon NormalFormGame from a gam file storing
+Create a QuantEcon NormalFormGame from a .gam file storing
 a 3-player Minimum Effort Game
 
 >>> import os
@@ -27,10 +27,133 @@
   [[-19., -19.,   1.],   [ -8.,  -8.,   2.],   [  3.,   3.,   3.]]]]
 
 """
+import numbers
 import numpy as np
 from .normal_form_game import Player, NormalFormGame
 
 
+class GamPayoffVector:
+    """
+    Internal intermediate representation that stores payoffs in a single
+    flat 1-dim array.
+
+    Payoff values are ordered as in the GameTracer .gam format:
+    1. Player-major blocks: player 0, ..., player N-1.
+    2. Within each block, action profiles are ordered with player 0
+       varying fastest, then player 1, ..., player N-1 (i.e.,
+       Fortran/column-major order).
+
+    Attributes
+    ----------
+    N : scalar(int)
+        Number of players.
+
+    nums_actions : tuple(int)
+        Tuple of the numbers of actions, one for each player.
+
+    payoffs : ndarray(ndim=1)
+        Array storing payoffs in .gam order.
+
+    """
+    def __init__(self, nums_actions, payoffs):
+        nums_actions = tuple(nums_actions)
+        if len(nums_actions) == 0:
+            raise ValueError('nums_actions must be a non-empty iterable ' +
+                             'of positive integers')
+
+        for n in nums_actions:
+            if not isinstance(n, numbers.Integral):
+                raise TypeError('nums_actions must contain only integers')
+            if n <= 0:
+                raise ValueError('all nums_actions must be positive')
+
+        self.nums_actions = tuple(int(n) for n in nums_actions)
+        self.N = len(self.nums_actions)
+
+        payoffs = np.ascontiguousarray(payoffs)
+        if payoffs.ndim != 1:
+            raise ValueError('payoffs must be a 1-dim array_like')
+
+        expected = np.prod(self.nums_actions) * self.N
+        if payoffs.size != expected:
+            raise ValueError(
+                f'payoffs length mismatch: expected {expected}, ' +
+                f'got {payoffs.size}'
+            )
+
+        self.payoffs = payoffs
+
+    @classmethod
+    def from_nfg(cls, g, dtype=None):
+        """
+        Construct a GamPayoffVector from a NormalFormGame `g`.
+
+        Examples
+        --------
+        >>> player0 = Player([[0, 3], [1, 4], [2, 5]])
+        >>> player1 = Player([[6, 7, 8], [9, 10, 11]])
+        >>> g = NormalFormGame((player0, player1))
+        >>> print(g)
+        2-player NormalFormGame with payoff profile array:
+        [[[ 0,  6],  [ 3,  9]],
+         [[ 1,  7],  [ 4, 10]],
+         [[ 2,  8],  [ 5, 11]]]
+        >>> p = GamPayoffVector.from_nfg(g)
+        >>> p.payoffs
+        array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11])
+
+        """
+        N = g.N
+        nums_actions = g.nums_actions
+        if dtype is None:
+            dtype = g.dtype
+
+        na = np.prod(nums_actions)
+        payoffs = np.empty(na*N, dtype=dtype)
+
+        for i, player in enumerate(g.players):
+            payoffs[na*i:na*(i+1)].reshape(nums_actions, order='F')[:] = \
+                player.payoff_array.transpose(
+                    (*range(N-i, g.N), *range(N-i))
+                )
+
+        return cls(nums_actions, payoffs)
+
+    def to_nfg(self, dtype=None):
+        """
+        Construct a NormalFormGame from self.
+
+        Examples
+        --------
+        >>> nums_actions = (3, 2)
+        >>> payoffs = np.arange(12)
+        >>> p = GamPayoffVector(nums_actions, payoffs)
+        >>> g = p.to_nfg()
+        >>> print(g)
+        2-player NormalFormGame with payoff profile array:
+        [[[ 0,  6],  [ 3,  9]],
+         [[ 1,  7],  [ 4, 10]],
+         [[ 2,  8],  [ 5, 11]]]
+
+        """
+        N = self.N
+        nums_actions = self.nums_actions
+
+        na = np.prod(nums_actions)
+        payoffs2d = self.payoffs.reshape((na, N), order='F')
+        players = tuple(
+            Player(
+                np.asarray(
+                    payoffs2d[:, i].reshape(nums_actions, order='F').transpose(
+                        (*range(i, N), *range(i))
+                    ), dtype=dtype, order='C'
+                )
+            ) for i in range(N)
+        )
+
+        return NormalFormGame(players)
+
+
 def _str2num(s):
     """
     Convert string to appropriate numeric type.
@@ -52,27 +175,27 @@ def _str2num(s):
 
 class GAMReader:
     """
-    Reader object that converts a game in GameTracer gam format into
+    Reader object that converts a game in GameTracer .gam format into
     a NormalFormGame.
 
     """
     @classmethod
     def from_file(cls, file_path):
         """
-        Read from a gam format file.
+        Read from a .gam format file.
 
         Parameters
         ----------
         file_path : str
-            Path to gam file.
+            Path to .gam file.
 
         Returns
         -------
         NormalFormGame
 
         Examples
         --------
-        Save a gam format string in a temporary file:
+        Save a .gam format string in a temporary file:
 
         >>> import tempfile
         >>> fname = tempfile.mkstemp()[1]
@@ -111,12 +234,12 @@ def from_url(cls, url):
     @classmethod
     def from_string(cls, string):
         """
-        Read from a gam format string.
+        Read from a .gam format string.
 
         Parameters
         ----------
         string : str
-            String in gam format.
+            String in .gam format.
 
         Returns
         -------
@@ -163,13 +286,13 @@ def _parse(string):
 class GAMWriter:
     """
     Writer object that converts a NormalFormgame into a game in
-    GameTracer gam format.
+    GameTracer .gam format.
 
     """
     @classmethod
     def to_file(cls, g, file_path):
         """
-        Save the GameTracer gam format string representation of the
+        Save the GameTracer .gam format string representation of the
         NormalFormGame `g` to a file.
 
         Parameters
@@ -186,7 +309,7 @@ def to_file(cls, g, file_path):
     @classmethod
     def to_string(cls, g):
         """
-        Return a GameTracer gam format string representing the
+        Return a GameTracer .gam format string representing the
         NormalFormGame `g`.
 
         Parameters
@@ -196,7 +319,7 @@ def to_string(cls, g):
         Returns
         -------
         str
-            String representation in gam format.
+            String representation in .gam format.
 
         """
         return cls._dump(g)
@@ -218,19 +341,19 @@ def _dump(g):
 
 def from_gam(filename: str) -> NormalFormGame:
     """
-    Makes a QuantEcon Normal Form Game from a gam file.
+    Makes a QuantEcon Normal Form Game from a .gam file.
 
     Gam files are described by GameTracer [1]_.
 
     Parameters
     ----------
     filename : str
-        path to gam file.
+        path to .gam file.
 
     Returns
     -------
     NormalFormGame
-        The QuantEcon Normal Form Game described by the gam file.
+        The QuantEcon Normal Form Game described by the .gam file.
 
     References
     ----------
@@ -243,7 +366,7 @@ def from_gam(filename: str) -> NormalFormGame:
 
 def to_gam(g, file_path=None):
     """
-    Write a NormalFormGame to a file in gam format.
+    Write a NormalFormGame to a file in .gam format.
 
     Parameters
     ----------
diff --git a/quantecon/game_theory/tests/test_game_converters.py b/quantecon/game_theory/tests/test_game_converters.py
@@ -4,10 +4,108 @@
 """
 import os
 from tempfile import NamedTemporaryFile
-from numpy.testing import assert_string_equal
-from quantecon.game_theory import NormalFormGame, GAMWriter, to_gam
+import numpy as np
+from numpy.testing import (
+    assert_, assert_array_equal, assert_string_equal, assert_raises
+)
+from quantecon.game_theory import (
+    Player, NormalFormGame, random_game, GAMWriter, to_gam
+)
+from quantecon.game_theory.game_converters import GamPayoffVector
 
 
+# GamPayoffVector #
+
+class TestGamPayoffVector:
+    """Golden test for GamPayoffVector"""
+
+    def setup_method(self):
+        nums_actions = (2, 3, 4)
+        N = len(nums_actions)
+        na = np.prod(nums_actions)
+
+        A0 = np.arange(na).reshape(nums_actions, order='F')
+        A1 = np.arange(100, 100+na).reshape(nums_actions, order='F')
+        A2 = np.arange(200, 200+na).reshape(nums_actions, order='F')
+
+        self.payoffs1d = np.hstack([A.ravel(order='F') for A in [A0, A1, A2]])
+        self.payoffs4d = np.stack([A0, A1, A2], axis=N)
+
+        self.N = N
+        self.nums_actions = nums_actions
+
+    def test_init(self):
+        p = GamPayoffVector(self.nums_actions, self.payoffs1d)
+
+        assert_(p.N == self.N)
+        assert_(p.nums_actions == self.nums_actions)
+        assert_array_equal(p.payoffs, self.payoffs1d)
+
+    def test_from_nfg(self):
+        g = NormalFormGame(self.payoffs4d)
+        p = GamPayoffVector.from_nfg(g)
+
+        assert_(p.N == self.N)
+        assert_(p.nums_actions == self.nums_actions)
+        assert_array_equal(p.payoffs, self.payoffs1d)
+
+    def test_to_nfg(self):
+        p = GamPayoffVector(self.nums_actions, self.payoffs1d)
+        g = p.to_nfg()
+        assert_array_equal(g.payoff_profile_array, self.payoffs4d)
+
+
+def test_gampayoffvector_roundtrip():
+    for ns in [(4, 3), (2, 2, 3, 2)]:
+        N = len(ns)
+        seed = 12345
+        rng = np.random.default_rng(seed)
+        payoffs = rng.integers(low=0, high=100, size=(*ns, N), dtype=np.int64)
+        g = NormalFormGame(payoffs)
+        p = GamPayoffVector.from_nfg(g)
+        g1 = p.to_nfg()
+
+        p_32 = GamPayoffVector.from_nfg(g, dtype=np.int32)
+        g2 = p_32.to_nfg()
+        g3 = p_32.to_nfg(dtype=np.int64)
+
+        assert_(p_32.payoffs.dtype == np.int32)
+        assert_(g2.dtype == np.int32)
+        assert_(g3.dtype == np.int64)
+
+        for g_new in [g1, g2, g3]:
+            assert_(g_new.N == g.N)
+            assert_(g_new.nums_actions == g.nums_actions)
+            for i in range(N):
+                assert_array_equal(g_new.players[i].payoff_array,
+                                   g.players[i].payoff_array)
+
+
+def test_gampayoffvector_1p():
+    payoffs = [1., 2., 3.]
+    nums_actions = (3,)
+
+    p0 = GamPayoffVector(nums_actions, payoffs)
+
+    g = NormalFormGame((Player(payoffs),))
+    p1 = GamPayoffVector.from_nfg(g)
+
+    for p in [p0, p1]:
+        assert_(p.N == 1)
+        assert_(p.nums_actions == nums_actions)
+        assert_array_equal(p.payoffs, payoffs)
+
+
+def test_invalid_inputs():
+    assert_raises(ValueError, GamPayoffVector, (), np.array([], dtype=float))
+    assert_raises(TypeError, GamPayoffVector, (2, 2.0), np.zeros(8))
+    assert_raises(ValueError, GamPayoffVector, (2, 0), np.zeros(0))
+    assert_raises(ValueError, GamPayoffVector, (2, 2), np.zeros((2, 4)))
+    assert_raises(ValueError, GamPayoffVector, (2, 2), np.zeros(7))
+
+
+# TestGAMWriter #
+
 class TestGAMWriter:
     def setup_method(self):
         nums_actions = (2, 2, 2)
