README

   1 POLYGLOT(6)                                                        POLYGLOT(6)
   2
   3
   4
   5 NAME
   6        PolyGlot -  Winboard protocol to UCI protocol adapter
   7                 -  book engine for Polyglot books
   8                 -  a collection of utilities for creating and analyzing open-
   9        ing books
  10                 -  a utility for analyzing epd files
  11                 -  a perft counter
  12
  13 SYNOPSIS
  14        polyglot [configfile]
  15
  16        polyglot -ec engine
  17
  18        polyglot make-book [-pgn inputfile] [-bin outputfile] [-max-ply ply]
  19        [-min-game games] [-min-score score] [-only-white] [-only-black] [-uni-
  20        form]
  21
  22        polyglot merge-book -in1 inputfile1 -in2 inputfile2 [-out outputfile]
  23
  24        polyglot info-book [-bin inputfile] [-exact]
  25
  26        polyglot dumb-book [-bin inputfile] -color color [-out outputfile]
  27
  28        polyglot [configfile] epd-test [-epd inputfile] [-min-depth depth]
  29        [-max-depth depth] [-max-time time] [-depth-delta delta]
  30
  31        polyglot perft [-fen fen] [-max-depth depth]
  32
  33 DESCRIPTION
  34        PolyGlot as adapter and book engine
  35
  36        PolyGlot is a "UCI adapter".  It connects a GUI interface (such as
  37        XBoard, Winboard, Arena or Chessbase) to a UCI chess engine.
  38
  39        By specifying an opening book (in PolyGlot book format) chess engines
  40        can transparently use such books.
  41
  42        PolyGlot understands the two main GUI protocols: UCI and xboard. Nor-
  43        mally the protocol will be auto detected but this can be overridden in
  44        the configuration file.
  45
  46        In xboard mode PolyGlot fully translates between the xboard and UCI
  47        protocols.  In addition it tries to solve known problems with other
  48        adapters.  For instance, it detects and reports draws by fifty-move
  49        rule, repetition, etc ... It also supports Chess960.
  50
  51        When in UCI mode PolyGlot mostly passes commands from the GUI to the
  52        engine and vice versa, except that it will play book moves on behalf of
  53        the engine when the occasion arises.
  54
  55        The engine options are exported as UCI options in UCI mode and as "fea-
  56        ture option=" commands in xboard mode. The latter form an extension of
  57        the xboard protocol as defined by H.G. Muller.
  58
  59        Options which normally appear in the [PolyGlot] section of the config
  60        file (see below) are exported as options with their name prefixed by
  61        "Polyglot". This makes it easy to filter them in the GUI.
  62
  63        NOTE: Not all options are exported, only those that make sense in the
  64        given mode.
  65
  66        Book making utilities
  67
  68        PolyGlot supports the "PolyGlot opening book format". This is the
  69        defacto standard non-proprietary opening book format. It is fully docu-
  70        mented here
  71
  72        http://alpha.uhasselt.be/Research/Algebra/Toga/book_format.html
  73
  74        Roughly speaking a PolyGlot opening book is a collection of triples
  75        (position, move, weight). A "position" is represented by a 64-bit
  76        Zobrist hash key. The weight is proportional to the probability the
  77        move should be played.
  78
  79        Other opening book formats such as ChessBase's .ctg format and Arena's
  80        .abk format are undocumented and proprietary. They can only be used by
  81        their own GUIs.
  82
  83        PolyGlot can compile a pgn file into a binary PolyGlot book and fur-
  84        thermore it can merge two such binary books into a third one.
  85
  86        PolyGlot can also extract some useful information from PolyGlot books.
  87        The utility "dump-book" dumps the "lines" in a book for a given color.
  88        By definition a line is a sequence of moves (from the starting posi-
  89        tion) in which the given color makes only book moves and the other
  90        color makes arbitrary moves (i.e. not necessarily book moves).
  91
  92        Since a PolyGlot book is built up from positions and not lines there
  93        may be (and there usually are) many positions in the book that are not
  94        on a "line" as defined in the previous paragraph. It is convenient to
  95        call such positions "isolated" positions. The utility "info-book"
  96        counts such isolated positions.
  97
  98        Some of the isolated positions are provably unreachable and they could
  99        in principle be deleted from the book. For example if a book contains
 100        only the move "e4" in the starting position but also the position after
 101        "d4 d5" then this last position is provably unreachable since it
 102        requires white to make a non-book move when a book move is available.
 103        Such situations arise frequently from the priority rules in merging
 104        books.
 105
 106        Unfortunately not all isolated positions are provably unreachable and
 107        it is difficult to identify the latter. If invoked with "-exact" the
 108        utility info-book will attempt to count the isolated positions which
 109        require a player to make a non-book move when a book move is available.
 110        Due to the possibility of transpositions this is not a fool proof
 111        method.
 112
 113        Epd test mode
 114
 115        In epd test mode, PolyGlot will search positions in an epd file and
 116        record the number of times the right best move was found.  The argu-
 117        ments specify when to stop the search in any given position.
 118
 119        Perft counts
 120
 121        A perft count is the number of legal move sequence in a given position
 122        up to a given depth. PolyGlot can perform such perft counts. It is how-
 123        ever much slower than other more dedicated programs.
 124
 125 OPTIONS
 126        When invoked without options or with a config file as argument PolyGlot
 127        acts as an adapter. The config file format is documented below.  The
 128        default config file is "polyglot.ini".
 129
 130        When invoked as
 131
 132        polyglot -ec engine
 133
 134        PolyGlot simply starts "engine" and acts as an adapter. No config file
 135        is used and thus it is expected that all properties will be set by the
 136        GUI.
 137
 138        When invoked as
 139
 140        polyglot make-book
 141
 142        PolyGlot supports the following options
 143
 144        -pgn (default: "book.pgn")
 145            Input file in pgn format.
 146
 147        -bin (default: "book.bin")
 148            Output file in PolyGlot format.
 149
 150        -max-ply (default: 1024)
 151            Specifies the maximum ply-depth of lines included in the book.
 152
 153        -min-game (default: 3)
 154            Specifies the minimum number of games that have to contain this
 155            move for it to be included in the book.
 156
 157        -min-score (default: 0.0)
 158            Specifies the minimum score (or weight) this move should have
 159            received for it to  be included in the book. The score is
 160            2*(wins)+(draws), globally scaled to fit into 16 bits.
 161
 162        -only-white
 163            Include only moves for white in the book.
 164
 165        -only-black
 166            Include only moves for black in the book.
 167
 168        -uniform
 169            Set all weights to 1. In other words, all moves will be selected
 170            with equal probability.
 171
 172        When invoked as
 173
 174        polyglot merge-book
 175
 176        PolyGlot supports the following options
 177
 178        -in1
 179            First input file (in PolyGlot book format).
 180
 181        -in2
 182            Second input file (in PolyGlot book format).
 183
 184        -out (default: out.bin)
 185            Output file (in PolyGlot book format).
 186
 187        Input files are not symmetrical, "in1" has priority over "in2". In
 188        other words when a position occurs both in "in1" and "in2" only the
 189        moves and weights from "in1" will be retained in "out".
 190
 191        When invoked as
 192
 193        polyglot dump-book
 194
 195        PolyGlot supports the following options
 196
 197        -bin (default: book.bin)
 198            Input file in PolyGlot book format.
 199
 200        -color
 201            The color for whom to generate the lines.
 202
 203        -out (default: book_<color>.txt)
 204            The name of the output file.
 205
 206        When invoked as
 207
 208        polyglot info-book
 209
 210        PolyGlot supports the following options
 211
 212        -bin (default: book.bin)
 213            Input file in PolyGlot book format.
 214
 215        -exact
 216            Attempt to count the provably unreachable positions among the iso-
 217            lated ones.  Note that this takes a very long time.
 218
 219        When invoked as
 220
 221        polyglot epd-test
 222
 223        (possibly with a config file as first argument) PolyGlot supports the
 224        following options
 225
 226        -max-depth (default: 63)
 227            Unconditionally stop the search when this depth has been reached.
 228
 229        -max-time (default: 5.0)
 230            Unconditionally stop the seach after this amount of time.
 231
 232        -depth-delta (default: 3)
 233            Stop the search if the solution as been found and the best move has
 234            been constant for this many depths, on condition that the mininal
 235            depth and minimal time have been reached.
 236
 237        -min-depth (default: 8)
 238            Minimal search depth when the search is stopped using
 239            "-depth-delta".
 240
 241        -min-time (default: 1.0)
 242            Minimal search time when the search is stopped using
 243            "-depth-delta".
 244
 245        When invoked as
 246
 247        polyglot perft
 248
 249        PolyGlot supports the following options
 250
 251        -fen (default: starting position)
 252            Fen at which to start searching.
 253
 254        -max-depth (default: 1)
 255            Maximum depth to search.
 256
 257 CONFIG FILE FORMAT
 258        There should be a different config file for each engine.
 259
 260        The config file is in the traditional INI format.
 261
 262            [PolyGLot]
 263            option = value
 264            ...
 265            [Engine]
 266            option = value
 267            ...
 268
 269        The characters "#" and ";" serve as comment characters.
 270
 271        NOTE: There can be spaces in option names or values.  Do not use
 272        quotes. Boolean values are written as "true" or "false".
 273
 274        [PolyGlot] section
 275
 276        This section is used by PolyGlot only.  The engine is unaware of these
 277        options.  The list of available options is detailed below.
 278
 279        EngineName (default: UCI name)
 280            This is the name that will appear in the GUI.  It is cosmetic only.
 281            You can use different names for tweaked versions of the same
 282            engine.
 283
 284        EngineDir (default: ".")
 285            Full path of the directory where the engine is installed.  You can
 286            use "." (without the quotes) if you know that PolyGlot will be
 287            launched in the engine directory or the engine is in the "path" and
 288            does not need any data file.
 289
 290        EngineCommand
 291            Put here the name of the engine executable file.  You can also add
 292            command-line arguments.  Path searching is used and the current
 293            directory will be "EngineDir".
 294
 295        Log (default: false)
 296            Whether PolyGlot should log all transactions with the interface and
 297            the engine.  This should be necessary only to locate problems.
 298
 299        LogFile (default: polyglot.log)
 300            The name of the log file.  Note that it is put where PolyGlot was
 301            launched from, not into the engine directory.
 302
 303            WARNING: Log files are not cleared between sessions, and can become
 304            very large.  It is safe to remove them though.
 305
 306        Resign (default: false)
 307            Set this to "true" if you want PolyGlot to resign on behalf of the
 308            engine.
 309
 310            NOTE: Some engines display buggy scores from time to time although
 311            the best move is correct.  Use this option only if you know what
 312            you are doing (e.g. you always check the final position of games).
 313
 314        ResignMoves (default: 3)
 315            Number of consecutive moves with "resign" score (see below) before
 316            PolyGlot resigns for the engine.  Positions with only one legal
 317            move are ignored.
 318
 319        ResignScore (default: 600)
 320            This is the score in centipawns that will trigger resign "count-
 321            ing".
 322
 323        ShowPonder (default: true)
 324            Show search information during engine pondering.  Turning this off
 325            might be better for interactive use in some interfaces.
 326
 327        KibitzMove (default: false)
 328            Whether to kibitz when playing a move.
 329
 330        KibitzPV (default: false)
 331            Whether to kibitz when the PV is changed (new iteration or new best
 332            move).
 333
 334        KibitzCommand (default: "tellall")
 335            xboard command to use for kibitzing, normally "tellall" for kibitz-
 336            ing or "tellothers" for whispering.
 337
 338        KibitzDelay (default: 5)
 339            How many seconds to wait before starting kibitzing.  This has an
 340            effect only if "KibitzPV" is selected, move kibitzes are always
 341            sent regardless of the delay.
 342
 343        UCI (default: false)
 344            If true PolyGlot will not understand xboard commands.
 345
 346        Chess960 (default: false)
 347            Play Chess960 (also called Fischer Random Chess or FRC),
 348
 349        MateScore (default: 10000)
 350            Mate score reported to GUI when in xboard mode.
 351
 352        Book (default: false)
 353            Indicates whether a PolyGlot book should be used.  This has no
 354            effect on the engine own book (which can be controlled with the UCI
 355            option "OwnBook" in the [Engine] section).  In particular, it is
 356            possible to use both a PolyGlot book and an engine book.  In that
 357            case, the engine book will be used whenever PolyGlot is out of
 358            book.  Remember that PolyGlot is unaware of whether the engine is
 359            itself using a book or not.
 360
 361        BookFile (default: book.bin)
 362            The name of the (binary) book file.  Note that PolyGlot will look
 363            for it in the directory it was launched from, not in the engine
 364            directory.  Of course, full path can be used in which case the cur-
 365            rent directory does not matter.
 366
 367        BookRandom (default: true)
 368            Select moves according to their weights in the book. If false the
 369            move with the highest weight is selected.
 370
 371        BookLearn (default: false)
 372            Record learning information in the opening book. Naturally this
 373            requires the opening book to be writable.
 374
 375        UseNice (default: false)
 376            Run the engine at nice level 5, or "NiceValue" if it set.  On some
 377            operating systems it may be necessary to run the engine at lower
 378            priority for it to be responsive to commands from PolyGlot while
 379            searching.
 380
 381        NiceValue (default: 5)
 382            Nice levels go from -20 to 20 with 20 being the lowest priority.
 383            On Unix only root can set negative nice levels. On Windows the
 384            standard Win32 priority levels are mapped in a sensible way to Unix
 385            nice levels.
 386
 387        Affinity (default: -1)
 388            This a bit vector in which each bit represents the processors that
 389            a process is allowed to run on. This option works only on Windows.
 390
 391        Work arounds
 392
 393        Work arounds are identical to options except that they should be used
 394        only when necessary.  Their purpose is to try to hide problems with
 395        various software (not just engines).  The default value is always cor-
 396        rect for bug-free software.
 397
 398        IMPORTANT: Any of these work arounds might be removed in future ver-
 399        sions of PolyGlot.  You are strongly recommended to contact the author
 400        of faulty software and truly fix the problem.
 401
 402        PolyGlot supports the following work arounds:
 403
 404        UCIVersion (default: 2)
 405            The default value of 2 corresponds to UCI+.  Use 1 to select plain
 406            UCI for engines that have problems with UCI+.
 407
 408        CanPonder (default: false)
 409            PolyGlot now conforms to the documented UCI behaviour: the engine
 410            will be allowed to ponder only if it (the engine) declares the
 411            "Ponder" UCI option.  However some engines which can actually pon-
 412            der do not declare the option.  This work around lets PolyGlot know
 413            that they can ponder.
 414
 415        SyncStop (default: false)
 416            When a ponder miss occurs, Polyglot interrupts the engine and IMME-
 417            DIATELY launches a new search.  While there should be no problem
 418            with this, some engines seem confused and corrupt their search
 419            board.  "SyncStop" forces PolyGlot to wait for the (now useless)
 420            ponder search to finish before launching the new search.
 421
 422        PromoteWorkAround (default: false)
 423            Some engines do not specify a promotion piece, e.g. they send
 424            "e7e8" instead of the correct "e7e8q".  This work around enables
 425            the incorrect form (and of course promotes into a queen).
 426
 427        RepeatPV (default: true)
 428            When true, PolyGlot repeats the last pv string (which also contains
 429            score,depth and time usage) it got from the engine. Some engines
 430            however do not send a new pv string just before sending the move
 431            and the now old pv string might confuse debugtools that parse the
 432            winboard debug files.
 433
 434        [Engine] section
 435
 436        This section contains engine UCI options.  PolyGlot does not understand
 437        them, but sends the information to the engine at startup (converted to
 438        UCI form).  You can add any UCI option that makes sense to the engine
 439        (not just the common options about hash-table size and tablebases).
 440
 441        NOTE: use INI syntax, not UCI.  For example "OwnBook = true" is cor-
 442        rect.  It will be replaced by PolyGlot with "setoption name OwnBook
 443        value true" at engine startup.
 444
 445        Standard UCI options are
 446
 447            Hash
 448            NalimovPath
 449            NalimovCache
 450            OwnBook
 451
 452        Hidden options like "Ponder" or "UCI_xxx" are automatic and should not
 453        be put in an INI file.
 454
 455        The other options are engine-specific.  Check their name using a UCI
 456        GUI or launch the engine in a console and type "uci".
 457
 458 EXAMPLES
 459        Compile "games.pgn" into a book "book.bin" retaining all lines of at
 460        most 30 plies.
 461
 462            polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
 463
 464        Merge books "w1.bin" and "w2.bin" into a book "w.bin".
 465
 466            polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
 467
 468        Inspect lines for white in "w.bin"
 469
 470            polyglot dump-book -bin w.bin -color white -out w_white.txt
 471
 472        Test epd file "test.epd" with a (maximum) search time of 7 minutes per
 473        position
 474
 475            polyglot epd-test -epd test.epd -max-time 420
 476
 477        The command line for using the UCI engine "fruit" in a GUI which uses
 478        the xboard protocol.
 479
 480            polyglot -ec fruit
 481
 482        The equivalent config file:
 483
 484            [PolyGlot]
 485            EngineCommand = fruit
 486            [Engine]
 487
 488 EXIT STATUS
 489        PolyGlot always returns 0 on exit.
 490
 491 AUTHORS
 492        Main author: Fabien Letouzey<fabien_letouzey(at)hotmail.com>
 493
 494        Native Windows port:  Huang Chen<webmaster@elephantbase.net> ("Morning
 495        Yellow")
 496
 497        Various enhancements: Fonzy Bleumers<match(at)geenvis.net>
 498
 499        UCI port: Michel Van den Bergh <michel.vandenbergh(at)uhasselt.be>
 500
 501 SEE ALSO
 502        xboard(6)
 503
 504
 505
 506                                   2009-01-16                       POLYGLOT(6)