1 2Legal details 3------------- 4 5PolyGlot 1.4 Copyright 2004-2006 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.4 (2006/01/16). 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 can be placed in its own directory, or anywhere it can access 51the DLL file from (on Windows). 52 53On Windows the files "polyglot.exe" and "cygwin1.dll" (which you can 54download from http://wbec-ridderkerk.nl/) are needed. On Linux and 55Mac OS X only the file "polyglot_linux" or "polyglot_mac" is required. 56 57 58Compiling 59--------- 60 61The distribution comes up with Windows, Linux and Mac OS X binaries. 62Compiling should therefore not be necessary on those systems unless 63you want to make a change in the program. In any case this section 64describes the compiling procedure, it is safe to skip it. 65 66PolyGlot is a POSIX application (Unix compatible), and was developed 67on Linux using g++ (the GNU C++ compiler). 68 691) Unix 70 71You should be able to compile it on any POSIX-compliant operating 72system (*not* Windows) with the following command line (or similar): 73 74> g++ -O2 -o polyglot *.cpp 75 76IMPORTANT: In "io.cpp", the variable "UseCR" should be set to "false". 77 78A Makefile is provided but might not work on your system ... 79 802) Windows 81 82On Windows, you *must* use Cygnus GCC to compile PolyGlot. 83 84IMPORTANT: In "io.cpp", the variable "UseCR" should be set to "true". 85 86 87Usage 88----- 89 90PolyGlot acts as an xboard engine. There should be no difference with 91a normal chess program as far as the interface (e.g. WinBoard) is 92concerned. 93 94PolyGlot is invoked using "polyglot ". Note that PolyGlot 95will look for the INI file in the current directory. If no 96is given, "polyglot.ini" is selected. 97 98To use PolyGlot with XBoard, you would type something like this: 99> xboard -fd 'ini_dir' -fcp 'polyglot engine.ini' 100 101Quotes are important when there is a space in the argument. 102 103IMPORTANT: some users seem confused by the concept of "current 104directory". PolyGlot needs to know where to read (INI file) and write 105(log file) files. Although it's possible to specify the full path to 106each file, a better solution is to provide a directory when launching 107PolyGlot, e.g. with the "-fd" XBoard option above. The directory 108should be where the INI file is. 109 110 111INI file 112-------- 113 114There should be a different INI file for each engine. Sections are 115composed of "variable = value" lines. See the sample INI files in the 116"example" directory. 117 118NOTE: There can be spaces in variable names or values. Do not use 119quotes. 120 1211) [PolyGlot] section 122 123This section is used by PolyGlot only. The engine is unaware of these 124options. The list of available options is detailed below in this 125document. 126 1272) [Engine] section 128 129This section contains engine UCI options. PolyGlot does not 130understand them, but sends the information to the engine at startup 131(converted to UCI form). You can add any UCI option that makes sense 132to the engine (not just the common options about hash-table size and 133tablebases). 134 135NOTE: use INI syntax, not UCI. For example "OwnBook = true" is 136correct. It will be replaced by PolyGlot with "setoption name OwnBook 137value true" at engine startup. 138 139Standard UCI options are "Hash", "NalimovPath", "NalimovCache" and 140"OwnBook". Hidden options like "Ponder" or "UCI_xxx" are automatic 141and should not be put in an INI file. 142 143The other options are engine-specific. Check their name using a UCI 144GUI or launch the engine in a console and type "uci". 145 146 147Options 148------- 149 150These should be put in the [PolyGlot] section. 151 152- "EngineName" (default: UCI name) 153 154This is the name that will appear in the xboard interface. It is 155cosmetic only. You can use different names for tweaked versions of 156the same engine. 157 158If no "Engine Name" is given, the UCI name will be used. 159 160- "EngineDir" (default: ".") 161 162Full path of the directory where the engine is installed. You can use 163"." (without the quotes) if you know that PolyGlot will be launched in 164the engine directory or the engine is in the "path" and does not need 165any data file. 166 167- "EngineCommand" 168 169Put here the name of the engine executable file. You can also add 170command-line arguments. Path searching is used and the current 171directory will be "EngineDir". 172 173NOTE: Unix users are recommended to prepend "./"; this is required on 174some secure systems. 175 176- "Log" (default: false) 177 178Whether PolyGlot should log all transactions with the interface and 179the engine. This should be necessary only to locate problems. 180 181- "LogFile" 182 183The name of the log file. Note that it is put where PolyGlot was 184launched from, not into the engine directory. 185 186WARNING: Log files are not cleared between sessions, and can become 187very large. It is safe to remove them though. 188 189- "Resign" (default: false) 190 191Set this to "true" if you want PolyGlot to resign on behalf of the 192engine. 193 194NOTE: Some engines display buggy scores from time to time although the 195best move is correct. Use this option only if you know what you are 196doing (e.g. you always check the final position of games). 197 198- "ResignMoves" (default: 3) 199 200Number of consecutive moves with "resign" score (see below) before 201PolyGlot resigns for the engine. Positions with only one legal move 202are ignored. 203 204- "ResignScore" (default: 600) 205 206This is the score in centipawns that will trigger resign "counting". 207 208- "ShowPonder" (default: true) 209 210Show search information during engine pondering. Turning this off 211might be better for interactive use in some interfaces. 212 213- "KibitzMove" (default: false) 214 215Whether to kibitz when playing a move. 216 217- "KibitzPV" (default: false) 218 219Whether to kibitz when the PV is changed (new iteration or new best move). 220 221- "KibitzCommand" (default: "tellall") 222 223xboard command to use for kibitzing, normally "tellall" for kibitzing 224or "tellothers" for whispering. 225 226 227- "KibitzDelay" (default: 5) 228 229How many seconds to wait before starting kibitzing. This has an 230affect only if "KibitzPV" is selected, move kibitzes are always sent 231regardless of the delay. 232 233 234Work arounds 235------------ 236 237Work arounds are identical to options except that they should be used 238only when necessary. Their purpose is to try to hide problems with 239various software (not just engines). The default value is always 240correct for bug-free software. 241 242IMPORTANT: Any of these work arounds might be removed in future 243versions of PolyGlot. You are strongly recommended to contact the 244author of faulty software and truly fix the problem. 245 246PolyGlot 1.4 supports the following work arounds: 247 248- "UCIVersion" (default: 2) 249 250The default value of 2 corresponds to UCI+. Use 1 to select plain 251UCI for engines that have problems with UCI+. 252 253- "CanPonder" (*** NEW ***, default: false) 254 255PolyGlot now conforms to the documented UCI behaviour: the engine will 256be allowed to ponder only if it (the engine) declares the "Ponder" UCI 257option. However some engines which can actually ponder do not declare 258the option. This work around lets PolyGlot know that they can ponder. 259 260- "SyncStop" (*** NEW ***, default: false) 261 262When a ponder miss occurs, Polyglot interrupts the engine and 263IMMEDIATELY launches a new search. While there should be no problem 264with this, some engines seem confused and corrupt their search board. 265"SyncStop" forces PolyGlot to wait for the (now useless) ponder search 266to finish before launching the new search. 267 268- "PromoteWorkAround" (*** NEW ***, default: false) 269 270Some engines do not specify a promotion piece, e.g. they send "e7e8" 271instead of the correct "e7e8q". This work around enables the 272incorrect form (and of course promotes into a queen). 273 274 275Opening Book 276------------ 277 278PolyGlot 1.4 provides a simplistic opening-book implementation. 279 280The following options can be added to the [PolyGlot] section: 281 282- "Book" (default: false) 283 284Indicates whether a PolyGlot book should be used. This has no effect 285on the engine own book (which can be controlled with the UCI option 286"OwnBook" in the [Engine] section). In particular, it is possible to 287use both a PolyGlot book and an engine book. In that case, the engine 288book will be used whenever PolyGlot is out of book. Remember that 289PolyGlot is unaware of whether the engine is itself using a book or 290not. 291 292- "BookFile" 293 294The name of the (binary) book file. Note that PolyGlot will look for 295it in the directory it was launched from, not in the engine directory. 296Of course, full path can be used in which case the current directory 297does not matter. 298 299Note that there is no option to control book usage. All parameters 300are fixed when compiling a PGN file into a binary book (see below). 301This is purposeful and is not likely to change. 302 303Using a book does not require any additional memory, this can be 304important for memory-limited tournaments. 305 306A default book "fruit.bin" is provided in the archive. Note that this 307book is very small and should probably not be used in serious games. 308I hope that users will make other books available in the future. 309 310 311Book Making 312----------- 313 314You can compile a PGN file into a binary book using PolyGlot on the 315command line. At the moment, only a main (random) book is provided. 316It is not yet possible to control opening lines manually. I am 317working on it though. 318 319Usage: "polyglot make-book ". 320 321"make-book" options are: 322 323- "-pgn" 324 325Name of the input PGN file. PolyGlot should support any 326standard-conforming file. Let me know if you encounter a problem. 327 328- "-bin" 329 330Name of the output binary file. I suggest ".bin" as the extension but 331in fact PolyGlot does not care. 332 333- "-max-ply" (default: infinite) 334 335How many plies (half moves) to read for each game. E.g. if set to 336"20", only the first 10 full moves of each game will be scanned. 337 338- "-min-game" (default: 3) 339 340How many times must a move be played to be kept in the book. In other 341words, moves that were played too rarely will be left out. If you 342scan full games "2" seems a minimum, but if you selected lines 343manually "1" will make sense. 344 345- "-only-white" *** NEW *** 346 347Save only white moves. This allows to use different parameters for 348white and black books, and merge them into a single file with the 349"merge-book" command, see below. 350 351- "-only-black" *** NEW *** 352 353Same for black moves. 354 355- "-uniform" *** NEW *** 356 357By default, a probability is calculated by PolyGlot for each move 358depending on how popular it is (how often it was playing in the 359provided PGN file) and how much it "scored". This option bypasses the 360default mechanism and affects equal probability to all moves. This 361allows more variety of play. 362 363This option is normally used only with hand-selected lines (e.g. "user 364books"). 365 366--- 367 368Example: "polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30". 369 370Building a book is usually very fast (a few minutes at most). Note 371however that a lot of memory may be required. To reduce memory usage, 372select a ply limit. 373 374 375Book Merging 376------------ 377 378*** NEW *** 379 380Usage: "polyglot merge-book -in1 -in2 -out " 381 382Merge two bin files into a single one. has "priority"; this 383means that if a position is present in both input books, data from 384 will be ignored for this position. 385 386The two main applications are: 387 3881) combine a white book and a black book (in which case priority does 389 not matter) 390 3912) combine a "user book" of manually-selected lines with a broader one 392 from a large game set 393 394What follows is an admitedly complicated example of how this can be 395used. DO NOT MAILBOMB ME IF YOU DO NOT UNDERSTAND! 396 397My hope is that at least one advanced user will get what I mean and 398writes a better explanation on a web page or forum thread (yes, that's 399YOU, thanks by the way) ... 400 401--- 402 403Imagine that we've got 4 PGN files as follows: 404 405w1.pgn: fixed white lines, all moves manually checked 406w2.pgn: selected games (for random book as with PolyGlot 1.3) 407 408b1.pgn and b2.pgn: same for black 409 410The first step is to build 4 .bin files with appropriate options. 411Lines starting with "> " indicate what is typed on the command line. 412 413> polyglot make-book -min-game 1 -uniform -only-white -pgn w1.pgn -bin w1.bin 414 415I added "-uniform" because it allows randomness in the fixed lines 416(e.g. d4+e4 at 50%). It has no effect if lines are deterministic 417(only one move for a given position). 418 419"-min-game 1" is characteristic for user books. All moves are supposed 420to be safe so there is no reason to filter them with other heuristics. 421 422> polyglot make-book -min-score 50 -only-white -pgn w2.pgn -bin w2.bin 423 424This shows how min-score can actually be different for white and black 425(as with multiple books). I don't use "max-ply" because "min-game" 426default value of 3 will limit depth somewhat. You are of course free 427to use it. 428 429Same for black: 430 431> polyglot make-book -min-game 1 -uniform -only-black -pgn b1.pgn -bin b1.bin 432> polyglot make-book -min-score 40 -only-black -pgn b2.pgn -bin b2.bin 433 434At this point we have 4 .bin files. Notice that different parameters 435were used for white and for black (not to mention that different PGN 436files can be used). 437 438--- 439 440Let's now merge the white books. 441 442> polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin 443 444Input files are not symmetrical, "in1" has priority over "in2". 445 446"skipped xxx entries." message from PolyGlot means there were some 447position conflicts. This is normal since we want to overwrite some 448random moves with fixed lines instead. 449 450Same for black: 451 452> polyglot merge-book -in1 b1.bin -in2 b2.bin -out b.bin 453 454Now we can finally merge the white and black books. 455 456> polyglot merge-book -in1 w.bin -in2 b.bin -out book.bin 457 458It's important to check that there are no conflicts, otherwise 459something went wrong. 460 461Note that this last operation was only made possible thanks to colour 462filtering, otherwise nearly all positions would lead to conflicts. 463For this reason, it does not make much sense to mix old .bin files 464(which contain moves for both colours). 465 466All these command lines might seem numerous and complicated but they 467can be put together into batch files. 468 469 470Chess 960 471--------- 472 473*** NEW *** 474 475PolyGlot now supports Chess 960. 476 477However note that most xboard interfaces like WinBoard do not (except 478perhaps on an Internet chess server)! 479 480Here are pointers to modified XBoard/WinBoard versions that are known 481to work with PolyGlot in Chess960 mode: 482 483http://www.ascotti.org/programming/chess/winboard_x.htm (Windows) 484http://www.glaurungchess.com/xboard-960.tar.bz2 (Unix) 485http://www.milix.net/aice (?) 486 487It is also possible that PolyGlot is useful in combination with 488Arena(!): Arena Chess960 works correctly in xboard mode but it seems 489not compatible with the official UCI standard. With PolyGlot it is 490possible to include Chess960 UCI engines by using the xboard protocol 491instead. 492 493 494History 495------- 496 4972004/04/30: PolyGlot 1.0 498 499- first public release. 500 5012004/10/01: PolyGlot 1.1 502 503- added "StartupWait" and "PonderWorkAround" ("AutoQuit" was available 504 in version 1.0 but not documented). 505 506- fixed a minor bug that could prevent "AutoQuit" from working with 507 some engines. 508 5092005/01/29: PolyGlot 1.2 510 511- rewrote engine initialisation and UCI parsing to increase 512 UCI-standard compliance 513 514- added multi-move resign 515 516- added an internal work around for engines hanging with WinBoard 517 5182005/06/03: PolyGlot 1.3 519 520- added opening book 521 522- added kibitzing 523 524- added "ShowPonder" option 525 5262006/01/16: PolyGlot 1.4 527 528- added Chess960 (requires "fischerandom" xboard variant) 529 530- added "-only-white", "-only-black" and "-uniform" book-making 531 options 532 533- added "merge-book" command 534 535- added "CanPonder", "SyncStop" and "PromoteWorkAround" work arounds 536 537- fixed "Move Now" (the engine was interrupted but the move was 538 ignored) 539 540- fixed an UCI+draw problem that could occur with some engines after a 541 draw by 50 moves or repetition 542 543- fixed pondering behaviour: the engine will ponder only if it 544 declares the "Ponder" UCI option 545 546 547Known problems 548-------------- 549 550The addition of Chess960 support lead to a change in internal-move 551representation for castling. This slightly affected the opening-book 552format. I recommend that you recompile books with this version. 553 554Fruit 2.2 and above handle both book formats though. 555 556--- 557 558Several users reported engines losing on time. The playing conditions 559always mixed playing on an Internet server with pondering. Early 560log-file analysis did not reveal any misbehaviour by PolyGlot, but I 561have others to study. 562 563It is not yet clear what the source of the problem is, but let me 564state one more time that there is a forever incompatibility between 565the xboard and UCI protocol regarding a complex 566pondering/remaining-time relation. I suspect this might be related to 567the problem described above and if so, it is possible that there is no 568clean solution to it! 569 570In any case I have other log file to study that might reveal 571something, stay tuned! 572 573 574Thanks 575------ 576 577Big thanks go to: 578 579- Leo Dijksman for compiling, hosting the PolyGlot distribution on his web site 580 (see Links) and also for thorough testing 581 582- Tord Romstad, Joshua Shriver and George Sobala for compiling and 583 testing on Mac OS X 584 585- all those who reported problems or proposed improvements; I am not 586 well organised enough to provide their names! 587 588 589Links 590----- 591 592- Tim Mann's Chess Pages: http://www.tim-mann.org/xboard.html 593- Leo Dijksman's WBEC Ridderkerk: http://wbec-ridderkerk.nl/ 594- Volker Pittlik's Winboard Forum: http://wbforum.volker-pittlik.name/ 595 596 597Contact me 598---------- 599 600You can contact me at fabien_letouzey@hotmail.com; expect SLOW answer, 601if at all! 602 603If I am not available, you can discuss PolyGlot issues in Volker 604Pittlik's Winboard Forum: http://wbforum.volker-pittlik.name/ 605 606In fact for questions regarding specific Windows-only engines, you are 607advised to ask directly in the WinBoard forum, as I don't have Windows 608myself. 609 610 611The end 612------- 613 614Fabien Letouzey, 2006/01/16. 615 616