--- /dev/null
+
+
+
+
+
+
+
+ Crafty Command Documentation (version 18)
+ -----------------------------------------------
+Crafty is nothing more than a long-time hobby of mine, dat-
+ing back to Blitz and later Cray Blitz. People ask me how I
+keep doing this, and that is the one question that generally
+leaves me at a loss for words.
+
+Perhaps the most common question I'm asked is "is this ver-
+sion of Crafty some dumbed-down version of what you play on
+ICC or what you use at a computer chess event?" The answer
+is a resounding *NO*. The current version is *exactly* what
+is running on ICC under this version number. Note that a
+new version can, on occasion, introduce weaknesses or out-
+right bugs that were not present in previous "gold" ver-
+sions. As a result, you should be careful to back up your
+"favorite" before trying the latest and greatest. If you
+aren't satisfied with the new version, you can then go back
+to what you believe is a better version.
+
+If you are looking for the strongest playing computer chess
+program available, you should likely look to Fritz, Rebel,
+Tiger, and the other commercial entries. There you will
+find strong opponents with polished interfaces that have
+been tested in a systematic and careful way. If you are
+looking for a program that plays good chess, has a reason-
+able set of features for you to use, is available in source
+form, and one where the author welcomes feedback, code or
+suggestions, then you are at the right place. I welcome
+comments and suggestions, and also feedback from ideas you
+try yourself that seem to work.
+
+Crafty is a state-of-the-art computer chess program, and
+uses all of the search algorithms you have probably read
+about, negascout search, killer/history move ordering, SEE
+(Static Exchange Evaluation) quiescence move ordering and
+pruning, hash (transposition/refutation) tables as well as
+evaluation caches, selective extensions, recursive null-move
+search, and a host of other features that have been used and
+are still being used in most computer chess programs. If
+it's not in Crafty, either it is on the "to do" list, or it
+has been tried, found wanting, and discarded.
+
+Chess Knowledge is growing, and suggestions (or even better,
+real code) are welcome. This is the best place to con-
+tribute your ideas, because knowledge can be used to sup-
+plant search and make it play better. The evaluation is
+probably the easiest place to start studying Crafty because
+of the comments and simplicity of using bitmaps, *once* you
+get "into" them.
+
+My purpose for doing this is an exercise in computer chess
+efficiency. I can't begin to count the number of people I
+know that started from scratch to write a chess program.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Even larger is the group that started from scratch, and gave
+up before finishing, because of the basic size of the pro-
+ject.
+
+Crafty offers everyone a very clean starting point, if you
+are fascinated by the bitmap chess board implementation (as
+I am). The search and quiescence code is reasonably
+straightforward, as is the evaluation,
+
+It offers a great starting point, so that if you are inter-
+ested in trying a new search extension, you can be testing
+tomorrow, rather than next year, because you start with a
+fully functional chess engine that is not a "toy" applica-
+tion, but is a functional and "dangerous" chess player. It
+offers a rapid start, although you can certainly replace it
+piece by piece until it is "yours" if you want. It also
+offers a fairly complete set of commands and an interface
+for a GUI as well as support for chess server play, so that
+testing and debugging your new ideas is greatly simplified.
+
+If you'd like more information, please check out the read.me
+document and the crafty.FAQ that are distributed with
+Crafty. These contain recent news and specific instructions
+for commonly asked questions, like "where can I obtain
+tablebase files and how do I use them?"
+ How to play a game.
+ -------------------
+When you execute Crafty, you will immediately be greeted by
+the prompt string "white(1): " and Crafty will wait for com-
+mands. This prompt means it is white on move, and we are at
+move #1 for white. You can first use any of the commands
+from the alphabetic command listing below to tailor the game
+to your liking (time control, hash table size, book random-
+ness, etc.) and then you have two choices. If you want to
+play white, just enter your move, and Crafty will take it
+from there and make a move in response. You will then be
+prompted by "white(2):" and it is your move again. If you
+would prefer to play black, just enter either "move" or "go"
+at the prompt and crafty will move for that side rather than
+accepting a move from you. After it makes its move for
+white, you will then see the prompt "black(1): " indicating
+it is now time for blacks first move. You can enter a move,
+or you can once again enter "move" or "go" and Crafty will
+again move for the current side, change sides, and prompt
+you for what to do next.
+
+If you find yourself continually using a set of commands to
+configure crafty to play as you want, you can put these com-
+mands in a startup file called .craftyrc (Unix) or crafty.rc
+(DOS/Windows). The format for this file is just like you
+would type the commands at the keyboard, with the require-
+ment that the last line of the file must be "exit" on a line
+by itself. Using this, each time you start Crafty, it will
+
+
+
+
+
+
+
+
+
+
+
+
+
+first execute the commands from this file before it prompts
+you for input.
+
+While Crafty is running, you can control what it displays,
+but here's a couple of samples to explain what it is saying
+and why:
+
+ depth time score variation (1)
+ book moves {d4, c3, Nc3, d3, b3, c4, g3, b4, Be2, Bb5}
+ book 0.0s 70% d4
+
+White(3): d4
+ time used: 0.01
+
+This is the normal output for those cases where Crafty is in
+book. The book moves line gives the set of book moves that
+made the first selection cut (see the book selection expla-
+nation given later), followed by the move actually played,
+in this case d4.
+
+If Crafty is out of book, then the output looks somewhat
+different as given below:
+
+ depth time score variation (1)
+ 4-> 0.81 2.09 6. dxe4 Bxe4 7. Rad8 Qf2 8. Qb5
+ 5 1.37 2.41 6. dxe4 Bxe4 7. Ne5 Qf4 8. Bxe4+
+Qxe4 9. f5
+ 5-> 1.88 2.41 6. dxe4 Bxe4 7. Ne5 Qf4 8. Bxe4+
+Qxe4 9. f5
+ 6 7.38 -- 6. dxe4
+ 6 11.90 1.97 6. dxe4 Bxe4 7. Rab8 Qf2 8. Qc7
+Nc5 9. Qe5
+ 6 12.92 ++ 6. Ne5
+ 6 13.71 2.23 6. Ne5 Qg2 7. Ng6 h5 8. Nh4 Qg4
+ 6-> 15.59 2.23 6. Ne5 Qg2 7. Ng6 h5 8. Nh4 Qg4
+ time: 15.60 cpu:99% mat:1 n:246565 nps:15927
+ ext-> checks:4706 recaps:1336 pawns:0 1rep:301
+ nodes full:45951 quiescence:200614 evals:104657
+ endgame tablebase-> probes done: 0 successful: 0
+
+Let's take this stuff one line at a time. Lines that have
+something like 4-> in the depth column are printed when that
+iteration (depth) is completely finished. The time and
+score columns should be obvious as to their meaning as is
+the PV, the sequence of moves that led to this score. One
+note about the "score" column. As of version 18, Crafty
+displays the score with + values good for white, - values
+good for black, no matter which side it is playing in the
+game. All output now follows this convention, from playing,
+to analysis mode, to annotating your games, to whisper-
+ing/kibitzing on the chess servers, and so forth. This is
+unlike other engines, but once you get used to it, it is
+much less confusing when you remember that negative scores
+
+
+
+
+
+
+
+
+
+
+
+
+
+are good for black and bad for white, and vice-versa.
+
+the line that has -- in the score column means that when we
+started depth 6, dxe4 turned out to be worse than we thought
+(notice score dropped from 2.411 last search to 1.972 for
+this move this search.) To resolve this, Crafty lowers the
+lower search bound (alpha) and re-searches the move to find
+the score. The line with ++ means that this move (Ne5) is
+better than the best move so far, so Crafty raises the upper
+search bound (beta) and re-searches this move to find the
+new score.
+
+the first line of statistics gives the total time taken for
+this search, the cpu percentage which should stay at 98-100%
+unless your machine is heavily loaded or unless Crafty is in
+an endgame that is having lots of contact with endgame
+databases. If this drops below 98%, it means that Crafty is
+not getting full CPU usage and will be playing weaker than
+normal. The mat:1 is simply the true material score, since
+Crafty's positional scores are often larger than a pawn.
+
+ Alphabetic Listing of Commands
+ ------------------------------
+
+1. alarm on|off This command is used to control Crafty's
+"beep" after it makes a move. Turning this off will make
+Crafty "quiet" when it plays, but also makes it easy to miss
+a move if you are using crafty to play in a tournament.
+This is primarily designed to make Crafty tolerable during
+late night matches.
+
+2. analyze This command puts crafty into analyze mode. In
+this mode, Crafty starts computing for whichever side is on
+move, and it continues computing and showing its analysis
+until a move is entered. This move is made, Crafty changes
+sides, and starts thinking and printing analysis all over,
+but for the other side now.
+
+This command is useful to play through a game, because you
+get instant feedback when you try a move. If you want to
+try a different move from the one you just entered, use the
+"back" command to back up one move, or use "back <n>" to
+back up <n> moves. Note that one move is a single move for
+the last player, not a move for both sides. To unmake the
+most recent 2 moves (one for black, one for white) use "back
+2".
+
+3. annotate|annotateh <filename> <colors|name> <moves>
+<margin> <time> This command is used to annotate (make com-
+ments in) a game that has already been played.
+
+The annotate command produces a file with the .can extension
+added to the original name. This file will contain pure
+
+
+
+
+
+
+
+
+
+
+
+
+
+ascii information from the annotation pass. "annotateh"
+produces an HTML file instead (with the .html extension).
+This includes the normal output, plus a nice bitmapped
+graphical board display for every position where crafty had
+'something to say'.
+
+<filename> is the name of the file that has the game moves
+stored in it. This should be a PGN-compatible file,
+although Crafty can read nearly any file with chess moves
+and convert it to pgn using the "read" and "savegame" com-
+mands to perform the conversion.
+
+<colors|name> indicates which side Crafty will annotate.
+The valid choices are w, b, and wb/bw for white only, black
+only, and both, respectively. Crafty will search and pro-
+duce results for the indicated color only, making moves for
+the other side silently as they are read in.
+
+Alternatively, you can specify the player's name (useful if
+you want to annotate several of your own games in one large
+pgn file, for example, and you alternated colors so that you
+can't pick the right one easily). Crafty will then figure
+out which side to annotate for in each game. Note that the
+name is case-sensitive, but that you only have to enter a
+string that is unique in the name field. IE if one name is
+"Anatoly Karpov" and the other is "unknown" then specifying
+Karpov as the name would be sufficient. If the same
+'string' appears in both names, Crafty will complain.
+
+<moves> indicates the moves that should be annotated. If
+this is a single integer, annotation starts at this move
+number (for the color given above) and proceeds for the rest
+of the game. If a range is given, as (20-33), then only
+moves 20-33 inclusive are annotated. To annotate the com-
+plete game, you can use 1-999.
+
+<margin> gives a score "window" that controls whether Crafty
+will produce comments (see below). The larger this number
+this number, the fewer annotations Crafty will produce. A
+negative number will result in an annotation for every move
+selected.
+
+<time> indicates the time limit for each search. Since each
+move selected requires two searches, you can take the number
+of moves, double this number and multiply by <time> to
+determine how long the annotation process will take. This
+time is in seconds.
+
+How it works. Suppose you use the command "annotate game1 w
+1-999 1.000 30" This asks Crafty to read the file "game1",
+and annotate the white moves for the entire game. The mar-
+gin is 1 pawn and the search time limit is 30 seconds. The
+output for the annotate command is found in <filename>.can,
+
+
+
+
+
+
+
+
+
+
+
+
+
+in this case this is game1.can.
+
+Crafty first searches the move actually played in the game
+to determine the score for it. Crafty then searches the
+same position, but tries all legal moves. If the score for
+the best move found in this search is greater than the score
+for the move actually played plus the margin, then a comment
+is added to the output file. This output file is quite
+short, with all the game moves (plus any PGN tags in the
+original, for identification purposes) plus the brief com-
+ments. An annotation looks like this:
+
+{real_value (depth:best_value PV moves)}
+
+real_value is the score for the move actually played. depth
+is the depth Crafty searched to produce the best_value and
+PV for what it thinks is the best sequence of moves for both
+sides. If you set <margin> to 1.000, you are asking Crafty
+to only annotate moves that either lost a pawn or more, or
+moves that failed to win a pawn or more. If you set <mar-
+gin> to .300, you are asking for annotations for any move
+that makes the score drop about 1/3 of a pawn below the
+value for the best move Crafty found.
+
+If you have other moves you would like to see analyzed dur-
+ing this annotate process, at the point where the move can
+be played, insert it into the PGN file as an analysis com-
+ment, surrounded by () or {} characters. Crafty will pro-
+duce analysis for this move as well. If more than one move
+appears inside a single set of delimiters, only the first
+will be analyzed. To force Crafty to analyze more than one
+move, enter them like this: (move1) (move2) as though they
+were two separate comments.
+
+4. ANSI on|off This command is used to control whether or
+not Crafty attempts to display its move in reverse video or
+not. For PC's, Linux, and most Unix boxes, this works fine.
+Should you find yourself playing crafty via a dumb terminal,
+this might hose the terminal and interfere with your ability
+to see or input moves. If moves are not displayed in
+reverse video, it's probably wise to turn this off to avoid
+hanging the terminal you are using.
+
+5. black|white This command simply toggles the side on
+move. if it is white to move, and you enter white, nothing
+happens. If it is white to move and you enter black, then
+it becomes blacks turn to move immediately from the same
+position. Used only infrequently.
+
+6. book (see the book explanation near the end of this doc-
+ument for a full explanation of this command and its many
+options.) Note that there are special commands available
+(*only* on the command line, *not* in the
+
+
+
+
+
+
+
+
+
+
+
+
+
+crafty.rc/.craftyrc files) to direct crafty to specific
+directories for the book files (bookpath=/a/b/c), the table-
+base files (tbpath=/i/j/k) and the log files (log-
+path=/x/y/z). Note that these commands can *only* be used
+on the command line, because they must be executed before
+the engine is initialized. Putting them in the
+crafty.rc/.craftyrc file will produce error messages without
+affecting how the files are opened.
+
+If you need to specify multiple directories (tbpath only)
+you may do so by using "tbpath=path1:path2:path3:etc" or
+else use the more Unix- like
+"tbpath=(path1:path2:path3:etc)" instead. The paths are
+separated by ":" (colon) characters and everything is case-
+sensitive as usual. For dos/windows users, the separator
+can be a semi-color (;) or a comma(,) to avoid the drive
+designation ambiguity.
+
+7. cache=N This command is used to alter the cache size
+used for endgame database probes. N can be a simple inte-
+ger, representing the number of bytes to use or it can be
+specified as nK or nM representing n * 1024 bytes or n *
+1024 * 1024 bytes. This should be in multiples of the
+database "chunk" size, which might vary. Using the nM form
+guarantees that you will have a reasonable number.
+
+8. clock <ctime> <otime> This command is primarily
+intended for use when Crafty is playing in a tournament,
+such as the WMCCC or WCCC events. If the operator is some-
+what slow in entering moves, or forgets to stop the clock
+after making a move for Crafty, the chess clock for the game
+will drift from the values that Crafty maintains internally.
+<ctime> is the time (in minutes or hh:mm format) crafty has
+left until the next time control, and <otime> is the oppo-
+nent's remaining clock time. This command can be used at
+any time, but will only affect the time per move *after*
+crafty makes the current move and starts to think about what
+the opponent might do next.
+
+9. computer This command usually comes from xboard/win-
+board, but can be used at any time to tell Crafty it is
+playing a computer. This will prevent some things from hap-
+pening, such as a draw score that varies, as well as adjust-
+ing the book selection code to be more selective in what it
+plays.
+
+10. display this command is used to display the game
+board. This board is displayed using the ICS style #1 type
+of ASCII display, with white always at the bottom of the
+screen, black at the top. Very unusable to play a game
+with, but good to verify a position after it has been set
+up.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+This command is also used to display the various
+piece/square tables, by typing "display <piece>" where
+<piece> is replaced by pawn, knight, bishop, rook, queen or
+king. The board is oriented in the same way as the display
+board with a one-to-one correspondence between the squares.
+Perhaps useful for curiosity, but not for anything else.
+These values can not be modified by the user.
+
+The final version of this command is used to control what
+kind of output you will see when crafty runs. Currently the
+following options are available.
+
+ display time: this will make Crafty display the
+ amount of time each side takes after making a move.
+
+ display changes: this will make Crafty display the
+ PV each time it changes during the search, including
+ when a move fails high or becomes a new best move.
+
+ display variation: this will make Crafty display the
+ PV at the end of each iteration, but it will only show
+ the best PV for the entire iteration, not all of the
+ changes.
+
+ display stats: this enables basic search statistics
+ output including time, nodes and so forth.
+
+ display extstats: this enables extended search stats
+ including the hashing statistics, search extension
+ statistics and so forth.
+
+ display movenum: causes all PV output to have move num-
+ bers embedded in them to make the PV possibly easier to
+ read. This causes the PV to look like this: 12. ...
+ Nxe4 13. Bxe4 h6 rather than simply Nxe4 Bxe4 h6. This
+ is very helpful when playing on a server and whispering
+ or kibitzing analysis. It will also be useful when
+ crafty is run from within a database program as the
+ move numbers will sync up with the actual game.
+
+ display moves: will display each root move as it is
+ searched, along with updating the search time at the
+ bottom of the screen, so you can see what move is cur-
+ rently being analyzed.
+
+ display general: will display general information mes-
+ sages whenever Crafty wants to tell you something (ie
+ "clearing hash tables" or other such things like "Mate
+ in n moves."
+
+If you put a "no" in front of any of these options, that
+will disable that particular type of output.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+11. draw offers Crafty a draw. It generally will look at
+the value returned by the last search, and compare it with
+the value returned by an internal function DrawScore(). If
+the search value is not above this result, then Crafty will
+accept the draw. If the search value is above the theoreti-
+cal value for a draw, Crafty will decline the draw. Note
+that crafty will offer draws based on internal analysis.
+When it offers a draw, you can respond with "draw" although
+the game does not really end until you exit Crafty.
+
+12. drawscore N sets the draw score (or contempt factor) to
+N. If you want crafty to avoid draws, set this number to
+something that is negative. IE -50 says that a repetition
+(draw) is the same as being 1/2 pawn down. Setting it to
++100 will make it try very hard to draw because that looks
+like it is winning a pawn when it does so. Note that this
+is dangerous (either way) as a -50 in a king and pawn ending
+is very likely dead lost... and a repetition is better.
+
+13. echo <text> This command is normally used inside a
+command file that you are going to use to "feed" crafty some
+positions for analysis or whatever. Since crafty depends on
+the operating system to echo commands as they are typed,
+commands read in from a file are "invisible." This gives
+you the ability to insert commands into such a file so that
+crafty displays a message on the screen to give you an idea
+of where it is in processing the file.
+
+14. edit This command has been "cloned" from GnuChess to
+provide an interface with Xboard. After entering the "edit"
+command, you are in "edit.white" mode, where any
+piece/square combination you enter will add the indicated
+white piece on the given square. Piece/squares are entered
+as "qa3", or "bc4" for example. This puts a white queen on
+a3 and a white bishop on c4. Once all white pieces are
+entered, typing a "c" changes to "edit.black" mode where
+piece/square combinations now place black pieces. Typing a
+"." character exits edit mode. To clear the board ini-
+tially, you use the "#" character.
+
+Here's a sample to set up the original starting position,
+after white has played 1. e4, but no other moves have been
+played.
+
+ edit
+ #
+ ra1 nb1 bc1 qd1 ke1 bf1 ng1 rh1
+ pa2 pb2 pc2 pd2 pe4 pf2 pg2 ph2
+ c
+ ra8 nb8 bc8 qd8 ke8 bf8 ng8 rh8
+ pa7 pb7 pc7 pd7 pe7 pf7 pg7 ph7
+ .
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Note that input is free form, so piece/squares can be
+entered one per line or all on one line. Ditto for the #,
+c, and . special characters. Note also that there is no way
+to enter castling status here. It is far better to use the
+"setboard" command which uses a FEN-like syntax and allows
+you to set both castling and enpassant status.
+
+15. egtb This command enables the endgame databases.
+Crafty will use the "tbpath" directory (if provided) to
+locate and register all of the databases you have down-
+loaded. It will report the largest class it found, as in "5
+piece tablebase files found" if you downloaded at least one
+5-piece file. If you use this command to enable databases,
+you should also consider using the "cache" command to spec-
+ify the egtb cache size.
+
+16. end|quit These commands are used to terminate crafty.
+Note that you can resume a game later without having to
+replay the moves, by starting Crafty using the "crafty c"
+command. It will immediately read in the moves for the last
+game, although you will have to set the time controls and
+clock time remaining yourself.
+
+17. evaluation option <value> This command is used to mod-
+ify the evaluation scores.
+
+The option "asymmetry" is used to make crafty evaluate king
+safety differently for each side. "evaluation asymmetry 25"
+will increase the king safety scores for the opponent only,
+meaning it will pay less attention to its own king safety
+than to that of its opponent. This will make it play more
+aggressively. "evaluation asymmetry -25" will reduce the
+king safety scores for for the opponent by 25%, making it
+care more about its own king safety than that of its oppo-
+nent. This will make it play more defensively.
+
+The "bscale" option will adjust the scores for blocked
+pawns. The default value is 100. Increasing this will tend
+to make Crafty dislike blocked pawn positions more, which
+will lead to more open positions. Note that this only
+affects moves _after_ the opening book has been followed,
+which means that the position might be blocked before the
+evaluation term has a chance to affect the game.
+
+The "kscale" option will adjust all king safety scores based
+on the 'value' entered. For example, "evaluation kscale 50"
+will reduce all king safety scores to 50% of their normal
+value. "evaluation kscale 133" will increase all king
+safety scores to 133% of their normal values.
+
+The option "tropism" is used to scale king tropism scores.
+This will attract pieces toward kings. A value of 100 means
+no change. other values are treated as a percentage (like
+
+
+
+
+
+
+
+
+
+
+
+
+
+scale) to increase (> 100) or decrease (<100) the king
+tropism scores.
+
+When you use this command, you will see something like this:
+
+modified king-safety values:
+white: 0 4 16 26 39 45 58 77 87 90 93 96 100 103 106 109
+ 112 116 119 122 125 128 128 128 128 128 128 128 128 128 128 128
+
+black: 0 5 20 32 48 56 72 96 108 112 116 120 124 128 132 136
+ 140 144 148 152 156 160 160 160 160 160 160 160 160 160 160 160
+
+Those values represent the king-safety evaluation as the
+king gets more and more exposed. This is always based on
+the fast that "crafty" will be the side on move when the
+search starts. In the above, it was white's move when this
+was typed, meaning that it appears that crafty will be play-
+ing black. Notice that white's king safety numbers are
+scaled by 20% to make it slightly more cautious about its
+own king. If you type "go" in this position, the scores get
+reversed as Crafty's scores are always left alone (with the
+asymmetry option) and the opponent's scores are scaled down
+as indicated.
+
+You will see similar numbers (but not black and white sets)
+that represent the actual scores produced for king tropism.
+Note that pieces interact to choose which element of this
+vector is used, but in general, the more pieces are close to
+the king, the larger the element from this array.
+
+The "pscale" option is used to scale normal pawn structure
+scoring in the same way as the other scaling options. 100
+is the default. Values less than 100 reduce this term, val-
+ues over 100 inflate it.
+
+The "ppscale" option is used to scale some passed pawn scor-
+ing in the same way as the other scaling options. 100 is
+the default. Values less than 100 reduce this term, values
+over 100 inflate it. This mainly effects outside passed
+pawns/protected passed pawns. The normal pawn scoring com-
+putes the value of a passed pawn. This term is then used to
+scale those terms that modify this value further, such as
+two connected passed pawns on the 6th, or a passed pawn with
+the king supporting it in an endgame.
+
+18. extensions type value
+
+This command is used to control the extension depth for the
+various extensions done in Crafty's search. The extensions
+are set as decimel numbers that represent plies (or frac-
+tions of plies) to extend for each particular reason. Most
+default to 1.0 and .75, but any value can be used. Note
+that value > 1.0 are _very_ dangerous as they can cause the
+
+
+
+
+
+
+
+
+
+
+
+
+
+search to become non-terminating (crafty will stop when it
+runs out of time for the move, but it might not be able to
+get anything useful from such a search).
+
+These extensions are presently limited to a maximum of one
+ply of extensions at any point in the tree. IE no matter
+what you set these values to, they can not exceed one ply at
+present.
+
+incheck This is the amount to extend when the side on move
+makes a move that leaves the opponent in check. Note that
+Crafty extends on the ply where the check is played, not on
+the next ply where the opposite side is in check.
+
+onerep This is the one-reply-to-check extensions, and is
+done at the point where one side is in check and has exactly
+one legal move to escape from the check.
+
+pushpp This is the extension used for certain passed pawn
+pushes in the endgame.
+
+recapture This is the recapture extension, and is applied
+when the current move recaptures an equal-valued piece that
+made a capture at the previous ply. IE BxN, PxB. Note that
+this can only be applied once for every two plies so that
+BxN, BxB, NxB, NxN won't look like three recaptures.
+
+mate This is the mate threat extensions and is applied when
+a null move search returns -MATED, which means that doing
+nothing gets the side on move mated. The opponent must have
+some sort of serious mate threat in such a position.
+
+19. flag on|off This command is used to force crafty to
+end a game where the opponent runs out of time with win-
+board/xboard (on) or to ignore this (off) if desired.
+
+20. force [move] This command is used to force Crafty to
+play a move that is different from the one chosen and played
+by the tree search. If [move] is given, and it is a legal
+move, Crafty will retract its last move and make this move
+instead. It does not change the side on move, but does
+change the position of course. If [move] is not given,
+Crafty will prompt you for a move to make.
+
+21. help This command displays multiple pages of one-line
+help, one command per line. If a line ends with [help],
+then you can use help followed by the specific command to
+get detailed help.
+
+22. history This command displays the history in a verti-
+cal column with one move for white and one per black per
+line. There are other ways to display the current game
+moves and also to save them in files that are explained
+
+
+
+
+
+
+
+
+
+
+
+
+
+later.
+
+23. hash=x and hashp=x These commands are used to adjust
+the size of the hash tables in Crafty. hash modifies the
+size of the transposition/refutation table, while hashp mod-
+ifies the size of the pawn structure/king safety hash table.
+The sizes may be entered as one of the following two types
+of values: nnnK where nnn is an integer indicating how many
+Kbytes Crafty should use for this hash table; nnnM where nnn
+is an integer indicating how many Mbytes Crafty should use.
+
+The transposition/Refutation table is the most critical of
+the two, because it directly affects search efficiency, par-
+ticularly in the endgame. For this reason this should be
+maximized. The most effective size for this hash table is
+3/4 of your available memory. If you don't know how to fig-
+ure this out, but know that you have 16 megs for example,
+they you can say hash=16M and crafty will round that down to
+12M, which is 3/4 of a power of two size. If you study the
+sizes that are possible, you will find 3M, 6M, 12M, 24M,
+48M, and so forth. Anything up to, but not including, the
+next size will be rounded down to the next lower size.
+hashp should be set to approximately 1/2 of what is left.
+For example, the P6 Crafty runs on when playing on ICC often
+uses hash=48M and hashp=8M. The only thing to watch for is
+that if you make this too large, particularly under windows,
+performance will suffer badly because of paging I/O over-
+head. When Crafty is searching in a normal (non-book, non-
+endgame database) position, the disk light should *not* be
+on, indicating lots of I/O.
+
+There is no danger in making this table too large, although
+you have to watch out because if Crafty barely fits in mem-
+ory, doing something else on the machine can cause Crafty to
+be swapped out completely or partially, depending on the
+operating system you are using. If you are going to use the
+machine for anything else while Crafty is running, it is
+better to "pretend" that the machine only has 1/2 of the
+memory it actually does when computing the size of the hash
+tables you want to use.
+
+24. import <filename> [clear] This command is used to
+import any sort of learning data that Crafty supports, which
+currently includes book learning data and position learning
+data. This command reads the appropriate <filename> and
+imports that learned data, just as though Crafty had learned
+it by playing the games. The [clear] option, if specified,
+caused all old learned results to be cleared before the
+import operation, otherwise the imported data is simply
+added to what is already present.
+
+25. input <filename> This command is used to redirect the
+console input I/O stream from the keyboard to a file.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Crafty will then read commands from this file, rather than
+from the keyboard, and execute them just as though they were
+typed in. Such a command file *must* be terminated by an
+"exit" command (no quotes) as the last command in the file.
+This reverts the input stream back to the keyboard, and
+prompts you for another command or move.
+
+This command might be used to configure crafty for a spe-
+cific time control, by putting the appropriate time control
+commands in the file, or to customize the hash table sizes
+as needed.
+
+26. info This command is used to display information about
+Crafty and the current game. Such things as the time con-
+trol, the time left on the clocks and other information is
+shown.
+
+27. learn n controls the learning facilities in crafty.
+Currently this is a 3-bit boolean switch, bit 1 (001) con-
+trols book learning, bit 2 (010) controls position learning,
+and bit 3 (100) controls result learning. learn=0 disables
+all learning, learn=1 enables book learning only, learn=2
+enables position learning only, and learn=4 enables result
+learning. Add the values together to turn on more than one
+type of learning (default=7 to enable everything).
+
+28. level <m> <t> <inc> This command was taken directly
+from GnuChess so that the Xboard/WinBoard interface would
+interface with Crafty. There are other better ways to set
+the time, but this one is well-known. The three parameters
+are <m> (number of moves in the game) <t> initial time on
+the clock. After <m> moves are made, this amount of time is
+added to the clock again. <inc> is the Fischer-Clock incre-
+ment that is added back to each clock after a move is made.
+It may be zero for a non-increment game.
+
+Examples:
+
+level 0 5 0 (ICS 5 0 game)
+level 0 5 3 (ICS 5 3 game)
+level 0 15 30 (ICS 15 30 game)
+
+29. list GM|IM|C|AK|S +name [+name ...] -name [-name ...]
+This command is used to maintain the internal "lists" Crafty
+uses to auto-tune itself when playing on a chess server.
+There are three lists, GM, IM and C. If Crafty's opponent
+is in any of these lists, Crafty adjusts internal controls
+that affect how/when it resigns or offers draws, and how
+randomly it will choose moves from the opening book. For
+example, Crafty resigns much sooner against a GM, because it
+assumes he knows how to win a rook-up ending, regardless of
+how much time is left. By the same token, when playing
+against computers, Crafty will always assume that a draw is
+
+
+
+
+
+
+
+
+
+
+
+
+
+0.000, so that it doesn't wreck its position trying to avoid
+repeating a position.
+
+The AK list will automatically kibitz scores/PV's if the
+opponent is in this list. The S list will turn on special
+scoring for opponents in this list. The only current member
+is "mercilous".
+
+The syntax +name1 +name2 simply adds these players to the
+specified list. To remove a name, use -name1 -name2. You
+can use one command per name to remove or add, or you can
+use one command to add and remove multiple names. Note that
+all names must be entered in lowercase characters, using any
+uppercase characters will break the matching algorithm.
+
+30. log off|on|<n> This command is used to disable log-
+ging. The default is log on, which causes crafty to produce
+a new log.nnn file for each game played. If you are running
+Crafty on a server, you might use log off, which disables
+creating these files as well as the game.nnn files used to
+restart a game after you exit crafty and come back later.
+If you use the form "log n" crafty will simply display the
+last n lines of the log on the screen. If you use "log n
+file" crafty will copy the last n lines of the log to "file"
+which could be your hard drive, or a floppy.
+
+Note that if you run with log off, you will be unable to
+find out what Crafty was thinking about since there is no
+other record of the game. You will always see a game.001
+because as crafty plays a game, this contains all the real
+moves played so far so that you can back up if needed. you
+will also see a log.001 file, but it will be empty.
+
+31. ls <filename> will list all the files that match the
+filename wildcard (the wildcards depend on the system you
+are using, but generally *, ? will work fine. you can also
+supply path information in the filename if you want to list
+the contents of a different directory. Just use the same
+syntax you would if you were using "ls" under unix or "dir"
+under windows.
+
+32. mode tournament|normal This command is primarily used
+to put Crafty into "tournament" mode, which is intended for
+use when Crafty is playing in computer chess events. It
+accomplishes two things: (1) makes all draws return a score
+of 0.000, and (2) makes crafty issue a message after each
+move showing the internal chess clock time, and requesting
+that that operator check and adjust as needed using the
+"clock" command. This primarily makes Crafty comply with
+computer chess rules that say the operator can't do anything
+not specifically requested by the program.
+
+33. name <name> This command is an ICS-play specific
+
+
+
+
+
+
+
+
+
+
+
+
+
+command. Xboard/WinBoard uses this to inform Crafty of the
+opponent's name. Crafty uses the name, and looks it up in
+its GM/IM/C lists, and if found, adjusts itself accordingly.
+This is not used by the PGN code and this will not cause the
+players <name> to show up in the PGN tag section.
+
+34. new This command wipes everything out and starts a
+brand new game. It closes the old log-file and game-file,
+and opens the next sequential numbered file. It also resets
+the game to the beginning and prepares to start a brand new
+game. This was added for Xboard, but it turns out that
+Xboard does not use this, rather it starts Crafty fresh for
+each new game by first terminating the old copy then start-
+ing a new one. Not nearly as efficient as using "new" but
+likely safer it a program can't be sure of resetting every-
+thing back to the initial state.
+
+35. noise <n> This command sets the "noise" level in
+Crafty. Basically, until <n> nodes have been searched,
+crafty will be silent and not display analysis.
+
+This is useful in two ways. First, in end-games, 20+ ply
+searches are not uncommon, and the search analysis for the
+first few plies arrives so quickly that it is distracting.
+Second, when observing games (new interface only) on ICS
+servers, this can be used to avoid having Crafty generate
+too many analysis kibitzes. A value of 100000 will basi-
+cally shut off any output for the first second or so (on a
+P6/200). Similarly, 1000000 will eliminate any output for
+about the first 10 seconds. When watching and kibitzing
+games like the World Championship games on ICC, I generally
+use 5000000, which is almost one minute of silence so that
+the first PV it kibitzes is a pretty deep search.
+
+noise 0 will cause *all* analysis to be displayed, which on
+a fast machine causes no problems. On a slower machine, or
+over a slow phone connection, this might cause a big commu-
+nication backlog. The default is roughly one second on a
+P6/200 (100000) but can be modified by this command.
+
+36. operator <n> Another command intended for use when
+Crafty is playing in a tournament, operated by a human.
+This tells crafty to "hide" <n> minutes of time and not use
+them. This time is basically allocated to the operator to
+make up for the time it takes to type in moves and/or cor-
+rect mistakes. At the WMCCC events, the normal value we use
+is 5. Playing on a server, this is not needed, as it is not
+needed if you are playing Crafty yourself.
+
+37. perf This command is primarily used in optimizing
+Crafty, or to test the speed of the move generator and Make-
+Move()/UnMakeMove() on different platforms. It produces two
+results, the moves it can generate per second, and the moves
+
+
+
+
+
+
+
+
+
+
+
+
+
+is can generate and make/unmake per second. While this is
+not a perfect performance indicator, it does give an
+"approximation" for how fast Crafty might run. In general,
+the higher the numbers, the better the program will play,
+although machines are certainly different. It's not uncom-
+mon to find a machine that searches slower than another, but
+has a higher "perf" value.
+
+38. perft <depth> This command is generally used to con-
+firm that the move generator and bitmap operators are work-
+ing properly. It simply takes the current position, and
+generates/makes/unmakes moves and counts them. Many pro-
+grams use this from a "standard" position to make sure that
+their move generator does not miss generating odd moves like
+enpassant/promotions and also to confirm that the
+make/unmake code correctly updates the board so that the
+totals remain constant across different machines and pro-
+grams, since there is no alpha/beta or evaluation things
+done. if <depth> is greater than 5 or 6, it will take a
+*long* time, since this is basically a minimax tree traver-
+sal that will visit *every* node within the <depth> search
+horizon.
+
+39. pgn <tag> <value> This command is used to set the
+usual PGN tags to meaningful values. The recognized tags
+are Event, Site, Round, Date, White, WhiteElo, Black, Black-
+Elo, and Result, and the tags *are* case sensitive. The
+<value> can be any valid input and blanks and special char-
+acters are allowed. Note that the date is clearly specified
+in the PGN standard and must be yyyy.mm.dd with no variance.
+Valid results are 1-0 (white won), 0-1 (black won), 1/2-1/2
+(drawn) and * (unknown). Some examples:
+
+pgn Event 14th World MicroComputer Chess Championship
+pgn Date 1996.10.8
+pgn Site Jakarta, Indonesia
+pgn Round 1
+pgn White Crafty
+pgn WhiteElo 2400
+pgn Black assassin
+pgn BlackElo 2400
+pgn Result 1-0
+
+Setting these values will result in a proper PGN file when
+using the savegame command. Note that if you use the "read"
+command to input a PGN game, these values will be extracted
+from that game if they are given.
+
+40. ponder off|on|<move> This command serves two purposes.
+First, it can be used to disable (off) or enable (on) think-
+ing on the opponent's time (or pondering as it is called in
+many programs including Crafty.) Turning it off will weaken
+Crafty since it will not use any machine time while waiting
+
+
+
+
+
+
+
+
+
+
+
+
+
+on the opponent to move. It is sometimes useful, however,
+when playing Crafty against another computer and the
+machines are not equal. If crafty is on a faster machine,
+and you attempt to adjust for this by giving the opponent
+more time than Crafty, it doesn't work quite as expected,
+because while the opponent is thinking, so is Crafty, which
+lets it use the extra opponent time in an unexpected way.
+In such a case, it's best to stop pondering in both pro-
+grams.
+
+If <move> is given, it directs Crafty to use that <move> to
+ponder, rather than the one from the previous search. Most
+commonly this is used to set the right move to ponder after
+Crafty has been stopped and then restarted, assuming that it
+is the opponent's turn to move when this happens. Other-
+wise, it is probably better to not try to influence things,
+although if you are watching and suddenly wonder "what would
+Crafty do if the opponent plays move 'X'?", you can answer
+this by simply typing "ponder X" and then watching the anal-
+ysis. You should reset the correct ponder move after you do
+this of course.
+
+41. reset <n> This command lets you back up in the current
+game to any move of your choice. reset <n> backs up the
+game to move <n> with the same side on move. If you want to
+first change the side to move, use the white/black command,
+then use the reset command to back up to the right move.
+Note that you can also go forward as well, just so there are
+moves in the current game history.
+
+42. resign <n> This command sets the resign threshold.
+When running on ICC I typically use "resign 9" which will
+make crafty resign roughly five moves after the score drops
+below -9.000. For IM's I change this to 6, and for GM's I
+often use 3, so that it will resign quicker and not drag a
+lost game out unnecessarily.
+
+43. read/reada [<filename>] This command will read input,
+and extract the chess moves and make them to set up the
+position at the end of the game. It first resets the chess
+board to the initial position (read command only) and then
+extracts the PGN tags (if present) from the front of the
+input. The rest of the input is parsed for chess moves
+(comments and similar things are culled automatically) and
+the moves are made and added to the game history. Once this
+is done, you can back up, go forward, or play from any point
+in the game. If you specify a <filename> everything is read
+from the file, otherwise it is read from the console key-
+board.
+
+The reada command reads moves, but appends them to the cur-
+rent game history/ position rather than resetting to the
+initial chess position. This lets you read in a game, then
+
+
+
+
+
+
+
+
+
+
+
+
+
+use reada to manually add some more moves to see the result-
+ing position.
+
+44. savegame <filename> This command is used to save the
+current game in a PGN-compliant file with the PGN tags
+included. Note that the default TAG values might not be
+what you want if you do not either use the pgn command to
+set them or else input a valid PGN file with the tags
+already filled in.
+
+Be aware that this command doesn't check the filename for
+legality since anything goes in UNIX. In DOS, you might
+produce a bad filename with either too many characters, too
+many periods, or whatever, so be careful with the name you
+choose. Note also that this file will be overwritten if it
+already exists, so be sure to choose a name that is not the
+name of a file that has something you consider important in
+it.
+
+45. savepos <filename> This command writes a single line
+into <filename> in FEN-like notation. This lets you save a
+position, and then come back later to re-examine it. You
+would use the "in <filename>" command to input this file and
+set the position up.
+
+46. search <move> This command allows you to specify one
+particular move for the side on move, and then when you tell
+Crafty to search this position, this is the only move that
+will be searched. This is used internally by the annotate
+command, but can be used to investigate one specific move.
+If the move is not the best move, a normal search won't show
+you why it is bad, but this will. It is also quite a bit
+faster since the other moves in the position are not
+searched at all.
+
+47. settc <moves> <ctime> <otime> This command is primar-
+ily used in tournaments, and is an error-recovery command.
+If the machine crashes and corrupts the game history file,
+frequently the operator will have to simply set the position
+using the setboard command, and then use the settc command
+to restore the time control values. <moves> is moves until
+the next time control (from Crafty's perspective, be careful
+and don't look at the opponent's moves to time control by
+accident.) <ctime> is minutes left on Crafty's clock,
+<otime> is minutes left on the opponent's clock.
+
+48. setboard <FEN input> This command is used to set a
+chess position up for analysis and is the preferred way to
+do this, rather than using the gnu EDIT interface. It uses
+a classic Forsythe-like notation to encode the position and
+also has provisions for castling status and enpassant cap-
+ture status.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+the standard piece codes p,n,b,r,q,k are used to denote the
+type of piece on a square, upper/lower case are used to
+indicate the color of the piece (uppercase=white pieces,
+lowercase=black pieces).
+
+the pieces are entered from the classic chess diagram's ori-
+entation of a8 being the upper-left-hand corner of the
+board, and this square is entered first, followed by the
+remainder of the 8th rank left to right. To indicate empty
+squares, use a number between 1 and 8 to indicate how many
+adjacent squares are empty. use a / to terminate each rank
+after all of the pieces for that rank have been entered.
+Note that you do not have to account for all 8 squares on a
+given rank, although many test suites do this for clarity.
+
+the following input will setup the board position that given
+below:
+
+ k2r/ppp////Q/5PPP/7K/ B
+
+this assumes that k represents a white king and -q repre-
+sents a black queen.
+
+ -k * * -r * * * *
+ -p -p -p * * * * *
+ * * * * * * * *
+ * * * * * * * *
+ * * * * * * * *
+ q * * * * * * *
+ * * * * * p p p
+ * * * * * * * k
+ *
+the field after the final "/" should be either b or w to
+indicate which side is "on move." after this side-to-move
+field any of the following characters can appear to indicate
+the following: KQ: white can castle king-side/queen-
+side/both; kq: same for black; a1-h8: indicates the square
+occupied by a pawn that can be captured enpassant.
+
+49. score This command simply gives the positional score
+for the current position. This score is from whites per-
+spective, so a + score is good for white, a - score is good
+for black. Crafty also breaks the score down into major
+categories (from Evaluate()) to indicate things like pawn
+structure, piece evaluation, passed pawns, development, and
+so forth. Note that some of Crafty's evaluation is asymmet-
+ric, so that if you simply change sides with the white/black
+command and then enter "score" again, you may get a differ-
+ent value. This is *not* a bug. :)
+
+50. sd <n> This command lets you specify a specific search
+depth limit that Crafty can not exceed. It still pays
+attention to the clock, however, so often you will use the
+
+
+
+
+
+
+
+
+
+
+
+
+
+st <n> command (below) in conjunction with this if the
+search is going to take an extended amount of time. <n> is
+the depth (in plies or 1/2 moves) that the search must
+reach. Note that if Crafty is pondering, it still honors
+this limit and will stop a ponder search after this depth
+has been completed as well. This is *not* the way to make
+Crafty play weaker, although this will be covered in a later
+section of this document.
+
+51. show <category> This command forces Crafty to display
+additional information about certain actions it takes. Cur-
+rently the only <category> is "book" which will make crafty
+display information about all the book moves it found in the
+database. More is given about this information in the BOOK
+section later in this file.
+
+52. smpmt=n This command is used to set the number of
+threads to use on a machine with more than one processor.
+For optimal performance, "n" should be set to the number of
+processors you have, although using fewer will reduce the
+load on your machine. For this command to work, Crafty must
+have been compiled with SMP defined. When compiled with SMP
+enabled, mt=0 effectively disables the SMP code completely.
+
+This command also has two that are closely related. smpmin
+and smpmax. Both accept single numerical arguments. smpmin
+is used to control the minimum tree depth required at a node
+for it to be eligible for parallel searching. IE smpmin 2
+says don't split unless at least two more plies are left to
+search below this node. smpmax sets the maximum for the
+same idea, is smpmax 10 says don't split if more than 10
+plies are remaining below this node.
+
+53. sn <n> This command is similar to the sd command, but
+instead of setting a specific search depth, it sets a number
+of nodes to search. Once the search has searched this num-
+ber of nodes (+ maybe one more second of searching to check
+the time) the search will exit.
+
+54. st <n> This command lets you specify a specific search
+time limit for Crafty. Again, this is not the preferred way
+to set a time per move, because this limit is absolute and
+Crafty will never go over this limit, even if it sees that
+it is losing or getting mated. Setting the time control
+with the usual "time" or "level" command is *much* better.
+<time> is given in seconds, although it may also be entered
+as mm:ss if preferred.
+
+55. swindle on|off This command gives you control over
+"swindle mode." When on, and playing a game, Crafty will
+try to win drawn endings (according to the tablebases) if it
+has winning chances (like KR vs KB, for example). This will
+put up very stiff "resistance" to accepting the draw, while
+
+
+
+
+
+
+
+
+
+
+
+
+
+with this mode off, it may be very easy to draw a position
+once the tablebases say "drawn." This mode is automatically
+turned "off" during analysis or when annotating a game, and
+is only used when actually playing a game against an oppo-
+nent. If there are no tablebases then this has no effect on
+the game at all.
+
+56. tags This command will simply display the current PGN
+tags (you can edit them with the various PGN commands).
+
+57. test <filename> [n] This command will run a suite of
+positions (the file must be in "Crafty" format as explained
+below) and produce a summary of how many it got right,
+wrong, etc. It uses the time per move you set with the
+(typically) st <n> command. The optional parameter [n] is
+the "early exit" counter. If Crafty finds, and holds the
+solution move for n iterations, it will terminate the
+search. I use this to make a win at chess run take < 15
+minutes, even though the time per position is set to 1
+minute, by setting n to 2. After two correct iterations,
+Crafty goes on to the next problem. For absolutely correct
+results, this is not advisable as it could obviously change
+its mind later on, but for performance analysis, this saves
+a lot of time.
+
+The test suite contains the following lines: (this is a
+sample from my test suite for Win At Chess.)
+
+title wac299
+setboard 1n2rr2/1pk3pp/pNn2p2/2N1p3/8/6P1/PP2PPKP/2RR4 w
+solution Nca4
+
+title wac300
+setboard b2b1r1k/3R1ppp/4qP2/4p1PQ/4P3/5B2/4N1K1/8 w
+solution g6
+
+end
+
+The title command simply displays this message in the log
+file so you can look at the output and figure out which
+position it goes with. This is optional, but useful.
+
+The setboard command sets the position as explained before.
+
+The solution command gives the set of solution moves (one or
+more moves that are separated by blanks) and/or a set of
+"anti-solution" moves (moves that must not be played to
+count the position as correct.) "anti-solution" moves are
+simply followed by a "?" character, for example:
+
+solution Bxa7?
+
+The solution command supplies a set of key moves, and then
+
+
+
+
+
+
+
+
+
+
+
+
+
+starts the search. If, after the search terminates, one of
+the key solution moves was chosen (or none of the anti-solu-
+tion moves were chosen) the position is counted as correct.
+
+The final line should be "end" although end-of-file or EOF
+will also be detected in this case.
+
+57. time CPU|elapsed|<values> This command controls
+whether the program uses CPU time or wall-clock time for
+timing. for tournament play, it is safer to use wall-clock
+timing, for testing it may be more consistent to use CPU
+timing if the machine is used for other things concurrently
+with the tests being run.
+
+time is also used to set the basic search timing controls.
+the general form of the command is as follows:
+
+ time nmoves/ntime/[nmoves/ntime]/[increment]
+
+nmoves/ntime represents a traditional first time control
+when nmoves is an integer representing the number of moves
+and ntime is the total time allowed for these moves. the
+[optional] nmoves/ntime is a traditional secondary time con-
+trol. increment is a feature related to ICS play and emu-
+lates the Fischer clock where <increment> is added to the
+time left after each move is made.
+
+as an alternative, nmoves can be "sd" which represents a
+sudden death time control of the remainder of the game
+played in ntime. the optional secondary time control can be
+a sudden-death time control, as in the following example:
+
+ time 60/30/sd/30
+
+this sets 60 moves in 30 minutes, then game in 30 additional
+minutes. an increment can be added if desired.
+
+One final example is the following:
+
+ time sd/15
+
+which is a simple game/15 setting. This command can also be
+used to perform the same function as the "level" command.
+For example, to set up a classic ICS 2 12 game, the follow-
+ing would would work:
+
+ time sd/2/12
+
+59. trace <n> This command is used to make crafty display
+the tree as it searches a position. Due to the incredible
+speed at which this program can search, however, this is
+less than useful since it can swamp any known display driver
+and make things scroll impossibly fast.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Also note that this command usually is disabled, because
+Crafty is generally compiled with the -DFAST flag, which
+removes the trace output code from the search to make things
+slightly faster. You will have to recompile, without the
+-DFAST, if you want to use this. It's utility is limited,
+except for debugging, anyway.
+
+60. usage <n> is simply a way to modify Crafty's time usage
+to fit your tastes. You can "suggest" a time limit with any
+of the options discussed previously, but if you use anything
+other than the "st" command, Crafty will do its best to use
+time as you suggest, but it also anticipates that it will
+save some time by pondering, etc., and will therefore be
+more aggressive at trying to use time. if <n> is a positive
+integer, it is taken as a percentage and crafty will compute
+the time limit it thinks is appropriate for the current
+clock settings, then increase this limit by this percentage
+(50 would make it take 1.5 times longer than normal.) -50
+would make it take 1/2 the time it would normally take.
+
+Crafty adjusts the usage internally based on time left,
+opponent's time left, how quickly or slowly the opponent is
+moving, etc. Further modifying things with this is danger-
+ous, but possible.
+
+61. whisper/kibitz <n> These commands are used to control
+what Crafty will whisper or kibitz on a chess server. The
+options are (1) only whispers or kibitzes mate announce-
+ments; (2) adds time, score, depth to the previous option,
+but no PV or moves. (3) adds the PV. (4) adds book move
+information to the output. The remaining two options gener-
+ate a lot of output and should be used with caution. (5)
+displays the PV after each iteration completes. I use this
+when using my custom interface to let Crafty observe/comment
+on games in progress on ICC. Noise can be used to prevent
+shallow searches from generating output and keeping "noise"
+down on the games being watched. (6) basically will whis-
+per/kibitz nearly everything you see on the console from a
+search, each PV when it changes, fail highs and fail lows,
+etc. A significant amount of output that should be care-
+fully weighed before turning it "loose."
+
+62. xboard This command turns on Xboard/WinBoard compati-
+bility mode, and makes Crafty behave somewhat like GnuChess.
+This is designed to be used *only* when Crafty is interfac-
+ing with Xboard/WinBoard. Crafty will not work with these
+two GUIs without this option, and really won't work very
+well with this option if it is not connected to one of them.
+
+63. There are other commands that are not documented. They
+are part of the xboard protocol and really should not be
+used by the normal user. You can find all the commands in
+option.c should you be interested.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Opening Book Setup and Usage
+ ----------------------------
+
+Crafty uses two pre-compiled opening books, called
+"book.bin" and "books.bin".
+
+The file book.bin is usually build from a large text file
+containing PGN games, often taken from collections of GM
+games. Building book.bin is a simple exercise and requires
+nothing other than the raw input file you are going to use.
+Generally this will be either medium.zip or the set of four
+files large[1-4].zip, all of which are stored on the ftp
+machine ftp.cis.uab.edu/pub/hyatt/.
+
+To create the file book.bin, you need a PGN game collection
+that is a *real* PGN-compliant file. Supposing this file is
+called "large.pgn" you would use the following command:
+
+book create large.pgn <m> [n] [wpct]
+
+The only thing you have to supply is <m>, a number indicat-
+ing how many moves from each game are to be stored in the
+book.bin database. I typically use 60, which stores the
+first 60 moves from each game. Increasing this number
+slightly increases the probability that Crafty will stay in
+book longer, but it also increases the probability that it
+will follow a game too far, so that it begins to reach posi-
+tions where the move actually played might not be the best
+move, letting it fall into a bad hole. Increasing this also
+increases the size of the database as well.
+
+You can decrease the size of the book, and also reduce the
+number of ugly moves by specifying <n>, which says that
+unless a move is played in at least N games, the move is
+discarded. This will substantially decrease the size of the
+book.bin file, and also eliminate single game moves that
+often have significant errors or blunders.
+
+You can increase the quality of book lines by specifying
+<wpct> which is the "winning percentage". This is specified
+as a percentage of lost games, and is used to discard moves
+that led to mostly losses. A safe value is 50, which says
+that if a particular opening move didn't win at least 50% as
+many games as it lost, the move is culled. A value of 100
+would mean that moves are culled if they produced more
+losses than wins, and is really a strict criterion.
+
+After creating book.bin, you need to create books.bin. This
+is a small version of book.bin, which is intended to give
+you more control over the moves/openings Crafty will play.
+This is usually built from the file start.pgn on the ftp
+machine, but you can modify this file to suit your taste
+easily. To build books.bin, you use the following command:
+
+
+
+
+
+
+
+
+
+
+
+
+
+books create start.pgn 60
+
+Again, 60 is what I use, but none of my start.pgn lines go
+anywhere near that many moves. The main point here is that
+in start.pgn, you can append a "!" to any move you want, and
+when it is Crafty's turn to move for that color, it will
+play from the set of moves with "!" if there are any, ignor-
+ing the rest of the book moves. If you only want it to play
+1. e4 as white, you would just enter the short game:
+
+[Crafty only plays 1. e4] 1. e4!
+
+and you are finished!. You can enter as many as you want.
+If on the other hand there is a move you don't want Crafty
+to play, then follow that move with a "?" and it will never
+play it. Moves in books.bin that are not flagged with ! or
+? don't have any influence on Crafty's choice at all.
+
+Here's how the files are used. When searching a position,
+Crafty first enumerates the set of moves it can find in the
+opening database. It then does the same for the books.bin
+database, and performs a "merge" operation to combine the ?
+and ! flags... The purpose of the books.bin file is to give
+you a small database that you can easily modify, rebuild,
+and repeat this process over and over. Since it takes a
+fraction of a second to completely rebuild this file, it is
+very easy to modify this to control what Crafty will play,
+without having to rebuild the large database.
+
+One important characteristic of the PGN input is the Result
+tag must be specified in most of the lines, because Crafty
+counts wins, losses and draws for each book move and uses
+these counts with some of the book selection options given
+below.
+
+How the flags are used.
+
+The ! and ? flags should only appear in the small books.bin
+file, although there is no reason why they can not appear in
+the large file as well. For this discussion, it doesn't
+matter since Crafty takes the moves from both files and
+"merges" the flags/etc into one entry for each move.
+
+Quite simply, if any book legal book move has a ! flag, then
+Crafty will only play moves from the set of moves which all
+have the ! flag. If a move has a ? flag, then that move is
+immediately removed from the set of possible book moves. If
+the only legal book move has a ? flag, it will not be played
+as a book move and Crafty will simply pretend that it found
+no book moves and will execute a normal tree search. Pretty
+simple.
+
+How to control the frequency of opening move selection.
+
+
+
+
+
+
+
+
+
+
+
+
+
+A new feature in version 15.15 and beyond allows you to
+append a PGN comment to any move in a text file used to cre-
+ate books.bin, of the form {play nn%}. This will force the
+move it follows to be played that percentage of the time,
+regardless of the normal book-ordering values based on fre-
+quency and so forth.
+
+Note that {play 0%} will not prevent a move from being
+played at all, as this will look just like a move with no
+percent specified. To avoid playing a move, use the ? flag.
+
+How does Crafty choose book moves?
+
+Crafty's book selection algorithm depends on two user-
+defined values that can be set at any time during a game:
+
+book random <n>
+
+book width <w>
+
+The selection algorithm first finds the set of legal book
+moves as above. This set will either be all ! moves, or
+will have no ! moves in it. This set is then sorted based
+on the setting of book random. Here's the options:
+
+book random 0. This is a special case for book selection.
+Crafty simply takes the set of book moves, and searches only
+these moves using a normal alpha/beta search, but with a
+shorter than usual time limit. It then plays the move that
+produces the best search value. This has one serious disad-
+vantage in that there is no randomness to this at all. It
+will always play the same move in the same position, unless
+the evaluation is modified, or the time per move is differ-
+ent enough to let the search find a different move from the
+book move set.
+
+book random 1. This enables a random form of book move
+selection, but you have a lot of control over how moves are
+randomly chosen. The moves are ordered, based on 4 parame-
+ters: frequency of play, win/lose ratio, static evaluation
+and learned results. Normally these are factored into the
+value used to sort the moves, based on default settings that
+you can modify by using the command "bookw option N"
+"option" should be "freq", "ratio", "eval" and "learn". N
+should be a number between 0 and 1.
+
+Crafty finds the min and max values for each of the 4 param-
+eters, and then maps this into the range 0-1000 for each
+parameter. Each parameter is multiplied by the correspond-
+ing "weight" you have assigned, and this is used as a value
+to sort the moves from low to high. Note that the first
+sort value is always the "play percent" to move them to the
+top of the list. For moves with equal "play percent"
+
+
+
+
+
+
+
+
+
+
+
+
+
+values, the normal sort-value is used as the second-level
+sort variable (if no moves have a play-percent, then this
+second-level variable is the only one used, of course.)
+
+Once Crafty has sorted the moves as given above, it next
+excludes any book moves which have 0 wins. This culls the
+odd lines where a player chose a bad line and lost quickly.
+With zero wins, it will never be chosen, although Crafty
+will happily follow it from the other side. :) This is not
+anywhere near perfect, however, because an opening could
+have 1 win and 19 losses and that still would stay in the
+list.
+
+If a move has a learned value of > 100, this move is ele-
+vated in priority to that of a ! move, since it appears to
+win material instantly. If a value is < -100, it is given a
+? since it appears to be a lemon.
+
+After this, the setting for "book width <w>" is used to keep
+the first <w> moves in the list, after the above culling has
+been completed. The smaller you make <w> the less random-
+ness you get, but the chance of Crafty popping out a really
+bizarre book move gets smaller as well.
+
+After sorting, the final step is to fold in any mandatory
+"play percent" values. What this step does is that it finds
+all the moves in the "playable move set" just computed,
+which have no percent-to-play value set. It sums the sort-
+values for these moves, then adjusts the sort-values for the
+other moves so that their percentages will be honored.
+
+Once this has been done, crafty simply uses the "sort value"
+for each move to compute a total for all moves. It then
+generates a random number between 1 and this limit, and
+chooses the move that this probability distribution matches.
+This will certainly evolve over time as new ideas are devel-
+oped.
+
+For my play on ICC, I use book random 1, and book width 5
+normally, although for titled players this is reduced to
+book width 3. For computers, I reduce this further to 2, to
+try to play reasonable openings and cull the gambits and
+things that don't work out.
+
+How does book learning work and how can I share learned
+results?
+
+1. *all* of crafty's "learned knowledge" is in the book.bin
+file. It keeps the learned value and learned count right in
+the book file for speed. You can't modify it, although
+"show book" will make crafty display all the book stuff
+before it makes a move.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+2. the book.lrn file has two purposes: (a) to serve as a
+log for your prying eyes, so you can see what it's learned,
+against whom, and what the score was that got its attention
+in the first place. The values on the end of each book
+line, inside the {} characters are as follows:
+ {value, depth, rating_difference} value is the value of
+the "key" search that comes from the first 10 moves out of
+book. it's in centipawns, and + is good - is bad. depth is
+the depth the search reached at this "key" position, the
+deeper the search, the more the value is "trusted." rat-
+ing_difference is crafty's rating - opponent's rating a neg-
+ative value means pay more attention to the score since the
+opponent is better than crafty, a positive value means to
+take the score with a grain of salt, because the opponent
+was weaker than Crafty.
+
+You can delete this file at any time, and it has no effect
+on learning. As I mentioned, the learning takes place in
+book.bin... this is mainly for you to peek at if you are
+interested. However, this is the "portable learning data
+file" also, and can be given to others to import into their
+crafty, where it will affect the opening book just like
+their crafty had played the openings and got the same
+scores. There are two ways to use such "lrn" files:
+
+1. "import <filename>" will read <filename> and import the
+knowledge therein into your book.bin. Since I use the same
+learning code as is used when playing games, this informa-
+tion also gets appended to *your* book.lrn file as well, so
+that your book.lrn always reflects *everything* your program
+has learned, so long as you don't ever remove this file. It
+would be a mistake to use this command on your own book.lrn
+file, because the things would get counted twice, which
+might or might not be a good thing.
+
+2. "import <filename> clear" will read <filename) and
+import the knowledge as above, but first clears *all*
+learned results from book.bin. you will want to do this if
+you import my book.lrn, *and*, you have contributed to my
+book.lrn data by sending me yours. I'll take care of elimi-
+nating duplicates if you screw up in what you send me, but
+once you send me something, you run the risk of getting it
+"back again" later. This is going to be a problem until
+everyone gets used to sharing something that is rather
+"vapid" like this "learned info" is...
+
+Other than that, we are now "open for business"... when the
+urge strikes you, email me your .lrn file, I'll keep a large
+master here and update it on occasion. Probably the best
+thing to do is to send me your .lrn and at the same
+*instant* delete yours. This will capture anything learned
+*after* you send me the file, but you'll get it all right
+back with the next version of book.lrn that I distribute.
+
+
+
+
+
+
+
+
+
+
+
+
+
+after getting this new book.lrn back, here's what you should
+do:
+
+1. rename your old book.lrn to something else. I'll call
+it "book.lrn.old" here.
+
+2. copy my blearn.dat to your machine, but *do not* put it
+in the directory with your book.bin and books.bin file
+because it will get confusing very quickly if you do. put
+it somewhere else, because you are going to remove it
+quickly anyway. I'll call it new.lrn for this example.
+
+3. import new.lrn clear
+ import book.lrn.old
+
+and you are ready to rumble again. The first command clears
+the learned values, sucks in my new learn file and updates
+everything. the second command re-learns everything you've
+learned since you sent me the last book.lrn file. After
+doing this your book.lrn will have my .lrn stuff, plus your
+old.lrn stuff, just waiting to be sent to me again...
+
+If this is confusing, I can probably add an automatic com-
+mand to do all of this by renaming book.lrn, etc. Hopefully
+this is not too error-prone for the time being anyway...
+
+What is this new Position Learning I've heard about?
+
+Crafty now has a "permanent" hash table that is kept from
+game to game. A position gets into this "hash file" when
+Crafty executes a search and the search value is signifi-
+cantly lower than the last search value.
+
+When this happens, Crafty stores the current information for
+this position in the permanent hash file, which can hold up
+to 65536 positions. Once it fills up, the positions are
+replaced on a FIFO basic always keeping the most recent 64K
+entries.
+
+Each time crafty starts a search, the positions/scores from
+this file are stuffed into the normal transposition table,
+and used during the search just like any other table entry.
+Here's how it helps: In a game that was played, the follow-
+ing moves and scores were found by crafty (playing white):
+
+1. Ng5 (+.277) h6 2. Nh7 (+.321) Kg8 3. Qh5 (+.133)
+Qg7 4. Ng5 (-2.122) hxg5
+
+So, the knight got trapped at h7, and at move 4 crafty dis-
+covered that this is gross and "learns" this result/posi-
+tion.
+
+We play the exact same game again: except that two things
+
+
+
+
+
+
+
+
+
+
+
+
+
+can happen here. It might be that Ng7 is the *only* square
+the knight can move to here, which means this whole thing is
+forced. the first search would find:
+
+1. Ng5 (-2.122) if the search can reach 8 plies deep, which
+happens even in 5 second games. It's learned that Ng5 is
+bad. It stores *this* position in the permanent hash file
+also, and the next time you try this same trap, it will dis-
+cover 4-5 moves earlier that if the knight gets to g5 it is
+in trouble. Each game will diverge from the first game 3-4
+moves earlier. Simple and effective.
+
+2. Ng5 might not be forced, and if not, it knows Ng5 loses
+a piece for a pawn, so it will promptly play something else,
+which is exactly what is desired.
+
+This is implemented with two (count 'em, two) files. One
+file "position.bin" is a binary file that contains the hash
+table entries, and it right at one megabyte in size, *max*.
+(16 bytes per hash entry X 65536 entries = exactly one meg,
+but I have 8 extra bytes for the FIFO queue implementation
+and to see how many entries are currently in the file if it
+is not full.
+
+The second file is "position.lrn" and is, you guessed it, a
+file that can be shared with others, just like book.lrn. It
+contains all information needed to reconstruct the position,
+the score, the depth, etc. and also included the pgn tags
+for who was what color and when the game was played...
+
+This data can be imported with the new "import" command (the
+old book learn <filename> is no longer around) which will
+import either book.lrn type data or position.lrn type data
+and can tell them apart without your having to do anything.
+The <clear> option is still there, should you want to use
+it, and simply removes the position.lrn and position.bin
+files before starting the import process for position learn-
+ing.
+
+This can be turned off, if you like, by checking out the
+"learn" command, which gives you the ability to turn off
+book learning (as it presently works), position learning,
+and the next book learning stage which will add to the book
+in addition to learning which book lines are good and bad.
+
+What is this new "result" learning?
+
+Result learning works just like normal book learning, except
+that if Crafty is checkmated or resigns, it will step back
+through the book line to find the last point where it had
+more than one move to choose from. It will flag the move it
+chose as "never play again".
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+This handles the case where the first ten non-book moves
+produce reasonable scores, but the position is one that
+Crafty simply can't handle very well. If it loses such a
+game, it will still vary the next time this opening is
+played, as otherwise it would possibly repeat the same open-
+ing, and would certainly repeat the remainder of the game.
+
+All three learning modes are turned on by default, although
+any of them can be disabled with the appropriate command
+option to "learn".
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
projects / packages / crafty.git / blobdiff