\section{System Analysis} %\subsection{System reach determination} \subsection{System Requirements} The requirements for the system are expressed here in a nested list way, each of them with a textual and numeric reference for them to be traceable. The functional requirements are exposed first, followed by the other kinds of requisites needed for the system. \setlist[enumerate,2]{label*=\arabic*.} \setlist[enumerate,3]{label*=\arabic*.} \subsubsection{Functional Requirements} \paragraph{Game Requirements} \setlist[enumerate,1]{label=FRG \arabic*.} \begin{enumerate} \item The state of the board can be shown to the user. \begin{enumerate} \item A text representation of each cell is printed. \begin{enumerate} \item A different character is used for each different state of a cell. \end{enumerate} \item The coordinates system is shown around the board. \begin{enumerate} \item Columns are shown as capital letters left to right starting with ``A'' and skipping ``I''. \item Rows are shown as numbers starting with 1 on the lowest row and increasing upwards. \end{enumerate} \end{enumerate} \item Movements can be introduced to be played on the board. \begin{enumerate} \item A move is introduced as the textual representation of the coordinates of the vertex to play on or as ``pass''. \begin{enumerate} \item The text introduced for the move must follow the regular expression \texttt{([A-Z][0-9]+|pass)} \item If the move is not valid, it must be notified to the user and another move asked for. \end{enumerate} \end{enumerate} \item The board will behave according to the Japanese rules of Go. \end{enumerate} \paragraph{Engine Requirements} \setlist[enumerate,1]{label=FRE \arabic*.} \begin{enumerate} \item The engine implements the GTP (\textit{Go Text Protocol}) for its interface. \begin{enumerate} \item Commands are read from standard input. \item Responses are provided via standard output. \item There exist commands to set up the conditions of the match. \begin{enumerate} \item The size of the board can be set. \item The komi can be set. \end{enumerate} \item There exist commands to manipulate the internal representation of the match. \begin{enumerate} \item It is possible to indicate a move being played. \item It is possible to clear the board. \end{enumerate} \item There exists a command to generate a move. \begin{enumerate} \item The generated move must be a playable move. \item Generating a move does not change the internal representation of the match. \end{enumerate} \item There exist commands to ask for information about the engine. \begin{enumerate} \item It is possible to ask for the protocol version implemented. \item It is possible to ask for the name of the engine. \item It is possible to ask for the version of the engine. \item It is possible to ask whether a specific command is known to the engine. \item It is possible to ask for a list of the known commands. \end{enumerate} \item There exists a command to stop the engine. \end{enumerate} \item The engine can be executed from the command line. \begin{enumerate} \item The engine can be executed directly from an interactive shell. \item The engine can be executed by another program to be used as backend. \end{enumerate} \end{enumerate} %\subsubsection{Security Requirements} % %\setlist[enumerate,1]{label=SR \arabic*.} \subsubsection{Usability Requirements} \setlist[enumerate,1]{label=UR \arabic*.} \begin{enumerate} \item The engine executable will include a help option with the different modes of execution. \end{enumerate} \subsubsection{User Requirements} \setlist[enumerate,1]{label=USR \arabic*.} \begin{enumerate} \item For understanding the workings of the application the user needs to be familiar with the basics of the game of Go. \item For directly using the engine the user needs to be familiar with command line interfaces. \end{enumerate} \subsubsection{Technological Requirements} \setlist[enumerate,1]{label=TR \arabic*.} \begin{enumerate} \item The game program will be a python file able to be executed by the python interpreter. \item The program will make use of standard input and standard output for communication. \begin{enumerate} \item Standard input will be used for reading moves. \item Standard output will be used for showing the board and for messages directed to the user. \end{enumerate} \end{enumerate} \subsubsection{Response Time Requirements} \setlist[enumerate,1]{label=RTR \arabic*.} \begin{enumerate} \item The maximum thinking time of the engine will be configurable. \begin{enumerate} \item It will be possible to pass the maximum time as a launch argument. \item It will be possible to store the maximum time as a setting in a configuration file. \end{enumerate} \end{enumerate} \setlist[enumerate,1]{label=\arabic*.} \subsection{System Actors} There are various actors who will interact with the system, both human and non-human. \begin{itemize} \item The human player who interacts with the playing interface. \item The human user who interacts with the engine. \item A GUI software which uses the engine to generate moves. \end{itemize} \subsection{Use Cases} \begin{figure}[h] \begin{center} \includegraphics[width=\textwidth]{diagrams/useCases.png} \caption{Use cases.}\label{fig:useCases} \end{center} \end{figure} The different actors and use cases are represented on \fref{fig:useCases}. Each use case is explained next. \paragraph{Play a match} The game interface reads the moves presented by the player and shows their result on the board. \paragraph{Generate moves} The engine interface reads the input for generating a move as stated by the GTP protocol and outputs the coordinates of the board to play. \paragraph{Use as backend for machine player} The engine is used as the backend for generating moves for a machine player. \subsection{Subsystems} There will be two main subsystems. % TODO: Are there really two different subsystems? They look very coupled, since % the engine will use some classes of the game. This section is more suited for % independently run systems which communicate through some common interface. % ...Or maybe not. From the template: "Subsystems are groupings of packages and % classes with a common objective. Examples of subsystems are the classes which % handle the database, classes joining a group of related services..." \subsubsection{Game System} The first, called the Game System, will be in charge of storing all the state information regarding a Go match, such as the history of moves, the possible variations, the state of the board at any given time or the current number of captured stones. This system will include a command-line interface with which to play Go matches between human players to show and test its capabilities. \subsubsection{Engine System} The second, called the Engine System, will implement the GTP interface and use the Game System to analyze positions and generate moves via decision algorithms. This system can be directly called to manually set up game states and ask for moves or can be called by other programs to be used as backend for playing matches against a computer player. %\subsubsection{Interface between subsystems} \subsection{Class analysis} \subsubsection{Class diagram} The classes resulting from the analysis phase are shown in \fref{fig:analysisClasses}. \begin{figure}[h] \begin{center} \includegraphics[width=\textwidth]{diagrams/analysisClasses.png} \caption{General classes obtained from the analysis phase.}\label{fig:analysisClasses} \end{center} \end{figure} \subsubsection{Class description} \newcommand{\interclassSpace}{30pt} \indent \begin{tabular}{p{\linewidth}} \toprule \textbf{EngineIO} \\ \midrule \textbf{Description} \\ Offers the interface with the engine. \\ \midrule \textbf{Responsibilities} \\ % TODO: Single responsibility would be better? \tabitem{Read input.} \\ \tabitem{Do some preprocessing.} \\ \tabitem{Forward commands to the engine logic component.} \\ \midrule \textbf{Proposed attributes} \\ \midrule \textbf{Proposed methods} \\ \tabitem{\textbf{start()}: Starts reading standard input in a loop.} \\ \bottomrule \end{tabular} \vspace{\interclassSpace} \begin{tabular}{p{\linewidth}} \toprule \textbf{EngineLogic} \\ \midrule \textbf{Description} \\ Does the core logic and connects the different components of the engine. \\ \midrule \textbf{Responsibilities} \\ \tabitem{Processes the commands and arguments forwarded by the IO component.} \\ \tabitem{Handles the logic of the game by using components from the game module.} \\ \tabitem{Calls a decision algorithm to generate moves.} \\ \midrule \textbf{Proposed attributes} \\ \midrule \textbf{Proposed methods} \\ \bottomrule \end{tabular} \vspace{\interclassSpace} \begin{tabular}{p{\linewidth}} \toprule \textbf{DecisionAlgorithm} \\ \midrule \textbf{Description} \\ Interface for the decision algorithms to be used by the engine. \\ \midrule \textbf{Responsibilities} \\ \tabitem{Analyzing game states and generating moves.} \\ \midrule \textbf{Proposed attributes} \\ \textit{(Depends on the algorithm.)} \\ \midrule \textbf{Proposed methods} \\ \tabitem{\textbf{genmove()}: Gives the coordinates of a move to play.} \\ \bottomrule \end{tabular} \vspace{\interclassSpace} \begin{tabular}{p{\linewidth}} \toprule \textbf{GameIO} \\ \midrule \textbf{Description} \\ Offers the interface with the game. \\ \midrule \textbf{Responsibilities} \\ \tabitem{Read input.} \\ \tabitem{Do some preprocessing.} \\ \tabitem{Forward commands to the game state component.} \\ \midrule \textbf{Proposed attributes} \\ \midrule \textbf{Proposed methods} \\ \tabitem{\textbf{start()}: Starts reading standard input in a loop.} \\ \bottomrule \end{tabular} \vspace{\interclassSpace} \begin{tabular}{p{\linewidth}} \toprule \textbf{GameState} \\ \midrule \textbf{Description} \\ Stores the state of a match. \\ \midrule \textbf{Responsibilities} \\ \tabitem{Store state information.} \\ \tabitem{Offer methods to manipulate the game state.} \\ \midrule \textbf{Proposed attributes} \\ \midrule \textbf{Proposed methods} \\ \tabitem{\textbf{getCurrentPlayer()}: Returns the player who should play next.} \\ \tabitem{\textbf{playMove()}: Play a move in the specified coordinates for the specified player.} \\ \tabitem{\textbf{playMoveForPlayer()}: Play a move in the specified coordinates for the player who should play next.} \\ \tabitem{\textbf{undo()}: Reset the state to how it was just before the last move was played.} \\ \bottomrule \end{tabular} \vspace{\interclassSpace} \begin{tabular}{p{\linewidth}} \toprule \textbf{GameBoard} \\ \midrule \textbf{Description} \\ Stores the state of a board position and handles its logic. \\ \midrule \textbf{Responsibilities} \\ \tabitem{Store the vertices of a board position.} \\ \tabitem{Logic related to a board position.} \\ \midrule \textbf{Proposed attributes} \\ \tabitem{\textbf{Player[][] board}: An array of the stones on the board.} \\ \midrule \textbf{Proposed methods} \\ \tabitem{\textbf{getGroupLiberties()}: Returns a set with the empty vertices adjacent to the group occupying a vertex.} \\ \tabitem{\textbf{getGroupLibertiesCount()}: Returns the number of liberties of the group occupying a vertex.} \\ \tabitem{\textbf{getGroupVertices()}: Returns a set with the vertices of the group occupying a vertex.} \\ \tabitem{\textbf{getGroupVerticesCount()}: Returns the number of stones of the group occupying a vertex.} \\ \bottomrule \end{tabular} \vspace{\interclassSpace} \begin{tabular}{p{\linewidth}} \toprule \textbf{GameMove} \\ \midrule \textbf{Description} \\ Stores information about a specific move and its relationships to the previous and next moves. \\ \midrule \textbf{Responsibilities} \\ \tabitem{Store information about a move (board, player, coordinates\ldots).} \\ \midrule \textbf{Proposed attributes} \\ \tabitem{\textbf{GameBoard board}: The board as of this move.} \\ \tabitem{\textbf{GameMove[] nextMoves}: The list of moves played after this one. Different moves represent different game variations.} \\ \tabitem{\textbf{GameMove previousMove}: The move before this one.} \\ \tabitem{\textbf{boolean isPass}: True if the move is a pass and not a stone placement.} \\ \tabitem{\textbf{int[] coords}: The coordinates of the board the move was played at. Have no meaning if \textbf{isPass} is true.} \\ \midrule \textbf{Proposed methods} \\ \tabitem{\textbf{getRow()}: Returns the row the move was played at.} \\ \tabitem{\textbf{getCol()}: Returns the col the move was played at.} \\ \tabitem{\textbf{getPlayer()}: Returns the player who played the move.} \\ \tabitem{\textbf{getNextPlayer()}: Returns the player who should play after this move.} \\ \tabitem{\textbf{getGameLength()}: Returns the number of moves the game has had.} \\ \tabitem{\textbf{getPlayableVertices()}: Returns the legal vertices for the next move.} \\ \tabitem{\textbf{addMove()}: Inserts a new children move for the given coordinates and for the player who should make the next move.} \\ \tabitem{\textbf{addMoveForPlayer()}: Inserts a new children move for the given coordinates and player.} \\ \bottomrule \end{tabular} \vspace{\interclassSpace} \subsection{Use case analysis and scenarios} \indent \begin{tabular}{lp{0.7\linewidth}} \toprule \multicolumn{2}{c}{\textbf{Play a match (Make a move?)}} \\ \midrule \textbf{Preconditions} & The game interface has been started. \\ \midrule \textbf{Postconditions} & Description of postconditions \\ \midrule \textbf{Actors} & Actors \\ \midrule \textbf{Description} & Description \\ \midrule \textbf{Secondary scenarios} & Secondary scenarios \\ \midrule \textbf{Exceptions} & Exceptions \\ \midrule \textbf{Notes} & ---\\ \bottomrule \end{tabular} \vspace{\interclassSpace} \begin{tabular}{lp{0.7\linewidth}} \toprule \multicolumn{2}{c}{\textbf{Generate a move}} \\ \midrule \textbf{Preconditions} & The game engine has been started. \newline Optionally, some moves have already been played. \\ \midrule \textbf{Postconditions} & A move is suggested via the engine output. \\ \midrule \textbf{Actors} & Human user and GUI program. \\ \midrule \textbf{Description} & 1. The user or program enters the player to generate the move for.\newline 2. The suggested move is outputted by the engine, either as coordinates or as an indication to pass. \\ \midrule \textbf{Secondary scenarios} & \textbf{The move is illegal}: An error message is shown. Go back to step 1 of main scenario. \\ \midrule \textbf{Exceptions} & \textbf{The input is wrong}: An error message is shown. Go back to step 1 of main scenario.\\ \midrule \textbf{Notes} & ---\\ \bottomrule \end{tabular} \vspace{\interclassSpace} \subsubsection{Use as backend for machine player} \begin{figure}[h] \begin{center} \includegraphics[width=\textwidth]{diagrams/useCase_useAsBackend.png} \caption{Use as backend for machine player} \end{center} \end{figure} \begin{tabular}{lp{0.7\linewidth}} \toprule \multicolumn{2}{c}{\textbf{Use as backend for machine player}} \\ \midrule \textbf{Preconditions} & The game engine has been configured as engine for the software. \\ \midrule \textbf{Postconditions} & A match has been played against the engine. \\ \midrule \textbf{Actors} & GUI program. \\ \midrule \textbf{Description} & 1. The program gives commands to the engine. The specific commands will vary from program to program.\newline 2. The engine suggest moves to the program.\newline 3. The moves are shown by the program as if made by another player.\\ \midrule \textbf{Secondary scenarios} & ---\\ \midrule \textbf{Exceptions} & ---\\ \midrule \textbf{Notes} & ---\\ \bottomrule \end{tabular} \subsection{Testing Plan Specification} \subsubsection{Unitary Testing} Tests for the python code are developed using the unittest\cite{python_unittest} testing framework. It has been chosen by virtue of being thoroughly documented and widely used. The coverage of unit testing is checked with Coverage.py\cite{python_coverage}, which can by itself run the unittest tests and generate coverage reports based on the results. % Maybe put an example report here? \subsubsection{Integration Testing} \subsubsection{System Testing}