ShogiArena

ShogiArenaは、USI対応の将棋エンジンを自動で対局させ、結果を比較するPython製のツールです。 エンジンの強さの検定、パラメータの調整、自己対局による学習用棋譜の生成にも使えます。

ドキュメント | クイックスタート | PyPI | 変更履歴

できること

設定、棋譜、対局結果は実行ごとに保存されます。 途中で止めたトーナメントの再開や、保存した結果の集計もできます。

ダッシュボード

https://github.com/user-attachments/assets/1cdebe23-b1a9-4d8e-91c0-f56ca970b569

ブラウザで進行中の対局や順位表を確認し、棋譜を再生できます。 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: 256

engine_b.yaml:

name: "Engine B"
engine_path: "/path/to/engine_b"
working_directory: "/path/to"
options:
  Threads: 2
  USI_Hash: 256

Threadsと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から使う

同じ設定ファイルを使って、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から取得してください。

• インストール
• 最初のトーナメント
• トーナメント
• SPRT／SPSA
• リモート実行
• エンジン設定
• ダッシュボード
• Pythonライブラリ
• CLIリファレンス

開発環境の準備や変更の検証方法は、コントリビュートガイドにまとめています。

ライセンス

ShogiArenaはMIT Licenseで公開しています。