Merge branch 'main' of https://github.com/khalid-a-omar/Polyfish

README.md

@@ -1,17 +1,10 @@
-
-
 ## Overview
-**Polyfish** is a UCI chess engine based on [Stockfish](https://github.com/official-stockfish). It is identical to Stockfish with the added capability of handling [Polyglot](https://web.archive.org/web/20191216195456/http://hardy.uhasselt.be/Toga/book_format.html) books and [CTG](https://www.chessprogramming.org/CTG) books
+**Polyfish** is a UCI chess engine based on [Stockfish](https://github.com/official-stockfish). It is identical to Stockfish with the added capability of handling [Polyglot](https://web.archive.org/web/20191216195456/http://hardy.uhasselt.be/Toga/book_format.html) and [CTG](https://www.chessprogramming.org/CTG) book.
 
-**Polyfish** supports two polyglot BIN books at the same time. The second book is only probed if the first book has no moves for the given position. The engine starts searching only if no move is found in either the first book or the second book.
-
-**Polyfish** also supports CTG book format, which is **C**hessBase Opening **T**ree of **G**ames, used natively by ChessBase product family. The code and logic to read CTG in **Polyfish** is based on the following resources:
-* [remoteglot](https://github.com/madnight/remoteglot)
-* [jja](https://git.sr.ht/~alip/jja)
-* [ctgexporter](https://github.com/sshivaji/ctgexporter)
-* [CTG Specifications](https://web.archive.org/web/20210129162445/https://rybkaforum.net/cgi-bin/rybkaforum/topic_show.pl?tid=2319)
+**Polyfish** supports two books at the same time, one could configure two CTG books, two BIN books, or one CTG and one BIN in either order. The second book is only probed if the first book has no moves for the given position. The engine starts searching only if no move is found in either the first book or the second book.
 
 #### Read [Note about CTG books](https://github.com/khalid-a-omar/Polyfish#note-about-ctg-books)
+#### Read [Questions and Answers about Polyfish book support](https://github.com/khalid-a-omar/Polyfish#questions-and-answers)
 
 ## Files
 
@@ -23,9 +16,9 @@ This distribution of Polyfish consists of the following files:
 
   * [AUTHORS.md](https://github.com/khalid-a-omar/Polyfish/blob/main/AUTHORS.md), a text file with the list of authors for the project. *Click [here](https://github.com/official-stockfish/Stockfish/blob/master/AUTHORS) to see the original AUTHORS file of Stockfish*
 
-  * [src](https://github.com/khalid-a-omar/Polyfish/blob/main/src), a subdirectory containing the full source code. *Click [here](https://github.com/official-stockfish/Stockfish/tree/master/src) to see the original source code of Stockfish*
+  * [src](https://github.com/khalid-a-omar/Polyfish/blob/main/src), a sub-directory containing the full source code. *Click [here](https://github.com/official-stockfish/Stockfish/tree/master/src) to see the original source code of Stockfish*
 
-  * [Tools](https://github.com/khalid-a-omar/Polyfish/blob/main/Tools), a subdirectory containing scripts used to create Windows and Linux builds.
+  * [Tools](https://github.com/khalid-a-omar/Polyfish/blob/main/Tools), a sub-directory containing scripts used to create Windows and Linux builds.
 
 ## UCI options
 
@@ -48,16 +41,16 @@ Polyfish also supports the following UCI options
 	This option has no effect or use if the loaded book is a Polyglot (BIN) book
 
   * #### CTG/BIN Book 2 File
-    Same explaination as **CTG/BIN Book 1 File**, but for the second book
+    Same explanation as **CTG/BIN Book 1 File**, but for the second book
 
   * #### Book 2 Width
-    Same explaination as **BIN Book 1 Width**, but for the second book
+    Same explanation as **Book 1 Width**, but for the second book
 
   * #### Book 2 Depth
-    Same explaination as **BIN Book 1 Depth**, but for the second book
+    Same explanation as **Book 1 Depth**, but for the second book
 
   * #### (CTG) Book 2 Only Green
-    Same explaination as **(CTG) Book 1 Only Green**, but for the second book
+    Same explanation as **(CTG) Book 1 Only Green**, but for the second book
 
 
 ## UCI commands
@@ -138,7 +131,11 @@ Polyfish also supports the following UCI commands
 	```
 
 ## Note about CTG books:
-CTG book format specification is not available to the public from Chessbase. The code that reads and parses CTG books is based on the reverse engineered book specification published on [CTG Specifications](https://web.archive.org/web/20210129162445/https://rybkaforum.net/cgi-bin/rybkaforum/topic_show.pl?tid=2319) as well as the other resources mentioned earlier.
+<ins>**C**</ins>hessBase Opening <ins>**T**</ins>ree of <ins>**G**</ins>ames (CTG), is the natibe book format used by all ChessBase products. The specification is not made available to the public from Chessbase. Instead, **Polyfish** relied on the following public resources:
+* [CTG Specifications](https://web.archive.org/web/20210129162445/https://rybkaforum.net/cgi-bin/rybkaforum/topic_show.pl?tid=2319)
+* [remoteglot](https://github.com/madnight/remoteglot)
+* [jja](https://git.sr.ht/~alip/jja)
+* [ctgexporter](https://github.com/sshivaji/ctgexporter)
 
 The reverse engineered specs are good enough to proble the book for moves, but it does not provide the same functionality as Chessbase own products. The following is a list of known limitations of **Polyfish**'s CTG book implementation:
 - Does not support underpromotion, which means all promotion moves are assumed to be to a Queen
@@ -149,3 +146,27 @@ The reverse engineered specs are good enough to proble the book for moves, but i
 The move weight calculated by **Polyfish** (can be seen using the **book** command) is my own attempt to compensate for all the missing/unknown information about the CTG specification. Using the calculated weight, **Polyfish** can pick the best move for a given position in 99% of the times because it ustilizes existing move statistics such as number of wins, draws, and losses, as well as "known" annotations (!, !?, ?!, ??, OnlyMove, etc...) and recommendations (Green vs. Red) if available.
 
 Despite the fact that Polyfish can read and play from CTG Book, it is not going to be identical to Chessbase own products since it is based on the partial CTG specification available publicly. Use at your own risk!
+
+## Questions and Answers
+
+- **<ins>How do I force my CTG book to play only Green moves?</ins>**<br/>
+You can force the engine to only pick and play Green moves from your configured CTG book by enabling the option ```CTG) Book 1 Only Green``` or ```(CTG) Book 2 Only Green``` (enabled by default)
+<br/><br/>
+
+- **<ins>If my CTG book has more than one Green move for a given position, which move will be played?</ins>**<br/>
+The move selection from CTG books and BIN books depends on the attributes (properties and statistics) associated with the moves in question. Such attributes are the WDL game count (Win, Draw, and Loss) as well as move recommendations (Green or Red) and commentary (!, !!, !?, ?, ?!, ??, only move, Zugzwang) which are stored in the CTG book (note that BIN books only have number of games without WDL statistics, recommendations, commentary, or annotations).
+<br/><br/>Polyfish uses all available move attributes depending on the book type to calculate a **Weight** which indicates how good or bad the move is. The higher the weight, the better the move.
+<br/><br/>After calculating move weights, the engine selects one of the top **N** moves randomly. The value of **N** can be configured using the UCI option ```Book 1 Width``` and ```Book 2 Width```
+<br/><br/>
+
+- **<ins>How do I make the engine play the best Green move available?</ins>**<br/>
+Configure the ```Book 1 Width``` (or ```Book 2 Width```) to the value **1** and make sure to enable the option ```(CTG) Book 1 Only Green``` (or ```(CTG) Book 2 Only Green```)
+<br/><br/>
+
+- **<ins>What move will be played if my CTG book has no Green moves for a given position?</ins>**<br/>
+If no Green moves are found in the configured CTG book,  then engine will check the value of the UCI option ```(CTG) Book 1 Only Green``` (or ```(CTG) Book 2 Only Green```) in order to decide if it is allowed to play a non Green move. If not allowed then no move is played and the next book is checked, if configured, or the engine will start thinking.
+<br/><br/>If it is allowed to play a non Green move, then the engine will calculate the weights of available moves (as described earlier) and play one of the top weight moves depending the configured value of ```Book 1 Width``` or (```Book 2 Width```)
+<br/><br/>
+
+- **<ins>What effect does the options ```(CTG) Book 1 Only Green``` and ```(CTG) Book 2 Only Green<``` have on my Polyglot (BIN) book?</ins>**<br/>
+The options ```(CTG) Book 1 Only Green``` and ```(CTG) Book 2 Only Green``` do not have any effect on BIN books so it does not matter if they are checked (true) or unchecked (false). Use these two options only for CTG books