From 77764bee49c93a5d08d134cf7919b7f84a997e20 Mon Sep 17 00:00:00 2001 From: InigoGutierrez Date: Sat, 25 Jun 2022 19:56:48 +0200 Subject: Back to the documentation after creating neural networks. --- .gitignore | 11 +++ doc/Makefile | 5 +- doc/diagrams/interfaces.puml | 20 ++++++ doc/diagrams/planificationWorkPlanEngine.puml | 46 +++++++++---- doc/diagrams/planificationWorkPlanGame.puml | 22 +++--- doc/diagrams/useCases.puml | 8 ++- doc/tex/biber.bib | 8 +++ doc/tex/implementation.tex | 8 +-- doc/tex/interface.tex | 6 -- doc/tex/planification.tex | 35 ++++++++-- doc/tex/systemAnalysis.tex | 99 ++++++++++++++++++++++----- doc/tex/tfg.tex | 17 +++-- 12 files changed, 220 insertions(+), 65 deletions(-) create mode 100644 doc/diagrams/interfaces.puml delete mode 100644 doc/tex/interface.tex diff --git a/.gitignore b/.gitignore index 750838b..46fefef 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,10 @@ *.sgf +# images +*.png +*.jpg +*.xcf + # doc *.pdf doc/out/ @@ -12,3 +17,9 @@ __pycache__/ # ply parser.out parsetab.py + +# logs +*.log + +# NN models +models/ diff --git a/doc/Makefile b/doc/Makefile index 4153756..d2799a8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,8 +3,9 @@ docName = tfg outputFolder = out -texFiles = tex/tfg.tex tex/introduction.tex tex/planification.tex tex/interface.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 +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 all: $(docName).pdf diff --git a/doc/diagrams/interfaces.puml b/doc/diagrams/interfaces.puml new file mode 100644 index 0000000..3ade81e --- /dev/null +++ b/doc/diagrams/interfaces.puml @@ -0,0 +1,20 @@ +@startuml + +!include ./skinparams.puml + +component Game +component Engine +component Trainer + +interface "Game text interface" as GTI +interface "Engine text interface" as ETI +interface "Neural network model" as NNM +interface "SGF files" as SGF + +Game -- GTI +Engine -- ETI +Engine -- NNM +Trainer -- NNM +Trainer -- SGF + +@enduml diff --git a/doc/diagrams/planificationWorkPlanEngine.puml b/doc/diagrams/planificationWorkPlanEngine.puml index 53bd5ea..fcdb3ba 100644 --- a/doc/diagrams/planificationWorkPlanEngine.puml +++ b/doc/diagrams/planificationWorkPlanEngine.puml @@ -4,27 +4,43 @@ !include skinparamsGantt.puml 'printscale weekly +Saturday are closed Sunday are closed -Project starts 2021-01-04 +Project starts 2021-01-11 + +-- Preliminary research -- +[Previous works research] as [PWR] lasts 1 week +[Algorithms research] as [AR] lasts 2 weeks -- Engine Implementation -- -[Engine modelling] as [EM] starts 2021-01-04 [Engine modelling] as [EM] lasts 1 week -[Engine implementation] as [EI] lasts 5 weeks -[Engine testing] as [ET] lasts 5 weeks +[Engine implementation] as [EI] lasts 4 weeks -- Algorithms Implementations -- -[Algorithm research] as [AR] lasts 1 week -[Monte Carlo implementation] as [MCI] lasts 3 weeks -[Extra algorithms research] as [EAR] lasts 2 weeks -[Extra algorithms implementation] as [EAI] lasts 4 weeks - -[EM] -> [AR] -[AR] -> [MCI] -[AR] -> [EI] -[AR] -> [ET] -[EI] -> [EAR] -[EAR] -> [EAI] +[Monte Carlo implementation] as [MCI] lasts 4 weeks +[Neural networks research] as [NNR] lasts 2 weeks +[Neural networks implementation] as [NNI] lasts 3 weeks + +-- Testing -- +[Engine unit testing] as [EUT] lasts 4 weeks +[System testing] as [ST] lasts 1 week + +-- Analysis -- +[Algorithms comparison] as [AC] lasts 2 weeks + +[PWR] -> [AR] +[AR] -> [EM] + +[EM] -> [MCI] +[EM] -> [EI] +[EM] -> [EUT] + +[MCI] -> [NNR] +[NNR] -> [NNI] + +[NNI] -> [ST] + +[ST] -> [AC] @endgantt diff --git a/doc/diagrams/planificationWorkPlanGame.puml b/doc/diagrams/planificationWorkPlanGame.puml index 42b0821..fa09384 100644 --- a/doc/diagrams/planificationWorkPlanGame.puml +++ b/doc/diagrams/planificationWorkPlanGame.puml @@ -4,21 +4,27 @@ !include skinparamsGantt.puml 'printscale weekly +Saturday are closed Sunday are closed Project starts 2020-11-02 --- Preliminary investigation -- -[Previous works investigation] as [PWI] lasts 7 days -[Engines investigation] as [EI] lasts 7 days +-- Preliminary research -- +[Previous works research] as [PWR] lasts 1 week -- Game Implementation -- -[Domain modelling] as [DM] lasts 6 days -[Domain implementation] as [DI] lasts 30 days -[Domain testing] as [DT] lasts 30 days +[Domain modelling] as [DM] lasts 1 week +[Domain implementation] as [DI] lasts 6 weeks + +-- Testing -- +[Unit testing] as [UT] lasts 6 weeks +[System testing] as [ST] lasts 3 days + +[PWR] -> [DM] -[PWI] -> [DM] [DM] -> [DI] -[DM] -> [DT] +[DM] -> [UT] + +[DI] -> [ST] @endgantt diff --git a/doc/diagrams/useCases.puml b/doc/diagrams/useCases.puml index e3da3f8..022bd4c 100644 --- a/doc/diagrams/useCases.puml +++ b/doc/diagrams/useCases.puml @@ -3,16 +3,18 @@ !include skinparams.puml actor "Human Player" as player -actor "Human User" as user actor "GUI Program" as gui +actor "Human User" as user usecase "Play a match" as play -usecase "Generate a move" as genMove 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 -gui --> backend +user --> train @enduml diff --git a/doc/tex/biber.bib b/doc/tex/biber.bib index ef09d98..7dd5251 100644 --- a/doc/tex/biber.bib +++ b/doc/tex/biber.bib @@ -14,6 +14,14 @@ url = {https://www.lysator.liu.se/~gunnar/gtp} } +@online{sgf, + author = {Arno Hollosi}, + title = {SGF File Format FF[4]}, + date = {2021}, + urldate = {2022}, + url = {https://www.red-bean.com/sgf} +} + @online{katago, author = {David J Wu ("lightvector")}, title = {KataGo}, diff --git a/doc/tex/implementation.tex b/doc/tex/implementation.tex index 28fd0ec..297ba0e 100644 --- a/doc/tex/implementation.tex +++ b/doc/tex/implementation.tex @@ -3,10 +3,10 @@ \subsection{Engine} An implementation of GTP, that is, the piece of software which offers the GTP -interface to other applications.\@ It is designed to be used by a software controller -but can also be directly run, mostly for debugging purposes. Its design is shown -in \fref{fig:engine}. The core of the engine is related with three components, -each with a separate responsibility: +interface to other applications.\@ It is designed to be used by a software +controller but can also be directly run, mostly for debugging purposes. Its +design is shown in \fref{fig:engine}. The core of the engine is related with +three components, each with a separate responsibility: \begin{itemize} \item The IO component is the one called from other applications and offers diff --git a/doc/tex/interface.tex b/doc/tex/interface.tex deleted file mode 100644 index 9caa78d..0000000 --- a/doc/tex/interface.tex +++ /dev/null @@ -1,6 +0,0 @@ -\section{Interface} - -\subsection{Importing and exporting games} - -The format chosen to read and write games is SGF (Smart Game Format). It is a -widely used text format which allows for variants, comments and other metadata. diff --git a/doc/tex/planification.tex b/doc/tex/planification.tex index 5c9b253..942973f 100644 --- a/doc/tex/planification.tex +++ b/doc/tex/planification.tex @@ -21,10 +21,12 @@ Presented here are the ideal targets of the project. moves and variants of a match (a tree of moves) and the logic for the game's rules. \item An engine capable of analyzing board positions and generating strong - moves. + moves via various decision algorithms. \item Either a GUI specifically developed for the project or an implementation of an existing protocol so the engine can be used with existing tools and GUIs. + \item A way for processing existing records of games, which are usually + recorded in the SGF format. \end{itemize} \subsection{Project stages} @@ -70,7 +72,7 @@ The sole developer will be the student, who is currently working as a Junior Software Engineer on a 35 hour per week schedule and with no university responsibilities other than this project. Taking this into account, a sensible initial assumption is that he will be able to work 3 hours a day, Monday to -Saturday. Gantt diagrams for the planned working schedule are shown as +Friday. Gantt diagrams for the planned working schedule are shown as Fig.~\ref{fig:planificationWorkPlanGame} and Fig.~\ref{fig:planificationWorkPlanEngine}. @@ -120,7 +122,9 @@ A software capable of playing Go part of the GNU project. Although not a strong engine anymore, it is interesting for historic reasons as the free software engine for which the GTP protocol was first defined. -\subsubsection{GTP~\cite{gtp}} +\subsubsection{Existing standards} + +\paragraph{GTP~\cite{gtp}} GTP (\textit{Go Text Protocol}) is a text based protocol for communication with computer go programs. It is the protocol used by GNU Go and @@ -128,6 +132,13 @@ the more modern and powerful KataGo. By supporting GTP the engine developed for this project can be used with existing GUIs and other programs, making it easier to use it with the tools users are already familiar with. +\paragraph{SGF~\cite{sgf}} + +SGF (\textit{Smart Game Format}) is a text format widely used for storing +records of Go matches which allows for variants, comments and other metadata. +Many popular playing tools use it. By supporting SGF vast existing collections +of games can be used to train the decision algorithms based on neural networks. + \subsubsection{Sabaki~\cite{sabaki}} Sabaki is a go board software compatible with GTP engines. It can serve as a GUI @@ -148,7 +159,7 @@ choice is Python, for various reasons: specifically on AI research and development. \item Interpreters are available for many platforms, which allows the most people possible to access the product. - \item Although not too deeply, it has been used by the developer student + \item Although not very deeply, it has been used by the developer student during its degree including in AI and game theory contexts. \end{itemize} @@ -159,3 +170,19 @@ 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 GTP is a text based protocol for programs using text interfaces. Independent programs compatible with this interface can be used as a GUI. + +There is also the need of an interface with SGF files so existing games can be +processed by the trainer. + +Both the engine and the trainer will need to interface with the files storing +the neural network models. + +The systems' interfaces are shown in Fig.~\ref{fig:interfaces}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=\textwidth]{diagrams/interfaces.png} + \caption{Interfaces of the three components of the project. + }\label{fig:interfaces} + \end{center} +\end{figure} diff --git a/doc/tex/systemAnalysis.tex b/doc/tex/systemAnalysis.tex index 5868422..d0eb0b5 100644 --- a/doc/tex/systemAnalysis.tex +++ b/doc/tex/systemAnalysis.tex @@ -20,6 +20,20 @@ requisites needed for the system. \begin{enumerate} + \item The game program is interactive. + + \item Movements can be introduced to be played on the board. + \begin{enumerate} + \item A move is introduced as the textual representation of the + 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)} + \item If the move is not valid it must be notified to the + user and another move asked for. + \end{enumerate} + \end{enumerate} + \item The state of the board can be shown to the user. \begin{enumerate} \item A text representation of each cell is printed. @@ -36,18 +50,6 @@ requisites needed for the system. \end{enumerate} \end{enumerate} - \item Movements can be introduced to be played on the board. - \begin{enumerate} - \item A move is introduced as the textual representation of the - 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)} - \item If the move is not valid, it must be notified to the - user and another move asked for. - \end{enumerate} - \end{enumerate} - \item The board will behave according to the Japanese rules of Go. \end{enumerate} @@ -58,6 +60,8 @@ requisites needed for the system. \begin{enumerate} + \item The engine program is interactive. + \item The engine implements the GTP (\textit{Go Text Protocol}) for its interface. \begin{enumerate} @@ -102,6 +106,34 @@ requisites needed for the system. \end{enumerate} +\paragraph{Trainer Requirements} + +\setlist[enumerate,1]{label=FRT \arabic*.} + +\begin{enumerate} + + \item The trainer program is non-interactive. + + \item The trainer can be executed from the command line. + \begin{enumerate} + \item The trainer can be executed directly from an interactive shell. + \end{enumerate} + + \item The trainer can interact with stored neural network models. + \begin{enumerate} + \item The trainer can read stored models to continue training them. + \item The trainer can store model files after their training. + \end{enumerate} + + \item The trainer can import existing games. + \begin{enumerate} + \item Records of games stored as SGF can be imported. + \item Files containing records of games are provided as arguments to + the trainer. + \end{enumerate} + +\end{enumerate} + %\subsubsection{Security Requirements} % %\setlist[enumerate,1]{label=SR \arabic*.} @@ -129,6 +161,9 @@ requisites needed for the system. \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. + \end{enumerate} \subsubsection{Technological Requirements} @@ -140,12 +175,34 @@ requisites needed for the system. \item The game program will be a python file able to be executed by the python interpreter. - \item The program will make use of standard input and standard output for - communication. + \item The game program will make use of standard input and standard output + for communication. \begin{enumerate} \item Standard input will be used for reading moves. - \item Standard output will be used for showing the board and for - messages directed to the user. + \item Standard output will be used for showing the board. + \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 + python interpreter. + + \item The engine 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 + commands. + \end{enumerate} + + \item The trainer program will be a python file able to be executed by the + python interpreter. + + \item The engine 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 + commands. \end{enumerate} \end{enumerate} @@ -156,6 +213,7 @@ requisites needed for the system. \begin{enumerate} +%TODO: Check and update this to something feasible \item The maximum thinking time of the engine will be configurable. \begin{enumerate} \item It will be possible to pass the maximum time as a launch @@ -166,7 +224,6 @@ requisites needed for the system. \end{enumerate} - \setlist[enumerate,1]{label=\arabic*.} \subsection{System Actors} @@ -206,7 +263,13 @@ 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. +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 over a given list of moves. \subsection{Subsystems} diff --git a/doc/tex/tfg.tex b/doc/tex/tfg.tex index 6e2c472..5af6278 100644 --- a/doc/tex/tfg.tex +++ b/doc/tex/tfg.tex @@ -13,7 +13,7 @@ \usepackage[backend=biber, style=numeric, sorting=none]{biblatex} \addbibresource{tex/biber.bib} -\geometry{left=4.5cm,top=2cm,bottom=2cm,right=4.5cm} +\geometry{left=4cm,top=2cm,bottom=2cm,right=4cm} \hypersetup{colorlinks=false, linkcolor=black, @@ -42,6 +42,14 @@ \maketitle +\thispagestyle{empty} + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.6\textwidth]{img/imago.jpg} + \end{center} +\end{figure} + \begin{abstract} This is the abstract. \end{abstract} @@ -85,7 +93,8 @@ inclusion to use this template is included here. \begin{displayquote} - Copyright (C) 2019 \textbf{JOSÉ MANUEL REDONDO LÓPEZ}.\cite{plantillaRedondo} + Copyright (C) 2019 \textbf{JOSÉ MANUEL REDONDO + LÓPEZ}.\cite{plantillaRedondo} \textit{Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 @@ -108,9 +117,7 @@ inclusion to use this template is included here. \input{tex/systemDesign.tex} -%\input{tex/interface.tex} - -%\input{tex/implementation.tex} +\input{tex/implementation.tex} \clearpage -- cgit v1.2.1