miniosl

miniosl, facade as a Python module.

Many functions are imported from minioslcc implemented in C++20.

class miniosl.UI(init: str | BaseState | MiniRecord = '', *, prefer_text=None, default_format='usi')

general interface for shogi state (State , board position + pieces in hand), enhanced with move history (MiniRecord) and other utilities

Parameters:

• init – initial contents handled by load_record()

• prefer_text – preference of state visualization

• default_format – preference in __str__

make the initial state in shogi

>>> shogi = miniosl.UI()

or read csa/usi file (local or web)

>>> url = 'http://live4.computer-shogi.org/wcsc33/kifu/WCSC33+F7_1-900-5F+dlshogi+Ryfamate+20230505161013.csa'
>>> shogi = miniosl.UI(url)
>>> _ = shogi.go(10)
>>> print(shogi.to_csa(), end='')
P1-KY-KE * -KI *  * -GI-KE-KY
P2 * -HI-GI * -OU * -KI-KA * 
P3-FU * -FU-FU-FU-FU-FU-FU-FU
P4 *  *  *  *  *  *  *  *  * 
P5 * -FU *  *  *  *  * +FU * 
P6+FU *  *  *  *  *  *  *  * 
P7 * +FU+FU+FU+FU+FU+FU * +FU
P8 * +KA+KI *  *  * +GI+HI * 
P9+KY+KE+GI * +OU+KI * +KE+KY
+

analyze()

evaluate all positions in the current game

count_hand(color: Player, ptype: Ptype) → int

number of pieces in hand

eval(verbose=False) → Tuple[ndarray, list]

return value and policy for current state.

need to call load_eval() in advance

first()

go to the first state in the history

follow_opening(nth: int = 0)

make a move following the opening db

game_play()

make an interactive widget for playing in colab

genmove()

generate legal moves in the state

genmove_check()

generate legal moves giving check to the opponent

genmove_ja() → list[str]

generate legal moves in Japanese

go(step)

make moves (step > 0) or unmake moves (step < 0)

in_check()

return whether king of the side to move is in check

in_checkmate()

return whether king of the side to move is in checkmate

ipywidget()

make an interactive widget for viewing record in colab

ipywidget_slider()

make an interactive widget for colab or jupyter notebooks

last()

go to the last state in the history

last_move() → Move | None

the last move played or None

last_to() → Square | None

the destination square of the last move or None

>>> shogi = miniosl.UI()
>>> shogi.last_to()
>>> _ = shogi.make_move('+2726FU')
>>> shogi.last_to() == miniosl.Square(2, 6)
True

load_eval(path: str = '', device: str = '', torch_cfg: dict = {})

load parameters of evaluation function from file

parameters will be passed to inference.load().

load_opening_tree(filename)

load opening db

load_record(src: str | BaseState | MiniRecord = '')

load a game record from various sources.

Parameters:

src – BaseState or MiniRecord or URL or filepath containing .csa or usi.

load_record_set(path: str, idx: int)

load idx-th game record in RecordSet

Parameters:

path – filepath for .npz generated by RecordSet.save_npz() or sfen text

make_move(move)

make a move in the current state

make_opening_db_from_sfen(filename: str, threshold: int = 100)

make opening tree from sfen records, and save in npz

mcts(budget: int = 100, report: int = 4, *, batch_size=1, resume_root=None)

run mcts - budegt: number of simulations - report: number of (interim) report during search

opening_moves()

retrieve or show opening moves.

Note: need to load data by load_opening_tree() in advance

previous_repeat_index() → int

the latest repeating state the history

pv_to_ja(pv: list[minioslcc.Move]) → list[str]

show moves in Japanese

repeat_count() → int

number of occurrence of the state in the history

replay(idx: int, show_hint: bool = False)

move to idx-th state in the history

show_features(plane_id: int | str, *args, **kwargs)

visualize features in matplotlib.

Parameters:

plane_id – 'pieces' | 'hands' | 'lastmove' | 'long' | 'safety', or integer id (in internal representation)

show_top8_moves(verbose=False)

suggest top8 moves by policy

to_anim(*args, **kwargs)

make matplotlib animation showing current game record

to_csa() → str

show state in csa

to_img(*args, **kwargs)

show state in matplotlib image

Returns:

an image shown in colab or jupyter notebooks

to_move(move_rep: str) → Move

interpret string as a Move

to_np_cover() → array

make planes to show a square is covered (1) or not (0)

to_np_pack() → array

compress state information

to_np_state_feature() → array

make tensor of feature for the current state (w/o history).

• 44ch each 9x9 channel is responsible for a specific piece type and color - where each element is 1 (0) for existence (absent) of the piece for the first 30ch - filled by the same value indicating number of hand pieces for the latter 14ch

• 13ch for heuristic features

to_usi() → str

show state in usi

to_usi_history() → str

show the history in usi

>>> shogi = miniosl.UI()
>>> _ = shogi.make_move('+2726FU')
>>> _ = shogi.make_move('-3334FU')
>>> shogi.to_usi()
'sfen lnsgkgsnl/1r5b1/pppppp1pp/6p2/9/7P1/PPPPPPP1P/1B5R1/LNSGKGSNL b - 1'
>>> shogi.to_usi_history()
'startpos moves 2g2f 3c3d'

turn() → Player

side to move

unmake_move()

undo the last move

Training with torch

class miniosl.StandardNetwork(*, in_channels: int, channels: int, out_channels: int, auxout_channels: int, num_blocks: int, value_head_hidden: int = 256, broadcast_every: int = 3)

Bases: PVNetwork

Standard residual networks with bottleneck architecture

Parameters:

• in_channels – number of channels in input features,

• channels – number of channels in main body,

• out_channels – number of channels in policy_head,

• auxout_channels – number of channels in miscellaneous output,

• value_head_hidden – hidden units in the last layer in the value head

forward(x: Tensor) → Tuple[Tensor, Tensor, Tensor]

take a batch of input features and return a batch of [policies, values, misc].

class miniosl.GameDataset(window_size: int, block_unit: int, batch_with_collate: bool = True)

Bases: Dataset

dataset for training.

• sample position by game index (a random position in the game record is returned)

• keep the latest GameRecordBlock s (e.g., 50) as in MuZero

Parameters:

• window_size – number of game records to keep

• block_unit – number of game records for a block, that is a unit in add/replace oporation

• batch_with_collate – need to specify collate_fn=lambda indices: dataset.collate(indices) for trainloader, if (and only if) True

add(new_block)

add or replace the oldest one with new_block

block_id() → int

number of block added so far

collate(indices)

make_block(compress_and_rm=True, strict=True)

a helper function to make a block

reshape_item(item)

sample_id(index)

stored_game_records()

unit_size() → int

number of records in a GameRecordBlock

Handle game records

see also Game record section, MiniRecord and RecordSet

miniosl.load_record_set(path: str, name: str = '', *, limit: int | None = None)

load miniosl.RecordSet from npz file

Visualization

miniosl.state_to_img(state: BaseState, *, decorate: bool = False, plane: ndarray | None = None, plane_color: str = 'orange', last_move_ja: str = '', last_to: Square | None = None, move_number: int = 0, repeat_distance: int = 0, repeat_count: int = 0, flip_if_white: bool = False, id: int = 4081) → Figure

make ShogiFig object including matplotlib figure as .fig

Parameters:

• state – state,

• decorate – highlight king location and piece covers for each color,

• plane – 9x9 numpy array to make a mark on squares,

• last_move_ja – last move in japanese,

• last_to – the destination square of the last move,

• move_number – ply in a game record,

• repeat_distance – distance to the latest same position,

• repeat_count – number of the occurrence of this state,

• flip_if_white – rotate180() if white to move

class miniosl.ShogiFig(state: BaseState, last_move_ja: str = '', move_number: int = 0, id: int = 4081)

data holding state and matplotlib objects

use self.fig for completed image.

make_move(move: Move | str)

update board and figure

Use external engines

class miniosl.UsiProcess(path_and_args: list[str], setoptions: list[str] = ['setoption name Threads value 1', 'setoption name USI_Hash value 16'], cwd: str | None = None)

Proxy for usi process

create process, initilaze its options and wait until readyok

Parameters:

path_and_args – list of path and argments

close() → bool

finish process

search(position: str, limit: str) → dict

search: give position with go commands, and wait bestmove

Returns hash contains “info”

Parameters:

• position – e.g., 'startpos'

• limit – e.g., 'byoyomi 1000'

class miniosl.UsiPlayer(engine: UsiProcess)

bridge between usi engine and CPUPlayer for self-play with GameArray.

name(self: minioslcc.SingleCPUPlayer) → str

think(self: minioslcc.SingleCPUPlayer, arg0: str) → minioslcc.Move

class miniosl.CPUPlayer

adaptor for PlayerArray

Parameters:

• player – object descendant of SingleCPUPlayer

• greedy – indicating greedy behavior

Note

if you give a player implemented in Python, please make sure its lifetime

name(self: minioslcc.CPUPlayer) → str