New doc elements (#27)

docs/cmap.md

@@ -0,0 +1,31 @@
+# Combinatorial maps
+
+2-dimensional combinatorial maps, or 2-C-maps for short,  are topological structures that allow us to represent and 
+handle 2D oriented manifold surfaces. In order to introduce this model, let us consider
+the following picture:
+- On the top left, the structure is made of 3 faces, or 2-cells: one quadrilateral, and two triangles
+- On the top right, the cells are explicitly named and in particular, we show that faces and nodes are considered.
+- In fact, faces are usually defined and built from a set of nodes. Here, for instance, the face *f1* is defined from 
+the ordered list of nodes : n1, n6, n5, n2. To have whole well-oriented structure, faces must be oriented in the same 
+direction (see bottom left).
+- The 2-C-map model is derived from this orientation. For every face, each edge is split and oriented accordingly. On 
+the bottom right, we can see those oriented edges (or darts), which are duplicated for edges that are
+shared by two faces (inner edges).
+
+<img src="img/split-model.png"/>
+
+The full 2-C-map is depicted below
+
+<img src="img/2Cmap.png" width="80%" height="70%"/>
+
+## Implementation choices 
+In order to represent 2D meshes with 2-C-map, we consider a data structue with 2 layers:
+- A cellular level that we traditionally handle. We have nodes and faces. Nodes have (x,y) coordinates and a face
+is built from an ordered list of nodes.
+- A topological level, which is a 2-C-map.
+
+Those 2 levels are interconnected:
+1. Each node and each face knows/stores the id of a dart that defines it;
+2. Each dart stores the id of the node it starts from and the face it belongs to, plus
+the id of the dart reached by beta1 and beta2. 
+

docs/design.md

@@ -1,11 +1,10 @@
-# Design principles
+# What to do in this project?
 
-
-## Incremental game design
+# Triangular mesh adaptation
 In order to learn how to modify a 2D mesh, we first implement a 2D game
 that works on pure triangular meshes. Starting from a 2D mesh, the goal 
 of the player is to modify the mesh by applying topological operations 
-in order to improve the **mesh quality**. Here the quality is defined 
+in order to improve the **mesh quality**. Here the quality is based 
 on topological criteria only. More precisely, we consider the degree 
 of nodes. The degree of a node is defined as its number of adjacent 
 faces. Ideally:
@@ -14,13 +13,9 @@ faces. Ideally:
 around *n*.
 
 ### Version 1 - Triangles and edge flip
-In this first version, we consider a pure triangular mesh, and we have only one 
-operation, the *edge flipping*
-
+In the first version, we have only one 
+operation - the *edge flipping* - and we provide triangular meshes for which we know
+what the best solution is. The aim of the intelligent agent we develop is to build this best 
+solution in a mininum number of movements.
 
-## CMap design choices
-1. Each node and each face knows/stores the id of a dart
-2. Each dart stores the id of the node and the face it belongs to, plus
-the id of the dart reached by beta1 and beta2. 
 
-<img src="img/scheme.png" width="70%" height="70%"/>

docs/dev/tools.md

@@ -1,10 +1,17 @@
-# Tools to use
+# Some development tips
 
-In order to contribute to this project, we suggest to download and use:
-- [Pycharm](https://www.jetbrains.com/pycharm/) as a Python IDE. The community edition is sufficient for this project
-- Python 3
-- Several python packages, which are 
-  - numpy
-  - pygame
+## Tools to use
 
-# Github procedure
+In order to contribute to this project, we suggest to download and/or use:
+- [Pycharm](https://www.jetbrains.com/pycharm/) as a Python IDE. The community edition is sufficient for this project;
+- Python 3 and some python packages like numpy and pygame;
+- To draw pictures, you can use the version of [Excalidraw](https://math.preview.excalidraw.com) that integrates LateX
+support;
+- The documentation is built using [MkDocs](https://www.mkdocs.org). To complete the documentation, you can
+add content in the [documentation directory](../../docs), and the documentation website will be updated when a branch 
+is merged in the main branch of **tune**. If you want to see the documentation in your own computer, you can use
+the `mkdocs serve` command (see [here](https://www.mkdocs.org/getting-started/) for a first example).
+
+## Github procedure
+We use merge/pull request to accept contributions. In other words, if you want to contribute to the **tune** project, 
+you have to develop in your own branch and ask for a merge request onto the main branch.