game-resolver-cpp 0.1.1__tar.gz → 0.1.2__tar.gz

{game_resolver_cpp-0.1.1 → game_resolver_cpp-0.1.2}/.gitignore

@@ -17,3 +17,12 @@ compile_commands.json
 dist/
 wheelhouse/
 *.egg-info/
+__pycache__/
+*.pyc
+
+# examples が吐くゲームツリー
+entry_deterrence.html
+battle_sequential.html
+battle_simultaneous.html
+centipede.html
+game_tree.html

{game_resolver_cpp-0.1.1 → game_resolver_cpp-0.1.2}/CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.21)
-project(game_resolver_cpp VERSION 0.1.1 LANGUAGES CXX)
+project(game_resolver_cpp VERSION 0.1.2 LANGUAGES CXX)
 
 option(GAME_RESOLVER_BUILD_TESTS "Build the test suite" ${PROJECT_IS_TOP_LEVEL})
 option(GAME_RESOLVER_BUILD_EXAMPLES "Build the example programs" ${PROJECT_IS_TOP_LEVEL})
@@ -27,6 +27,84 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
 endif()
 
+# ------------------------------------------------------- 可視化アセットの埋め込み
+# assets/ と third_party/d3-mini/ を C++ の生文字列リテラルにしたヘッダを configure 時に作る。
+# こうしておくと tree_view.cpp が吐く HTML が 1 ファイルで完結し、実行時に何も探しに行かない。
+#
+# MSVC は 1 つの文字列リテラルを 65535 バイトまでしか許さないので、16 KB ずつに割って
+# 配列にし、実行時に連結する（d3-mini.min.js が 57 KB あり、素直に書くと将来引っかかる）。
+set(GR_ASSET_FILES
+  ${CMAKE_CURRENT_SOURCE_DIR}/assets/tree_view.html.in
+  ${CMAKE_CURRENT_SOURCE_DIR}/assets/tree_view.css
+  ${CMAKE_CURRENT_SOURCE_DIR}/assets/tree_view.js
+  ${CMAKE_CURRENT_SOURCE_DIR}/assets/editor.html.in
+  ${CMAKE_CURRENT_SOURCE_DIR}/assets/editor.css
+  ${CMAKE_CURRENT_SOURCE_DIR}/assets/editor.js
+  ${CMAKE_CURRENT_SOURCE_DIR}/third_party/d3-mini/d3-mini.min.js
+)
+set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GR_ASSET_FILES})
+
+function(gr_emit_asset out_var function_name path)
+  file(READ "${path}" _content)
+  string(FIND "${_content}" ")GRASSET\"" _clash)
+  if(NOT _clash EQUAL -1)
+    message(FATAL_ERROR "${path}: 生文字列リテラルの終端子 )GRASSET\" が中身に含まれています")
+  endif()
+
+  string(LENGTH "${_content}" _len)
+  set(_chunks "")
+  set(_at 0)
+  while(_at LESS _len)
+    math(EXPR _take "${_len} - ${_at}")
+    if(_take GREATER 16000)
+      set(_take 16000)
+    endif()
+    string(SUBSTRING "${_content}" ${_at} ${_take} _piece)
+    string(APPEND _chunks "    R\"GRASSET(${_piece})GRASSET\",\n")
+    math(EXPR _at "${_at} + ${_take}")
+  endwhile()
+
+  string(APPEND ${out_var}
+    "inline std::string ${function_name}() {\n"
+    "  static const char* const kParts[] = {\n${_chunks}  };\n"
+    "  return detail::join(kParts, sizeof(kParts) / sizeof(kParts[0]));\n"
+    "}\n\n")
+  set(${out_var} "${${out_var}}" PARENT_SCOPE)
+endfunction()
+
+set(GR_ASSET_BODY "")
+gr_emit_asset(GR_ASSET_BODY tree_view_template ${CMAKE_CURRENT_SOURCE_DIR}/assets/tree_view.html.in)
+gr_emit_asset(GR_ASSET_BODY tree_view_css ${CMAKE_CURRENT_SOURCE_DIR}/assets/tree_view.css)
+gr_emit_asset(GR_ASSET_BODY tree_view_js ${CMAKE_CURRENT_SOURCE_DIR}/assets/tree_view.js)
+gr_emit_asset(GR_ASSET_BODY editor_template ${CMAKE_CURRENT_SOURCE_DIR}/assets/editor.html.in)
+gr_emit_asset(GR_ASSET_BODY editor_css ${CMAKE_CURRENT_SOURCE_DIR}/assets/editor.css)
+gr_emit_asset(GR_ASSET_BODY editor_js ${CMAKE_CURRENT_SOURCE_DIR}/assets/editor.js)
+gr_emit_asset(GR_ASSET_BODY d3_mini ${CMAKE_CURRENT_SOURCE_DIR}/third_party/d3-mini/d3-mini.min.js)
+
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/generated/game_resolver_assets.hpp
+"// CMake が assets/ と third_party/d3-mini/ から生成する。直接編集しない。
+// 元ファイルを直せば configure が走り直して作り直される。
+#pragma once
+
+#include <cstddef>
+#include <string>
+
+namespace game_resolver::assets {
+namespace detail {
+
+inline std::string join(const char* const* parts, std::size_t count) {
+  std::string out;
+  for (std::size_t i = 0; i < count; ++i) {
+    out += parts[i];
+  }
+  return out;
+}
+
+}  // namespace detail
+
+${GR_ASSET_BODY}}  // namespace game_resolver::assets
+")
+
 # ---------------------------------------------------------------- library
 add_library(game_resolver
   src/version.cpp
@@ -36,6 +114,11 @@ add_library(game_resolver
   src/solver/nash_solver.cpp
   src/bayesian/bayesian_player.cpp
   src/bayesian/bayesian_nash_equilibrium.cpp
+  src/extensive/extensive_form_game.cpp
+  src/extensive/subgame_perfect_equilibrium.cpp
+  src/extensive/tree_view.cpp
+  src/extensive/html_util.cpp
+  src/extensive/editor.cpp
 )
 add_library(game_resolver::game_resolver ALIAS game_resolver)
 
@@ -43,6 +126,8 @@ target_include_directories(game_resolver PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
   $<INSTALL_INTERFACE:include>
 )
+# 生成した game_resolver_assets.hpp は tree_view.cpp だけが使う。公開ヘッダではない。
+target_include_directories(game_resolver PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/generated)
 target_compile_features(game_resolver PUBLIC cxx_std_20)
 
 # 静的ライブラリを共有オブジェクトにリンクできるようにする。

{game_resolver_cpp-0.1.1 → game_resolver_cpp-0.1.2}/Makefile

@@ -4,7 +4,7 @@ BUILD_DIR ?= build
 BUILD_TYPE ?= Release
 GENERATOR ?= Ninja
 
-.PHONY: all configure build test bench format format-check tidy clean python-install python-test python-bench
+.PHONY: all configure build test bench format format-check tidy clean python-install python-test python-bench web
 
 all: build
 
@@ -30,6 +30,10 @@ python-test:
 python-bench:
 	python3 python/benchmarks/compare_with_python.py
 
+# ブラウザでゲームツリーを描いて解く（python-install 済みであること）
+web:
+	python3 -m game_resolver_cpp.web
+
 # サニタイザ付きのデバッグビルドでテストする
 test-asan:
 	$(CMAKE) -S . -B $(BUILD_DIR)-asan -G $(GENERATOR) -DCMAKE_BUILD_TYPE=Debug -DGAME_RESOLVER_SANITIZE=ON

{game_resolver_cpp-0.1.1 → game_resolver_cpp-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: game_resolver_cpp
-Version: 0.1.1
+Version: 0.1.2
 Summary: C++ backed game equilibrium solver with the game_resolver interface
 Keywords: game-theory,nash-equilibrium,bayesian-game
 Author: nishino-lab
@@ -158,10 +158,46 @@ an exact `==`, because an exact comparison makes genuine ties depend on rounding
 Cournot example has three equilibria on its grid; the Python version reports one of them.
 Pass `tolerance=0` to `NashEquilibrium` for the Python version's strict behaviour.
 
+## Run an extensive form game
+
+Build a game tree and get its pure strategy subgame perfect equilibria. Information sets
+turn the same tree into a simultaneous move game.
+
+```python
+from game_resolver_cpp.extensive_form_game import ExtensiveFormGame
+
+game = ExtensiveFormGame()
+entrant = game.add_player("Entrant")
+incumbent = game.add_player("Incumbent")
+
+enter = game.node(entrant, "E")
+react = game.node(incumbent, "I")
+game.edge(enter, game.terminal([0, 2], "out"), "Out")
+game.edge(enter, react, "In")
+game.edge(react, game.terminal([-1, -1], "fight"), "Fight")
+game.edge(react, game.terminal([1, 1], "share"), "Accommodate")
+game.auto_information_sets()
+
+print(game.get_subgame_perfect_equilibrium())
+# [{'payoff': [1.0, 1.0], 'strategy': {'E': 'In', 'I': 'Accommodate'},
+#   'path': ['E', 'I', 'share'], 'outcome': 'share'}]
+
+game.draw_gametree("entry.html")   # self-contained page with the tree and the equilibria
+```
+
+Or draw the tree in the browser and press ▶ 解く:
+
+```
+python -m game_resolver_cpp.web
+```
+
+The editor saves games as JSON, `ExtensiveFormGame.load()` reads them, and `game.edit()`
+opens a game built in code in the editor.
+
 ## Not supported
 
 - Mixed strategy Nash equilibria (the Python version does not have them either)
-- Extensive form games, subgame perfect equilibria
+- Chance (Nature) nodes in extensive form games
 
 ## Links
 

{game_resolver_cpp-0.1.1 → game_resolver_cpp-0.1.2}/README.md

@@ -250,6 +250,140 @@ std::cout << nash << '\n';
 
 `payoff` is the expected payoff indexed by `[equilibrium][player][type]`.
 
+## Run an extensive form game
+
+Build a game tree, get its pure strategy subgame perfect equilibria, and draw it.
+
+```cpp
+#include <iostream>
+
+#include "game_resolver/extensive/subgame_perfect_equilibrium.hpp"
+#include "game_resolver/extensive/tree_view.hpp"
+
+using namespace game_resolver;
+
+int main() {
+  ExtensiveFormGame game;
+  const int entrant = game.add_player("Entrant");
+  const int incumbent = game.add_player("Incumbent");
+
+  const NodeId enter = game.decision_node(entrant, "E");
+  const NodeId react = game.decision_node(incumbent, "I");
+
+  game.edge(enter, game.terminal_node({0.0, 2.0}, "out"), Action(std::string("Out")));
+  game.edge(enter, react, Action(std::string("In")));
+  game.edge(react, game.terminal_node({-1.0, -1.0}, "fight"), Action(std::string("Fight")));
+  game.edge(react, game.terminal_node({1.0, 1.0}, "share"), Action(std::string("Accommodate")));
+
+  game.auto_information_sets();  // perfect information: one node per information set
+
+  const SubgamePerfectEquilibrium equilibrium(game);
+  std::cout << describe(game, equilibrium.solve()) << '\n';
+
+  write_solved_tree_view(game, "entry.html", "Entry deterrence");
+}
+```
+
+```
+subgame perfect equilibria: 1
+  [0] payoff=(1, 1)
+      strategy: E=In, I=Accommodate
+      path:     E -In-> I -Accommodate-> share
+```
+
+`(Out, Fight)` is a Nash equilibrium of the normal form but not a subgame perfect one: once
+the entrant is in, fighting pays -1 and accommodating pays 1, so the threat is never carried
+out. Backward induction drops it.
+
+### Imperfect information
+
+Put several nodes in one information set and the player cannot tell them apart. The same
+tree then describes a simultaneous move game:
+
+```cpp
+// instead of auto_information_sets()
+game.information_set(her, {boxing, ballet}, {first}, "her");
+game.information_set(him, {boxing, ballet}, {after_boxing, after_ballet}, "him (blind)");
+```
+
+Every node in one information set must offer the same actions in the same order — otherwise
+the player could tell the nodes apart by what they can do. `validate()` checks this.
+
+There is one algorithm for both cases. Subgames are found and collapsed deepest first; each
+is converted to its induced normal form and handed to the same `solve_pure_nash` the rest of
+the library uses. Under perfect information every decision node is its own subgame and the
+induced normal form degenerates to picking a maximum, which is exactly backward induction.
+
+### The HTML view
+
+`write_solved_tree_view` writes one self-contained file — no network access, nothing to
+serve, just open it.
+
+| | |
+| --- | --- |
+| Layout | tidy tree (Reingold-Tilford) via `d3-hierarchy`. Deterministic: the same game always draws the same picture |
+| Payoffs | shown at the leaves, one colored dot per player next to the number |
+| Information sets | non-singleton sets are joined by a dashed connector |
+| Equilibria | listed in the sidebar; selecting one highlights its path |
+| Off-path moves | drawn as dashed colored edges — a subgame perfect equilibrium fixes behaviour at information sets the path never reaches, and that is what separates it from a plain Nash equilibrium |
+| Interaction | pan / zoom, click a node to collapse its subtree, hover for details, `f` to fit, `1`–`9` to pick an equilibrium |
+| Size | about 97 KB, of which 57 KB is the embedded subset of D3 (see [third_party/d3-mini/](third_party/d3-mini/)) |
+
+Player colors come from a palette validated for colorblind separation, but identity never
+rests on color alone: each node shows the player number, and the legend is always visible.
+Beyond three players the categorical hues cannot be kept pairwise distinguishable, so the
+number and the legend are what carry identity.
+
+Runnable versions of all of the above are in
+[examples/entry_deterrence.cpp](examples/entry_deterrence.cpp),
+[examples/extensive_battle_of_sex.cpp](examples/extensive_battle_of_sex.cpp) and
+[examples/centipede.cpp](examples/centipede.cpp).
+
+### Draw the tree in the browser instead
+
+You do not have to write the tree as code. The package ships an editor that runs in the
+browser: draw the tree, press **▶ 解く**, and the equilibria are computed by the same C++
+solver and drawn on the tree.
+
+```bash
+pip install .
+python -m game_resolver_cpp.web        # or: game-resolver-web
+```
+
+This starts a local server on `http://127.0.0.1:8765/` and opens it. Nothing is installed
+besides the package itself; the server is the standard library's `http.server`, and the
+page is the same self-contained HTML the tree view uses.
+
+| | |
+| --- | --- |
+| Building | click a node to edit it in the inspector; hover a node and press **＋** (or `a`) to add a branch; each branch has a menu to make its child a terminal node or a decision node of some player |
+| Information sets | select a decision node and tick the other nodes of the same player under 「同じ情報集合に入れる」. Only nodes with the same actions in the same order are offered, and a node cannot be joined with its own ancestor (that would break perfect recall). Adding, removing or renaming a branch on one member is applied to every member, so a set never goes out of sync |
+| Solving | **▶ 解く** (`Ctrl+Enter`) lists the pure strategy subgame perfect equilibria; picking one highlights its path and shows off-path choices as dashed edges, as in the HTML view |
+| Saving | **保存** downloads the game as JSON, **開く** reads it back, and edits are also kept in the browser's local storage so a reload does not lose them. `Ctrl+Z` undoes |
+| Getting it into code | **Python** shows the `ExtensiveFormGame` code that builds the same tree; **HTML** downloads the solved tree view. `ExtensiveFormGame.load("game.json")` reads a saved file directly |
+| Samples | 参入阻止 / 男女の争い（逐次・同時）/ ムカデゲーム, from the menu at the top |
+
+The other direction works too: `game.edit()` on a game built in Python opens it in the
+editor. See [Extensive form games from Python](#extensive-form-games-from-python).
+
+From C++, `game_json()` / `tree_view_json()` in
+[tree_view.hpp](include/game_resolver/extensive/tree_view.hpp) return the JSON the editor
+and the view read, and `write_editor()` in [editor.hpp](include/game_resolver/extensive/editor.hpp)
+writes the editor page itself. Without a server that page can edit and export but not solve;
+the solving is done by the C++ library on the server side, not re-implemented in JavaScript.
+
+### Limits
+
+- **Pure strategies only**, same as the rest of the library. A game with no pure strategy
+  equilibrium returns an empty result rather than a mixed one.
+- **Perfect recall is only partly checked.** `validate()` rejects an information set that
+  contains a node and one of its own descendants, which is the case that silently breaks the
+  conversion to normal form. It does not verify the full perfect recall condition.
+- **No chance (Nature) nodes yet.**
+- The induced normal form of a subgame has `Π_players Π_{their information sets} |actions|`
+  cells, which grows doubly exponentially. `SpneOptions::max_cells` (10,000,000 by default)
+  stops a mis-built game from quietly allocating gigabytes.
+
 ## Use it from Python
 
 The package exposes the same interface as the Python `game_resolver`, so existing lab code
@@ -299,6 +433,55 @@ payoff.update(more_entries)              # also works
 Player(0, actions=actions, payoff=mapping)   # a plain dict is accepted too
 ```
 
+### Extensive form games from Python
+
+`node` / `edge` / `information_set` / `draw_gametree` keep the names used by the prototype on
+the Python side's `feature/extensive_form_game` branch. Terminal nodes carry payoffs, which
+that branch did not have, and nodes are integer ids rather than objects.
+
+```python
+from game_resolver_cpp.extensive_form_game import ExtensiveFormGame
+
+game = ExtensiveFormGame()
+entrant = game.add_player("Entrant")
+incumbent = game.add_player("Incumbent")
+
+enter = game.node(entrant, "E")
+react = game.node(incumbent, "I")
+game.edge(enter, game.terminal([0, 2], "out"), "Out")
+game.edge(enter, react, "In")
+game.edge(react, game.terminal([-1, -1], "fight"), "Fight")
+game.edge(react, game.terminal([1, 1], "share"), "Accommodate")
+game.auto_information_sets()
+
+for eq in game.get_subgame_perfect_equilibrium():
+    print(eq)
+# {'payoff': [1.0, 1.0], 'strategy': {'E': 'In', 'I': 'Accommodate'},
+#  'path': ['E', 'I', 'share'], 'outcome': 'share'}
+
+game.draw_gametree("entry.html", "Entry deterrence")
+```
+
+`strategy` covers every information set, including ones the equilibrium path never reaches.
+For imperfect information, pass several nodes to `information_set`:
+
+```python
+game.information_set(him, ["Boxing", "Ballet"], after_boxing, after_ballet, label="him")
+```
+
+A game can be moved between code and the browser editor in both directions:
+
+```python
+game.edit()                                   # open this game in the editor (Ctrl+C to stop)
+game = ExtensiveFormGame.load("entry.json")   # read a file saved from the editor
+game.save("entry.json")                       # the same format, from code
+data = game.to_dict(); ExtensiveFormGame.from_dict(data)
+```
+
+The JSON is `{"players", "root", "nodes", "informationSets"}`; `from_dict` also accepts a
+shorter form (player names as strings, no ids, only the non-singleton information sets),
+which is what the editor writes.
+
 ### What actually gets faster
 
 One run of `python3 python/benchmarks/compare_with_python.py` on an 11-core Apple M series
@@ -363,6 +546,26 @@ The reasoning behind each of these, and the alternatives that were measured and
 | `BayesianNashEquilibrium(g)` + `initialize_payoff_matrices()` | `BayesianNashEquilibrium(g)` (built in the constructor) |
 | strategy = `dict[type, action]` | strategy = `Strategy` (a vector of action indices, one per type) |
 
+From the `feature/extensive_form_game` branch:
+
+| Python prototype | C++ |
+| --- | --- |
+| `ExtensiveFormPlayer(id=0)` + `game.add(p)` | `game.add_player("name")` -> `int` |
+| `game.node(player)` -> `Node` | `game.decision_node(player)` -> `NodeId` |
+| — (terminals were invented at draw time) | `game.terminal_node({2.0, 1.0})` -> `NodeId` |
+| `game.edge(parent, child, action)` | same, with `NodeId` |
+| `game.information_set(player, actions, *nodes)` | `game.information_set(player, actions, {nodes})` |
+| `player.setup_actions()` | not needed — the solver derives the induced normal form |
+| `SubgamePerfectNashEquilibrium(g)` (an empty stub) | `SubgamePerfectEquilibrium(g).solve()` |
+| `game.draw_gametree()` -> pyvis, physics layout | `write_solved_tree_view(g, path, title)` -> deterministic tidy tree |
+
+What that branch had was the tree structure and the idea of taking the product of local
+strategies to get the induced normal form. It had no payoffs on the tree
+(`draw_gametree` carried a `# ToDo 利得ベクトルを書く！` where the payoff vector belongs and
+manufactured terminal nodes from `local_actions` at draw time), and
+`SubgamePerfectNashEquilibrium.initialize_payoff_matrices` was `pass`. The solver and the
+HTML view here are new.
+
 Deliberate differences:
 
 - **The Type1 / Type2 distinction is gone from the C++ API.** In the Python version, whether
@@ -401,6 +604,7 @@ make test
 | `make python-install` | `pip install ".[test]"` |
 | `make python-test` | run the Python tests |
 | `make python-bench` | compare against the Python version |
+| `make web` | open the browser editor (needs `make python-install` first) |
 
 Or drive CMake directly:
 
@@ -516,7 +720,7 @@ Two things are deliberately excluded:
 ## Not supported
 
 - Mixed strategy Nash equilibria (the Python version does not have them either)
-- Extensive form games, subgame perfect equilibria
+- Chance (Nature) nodes in extensive form games
 - A Bayesian game's strategy space grows as `|actions|^|types|`. That blow-up is inherent,
   so oversized settings are rejected up front.