WebSVN – Games.Chess Giants – Blame – /engines/Crafty/readme.html

Rev	Author	Line No.	Line
31	pmbaty	1	<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
		2	<html> <head>
		3	<title> Crafty Command Documentation (version 18)
		4	</title>
		5	</head>
		6
		7	<body>
		8	<h1> Crafty Command Documentation
		9	</h1>
		10
		11	<!--- Note that I have put "Crafty" into <cite></cite>. This is
		12	logical, as a computer program with source code provided is not less
		13	than a book. On the other hand, maybe the document looks a bit garish
		14	as a result? A matter of taste. ---JM. --->
		15
		16	<cite>Crafty</cite> is nothing more than a long-time hobby of mine,
		17	dating back to <cite>Blitz</cite> and later <cite>Cray Blitz</cite>.
		18	People ask me how I keep doing this, and that is the one question that
		19	generally leaves me at a loss for words.
		20
		21	<p>Perhaps the most common question I'm asked is "is this version of
		22	<cite>Crafty</cite> some dumbed-down version of what you play on ICC
		23	or what you use at a computer chess event?" The answer is a
		24	resounding <strong>NO</strong>. The current version is
		25	<em>exactly</em> what is running on ICC under this version number.
		26	Note that a new version can, on occasion, introduce weaknesses or
		27	outright bugs that were not present in previous "gold" versions. As a
		28	result, you should be careful to back up your "favorite" before trying
		29	the latest and greatest. If you aren't satisfied with the new
		30	version, you can then go back to what you believe is a better version.
		31
		32	<p>If you are looking for the strongest playing computer chess
		33	program available, you should likely look to <cite>Fritz</cite>,
		34	<cite>Rebel</cite>, <cite>Tiger</cite>, and the other commercial
		35	entries. There you will find strong opponents with polished
		36	interfaces that have been tested in a systematic and careful way. If
		37	you are looking for a program that plays good chess, has a reasonable
		38	set of features for you to use, is available in source form, and one
		39	where the author welcomes feedback, code or suggestions, then you are
		40	at the right place. I welcome comments and suggestions, and also
		41	feedback from ideas you try yourself that seem to work.
		42
		43	<p><cite>Crafty</cite> is a state-of-the-art computer chess program,
		44	and uses all of the search algorithms you have probably read about,
		45	negascout search, killer/history move ordering, SEE (Static Exchange
		46	Evaluation) quiescence move ordering and pruning, hash
		47	(transposition/refutation) tables as well as evaluation caches,
		48	selective extensions, recursive null-move search, and a host of other
		49	features that have been used and are still being used in most computer
		50	chess programs. If it's not in <cite>Crafty</cite>, either it is on
		51	the "to do" list, or it has been tried, found wanting, and discarded.
		52
		53	<p>Chess knowledge is growing, and suggestions (or even better, real
		54	code) are welcome. This is the best place to contribute your ideas,
		55	because knowledge can be used to supplant search and make it play
		56	better. The evaluation is probably the easiest place to start
		57	studying <cite>Crafty</cite> because of the comments and simplicity of
		58	using bitmaps, once you get "into" them.
		59
		60	<p>My purpose for doing this is an exercise in computer chess
		61	efficiency. I can't begin to count the number of people I know that
		62	started from scratch to write a chess program. Even larger is the
		63	group that started from scratch, and gave up before finishing, because
		64	of the basic size of the project.
		65
		66	<p><cite>Crafty</cite> offers everyone a very clean starting point,
		67	if you are fascinated by the bitmap chess board implementation (as I
		68	am). The search and quiescence code is reasonably straightforward, as
		69	is the evaluation.
		70
		71	<p>It offers a great starting point, so that if you are interested
		72	in trying a new search extension, you can be testing tomorrow, rather
		73	than next year, because you start with a fully functional chess engine
		74	that is not a "toy" application, but is a functional and "dangerous"
		75	chess player. It offers a rapid start, although you can certainly
		76	replace it piece by piece until it is "yours" if you want. It also
		77	offers a fairly complete set of commands and an interface for a GUI as
		78	well as support for chess server play, so that testing and debugging
		79	your new ideas is greatly simplified.
		80
		81	<p>If you'd like more information, please check out the
		82	<code>read.me</code> document and the <code>crafty.FAQ</code> that are
		83	distributed with <cite>Crafty</cite>. These contain recent news and
		84	specific instructions for commonly asked questions, like "where can I
		85	obtain tablebase files and how do I use them?"
		86
		87
		88
		89	<hr>
		90	<h2>How to play a game.</h2>
		91
		92	When you execute <strong>crafty</strong>, you will immediately be
		93	greeted by the prompt string <strong>white(1): </strong> and
		94	<cite>Crafty</cite> will wait for commands. This prompt means it is
		95	White on move, and we are at move #1 for White. You can first use any
		96	of the commands from the alphabetic command listing below to tailor
		97	the game to your liking (time control, hash table size, book
		98	randomness, etc.) and then you have two choices. If you want to play
		99	White, just enter your move, and <cite>Crafty</cite> will take it from
		100	there and make a move in response. You will then be prompted by
		101	<strong>white(2):</strong> and it is your move again. If you would
		102	prefer to play Black, just enter either <strong>move</strong> or
		103	<strong>go</strong> at the prompt and <cite>Crafty</cite> will move
		104	for that side rather than accepting a move from you. After it makes
		105	its move for White, you will then see the prompt
		106	<strong>black(1):</strong> indicating it is now time for Black's first
		107	move. You can enter a move, or you can once again enter
		108	<strong>move</strong> or <strong>go</strong> and <cite>Crafty</cite>
		109	will again move for the current side, change sides, and prompt you for
		110	what to do next.
		111
		112	<p>If you find yourself continually using a set of commands to
		113	configure <cite>Crafty</cite> to play as you want, you can put these
		114	commands in a startup file called <code>.craftyrc</code>
		115	(<cite>Unix</cite>) or <code>crafty.rc</code>
		116	(<cite>DOS</cite>/<cite>Windows</cite>). The format for this file is
		117	just like you would type the commands at the keyboard, with the
		118	requirement that the last line of the file must be
		119	<strong>exit</strong> on a line by itself. Using this, each time you
		120	start <cite>Crafty</cite>, it will first execute the commands from
		121	this file before it prompts you for input.
		122
		123	<p>While <cite>Crafty</cite> is running, you can control what it
		124	displays, but here's a couple of samples to explain what it is saying
		125	and why:
		126
		127	<pre><tt><strong>
		128	depth time score variation (1)
		129	book moves {d4, c3, Nc3, d3, b3, c4, g3, b4, Be2, Bb5}
		130	book 0.0s 70% d4
		131
		132	White(3): d4
		133	time used: 0.01
		134	</strong></tt></pre>
		135
		136	This is the normal output for those cases where <cite>Crafty</cite> is
		137	in book. The book moves line gives the set of book moves that made
		138	the first selection cut (see the book selection explanation given
		139	later), followed by the move actually played, in this case d4.
		140
		141	<p>If <cite>Crafty</cite> is out of book, then the output looks
		142	somewhat different as given below:
		143
		144	<pre><tt><strong>
		145	depth time score variation (1)
		146	4-> 0.81 2.09 6. dxe4 Bxe4 7. Rad8 Qf2 8. Qb5
		147	5 1.37 2.41 6. dxe4 Bxe4 7. Ne5 Qf4 8. Bxe4+ Qxe4 9. f5
		148	5-> 1.88 2.41 6. dxe4 Bxe4 7. Ne5 Qf4 8. Bxe4+ Qxe4 9. f5
		149	6 7.38 -- 6. dxe4
		150	6 11.90 1.97 6. dxe4 Bxe4 7. Rab8 Qf2 8. Qc7 Nc5 9. Qe5
		151	6 12.92 ++ 6. Ne5
		152	6 13.71 2.23 6. Ne5 Qg2 7. Ng6 h5 8. Nh4 Qg4
		153	6-> 15.59 2.23 6. Ne5 Qg2 7. Ng6 h5 8. Nh4 Qg4
		154	time: 15.60 cpu:99% mat:1 n:246565 nps:15927
		155	ext-> checks:4706 recaps:1336 pawns:0 1rep:301
		156	nodes full:45951 quiescence:200614 evals:104657
		157	endgame tablebase-> probes done: 0 successful: 0
		158	</strong></tt></pre>
		159
		160	Let's take this stuff one line at a time.<ul>
		161
		162	<li> Lines that have something like <samp>4-></samp> in the depth
		163	column are printed when that iteration (depth) is completely finished.
		164
		165	<li> The time and score columns should be obvious as to their
		166	meaning as is the PV, the sequence of moves that led to this score.
		167	One note about the "score" column. As of version 18,
		168	<cite>Crafty</cite> displays the score with + values good for White,
		169	- values good for Black, no matter which side it is playing in the
		170	game. All output now follows this convention, from playing, to
		171	analysis mode, to annotating your games, to whispering/kibitzing on
		172	the chess servers, and so forth. This is unlike other engines, but
		173	once you get used to it, it is much less confusing when you remember
		174	that negative scores are good for Black and bad for White, and
		175	vice-versa.
		176
		177	<li> The line that has <samp>--</samp> in the score column means that
		178	when we started depth 6, dxe4 turned out to be worse than we thought
		179	(notice score dropped from 2.411 last search to 1.972 for this move
		180	this search.) To resolve this, <cite>Crafty</cite> lowers the lower
		181	search bound (alpha) and re-searches the move to find the score.
		182
		183	<li> The line with <samp>++</samp> means that this move
		184	(<samp>Ne5</samp>) is better than the best move so far, so
		185	<cite>Crafty</cite> raises the upper search bound (beta) and
		186	re-searches this move to find the new score.
		187
		188	<li> The first line of statistics gives the total time taken for
		189	this search, the cpu percentage which should stay at 98-100%
		190	unless your machine is heavily loaded or unless <cite>Crafty</cite>
		191	is in an endgame that is having lots of contact with endgame
		192	databases. If this drops below 98%, it means that
		193	<cite>Crafty</cite> is not getting full CPU usage and will be
		194	playing weaker than normal. The mat:1 is simply the true material
		195	score, since <cite>Crafty</cite>'s positional scores are often
		196	larger than a pawn.
		197
		198	</ul>
		199
		200
		201
		202
		203	<hr>
		204	<h2>Alphabetic Listing of Commands</h2>
		205
		206	<dl>
		207
		208	<!-- This is formatted as a `definition list', quite properly.
		209	However, there is a problem about what tags to wrap around the
		210	`definiendum'. The general style, `dfn', is not quite suitable for
		211	computer commands. The logical choice, `code', does not show up well
		212	in Lynx, nor in the default settings of Mozilla. So I have cheated
		213	slightly, and used `strong'. Further, it all looks better with the
		214	crude expedient of putting an empty paragraph at the end of each
		215	definition. ---JM. --->
		216
		217
		218	<a name="alarm"></a>
		219	<dt> <strong>alarm on</strong>\|<strong>off</strong>
		220
		221	<dd> This command is used to control <cite>Crafty</cite>'s "beep"
		222	after it makes a move. Turning this off will make <cite>Crafty</cite>
		223	"quiet" when it plays, but also makes it easy to miss a move if you
		224	are using <cite>Crafty</cite> to play in a tournament. This is
		225	primarily designed to make <cite>Crafty</cite> tolerable during late
		226	night matches.
		227
		228
		229	<p>
		230	<a name="analyze"></a>
		231	<dt> <strong>analyze</strong>
		232
		233	<dd> This command puts <cite>Crafty</cite> into analyze mode. In this
		234	mode, <cite>Crafty</cite> starts computing for whichever side is on
		235	move, and it continues computing and showing its analysis until a move
		236	is entered. This move is made, <cite>Crafty</cite> changes sides, and
		237	starts thinking and printing analysis all over, but for the other side
		238	now.
		239
		240	<p>This command is useful to play through a game, because you get
		241	instant feedback when you try a move. If you want to try a different
		242	move from the one you just entered, use the <strong>back</strong>
		243	command to back up one move, or use <strong>back <n></strong> to
		244	back up <n> moves. Note that one move is a single move for the
		245	last player, not a move for both sides. To unmake the most recent 2
		246	moves (one for Black, one for White) use <strong>back 2</strong>.<p>
		247
		248
		249
		250	<a name="annotate"></a>
		251	<dt> <strong>annotate</strong> \| <strong>annotateh</strong>
		252	<var><filename> <colors</var> \| <var>name> <moves>
		253	<margin> <time></var>
		254
		255	<dd> This command is used to annotate (make comments in) a game that
		256	has already been played.<p><dl>
		257
		258	<dt> <strong>annotate</strong>
		259	<dd> produces a file with the .can extension added to the original
		260	name. This file will contain pure ascii information from the
		261	annotation pass.
		262
		263	<dt> <strong>annotateh</strong>
		264	<dd> produces an HTML file instead (with the .html extension). This
		265	includes the normal output, plus a nice bitmapped graphical board
		266	display for every position where <cite>Crafty</cite> had 'something to say'.
		267
		268	<dt> <var><filename></var>
		269	<dd> is the name of the file that has the game moves stored in it.
		270	This should be a PGN-compatible file, although <cite>Crafty</cite> can
		271	read nearly any file with chess moves and convert it to pgn using the
		272	<a href="#read"><strong>read</strong></a> and <a
		273	href="#savegame"><strong>savegame</strong></a> commands to perform the
		274	conversion.
		275
		276	<dt> <var><colors</var> \| <var>name></var>
		277	<dd> indicates which side <cite>Crafty</cite> will annotate. The
		278	valid choices are <strong>w</strong>, <strong>b</strong>, and
		279	<strong>wb</strong>/<strong>bw</strong> for White only, Black only,
		280	and both, respectively. <cite>Crafty</cite> will search and produce
		281	results for the indicated color only, making moves for the other side
		282	silently as they are read in. Alternatively, you can specify the
		283	player's name (useful if you want to annotate several of your own
		284	games in one large pgn file, for example, and you alternated colors so
		285	that you can't pick the right one easily). <cite>Crafty</cite> will
		286	then figure out which side to annotate for in each game. Note that
		287	the name is case-sensitive, but that you only have to enter a string
		288	that is unique in the name field. IE if one name is "Anatoly Karpov"
		289	and the other is "unknown" then specifying Karpov as the name would be
		290	sufficient. If the same 'string' appears in both names,
		291	<cite>Crafty</cite> will complain.
		292
		293	<dt><var><moves></var>
		294	<dd> indicates the moves that should be annotated. If this is a
		295	single integer, annotation starts at this move number (for the color
		296	given above) and proceeds for the rest of the game. If a range is
		297	given, as (20-33), then only moves 20-33 inclusive are annotated. To
		298	annotate the complete game, you can use 1-999.
		299
		300	<dt> <var><margin></var>
		301	<dd> gives a score "window" that controls whether
		302	<cite>Crafty</cite> will produce comments (see below). The larger
		303	this number this number, the fewer annotations <cite>Crafty</cite>
		304	will produce. A negative number will result in an annotation for
		305	every move selected.
		306
		307	<dt> <var><time></var>
		308	<dd> indicates the time limit for each search. Since each move
		309	selected requires two searches, you can take the number of moves,
		310	double this number and multiply by <time> to determine how long
		311	the annotation process will take. This time is in seconds.
		312
		313	</dl>
		314
		315
		316	<p>How it works. Suppose you use the command <strong>annotate game1
		317	w 1-999 1.000 30</strong>. This asks <cite>Crafty</cite> to read the
		318	file "game1", and annotate the white moves for the entire game. The
		319	margin is 1 pawn and the search time limit is 30 seconds. The output
		320	for the annotate command is found in <filename>.can, in this
		321	case this is game1.can.
		322
		323	<p><cite>Crafty</cite> first searches the move actually played in
		324	the game to determine the score for it. <cite>Crafty</cite> then
		325	searches the same position, but tries all legal moves. If the score
		326	for the best move found in this search is greater than the score for
		327	the move actually played plus the margin, then a comment is added to
		328	the output file. This output file is quite short, with all the game
		329	moves (plus any PGN tags in the original, for identification purposes)
		330	plus the brief comments.
		331
		332	<p>An annotation looks like this: <strong>{real_value
		333	(depth:best_value PV moves)}</strong>
		334
		335	<ul>
		336
		337	<li> <strong>real_value</strong> is the score for the move actually
		338	played.
		339
		340	<li> <strong>depth</strong> is the depth <cite>Crafty</cite>
		341	searched to produce the best_value and PV for what it thinks is the
		342	best sequence of moves for both sides.
		343
		344	</ul>
		345
		346	<p>If you set <var><margin></var> to 1.000, you are asking
		347	<cite>Crafty</cite> to only annotate moves that either lost a pawn or
		348	more, or moves that failed to win a pawn or more. If you set
		349	<var><margin></var> to .300, you are asking for annotations for
		350	any move that makes the score drop about 1/3 of a pawn below the value
		351	for the best move <cite>Crafty</cite> found.
		352
		353	<p>If you have other moves you would like to see analyzed during
		354	this annotate process, at the point where the move can be played,
		355	insert it into the PGN file as an analysis comment, surrounded by ()
		356	or {} characters. <cite>Crafty</cite> will produce analysis for this
		357	move as well. If more than one move appears inside a single set of
		358	delimiters, only the first will be analyzed. To force
		359	<cite>Crafty</cite> to analyze more than one move, enter them like
		360	this: (move1) (move2) as though they were two separate comments.<p>
		361
		362
		363
		364	<a name="ANSI"></a>
		365	<dt><strong>ANSI on</strong> \| <strong>off</strong>
		366
		367	<dd> This command is used to control whether or not
		368	<cite>Crafty</cite> attempts to display its move in reverse video or
		369	not. For PC's, Linux, and most Unix boxes, this works fine. Should
		370	you find yourself playing <cite>Crafty</cite> via a dumb terminal,
		371	this might hose the terminal and interfere with your ability to see or
		372	input moves. If moves are not displayed in reverse video, it's
		373	probably wise to turn this off to avoid hanging the terminal you are
		374	using.<p>
		375
		376
		377
		378	<a name="black\|white"></a>
		379	<dt> <strong>black</strong> \| <strong>white</strong>
		380
		381	<dd> This command simply toggles the side on move. if it is White to
		382	move, and you enter white, nothing happens. If it is White to move
		383	and you enter black, then it becomes Black's turn to move immediately
		384	from the same position. Used only infrequently.<p>
		385
		386
		387
		388	<a name="book"></a>
		389	<dt> <strong>book</strong>
		390
		391	<dd> (See the <a href="#Opening Book">Opening Book Setup and Usage</a>
		392	section near the end of this document for a full explanation of this
		393	command and its many options.) Note that there are special commands
		394	available (only on the command line, not in the
		395	<code>crafty.rc</code>/<code>.craftyrc</code> files) to direct
		396	<cite>Crafty</cite> to specific directories for the book files
		397	(<code>bookpath=/a/b/c</code>), the tablebase files
		398	(<code>tbpath=/i/j/k</code>) and the log files
		399	(<code>logpath=/x/y/z</code>). Note that these commands can only be
		400	used on the command line, because they must be executed before the
		401	engine is initialized. Putting them in the
		402	<code>crafty.rc</code>/<code>.craftyrc</code> file will produce error
		403	messages without affecting how the files are opened.
		404
		405	<p>If you need to specify multiple directories (tbpath only) you may
		406	do so by using "<code>tbpath=path1:path2:path3:etc</code>" or else use
		407	the more Unix-like "<code>tbpath=(path1:path2:path3:etc)</code>"
		408	instead. The paths are separated by ":" (colon) characters and
		409	everything is case-sensitive as usual. For
		410	<cite>DOS</cite>/<cite>Windows</cite> users, the separator can be a
		411	semi-colon (;) or a comma (,) to avoid the drive designation
		412	ambiguity.<p>
		413
		414
		415
		416	<a name="cache"></a>
		417	<dt> <strong>cache</strong> [=] <var><N></var>
		418
		419	<dd> This command is used to alter the cache size used for <a
		420	href="#egtb">endgame database</a> probes. <var><N></var> can be
		421	a simple integer, representing the number of bytes to use or it can be
		422	specified as nK or nM representing n * 1024 bytes or n * 1024 * 1024
		423	bytes. This should be in multiples of the database "chunk" size,
		424	which might vary. Using the nM form guarantees that you will have a
		425	reasonable number.<p>
		426
		427
		428
		429	<a name="clock"></a>
		430	<dt> <strong>clock</strong> <var><ctime> <otime></var>
		431
		432	<dd> This command is primarily intended for use when
		433	<cite>Crafty</cite> is playing in a tournament, such as the WMCCC or
		434	WCCC events. If the operator is somewhat slow in entering moves, or
		435	forgets to stop the clock after making a move for <cite>Crafty</cite>,
		436	the chess clock for the game will drift from the values that
		437	<cite>Crafty</cite> maintains internally. <var><ctime></var> is
		438	the time (in minutes or hh:mm format) <cite>Crafty</cite> has left
		439	until the next time control, and <var><otime></var> is the
		440	opponent's remaining clock time. This command can be used at any
		441	time, but will only affect the time per move after
		442	<cite>Crafty</cite> makes the current move and starts to think about
		443	what the opponent might do next.<p>
		444
		445
		446
		447	<a name="computer"></a>
		448	<dt> <strong>computer</strong>
		449
		450	<dd> This command usually comes from <a
		451	href="#xboard">XBoard/WinBoard</a>, but can be used at any time to
		452	tell <cite>Crafty</cite> it is playing a computer. This will prevent
		453	some things from happening, such as a draw score that varies, as well
		454	as adjusting the book selection code to be more selective in what it
		455	plays.<p>
		456
		457
		458
		459	<a name="display"></a>
		460	<dt> <strong>display</strong>
		461
		462	<dd> This command is used to display the game board. This board is
		463	displayed using the ICS style #1 type of ASCII display, with White
		464	always at the bottom of the screen, Black at the top. Very unusable
		465	to play a game with, but good to verify a position after it has been
		466	set up.
		467
		468	<p>This command is also used to display the various piece/square
		469	tables, by typing <strong>display</strong> <var><piece></var>
		470	where <var><piece></var> is replaced by <strong>pawn</strong>,
		471	<strong>knight</strong>, <strong>bishop</strong>,
		472	<strong>rook</strong>, <strong>queen</strong> or
		473	<strong>king</strong>. The board is oriented in the same way as the
		474	display board with a one-to-one correspondence between the squares.
		475	Perhaps useful for curiosity, but not for anything else. These values
		476	can not be modified by the user.
		477
		478	<p>The final version of this command is used to control what kind of
		479	output you will see when <cite>Crafty</cite> runs. Currently the
		480	following options are available.
		481
		482	<dl>
		483
		484	<dt> <strong>display time</strong>:
		485
		486	<dd> this will make <cite>Crafty</cite> display the amount of
		487	time each side takes after making a move.
		488
		489
		490	<dt> <strong>display changes</strong>:
		491
		492	<dd> this will make <cite>Crafty</cite> display the PV each time
		493	it changes during the search, including when a move fails high or
		494	becomes a new best move.
		495
		496
		497	<dt> <strong>display variation</strong>:
		498
		499	<dd> this will make <cite>Crafty</cite> display the PV at the end of each
		500	iteration, but it will only show the best PV for the entire
		501	iteration, not all of the changes.
		502
		503
		504	<dt> <strong>display stats</strong>:
		505
		506	<dd> this enables basic search statistics output including time,
		507	nodes and so forth.
		508
		509
		510	<dt> <strong>display extstats</strong>:
		511
		512	<dd> this enables extended search stats including the hashing
		513	statistics, search extension statistics and so forth.
		514
		515
		516	<dt> <strong>display movenum</strong>:
		517
		518	<dd> causes all PV output to have move numbers embedded in them to
		519	make the PV possibly easier to read. This causes the PV to look
		520	like this: <strong>12. ... Nxe4 13. Bxe4 h6</strong> rather than
		521	simply <strong>Nxe4 Bxe4 h6</strong>. This is very helpful when
		522	playing on a server and whispering or kibitzing analysis. It
		523	will also be useful when <cite>Crafty</cite> is run from within a
		524	database program as the move numbers will sync up with the actual
		525	game.
		526
		527
		528	<dt> <strong>display moves</strong>:
		529
		530	<dd> will display each root move as it is searched, along with
		531	updating the search time at the bottom of the screen, so you can
		532	see what move is currently being analyzed.
		533
		534
		535	<dt> <strong>display general</strong>:
		536
		537	<dd> will display general information messages whenever
		538	<cite>Crafty</cite> wants to tell you something (ie "clearing
		539	hash tables" or other such things like "Mate in n moves."
		540
		541	</dl>
		542
		543	If you put a <strong>no</strong> in front of any of these options,
		544	that will disable that particular type of output.<p>
		545
		546
		547
		548	<a name="draw"></a>
		549	<dt> <strong>draw</strong>
		550
		551	<dd> offers <cite>Crafty</cite> a draw. It generally will look at the
		552	value returned by the last search, and compare it with the value
		553	returned by an internal function DrawScore(). If the search value is
		554	not above this result, then <cite>Crafty</cite> will accept the draw.
		555	If the search value is above the theoretical value for a draw,
		556	<cite>Crafty</cite> will decline the draw. Note that
		557	<cite>Crafty</cite> will offer draws based on internal analysis. When
		558	it offers a draw, you can respond with <strong>"draw"</strong>
		559	although the game does not really end until you exit
		560	<cite>Crafty</cite>.<p>
		561
		562
		563
		564	<a name="drawscore"></a>
		565	<dt> <strong>drawscore</strong> <var>N</var>
		566
		567	<dd> sets the draw score (or contempt factor) to <var>N</var>. If you
		568	want <cite>Crafty</cite> to avoid draws, set this number to something that is
		569	negative. IE -50 says that a repetition (draw) is the same as being
		570	1/2 pawn down. Setting it to +100 will make it try very hard to draw
		571	because that looks like it is winning a pawn when it does so. Note
		572	that this is dangerous (either way) as a -50 in a king and pawn ending
		573	is very likely dead lost... and a repetition is better.<p>
		574
		575
		576
		577	<a name="echo"></a>
		578	<dt> <strong>echo</strong> <var><text></var>
		579
		580	<dd> This command is normally used inside a command file that you are
		581	going to use to "feed" <cite>Crafty</cite> some positions for analysis
		582	or whatever. Since <cite>Crafty</cite> depends on the operating
		583	system to echo commands as they are typed, commands read in from a
		584	file are "invisible." This gives you the ability to insert commands
		585	into such a file so that <cite>Crafty</cite> displays a message on the
		586	screen to give you an idea of where it is in processing the file.<p>
		587
		588
		589
		590	<a name="edit"></a>
		591	<dt> <strong>edit</strong>
		592
		593	<dd> This command has been "cloned" from <cite>GnuChess</cite> to
		594	provide an interface with <a href="#xboard">Xboard</a>. After
		595	entering the <strong>edit</strong> command, you are in "edit.white"
		596	mode, where any piece/square combination you enter will add the
		597	indicated white piece on the given square. Piece/squares are entered
		598	as "qa3", or "bc4" for example. This puts a white queen on a3 and a
		599	white bishop on c4. Once all white pieces are entered, typing a "c"
		600	changes to "edit.black" mode where piece/square combinations now place
		601	black pieces. Typing a "." character exits edit mode. To clear the
		602	board initially, you use the "#" character.
		603
		604	<p>Here's a sample to set up the original starting position, after
		605	White has played 1. e4, but no other moves have been played.
		606
		607	<pre><strong>
		608	edit
		609	#
		610	ra1 nb1 bc1 qd1 ke1 bf1 ng1 rh1
		611	pa2 pb2 pc2 pd2 pe4 pf2 pg2 ph2
		612	c
		613	ra8 nb8 bc8 qd8 ke8 bf8 ng8 rh8
		614	pa7 pb7 pc7 pd7 pe7 pf7 pg7 ph7
		615	.
		616	</strong></pre>
		617
		618	Note that input is free form, so piece/squares can be entered one per
		619	line or all on one line. Ditto for the #, c, and . special
		620	characters. Note also that there is no way to enter castling status
		621	here. It is far better to use the <a href="#setboard">
		622	<strong>setboard</strong></a> command which uses a FEN-like syntax and
		623	allows you to set both castling and en passant status.<p>
		624
		625
		626
		627	<a name="egtb"></a>
		628	<dt> <strong>egtb</strong>
		629
		630	<dd> This command enables the endgame databases. <cite>Crafty</cite>
		631	will use the "tbpath" directory (if provided) to locate and register
		632	all of the databases you have downloaded. It will report the largest
		633	class it found, as in "5 piece tablebase files found" if you
		634	downloaded at least one 5-piece file. If you use this command to
		635	enable databases, you should also consider using the <a
		636	href="commands.html#cache"><strong>cache</strong></a> command to
		637	specify the egtb cache size.<p>
		638
		639
		640
		641	<a name="quit"></a> <dt> <strong>end</strong> \| <strong>quit</strong>
		642
		643	<dd> These commands are used to terminate <cite>Crafty</cite>. Note
		644	that you can resume a game later without having to replay the moves,
		645	by starting <cite>Crafty</cite> using the <strong>crafty c</strong>
		646	command. It will immediately read in the moves for the last game,
		647	although you will have to set the time controls and clock time
		648	remaining yourself.<p>
		649
		650
		651
		652	<a name="evaluation"></a>
		653	<dt> <strong>evaluation</strong> <var>option <value></var>
		654
		655	<dd> This command is used to modify the evaluation scores.
		656
		657	<ul>
		658
		659
		660	<li> The option <strong>asymmetry</strong> is used to make
		661	<cite>Crafty</cite> evaluate king safety differently for each side.
		662
		663	<p><strong>evaluation asymmetry 25</strong> will increase the king
		664	safety scores for the opponent only, meaning it will pay less
		665	attention to its own king safety than to that of its opponent. This
		666	will make it play more aggressively.
		667
		668	<p><strong>evaluation asymmetry -25</strong> will reduce the king
		669	safety scores for the opponent by 25%, making it care more about
		670	its own king safety than that of its opponent. This will make it
		671	play more defensively.
		672
		673
		674	<li> The <strong>bscale</strong> option will adjust the scores for blocked
		675	pawns. The default value is 100. Increasing this will tend to make
		676	<cite>Crafty</cite> dislike blocked pawn positions more, which will
		677	lead to more open positions. Note that this only affects moves
		678	_after_ the opening book has been followed, which means that the
		679	position might be blocked before the evaluation term has a chance to
		680	affect the game.
		681
		682
		683	<li> The <strong>kscale</strong> option will adjust all king safety
		684	scores based on the 'value' entered. For example,
		685
		686	<dl>
		687
		688	<dt> <strong>evaluation kscale 50</strong>
		689	<dd> will reduce all king safety scores to 50% of their normal
		690	value.
		691
		692	<dt> <strong>evaluation kscale 133</strong>
		693	<dd> will increase all king safety scores to 133% of their normal
		694	values.<dd></dl>
		695
		696
		697	<li> The option <strong>tropism</strong> is used to scale king
		698	tropism scores. This will attract pieces toward kings. A value of
		699	100 means no change. other values are treated as a percentage (like
		700	scale) to increase (> 100) or decrease (<100) the king
		701	tropism scores.
		702
		703	</ul>
		704
		705	<p>When you use this command, you will see something like this:
		706
		707	<pre>
		708
		709	modified king-safety values:
		710	white: 0 4 16 26 39 45 58 77 87 90 93 96 100 103 106 109
		711	112 116 119 122 125 128 128 128 128 128 128 128 128 128 128 128
		712
		713	black: 0 5 20 32 48 56 72 96 108 112 116 120 124 128 132 136
		714	140 144 148 152 156 160 160 160 160 160 160 160 160 160 160 160
		715
		716	</pre>
		717
		718	Those values represent the king-safety evaluation as the king gets
		719	more and more exposed. This is always based on the fast that "crafty"
		720	will be the side on move when the search starts. In the above, it was
		721	White's move when this was typed, meaning that it appears that
		722	<cite>Crafty</cite> will be playing Black. Notice that White's king
		723	safety numbers are scaled by 20% to make it slightly more cautious
		724	about its own king. If you type <strong>go</strong> in this position,
		725	the scores get reversed as <cite>Crafty</cite>'s scores are always
		726	left alone (with the asymmetry option) and the opponent's scores are
		727	scaled down as indicated.
		728
		729	<p>You will see similar numbers (but not black and white sets) that
		730	represent the actual scores produced for king tropism. Note that
		731	pieces interact to choose which element of this vector is used, but in
		732	general, the more pieces are close to the king, the larger the element
		733	from this array.
		734
		735	<ul>
		736
		737	<li> The <strong>pscale</strong> option is used to scale normal pawn
		738	structure scoring in the same way as the other scaling options. 100
		739	is the default. Values less than 100 reduce this term, values over
		740	100 inflate it.
		741
		742
		743	<li> The <strong>ppscale</strong> option is used to scale some
		744	passed pawn scoring in the same way as the other scaling options.
		745	100 is the default. Values less than 100 reduce this term, values
		746	over 100 inflate it. This mainly effects outside passed
		747	pawns/protected passed pawns. The normal pawn scoring computes the
		748	value of a passed pawn. This term is then used to scale those terms
		749	that modify this value further, such as two connected passed pawns
		750	on the 6th, or a passed pawn with the king supporting it in an
		751	endgame.
		752
		753	</ul><p>
		754
		755
		756
		757	<a name="extensions"></a>
		758	<dt> <strong>extensions</strong> <var><type> <value></var>
		759
		760	<dd> This command is used to control the extension depth for the
		761	various extensions done in <cite>Crafty</cite>'s search. The
		762	extensions are set as decimal numbers that represent plies (or
		763	fractions of plies) to extend for each particular reason. Most
		764	default to 1.0 and .75, but any value can be used. Note that values
		765	> 1.0 are _very_ dangerous as they can cause the search to become
		766	non-terminating (<cite>Crafty</cite> will stop when it runs out of
		767	time for the move, but it might not be able to get anything useful
		768	from such a search).
		769
		770	<p>These extensions are presently limited to a maximum of one ply of
		771	extensions at any point in the tree. IE no matter what you set these
		772	values to, they can not exceed one ply at present.
		773
		774	<dl>
		775
		776	<dt> <strong>incheck</strong>
		777
		778	<dd> This is the amount to extend when the side on move makes a move
		779	that leaves the opponent in check. Note that <cite>Crafty</cite>
		780	extends on the ply where the check is played, not on the next ply
		781	where the opposite side is in check.
		782
		783	<dt> <strong>onerep</strong>
		784	<dd> This is the one-reply-to-check extensions, and is done at the
		785	point where one side is in check and has exactly one legal move to
		786	escape from the check.
		787
		788	<dt> <strong>pushpp</strong>
		789	<dd> This is the extension used for certain passed pawn pushes in
		790	the endgame.
		791
		792	<dt> <strong>recapture</strong>
		793	<dd> This is the recapture extension, and is applied when the
		794	current move recaptures an equal-valued piece that made a capture at
		795	the previous ply. IE BxN, PxB. Note that this can only be applied
		796	once for every two plies so that BxN, BxB, NxB, NxN won't look like
		797	three recaptures.
		798
		799	<dt> <strong>mate</strong>
		800	<dd> This is the mate threat extensions and is applied when a null
		801	move search returns -MATED, which means that doing nothing gets the
		802	side on move mated. The opponent must have some sort of serious mate
		803	threat in such a position.
		804
		805	</dl><p>
		806
		807
		808
		809	<a name="flag"></a>
		810	<dt> <strong>flag on</strong>\|<strong>off</strong>
		811
		812	<dd> This command is used to force <cite>Crafty</cite> to end a game
		813	where the opponent runs out of time with <a
		814	href="#xboard">WinBoard/XBoard</a> (<strong>on</strong>) or to ignore
		815	this (<strong>off</strong>) if desired.<p>
		816
		817
		818
		819	<a name="force"></a>
		820	<dt> <strong>force</strong> [<var>move</var>]
		821
		822	<dd> This command is used to force <cite>Crafty</cite> to play a move
		823	that is different from the one chosen and played by the tree search.
		824	If [<var>move</var>] is given, and it is a legal move,
		825	<cite>Crafty</cite> will retract its last move and make this move
		826	instead. It does not change the side on move, but does change the
		827	position of course. If [<var>move </var>]is not given,
		828	<cite>Crafty</cite> will prompt you for a move to make.<p>
		829
		830
		831
		832	<a name="hash"></a>
		833	<dt> <strong>hash=</strong><var>x</var> and
		834	<strong>hashp=</strong><var>x</var>
		835
		836	<dd> These commands are used to adjust the size of the hash tables in
		837	<cite>Crafty</cite>: <strong>hash</strong> modifies the size of the
		838	transposition/refutation table, while <strong>hashp</strong> modifies
		839	the size of the pawn structure/king safety hash table. The size
		840	<var>x</var> may be entered as one of the following two types of
		841	values: nnnK where nnn is an integer indicating how many Kbytes
		842	<cite>Crafty</cite> should use for this hash table; nnnM where nnn is
		843	an integer indicating how many Mbytes <cite>Crafty</cite> should use.
		844
		845	<p>The transposition/refutation table is the more critical of the
		846	two, because it directly affects search efficiency, particularly in
		847	the endgame. For this reason this should be maximized. The most
		848	effective size for this hash table is 3/4 of your available memory.
		849	If you don't know how to figure this out, but know that you have 16
		850	megs for example, they you can say <strong>hash=16M</strong> and
		851	<cite>Crafty</cite> will round that down to 12M, which is 3/4 of a
		852	power of two size. If you study the sizes that are possible, you will
		853	find 3M, 6M, 12M, 24M, 48M, and so forth. Anything up to, but not
		854	including, the next size will be rounded down to the next lower size.
		855	hashp should be set to approximately 1/2 of what is left. For
		856	example, the P6 <cite>Crafty</cite> runs on when playing on ICC often
		857	uses <strong>hash=48M</strong> and <strong>hashp=8M</strong>. The
		858	only thing to watch for is that if you make this too large,
		859	particularly under <cite>Windows</cite>, performance will suffer badly
		860	because of paging I/O overhead. When <cite>Crafty</cite> is searching
		861	in a normal (non-book, non-endgame database) position, the disk light
		862	should not be on, indicating lots of I/O.
		863
		864	<p>There is no danger in making this table too large, although you
		865	have to watch out because if <cite>Crafty</cite> barely fits in
		866	memory, doing something else on the machine can cause
		867	<cite>Crafty</cite> to be swapped out completely or partially,
		868	depending on the operating system you are using. If you are going to
		869	use the machine for anything else while <cite>Crafty</cite> is
		870	running, it is better to "pretend" that the machine only has 1/2 of
		871	the memory it actually does when computing the size of the hash tables
		872	you want to use.<p>
		873
		874
		875
		876	<a name="help"></a>
		877	<dt> <strong>help</strong>
		878
		879	<dd> This command displays multiple pages of one-line help, one
		880	command per line. If a line ends with [help], then you can use help
		881	followed by the specific command to get detailed help.<p>
		882
		883
		884
		885	<a name="history"></a>
		886	<dt> <strong>history</strong>
		887
		888	<dd> This command displays the history in a vertical column with one
		889	move for White and one per Black per line. There are other ways to
		890	display the current game moves and also to save them in files that are
		891	explained later.<p>
		892
		893
		894	<a name="import"></a>
		895	<dt> <strong>import</strong> <var><filename></var>
		896	[<strong>clear</strong>]
		897
		898	<dd> This command is used to import any sort of learning data that
		899	<cite>Crafty</cite> supports, which currently includes book learning
		900	data and position learning data. This command reads the appropriate
		901	<var><filename></var> and imports that learned data, just as
		902	though <cite>Crafty</cite> had learned it by playing the games. The
		903	[<strong>clear</strong>] option, if specified, causes all old learned
		904	results to be cleared before the import operation, otherwise the
		905	imported data is simply added to what is already present.<p>
		906
		907
		908
		909	<a name="info"></a>
		910	<dt> <strong>info</strong>
		911
		912	<dd> This command is used to display information about
		913	<cite>Crafty</cite> and the current game. Such things as the time
		914	control, the time left on the clocks and other information is
		915	shown.<p>
		916
		917
		918
		919	<a name="input"></a>
		920	<dt> <strong>input</strong> <var><filename></var>
		921
		922	<dd> This command is used to redirect the console input I/O stream
		923	from the keyboard to a file. <cite>Crafty</cite> will then read
		924	commands from this file, rather than from the keyboard, and execute
		925	them just as though they were typed in. Such a command file must be
		926	terminated by an <strong>"exit"</strong> command (no quotes) as the
		927	last command in the file. This reverts the input stream back to the
		928	keyboard, and prompts you for another command or move.
		929
		930	<p>This command might be used to configure <cite>Crafty</cite> for a
		931	specific time control, by putting the appropriate time control
		932	commands in the file, or to customize the hash table sizes as
		933	needed.<p>
		934
		935
		936
		937	<a name="learn"></a>
		938	<dt> <strong>learn</strong> <var>n</var>
		939
		940	<dd> controls the learning facilities in <cite>Crafty</cite>.
		941	Currently this is a 3-bit boolean switch, bit 1 (001) controls book
		942	learning, bit 2 (010) controls position learning, and bit 3 (100)
		943	controls result learning. <strong>learn=0</strong> disables all
		944	learning, <strong>learn=1</strong> enables book learning only,
		945	<strong>learn=2</strong> enables position learning only, and
		946	<strong>learn=4</strong> enables result learning. Add the values
		947	together to turn on more than one type of learning (default=7 to
		948	enable everything).<p>
		949
		950
		951
		952	<a name="level"></a>
		953	<dt> <strong>level</strong> <var><m> <t> <inc></var>
		954
		955	<dd> This command was taken directly from <cite>GnuChess</cite> so
		956	that the <cite>Xboard</cite>/<cite>WinBoard</cite> interface would
		957	interface with <cite>Crafty</cite>. There are other better ways to
		958	set the time, but this one is well-known. The three parameters are
		959	<var><m></var> (number of moves in the game)
		960	<var><t></var> initial time on the clock. After
		961	<var><m></var> moves are made, this amount of time is added to
		962	the clock again. <var><inc></var> is the Fischer-Clock
		963	increment that is added back to each clock after a move is made. It
		964	may be zero for a non-increment game.
		965
		966	<p> Examples:
		967
		968	<pre>
		969
		970	<strong>level 0 5 0</strong> (ICS 5 0 game)
		971	<strong>level 0 5 3</strong> (ICS 5 3 game)
		972	<strong>level 0 15 30</strong> (ICS 15 30 game)
		973
		974	</pre><p>
		975
		976
		977	<a name="list"></a>
		978
		979	<dt> <strong>list GM</strong> \| <strong>IM</strong> \|
		980	<strong>C</strong> \| <strong>AK</strong> \| <strong>S +</strong><var>name</var>
		981	[<strong>+</strong><var>name</var> ...]
		982	<strong>-</strong><var>name</var> [<strong>-</strong><var>name</var>
		983	<strong>...</strong>]
		984
		985	<dd> This command is used to maintain the internal "lists"
		986	<cite>Crafty</cite> uses to auto-tune itself when playing on a chess
		987	server. There are three lists, <strong>GM</strong>,
		988	<strong>IM</strong> and <strong>C</strong>. If <cite>Crafty</cite>'s
		989	opponent is in any of these lists, <cite>Crafty</cite> adjusts
		990	internal controls that affect how/when it resigns or offers draws, and
		991	how randomly it will choose moves from the opening book. For example,
		992	<cite>Crafty</cite> resigns much sooner against a GM, because it
		993	assumes he knows how to win a rook-up ending, regardless of how much
		994	time is left. By the same token, when playing against computers,
		995	<cite>Crafty</cite> will always assume that a draw is 0.000, so that
		996	it doesn't wreck its position trying to avoid repeating a position.
		997
		998	<p>The <strong>AK</strong> list will automatically kibitz
		999	scores/PV's if the opponent is in this list. The <strong>S</strong>
		1000	list will turn on special scoring for opponents in this list. The
		1001	only current member is "mercilous".
		1002
		1003	<p>The syntax +name1 +name2 simply adds these players to the
		1004	specified list. To remove a name, use -name1 -name2. You can use one
		1005	command per name to remove or add, or you can use one command to add
		1006	and remove multiple names. Note that all names must be entered in
		1007	lowercase characters, using any uppercase characters will break the
		1008	matching algorithm.<dd><p>
		1009
		1010
		1011
		1012	<a name="log"></a>
		1013	<dt> <strong>log off</strong> \| <strong>on</strong> \|
		1014	<var><n></var>
		1015
		1016	<dd> This command is used to disable logging. The default is
		1017	<strong>log on</strong>, which causes <cite>Crafty</cite> to produce a
		1018	new log.nnn file for each game played. If you are running
		1019	<cite>Crafty</cite> on a server, you might use <strong>log
		1020	off</strong>, which disables creating these files as well as the
		1021	game.nnn files used to restart a game after you exit
		1022	<cite>Crafty</cite> and come back later. If you use the form
		1023	<strong>log</strong> <var>n</var> <cite>Crafty</cite> will simply
		1024	display the last <var>n</var> lines of the log on the screen. If you
		1025	use <strong>log</strong> <var>n file</var> <cite>Crafty</cite> will
		1026	copy the last n lines of the log to <var>file</var> which could be
		1027	your hard drive, or a floppy.
		1028
		1029	<p>Note that if you run with <strong>log off</strong>, you will be
		1030	unable to find out what <cite>Crafty</cite> was thinking about since
		1031	there is no other record of the game. You will always see a game.001
		1032	because as <cite>Crafty</cite> plays a game, this contains all the
		1033	real moves played so far so that you can back up if needed. you will
		1034	also see a log.001 file, but it will be empty.<p>
		1035
		1036
		1037	<a name="ls"></a>
		1038	<dt> <strong>ls</strong> <var><filename></var>
		1039
		1040	<dd> will list all the files that match the
		1041	<var><filename></var> wildcard (the wildcards depend on the
		1042	system you are using, but generally *, ? will work fine). you can
		1043	also supply path information in the filename if you want to list the
		1044	contents of a different directory. Just use the same syntax you would
		1045	if you were using "ls" under <cite>Unix</cite> or "dir" under
		1046	<cite>Windows</cite>.<p>
		1047
		1048
		1049
		1050	<a name="mode"></a>
		1051	<dt> <strong>mode tournament</strong> \| <strong>normal</strong>
		1052
		1053	<dd> This command is primarily used to put <cite>Crafty</cite> into
		1054	"tournament" mode, which is intended for use when <cite>Crafty</cite>
		1055	is playing in computer chess events. It accomplishes two things: (1)
		1056	makes all draws return a score of 0.000, and (2) makes
		1057	<cite>Crafty</cite> issue a message after each move showing the
		1058	internal chess clock time, and requesting that that operator check and
		1059	adjust as needed using the <a href="#clock"><strong>clock</strong></a>
		1060	command. This primarily makes <cite>Crafty</cite> comply with
		1061	computer chess rules that say the operator can't do anything not
		1062	specifically requested by the program.<p>
		1063
		1064
		1065
		1066	<a name="name"></a>
		1067	<dt> <strong>name</strong> <var><name></var>
		1068
		1069	<dd> This command is an ICS-play specific command.
		1070	<cite>Xboard</cite>/<cite>WinBoard</cite> uses this to inform
		1071	<cite>Crafty</cite> of the opponent's name. <cite>Crafty</cite> uses
		1072	the <var><name></var>, and looks it up in its GM/IM/C lists, and
		1073	if found, adjusts itself accordingly. This is not used by the PGN
		1074	code and this will not cause the players <var><name></var> to
		1075	show up in the PGN tag section.<p>
		1076
		1077
		1078
		1079	<a name="new"></a>
		1080	<dt> <strong>new</strong>
		1081
		1082	<dd> This command wipes everything out and starts a brand new game.
		1083	It closes the old log-file and game-file, and opens the next
		1084	sequential numbered file. It also resets the game to the beginning
		1085	and prepares to start a brand new game. This was added for Xboard,
		1086	but it turns out that Xboard does not use this, rather it starts
		1087	<cite>Crafty</cite> fresh for each new game by first terminating the
		1088	old copy then starting a new one. Not nearly as efficient as using
		1089	<strong>new</strong> but likely safer it a program can't be sure of
		1090	resetting everything back to the initial state.<p>
		1091
		1092
		1093
		1094	<a name="noise"></a>
		1095	<dt> <strong>noise</strong> <var><n></var>
		1096
		1097	<dd> This command sets the "noise" level in <cite>Crafty</cite>.
		1098	Basically, until <var><n></var> nodes have been searched,
		1099	<cite>Crafty</cite> will be silent and not display analysis.
		1100
		1101	<p>This is useful in two ways. First, in end-games, 20+ ply
		1102	searches are not uncommon, and the search analysis for the first few
		1103	plies arrives so quickly that it is distracting. Second, when
		1104	observing games (new interface only) on ICS servers, this can be used
		1105	to avoid having <cite>Crafty</cite> generate too many analysis kibitzes. A value
		1106	of 100000 will basically shut off any output for the first second or
		1107	so (on a P6/200). Similarly, 1000000 will eliminate any output for
		1108	about the first 10 seconds. When watching and kibitzing games like
		1109	the World Championship games on ICC, I generally use 5000000, which is
		1110	almost one minute of silence so that the first PV it kibitzes is a
		1111	pretty deep search.
		1112
		1113	<p><strong>noise 0</strong> will cause all analysis to be
		1114	displayed, which on a fast machine causes no problems. On a slower
		1115	machine, or over a slow phone connection, this might cause a big
		1116	communication backlog. The default is roughly one second on a P6/200
		1117	(100000) but can be modified by this command.<p>
		1118
		1119
		1120	<a name="operator"></a>
		1121	<dt> <strong>operator</strong> <var><n></var>
		1122
		1123	<dd> Another command intended for use when <cite>Crafty</cite> is
		1124	playing in a tournament, operated by a human. This tells
		1125	<cite>Crafty</cite> to "hide" <var><n></var> minutes of time and
		1126	not use them. This time is basically allocated to the operator to
		1127	make up for the time it takes to type in moves and/or correct
		1128	mistakes. At the WMCCC events, the normal value we use is 5. Playing
		1129	on a server, this is not needed, as it is not needed if you are
		1130	playing <cite>Crafty</cite> yourself.<p>
		1131
		1132
		1133	<a name="perf"></a>
		1134	<dt> <strong>perf</strong>
		1135
		1136	<dd> This command is primarily used in optimizing <cite>Crafty</cite>,
		1137	or to test the speed of the move generator and
		1138	<code>MakeMove()</code>/<code>UnMakeMove()</code> on different
		1139	platforms. It produces two results, the moves it can generate per
		1140	second, and the moves is can generate and make/unmake per second.
		1141	While this is not a perfect performance indicator, it does give an
		1142	"approximation" for how fast <cite>Crafty</cite> might run. In
		1143	general, the higher the numbers, the better the program will play,
		1144	although machines are certainly different. It's not uncommon to find
		1145	a machine that searches slower than another, but has a higher "perf"
		1146	value.<p>
		1147
		1148
		1149	<a name="perft"></a>
		1150	<dt> <strong>perft</strong> <var><depth></var>
		1151
		1152	<dd> This command is generally used to confirm that the move generator
		1153	and bitmap operators are working properly. It simply takes the
		1154	current position, and generates/makes/unmakes moves and counts them.
		1155	Many programs use this from a "standard" position to make sure that
		1156	their move generator does not miss generating odd moves like
		1157	enpassant/promotions and also to confirm that the make/unmake code
		1158	correctly updates the board so that the totals remain constant across
		1159	different machines and programs, since there is no alpha/beta or
		1160	evaluation things done. if <var><depth></var> is greater than 5
		1161	or 6, it will take a long time, since this is basically a minimax
		1162	tree traversal that will visit every node within the
		1163	<var><depth></var> search horizon.<p>
		1164
		1165
		1166	<a name="pgn"></a>
		1167	<dt> <strong>pgn</strong> <var><tag> <value></var>
		1168
		1169	<dd> This command is used to set the usual PGN tags to meaningful
		1170	values. The recognized tags are <strong>Event</strong>,
		1171	<strong>Site</strong>, <strong>Round</strong>, <strong>Date</strong>,
		1172	<strong>White</strong>, <strong>WhiteElo</strong>,
		1173	<strong>Black</strong>, <strong>BlackElo</strong>, and
		1174	<strong>Result</strong>, and the tags are case sensitive. The
		1175	<var><value></var> can be any valid input and blanks and special
		1176	characters are allowed. Note that the date is clearly specified in
		1177	the PGN standard and must be yyyy.mm.dd with no variance. Valid
		1178	results are <strong>1-0</strong> (White won), <strong>0-1</strong>
		1179	(Black won), <strong>1/2-1/2</strong> (drawn) and <strong>*</strong>
		1180	(unknown). Some examples:
		1181
		1182	<pre><strong>
		1183	pgn Event 14th World MicroComputer Chess Championship
		1184	pgn Date 1996.10.8
		1185	pgn Site Jakarta, Indonesia
		1186	pgn Round 1
		1187	pgn White Crafty
		1188	pgn WhiteElo 2400
		1189	pgn Black assassin
		1190	pgn BlackElo 2400
		1191	pgn Result 1-0
		1192	</strong></pre>
		1193
		1194	Setting these values will result in a proper PGN file when using the
		1195	<a href="#savegame"><strong>savegame</strong></a> command. Note that if you
		1196	use the <a href="#read"><strong>read</strong></a> command to input a PGN game,
		1197	these values will be extracted from that game if they are given.<p>
		1198
		1199
		1200
		1201	<a name="ponder"></a>
		1202	<dt> <strong>ponder off</strong> \| <strong>on</strong> \|
		1203	<var><move></var>
		1204
		1205	<dd> This command serves two purposes. First, it can be used to
		1206	disable (<strong>off</strong>) or enable (<strong>on</strong>)
		1207	thinking on the opponent's time (or pondering as it is called in many
		1208	programs including <cite>Crafty</cite>.) Turning it off will weaken
		1209	<cite>Crafty</cite> since it will not use any machine time while
		1210	waiting on the opponent to move. It is sometimes useful, however,
		1211	when playing <cite>Crafty</cite> against another computer and the
		1212	machines are not equal. If <cite>Crafty</cite> is on a faster
		1213	machine, and you attempt to adjust for this by giving the opponent
		1214	more time than <cite>Crafty</cite>, it doesn't work quite as expected,
		1215	because while the opponent is thinking, so is <cite>Crafty</cite>,
		1216	which lets it use the extra opponent time in an unexpected way. In
		1217	such a case, it's best to stop pondering in both programs.
		1218
		1219	<p>If <var><move></var> is given, it directs
		1220	<cite>Crafty</cite> to use that <var><move></var> to ponder,
		1221	rather than the one from the previous search. Most commonly this is
		1222	used to set the right move to ponder after <cite>Crafty</cite> has
		1223	been stopped and then restarted, assuming that it is the opponent's
		1224	turn to move when this happens. Otherwise, it is probably better to
		1225	not try to influence things, although if you are watching and suddenly
		1226	wonder "what would <cite>Crafty</cite> do if the opponent plays move
		1227	'X'?", you can answer this by simply typing <strong>ponder X</strong>
		1228	and then watching the analysis. You should reset the correct ponder
		1229	move after you do this of course.<p>
		1230
		1231
		1232	<a name="read"></a>
		1233	<dt> <strong>read</strong> \| <strong>reada</strong>
		1234	[<var><filename></var>]
		1235
		1236	<dd> This command will read input, and extract the chess moves and
		1237	make them to set up the position at the end of the game. It first
		1238	resets the chess board to the initial position (read command only) and
		1239	then extracts the PGN tags (if present) from the front of the input.
		1240	The rest of the input is parsed for chess moves (comments and similar
		1241	things are culled automatically) and the moves are made and added to
		1242	the game history. Once this is done, you can back up, go forward, or
		1243	play from any point in the game. If you specify a
		1244	<var><filename></var> everything is read from the file,
		1245	otherwise it is read from the console keyboard.
		1246
		1247	<p>The <strong>reada</strong> command reads moves, but appends them
		1248	to the current game history/position rather than resetting to the
		1249	initial chess position. This lets you read in a game, then use reada
		1250	to manually add some more moves to see the resulting position.<p>
		1251
		1252
		1253
		1254	<a name="reset"></a>
		1255	<dt> <strong>reset</strong> <var><n></var>
		1256
		1257	<dd> This command lets you back up in the current game to any move of
		1258	your choice. <strong>reset</strong> <var><n></var> backs up the
		1259	game to move <var><n></var> with the same side on move. If you
		1260	want to first change the side to move, use the <a href="#black\|white"
		1261	><strong>white</strong>\|<strong>black</strong></a> command, then use
		1262	the <strong>reset</strong> command to back up to the right move. Note
		1263	that you can also go forward as well, just so there are moves in the
		1264	current game history.<p>
		1265
		1266
		1267
		1268	<a name="resign"></a>
		1269	<dt> <strong>resign</strong> <var><n></var>
		1270
		1271	<dd> This command sets the resign threshold. When running on ICC I
		1272	typically use <strong>resign 9</strong> which will make
		1273	<cite>Crafty</cite> resign roughly five moves after the score drops
		1274	below -9.000. For IM's I change this to 6, and for GM's I often use
		1275	3, so that it will resign quicker and not drag a lost game out
		1276	unnecessarily.<p>
		1277
		1278
		1279	<a name="savegame"></a>
		1280	<dt> <strong>savegame</strong> <var><filename></var>
		1281
		1282	<dd> This command is used to save the current game in a PGN-compliant
		1283	file with the PGN tags included. Note that the default TAG values
		1284	might not be what you want if you do not either use the <a
		1285	href="#pgn"><strong>pgn</strong></a> command to set them or else input
		1286	a valid PGN file with the tags already filled in.
		1287
		1288	<p>Be aware that this command doesn't check the filename for
		1289	legality since anything goes in UNIX. In DOS, you might produce a bad
		1290	filename with either too many characters, too many periods, or
		1291	whatever, so be careful with the name you choose. Note also that this
		1292	file will be overwritten if it already exists, so be sure to choose a
		1293	name that is not the name of a file that has something you consider
		1294	important in it.<p>
		1295
		1296
		1297
		1298	<a name="savepos"></a>
		1299	<dt> <strong>savepos</strong> <var><filename></var>
		1300
		1301	<dd> This command writes a single line into
		1302	<var><filename></var> in FEN-like notation. This lets you save
		1303	a position, and then come back later to re-examine it. You would use
		1304	the <a href=#input><strong>input</strong>
		1305	<var><filename></var></a> command to input this file and set the
		1306	position up.<p>
		1307
		1308
		1309
		1310	<a name="search"></a>
		1311	<dt> <strong>search</strong> <var><move></var>
		1312
		1313	<dd> This command allows you to specify one particular move for the
		1314	side on move, and then when you tell <cite>Crafty</cite> to search
		1315	this position, this is the only move that will be searched. This is
		1316	used internally by the annotate command, but can be used to
		1317	investigate one specific move. If the move is not the best move, a
		1318	normal search won't show you why it is bad, but this will. It is also
		1319	quite a bit faster since the other moves in the position are not
		1320	searched at all.<p>
		1321
		1322
		1323
		1324	<a name="settc"></a>
		1325	<dt> <strong>settc</strong> <var><moves> <ctime>
		1326	<otime></var>
		1327
		1328	<dd> This command is primarily used in tournaments, and is an
		1329	error-recovery command. If the machine crashes and corrupts the game
		1330	history file, frequently the operator will have to simply set the
		1331	position using the <a href=#setboard"><strong>setboard</strong></a>
		1332	command, and then use the <strong>settc</strong> command to restore
		1333	the time control values.
		1334
		1335	<dl>
		1336
		1337	<dt> <var><moves></var>
		1338	<dd> is moves until the next time control (from <cite>Crafty</cite>'s
		1339	perspective, be careful and don't look at the opponent's moves to time
		1340	control by accident.)<dd>
		1341
		1342	<dt> <var><ctime></var>
		1343	<dd> is minutes left on <cite>Crafty</cite>'s clock,
		1344	<var><otime></var> is minutes left on the opponent's clock.
		1345
		1346	</dl><p>
		1347
		1348
		1349
		1350	<a name="setboard"></a>
		1351	<dt> <strong>setboard</strong> <var><FEN input></var>
		1352
		1353	<dd> This command is used to set a chess position up for analysis and
		1354	is the preferred way to do this, rather than using the gnu <a
		1355	href=#edit><strong> edit</strong></a> interface. It uses a classic
		1356	Forsythe-like notation to encode the position and also has provisions
		1357	for castling status and en passant capture status.
		1358
		1359	<p>Standard piece codes p, n, b, r, q, k are used to denote the type
		1360	of piece on a square, upper/lower case are used to indicate the color
		1361	of the piece (uppercase=white pieces, lowercase=black pieces).
		1362
		1363	<p>Pieces are entered from the classic chess diagram's orientation
		1364	of a8 being the upper-left-hand corner of the board, and this square
		1365	is entered first, followed by the remainder of the 8th rank left to
		1366	right. To indicate empty squares, use a number between 1 and 8 to
		1367	indicate how many adjacent squares are empty. Use a slash (/) to
		1368	terminate each rank after all of the pieces for that rank have been
		1369	entered. Note that you do not have to account for all 8 squares on a
		1370	given rank, although many test suites do this for clarity.
		1371
		1372	<p>The input <strong>k2r/ppp////Q/5PPP/7K/ B</strong>
		1373	will setup the board position that is given below:
		1374
		1375	<pre><tt>
		1376	-k * * -r * * * *
		1377	-p -p -p * * * * *
		1378	* * * * * * * *
		1379	* * * * * * * *
		1380	* * * * * * * *
		1381	q * * * * * * *
		1382	* * * * * p p p
		1383	* * * * * * * k *
		1384	</tt></pre>
		1385
		1386	This assumes that k represents a white king and -q represents a black
		1387	queen.
		1388
		1389	<p>The field after the final "/" should be either b or w to indicate
		1390	which side is "on move." After this side-to-move field any of the
		1391	following characters can appear to indicate the following: KQ: White
		1392	can castle king-side/queen-side/both; kq: same for Black; a1-h8:
		1393	indicates the square occupied by a pawn that can be captured en
		1394	passant.<p>
		1395
		1396
		1397
		1398	<a name="score"></a>
		1399	<dt> <strong>score</strong>
		1400
		1401	<dd> This command simply gives the positional score for the current
		1402	position. This score is from White's perspective, so a + score is
		1403	good for White, a - score is good for Black. <cite>Crafty</cite> also
		1404	breaks the score down into major categories (from Evaluate()) to
		1405	indicate things like pawn structure, piece evaluation, passed pawns,
		1406	development, and so forth. Note that some of <cite>Crafty</cite>'s
		1407	evaluation is asymmetric, so that if you simply change sides with the
		1408	<a
		1409	href="#black\|white"><strong>white</strong>/<strong>black</strong></a>
		1410	command and then enter "score" again, you may get a different value.
		1411	This is not a bug. :)<p>
		1412
		1413
		1414
		1415	<a name="sd"></a>
		1416	<dt> <strong>sd</strong> <var><n></var>
		1417
		1418	<dd> This command lets you specify a specific search depth limit that
		1419	<cite>Crafty</cite> can not exceed. It still pays attention to the
		1420	clock, however, so often you will use the <a
		1421	href=#st><strong>st</strong></a> command (below) in conjunction with
		1422	this if the search is going to take an extended amount of time.
		1423	<var><n></var> is the depth (in plies or 1/2 moves) that the
		1424	search must reach. Note that if <cite>Crafty</cite> is pondering, it
		1425	still honors this limit and will stop a ponder search after this depth
		1426	has been completed as well. This is not the way to make
		1427	<cite>Crafty</cite> play weaker, although this will be covered in a
		1428	later section of this document.<p>
		1429
		1430
		1431
		1432	<a name="show"></a>
		1433	<dt> <strong>show</strong> <var><category></var>
		1434
		1435	<dd> This command forces <cite>Crafty</cite> to display additional
		1436	information about certain actions it takes. Currently the only
		1437	<var><category></var> is <strong>book</strong> which will make
		1438	<cite>Crafty</cite> display information about all the book moves it
		1439	found in the database. More is given about this information in the
		1440	the <a href="#Opening Book">Opening Book Setup and Usage</a> section
		1441	later in this file.<p>
		1442
		1443
		1444	<a name="smpmt"></a>
		1445	<dt> <strong>smpmt=</strong><var>n</var>
		1446
		1447	<dd> This command is used to set the number of threads to use on a
		1448	machine with more than one processor. For optimal performance,
		1449	"<var>n</var>" should be set to the number of processors you have,
		1450	although using fewer will reduce the load on your machine. For this
		1451	command to work, <cite>Crafty</cite> must have been compiled with SMP
		1452	defined. When compiled with SMP enabled, <strong>mt=0</strong>
		1453	effectively disables the SMP code completely.
		1454
		1455	<p>This command also has two that are closely related:
		1456	<strong>smpmin</strong> and <strong>smpmax</strong>. Both accept
		1457	single numerical arguments.<dl>
		1458
		1459
		1460	<a name="smpmin"></a>
		1461	<dt> <strong>smpmin</strong>
		1462
		1463	<dd> is used to control the minimum tree depth required at a node
		1464	for it to be eligible for parallel searching. IE <strong>smpmin
		1465	2</strong> says don't split unless at least two more plies are left
		1466	to search below this node.<dd
		1467
		1468
		1469	<a name="smpmax"></a>
		1470	<dt> <strong>smpmax</strong>
		1471
		1472	<dd> sets the maximum for the same idea; that is, <strong>smpmax
		1473	10</strong> says don't split if more than 10 plies are remaining
		1474	below this node.
		1475
		1476	</dl><p>
		1477
		1478
		1479
		1480	<a name="sn"></a>
		1481	<dt> <strong>sn</strong> <var><n></var>
		1482
		1483	<dd> This command is similar to the <a
		1484	href="#sd"><strong>sd</strong></a> command, but instead of setting a
		1485	specific search depth, it sets a number of nodes to search. Once the
		1486	search has searched this number of nodes (+ maybe one more second of
		1487	searching to check the time) the search will exit.<p>
		1488
		1489
		1490
		1491	<a name="st"></a>
		1492	<dt> <strong>st</strong> <var><n></var>
		1493
		1494	<dd> This command lets you specify a specific search time limit for
		1495	<cite>Crafty</cite>. Again, this is not the preferred way to set a
		1496	time per move, because this limit is absolute and <cite>Crafty</cite>
		1497	will never go over this limit, even if it sees that it is losing or
		1498	getting mated. Setting the time control with the usual <a
		1499	href="#time"><strong>time</strong></a> or <a
		1500	href="#level"><strong>level</strong></a> command is much better.
		1501	<var><n></var> is given in seconds, although it may also be
		1502	entered as mm:ss if preferred.<p>
		1503
		1504
		1505
		1506	<a name="swindle"></a>
		1507	<dt> <strong>swindle on</strong>\|<strong>off</strong>
		1508
		1509	<dd> This command gives you control over "swindle mode." When on, and
		1510	playing a game, <cite>Crafty</cite> will try to win drawn endings
		1511	(according to the tablebases) if it has winning chances (like KR vs
		1512	KB, for example). This will put up very stiff "resistance" to
		1513	accepting the draw, while with this mode off, it may be very easy to
		1514	draw a position once the tablebases say "drawn." This mode is
		1515	automatically turned "off" during <a href="#analyze">analysis</a> or
		1516	when <a href="#annotate">annotating</a> a game, and is only used when
		1517	actually playing a game against an opponent. If there are <a
		1518	href="#egtb">no tablebases</a> then this has no effect on the game at
		1519	all.<p>
		1520
		1521
		1522
		1523	<a name="tags"></a>
		1524	<dt> <strong>tags</strong>
		1525
		1526	<dd> This command will simply display the current PGN tags (you can
		1527	edit them with the various <a href="#pgn"><strong>pgn</strong></a>
		1528	commands).<p>
		1529
		1530
		1531
		1532	<a name="test"></a>
		1533	<dt> <strong>test</strong> <var><filename></var> [<var>n</var>]
		1534
		1535	<dd> This command will run a suite of positions (the file must be in
		1536	"<cite>Crafty</cite>" format as explained below) and produce a summary
		1537	of how many it got right, wrong, etc. It uses the time per move you
		1538	set with the (typically) <strong>st</strong> <var><n></var>
		1539	command. The optional parameter [<var>n</var>] is the "early exit"
		1540	counter. If <cite>Crafty</cite> finds, and holds the solution move
		1541	for n iterations, it will terminate the search. I use this to make a
		1542	"<cite>Win at Chess</cite>" run take < 15 minutes, even though the
		1543	time per position is set to 1 minute, by setting n to 2. After two
		1544	correct iterations, <cite>Crafty</cite> goes on to the next problem.
		1545	For absolutely correct results, this is not advisable as it could
		1546	obviously change its mind later on, but for performance analysis, this
		1547	saves a lot of time.
		1548
		1549	<p>The test suite contains the following lines: (this is a sample
		1550	from my test suite for <cite>Win At Chess</cite>.)
		1551
		1552	<pre>
		1553	title wac299
		1554	setboard 1n2rr2/1pk3pp/pNn2p2/2N1p3/8/6P1/PP2PPKP/2RR4 w
		1555	solution Nca4
		1556
		1557	title wac300
		1558	setboard b2b1r1k/3R1ppp/4qP2/4p1PQ/4P3/5B2/4N1K1/8 w
		1559	solution g6
		1560
		1561	end
		1562
		1563	</pre>
		1564
		1565	<ul>
		1566
		1567	<li> The <strong>title</strong> command simply displays this message
		1568	in the log file so you can look at the output and figure out which
		1569	position it goes with. This is optional, but useful.
		1570
		1571	<li> The <strong>setboard</strong> command sets the position as
		1572	explained above.
		1573
		1574	<li> The <strong>solution</strong> command gives the set of solution
		1575	moves (one or more moves that are separated by blanks) and/or a set
		1576	of "anti-solution" moves (moves that must not be played to
		1577	count the position as correct.) "anti-solution" moves are
		1578	simply followed by a "?" character, for example:
		1579
		1580	<center><strong> solution Bxa7?</strong></center>
		1581	<center> </center>
		1582
		1583	<p>The <strong>solution</strong> command supplies a set of key moves, and
		1584	then starts the search. If, after the search terminates, one of the
		1585	key solution moves was chosen (or none of the anti-solution moves
		1586	were chosen) the position is counted as correct.
		1587
		1588	<li> The final line should be <strong>end</strong> although
		1589	end-of-file or EOF will also be detected in this case.</ul><p>
		1590
		1591
		1592
		1593	<a name="time"></a>
		1594	<dt> <strong>time
		1595	CPU</strong> \| <strong>elapsed</strong> \| <var><values></var>
		1596
		1597	<dd> In the forms <strong>time CPU</strong> and <strong>time
		1598	elapsed</strong>, this command controls whether the program uses CPU
		1599	time or wall-clock time for timing. For tournament play, it is safer
		1600	to use wall-clock timing. For testing it may be more consistent to
		1601	use CPU timing if the machine is used for other things concurrently
		1602	with the tests being run.
		1603
		1604	<p>The form <strong>time</strong> <var><values></var> is used
		1605	to set the basic search timing controls. The general form of the
		1606	command is as follows:
		1607
		1608	<center><strong>time</strong>
		1609	<var>nmoves</var> <strong>/</strong> <var>ntime</var>
		1610	[<strong>/</strong> <var>nmoves</var> <strong>/</strong>
		1611	<var>ntime</var>]
		1612	[<strong>/</strong> <var>increment</var>]</center>
		1613
		1614	<ul>
		1615
		1616	<li> <var>nmoves</var><strong>/</strong><var>ntime</var> represents a
		1617	traditional first time control when nmoves is an integer representing
		1618	the number of moves and ntime is the total time allowed for these
		1619	moves.
		1620
		1621	<li> the optional
		1622	[<var>nmoves</var><strong>/</strong><var>ntime</var>] is a traditional
		1623	secondary time control.
		1624
		1625	<li> <var>increment</var> is a feature related to ICS play and
		1626	emulates the Fischer clock where <var><increment></var> is added
		1627	to the time left after each move is made.
		1628
		1629	</ul>
		1630
		1631	<p>Instead of an integer, nmoves can be <strong>sd</strong> which
		1632	represents a sudden death time control of the remainder of the game
		1633	played in ntime. The optional secondary time control can be a
		1634	sudden-death time control, as in the following example:
		1635
		1636	<center><strong>time 60/30/sd/30</strong>;</center>
		1637
		1638	this sets 60 moves in 30 minutes, then game in 30 additional
		1639	minutes. An increment can be added if desired.
		1640
		1641	<p>One final example is the following:
		1642
		1643	<center><strong>time sd/15</strong></center>
		1644
		1645	which is a simple game/15 setting. This command can also be used to
		1646	perform the same function as the "level" command. For example, to set
		1647	up a classic ICS 2 12 game, the following would would work:
		1648
		1649	<center><strong>time sd/2/12</strong>.</center>
		1650	<p>
		1651
		1652
		1653	<a name="trace"></a>
		1654	<dt> <strong>trace</strong> <var><n></var>
		1655
		1656	<dd> This command is used to make <cite>Crafty</cite> display the tree as it
		1657	searches a position. Due to the incredible speed at which this
		1658	program can search, however, this is less than useful since it can
		1659	swamp any known display driver and make things scroll impossibly fast.
		1660
		1661	<p>Also note that this command usually is disabled, because
		1662	<cite>Crafty</cite> is generally compiled with the -DFAST flag, which
		1663	removes the trace output code from the search to make things slightly
		1664	faster. You will have to recompile, without the -DFAST, if you want
		1665	to use this. Its utility is limited, except for debugging, anyway.<p>
		1666
		1667
		1668	<a name="usage"></a>
		1669	<dt> <strong>usage</strong> <var><n></var>
		1670
		1671	<dd> is simply a way to modify <cite>Crafty</cite>'s time usage to fit
		1672	your tastes. You can "suggest" a time limit with any of the options
		1673	discussed previously, but if you use anything other than the <a
		1674	href="#st"><strong>st</strong></a> command, <cite>Crafty</cite> will
		1675	do its best to use time as you suggest, but it also anticipates that
		1676	it will save some time by pondering, etc., and will therefore be more
		1677	aggressive at trying to use time. If <var><n></var> is a
		1678	positive integer, it is taken as a percentage and <cite>Crafty</cite>
		1679	will compute the time limit it thinks is appropriate for the current
		1680	clock settings, then increase this limit by this percentage (50 would
		1681	make it take 1.5 times longer than normal.) -50 would make it take
		1682	1/2 the time it would normally take.
		1683
		1684	<p><cite>Crafty</cite> adjusts the usage internally based on time
		1685	left, opponent's time left, how quickly or slowly the opponent is
		1686	moving, etc. Further modifying things with this is dangerous, but
		1687	possible.<p>
		1688
		1689
		1690
		1691	<a name="whisper/kibitz"></a>
		1692	<dt> <strong>whisper/kibitz</strong> <var><n></var>
		1693
		1694	<dd> These commands are used to control what <cite>Crafty</cite> will
		1695	whisper or kibitz on a chess server. The options are (1) only
		1696	whispers or kibitzes mate announcements; (2) adds time, score, depth
		1697	to the previous option, but no PV or moves. (3) adds the PV. (4)
		1698	adds book move information to the output. The remaining two options
		1699	generate a lot of output and should be used with caution. (5)
		1700	displays the PV after each iteration completes. I use this when using
		1701	my custom interface to let <cite>Crafty</cite> observe/comment on
		1702	games in progress on ICC. Noise can be used to prevent shallow
		1703	searches from generating output and keeping "noise" down on the games
		1704	being watched. (6) basically will whisper/kibitz nearly everything
		1705	you see on the console from a search, each PV when it changes, fail
		1706	highs and fail lows, etc. A significant amount of output that should
		1707	be carefully weighed before turning it "loose."<p>
		1708
		1709
		1710
		1711	<a name="xboard"></a>
		1712	<dt> <strong>xboard</strong>
		1713
		1714	<dd> This command turns on <cite>Xboard</cite>/<cite>WinBoard</cite>
		1715	compatibility mode, and makes <cite>Crafty</cite> behave somewhat like
		1716	GnuChess. This is designed to be used only when <cite>Crafty</cite>
		1717	is interfacing with <cite>Xboard</cite>/<cite>WinBoard</cite>.
		1718	<cite>Crafty</cite> will not work with these two GUIs without this
		1719	option, and really won't work very well with this option if it is not
		1720	connected to one of them.<p>
		1721
		1722
		1723	</dl>
		1724
		1725	There are other commands that are not documented. They are part of
		1726	the xboard protocol and really should not be used by the normal user.
		1727	You can find all the commands in option.c should you be interested.
		1728
		1729
		1730
		1731
		1732	<hr>
		1733	<a name="Opening Book"></a>
		1734	<h2>Opening Book Setup and Usage</h2>
		1735
		1736	<cite>Crafty</cite> uses two pre-compiled opening books, called
		1737	"<code>book.bin</code>" and "<code>books.bin</code>".
		1738
		1739	<p>The file <code>book.bin</code> is usually build from a large text
		1740	file containing PGN games, often taken from collections of GM games.
		1741	Building <code>book.bin</code> is a simple exercise and requires
		1742	nothing other than the raw input file you are going to use. Generally
		1743	this will be either <code>medium.zip</code> or the set of four files
		1744	<code>large</code>[1-4].<code>zip</code>, all of which are stored on
		1745	the ftp machine <a
		1746	href="ftp://ftp.cis.uab.edu/pub/hyatt/">ftp.cis.uab.edu/pub/hyatt/</a>.
		1747
		1748	<p>To create the file <code>book.bin</code>, you need a PGN game
		1749	collection that is a real PGN-compliant file. Supposing this file
		1750	is called "large.pgn" you would use the following command:
		1751
		1752	<center><strong>book create large.pgn</strong> <var><m></var>
		1753	[<var>n</var>] [<var>wpct</var>]</center>
		1754
		1755	<p>The only thing you have to supply is <var><m></var>,
		1756	a number indicating how many moves from each game are to be stored in
		1757	the book.bin database. I typically use 60, which stores the first 60
		1758	moves from each game. Increasing this number slightly increases the
		1759	probability that <cite>Crafty</cite> will stay in book longer, but it also
		1760	increases the probability that it will follow a game too far, so that
		1761	it begins to reach positions where the move actually played might not
		1762	be the best move, letting it fall into a bad hole. Increasing this
		1763	also increases the size of the database as well.
		1764
		1765	<p>You can decrease the size of the book, and also reduce the number
		1766	of ugly moves by specifying [<var>n</var>], which says that unless a
		1767	move is played in at least <var>n</var> games, the move is discarded.
		1768	This will substantially decrease the size of the book.bin file, and
		1769	also eliminate single game moves that often have significant errors or
		1770	blunders.
		1771
		1772	<p>You can increase the quality of book lines by specifying
		1773	<var>wpct</var> which is the "winning percentage". This is specified
		1774	as a percentage of lost games, and is used to discard moves that led
		1775	to mostly losses. A safe value is 50, which says that if a particular
		1776	opening move didn't win at least 50% as many games as it lost, the
		1777	move is culled. A value of 100 would mean that moves are culled if
		1778	they produced more losses than wins, and is really a strict criterion.
		1779
		1780	<p>After creating <code>book.bin</code>, you need to create
		1781	<code>books.bin</code>. This is a small version of
		1782	<code>book.bin</code>, which is intended to give you more control over
		1783	the moves/openings <cite>Crafty</cite> will play. This is usually
		1784	built from the file <code>start.pgn</code> on the ftp machine, but you
		1785	can modify this file to suit your taste easily. To build
		1786	<code>books.bin</code>, you use the following command:
		1787
		1788	<center><strong>books create start.pgn 60</strong></center>
		1789
		1790	<p>Again, 60 is what I use, but none of my <code>start.pgn</code>
		1791	lines go anywhere near that many moves. The main point here is that
		1792	in <code>start.pgn</code>, you can append a "!" to any move you want,
		1793	and when it is <cite>Crafty</cite>'s turn to move for that color, it
		1794	will play from the set of moves with "!" if there are any, ignoring
		1795	the rest of the book moves. If you only want it to play 1. e4 as
		1796	White, you would just enter the short game:
		1797
		1798	<center><strong>[Crafty only plays 1. e4]
		1799	1. e4!</strong></center>
		1800
		1801	<p>and you are finished! You can enter as many as you want. If on
		1802	the other hand there is a move you don't want <cite>Crafty</cite> to
		1803	play, then follow that move with a "?" and it will never play it.
		1804	Moves in <code>books.bin</code> that are not flagged with ! or ? don't
		1805	have any influence on <cite>Crafty</cite>'s choice at all.
		1806
		1807	<p>Here's how the files are used. When searching a position,
		1808	<cite>Crafty</cite> first enumerates the set of moves it can find in
		1809	the opening database. It then does the same for the
		1810	<code>books.bin</code> database, and performs a "merge" operation to
		1811	combine the ? and ! flags... The purpose of the
		1812	<code>books.bin</code> file is to give you a small database that you
		1813	can easily modify, rebuild, and repeat this process over and over.
		1814	Since it takes a fraction of a second to completely rebuild this file,
		1815	it is very easy to modify this to control what <cite>Crafty</cite>
		1816	will play, without having to rebuild the large database.
		1817
		1818	<p>One important characteristic of the PGN input is the Result tag
		1819	must be specified in most of the lines, because <cite>Crafty</cite>
		1820	counts wins, losses and draws for each book move and uses these counts
		1821	with some of the book selection options given below.
		1822
		1823
		1824
		1825	<h3>How the flags are used.</h3>
		1826
		1827	The ! and ? flags should only appear in the small
		1828	<code>books.bin</code> file, although there is no reason why they can
		1829	not appear in the large file as well. For this discussion, it doesn't
		1830	matter since <cite>Crafty</cite> takes the moves from both files and
		1831	"merges" the flags, etc., into one entry for each move.
		1832
		1833	<p>Quite simply, if any book legal book move has a ! flag, then
		1834	<cite>Crafty</cite> will only play moves from the set of moves which
		1835	all have the ! flag. If a move has a ? flag, then that move is
		1836	immediately removed from the set of possible book moves. If the only
		1837	legal book move has a ? flag, it will not be played as a book move and
		1838	<cite>Crafty</cite> will simply pretend that it found no book moves
		1839	and will execute a normal tree search. Pretty simple.
		1840
		1841
		1842	<h3>
		1843	How to control the frequency of opening move selection.</h3>
		1844
		1845	A new feature in version 15.15 and beyond allows you to append a PGN
		1846	comment to any move in a text file used to create
		1847	<code>books.bin</code>, of the form <strong>{play</strong>
		1848	<var>nn</var><strong>%}</strong>. This will force the move it follows
		1849	to be played that percentage of the time, regardless of the normal
		1850	book-ordering values based on frequency and so forth.
		1851
		1852	<p>Note that <strong>{play 0%}</strong> will not prevent a move from
		1853	being played at all, as this will look just like a move with no
		1854	percent specified. To avoid playing a move, use the ? flag.
		1855
		1856
		1857	<h3>
		1858	How does <cite>Crafty</cite> choose book moves?</h3>
		1859
		1860	<cite>Crafty</cite>'s book selection algorithm depends on two
		1861	user-defined values that can be set at any time during a game:
		1862
		1863	<center><strong>book random</strong> <var><n></var></center>
		1864
		1865	<center><strong>book width</strong><var> <w></var></center>
		1866
		1867	<p>The selection algorithm first finds the set of legal book moves
		1868	as above. This set will either be all ! moves, or will have no !
		1869	moves in it. This set is then sorted based on the setting of book
		1870	random. Here's the options:
		1871
		1872	<p><strong>book random 0</strong>. This is a special case for book
		1873	selection. <cite>Crafty</cite> simply takes the set of book moves,
		1874	and searches only these moves using a normal alpha/beta search, but
		1875	with a shorter than usual time limit. It then plays the move that
		1876	produces the best search value. This has one serious disadvantage in
		1877	that there is no randomness to this at all. It will always play the
		1878	same move in the same position, unless the evaluation is modified, or
		1879	the time per move is different enough to let the search find a
		1880	different move from the book move set.
		1881
		1882	<p><strong>book random 1</strong>. This enables a random form of
		1883	book move selection, but you have a lot of control over how moves are
		1884	randomly chosen. The moves are ordered, based on 4 parameters:
		1885	frequency of play, win/lose ratio, static evaluation and learned
		1886	results. Normally these are factored into the value used to sort the
		1887	moves, based on default settings that you can modify by using the
		1888	command <strong>bookw</strong> <var><option> <N></var>,
		1889	where <var><option></var> should be "freq", "ratio", "eval" or
		1890	"learn". <var><N></var> should be a number between 0 and 1.
		1891
		1892	<p><cite>Crafty</cite> finds the min and max values for each of the
		1893	4 parameters, and then maps this into the range 0-1000 for each
		1894	parameter. Each parameter is multiplied by the corresponding "weight"
		1895	you have assigned, and this is used as a value to sort the moves from
		1896	low to high. Note that the first sort value is always the "play
		1897	percent" to move them to the top of the list. For moves with equal
		1898	"play percent" values, the normal sort-value is used as the
		1899	second-level sort variable (if no moves have a play-percent, then this
		1900	second-level variable is the only one used, of course.)
		1901
		1902	<p>Once <cite>Crafty</cite> has sorted the moves as given above, it
		1903	next excludes any book moves which have 0 wins. This culls the odd
		1904	lines where a player chose a bad line and lost quickly. With zero
		1905	wins, it will never be chosen, although <cite>Crafty</cite> will
		1906	happily follow it from the other side. :) This is not anywhere near
		1907	perfect, however, because an opening could have 1 win and 19 losses
		1908	and that still would stay in the list.
		1909
		1910	<p>If a move has a learned value of > 100, this move is elevated
		1911	in priority to that of a ! move, since it appears to win material
		1912	instantly. If a value is < -100, it is given a ? since it appears
		1913	to be a lemon.
		1914
		1915	<p>After this, the setting for <strong>book width</strong>
		1916	<var><w></var> is used to keep the first
		1917	<var><w></var> moves in the list, after the above culling
		1918	has been completed. The smaller you make <var><w></var>
		1919	the less randomness you get, but the chance of <cite>Crafty</cite>
		1920	popping out a really bizarre book move gets smaller as well.
		1921
		1922	<p>After sorting, the final step is to fold in any mandatory "play
		1923	percent" values. What this step does is that it finds all the moves
		1924	in the "playable move set" just computed, which have no
		1925	percent-to-play value set. It sums the sort-values for these moves,
		1926	then adjusts the sort-values for the other moves so that their
		1927	percentages will be honored.
		1928
		1929	<p>Once this has been done, <cite>Crafty</cite> simply uses the
		1930	"sort value" for each move to compute a total for all moves. It then
		1931	generates a random number between 1 and this limit, and chooses the
		1932	move that this probability distribution matches. This will certainly
		1933	evolve over time as new ideas are developed.
		1934
		1935	<p>For my play on ICC, I use <strong>book random 1</strong>, and
		1936	<strong>book width 5</strong> normally, although for titled players
		1937	this is reduced to <strong>book width 3</strong>. For computers, I
		1938	reduce this further to <strong>2</strong>, to try to play reasonable
		1939	openings and cull the gambits and things that don't work out.
		1940
		1941
		1942	<h3> How does book learning work and how can I share learned
		1943	results?</h3>
		1944
		1945	<p>1. All of <cite>Crafty</cite>'s "learned knowledge" is in the
		1946	<code>book.bin</code> file. It keeps the learned value and learned
		1947	count right in the book file for speed. You can't modify it, although
		1948	<a href="#show"><strong>show book</strong></a> will make
		1949	<cite>Crafty</cite> display all the book stuff before it makes a move.
		1950
		1951	<p>2. the <code>book.lrn</code> file has two purposes: (a) to
		1952	serve as a log for your prying eyes, so you can see what it's learned,
		1953	against whom, and what the score was that got its attention in the
		1954	first place. The values on the end of each book line, inside the {}
		1955	characters are as follows:
		1956
		1957	<center>{value, depth, rating_difference}</center>
		1958
		1959	<dl>
		1960
		1961	<dt> <strong>value</strong> is the value of the "key" search that
		1962	comes from the first 10 moves out of book. It's in centipawns, and +
		1963	is good - is bad.<dd>
		1964
		1965	<dt> <strong>depth</strong> is the depth the search reached at this "key"
		1966	position, the deeper the search, the more the value is "trusted."<dd>
		1967
		1968	<dt> <strong>rating_difference</strong> is <cite>Crafty</cite>'s
		1969	rating - opponent's rating a negative value means pay more attention
		1970	to the score since the opponent is better than <cite>Crafty</cite>, a
		1971	positive value means to take the score with a grain of salt, because
		1972	the opponent was weaker than <cite>Crafty</cite>.<dd></dl>
		1973
		1974
		1975	<p>You can delete this file at any time, and it has no effect on
		1976	learning. As I mentioned, the learning takes place in
		1977	<code>book.bin</code>... this is mainly for you to peek at if you are
		1978	interested. However, this is the "portable learning data file" also,
		1979	and can be given to others to import into their <cite>Crafty</cite>,
		1980	where it will affect the opening book just like their
		1981	<cite>Crafty</cite> had played the openings and got the same scores.
		1982	There are two ways to use such "lrn" files:
		1983
		1984	<p>1. <a href="#import"><strong>import</strong></a>
		1985	<strong><filename></strong> will read <filename> and
		1986	import the knowledge therein into your book.bin. Since I use the same
		1987	learning code as is used when playing games, this information also
		1988	gets appended to your <code>book.lrn</code> file as well, so that
		1989	your <code>book.lrn</code> always reflects everything your program
		1990	has learned, so long as you don't ever remove this file. It would be
		1991	a mistake to use this command on your own book.lrn file, because the
		1992	things would get counted twice, which might or might not be a good
		1993	thing.
		1994
		1995	<p>2. <a href="#import"<strong>import</strong></a>
		1996	<strong><filename> clear</strong> will read <filename) and
		1997	import the knowledge as above, but first clears all learned results
		1998	from book.bin. you will want to do this if you import my book.lrn,
		1999	and, you have contributed to my book.lrn data by sending me yours.
		2000	I'll take care of eliminating duplicates if you screw up in what you
		2001	send me, but once you send me something, you run the risk of getting
		2002	it "back again" later. This is going to be a problem until everyone
		2003	gets used to sharing something that is rather "vapid" like this
		2004	"learned info" is...
		2005
		2006	<p>Other than that, we are now "open for business"... when the urge
		2007	strikes you, email me your .lrn file, I'll keep a large master here
		2008	and update it on occasion. Probably the best thing to do is to send
		2009	me your .lrn and at the same instant delete yours. This will
		2010	capture anything learned after you send me the file, but you'll get
		2011	it all right back with the next version of book.lrn that I
		2012	distribute.
		2013
		2014	<p>After getting this new book.lrn back, here's what you should
		2015	do:
		2016
		2017	<p>1. rename your old <code>book.lrn</code> to something else.
		2018	I'll call it "book.lrn.old" here.
		2019
		2020	<p>2. copy my blearn.dat to your machine, but do not put it in
		2021	the directory with your <code>book.bin</code> and
		2022	<code>books.bin</code> file because it will get confusing very quickly
		2023	if you do. Put it somewhere else, because you are going to remove it
		2024	quickly anyway. I'll call it new.lrn for this example.
		2025
		2026	<p>3.<pre><strong>
		2027	import new.lrn clear
		2028	import book.lrn.old</strong></pre>
		2029
		2030	and you are ready to rumble again. The first command clears the
		2031	learned values, sucks in my new learn file and updates everything.
		2032	the second command re-learns everything you've learned since you sent
		2033	me the last book.lrn file. After doing this your book.lrn will have
		2034	my .lrn stuff, plus your old.lrn stuff, just waiting to be sent to me
		2035	again...
		2036
		2037	<p>If this is confusing, I can probably add an automatic command to
		2038	do all of this by renaming book.lrn, etc. Hopefully this is not too
		2039	error-prone for the time being anyway...
		2040
		2041
		2042	<h3>
		2043	What is this new Position Learning I've heard about?</h3>
		2044
		2045	<cite>Crafty</cite> now has a "permanent" hash table that is kept from
		2046	game to game. A position gets into this "hash file" when
		2047	<cite>Crafty</cite> executes a search and the search value is
		2048	significantly lower than the last search value.
		2049
		2050	<p>When this happens, <cite>Crafty</cite> stores the current
		2051	information for this position in the permanent hash file, which can
		2052	hold up to 65536 positions. Once it fills up, the positions are
		2053	replaced on a FIFO basis, always keeping the most recent 64K entries.
		2054
		2055	<p>Each time <cite>Crafty</cite> starts a search, the
		2056	positions/scores from this file are stuffed into the normal
		2057	transposition table, and used during the search just like any other
		2058	table entry. Here's how it helps: In a game that was played, the
		2059	following moves and scores were found by <cite>Crafty</cite> (playing
		2060	White):
		2061
		2062	<p>1. Ng5 (+.277) h6 2. Nh7 (+.321) Kg8 3. Qh5 (+.133) Qg7 4. Ng5
		2063	(-2.122) hxg5
		2064
		2065	<p>So, the knight got trapped at h7, and at move 4
		2066	<cite>Crafty</cite> discovered that this is gross and "learns" this
		2067	result/position.
		2068
		2069	<p>We play the exact same game again: except that two things can
		2070	happen here.
		2071
		2072	<p>1. It might be that g5 is the only square the knight can move
		2073	to here, which means this whole thing is forced. The first search
		2074	would find 1. Ng5 (-2.122) if the search can reach 8 plies deep, which
		2075	happens even in 5 second games. It's learned that Ng5 is bad. It
		2076	stores this position in the permanent hash file also, and the next
		2077	time you try this same trap, it will discover 4-5 moves earlier that
		2078	if the knight gets to g5 it is in trouble. Each game will diverge
		2079	from the first game 3-4 moves earlier. Simple and effective.
		2080
		2081	<p>2. Ng5 might not be forced, and if not, it knows Ng5 loses a
		2082	piece for a pawn, so it will promptly play something else, which is
		2083	exactly what is desired.
		2084
		2085	<p>This is implemented with two (count 'em, two) files. One file
		2086	"<code>position.bin</code>" is a binary file that contains the hash
		2087	table entries, and it right at one megabyte in size, max. (16 bytes
		2088	per hash entry X 65536 entries = exactly one meg, but I have 8 extra
		2089	bytes for the FIFO queue implementation and to see how many entries
		2090	are currently in the file if it is not full.
		2091
		2092	<p>The second file is "<code>position.lrn</code>" and is, you
		2093	guessed it, a file that can be shared with others, just like book.lrn.
		2094	It contains all information needed to reconstruct the position, the
		2095	score, the depth, etc. and also included the pgn tags for who was
		2096	what color and when the game was played...
		2097
		2098	<p>This data can be imported with the new <a
		2099	href="#import"><strong>import</strong></a> command (the old book learn
		2100	<filename> is no longer around) which will import either
		2101	book.lrn type data or position.lrn type data and can tell them apart
		2102	without your having to do anything. The [<strong>clear</strong>]
		2103	option is still there, should you want to use it, and simply removes
		2104	the position.lrn and position.bin files before starting the import
		2105	process for position learning.
		2106
		2107	<p>This can be turned off, if you like, by checking out the <a
		2108	href="#learn"><strong>learn</strong></a> command, which gives you the
		2109	ability to turn off book learning (as it presently works), position
		2110	learning, and the next book learning stage which will add to the book
		2111	in addition to learning which book lines are good and bad.
		2112
		2113
		2114	<h3>
		2115	What is this new "result" learning?</h3>
		2116
		2117	Result learning works just like normal book learning, except
		2118	that if <cite>Crafty</cite> is checkmated or resigns, it will step back
		2119	through the book line to find the last point where it had
		2120	more than one move to choose from. It will flag the move it
		2121	chose as "never play again".
		2122
		2123	<p>This handles the case where the first ten non-book moves produce
		2124	reasonable scores, but the position is one that <cite>Crafty</cite>
		2125	simply can't handle very well. If it loses such a game, it will still
		2126	vary the next time this opening is played, as otherwise it would
		2127	possibly repeat the same opening, and would certainly repeat the
		2128	remainder of the game.
		2129
		2130	<p>All three learning modes are turned on by default, although any
		2131	of them can be disabled with the appropriate command option to <a
		2132	href="#learn"><strong>learn</strong></a>.
		2133
		2134
		2135	<hr>
		2136	<address></address>
		2137	<!-- hhmts start --> Last modified: Sat Dec 20 01:41:05 EST 2003 <!-- hhmts end -->
		2138	</body> </html>

Subversion Repositories Games.Chess Giants

Games.Chess Giants/engines/Crafty/readme.html @ 31 – Rev