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