G. Wiesenekker. ZZZZZZ a chess program.
Copyright (C) 1993-1994 G. Wiesenekker
E-mail: wiesenekker@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 and choose your favourite C-compiler and CFLAGS.
Change PVM_INCLUDE and PVM_LIB to the path's at your site.

Type 'make progs'.
  This compiles zzzzzz, fin2zzz and fin2tex.
Type 'make book'.
  This compiles an opening book and checks the output against an
  output generated at my site.
Type 'make pgn'.
  This compiles a pgn database and checks the output against an output
  generated at my site.
	Only the compilation time stamps and the 'games per sec' things 
  should be different.
Type 'make check'.
  This solves the first 10 'Win At Chess' positions and checks the output
  against an output generated at my site.
  Only the compilation time stamps and the 'time=' things should be 
  different, not the 'stats='.

If you also like draughts (the 10x10 version): go to the draughts directory
and follow the instructions in the README file.

You are now ready to use the program. To play against it, type
'touch game.txt' followed by 'zzzzzz black game.txt' and play some moves
(or zzzzzz -PvmProcs 2 black game.txt if you are using PVM).
If you type '?' you get the list of legal moves. When you enter a move, only
the first few characters that make the move unique have to be entered.
'quit' exits the program.
ZZZZZZ recognizes Standard Algebraic Notation.

If this worked, try to choose CACHE_BITS (defines the size of the hash table
for the alpha beta), and SCORE_CACHE_BITS 
(defines the size of the hash table used for the static evaluation) 
in zzzzzz.c as large as possible (say such that the total sizes of the 
hash tables equals half of the physical memory in your machine).

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: How can I change the starting position?
A: ZZZZZZ reads the starting position from the file 'brd.txt'. You can change
   the starting position by editing this file.

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 have been played.
A: Correct. ZZZZZZ was designed to play in computer chess tournaments,
   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)'.

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:
Fields of a struct are usually prefixed with the name of the struct.
Braces are placed like
{
}
If if-then-else is used inside a loop, I use continue, rather than
else to avoid excessive indentation.
Same for goto's.

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 are read from $HOME/.zzzzzzrc (if it exists), then from
./.zzzzzrc, then from environment variables and finally from the commandline.
In .zzzzzzrc are recognized Depthmax=value and TimeLimit=value and 
the options random_opening (whether to chose a random opening), 
print_dbase (enables printing of the database) and print_distrib
(for debugging the PVM code).
In the environment are recognized ZZZZZZ_DEPTHMAX and ZZZZZZ_TIMELIMIT.

-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 minutes (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).
-MateDepth n
   Sets the maximum mate depth to n plies.
-NoAppend
   Do not append the move played to the file with moves (useful when debugging).
-NoBook
   Disables the opening book.
-NoPos
   Disables the positional evaluation.
-PvmProcs n
   ZZZZZZ has an option to play parallel. This parallelism is built on PVM
   (Parallel Virtual Machine), available by anonymous ftp to 
   netlib2.cs.utk.edu in the directory pvm3. If you do not have it, 
   get it now and install it. It is great!
   PvmProcs specifies the number of virtual processors on which ZZZZZZ will
   run.
-PvmDepth n
   The minimum depth at which to to split a node.
-PvmLegal n
   The number of moves that should be searched by a slave.

The possible commands are:

pos posfile
  Reads in the positions on the file posfile and prints the pseudo 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.

verif gamefile
  Reads in the moves in the file gamefile and checks the moves for legality.

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 the problems (the position and the best move) from
  the file problemfile, and compares it to the move ZZZZZZ would
  have played in that position. After processing all problems 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) that contains 
  files with all kinds of problems.
  The program fin2zzz reads from standard input a Lang&Smith file
  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 solve win.txt' for an example.
  
mate matefile
  ZZZZZ has a primitev mate finder.
  Reads the mate problems (the position and the colour to move) from
  the file problem file and tries to find a mate within MateDepth (see
  above) plies.
  Try 'zzzzzz mate mate.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 (in minutes) used sofar.
black gamefile
  Same for black.
  
book bookfile.
  Reads in the opening variations from the file 'bookfile' and writes the
  positions together with the move to play to the file 'dbase.txt'. 
  The positions can be added to the database with 'dbase dbase.txt'.

pgn
  This drops you into a pgn reader. Portable Game Format is a game standard
  proposed by Stephen J. Edwards, and he has made many games available in
  this format at chess.uoknor.edu. Currently, there are two commands:
  comp filename.
    Reads a pgn file and stores it in a digested form for rapid
    access in the file 'pgn.bin'. Although Stephen J. Edwards has proposed
    a standard for storing a digested pgn file, ZZZZZZ does not adhere
    to this because it would make the search for transpositions very slow.
  anal gamefile
    Reads a game in pgn format and checks whether the position has occurred
    before in a game stored in the 'pgn.bin' file. If so, it prints the
    result and the move played in that game.
  keys keyfile
    Reads in openings (moves and tags) from the file keyfile and stores them in
    a digested form in the file 'keys.bin'. This file is used to tag games.
  
dbase dbasefile
  This will digest the text file dbasefile consisting of positions in FEN
  notation and the move to play in that position and stores them in a btree
  indexed database.
  The dbasefile should consist of opening positions and for example
  endgame positions. Do you run into a position in which ZZZZZZ plays a bad move?
  Just add the position and the move it should have played to dbasefile, update the 
  dbatabase with 'dbase dbasefile' and ZZZZZZ will not make the same mistake again.
    
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 then 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 5%, not 90%! 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 wiesenekker@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 program.
