Struct MCTSEngine 

pub struct MCTSEngine { /* private fields */ }

Implementations

impl MCTSEngine

pub fn new(config: MCTSConfig) -> Self

Examples found in repository

examples/selfplay_export.rs (lines 106-111)

fn play_game(seed: u64, iterations: u32) -> (Vec<PendingRow>, WinStatus) {
    let mut bb = Bitboard::EMPTY;
    let mut rows = Vec::new();
    let mut ply = 0u32;

    loop {
        if has_winning_line(&bb) {
            return (rows, check_winner(&bb));
        }
        let legal = generate_legal_moves(&bb);
        if legal.is_empty() {
            // No legal moves: the side to move loses (see Global
            // Constraints — this is a decisive result, never a draw).
            let loser = current_player(&bb).unwrap();
            let winner = if loser == 0 {
                WinStatus::Player1Wins
            } else {
                WinStatus::Player0Wins
            };
            return (rows, winner);
        }

        let side_to_move = current_player(&bb).unwrap();
        // use_transposition_table MUST be false here: with it on (the
        // engine's actual default), root moves that canonicalize to the
        // same child are merged onto one shared node and reported under a
        // single arbitrary move, silently dropping every other legal move
        // that led there — worst exactly at shallow plies (the empty
        // board's 64 legal moves collapse to 3), which every self-play
        // game passes through. Verified in mcts.rs's
        // root_move_visits_default_config_collapses_symmetric_root_moves
        // test — this is not a hypothetical concern, it was caught by
        // Opus review of the PR that added root_move_visits and is
        // exactly what this exporter must avoid to produce a faithful
        // per-legal-move policy target.
        let mut engine = MCTSEngine::new(MCTSConfig {
            max_iterations: iterations,
            seed: Some(seed.wrapping_add(ply as u64)),
            use_transposition_table: false,
            ..Default::default()
        });
        let (best_move, _) = engine.search(&bb).expect("legal moves exist");
        let policy: Vec<(u8, u8, u32)> = engine
            .root_move_visits()
            .into_iter()
            .map(|(mv, visits)| (mv.shape, mv.position, visits))
            .collect();

        rows.push(PendingRow {
            ply,
            qfen: State::new(bb).to_qfen(),
            side_to_move,
            policy,
        });

        bb = apply_move(&bb, &best_move);
        ply += 1;
    }
}

pub fn search(&mut self, bb: &Bitboard) -> Option<(Move, f64)>

Run MCTS from the given bitboard and return (best_move, win_probability_for_the_root_mover).

Examples found in repository

examples/selfplay_export.rs (line 112)

fn play_game(seed: u64, iterations: u32) -> (Vec<PendingRow>, WinStatus) {
    let mut bb = Bitboard::EMPTY;
    let mut rows = Vec::new();
    let mut ply = 0u32;

    loop {
        if has_winning_line(&bb) {
            return (rows, check_winner(&bb));
        }
        let legal = generate_legal_moves(&bb);
        if legal.is_empty() {
            // No legal moves: the side to move loses (see Global
            // Constraints — this is a decisive result, never a draw).
            let loser = current_player(&bb).unwrap();
            let winner = if loser == 0 {
                WinStatus::Player1Wins
            } else {
                WinStatus::Player0Wins
            };
            return (rows, winner);
        }

        let side_to_move = current_player(&bb).unwrap();
        // use_transposition_table MUST be false here: with it on (the
        // engine's actual default), root moves that canonicalize to the
        // same child are merged onto one shared node and reported under a
        // single arbitrary move, silently dropping every other legal move
        // that led there — worst exactly at shallow plies (the empty
        // board's 64 legal moves collapse to 3), which every self-play
        // game passes through. Verified in mcts.rs's
        // root_move_visits_default_config_collapses_symmetric_root_moves
        // test — this is not a hypothetical concern, it was caught by
        // Opus review of the PR that added root_move_visits and is
        // exactly what this exporter must avoid to produce a faithful
        // per-legal-move policy target.
        let mut engine = MCTSEngine::new(MCTSConfig {
            max_iterations: iterations,
            seed: Some(seed.wrapping_add(ply as u64)),
            use_transposition_table: false,
            ..Default::default()
        });
        let (best_move, _) = engine.search(&bb).expect("legal moves exist");
        let policy: Vec<(u8, u8, u32)> = engine
            .root_move_visits()
            .into_iter()
            .map(|(mv, visits)| (mv.shape, mv.position, visits))
            .collect();

        rows.push(PendingRow {
            ply,
            qfen: State::new(bb).to_qfen(),
            side_to_move,
            policy,
        });

        bb = apply_move(&bb, &best_move);
        ply += 1;
    }
}

pub fn root_move_visits(&self) -> Vec<(Move, u32)>

Visit-count distribution over the root’s legal moves from the most recent search() call — the raw material for an AlphaZero-style soft policy target (visits / total_visits per move), as opposed to the single argmax move search() returns. Empty if search() returned None (no legal moves) or hasn’t been called yet.

With use_transposition_table enabled (the default), this is NOT one entry per legal move. Root moves that canonicalize to the same child state are merged onto one shared node, reported under a single arbitrary “first discovered” move — every other legal move that led there is silently absent, not just uncounted. This is worst exactly where self-play data collection needs it most: the empty board’s 64 legal first moves collapse to 3 entries (see root_move_visits_default_config_collapses_symmetric_root_moves below, and docs/benchmarks/quantik-game-tree-census-2026-07-13.md for how orbit size — and therefore collapse severity — shrinks with depth but is large at the shallow plies every game starts from). For a faithful per-legal-move policy target, run search() with use_transposition_table: false.

Examples found in repository

examples/selfplay_export.rs (line 114)

fn play_game(seed: u64, iterations: u32) -> (Vec<PendingRow>, WinStatus) {
    let mut bb = Bitboard::EMPTY;
    let mut rows = Vec::new();
    let mut ply = 0u32;

    loop {
        if has_winning_line(&bb) {
            return (rows, check_winner(&bb));
        }
        let legal = generate_legal_moves(&bb);
        if legal.is_empty() {
            // No legal moves: the side to move loses (see Global
            // Constraints — this is a decisive result, never a draw).
            let loser = current_player(&bb).unwrap();
            let winner = if loser == 0 {
                WinStatus::Player1Wins
            } else {
                WinStatus::Player0Wins
            };
            return (rows, winner);
        }

        let side_to_move = current_player(&bb).unwrap();
        // use_transposition_table MUST be false here: with it on (the
        // engine's actual default), root moves that canonicalize to the
        // same child are merged onto one shared node and reported under a
        // single arbitrary move, silently dropping every other legal move
        // that led there — worst exactly at shallow plies (the empty
        // board's 64 legal moves collapse to 3), which every self-play
        // game passes through. Verified in mcts.rs's
        // root_move_visits_default_config_collapses_symmetric_root_moves
        // test — this is not a hypothetical concern, it was caught by
        // Opus review of the PR that added root_move_visits and is
        // exactly what this exporter must avoid to produce a faithful
        // per-legal-move policy target.
        let mut engine = MCTSEngine::new(MCTSConfig {
            max_iterations: iterations,
            seed: Some(seed.wrapping_add(ply as u64)),
            use_transposition_table: false,
            ..Default::default()
        });
        let (best_move, _) = engine.search(&bb).expect("legal moves exist");
        let policy: Vec<(u8, u8, u32)> = engine
            .root_move_visits()
            .into_iter()
            .map(|(mv, visits)| (mv.shape, mv.position, visits))
            .collect();

        rows.push(PendingRow {
            ply,
            qfen: State::new(bb).to_qfen(),
            side_to_move,
            policy,
        });

        bb = apply_move(&bb, &best_move);
        ply += 1;
    }
}

pub fn iterations_performed(&self) -> u32

pub fn nodes_created(&self) -> usize