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
   9        opening books
  10                 -  a utility for analyzing epd files
  11                 -  a perft counter
  12
  13 SYNOPSIS
  14        polyglot [configfile] [-noini] [-ec engine] [-ed enginedirectory] [-en
  15        enginename] [-log] [-lf logfile] [-hash value] [-bk book] [-pg
  16        <name>=<value>]* [-uci <name>=<value>]*
  17
  18        polyglot make-book [-pgn inputfile] [-bin outputfile] [-max-ply ply]
  19        [-min-game games] [-min-score score] [-only-white] [-only-black]
  20        [-uniform]
  21
  22        polyglot merge-book -in1 inputfile1 -in2 inputfile2 [-out outputfile]
  23
  24        polyglot info-book [-bin inputfile] [-exact]
  25
  26        polyglot dump-book [-bin inputfile] -color color [-out outputfile]
  27
  28        polyglot [configfile] epd-test [engineoptions] [-epd inputfile]
  29        [-min-depth depth] [-max-depth depth] [-max-time time] [-depth-delta
  30        delta]
  31
  32        polyglot perft [-fen fen] [-max-depth depth]
  33
  34 DESCRIPTION
  35    PolyGlot as adapter and book engine
  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.
  43        Normally the protocol will be auto detected but this can be overridden
  44        in 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
  56        "feature option=" commands in xboard mode. The latter form an extension
  57        of 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        PolyGlot supports the "PolyGlot opening book format". This is the
  68        defacto standard non-proprietary opening book format. It is fully
  69        documented here
  70
  71        http://alpha.uhasselt.be/Research/Algebra/Toga/book_format.html
  72
  73        Roughly speaking a PolyGlot opening book is a collection of triples
  74        (position, move, weight). A "position" is represented by a 64-bit
  75        Zobrist hash key. The weight is proportional to the probability the
  76        move should be played.
  77
  78        Other opening book formats such as ChessBase's .ctg format and Arena's
  79        .abk format are undocumented and proprietary. They can only be used by
  80        their own GUIs.
  81
  82        PolyGlot can compile a pgn file into a binary PolyGlot book and
  83        furthermore it can merge two such binary books into a third one.
  84
  85        PolyGlot can also extract some useful information from PolyGlot books.
  86        The utility "dump-book" dumps the "lines" in a book for a given color.
  87        By definition a line is a sequence of moves (from the starting
  88        position) in which the given color makes only book moves and the other
  89        color makes arbitrary moves (i.e. not necessarily book moves).
  90
  91        Since a PolyGlot book is built up from positions and not lines there
  92        may be (and there usually are) many positions in the book that are not
  93        on a "line" as defined in the previous paragraph. It is convenient to
  94        call such positions "isolated" positions. The utility "info-book"
  95        counts such isolated positions.
  96
  97        Some of the isolated positions are provably unreachable and they could
  98        in principle be deleted from the book. For example if a book contains
  99        only the move "e4" in the starting position but also the position after
 100        "d4 d5" then this last position is provably unreachable since it
 101        requires white to make a non-book move when a book move is available.
 102        Such situations arise frequently from the priority rules in merging
 103        books.
 104
 105        Unfortunately not all isolated positions are provably unreachable and
 106        it is difficult to identify the latter. If invoked with "-exact" the
 107        utility info-book will attempt to count the isolated positions which
 108        require a player to make a non-book move when a book move is available.
 109        Due to the possibility of transpositions this is not a fool proof
 110        method.
 111
 112    Epd test mode
 113        In epd test mode, PolyGlot will search positions in an epd file and
 114        record the number of times the right best move was found.  The
 115        arguments specify when to stop the search in any given position.
 116
 117    Perft counts
 118        A perft count is the number of legal move sequence in a given position
 119        up to a given depth. PolyGlot can perform such perft counts. It is
 120        however much slower than other more dedicated programs.
 121
 122 OPTIONS
 123        When PolyGlot is invoked as an adapter of in epd-test mode it gets its
 124        options from a config file and then from the command line.  The default
 125        config file is "polyglot.ini" but an alternative one may be optionally
 126        included as first argument. The config file format is described below.
 127
 128        The following engine options may be specified on the command line.
 129
 130        -noini
 131            Do not use a config file, even if one was specified on the command
 132            line.
 133
 134        -pg The argument is a string of the form <name>=<value>. This option
 135            will set the Polyglot option <name> to <value>.
 136
 137        -uci
 138            The argument is a string of the form <name>=<value>. This option
 139            will set the engine option <name> to <value>.
 140
 141        -ec This sets the EngineCommand.
 142
 143        -ed This sets the EngineDir.
 144
 145        -en This sets the EngineName.
 146
 147        -hash
 148            This is an alias for -uci "Hash=<value>".
 149
 150        -log
 151            This is an alias for -pg "Log=true".
 152
 153        -lf (default: "polyglot.log")
 154            This is an alias for -pg "LogFile=<value>".
 155
 156        -bk This is an alias for -pg "Book=true" -pg "BookFile=<value>".
 157
 158        When invoked as
 159
 160    polyglot make-book
 161        PolyGlot supports the following options
 162
 163        -pgn (default: "book.pgn")
 164            Input file in pgn format.
 165
 166        -bin (default: "book.bin")
 167            Output file in PolyGlot format.
 168
 169        -max-ply (default: 1024)
 170            Specifies the maximum ply-depth of lines included in the book.
 171
 172        -min-game (default: 3)
 173            Specifies the minimum number of games that have to contain this
 174            move for it to be included in the book.
 175
 176        -min-score (default: 0.0)
 177            Specifies the minimum score (or weight) this move should have
 178            received for it to  be included in the book. The score is
 179            2*(wins)+(draws), globally scaled to fit into 16 bits.
 180
 181        -only-white
 182            Include only moves for white in the book.
 183
 184        -only-black
 185            Include only moves for black in the book.
 186
 187        -uniform
 188            Set all weights to 1. In other words, all moves will be selected
 189            with equal probability.
 190
 191        When invoked as
 192
 193    polyglot merge-book
 194        PolyGlot supports the following options
 195
 196        -in1
 197            First input file (in PolyGlot book format).
 198
 199        -in2
 200            Second input file (in PolyGlot book format).
 201
 202        -out (default: out.bin)
 203            Output file (in PolyGlot book format).
 204
 205        Input files are not symmetrical, "in1" has priority over "in2". In
 206        other words when a position occurs both in "in1" and "in2" only the
 207        moves and weights from "in1" will be retained in "out".
 208
 209        When invoked as
 210
 211    polyglot dump-book
 212        PolyGlot supports the following options
 213
 214        -bin (default: book.bin)
 215            Input file in PolyGlot book format.
 216
 217        -color
 218            The color for whom to generate the lines.
 219
 220        -out (default: book_<color>.txt)
 221            The name of the output file.
 222
 223        When invoked as
 224
 225    polyglot info-book
 226        PolyGlot supports the following options
 227
 228        -bin (default: book.bin)
 229            Input file in PolyGlot book format.
 230
 231        -exact
 232            Attempt to count the provably unreachable positions among the
 233            isolated ones.  Note that this takes a very long time.
 234
 235        When invoked as
 236
 237    polyglot epd-test
 238        (possibly with a config file as first argument) PolyGlot supports
 239        besides the generic options described above the following additional
 240        options.
 241
 242        -max-depth (default: 63)
 243            Unconditionally stop the search when this depth has been reached.
 244
 245        -max-time (default: 5.0)
 246            Unconditionally stop the seach after this amount of time.
 247
 248        -depth-delta (default: 3)
 249            Stop the search if the solution as been found and the best move has
 250            been constant for this many depths, on condition that the mininal
 251            depth and minimal time have been reached.
 252
 253        -min-depth (default: 8)
 254            Minimal search depth when the search is stopped using
 255            "-depth-delta".
 256
 257        -min-time (default: 1.0)
 258            Minimal search time when the search is stopped using
 259            "-depth-delta".
 260
 261        When invoked as
 262
 263    polyglot perft
 264        PolyGlot supports the following options
 265
 266        -fen (default: starting position)
 267            Fen at which to start searching.
 268
 269        -max-depth (default: 1)
 270            Maximum depth to search.
 271
 272 CONFIG FILE FORMAT
 273        There should be a different config file for each engine.
 274
 275        The config file is in the traditional INI format.
 276
 277            [PolyGLot]
 278            option = value
 279            ...
 280            [Engine]
 281            option = value
 282            ...
 283
 284        The characters "#" and ";" serve as comment characters.
 285
 286        By default initial and final white space is stripped from option
 287        values. If you want to avoid this, or if you want use one of the
 288        comment characters # or ; in option values (such as for NalimovPath),
 289        enclose the value in quotes.
 290
 291    [PolyGlot] section
 292        This section is used by PolyGlot only.  The engine is unaware of these
 293        options.  The list of available options is detailed below.
 294
 295        EngineName (default: UCI name)
 296            This is the name that will appear in the GUI.  It is cosmetic only.
 297            You can use different names for tweaked versions of the same
 298            engine.
 299
 300        EngineDir (default: ".")
 301            Full path of the directory where the engine is installed.  You can
 302            use "." (without the quotes) if you know that PolyGlot will be
 303            launched in the engine directory or the engine is in the "path" and
 304            does not need any data file.
 305
 306        EngineCommand
 307            Put here the name of the engine executable file.  You can also add
 308            command-line arguments.  Path searching is used and the current
 309            directory will be "EngineDir".
 310
 311        Log (default: false)
 312            Whether PolyGlot should log all transactions with the interface and
 313            the engine.  This should be necessary only to locate problems.
 314
 315        LogFile (default: polyglot.log)
 316            The name of the log file.  Note that it is put where PolyGlot was
 317            launched from, not into the engine directory.
 318
 319            WARNING: Log files are not cleared between sessions, and can become
 320            very large.  It is safe to remove them though.
 321
 322        Resign (default: false)
 323            Set this to "true" if you want PolyGlot to resign on behalf of the
 324            engine.
 325
 326            NOTE: Some engines display buggy scores from time to time although
 327            the best move is correct.  Use this option only if you know what
 328            you are doing (e.g. you always check the final position of games).
 329
 330        ResignMoves (default: 3)
 331            Number of consecutive moves with "resign" score (see below) before
 332            PolyGlot resigns for the engine.  Positions with only one legal
 333            move are ignored.
 334
 335        ResignScore (default: 600)
 336            This is the score in centipawns that will trigger resign
 337            "counting".
 338
 339        ShowPonder (default: true)
 340            Show search information during engine pondering.  Turning this off
 341            might be better for interactive use in some interfaces.
 342
 343        ScoreWhite (default: true)
 344            Report score from white's point of view in xboard mode.
 345
 346        KibitzMove (default: false)
 347            Whether to kibitz when playing a move.
 348
 349        KibitzPV (default: false)
 350            Whether to kibitz when the PV is changed (new iteration or new best
 351            move).
 352
 353        KibitzCommand (default: "tellall")
 354            xboard command to use for kibitzing, normally "tellall" for
 355            kibitzing or "tellothers" for whispering.
 356
 357        KibitzDelay (default: 5)
 358            How many seconds to wait before starting kibitzing.  This has an
 359            effect only if "KibitzPV" is selected, move kibitzes are always
 360            sent regardless of the delay.
 361
 362        KibitzInterval (default: 0)
 363            This is another form of throttling. PolyGlot will usually wait this
 364            many seconds before doing the next kibitz.
 365
 366        UCI (default: false)
 367            If true PolyGlot will not understand xboard commands.
 368
 369        MateScore (default: 10000)
 370            Mate score reported to GUI when in xboard mode.
 371
 372        Book (default: false)
 373            Indicates whether a PolyGlot book should be used.  This has no
 374            effect on the engine own book (which can be controlled with the UCI
 375            option "OwnBook" in the [Engine] section).  In particular, it is
 376            possible to use both a PolyGlot book and an engine book.  In that
 377            case, the engine book will be used whenever PolyGlot is out of
 378            book.  Remember that PolyGlot is unaware of whether the engine is
 379            itself using a book or not.
 380
 381        BookFile (default: book.bin)
 382            The name of the (binary) book file.  Note that PolyGlot will look
 383            for it in the directory it was launched from, not in the engine
 384            directory.  Of course, full path can be used in which case the
 385            current directory does not matter.
 386
 387        BookRandom (default: true)
 388            Select moves according to their weights in the book. If false the
 389            move with the highest weight is selected.
 390
 391        BookLearn (default: false)
 392            Store learning information in the book (which must be writable).
 393            Currently no engine actually uses this information.
 394
 395        BookDepth (default: 256)
 396            Stop using the book after this number of moves.
 397
 398        BookTreshold (default: 5)
 399            Do not play moves with a weight (probability) lower than this (in
 400            per mil).
 401
 402        UseNice (default: false)
 403            Run the engine at nice level 5, or "NiceValue" if it set.  On some
 404            operating systems it may be necessary to run the engine at lower
 405            priority for it to be responsive to commands from PolyGlot while
 406            searching.
 407
 408        NiceValue (default: 5)
 409            Nice levels go from -20 to 20 with 20 being the lowest priority.
 410            On Unix only root can set negative nice levels. On Windows the
 411            standard Win32 priority levels are mapped in a sensible way to Unix
 412            nice levels.
 413
 414        Affinity (default: -1)
 415            This a bit vector in which each bit represents the processors that
 416            a process is allowed to run on. This option works only on Windows.
 417
 418        Persist (default: true)
 419            If true then PolyGlot will implement persistence by loading options
 420            from an additional INI file whose name is by default derived from
 421            the engine name. At exit PolyGlot will also save its options to
 422            this INI file.
 423
 424        PersistFile (default: <EngineName>.ini)
 425            The name of the file from which to take the additional options.  It
 426            is probably best to stick with the default. You can safely edit
 427            this file, or delete it to restore the default options.
 428
 429        PersistDir (default: $HOME/.polyglot on Linux; ".\Polyglot Settings" on
 430        Windows)
 431            The directory where the PersistFile is stored.
 432
 433    Work arounds
 434        Work arounds are identical to options except that they should be used
 435        only when necessary.  Their purpose is to try to hide problems with
 436        various software (not just engines).
 437
 438        IMPORTANT: Any of these work arounds might be removed in future
 439        versions of PolyGlot.  You are strongly recommended to contact the
 440        author of faulty software and truly fix the problem.
 441
 442        PolyGlot supports the following work arounds:
 443
 444        UCIVersion (default: 2)
 445            The default value of 2 corresponds to UCI+.  Use 1 to select plain
 446            UCI for engines that have problems with UCI+.
 447
 448        CanPonder (default: false)
 449            PolyGlot now conforms to the documented UCI behaviour: the engine
 450            will be allowed to ponder only if it (the engine) declares the
 451            "Ponder" UCI option.  However some engines which can actually
 452            ponder do not declare the option.  This work around lets PolyGlot
 453            know that they can ponder.
 454
 455        SyncStop (default: false)
 456            When a ponder miss occurs, Polyglot interrupts the engine and
 457            IMMEDIATELY launches a new search.  While there should be no
 458            problem with this, some engines seem confused and corrupt their
 459            search board.  "SyncStop" forces PolyGlot to wait for the (now
 460            useless) ponder search to finish before launching the new search.
 461
 462        PromoteWorkAround (default: false)
 463            Some engines do not specify a promotion piece, e.g. they send
 464            "e7e8" instead of the correct "e7e8q".  This work around enables
 465            the incorrect form (and of course promotes into a queen).
 466
 467        RepeatPV (default: true)
 468            When true, PolyGlot repeats the last pv string (which also contains
 469            score,depth and time usage) it got from the engine. Some engines
 470            however do not send a new pv string just before sending the move.
 471            In that case the output of PolyGlot would be inconsistent.  When
 472            RepeatPV is false PolyGlot does not repeat the last pv string.  Due
 473            to the way kibitzing is implemented, KibitzMove is disabled in that
 474            case.
 475
 476        WbWorkArounds (default: true)
 477            The intention of these options is to provide work arounds for
 478            xboard/winboard bugs should they arise.  This one decapitalizes the
 479            word Draw in options that contain this word. Some versions of
 480            xboard/winboard contain a bug which causes such options to be
 481            interpreted as draw claims by the engine.
 482
 483            Engines that send options with "Draw" in their name are Rybka and
 484            HIARCS.
 485
 486        WbWorkArounds2 (default: false)
 487            Old version of Winboard clear the engine output window at depth 1.
 488            With this work around PG will send info lines at depth >=2. This
 489            may or may not improve the display.
 490
 491    [Engine] section
 492        This section contains engine UCI options.  PolyGlot does not understand
 493        them, but sends the information to the engine at startup (converted to
 494        UCI form).  You can add any UCI option that makes sense to the engine
 495        (not just the common options about hash-table size and tablebases).
 496
 497        NOTE: use INI syntax, not UCI.  For example "OwnBook = true" is
 498        correct.  It will be replaced by PolyGlot with "setoption name OwnBook
 499        value true" at engine startup.
 500
 501        Standard UCI options are
 502
 503            Hash
 504            NalimovPath
 505            NalimovCache
 506            OwnBook
 507
 508        Hidden options like "Ponder" or "UCI_xxx" are automatic and should not
 509        be put in an INI file.
 510
 511        The other options are engine-specific.  Check their name using a UCI
 512        GUI or launch the engine in a console and type "uci".
 513
 514 EXAMPLES
 515        Running the UCI engine "fruit" under xboard 4.3.15 and later (this
 516        invokes PolyGlot internally).
 517
 518            xboard -fcp fruit -fUCI
 519
 520        An explicit command line for using the UCI engine "fruit" with 128M
 521        hash in xboard with logging enabled (this also works on xboard 4.2.7).
 522
 523            xboard -fcp "polyglot -noini -log -ec fruit -hash 128"
 524
 525        The equivalent config file would be:
 526
 527            [PolyGlot]
 528            EngineCommand = fruit
 529            Log = true
 530            [Engine]
 531            Hash=128
 532
 533        Compile "games.pgn" into a book "book.bin" retaining all lines of at
 534        most 30 plies.
 535
 536            polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
 537
 538        Merge books "w1.bin" and "w2.bin" into a book "w.bin".
 539
 540            polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
 541
 542        Inspect lines for white in "w.bin"
 543
 544            polyglot dump-book -bin w.bin -color white -out w_white.txt
 545
 546        Test epd file "test.epd" with a (maximum) search time of 7 minutes per
 547        position
 548
 549            polyglot epd-test -epd test.epd -max-time 420
 550
 551 EXIT STATUS
 552        PolyGlot always returns 0 on exit.
 553
 554 AUTHORS
 555        Main author: Fabien Letouzey<fabien_letouzey(at)hotmail.com>
 556
 557        Native Windows port:  Huang Chen<webmaster@elephantbase.net> ("Morning
 558        Yellow")
 559
 560        Various enhancements: Fonzy Bleumers<match(at)geenvis.net>
 561
 562        UCI port, option persistence and new WB protocol: Michel Van den Bergh
 563        <michel.vandenbergh(at)uhasselt.be>
 564
 565 SEE ALSO
 566        xboard(6)
 567
 568
 569
 570                                   2009-09-05                       POLYGLOT(6)