From d5d3ffad63ff3c274430725dd519191ec0f33029 Mon Sep 17 00:00:00 2001 From: InigoGutierrez Date: Wed, 29 Jun 2022 01:31:51 +0200 Subject: Updated use cases documentation. --- doc/tex/biber.bib | 6 ++ doc/tex/previousWorks.tex | 24 ++--- doc/tex/systemAnalysis.tex | 251 +++++++++++++++++++++++++++++++++------------ 3 files changed, 201 insertions(+), 80 deletions(-) (limited to 'doc/tex') 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} -- cgit v1.2.1