CSE 4308/5360 - Assignments
Assignment 4 (Programming 2)

Due date: Thursday, October 11, 2007, 11:59pm.

Summary

The task in this programming assignment is to implement an agent that plays the SOS game using variants of minimax search. Figure 1 shows step by step a complete game. The game is played on a NxN grid (in the example of Figure 1, N=4). There are two players, player A and player B. Each move consists of writing either "S" or "O" on a blank square. If this move (together with letters already existing on the board) creates an "SOS" word on the board, either horizontally, vertically, or diagonally, then the player making that move gets one point and gets to play again (for example, player A plays five times in a row, in moves 6-10). If the move creates multiple "SOS" words, then the player receives as many points as the number of "SOS" words that are created by that move (for example, on move 13, player B receives two points). The game is over when all squares on the board are filled.

On Figure 1, each move by player A is shown in blue color, and each move by player B is shown in green color. When an "SOS" word is formed, the remainder of that word is shown in red color.


Figure 1. A step-by-step game of SOS.

Text File Format

One input to the program is always the name of a text file, that specifies the current board state (including the dimensions of the board, and any letters already placed on the board) and the current score. Assuming that the board is of size M rows by N columns, the format of the file is the following (expressions in brackets should be substituted by specific values in an actual file): 
SIZE: [M] ROWS, [N] COLUMNS
SCORE: [SCORE OF PLAYER MAKING NEXT MOVE] [SCORE OF OTHER PLAYER]
[L_11][L_12]...[L_1N]
[L_21][L_22]...[L_2N]
...
[L_M1][L_M2]...[L_MN]
In the above, L_IJ indicates the letter corresponding to position (I,J) on the board, and there are only three possible values for L_IJ: the letter "S", the letter "O", and the character "-" (which indicates a blank position). Some examples of input files are input1.txt and input2.txt.

Interactive Mode

The program should run in two modes: interactive mode and one-move node. In interactive mode, the program is invoked from the command line as follows (the following line assumes a Java implementation): 
java sos [input_file] [number_of_nodes]
For example: 
java sos input1.txt 1000
In this case, the program reads the input file, which specifies an initial board state (dimensions, plus some squares with values already filled in).

After reading the input file, the program gets into the following loop:

  1. Print the current board state and score. If the board is full, exit.
  2. Choose and make the next move. If using depth-limited search, do not explore more than the specified number of nodes. For other strategies (random move, minimax, alpha-beta) the number_of_nodes argument is ignored.
  3. If the computer just made an SOS, goto 1.
  4. Print the current board state and score. If the board is full, exit.
  5. Ask the human user to make a move (make sure that the move is valid, otherwise repeat request to the user).
  6. If the human just made an SOS, goto 4.
  7. Goto 1.

One-Move Mode

The purpose of the one-move mode is to make it easy for programs to compete against each other, and communicate their moves to each other using text files. The one-move mode is invoked as follows: 
java sos [input_file] [number_of_nodes] [output_file]
For example: 
java sos input1.txt 1000 output2.txt
In this case, the program simply makes a single move and terminates. In particular, the program should:
  1. Read the input file and initialize the board state and current score, as in interactive mode.
  2. Print the current board state and score. If the board is full, exit.
  3. Choose and make the next move. If using depth-limited search, it should not explore more than the specified number of nodes. For other strategies (random move, minimax, alpha-beta) the number_of_nodes argument is ignored.
  4. If the computer just made an SOS, goto 2.
  5. Print the current board state and score.
  6. Save the current board state to the output file IN EXACTLY THE SAME FORMAT THAT IS USED FOR INPUT FILES. Make sure that only capital letters are used.
  7. Exit
Important: the format of input and output files specifies that, on the second line of the file, where the score is given, the first score is that of the player making the next move. For example, suppose that the program reads an input file where the score is stated as: 
SCORE: 12 5
Further suppose that the program makes a move that gains no points. When the program saves the output file, the order of points in the output file IS REVERSED, so the score line should read as: 
SCORE: 5 12

Submissions

All submissions are via e-mail. E-mail your submission to BOTH the instructor and the TA.

Implementations in LISP, C, C++, and Java will be accepted. If you would like to use another language, please first check with the instructor via e-mail.

Submit a zipped directory (no other forms of compression accepted) via e-mail, with subject "CSE 4308/5360, assignment 4". THE ATTACHMENT SHOULD NOT EXCEED 800KB in size (e-mail the instructor if the 800KB limit is a concern). The directory should contain source code, and optionally, binaries that are appropriate for gamma or omega. The directory should also contain a file called readme.txt, which should specify precisely:

Insufficient or unclear instructions will be penalized by up to 20 points. Code that does not run on at least one of the gamma and omega machines gets zero points.

Grading

The perfect score is 50 for CSE 4308, and 60 for CSE 5360. There are also 21 extra credit points available. To encourage students to start early, 6 extra credit points will be awarded for preliminary submissions, e-mailed to the instructor and TA by specified times before the deadline, that implement specific parts of the assignment (see items 11-14 below).

All code has to run on omega. All submissions must include very clear instructions for how to run the code on omega. Code that we cannot run will only receive partial credit and a 10 point penalty, and no consideration for extra credit, even if it runs perfectly on some other platform. Submissions that do not include sufficient instructions for how to run the code will similarly receive only partial credit, a 10 point penalty, and no consideration for extra credit.

Please have in mind the following policy about comments in the code: partial credit will only be given for code that is very very well documented, so that it is easy for us to understand what each function is doing, line by line. At the same time, if the code behaves correctly, and the instructions for how to run the code are clear, then no comments are necessary. Therefore, feel free not to comment (or to comment poorly) the code, but in that case you should not expect partial credit for any part of the code that does not work.

Pointwise, the assignment is broken down into the following parts.

  1. (5 points). Ability to read input file and print initial board state and score.
  2. (5 points). Ability to make a valid move and print the updated board state and score.
  3. (5 points). Ability to successfully complete the one-move mode (make a move, even a random/dumb move, that is valid given the initial board state, print the updated board state and score, and save the output file IN THE CORRECT FORMAT).
  4. (5 points). Ability to successfully complete the interactive mode (i.e., play a complete game with valid, even if random/dumb, moves from computer, reject any invalid inputs by the human user, print the correct score after every move, and terminate at the end).
  5. (10 points). Implementing plain minimax.
  6. (10 points). Implementing alpha-beta search (if correct, you also get the 10 points for plain minimax, you don't need to have a separate implementation).
  7. (10 points). Implementing depth-limited alpha-beta (if correct, you also get the 20 points for plain minimax and alpha-beta search, you don't need to have separate implementations for those).
  8. (10 points, CSE 5360). Create a table of runtime (for making a single move) vs number of empty squares. Document the number of measurements for each entry on the table.
  9. (5 points, extra credit). Define (and document well) a really cool heuristic for evaluating non-terminal nodes in depth-limited search. WARNING: determining coolness is subjective, somewhat arbitrary, and the sole prerogative of the instructor and TA.
  10. (10 points, extra credit). In a separate implementation, implement depth-limited alpha-beta search for a non-deterministic version of the game: when a player makes a move (excluding moves after just making an SOS word, i.e., excluding moves in which the same player also made the last move), the player rolls a dice. If the roll is a six, then that player will play the minimum of twice in a row, or as long as the player keeps making SOS words with each move. In other words, even if the player does not make an SOS word with the next move, the player will play at least twice in a row.
  11. (extra credit, 2 points) Submit by Thursday, 09/27/2007, 11:59pm, code that implements items 1, 2, and 3.
  12. (extra credit, 1 points) Submit by Thursday, 09/27/2007, 11:59pm, code that implements items 1, 2, 3 and 4.
  13. (extra credit, 2 points) Submit by Tuesday, 10/02/2007, 11:59pm, code that implements items 1, 2, 3, 4, and 5.
  14. (extra credit, 1 point) Submit by Tuesday, 10/02/2007, 11:59pm, code that implements items 1, 2, 3, 4, 5, and 6.

Some hints