diff options
Diffstat (limited to 'doc/tex')
| -rw-r--r-- | doc/tex/appendixes.tex | 279 | ||||
| -rw-r--r-- | doc/tex/glossary.tex | 5 | ||||
| -rw-r--r-- | doc/tex/imago.tex | 7 | ||||
| -rw-r--r-- | doc/tex/introduction.tex | 4 | ||||
| -rw-r--r-- | doc/tex/planning.tex | 6 | ||||
| -rw-r--r-- | doc/tex/systemAnalysis.tex | 12 | ||||
| -rw-r--r-- | doc/tex/systemDesign.tex | 2 |
7 files changed, 291 insertions, 24 deletions
diff --git a/doc/tex/appendixes.tex b/doc/tex/appendixes.tex index 581f764..ec6c2aa 100644 --- a/doc/tex/appendixes.tex +++ b/doc/tex/appendixes.tex @@ -3,6 +3,275 @@ 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 @@ -12,7 +281,7 @@ project. The costs are calculated based on a programmer salary of 20€/hour. -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r r} \toprule @@ -34,7 +303,7 @@ The costs are calculated based on a programmer salary of 20€/hour. \subsubsection{Material resources} -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r} \toprule @@ -48,7 +317,7 @@ The costs are calculated based on a programmer salary of 20€/hour. \subsubsection{Totals} -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r} \toprule @@ -64,9 +333,9 @@ The costs are calculated based on a programmer salary of 20€/hour. } \end{table} -\subsection{Budget for the client} +\subsubsection{Budget for the client} -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r} \toprule diff --git a/doc/tex/glossary.tex b/doc/tex/glossary.tex index d14dc02..25c0488 100644 --- a/doc/tex/glossary.tex +++ b/doc/tex/glossary.tex @@ -48,6 +48,7 @@ } \newacronym{ai}{AI}{Artificial Intelligence} -\newacronym{sgf}{SGF}{Smart Game Format} -\newacronym{gtp}{GTP}{Go Text Protocol} \newacronym{ast}{AST}{Annotated Syntax Tree} +\newacronym{gtp}{GTP}{Go Text Protocol} +\newacronym{gui}{GUI}{Graphical User Interface} +\newacronym{sgf}{SGF}{Smart Game Format} diff --git a/doc/tex/imago.tex b/doc/tex/imago.tex index f8e3101..4287330 100644 --- a/doc/tex/imago.tex +++ b/doc/tex/imago.tex @@ -8,6 +8,7 @@ \usepackage{enumitem} \usepackage[indent=20pt]{parskip} % Space between paragraphs \usepackage{indentfirst} % Indent first paragraph of sections +\usepackage{multicol} % Multiple columns \geometry{left=3cm,top=2cm,bottom=2cm,right=3cm} @@ -192,11 +193,7 @@ inclusion of to use this template is included here. \clearpage % References (bibliography) - -\setcounter{secnumdepth}{0} -\section{References} -\printbibliography[type=article,title={Cited articles},heading=subbibintoc]{} -\printbibliography[type=online,title={Online resources},heading=subbibintoc]{} +\printbibliography[heading=bibintoc]{} \clearpage \input{tex/license.tex} diff --git a/doc/tex/introduction.tex b/doc/tex/introduction.tex index 22dd98a..c50d700 100644 --- a/doc/tex/introduction.tex +++ b/doc/tex/introduction.tex @@ -18,7 +18,7 @@ As old and deep as Go is it has recently lived a revolution by the appearance of artificial intelligences with superhuman strength. While not expecting to achieve what a full team of developers and computer scientists at Google did, -this project aims to evaluate how an engine able to play the game of Go could be +this project aims to analyze how an engine able to play the game of Go could be created, implement such an engine and evaluate the results of the whole process. \subsection{Driving Needs} @@ -43,7 +43,7 @@ Presented here are the ideal targets of the project. game's rules. \item An engine capable of analyzing board positions and generating strong moves via various decision algorithms. - \item An interface compatible with existing GUIs. + \item An interface compatible with existing \acrshort{gui}s. \item A way for processing existing records of games, which are usually recorded in the \acrfull{sgf}. \end{itemize} diff --git a/doc/tex/planning.tex b/doc/tex/planning.tex index 4057268..790a988 100644 --- a/doc/tex/planning.tex +++ b/doc/tex/planning.tex @@ -139,7 +139,7 @@ of the project is shown on \fref{fig:gnuGoLogo}. The \acrfull{gtp} \cite{gtp} is a text based protocol for communication with computer Go programs. It is the protocol used by GNU Go and the more modern and powerful KataGo. By supporting \acrshort{gtp} the engine developed for this -project can be used with existing GUIs and other programs, making it easier to +project can be used with existing \acrshort{gui}s and other programs, making it easier to be used with the tools target users are already familiar with. %TODO @@ -191,7 +191,7 @@ described in this file is shown visually in \fref{fig:sgfExample}. \subsubsection{Sabaki} Sabaki \cite{sabaki} is a Go board software compatible with \acrshort{gtp} -engines. It can serve as a GUI for the engine developed in this project and as +engines. It can serve as a \acrshort{gui} for the engine developed in this project and as an example of the advantages of following a standardized protocol. Part of its graphical interface is shown on \fref{fig:sabaki}. @@ -245,7 +245,7 @@ Both the game and the engine will offer a text interface. For the game this allows for quick human testing. For the engine it is mandated by the protocol, since \acrshort{gtp} is a text based protocol for programs using text interfaces. Independent programs compatible with this interface will be able to -be used in conjunction with this engine, for example to serve as a GUI. +be used in conjunction with this engine, for example to serve as a \acrshort{gui}. There is also the need of an interface with \acrshort{sgf} files so existing games can be processed by the trainer. diff --git a/doc/tex/systemAnalysis.tex b/doc/tex/systemAnalysis.tex index 811a8f3..1f0c997 100644 --- a/doc/tex/systemAnalysis.tex +++ b/doc/tex/systemAnalysis.tex @@ -21,7 +21,7 @@ These are the main goals the final product must reach. \item An engine program as a way of presenting an interface for using these algorithms. The engine will use the \acrshort{gtp} so it can be used with an - existing GUI or other tools. + existing \acrshort{gui} or other tools. \item A parser for \acrshort{sgf} files so they can be processed in the training of neural networks. @@ -724,7 +724,7 @@ non-human. \item The human player who interacts with the playing interface. \item The human user who interacts with the engine. \item The human user who starts the training. - \item A GUI software which uses the engine to generate moves. + \item A \acrshort{gui} software which uses the engine to generate moves. \end{itemize} @@ -759,7 +759,7 @@ and to train a neural network. \paragraph{Use as backend for machine player} The engine is used as the backend for generating moves for a machine player, -this is, for automated play, either against a human who is using the GUI or +this is, for automated play, either against a human who is using the \acrshort{gui} or against another machine player. \subsection{Use Case Analysis and Scenarios} @@ -826,7 +826,7 @@ against another machine player. \midrule \textbf{Postconditions} & A move is suggested via the engine output. \\ \midrule - \textbf{Actors} & Human user and GUI program. \\ + \textbf{Actors} & Human user and \acrshort{gui} program. \\ \midrule \textbf{Description} & 1. The user or program enters the player to generate the move @@ -910,7 +910,7 @@ against another machine player. \midrule \textbf{Postconditions} & A match has been played against the engine. \\ \midrule - \textbf{Actors} & GUI program. \\ + \textbf{Actors} & \acrshort{gui} program. \\ \midrule \textbf{Description} & 1. The program gives commands to the engine to set up the game. The @@ -974,7 +974,7 @@ The working of the system as a whole has to be tested. Mainly: \item A game of Go can be played against the computer by using the \acrshort{gtp} interface of the Engine module. \item The \acrshort{gtp} interface is compatible with at least one existing - GUI that claims compatibility with this protocol. + \acrshort{gui} that claims compatibility with this protocol. \item A training session can be started and it produces some results to be evaluated independent of this test step. diff --git a/doc/tex/systemDesign.tex b/doc/tex/systemDesign.tex index 78fb2dc..3542cb5 100644 --- a/doc/tex/systemDesign.tex +++ b/doc/tex/systemDesign.tex @@ -457,7 +457,7 @@ These are the questions provided to the testers. \item How strong did you find the engine? \end{itemize} - \item Playing a game against the interface through a third-party GUI: + \item Playing a game against the interface through a third-party \acrshort{gui}: \begin{itemize} \item Were you able to start the interface? \item Did you find any problems when setting up the engine? |