Add tune-params subcommand for PUCT hyperparameter tuning via QRS optimization

[ChinChangYang]

Summary

Adds a tune-params subcommand for automated PUCT hyperparameter tuning using QRS (Quadratic Response Surface) optimization. The optimizer runs sequential head-to-head matches between a base bot and an experiment bot, fitting a quadratic logistic regression model to propose better parameter combinations over time.

Currently tunes cpuctExplorationLog by default, with the framework supporting additional PUCT dimensions.

Changes

New: tune-params subcommand (cpp/command/tuneparams.cpp)

• Runs head-to-head matches between a fixed base bot (bot0) and an experiment bot (bot1)
• After each game, feeds the outcome into QRSTuner::addResult()
• Proposes the next parameter point via QRSTuner::nextSample() (MAP optimum + decaying Gaussian noise)
• Reports progress at 10% intervals with ETA and 95% confidence intervals (delta method) for each tuned parameter
• Prints best-found values and suggested match command to verify results
• Graceful SIGINT/SIGTERM shutdown (matches pattern in match.cpp)

New: cpp/qrstune/QRSOptimizer.h + QRSOptimizer.cpp

• QRSModel — Quadratic logistic regression with L2 regularization; Newton-Raphson MAP estimation; feature map is [1, x_i, x_i², x_i·x_j]
  • computeOptimumSE() — 95% CIs via delta method (implicit differentiation through MAP optimization)
  • hasConvexDim() — Detects noisy/unreliable dimensions and falls back to uniform sampling
• QRSBuffer — Sample storage with confidence-based pruning: drops samples whose predicted win rate falls > 0.25 below the current MAP best, keeping at least 30 oldest samples for diversity
• QRSTuner — Top-level interface: proposes next sample, records results, refits model periodically, prunes, decays exploration noise linearly (σ: 0.40 → 0.05)
• 15 unit test suites covering feature computation, sigmoid, Gaussian elimination, 1D/2D model fitting, convergence, convex-dimension detection, Newton-Raphson stability, and convergence scaling (100/1000/10000 trials)

Enhanced: match command statistics (cpp/command/match.cpp)

• Tracks pairwise W/L/D counts during the match loop
• Prints Bradley-Terry MLE Elo (Newton-Raphson solver with convergence warning)
• Wilson 95% CI on win rate per pairing
• One-tailed p-value for whether the experiment bot's win rate exceeds 50%

New: cpp/core/elo.h + elo.cpp, cpp/core/fancymath.h + fancymath.cpp

• Bradley-Terry Elo estimation and statistical functions extracted to core namespaces

New: cpp/configs/tune_params_example.cfg

Example config with 500 trials, maxVisits = 500, Tromp-Taylor rules with komi 7, and GTP-equivalent search defaults (useUncertainty, policyOptimism, useNoisePruning, useGraphSearch).

Documentation

• README.md — Added command example for tune-params
• cpp/README.md — Added qrstune/ to source folder summary and tuneparams.cpp to command list

Test plan

• Unit tests pass (./katago runtests — 15 QRSTune test suites)
• Run tune-params with example config on real model to verify end-to-end tuning loop
• Run suggested match command to validate tuned parameters improve win rate

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com