X-Git-Url: http://winboard.nl/cgi-bin?a=blobdiff_plain;f=README;h=339c1f49f6ee27f74ed2a656b4f725558600d48b;hb=037f73ac400afcd812f31f9260e6bf8a0ba7ef53;hp=ac68f6658292fd3748a855fb5eff45f89a35ab4c;hpb=5eed4adb3552562329c0b0b460c8851efb1a38bb;p=polyglot.git diff --git a/README b/README index ac68f66..339c1f4 100644 --- a/README +++ b/README @@ -5,19 +5,19 @@ POLYGLOT(6) POLYGLOT(6) NAME PolyGlot - Winboard protocol to UCI protocol adapter - book engine for Polyglot books - - a collection of utilities for creating and analyzing open- - ing books + - a collection of utilities for creating and analyzing + opening books - a utility for analyzing epd files - a perft counter SYNOPSIS polyglot [configfile] [-noini] [-ec engine] [-ed enginedirectory] [-en - enginename] [-log] [-lf logfile] [-hash value] [-bk book] [-pg - =]* [-uci =]* + enginename] [-log true/false] [-lf logfile] [-pg =]* [-uci + =]* polyglot make-book [-pgn inputfile] [-bin outputfile] [-max-ply ply] - [-min-game games] [-min-score score] [-only-white] [-only-black] [-uni- - form] + [-min-game games] [-min-score score] [-only-white] [-only-black] + [-uniform] polyglot merge-book -in1 inputfile1 -in2 inputfile2 [-out outputfile] @@ -40,9 +40,9 @@ DESCRIPTION By specifying an opening book (in PolyGlot book format) chess engines can transparently use such books. - PolyGlot understands the two main GUI protocols: UCI and xboard. Nor- - mally the protocol will be auto detected but this can be overridden in - the configuration file. + PolyGlot understands the two main GUI protocols: UCI and xboard. + Normally the protocol will be auto detected but this can be overridden + in the configuration file. In xboard mode PolyGlot fully translates between the xboard and UCI protocols. In addition it tries to solve known problems with other @@ -53,9 +53,9 @@ DESCRIPTION engine and vice versa, except that it will play book moves on behalf of the engine when the occasion arises. - The engine options are exported as UCI options in UCI mode and as "fea- - ture option=" commands in xboard mode. The latter form an extension of - the xboard protocol as defined by H.G. Muller. + The engine options are exported as UCI options in UCI mode and as + "feature option=" commands in xboard mode. The latter form an extension + of the xboard protocol as defined by H.G. Muller. Options which normally appear in the [PolyGlot] section of the config file (see below) are exported as options with their name prefixed by @@ -67,8 +67,8 @@ DESCRIPTION Book making utilities PolyGlot supports the "PolyGlot opening book format". This is the - defacto standard non-proprietary opening book format. It is fully docu- - mented here + defacto standard non-proprietary opening book format. It is fully + documented here http://alpha.uhasselt.be/Research/Algebra/Toga/book_format.html @@ -81,13 +81,13 @@ DESCRIPTION .abk format are undocumented and proprietary. They can only be used by their own GUIs. - PolyGlot can compile a pgn file into a binary PolyGlot book and fur- - thermore it can merge two such binary books into a third one. + PolyGlot can compile a pgn file into a binary PolyGlot book and + furthermore it can merge two such binary books into a third one. PolyGlot can also extract some useful information from PolyGlot books. The utility "dump-book" dumps the "lines" in a book for a given color. - By definition a line is a sequence of moves (from the starting posi- - tion) in which the given color makes only book moves and the other + By definition a line is a sequence of moves (from the starting + position) in which the given color makes only book moves and the other color makes arbitrary moves (i.e. not necessarily book moves). Since a PolyGlot book is built up from positions and not lines there @@ -114,14 +114,14 @@ DESCRIPTION Epd test mode In epd test mode, PolyGlot will search positions in an epd file and - record the number of times the right best move was found. The argu- - ments specify when to stop the search in any given position. + record the number of times the right best move was found. The + arguments specify when to stop the search in any given position. Perft counts A perft count is the number of legal move sequence in a given position - up to a given depth. PolyGlot can perform such perft counts. It is how- - ever much slower than other more dedicated programs. + up to a given depth. PolyGlot can perform such perft counts. It is + however much slower than other more dedicated programs. OPTIONS When PolyGlot is invoked as an adapter of in epd-test mode it gets its @@ -142,22 +142,20 @@ OPTIONS The argument is a string of the form =. This option will set the engine option to . - -ec This is an alias for -pg "EngineCommand=". + -ec This is an alias for -pg "EngineCommand=" - -ed This is an alias for -pg "EngineDir=". + -ed This is an alias for -pg "EngineDir=" -en This is an alias for -pg "EngineName=" - -hash - This is an alias for -uci "Hash=". - - -log - This is an alias for -pg "Log=true". + -log (default: false) + This is an alias for -pg "Log=" -lf (default: "polyglot.log") This is an alias for -pg "LogFile=". - -bk This is an alias for -pg "Book=true" -pg "BookFile=". + -wb (default: "true") + This is an alias for -pg "OnlyWbOptions=". When invoked as @@ -237,8 +235,8 @@ OPTIONS Input file in PolyGlot book format. -exact - Attempt to count the provably unreachable positions among the iso- - lated ones. Note that this takes a very long time. + Attempt to count the provably unreachable positions among the + isolated ones. Note that this takes a very long time. When invoked as @@ -293,10 +291,11 @@ CONFIG FILE FORMAT The characters "#" and ";" serve as comment characters. - By default initial and final white space is stripped from option val- - ues. If you want to avoid this, or if you want use one of the comment - characters # or ; in option values (such as for NalimovPath), enclose - the value in quotes. + Initial and final white space is stripped from option names and values. + If you need to use characters which have a special meaning to PolyGlot + (these are ';#[]=\') you should quote them by preceding them with '\'. + "Quoting" other characters in this way has no effect. In particular the + use of '\' as a path separator in windows should normally not affected. [PolyGlot] section @@ -317,7 +316,18 @@ CONFIG FILE FORMAT EngineCommand Put here the name of the engine executable file. You can also add command-line arguments. Path searching is used and the current - directory will be "EngineDir". + directory will be "EngineDir". On Linux the EngineCommand is passed + to wordexp so that shell quoting rules and expansions are applied. + On Windows the EngineCommand is simply passed to CreateProcess + which does its own shell like processing. + + SettingsDir (default: $HOME/.polyglot on Linux; ".\_PG" on Windows) + The directory where ini files are stored for engines that are + started with -noini. Such ini files may be created by pushing the + "Save" button in the Engine settings dialog in WB/XB 4.4.0 and + higher. As a special exception (for WB/XB 4.4.0 compatibility) this + directory is also used in case PolyGlot is started with config + files named "polyglot_1st.ini" or "polyglot_2nd.ini". Log (default: false) Whether PolyGlot should log all transactions with the interface and @@ -344,8 +354,8 @@ CONFIG FILE FORMAT move are ignored. ResignScore (default: 600) - This is the score in centipawns that will trigger resign "count- - ing". + This is the score in centipawns that will trigger resign + "counting". ShowPonder (default: true) Show search information during engine pondering. Turning this off @@ -362,8 +372,8 @@ CONFIG FILE FORMAT move). KibitzCommand (default: "tellall") - xboard command to use for kibitzing, normally "tellall" for kibitz- - ing or "tellothers" for whispering. + xboard command to use for kibitzing, normally "tellall" for + kibitzing or "tellothers" for whispering. KibitzDelay (default: 5) How many seconds to wait before starting kibitzing. This has an @@ -392,16 +402,15 @@ CONFIG FILE FORMAT BookFile (default: book.bin) The name of the (binary) book file. Note that PolyGlot will look for it in the directory it was launched from, not in the engine - directory. Of course, full path can be used in which case the cur- - rent directory does not matter. + directory. Of course, full path can be used in which case the + current directory does not matter. BookRandom (default: true) Select moves according to their weights in the book. If false the move with the highest weight is selected. - BookRandom (default: true) - Select moves according to their weights in the book. If false the - move with the highest weight is selected. + BookLearn (default: false) + This is a noop. BookDepth (default: 256) Stop using the book after this number of moves. @@ -426,14 +435,15 @@ CONFIG FILE FORMAT This a bit vector in which each bit represents the processors that a process is allowed to run on. This option works only on Windows. - SaveSettingsOnExit (default: true) - If true then PolyGlot will implement persistence by loading its - options from an additional INI file which is specified by the - option "SaveFile". At exit PolyGlot will also save its options to - this INI file. + STFudge (default: 20) + PolyGlot will translate "st x" as "go movetime 1000*x-STFudge". + The rationale is that in the UCI specification the argument of + movetime is defined as the exact search time whereas the argument + of the st command is only an upperbound. - SaveFile (default: .ini) - The name of the file from which to take the additional options. + OnlyWbOptions (default: true) + If true then PolyGlot restricts the options it sends to those that + are potentially useful for WinBoard. Work arounds @@ -441,9 +451,9 @@ CONFIG FILE FORMAT only when necessary. Their purpose is to try to hide problems with various software (not just engines). - IMPORTANT: Any of these work arounds might be removed in future ver- - sions of PolyGlot. You are strongly recommended to contact the author - of faulty software and truly fix the problem. + IMPORTANT: Any of these work arounds might be removed in future + versions of PolyGlot. You are strongly recommended to contact the + author of faulty software and truly fix the problem. PolyGlot supports the following work arounds: @@ -454,16 +464,16 @@ CONFIG FILE FORMAT CanPonder (default: false) PolyGlot now conforms to the documented UCI behaviour: the engine will be allowed to ponder only if it (the engine) declares the - "Ponder" UCI option. However some engines which can actually pon- - der do not declare the option. This work around lets PolyGlot know - that they can ponder. + "Ponder" UCI option. However some engines which can actually + ponder do not declare the option. This work around lets PolyGlot + know that they can ponder. SyncStop (default: false) - When a ponder miss occurs, Polyglot interrupts the engine and IMME- - DIATELY launches a new search. While there should be no problem - with this, some engines seem confused and corrupt their search - board. "SyncStop" forces PolyGlot to wait for the (now useless) - ponder search to finish before launching the new search. + When a ponder miss occurs, Polyglot interrupts the engine and + IMMEDIATELY launches a new search. While there should be no + problem with this, some engines seem confused and corrupt their + search board. "SyncStop" forces PolyGlot to wait for the (now + useless) ponder search to finish before launching the new search. PromoteWorkAround (default: false) Some engines do not specify a promotion piece, e.g. they send @@ -479,21 +489,6 @@ CONFIG FILE FORMAT to the way kibitzing is implemented, KibitzMove is disabled in that case. - WbWorkArounds (default: true) - The intention of these options is to provide work arounds for - xboard/winboard bugs should they arise. This one decapitalizes the - word Draw in options that contain this word. Some versions of - xboard/winboard contain a bug which causes such options to be - interpreted as draw claims by the engine. - - Engines that send options with "Draw" in their name are Rybka and - HIARCS. - - WbWorkArounds2 (default: false) - Old version of Winboard clear the engine output window at depth 1. - With this work around PG will send info lines at depth >=2. This - may or may not improve the display. - [Engine] section This section contains engine UCI options. PolyGlot does not understand @@ -501,8 +496,8 @@ CONFIG FILE FORMAT UCI form). You can add any UCI option that makes sense to the engine (not just the common options about hash-table size and tablebases). - NOTE: use INI syntax, not UCI. For example "OwnBook = true" is cor- - rect. It will be replaced by PolyGlot with "setoption name OwnBook + NOTE: use INI syntax, not UCI. For example "OwnBook = true" is + correct. It will be replaced by PolyGlot with "setoption name OwnBook value true" at engine startup. Standard UCI options are @@ -519,6 +514,23 @@ CONFIG FILE FORMAT GUI or launch the engine in a console and type "uci". EXAMPLES + Running the UCI engine "fruit" under xboard 4.3.15 and later (this + invokes PolyGlot internally). + + xboard -fcp fruit -fUCI + + An explicit command line for using the UCI engine "fruit" with logging + enabled (this works also with older versions of xboard). + + xboard -fcp "polyglot -noini -log true -ec fruit" + + The equivalent config file would be: + + [PolyGlot] + EngineCommand = fruit + Log = true + [Engine] + Compile "games.pgn" into a book "book.bin" retaining all lines of at most 30 plies. @@ -537,19 +549,6 @@ EXAMPLES polyglot epd-test -epd test.epd -max-time 420 - The command line for using the UCI engine "fruit" with 128M hash in - xboard with logging enabled. - - xboard -fcp "polyglot -noini -log -ec fruit -hash 128" - - The equivalent config file would be: - - [PolyGlot] - EngineCommand = fruit - Log = true - [Engine] - Hash=128 - EXIT STATUS PolyGlot always returns 0 on exit. @@ -561,11 +560,12 @@ AUTHORS Various enhancements: Fonzy Bleumers - UCI port: Michel Van den Bergh + UCI port and implementation of new WB protocol: Michel Van den Bergh + SEE ALSO xboard(6) - 2009-08-31 POLYGLOT(6) + 2011-06-01 POLYGLOT(6)