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        ScoreWhite (default: true)
 328            Report score from white's point of view in xboard mode.
 329
 330        KibitzMove (default: false)
 331            Whether to kibitz when playing a move.
 332
 333        KibitzPV (default: false)
 334            Whether to kibitz when the PV is changed (new iteration or new best
 335            move).
 336
 337        KibitzCommand (default: "tellall")
 338            xboard command to use for kibitzing, normally "tellall" for kibitz-
 339            ing or "tellothers" for whispering.
 340
 341        KibitzDelay (default: 5)
 342            How many seconds to wait before starting kibitzing.  This has an
 343            effect only if "KibitzPV" is selected, move kibitzes are always
 344            sent regardless of the delay.
 345
 346        KibitzInterval (default: 0)
 347            This is another form of throttling. PolyGlot will usually wait this
 348            many seconds before doing the next kibitz.
 349
 350        UCI (default: false)
 351            If true PolyGlot will not understand xboard commands.
 352
 353        Chess960 (default: false)
 354            Play Chess960 (also called Fischer Random Chess or FRC),
 355
 356        MateScore (default: 10000)
 357            Mate score reported to GUI when in xboard mode.
 358
 359        Book (default: false)
 360            Indicates whether a PolyGlot book should be used.  This has no
 361            effect on the engine own book (which can be controlled with the UCI
 362            option "OwnBook" in the [Engine] section).  In particular, it is
 363            possible to use both a PolyGlot book and an engine book.  In that
 364            case, the engine book will be used whenever PolyGlot is out of
 365            book.  Remember that PolyGlot is unaware of whether the engine is
 366            itself using a book or not.
 367
 368        BookFile (default: book.bin)
 369            The name of the (binary) book file.  Note that PolyGlot will look
 370            for it in the directory it was launched from, not in the engine
 371            directory.  Of course, full path can be used in which case the cur-
 372            rent directory does not matter.
 373
 374        BookRandom (default: true)
 375            Select moves according to their weights in the book. If false the
 376            move with the highest weight is selected.
 377
 378        BookLearn (default: false)
 379            Record learning information in the opening book. Naturally this
 380            requires the opening book to be writable.
 381
 382        UseNice (default: false)
 383            Run the engine at nice level 5, or "NiceValue" if it set.  On some
 384            operating systems it may be necessary to run the engine at lower
 385            priority for it to be responsive to commands from PolyGlot while
 386            searching.
 387
 388        NiceValue (default: 5)
 389            Nice levels go from -20 to 20 with 20 being the lowest priority.
 390            On Unix only root can set negative nice levels. On Windows the
 391            standard Win32 priority levels are mapped in a sensible way to Unix
 392            nice levels.
 393
 394        Affinity (default: -1)
 395            This a bit vector in which each bit represents the processors that
 396            a process is allowed to run on. This option works only on Windows.
 397
 398        Work arounds
 399
 400        Work arounds are identical to options except that they should be used
 401        only when necessary.  Their purpose is to try to hide problems with
 402        various software (not just engines).  The default value is always cor-
 403        rect for bug-free software.
 404
 405        IMPORTANT: Any of these work arounds might be removed in future ver-
 406        sions of PolyGlot.  You are strongly recommended to contact the author
 407        of faulty software and truly fix the problem.
 408
 409        PolyGlot supports the following work arounds:
 410
 411        UCIVersion (default: 2)
 412            The default value of 2 corresponds to UCI+.  Use 1 to select plain
 413            UCI for engines that have problems with UCI+.
 414
 415        CanPonder (default: false)
 416            PolyGlot now conforms to the documented UCI behaviour: the engine
 417            will be allowed to ponder only if it (the engine) declares the
 418            "Ponder" UCI option.  However some engines which can actually pon-
 419            der do not declare the option.  This work around lets PolyGlot know
 420            that they can ponder.
 421
 422        SyncStop (default: false)
 423            When a ponder miss occurs, Polyglot interrupts the engine and IMME-
 424            DIATELY launches a new search.  While there should be no problem
 425            with this, some engines seem confused and corrupt their search
 426            board.  "SyncStop" forces PolyGlot to wait for the (now useless)
 427            ponder search to finish before launching the new search.
 428
 429        PromoteWorkAround (default: false)
 430            Some engines do not specify a promotion piece, e.g. they send
 431            "e7e8" instead of the correct "e7e8q".  This work around enables
 432            the incorrect form (and of course promotes into a queen).
 433
 434        RepeatPV (default: true)
 435            When true, PolyGlot repeats the last pv string (which also contains
 436            score,depth and time usage) it got from the engine. Some engines
 437            however do not send a new pv string just before sending the move.
 438            In that case the output of PolyGlot would be inconsistent.  When
 439            RepeatPV is false PolyGlot does not repeat the last pv string.  Due
 440            to the way kibitzing is implemented, KibitzMove is disabled in that
 441            case.
 442
 443        [Engine] section
 444
 445        This section contains engine UCI options.  PolyGlot does not understand
 446        them, but sends the information to the engine at startup (converted to
 447        UCI form).  You can add any UCI option that makes sense to the engine
 448        (not just the common options about hash-table size and tablebases).
 449
 450        NOTE: use INI syntax, not UCI.  For example "OwnBook = true" is cor-
 451        rect.  It will be replaced by PolyGlot with "setoption name OwnBook
 452        value true" at engine startup.
 453
 454        Standard UCI options are
 455
 456            Hash
 457            NalimovPath
 458            NalimovCache
 459            OwnBook
 460
 461        Hidden options like "Ponder" or "UCI_xxx" are automatic and should not
 462        be put in an INI file.
 463
 464        The other options are engine-specific.  Check their name using a UCI
 465        GUI or launch the engine in a console and type "uci".
 466
 467 EXAMPLES
 468        Compile "games.pgn" into a book "book.bin" retaining all lines of at
 469        most 30 plies.
 470
 471            polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
 472
 473        Merge books "w1.bin" and "w2.bin" into a book "w.bin".
 474
 475            polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
 476
 477        Inspect lines for white in "w.bin"
 478
 479            polyglot dump-book -bin w.bin -color white -out w_white.txt
 480
 481        Test epd file "test.epd" with a (maximum) search time of 7 minutes per
 482        position
 483
 484            polyglot epd-test -epd test.epd -max-time 420
 485
 486        The command line for using the UCI engine "fruit" in a GUI which uses
 487        the xboard protocol.
 488
 489            polyglot -ec fruit
 490
 491        The equivalent config file:
 492
 493            [PolyGlot]
 494            EngineCommand = fruit
 495            [Engine]
 496
 497 EXIT STATUS
 498        PolyGlot always returns 0 on exit.
 499
 500 AUTHORS
 501        Main author: Fabien Letouzey<fabien_letouzey(at)hotmail.com>
 502
 503        Native Windows port:  Huang Chen<webmaster@elephantbase.net> ("Morning
 504        Yellow")
 505
 506        Various enhancements: Fonzy Bleumers<match(at)geenvis.net>
 507
 508        UCI port: Michel Van den Bergh <michel.vandenbergh(at)uhasselt.be>
 509
 510 SEE ALSO
 511        xboard(6)
 512
 513
 514
 515                                   2009-07-26                       POLYGLOT(6)