ISMCTS Modules¶

対象: pca.search.ismcts

Purpose¶

不完全情報下の tree search を実装する。public information key で tree node を共有し、hidden state を determinization ごとに sample する。leaf は rollout せず、NN value と progress value で評価する。

Modules¶

Module	Role	Implementation Details
`config.py`	config / protocol	`ISMCTSConfig`, `SearchApi`, `finish_search_session()` を定義する。
`tree.py`	tree state	`ISMCTSNode` と `ISMCTSTree`。node cache、encode cache、node 作成/再利用を扱う。
`runtime_stats.py`	diagnostics	depth、stop reason、candidate filter、prize delta、aux prize usage を記録する `ISMCTSRuntimeStats`。
`simulation_types.py`	internal dataclasses	leaf batching 用の `DeferredLeafEvaluation` と `CompletedSimulation`。
`simulation.py`	simulation engine	1 simulation の traversal、leaf value、backprop、deferred leaf batch、hidden clone を実装する。
`actions.py`	action selection	PUCT、candidate pruning、Dirichlet noise、visit distribution、option category/equivalence。
`public_state.py`	information set	public observation から information-set key と public-state tokens を作る。
`impl.py`	root orchestration	`ismcts_policy()` と `ismcts_policy_with_hidden()` の実体。hidden sampling と root decision をまとめる。
`policy.py`	facade	policy entrypoint の re-export。
`types.py`	compatibility facade	分割後の型を旧 import path から re-export する。

Public API¶

API	Usage
`ISMCTSConfig`	探索回数、candidate cap、leaf batching、Dirichlet noise、value config を指定する。
`ISMCTSRuntimeStats`	self-play diagnostics に runtime stats を渡す。
`ismcts_policy(...)`	belief sampling 付き root policy。
`ismcts_policy_with_hidden(...)`	training-only oracle target 用 fixed-hidden search。
`candidate_action_indices(...)`	candidate pruning の結果を見る/テストする。
`visit_distribution(...)`	visit counts を policy target に変換する。
`leaf_value_from_decision(...)`	leaf value shaping をテストする入口。

Execution Flow¶

impl.ismcts_policy() が root observation を encode し、base policy で root prior/value を作る。
belief.sample_hidden_state() で hidden state を determinization ごとに作る。
config.SearchApi.search_begin() で CABT search session を開始する。
simulation.run_simulation() が actions.select_puct_action() で leaf まで進む。
simulation.leaf_value_from_decision() が NN value と progress/aux value を合成する。
actions.backpropagate() が path に value を戻す。
actions.visit_distribution() と choose_from_visits() で PolicyDecision を返す。

Usage¶

from pca.search.ismcts import ISMCTSConfig, ismcts_policy

decision = ismcts_policy(
    obs,
    your_full_deck=deck0,
    opponent_prior_deck=deck1,
    policy_fn=policy_fn,
    search_api=search_api,
    config=ISMCTSConfig(determinizations=8, simulations_per_determinization=8),
)

Notes¶

types.py は互換 facade。新しい実装を読むときは config.py, tree.py, simulation.py, impl.py を優先する。
runtime_stats.py は大きいが、統計 field と delta/snapshot の凝集クラスなので単独 module にしている。