diff options
| -rw-r--r-- | doc/Makefile | 2 | ||||
| -rw-r--r-- | doc/diagrams/useCase_generateAMove.puml | 24 | ||||
| -rw-r--r-- | doc/diagrams/useCase_playAMatch.puml | 20 | ||||
| -rw-r--r-- | doc/diagrams/useCase_useAsBackend.puml | 35 | ||||
| -rw-r--r-- | doc/diagrams/useCases.puml | 2 | ||||
| -rw-r--r-- | doc/tex/biber.bib | 6 | ||||
| -rw-r--r-- | doc/tex/previousWorks.tex | 24 | ||||
| -rw-r--r-- | doc/tex/systemAnalysis.tex | 251 |
8 files changed, 268 insertions, 96 deletions
diff --git a/doc/Makefile b/doc/Makefile index d2799a8..e849a01 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,7 +5,7 @@ outputFolder = out texFiles = tex/tfg.tex tex/introduction.tex tex/planification.tex tex/implementation.tex tex/systemAnalysis.tex tex/systemDesign.tex tex/biber.bib -diagramImgs = diagrams/gameRepresentation.png diagrams/gtpEngine.png diagrams/modules.png diagrams/planificationWorkPlanEngine.png diagrams/planificationWorkPlanGame.png diagrams/sgfModule.png diagrams/useCases.png diagrams/analysisClasses.png diagrams/useCase_useAsBackend.png diagrams/interfaces.png +diagramImgs = diagrams/gameRepresentation.png diagrams/gtpEngine.png diagrams/modules.png diagrams/planificationWorkPlanEngine.png diagrams/planificationWorkPlanGame.png diagrams/sgfModule.png diagrams/useCases.png diagrams/analysisClasses.png diagrams/useCase_generateAMove.png diagrams/useCase_useAsBackend.png diagrams/useCase_playAMatch.png diagrams/interfaces.png all: $(docName).pdf diff --git a/doc/diagrams/useCase_generateAMove.puml b/doc/diagrams/useCase_generateAMove.puml new file mode 100644 index 0000000..fa76edb --- /dev/null +++ b/doc/diagrams/useCase_generateAMove.puml @@ -0,0 +1,24 @@ +@startuml + +!include skinparams.puml + +actor "GUI program / Human user" as user + +boundary "Engine CLI" as cli +control "Play a stone" as playStone +control "Think next move" as think +entity "Board state" as state + +loop until desired board is set + user -> cli : play stone + cli -> playStone + playStone -> state + cli <- state +end + +user -> cli : ask for move +cli -> think +think -> state +cli <- state : Show move + +@enduml diff --git a/doc/diagrams/useCase_playAMatch.puml b/doc/diagrams/useCase_playAMatch.puml new file mode 100644 index 0000000..65d1517 --- /dev/null +++ b/doc/diagrams/useCase_playAMatch.puml @@ -0,0 +1,20 @@ +@startuml + +!include skinparams.puml + +actor "Player" as player + +boundary "Game CLI" as cli +control "Play a stone" as playStone +control "Show board" as showBoard +entity "Board state" as state + +loop until game ends + player -> cli + cli -> playStone + playStone -> state + showBoard <- state + cli <- showBoard +end + +@enduml diff --git a/doc/diagrams/useCase_useAsBackend.puml b/doc/diagrams/useCase_useAsBackend.puml index 3f1cece..9076769 100644 --- a/doc/diagrams/useCase_useAsBackend.puml +++ b/doc/diagrams/useCase_useAsBackend.puml @@ -2,22 +2,31 @@ !include skinparams.puml +actor "Opponent" as opponent actor "GUI Program" as program -boundary "Set board state" as setState -control "State set to represent the needed board" as setStateEngine +boundary "Engine CLI" as cli +control "Play a stone" as playStone +control "Think next move" as think entity "Board state" as state -boundary "Move is asked for" as ask -control "Engine thinks next move" as think -boundary "Move is suggested" as suggestion -program -> setState -setState -> setStateEngine -setStateEngine -> state -state -> ask -program -> ask -ask -> think -think -> suggestion -program -> suggestion +loop until starting board is set + program -> cli : play stone + cli -> playStone + playStone -> state + cli <- state +end + +loop until game ends + program -> cli : ask for move + cli -> think + think -> state + cli <- state : Show move + opponent -> program : give input + program -> cli : play stone + cli -> playStone + playStone -> state + cli <- state +end @enduml diff --git a/doc/diagrams/useCases.puml b/doc/diagrams/useCases.puml index 022bd4c..8d4aa71 100644 --- a/doc/diagrams/useCases.puml +++ b/doc/diagrams/useCases.puml @@ -9,12 +9,10 @@ actor "Human User" as user usecase "Play a match" as play usecase "Use as backend for machine player" as backend usecase "Generate a move" as genMove -usecase "Train a neural network" as train player --> play gui --> backend user --> genMove gui --> genMove -user --> train @enduml diff --git a/doc/tex/biber.bib b/doc/tex/biber.bib index 7dd5251..055ca8f 100644 --- a/doc/tex/biber.bib +++ b/doc/tex/biber.bib @@ -72,3 +72,9 @@ urldate = {2021}, url = {https://coverage.readthedocs.io} } + +@online{matplotlib_heatmaps, + title = {Creating annotated heatmaps — Matplotlib 3.5.2 documentation}, + urldate = {2022}, + url = {https://matplotlib.org/stable/gallery/images_contours_and_fields/image_annotated_heatmap.html} +} diff --git a/doc/tex/previousWorks.tex b/doc/tex/previousWorks.tex index bff0c82..6e503a3 100644 --- a/doc/tex/previousWorks.tex +++ b/doc/tex/previousWorks.tex @@ -1,17 +1,17 @@ \section{Previous works} -%\subsection{SGF} -% -%SGF (\textit{Smart Go Format} or, in a more general context, \textit{Smart Game -%Format}) is a text file format specification for records of games or collections -%of them. It was devised for Go but it supports other games with similar -%turn-based structure. It supports move variations, annotations, setups and game -%metadata. By supporting SGF our application can be used to analyse existing -%games registered by other applications, such as those played on online Go -%servers. -% -%The SGF specification can be found at -%\url{https://www.red-bean.com/sgf/user_guide/index.html} +\subsection{SGF} + +SGF (\textit{Smart Go Format} or, in a more general context, \textit{Smart Game +Format}) is a text file format specification for records of games or collections +of them. It was devised for Go but it supports other games with similar +turn-based structure. It supports move variations, annotations, setups and game +metadata. By supporting SGF our application can be used to analyse existing +games registered by other applications, such as those played on online Go +servers. + +The SGF specification can be found at +\url{https://www.red-bean.com/sgf/user_guide/index.html} \subsection{GTP} diff --git a/doc/tex/systemAnalysis.tex b/doc/tex/systemAnalysis.tex index 044f2ee..e4962d3 100644 --- a/doc/tex/systemAnalysis.tex +++ b/doc/tex/systemAnalysis.tex @@ -249,51 +249,6 @@ requisites needed for the system. \setlist[enumerate,1]{label=\arabic*.} -\subsection{System Actors} - -There are various actors who will interact with the system, both human and -non-human. - -\begin{itemize} - - \item The human player who interacts with the playing interface. - \item The human user who interacts with the engine. - \item A GUI software which uses the engine to generate moves. - -\end{itemize} - -\subsection{Use Cases} - -\begin{figure}[h] - \begin{center} - \includegraphics[width=\textwidth]{diagrams/useCases.png} - \caption{Use cases.}\label{fig:useCases} - \end{center} -\end{figure} - -The different actors and use cases are represented on \fref{fig:useCases}. Each -use case is explained next. - -\paragraph{Play a match} - -The game interface reads the moves presented by the player and shows their -result on the board. - -\paragraph{Generate moves} - -The engine interface reads the input for generating a move as stated by the -GTP protocol and outputs the coordinates of the board to play. - -\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 -against another machine player. - -\paragraph{Train a neural network} - -A neural network is trained by providing records of games. - \subsection{Subsystems} There will be three main subsystems. @@ -510,6 +465,8 @@ The classes resulting from the analysis phase are shown in \bottomrule \end{tabular} +\vspace{\interclassSpace} + \begin{tabular}{p{\linewidth}} \toprule \textbf{NeuralNetwork} \\ @@ -542,6 +499,8 @@ The classes resulting from the analysis phase are shown in \bottomrule \end{tabular} +\vspace{\interclassSpace} + \paragraph{Game System} \indent \\ @@ -585,7 +544,7 @@ The classes resulting from the analysis phase are shown in \tabitem{Logic related to a board position.} \\ \midrule \textbf{Proposed attributes} \\ - \tabitem{\textbf{Player[][] board}: An array of the stones on the board.} \\ + \tabitem{\textbf{board}: An array of the stones on the board.} \\ \midrule \textbf{Proposed methods} \\ \tabitem{\textbf{getGroupLiberties()}: Returns a set with the empty vertices @@ -644,6 +603,40 @@ The classes resulting from the analysis phase are shown in \vspace{\interclassSpace} +\begin{tabular}{p{\linewidth}} + \toprule + \textbf{GameBoard} \\ + \midrule + \textbf{Description} \\ + Represents a board. Contains played stones and the amount of captures made + by each player. \\ + \midrule + \textbf{Responsibilities} \\ + \tabitem{Store a specific layout of stones in the board.} \\ + \midrule + \textbf{Proposed attributes} \\ + \tabitem{\textbf{board}: An array containing the stone layout.} \\ + \tabitem{\textbf{capturesBlack}: The stones captured by black before the + position.} \\ + \tabitem{\textbf{capturesWhite}: The stones captured by white before the + position.} \\ + \midrule + \textbf{Proposed methods} \\ + \tabitem{\textbf{getBoardHeight()}: Returns the number of rows of the board.} \\ + \tabitem{\textbf{getBoardWidth()}: Returns the number of columns of the board.} \\ + \tabitem{\textbf{getGroupLiberties()}: Returns a list with the empty + vertices adjacent to the group occupying a vertex.} \\ + \tabitem{\textbf{getGroupVertices()}: Returns a list with the vertices + occupied by the group occupying a vertex.} \\ + \tabitem{\textbf{moveAndCapture()}: Makes a move and captures the + corresponding stones if the move results in the capture of a group.} \\ + \tabitem{\textbf{score()}: Gets the current score based on the already + surrounded territory. This follows Japanese rules.} \\ + \bottomrule +\end{tabular} + +\vspace{\interclassSpace} + %TODO: Finish the classes of the Game System \paragraph{Training System} @@ -655,46 +648,162 @@ The classes resulting from the analysis phase are shown in \textbf{Trainer} \\ \midrule \textbf{Description} \\ - . \\ + Provides the neural networks with moves to train on. \\ + \midrule + \textbf{Responsibilities} \\ + \tabitem{Obtain moves from stored records of matches.} \\ + \tabitem{Provide neural networks with moves to train on.} \\ + \midrule + \textbf{Proposed attributes} \\ + %TODO: Explain why this is empty + \midrule + \textbf{Proposed methods} \\ + %TODO: Explain why this is empty + \bottomrule +\end{tabular} + +\vspace{\interclassSpace} + +\begin{tabular}{p{\linewidth}} + \toprule + \textbf{Parser} \\ + \midrule + \textbf{Description} \\ + Reads SGF files and converts them to a tree of GameMove from the Game + System. \\ + \midrule + \textbf{Responsibilities} \\ + \tabitem{Read SGF files.} \\ + \tabitem{Convert the content of the SGF files to a tree of GameMove.} \\ + \midrule + \textbf{Proposed attributes} \\ + %TODO: Explain why this is empty + \midrule + \textbf{Proposed methods} \\ + %TODO: Explain why this is empty + \bottomrule +\end{tabular} + +\vspace{\interclassSpace} + +\begin{tabular}{p{\linewidth}} + \toprule + \textbf{ASTNode} \\ + \midrule + \textbf{Description} \\ + Makes up the tree resulting from the parsing of an SGF file.\\ \midrule \textbf{Responsibilities} \\ - \tabitem{.} \\ + \tabitem{Obtain a GameMove tree from itself and its children.} \\ \midrule \textbf{Proposed attributes} \\ - \tabitem{\textbf{}: .} \\ + \tabitem{\textbf{children}: The nodes following from itself.} \\ + \tabitem{\textbf{props}: The properties of the tree read from an SGF file.} + \\ \midrule \textbf{Proposed methods} \\ - \tabitem{\textbf{}: .} \\ + \tabitem{\textbf{toGameTree()}: Returns a GameMove tree corresponding to the + tree following from this node.} \\ \bottomrule \end{tabular} +\vspace{\interclassSpace} + +\subsection{System Actors} + +There are various actors who will interact with the system, both human and +non-human. + +\begin{itemize} + + \item The human player who interacts with the playing interface. + \item The human user who interacts with the engine. + \item A GUI software which uses the engine to generate moves. + +\end{itemize} + +\subsection{Use Cases} + +\begin{figure}[h] + \begin{center} + \includegraphics[width=\textwidth]{diagrams/useCases.png} + \caption{Use cases.} + \label{fig:useCases} + \end{center} +\end{figure} + +The different actors and use cases are represented on \fref{fig:useCases}. Each +use case is explained next. + +\paragraph{Play a match} + +The game interface reads the moves presented by the player and shows their +result on the board. + +\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 +against another machine player. + +\paragraph{Generate a move} + +The engine interface reads the input for generating a move as stated by the +GTP protocol and outputs the coordinates of the board to play. + \subsection{Use case analysis and scenarios} -\indent +\begin{figure}[h] + \begin{center} + \includegraphics[width=\textwidth]{diagrams/useCase_playAMatch.png} + \caption{Use case: Play a match.} + \label{fig:useCase_playAMatch} + \end{center} +\end{figure} \begin{tabular}{lp{0.7\linewidth}} \toprule - \multicolumn{2}{c}{\textbf{Play a match (Make a move?)}} \\ + \multicolumn{2}{c}{\textbf{Play a match}} \\ \midrule \textbf{Preconditions} & The game interface has been started. \\ \midrule - \textbf{Postconditions} & Description of postconditions \\ + \textbf{Postconditions} & The program terminates after a match has been + played. \\ \midrule - \textbf{Actors} & Actors \\ + \textbf{Actors} & Human player \\ \midrule - \textbf{Description} & Description \\ + \textbf{Description} & + 1. The user enters the move to make.\newline + 2. The result of playing that move is outputted by the program.\newline + 3. Stop the program if the game has ended or go back to 1 if not. \\ \midrule - \textbf{Secondary scenarios} & Secondary scenarios \\ + \textbf{Secondary scenarios} & + \textbf{The move is illegal}: An error message is shown. Go back to step 1 of + main scenario. \\ \midrule - \textbf{Exceptions} & Exceptions \\ + \textbf{Exceptions} & + \textbf{The input is wrong}: An error message is shown. Go back to step 1 of + main scenario. \\ \midrule \textbf{Notes} & - ---\\ + This scenario does not pretend to be a complete recreation of a go match. It + will be playable, but its main purpose is to see the Game implementation in + action.\newline + A robustness diagram for this scenario is shown in + \fref{fig:useCase_playAMatch}.\\ \bottomrule \end{tabular} \vspace{\interclassSpace} +\begin{figure}[h] + \begin{center} + \includegraphics[width=\textwidth]{diagrams/useCase_generateAMove.png} + \caption{Use case: Generate a move.} + \label{fig:useCase_generateAMove} + \end{center} +\end{figure} + \begin{tabular}{lp{0.7\linewidth}} \toprule \multicolumn{2}{c}{\textbf{Generate a move}} \\ @@ -719,21 +828,21 @@ The classes resulting from the analysis phase are shown in \midrule \textbf{Exceptions} & \textbf{The input is wrong}: An error message is shown. Go back to step 1 of - main scenario.\\ + main scenario. \\ \midrule \textbf{Notes} & - ---\\ + A robustness diagram for this scenario is shown in + \fref{fig:useCase_generateAMove}.\\ \bottomrule \end{tabular} \vspace{\interclassSpace} -\subsubsection{Use as backend for machine player} - \begin{figure}[h] \begin{center} \includegraphics[width=\textwidth]{diagrams/useCase_useAsBackend.png} - \caption{Use as backend for machine player} + \caption{Use case: Use as backend for machine player.} + \label{fig:useCase_useAsBackend} \end{center} \end{figure} @@ -749,10 +858,13 @@ The classes resulting from the analysis phase are shown in \textbf{Actors} & GUI program. \\ \midrule \textbf{Description} & - 1. The program gives commands to the engine. The specific commands will - vary from program to program.\newline - 2. The engine suggest moves to the program.\newline - 3. The moves are shown by the program as if made by another player.\\ + 1. The program gives commands to the engine to set up the game. The + specific commands will vary from program to program.\newline + 2. The program asks the engine for a move.\newline + 3. The engine suggest a move to the program.\newline + 4. The moves are shown by the program as if made by a player.\newline + 5. The opponent gives a move to the program.\newline + 6. Repeat from step 2 until the game ends. \\ \midrule \textbf{Secondary scenarios} & ---\\ @@ -761,10 +873,13 @@ The classes resulting from the analysis phase are shown in ---\\ \midrule \textbf{Notes} & - ---\\ + A robustness diagram for this scenario is shown in + \fref{fig:useCase_useAsBackend}.\\ \bottomrule \end{tabular} +\vspace{\interclassSpace} + \subsection{Testing Plan Specification} \subsubsection{Unitary Testing} |