ShogiArenaは、USI対応の将棋エンジンを自動で対局させ、結果を比較するPython製のツールです。 エンジンの強さの検定、パラメータの調整、自己対局による学習用棋譜の生成にも使えます。
ドキュメント | クイックスタート | PyPI | 変更履歴
| やりたいこと | ShogiArenaの機能 |
|---|---|
| エンジン同士を対局させる | 総当たり、基準エンジンとの対局（gauntlet）、並列実行 |
| 変更前後の強さを比べる | 対局結果から統計的に検定するSPRT（GSPRT） |
| パラメータを調整する | 対局結果を使ってUSIオプションを調整するSPSA |
| 学習用の棋譜を作る | 自己対局、SFEN／KIF／CSA／バイナリ形式での出力 |
| 複数のマシンで対局を回す | SSH接続によるリモート実行 |
設定、棋譜、対局結果は実行ごとに保存されます。 途中で止めたトーナメントの再開や、保存した結果の集計もできます。
shogiarena-demo.mp4
ブラウザで進行中の対局や順位表を確認し、棋譜を再生できます。 SPRTの判定やSPSAの更新状況も表示でき、終了後に保存した結果を開き直すこともできます。
Python 3.11以上が必要です。 Windows x86_64、Linux x86_64／arm64、macOS Intel／Apple Siliconで動作します。
pip install shogiarena
shogiarena --version対局に使うUSIエンジンの実行ファイルと、そのエンジンに必要な評価関数は別途用意してください。 エンジンの入手から試したい場合は、クイックスタートにYaneuraOuと水匠5を取得する手順があります。
インストールの詳細はインストールガイドを参照してください。 SSHでのリモート実行先はLinux x86_64のみ対応しています。
手元のUSIエンジンを二つ登録して、動作確認用に10局対局させます。 同じエンジンの設定違いを比較することもできます。
まず、次の三つのファイルを同じディレクトリに作ります。
engine_pathは実行ファイルのパスに置き換えてください。
working_directoryには、エンジンの作業ディレクトリ（通常は実行ファイルのあるディレクトリ）を指定します。
WindowsではC:/engines/engine_a.exeのように、/で区切る書き方も使えます。
engine_a.yaml:
name: "Engine A"
engine_path: "/path/to/engine_a"
working_directory: "/path/to"
options:
Threads: 2
USI_Hash: 256engine_b.yaml:
name: "Engine B"
engine_path: "/path/to/engine_b"
working_directory: "/path/to"
options:
Threads: 2
USI_Hash: 256ThreadsとUSI_Hashは、それぞれスレッド数とハッシュメモリ量（MB）の指定例です。
使えるオプションはエンジンによって異なるので、必要な評価関数のパスなども含めて、エンジン設定を参考に調整してください。
tournament.yaml:
experiment_name: "first_tournament"
engines:
- engine_path: "engine_a.yaml"
- engine_path: "engine_b.yaml"
tournament:
scheduler: "round_robin"
games_per_pair: 10
num_parallel: 2
rules:
time_control:
time_ms: 10000
increment_ms: 100
dashboard:
enabled: true
api_port: 8080この設定では2局を並列に進めます。 各エンジンの持ち時間は10秒で、1手ごとに0.1秒加算します。
ファイルを作ったディレクトリで、設定を確認してから実行します。
--dry-runでは設定と対局予定を確認できますが、エンジンは起動しません。
shogiarena run tournament tournament.yaml --dry-run --run-dir runs/first_tournament
shogiarena run tournament tournament.yaml --run-dir runs/first_tournament実行中はhttp://localhost:8080でダッシュボードを開けます。
棋譜や対局結果はruns/first_tournamentに保存されます。
終了後も、保存先を指定すればダッシュボードで結果や棋譜を確認できます。
shogiarena dashboard serve --run-dir runs/first_tournament端末で勝敗を集計したり、JSONやCSVで出力したりすることもできます。
shogiarena results summary runs/first_tournament
shogiarena results summary runs/first_tournament --format json
shogiarena results summary runs/first_tournament --format csv対局結果を強さの比較に使うときは、completion_status.jsonで終了状態も確認してください。
正常完了と途中停止の違いや、集計から除外される対局の扱いは、トーナメントガイドで説明しています。
同じ設定ファイルを使って、Pythonスクリプトからトーナメントを実行できます。
import asyncio
from shogiarena.tournament import run_tournament
async def main() -> None:
result = await run_tournament(
"tournament.yaml",
run_dir="runs/example",
)
print(result)
asyncio.run(main())USIエンジンを直接操作して局面を解析するAPIもあります。 使い方はPythonライブラリガイド、関数や型の一覧はAPIリファレンスを参照してください。
用途別の設定テンプレートはexamples/configsにあります。
pip installでインストールした環境では、GitHubから取得してください。
開発環境の準備や変更の検証方法は、コントリビュートガイドにまとめています。
ShogiArenaはMIT Licenseで公開しています。