ENH: Implement pure strategy node reachability check (#632)

This adds a property which checks whether a node is reachable by a pure strategy profile.

A node may be unreachable in a game with (an) absent-minded information set, as reaching that node
may require contradictory actions to be played if the node's history would require different actions
to be played on multiple visits to an information set.

Closes #629.

Author: d-kad

ChangeLog

@@ -10,6 +10,9 @@
 
 ### Added
 - Tests for EFG Nash solvers -- `enumpoly_solve`, `lp_solve`, `lcp_solve` -- in behavior stratgegies
+- In `pygambit`, `Node` objects now have a read-only property `is_strategy_reachable` to determine
+  if the node is reachable by at least one pure strategy profile. This proves useful for identifying
+  unreachable parts of the game tree in games with absent-mindedness. (#629)
 
 ### Removed
 - Eliminating dominated actions has been removed from the GUI as it was implementing a non-standard

doc/pygambit.api.rst

@@ -141,6 +141,7 @@ Information about the game
    Node.parent
    Node.is_subgame_root
    Node.is_terminal
+   Node.is_strategy_reachable
    Node.prior_action
    Node.prior_sibling
    Node.next_sibling

src/games/game.h

@@ -500,6 +500,7 @@ class GameNodeRep : public std::enable_shared_from_this<GameNodeRep> {
 
   bool IsSuccessorOf(GameNode from) const;
   bool IsSubgameRoot() const;
+  bool IsStrategyReachable() const;
 };
 
 class GameNodeRep::Actions::iterator {

src/games/gametree.cc

@@ -388,6 +388,18 @@ bool GameNodeRep::IsSubgameRoot() const
   return true;
 }
 
+bool GameNodeRep::IsStrategyReachable() const
+{
+  auto tree_game = static_cast<GameTreeRep *>(m_game);
+
+  if (!tree_game->m_unreachableNodes) {
+    tree_game->BuildInfosetParents();
+  }
+
+  // A node is reachable if it is NOT in the set of unreachable nodes.
+  return !contains(*tree_game->m_unreachableNodes, const_cast<GameNodeRep *>(this));
+}
+
 void GameTreeRep::DeleteParent(GameNode p_node)
 {
   if (p_node->m_game != this) {
@@ -800,6 +812,7 @@ void GameTreeRep::ClearComputedValues() const
   }
   const_cast<GameTreeRep *>(this)->m_nodePlays.clear();
   const_cast<GameTreeRep *>(this)->m_infosetParents.clear();
+  const_cast<GameTreeRep *>(this)->m_unreachableNodes = nullptr;
   m_computedValues = false;
 }
 
@@ -842,6 +855,9 @@ std::vector<GameNodeRep *> GameTreeRep::BuildConsistentPlaysRecursiveImpl(GameNo
 
 void GameTreeRep::BuildInfosetParents()
 {
+  m_infosetParents.clear();
+  m_unreachableNodes = std::make_unique<std::set<GameNodeRep *>>();
+
   if (m_root->IsTerminal()) {
     m_infosetParents[m_root->m_infoset].insert(nullptr);
     return;
@@ -893,7 +909,6 @@ void GameTreeRep::BuildInfosetParents()
     }
 
     prior_actions.at(node->m_infoset->m_player->shared_from_this()).top() = action;
-
     if (!child->IsTerminal()) {
       auto child_player = child->m_infoset->m_player->shared_from_this();
       auto prior_action = prior_actions.at(child_player).top();
@@ -902,6 +917,26 @@ void GameTreeRep::BuildInfosetParents()
       if (path_choices.find(child->m_infoset->shared_from_this()) != path_choices.end()) {
         const GameAction replay_action = path_choices.at(child->m_infoset->shared_from_this());
         position.emplace(AbsentMindedEdge{replay_action, child});
+
+        // Start of the traversal of unreachable subtrees
+        for (const auto &[current_action, subtree_root] : child->GetActions()) {
+          if (current_action != replay_action) {
+
+            std::stack<GameNodeRep *> nodes_to_visit;
+            nodes_to_visit.push(subtree_root.get());
+
+            while (!nodes_to_visit.empty()) {
+              GameNodeRep *current_unreachable_node = nodes_to_visit.top();
+              nodes_to_visit.pop();
+              m_unreachableNodes->insert(current_unreachable_node);
+
+              for (const auto &unreachable_child : current_unreachable_node->GetChildren()) {
+                nodes_to_visit.push(unreachable_child.get());
+              }
+            }
+          }
+        }
+        // End of the traversal of unreachable subtrees
       }
       else {
         position.emplace(child->GetActions().begin());

src/games/gametree.h

@@ -40,6 +40,7 @@ class GameTreeRep : public GameExplicitRep {
   std::size_t m_numNonterminalNodes = 0;
   std::map<GameNodeRep *, std::vector<GameNodeRep *>> m_nodePlays;
   std::map<GameInfosetRep *, std::set<GameActionRep *>> m_infosetParents;
+  mutable std::unique_ptr<std::set<GameNodeRep *>> m_unreachableNodes;
 
   /// @name Private auxiliary functions
   //@{

src/pygambit/gambit.pxd

@@ -218,6 +218,7 @@ cdef extern from "games/game.h":
         bint IsTerminal() except +
         bint IsSuccessorOf(c_GameNode) except +
         bint IsSubgameRoot() except +
+        bint IsStrategyReachable() except +
         c_GameAction GetPriorAction() except +
 
     cdef cppclass c_GameRep "GameRep":

src/pygambit/node.pxi

@@ -212,6 +212,19 @@ class Node:
         """
         return self.node.deref().IsSubgameRoot()
 
+    @property
+    def is_strategy_reachable(self) -> bool:
+        """Returns whether this node is reachable by any pure strategy profile.
+
+        A node is considered reachable if there exists at least one pure
+        strategy profile where the resulting path of play passes
+        through that node.
+
+        In games with absent-mindedness, some nodes may be unreachable because
+        any path to them requires conflicting choices at the same information set.
+        """
+        return self.node.deref().IsStrategyReachable()
+
     @property
     def outcome(self) -> typing.Optional[Outcome]:
         """Returns the outcome attached to the node.

tests/test_games/AM-driver-one-infoset.efg

@@ -0,0 +1,8 @@
+EFG 2 R "Untitled Extensive Game" { "Player 1" "Player 2" }
+""
+
+p "" 1 1 "" { "S" "T" } 0
+p "" 1 1 "" { "S" "T" } 0
+t "" 1 "Outcome 1" { 1, -1 }
+t "" 2 "Outcome 2" { 2, -2 }
+t "" 3 "Outcome 3" { 3, -3 }

tests/test_games/AM-driver-subgame.efg

@@ -1,10 +1,10 @@
 EFG 2 R "Untitled Extensive Game" { "Player 1" "Player 2" }
 ""
 
-p "" 1 1 "" { "1" "2" } 0
-p "" 1 1 "" { "1" "2" } 0
+p "" 1 1 "" { "S" "T" } 0
+p "" 1 1 "" { "S" "T" } 0
 t "" 1 "Outcome 1" { 1, -1 }
-p "" 2 1 "" { "1" "2" } 0
+p "" 2 1 "" { "r" "l" } 0
 t "" 2 "Outcome 2" { 2, -2 }
 t "" 3 "Outcome 3" { 3, -3 }
 t "" 4 "Outcome 4" { 4, -4 }

tests/test_node.py

@@ -112,6 +112,57 @@ def test_legacy_is_subgame_root_set(game: gbt.Game, expected_result: set):
     assert legacy_roots == expected_roots
 
 
+def _get_path_of_action_labels(node: gbt.Node) -> list[str]:
+    """
+    Computes the path of action labels from the root to the given node.
+    Returns a list of strings.
+    """
+    if not isinstance(node, gbt.Node):
+        raise TypeError(f"Input must be a pygambit.Node, but got {type(node).__name__}")
+
+    path = []
+    current_node = node
+    while current_node.parent:
+        path.append(current_node.prior_action.label)
+        current_node = current_node.parent
+
+    return path[::-1]
+
+
+@pytest.mark.parametrize("game_file, expected_unreachable_paths", [
+    # Games without absent-mindedness, where all nodes are reachable
+    ("e02.efg", []),
+    ("wichardt.efg", []),
+    ("subgames.efg", []),
+
+    # An absent-minded driver game with an unreachable terminal node
+    (
+        "AM-driver-one-infoset.efg",
+        [["S", "T"]]
+    ),
+
+    # An absent-minded driver game with an unreachable subtree
+    (
+        "AM-driver-subgame.efg",
+        [["S", "T"], ["S", "T", "r"], ["S", "T", "l"]]
+    ),
+])
+def test_is_strategy_reachable(game_file: str, expected_unreachable_paths: list[list[str]]):
+    """
+    Tests `node.is_strategy_reachable` by collecting all unreachable nodes,
+    converting them to their action-label paths, and comparing the resulting
+    list of paths against a known-correct list.
+    """
+    game = games.read_from_file(game_file)
+    nodes = game.nodes
+
+    actual_unreachable_paths = [
+        _get_path_of_action_labels(node) for node in nodes if not node.is_strategy_reachable
+    ]
+
+    assert actual_unreachable_paths == expected_unreachable_paths
+
+
 def test_append_move_error_player_actions():
     """Test to ensure there are actions when appending with a player"""
     game = games.read_from_file("basic_extensive_game.efg")