ColChess v8.x.y ReadMe
Cambridge, 14th October 2001
CONTENTS
(1) Compiling and Running ColChess
(2) Compilation Problems
(3) Xboard compatability
(4) Windows Users (inc. WinBoard compatability)
(5) Development
(6) Opening Book
(7) EPD Test Suites
(8) Copyright Notices
(1) COMPILING AND RUNNING COLCHESS *****
**Windows users refer to section (4)
Unix/Linux Installation;
Once you have downloaded the source .tgz file, simply change into your home directory (or wherever you want to install ColChess) and type;
> tar -xvzf chess.tgz
( the '>' character is the UNIX prompt, not something to type in! )
ColChess will un-tar itself into a subdirectory. The chances are that if you are reading this then you have already managed that bit!
To compile ColChess, you first need to alter one or two things.
- First of all, alter the line in chess.c that looks like this;
char path[FILENAME_MAX] = "./"; /* <---- PATH TO CHESS DIRECTORY!!!! */
so that it has the path to wherever you've installed ColChess on your system. You can get round this problem by defining an environment variable as shown below, or always running it from within its own directory. Note that this isn't important from version 8.0 onwards as the datafiles are hardcoded. It will, however, affect where your saves are stored.
- Next, change into the ColChess main directory, and type;
- make
.. and with a bit of luck, ColChess will compile just fine. To run it, simply type 'chess' or './chess' depending on your system.
####****----
If you're not happy with altering the 'c' files, then just compile ColChess
as it is.
####****----
-- Optimal Compilation --
For optimal performance, I suggest instead using the single file colchess.c which is distributed with the source. If instead of typing 'make' to compile ColChess, you simply type;
> gcc -o chess colchess.c -O3
..then the compiler will put all source code in one file, allowing more efficient optimisations. The output from this method is about 20-30% faster on average.
(2) COMPILATION PROBLEMS *****
If you don't have gcc installed on your system, then you need to alter the Makefile to use whatever 'c' compiler you normally use.
Edit the line that begins;
gcc -o <etc......>
and replace 'gcc' with your compiler's name. I suggest you still use the optimised method of compilation, described above under 'Optimal Compilation'.
If you're using a development environment then consult the particular manual or helpfiles for that environment.
(3) XBOARD COMPATABILITY *****
Since version v6.2, ColChess interfaces automatically with Xboard and Winboard and requires no extra recompiles. I suggest using the following command line options;
> xboard -size average -fcp "chess" -fd <chessdir> &
where <chessdir> is the directory where you installed ColChess. You may also have to add ColChess to your path so that Xboard knows where it can be found. This can be done in your .bashrc file as described above under 'Setting Up'.
If you want to set up the options for ColChess, e.g. hash size, then just use the command line options. They are;
CHESS Q<quiescence depth> H<hash size> D<search depth> L<Time limit> SW<White Player Skill> SB<Black Player Skill> DEATH WHITE BLACK BOTH LEARN NOLEARN BOOK NOBOOK
(4) WINDOWS USERS *****
Unzip the file colchess.zip into a directory on your hard drive. I have included a binary for the WinBoard version just in case you need it, but I suggest that you recompile ColChess from scratch if possible. If you don't have a 'c' compiler then by all means just copy the file chess.exe into a suitable location, along with all the other files from the zip, maintaining the directory structure as in the zip. You should end up with a main directory containing most of the files, and a games\ directory and a tests\ directory off this.
-- Compiling --
If you have a 'c' compiler and the source code then you can alter the diretory that ColChess looks for files in by altering the line near the beginning of chess.c which reads similar to;
char path[MAX_FILENAME] = ""
.. and recompiling. You can also change other options if you so desire by messing around with the source, but for inexperienced programmers I recommend leaving them as they are.
Before you compile, you'll also need to alter the line in common.h which reads;
/*#define _WIN32 */
..and remove the comment marks '/' and '/'. You may find (depending on your distribution) that this has already been done.
-- WinBoard Interfacing --
To interface with WinBoard, I recommend creating a shortcut to WinBoard in your start menu or desktop, and altering its properties. This can be done by rightclicking on the icon, and selecting the 'properties' tab. Then, go to the line which says 'target', and should contain the text
"c:\Program Files\WinBoard\winboard.exe"
..where the path will depend on where you installed it.
After this entry, insert the following;
-cp -fcp "chess.exe" -fd "c:\games\colchess\" -scp "chess.exe" -sd "c:\games\colchess\"
(all on the one line, and replacing the directory shown here with the one you want to use for ColChess)
Alternatively, simply copy the file 'chess.exe' to your winboard directory, and just add;
-cp -fcp "chess.exe" -scp "chess.exe"
after the winboard.exe path in the same box.
This should work, though you might need to play around with it a little, and the path will still need to be set up properly (see above)
You might find that you have problems running ColChess under WinBoard if you use a filename longer than 8 characters. I suggest you don't rename the .exe, or just rename it to ColChess.exe or something similar. I have no idea why this is - it's just some strange Windows problem.
Let me know if you have any problems with ColChess under Windows, but I rarely use Windows myself so I might not be able to help.
(5) DEVELOPMENT *****
ColChess is a finished project, but feel free to alter the code yourselves. I have commented it quite a lot, but not extravagantly. If you want me to explain one particularly obscure bit of code then feel free to email me on;
Also, make sure you also get the latest code versions, and check what I've done recently myself. This will save you doubling work that I've already done! Of course, this is an old project, and the quality of the code is abysmal. I do apologise for that. I suggest you instead check out my latest project, Beowulf.
http://www.ast.cam.ac.uk/~cmf/chess/beowulf.html
If you manage to get test results for ColChess on a different system to my own (P3 450, Red Hat Linux 6.1) then I'd also be grateful if you could tell me.
Finally, any code enhancements you manage to make, I would be more than happy to hear about!
(6) OPENING BOOK ****
I finally gave up after much deliberation, and for ColChess v5.0 I added an opening book in an extremely naive way. This isn't designed to be one of those enormous opening books like Crafty or GNUChess has, it's just meant to stop me wasting my time trying to make ColChess play sensible moves for the first 2 or 3 ply when I should be spending my time more productively. Basically, if the book ever get so large that the stupid way I've implemented it actually causes problems, then I'll think about rewriting it properly.
The format of each entry is as follows;
FEN Position\n
Suggested Moves for this position\n
The moves are in the format;
e2e4{1}
and are space separated. Here, e2e4 means 'White's King's pawn forward two'. A promotion move is coded like so;
a7a8Q{1}
where the promotion piece is written after the move using CAPS for white and lower case for black.
The final number in braces {} is the weighting for this particular move. A weighting of zero means that this move is recognised, but will never be played. In addition, ColChess will never raise its score above zero. This is useful for noting lines that you want ColChess to learn how to defend against, but which you don't want it to play.
By all means customise your opening book, but its most powerful feature is the ability to learn. ColChess automatically learns from its mistakes (and successes). Every time a game ends in checkmate or resignation, ColChess checks to see if there is an opening book, and it updates it. Firstly, it goes through every move the winning side played. If it has already got an entry for that position then it checks to see if the move played exists. If it does, then it increases its score by 1, otherwise, it adds it and sets its score to 1. After adding a new move, ColChess quits the book updating function. If the game was very short (i.e. the winning side played really well) then the score for any new moves is increased by 2. This encourages playing moves which are good refutations to blunder moves.
If the position does not exist then ColChess adds it to the book, along with its best move, and stops.
Note, ColChess will only add positions up to a certain number of ply into the game, determined by the global define in common.h;
#define learn_max_ply <num ply>
Default is 40 ply. The learning can be turned off either by setting the variable 'learn' in ColChess either during the running of the program or as a command line parameter ('nolearn'). Alternatively, you can simply move the opening book so that there is no file called 'book.dat' in the chess directory. This will, however, also stop the opening book from being used completely. Note that the opening learning function is ON by default in the source, so you will need to alter chess.c to turn it off. Also note that the command 'book' turns off the opening book, but doesn't stop ColChess from learning new openings.
Also, please bear in mind that if ColChess is played against a weak player, then it might well get worse by using the learning method.
(7) EPD TEST SUITES ****
ColChess comes with a selection of EPD test suites. These can be used with the 'test' command. You must simply type in the name of the test suite (ColChess searches in the 'tests' directory off your program's main directory) and specify the maximum amount of time ColChess can spend on any one position. Results for the latest version can usually be found at;
http://www.ast.cam.ac.uk/~cmf/chess/tests.html
ColChess expects the test suite to be a list of positions, one per line, in the following format;
2rr3k/pp3pp1/1nnqbN1p/3pN3/2pP4/2P3Q1/PPB4P/R4RK1 w - - bm Qg6; id "WAC.001";
... where everything after the first semicolon is ignored.
The results ColChess gives are in the format;
Correct So Far: 232[60]/300 (77%)[20%]
where the 5 numbers are (in order);
Number of positions where correct move was given,
Number where ColChess saw a direct unavoidable checkmate for the side to play,
Total number of positions,
Percentage of positions where a correct move was given,
Percentage of positions where an unavoidable CM was seen.
The supplied tests are;
WAC - Win at Chess. General middle and endgame tactical problems. 300 tests BWTC - Brilliant Ways to Checkmate - Clever checkmating strategies. 1001 tests WCSAC - Winning Chess Sacrifices and Combinations. 1001 tests BK - Bratko-Kopec - Very Difficult middle- and end-game problems. 24 tests.
More can be found at Maro's web site;
http://www.geocities.com/CapeCanaveral/Launchpad/2640/pgn/tests/index.htm
If you get any new results then feel free to email me them. This function is really designed to be run in text mode, not under Xboard/Winboard.
-- EPDAnaly Mode --
This is a new function which I introduced for version 6.0 (and some late editions of v5.6) which compliments the 'test' function. This function does a similar job to 'test' but examines positions where there is no best move given. It reads in basic FEN positions such as this;
2rr3k/pp3pp1/1nnqbN1p/3pN3/2pP4/2P3Q1/PPB4P/R4RK1 w - -
it analyses these for the specified time, and then prints off its analysis. It can output to a log file if you specify this.
-- Annotating/Studying PGN Games --
ColChess has two features allowing you to read in and study or annotate PGN games. STUDY tells ColChess to read in a PGN file and to elarn new opening moves from it. This is particularly useful for building up large opening books from the games of your favourite grandmasters etc... There is also an option to force ColChess to actually think of the best move to play itself without wildly accepting the given move. This helps to avoid blunders.
The ANNOTATE function is similar. It loads in a PGN file, and then accepts a few analysis parameters and analyses each game in turn, going through each move and checking for mistakes and missed opportunities. Obviously, the longer you tell ColChess to search for, the more accurate this will be.
(8) COPYRIGHT *****
The core code to ColChess remains my property, and though it is freely distributed, I'd like to know if you use my code for your own purposes, and I'd appreciate it if you linked to my original website if possible. That can be found at;
http://www.ast.cam.ac.uk/~cmf/chess/index.html
I hope you enjoy using ColChess as much as I enjoy writing it!
Thanks,
Colin Frayn, October 2001