aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorInigoGutierrez <inigogf.95@gmail.com>2022-06-29 01:31:51 +0200
committerInigoGutierrez <inigogf.95@gmail.com>2022-06-29 01:31:51 +0200
commitd5d3ffad63ff3c274430725dd519191ec0f33029 (patch)
tree8baf51a295542d0f13d1f30b8f60a52ee6880b35
parent32ba965ef1312856ef1ef1a90bb945f9fdba5537 (diff)
downloadimago-d5d3ffad63ff3c274430725dd519191ec0f33029.tar.gz
imago-d5d3ffad63ff3c274430725dd519191ec0f33029.zip
Updated use cases documentation.
-rw-r--r--doc/Makefile2
-rw-r--r--doc/diagrams/useCase_generateAMove.puml24
-rw-r--r--doc/diagrams/useCase_playAMatch.puml20
-rw-r--r--doc/diagrams/useCase_useAsBackend.puml35
-rw-r--r--doc/diagrams/useCases.puml2
-rw-r--r--doc/tex/biber.bib6
-rw-r--r--doc/tex/previousWorks.tex24
-rw-r--r--doc/tex/systemAnalysis.tex251
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}