1 POLYGLOT(6) POLYGLOT(6)
6 PolyGlot - Winboard protocol to UCI protocol adapter
7 - book engine for Polyglot books
8 - a collection of utilities for creating opening books
9 - a utility for analyzing epd files
15 polyglot make-book [-pgn inputfile] [-bin outputfile] [-max-ply ply]
16 [-min-game games] [-min-score score] [-only-white] [-only-black] [-uni-
19 polyglot merge-book -in1 inputfile1 -in2 inputfile2 [-out outputfile]
21 polyglot [configfile] epd-test [-epd inputfile] [-min-depth depth]
22 [-max-depth depth] [-max-time time] [-depth-delta delta]
24 polyglot perft [-fen fen] [-max-depth depth]
27 PolyGlot as adapter and book engine
29 PolyGlot is a "UCI adapter". It connects a GUI interface (such as
30 XBoard, Winboard, Arena or Chessbase) to a UCI chess engine.
32 By specifying an opening book (in PolyGlot book format) chess engines
33 can transparently use such books.
35 PolyGlot understands the two main GUI protocols: UCI and xboard. Nor-
36 mally the protocol will be auto detected but this can be overridden in
37 the configuration file.
39 In xboard mode PolyGlot fully translates between the xboard and UCI
40 protocols. In addition it tries to solve known problems with other
41 adapters. For instance, it detects and reports draws by fifty-move
42 rule, repetition, etc ... It also supports Chess960.
44 When in UCI mode PolyGlot mostly passes commands from the GUI to the
45 engine and vice versa, except that it will play book moves on behalf of
46 the engine when the occasion arises.
50 PolyGlot supports the "PolyGlot opening book format". This is the
51 defacto standard non-proprietary opening book format. It is fully docu-
54 http://alpha.uhasselt.be/Research/Algebra/Toga/book_format.html
56 Roughly speaking a PolyGlot opening book is a collection of triples
57 (position, move, weight). A "position" is represented by a 64-bit
58 Zobrist hash key. The weight is proportional to the probability the
59 move should be played.
61 Other opening book formats such as ChessBase's .ctg format and Arena's
62 .abk format are undocumented and proprietary. They can only be used by
65 PolyGlot can compile a pgn file into a binary PolyGlot book and fur-
66 thermore it can merge two such binary books into a third one.
70 In epd test mode, PolyGlot will search positions in an epd file and
71 record the number of times the right best move was found. The argu-
72 ments specify when to stop the search in any given position.
76 A perft count is the number of legal move sequence in a given position
77 up to a given depth. PolyGlot can perform such perft counts. It is how-
78 ever much slower than other more dedicated programs.
81 When invoked without options or with a config file as argument PolyGlot
82 acts as an adapter. The config file format is documented below. The
83 default config file is "polyglot.ini".
89 PolyGlot supports the following options
91 -pgn (default: "book.pgn")
92 Input file in pgn format.
94 -bin (default: "book.bin")
95 Output file in PolyGlot format.
97 -max-ply (default: 1024)
98 Specifies the maximum ply-depth of lines included in the book.
100 -min-game (default: 3)
101 Specifies the minimum number of games that have to contain this
102 move for it to be included in the book.
104 -min-score (default: 0.0)
105 Specifies the minimum score (or weight) this move should have
106 received for it to be included in the book. The score is
107 2*(wins)+(draws), globally scaled to fit into 16 bits.
110 Include only moves for white in the book.
113 Include only moves for black in the book.
116 Set all weights to 1. In other words, all moves will be selected
117 with equal probability.
123 PolyGlot supports the following options
126 First input file (in PolyGlot book format).
129 Second input file (in PolyGlot book format).
131 -out (default: out.bin)
132 Output file (in PolyGlot book format).
134 Input files are not symmetrical, "in1" has priority over "in2". In
135 other words when a position occurs both in "in1" and "in2" only the
136 moves and weights from "in1" will be retained in "out".
142 (possibly with a config file as first argument) PolyGlot supports the
145 -max-depth (default: 63)
146 Unconditionally stop the search when this depth has been reached.
148 -max-time (default: 5.0)
149 Unconditionally stop the seach after this amount of time.
151 -depth-delta (default: 3)
152 Stop the search if the best move has been constant for this many
153 depths, on condition that the mininal depth and minimal time have
156 -min-depth (default: 8)
157 Minimal search depth when the search is stopped using
160 -min-time (default: 1.0)
161 Minimal search time when the search is stopped using
168 PolyGlot supports the following options
170 -fen (default: starting position)
171 Fen at which to start searching.
173 -max-depth (default: 1)
174 Maximum depth to search.
177 There should be a different config file for each engine.
179 The config file is in the traditional INI format.
188 Lines starting with "#" are ignored.
190 NOTE: There can be spaces in option names or values. Do not use
191 quotes. Boolean values are written as "true" or "false".
195 This section is used by PolyGlot only. The engine is unaware of these
196 options. The list of available options is detailed below.
198 EngineName (default: UCI name)
199 This is the name that will appear in the GUI. It is cosmetic only.
200 You can use different names for tweaked versions of the same
203 EngineDir (default: ".")
204 Full path of the directory where the engine is installed. You can
205 use "." (without the quotes) if you know that PolyGlot will be
206 launched in the engine directory or the engine is in the "path" and
207 does not need any data file.
210 Put here the name of the engine executable file. You can also add
211 command-line arguments. Path searching is used and the current
212 directory will be "EngineDir".
215 Whether PolyGlot should log all transactions with the interface and
216 the engine. This should be necessary only to locate problems.
218 LogFile (default: polyglot.log)
219 The name of the log file. Note that it is put where PolyGlot was
220 launched from, not into the engine directory.
222 WARNING: Log files are not cleared between sessions, and can become
223 very large. It is safe to remove them though.
225 Resign (default: false)
226 Set this to "true" if you want PolyGlot to resign on behalf of the
229 NOTE: Some engines display buggy scores from time to time although
230 the best move is correct. Use this option only if you know what
231 you are doing (e.g. you always check the final position of games).
233 ResignMoves (default: 3)
234 Number of consecutive moves with "resign" score (see below) before
235 PolyGlot resigns for the engine. Positions with only one legal
238 ResignScore (default: 600)
239 This is the score in centipawns that will trigger resign "count-
242 ShowPonder (default: true)
243 Show search information during engine pondering. Turning this off
244 might be better for interactive use in some interfaces.
246 KibitzMove (default: false)
247 Whether to kibitz when playing a move.
249 KibitzPV (default: false)
250 Whether to kibitz when the PV is changed (new iteration or new best
253 KibitzCommand (default: "tellall")
254 xboard command to use for kibitzing, normally "tellall" for kibitz-
255 ing or "tellothers" for whispering.
257 KibitzDelay (default: 5)
258 How many seconds to wait before starting kibitzing. This has an
259 effect only if "KibitzPV" is selected, move kibitzes are always
260 sent regardless of the delay.
263 If true PolyGlot will not understand xboard commands.
265 Book (default: false)
266 Indicates whether a PolyGlot book should be used. This has no
267 effect on the engine own book (which can be controlled with the UCI
268 option "OwnBook" in the [Engine] section). In particular, it is
269 possible to use both a PolyGlot book and an engine book. In that
270 case, the engine book will be used whenever PolyGlot is out of
271 book. Remember that PolyGlot is unaware of whether the engine is
272 itself using a book or not.
274 Chess960 (default: false)
275 Play Chess960 (also called Fischer Random Chess or FRC),
277 MateScore (default: 10000)
278 Mate score reported to GUI when in xboard mode.
280 BookFile (default: book.bin)
281 The name of the (binary) book file. Note that PolyGlot will look
282 for it in the directory it was launched from, not in the engine
283 directory. Of course, full path can be used in which case the cur-
284 rent directory does not matter.
286 NOTE: When using PolyGlot with a UCI GUI this parameter can be set
287 via the UCI option "Polyglot BookFile".
289 BookRandom (default: true)
290 Select moves according to their weights in the book. If false the
291 move with the highest weight is selected.
293 BookLearn (default: false)
294 Record learning information in the opening book. Naturally this
295 requires the opening book to be writable.
297 UseNice (default: false)
298 Run the engine at nice level 5, or "NiceValue" if it set. On some
299 operating systems it may be necessary to run the engine at lower
300 priority for it to be responsive to commands from PolyGlot while
303 NiceValue (default: 5)
304 Nice levels go from -20 to 20 with 20 being the lowest priority.
305 On Unix only root can set negative nice levels. On Windows the
306 standard Win32 priority levels are mapped in a sensible way to Unix
309 Affinity (default: -1)
310 This a bit vector in which each bit represents the processors that
311 a process is allowed to run on. This option works only on Windows.
315 Work arounds are identical to options except that they should be used
316 only when necessary. Their purpose is to try to hide problems with
317 various software (not just engines). The default value is always cor-
318 rect for bug-free software.
320 IMPORTANT: Any of these work arounds might be removed in future ver-
321 sions of PolyGlot. You are strongly recommended to contact the author
322 of faulty software and truly fix the problem.
324 PolyGlot supports the following work arounds:
326 UCIVersion (default: 2)
327 The default value of 2 corresponds to UCI+. Use 1 to select plain
328 UCI for engines that have problems with UCI+.
330 CanPonder (default: false)
331 PolyGlot now conforms to the documented UCI behaviour: the engine
332 will be allowed to ponder only if it (the engine) declares the
333 "Ponder" UCI option. However some engines which can actually pon-
334 der do not declare the option. This work around lets PolyGlot know
335 that they can ponder.
337 SyncStop (default: false)
338 When a ponder miss occurs, Polyglot interrupts the engine and IMME-
339 DIATELY launches a new search. While there should be no problem
340 with this, some engines seem confused and corrupt their search
341 board. "SyncStop" forces PolyGlot to wait for the (now useless)
342 ponder search to finish before launching the new search.
344 PromoteWorkAround (default: false)
345 Some engines do not specify a promotion piece, e.g. they send
346 "e7e8" instead of the correct "e7e8q". This work around enables
347 the incorrect form (and of course promotes into a queen).
349 RepeatPV (default: true)
350 When true, PolyGlot repeats the last pv string (which also contains
351 score,depth and time usage) it got from the engine. Some engines
352 however do not send a new pv string just before sending the move
353 and the now old pv string might confuse debugtools that parse the
354 winboard debug files.
358 This section contains engine UCI options. PolyGlot does not understand
359 them, but sends the information to the engine at startup (converted to
360 UCI form). You can add any UCI option that makes sense to the engine
361 (not just the common options about hash-table size and tablebases).
363 NOTE: use INI syntax, not UCI. For example "OwnBook = true" is cor-
364 rect. It will be replaced by PolyGlot with "setoption name OwnBook
365 value true" at engine startup.
367 Standard UCI options are
374 Hidden options like "Ponder" or "UCI_xxx" are automatic and should not
375 be put in an INI file.
377 The other options are engine-specific. Check their name using a UCI
378 GUI or launch the engine in a console and type "uci".
381 Compile "games.pgn" into a book "book.bin" retaining all lines of at
384 polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
386 Merge books "in1.bin" and "in2.bin" into a book "out.bin".
388 polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
390 Here is a minimal config file
393 EngineCommand = fruit
397 PolyGlot always returns 0 on exit.
400 Main author: Fabien Letouzey<fabien_letouzey(at)hotmail.com>
402 Native Windows port: Huang Chen<webmaster@elephantbase.net> ("Morning
405 Various enhancements: Fonzy Bleumers<match(at)geenvis.net>
407 UCI port: Michel Van den Bergh <michel.vandenbergh(at)uhasselt.be>
414 2009-01-10 POLYGLOT(6)