Skip to contents

R-CMD-check pkgdown CRAN status Codecov test coverage CRAN downloads CRAN downloads total License: MIT Lifecycle: experimental

One evaluator, many consumers

The single source of truth for “how good is this position?” is mxo_evaluate(). It counts existence-gated m-lines (length-k extents with m marks of one colour and the rest empty) per axis class and sums a weighted contribution from each side’s perspective.

g <- mxo_example_game()
mxo_evaluate(g)                    # X perspective by default
#> [1] -255
mxo_evaluate(g, player = 2L)       # O perspective is the negation
#> [1] -255

The raw feature vector — same input the heuristic and the calibrator share — is available as an internal helper:

head(multixoR:::.mxo_line_features(g), 8L)
#> # A tibble: 8 × 4
#>   player     m axis_class count
#>    <int> <int> <chr>      <int>
#> 1      1     1 spatial       64
#> 2      2     1 spatial       54
#> 3      1     2 spatial        5
#> 4      2     2 spatial        0
#> 5      1     3 spatial        0
#> 6      2     3 spatial        0
#> 7      1     1 time           2
#> 8      2     1 time           0

Searcher and MCTS

mxo_search() implements negamax + α-β with a configurable branch_policy (all / promising / none). The branching factor of the multiverse is large, so none is the practical default for fast local lookahead.

small <- mxo_new_game(n = 3L, k = 3L)
small <- mxo_move(small, "present", 0L, 0L, 0L)
res <- mxo_search(small, depth = 1L, branch_policy = "none")
res$move
#> # A tibble: 1 × 5
#>   kind    L_src t_src   idx player
#>   <chr>   <int> <int> <int>  <int>
#> 1 present     0     1    13      2

mxo_mcts() is the real-time path: a light UCT with random or heuristic rollouts. It’s seedable for reproducibility.

set.seed(1L)
mc <- mxo_mcts(small, iterations = 30L,
               rollout = "random", branch_policy = "none")
mc$move
#> # A tibble: 1 × 5
#>   kind    L_src t_src   idx player
#>   <chr>   <int> <int> <int>  <int>
#> 1 present     0     1     2      2

Interpreting win estimates

mxo_win_prob() defaults to MCTS and returns a smoothed expected score with half credit for draws and bounded heuristic values for unfinished rollouts. With method = "heuristic", it uses the shipped logistic fit from small-board random-policy self-play; draw rows are excluded from that fit, so the estimate concerns decisive outcomes in its training setting. See data-raw/make_calibrator.R for the recipe. Fit diagnostics are not held-out validation, and neither method is a guaranteed win probability against people or across board configurations. Terminal draws return 0.5.

mxo_win_prob(small, player = 1L, method = "heuristic")
#> [1] 0.5428756

Move rating

mxo_rate_moves() is the type-stable per-move tibble the visualisation stack and the Shiny app consume. The label column applies chess-engine-style thresholds on the win-prob drop vs the best move.

head(mxo_rate_moves(small, method = "heuristic"), 6L)
#> # A tibble: 6 × 9
#>   kind    L_src t_src   idx player score win_prob  rank label
#>   <chr>   <int> <int> <int>  <int> <dbl>    <dbl> <int> <chr>
#> 1 present     0     1     1      2   -78    0.543    41 best 
#> 2 present     0     1     2      2   -70    0.543    28 best 
#> 3 present     0     1     3      2   -78    0.543    41 best 
#> 4 present     0     1     4      2   -72    0.543    35 best 
#> 5 present     0     1     5      2   -78    0.543    41 best 
#> 6 present     0     1     6      2   -70    0.543    28 best

mxo_ai_move() is the convenience wrapper for the app’s AI player; the difficulty knob maps to search depth and MCTS iteration counts.

mxo_ai_move(small, difficulty = "easy", seed = 1L)
#> # A tibble: 1 × 5
#>   kind   L_src t_src   idx player
#>   <chr>  <int> <int> <int>  <int>
#> 1 branch     0     0    13      2