1 2Legal details 3------------- 4 5PolyGlot 1.3 Copyright 2004-2005 Fabien Letouzey. 6 7This program is free software; you can redistribute it and/or modify 8it under the terms of the GNU General Public License as published by 9the Free Software Foundation; either version 2 of the License, or (at 10your option) any later version. 11 12This program is distributed in the hope that it will be useful, but 13WITHOUT ANY WARRANTY; without even the implied warranty of 14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15General Public License for more details. 16 17You should have received a copy of the GNU General Public License 18along with this program; if not, write to the Free Software 19Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 20USA 21 22See the file "copying.txt" for details. 23 24 25General 26------- 27 28PolyGlot 1.3 (2005/06/03). 29 30PolyGlot is a "UCI adapter". It connects a UCI chess engine to an 31xboard interface such as WinBoard. UCI2WB is another such adapter 32(for Windows). 33 34PolyGlot tries to solve known problems with other adapters. For 35instance, it detects and reports draws by fifty-move rule, repetition, 36etc ... 37 38 39Official distribution URL 40------------------------- 41 42The official distribution web site is Leo Dijksman's WBEC Ridderkerk: 43http://wbec-ridderkerk.nl/ This is where you should be looking for 44PolyGlot updates in the future. 45 46 47Install 48------- 49 50PolyGlot should have its own directory. The INI files for engines 51should also be put there. Dirtier solutions are needed when 52BookThinker is used though. 53 54On Windows the files "polyglot.exe" and "cygwin1.dll" (which you can 55download from http://wbec-ridderkerk.nl/) are needed. On Linux and 56Mac OS X only the file "polyglot_linux" or "polyglot_mac" is required. 57 58 59Compiling 60--------- 61 62The distribution comes up with Windows, Linux and Mac OS X binaries. 63Compiling is therefore not necessary on those systems unless you want 64to make a change in the program. In any case this section describes 65the compiling procedure, it is safe to skip it. 66 67PolyGlot is a POSIX application (Unix compatible), and was developed 68on Linux using g++ (the GNU C++ compiler). 69 701) Unix 71 72You should be able to compile it on any POSIX-compliant operating 73system (*not* Windows) with the following command line (or similar): 74 75> g++ -O2 -o polyglot *.cpp 76 77IMPORTANT: In "io.cpp", the variable "UseCR" should be set to "false". 78 79A Makefile is provided but might not work on your system ... 80 812) Windows 82 83On Windows, you *must* use Cygnus GCC to compile PolyGlot. 84 85IMPORTANT: In "io.cpp", the variable "UseCR" should be set to "true". 86 87 88Usage 89----- 90 91PolyGlot acts as an xboard engine. There should be no difference with 92a normal chess program as far as the interface (e.g. WinBoard) is 93concerned. 94 95PolyGlot is invoked using "polyglot <INI file>". Note that PolyGlot 96will look for the INI file in the current directory. If no <INI file> 97is given, "polyglot.ini" is selected. 98 99To use PolyGlot with XBoard, you would type something like this: 100> xboard -fd 'polyglot_dir' -fcp 'polyglot engine.ini' 101 102Quotes are important when there is a space in the argument. 103 104 105INI file 106-------- 107 108There should be a different INI file for each engine. Sections are 109composed of "variable = value" lines. See the sample INI files in the 110"example" directory. 111 112NOTE: There can be spaces in variable names or values. Do not use 113quotes. 114 1151) [PolyGlot] section 116 117This section is used by PolyGlot only. The engine is unaware of these 118options. The list of available options is detailed below in this 119document. 120 1212) [Engine] section 122 123This section contains engine UCI options. PolyGlot does not 124understand them, but sends the information to the engine at startup 125(converted to UCI form). You can add any UCI option that makes sense 126to the engine (not just the common options about hash-table size and 127tablebases). 128 129NOTE: use INI syntax, not UCI. For example "OwnBook = true" is 130correct. It will be replaced by PolyGlot with "setoption name OwnBook 131value true" at engine startup. 132 133Standard UCI options are "Hash", "NalimovPath", "NalimovCache" and 134"OwnBook". Hidden options like "Ponder" or "UCI_xxx" are automatic 135and should not be put in an INI file. 136 137The other options are engine-specific. Check their name using a UCI 138GUI or launch the engine in a console and type "uci". 139 140 141Options 142------- 143 144These should be put in the [PolyGlot] section. 145 146- "EngineName" (default: UCI name) 147 148This is the name that will appear in the xboard interface. It is 149cosmetic only. You can use different names for tweaked versions of 150the same engine. 151 152If no "Engine Name" is given, the UCI name will be used. 153 154- "EngineDir" (default: ".") 155 156Full path of the directory where the engine is installed. You can use 157"." (without the quotes) if you know that PolyGlot will be launched in 158the engine directory or the engine is in the "path" and does not need 159any data file. 160 161- "EngineCommand" 162 163Put here the name of the engine executable file. You can also add 164command-line arguments. Path searching is used and the current 165directory will be "EngineDir". 166 167NOTE: Unix users are recommended to prepend "./"; this is required on 168some secure systems. 169 170- "Log" (default: false) 171 172Whether PolyGlot should log all transactions with the interface and 173the engine. This should be necessary only to locate problems. 174 175- "LogFile" 176 177The name of the log file. Note that it is put where PolyGlot was 178launched from, not into the engine directory. 179 180WARNING: Log files are not cleared between sessions, and can become 181very large. It is safe to remove them though. 182 183- "Resign" (default: false) 184 185Set this to "true" if you want PolyGlot to resign on behalf of the 186engine. 187 188NOTE: Some engines display buggy scores from time to time although the 189best move is correct. Use this option only if you know what you are 190doing (e.g. you always check the final position of games). 191 192- "ResignMoves" (default: 3) 193 194Number of consecutive moves with "resign" score (see below) before 195PolyGlot resigns for the engine. Positions with only one legal move 196are ignored. 197 198- "ResignScore" (default: 600) 199 200This is the score in centipawns that will trigger resign "counting". 201 202- "ShowPonder" (*** NEW ***, default: true) 203 204Show search information during engine pondering. Turning this off 205might be better for interactive use in some interfaces. 206 207- "KibitzMove" (*** NEW ***, default: false) 208 209Whether to kibitz when playing a move. 210 211- "KibitzPV" (*** NEW ***, default: false) 212 213Whether to kibitz when the PV is changed (new iteration or new best move). 214 215- "KibitzCommand" (*** NEW ***, default: "tellall") 216 217xboard command to use for kibitzing, normally "tellall" for kibitzing 218or "tellothers" for whispering. 219 220- "KibitzDelay" (*** NEW ***, default: 5) 221 222How many seconds to wait before starting kibitzing. This has an 223affect only if "KibitzPV" is selected, move kibitzes are always sent 224regardless of the delay. 225 226 227Work arounds 228------------ 229 230Work arounds are identical to options except that they should be used 231only when necessary. Their purpose is to try to hide problems with 232various software (not just engines). The default value is always 233correct for bug-free software. 234 235IMPORTANT: Any of these work arounds might be removed in future 236versions of PolyGlot. You are strongly recommended to contact the 237author of faulty software and truly fix the problem. 238 239In PolyGlot 1.3 there is only one optional work around: 240 241- "UCIVersion" (default: 2) 242 243The default value of 2 corresponds to UCI+. Use 1 to select plain 244UCI for engines that have problems with UCI+. 245 246 247Opening Book 248------------ 249 250*** NEW *** 251 252PolyGlot 1.3 provides a minimal opening-book implementation. 253 254New options can be added to the [PolyGlot] section: 255 256- "Book" (default: false) 257 258Indicates whether a PolyGlot book should be used. This has no effect 259on the engine own book (which can be controlled with the UCI option 260"OwnBook" in the [Engine] section). In particular, it is possible to 261use both a PolyGlot book and an engine book. In that case, the engine 262book will be used whenever PolyGlot is out of book. Remember that 263PolyGlot is unaware of whether the engine is itself using a book or 264not. 265 266- "BookFile" 267 268The name of the (binary) book file. Note that PolyGlot will look for 269it in the directory it was launched from, not in the engine directory. 270Of course, full path can be used in which case the current directory 271does not matter. 272 273Note that there is no option to control book usage. All parameters 274are fixed when compiling a PGN file into a binary book (see below). 275This is purposeful and is not likely to change. 276 277Using a book does not require any additional memory, this can be 278important for memory-limited tournaments. 279 280A default book "fruit.bin" is provided in the archive. Note that this 281book is very small and should probably not be used in serious games. 282I hope that users will make other books available in the future. 283 284 285Book Making 286----------- 287 288*** NEW *** 289 290You can compile a PGN file into a binary book using PolyGlot on the 291command line. At the moment, only a main (random) book is provided. 292It is not yet possible to control opening lines manually. I am 293working on it though. 294 295Usage: "polyglot make-book <options>". 296 297"make-book" options are: 298 299- "-pgn" 300 301Name of the input PGN file. PolyGlot should support any 302standard-conforming file. Let me know if you encounter a problem. 303 304- "-bin" 305 306Name of the output binary file. I suggest ".bin" as the extension but 307in fact PolyGlot does not care. 308 309- "-max-ply" (default: infinite) 310 311How many plies (half moves) to read for each game. E.g. if set to 312"20", only the first 10 full moves of each game will be scanned. 313 314- "-min-game" (default: 3) 315 316How many times must a move be played to be kept in the book. In other 317words, moves that were played too rarely will be left out. If you 318scan full games "2" seems a minimum, but if you selected lines 319manually "1" will make sense. 320 321Example: "polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30". 322 323Building a book is usually very fast (a few minutes at most). Note 324however that a lot of memory may be required. To reduce memory usage, 325select a ply limit. 326 327 328History 329------- 330 3312004/04/30: PolyGlot 1.0 332 333- first public release. 334 3352004/10/01: PolyGlot 1.1 336 337- added "StartupWait" and "PonderWorkAround" ("AutoQuit" was available 338 in version 1.0 but not documented). 339 340- fixed a minor bug that could prevent "AutoQuit" from working with 341 some engines. 342 3432005/01/29: PolyGlot 1.2 344 345- rewrote engine initialisation and UCI parsing to increase 346 UCI-standard compliance 347 348- added multi-move resign 349 350- added an internal work around for engines hanging with WinBoard 351 3522005/06/03: PolyGlot 1.3 353 354- added opening book 355 356- added kibitzing 357 358- added "ShowPonder" option 359 360 361 362Known bugs 363---------- 364 365*** IMPORTANT *** 366 367There is a bug (!) in the xboard automaton. The bug is related to 368searching in draw positions (e.g. 50-move rule or repetition). I had 369only been able to make PolyGlot crash by using analysis mode and 370performing manual takebacks. I believe that this bug can only happen 371in highly-interactive use (e.g. manual analysis). It is present in 372all versions of PolyGlot, including this one. 373 374I attempted a work around in February. I vaguely remember the change 375prevents crashing (not sure) but it is possible that PolyGlot now gets 376stuck in some rare case, i.e. it refuses to produce a move. In any 377case, the bug cannot occur silently, e.g. in a game that terminated 378normally. 379 380Because of the small expected impact (nobody ever reported it to me) 381and because fixing the bug would require a whole redesign of the 382xboard module, I have no intention of working on it at the moment (!). 383 384Make sure to let me know if it appeared in any circounstance, thanks! 385In particular if the bug ever occurs during a non-interactive session 386(e.g. engine vs. engine game), then I will do something. 387 388 389Thanks 390------ 391 392Big thanks go to: 393 394- Dann Corbit for spending a lot of time compiling, testing, making 395 files available, etc ... 396 397- Leo Dijksman for hosting the PolyGlot distribution on his web site 398 (see Links) and also for thorough testing 399 400- Tord Romstad, Joshua Shriver and George Sobala for compiling and 401 testing on Mac OS X 402 403- users in the WinBoard forum for their feedback and encouraging 404 words: Roger Brown, Leo Dijksman, Igor Gorelikov, Mogens Larsen, 405 Volker Pittlik, Norm Pollock, G�nther Simon and Salvo Spitaleri 406 in particular 407 408 409Links 410----- 411 412- Tim Mann's Chess Pages: http://www.tim-mann.org/xboard.html 413- Leo Dijksman's WBEC Ridderkerk: http://wbec-ridderkerk.nl/ 414- Volker Pittlik's Winboard Forum: http://wbforum.volker-pittlik.name/ 415 416 417Contact me 418---------- 419 420You can contact me at fabien_letouzey@hotmail.com 421 422If I am not available, you can discuss PolyGlot issues in Volker 423Pittlik's Winboard Forum: http://wbforum.volker-pittlik.name/ 424 425In fact for questions regarding specific Windows-only engines, you are 426advised to ask directly in the WinBoard forum, as I don't have Windows 427myself. 428 429 430The end 431------- 432 433Fabien Letouzey, 2005/06/03. 434 435