+++ /dev/null
-README
-GNU CHESS 5
-by Stuart Cracraft <cracraft@gnu.org>
-copyright (c) 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1992, 1993
-1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001
-Modified Simon Waters <simon@wretched.demon.co.uk> 2001
-Modified Simon Waters <simon@wretched.demon.co.uk> 2003
-
-IMPORTANT: Please send all updates to Simon at the above address.
-
-Table of Contents
-
- Introduction
- Who We Are
- Data Structures
- Move Generator
- Search
- Evaluation
- Book
- Hash Table
- Auxillary File Formats (PGN, EPD)
- Universal Board
- Caveats
- Compilers
- Internet
- Xboard/Winboard
- Command List
-
-
-INTRODUCTION
-
-Welcome to the GNU CHESS 5 README. This is somewhat different than
-a normal readme. You might consider this a manual. We've always found
-multiple documents confusing, overlapping and sometimes contradictory
-as far as software documentation goes. By putting it all together in
-one place we hope to avoid these traditional inadequacies and be able
-to maintain a single document. If you add documentation, add it to
-this document only.
-
-GNU Chess 5 is the new version of GNU Chess. The goal of creating this
-new version was to eliminate perceived problems with past versions, the
-major one being spaghetti-code that was extremely poorly documented, but
-another being antiquated data structures and especially the ignominous
-linked list. Another good reason was to have more standard file formats
-for game positions and game listings.
-
-
-WHO WE ARE
-
-We are the GNU Chess developers and you may reach us at
-
- bug-gnu-chess@gnu.org
-
-We are indebted to our sponsor, the Free Software Foundation
-whose web page is:
-
- http://www.gnu.org
-
-and which also serves as our software depository for new versions of
-GNU and GNU Chess.
-
-We also have a Usenet bulletin board, gnu.chess. Feel free to post and
-support. Please become a developer and contribute your time and coding skill
-to GNU Chess. Make a donation of your time and money.
-
-But, as developers we like to develop our own ideas. Thus, if you have
-an idea check to see that no one else is working on it (posting on the
-above bulletin board or sending an email should be sufficient to find
-if someone is working on the idea and if you can collaborate with
-them.)
-
-We don't like messages asking us to implement features. Everybody
-has a list a mile long. Instead, contribute by writing code or pointing
-out very clearly a bug. To report a bug, tell us the version number
-of the program ("./gnuchess --version").
-
-The code is provided for the purpose of encouraging you to do the
-programming. If you lack the programming skills to do so, try
-dabbling in it. You might surprise yourself.
-
-
-DATA STRUCTURES
-
-The primary data structure of GNU Chess is the bitboard. A bitboard
-is a 64-bit GNU C long long. It represents characteristics of a position.
-For example, 12 bitboards are sufficient to describe the whereabouts
-of all the pieces for both sides, i.e.
-
- BitBoard board.b[2][6];
-
-So for example with a knight equal to 2 and white equal to 0 all the
-knights are located by the reference
-
- #define white 0
- #define knight 2
-
- ... board.b[white][knight] ...
-
-Testing whether a particular square has a knight on it could be done
-with
-
- if (BitBoard[B1] & board.b[white][knight]) { ... }
-
-Another set of move arrays is helpful for calculating the simple moves
-of a knight or a king
-
- MoveArray[knight or king][sq]
-
-This returns a bitmap of the squares from which a knight or king
-could move from the square sq. Squares are based at 0 for a1 (White's
-queen's rook 1) and numbered left to right up until 63 for h8 (Black's
-king's rook 1).
-
-Another basic data structure is the board. It is defined in common.h
-as the Board typedef:
-
- typedef struct
- {
- BitBoard b[2][7]; /* Pieces by side (0 - white, 1 black
- by piece (1 - pawn ... 6 - king */
- BitBoard friend[2]; /* Friendly (this side's) pieces */
- BitBoard blocker; /* Enemy pieces */
- BitBoard blockerr90;
- BitBoard blockerr45;
- BitBoard blockerr315;
- short ep; /* Location of en passant square */
- short flag; /* Relevant flags relating to castle privs */
- short side; /* Color of side on move 0 - white 1 - black */
- short material[2]; /* Total material by side not inc. king */
- short pmaterial[2]; /* Total pawn material by side not inc. king */
- short castled[2]; /* True (1) if side is castled */
- short king[2]; /* Location of king 0 - a1 .. 63 - h8 */
- } Board;
-
-Basic data structure typedefs are defined in common.h and allocated in
-main.c for the most part. Please read and understand those files. The
-best way to understand data structures is to add new evaluation terms.
-
-MOVE GENERATOR
-
-This is a rotated bit-board method which is considered state-of-the-art
-currently.
-
-SEARCH
-
-Based on Professor Tony Marsland's modification to alpha-beta minimax,
-called Principal Variation Search (PVS), this algorithm performs credibly.
-
-EVALUATION
-
-Evaluation in this version is quite a bit different than before.
-Earlier versions used piece/square tables with some end-leaf
-evaluation (but primary pc/sq tables). These are tables filled with
-values regarding the importance of having pieces on particular squares.
-It was filled once, at the beginning of the search.
-
-The drawback of pc/sq tables is that the information is typically of
-less and less importance the deeper a program searches because the
-board changes so much. With computers getting faster and faster, deeper
-and deeper searches are possible and so the pc/sq tables can provide
-misleading direction to the program, resulting in anti-positional moves.
-
-More recently there has been a return by some to what we espouse here:
-full end-leaf evaluation. Further, we use bitboards (64-bit quantities)
-to represents characteristics of the board. This harkens back, ironically
-to the early days of computer chess when giant number-crunching machines
-back in the 60's used bitmaps to describe positions.
-
-Bitboards in this version of GNU are defined using the "BitBoard" typedef
-defined in common.h. main.c contains most of the bitboards and these
-are accessed and used throughout the program and particularly by
-the move generator and the evaluator.
-
-The evaluator in eval.c consists of a series of scoring routines like
-ScoreP (), ScoreN (), ScoreB (), corresponding to the piece being
-scored. The routine evaluates all pieces of that type (P - pawn,
-N - knight, B - bishop, etc.) on the current board and returns a
-score.
-
-Typically a loop is used of the form
-
- short sq; /* Location of the piece of this type */
- short s; /* Score value for all pieces
- BitBoard b; /* Stores the bitboard representing location of the piece */
- s = 0; /* Score starts out as zero */
- b = board.b[side][knight];
- while (b) {
- sq = leadz(b);
- CLEARBIT (b, sq);
- if (piece on sq has some property)
- s += SOME_BONUS_OR_PENALTY; /* defined in eval.h */
- }
- return(s);
-
-As you can see, this routine locates each piece in the 64-bit map
-where the corresponding square of the 64 is set to 1 meaning a piece
-is there. Hence for example in the opening position, board.b[white][bishop]
-would have the 3rd and 7th low-order bits set corresponding to the original
-locations of bishops in a game on C1 and F1. Likewise the values
-BitPosArray[C1] and BitPosArray[F1] can be used to return 64-bit
-quantities for checking specific matches as in
-
- if (BitPosArray[A1] & board.b[side][bishop])
- s += SOME_VERY_NEGATIVE_PENALTY_FOR_BISHOP_IN_A1_CORNER
-
-Writing evaluation code comes very naturally using these methods. Try
-to avoid too many specific square checks as those are expensive. Ideas
-as shown in the CTL() routine can be used to check for piece placement
-on specific squares being advantageous or disadvantageous.
-
-Primary evaluation is done with Evaluate(). Certain specifics are
-calculated which are deemed very important such as king evaluation
-and pawn evaluation. Then a "lazy evaluation" scenario is checked
-for which can save time. Otherwise other pieces are also evaluated.
-
-Very important for evaluation is the ability to see what board you
-are evaluating. Typically this should be sufficient when you add
-the new term:
-
- /* ... new logic ... */
- {
- s += SOME_NEW_BONUS (define in eval.h)
- printf("The condition is triggered:\n");
- ShowBoard ();
- getchar();
- }
-
-This lets you see the board at the point the condition is triggered
-which adds the bonus or penalty to the evaluation score.
-
-
-BOOK
-
-The opening book is implemented as a simple binary file consisting of
-a set of sequential records of struct hashtype as defined in the module
-book.c. This data structure is simply two part, a 64-bit HashType (see
-common.h) and a 32-bit score.
-
-The binary book stored in book.dat is compiled from the file book.pgn
-using the command "book add book.pgn" into a sequential set of binary
-records in the format as described above. book.pgn is simply a set of
-game records in portable game notation format. A set of master games
-may be used or specific openings programmed this way for a user-changeable
-opening book.
-
-HASH TABLE
-
-The hash table is simply an area of memory where information about
-positions is stored. In this version of the program there are two
-types of hash tables: general and pawn.
-
-The general hash table size is controlled by the variable HASHSLOTS
-as defined in common.h. Likewise the pawn hash table size is controlled
-by the variable PAWNSLOTS in common.h.
-
-The number of hashtable slots can be controlled from the command
-line (Type "gnuchess -help" for details), or via the interactive
-hashsize command.
-
-Typically middle-game searches are sped up by 25%-50% by the general
-hash table and by much more in endgames where there are few pieces
-(because so many of the positions turn out to be cached already in
-the hash table.)
-
-Pawn evaluation is traditionally expensive because there are so many
-things to evaluate. The pawn hash table remembers all the different
-pawn structures in the search. Typically pawn structure evaluation
-(without reference to pieces) may be calculated by simple table
-lookup this way 90-99% of the time. Hence, any amount of pawn logic
-that is pure-pawn and not related to pieces may be added without guilt.
-On the other hand, pawn structure that relates to pieces must be
-recalculated for every position. See ScoreP() in eval.c
-
-
-AUXILLARY FILE FORMATS
-
-.dat - binary book format, simply a 64-bit position hash and a 32-bit score
-.pgn - game listing like 1. e4 e5 2. Nf3 etc.
-.epd - epd-style format using FEN notation. See tests subdirectory for example.
-log.nnn - record of an entire game from computer's viewpoint (thinking, etc.)
-game.nnn - record of an entire game, similar to .pgn but auto-generated
-
-The .dat file format is a simple binary format for the compiled book
-which is read by the program when it is using book. See the section BOOK
-for more detail.
-
-EPD and PGN require little introduction. These are the uniformly accepted
-standards for position recording and game recording.
-
-Note that log.nnn and game.nnn files are written at the end of a game
-when you use the "name" command to give the computer your name. It is
-highly recommended to do this since the resulting two files that match
-in a monotonically-increasing extension numbered suffix may be used for
-reporting bugs and keeping track of your games.
-
-
-COMPILERS
-
- We like GNU C in all its various forms. For Unix and Linux, use GNU C.
-
- For Microsoft Windows platforms we compile and test using Cygwin,
- which is a port of many GNU packages, including GCC.
-
- Cygwin may require specific run time DLL's to provide the interface,
- these should be provided with any executable you receive.
-
- Whilst GCC is the supported compiler, a key goal is portability. If
- you experience problems compiling GNU Chess with a modern C compiler
- please let the developers know.
-
-INTERNET
-
- GNU CHESS 5 has been tested substantially on the Free Internet Chess
- Servers (freechess.org) with Xboard (See Zippy documentation in the
- Xboard/Winboard distribution http://www.tim-mann.org/).
-
- GNU Chess 5.06 and later should also operate with icsDrone. Testing
- 5.06 with icsDrone 1.5.0 showed no immediate issues.
-
-XBOARD/WINBOARD
-
- Running the program with the "--xboard" command line parameter sets it
- to produce output acceptable to and accept input suitable for xboard
- and winboard, the graphical display front-ends with mouse interface.
-
- For historical reasons the option "xboard" does not need to be
- preceeded by "--", however we would encourage the new syntax.
-
-COMMAND LIST
-
- ^C
- Typically the interrupt key stops a search in progress,
- makes the move last considered best and returns to the
- command prompt
-
- quit
- Quit the program.
- exit
- In analysis mode this stops analysis, otherwise it quits the program.
-
- help
- Produces a help blurb corresponding to this list of commands.
-
- usage
- Produce blurb on command line options.
- (Same as "gnuchess --help")
-
- book
- add - compiles book.dat from book.pgn
- on - enables use of book
- off - disables use of book
- best - play best move from book
- worst - play worst move from book
- random - play any move from book
-
- prefer (default) - choose a good move from book
- (Method subject to variation)
-
- version
- prints out the version of this program
- (Same as "gnuchess --version")
-
- pgnsave FILENAME
- saves the game so far to the file from memory
-
- pgnload FILENAME
- loads the game in the file into memory
-
- force
- manual
- Makes the program stop moving. You may now enter moves
- to reach some position in the future.
- (Same as "gnuchess --manual")
-
- white
- Program plays black, set white to move.
-
- black
- Program plays white, set black to move.
-
- (White and black commands are mainly for icsDrone
- and will cause the current en-passant capture
- square to be forgotten).
-
- go
- Computer takes whichever side is on move and begins its
- thinking immediately
-
- easy
- Disables thinking on opponent's time
- (Same as "gnuchess --easy").
-
- hard
- Enables thinking on opponent's time
-
- post
- Arranges for verbose thinking output showing variation, score,
- time, depth, etc.
-
- If pondering (see hard) is on, the program will output
- it's thinking whilst the opponent is thinking.
-
- (Also "gnuchess --post")
-
- nopost
- Turns off verbose thinking output
-
- name NAME
- Lets you input your name. Also writes the log.nnn and a
- corresponding game.nnn file. For details please see
- auxillary file format sections.
-
- result
- Mostly used by Internet Chess server.
-
- activate
-
- This command reactivates a game that has been terminated automatically
- due to checkmate or no more time on the clock. However, it does not
- alter those conditions. You would have to undo a move or two or
- add time to the clock with level or time in that case.
-
- rating COMPUTERRATING OPPONENTRATING
- Inputs the estimated rating for computer and for its opponent
-
- new
- Sets up new game (i.e. positions in original positions)
-
- time
- Inputs time left in game for computer in hundredths of a second.
- Mostly used by Internet Chess server.
-
- otim (NOT IMPLEMENTED)
- Mostly used by Internet Chess server.
-
- random (NOT IMPLEMENTED)
- Randomizes play by perturbing the evaluation score slightly.
- The degree of perturbation is adjustable.
-
- hash
- on - enables using the memory hash table to speed search
- off - disables the memory hash table
-
- hashsize N
- Sets the hash table to permit storage of N positions
- N is rounded down to nearest power of 2.
- (Also "gnuchess --hashsize=N")
-
- null
- on - enables using the null move heuristic to speed search
- off - disables using the null move heuristic
-
- xboard
- on - enables use of xboard/winboard
- off - disables use of xboard/winboard
- (Also "gnuchess --xboard")
-
- depth N
- Sets the program to look N ply (half-moves) deep for every
- search it performs. If there is a checkmate or other condition
- that does not allow that depth, then it will not be
-
- level MOVES MINUTES INCREMENT
- Sets time control to be MOVES in MINUTES with each move giving
- an INCREMENT (in seconds, i.e. Fischer-style clock).
-
- load
- epdload
- Loads a position in EPD format from disk into memory.
-
- save
- epdsave
- Saves game position into EPD format from memory to disk.
-
- switch
- Switches side to move
-
- solve FILENAME
- solveepd FILENAME
- Solves the positions in FILENAME
-
- remove
- Backs up two moves in game history
-
- undo
- Backs up one move in game history
-
- show
- board - displays the current board
- time - displays the time settings
- moves - shows all moves using one call to routine
- escape - shows moves that escape from check using one call to routine
- noncapture - shows non-capture moves
- capture - shows capture moves
- eval [or score] - shows the evaluation per piece and overall
- game - shows moves in game history
- pin - shows pinned pieces
-
- test
- movelist - reads in an epd file and shows legal moves for its entries
- capture - reads in an epd file and shows legal captures for its entries
- movegenspeed - tests speed of move generator
- capturespeed - tests speed of capture move generator
- eval - reads in an epd file and shows evaluation for its entries
- evalspeed tests speed of the evaluator
-
- analyze
- Switches program into analysis mode, this is primarily intended for
- communicating analysis to an external interface using the Xboard
- chess engine protocol. It enables "force", "post", and
- "hard", at the same time, whilst altering the
- output format of post to conform with the engine protocol.