ColChess v7.x.y ReadMe
----------------------

Cambridge, 13th August 2000


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.

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.


-- Setting Up --

Whether or not you set the path directly in the code, you should also set up
an environment variable to point to your chess program's path.  This isn't
necessary, but it's a little tidier.  If you don't do this then you must
make sure to run ColChess from within its install directory or it won't be
able to find some necessary files.  Setting the path should be done in the
following way;

> COLCHESS_PATH=/home/chess/
> export COLCHESS_PATH

..where you replace the path in the first of these two commands with the
location of ColChess, including the final '/'.

You might want to add these two lines to your .bashrc file, which will be
located in your home directory.  This might have a different name depending
on what shell you're using, i.e. .mytcshrc or similar.  It's the file where
all your user-defined aliases are kept.

Next you should type;

> source .bashrc

To enable these changes. (Replacing .bashrc with whatever this file is on
your system)

If ColChess is going to be usable by the entire system, then add
these two lines in the /etc/profile  file instead.  You should then type;

> source /etc/profile

and everything will be set up nicely.



(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'.



(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.

Included in the distribution is a colchess.ini file, which you should copy
to your windows root directory.  This is not strictly necessary, and
ColChess should still find it if you leave it in your install directory.
It might be a wise idea to leave one copy in each directory.  ColChess will
first search the current directory, and if it cannot find a .ini file then
it will search the windows directory.  This is usually c:\windows, but varies
depending on your system.

This colchess.ini file is not vital, but it helps ColChess find out where a few
other files are kept, and sets up some default parameters.  You will first need
to alter the line in colchess.ini which reads;

COLCHESS_PATH=c:\games\colchess\

You can use notepad or a similar text editor.  Change this to the correct path for
wherever ColChess is installed on your system.  No reboot is needed as ColChess
just reads in the file if it exists, and if it can't find it then ColChess
makes its best guess!

-- More Advanced Solutions --

You could instead set an environment variable to fix ColChess's path by adding
the following line to your autoexec.bat file;

set COLCHESS_PATH=c:\games\colchess\

remembering the final backslash!  Here the right hand side is wherever you
have installed ColChess on your machine.  You will then need to reboot your
system for the changes to take effect.  If you have the colchess.ini file
set up correctly then this is not necessary.


-- 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
chess.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 right-
clicking 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 in continuous development, 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;

cmf29@cam.ac.uk

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!

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$  COMMENTS\n
Suggested Moves for this position\n

The moves are in the format;

e2e4[0,0,0]{1}

and are space separated.  Here, e2e4 means 'White's King's pawn forward
two', and the three numbers in brackets are castling, en-passant, and
promotion values respectively.  You shouldn't need to touch the second or
third, but the first one is coded as follows;

0 = Not castling
1 = Castling King's side
2 = Castling Queen's side

If all three numbers are 0 then you can leave this [] part out, as I have done
in the large opening book provided separately from my home page.

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.

After the FEN there is a dollar '$' sign, which is ignored, and anything
following that until the end of the line is also ignored.  This can be used
for notating the positions, as I have done with the small example book provided.
If ColChess adds a new position then it will automatically notate it properly.

By all means customise your opening book, but the most powerful feature of
it is learning.  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 chess.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 checkmate,
Total number of positions,
Percentage of positions where a correct move was given,
Percentage of positions where a 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.



(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, August 2000
