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 prompt 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 \acrshort{gtp}
specification. It can be executed in a shell as:

{
	\centering
	\begin{minipage}{0.4\textwidth}
		\texttt{python imagocli.py}
	\end{minipage}
	\par
}

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.

There 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 wether 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 in in conjunction
with one such established tool is provided.

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}[h]
	\begin{center}
		\includegraphics[width=0.8\textwidth]{img/sabakiManual/01-initialScreen.jpg}
		\caption{Sabaki after being started.
		}\label{fig:sabakiStart}
	\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}[h]
	\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}

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/03-enginesSidebar.jpg}
		\caption{Opened the engines sidebar (on the left).
		}\label{fig:sabakiEnginesSidebar}
	\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}[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}

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.
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}[h]
	\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}

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}[h]
	\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 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.

\begin{figure}[h]
	\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}

\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 & 55 & 1100 \\
		\midrule
		Game unit testing & 50 & 1000 \\
		\midrule
		Game system testing & 5 & 100 \\
		\midrule
		\textbf{Total} & \textbf{125} & \textbf{2500} \\
		\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 & 2500 \\
		\midrule
		Materials & 600 \\
		\midrule
		\textbf{Total} & \textbf{3100} \\
		\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 preliminary research & 300 \\
		\midrule
		Game implementation & 1100 \\
		\midrule
		Game unit testing & 1000 \\
		\midrule
		Game system testing & 100 \\
		\midrule
		Materials & 600 \\
		\midrule
		\textbf{Total} & \textbf{3100} \\
		\bottomrule
	\end{tabular}
	}
\end{table}