3 PolyGlot - Winboard protocol to UCI protocol adapter
4 - book engine for Polyglot books
5 - a collection of utilities for creating opening books
6 - a utility for analyzing epd files
15 polyglot make-book [-pgn inputfile] [-bin outputfile] [-max-ply ply] [-min-game games] [-min-score score] [-only-white] [-only-black] [-uniform]
17 polyglot merge-book -in1 inputfile1 -in2 inputfile2 [-out outputfile]
19 polyglot [configfile] epd-test [-epd inputfile] [-min-depth depth] [-max-depth depth] [-max-time time] [-depth-delta delta]
21 polyglot perft [-fen fen] [-max-depth depth]
25 =head2 PolyGlot as adapter and book engine
27 PolyGlot is a "UCI adapter". It connects a GUI interface (such as
28 XBoard, Winboard, Arena or Chessbase) to a UCI chess engine.
30 By specifying an opening book (in PolyGlot book format) chess engines can
31 transparently use such books.
33 PolyGlot understands the two main GUI protocols: UCI and
34 xboard. Normally the protocol will be auto detected but this can be
35 overridden in the configuration file.
37 In xboard mode PolyGlot fully translates between the xboard and UCI protocols.
38 In addition it tries to solve known problems with other adapters.
39 For instance, it detects and reports draws by fifty-move rule,
40 repetition, etc ... It also supports Chess960.
42 When in UCI mode PolyGlot mostly passes commands from the GUI
43 to the engine and vice versa, except that it will play book moves on
44 behalf of the engine when the occasion arises.
46 The engine options are exported as UCI options in UCI
47 mode and as "feature option=" commands in xboard mode. The latter form
48 an extension of the xboard protocol as defined by H.G. Muller.
50 Options which normally appear in the [PolyGlot] section of the
51 config file (see below) are exported as options with their name prefixed
52 by "Polyglot". This makes it easy to filter them in the GUI.
54 NOTE: Not all options are exported, only those that make sense in the
57 =head2 Book making utilities
59 PolyGlot supports the "PolyGlot opening book format". This is the
60 defacto standard non-proprietary opening book format. It is fully documented
63 http://alpha.uhasselt.be/Research/Algebra/Toga/book_format.html
65 Roughly speaking a PolyGlot opening book is a collection of triples
66 (position, move, weight). A "position" is represented by a 64-bit
67 Zobrist hash key. The weight is proportional to the probability the move should
70 Other opening book formats such as ChessBase's .ctg format and Arena's
71 .abk format are undocumented and proprietary. They can only be used
74 PolyGlot can compile a pgn file into a binary PolyGlot book and furthermore
75 it can merge two such binary books into a third one.
79 In epd test mode, PolyGlot will search positions in an epd file and
80 record the number of times the right best move was found. The
81 arguments specify when to stop the search in any given position.
85 A perft count is the number of legal move sequence in a given position
86 up to a given depth. PolyGlot can perform such perft counts. It
87 is however much slower than other more dedicated programs.
91 When invoked without options or with a config file as argument PolyGlot
92 acts as an adapter. The config file format is documented below. The
93 default config file is "polyglot.ini".
97 =head2 polyglot -ec engine
99 PolyGlot simply starts "engine" and acts as an adapter. No config file
100 is used and thus it is expected that all properties will be set by the
105 =head2 polyglot make-book
107 PolyGlot supports the following options
111 =item B<-pgn> (default: "book.pgn")
113 Input file in pgn format.
115 =item B<-bin> (default: "book.bin")
117 Output file in PolyGlot format.
119 =item B<-max-ply> (default: 1024)
121 Specifies the maximum ply-depth of lines included in the book.
123 =item B<-min-game> (default: 3)
125 Specifies the minimum number of games that have to contain this move for it to be included in the book.
127 =item B<-min-score> (default: 0.0)
129 Specifies the minimum score (or weight) this move should have received for
130 it to be included in the book. The score is 2*(wins)+(draws), globally scaled
135 Include only moves for white in the book.
139 Include only moves for black in the book.
143 Set all weights to 1. In other words, all moves will be selected with
151 =head2 polyglot merge-book
153 PolyGlot supports the following options
159 First input file (in PolyGlot book format).
163 Second input file (in PolyGlot book format).
165 =item B<-out> (default: out.bin)
167 Output file (in PolyGlot book format).
171 Input files are not symmetrical, "in1" has priority over "in2". In other
172 words when a position occurs both in "in1" and "in2" only the
173 moves and weights from "in1" will be retained in "out".
177 =head2 polyglot epd-test
179 (possibly with a config file as first argument) PolyGlot supports the following
184 =item B<-max-depth> (default: 63)
186 Unconditionally stop the search when this depth has
189 =item B<-max-time> (default: 5.0)
191 Unconditionally stop the seach after this amount of time.
193 =item B<-depth-delta> (default: 3)
195 Stop the search if the best move has been constant for this many depths,
196 on condition that the mininal depth and minimal time have been reached.
198 =item B<-min-depth> (default: 8)
200 Minimal search depth when the search is stopped using "-depth-delta".
202 =item B<-min-time> (default: 1.0)
204 Minimal search time when the search is stopped using "-depth-delta".
211 =head2 polyglot perft
213 PolyGlot supports the following
218 =item B<-fen> (default: starting position)
220 Fen at which to start searching.
222 =item B<-max-depth> (default: 1)
224 Maximum depth to search.
228 =head1 CONFIG FILE FORMAT
230 There should be a different config file for each engine.
232 The config file is in the traditional INI format.
241 Lines starting with "#" are ignored.
243 NOTE: There can be spaces in option names or values. Do not use
244 quotes. Boolean values are written as "true" or "false".
246 =head2 [PolyGlot] section
248 This section is used by PolyGlot only. The engine is unaware of these
249 options. The list of available options is detailed below.
253 =item B<EngineName> (default: UCI name)
255 This is the name that will appear in the GUI. It is
256 cosmetic only. You can use different names for tweaked versions of
259 =item B<EngineDir> (default: ".")
261 Full path of the directory where the engine is installed. You can use
262 "." (without the quotes) if you know that PolyGlot will be launched in
263 the engine directory or the engine is in the "path" and does not need
266 =item B<EngineCommand>
268 Put here the name of the engine executable file. You can also add
269 command-line arguments. Path searching is used and the current
270 directory will be "EngineDir".
272 =item B<Log> (default: false)
274 Whether PolyGlot should log all transactions with the interface and
275 the engine. This should be necessary only to locate problems.
277 =item B<LogFile> (default: polyglot.log)
279 The name of the log file. Note that it is put where PolyGlot was
280 launched from, not into the engine directory.
282 WARNING: Log files are not cleared between sessions, and can become
283 very large. It is safe to remove them though.
285 =item B<Resign> (default: false)
287 Set this to "true" if you want PolyGlot to resign on behalf of the
290 NOTE: Some engines display buggy scores from time to time although the
291 best move is correct. Use this option only if you know what you are
292 doing (e.g. you always check the final position of games).
294 =item B<ResignMoves> (default: 3)
296 Number of consecutive moves with "resign" score (see below) before
297 PolyGlot resigns for the engine. Positions with only one legal move
300 =item B<ResignScore> (default: 600)
302 This is the score in centipawns that will trigger resign "counting".
304 =item B<ShowPonder> (default: true)
306 Show search information during engine pondering. Turning this off
307 might be better for interactive use in some interfaces.
309 =item B<KibitzMove> (default: false)
311 Whether to kibitz when playing a move.
313 =item B<KibitzPV> (default: false)
315 Whether to kibitz when the PV is changed (new iteration or new best move).
317 =item B<KibitzCommand> (default: "tellall")
319 xboard command to use for kibitzing, normally "tellall" for kibitzing
320 or "tellothers" for whispering.
323 =item B<KibitzDelay> (default: 5)
325 How many seconds to wait before starting kibitzing. This has an
326 effect only if "KibitzPV" is selected, move kibitzes are always sent
327 regardless of the delay.
329 =item B<UCI> (default: false)
331 If true PolyGlot will not understand xboard commands.
333 =item B<Chess960> (default: false)
335 Play Chess960 (also called Fischer Random Chess or FRC),
337 =item B<MateScore> (default: 10000)
339 Mate score reported to GUI when in xboard mode.
341 =item B<Book> (default: false)
343 Indicates whether a PolyGlot book should be used. This has no effect
344 on the engine own book (which can be controlled with the UCI option
345 "OwnBook" in the [Engine] section). In particular, it is possible to
346 use both a PolyGlot book and an engine book. In that case, the engine
347 book will be used whenever PolyGlot is out of book. Remember that
348 PolyGlot is unaware of whether the engine is itself using a book or
351 =item B<BookFile> (default: book.bin)
353 The name of the (binary) book file. Note that PolyGlot will look for
354 it in the directory it was launched from, not in the engine directory.
355 Of course, full path can be used in which case the current directory
358 =item B<BookRandom> (default: true)
360 Select moves according to their weights in the book. If false the move
361 with the highest weight is selected.
363 =item B<BookLearn> (default: false)
365 Record learning information in the opening book. Naturally this requires
366 the opening book to be writable.
368 =item B<UseNice> (default: false)
370 Run the engine at nice level 5, or "NiceValue" if it set. On some
371 operating systems it may be necessary to run the engine at lower
372 priority for it to be responsive to commands from PolyGlot while
375 =item B<NiceValue> (default: 5)
377 Nice levels go from -20 to 20 with 20 being the lowest priority.
378 On Unix only root can set negative nice levels. On Windows the standard
379 Win32 priority levels are mapped in a sensible way to Unix nice levels.
382 =item B<Affinity> (default: -1)
384 This a bit vector in which each bit represents the processors that a
385 process is allowed to run on. This option works only on Windows.
392 Work arounds are identical to options except that they should be used
393 only when necessary. Their purpose is to try to hide problems with
394 various software (not just engines). The default value is always
395 correct for bug-free software.
397 IMPORTANT: Any of these work arounds might be removed in future
398 versions of PolyGlot. You are strongly recommended to contact the
399 author of faulty software and truly fix the problem.
401 PolyGlot supports the following work arounds:
405 =item B<UCIVersion> (default: 2)
407 The default value of 2 corresponds to UCI+. Use 1 to select plain
408 UCI for engines that have problems with UCI+.
410 =item B<CanPonder> (default: false)
412 PolyGlot now conforms to the documented UCI behaviour: the engine will
413 be allowed to ponder only if it (the engine) declares the "Ponder" UCI
414 option. However some engines which can actually ponder do not declare
415 the option. This work around lets PolyGlot know that they can ponder.
417 =item B<SyncStop> (default: false)
419 When a ponder miss occurs, Polyglot interrupts the engine and
420 IMMEDIATELY launches a new search. While there should be no problem
421 with this, some engines seem confused and corrupt their search board.
422 "SyncStop" forces PolyGlot to wait for the (now useless) ponder search
423 to finish before launching the new search.
425 =item B<PromoteWorkAround> (default: false)
427 Some engines do not specify a promotion piece, e.g. they send "e7e8"
428 instead of the correct "e7e8q". This work around enables the
429 incorrect form (and of course promotes into a queen).
431 =item B<RepeatPV> (default: true)
433 When true, PolyGlot repeats the last pv string (which also contains
434 score,depth and time usage) it got from the engine. Some engines
435 however do not send a new pv string just before sending the move and
436 the now old pv string might confuse debugtools that parse the winboard
443 =head2 [Engine] section
445 This section contains engine UCI options. PolyGlot does not
446 understand them, but sends the information to the engine at startup
447 (converted to UCI form). You can add any UCI option that makes sense
448 to the engine (not just the common options about hash-table size and
451 NOTE: use INI syntax, not UCI. For example "OwnBook = true" is
452 correct. It will be replaced by PolyGlot with "setoption name OwnBook
453 value true" at engine startup.
455 Standard UCI options are
462 Hidden options like "Ponder" or "UCI_xxx" are automatic
463 and should not be put in an INI file.
465 The other options are engine-specific. Check their name using a UCI
466 GUI or launch the engine in a console and type "uci".
470 Compile "games.pgn" into a book "book.bin" retaining all lines of at
473 polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
475 Merge books "in1.bin" and "in2.bin" into a book "out.bin".
477 polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
479 The command line for using the UCI engine "fruit" in a GUI which uses the
484 The equivalent config file:
487 EngineCommand = fruit
493 PolyGlot always returns 0 on exit.
497 Main author: Fabien Letouzey<fabien_letouzey(at)hotmail.com>
499 Native Windows port: Huang Chen<webmaster@elephantbase.net> ("Morning Yellow")
501 Various enhancements: Fonzy Bleumers<match(at)geenvis.net>
503 UCI port: Michel Van den Bergh <michel.vandenbergh(at)uhasselt.be>