Final clearout of Node as a public-facing object in pygambit

doc/pygambit.api.rst

@@ -16,8 +16,8 @@ Representation of games
    Game
    Outcome
    Node
-   Branch
-   Subgame
+   TreeLayout
+   TreeLayoutCoordinates
 
 
 Creating, reading, and writing games
@@ -43,6 +43,15 @@ Creating, reading, and writing games
    Game.to_latex
 
 
+Computing a tree layout for graphical display
+..............................................
+
+.. autosummary::
+   :toctree: api/
+
+   layout_tree
+
+
 Transforming game trees
 .......................
 
@@ -106,17 +115,16 @@ Information about the game
    Game.max_payoff
    Game.get_min_payoff
    Game.get_max_payoff
-   Game.root
    Game.get_infosets
    Game.get_events
    Game.get_strategies
    Game.get_sequences
-   Game.nodes
    Game.contingencies
    Game.get_outcome
    Game.get_payoffs
-   Game.subgames
+   Game.get_subgame_roots
    Game.get_minimal_subgame
+   Game.get_strategy_unreachable
 
 .. autosummary::
    :toctree: api/
@@ -128,32 +136,10 @@ Information about the game
 .. autosummary::
    :toctree: api/
 
-   Node.label
-   Node.game
-   Node.outcome
-   Node.children
-   Node.parent
-   Node.is_subgame_root
-   Node.is_terminal
-   Node.is_strategy_reachable
-   Node.prior_action
-   Node.prior_sibling
-   Node.next_sibling
    Node.members
    Node.actions
    Node.action_probs
    Node.player
-   Node.is_successor_of
-   Node.plays
-   Node.own_prior_action
-
-.. autosummary::
-   :toctree: api/
-
-   Subgame.game
-   Subgame.root
-   Subgame.parent
-   Subgame.children
 
 .. autosummary::
 

doc/tutorials/03_stripped_down_poker.ipynb

@@ -371,26 +371,7 @@
    "id": "9c1f6a2e",
    "metadata": {},
    "source": [
-    "Indexing the profile directly by a `Node` requires identifying it with a `Selector`, since `MixedBehaviorProfile.__getitem__` accepts only a player label or a `Selector`, not a bare `Node`.\n",
-    "\n",
-    "A `Node`'s own path of action labels back to the root builds exactly the `Selector` that matches it:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "b7c1e8a4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "def selector_for_node(node):\n",
-    "    labels = []\n",
-    "    current = node\n",
-    "    while current.parent is not None:\n",
-    "        labels.append(current.prior_action.label)\n",
-    "        current = current.parent\n",
-    "    labels.reverse()\n",
-    "    return gbt.H.path(*labels)"
+    "`Game.get_infosets` returns each information set's canonical member as a `History` -- a plain tuple of action labels from the root. Indexing the profile directly by that tuple requires turning it into a `Selector` first, since `MixedBehaviorProfile.__getitem__` accepts only a player label or a `Selector`:"
    ]
   },
   {
@@ -401,10 +382,10 @@
    "outputs": [],
    "source": [
     "for number, node in enumerate(g.get_infosets(\"Alice\"), start=1):\n",
-    "    for action in node.actions:\n",
+    "    for action in g.get_actions(gbt.H.path(*node)):\n",
     "        print(\n",
     "            f\"At information set {number}, \"\n",
-    "            f\"Alice plays {action} with probability: {eqm[selector_for_node(node)][action]}\"\n",
+    "            f\"Alice plays {action} with probability: {eqm[gbt.H.path(*node)][action]}\"\n",
     "        )"
    ]
   },
@@ -443,7 +424,10 @@
    "id": "2966e700",
    "metadata": {},
    "outputs": [],
-   "source": "(bob_node,) = g.get_infosets(\"Bob\")\neqm[selector_for_node(bob_node)][\"Call\"]"
+   "source": [
+    "(bob_node,) = g.get_infosets(\"Bob\")\n",
+    "eqm[gbt.H.path(*bob_node)][\"Call\"]"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -462,8 +446,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "bob_action_values = eqm.action_values[bob_node]\n",
-    "for action in bob_node.actions:\n",
+    "bob_action_values = eqm.action_values[gbt.H.path(*bob_node)]\n",
+    "for action in g.get_actions(gbt.H.path(*bob_node)):\n",
     "    print(\n",
     "        f\"When Bob plays {action} his expected payoff is {bob_action_values[action]}\"\n",
     "    )"
@@ -478,7 +462,7 @@
     "\n",
     "`MixedBehaviorProfile.beliefs` returns the probability of reaching each node, conditional on its information set being reached.\n",
     "\n",
-    "Recall that the two nodes in Bob's only information set are `g.root.children[\"King\"].children[\"Bet\"]` and `g.root.children[\"Queen\"].children[\"Bet\"]`):"
+    "Recall that the two nodes in Bob's only information set are `(\"King\", \"Bet\")` and `(\"Queen\", \"Bet\")` (as Histories):"
    ]
   },
   {
@@ -488,10 +472,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for node in bob_node.members:\n",
+    "for node in g.get_members(gbt.H.path(*bob_node)):\n",
     "    print(\n",
-    "        f\"Bob's belief in reaching the {node.parent.prior_action.label} -> \"\n",
-    "        f\"{node.prior_action.label} node is: {eqm.beliefs[node]}\"\n",
+    "        f\"Bob's belief in reaching the {node[-2]} -> \"\n",
+    "        f\"{node[-1]} node is: {eqm.beliefs[node]}\"\n",
     "    )"
    ]
   },
@@ -512,7 +496,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "eqm.infoset_probs[bob_node]"
+    "eqm.infoset_probs[gbt.H.path(*bob_node)]"
    ]
   },
   {
@@ -531,10 +515,10 @@
    "outputs": [],
    "source": [
     "bob_node_values = eqm.node_values[\"Bob\"]\n",
-    "for node in bob_node.members:\n",
+    "for node in g.get_members(gbt.H.path(*bob_node)):\n",
     "    print(\n",
-    "        f\"The probability that the node {node.parent.prior_action.label} -> \"\n",
-    "        f\"{node.prior_action.label} is reached is: {eqm.realiz_probs[node]}. \",\n",
+    "        f\"The probability that the node {node[-2]} -> \"\n",
+    "        f\"{node[-1]} is reached is: {eqm.realiz_probs[node]}. \",\n",
     "        f\"Bob's expected payoff conditional on reaching this node is {bob_node_values[node]}\"\n",
     "    )"
    ]
@@ -669,7 +653,23 @@
    "id": "d18a91f0",
    "metadata": {},
    "outputs": [],
-   "source": "for player in g.players:\n    print(\n        f\"{player}'s expected payoffs:\"\n    )\n    gnm_action_values = gnm_eqm.as_behavior().action_values\n    lcp_action_values = eqm.action_values\n    for number, node in enumerate(g.get_infosets(player), start=1):\n        for action in node.actions:\n            print(\n                f\"At information set {number}, \"\n                f\"when playing {action} - \"\n                f\"gnm: {gnm_action_values[node][action]:.4f}\"\n                f\", lcp: {str(lcp_action_values[node][action])}\"\n            )\n    print()"
+   "source": [
+    "for player in g.players:\n",
+    "    print(\n",
+    "        f\"{player}'s expected payoffs:\"\n",
+    "    )\n",
+    "    gnm_action_values = gnm_eqm.as_behavior().action_values\n",
+    "    lcp_action_values = eqm.action_values\n",
+    "    for number, node in enumerate(g.get_infosets(player), start=1):\n",
+    "        for action in g.get_actions(gbt.H.path(*node)):\n",
+    "            print(\n",
+    "                f\"At information set {number}, \"\n",
+    "                f\"when playing {action} - \"\n",
+    "                f\"gnm: {gnm_action_values[gbt.H.path(*node)][action]:.4f}\"\n",
+    "                f\", lcp: {str(lcp_action_values[gbt.H.path(*node)][action])}\"\n",
+    "            )\n",
+    "    print()"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -877,7 +877,7 @@
    "source": [
     "small_game = gbt.Game.new_tree()\n",
     "small_game.append_event(gbt.H.path(), dict.fromkeys([\"a\", \"b\", \"c\"], gbt.Rational(1, 3)))\n",
-    "list(small_game.root.action_probs.values())"
+    "list(small_game.get_action_probs(gbt.H.path()).values())"
    ]
   },
   {
@@ -897,7 +897,7 @@
     "    gbt.H.path(),\n",
     "    {\"a\": gbt.Rational(1, 4), \"b\": gbt.Rational(1, 2), \"c\": gbt.Rational(1, 4)}\n",
     ")\n",
-    "list(small_game.root.action_probs.values())"
+    "list(small_game.get_action_probs(gbt.H.path()).values())"
    ]
   },
   {
@@ -919,7 +919,7 @@
     "    gbt.H.path(),\n",
     "    {\"a\": gbt.Decimal(\".25\"), \"b\": gbt.Decimal(\".50\"), \"c\": gbt.Decimal(\".25\")}\n",
     ")\n",
-    "list(small_game.root.action_probs.values())"
+    "list(small_game.get_action_probs(gbt.H.path()).values())"
    ]
   },
   {
@@ -942,7 +942,7 @@
    "outputs": [],
    "source": [
     "small_game.make_event(gbt.H.path(), {\"a\": \"1/4\", \"b\": \"1/2\", \"c\": \"1/4\"})\n",
-    "list(small_game.root.action_probs.values())"
+    "list(small_game.get_action_probs(gbt.H.path()).values())"
    ]
   },
   {
@@ -953,7 +953,7 @@
    "outputs": [],
    "source": [
     "small_game.make_event(gbt.H.path(), {\"a\": \".25\", \"b\": \".50\", \"c\": \".25\"})\n",
-    "list(small_game.root.action_probs.values())"
+    "list(small_game.get_action_probs(gbt.H.path()).values())"
    ]
   },
   {
@@ -977,7 +977,7 @@
    "outputs": [],
    "source": [
     "small_game.make_event(gbt.H.path(), {\"a\": .25, \"b\": .50, \"c\": .25})\n",
-    "list(small_game.root.action_probs.values())"
+    "list(small_game.get_action_probs(gbt.H.path()).values())"
    ]
   },
   {