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://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 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        ShowPonder (default: true)
 350            Show search information during engine pondering.  Turning this off
 351            might be better for interactive use in some interfaces.
 352
 353        ScoreWhite (default: true)
 354            Report score from white's point of view in xboard mode.
 355
 356        KibitzMove (default: false)
 357            Whether to kibitz when playing a move.
 358
 359        KibitzPV (default: false)
 360            Whether to kibitz when the PV is changed (new iteration or new best
 361            move).
 362
 363        KibitzCommand (default: "tellall")
 364            xboard command to use for kibitzing, normally "tellall" for
 365            kibitzing or "tellothers" for whispering.
 366
 367        KibitzDelay (default: 5)
 368            How many seconds to wait before starting kibitzing.  This has an
 369            effect only if "KibitzPV" is selected, move kibitzes are always
 370            sent regardless of the delay.
 371
 372        KibitzInterval (default: 0)
 373            This is another form of throttling. PolyGlot will usually wait this
 374            many seconds before doing the next kibitz.
 375
 376        UCI (default: false)
 377            If true PolyGlot will not understand xboard commands.
 378
 379        MateScore (default: 10000)
 380            Mate score reported to GUI when in xboard mode.
 381
 382        Book (default: false)
 383            Indicates whether a PolyGlot book should be used.  This has no
 384            effect on the engine own book (which can be controlled with the UCI
 385            option "OwnBook" in the [Engine] section).  In particular, it is
 386            possible to use both a PolyGlot book and an engine book.  In that
 387            case, the engine book will be used whenever PolyGlot is out of
 388            book.  Remember that PolyGlot is unaware of whether the engine is
 389            itself using a book or not.
 390
 391        BookFile (default: book.bin)
 392            The name of the (binary) book file.  Note that PolyGlot will look
 393            for it in the directory it was launched from, not in the engine
 394            directory.  Of course, full path can be used in which case the
 395            current directory does not matter.
 396
 397        BookRandom (default: true)
 398            Select moves according to their weights in the book. If false the
 399            move with the highest weight is selected.
 400
 401        BookLearn (default: false)
 402            This is a noop.
 403
 404        BookDepth (default: 256)
 405            Stop using the book after this number of moves.
 406
 407        BookTreshold (default: 5)
 408            Do not play moves with a weight (probability) lower than this (in
 409            per mil).
 410
 411        UseNice (default: false)
 412            Run the engine at nice level 5, or "NiceValue" if it set.  On some
 413            operating systems it may be necessary to run the engine at lower
 414            priority for it to be responsive to commands from PolyGlot while
 415            searching.
 416
 417        NiceValue (default: 5)
 418            Nice levels go from -20 to 20 with 20 being the lowest priority.
 419            On Unix only root can set negative nice levels. On Windows the
 420            standard Win32 priority levels are mapped in a sensible way to Unix
 421            nice levels.
 422
 423        Affinity (default: -1)
 424            This a bit vector in which each bit represents the processors that
 425            a process is allowed to run on. This option works only on Windows.
 426
 427        STFudge (default: 20)
 428            PolyGlot will translate "st x" as "go movetime 1000*x-STFudge".
 429            The rationale is that in the UCI specification the argument of
 430            movetime is defined as the exact search time whereas the argument
 431            of the st command is only an upperbound.
 432
 433        OnlyWbOptions (default: true)
 434            If true then PolyGlot restricts the options it sends to those that
 435            are potentially useful for WinBoard.
 436
 437    Work arounds
 438        Work arounds are identical to options except that they should be used
 439        only when necessary.  Their purpose is to try to hide problems with
 440        various software (not just engines).
 441
 442        IMPORTANT: Any of these work arounds might be removed in future
 443        versions of PolyGlot.  You are strongly recommended to contact the
 444        author of faulty software and truly fix the problem.
 445
 446        PolyGlot supports the following work arounds:
 447
 448        UCIVersion (default: 2)
 449            The default value of 2 corresponds to UCI+.  Use 1 to select plain
 450            UCI for engines that have problems with UCI+.
 451
 452        CanPonder (default: false)
 453            PolyGlot now conforms to the documented UCI behaviour: the engine
 454            will be allowed to ponder only if it (the engine) declares the
 455            "Ponder" UCI option.  However some engines which can actually
 456            ponder do not declare the option.  This work around lets PolyGlot
 457            know that they can ponder.
 458
 459        SyncStop (default: false)
 460            When a ponder miss occurs, Polyglot interrupts the engine and
 461            IMMEDIATELY launches a new search.  While there should be no
 462            problem with this, some engines seem confused and corrupt their
 463            search board.  "SyncStop" forces PolyGlot to wait for the (now
 464            useless) ponder search to finish before launching the new search.
 465
 466        PromoteWorkAround (default: false)
 467            Some engines do not specify a promotion piece, e.g. they send
 468            "e7e8" instead of the correct "e7e8q".  This work around enables
 469            the incorrect form (and of course promotes into a queen).
 470
 471        RepeatPV (default: true)
 472            When true, PolyGlot repeats the last pv string (which also contains
 473            score,depth and time usage) it got from the engine. Some engines
 474            however do not send a new pv string just before sending the move.
 475            In that case the output of PolyGlot would be inconsistent.  When
 476            RepeatPV is false PolyGlot does not repeat the last pv string.  Due
 477            to the way kibitzing is implemented, KibitzMove is disabled in that
 478            case.
 479
 480    [Engine] section
 481        This section contains engine UCI options.  PolyGlot does not understand
 482        them, but sends the information to the engine at startup (converted to
 483        UCI form).  You can add any UCI option that makes sense to the engine
 484        (not just the common options about hash-table size and tablebases).
 485
 486        NOTE: use INI syntax, not UCI.  For example "OwnBook = true" is
 487        correct.  It will be replaced by PolyGlot with "setoption name OwnBook
 488        value true" at engine startup.
 489
 490        Standard UCI options are
 491
 492            Hash
 493            NalimovPath
 494            NalimovCache
 495            OwnBook
 496
 497        Hidden options like "Ponder" or "UCI_xxx" are automatic and should not
 498        be put in an INI file.
 499
 500        The other options are engine-specific.  Check their name using a UCI
 501        GUI or launch the engine in a console and type "uci".
 502
 503 EXAMPLES
 504        Running the UCI engine "fruit" under xboard 4.3.15 and later (this
 505        invokes PolyGlot internally).
 506
 507            xboard -fcp fruit -fUCI
 508
 509        An explicit command line for using the UCI engine "fruit" with logging
 510        enabled (this works also with older versions of xboard).
 511
 512            xboard -fcp "polyglot -noini -log true -ec fruit"
 513
 514        The equivalent config file would be:
 515
 516            [PolyGlot]
 517            EngineCommand = fruit
 518            Log = true
 519            [Engine]
 520
 521        Compile "games.pgn" into a book "book.bin" retaining all lines of at
 522        most 30 plies.
 523
 524            polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
 525
 526        Merge books "w1.bin" and "w2.bin" into a book "w.bin".
 527
 528            polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
 529
 530        Inspect lines for white in "w.bin"
 531
 532            polyglot dump-book -bin w.bin -color white -out w_white.txt
 533
 534        Test epd file "test.epd" with a (maximum) search time of 7 minutes per
 535        position
 536
 537            polyglot epd-test -epd test.epd -max-time 420
 538
 539 EXIT STATUS
 540        PolyGlot always returns 0 on exit.
 541
 542 AUTHORS
 543        Main author: Fabien Letouzey<fabien_letouzey(at)hotmail.com>
 544
 545        Native Windows port:  Huang Chen<webmaster@elephantbase.net> ("Morning
 546        Yellow")
 547
 548        Various enhancements: Fonzy Bleumers<match(at)geenvis.net>
 549
 550        UCI port and implementation of new WB protocol: Michel Van den Bergh
 551        <michel.vandenbergh(at)uhasselt.be>
 552
 553 SEE ALSO
 554        xboard(6)
 555
 556
 557
 558                                   2012-09-17                       POLYGLOT(6)