Introduction to Artificial Intelligence

Introduction to Artificial Intelligence Prof. Richard Lathrop Project: Sudoku Solver Last Updated Jan-28-2016.

Sudoku Puzzle Assignments

1. Introduction All coding assignments require that you produce and turn in each time: 1. An executable file that can be run from the command line prompt by a Unix/Linux script on openlab.ics.uci.edu. You can use ‘ssh’ or ‘putty’ to connect to openlab. We will provide a test script that you can use to verify that your executable runs successfully under these conditions. 2. A source file or set of source files that can be compiled on openlab to produce your executable file. We will provide the command line string that will be used to compile your source code, one each for Java, Python, and C++. Your source code must compile properly on openlab using the command line string that we provide. 3. Documentation that describes the changes to your code since the last project assignment was submitted. Do not document your entire program; only document the changes you made for the current assignment. Do not use more than one page for this documentation. Then, provide an Appendix that shows the changes that you made to your source code for the current assignment. Do not list your entire source code in the Appendix; only list the changes you made for the current assignment.

You must turn in to EEE Dropbox a single zipped file named “yourLastName_yourUCINumericID_yourTeamName.” ( NO spaces or Unix/Linux special characters in yourTeamName . Alphanumerics , hyp hens, and underscores are safe .)  It should have three subdirectories: src, bin, & doc. ‘src’ must contain your source code, ‘bin’ must contain your executable, and ‘doc’ must contain your documentation.  Please deposit only one submission per team.  If your partner has deposited your submission, please deposit a text file stating your name/NumericID, your partner’s name/NumericID, and your team name, all delimited by newlines. Please use the same filename format given above.

Your executable must accept a first command line argument that is the filename of the Sudoku puzzle that your AI is to solve. The filename is followed by zero or more of the tokens MRV, DH, LCV, FC, ACP, MAC, in any order, separated by spaces. These tokens govern which heuristics and consistency checks you are to do.  MRV (Minimum Remaining Value): Use the MRV heuristic to select the next variable to explore next.  DH (Degree Heuristic): Use the DH heuristic to select the next variable to explore next. If both MRV and DH are present, then use MRV first to select candidate variables and next use DH to break ties if MRV returneds more than one candidate variable. If neither MRV nor DH is present, then order the variables left-to-right, then top-to-bottom.  LCV (Least Constraining Value): Use the LCV heuristic to order the values. If LCV is not present then order the values in increasing order from 1 to N.  FC (Forward Checking): Run Forward Checking after each assignment.  ACP (Arc Consistency Preprocessor): Run AC-3 as a preprocessing step before starting to solve the given problem.  MAC (Maintaining Arc Consistency): Run AC-3 after each assignment. If both FH and MAC are present, run FC first and then AC-3 second.

2. Grading (Percentages below are of Project grade. Project grade is 20% of Final grade, so divide by 5 to get Final grade percentages)  Final report 25 %  Progress report 10 % (2 % per each assignment submission)  5 Five Assignment Submissions 65 % o Problem Generator, Backtracking Search 10 % o Forward Checking 15 % o Arc Consistency Preprocessor, Maintaining Arc Consistency 15 % o Minimum Remaining Value, Degree Heuristic 15 % o Least Constraining Value Heuristic 10 %  Extra Credit: Speed Bonus Point (only on your Final Submission; should be your very fastest solver). o The fastest 10 % get 10 bonus points, the second fastest 10 % get 9 bonus point, …, and the lowest 10 % get 1 bonus point. We will decide N, P, and Q; but not tell you. o Each language class will be run separately, i.e., Java will compete only against Java, Python only against Python, and C++ only against C++. If there are fewer than 10 entries for a language class, then those percentages will be pro-rated.  Extra Credit: Create Own Design for Shell Extra 10 % o If you don’t use provided JAVA shell, you will get extra credit from your own work! o If you want to claim extra credit from your work, you should must clearly state that in your progress report  Team Formation Extra 1 %

3. General Submission Guideline  Submit ZIPPED archive file to dropbox  Put your source code under “src”, a single executable file in “bin”, and all documents under “doc”. Your executable MUST be named as shown below. o In Java, your single JAR file should MUST be named “main.jar” and you should compile your code using JAVA 1.7  How to make a jar file in JAVA? (Go to the end)  Please provide only one JAR file under bin  The name should be main.jar o In Python, your main script file MUST be named “main.py” and you may put rest of the files as you wish  If you use another name, we cannot pick up the main script automatically!  How to configure python interpreter in openlab? (Go to the end) o In C++, your single executable file should MUST be named “main”  How to configure g++ in openlab? (Go to the end)  Please provide only one executable file with name main  Your executable will be tested in openlab.ics.uci.edu  Your program will o Read input file (name will be provided by command line argument) o Write output file (name will be provided by command line argument) o Read Timelimit in Seconds and terminate it if it reaches time limit o Turn on desired components from option tokens [GEN | [BT | FC | ACP | MAC | MRV | DH | LCV ] . If no option tokens are provided then do simple backtracking search: order the variables left-to-right then top-to-bottom, and order the values 1, 2. ..., N.  Examples of command line arguments o $ java –jar main.jar M-N-P-Q.txt problem_M-N-P-Q.txt 600 GEN o $ python main.py M-N-P-Q.txt problem_M-N-P-Q.txt 600 GEN o $./main M-N-P-Q.txt problem-M-N-P-Q.txt 600 GEN o $ java –jar main.jar problem-M-N-P-Q.txt BT_problem-M-N-P-Q.txt 600 BTMRV o $./main problem-M-N-P-Q.txt BT_problem-M-N-P-Q.txt 600 BT MRV DH FC LCV o Etc.  We will provide test program before submission deadline o Please use it and check how your program works in openlab.ics.uci.edu  You also submit a short progress report for each assignment. It should state the followings in one1 page of text with an appendix. Do not use more than one page of text for the body of your progress report. o Scope of your work o Progress you made: list of coding changes since last submission, main activities have done, etc o Problems & Questions: that have arisen o Results: It is optional. You could have your own initial assessment from provided test program. o If you want to claim extra credit, then you should clearly state what you did and why it is worth awarding extra credit  For example, if you modified the constraint checking method in the provided JAVA shell  If you ported the provided JAVA shell to another language  If you designed and wrote your own coding shell program  If you implemented a Local Search solver  If you tried advanced techniques…  Etc.  The Teaching Staff will evaluate what you did and assign any extra credit at their sole discretion

4. Program Input/ Output Specification

Your program should have two modes Problem generation mode: this mode will be activated by accepting GEN token in command line. Under problem generation mode, Your program should read input text file, which gives input parameters M, N, P, Q to the problem generator and write a problem file. Problem file format is described in http://www.ics.uci.edu/~rickl/courses/AI- projects/sudoku-solver/monster-sudoku/aiproject-monster-sudoku-generator- reader-specs.pdf If your program couldn’t generate a problem within time limit, a problem file will contain a single line text “timeout” If input parameters M, N, P, Q were invalid, your program should write a single line text “error: invalid input parameters” to the problem file Problem solving mode: this mode will be activated by accepting BT token in command line. Other algorithmic components such as Forward Checking, Arc Consistency Preprocessor, etc could be turned on by accepting corresponding tokens. Under problem solving mode, Your program should read accept as command line arguments (1) an input problem filename, (2) which name will be given as a command line argument, writean output log filename, (3) which name will be given as a command line argument,a time out parameter in seconds, (4) and zero or more option tokens supplied in any order.

 Input File Specification o In problem generation mode, input file will contain a single line text with 4 numbers M, N, P, Q.  For example, “25, 9, 3, 3”, “100, 20, 4, 5” o In problem solving mode,The input file will be given as a problem file as described in http://www.ics.uci.edu/~rickl/courses/AI-projects/sudoku-solver/monster- sudoku/aiproject-monster-sudoku-generator-reader-specs.pdf

 Output File Specification o In problem generation mode, output file will be a problem file as described in http://www.ics.uci.edu/~rickl/courses/AI-projects/sudoku-solver/monster- sudoku/aiproject-monster-sudoku-generator-reader-specs.pdf  If your generator couldn’t produce a problem within time limit, your problem file should include a single text line “timeout”  If input parameters (M, N, P, Q) were invalid, then your problem file should include a single text line “error: invalid input parameters” o In problem solving mode,The output file will be a log file that collects statistics from your solver. Your program should print each line:  TOTAL_START=  Record the time when your program starts!  Relative time/ system time both OK if it is coherently used  Make sure you convert it in second (if it becomes 0 second it is okay)  PREPROCESSING_START=  Record the time when AC Preprocessor starts!  If you are not doing AC Preprocessing then simply record the current time.  PREPROCESSING_DONE=  Record the time when AC Preprocessor finished!  If you are not doing AC Preprocessing then PREPROCESSING_DONE = PREPROCESSING_START  SEARCH_START=  Record the time when Backtracking search starts!  SEARCH_DONE=  Record the time when Backtracking search finished!  If you meet timeout then write the time you encountered time limit  SOLUTION_TIME=  Compute time for finding a solution  (PREPROCESSING_DONE-PREPROCESSING_START) + (SEARCH_DONE-SEARCH_START)  If you encountered time limit, you can compute it or you can skip computing it because STATUS will show you encountered timeout  STATUS=success | timeout | error  “success”: when you find a solution or prove that a problem doesn’t have any solution  “timeout”: when your program couldn’t solve the input problem or prove that no solution exists within the time limit.  “error” : other than above cases  SOLUTION=(value assignment to variables)  If you find a solution, print out a tuple of values in single line.  If you prove that there is no solution, print out all zero tuple. (keep the length of the tuple as N*N)  For example, if N = 2, and you had final board configuration  (1,2,3,4)  (3,4,1,2)  (2,1,4,3)  (4,3,2,1)  Then the solution will be (1,2,3,4,3,4,1,2,2,1,4,3,4,3,2,1)  [Note: for your own use and interest, you probably will want to write a small utility that can read your log file and display your solution as an NxN grid in traditional Sudoku format.]  COUNT_NODES=  You should be able to print out COUNT_NODES when you encounter time limit  COUNT_DEADENDS  You should be able to print out COUNT_DEADENDS when you encounter time limit  More Statistics will be added as you implement more algorithms o What happens if youI generate thed output file in a different way?  Your program cannot be tested automatically and you will lose points. o What happens if youI put the wrong numbers to in the output file?  We will check automatically if your program only generates a log file or actually producing produces the right numbera correct solution to the test problems we give it.  If your program produces a solution that is illegal (i.e., that violates any of the constraints), you will lose points.  If you made mistake and produced wrongly formatted output file, we cannot test your program automatically, and you will lose points.  If you submit a source code and program that does nothing but generates fake output files, it will be regarded as an act of academic dishonesty.

 Timeout parameter o The third input parameter to your program sets time out limit in seconds. o Internally, you can use any time unit. But when you printing it you should convert it in to seconds. It is okay to print out all zero time, which > It willmay happen if a problem is small. o While running ACP or BT, you should  Check if (current time - TOTAL_START) > timeout  If you encounter timeout then you terminate current loop and print out log output file as specified  When you encounter time out before starting preprocessing,  Make sure you wrote STATUS=timeout  You can put arbitrary number to other fields  When you encounter time out while preprocessing (ACP)  Make sure you wrote STATUS=timeout  You can put arbitrary number to other fields  When you encounter time out while search  You should print out desired output files as specified o It is okay to check time elapsed at the end of each loop (for BT/ ACP).

 Tokens o Your program will read a sequence of tokens and your program should properly activate corresponding components in your program o We will not provide invalid combination, such as GEN BTNote that any combination of tokens is legal. Some combinations have special meanings:  If both MRV and DH are present, run MRV first and use DH to break ties among the best candidates from MRV.  If ties remain after running MRV and/or DH, or if neither MRV nor DH are present, choose the first unassigned variable (from among the candidates) encountered in a scan left-to-right then top-to-bottom.  If both FC and MAC are present, then run FC first followed by AC-3 after each assignment.   If ties remain after running LCV, or if LCV is not present, then choose the lowest remaining domain value (from among the candidates).GEN: problem generator  BT: backtracking search o FC: run Fforward Cchecking before starting search and after each assignment o ACP: Aarc Cconsistency Ppreprocessor, run AC-3 before starting backtracking search o MAC: Mmaintaining Aarch Cconsistency, run AC-3 after each assignment o MRV: order variables by the Mminimum Rremaining Vvalues heuristic o DH: order variables by the Ddegree Hheuristic o LCV: order values by the Lleast Cconstraininged Vvalue heuristic o For example, your program may see combinations of tokens such as: o GEN o BT  BT FC  BT ACP  BT FC MRV  BT FC MRV DH LCV  FC ACP BT MAC MRV DH LCV  etc.

5. Backtracking Search Checklist (due Sun., 31 Jan., 11:59pm) You must turn in a Sudoku solver that uses backtracking search to solve Sudoku puzzles, using the submission format described above. It will be called with a command line that contains an a input filename, an output filename, and a timeout parameter in seconds, but none of the heuristic nor consistency check tokens.

 One or Both in your team submitted archivedPlease submit only one ZIP file per assignment to the corresponding EEE DropBox o If your partner uploaded the ZIP file, pleasethen you can 1) submit ZIP file or 2) submit < yourLastName_yourUCINumericID_yourTeamName>.text  your name/UCI numeric ID  your partner’s name/UCI numeric ID  your team name  all delimited by newlines.  Your program can MUST be executableed in openlab.ics.uci.edu o If you can’t, then state that in progress report, and explain why. If this outcome occurs, please consult with the TA and Reader well in advance of the deadline.  Your program MUST process input in the right way  While generating a problem, it should read M, N, P, Q as defined in the specification. If you change the role of P and Q then your output problem will be regarded as a wrong result o While solving a problem, it should produce the output file properly. If string the output file doesn’t match with the specification, your program could get an under- evaluated scorewill lose points.  You also must submit ating progress report (1 page plus+ appendix) o You should state if you are claiming extra credit for your own design and implementation. You don’t need to explain in detail, but do indicate what you dids.  Don’t miss the deadline! o You can upload version 1.0 early, and you canthen upload better ones later as available. o Last Updated Jan-26-2016. How to make a jar file and run it in openlab?

Make sure that you are using JAVA version 1.7. Please use Eclipse (or similar IDEs) to get JAR

Once you upload your JAR file to openlab

If you have any difficulty please contact [email protected] How to configure C++ project in openlab? If your g++ version is less than 5.2 and you want to use it Try $module load gcc/5.2.0 Check version after load $g++ --version

To compile C++ project, Try

$g++ [options] [source files] [include directories for header] [library directories] [libraries for linking] [-o output_name]

[options] : -static

if you are linking static library *.a

[include directories]: -I/home/junkyul/project/include1

If you want to add more than 1, then add another one like –I/home/junkyul/project/include2

[library directories]: -L/home/junkyul/project/librarypath

If you want to add more than 1, then add another one like –L/home/junkyul/project/librarypath2

[libraries for linking]: -lLIBNAME

If you are linking libXXX.a then add –lXXX (remove lib)

[-o output_name]: output_name will be your executable’s name

If you have any difficulty, please contact [email protected] How to configure Python project in openlab?

If your interpreter version is less than 3.4.3, (In February, Python 3.5 will be available) Try $module load python/3.4.3

Check python interpreter version $python

If you have any difficulty, please contact [email protected] How to Use “testing program” in OPENLAB ?

It will be announced on Thursday when we release testing program.