README1.3

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