Skip to content

Add persistent MCTS export/import support#1211

Open
Zyxxx-xxxyZ wants to merge 1 commit into
lightvector:masterfrom
Zyxxx-xxxyZ:codex/persistent-mcts-export-import
Open

Add persistent MCTS export/import support#1211
Zyxxx-xxxyZ wants to merge 1 commit into
lightvector:masterfrom
Zyxxx-xxxyZ:codex/persistent-mcts-export-import

Conversation

@Zyxxx-xxxyZ

@Zyxxx-xxxyZ Zyxxx-xxxyZ commented Jul 1, 2026

Copy link
Copy Markdown

Summary

This PR adds an opt-in persistent MCTS mode that keeps search state across arbitrary root changes and can export/import the persistent MCTS state as JSON.

The key behavior is that useful ancestor-root search information can be inherited by a later descendant root, while searches performed inside a descendant subtree do not contaminate the ancestor's root-local result when switching back.

Approach

  • Add persistent root copies keyed by the root position/history hash, while preserving the existing non-persistent search behavior by default.
  • Store persistent primitive facts with the root key that generated them: direct leaf/NN stats on nodes, edge visits on child pointers, and pending inherited visits for future roots.
  • Treat aggregate NodeStats as a materialized cache. On root switches and import, rebuild the visible subtree from only the current root's tagged primitives.
  • When a real ancestor-root playout traverses a descendant, record one pending inherited visit for that descendant. When the descendant becomes root, consume those pending visits by running its own normal MCTS transition, with descendant-credit propagation disabled during catch-up.
  • Make persistent root move filtering non-destructive so temporarily hidden root children keep their tagged state for future switches.
  • Serialize enough primitive state to reconstruct the graph, root copies, pending visits, root position/history, NN outputs, direct stats, and edge visits.

The proof sketch and invariants are documented in docs/persistent-mcts.md.

Tests

  • ./build-persistent-mcts/katago runpersistentmctstests
  • ./build-persistent-mcts/katago runpersistentmctsstricttests

The strict test runs deterministic SGF root-switch alignment against standard MCTS, including export/import reload checkpoints, and a stress pass. Local run summary:

Persistent MCTS tests passed
Persistent MCTS correctness SGF case 0: tests/data/sampletest/sampletest9x9.sgf
Persistent MCTS correctness SGF case 1: tests/data/humanslbigdiff.sgf
Persistent MCTS stress SGF case: tests/data/sampletest/sampletest9x9.sgf
Persistent MCTS stress nodes=106182 requestedPlayouts=107520 bound=111631
Strict persistent MCTS tests passed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant