Merge branch 'devel'HEADmaster

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}