rshogi-py 0.11.0

Python tools for shogi board handling, move legality, records, and training-data formats.

rshogi-py

rshogi-py は、Python から将棋の局面・指し手・合法性・棋譜・学習データ形式を扱うための ライブラリです。

English: rshogi-py provides Python tools for shogi board handling, move legality, game records, policy labels, and dataset formats.

Rust 製の rshogi core を内部で利用していますが、通常の Python モジュールとして使えるように 構成しています。通常はこの標準ビルドを利用してください。AVX2 対応の x86_64 CPU で AVX2 最適化版を使いたい場合は rshogi-py-avx2 を利用します。

Python API は cshogi から影響を受けています。

できること

• SFEN / USI から局面を構築し、指し手を適用して更新する
• 指し手の生成・検証を行い、局面を SFEN として出力する
• KIF / KI2 / CSA / JKF / SFEN などの棋譜形式を読み書きする
• policy label や学習データ向けに指し手・局面を変換する
• データセット向けに NumPy と扱いやすい packed position 形式を利用する

開発用インストール

python -m pip install maturin
maturin develop -m crates/rshogi-py/pyproject.toml

AVX2 ビルド

rshogi-py-avx2 は、AVX2 対応 x86_64 CPU 向けに最適化した同じ Python モジュールです。

python -m pip install rshogi-py-avx2

注意

• rshogi-py と rshogi-py-avx2 は同時にインストールせず、どちらか一方だけを利用してください。
• 幅広い環境では rshogi-py が安全な標準選択です。
• 学習向けの policy label 変換は rshogi.policy から利用できます。

Policy Label

from rshogi.core import Move
from rshogi.policy import compact_move_label, move_label
from rshogi.types import Color

mv = Move.from_usi("7g7f")

label = move_label(mv, Color.BLACK)
compact = compact_move_label(mv, Color.BLACK)

print(label)    # 2187 クラス
print(compact)  # 1496 クラス or None

クイック例

from rshogi.core import Board

board = Board()
board.apply_usi("7g7f")
print(board.to_sfen())

raw-state を Python から直接編集することもできます。

from rshogi.core import Board
from rshogi.types import Color, Piece, PieceType, Square

board = Board()
state = board.to_position_state()
state.set_piece(Square.from_usi("7g"), Piece(0))
state.set_piece(Square.from_usi("7f"), Piece.from_color_type(Color.BLACK, PieceType.PAWN))
state.ply = 42

board.set_position_state(state)
report = board.validate_all()
print(board.to_sfen())
print(report.is_valid())

USI の position 文字列を直接扱うこともできます。

from rshogi.core import Board, normalize_usi_position, parse_usi_position

board = Board()
board.set_usi_position("position startpos moves 7g7f 3c3d")

board2 = parse_usi_position("startpos moves 7g7f")
print(board2.to_sfen())

print(normalize_usi_position("position startpos"))  # "startpos"

構造化 import

rshogi-py は用途別の submodule から import できます。

# 型と定数
from rshogi.types import Color, PieceType, Square
from rshogi.core import Move, Move32

# 盤面
from rshogi.core import Board, PositionState, ValidationIssue, ValidationReport

# 棋譜
from rshogi.record import Record, RecordMetadata, GameResult

# 棋譜変換
record = Record.from_kif_str(kif_text)
kif_text = record.to_kif()

# 棋譜ファイル I/O
record = Record.from_kif_file("example.kif")
record.write_kif("example_out.kif")

# NumPy dtype
from rshogi.numpy import (
    PackedSfen,
    PackedSfenValue,
    HuffmanCodedPos,
    HuffmanCodedPosAndEval,
)

# Policy label
from rshogi.policy import move_label, compact_move_label

基本的には submodule から import してください。

from rshogi.core import Board
from rshogi.core import Move
from rshogi.record import Record

棋譜 I/O の注意

Record の棋譜 I/O は、内部の rshogi 実装と同じ互換方針で動作します。

• KIF/KI2 は ShogiHome/tsshogi 系の実務互換と shogi-validator 寄りの整形を意識しています。
• 変化手順と終局要約が同居する場合、to_kif() / to_ki2() は 変化：... を先に、 まで... を最後に出力します。
• from_kif_str() / from_ki2_str() で読んだ初手前コメントは Record.initial_comment に保持され、to_kif() / to_ki2() で 1 手目の前に戻ります。
• from_csa_str() / from_csa_file() は CSA 3.0 に合わせて '*comment だけを プログラムが読むコメントとして受理し、plain な 'comment は読み飛ばします。 受理した開始局面コメントは Record.initial_comment に保持されます。
• 互換性のため、手番行より前にある '*comment も initial_comment に正規化して受理します。
• RecordMetadata.comment は自由コメントではなく、KIF の 備考 / CSA の $NOTE / JKF header の 備考 に対応します。
• to_csa() は move comment と初期局面コメントを '*comment として出力し、 write_kif() / write_ki2() / write_csa() は末尾改行つきで書き出します。