From ddde2a9a43daf870c26bef33f47abe45b414c3d0 Mon Sep 17 00:00:00 2001 From: InigoGutierrez Date: Sun, 24 Jan 2021 20:47:26 +0100 Subject: First commit! --- doc/Makefile | 23 +++++++++++++ doc/diagrams/ASTNode.pumlc | 10 ++++++ doc/diagrams/GameMove.pumlc | 13 ++++++++ doc/diagrams/GameState.pumlc | 14 ++++++++ doc/diagrams/GameTree.pumlc | 8 +++++ doc/diagrams/MoveParser.pumlc | 7 ++++ doc/diagrams/SGF.pumlc | 8 +++++ doc/diagrams/gameRepresentation.puml | 14 ++++++++ doc/diagrams/gtpEngine.puml | 29 ++++++++++++++++ doc/diagrams/modules.puml | 9 +++++ doc/diagrams/sgfModule.puml | 17 ++++++++++ doc/diagrams/sgflex.pumlc | 8 +++++ doc/diagrams/sgfyacc.pumlc | 8 +++++ doc/diagrams/skinparams.puml | 9 +++++ doc/tex/implementation.tex | 64 ++++++++++++++++++++++++++++++++++++ doc/tex/interface.tex | 6 ++++ doc/tex/introduction.tex | 16 +++++++++ doc/tex/previousWorks.tex | 21 ++++++++++++ doc/tex/tfg.tex | 60 +++++++++++++++++++++++++++++++++ 19 files changed, 344 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/diagrams/ASTNode.pumlc create mode 100644 doc/diagrams/GameMove.pumlc create mode 100644 doc/diagrams/GameState.pumlc create mode 100644 doc/diagrams/GameTree.pumlc create mode 100644 doc/diagrams/MoveParser.pumlc create mode 100644 doc/diagrams/SGF.pumlc create mode 100644 doc/diagrams/gameRepresentation.puml create mode 100644 doc/diagrams/gtpEngine.puml create mode 100644 doc/diagrams/modules.puml create mode 100644 doc/diagrams/sgfModule.puml create mode 100644 doc/diagrams/sgflex.pumlc create mode 100644 doc/diagrams/sgfyacc.pumlc create mode 100644 doc/diagrams/skinparams.puml create mode 100644 doc/tex/implementation.tex create mode 100644 doc/tex/interface.tex create mode 100644 doc/tex/introduction.tex create mode 100644 doc/tex/previousWorks.tex create mode 100644 doc/tex/tfg.tex (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..954ae3c --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,23 @@ +.SUFFIXES: .puml .png + +docName = tfg +outputFolder = out + +texFiles = tex/tfg.tex tex/introduction.tex tex/previousWorks.tex tex/interface.tex tex/implementation.tex +diagramImgs = diagrams/gameRepresentation.png diagrams/modules.png diagrams/sgfModule.png diagrams/gtpEngine.png + +all: $(docName).pdf + +$(docName).pdf: $(texFiles) $(diagramImgs) + [ -d $(outputFolder) ] || mkdir $(outputFolder) + xelatex -output-directory $(outputFolder) tex/$(docName).tex + biber $(outputFolder)/$(docName) + xelatex -output-directory $(outputFolder) tex/$(docName).tex + mv $(outputFolder)/$(docName).pdf . + +.puml.png: + plantuml $< + +clean: + rm -r $(outputFolder) + rm diagrams/*.png diff --git a/doc/diagrams/ASTNode.pumlc b/doc/diagrams/ASTNode.pumlc new file mode 100644 index 0000000..05c13ac --- /dev/null +++ b/doc/diagrams/ASTNode.pumlc @@ -0,0 +1,10 @@ +@startuml + +class ASTNode { + ASTNode[] children + Property properties + void addtoSequence() + GameTree toGameTree() +} + +@enduml diff --git a/doc/diagrams/GameMove.pumlc b/doc/diagrams/GameMove.pumlc new file mode 100644 index 0000000..7dcb5e3 --- /dev/null +++ b/doc/diagrams/GameMove.pumlc @@ -0,0 +1,13 @@ +@startuml + +class GameMove { + int player + int row + int col + int[2] makesKo + int[] board + GameMove[] nextMoves + GameMove previousMove +} + +@enduml diff --git a/doc/diagrams/GameState.pumlc b/doc/diagrams/GameState.pumlc new file mode 100644 index 0000000..db39d8f --- /dev/null +++ b/doc/diagrams/GameState.pumlc @@ -0,0 +1,14 @@ +@startuml + +class GameState { + int player + int capturesBlack + int capturesWhite + List board + List prevBoards # for ko + GameTree gameTree + GameMove lastMove + GameData gameData +} + +@enduml diff --git a/doc/diagrams/GameTree.pumlc b/doc/diagrams/GameTree.pumlc new file mode 100644 index 0000000..85859d8 --- /dev/null +++ b/doc/diagrams/GameTree.pumlc @@ -0,0 +1,8 @@ +@startuml + +class GameTree { + GameNode[] firstMoves + GameData gameData +} + +@enduml diff --git a/doc/diagrams/MoveParser.pumlc b/doc/diagrams/MoveParser.pumlc new file mode 100644 index 0000000..4c0dc00 --- /dev/null +++ b/doc/diagrams/MoveParser.pumlc @@ -0,0 +1,7 @@ +@startuml + +class MoveParser { + int[] parseMove(input) +} + +@enduml diff --git a/doc/diagrams/SGF.pumlc b/doc/diagrams/SGF.pumlc new file mode 100644 index 0000000..2c30202 --- /dev/null +++ b/doc/diagrams/SGF.pumlc @@ -0,0 +1,8 @@ +@startuml + +class SGF { + GameTree loadGameTree(file) + void saveGameTree(file) +} + +@enduml diff --git a/doc/diagrams/gameRepresentation.puml b/doc/diagrams/gameRepresentation.puml new file mode 100644 index 0000000..9a869f1 --- /dev/null +++ b/doc/diagrams/gameRepresentation.puml @@ -0,0 +1,14 @@ +@startuml + +!include skinparams.puml + +!include GameState.pumlc +!include GameTree.pumlc +!include GameMove.pumlc + +GameState --> GameTree +GameState --> GameMove: Current move +GameTree *--> GameMove +GameMove -> GameMove + +@enduml diff --git a/doc/diagrams/gtpEngine.puml b/doc/diagrams/gtpEngine.puml new file mode 100644 index 0000000..c4caf32 --- /dev/null +++ b/doc/diagrams/gtpEngine.puml @@ -0,0 +1,29 @@ +@startuml + +!include skinparams.puml + +class EngineCore { +} + +class IO { + processComand() +} + +!include GameState.pumlc + +'class EngineBoard { +' setSize() +' setKomi() +' play() +' undo() +'} + +class EngineAI { + genmove(board) +} + +EngineCore --> IO +EngineCore --> GameState +EngineCore --> EngineAI + +@enduml diff --git a/doc/diagrams/modules.puml b/doc/diagrams/modules.puml new file mode 100644 index 0000000..064be1d --- /dev/null +++ b/doc/diagrams/modules.puml @@ -0,0 +1,9 @@ +@startuml + +!include ./skinparams.puml + +!include GameState.pumlc +!include SGF.pumlc +!include MoveParser.pumlc + +@enduml diff --git a/doc/diagrams/sgfModule.puml b/doc/diagrams/sgfModule.puml new file mode 100644 index 0000000..c8b51cd --- /dev/null +++ b/doc/diagrams/sgfModule.puml @@ -0,0 +1,17 @@ +@startuml + +!include ./skinparams.puml + +package "SGF" { + !include sgflex.pumlc + !include sgfyacc.pumlc + !include ASTNode.pumlc +} + +!include GameTree.pumlc + +sgflex <- sgfyacc +sgfyacc -> "*" ASTNode +ASTNode "1" -> "1" GameTree + +@enduml diff --git a/doc/diagrams/sgflex.pumlc b/doc/diagrams/sgflex.pumlc new file mode 100644 index 0000000..9b98885 --- /dev/null +++ b/doc/diagrams/sgflex.pumlc @@ -0,0 +1,8 @@ +@startuml + +object sgflex { + input() + token() +} + +@enduml diff --git a/doc/diagrams/sgfyacc.pumlc b/doc/diagrams/sgfyacc.pumlc new file mode 100644 index 0000000..72a2f3f --- /dev/null +++ b/doc/diagrams/sgfyacc.pumlc @@ -0,0 +1,8 @@ +@startuml + +object sgfyacc { + parse() +} + +@enduml + diff --git a/doc/diagrams/skinparams.puml b/doc/diagrams/skinparams.puml new file mode 100644 index 0000000..cde3da7 --- /dev/null +++ b/doc/diagrams/skinparams.puml @@ -0,0 +1,9 @@ +@startuml + +skinparam { + monochrome true + shadowing false + linetype polyline +} + +@enduml diff --git a/doc/tex/implementation.tex b/doc/tex/implementation.tex new file mode 100644 index 0000000..9e42313 --- /dev/null +++ b/doc/tex/implementation.tex @@ -0,0 +1,64 @@ +\section{Implementation} + +\subsection{Engine} + +An engine implementing GTP.\@ 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} + +\begin{figure}[h] + \begin{center} + \includegraphics[width=\textwidth]{diagrams/gtpEngine.png} + \caption{Design of the GTP engine.}\label{fig:engine} + \end{center} +\end{figure} + +\subsection{Modules} + +One module to store the state of the game and the game tree. One module to parse +moves. One module to read and write SGF files. Modules are shown in +\fref{fig:modules}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=\textwidth]{diagrams/modules.png} + \caption{Modules.}\label{fig:modules} + \end{center} +\end{figure} + +\subsection{Representation of a match} + +Strictly said, a match is composed of a series of moves. But since game review +and variants exploration is an important part of Go learing, \program{} allows +for navigation back and forth through the board states of a match and for new +variants to be created from each of these board states. Therefore, a match is +represented as a tree of moves. The state of the game must also be present so +liberties, captures and legality of moves can be addressed, so it is represented +with its own class, which holds a reference both to the game tree and the +current move. This classes and their relationship can be seen in +\fref{fig:gameRepresentation}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.7\textwidth]{diagrams/gameRepresentation.png} + \caption{A game is represented as a tree of moves.}\label{fig:gameRepresentation} + \end{center} +\end{figure} + +\subsection{SGF} + +To parse SGF files a lexer and parser have been implemented using PLY.\@ The +result of the parsing is an AST (Annotated Syntax Tree) reflecting the contents +of the text input, each node with zero or more properties, and with the ability +to convert themselves and their corresponding subtree into a GameTree. This is +done for the root node, since from the SGF specification there are some +properties only usable in the root node, like those which specify general game +information and properties such as rank of players or komi. These components are +shown in \fref{fig:sgfModule}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=\textwidth]{diagrams/sgfModule.png} + \caption{Components of the SGF file parsing module.}\label{fig:sgfModule} + \end{center} +\end{figure} diff --git a/doc/tex/interface.tex b/doc/tex/interface.tex new file mode 100644 index 0000000..9caa78d --- /dev/null +++ b/doc/tex/interface.tex @@ -0,0 +1,6 @@ +\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/introduction.tex b/doc/tex/introduction.tex new file mode 100644 index 0000000..6defbd9 --- /dev/null +++ b/doc/tex/introduction.tex @@ -0,0 +1,16 @@ +\section{Introduction} + +\begin{displayquote} + Go is an ancient game which, from its forgotten origins in China, spread first + to the rest of East Asia, and then to the entire world. How ancient? Historians + aren't sure; it has a definite history of over 3000 years, but according to + tradition Go was invented more than 4000 years ago. The English name comes from + the Japanese name Igo, which means ``surrounding boardgame''. + + In this game, each player tries to use threats of death, capture, or isolation + to assert control over more of the board than his opponent. An abstract strategy + game at heart, Go has nonetheless been interpreted as a stylized representation + of fighting a war, settling a frontier, cornering a market, thrashing out an + argument, or even of fortune-telling and prophecy. Go has always been one of the + most played games in the world. \parencite{sl_go} +\end{displayquote} diff --git a/doc/tex/previousWorks.tex b/doc/tex/previousWorks.tex new file mode 100644 index 0000000..6ba5dce --- /dev/null +++ b/doc/tex/previousWorks.tex @@ -0,0 +1,21 @@ +\section{Previous works} + +\subsection{SGF} + +SGF (\textit{Smart Go Format} or \textit{Smart Game Format}) is a text file +format specification for records of games or even collections of them. It was +devised for Go but it supports other games with similar turns 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} + +GTP (\textit{Go Text Protocol}) is a text based protocol for communication with +computer go programs. [ref https://www.lysator.liu.se/~gunnar/gtp/] It is the +protocol used by GNU Go and the more modern and powerful KataGo. By supporting +GTP, our application can be used with existing GUIs and other programs, making +it easier to use it with the tools users are already familiar with. diff --git a/doc/tex/tfg.tex b/doc/tex/tfg.tex new file mode 100644 index 0000000..9248748 --- /dev/null +++ b/doc/tex/tfg.tex @@ -0,0 +1,60 @@ +\documentclass{article} + +\usepackage{geometry} +\usepackage{graphicx} +\usepackage{booktabs} +\usepackage{hyperref} +\usepackage{csquotes} + +\usepackage[backend=biber, style=numeric-comp]{biblatex} +\addbibresource{/home/taamas/docs/biber.bib} + +\geometry{left=4.5cm,top=2cm,bottom=2cm,right=4.5cm} + +\hypersetup{colorlinks=true, + linkcolor=black, + filecolor=magenta, + urlcolor=black, + bookmarks=true +} + +\urlstyle{mono} + +%\renewcommand{\contentsname}{Contenidos} +%\renewcommand{\figurename}{Figura} + +\newcommand{\program}{Go-AI} + +\newcommand{\inputtex}[1]{\input{tex/#1}} +\newcommand{\fref}[1]{Fig.~\ref{#1}} +%\newcommand{\uurl}[1]{\underline{\url{#1}}} + +\begin{document} + +\frenchspacing + +\title{\program} + +\author{Íñigo Gutiérrez Fernández} + +\date{} + +\maketitle + +\begin{abstract} + This is the abstract. +\end{abstract} + +\tableofcontents + +\inputtex{introduction.tex} + +\inputtex{previousWorks.tex} + +\inputtex{interface.tex} + +\inputtex{implementation.tex} + +\printbibliography{} + +\end{document} -- cgit v1.2.1