README1.3

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