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