OVERVIEW
---------------------------------------------------------------------------------
Leiserchess contains the following sub directories:

BayesElo:
* This is a software developed by Rémi Coulom to estimate Elo ratings.  
  (http://remi.coulom.free.fr/Bayesian-Elo/)
  (The Elo rating system is a method for calculating the relative skill levels 
   of players in two-player games.)  
* For the purpose of this project, you only need to familiarize yourself with 
  the use of this tool, but not actually understand any of the code base.  
* BayesElo takes a PGN file (*.pgn extension), which is essentially a 
  recording of game plays, and produces a rating for the players based on 
  the PGN file.  The PGN file will be generated by our autotester.  You will 
  find detailed instructions on how to use BayesElo and autotester later in
  this README, under EVALUATE PLAYERS.

autotester:
* An autotesting framework for Leiserchess developed by Don Dailey, although 
  the framework supports any two-player game engine that support UCI protocol.
* Again, you don't need to understand any of the codebase.  You just need to 
  use it.
* The autotester plays two player engines against each other according to 
  the input configuration file given, and produces a PGN file (*.pgn) that 
  is a recording of the game plays.
* You will find detailed instructions later under EVALUATE PLAYERS.

doc:
* This directory contains the relevant documentation for Leiserchess:
  - Leiserchess.pdf: the game rules for Leiserchess
  - engine-interface.txt: detailed document of the player engine interface
  It's a good idea to read through these documents before you begin playing 
  with the code.
   
player:
* The code for the game engine that you will be improving.
* There is a README in the directory that orients you to the codebase and 
  gives a high-level overview of what each of the component does.
* We have provided a basic Makefile.  You can type 'make' to compile the 
  program.  Upon compilation, a binary 'leiserchess' will be produced.
 
tests:
* We thought we would create a directory for you to store your configuration 
  files for the autotester, so you can be organized. :-)
  Right now, there is only one configuration file in the directory, namely 
  basic.txt.  You can model after that and build your own configuration file.  
  Note that when you run the autotester, the PGN file produced will go into 
  this directory as well. 

webgui:
* The codebase of web GUI for playing Leiserchess, so you can play with 
  your classmate or against the player bot you build.  Or even better, have 
  you parent play with the bot you built. :-)
* Again, this is a tool for you to use, and you don't need to understand the 
  codebase to do well in this project.  Of course, if you are so inclined, 
  we welcome you to hack the web interface as well and contribute to the 
  codebase. 


HOW TO PLAY
---------------------------------------------------------------------------------
* Locally: 
- Compile leiserchess in player/.
- cd into webgui.
- Start the webserver via 'python ./webserver.py' and leave it running.
  It should print out "start Leiserchess at port 55555."
- Open a browser and type 'localhost:55555'
- Click 'Start' and enjoy the game!
  By default, this configuration is human versus bot (specially, the 
  "leiserchess" in player/)
  (Note: We will later support human-to-human and bot-to-bot interface.)
- Once you are done, remember to shut down your webserver (Ctrl-C on the 
  terminal that you ran python webserver.py).

* On cloud machines:
- Download the software onto a cloud machine.
- Repeat the same process as playing locally.
- Open a browser and type 'cloud<N>.csail.mit.edu:55555' where <N> is
  the number for the cloud machine where you started the webserver.
- Now your parent can enjoy the game as well. :-)
- IMPORTANT: Remember to shutdown the webserver when you are done, or
  the leiserchess process will stay alive and consume resources.
  Occationally, if things are not shut down properly, there may be
  orphand player processes running, so it's also a good idea to do a
      $ ps aux | grep 'leiserchess'
  and kill orphand process if there is any.
- If you start a webserver on your cloud machine remotely, the
  webserver process will be terminated once you log out of your ssh
  session.  One way to keep it alive is to start the webserver in tmux
  or screen.  Then you can detach from tmux / screen before you log
  out and keep the webserver alive even after you close the ssh
  session.

Sometimes the webserver doesn't die properly, hanging up the port and
preventing a new webserver from starting.  In this case, type

    $ lsof -i :55555

Note the PID of the python job, and type

    $ kill <PID>


EVALUTE PLAYERS
--------------------------------------------------------------------------------
Once you start modifying the player code, you will want to check and
make sure that your modification is indeed an improvement, and this is
where the autotester comes into play.  We recommend that you set up
your Makefile so that you can easily compile different versions of the
players easily (with different binary names).  Once you have your
player binaries, you can evaluate your changes by playing the newer
player binary against the older one using the autotester framework.
Be sure that you are not running anything else computationally
intensive when running the autotester for accurate results.  The
autotester also acts as a referee, ensuring that both engines are
making valid moves.

The autotester takes in a configuration file, specifying the parameter
for running the autotester.  The detailed instructions for writing a
configuration file are in autotester/README.  We have provided a basic
configuration file for you, in tests/basic.txt.

To run the autotester:
* Make a configuration file based on the README in autotester, or use 
  tests/basic.txt.
  (NOTE: A configuration file must alawys have *.txt extension.)  
* Compile the autotester ('make' in autotester directory).
* cd back into the tests/ directory.
* Run 'java -jar lauto.jar basic.txt (or your own configuration file).
* A basic.pgn will be created in the same directory as the
  configuration file .  (The PGN file is a recording of the game plays
  run by the autotester based on the given configuration file.)

To run the BayesElo software to get a rating of your players:
* Make sure that the BayesElo software is compiled (cd into BayesElo
  directory and type 'make').
* cd into the tests/ directory.
* Run './pgnstats.tcl basic.pgn' which reads in a PGN file and outputs
  rating.
* The README in tests/ describes how you interpret the rating.

Note 1: The autotester will report illegal moves made by a player (and
in which case, the autotester declares that the player who made the
invalid move loses and terminates the game), so grep for "Illegal move
|<move>| attempted" in your PGN file to be sure that your player is
making valid moves.

Note 2: The autotester does not actually play the games if a given
configuration file already has a corresponding PGN file in the
directory, and that the configuration of the players have not changed
since the last run.  On the other hand, if the configuration file has
the same name but the player configuration has changed, the autotester
will play new games according to the new configuration and appends the
records in the corresponding PGN file.


DEBUGGING
---------------------------------------------------------------------------------
When you run the leiserchess binary directly without the web GUI,
leiserchess launches into an "infinite" loop, accepting command based
on the UCI specification.  Check the document doc/engine-interface.txt
for detailed descriptions of what's accepted.  You can also type
'help' to see possible commands supported by leiserches UCI.  The UCI
interface is purely text based, so you can debug your player program
easily using a terminal.  Anything you print in the player code base
gets printed out to the terminal window in which you run leiserchess.

Note: You should rename the player from 'Leiserchess' to something
else (both the binary and what's printed by the 'uci' command) once
you start modifying the player.