5 PolyGlot 1.4 Copyright 2004-2006 Fabien Letouzey.
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.
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.
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
22 See the file "copying.txt" for details.
28 PolyGlot 1.4 (2006/01/16).
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
34 PolyGlot tries to solve known problems with other adapters. For
35 instance, it detects and reports draws by fifty-move rule, repetition,
39 Official distribution URL
40 -------------------------
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.
50 PolyGlot can be placed in its own directory, or anywhere it can access
51 the DLL file from (on Windows).
53 On Windows the files "polyglot.exe" and "cygwin1.dll" (which you can
54 download from http://wbec-ridderkerk.nl/) are needed. On Linux and
55 Mac OS X only the file "polyglot_linux" or "polyglot_mac" is required.
61 The distribution comes up with Windows, Linux and Mac OS X binaries.
62 Compiling should therefore not be necessary on those systems unless
63 you want to make a change in the program. In any case this section
64 describes the compiling procedure, it is safe to skip it.
66 PolyGlot is a POSIX application (Unix compatible), and was developed
67 on Linux using g++ (the GNU C++ compiler).
71 You should be able to compile it on any POSIX-compliant operating
72 system (*not* Windows) with the following command line (or similar):
74 > g++ -O2 -o polyglot *.cpp
76 IMPORTANT: In "io.cpp", the variable "UseCR" should be set to "false".
78 A Makefile is provided but might not work on your system ...
82 On Windows, you *must* use Cygnus GCC to compile PolyGlot.
84 IMPORTANT: In "io.cpp", the variable "UseCR" should be set to "true".
90 PolyGlot acts as an xboard engine. There should be no difference with
91 a normal chess program as far as the interface (e.g. WinBoard) is
94 PolyGlot is invoked using "polyglot ". Note that PolyGlot
95 will look for the INI file in the current directory. If no
96 is given, "polyglot.ini" is selected.
98 To use PolyGlot with XBoard, you would type something like this:
99 > xboard -fd 'ini_dir' -fcp 'polyglot engine.ini'
101 Quotes are important when there is a space in the argument.
103 IMPORTANT: some users seem confused by the concept of "current
104 directory". 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
106 each file, a better solution is to provide a directory when launching
107 PolyGlot, e.g. with the "-fd" XBoard option above. The directory
108 should be where the INI file is.
114 There should be a different INI file for each engine. Sections are
115 composed of "variable = value" lines. See the sample INI files in the
118 NOTE: There can be spaces in variable names or values. Do not use
121 1) [PolyGlot] section
123 This section is used by PolyGlot only. The engine is unaware of these
124 options. The list of available options is detailed below in this
129 This section contains engine UCI options. PolyGlot does not
130 understand them, but sends the information to the engine at startup
131 (converted to UCI form). You can add any UCI option that makes sense
132 to the engine (not just the common options about hash-table size and
135 NOTE: use INI syntax, not UCI. For example "OwnBook = true" is
136 correct. It will be replaced by PolyGlot with "setoption name OwnBook
137 value true" at engine startup.
139 Standard UCI options are "Hash", "NalimovPath", "NalimovCache" and
140 "OwnBook". Hidden options like "Ponder" or "UCI_xxx" are automatic
141 and should not be put in an INI file.
143 The other options are engine-specific. Check their name using a UCI
144 GUI or launch the engine in a console and type "uci".
150 These should be put in the [PolyGlot] section.
152 - "EngineName" (default: UCI name)
154 This is the name that will appear in the xboard interface. It is
155 cosmetic only. You can use different names for tweaked versions of
158 If no "Engine Name" is given, the UCI name will be used.
160 - "EngineDir" (default: ".")
162 Full 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
164 the engine directory or the engine is in the "path" and does not need
169 Put here the name of the engine executable file. You can also add
170 command-line arguments. Path searching is used and the current
171 directory will be "EngineDir".
173 NOTE: Unix users are recommended to prepend "./"; this is required on
176 - "Log" (default: false)
178 Whether PolyGlot should log all transactions with the interface and
179 the engine. This should be necessary only to locate problems.
183 The name of the log file. Note that it is put where PolyGlot was
184 launched from, not into the engine directory.
186 WARNING: Log files are not cleared between sessions, and can become
187 very large. It is safe to remove them though.
189 - "Resign" (default: false)
191 Set this to "true" if you want PolyGlot to resign on behalf of the
194 NOTE: Some engines display buggy scores from time to time although the
195 best move is correct. Use this option only if you know what you are
196 doing (e.g. you always check the final position of games).
198 - "ResignMoves" (default: 3)
200 Number of consecutive moves with "resign" score (see below) before
201 PolyGlot resigns for the engine. Positions with only one legal move
204 - "ResignScore" (default: 600)
206 This is the score in centipawns that will trigger resign "counting".
208 - "ShowPonder" (default: true)
210 Show search information during engine pondering. Turning this off
211 might be better for interactive use in some interfaces.
213 - "KibitzMove" (default: false)
215 Whether to kibitz when playing a move.
217 - "KibitzPV" (default: false)
219 Whether to kibitz when the PV is changed (new iteration or new best move).
221 - "KibitzCommand" (default: "tellall")
223 xboard command to use for kibitzing, normally "tellall" for kibitzing
224 or "tellothers" for whispering.
227 - "KibitzDelay" (default: 5)
229 How many seconds to wait before starting kibitzing. This has an
230 affect only if "KibitzPV" is selected, move kibitzes are always sent
231 regardless of the delay.
237 Work arounds are identical to options except that they should be used
238 only when necessary. Their purpose is to try to hide problems with
239 various software (not just engines). The default value is always
240 correct for bug-free software.
242 IMPORTANT: Any of these work arounds might be removed in future
243 versions of PolyGlot. You are strongly recommended to contact the
244 author of faulty software and truly fix the problem.
246 PolyGlot 1.4 supports the following work arounds:
248 - "UCIVersion" (default: 2)
250 The default value of 2 corresponds to UCI+. Use 1 to select plain
251 UCI for engines that have problems with UCI+.
253 - "CanPonder" (*** NEW ***, default: false)
255 PolyGlot now conforms to the documented UCI behaviour: the engine will
256 be allowed to ponder only if it (the engine) declares the "Ponder" UCI
257 option. However some engines which can actually ponder do not declare
258 the option. This work around lets PolyGlot know that they can ponder.
260 - "SyncStop" (*** NEW ***, default: false)
262 When a ponder miss occurs, Polyglot interrupts the engine and
263 IMMEDIATELY launches a new search. While there should be no problem
264 with this, some engines seem confused and corrupt their search board.
265 "SyncStop" forces PolyGlot to wait for the (now useless) ponder search
266 to finish before launching the new search.
268 - "PromoteWorkAround" (*** NEW ***, default: false)
270 Some engines do not specify a promotion piece, e.g. they send "e7e8"
271 instead of the correct "e7e8q". This work around enables the
272 incorrect form (and of course promotes into a queen).
278 PolyGlot 1.4 provides a simplistic opening-book implementation.
280 The following options can be added to the [PolyGlot] section:
282 - "Book" (default: false)
284 Indicates whether a PolyGlot book should be used. This has no effect
285 on the engine own book (which can be controlled with the UCI option
286 "OwnBook" in the [Engine] section). In particular, it is possible to
287 use both a PolyGlot book and an engine book. In that case, the engine
288 book will be used whenever PolyGlot is out of book. Remember that
289 PolyGlot is unaware of whether the engine is itself using a book or
294 The name of the (binary) book file. Note that PolyGlot will look for
295 it in the directory it was launched from, not in the engine directory.
296 Of course, full path can be used in which case the current directory
299 Note that there is no option to control book usage. All parameters
300 are fixed when compiling a PGN file into a binary book (see below).
301 This is purposeful and is not likely to change.
303 Using a book does not require any additional memory, this can be
304 important for memory-limited tournaments.
306 A default book "fruit.bin" is provided in the archive. Note that this
307 book is very small and should probably not be used in serious games.
308 I hope that users will make other books available in the future.
314 You can compile a PGN file into a binary book using PolyGlot on the
315 command line. At the moment, only a main (random) book is provided.
316 It is not yet possible to control opening lines manually. I am
317 working on it though.
319 Usage: "polyglot make-book ".
321 "make-book" options are:
325 Name of the input PGN file. PolyGlot should support any
326 standard-conforming file. Let me know if you encounter a problem.
330 Name of the output binary file. I suggest ".bin" as the extension but
331 in fact PolyGlot does not care.
333 - "-max-ply" (default: infinite)
335 How 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.
338 - "-min-game" (default: 3)
340 How many times must a move be played to be kept in the book. In other
341 words, moves that were played too rarely will be left out. If you
342 scan full games "2" seems a minimum, but if you selected lines
343 manually "1" will make sense.
345 - "-only-white" *** NEW ***
347 Save only white moves. This allows to use different parameters for
348 white and black books, and merge them into a single file with the
349 "merge-book" command, see below.
351 - "-only-black" *** NEW ***
353 Same for black moves.
355 - "-uniform" *** NEW ***
357 By default, a probability is calculated by PolyGlot for each move
358 depending on how popular it is (how often it was playing in the
359 provided PGN file) and how much it "scored". This option bypasses the
360 default mechanism and affects equal probability to all moves. This
361 allows more variety of play.
363 This option is normally used only with hand-selected lines (e.g. "user
368 Example: "polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30".
370 Building a book is usually very fast (a few minutes at most). Note
371 however that a lot of memory may be required. To reduce memory usage,
380 Usage: "polyglot merge-book -in1 -in2 -out "
382 Merge two bin files into a single one. has "priority"; this
383 means that if a position is present in both input books, data from
384 will be ignored for this position.
386 The two main applications are:
388 1) combine a white book and a black book (in which case priority does
391 2) combine a "user book" of manually-selected lines with a broader one
392 from a large game set
394 What follows is an admitedly complicated example of how this can be
395 used. DO NOT MAILBOMB ME IF YOU DO NOT UNDERSTAND!
397 My hope is that at least one advanced user will get what I mean and
398 writes a better explanation on a web page or forum thread (yes, that's
399 YOU, thanks by the way) ...
403 Imagine that we've got 4 PGN files as follows:
405 w1.pgn: fixed white lines, all moves manually checked
406 w2.pgn: selected games (for random book as with PolyGlot 1.3)
408 b1.pgn and b2.pgn: same for black
410 The first step is to build 4 .bin files with appropriate options.
411 Lines starting with "> " indicate what is typed on the command line.
413 > polyglot make-book -min-game 1 -uniform -only-white -pgn w1.pgn -bin w1.bin
415 I 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).
419 "-min-game 1" is characteristic for user books. All moves are supposed
420 to be safe so there is no reason to filter them with other heuristics.
422 > polyglot make-book -min-score 50 -only-white -pgn w2.pgn -bin w2.bin
424 This 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"
426 default value of 3 will limit depth somewhat. You are of course free
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
434 At this point we have 4 .bin files. Notice that different parameters
435 were used for white and for black (not to mention that different PGN
440 Let's now merge the white books.
442 > polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
444 Input files are not symmetrical, "in1" has priority over "in2".
446 "skipped xxx entries." message from PolyGlot means there were some
447 position conflicts. This is normal since we want to overwrite some
448 random moves with fixed lines instead.
452 > polyglot merge-book -in1 b1.bin -in2 b2.bin -out b.bin
454 Now we can finally merge the white and black books.
456 > polyglot merge-book -in1 w.bin -in2 b.bin -out book.bin
458 It's important to check that there are no conflicts, otherwise
459 something went wrong.
461 Note that this last operation was only made possible thanks to colour
462 filtering, otherwise nearly all positions would lead to conflicts.
463 For this reason, it does not make much sense to mix old .bin files
464 (which contain moves for both colours).
466 All these command lines might seem numerous and complicated but they
467 can be put together into batch files.
475 PolyGlot now supports Chess 960.
477 However note that most xboard interfaces like WinBoard do not (except
478 perhaps on an Internet chess server)!
480 Here are pointers to modified XBoard/WinBoard versions that are known
481 to work with PolyGlot in Chess960 mode:
483 http://www.ascotti.org/programming/chess/winboard_x.htm (Windows)
484 http://www.glaurungchess.com/xboard-960.tar.bz2 (Unix)
485 http://www.milix.net/aice (?)
487 It is also possible that PolyGlot is useful in combination with
488 Arena(!): Arena Chess960 works correctly in xboard mode but it seems
489 not compatible with the official UCI standard. With PolyGlot it is
490 possible to include Chess960 UCI engines by using the xboard protocol
497 2004/04/30: PolyGlot 1.0
499 - first public release.
501 2004/10/01: PolyGlot 1.1
503 - added "StartupWait" and "PonderWorkAround" ("AutoQuit" was available
504 in version 1.0 but not documented).
506 - fixed a minor bug that could prevent "AutoQuit" from working with
509 2005/01/29: PolyGlot 1.2
511 - rewrote engine initialisation and UCI parsing to increase
512 UCI-standard compliance
514 - added multi-move resign
516 - added an internal work around for engines hanging with WinBoard
518 2005/06/03: PolyGlot 1.3
524 - added "ShowPonder" option
526 2006/01/16: PolyGlot 1.4
528 - added Chess960 (requires "fischerandom" xboard variant)
530 - added "-only-white", "-only-black" and "-uniform" book-making
533 - added "merge-book" command
535 - added "CanPonder", "SyncStop" and "PromoteWorkAround" work arounds
537 - fixed "Move Now" (the engine was interrupted but the move was
540 - fixed an UCI+draw problem that could occur with some engines after a
541 draw by 50 moves or repetition
543 - fixed pondering behaviour: the engine will ponder only if it
544 declares the "Ponder" UCI option
550 The addition of Chess960 support lead to a change in internal-move
551 representation for castling. This slightly affected the opening-book
552 format. I recommend that you recompile books with this version.
554 Fruit 2.2 and above handle both book formats though.
558 Several users reported engines losing on time. The playing conditions
559 always mixed playing on an Internet server with pondering. Early
560 log-file analysis did not reveal any misbehaviour by PolyGlot, but I
561 have others to study.
563 It is not yet clear what the source of the problem is, but let me
564 state one more time that there is a forever incompatibility between
565 the xboard and UCI protocol regarding a complex
566 pondering/remaining-time relation. I suspect this might be related to
567 the problem described above and if so, it is possible that there is no
568 clean solution to it!
570 In any case I have other log file to study that might reveal
571 something, stay tuned!
579 - Leo Dijksman for compiling, hosting the PolyGlot distribution on his web site
580 (see Links) and also for thorough testing
582 - Tord Romstad, Joshua Shriver and George Sobala for compiling and
585 - all those who reported problems or proposed improvements; I am not
586 well organised enough to provide their names!
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/
600 You can contact me at fabien_letouzey@hotmail.com; expect SLOW answer,
603 If I am not available, you can discuss PolyGlot issues in Volker
604 Pittlik's Winboard Forum: http://wbforum.volker-pittlik.name/
606 In fact for questions regarding specific Windows-only engines, you are
607 advised to ask directly in the WinBoard forum, as I don't have Windows
614 Fabien Letouzey, 2006/01/16.