+-------------------------------------------------------------------+
|                            Sunfish                                |
|                                                  R.Kubo 2009-2012 |
+-------------------------------------------------------------------+

KUBO Ryosuke


1. Introduction
2. Compile
3. Files
4. SFMT
5. Usage
6. Tools
7. Clustering


| 1. Introduction
+--------------------------------------------------------------------

Sunfishは将棋の対局, 及び学習を行うプログラムです.
このプログラムはC++で書かれています.


| 2. Compile
+--------------------------------------------------------------------

2.1 g++の場合

(a). All

	make

(b). Sunfish

	make sunfish


2.2 Visual Studio 2017 の場合

sikou.sln または usi.sln を開いてビルドしてください.

| 3. Files
+--------------------------------------------------------------------

3.1 ソースコードとスクリプト

(a). Main

book.cpp         : 定跡管理
consultation.cpp : 合議
csa.cpp          : CSAプロトコルによる通信対局
data.cpp         : プログラム中で使用する静的なデータ
debug.cpp        : デバッグ用出力
effect.cpp       : 利き情報の差分計算
evaluate.cpp     : 評価関数
feature.h        : 特徴抽出
filelist.cpp     : ファイル列挙
gencheck.cpp     : 王手生成
generate.cpp     : 合法手生成
hash.cpp         : 局面ハッシュ
kifu.cpp         : 棋譜の入出力
kisen2csa.cpp    : 棋泉からCSAへの変換
learn.cpp        : バッチ学習(Bonanza Method)
learn2.cpp       : オンライン学習
limit.cpp        : 制限時間管理
match.cpp        : 対局
match.h          : 対局関連ヘッダ
mate.cpp         : 詰み探索
param.cpp        : 評価パラメータ
rand.h           : 疑似乱数生成
shogi.cpp        : Shogiクラス
shogi.h          : 将棋のルールや局面評価関連
shogi2.cpp       : 局面評価つきShogiクラス
string.cpp       : 文字列処理
sunfish.cpp      : Sunfishのメインルーチン
sunfish.h        : Sunfishヘッダ
think.cpp        : Nega-Max 探索
thread.cpp       : 並列探索
tree.cpp         : Treeクラス
uint96.cpp       : 符号なし96ビット演算
uint96.h         : 符号なし96ビット演算ヘッダ

(b). Tools

change.cpp       : evdataの一部の要素を書き換え
cut.cpp          : evdataから一部の要素を削除
disp.cpp         : evdataの一部の要素を表示
evcsv.cpp        : evdataを解析して統計情報などをCSV形式で出力するツール
kisen2csa.cpp    : 棋泉からCSAへ変換
ins.cpp          : evdataに要素を追加
offset.cpp       : パラメータのオフセット管理
offset.h         : パラメータのオフセット管理ヘッダ

ban.pl           : gdbのShogi::_banの出力を見やすく整形
csvs.pl          : CSVの各列の合計を計算(csalog.csvに使用)
dedupe.pl        : CSA形式ファイルの重複を削除します.
delcr.pl         : 改行コードを CR + LF から LF に変換するツール(nkfがあれば必要なし)
demo_board.pl    : 学習の様子をグラフィカルに表示
demo_learn.pl    : 学習の様子をグラフィカルに表示
rcopy.pl         : CSA形式ファイルをランダムに選択し, 複製します.
rmove.pl         : CSA形式ファイルをランダムに選択し, 移動します.
time.pl          : CSA形式ファイルから消費時間計算

client.sh        : Bonanza Methodクラスタ化のためのクライアント
server.sh        : Bonanza Methodクラスタ化のためのサーバ
setc.sh          : Bonanza Methodクラスタ化のためのクライアント環境構築
stop.sh          : nconfのstopオプション切り替え

(c). Windows GUI

resource.h       : リソースのヘッダ
sikou.cpp        : sikou.dll
sikou.h          : sikou.dllヘッダ
sikou.rc         : リソースファイル
wconf.cpp        : 設定ファイルの読み書き(USIも共通)
wconf.h          : 設定ファイルの読み書き(USIも共通)ヘッダ
window.cpp       : Sikou.dllのウィンドウ

(d). USI Protocol

usi.cpp          : USIプロトコル


3.2 Executable Files

sunfish          : メインプログラム
evcsv            : evdataを解析して統計情報などをCSV形式で出力するツール
ins              : evdataに要素を追加
cut              : evdataから要素を削除


3.3 Data Files

book             : 定跡
evdata           : 評価パラメータ
evinfo           : 学習履歴(学習時に生成)
hash             : 局面ハッシュを求めるための数値列

************* 定跡ファイル book について *************
book内部では局面ハッシュを使用しています.
hashファイルがない場合にhashファイルを再生成しますが,
これには乱数を用いており毎回異なる内容が出力されます.
そのため, bookを生成したときのhashファイルがないと
定跡を読み込むことができません.
******************************************************


3.4 Configures

lconf            : 学習の設定ファイル
nconf            : 通信対局の設定ファイル

* 各設定ファイル内に説明があります.


3.5 SFMT Library

SFMT/            : SFMT


3.6 Debug

debug.csa        : 棋譜を随時書き出し
tdebug           : 探索木のrootの情報書き出し

* いずれも, コンパイル時にNDEBUGマクロを無効にすると
  出力されます.


| 4. SFMT
+--------------------------------------------------------------------

Sunfishでは以下で配布されているSFMTのルーチンを使用しています.
http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/index-jp.html
(最終アクセス.. Dec. 2010)

ライセンスについて詳しくはSFMT/LICENCE.txt を参照してください.


| 5. Usage
+--------------------------------------------------------------------

5.1 Help

	./sunfish --help


5.2 Game

(a) Sunfishと対局をしたいなら..

	./sunfish -g -d 20 -t 30

-g : Sunfishは後手番で対局します.
     あなたが後手番で対局したいなら, -s オプションを使用します.
	 -s と -g を同時に指定するとコンピュータ同士の対局になります.
-d : 探索深さ
-t : Sunfishの1手当たりの最大思考時間 (秒)

(b) 指し手の入力例

指し手は4文字で入力します.
最初の2文字が移動元, 残りの2文字が移動先を表します.
アルファベットの大文字小文字はどちらでもかまいません.

MOVE >4958          4九 -> 5八
MOVE >5655          5六 -> 5五
MOVE >KI23          持駒の金 -> 2三

成, 不成は次の行でY/nで答えます.

******************** 実行時の注意 ******************
対局を行う場合にはhash, book, evdataが
カレントディレクトリに必要です.
hashは局面のハッシュ値を求めるための乱数列を記録し,
bookではそれに基づくハッシュ値を用いています.
従って, bookとhashの片方でもない場合,
あるいはbookとhashの対応が取れない場合
定跡を使用することができません.
また, bookは32bit, 64bitのそれぞれのアーキテクチャで
異なります.
evdataがない場合は局面評価のためのパラメータが
全て0で初期化されます.
****************************************************

(c) コマンドモード

起動時に -f オプションを使用した場合や
起動後に"cmd"と入力した場合, 及び終局時には
コマンドモードに移行し, 画面上の表示がに
"MOVE >" から "CMD >" に変化します.
コマンドモードでも上記の指し手の入力はできますが,
コンピュータによる対局は行いません.
元のモード(プレイモード)に戻る場合は
"play"と入力します.
コマンドモードでは様々なコマンドによる操作が可能です.
以下にコマンドの一覧を示します.
(多くのコマンドはプレイモードでも使用可能)

play       : プレイモードに移行
cmd        : コマンドモードに移行
help       : コマンドの一覧を表示
quit       : プログラムの終了

prev       : 1手戻す.
p          : (prevに同じ)
next       : 1手進める.
n          : (nextに同じ)
p10        : 10手戻す.
n10        : 10手戻す.
top        : 初手まで戻す.
end        : 終局まで進める.
num        : 現在までの手数を表示
num=**     : 指定した手数まで移動

moves      : 合法手を列挙
captures   : 駒を取る手を列挙
nocaptures : 駒を取らない手を列挙
tactical   : 戦略的な手を列挙
check      : 王手を列挙
book       : 定跡手を表示
mate       : 詰みを調べる.

config     : 設定を表示
sente=**   : 先手番を指定("USER" or "COM")
gote=**    : 後手番を指定("USER" or "COM")
depth=**   : 探索深さを指定
time=**    : 1手当たりの思考時間を指定
hash=**    : ハッシュ表のサイズ変更

print      : 棋譜を画面に出力
input=**   : 指定した棋譜ファイルを開く.
output=**  : 指定したファイル名で棋譜を保存する.


5.3 定跡作成

	./sunfish -b Directory

定席に登録するCSA形式の棋譜ファイルが保存されているディレクトリを
指定します. その直下にあるCSA形式ファイルが読み込まれます.

	./sunfish -b Directory 50

定跡に登録する手数を指定することができます.
上記の例では各棋譜ファイルの開始局面から
50手までのみを定跡に登録します.


5.4 Learning

	./sunfish -l

Bonanza Methodによる学習を実行するには -l オプションをつけます.
学習に関する設定は全てlconfファイルに記述します.
lconfの書き方は付属のlconfファイル内にコメントがあります.

********************** 注意 ************************
コンパイル時のオプション-DNLEARNによって
学習部はコンパイルされないようになっています.
従って, Makefileの内容を次のように書き換える必要が
あります.

Makefile :
	CFLAGS += -DNLEARN => #CFLAGS += -DNLEARN

また, learn.cpp内では抑制係数の値が記述されておらず,
"NON"と書かれている部分を適切に記述することで
コンパイルが可能になります.
****************************************************


5.5 CSA client

	./sunfish -n

CSAプロトコルによる通信対局を行うには -n オプションをつけます.
各種設定は全てnconfファイルに記述します.
nconfの書き方は付属のnconfファイル内にコメントがあります.


5.6 Other options

-f or --file
起動時にCSA形式の棋譜ファイルを開いてコマンドモードに入ります.

-o or --node
探索ノード数の上限を指定します.

-m or --hash-mbytes
ハッシュ表のサイズをMBytesで指定します.
(1要素の2のべき乗倍に切り捨て)

-c or --csa
局面や指し手の表示にCSA形式を使用します.

-p or --parallel
スレッド数を指定します.

-a or --agree
棋譜との一致度を調べます.

-v or --version
Sunfishのバージョン情報を表示します.


5.7 Additional explanation

-b, -l, -v オプションが指定された場合,
その他のオプションは全て無視されます.


| 6. Tools
+--------------------------------------------------------------------

6.1 evcsv

	./evcsv

evdataを読み込んで平均や分散などをevdata.csvに出力します.


6.2 cut

evdataから一部の要素を取り除きます.
評価項目を減らす場合に, 減らす前のバージョンで
cutを実行して下さい.
例えばversion 1.19からversion 1.20では
たくさんの評価項目を減らしましたが,
その際のコマンドを ver1.20.sh に記述し添付しています.


6.3 ins

evdataに新しい要素を加えます.
評価項目を増やした場合に用います.
cutとは反対に追加後の新しいバージョンで
insを実行することに注意してください.
使用方法はcutと同様で, なお追加された要素は
0で初期化されます.


6.4 change

evdataの一部の要素の値を書き換えます.
評価項目名とオフセット, 及び書き換え後の値を
起動時引数で指定します.


6.5 disp

evdataの一部の要素の値を標準出力に出力します.


6.6 delcr.pl

	./delcr.pl

ディレクトリ内にあるソースファイルからCRコードを削除します.


6.7 rcopy.pl

	./rcopy.pl Directory1 Directory2 100

上記の例ではDirectory1内のCSA形式棋譜ファイルのうち,
ランダムに選んだ100個をDirectory2へコピーします.
学習ようの棋譜を用意するときなどに使用します.


6.8 rmove.pl

rcopy.plのファイル移動版です.


6.9 dedupe.pl

	./dedupe.pl Directory1 Directory2

2つのディレクトリ内のCSA形式棋譜ファイルについて
重複するファイルを削除します.


6.10 ban.pl

gdbでShogi::_banの内容を出力したものを
見やすい表記に直します.


6.11 time.pl

CSA形式棋譜ファイルから消費時間を調べて表示します.


| 7. Clustering
+--------------------------------------------------------------------

client.sh, server.shを使用することで,
機械学習のクラスタ化が可能です.
但し, 各マシンにあらかじめ棋譜を割り振らなければいけません.

sunfishには隠しオプション -lp, -lg, -laがあります.
(1) -lp は棋譜を読み込んで, pvmoveファイルに保存.
(2) -lg はpvmoveファイルを読み込み, gradientファイルを生成.
(3) -la はgradientを読み込み, evdataを更新.
-l オプション(normalモード)はこれら(1), (2), (3)を全て行いますが,
隠しオプションによりこのうちの一部の作業のみを行うことができるわけです.

以下にclient.shとserver.shの動作を示します.

1. 各クライアントマシンでclient.sh実行
2. サーバマシンでserver.sh実行
3. サーバからクライアントへevdataを送信
4. クライアントは(1)を実行
5. クライアントは(2)を実行し, gradientをサーバへ送信
6. サーバは(3)を実行
7. サーバからクライアントへevdataを送信
8. 一定回数まで手順5以降を繰り返す.
9. 4へ戻る.

以下に実際に環境を構築する手順を簡単に示します.

1. hosts内にホスト名とユーザ名, パスワード(など)を記述
2. クライアントとサーバにソースをコピーしてコンパイル
3. 各クライアントに棋譜ファイルを用意
4. lconfを書き換える.
5. client.shを実行
6. server.shを実行
(必ずserver.shの実行は最後に行う)