path: root/doc/tex/appendixes.tex

\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}