diff options
Diffstat (limited to 'doc/tex/appendixes.tex')
| -rw-r--r-- | doc/tex/appendixes.tex | 399 |
1 files changed, 399 insertions, 0 deletions
diff --git a/doc/tex/appendixes.tex b/doc/tex/appendixes.tex new file mode 100644 index 0000000..b4533d6 --- /dev/null +++ b/doc/tex/appendixes.tex @@ -0,0 +1,399 @@ +\section{Appendixes} + +Additional information is included here, after the main sections regarding the +project. + +\subsection{User manual} + +This manual explains to the end user how to use the software. + +\subsubsection{The game: the \texttt{go.py} interface} + +\texttt{go.py} is a simple executable to interact with the Game system of this +project. It makes use of no artificial intelligence whatsoever, its aim just +being allowing for human play. It can be executed in a shell as: + +{ + \centering + \begin{minipage}{0.4\textwidth} + \texttt{python go.py} + \end{minipage} + \par +} + +or by any other means of executing a python file with access to its input and +output streams. The executable receives no arguments and has no options. + +When executed the user is presented with the following interface: + +{ + \centering + \begin{minipage}{0.4\textwidth} + \inputminted{text}{listings/goInterface/01-start.txt} + \end{minipage} + \par +} + +The state of the board (empty for now) is shown and the user is prompted for a +move. The color to make the move is marked between brackets: \texttt{B} for +Black, \texttt{W} for White. + +A move can now be provided for the Black player, such as \texttt{e6}. + +{ + \centering + \begin{minipage}{0.4\textwidth} + \inputminted{text}{listings/goInterface/02-firstMove.txt} + \end{minipage} + \par +} + +The interface shows again the state of the board. The game can continue until +the move ``pass'' is provided for both players. + +{ + \centering + \begin{minipage}{\textwidth} + \begin{multicols}{2} + \inputminted[fontsize=\small]{text}{listings/goInterface/03-fullGame.txt} + \end{multicols} + \end{minipage} + \par +} + +The game will also show captured stones and notify illegal moves, such as wrong +input or because of the \gls{ko} rule. + +{ + \centering + \begin{minipage}{\textwidth} + \begin{multicols}{2} + \inputminted[fontsize=\small]{text}{listings/goInterface/04-ko.txt} + \end{multicols} + \end{minipage} + \par +} + +\subsubsection{The engine: the \texttt{imagocli.py} interface} + +\texttt{imagocli.py} is a text interface which follows the \acrfull{gtp} +specification. It can be executed in a shell as: + +{ + \centering + \begin{minipage}{0.4\textwidth} + \texttt{python imagocli.py} + \end{minipage} + \par +} + +If desired, the \acrshort{ai} to be run can be passed as an argument to the +\texttt{-e} option, but it is not necessary. The available arguments are: + +\begin{itemize} + + \item \texttt{montecarlo}: The Monte Carlo Tree Search algorithm is used. + \item \texttt{keras}: The default Keras neural network, the convolutional + one, is used. + \item \texttt{dense}: The dense neural network is used. + \item \texttt{conv}: The convolutional neural network is used. + +\end{itemize} + +So, if for example the dense neural network is the one to use, the program would +be executed as: + +{ + \centering + \begin{minipage}{0.4\textwidth} + \texttt{python imagocli.py -e dense} + \end{minipage} + \par +} + +If no arguments are provided the default configuration is to use the Monte Carlo +Tree Search algorithm. + +When executed interactively and before any input is provided it just waits for +input with no prompt whatsoever. This is in compliance with the \acrshort{gtp} +specification. + +These are the commands that the program knows and a short description of what +each does: + +\begin{itemize} + + \item \texttt{list\_commands}: Shows a list of the commands the engine + knows. + \item \texttt{known\_command}: Receives an argument and tells whether it is + a known command or not. + \item \texttt{name}: Shows the name of the program. + \item \texttt{version}: Shows the version of the program. + \item \texttt{protocol\_version}: Shows the implemented \acrshort{gtp} + version number. + \item \texttt{boardsize}: Changes the size of the board. Results in an + arbitrary internal state unless \texttt{clear\_board} is called after + it. + \item \texttt{clear\_board}: The board is cleared of stones, the record of + captured stones resets to zero and the move history resets to empty. + \item \texttt{komi}: Sets the value for \gls{komi}. + \item \texttt{fixed\_handicap}: The given number of handicap stones are + placed following the protocol specification, which follows traditional + placement of handicap. + \item \texttt{place\_free\_handicap}: The given number of handicap stones + are placed following the AI criteria. + \item \texttt{set\_free\_handicap}: The given number of handicap stones are + placed on the requested vertices. + \item \texttt{play}: A stone of the requested color is played at the + requested vertex. + \item \texttt{genmove}: A stone of the requested color is played following + the AI criteria. The played move is printed. + \item \texttt{undo}: The state is restored to before the last move, which is + removed from the move history. + \item \texttt{showboard}: Prints a text representation of the board state. + +\end{itemize} + +Here is an example of a session. + +{ + \centering + \begin{minipage}{\textwidth} + \begin{multicols}{2} + \inputminted[fontsize=\small]{text}{listings/imagocliInterface/01-start.txt} + \end{multicols} + \end{minipage} + \par +} + +Note how responses from the program begin with an equals symbol and a space but +with a question mark replacing the space to mark errors, like when providing an +unknown command (exemplified here with \texttt{nonexistentcommand} in line 16). + +This session consists first of some information asked to the engine: its name, +its version and the version of \acrshort{gtp} it implements. Then exemplifies +how to check if a command is implemented and an error answer. Then, the main +commands to interact with the game and the \acrshort{ai} are executed: +\texttt{play}, to provide an initial explicit move, and \texttt{genmove}, to +obtain an \acrshort{ai}-generated move. Finally, a representation of the board +state after these two moves is obtained with \texttt{showboard} and the engine +is closed with \texttt{quit}. + +\subsubsection{Example of \acrshort{gui} use: configuring Sabaki} + +Since the main aim of implementing a \acrshort{gtp} interface is having it be +compatible with existing tools, an explanation of how to use it in conjunction +with one such established tool is provided. + +\begin{figure}[p] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/01-initialScreen.jpg} + \caption{Sabaki after being started. + }\label{fig:sabakiStart} + \end{center} +\end{figure} + +Sabaki \cite{sabaki} is a Go board software compatible with \acrshort{gtp} +engines. It can be downloaded from \texttt{https://sabaki.yichuanshen.de/}. When +started, it shows a screen such as the one in \fref{fig:sabakiStart}. + +\begin{figure}[p] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/02-examplePlaying.jpg} + \caption{Playing some moves on the default board. + }\label{fig:sabakiExampleMoves} + \end{center} +\end{figure} + +This initial screen contains a 19x19 board ready to be played on by local human +players. The stones can be placed by clicking on the desired vertices of the +board and, as would be expected, the interface swaps between players after each +move. An example of the screen after some initial moves can be seen on +\fref{fig:sabakiExampleMoves}. + +\begin{figure}[p] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/03-enginesSidebar.jpg} + \caption{Opened the engines sidebar (on the left). + }\label{fig:sabakiEnginesSidebar} + \end{center} +\end{figure} + +To set Sabaki to work with \texttt{imagocli.py} first open the engines sidebar +by clicking on ``Engines'', then ``Show Engines Sidebar''. The window should now +look like the one shown on \fref{fig:sabakiEnginesSidebar}, with the engines +sidebar open at the left but with nothing shown on it yet. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/04-engineManagement.jpg} + \caption{The engine management window. + }\label{fig:sabakiEngineManagement} + \end{center} +\end{figure} + +Click on the symbol on the top left of the engines sidebar, the one with a +triangle inside of a circle (the play button), and on ``Manage Engines...'' on +the opened floating dialog. The engine management window will open, as shown on +\fref{fig:sabakiEngineManagement}. + +\begin{figure}[p] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/05-configuredEngine.jpg} + \caption{\texttt{imagocli.py} configured as engine. + }\label{fig:sabakiConfiguredEngine} + \end{center} +\end{figure} + +Engines are listed on the big box at the center of the window, but if none has +yet been configured nothing will be shown there. Click ``Add'' to create the +first engine entry. Give it a name by writing on the first line of the newly +created entry, then write the path to the \texttt{imagocli.py} executable +besides the folder symbol, at the text box prompting for the path to the engine. +Alternatively, click on the folder symbol and a file explorer will open where it +will be possible to graphically select the executable file. Arguments and +initial commands to provide to the engine can be configured here, but none of +them will be needed for the default configuration of \program{}. An example of +the configured engine is shown on \fref{fig:sabakiConfiguredEngine}. + +\begin{figure}[p] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/06-configuringAMatch.jpg} + \caption{Configuring a match against the engine. + }\label{fig:sabakiConfiguringAMatch} + \end{center} +\end{figure} + +The engine management window can now be closed by clicking on ``Close'' at its +bottom right. Click again on the play button, the one on the top left of the +engines sidebar, and select the newly created engine entry. The engine will now +be started. By default, Sabaki will provide it the \texttt{name}, +\texttt{version}, \texttt{protocol\_version} and \texttt{list\_commands} +commands, and the text interface will be shown on the engines sidebar. To play +against the engine, click on ``File'', then ``New'', or just use the keyboard +shortcut Ctrl+N. A window will be shown where a new game can be configured. The +most important settings are making the engine be one (or both) of the players +and setting the board size to 9x9, since this is where the engine plays best. +For example, to set the engine as the white player, click on the arrow next to +the white player's name and select the engine, represented by the name given to +it before, on the floating menu. The size of the board can be set on the ``Board +Size'' setting. Other options allow to set a name for the other player, a name +for the match, the \gls{komi} and the handicap stones, if any. When ready, click +``Ok'' on the bottom right of the window. An example configuration can be seen +on \fref{fig:sabakiConfiguringAMatch}. If the engine doesn't respond to the +moves, which should be clear since its status is shown on the engines sidebar, +try adding it to the match by clicking on ``Attach Engine'' and then on its name +on the new match window, instead of directly on its name. This creates a new +entry for the engine on the engines sidebar. Multiple instances of the same or +different engines can be running at the same time; to remove one, just right +click on its name and click on ``Detach'' on the floating menu. + +\begin{figure}[p] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/07-playingAgainstImago.png} + \caption{Playing some moves against \program{}. + }\label{fig:sabakiAgainstTheEngine} + \end{center} +\end{figure} + +The engine can now be played against: when black (the human) makes a move, it +will respond as white. Some initial moves against it can be seen on +\fref{fig:sabakiAgainstTheEngine}. Note the interaction between Sabaki and the +\acrshort{gtp} interface on the engines sidebar. + +\clearpage + +\subsection{Budget} + +Here are tables regarding the costs of resources and development for the +project. + +\subsubsection{Work resources} + +The costs are calculated based on a programmer salary of 20€/hour. + +\begin{table}[H] + \makebox[\linewidth]{ + \begin{tabular}{l r r} + \toprule + \textbf{Task} & \textbf{Time (hours)} & \textbf{Cost (€)} \\ + \midrule + Game preliminary research & 15 & 300 \\ + \midrule + Game implementation & 95 & 1900 \\ + \midrule + Game unit testing & 90 & 1800 \\ + \midrule + Game system testing & 15 & 300 \\ + \midrule + Engine preliminary research & 15 & 300 \\ + \midrule + Engine implementation & 75 & 1500 \\ + \midrule + Algorithms implementations & 135 & 2700 \\ + \midrule + Engine testing & 75 & 1500 \\ + \midrule + Results analysis & 30 & 600 \\ + \midrule + \textbf{Total} & \textbf{545} & \textbf{10900} \\ + \bottomrule + \end{tabular} + } +\end{table} + +\subsubsection{Material resources} + +\begin{table}[H] + \makebox[\linewidth]{ + \begin{tabular}{l r} + \toprule + \textbf{Resource} & \textbf{Cost (€)} \\ + \midrule + Development computer & 600 \\ + \bottomrule + \end{tabular} + } +\end{table} + +\subsubsection{Totals} + +\begin{table}[H] + \makebox[\linewidth]{ + \begin{tabular}{l r} + \toprule + \textbf{Category} & \textbf{Cost (€)} \\ + \midrule + Work & 10900 \\ + \midrule + Materials & 600 \\ + \midrule + \textbf{Total} & \textbf{11500} \\ + \bottomrule + \end{tabular} + } +\end{table} + +\subsubsection{Budget for the client} + +\begin{table}[H] + \makebox[\linewidth]{ + \begin{tabular}{l r} + \toprule + \textbf{Task} & \textbf{Cost (€)} \\ + \midrule + Game system development & 2200 \\ + \midrule + Engine development & 4500 \\ + \midrule + Testing & 3600 \\ + \midrule + Result analysis & 600 \\ + \midrule + Materials & 600 \\ + \midrule + \textbf{Total} & \textbf{11500} \\ + \bottomrule + \end{tabular} + } +\end{table} |