Second revision and added rules of the game.

1 files changed, 105 insertions, 47 deletions

diff --git a/doc/tex/systemAnalysis.tex b/doc/tex/systemAnalysis.tex
index 5263d1f..811a8f3 100644
--- a/doc/tex/systemAnalysis.tex
+++ b/doc/tex/systemAnalysis.tex
@@ -1,5 +1,9 @@
 \section{System Analysis}
 
+This section provides a preliminary analysis of the needs of the project, such
+as its requirements, components and use cases. It also includes the
+specification of the testing plan.
+
 \subsection{System Reach Determination}
 
 These are the main goals the final product must reach.
@@ -12,8 +16,8 @@ These are the main goals the final product must reach.
 
 	\item A library for representing the game of Go. It can be used for the
 		decision algorithms to keep the state of the game and can also be used
-		in an interactive application for a user to play the game and test the
-		code.
+		in an interactive application for a human user to play the game and test
+		the code.
 
 	\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
@@ -50,7 +54,7 @@ requisites needed for the system.
 				coordinates of the vertex to play on or as ``pass''.
 				\begin{enumerate}
 					\item The text introduced for the move must follow the
-						regular expression \texttt{([A-Z][0-9]+|pass)}
+						regular expression \texttt{([A-HJ-Z][0-9]+)|(pass)}
 					\item If the move is not valid it must be notified to the
 						user and another move asked for.
 				\end{enumerate}
@@ -149,8 +153,8 @@ requisites needed for the system.
 	\item The trainer can import existing games.
 		\begin{enumerate}
 			\item Records of games stored as \acrshort{sgf} can be imported.
-			\item Files containing records of games are provided as arguments to
-				the trainer.
+			\item Files containing records of games can be provided as arguments
+				to the trainer.
 		\end{enumerate}
 
 \end{enumerate}
@@ -178,13 +182,13 @@ requisites needed for the system.
 \begin{enumerate}
 
 	\item For understanding the workings of the application the user needs to be
-		familiar with the basics of the game of Go.
+		familiar with the rules of the game of Go.
 
 	\item For directly using the engine the user needs to be familiar with
 		command line interfaces.
 
-	\item For directly using the trainer the user needs to know the different
-		network models available.
+	\item For directly using the trainer the user needs to know about the
+		different network models available.
 
 \end{enumerate}
 
@@ -194,7 +198,7 @@ requisites needed for the system.
 
 \begin{enumerate}
 
-	\item The game program will be a Python file able to be executed by the
+	\item The game program will be a Python script able to be executed by the
 		Python interpreter.
 
 	\item The game program will make use of standard input and standard output
@@ -205,7 +209,7 @@ requisites needed for the system.
 			\item Standard output will be used for messages directed to the user.
 		\end{enumerate}
 
-	\item The engine program will be a Python file able to be executed by the
+	\item The engine program will be a Python script able to be executed by the
 		Python interpreter.
 
 	\item The engine program will make use of standard input and standard output
@@ -216,11 +220,11 @@ requisites needed for the system.
 				commands.
 		\end{enumerate}
 
-	\item The trainer program will be a Python file able to be executed by the
+	\item The trainer program will be a Python script able to be executed by the
 		Python interpreter.
 
-	\item The engine program will make use of standard input and standard output
-		for communication.
+	\item The trainer program will make use of standard input and standard
+		output for communication.
 		\begin{enumerate}
 			\item Standard input will be used for reading commands.
 			\item Standard output will be used for showing the result of
@@ -289,12 +293,15 @@ internal representation of a game resulting from the processing of an
 
 \subsection{Class Analysis}
 
+This section describes the needed classes expected as a result of the analysis
+of the project.
+
 \subsubsection{Class Diagram}
 
 The classes resulting from the analysis phase are shown in
 \fref{fig:analysisClasses}.
 
-\begin{figure}[h]
+\begin{figure}[p]
 	\begin{center}
 		\includegraphics[width=\textwidth]{diagrams/analysisClasses.png}
 		\caption{General classes obtained from the analysis
@@ -716,13 +723,14 @@ 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.
 
 \end{itemize}
 
 \subsection{Use Cases}
 
-\begin{figure}[h]
+\begin{figure}[p]
 	\begin{center}
 		\includegraphics[width=\textwidth]{diagrams/useCases.png}
 		\caption{Use cases.}
@@ -738,20 +746,25 @@ use case is explained next.
 The game interface reads the moves presented by the player and shows their
 result on the board.
 
+\paragraph{Generate a move}
+
+The engine interface reads the input for generating a move as stated by the
+\acrshort{gtp} protocol and outputs the coordinates of the board to play.
+
+\paragraph{Train the engine}
+
+The training system is started to process matches stored as \acrshort{sgf} files
+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
 against another machine player.
 
-\paragraph{Generate a move}
-
-The engine interface reads the input for generating a move as stated by the
-\acrshort{gtp} protocol and outputs the coordinates of the board to play.
-
 \subsection{Use Case Analysis and Scenarios}
 
-\begin{figure}[h]
+\begin{figure}[p]
 	\begin{center}
 		\includegraphics[width=0.8\textwidth]{diagrams/useCase_playAMatch.png}
 		\caption{Use case: Play a match.}
@@ -759,6 +772,8 @@ The engine interface reads the input for generating a move as stated by the
 	\end{center}
 \end{figure}
 
+\vspace{\interclassSpace}
+
 \begin{tabular}{lp{0.6\linewidth}}
 	\toprule
 	\multicolumn{2}{c}{\textbf{Play a match}} \\
@@ -794,7 +809,7 @@ The engine interface reads the input for generating a move as stated by the
 
 \vspace{\interclassSpace}
 
-\begin{figure}[h]
+\begin{figure}[p]
 	\begin{center}
 		\includegraphics[width=\textwidth]{diagrams/useCase_generateAMove.png}
 		\caption{Use case: Generate a move.}
@@ -836,7 +851,49 @@ The engine interface reads the input for generating a move as stated by the
 
 \vspace{\interclassSpace}
 
-\begin{figure}[h]
+\begin{figure}[p]
+	\begin{center}
+		\includegraphics[width=\textwidth]{diagrams/useCase_trainTheEngine.png}
+		\caption{Use case: Train the engine.}
+		\label{fig:useCase_trainTheEngine}
+	\end{center}
+\end{figure}
+
+\begin{tabular}{lp{0.6\linewidth}}
+	\toprule
+	\multicolumn{2}{c}{\textbf{Train the engine}} \\
+	\midrule
+	\textbf{Preconditions} & Some SGF files have been acquired to be used as
+	training games. \\
+	\midrule
+	\textbf{Postconditions} & A neural network model has been created or updated. \\
+	\midrule
+	\textbf{Actors} & Human user. \\
+	\midrule
+	\textbf{Description} &
+		1. The user starts the trainer.\newline
+		2. The trainer processes the input files.\newline
+		3. The trainer trains a model with the games described in the input
+		files. \\
+	\midrule
+	\textbf{Secondary scenarios} &
+	--- \\
+	\midrule
+	\textbf{Exceptions} &
+	\textbf{No input provided}: An error message is shown. Go back to step 1 of
+	main scenario. \newline
+	\textbf{The input is not formatted properly}: An error message is shown. Go
+	back to step 1 of main scenario. \\
+	\midrule
+	\textbf{Notes} &
+	A robustness diagram for this scenario is shown in
+	\fref{fig:useCase_trainTheEngine}.\\
+	\bottomrule
+\end{tabular}
+
+\vspace{\interclassSpace}
+
+\begin{figure}[p]
 	\begin{center}
 		\includegraphics[width=\textwidth]{diagrams/useCase_useAsBackend.png}
 		\caption{Use case: Use as backend for machine player.}
@@ -893,36 +950,37 @@ The Testing Plan will include four types of tests:
 
 \subsubsection{Unitary Testing}
 
-Tests for the Python code are developed using the unittest \cite{python_unittest}
-testing framework. It has been chosen by virtue of being thoroughly documented
-and widely used.
+A unitary testing suite provides test coverage at a base level, checking the
+correct behaviour of each specific code piece.
 
-The coverage of unit testing is checked with Coverage.py \cite{python_coverage},
-which can by itself run the unittest tests and generate coverage reports based
-on the results.
+\subsubsection{Integration Testing}
 
-The script used to run the tests is shown on \lref{lst:test} and its output on
-\lref{lst:testOutput}.
+The interaction between components will be tested to check their correct
+behaviour on the various situations where they have to work together:
 
-% Maybe put an example report here?
-\begin{listing}[h]
-	\inputminted{bash}{listings/test.sh}
-	\caption{Script to run the tests.}
-	\label{lst:test}
-\end{listing}
+\begin{itemize}
+\item The Engine module is able to use the Game module to handle a match.
+\item The Training module is able to use the Engine module and its definitions
+	of neural networks.
+\end{itemize}
 
-\begin{listing}[h]
-	\inputminted[fontsize=\footnotesize]{text}{listings/testOutput.txt}
-	\caption{Unitary testing output.}
-	\label{lst:testOutput}
-\end{listing}
+\subsubsection{System Testing}
 
-\subsubsection{Integration Testing}
+The working of the system as a whole has to be tested. Mainly:
 
-\subsubsection{System Testing}
+\begin{itemize}
 
-\subsubsection{Usability Testing}
+	\item A game of Go can be played by a human by using the Game module.
+	\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.
+	\item A training session can be started and it produces some results to be
+		evaluated independent of this test step.
 
-% Game playing
+\end{itemize}
+
+\subsubsection{Usability Testing}
 
-% Using the engine with an existing GUI
+Some people representing the final user will be confronted with the interfaces
+of the system to test its usability.