doc: update content of the book (#485)

The content and illustrations come from my PhD manuscript.

Author: imrn99

user-guide/book.toml

@@ -6,3 +6,4 @@ title = "The Honeycomb Book"
 
 [output.html]
 site-url = "/honeycomb/"
+mathjax-support = true

user-guide/src/SUMMARY.md

@@ -8,7 +8,7 @@
   - [Components](./definitions/components.md)
   - [Cell representation](./definitions/cells.md)
   - [Embedding](./definitions/embedding.md)
-  - [Element insertion and deletion](./definitions/insertion.md)
+  - [Element insertion and deletion](./definitions/ops.md)
   - [Sewing operation](./definitions/sews.md)
 - [Transactional memory](./definitions/stm.md)
 - [Resources]()

user-guide/src/definitions/cells.md

@@ -1,51 +1,72 @@
 # Cell representation
 
-**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved
-at some point.**
-
 ---
 
-We define orbits as a set of darts that are accessible from a given dart,
-using a certain set of beta functions. For example:
+## Orbits
 
-- *⟨β<sub>1</sub>⟩(d)* refers to all darts accessible from *d* using
-  *β<sub>1</sub>* recursively any number of times.
-- *⟨β<sub>1</sub>, β<sub>3</sub>⟩(d)* refers to all darts accessible
-  from *d* using any combination of *β<sub>1</sub>* and *β<sub>3</sub>*.
+<figure style="text-align:center">
+    <img src="../images/2map.svg" alt="MapMeshEquivalent" width=100%/>
+    <figcaption><i>2-map example and its components values.</i></figcaption>
+</figure>
 
-## *i*-cells
+In our \\(2\\)-map example, applying \\(\beta_1\\) recursively to \\(d_1\\) makes us cycle through
+darts \\(d_1\\), \\(d_2\\), \\(d_3\\), that belong to different edges. Applying \\(\beta_2\\)
+to \\(d_6\\) makes us cycle between \\(d_6\\) and \\(d_8\\), both belonging to different faces.
+This set of darts accessible from a starting dart via a given \\(\beta_i\\) function is called
+**orbit**.
 
-A specific subset of orbits, referred to as *i*-cells are defined and often
-used in algorithms. The general definition is the following:
+> **Definition**: Orbit
+>
+> We call **orbit of \\(d\\) by \\( \lbrace f_1, f_2, ..., f_k \rbrace \\) and denote
+> \\( \langle f_1, f_2, ..., f_k \rangle (d)\\)** the set of darts retrievable from \\(d\\) using
+> any composition of \\(f_1, f_2, ..., f_k\\), including recursions. In other words,
+> \\( \langle f_1, f_2, ..., f_k \rangle (d)\\) refers to the set of darts connected to
+> \\(d\\), via the \\(f_1, f_2, ..., f_k\\) functions.
+>
+> The set is obtained by doing a Breadth First Search algorithm from the starting dart \\(d\\),
+> where each connected node is the image of the current dart via one function
+> \\(f \in \lbrace f_1, f_2, ..., f_k \rbrace\\). The order in which nodes are explored is
+> determined by the order of the function set. 
 
-- **if i = 0**:  *0-cell(d) = ⟨{ β<sub>j</sub> o β<sub>k</sub> with 1 ≤ j < k ≤ N }⟩(d)*
-- **else**: *i-cell(d) = ⟨β<sub>1</sub>, β<sub>2</sub>, ..., β<sub>i-1</sub>, β<sub>i+1</sub>, ..., β<sub>N</sub>⟩(d)*
+For example, the orbit \\(\langle \beta _2 \rangle (d)\\) refers to the subset of unique darts
+accessible from dart \\(d\\) using any composition of \\(\beta_2\\), including recursive ones.
+The orbit \\(\langle \beta_1, \beta_0 \rangle (d_7)\\) refers to darts accessible from dart
+\\(d_7\\) using any composition of \\(\beta_1\\) and \\(\beta_0\\). The computation process is
+detailed below.
 
-In our case, we can use specialized definitions for our dimensions:
+<figure style="text-align:center">
+    <img src="../images/orbit-bfs.svg" alt="OrbitComputationProcess" width=100%/>
+    <figcaption><i>Orbit computation BFS.</i></figcaption>
+</figure>
 
-| *i* | Geometry | 2-map                                                                                       | 3-map                                                                                                                                                     |
-|-----|----------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 0   | Vertex   | *⟨β<sub>1</sub> o β<sub>2</sub>⟩(d)* <br> **or** <br> *⟨β<sub>2</sub> o β<sub>-1</sub>⟩(d)* | *⟨β<sub>3</sub> o β<sub>2</sub>, β<sub>1</sub> o β<sub>3</sub>⟩(d)* <br> **or** <br> *⟨β<sub>3</sub> o β<sub>2</sub>, β<sub>3</sub> o β<sub>-1</sub>⟩(d)* |
-| 1   | Edge     | *⟨β<sub>2</sub>⟩(d)*                                                                        | *⟨β<sub>2</sub>, β<sub>3</sub>⟩(d)*                                                                                                                       |
-| 2   | Face     | *⟨β<sub>1</sub>⟩(d)*                                                                        | *⟨β<sub>1</sub>, β<sub>3</sub>⟩(d)*                                                                                                                       |
-| 3   | Volume   | -                                                                                           | *⟨β<sub>1</sub>, β<sub>2</sub>⟩(d)*                                                                                                                       |
+## \\(i\\)-cells
 
-## Examples
+Specific values of orbits can be used to define the cells commonly used in meshing algorithms.
+These specific values are referred to as \\(i\\)-cells. For example the subset of dart defined by
+\\( \langle \beta_1 \rangle (d)\\) corresponds to darts of a face, i.e., a \\(2\\)-cell. The subset
+of dart defined by orbit \\( \langle \beta_2 \rangle (d)\\) corresponds to darts of an edge, i.e.,
+a \\(1\\)-cell.
 
 <figure style="text-align:center">
-    <img src="../images/bg_orbit_face.svg" alt="Embed" />
-    <figcaption>
-        <i>2-cell (face) associated to d<sub>2</sub>; 
-        Note that the 2-faces of d<sub>1</sub>, d<sub>3</sub>, d<sub>4</sub> are the same
-    </i></figcaption>
+    <img src="../images/icells.svg" alt="iCells" width=100%/>
+    <figcaption><i>0-cell, 1-cell, and 2-cell of d<sub>3</sub>.</i></figcaption>
 </figure>
 
-<figure style="text-align:center">
-    <img src="../images/bg_orbit_edge.svg" alt="Embed" />
-    <figcaption><i>1-cell (edge) associated to d<sub>2</sub></i></figcaption>
-</figure>
+> **Definition**: \\(0\\)-cell
+>
+> Let \\(d \in D\\). The \\(0\\)-dimensional cell associated to dart \\(d\\) is
+> \\( \langle { \beta_j \circ \beta_k, 1 \le j < k \le N } \rangle (d)\\).
 
-<figure style="text-align:center">
-    <img src="../images/bg_orbit_vertex.svg" alt="Embed" />
-    <figcaption><i>0-cell (vertex) associated to d<sub>7</sub></i></figcaption>
-</figure>
+> **Definition**: \\(i\\)-cell, \\(i \ne 0\\)
+>
+> Let \\(d \in D\\). The \\(i\\)-dimensional cell associated to dart \\(d\\) is
+> \\(\langle \beta _1, ..., \beta _{i-1}, \beta _{i+1}, ..., \beta _N \rangle (d)\\).
+
+Our interest lies in mesh representation, so we use these definitions applied to dimension 2 and 3.
+
+| *i* | Geometry | 2-map                                            | 3-map                                      |
+|-----|----------|--------------------------------------------------|------------ -------------------------------|
+| 0   | Vertex   | \\( \langle \beta_1 \circ \beta_2 \rangle (d)\\) | \\(\langle \beta_1 \circ \beta_2, \beta_1 \circ \beta_3, \beta_2 \circ \beta_3 \rangle (d)\\) |
+| 1   | Edge     | \\(\langle \beta_2 \rangle (d)\\)                | \\(\langle \beta_2, \beta_3 \rangle (d)\\) |
+| 2   | Face     | \\(\langle \beta_1 \rangle (d)\\)                | \\(\langle \beta_1, \beta_3 \rangle (d)\\) |
+| 3   | Volume   | -                                                | \\(\langle \beta_1, \beta_2 \rangle (d)\\) |

user-guide/src/definitions/cmaps.md

@@ -1,36 +1,25 @@
 # Combinatorial maps
 
-**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved
-at some point.**
-
 ---
 
-## Definition
-
-### Maps
-
-N-dimensional combinatorial maps, noted *N-map*, are objects made up of
-two main elements:
-
-- A set of darts, darts being the smallest elements making up the map
-- N beta functions, linking the darts of the map
-
-Additionally, we can define *embedded data* as spatial anchoring of the
-darts making up the map. While the first two elements hold topological
-information, embedded data gives information about the "shape" of the
-map (e.g. vertices position in a spatial domain).
+Combinatorial maps are combinatorial, graph-like, data structures which can be seen as the
+formalization of half-edges to higher dimensions. They can be used in dimension two and three for
+mesh representation, including both surface and volume 3D meshing.
 
-With these elements, we can represent and operate on meshes.
-
-## Example
-
-Operations on a combinatorial map can affect its topology, shape or both:
+Roughly speaking, a map is simply a set of abstract elements, called darts, augmented with functions defined on this set of darts, which describe topological relations between them. This section
+presents the notions useful to understand maps, as they are the mai structure offered by the
+library.
 
 <figure style="text-align:center">
-    <img src="../images/bg_hcmap_example.svg" alt="MapMeshEquivalent" />
-    <figcaption><i>Core crate quickstart example</i></figcaption>
+    <img src="../images/meshmap.svg" alt="MapMeshEquivalent" width=70%/>
+    <figcaption><i>Simple 2D mesh and its map representation.</i></figcaption>
 </figure>
 
-The specifics on how data is encoded is detailed in attribute-specific
-sections.
+All of the definitions we present in this section are based on G. Damiand and P. Lienhardt
+_Combinatorial Maps: Efficient Data Structures for Computer Graphics and Image Processing_;
+The reader may refer to this book for more details.
 
+<figure style="text-align:center">
+    <img src="../images/3meshmap.svg" alt="MapMeshEquivalent" width=100%/>
+    <figcaption><i>Simple 3D mesh and its map representation.</i></figcaption>
+</figure>

user-guide/src/definitions/components.md

@@ -1,61 +1,81 @@
 # Components
 
-**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved
-at some point.**
-
 ---
 
-## Darts
+## Preliminary notions
 
-Darts are the finest grain composing combinatorial maps. The structure of the map is given by the relationship between
-darts, defined through beta functions. Additionally, a null dart is defined, we denote it *∅*.
+Let \\(F, G\\) be finite sets of elements. Let \\(f\\) an application defined on \\(F\\) to \\(G\\).
 
-In our implementation, darts exist implicitly through indexing and their associated data. There are no dart *objects*
-in a strict sense, there is only a given number of dart, their associated data ordered by an array-like logic, and a
-record of "unused" slots that can be used for dart insertion. Because of this, we assimilate dart and dart index.
+> **Definition**: Permutation
+>
+> \\(f: F \rightarrow G\\) is a **permutation** if and only if \\(f\\) is a bijection and
+> \\(F = G\\), i.e.,\\(f\\) is a one-to-one mapping from \\(F\\) to \\(F\\). 
 
-## Beta functions
+> **Definition**: Involution
+>
+> \\(f: F \rightarrow F\\) is an **involution** if it is a permutation and is its own inverse, i.e.,
+> \\(f\\) is a one-to-one mapping from \\(F\\) to \\(F\\), and \\(f = f^{-1}\\). 
 
-Each combinatorial map of dimension *N* defines *N* beta functions linking the set of darts together (e.g. a 2-map
-contains *β<sub>1</sub>* and *β<sub>2</sub>*). These functions model the topology of the map, giving information about
-connections of the different cells of the map / mesh. In our case, we mostly use:
+Let \\(\emptyset\\) denote a null element. Let \\(F' = F \cup { \emptyset }\\).
 
-- *β<sub>1</sub>*, a (partial) permutation,
-- *β<sub>2</sub>*, *β<sub>3</sub>*, two (partial) involutions
 
-Additionally, we define *β<sub>0</sub>* as the inverse of *β<sub>1</sub>*, i.e. *β<sub>0</sub>(β<sub>1</sub>(d)) = d*.
-This comes from a practical consideration for performances and efficiency of the implementation.
+> **Definition**: Partial permutation
+>
+> \\(f': F' \rightarrow F'\\) is a **partial permutation** if \\(f'(\emptyset) = \emptyset\\) and
+> \\(\forall x,y \in F, f'(x) = f'(y) \ne \emptyset \Rightarrow x = y\\). 
 
-The *β<sub>i</sub>* functions can be interpreted as navigation functions along the *i-th* dimensions: *β<sub>1</sub>*
-makes you navigate along the edges, *β<sub>2</sub>* along the faces, etc. This can be generalized to *N* dimensions,
-but we are only interested in 2D and 3D at the moment.
+> **Definition**: Partial involution
+>
+> \\(f': F' \rightarrow F'\\) is a partial involution if it is a partial permutation and
+> \\(\forall x \in F, f'(x) = \emptyset\\) or \\(f'(x) \ne \emptyset \Rightarrow f'(f'(x)) = x\\). 
 
-### Properties
+## Combinatorial maps
 
-For a given dart *d*, we define two properties:
+Let \\( N \in \mathbb{N} \\). An \\(N\\)-dimensional map is defined as follows:
 
-- *d* is ***i*-free** if *β<sub>i</sub>(d) = ∅*, *∅* being the null dart
-- *d* is **free** if it is ***i*-free for all *i***
+> **Definition**: Combinatorial map
+>
+> \\(N\\)-dimensional combinatorial maps, or \\(N\\)-maps, are an \\((N+1)\\)-tuple
+> \\((D, \beta_1, ..., \beta_N)\\) such that:
+>
+> - \\(D = \lbrace d_i \rbrace_i\\) is a finite set of darts,
+> - \\(\forall j \in [ 1; N ], \beta_j\\) is a function from \\(D\\) to \\(D\\) defining
+>   topology of the space. 
 
-## Construction Example
+### Darts
 
-<figure style="text-align:center">
-    <img src="../images/bg_darts.svg" alt="Embed" />
-    <figcaption><i>Start from unorganized darts</i></figcaption>
-</figure>
+Darts are the finest grain composing combinatorial maps. The structure of the map is given by the
+relationship between darts, defined through beta functions. Additionally, a null dart is defined,
+we denote it \\(d_0 = \emptyset\\).
 
-<figure style="text-align:center">
-    <img src="../images/bg_beta1.svg" alt="Embed" />
-    <figcaption><i>Organize those using β<sub>1</sub></i></figcaption>
-</figure>
+In our implementation, darts exist implicitly through indexing and their associated data. There are
+no dart *objects* in a strict sense, there is only a given number of dart, their associated data
+stored using arrays, and a record of "unused" slots that can be used for dart insertion.
+Because of this, we assimilate dart and dart index.
+
+### Beta functions
+
+Each combinatorial map of dimension *N* defines *N* beta functions linking the set of darts
+together. These functions model the topology of the map, giving information about connections of
+the different cells of the mesh. They verify the following properties:
+
+- \\(\beta_1\\) is a partial permutation on \\(D\\).
+- \\(\forall i \ge 2, \beta_i\\) is a partial involution on \\(D\\).
+- \\(\forall i \in [1;N-2], \forall j \in [i+2; N], \beta_i \circ \beta_j\\) is a partial
+  involution on \\(D\\).
+
+Additionally, we define \\(\beta_0\\) as the inverse of \\(\beta_1\\).
+This comes from a practical consideration for performances and efficiency of the implementation.
+
+## Examples
 
 <figure style="text-align:center">
-    <img src="../images/bg_beta2.svg" alt="Embed" />
-    <figcaption><i>Add β<sub>2</sub> images; For details on vertices, refer to the Embedding section</i></figcaption>
+    <img src="../images/2map.svg" alt="MapMeshEquivalent" width=100%/>
+    <figcaption><i>2-map example and its components values.</i></figcaption>
 </figure>
 
 <figure style="text-align:center">
-    <img src="../images/bg_map.svg" alt="Embed" />
-    <figcaption><i>Build up a larger map</i></figcaption>
+    <img src="../images/3map.svg" alt="MapMeshEquivalent" width=80%/>
+    <img src="../images/components.svg" alt="MapMeshEquivalent" width=100%/>
+    <figcaption><i>3-map example and its components values.</i></figcaption>
 </figure>
-