3 by Stuart Cracraft <cracraft@gnu.org>
4 copyright (c) 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1992, 1993
5 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001
6 Modified Simon Waters <simon@wretched.demon.co.uk> 2001
7 Modified Simon Waters <simon@wretched.demon.co.uk> 2003
9 IMPORTANT: Please send all updates to Simon at the above address.
21 Auxillary File Formats (PGN, EPD)
32 Welcome to the GNU CHESS 5 README. This is somewhat different than
33 a normal readme. You might consider this a manual. We've always found
34 multiple documents confusing, overlapping and sometimes contradictory
35 as far as software documentation goes. By putting it all together in
36 one place we hope to avoid these traditional inadequacies and be able
37 to maintain a single document. If you add documentation, add it to
40 GNU Chess 5 is the new version of GNU Chess. The goal of creating this
41 new version was to eliminate perceived problems with past versions, the
42 major one being spaghetti-code that was extremely poorly documented, but
43 another being antiquated data structures and especially the ignominous
44 linked list. Another good reason was to have more standard file formats
45 for game positions and game listings.
50 We are the GNU Chess developers and you may reach us at
54 We are indebted to our sponsor, the Free Software Foundation
59 and which also serves as our software depository for new versions of
62 We also have a Usenet bulletin board, gnu.chess. Feel free to post and
63 support. Please become a developer and contribute your time and coding skill
64 to GNU Chess. Make a donation of your time and money.
66 But, as developers we like to develop our own ideas. Thus, if you have
67 an idea check to see that no one else is working on it (posting on the
68 above bulletin board or sending an email should be sufficient to find
69 if someone is working on the idea and if you can collaborate with
72 We don't like messages asking us to implement features. Everybody
73 has a list a mile long. Instead, contribute by writing code or pointing
74 out very clearly a bug. To report a bug, tell us the version number
75 of the program ("./gnuchess --version").
77 The code is provided for the purpose of encouraging you to do the
78 programming. If you lack the programming skills to do so, try
79 dabbling in it. You might surprise yourself.
84 The primary data structure of GNU Chess is the bitboard. A bitboard
85 is a 64-bit GNU C long long. It represents characteristics of a position.
86 For example, 12 bitboards are sufficient to describe the whereabouts
87 of all the pieces for both sides, i.e.
89 BitBoard board.b[2][6];
91 So for example with a knight equal to 2 and white equal to 0 all the
92 knights are located by the reference
97 ... board.b[white][knight] ...
99 Testing whether a particular square has a knight on it could be done
102 if (BitBoard[B1] & board.b[white][knight]) { ... }
104 Another set of move arrays is helpful for calculating the simple moves
105 of a knight or a king
107 MoveArray[knight or king][sq]
109 This returns a bitmap of the squares from which a knight or king
110 could move from the square sq. Squares are based at 0 for a1 (White's
111 queen's rook 1) and numbered left to right up until 63 for h8 (Black's
114 Another basic data structure is the board. It is defined in common.h
115 as the Board typedef:
119 BitBoard b[2][7]; /* Pieces by side (0 - white, 1 black
120 by piece (1 - pawn ... 6 - king */
121 BitBoard friend[2]; /* Friendly (this side's) pieces */
122 BitBoard blocker; /* Enemy pieces */
125 BitBoard blockerr315;
126 short ep; /* Location of en passant square */
127 short flag; /* Relevant flags relating to castle privs */
128 short side; /* Color of side on move 0 - white 1 - black */
129 short material[2]; /* Total material by side not inc. king */
130 short pmaterial[2]; /* Total pawn material by side not inc. king */
131 short castled[2]; /* True (1) if side is castled */
132 short king[2]; /* Location of king 0 - a1 .. 63 - h8 */
135 Basic data structure typedefs are defined in common.h and allocated in
136 main.c for the most part. Please read and understand those files. The
137 best way to understand data structures is to add new evaluation terms.
141 This is a rotated bit-board method which is considered state-of-the-art
146 Based on Professor Tony Marsland's modification to alpha-beta minimax,
147 called Principal Variation Search (PVS), this algorithm performs credibly.
151 Evaluation in this version is quite a bit different than before.
152 Earlier versions used piece/square tables with some end-leaf
153 evaluation (but primary pc/sq tables). These are tables filled with
154 values regarding the importance of having pieces on particular squares.
155 It was filled once, at the beginning of the search.
157 The drawback of pc/sq tables is that the information is typically of
158 less and less importance the deeper a program searches because the
159 board changes so much. With computers getting faster and faster, deeper
160 and deeper searches are possible and so the pc/sq tables can provide
161 misleading direction to the program, resulting in anti-positional moves.
163 More recently there has been a return by some to what we espouse here:
164 full end-leaf evaluation. Further, we use bitboards (64-bit quantities)
165 to represents characteristics of the board. This harkens back, ironically
166 to the early days of computer chess when giant number-crunching machines
167 back in the 60's used bitmaps to describe positions.
169 Bitboards in this version of GNU are defined using the "BitBoard" typedef
170 defined in common.h. main.c contains most of the bitboards and these
171 are accessed and used throughout the program and particularly by
172 the move generator and the evaluator.
174 The evaluator in eval.c consists of a series of scoring routines like
175 ScoreP (), ScoreN (), ScoreB (), corresponding to the piece being
176 scored. The routine evaluates all pieces of that type (P - pawn,
177 N - knight, B - bishop, etc.) on the current board and returns a
180 Typically a loop is used of the form
182 short sq; /* Location of the piece of this type */
183 short s; /* Score value for all pieces
184 BitBoard b; /* Stores the bitboard representing location of the piece */
185 s = 0; /* Score starts out as zero */
186 b = board.b[side][knight];
190 if (piece on sq has some property)
191 s += SOME_BONUS_OR_PENALTY; /* defined in eval.h */
195 As you can see, this routine locates each piece in the 64-bit map
196 where the corresponding square of the 64 is set to 1 meaning a piece
197 is there. Hence for example in the opening position, board.b[white][bishop]
198 would have the 3rd and 7th low-order bits set corresponding to the original
199 locations of bishops in a game on C1 and F1. Likewise the values
200 BitPosArray[C1] and BitPosArray[F1] can be used to return 64-bit
201 quantities for checking specific matches as in
203 if (BitPosArray[A1] & board.b[side][bishop])
204 s += SOME_VERY_NEGATIVE_PENALTY_FOR_BISHOP_IN_A1_CORNER
206 Writing evaluation code comes very naturally using these methods. Try
207 to avoid too many specific square checks as those are expensive. Ideas
208 as shown in the CTL() routine can be used to check for piece placement
209 on specific squares being advantageous or disadvantageous.
211 Primary evaluation is done with Evaluate(). Certain specifics are
212 calculated which are deemed very important such as king evaluation
213 and pawn evaluation. Then a "lazy evaluation" scenario is checked
214 for which can save time. Otherwise other pieces are also evaluated.
216 Very important for evaluation is the ability to see what board you
217 are evaluating. Typically this should be sufficient when you add
220 /* ... new logic ... */
222 s += SOME_NEW_BONUS (define in eval.h)
223 printf("The condition is triggered:\n");
228 This lets you see the board at the point the condition is triggered
229 which adds the bonus or penalty to the evaluation score.
234 The opening book is implemented as a simple binary file consisting of
235 a set of sequential records of struct hashtype as defined in the module
236 book.c. This data structure is simply two part, a 64-bit HashType (see
237 common.h) and a 32-bit score.
239 The binary book stored in book.dat is compiled from the file book.pgn
240 using the command "book add book.pgn" into a sequential set of binary
241 records in the format as described above. book.pgn is simply a set of
242 game records in portable game notation format. A set of master games
243 may be used or specific openings programmed this way for a user-changeable
248 The hash table is simply an area of memory where information about
249 positions is stored. In this version of the program there are two
250 types of hash tables: general and pawn.
252 The general hash table size is controlled by the variable HASHSLOTS
253 as defined in common.h. Likewise the pawn hash table size is controlled
254 by the variable PAWNSLOTS in common.h.
256 The number of hashtable slots can be controlled from the command
257 line (Type "gnuchess -help" for details), or via the interactive
260 Typically middle-game searches are sped up by 25%-50% by the general
261 hash table and by much more in endgames where there are few pieces
262 (because so many of the positions turn out to be cached already in
265 Pawn evaluation is traditionally expensive because there are so many
266 things to evaluate. The pawn hash table remembers all the different
267 pawn structures in the search. Typically pawn structure evaluation
268 (without reference to pieces) may be calculated by simple table
269 lookup this way 90-99% of the time. Hence, any amount of pawn logic
270 that is pure-pawn and not related to pieces may be added without guilt.
271 On the other hand, pawn structure that relates to pieces must be
272 recalculated for every position. See ScoreP() in eval.c
275 AUXILLARY FILE FORMATS
277 .dat - binary book format, simply a 64-bit position hash and a 32-bit score
278 .pgn - game listing like 1. e4 e5 2. Nf3 etc.
279 .epd - epd-style format using FEN notation. See tests subdirectory for example.
280 log.nnn - record of an entire game from computer's viewpoint (thinking, etc.)
281 game.nnn - record of an entire game, similar to .pgn but auto-generated
283 The .dat file format is a simple binary format for the compiled book
284 which is read by the program when it is using book. See the section BOOK
287 EPD and PGN require little introduction. These are the uniformly accepted
288 standards for position recording and game recording.
290 Note that log.nnn and game.nnn files are written at the end of a game
291 when you use the "name" command to give the computer your name. It is
292 highly recommended to do this since the resulting two files that match
293 in a monotonically-increasing extension numbered suffix may be used for
294 reporting bugs and keeping track of your games.
299 We like GNU C in all its various forms. For Unix and Linux, use GNU C.
301 For Microsoft Windows platforms we compile and test using Cygwin,
302 which is a port of many GNU packages, including GCC.
304 Cygwin may require specific run time DLL's to provide the interface,
305 these should be provided with any executable you receive.
307 Whilst GCC is the supported compiler, a key goal is portability. If
308 you experience problems compiling GNU Chess with a modern C compiler
309 please let the developers know.
313 GNU CHESS 5 has been tested substantially on the Free Internet Chess
314 Servers (freechess.org) with Xboard (See Zippy documentation in the
315 Xboard/Winboard distribution http://www.tim-mann.org/).
317 GNU Chess 5.06 and later should also operate with icsDrone. Testing
318 5.06 with icsDrone 1.5.0 showed no immediate issues.
322 Running the program with the "--xboard" command line parameter sets it
323 to produce output acceptable to and accept input suitable for xboard
324 and winboard, the graphical display front-ends with mouse interface.
326 For historical reasons the option "xboard" does not need to be
327 preceeded by "--", however we would encourage the new syntax.
332 Typically the interrupt key stops a search in progress,
333 makes the move last considered best and returns to the
339 In analysis mode this stops analysis, otherwise it quits the program.
342 Produces a help blurb corresponding to this list of commands.
345 Produce blurb on command line options.
346 (Same as "gnuchess --help")
349 add - compiles book.dat from book.pgn
350 on - enables use of book
351 off - disables use of book
352 best - play best move from book
353 worst - play worst move from book
354 random - play any move from book
356 prefer (default) - choose a good move from book
357 (Method subject to variation)
360 prints out the version of this program
361 (Same as "gnuchess --version")
364 saves the game so far to the file from memory
367 loads the game in the file into memory
371 Makes the program stop moving. You may now enter moves
372 to reach some position in the future.
373 (Same as "gnuchess --manual")
376 Program plays black, set white to move.
379 Program plays white, set black to move.
381 (White and black commands are mainly for icsDrone
382 and will cause the current en-passant capture
383 square to be forgotten).
386 Computer takes whichever side is on move and begins its
390 Disables thinking on opponent's time
391 (Same as "gnuchess --easy").
394 Enables thinking on opponent's time
397 Arranges for verbose thinking output showing variation, score,
400 If pondering (see hard) is on, the program will output
401 it's thinking whilst the opponent is thinking.
403 (Also "gnuchess --post")
406 Turns off verbose thinking output
409 Lets you input your name. Also writes the log.nnn and a
410 corresponding game.nnn file. For details please see
411 auxillary file format sections.
414 Mostly used by Internet Chess server.
418 This command reactivates a game that has been terminated automatically
419 due to checkmate or no more time on the clock. However, it does not
420 alter those conditions. You would have to undo a move or two or
421 add time to the clock with level or time in that case.
423 rating COMPUTERRATING OPPONENTRATING
424 Inputs the estimated rating for computer and for its opponent
427 Sets up new game (i.e. positions in original positions)
430 Inputs time left in game for computer in hundredths of a second.
431 Mostly used by Internet Chess server.
433 otim (NOT IMPLEMENTED)
434 Mostly used by Internet Chess server.
436 random (NOT IMPLEMENTED)
437 Randomizes play by perturbing the evaluation score slightly.
438 The degree of perturbation is adjustable.
441 on - enables using the memory hash table to speed search
442 off - disables the memory hash table
445 Sets the hash table to permit storage of N positions
446 N is rounded down to nearest power of 2.
447 (Also "gnuchess --hashsize=N")
450 on - enables using the null move heuristic to speed search
451 off - disables using the null move heuristic
454 on - enables use of xboard/winboard
455 off - disables use of xboard/winboard
456 (Also "gnuchess --xboard")
459 Sets the program to look N ply (half-moves) deep for every
460 search it performs. If there is a checkmate or other condition
461 that does not allow that depth, then it will not be
463 level MOVES MINUTES INCREMENT
464 Sets time control to be MOVES in MINUTES with each move giving
465 an INCREMENT (in seconds, i.e. Fischer-style clock).
469 Loads a position in EPD format from disk into memory.
473 Saves game position into EPD format from memory to disk.
476 Switches side to move
480 Solves the positions in FILENAME
483 Backs up two moves in game history
486 Backs up one move in game history
489 board - displays the current board
490 time - displays the time settings
491 moves - shows all moves using one call to routine
492 escape - shows moves that escape from check using one call to routine
493 noncapture - shows non-capture moves
494 capture - shows capture moves
495 eval [or score] - shows the evaluation per piece and overall
496 game - shows moves in game history
497 pin - shows pinned pieces
500 movelist - reads in an epd file and shows legal moves for its entries
501 capture - reads in an epd file and shows legal captures for its entries
502 movegenspeed - tests speed of move generator
503 capturespeed - tests speed of capture move generator
504 eval - reads in an epd file and shows evaluation for its entries
505 evalspeed tests speed of the evaluator
508 Switches program into analysis mode, this is primarily intended for
509 communicating analysis to an external interface using the Xboard
510 chess engine protocol. It enables "force", "post", and
511 "hard", at the same time, whilst altering the
512 output format of post to conform with the engine protocol.