X-Git-Url: http://winboard.nl/cgi-bin?a=blobdiff_plain;f=README;h=677348e252570c62edf79e90e4c5fc10b14152c8;hb=cd81270f2b1723e0798f4d6dcaee134f0b4aca7f;hp=0b313e9812733e21e6fe96041c9413995a636874;hpb=e7a2abd9bd4fce9ebbd70793b00d9d5f99886348;p=polyglot.git diff --git a/README b/README index 0b313e9..677348e 100644 --- a/README +++ b/README @@ -5,23 +5,29 @@ POLYGLOT(6) POLYGLOT(6) NAME PolyGlot - Winboard protocol to UCI protocol adapter - book engine for Polyglot books - - a collection of utilities for creating opening books + - a collection of utilities for creating and analyzing + opening books - a utility for analyzing epd files - a perft counter SYNOPSIS - polyglot [configfile] - - polyglot -ec engine + polyglot [configfile] [-noini] [-ec engine] [-ed enginedirectory] [-en + enginename] [-log] [-lf logfile] [-hash value] [-bk book] [-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] - polyglot [configfile] epd-test [-epd inputfile] [-min-depth depth] - [-max-depth depth] [-max-time time] [-depth-delta delta] + polyglot info-book [-bin inputfile] [-exact] + + polyglot dump-book [-bin inputfile] -color color [-out outputfile] + + polyglot [configfile] epd-test [engineoptions] [-epd inputfile] + [-min-depth depth] [-max-depth depth] [-max-time time] [-depth-delta + delta] polyglot perft [-fen fen] [-max-depth depth] @@ -34,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 @@ -47,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 @@ -61,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 @@ -75,33 +81,83 @@ 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 + 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 + may be (and there usually are) many positions in the book that are not + on a "line" as defined in the previous paragraph. It is convenient to + call such positions "isolated" positions. The utility "info-book" + counts such isolated positions. + + Some of the isolated positions are provably unreachable and they could + in principle be deleted from the book. For example if a book contains + only the move "e4" in the starting position but also the position after + "d4 d5" then this last position is provably unreachable since it + requires white to make a non-book move when a book move is available. + Such situations arise frequently from the priority rules in merging + books. + + Unfortunately not all isolated positions are provably unreachable and + it is difficult to identify the latter. If invoked with "-exact" the + utility info-book will attempt to count the isolated positions which + require a player to make a non-book move when a book move is available. + Due to the possibility of transpositions this is not a fool proof + method. 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 invoked without options or with a config file as argument PolyGlot - acts as an adapter. The config file format is documented below. The - default config file is "polyglot.ini". + When PolyGlot is invoked as an adapter of in epd-test mode it gets its + options from a config file and then from the command line. The default + config file is "polyglot.ini" but an alternative one may be optionally + included as first argument. The config file format is described below. - When invoked as + The following engine options may be specified on the command line. + + -noini + Do not use a config file, even if one was specified on the command + line. + + -pg The argument is a string of the form =. This option + will set the Polyglot option to . + + -uci + The argument is a string of the form =. This option + will set the engine option to . - polyglot -ec engine + -ec This sets the EngineCommand. - PolyGlot simply starts "engine" and acts as an adapter. No config file - is used and thus it is expected that all properties will be set by the - GUI. + -ed This sets the EngineDir. + + -en This sets the EngineName. + + -hash + This is an alias for -uci "Hash=". + + -log + This is an alias for -pg "Log=true". + + -lf (default: "polyglot.log") + This is an alias for -pg "LogFile=". + + -bk This is an alias for -pg "Book=true" -pg "BookFile=". When invoked as @@ -158,10 +214,39 @@ OPTIONS When invoked as + polyglot dump-book + + PolyGlot supports the following options + + -bin (default: book.bin) + Input file in PolyGlot book format. + + -color + The color for whom to generate the lines. + + -out (default: book_.txt) + The name of the output file. + + When invoked as + + polyglot info-book + + PolyGlot supports the following options + + -bin (default: book.bin) + Input file in PolyGlot book format. + + -exact + Attempt to count the provably unreachable positions among the + isolated ones. Note that this takes a very long time. + + When invoked as + polyglot epd-test - (possibly with a config file as first argument) PolyGlot supports the - following options + (possibly with a config file as first argument) PolyGlot supports + besides the generic options described above the following additional + options. -max-depth (default: 63) Unconditionally stop the search when this depth has been reached. @@ -170,9 +255,9 @@ OPTIONS Unconditionally stop the seach after this amount of time. -depth-delta (default: 3) - Stop the search if the best move has been constant for this many - depths, on condition that the mininal depth and minimal time have - been reached. + Stop the search if the solution as been found and the best move has + been constant for this many depths, on condition that the mininal + depth and minimal time have been reached. -min-depth (default: 8) Minimal search depth when the search is stopped using @@ -206,10 +291,12 @@ CONFIG FILE FORMAT option = value ... - Lines starting with "#" are ignored. + The characters "#" and ";" serve as comment characters. - NOTE: There can be spaces in option names or values. Do not use - quotes. Boolean values are written as "true" or "false". + By default initial and final white space is stripped from option + values. 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. [PolyGlot] section @@ -257,13 +344,16 @@ 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 might be better for interactive use in some interfaces. + ScoreWhite (default: true) + Report score from white's point of view in xboard mode. + KibitzMove (default: false) Whether to kibitz when playing a move. @@ -272,20 +362,21 @@ 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 effect only if "KibitzPV" is selected, move kibitzes are always sent regardless of the delay. + KibitzInterval (default: 0) + This is another form of throttling. PolyGlot will usually wait this + many seconds before doing the next kibitz. + UCI (default: false) If true PolyGlot will not understand xboard commands. - Chess960 (default: false) - Play Chess960 (also called Fischer Random Chess or FRC), - MateScore (default: 10000) Mate score reported to GUI when in xboard mode. @@ -301,16 +392,23 @@ 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. - BookLearn (default: false) - Record learning information in the opening book. Naturally this - requires the opening book to be writable. + BookRandom (default: true) + Select moves according to their weights in the book. If false the + move with the highest weight is selected. + + BookDepth (default: 256) + Stop using the book after this number of moves. + + BookTreshold (default: 5) + Do not play moves with a weight (probability) lower than this (in + per mil). UseNice (default: false) Run the engine at nice level 5, or "NiceValue" if it set. On some @@ -328,16 +426,30 @@ 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. + Persist (default: true) + If true then PolyGlot will implement persistence by loading options + from an additional INI file whose name is by default derived from + the engine name. At exit PolyGlot will also save its options to + this INI file. + + PersistFile (default: .ini) + The name of the file from which to take the additional options. It + is probably best to stick with the default. You can safely edit + this file, or delete it to restore the default options. + + PersistDir (default: $HOME/.polyglot on Linux; ".\Polyglot Settings" on + Windows) + The directory where the PersistFile is stored. + Work arounds Work arounds are identical to options except that they should be used only when necessary. Their purpose is to try to hide problems with - various software (not just engines). The default value is always cor- - rect for bug-free software. + 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: @@ -348,16 +460,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 @@ -367,9 +479,26 @@ CONFIG FILE FORMAT RepeatPV (default: true) When true, PolyGlot repeats the last pv string (which also contains score,depth and time usage) it got from the engine. Some engines - however do not send a new pv string just before sending the move - and the now old pv string might confuse debugtools that parse the - winboard debug files. + however do not send a new pv string just before sending the move. + In that case the output of PolyGlot would be inconsistent. When + RepeatPV is false PolyGlot does not repeat the last pv string. Due + 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 @@ -378,8 +507,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 @@ -396,20 +525,41 @@ 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 128M + hash in xboard with logging enabled (this also works on xboard 4.2.7). + + xboard -fcp "polyglot -noini -log -ec fruit -hash 128" + + The equivalent config file would be: + + [PolyGlot] + EngineCommand = fruit + Log = true + [Engine] + Hash=128 + Compile "games.pgn" into a book "book.bin" retaining all lines of at most 30 plies. polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30 - Merge books "in1.bin" and "in2.bin" into a book "out.bin". + Merge books "w1.bin" and "w2.bin" into a book "w.bin". polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin - Here is a minimal config file + Inspect lines for white in "w.bin" - [PolyGlot] - EngineCommand = fruit - [Engine] + polyglot dump-book -bin w.bin -color white -out w_white.txt + + Test epd file "test.epd" with a (maximum) search time of 7 minutes per + position + + polyglot epd-test -epd test.epd -max-time 420 EXIT STATUS PolyGlot always returns 0 on exit. @@ -422,11 +572,12 @@ AUTHORS Various enhancements: Fonzy Bleumers - UCI port: Michel Van den Bergh + UCI port, option persistence and new WB protocol: Michel Van den Bergh + SEE ALSO xboard(6) - 2009-01-13 POLYGLOT(6) + 2009-09-04 POLYGLOT(6)