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 true/false] [-lf logfile] [-pg <name>=<value>]* [-uci
  16        <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://hgm.nubati.net/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 is an alias for -pg "EngineCommand=<value>"
 142
 143        -ed This is an alias for -pg "EngineDir=<value>"
 144
 145        -en This is an alias for -pg "EngineName=<value>"
 146
 147        -log (default: false)
 148            This is an alias for -pg "Log=<value>"
 149
 150        -lf (default: "polyglot.log")
 151            This is an alias for -pg "LogFile=<value>".
 152
 153        -wb (default: "true")
 154            This is an alias for -pg "OnlyWbOptions=<value>".
 155
 156        When invoked as
 157
 158    polyglot make-book
 159        PolyGlot supports the following options
 160
 161        -pgn (default: "book.pgn")
 162            Input file in pgn format.
 163
 164        -bin (default: "book.bin")
 165            Output file in PolyGlot format.
 166
 167        -max-ply (default: 1024)
 168            Specifies the maximum ply-depth of lines included in the book.
 169
 170        -min-game (default: 3)
 171            Specifies the minimum number of games that have to contain this
 172            move for it to be included in the book.
 173
 174        -min-score (default: 0.0)
 175            Specifies the minimum score (or weight) this move should have
 176            received for it to  be included in the book. The score is
 177            2*(wins)+(draws), globally scaled to fit into 16 bits.
 178
 179        -only-white
 180            Include only moves for white in the book.
 181
 182        -only-black
 183            Include only moves for black in the book.
 184
 185        -uniform
 186            Set all weights to 1. In other words, all moves will be selected
 187            with equal probability.
 188
 189        When invoked as
 190
 191    polyglot merge-book
 192        PolyGlot supports the following options
 193
 194        -in1
 195            First input file (in PolyGlot book format).
 196
 197        -in2
 198            Second input file (in PolyGlot book format).
 199
 200        -out (default: out.bin)
 201            Output file (in PolyGlot book format).
 202
 203        Input files are not symmetrical, "in1" has priority over "in2". In
 204        other words when a position occurs both in "in1" and "in2" only the
 205        moves and weights from "in1" will be retained in "out".
 206
 207        When invoked as
 208
 209    polyglot dump-book
 210        PolyGlot supports the following options
 211
 212        -bin (default: book.bin)
 213            Input file in PolyGlot book format.
 214
 215        -color
 216            The color for whom to generate the lines.
 217
 218        -out (default: book_<color>.txt)
 219            The name of the output file.
 220
 221        When invoked as
 222
 223    polyglot info-book
 224        PolyGlot supports the following options
 225
 226        -bin (default: book.bin)
 227            Input file in PolyGlot book format.
 228
 229        -exact
 230            Attempt to count the provably unreachable positions among the
 231            isolated ones.  Note that this takes a very long time.
 232
 233        When invoked as
 234
 235    polyglot epd-test
 236        (possibly with a config file as first argument) PolyGlot supports
 237        besides the generic options described above the following additional
 238        options.
 239
 240        -max-depth (default: 63)
 241            Unconditionally stop the search when this depth has been reached.
 242
 243        -max-time (default: 5.0)
 244            Unconditionally stop the seach after this amount of time.
 245
 246        -depth-delta (default: 3)
 247            Stop the search if the solution as been found and the best move has
 248            been constant for this many depths, on condition that the mininal
 249            depth and minimal time have been reached.
 250
 251        -min-depth (default: 8)
 252            Minimal search depth when the search is stopped using
 253            "-depth-delta".
 254
 255        -min-time (default: 1.0)
 256            Minimal search time when the search is stopped using
 257            "-depth-delta".
 258
 259        When invoked as
 260
 261    polyglot perft
 262        PolyGlot supports the following options
 263
 264        -fen (default: starting position)
 265            Fen at which to start searching.
 266
 267        -max-depth (default: 1)
 268            Maximum depth to search.
 269
 270 CONFIG FILE FORMAT
 271        There should be a different config file for each engine.
 272
 273        The config file is in the traditional INI format.
 274
 275            [PolyGLot]
 276            option = value
 277            ...
 278            [Engine]
 279            option = value
 280            ...
 281
 282        The characters "#" and ";" serve as comment characters.
 283
 284        Initial and final white space is stripped from option names and values.
 285        If you need to use characters which have a special meaning to PolyGlot
 286        (these are ';#[]=\') you should quote them by preceding them with '\'.
 287        "Quoting" other characters in this way has no effect. In particular the
 288        use of '\' as a path separator in windows should normally not affected.
 289
 290    [PolyGlot] section
 291        This section is used by PolyGlot only.  The engine is unaware of these
 292        options.  The list of available options is detailed below.
 293
 294        EngineName (default: UCI name)
 295            This is the name that will appear in the GUI.  It is cosmetic only.
 296            You can use different names for tweaked versions of the same
 297            engine.
 298
 299        EngineDir (default: ".")
 300            Full path of the directory where the engine is installed.  You can
 301            use "." (without the quotes) if you know that PolyGlot will be
 302            launched in the engine directory or the engine is in the "path" and
 303            does not need any data file.
 304
 305        EngineCommand
 306            Put here the name of the engine executable file.  You can also add
 307            command-line arguments.  Path searching is used and the current
 308            directory will be "EngineDir". On Linux the EngineCommand is passed
 309            to wordexp so that shell quoting rules and expansions are applied.
 310            On Windows the EngineCommand is simply passed to CreateProcess
 311            which does its own shell like processing.
 312
 313        SettingsDir (default: $HOME/.polyglot on Linux; ".\_PG" on Windows)
 314            The directory where ini files are stored for engines that are
 315            started with -noini. Such ini files may be created by pushing the
 316            "Save" button in the Engine settings dialog in WB/XB 4.4.0 and
 317            higher. As a special exception (for WB/XB 4.4.0 compatibility) this
 318            directory is also used in case PolyGlot is started with config
 319            files named "polyglot_1st.ini" or "polyglot_2nd.ini".
 320
 321        Log (default: false)
 322            Whether PolyGlot should log all transactions with the interface and
 323            the engine.  This should be necessary only to locate problems.
 324
 325        LogFile (default: polyglot.log)
 326            The name of the log file.  Note that it is put where PolyGlot was
 327            launched from, not into the engine directory.
 328
 329            WARNING: Log files are not cleared between sessions, and can become
 330            very large.  It is safe to remove them though.
 331
 332        Resign (default: false)
 333            Set this to "true" if you want PolyGlot to resign on behalf of the
 334            engine.
 335
 336            NOTE: Some engines display buggy scores from time to time although
 337            the best move is correct.  Use this option only if you know what
 338            you are doing (e.g. you always check the final position of games).
 339
 340        ResignMoves (default: 3)
 341            Number of consecutive moves with "resign" score (see below) before
 342            PolyGlot resigns for the engine.  Positions with only one legal
 343            move are ignored.
 344
 345        ResignScore (default: 600)
 346            This is the score in centipawns that will trigger resign
 347            "counting".
 348
 349        QueenNeverResigns (default: true)
 350            Suppresses resigning irrespective of the score, as long as the
 351            engine still has a Queen (hoping for a perpetual).
 352
 353        HandleDraws (default: false)
 354            When set Polyglot can accept draw offers on behalf of the engine,
 355            when the last reported engine score is below Polyglot's contempt.
 356
 357        ContemptScore (default: 30)
 358            This is the score in centipawns that the engine must minimally see
 359            in its own disadvantage before Polyglot will accept a draw offer.
 360
 361        ShowPonder (default: true)
 362            Show search information during engine pondering.  Turning this off
 363            might be better for interactive use in some interfaces.
 364
 365        ShowTbHits (default: false)
 366            Reports extra info on selective depth, search speed (knps) and
 367            tablebase hits at the beginning of the PV field in the thinking
 368            output of WinBoard protocol, just before the real PV.
 369
 370        ScoreWhite (default: true)
 371            Report score from white's point of view in xboard mode. (Wrecks
 372            XBoard...).
 373
 374        KibitzMove (default: false)
 375            Whether to kibitz when playing a move.
 376
 377        KibitzPV (default: false)
 378            Whether to kibitz when the PV is changed (new iteration or new best
 379            move).
 380
 381        KibitzCommand (default: "tellall")
 382            xboard command to use for kibitzing, normally "tellall" for
 383            kibitzing or "tellothers" for whispering.
 384
 385        KibitzDelay (default: 5)
 386            How many seconds to wait before starting kibitzing.  This has an
 387            effect only if "KibitzPV" is selected, move kibitzes are always
 388            sent regardless of the delay.
 389
 390        KibitzInterval (default: 0)
 391            This is another form of throttling. PolyGlot will usually wait this
 392            many seconds before doing the next kibitz.
 393
 394        UCI (default: false)
 395            If true PolyGlot will not understand xboard commands.
 396
 397        MateScore (default: 10000)
 398            Mate score reported to GUI when in xboard mode.
 399
 400        Book (default: false)
 401            Indicates whether a PolyGlot book should be used.  This has no
 402            effect on the engine own book (which can be controlled with the UCI
 403            option "OwnBook" in the [Engine] section).  In particular, it is
 404            possible to use both a PolyGlot book and an engine book.  In that
 405            case, the engine book will be used whenever PolyGlot is out of
 406            book.  Remember that PolyGlot is unaware of whether the engine is
 407            itself using a book or not.
 408
 409        BookFile (default: book.bin)
 410            The name of the (binary) book file.  Note that PolyGlot will look
 411            for it in the directory it was launched from, not in the engine
 412            directory.  Of course, full path can be used in which case the
 413            current directory does not matter.
 414
 415        BookRandom (default: true)
 416            Select moves according to their weights in the book. If false the
 417            move with the highest weight is selected.
 418
 419        BookLearn (default: false)
 420            Switches on updating of the 'learn fields' of the opening book,
 421            which for each move record the number of times the move was played,
 422            and the number of half-points scored with it.  It also switches on
 423            making use of this information already in the book, for altering
 424            the move-selection probabilities from those specified by the book
 425            weights.  (Rarely played moves will be favored, moves with a
 426            significant poor performance will be shunned.)  This option must be
 427            set before the book is specified, or the updating of the learn info
 428            will not work!
 429
 430        BookDepth (default: 256)
 431            Stop using the book after this number of moves.
 432
 433        BookTreshold (default: 5)
 434            Do not play moves with a weight (probability) lower than this (in
 435            per mil).
 436
 437        UseNice (default: false)
 438            Run the engine at nice level 5, or "NiceValue" if it set.  On some
 439            operating systems it may be necessary to run the engine at lower
 440            priority for it to be responsive to commands from PolyGlot while
 441            searching.
 442
 443        NiceValue (default: 5)
 444            Nice levels go from -20 to 20 with 20 being the lowest priority.
 445            On Unix only root can set negative nice levels. On Windows the
 446            standard Win32 priority levels are mapped in a sensible way to Unix
 447            nice levels.
 448
 449        Affinity (default: -1)
 450            This a bit vector in which each bit represents the processors that
 451            a process is allowed to run on. This option works only on Windows.
 452
 453        STFudge (default: 20)
 454            PolyGlot will translate "st x" as "go movetime 1000*x-STFudge".
 455            The rationale is that in the UCI specification the argument of
 456            movetime is defined as the exact search time whereas the argument
 457            of the st command is only an upperbound.
 458
 459        OnlyWbOptions (default: true)
 460            If true then PolyGlot restricts the options it sends to those that
 461            are potentially useful for WinBoard.
 462
 463    Work arounds
 464        Work arounds are identical to options except that they should be used
 465        only when necessary.  Their purpose is to try to hide problems with
 466        various software (not just engines).
 467
 468        IMPORTANT: Any of these work arounds might be removed in future
 469        versions of PolyGlot.  You are strongly recommended to contact the
 470        author of faulty software and truly fix the problem.
 471
 472        PolyGlot supports the following work arounds:
 473
 474        UCIVersion (default: 2)
 475            The default value of 2 corresponds to UCI+.  Use 1 to select plain
 476            UCI for engines that have problems with UCI+.
 477
 478        CanPonder (default: false)
 479            PolyGlot now conforms to the documented UCI behaviour: the engine
 480            will be allowed to ponder only if it (the engine) declares the
 481            "Ponder" UCI option.  However some engines which can actually
 482            ponder do not declare the option.  This work around lets PolyGlot
 483            know that they can ponder.
 484
 485        SyncStop (default: false)
 486            When a ponder miss occurs, Polyglot interrupts the engine and
 487            IMMEDIATELY launches a new search.  While there should be no
 488            problem with this, some engines seem confused and corrupt their
 489            search board.  "SyncStop" forces PolyGlot to wait for the (now
 490            useless) ponder search to finish before launching the new search.
 491
 492        PromoteWorkAround (default: false)
 493            Some engines do not specify a promotion piece, e.g. they send
 494            "e7e8" instead of the correct "e7e8q".  This work around enables
 495            the incorrect form (and of course promotes into a queen).
 496
 497        RepeatPV (default: true)
 498            When true, PolyGlot repeats the last pv string (which also contains
 499            score,depth and time usage) it got from the engine. Some engines
 500            however do not send a new pv string just before sending the move.
 501            In that case the output of PolyGlot would be inconsistent.  When
 502            RepeatPV is false PolyGlot does not repeat the last pv string.  Due
 503            to the way kibitzing is implemented, KibitzMove is disabled in that
 504            case.
 505
 506    [Engine] section
 507        This section contains engine UCI options.  PolyGlot does not understand
 508        them, but sends the information to the engine at startup (converted to
 509        UCI form).  You can add any UCI option that makes sense to the engine
 510        (not just the common options about hash-table size and tablebases).
 511
 512        NOTE: use INI syntax, not UCI.  For example "OwnBook = true" is
 513        correct.  It will be replaced by PolyGlot with "setoption name OwnBook
 514        value true" at engine startup.
 515
 516        Standard UCI options are
 517
 518            Hash
 519            NalimovPath
 520            NalimovCache
 521            GaviotaPath
 522            GaviotaCache
 523            SyzygyPath
 524            OwnBook
 525
 526        Hidden options like "Ponder" or "UCI_xxx" are automatic and should not
 527        be put in an INI file.
 528
 529        The other options are engine-specific.  Check their name using a UCI
 530        GUI or launch the engine in a console and type "uci".
 531
 532 EXAMPLES
 533        Running the UCI engine "fruit" under xboard 4.3.15 and later (this
 534        invokes PolyGlot internally).
 535
 536            xboard -fcp fruit -fUCI
 537
 538        An explicit command line for using the UCI engine "fruit" with logging
 539        enabled (this works also with older versions of xboard).
 540
 541            xboard -fcp "polyglot -noini -log true -ec fruit"
 542
 543        The equivalent config file would be:
 544
 545            [PolyGlot]
 546            EngineCommand = fruit
 547            Log = true
 548            [Engine]
 549
 550        Compile "games.pgn" into a book "book.bin" retaining all lines of at
 551        most 30 plies.
 552
 553            polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
 554
 555        Merge books "w1.bin" and "w2.bin" into a book "w.bin".
 556
 557            polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
 558
 559        Inspect lines for white in "w.bin"
 560
 561            polyglot dump-book -bin w.bin -color white -out w_white.txt
 562
 563        Test epd file "test.epd" with a (maximum) search time of 7 minutes per
 564        position
 565
 566            polyglot epd-test -epd test.epd -max-time 420
 567
 568 EXIT STATUS
 569        PolyGlot always returns 0 on exit.
 570
 571 AUTHORS
 572        Main author: Fabien Letouzey<fabien_letouzey(at)hotmail.com>
 573
 574        Native Windows port:  Huang Chen<webmaster@elephantbase.net> ("Morning
 575        Yellow")
 576
 577        Various enhancements: Fonzy Bleumers<match(at)geenvis.net>
 578
 579        UCI port and implementation of new WB protocol: Michel Van den Bergh
 580        <michel.vandenbergh(at)uhasselt.be>
 581
 582 SEE ALSO
 583        xboard(6)
 584
 585
 586
 587                                   2014-09-08                       POLYGLOT(6)