G. Wiesenekker. ZZZZZZ a chess program.
Copyright (C) 1993  G. Wiesenekker
E-mail: wiesenecker@sara.nl

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

WELCOME

Murphy's Chess Program Law:
Bugs in chess programs usually show up during computer chess championships.

INSTALLATION (UNIX ONLY)

Edit the Makefile, fill in your favourite C compiler and compiler flags.

Type 'make progs'.
  This compiles zzzzzz, fin2zzz and fin2tex.
Type 'make book'
  This compiles the opening book and checks the output against an
  output generated at my site.
Type 'make win'
  This solves the first 10 'Win At Chess' positions and checks the output
  against an output generated at my site. Only the timings should
	be different, not the stats.
(demo) Type 'make try'.
	This solves a number of problems on the file opt.txt with
	the evaluation function parameters in the file init.txt. The
	results are written to the file results.txt.

You are now ready to use the program. Type
touch game.txt
zzzzzz black game.txt
and play some moves.
(quit exits the program).

READ THIS TOO

The purpose of this distribution is to provide you with the source
code of a working chess program, so that you can improve it.
You can use it 'sec', but it plays poorly (say 1500 ELO), and because
it is designed to play in computer chess tournaments, the user interface
is not that friendly e.g.

Possible ZZZZZZ FAQ

Q: Why is it called ZZZZZZ?
A: During my studies in theoretical chemistry, I had to program a lot 
   in FORTRAN77. ZZZZZZ was the name of my fatal error routine (6 Z's,
   so that it appeared last in the program listing).

Q: ZZZZZZ gives strange error messages when I do something wrong.
A: Correct. The error messages are only understandable by someone who takes
   a look at the code.

Q: ZZZZZZ prints a weird malloc error when I start it up.
A: Probably the hash tables are too big. At startup ZZZZZZ prints
   the sizes of the hash tables in bytes.
   Edit zzzzzz.c and change CACHE_BITS and SCORE_CACHE_BITS to a lower value.
   Recompile and try again.

Q: How can I undo a move? 
A: Quit the program; Edit the file with the moves; Restart the program

Q: ZZZZZZ now uses 90 minutes for the first 60 moves, and than 60 minutes
   for the next 40 moves. How can I make it play with different time
   limits?
A: Edit util.c and change the GAME_TIME1 and GAME_TIME2 defines.
   Recompile.
   
Q: ZZZZZZ asks 'GameTimeUsed? (min) ' when 5 moves are played.
A: Correct. ZZZZZZ was designed as a computer chess tournament
   playing program, so you have to synchronize the internal clock
   of the computer with the external chess clock (especially
   useful if you missed the 'bleep' when ZZZZZZ announced it's move).
   Edit util.c and change the if ((ngame_moves > 0) and (ngame_moves % 5) == 0) to 
   if (FALSE).

Q: How can I change the starting position?
A: ZZZZZZ reads it's starting position from the file brd.txt. You
   can edit this file to get another starting position.

Q: I try to compile ZZZZZZ under DOS. It crashes..
A: The problem sits in arrays larger than 64K under DOS. You have to
   use far or huge pointers for these, and you have to allocate these
   using farmalloc. Either reduce CACHE_BITS and SCORE_CACHE_BITS to 
   values such that the hash tables are smaller than 64K, or insert
   huge and farmalloc 'at the right places' (I could not do this, because
   I do not have access to a DOS machine).

etc. etc.

HOW TO STUDY THE CODE

Study zzzzzz.h first, then zzzzzz.c and util.c. You are advised to study the 
the references as well.
Although the code is written reasonably well, there are some places 
where it is clear that Hm-the-tournament-is-next-week-and-that-
option-still-does-not-work-thoughts troubled my brain.
Some comments about my coding style:
Braces are placed like
{
}
If if-then-else is used inside a loop, I use continue, rather than
else to avoid excessive indentation.

PROGRAM OPTIONS
Note: an a MAC (which has no command line interface) you can enter these
options and commands in the file 'arg.txt'.

Commandline options:
-DepthMax n
   set the maximum search depth to n.
-TimeLimit t
   Set the time limit to t seconds per move (not used when playing a game
   against ZZZZZZ. Then the time limit is calculated from the GAME_TIME and
   NGAME_MOVES parameters in util.c).
-GameTimeUsed t
   Set the GameTimeUsed to t seconds (only used when playing a game against
   ZZZZZZ. Useful when you entered a wrong move, and have to edit the file with the
   moves played sofar to undo the move).
-NoBook
   Disable opening book;
-NoAppend
   Do not append the move played to the file with moves (useful when debugging).

The possible commands are:

pos posfile
  Reads in the chess positions on the file posfile and prints the legal 
  moves for white and black and the static evaluation for white and black.
  Useful when debugging the move generation and the static evaluation
  function. Try 'zzzzzz pos pos.txt' for an example.

anal gamefile
  Reads in the moves in the file gamefile and evaluates each position of 
  the game. Try 'zzzzzz anal anal.txt' for an example.

solve problemfile
  Reads in the positions on the file problemfile, the colour to move and
  the best move in that position and compares it to the move ZZZZZ would
  have played in that position. After reading all positions the number
  of problems solved is printed.
  Lang and Smith (See ICCA journal, september 1993) have released in
  the Public Domain a test suite (available by ftp from 
  external.nj.nec.com in pub/wds/ChessTest.tar.Z) which contains 
  files with a large number of problems.
  The program fin2zzz reads from standard input a Lang&Smith file
	(with the leading and trailing comments stripped)
  and writes to standard output a file that can be read by zzzzzz.
  The program fin2tex reads from standard input a Lang&Smith file
  and writes to standard output a file that can by typeset by LaTeX
  if you have the chess12 macro's (available from many TeX 
  ftp servers).
  Try 'zzzzzz -DepthMax 4 solve win.txt' for an example.
  
batch gamefile
  reads the moves played sofar from the file gamefile, and appends a move
  to the gamefile. This can be used for automatic play. See the file
  job1 for an example.

white gamefile
  Play a game against ZZZZZZ. ZZZZZZ plays white. The moves played sofar will
  be read from the file gamefile. New moves will be appended to the 
  gamefile. To undo a move: quit the program; edit the gamefile and 
  restart the program with 'zzzzzz -GameTimeUsed xx white gamefile', where
  xx stands for the time used sofar.
black gamefile
  Same for black.

what gamefile dbasefile
  ZZZZZZ has an option to play parallel on a number of UNIX machines.
  It is very primitively implemented: the driver program (par.c)
  asks ZZZZZZ (which has to reside in the same directory as the program
  par is in) what to do. ZZZZZZ replies by writing on the dbasefile
  who is to move, the number of legal moves and the moves themselves.
  The driver program then distributes the legal moves over a number of
  workstations specified in the file hosts.cfg (see the file par.c) using
  fork, remote copy and remote shell. This setup works well and the program
  par.c is fairly portable (I wrote it on an RS6000, and it compiled without 
  problems on an SGI-IRIX). If you parallelize chess in this way, the time
  gained is strongly dependent on the position: in positions where there
  is clearly a best move (e.g. recaptures), you gain nothing because only
  one workstation is thinking about the right move, wherease the other 
  workstations are only thinking about nonsense. In other positions
  the gain is higher.
par gamefile dbasefile
  Used when playing parallel. The moves played sofar are read from the 
  file gamefile. The legal moves to considered are in the file dbasefile.
  The best move from those moves is written back to the dbasefile,
  together with the score.

book bookfile
  Generates an opening book from the variations in the file bookfile.
  The bookfile should be in GNUCHESS format: variations are seperated by
  exclamation marks. A good opening book (that is, leading to positions
  your chess program plays well) is very important. However, it takes 
  a long time to create such a book! I took the easy (but wrong) way:
  I just used the book created by John Nunn for GNUCHESS, and the program 
  removes all gambits when it generates the opening book.
  (My program does not know how to compensate positionally for the 
  sacrificed pawn, as I found out during the 1992 Dutch Computer Chess
  Championships). Even then you run into problems: see for example 
  the game against doerak: ZZZZZZ is out of the opening book and 
  plays the positionally very bad move e7e5?? (within the horizon, there
  is nothing wrong with the move, but on the long term, there is..).
	A file 'all.txt' is generated which contains all the final positions
	of the variations in 'solve' format, which makes it easy to check
	those positions with 'zzzzzz solve all.txt'.

try
  ZZZZZZ has a neural network based parameter optimizer. 
  It works like this (see also Van Tiggelen, ICCA journal Volume 14,
  no. 3 (1991) pp. 115-118).
  You choose a number of parameters sets for your evaluation function,
  and solve a number of problems with these parameter sets, e.g.
  1 2 3 4 20%
  2 1 3 4 10%
  1 2 4 3 15%.
  You train a neural network which has as input neurons the number of
  parameters of your evaluation function, and as output the 
  percentage of problems solved. Then you ask the neural network:
  'How can I get 90%'. The neural network tells you: try 4 3 2 1.
  With these parameters, you solve the problems again. Alas, you find 
  that 4 3 2 1 gives not 90%, but 5%! This is because the neural network
  is not yet a good model for your evaluation function parameter 
  dependence. But you can still add this result to the training set and
  train the neural network again and ask it how to get 90% etc. etc.
  Now this part of the code depends heavily on routines from Numerical
  Recipes in C, which are !@#$%^ copyrighted (This really puts a blame 
  on this outstanding book), so I have to write these routines myself.
  (that is read the references, study the algorithms, check if PD anything
  is available (fortunately, there is), if not implement it in C,
  debug it etc. etc). This rewrite will take some time, so I have disabled
  this feature in the current version (it will be included in the 
  next version) and replaced it by the option 'try'. This option
  will read from the file "init.txt" a number of parameter sets
  solve a number of problems on the file "opt.txt" with these sets and
  output the results to the file "results.txt".
  E.g. the file "init.txt" could contain (only parameter sets with
  negative percentages solved are read. Parameter sets with positive
  percentages are skipped)
  -1.0 1 2 3 4
  -1.0 2 1 3 4
  -1.0 1 2 4 3
  And after the run the file "results.txt" contains
  0.20 1 2 3 4 (i.e. 20%)
  0.10 2 1 3 4
  0.15 1 2 4 3

BUGS
  Please report any bugs and questions to wiesenecker@sara.nl.
  Remember: this distribution is primarily meant to provide you 
  with the source code for a chess program, not with user-friendly,
  strong chess playing program.
