-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
179 lines (146 loc) · 8.1 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
OVERVIEW
--------------------------------------------------------------------------------
Leiserchess contains the following sub directories:
autotester:
* An autotesting framework for Leiserchess developed by Don Dailey, although the
framework supports any two-player game engine that support the UCI (universal chess interface) 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.
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.
doc:
* This directory contains the relevant documentation for Leiserchess:
- Leiserchess_2018.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:
* A directory for you to store your configuration files for the autotester, so
you can be organized.
* Right now, there are only two configuration files in the directory, namely
basic.txt and basic2.txt. You can model after those and build your own
configuration files.
* 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 your
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.
pgnstats:
* You can use the pgnstats binary to print out the statistics of the PGN files
generated by the autotester.
* Build the pgnstats binary by typing make in the pgnstats folder.
* It would be useful for you to note the following statistics generated by
pgnstats:
- the average depth searched by each bot.
- the average time spent by each bot, which can help you with figuring out
whether parallel code is not aborting properly and continues to run well
after the desired time computed by the program is complete.
HOW TO PLAY
--------------------------------------------------------------------------------
Locally or on your AWS VM:
* Compile leiserchess in player/. (Note that you will need to have a local
installation of cilk to compile leiserchess locally on your own machine.)
* cd into webgui/.
* Start the webserver via:
$ python ./webserver.py
and leave it running. It should print out "start Leiserchess at port 5555."
* If you ran the webserver on your local machine:
- Open a browser and type 'localhost:5555'
If you ran the webserver on your AWS VM:
- Login to your Athena account and run:
$ cat ~/.aws/.6172_current_instance
and note the URL that appears. This the public URL for your instance.
- Alternatively, you can login to your AWS console and note the public IP
address of your running instance.
- Open a browser and type '<public_url>:5555' (or '<public_ip>:5555').
* Click 'Start' and enjoy the game! (Refer to the README file in the webgui/
folder for controls.) By default, this configuration is human versus bot
(specifically, the "leiserchess" binary in player/).
* Once you are done, remember to shut down your webserver (Ctrl-C on the
terminal that you ran python webserver.py).
Sometimes the webserver doesn't die properly, hanging up the port and preventing
a new webserver from starting. In this case, type
$ lsof -i :5555
Note the PID of the python job, and type
$ kill <PID>
EVALUATE 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 following commands you may need to install Java and Tcl on your AWS
VM using:
$ sudo apt-get install openjdk-8-jdk tcl
Don't forgot to log out and log back into your AWS VM after running sudo since sudo
messes with your permissions.
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 replace basic.txt with your own configuration file's path.)
* 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
$ ./pgnrate.tcl basic.pgn
which reads in a PGN file and outputs ratings.
* The README in tests/ describes how you interpret the rating.
NOTE: 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.
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 the leiserchess 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 to help you keep track of different versions of your bot.